From 3d180f7f532fd510cf97ba7c12d3e72b1d7be7b1 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Wed, 18 Jun 2025 07:37:28 +0300 Subject: [PATCH] docs: convert examples to ts, run doc verifier Enables type checking for docs so they are kept in sync with API changes. --- package.json | 1 + packages/ipfs-unixfs-exporter/README.md | 10 +++- packages/ipfs-unixfs-exporter/package.json | 1 + packages/ipfs-unixfs-exporter/src/index.ts | 22 +++++--- packages/ipfs-unixfs-importer/README.md | 4 +- packages/ipfs-unixfs-importer/package.json | 1 + packages/ipfs-unixfs-importer/src/index.ts | 4 +- packages/ipfs-unixfs/README.md | 65 +++++++++++++++------- packages/ipfs-unixfs/package.json | 1 + packages/ipfs-unixfs/src/index.ts | 65 +++++++++++++++------- 10 files changed, 120 insertions(+), 54 deletions(-) diff --git a/package.json b/package.json index 13c17a6f..ab2f7c5d 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "build": "aegir run build", "lint": "aegir run lint", "dep-check": "aegir run dep-check", + "doc-check": "aegir run doc-check", "release": "run-s build docs:no-publish npm:release docs", "npm:release": "aegir run release --concurrency 1", "docs": "aegir docs", diff --git a/packages/ipfs-unixfs-exporter/README.md b/packages/ipfs-unixfs-exporter/README.md index 899c2d81..19949f4a 100644 --- a/packages/ipfs-unixfs-exporter/README.md +++ b/packages/ipfs-unixfs-exporter/README.md @@ -28,7 +28,7 @@ The UnixFS Exporter provides a means to read DAGs from a blockstore given a CID. ## Example -```js +```TypeScript // import a file and export it again import { importer } from 'ipfs-unixfs-importer' import { exporter } from 'ipfs-unixfs-exporter' @@ -49,6 +49,10 @@ console.info(files[0].cid) // Qmbaz const entry = await exporter(files[0].cid, blockstore) +if (entry.type !== 'file') { + throw new Error('Unexpected entry type') +} + console.info(entry.cid) // Qmqux console.info(entry.path) // Qmbaz/foo/bar.txt console.info(entry.name) // bar.txt @@ -56,12 +60,12 @@ console.info(entry.unixfs.fileSize()) // 4 // stream content from unixfs node const size = entry.unixfs.fileSize() -const bytes = new Uint8Array(size) +const bytes = new Uint8Array(Number(size)) let offset = 0 for await (const buf of entry.content()) { bytes.set(buf, offset) - offset += chunk.length + offset += buf.byteLength } console.info(bytes) // 0, 1, 2, 3 diff --git a/packages/ipfs-unixfs-exporter/package.json b/packages/ipfs-unixfs-exporter/package.json index f77b4eab..f54340b6 100644 --- a/packages/ipfs-unixfs-exporter/package.json +++ b/packages/ipfs-unixfs-exporter/package.json @@ -134,6 +134,7 @@ "clean": "aegir clean", "lint": "aegir lint", "dep-check": "aegir dep-check", + "doc-check": "aegir doc-check", "release": "aegir release" }, "dependencies": { diff --git a/packages/ipfs-unixfs-exporter/src/index.ts b/packages/ipfs-unixfs-exporter/src/index.ts index ead6279a..e8b06f59 100644 --- a/packages/ipfs-unixfs-exporter/src/index.ts +++ b/packages/ipfs-unixfs-exporter/src/index.ts @@ -5,7 +5,7 @@ * * @example * - * ```js + * ```TypeScript * // import a file and export it again * import { importer } from 'ipfs-unixfs-importer' * import { exporter } from 'ipfs-unixfs-exporter' @@ -26,6 +26,10 @@ * * const entry = await exporter(files[0].cid, blockstore) * + * if (entry.type !== 'file') { + * throw new Error('Unexpected entry type') + * } + * * console.info(entry.cid) // Qmqux * console.info(entry.path) // Qmbaz/foo/bar.txt * console.info(entry.name) // bar.txt @@ -33,12 +37,12 @@ * * // stream content from unixfs node * const size = entry.unixfs.fileSize() - * const bytes = new Uint8Array(size) + * const bytes = new Uint8Array(Number(size)) * let offset = 0 * * for await (const buf of entry.content()) { * bytes.set(buf, offset) - * offset += chunk.length + * offset += buf.byteLength * } * * console.info(bytes) // 0, 1, 2, 3 @@ -180,7 +184,7 @@ export interface Exportable { * * When `entry` is a file or a `raw` node, `offset` and/or `length` arguments can be passed to `entry.content()` to return slices of data: * - * ```javascript + * ```TypeScript * const length = 5 * const data = new Uint8Array(length) * let offset = 0 @@ -201,7 +205,7 @@ export interface Exportable { * * If `entry` is a directory, passing `offset` and/or `length` to `entry.content()` will limit the number of files returned from the directory. * - * ```javascript + * ```TypeScript * const entries = [] * * for await (const entry of dir.content({ @@ -220,7 +224,7 @@ export interface Exportable { /** * If the entry is a file, `entry.content()` returns an async iterator that yields one or more Uint8Arrays containing the file content: * - * ```javascript + * ```TypeScript * if (entry.type === 'file') { * for await (const chunk of entry.content()) { * // chunk is a Buffer @@ -237,7 +241,7 @@ export interface UnixFSFile extends Exportable { /** * If the entry is a directory, `entry.content()` returns further `entry` objects: * - * ```javascript + * ```TypeScript * if (entry.type === 'directory') { * for await (const entry of dir.content()) { * console.info(entry.name) @@ -264,7 +268,7 @@ export interface ObjectNode extends Exportable { * * `entry.content()` returns an async iterator that yields a buffer containing the node content: * - * ```javascript + * ```TypeScript * for await (const chunk of entry.content()) { * // chunk is a Buffer * } @@ -371,7 +375,7 @@ const cidAndRest = (path: string | Uint8Array | CID): { cid: CID, toResolve: str * * @example * - * ```javascript + * ```TypeScript * import { walkPath } from 'ipfs-unixfs-exporter' * * const entries = [] diff --git a/packages/ipfs-unixfs-importer/README.md b/packages/ipfs-unixfs-importer/README.md index c0f69b4a..05c5c174 100644 --- a/packages/ipfs-unixfs-importer/README.md +++ b/packages/ipfs-unixfs-importer/README.md @@ -37,7 +37,7 @@ Let's create a little directory to import: And write the importing logic: -```js +```TypeScript import { importer } from 'ipfs-unixfs-importer' import { MemoryBlockstore } from 'blockstore-core/memory' import * as fs from 'node:fs' @@ -61,7 +61,7 @@ for await (const entry of importer(source, blockstore)) { When run, metadata about DAGNodes in the created tree is printed until the root: -```js +``` { cid: CID, // see https://github.com/multiformats/js-cid path: 'tmp/foo/bar', diff --git a/packages/ipfs-unixfs-importer/package.json b/packages/ipfs-unixfs-importer/package.json index 0511a28e..b776e675 100644 --- a/packages/ipfs-unixfs-importer/package.json +++ b/packages/ipfs-unixfs-importer/package.json @@ -158,6 +158,7 @@ "clean": "aegir clean", "lint": "aegir lint", "dep-check": "aegir dep-check", + "doc-check": "aegir doc-check", "release": "aegir release" }, "dependencies": { diff --git a/packages/ipfs-unixfs-importer/src/index.ts b/packages/ipfs-unixfs-importer/src/index.ts index 8497a79f..84e22564 100644 --- a/packages/ipfs-unixfs-importer/src/index.ts +++ b/packages/ipfs-unixfs-importer/src/index.ts @@ -14,7 +14,7 @@ * * And write the importing logic: * - * ```js + * ```TypeScript * import { importer } from 'ipfs-unixfs-importer' * import { MemoryBlockstore } from 'blockstore-core/memory' * import * as fs from 'node:fs' @@ -38,7 +38,7 @@ * * When run, metadata about DAGNodes in the created tree is printed until the root: * - * ```js + * ``` * { * cid: CID, // see https://github.com/multiformats/js-cid * path: 'tmp/foo/bar', diff --git a/packages/ipfs-unixfs/README.md b/packages/ipfs-unixfs/README.md index 52198d1f..d8757440 100644 --- a/packages/ipfs-unixfs/README.md +++ b/packages/ipfs-unixfs/README.md @@ -30,10 +30,12 @@ The UnixFS spec can be found in the [ipfs/specs repository](http://github.com/ip ## Example - Create a file composed of several blocks -```JavaScript +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + const data = new UnixFS({ type: 'file' }) -data.addBlockSize(256) // add the size of each block -data.addBlockSize(256) +data.addBlockSize(256n) // add the size of each block +data.addBlockSize(256n) // ... ``` @@ -41,14 +43,20 @@ data.addBlockSize(256) Creating a directory that contains several files is achieve by creating a unixfs element that identifies a MerkleDAG node as a directory. The links of that MerkleDAG node are the files that are contained in this directory. -```JavaScript +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + const data = new UnixFS({ type: 'directory' }) ``` ## Example - Create an unixfs Data element -```JavaScript -const data = new UnixFS([options]) +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + +const data = new UnixFS({ + // ...options +}) ``` `options` is an optional object argument that might include the following keys: @@ -67,34 +75,51 @@ const data = new UnixFS([options]) ## Example - Add and remove a block size to the block size list -```JavaScript -data.addBlockSize() +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + +const data = new UnixFS({ type: 'file' }) +const sizeInBytes = 100n +data.addBlockSize(sizeInBytes) ``` -```JavaScript -data.removeBlockSize() +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + +const data = new UnixFS({ type: 'file' }) + +const index = 0 +data.removeBlockSize(index) ``` ## Example - Get total fileSize -```JavaScript +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + +const data = new UnixFS({ type: 'file' }) data.fileSize() // => size in bytes ``` ## Example - Marshal and unmarshal -```javascript +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + +const data = new UnixFS({ type: 'file' }) const marshaled = data.marshal() -const unmarshaled = Unixfs.unmarshal(marshaled) +const unmarshaled = UnixFS.unmarshal(marshaled) ``` ## Example - Is this UnixFS entry a directory? -```JavaScript -const dir = new Data({ type: 'directory' }) +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + +const dir = new UnixFS({ type: 'directory' }) dir.isDirectory() // true -const file = new Data({ type: 'file' }) +const file = new UnixFS({ type: 'file' }) file.isDirectory() // false ``` @@ -102,13 +127,15 @@ file.isDirectory() // false If no modification time has been set, no `mtime` property will be present on the `Data` instance: -```JavaScript -const file = new Data({ type: 'file' }) +```TypeScript +import { UnixFS } from 'ipfs-unixfs' + +const file = new UnixFS({ type: 'file' }) file.mtime // undefined Object.prototype.hasOwnProperty.call(file, 'mtime') // false -const dir = new Data({ type: 'dir', mtime: new Date() }) +const dir = new UnixFS({ type: 'dir', mtime: { secs: 5n } }) dir.mtime // { secs: Number, nsecs: Number } ``` diff --git a/packages/ipfs-unixfs/package.json b/packages/ipfs-unixfs/package.json index fe5784da..6b4d032c 100644 --- a/packages/ipfs-unixfs/package.json +++ b/packages/ipfs-unixfs/package.json @@ -135,6 +135,7 @@ "clean": "aegir clean", "lint": "aegir lint", "dep-check": "aegir dep-check", + "doc-check": "aegir doc-check", "release": "aegir release" }, "dependencies": { diff --git a/packages/ipfs-unixfs/src/index.ts b/packages/ipfs-unixfs/src/index.ts index 82f76823..a5a98ed9 100644 --- a/packages/ipfs-unixfs/src/index.ts +++ b/packages/ipfs-unixfs/src/index.ts @@ -7,10 +7,12 @@ * * @example Create a file composed of several blocks * - * ```JavaScript + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * * const data = new UnixFS({ type: 'file' }) - * data.addBlockSize(256) // add the size of each block - * data.addBlockSize(256) + * data.addBlockSize(256n) // add the size of each block + * data.addBlockSize(256n) * // ... * ``` * @@ -18,14 +20,20 @@ * * Creating a directory that contains several files is achieve by creating a unixfs element that identifies a MerkleDAG node as a directory. The links of that MerkleDAG node are the files that are contained in this directory. * - * ```JavaScript + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * * const data = new UnixFS({ type: 'directory' }) * ``` * * @example Create an unixfs Data element * - * ```JavaScript - * const data = new UnixFS([options]) + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * + * const data = new UnixFS({ + * // ...options + * }) * ``` * * `options` is an optional object argument that might include the following keys: @@ -44,34 +52,51 @@ * * @example Add and remove a block size to the block size list * - * ```JavaScript - * data.addBlockSize() + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * + * const data = new UnixFS({ type: 'file' }) + * const sizeInBytes = 100n + * data.addBlockSize(sizeInBytes) * ``` * - * ```JavaScript - * data.removeBlockSize() + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * + * const data = new UnixFS({ type: 'file' }) + * + * const index = 0 + * data.removeBlockSize(index) * ``` * * @example Get total fileSize * - * ```JavaScript + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * + * const data = new UnixFS({ type: 'file' }) * data.fileSize() // => size in bytes * ``` * * @example Marshal and unmarshal * - * ```javascript + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * + * const data = new UnixFS({ type: 'file' }) * const marshaled = data.marshal() - * const unmarshaled = Unixfs.unmarshal(marshaled) + * const unmarshaled = UnixFS.unmarshal(marshaled) * ``` * * @example Is this UnixFS entry a directory? * - * ```JavaScript - * const dir = new Data({ type: 'directory' }) + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * + * const dir = new UnixFS({ type: 'directory' }) * dir.isDirectory() // true * - * const file = new Data({ type: 'file' }) + * const file = new UnixFS({ type: 'file' }) * file.isDirectory() // false * ``` * @@ -79,13 +104,15 @@ * * If no modification time has been set, no `mtime` property will be present on the `Data` instance: * - * ```JavaScript - * const file = new Data({ type: 'file' }) + * ```TypeScript + * import { UnixFS } from 'ipfs-unixfs' + * + * const file = new UnixFS({ type: 'file' }) * file.mtime // undefined * * Object.prototype.hasOwnProperty.call(file, 'mtime') // false * - * const dir = new Data({ type: 'dir', mtime: new Date() }) + * const dir = new UnixFS({ type: 'dir', mtime: { secs: 5n } }) * dir.mtime // { secs: Number, nsecs: Number } * ``` */