chore: rename import types (#3678)

Use `ImportCandidate` and `ImportCandidateStream` instead of `ToEntry`
and `ImportSource` as they are a bit more descriptive. Plus we already
have `BrowserImportCandidate` for `Blob`s so it's more consistent too.

Author: achingbrain

packages/ipfs-core-types/src/root.d.ts

@@ -1,4 +1,4 @@
-import { AbortOptions, PreloadOptions, IPFSPath, ImportSource, ToEntry } from './utils'
+import { AbortOptions, PreloadOptions, IPFSPath, ImportCandidateStream, ImportCandidate } from './utils'
 import CID, { CIDVersion } from 'cids'
 import { Mtime } from 'ipfs-unixfs'
 import { Multiaddr } from 'multiaddr'
@@ -8,12 +8,12 @@ export interface API<OptionExtension = {}> {
   /**
    * Import a file or data into IPFS
    */
-  add: (entry: ToEntry, options?: AddOptions & OptionExtension) => Promise<AddResult>
+  add: (entry: ImportCandidate, options?: AddOptions & OptionExtension) => Promise<AddResult>
 
   /**
    * Import multiple files and data into IPFS
    */
-  addAll: (source: ImportSource, options?: AddAllOptions & AbortOptions & OptionExtension) => AsyncIterable<AddResult>
+  addAll: (source: ImportCandidateStream, options?: AddAllOptions & AbortOptions & OptionExtension) => AsyncIterable<AddResult>
 
   /**
    * Returns content of the file addressed by a valid IPFS Path or CID

packages/ipfs-core-types/src/utils.d.ts

@@ -20,11 +20,11 @@ export interface DirectoryEntry extends BaseEntry {
   content?: undefined
 }
 
-export type ImportSource =
-| AwaitIterable<ToEntry>
-| ReadableStream<ToEntry>
+export type ImportCandidateStream =
+| AwaitIterable<ImportCandidate>
+| ReadableStream<ImportCandidate>
 
-export type ToEntry =
+export type ImportCandidate =
   | ToFile
   | ToDirectory
   | ToContent

packages/ipfs-core-utils/src/files/normalise-input/index.browser.js

@@ -4,7 +4,7 @@ const normaliseContent = require('./normalise-content.browser')
 const normaliseInput = require('./normalise-input')
 
 /**
- * @typedef {import('ipfs-core-types/src/utils').ImportSource} ImportSource
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidateStream} ImportCandidateStream
  * @typedef {import('ipfs-core-types/src/utils').BrowserImportCandidate} BrowserImportCandidate
  */
 
@@ -17,7 +17,7 @@ const normaliseInput = require('./normalise-input')
  *
  * See https://github.com/ipfs/js-ipfs/blob/master/docs/core-api/FILES.md#ipfsadddata-options
  *
- * @param {ImportSource} input
+ * @param {ImportCandidateStream} input
  * @returns {AsyncGenerator<BrowserImportCandidate, void, undefined>}
  */
 // @ts-ignore

packages/ipfs-core-utils/src/files/normalise-input/index.js

@@ -4,7 +4,7 @@ const normaliseContent = require('./normalise-content')
 const normaliseInput = require('./normalise-input')
 
 /**
- * @typedef {import('ipfs-core-types/src/utils').ImportSource} ImportSource
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidateStream} ImportCandidateStream
  * @typedef {import('ipfs-unixfs-importer').ImportCandidate} ImportCandidate
  */
 
@@ -17,7 +17,7 @@ const normaliseInput = require('./normalise-input')
  *
  * See https://github.com/ipfs/js-ipfs/blob/master/docs/core-api/FILES.md#ipfsadddata-options
  *
- * @param {ImportSource} input
+ * @param {ImportCandidateStream} input
  * @returns {AsyncGenerator<ImportCandidate, void, undefined>}
  */
 module.exports = (input) => normaliseInput(input, normaliseContent)

packages/ipfs-core-utils/src/files/normalise-input/normalise-input.js

@@ -17,12 +17,12 @@ const {
 
 /**
  * @typedef {import('ipfs-core-types/src/utils').ToContent} ToContent
- * @typedef {import('ipfs-unixfs-importer').ImportCandidate} ImportCandidate
- * @typedef {import('ipfs-core-types/src/utils').ToEntry} ToEntry
+ * @typedef {import('ipfs-unixfs-importer').ImportCandidate} ImporterImportCandidate
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidate} ImportCandidate
  */
 
 /**
- * @param {import('ipfs-core-types/src/utils').ImportSource} input
+ * @param {import('ipfs-core-types/src/utils').ImportCandidateStream} input
  * @param {(content:ToContent) => AsyncIterable<Uint8Array>} normaliseContent
  */
 // eslint-disable-next-line complexity
@@ -76,7 +76,7 @@ module.exports = async function * normaliseInput (input, normaliseContent) {
     // (Async)Iterable<String>
     // (Async)Iterable<{ path, content }>
     if (isFileObject(value) || isBlob(value) || typeof value === 'string' || value instanceof String) {
-      yield * map(peekable, (/** @type {ToEntry} */ value) => toFileObject(value, normaliseContent))
+      yield * map(peekable, (/** @type {ImportCandidate} */ value) => toFileObject(value, normaliseContent))
       return
     }
 
@@ -85,7 +85,7 @@ module.exports = async function * normaliseInput (input, normaliseContent) {
     // ReadableStream<(Async)Iterable<?>>
     // ReadableStream<ReadableStream<?>>
     if (value[Symbol.iterator] || value[Symbol.asyncIterator] || isReadableStream(value)) {
-      yield * map(peekable, (/** @type {ToEntry} */ value) => toFileObject(value, normaliseContent))
+      yield * map(peekable, (/** @type {ImportCandidate} */ value) => toFileObject(value, normaliseContent))
       return
     }
   }
@@ -102,14 +102,14 @@ module.exports = async function * normaliseInput (input, normaliseContent) {
 }
 
 /**
- * @param {ToEntry} input
+ * @param {ImportCandidate} input
  * @param {(content:ToContent) => AsyncIterable<Uint8Array>} normaliseContent
  */
 async function toFileObject (input, normaliseContent) {
   // @ts-ignore - Those properties don't exist on most input types
   const { path, mode, mtime, content } = input
 
-  /** @type {ImportCandidate} */
+  /** @type {ImporterImportCandidate} */
   const file = {
     path: path || '',
     mode: parseMode(mode),

packages/ipfs-core-utils/src/files/normalise-input/utils.js

@@ -22,7 +22,7 @@ function isBlob (obj) {
  * An object with a path or content property
  *
  * @param {any} obj
- * @returns {obj is import('ipfs-core-types/src/utils').ToEntry}
+ * @returns {obj is import('ipfs-core-types/src/utils').ImportCandidate}
  */
 function isFileObject (obj) {
   return typeof obj === 'object' && (obj.path || obj.content)

packages/ipfs-grpc-client/src/core-api/add-all.js

@@ -86,7 +86,7 @@ async function sendFile (index, sink, content, path, mode, mtime) {
 }
 
 /**
- * @param {import('ipfs-core-types/src/utils').ImportSource} stream
+ * @param {import('ipfs-core-types/src/utils').ImportCandidateStream} stream
  * @param {import('it-pushable').Pushable<any>} sink
  */
 async function sendFiles (stream, sink) {

packages/ipfs-http-client/src/lib/multipart-request.browser.js

@@ -6,12 +6,12 @@ const normaliseInput = require('ipfs-core-utils/src/files/normalise-input/index.
 const modeToString = require('./mode-to-string')
 
 /**
- * @typedef {import('ipfs-core-types/src/utils').ImportSource} ImportSource
- * @typedef {import('ipfs-core-types/src/utils').ToEntry} ToEntry
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidateStream} ImportCandidateStream
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidate} ImportCandidate
  */
 
 /**
- * @param {ImportSource|ToEntry} source
+ * @param {ImportCandidateStream|ImportCandidate} source
  * @param {AbortController} abortController
  * @param {Headers|Record<string, string>} [headers]
  */

packages/ipfs-http-client/src/lib/multipart-request.node.js

@@ -8,19 +8,19 @@ const merge = require('merge-options').bind({ ignoreUndefined: true })
 const toStream = require('it-to-stream')
 
 /**
- * @typedef {import('ipfs-core-types/src/utils').ImportSource} ImportSource
- * @typedef {import('ipfs-core-types/src/utils').ToEntry} ToEntry
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidateStream} ImportCandidateStream
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidate} ImportCandidate
  */
 
 /**
- * @param {ImportSource|ToEntry} source
+ * @param {ImportCandidateStream|ImportCandidate} source
  * @param {AbortController} abortController
  * @param {Headers|Record<string, string>} [headers]
  * @param {string} [boundary]
  */
 async function multipartRequest (source, abortController, headers = {}, boundary = `-----------------------------${nanoid()}`) {
   /**
-   * @param {ImportSource|ToEntry} source
+   * @param {ImportCandidateStream|ImportCandidate} source
    */
   async function * streamFiles (source) {
     try {

packages/ipfs-http-server/src/api/resources/files-regular.js

@@ -303,7 +303,7 @@ exports.add = {
         }
       },
       /**
-       * @param {import('ipfs-core-types/src/utils').ImportSource} source
+       * @param {import('ipfs-core-types/src/utils').ImportCandidateStream} source
        */
       function (source) {
         return ipfs.addAll(source, {

packages/ipfs-message-port-client/src/core.js

@@ -39,11 +39,11 @@ const {
  * @typedef {import('./interface').MessagePortClientOptions} MessagePortClientOptions
  * @typedef {import('ipfs-core-types/src/root').API<MessagePortClientOptions>} RootAPI
  *
- * @typedef {import('ipfs-core-types/src/utils').ToEntry} ToEntry
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidate} ImportCandidate
  * @typedef {import('ipfs-core-types/src/utils').ToFile} ToFile
  * @typedef {import('ipfs-core-types/src/utils').ToDirectory} ToDirectory
  * @typedef {import('ipfs-core-types/src/utils').ToContent} ToContent
- * @typedef {import('ipfs-core-types/src/utils').ImportSource} ImportSource
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidateStream} ImportCandidateStream
  */
 
 /**
@@ -181,7 +181,7 @@ const identity = (v) => v
  * Encodes input passed to the `ipfs.add` via the best possible strategy for the
  * given input.
  *
- * @param {ToEntry} input
+ * @param {ImportCandidate} input
  * @param {Transferable[]} transfer
  * @returns {EncodedAddInput}
  */
@@ -235,7 +235,7 @@ const encodeAddInput = (input, transfer) => {
  * Encodes input passed to the `ipfs.add` via the best possible strategy for the
  * given input.
  *
- * @param {ImportSource} input
+ * @param {ImportCandidateStream} input
  * @param {Transferable[]} transfer
  * @returns {EncodedAddAllInput}
  */
@@ -272,7 +272,7 @@ const encodeAddAllInput = (input, transfer) => {
  * Function encodes individual item of some `AsyncIterable` by choosing most
  * effective strategy.
  *
- * @param {ToEntry} content
+ * @param {ImportCandidate} content
  * @param {Transferable[]} transfer
  * @returns {EncodedAddInput}
  */
@@ -296,7 +296,7 @@ const encodeAsyncIterableContent = (content, transfer) => {
 }
 
 /**
- * @param {ToEntry} content
+ * @param {ImportCandidate} content
  * @param {Transferable[]} transfer
  * @returns {EncodedAddInput}
  */
@@ -388,7 +388,7 @@ const encodeFileContent = (content, transfer) => {
  * iterable or `null`.
  *
  * @template I
- * @param {Iterable<I>|ToEntry|ImportSource} input
+ * @param {Iterable<I>|ImportCandidate|ImportCandidateStream} input
  * @returns {Iterable<I>|null}
  */
 const asIterable = (input) => {
@@ -406,7 +406,7 @@ const asIterable = (input) => {
  * matched `AsyncIterable` or `null`.
  *
  * @template I
- * @param {AsyncIterable<I>|ToEntry|ImportSource} input
+ * @param {AsyncIterable<I>|ImportCandidate|ImportCandidateStream} input
  * @returns {AsyncIterable<I>|null}
  */
 const asAsyncIterable = (input) => {

packages/ipfs-message-port-server/src/core.js

@@ -16,8 +16,8 @@ const { decodeCID, encodeCID } = require('ipfs-message-port-protocol/src/cid')
  * @typedef {import('ipfs-core-types/src/root').AddAllOptions} AddAllOptions
  * @typedef {import('ipfs-core-types/src/root').IPFSEntry} IPFSEntry
  * @typedef {import('ipfs-message-port-protocol/src/cid').EncodedCID} EncodedCID
- * @typedef {import('ipfs-core-types/src/utils').ImportSource} ImportSource
- * @typedef {import('ipfs-core-types/src/utils').ToEntry} ToEntry
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidateStream} ImportCandidateStream
+ * @typedef {import('ipfs-core-types/src/utils').ImportCandidate} ImportCandidate
  * @typedef {import('ipfs-core-types/src/root').AddResult} AddResult
  * @typedef {import('ipfs-message-port-protocol/src/root').EncodedAddInput} EncodedAddInput
  * @typedef {import('ipfs-message-port-protocol/src/root').EncodedAddAllInput} EncodedAddAllInput
@@ -188,7 +188,7 @@ exports.CoreService = class CoreService {
 
 /**
  * @param {EncodedAddAllInput} input
- * @returns {ImportSource}
+ * @returns {ImportCandidateStream}
  */
 const decodeAddAllInput = input =>
   decodeIterable(input, decodeFileInput)