fix: add doc-check script and export types used by functions (#637)

Uses tsc to attempt to compile any `typescript` code blocks in
markdown files to ensure our examples don't get out of date.

Author: achingbrain

.gitignore

@@ -7,3 +7,5 @@ node_modules
 package-lock.json
 yarn.lock
 .vscode
+.tmp-compiled-docs
+tsconfig-doc-check.aegir.json

benchmarks/add-dir/package.json

@@ -9,6 +9,7 @@
     "build": "aegir build --bundle false",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "start": "npm run build && node dist/src/index.js"
   },
   "dependencies": {

benchmarks/gc/package.json

@@ -7,6 +7,7 @@
     "build": "aegir build --bundle false",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "start": "npm run build && node dist/src/index.js"
   },
   "dependencies": {

benchmarks/pinning/package.json

@@ -7,6 +7,7 @@
     "build": "aegir build --bundle false",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "start": "npm run build && node dist/src/index.js"
   },
   "dependencies": {

benchmarks/transfer/package.json

@@ -9,6 +9,7 @@
     "build": "aegir build --bundle false",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "start": "npm run build && node dist/src/index.js"
   },
   "dependencies": {

package.json

@@ -30,6 +30,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 exec --bail false npm -- publish",
     "release:rc": "aegir release-rc",

packages/bitswap/src/index.ts

@@ -7,7 +7,7 @@
  */
 
 import { Bitswap as BitswapClass } from './bitswap.js'
-import type { BitswapNetworkNotifyProgressEvents, BitswapNetworkWantProgressEvents } from './network.js'
+import type { BitswapNetworkNotifyProgressEvents, BitswapNetworkWantProgressEvents, BitswapNetworkProgressEvents } from './network.js'
 import type { WantType } from './pb/message.js'
 import type { BlockBroker, CreateSessionOptions } from '@helia/interface'
 import type { Routing } from '@helia/interface/routing'
@@ -28,6 +28,11 @@ export type BitswapWantBlockProgressEvents =
   ProgressEvent<'bitswap:want-block:block', CID> |
   BitswapNetworkWantProgressEvents
 
+export type { BitswapNetworkNotifyProgressEvents }
+export type { BitswapNetworkWantProgressEvents }
+export type { BitswapNetworkProgressEvents }
+export type { WantType }
+
 export interface WantListEntry {
   cid: CID
   priority: number

packages/block-brokers/package.json

@@ -43,6 +43,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "test": "aegir test",
     "test:chrome": "aegir test -t browser --cov",

packages/block-brokers/src/bitswap.ts

@@ -6,23 +6,23 @@ import type { Blockstore } from 'interface-blockstore'
 import type { CID } from 'multiformats/cid'
 import type { MultihashHasher } from 'multiformats/hashes/interface'
 
-interface BitswapComponents {
+export interface BitswapBlockBrokerComponents {
   libp2p: Libp2p
   blockstore: Blockstore
   routing: Routing
   logger: ComponentLogger
   getHasher: HasherLoader
 }
 
-export interface BitswapInit extends BitswapOptions {
+export interface BitswapBlockBrokerInit extends BitswapOptions {
 
 }
 
 class BitswapBlockBroker implements BlockBroker<BitswapWantBlockProgressEvents, BitswapNotifyProgressEvents>, Startable {
   private readonly bitswap: Bitswap
   private started: boolean
 
-  constructor (components: BitswapComponents, init: BitswapInit = {}) {
+  constructor (components: BitswapBlockBrokerComponents, init: BitswapBlockBrokerInit = {}) {
     const { getHasher } = components
 
     this.bitswap = createBitswap(components, {
@@ -77,6 +77,6 @@ class BitswapBlockBroker implements BlockBroker<BitswapWantBlockProgressEvents,
  * A helper factory for users who want to override Helia `blockBrokers` but
  * still want to use the default `BitswapBlockBroker`.
  */
-export function bitswap (init: BitswapInit = {}): (components: BitswapComponents) => BlockBroker {
+export function bitswap (init: BitswapBlockBrokerInit = {}): (components: BitswapBlockBrokerComponents) => BlockBroker {
   return (components) => new BitswapBlockBroker(components, init)
 }

packages/block-brokers/src/index.ts

@@ -1,2 +1,4 @@
 export { bitswap } from './bitswap.js'
+export type { BitswapBlockBrokerInit, BitswapBlockBrokerComponents } from './bitswap.js'
 export { trustlessGateway } from './trustless-gateway/index.js'
+export type { TrustlessGatewayBlockBrokerInit, TrustlessGatewayBlockBrokerComponents, TrustlessGatewayGetBlockProgressEvents } from './trustless-gateway/index.js'

packages/block-brokers/src/trustless-gateway/broker.ts

@@ -1,7 +1,7 @@
 import { createTrustlessGatewaySession } from './session.js'
 import { findHttpGatewayProviders } from './utils.js'
 import { DEFAULT_ALLOW_INSECURE, DEFAULT_ALLOW_LOCAL } from './index.js'
-import type { TrustlessGatewayBlockBrokerInit, TrustlessGatewayComponents, TrustlessGatewayGetBlockProgressEvents } from './index.js'
+import type { TrustlessGatewayBlockBrokerInit, TrustlessGatewayBlockBrokerComponents, TrustlessGatewayGetBlockProgressEvents } from './index.js'
 import type { Routing, BlockRetrievalOptions, BlockBroker, CreateSessionOptions } from '@helia/interface'
 import type { ComponentLogger, Logger } from '@libp2p/interface'
 import type { CID } from 'multiformats/cid'
@@ -35,7 +35,7 @@ export class TrustlessGatewayBlockBroker implements BlockBroker<TrustlessGateway
   private readonly log: Logger
   private readonly logger: ComponentLogger
 
-  constructor (components: TrustlessGatewayComponents, init: TrustlessGatewayBlockBrokerInit = {}) {
+  constructor (components: TrustlessGatewayBlockBrokerComponents, init: TrustlessGatewayBlockBrokerInit = {}) {
     this.log = components.logger.forComponent('helia:trustless-gateway-block-broker')
     this.logger = components.logger
     this.routing = components.routing

packages/block-brokers/src/trustless-gateway/index.ts

@@ -27,11 +27,11 @@ export interface TrustlessGatewayBlockBrokerInit {
   allowLocal?: boolean
 }
 
-export interface TrustlessGatewayComponents {
+export interface TrustlessGatewayBlockBrokerComponents {
   routing: Routing
   logger: ComponentLogger
 }
 
-export function trustlessGateway (init: TrustlessGatewayBlockBrokerInit = {}): (components: TrustlessGatewayComponents) => BlockBroker<TrustlessGatewayGetBlockProgressEvents> {
+export function trustlessGateway (init: TrustlessGatewayBlockBrokerInit = {}): (components: TrustlessGatewayBlockBrokerComponents) => BlockBroker<TrustlessGatewayGetBlockProgressEvents> {
   return (components) => new TrustlessGatewayBlockBroker(components, init)
 }

packages/car/README.md

@@ -46,13 +46,13 @@ import { CarWriter } from '@ipld/car'
 import { Readable } from 'node:stream'
 import nodeFs from 'node:fs'
 
-const helia = createHelia({
+const helia = await createHelia({
   // ... helia config
 })
 const fs = unixfs(helia)
 
 // add some UnixFS data
-const cid = await fs.addBytes(fileData1)
+const cid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3, 4]))
 
 // export it as a Car
 const c = car(helia)
@@ -75,14 +75,15 @@ import { CarReader } from '@ipld/car'
 import { Readable } from 'node:stream'
 import nodeFs from 'node:fs'
 
-const helia = createHelia({
+const helia = await createHelia({
   // ... helia config
 })
 
 // import the car
 const inStream = nodeFs.createReadStream('example.car')
 const reader = await CarReader.fromIterable(inStream)
 
+const c = car(helia)
 await c.import(reader)
 ```
 

packages/car/package.json

@@ -128,6 +128,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "test": "aegir test",
     "test:chrome": "aegir test -t browser --cov",

packages/car/src/index.ts

@@ -17,13 +17,13 @@
  * import { Readable } from 'node:stream'
  * import nodeFs from 'node:fs'
  *
- * const helia = createHelia({
+ * const helia = await createHelia({
  *   // ... helia config
  * })
  * const fs = unixfs(helia)
  *
  * // add some UnixFS data
- * const cid = await fs.addBytes(fileData1)
+ * const cid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3, 4]))
  *
  * // export it as a Car
  * const c = car(helia)
@@ -46,14 +46,15 @@
  * import { Readable } from 'node:stream'
  * import nodeFs from 'node:fs'
  *
- * const helia = createHelia({
+ * const helia = await createHelia({
  *   // ... helia config
  * })
  *
  * // import the car
  * const inStream = nodeFs.createReadStream('example.car')
  * const reader = await CarReader.fromIterable(inStream)
  *
+ * const c = car(helia)
  * await c.import(reader)
  * ```
  */
@@ -78,7 +79,7 @@ export interface CarComponents {
   getCodec: CodecLoader
 }
 
-interface ExportCarOptions extends AbortOptions, ProgressOptions<GetBlockProgressEvents> {
+export interface ExportCarOptions extends AbortOptions, ProgressOptions<GetBlockProgressEvents> {
   /**
    * If a filter is passed it will be used to deduplicate blocks exported in the car file
    */

packages/dag-cbor/README.md

@@ -41,8 +41,10 @@ import { createHelia } from 'helia'
 import { dagCbor } from '@helia/dag-cbor'
 import { CID } from 'multiformats/cid'
 
+const helia = await createHelia()
+
 const d = dagCbor(helia)
-const cid = await d.put({
+const cid = await d.add({
   hello: 'world'
 })
 const obj = await d.get(cid)

packages/dag-cbor/package.json

@@ -128,6 +128,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "docs": "aegir docs",
     "test": "aegir test",

packages/dag-cbor/src/index.ts

@@ -12,8 +12,10 @@
  * import { dagCbor } from '@helia/dag-cbor'
  * import { CID } from 'multiformats/cid'
  *
+ * const helia = await createHelia()
+ *
  * const d = dagCbor(helia)
- * const cid = await d.put({
+ * const cid = await d.add({
  *   hello: 'world'
  * })
  * const obj = await d.get(cid)
@@ -75,9 +77,12 @@ export interface DAGCBOR {
    * @example
    *
    * ```typescript
+   * import { createHelia } from 'helia'
    * import { dagCbor } from '@helia/dag-cbor'
    * import { CID } from 'multiformats/cid'
    *
+   * const helia = await createHelia()
+   *
    * const d = dagCbor(helia)
    * const cid = CID.parse('bafyreidykglsfhoixmivffc5uwhcgshx4j465xwqntbmu43nb2dzqwfvae')
    * const obj = await d.get(cid)

packages/dag-json/README.md

@@ -38,11 +38,13 @@ See the DAGJSON interface for all available operations.
 
 ```typescript
 import { createHelia } from 'helia'
-import { json } from '@helia/dag-json'
+import { dagJson } from '@helia/dag-json'
 import { CID } from 'multiformats/cid'
 
-const j = json(helia)
-const cid = await j.put({
+const helia = await createHelia()
+const j = dagJson(helia)
+
+const cid = await j.add({
   hello: 'world'
 })
 const obj = await j.get(cid)

packages/dag-json/package.json

@@ -128,6 +128,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "test": "aegir test",
     "test:chrome": "aegir test -t browser --cov",

packages/dag-json/src/index.ts

@@ -9,11 +9,13 @@
  *
  * ```typescript
  * import { createHelia } from 'helia'
- * import { json } from '@helia/dag-json'
+ * import { dagJson } from '@helia/dag-json'
  * import { CID } from 'multiformats/cid'
  *
- * const j = json(helia)
- * const cid = await j.put({
+ * const helia = await createHelia()
+ * const j = dagJson(helia)
+ *
+ * const cid = await j.add({
  *   hello: 'world'
  * })
  * const obj = await j.get(cid)
@@ -57,9 +59,12 @@ export interface DAGJSON {
    * @example
    *
    * ```typescript
-   * import { json } from '@helia/dag-json'
+   * import { createHelia } from 'helia'
+   * import { dagJson } from '@helia/dag-json'
+   *
+   * const helia = await createHelia()
+   * const j = dagJson(helia)
    *
-   * const j = json(helia)
    * const cid = await str.add({ hello: 'world' })
    *
    * console.info(cid)
@@ -75,10 +80,13 @@ export interface DAGJSON {
    * @example
    *
    * ```typescript
-   * import { json } from '@helia/dag-json'
+   * import { createHelia } from 'helia'
+   * import { dagJson } from '@helia/dag-json'
    * import { CID } from 'multiformats/cid'
    *
-   * const j = json(helia)
+   * const helia = await createHelia()
+   * const j = dagJson(helia)
+   *
    * const cid = CID.parse('baguqeerasords4njcts6vs7qvdjfcvgnume4hqohf65zsfguprqphs3icwea')
    * const obj = await j.get(cid)
    *

packages/helia/package.json

@@ -43,6 +43,7 @@
     "clean": "aegir clean",
     "lint": "aegir lint",
     "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check",
     "build": "aegir build",
     "test": "aegir test",
     "test:chrome": "aegir test -t browser --cov",

packages/helia/src/index.ts

@@ -27,6 +27,7 @@ import { HeliaP2P } from './helia-p2p.js'
 import { libp2pDefaults } from './utils/libp2p-defaults.js'
 import { createLibp2p } from './utils/libp2p.js'
 import type { DefaultLibp2pServices } from './utils/libp2p-defaults.js'
+import type { Libp2pDefaultsOptions } from './utils/libp2p.js'
 import type { Helia } from '@helia/interface'
 import type { HeliaInit as HeliaClassInit } from '@helia/utils'
 import type { Libp2p } from '@libp2p/interface'
@@ -38,7 +39,7 @@ import type { CID } from 'multiformats/cid'
 // if they don't want to
 export * from '@helia/interface'
 
-export type { DefaultLibp2pServices }
+export type { DefaultLibp2pServices, Libp2pDefaultsOptions }
 export { libp2pDefaults }
 
 /**

packages/http/README.md

@@ -54,18 +54,19 @@ fs.cat(CID.parse('bafyFoo'))
 ```typescript
 import { createHeliaHTTP } from '@helia/http'
 import { trustlessGateway } from '@helia/block-brokers'
-import { delegatedHTTPRouting } from '@helia/routers'
+import { delegatedHTTPRouting, httpGatewayRouting } from '@helia/routers'
 import { unixfs } from '@helia/unixfs'
 import { CID } from 'multiformats/cid'
 
 const helia = await createHeliaHTTP({
   blockBrokers: [
-    trustlessGateway({
-      gateways: ['https://cloudflare-ipfs.com', 'https://ipfs.io'],
-    }),
+    trustlessGateway()
   ],
   routers: [
-    delegatedHTTPRouting('https://delegated-ipfs.dev')
+    delegatedHTTPRouting('https://delegated-ipfs.dev'),
+    httpGatewayRouting({
+      gateways: ['https://cloudflare-ipfs.com', 'https://ipfs.io']
+    })
   ]
 })