chore: add readme

Author: vasco-santos

README.md

@@ -31,81 +31,81 @@ This library provides functionality similar to [ipfs-unixfs-importer][], but it
 You can encode a file as follows
 
 ```js
-import * as UnixFS from "@ipld/unixfs"
+import * as UnixFS from "@ipld/unixfs";
 
 // Create a redable & writable streams with internal queue that can
 // hold around 32 blocks
 const { readable, writable } = new TransformStream(
   {},
   UnixFS.withCapacity(1048576 * 32)
-)
+);
 // Next we create a writer with filesystem like API for encoding files and
 // directories into IPLD blocks that will come out on `readable` end.
-const writer = UnixFS.createWriter({ writable })
+const writer = UnixFS.createWriter({ writable });
 
 // Create file writer that can be used to encode UnixFS file.
-const file = UnixFS.createFileWriter(writer)
+const file = UnixFS.createFileWriter(writer);
 // write some content
-file.write(new TextEncoder().encode("hello world"))
+file.write(new TextEncoder().encode("hello world"));
 // Finalize file by closing it.
-const { cid } = await file.close()
+const { cid } = await file.close();
 
 // close the writer to close underlying block stream.
-writer.close()
+writer.close();
 
 // We could encode all this as car file
-encodeCAR({ roots: [cid], blocks: readable })
+encodeCAR({ roots: [cid], blocks: readable });
 ```
 
 You can encode (non sharded) directories with provided API as well
 
 ```ts
-import * as UnixFS from "@ipld/unixfs"
+import * as UnixFS from "@ipld/unixfs";
 
 export const demo = async () => {
-  const { readable, writable } = new TransformStream()
-  const writer = UnixFS.createWriter({ writable })
+  const { readable, writable } = new TransformStream();
+  const writer = UnixFS.createWriter({ writable });
 
   // write a file
-  const file = UnixFS.createFileWriter(writer)
-  file.write(new TextEncoder().encode("hello world"))
-  const fileLink = await file.close()
+  const file = UnixFS.createFileWriter(writer);
+  file.write(new TextEncoder().encode("hello world"));
+  const fileLink = await file.close();
 
   // create directory and add a file we encoded above
-  const dir = UnixFS.createDirectoryWriter(writer)
-  dir.set("intro.md", fileLink)
-  const dirLink = await dir.close()
+  const dir = UnixFS.createDirectoryWriter(writer);
+  dir.set("intro.md", fileLink);
+  const dirLink = await dir.close();
 
   // now wrap above directory with another and also add the same file
   // there
-  const root = UnixFS.createDirectoryWriter(fs)
-  root.set("user", dirLink)
-  root.set("hello.md", fileLink)
+  const root = UnixFS.createDirectoryWriter(fs);
+  root.set("user", dirLink);
+  root.set("hello.md", fileLink);
 
   // Creates following UnixFS structure where intro.md and hello.md link to same
   // IPFS file.
   // ./
   // ./user/intro.md
   // ./hello.md
-  const rootLink = await root.close()
+  const rootLink = await root.close();
   // ...
-  writer.close()
-}
+  writer.close();
+};
 ```
 
 ### Configuration
 
 You can configure DAG layout, chunking and bunch of other things by providing API compatible components. Library provides bunch of them but you can also bring your own.
 
 ```js
-import * as UnixFS from "@ipld/unixfs"
-import * as Rabin from "@ipld/unixfs/file/chunker/rabin"
-import * as Trickle from "@ipld/unixfs/file/layout/trickle"
-import * as RawLeaf from "multiformats/codecs/raw"
-import { sha256 } from "multiformats/hashes/sha2"
-
-const demo = async blob => {
-  const { readable, writable } = new TransformStream()
+import * as UnixFS from "@ipld/unixfs";
+import * as Rabin from "@ipld/unixfs/file/chunker/rabin";
+import * as Trickle from "@ipld/unixfs/file/layout/trickle";
+import * as RawLeaf from "multiformats/codecs/raw";
+import { sha256 } from "multiformats/hashes/sha2";
+
+const demo = async (blob) => {
+  const { readable, writable } = new TransformStream();
   const writer = UnixFS.createWriter({
     writable,
     // you can pass only things you want to override
@@ -122,11 +122,90 @@ const demo = async blob => {
       fileEncoder: UnixFS,
       hasher: sha256,
     },
-  })
+  });
 
-  const file = UnixFS.createFileWriter(writer)
+  const file = UnixFS.createFileWriter(writer);
   // ...
+};
+```
+
+### Collecting UnixFS FileLinks
+
+You can optionally pass a unixFsFileLinkWriter stream to capture metadata for each link (useful for indexing or tracking layout information).
+
+```js
+import { createWriter, createFileWriter } from "@vascosantos/unixfs";
+
+import { withMaxChunkSize } from "@vascosantos/unixfs/file/chunker/fixed";
+import { withWidth } from "@vascosantos/unixfs/file/layout/balanced";
+
+const defaultSettings = UnixFS.configure({
+  fileChunkEncoder: raw,
+  smallFileEncoder: raw,
+  chunker: withMaxChunkSize(1024 * 1024),
+  fileLayout: withWidth(1024),
+});
+
+/**
+ * @param {Blob} blob
+ * @returns {Promise<import('@vascosantos/unixfs').FileLink[]>}
+ */
+async function collectUnixFsFileLinks(blob) {
+  const fileLinks = [];
+
+  // Create a stream to collect metadata (FileLinks)
+  const { readable, writable } = new TransformStream();
+
+  // Set up the main UnixFS writer (data goes nowhere here)
+  const unixfsWriter = createWriter({
+    writable: new WritableStream(), // Discard actual DAG output
+    settings: defaultSettings,
+  });
+
+  // Set up the file writer with link metadata writer
+  const unixFsFileLinkWriter = writable.getWriter();
+
+  const fileWriter = createFileWriter({
+    ...unixfsWriter,
+    initOptions: {
+      unixFsFileLinkWriter,
+    },
+  });
+
+  // Start concurrent reading of the metadata stream
+  const fileLinkReader = readable.getReader();
+  const readLinks = (async () => {
+    while (true) {
+      const { done, value } = await fileLinkReader.read();
+      if (done) break;
+      fileLinks.push(value);
+    }
+  })();
+
+  // Pipe the blob to the file writer
+  await blob.stream().pipeTo(
+    new WritableStream({
+      async write(chunk) {
+        await fileWriter.write(chunk);
+      },
+    })
+  );
+
+  // Finalize everything
+  await fileWriter.close();
+  await unixfsWriter.close();
+  await unixFsFileLinkWriter.close();
+
+  // Wait for all links to be read
+  await readLinks;
+
+  return fileLinks;
 }
+
+// Usage
+const blob = new Blob(["Hello UnixFS links"]);
+const links = await collectUnixFsFileLinks(blob);
+console.log(links);
 ```
 
 ## License