docs: add example for full DAG-JSON put & retrieval

packages/client/examples/node.js/README.md

@@ -6,6 +6,7 @@ Examples for using the web3.storage client from Node.js.
 - `put-files-from-fs.js` - Adds files from your file system to web3.storage
 - `put-car-from-fs.js` - Adds a Content Archive (CAR) file from your file system to web3.storage
 - `put-car-dag-cbor.js` - Creates a Content Archive in memory from IPLD data and adds to web3.storage
+- `put-and-retrieve-car-dag-json.ts` - Creates & pushes a Content Archive in memory from DAG-JSON IPLD data, retrieves and decodes it again
 
 See the [Working with CARs guide](https://web3.storage/docs/how-tos/work-with-car-files/) on the [Web3.Storage documentation site](https://web3.storage/docs) for more context about the examples relating to Content Archives.
 
@@ -26,4 +27,5 @@ node put-files.js --token=<YOUR_TOKEN>
 node put-files-from-fs.js --token=<YOUR_TOKEN>
 node put-car-from-fs.js --token=<YOUR_TOKEN>
 node put-car-dag-cbor.js --token=<YOUR_TOKEN>
+npx ts-node-esm put-and-retrieve-car-dag-json.ts --token=<YOUR_TOKEN>
 ```

packages/client/examples/node.js/package.json

@@ -8,9 +8,16 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
+    "@ipld/car": "^3.2.4",
+    "@ipld/dag-json": "^10.1.1",
     "minimist": "^1.2.5",
+    "multiformats": "^9.9.0",
     "web3.storage": "latest"
   },
   "author": "Vasco Santos",
-  "license": "(Apache-2.0 AND MIT)"
+  "license": "(Apache-2.0 AND MIT)",
+  "devDependencies": {
+    "@types/minimist": "^1.2.2",
+    "ts-node": "^10.9.1"
+  }
 }

packages/client/examples/node.js/put-and-retrieve-car-dag-json.ts

@@ -0,0 +1,95 @@
+import process from 'process'
+import minimist from 'minimist'
+import { CarReader, CarWriter } from '@ipld/car'
+import * as json from '@ipld/dag-json'
+import { encode } from 'multiformats/block'
+import { sha256 } from 'multiformats/hashes/sha2'
+import { Web3Storage } from 'web3.storage'
+
+// This file contains an example of uploading DAG-JSON-encoded IPLD data to Web3.Storage
+// by creating a Content Archive (CAR) and using the putCar client method.
+// It also shows how you can retrieve it again.
+//
+// See https://web3.storage/docs/how-tos/work-with-car-files/#advanced-ipld-formats
+
+async function main () {
+  const args = minimist(process.argv.slice(2))
+  const token = args['token']
+
+  if (!token) {
+    console.error('The argument --token is required. You can create one on https://web3.storage')
+    return
+  }
+
+  const storage = new Web3Storage({ token })
+  await exampleDagJsonStoreAndRetrieve(storage)
+}
+main()
+
+export async function exampleDagJsonStoreAndRetrieve(client: Web3Storage) {
+	const cid = await storeDagJSON(client, { 'foo': `TEST ${new Date()}` })
+	const data = await retrieveDagJSON(client, cid)
+	console.log('Final retrieved data:', data)
+}
+
+async function storeDagJSON(client: Web3Storage, jsonObject: any) {
+	// encode the json object into an IPLD block
+	const block = await encode({ value: jsonObject, codec: json, hasher: sha256 })
+
+	// create a new CarWriter, with the encoded block as the root
+	const { writer, out } = CarWriter.create([block.cid])
+
+	// add the block to the CAR and close it
+	writer.put(block)
+	writer.close()
+
+	// create a new CarReader we can hand to web3.storage.putCar
+	const reader = await CarReader.fromIterable(out)
+
+	// upload to web3.storage using putCar
+	const cid = await client.putCar(reader, {
+		name: 'putCar using dag-json',
+		// include the dag-json codec in the decoders field
+		decoders: [json],
+	})
+	console.log('Stored dag-json:', cid)
+	return cid
+}
+
+async function retrieveDagJSON(client: Web3Storage, cid: string) {
+	// Fetch the CAR file from web3.storage
+	console.log('Retrieving:', cid)
+	const response = await client.get(cid)
+	if (!response?.ok) {
+		throw new Error(`unexpected response ${response?.statusText}`)
+	}
+
+	// The data is an AsyncIterable<Uint8Array>, convert it to an AsyncIterable for the CarReader
+	const bodyReader = response.body!.getReader()
+	const data: AsyncIterable<Uint8Array> = (async function*() {
+		while (true) {
+			const { done, value } = await bodyReader.read()
+			if (done) {
+				break
+			}
+			yield value
+		}
+	})()
+
+	// Create a CarReader from the CAR data
+	const reader = await CarReader.fromIterable(data)
+
+	// Get the root CID
+	const [rootCid] = await reader.getRoots()
+	if (!rootCid) throw new Error("no root CID")
+
+	// Fetch the dag-json block
+	const block = await reader.get(rootCid)
+	if (!rootCid) throw new Error("root block not found")
+	console.log('block:', block!.cid)
+
+	// Decode the block to a JSON object
+	const jsonObject = json.decode(block!.bytes)
+
+	return jsonObject
+}