@thi.ng/block-fs 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-06T13:54:45Z
+- **Last updated**: 2025-04-16T11:11:14Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,13 @@ 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.4.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/block-fs@0.4.1) (2025-04-16)
+
+#### ♻️ Refactoring
+
+- update Entry memory layout ([b5416bd](https://github.com/thi-ng/umbrella/commit/b5416bd))
+  - move block start & end ID locations
+
 ## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/block-fs@0.4.0) (2025-04-06)
 
 #### 🚀 Features

package/README.md

@@ -96,16 +96,33 @@ entries/sizes. The default [`Entry`
 implementation](https://docs.thi.ng/umbrella/block-fs/classes/Entry.html)
 requires 64 bytes.
 
-TODO diagram
+![Memory layout diagram for a single directory entry](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/block-fs/direntry-01.png)
 
 #### File blocks
 
 Files are stored as linked lists of blocks, with the first few bytes of each
-block reserved for linkage and number of data bytes in the block. The number of
-bytes effectively available for data depends on the configured block size and
-the max. number of blocks in the storage backend.
+block reserved for linkage and number of data bytes in the block.
 
-TODO diagram
+![Memory layout diagram for a single file block](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/block-fs/block-layout-01.png)
+
+The number of bytes effectively available for data depends on the configured
+block size and the max. number of blocks in the storage backend. For example, a
+max. block count of 65536 and a block size of 256 bytes only requires a two
+bytes for linkage and a third byte for storing the number of data bytes used in
+the block. Hence, in this configuration 253 bytes per block are available for
+data.
+
+The following diagram shows a block which links to block ID 0x1234 and uses the
+full 253 (0xfd in hex) bytes of data available:
+
+![Memory layout diagram for a single file block](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/block-fs/block-layout-02.png)
+
+The last block of a file uses a special sentinel marker to indicate that no
+other blocks follow. This sentinel value again depends on the configured max.
+block count, and in this example is 0xffff. This example block only stores 64
+(0x40 in hex) bytes of data, with the remainder zeroed out.
+
+![Memory layout diagram for a sentinel file block](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/block-fs/block-layout-03.png)
 
 ### Command line app
 

package/entry.d.ts

@@ -20,16 +20,16 @@ export declare class Entry implements IEntry {
     set owner(owner: number);
     get name(): string;
     set name(name: string);
+    get start(): number;
+    set start(block: number);
+    get end(): number;
+    set end(block: number);
     get size(): bigint;
     set size(size: bigint);
     get ctime(): number;
     set ctime(epoch: number);
     get mtime(): number;
     set mtime(epoch: number);
-    get start(): number;
-    set start(block: number);
-    get end(): number;
-    set end(block: number);
     set(spec: EntrySpec): void;
     release(): void;
     save(): Promise<void>;

package/entry.js

@@ -66,35 +66,35 @@ class Entry {
       this.data.subarray(offset, offset + Entry.NAME_MAX_LENGTH)
     );
   }
+  get start() {
+    return this.view.getUint32(32, true);
+  }
+  set start(block) {
+    this.view.setUint32(32, block, true);
+  }
+  get end() {
+    return this.view.getUint32(36, true);
+  }
+  set end(block) {
+    this.view.setUint32(36, block, true);
+  }
   get size() {
-    return this.view.getBigUint64(32, true);
+    return this.view.getBigUint64(40, true);
   }
   set size(size) {
-    this.view.setBigUint64(32, size, true);
+    this.view.setBigUint64(40, size, true);
   }
   get ctime() {
-    return Number(this.view.getBigUint64(40, true));
+    return Number(this.view.getBigUint64(48, true));
   }
   set ctime(epoch) {
-    this.view.setBigUint64(40, BigInt(epoch), true);
+    this.view.setBigUint64(48, BigInt(epoch), true);
   }
   get mtime() {
-    return Number(this.view.getBigUint64(48, true));
+    return Number(this.view.getBigUint64(56, true));
   }
   set mtime(epoch) {
-    this.view.setBigUint64(48, BigInt(epoch), true);
-  }
-  get start() {
-    return this.view.getUint32(56, true);
-  }
-  set start(block) {
-    this.view.setUint32(56, block, true);
-  }
-  get end() {
-    return this.view.getUint32(60, true);
-  }
-  set end(block) {
-    this.view.setUint32(60, block, true);
+    this.view.setBigUint64(56, BigInt(epoch), true);
   }
   set(spec) {
     this.type = spec.type;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/block-fs",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Customizable block-based storage, adapters & file system layer",
   "type": "module",
   "module": "./index.js",
@@ -42,23 +42,23 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "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",
-    "@thi.ng/errors": "^2.5.31",
-    "@thi.ng/file-io": "^2.1.34",
-    "@thi.ng/logger": "^3.1.6",
-    "@thi.ng/mime": "^2.7.7",
-    "@thi.ng/random": "^4.1.16",
-    "@thi.ng/strings": "^3.9.10"
+    "@thi.ng/api": "^8.11.26",
+    "@thi.ng/args": "^2.3.67",
+    "@thi.ng/binary": "^3.4.49",
+    "@thi.ng/bitfield": "^2.4.1",
+    "@thi.ng/checks": "^3.7.6",
+    "@thi.ng/errors": "^2.5.32",
+    "@thi.ng/file-io": "^2.1.35",
+    "@thi.ng/logger": "^3.1.7",
+    "@thi.ng/mime": "^2.7.8",
+    "@thi.ng/random": "^4.1.17",
+    "@thi.ng/strings": "^3.9.11"
   },
   "devDependencies": {
-    "@types/node": "^22.13.14",
+    "@types/node": "^22.14.1",
     "esbuild": "^0.25.2",
-    "typedoc": "^0.28.1",
-    "typescript": "^5.8.2"
+    "typedoc": "^0.28.2",
+    "typescript": "^5.8.3"
   },
   "keywords": [
     "async",
@@ -132,5 +132,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "c88a589f33207b02a43172313b38ea09571265f1\n"
+  "gitHead": "c464b6948f92cba90c2ea75b59203dad894fb450\n"
 }