docs: convert examples to ts, run doc verifier (#434)

Enables type checking for docs so they are kept in sync with API
changes.

Author: achingbrain

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",

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,19 +49,23 @@ 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
 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

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": {

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,19 +26,23 @@
  *
  * 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
  * 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
@@ -180,7 +184,7 @@ export interface Exportable<T> {
    *
    * 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<T> {
    *
    * 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<T> {
 /**
  * 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<Uint8Array> {
 /**
  * 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<any> {
  *
  * `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 = []

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',

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": {

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',

packages/ipfs-unixfs/README.md

@@ -30,25 +30,33 @@ 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)
 // ...
 ```
 
 ## Example - Create a directory that contains several files
 
 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,48 +75,67 @@ const data = new UnixFS([options])
 
 ## Example - Add and remove a block size to the block size list
 
-```JavaScript
-data.addBlockSize(<size in bytes>)
+```TypeScript
+import { UnixFS } from 'ipfs-unixfs'
+
+const data = new UnixFS({ type: 'file' })
+const sizeInBytes = 100n
+data.addBlockSize(sizeInBytes)
 ```
 
-```JavaScript
-data.removeBlockSize(<index>)
+```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
 ```
 
 ## Example - Has an mtime been set?
 
 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 }
 ```
 

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": {