@thi.ng/block-fs 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-02T10:24:13Z
+- **Last updated**: 2025-04-02T18:47:59Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,30 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/block-fs@0.3.0) (2025-04-02)
+
+#### 🚀 Features
+
+- add `BlockFS.readAsObjectURL()` ([551327c](https://github.com/thi-ng/umbrella/commit/551327c))
+- add mem storage opts, add logging ([27016d6](https://github.com/thi-ng/umbrella/commit/27016d6))
+  - add `MemoryBlockStorage` support for pre-loaded buffers
+  - add logging
+  - add docs
+- add CLI app wrapper ([68abe74](https://github.com/thi-ng/umbrella/commit/68abe74))
+  - add CLI app wrapper with these commands:
+    - `convert`: convert file tree into single BlockFS blob
+    - `list`: list file tree of a BlockFS blob
+  - update deps
+- improve tree display (`list` cmd) ([a23866c](https://github.com/thi-ng/umbrella/commit/a23866c))
+
+#### 🩹 Bug fixes
+
+- fix parent dir linkage ([a121e76](https://github.com/thi-ng/umbrella/commit/a121e76))
+
+#### ♻️ Refactoring
+
+- update sentinel block ID ([51a1e44](https://github.com/thi-ng/umbrella/commit/51a1e44))
+
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/block-fs@0.2.0) (2025-04-02)
 
 #### 🚀 Features

package/README.md

@@ -21,6 +21,9 @@
     - [Root directory](#root-directory)
     - [Directory entries](#directory-entries)
     - [File blocks](#file-blocks)
+  - [Command line app](#command-line-app)
+    - [Convert file tree into single BlockFS blob](#convert-file-tree-into-single-blockfs-blob)
+    - [List file tree of a BlockFS blob](#list-file-tree-of-a-blockfs-blob)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -102,6 +105,121 @@ the max. number of blocks in the storage backend.
 
 TODO diagram
 
+### Command line app
+
+The package includes a mult-command CLI app with the following operations:
+
+#### Convert file tree into single BlockFS blob
+
+The `convert` command is used to bundle an entire file tree from the host system
+into a single binary blob based on `BlockFS` with configured block size. The
+file tree MUST fit into the RAM available to `bun` (or `node`).
+
+Once bundled, the binary blob can then be used together with
+[`MemoryBlockStorage`](https://docs.thi.ng/umbrella/block-fs/classes/MemoryBlockStorage.html)
+and [`BlockFS`](https://docs.thi.ng/umbrella/block-fs/classes/BlockFS.html) for
+other purposes (e.g. distributed with your web app to provide a virtual
+filesystem).
+
+Example usage to bundle the source directory of this package:
+
+```bash
+npx @thi.ng/block-fs convert -o dummy.dat packages/block-fs/src/
+
+# [INFO] blockfs: number of files: 11
+# [INFO] blockfs: number of directories: 2
+# [INFO] blockfs: total file size: 40341
+# [INFO] blockfs: number of blocks: 56
+# [INFO] blockfs: writing file: dummy.dat
+```
+
+General usage:
+
+```text
+npx @thi.ng/block-fs convert --help
+
+Usage: blockfs <cmd> [opts] input
+
+Flags:
+
+-v, --verbose                   Display extra process information
+
+Main:
+
+-bs BYTES, --block-size BYTES   Block size (default: 1024)
+-n INT, --num-blocks INT        Number of blocks (multiple of 8)
+-o STR, --out STR               [required] Output file path
+```
+
+#### List file tree of a BlockFS blob
+
+The `list` command is used to list the files & directories stored in a binary blob created via the `convert` command. Several output options (e.g. `tree`-like output) are supported.
+
+```bash
+npx @thi.ng/block-fs list dummy.dat
+# /api.ts
+# /cli.ts
+# /directory.ts
+# /entry.ts
+# /fs.ts
+# /index.ts
+# /lock.ts
+# /storage
+# /storage/astorage.ts
+# /storage/file.ts
+# /storage/memory.ts
+# /utils.ts
+
+npx @thi.ng/block-fs list --tree dummy.dat
+# ├── api.ts
+# ├── cli.ts
+# ├── directory.ts
+# ├── entry.ts
+# ├── fs.ts
+# ├── index.ts
+# ├── lock.ts
+# ├── storage
+# │   ├── astorage.ts
+# │   ├── file.ts
+# │   └── memory.ts
+# └── utils.ts
+
+# display file sizes & modification times
+npx @thi.ng/block-fs list --tree --all dummy.dat
+# ├── api.ts           2204   2025-04-02T10:22:55.573Z
+# ├── cli.ts           6799   2025-04-02T18:07:58.895Z
+# ├── directory.ts     3994   2025-04-02T13:47:00.108Z
+# ├── entry.ts         4130   2025-04-02T10:22:55.574Z
+# ├── fs.ts            16377  2025-04-02T13:46:36.608Z
+# ├── index.ts         317    2025-04-01T21:38:08.232Z
+# ├── lock.ts          1501   2025-04-01T21:38:08.232Z
+# ├── storage                 2025-04-02T18:33:47.389Z
+# │   ├── astorage.ts  1205   2025-04-02T10:22:55.574Z
+# │   ├── file.ts      1780   2025-04-02T14:25:12.461Z
+# │   └── memory.ts    1802   2025-04-02T14:26:02.163Z
+# └── utils.ts         418    2025-04-02T10:22:55.574Z
+```
+
+General usage:
+
+```text
+npx @thi.ng/block-fs list --help
+
+Usage: blockfs <cmd> [opts] input
+
+Flags:
+
+-a, --all                       Display all attribs
+-t, --tree                      List files as tree
+-v, --verbose                   Display extra process information
+-m, --with-mtime                Display modified times
+-s, --with-size                 Display file sizes
+
+Main:
+
+-bs BYTES, --block-size BYTES   Block size (default: 1024)
+```
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -134,11 +252,12 @@ For Node.js REPL:
 const bf = await import("@thi.ng/block-fs");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.32 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.43 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/args](https://github.com/thi-ng/umbrella/tree/develop/packages/args)
 - [@thi.ng/binary](https://github.com/thi-ng/umbrella/tree/develop/packages/binary)
 - [@thi.ng/bitfield](https://github.com/thi-ng/umbrella/tree/develop/packages/bitfield)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)

package/bin/blockfs

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+# https://stackoverflow.com/a/246128/294515
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+DIR="$(dirname $DIR)"
+
+# prefer using bun
+if [ -x "$(command -v bun)" ]; then
+  CMD=bun
+else
+  CMD=node
+fi
+
+/usr/bin/env $CMD "$DIR/cli.js" "$DIR" "$@"

package/cli.d.ts

@@ -0,0 +1,23 @@
+import { type Command, type CommandCtx } from "@thi.ng/args";
+interface CLIOpts {
+    verbose: boolean;
+}
+interface ConvertOpts extends CLIOpts {
+    numBlocks?: number;
+    blockSize: number;
+    include?: string[];
+    out: string;
+}
+interface ListOpts extends CLIOpts {
+    blockSize: number;
+    all: boolean;
+    tree: boolean;
+    withMtime: boolean;
+    withSize: boolean;
+}
+export interface AppCtx<T extends CLIOpts> extends CommandCtx<T, CLIOpts> {
+}
+export declare const CONVERT: Command<ConvertOpts, CLIOpts, AppCtx<ConvertOpts>>;
+export declare const LIST: Command<ListOpts, CLIOpts, AppCtx<ListOpts>>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/cli.js

@@ -0,0 +1,214 @@
+import {
+  cliApp,
+  flag,
+  int,
+  string,
+  strings
+} from "@thi.ng/args";
+import { align, isPow2 } from "@thi.ng/binary";
+import { illegalArgs } from "@thi.ng/errors";
+import { files, readBinary, readJSON, writeFile } from "@thi.ng/file-io";
+import { LogLevel } from "@thi.ng/logger";
+import { statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { Entry } from "./entry.js";
+import { BlockFS } from "./fs.js";
+import { MemoryBlockStorage } from "./storage/memory.js";
+const PKG = readJSON(join(process.argv[2], "package.json"));
+const ARG_BLOCKSIZE = {
+  blockSize: int({
+    alias: "bs",
+    desc: "Block size",
+    hint: "BYTES",
+    default: 1024,
+    coerce: (x) => {
+      const size = +x;
+      if (!isPow2(size)) illegalArgs("block size must be a power of 2");
+      return size;
+    }
+  })
+};
+const collectFiles = (ctx) => {
+  const root = resolve(ctx.inputs[0]);
+  const filtered = [];
+  const dirs = /* @__PURE__ */ new Set();
+  let total = 0;
+  for (let f of files(root)) {
+    const stats = statSync(f);
+    if (stats.isFile()) {
+      const dest = relative(root, f);
+      filtered.push({
+        src: f,
+        dest,
+        size: stats.size,
+        ctime: stats.ctimeMs,
+        mtime: stats.mtimeMs
+      });
+      dirs.add(dirname(dest));
+      total += stats.size;
+    }
+  }
+  return { files: filtered, dirs: [...dirs], size: total };
+};
+const computeBlockCount = (collected, blockSize, numBlocks) => {
+  let blocks = collected.dirs.length;
+  const blockIDBytes = numBlocks ? align(Math.ceil(Math.log2(numBlocks)), 8) >> 3 : align(Math.ceil(Math.log2(collected.size / blockSize + blocks)), 8) >> 3;
+  const blockDataSizeBytes = align(Math.ceil(Math.log2(blockSize)), 8) >> 3;
+  const blockDataSize = blockSize - blockIDBytes - blockDataSizeBytes;
+  blocks += Math.ceil(
+    (collected.files.length + collected.dirs.length) * Entry.SIZE / blockDataSize
+  );
+  for (let f of collected.files) {
+    blocks += Math.ceil(f.size / blockDataSize);
+  }
+  const blockIDBytes2 = align(Math.ceil(Math.log2(blocks)), 8) >> 3;
+  return blockIDBytes2 > blockIDBytes ? computeBlockCount(collected, blockSize, blocks) : blocks;
+};
+const CONVERT = {
+  opts: {
+    ...ARG_BLOCKSIZE,
+    numBlocks: int({
+      alias: "n",
+      desc: "Number of blocks (multiple of 8)",
+      optional: true
+    }),
+    out: string({
+      alias: "o",
+      desc: "Output file path",
+      optional: false
+    }),
+    include: strings({
+      alias: "i",
+      desc: "Only include file extensions",
+      hint: "EXT"
+    })
+  },
+  desc: "Convert file tree into single BlockFS blob",
+  fn: async (ctx) => {
+    const collected = collectFiles(ctx);
+    const numBlocks = align(
+      ctx.opts.numBlocks ?? computeBlockCount(collected, ctx.opts.blockSize),
+      8
+    );
+    ctx.logger.info("number of files:", collected.files.length);
+    ctx.logger.info("number of directories:", collected.dirs.length);
+    ctx.logger.info("total file size:", collected.size);
+    ctx.logger.info("number of blocks:", numBlocks);
+    const storage = new MemoryBlockStorage({
+      numBlocks,
+      blockSize: ctx.opts.blockSize,
+      logger: ctx.logger
+    });
+    const bfs = new BlockFS(storage, { logger: ctx.logger });
+    await bfs.init();
+    for (let f of collected.files) {
+      ctx.logger.debug("writing file:", f.dest);
+      await bfs.writeFile(f.dest, readBinary(f.src));
+      const entry = await bfs.entryForPath(f.dest);
+      entry.ctime = f.ctime;
+      entry.mtime = f.mtime;
+      await entry.save();
+    }
+    writeFile(ctx.opts.out, storage.buffer, void 0, ctx.logger);
+  }
+};
+const LIST = {
+  opts: {
+    ...ARG_BLOCKSIZE,
+    all: flag({
+      alias: "a",
+      desc: "Display all attribs"
+    }),
+    tree: flag({
+      alias: "t",
+      desc: "List files as tree"
+    }),
+    withMtime: flag({
+      alias: "m",
+      desc: "Display modified times"
+    }),
+    withSize: flag({
+      alias: "s",
+      desc: "Display file sizes"
+    })
+  },
+  desc: "List file tree of a BlockFS blob",
+  fn: async (ctx) => {
+    if (ctx.opts.all) {
+      ctx.opts.withMtime = ctx.opts.withSize = true;
+    }
+    const buffer = readBinary(ctx.inputs[0]);
+    const storage = new MemoryBlockStorage({
+      numBlocks: buffer.length / ctx.opts.blockSize >>> 0,
+      blockSize: ctx.opts.blockSize,
+      logger: ctx.logger,
+      buffer
+    });
+    const bfs = new BlockFS(storage, { logger: ctx.logger });
+    await bfs.init();
+    const tree = [];
+    for await (let entry of bfs.root.tree()) {
+      const path = entry.path;
+      const depth = path.split("/").length - 2;
+      tree.push([path, depth, entry]);
+    }
+    tree.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const rows = [];
+    const maxWidths = [0, 0, 0];
+    for (let i = 0, num = tree.length - 1; i <= num; i++) {
+      const f = tree[i];
+      const isLast = i === num || f[1] > tree[i + 1][1];
+      const row = ctx.opts.tree ? ["\u2502   ".repeat(f[1]) + (isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ") + f[2].name] : [f[0]];
+      if (ctx.opts.withSize) {
+        row.push(f[2].isDirectory() ? "" : String(Number(f[2].size)));
+      }
+      if (ctx.opts.withMtime) {
+        row.push(new Date(f[2].mtime).toISOString());
+      }
+      rows.push(row);
+      for (let i2 = 0; i2 < row.length; i2++) {
+        maxWidths[i2] = Math.max(maxWidths[i2], row[i2].length);
+      }
+    }
+    for (let row of rows) {
+      console.log(row.map((x, i) => x.padEnd(maxWidths[i])).join("  "));
+    }
+  }
+};
+cliApp({
+  opts: {
+    verbose: flag({
+      alias: "v",
+      desc: "Display extra process information"
+    })
+  },
+  commands: {
+    convert: CONVERT,
+    list: LIST
+  },
+  name: "blockfs",
+  ctx: async (ctx) => {
+    if (ctx.opts.verbose) ctx.logger.level = LogLevel.DEBUG;
+    return ctx;
+  },
+  start: 3,
+  usage: {
+    prefix: `
+ \u2588 \u2588   \u2588           \u2502
+\u2588\u2588 \u2588               \u2502
+ \u2588 \u2588 \u2588 \u2588   \u2588 \u2588 \u2588 \u2588 \u2502 ${PKG.name} ${PKG.version}
+ \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2502 Block-based storage & file system layer
+                 \u2588 \u2502
+               \u2588 \u2588 \u2502
+
+Usage: blockfs <cmd> [opts] input [...]
+       blockfs <cmd> --help
+`,
+    showGroupNames: true,
+    paramWidth: 32
+  }
+});
+export {
+  CONVERT,
+  LIST
+};

package/directory.js

@@ -65,7 +65,7 @@ class Directory {
     const block = (await fs.allocateBlocks(1))[0];
     const data = await fs.storage.loadBlock(block);
     fs.setBlockMeta(data, fs.sentinelID, 0);
-    fs.setBlockLink(data, this.entry.start, fs.dataStartBlockID);
+    fs.setBlockLink(data, this.entry.start, fs.blockDataOffset);
     await fs.storage.saveBlock(block, data);
     return this.addEntry(
       {

package/fs.d.ts

@@ -155,6 +155,19 @@ export declare class BlockFS {
      * @param path
      */
     readJSON<T>(path: string | number): Promise<T>;
+    /**
+     * Fully reads given file into a single byte buffer and returns it as blob
+     * object URL, optionally typed with given MIME type.
+     *
+     * @remarks
+     * Reference:
+     *
+     * - https://developer.mozilla.org/en-US/docs/Web/API/Blob#creating_a_url_representing_the_contents_of_a_typed_array
+     *
+     * @param path
+     * @param type
+     */
+    readAsObjectURL(path: string | number, type?: string): Promise<string>;
     /**
      * Takes an array of block IDs (or `null`) and a `data` byte array. Writes
      * chunks of data into given blocks and connecting each block as linked

package/fs.js

@@ -41,7 +41,7 @@ class BlockFS {
     this.rootDirBlockID = align(this.blockIndex.data.length, storage.blockSize) / storage.blockSize;
     this.dataStartBlockID = this.rootDirBlockID + 1;
     this.dirDataOffset = this.blockDataOffset + this.blockIDBytes;
-    this.sentinelID = storage.numBlocks - 1;
+    this.sentinelID = 2 ** (this.blockIDBytes * 8) - 1;
     this.tmp = new Uint8Array(storage.blockSize);
   }
   blockIndex;
@@ -284,6 +284,23 @@ class BlockFS {
   async readJSON(path) {
     return JSON.parse(await this.readText(path));
   }
+  /**
+   * Fully reads given file into a single byte buffer and returns it as blob
+   * object URL, optionally typed with given MIME type.
+   *
+   * @remarks
+   * Reference:
+   *
+   * - https://developer.mozilla.org/en-US/docs/Web/API/Blob#creating_a_url_representing_the_contents_of_a_typed_array
+   *
+   * @param path
+   * @param type
+   */
+  async readAsObjectURL(path, type) {
+    return URL.createObjectURL(
+      new Blob([await this.readFile(path)], { type })
+    );
+  }
   /**
    * Takes an array of block IDs (or `null`) and a `data` byte array. Writes
    * chunks of data into given blocks and connecting each block as linked

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@thi.ng/block-fs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Customizable block-based storage, adapters & file system layer",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
+  "bin": {
+    "blockfs": "bin/blockfs"
+  },
   "sideEffects": false,
   "repository": {
     "type": "git",
@@ -40,6 +43,7 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.11.25",
+    "@thi.ng/args": "^2.3.66",
     "@thi.ng/binary": "^3.4.48",
     "@thi.ng/bitfield": "^2.4.0",
     "@thi.ng/checks": "^3.7.5",
@@ -58,10 +62,13 @@
   "keywords": [
     "binary",
     "block",
+    "cli",
+    "conversion",
     "file",
     "file-system",
     "memory",
     "memory-mapped",
+    "nodejs",
     "path",
     "storage",
     "typedarray",
@@ -80,6 +87,7 @@
   "files": [
     "./*.js",
     "./*.d.ts",
+    "bin",
     "storage"
   ],
   "exports": {
@@ -89,6 +97,9 @@
     "./api": {
       "default": "./api.js"
     },
+    "./cli": {
+      "default": "./cli.js"
+    },
     "./directory": {
       "default": "./directory.js"
     },
@@ -118,5 +129,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "de166de7bb358998c797090a49bf55bcb7c325ba\n"
+  "gitHead": "549e798e6a82254ee68727f12229c5252892b8f1\n"
 }

package/storage/file.d.ts

@@ -8,7 +8,13 @@ export declare class FileBlock implements IBlock {
     save(data: Uint8Array): Promise<void>;
     delete(): Promise<void>;
 }
+/**
+ * Configuration options for {@link FileBlockStorage}.
+ */
 export interface FileBlockStorageOpts extends BlockStorageOpts {
+    /**
+     * Path to host filesystem base directory used for storing blocks.
+     */
     baseDir: string;
 }
 export declare class FileBlockStorage extends ABlockStorage<FileBlock> {

package/storage/file.js

@@ -11,18 +11,15 @@ class FileBlock {
     this.id = id;
   }
   async load() {
-    const path = this.storage.getPath(this.id);
-    return existsSync(path) ? readBinary(path, this.storage.logger) : new Uint8Array(this.storage.blockSize);
+    const { storage } = this;
+    const path = storage.getPath(this.id);
+    return existsSync(path) ? readBinary(path, storage.logger) : new Uint8Array(storage.blockSize);
   }
   async save(data) {
-    if (data.length !== this.storage.blockSize)
+    const { storage } = this;
+    if (data.length !== storage.blockSize)
       illegalArgs(`wrong block size: ${data.length}`);
-    writeFile(
-      this.storage.getPath(this.id),
-      data,
-      null,
-      this.storage.logger
-    );
+    writeFile(storage.getPath(this.id), data, null, storage.logger);
   }
   async delete() {
     deleteFile(this.storage.getPath(this.id), this.storage.logger);

package/storage/memory.d.ts

@@ -8,9 +8,19 @@ export declare class MemoryBlock implements IBlock {
     save(data: Uint8Array): Promise<void>;
     delete(): Promise<void>;
 }
+/**
+ * Configuration options for {@link MemoryBlockStorage}.
+ */
+export interface MemoryBlockStorageOpts extends BlockStorageOpts {
+    /**
+     * Optional, pre-defined/loaded byte buffer. Must have at least `numBlocks *
+     * blockSize` capacity.
+     */
+    buffer?: Uint8Array;
+}
 export declare class MemoryBlockStorage extends ABlockStorage<MemoryBlock> {
     buffer: Uint8Array;
-    constructor(opts: BlockStorageOpts);
+    constructor(opts: MemoryBlockStorageOpts);
     hasBlock(id: number): Promise<boolean>;
     ensureBlock(id: number): MemoryBlock;
 }

package/storage/memory.js

@@ -6,16 +6,16 @@ class MemoryBlock {
     this.id = id;
   }
   async load() {
-    const size = this.storage.blockSize;
-    return this.storage.buffer.subarray(
-      this.id * size,
-      (this.id + 1) * size
-    );
+    const { storage } = this;
+    storage.logger.debug("load block", this.id);
+    const size = storage.blockSize;
+    return storage.buffer.subarray(this.id * size, (this.id + 1) * size);
   }
   async save(data) {
-    if (data.length !== this.storage.blockSize)
-      illegalArgs(`wrong block size`);
-    this.storage.buffer.set(data, this.id * this.storage.blockSize);
+    const { storage } = this;
+    if (data.length !== storage.blockSize) illegalArgs(`wrong block size`);
+    storage.logger.debug("save block", this.id);
+    storage.buffer.set(data, this.id * storage.blockSize);
   }
   async delete() {
     const size = this.storage.blockSize;
@@ -26,7 +26,13 @@ class MemoryBlockStorage extends ABlockStorage {
   buffer;
   constructor(opts) {
     super(opts);
-    this.buffer = new Uint8Array(this.numBlocks * this.blockSize);
+    const size = this.numBlocks * this.blockSize;
+    if (opts.buffer && opts.buffer.length < size) {
+      illegalArgs(
+        `given buffer is too small, expected at least ${size} bytes`
+      );
+    }
+    this.buffer = opts.buffer ?? new Uint8Array(size);
   }
   async hasBlock(id) {
     this.ensureValidID(id);