From 5b8ef7d18b9c6472f1a24384558ae48d31358000 Mon Sep 17 00:00:00 2001
From: Alan Shaw <alan.shaw@protocol.ai>
Date: Tue, 22 Nov 2022 15:43:45 +0000
Subject: [PATCH] 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`.
---
 packages/upload-client/README.md          | 39 ++++++++++++++++++++++-
 packages/upload-client/src/index.js       |  2 +-
 packages/upload-client/src/types.ts       |  2 +-
 packages/upload-client/test/index.test.js |  8 ++---
 4 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/packages/upload-client/README.md b/packages/upload-client/README.md
index 16fec11d9..bed958a45 100644
--- 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,6 +397,31 @@ 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`:
@@ -402,6 +429,16 @@ This is the configuration for the UCAN invocation. It's values can be obtained f
 - 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
index c461c0e58..e0d3deba2 100644
--- 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
index 4afa492ee..247dbe921 100644
--- 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
index fc26fcb3f..d82f01cbd 100644
--- 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),
       }
     )