refactor!: rename callback (#198)

I keep getting this wrong, to the extent that I even documented it this way in the README. I think `on[noun][verb]` aligns better with DOM event callbacks e.g. `onMouseClick`.
storacha · Nov 22, 2022 · 2349763 · 2349763
1 parent d2296c5
commit 2349763
Show file tree

Hide file tree

Showing 4 changed files with 44 additions and 7 deletions.
diff --git a/packages/upload-client/README.md b/packages/upload-client/README.md
@@ -144,7 +144,9 @@ await Upload.add(conf, rootCID, carCIDs)
  - [`Upload.remove`](#uploadremove)
 - [Types](#types)
  - [`CARFile`](#carfile)
+ - [`CARMetadata`](#carmetadata)
  - [`InvocationConfig`](#invocationconfig)
+ - [`ShardStoredCallback`](#shardstoredcallback)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -169,7 +171,7 @@ Uploads a directory of files to the service and returns the root data CID for th
 
 Required delegated capability proofs: `store/add`, `upload/add`
 
-More information: [`InvocationConfig`](#invocationconfig)
+More information: [`InvocationConfig`](#invocationconfig), [`ShardStoredCallback`](#shardstoredcallback)
 
 ### `uploadFile`
 
@@ -395,13 +397,48 @@ A `Blob` with two extra properties:
 type CARFile = Blob & { version: 1; roots: CID[] }
 ```
 
+### `CARMetadata`
+
+Metadata pertaining to a CAR file.
+
+```ts
+export interface CARMetadata {
+ /**
+ * CAR version number.
+ */
+ version: number
+ /**
+ * Root CIDs present in the CAR header.
+ */
+ roots: CID[]
+ /**
+ * CID of the CAR file (not the data it contains).
+ */
+ cid: CID
+ /**
+ * Size of the CAR file in bytes.
+ */
+ size: number
+}
+```
+
 ### `InvocationConfig`
 
 This is the configuration for the UCAN invocation. It's values can be obtained from an `Agent`. See [Create an Agent](#create-an-agent) for an example. It is an object with `issuer` and `proofs`:
 
 - The `issuer` is the signing authority that is issuing the UCAN invocation(s). It is typically the user _agent_.
 - The `proofs` are a set of capability delegations that prove the issuer has the capability to perform the action.
 
+### `ShardStoredCallback`
+
+A function called after a DAG shard has been successfully stored by the service:
+
+```ts
+type ShardStoredCallback = (meta: CARMetadata) => void
+```
+
+More information: [`CARMetadata`](#carmetadata)
+
 ## Contributing
 
 Feel free to join in. All welcome. Please [open an issue](https://github.com/web3-storage/w3protocol/issues)!

diff --git a/packages/upload-client/src/index.js b/packages/upload-client/src/index.js
@@ -87,7 +87,7 @@ async function uploadBlockStream(conf, blocks, options = {}) {
  write(meta) {
  root = root || meta.roots[0]
  shards.push(meta.cid)
- if (options.onStoredShard) options.onStoredShard(meta)
+ if (options.onShardStored) options.onShardStored(meta)
  },
  })
  )

diff --git a/packages/upload-client/src/types.ts b/packages/upload-client/src/types.ts
@@ -161,7 +161,7 @@ export interface ShardingOptions {
 }
 
 export interface UploadOptions extends RequestOptions, ShardingOptions {
- onStoredShard?: (meta: CARMetadata) => void
+ onShardStored?: (meta: CARMetadata) => void
 }
 
 export interface BlobLike {

diff --git a/packages/upload-client/test/index.test.js b/packages/upload-client/test/index.test.js
@@ -84,7 +84,7 @@ describe('uploadFile', () => {
  file,
  {
  connection,
- onStoredShard: (meta) => {
+ onShardStored: (meta) => {
  carCID = meta.cid
  },
  }
@@ -150,7 +150,7 @@ describe('uploadFile', () => {
  {
  connection,
  shardSize: 400_000, // should end up with 2 CAR files
- onStoredShard: (meta) => carCIDs.push(meta.cid),
+ onShardStored: (meta) => carCIDs.push(meta.cid),
  }
  )
 
@@ -232,7 +232,7 @@ describe('uploadDirectory', () => {
  files,
  {
  connection,
- onStoredShard: (meta) => {
+ onShardStored: (meta) => {
  carCID = meta.cid
  },
  }
@@ -298,7 +298,7 @@ describe('uploadDirectory', () => {
  {
  connection,
  shardSize: 400_000, // should end up with 2 CAR files
- onStoredShard: (meta) => carCIDs.push(meta.cid),
+ onShardStored: (meta) => carCIDs.push(meta.cid),
  }
  )