layout-data 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## v0.3.0
+
+### Breaking changes
+
+- **`access` is gathered in a transaction.** Inside `transaction(fn)` no `access` is emitted at once: the tags read and the tags written are gathered apart, and at the end at most one `access` of kind `read` and one of kind `write` are emitted, each with its tags in layout order and without repeats. At commit they come before the `change` events and `write`; on rollback only the `read` one is emitted, as those reads did happen, and the undone writes report nothing. The exceptions of `access` listeners follow the rules of the other handlers at commit, and are dropped on rollback.
+- **`read_bit` is a reserved name.** A layout with a tag named `read_bit` no longer registers. Before 1.0 the list of reserved names may still grow; from 1.0 on new members are added only as `Symbol`-keyed members or static methods.
+
+### Features
+
+- **`read_bit(offset, mask)`** reads the bits of a byte selected by `mask` and returns `true` when any of them is set. Its `access` names only the Bools whose bit is read, as `write_bit` does for writes, instead of every tag of the byte as `read_bytes` would.
+
+### Packaging
+
+- `yaml` is no longer bundled: it is a run-time dependency, and the package ships `src` as is, with the declarations in `dist/types`.
+
+## v0.3.0 (中文)
+
+### 破坏性变更
+
+- **事务内汇总 `access`。** 在 `transaction(fn)` 内不再立即发出 `access`：被读的 tag 和被写的 tag 分别汇总，结束时最多发出一次 `read` 类和一次 `write` 类的 `access`，tag 按布局顺序且不重复。提交时它们先于 `change` 事件和 `write`；回滚时只发出 `read` 类，因为那些读确实发生了，被撤销的写不报告。`access` 监听函数的异常在提交时与其他处理器的规则相同，回滚时丢弃。
+- **`read_bit` 成为保留名。** 含名为 `read_bit` 的 tag 的布局不再能注册。1.0 之前保留名清单仍可能增加；从 1.0 起新成员只以 `Symbol` 键成员或静态方法的形式加入。
+
+### 功能
+
+- **`read_bit(offset, mask)`** 读取一个字节中由 `mask` 选中的位，任一位置位即返回 `true`。它的 `access` 只列出被读位的 Bool，与 `write_bit` 对写的处理一致，而不像 `read_bytes` 那样列出该字节的所有 tag。
+
+### 打包
+
+- 不再内置 `yaml`：它成为运行时依赖，包直接发布 `src`，类型声明在 `dist/types`。
+
 ## v0.2.0
 
 The first release.

package/README.md

@@ -22,8 +22,6 @@ Requires Node.js >= 20.11. The package is ESM only.
 pnpm add layout-data
 ```
 
-`yaml` is bundled into the library, so nothing else needs to be installed.
-
 ## Usage
 
 Describe the layout (`pump.yaml`). Entries other than `layouts` are fragments that entries can reference by name. Offsets are in bits.
@@ -114,7 +112,7 @@ The specification and design documents are in [doc/](doc/spec.md) (English, `*.m
 
 ```bash
 pnpm install
-pnpm build      # bundle to dist/ and generate dist/types
+pnpm build      # generate dist/types
 pnpm test       # build, type tests, node --test
 pnpm lint
 ```

package/dist/types/Ldata.d.ts

@@ -91,11 +91,12 @@ export class Ldata extends EventEmitter<[never]> {
      */
     get(tagname: string): Ltag | undefined;
     /**
-     * Runs fn synchronously and makes its writes one whole: no event is emitted
-     * during it; when fn returns, one detection runs and one `write` is emitted
-     * if fn wrote; when fn throws, the buffer is restored and no event is
-     * emitted (doc/spec-data-api.md §4.2). The return value of fn is not
-     * inspected: a Promise is neither awaited nor rejected.
+     * Runs fn synchronously and makes its accesses and writes one whole: no
+     * event is emitted during it; when fn returns, the gathered `access` is
+     * emitted, one detection runs and one `write` is emitted if fn wrote; when
+     * fn throws, the buffer is restored and only the gathered `access` of kind
+     * `read` is emitted (doc/spec-data-api.md §4.2). The return value of fn is
+     * not inspected: a Promise is neither awaited nor rejected.
      *
      * @template T
      * @param {() => T} fn
@@ -122,6 +123,16 @@ export class Ldata extends EventEmitter<[never]> {
      * @throws {TypeError} When source is not a Uint8Array.
      */
     write_bytes(offset: number, source: Uint8Array): void;
+    /**
+     * Reads the bits selected by mask of the byte at offset
+     * (doc/spec-data-api.md §2.5); `access` names only the Bools of those bits.
+     *
+     * @param {number} offset - Byte offset.
+     * @param {number} mask - An integer from 1 to 0xff.
+     * @returns {boolean} Whether any of the bits is set.
+     * @throws {RangeError} For an offset out of range, or a mask that is not an integer from 1 to 0xff.
+     */
+    read_bit(offset: number, mask: number): boolean;
     /**
      * Writes the bits selected by mask of the byte at offset; the other bits
      * are unchanged (doc/spec-data-api.md §2.5).

package/package.json

@@ -1,30 +1,32 @@
 {
   "name": "layout-data",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Structured, reactive, buffer-based data blocks with named, typed tags",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "default": "./dist/layout-data.js"
+      "default": "./src/index.js"
     }
   },
   "files": [
-    "dist",
+    "src",
+    "dist/types",
     "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20.11"
   },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@stylistic/eslint-plugin": "5.10.0",
     "@types/node": "^20.19.43",
     "eslint": "10.12.0",
     "globals": "17.13.0",
-    "rolldown": "^1.2.12",
-    "typescript": "^5.9.3",
-    "yaml": "^2.9.1"
+    "typescript": "^5.9.3"
   },
   "keywords": [
     "buffer",
@@ -36,11 +38,11 @@
   "author": "Goosy Jo <goosy.jo@gmail.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/goosy/data_block.git"
+    "url": "git+https://github.com/goosy/layout-data.git"
   },
   "license": "MPL-2.0",
   "scripts": {
-    "build": "rolldown -c",
+    "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit false --emitDeclarationOnly --outDir .local/types",
     "test": "pnpm build && pnpm test:types && node --test",
     "test:types": "tsc -p type_check",

package/src/Ldata.js

@@ -0,0 +1,541 @@
+import { Buffer } from "node:buffer";
+import { EventEmitter } from "node:events";
+import { Ltag } from "./Ltag.js";
+import { emit_all } from "./dispatch.js";
+import { check_endian, io_range, load_entry, store_entry } from "./endian.js";
+import { Observer } from "./observer.js";
+import { compiled_of, find_layout, get_layout } from "./registry.js";
+import { is_reserved_name } from "./reserved.js";
+
+/** @import { Class_Access_Listener, Data_Listener, Endian, Layout } from "./typedefs.js" */
+/** @import { Compiled_Layout, Layout_Entry } from "./internal_types.js" */
+
+/** The classes built so far, by layout name (doc/design.md §4). */
+const classes = new Map();
+
+/**
+ * The class-level access listeners (doc/spec-data-api.md §2.8). They are kept
+ * here and not on the data blocks, so that nothing done to a data block
+ * removes them.
+ *
+ * @type {Set<Class_Access_Listener>}
+ */
+const class_access_listeners = new Set();
+
+/** Set while an access listener runs: the accesses made meanwhile emit nothing. */
+let in_access = false;
+
+/**
+ * The registered layout an Ldata argument stands for.
+ *
+ * @param {Layout | string} layout - A layout name, or the registered layout of its name.
+ * @returns {Layout}
+ * @throws {Error} For an unknown name, or a layout that is not the registered one.
+ */
+function resolve_layout(layout) {
+	if (typeof layout === "string") return get_layout(layout);
+	if (find_layout(layout?.name) !== layout) throw new Error(`${layout?.name} is not a registered layout`);
+	return layout;
+}
+
+export class Ldata extends EventEmitter {
+	/**
+	 * @type {Buffer}
+	 * @description Internal buffer, private (doc/spec-data-api.md §2.2).
+	 * All data items, including combined words, are stored in Big-Endian format.
+	 * Device endianness is converted only at the IO boundary (the IO layer).
+	 */
+	#buffer;
+	/** @returns {number} Size of the data block in bytes. */
+	get size() {
+		return this.#buffer.length;
+	}
+
+	/** @type {string} */
+	#name;
+	/** @returns {string} The name given at creation, used in logs and error messages. */
+	get name() {
+		return this.#name;
+	}
+
+	/** @type {Layout} */
+	#layout;
+	/** @type {Compiled_Layout} */
+	#compiled;
+	/**
+	 * The compiled layout of this data block (doc/design.md §3), read-only.
+	 * The tag accessors are defined once on the prototype of the class built for the layout.
+	 *
+	 * @returns {Layout}
+	 */
+	get layout() { return this.#layout; }
+
+	/** @type {Observer} */
+	#observer;
+	/**
+	 * The open transaction, null outside one (doc/spec-data-api.md §4.2): whether
+	 * it wrote, and the tags it read and wrote, gathered for `access`.
+	 *
+	 * @type {{ written: boolean, read: Set<Ltag>, write: Set<Ltag> } | null}
+	 */
+	#transaction = null;
+	/**
+	 * @type {Map<string, Ltag>}
+	 * @description The tag handles created so far, by tag name.
+	 */
+	#handles = new Map();
+	/**
+	 * Subscribes a listener; typed for `change` and `write`, any listener for
+	 * another event name (doc/spec-data-api.md §2.7).
+	 *
+	 * @template {string | symbol} E
+	 * @param {E} event
+	 * @param {Data_Listener<E>} listener
+	 * @returns {this}
+	 */
+	on(event, listener) { return super.on(event, listener); }
+
+	/**
+	 * Subscribes a listener for one emission, typed like `on`.
+	 *
+	 * @template {string | symbol} E
+	 * @param {E} event
+	 * @param {Data_Listener<E>} listener
+	 * @returns {this}
+	 */
+	once(event, listener) { return super.once(event, listener); }
+
+	/**
+	 * Removes a listener, typed like `on`.
+	 *
+	 * @template {string | symbol} E
+	 * @param {E} event
+	 * @param {Data_Listener<E>} listener
+	 * @returns {this}
+	 */
+	off(event, listener) { return super.off(event, listener); }
+
+	/**
+	 * Retrieves the handle of a tag, creating it on first use.
+	 * @param {string} tagname - The name of the tag to retrieve.
+	 * @returns {Ltag|undefined} The Ltag handle, undefined for an unknown name.
+	 */
+	get(tagname) {
+		let tag = this.#handles.get(tagname);
+		if (tag) return tag;
+		const entry = this.#compiled.entries.get(tagname);
+		if (!entry) return undefined;
+		tag = new Ltag(this, entry);
+		this.#handles.set(tagname, tag);
+		return tag;
+	}
+
+	/**
+	 * Runs fn synchronously and makes its accesses and writes one whole: no
+	 * event is emitted during it; when fn returns, the gathered `access` is
+	 * emitted, one detection runs and one `write` is emitted if fn wrote; when
+	 * fn throws, the buffer is restored and only the gathered `access` of kind
+	 * `read` is emitted (doc/spec-data-api.md §4.2). The return value of fn is
+	 * not inspected: a Promise is neither awaited nor rejected.
+	 *
+	 * @template T
+	 * @param {() => T} fn
+	 * @returns {T} The return value of fn.
+	 * @throws {Error} Inside a transaction; or whatever fn throws, after the rollback.
+	 */
+	transaction(fn) {
+		if (this.#transaction) throw new Error(`${this.name}: a transaction is already open`);
+		const saved = Buffer.from(this.#buffer);
+		const state = { written: false, read: new Set(), write: new Set() };
+		this.#transaction = state;
+		let result;
+		try {
+			result = fn();
+		} catch (error) {
+			this.#transaction = null;
+			saved.copy(this.#buffer);
+			this.#observer.discard();
+			this.#emit_access("read", this.#in_layout_order(state.read), []); // the writes were undone, the reads were not
+			throw error;
+		}
+		this.#transaction = null;
+		const errors = [];
+		this.#emit_access("read", this.#in_layout_order(state.read), errors);
+		this.#emit_access("write", this.#in_layout_order(state.write), errors);
+		this.#observer.diff(errors);
+		if (state.written) emit_all(this, "write", [this], errors);
+		if (errors.length > 0) throw errors[0];
+		return result;
+	}
+
+	/**
+	 * Reads a range of bytes (doc/spec-data-api.md §2.5).
+	 *
+	 * @param {number} [offset=0] - Byte offset.
+	 * @param {number} [length] - Number of bytes, up to the end of the data block by default.
+	 * @returns {Buffer} A copy: changing it does not affect the data block.
+	 * @throws {RangeError} For an offset or length out of range.
+	 */
+	read_bytes(offset = 0, length = this.#buffer.length - offset) {
+		this.#check_range(offset, length);
+		const bytes = Buffer.from(this.#buffer.subarray(offset, offset + length));
+		if (length > 0 && this.#has_access_listeners()) this.#accessed("read", this.#tags_in(offset, offset + length));
+		return bytes;
+	}
+
+	/**
+	 * Writes all the bytes of source from a byte offset (doc/spec-data-api.md §2.5).
+	 * An empty source writes nothing and emits no `write`.
+	 *
+	 * @param {number} offset - Byte offset.
+	 * @param {Uint8Array} source
+	 * @throws {RangeError} For an offset out of range, or a run past the end of the data block.
+	 * @throws {TypeError} When source is not a Uint8Array.
+	 */
+	write_bytes(offset, source) {
+		if (!(source instanceof Uint8Array)) throw new TypeError(`${this.name}: source must be a Uint8Array`);
+		this.#check_range(offset, source.length);
+		if (source.length === 0) return; // nothing written: not a write
+		this.#buffer.set(source, offset);
+		this.#written(offset, offset + source.length);
+	}
+
+	/**
+	 * Reads the bits selected by mask of the byte at offset
+	 * (doc/spec-data-api.md §2.5); `access` names only the Bools of those bits.
+	 *
+	 * @param {number} offset - Byte offset.
+	 * @param {number} mask - An integer from 1 to 0xff.
+	 * @returns {boolean} Whether any of the bits is set.
+	 * @throws {RangeError} For an offset out of range, or a mask that is not an integer from 1 to 0xff.
+	 */
+	read_bit(offset, mask) {
+		this.#check_bit(offset, mask);
+		const value = (this.#buffer[offset] & mask) !== 0;
+		if (this.#has_access_listeners()) this.#accessed("read", this.#tags_in(offset, offset + 1, mask));
+		return value;
+	}
+
+	/**
+	 * Writes the bits selected by mask of the byte at offset; the other bits
+	 * are unchanged (doc/spec-data-api.md §2.5).
+	 *
+	 * @param {number} offset - Byte offset.
+	 * @param {number} mask - An integer from 1 to 0xff.
+	 * @param {boolean} value - Taken by truthiness.
+	 * @throws {RangeError} For an offset out of range, or a mask that is not an integer from 1 to 0xff.
+	 */
+	write_bit(offset, mask, value) {
+		this.#check_bit(offset, mask);
+		const buffer = this.#buffer;
+		buffer[offset] = value ? buffer[offset] | mask : buffer[offset] & ~mask;
+		this.#written(offset, offset + 1, null, mask);
+	}
+
+	/**
+	 * Converts the bytes of a tag from a device-ordered IO buffer and writes
+	 * them into the data block; a write like any other
+	 * (doc/spec-data-api.md §2.9).
+	 *
+	 * @param {string} name - The tag name.
+	 * @param {Uint8Array} io_buffer - Indexed like the byte offsets of the data block.
+	 * @param {Endian} endian - Device byte order.
+	 * @throws {Error} For an unknown tag name.
+	 * @throws {RangeError} For another byte order, or a tag out of the IO buffer.
+	 * @throws {TypeError} When io_buffer is not a Uint8Array.
+	 */
+	load_tag(name, io_buffer, endian) {
+		const entry = this.#entry_for_io(name, io_buffer, endian);
+		load_entry(entry, io_buffer, this.#buffer, endian);
+		this.#written(entry.byte, entry.byte + entry.size, entry);
+	}
+
+	/**
+	 * Converts the bytes of a tag and writes them into a device-ordered IO
+	 * buffer; the data block is unchanged and no event is emitted
+	 * (doc/spec-data-api.md §2.9).
+	 *
+	 * @param {string} name - The tag name.
+	 * @param {Uint8Array} io_buffer - Indexed like the byte offsets of the data block.
+	 * @param {Endian} endian - Device byte order.
+	 * @throws {Error} For an unknown tag name.
+	 * @throws {RangeError} For another byte order, or a tag out of the IO buffer.
+	 * @throws {TypeError} When io_buffer is not a Uint8Array.
+	 */
+	store_tag(name, io_buffer, endian) {
+		const entry = this.#entry_for_io(name, io_buffer, endian);
+		store_entry(entry, this.#buffer, io_buffer, endian);
+		if (this.#has_access_listeners()) this.#accessed("read", [this.get(name)]);
+	}
+
+	/**
+	 * The compiled entry of a tag, after checking the arguments of load_tag
+	 * and store_tag before anything is changed.
+	 *
+	 * @param {string} name
+	 * @param {Uint8Array} io_buffer
+	 * @param {Endian} endian
+	 * @returns {import("./internal_types.js").Layout_Entry}
+	 */
+	#entry_for_io(name, io_buffer, endian) {
+		if (!(io_buffer instanceof Uint8Array)) throw new TypeError(`${this.name}: io_buffer must be a Uint8Array`);
+		check_endian(endian);
+		const entry = this.#compiled.entries.get(name);
+		if (!entry) throw new Error(`${this.name}: unknown tag ${name}`);
+		if (io_range(entry, endian).end > io_buffer.length) {
+			throw new RangeError(`${this.name}.${name}: out of the io_buffer of ${io_buffer.length} bytes`);
+		}
+		return entry;
+	}
+
+	/**
+	 * Checks a byte range before anything is read or written.
+	 *
+	 * @param {number} offset
+	 * @param {number} length
+	 * @throws {RangeError}
+	 */
+	#check_range(offset, length) {
+		if (!Number.isInteger(offset) || offset < 0) {
+			throw new RangeError(`${this.name}: offset ${offset} must be a non-negative integer`);
+		}
+		if (!Number.isInteger(length) || length < 0 || offset + length > this.#buffer.length) {
+			throw new RangeError(`${this.name}: length ${length} at offset ${offset} exceeds the data block`);
+		}
+	}
+
+	/**
+	 * Checks the arguments of read_bit and write_bit.
+	 *
+	 * @param {number} offset
+	 * @param {number} mask
+	 * @throws {RangeError}
+	 */
+	#check_bit(offset, mask) {
+		this.#check_range(offset, 1);
+		if (!Number.isInteger(mask) || mask < 1 || mask > 0xff) {
+			throw new RangeError(`${this.name}: mask ${mask} must be an integer from 1 to 0xff`);
+		}
+	}
+
+	/**
+	 * After a write of the byte range [start, end): registers the range, then
+	 * detects the change at once and emits `write`; inside a transaction only
+	 * remembers the write (doc/spec-data-api.md §4.2).
+	 *
+	 * @param {number} start
+	 * @param {number} end - Exclusive.
+	 * @param {Layout_Entry | null} [entry] - The tag written by name, null for a raw write.
+	 * @param {number} [mask] - The bits written by write_bit.
+	 */
+	#written(start, end, entry = null, mask = 0xff) {
+		this.#observer.touch(start, end);
+		const errors = [];
+		if (this.#has_access_listeners()) {
+			const tags = entry ? [this.get(entry.name)] : this.#tags_in(start, end, mask);
+			this.#emit_access("write", tags, errors);
+		}
+		if (this.#transaction) {
+			this.#transaction.written = true;
+			return;
+		}
+		this.#observer.diff(errors);
+		emit_all(this, "write", [this], errors);
+		if (errors.length > 0) throw errors[0];
+	}
+
+	/** Whether an access would reach a listener of the instance or of the class. */
+	#has_access_listeners() {
+		return class_access_listeners.size > 0 || this.listenerCount("access") > 0;
+	}
+
+	/**
+	 * Emits `access` (doc/spec-data-api.md §2.8) and throws the first
+	 * exception of the listeners, for a read.
+	 *
+	 * @param {"read" | "write"} kind
+	 * @param {Ltag[]} tags
+	 */
+	#accessed(kind, tags) {
+		const errors = [];
+		this.#emit_access(kind, tags, errors);
+		if (errors.length > 0) throw errors[0];
+	}
+
+	/**
+	 * Calls the `access` listeners, pushing what they throw to `errors`; inside
+	 * a transaction only gathers the tags (doc/spec-data-api.md §4.2).
+	 *
+	 * @param {"read" | "write"} kind
+	 * @param {Ltag[]} tags
+	 * @param {unknown[]} errors
+	 */
+	#emit_access(kind, tags, errors) {
+		if (in_access || tags.length === 0) return;
+		if (this.#transaction) {
+			const gathered = this.#transaction[kind];
+			for (const tag of tags) gathered.add(tag);
+			return;
+		}
+		in_access = true;
+		try {
+			emit_all(this, "access", [kind, tags], errors);
+			for (const listener of [...class_access_listeners]) {
+				try {
+					listener(this, kind, tags);
+				} catch (error) {
+					errors.push(error);
+				}
+			}
+		} finally {
+			in_access = false;
+		}
+	}
+
+	/**
+	 * The tags that have a byte in the range [start, end), in layout order and
+	 * without repeats; the Bools whose bit is not in `mask` are left out.
+	 *
+	 * @param {number} start
+	 * @param {number} end - Exclusive.
+	 * @param {number} [mask] - The bits of the bytes that are accessed.
+	 * @returns {Ltag[]}
+	 */
+	#tags_in(start, end, mask = 0xff) {
+		const entries = new Set();
+		const tags_at_byte = this.#compiled.tags_at_byte;
+		for (let i = start; i < end; i++) {
+			for (const entry of tags_at_byte[i]) {
+				if (entry.type === "bool" && (entry.mask & mask) === 0) continue;
+				entries.add(entry);
+			}
+		}
+		return [...entries].sort((a, b) => a.index - b.index).map((entry) => this.get(entry.name));
+	}
+
+	/**
+	 * The gathered tags of a transaction, in layout order.
+	 *
+	 * @param {Set<Ltag>} tags
+	 * @returns {Ltag[]}
+	 */
+	#in_layout_order(tags) {
+		const entries = this.#compiled.entries;
+		return [...tags].sort((a, b) => entries.get(a.name).index - entries.get(b.name).index);
+	}
+
+	/**
+	 * The class of a layout, built on the first use of its name: the name tells
+	 * the layouts apart, as the registry holds one layout per name.
+	 *
+	 * @param {Layout} layout - A registered layout.
+	 * @returns {typeof Ldata}
+	 */
+	static #class_of(layout) {
+		let Layout_Data = classes.get(layout.name);
+		if (!Layout_Data) {
+			Layout_Data = Ldata.#build_class(layout);
+			classes.set(layout.name, Layout_Data);
+		}
+		return Layout_Data;
+	}
+
+	/**
+	 * Builds the class of a layout: a subclass of Ldata whose prototype holds
+	 * the accessor of every tag, shared by all instances of the layout. The
+	 * accessors are defined here so that they reach the private buffer.
+	 *
+	 * @param {Layout} layout
+	 * @returns {typeof Ldata}
+	 */
+	static #build_class(layout) {
+		const Layout_Data = class extends Ldata { };
+		Object.defineProperty(Layout_Data, "name", { value: `Ldata_${layout.name}` });
+		const compiled = compiled_of(layout);
+		for (const entry of compiled.entries.values()) {
+			const { name, codec, byte, mask, size } = entry;
+			if (is_reserved_name(name)) {
+				throw new Error(`${layout.name}.${name}: reserved tag name`);
+			}
+			Object.defineProperty(Layout_Data.prototype, name, {
+				get() {
+					const value = codec.get(this.#buffer, byte, mask);
+					if (this.#has_access_listeners()) this.#accessed("read", [this.get(name)]);
+					return value;
+				},
+				set(value) {
+					const reason = codec.check(value);
+					if (reason !== null) {
+						const Refused_Error = typeof value === "number" ? RangeError : TypeError;
+						throw new Refused_Error(`${this.name}.${name}: ${reason}`);
+					}
+					codec.set(this.#buffer, byte, mask, value);
+					this.#written(byte, byte + size, entry);
+				},
+				enumerable: true,
+				configurable: false,
+			});
+		}
+		Layout_Data.layout = layout;
+		Layout_Data.compiled = compiled;
+		return Layout_Data;
+	}
+
+	/**
+	 * Subscribes a function called for the accesses to every data block, with
+	 * (data, kind, tags); the same function twice is one subscription
+	 * (doc/spec-data-api.md §2.8).
+	 *
+	 * @param {Class_Access_Listener} listener
+	 * @throws {TypeError} When listener is not a function.
+	 */
+	static on_access(listener) {
+		if (typeof listener !== "function") throw new TypeError("an access listener must be a function");
+		class_access_listeners.add(listener);
+	}
+
+	/**
+	 * Cancels a subscription of on_access; nothing happens for a function that
+	 * is not subscribed.
+	 *
+	 * @param {Class_Access_Listener} listener
+	 */
+	static off_access(listener) {
+		class_access_listeners.delete(listener);
+	}
+
+	/**
+	 * Creates a data block of a layout (doc/spec-data-api.md §2.1).
+	 *
+	 * `new Ldata(layout, name)` returns an instance of the class built for the
+	 * layout name (a subclass of Ldata whose prototype holds the tag
+	 * accessors), building the class on the first use of the name.
+	 *
+	 * @param {Layout | string} layout - A registered layout, or its name (get_layout).
+	 * @param {string} name - The name of the Ldata instance, a string that cannot be changed afterwards.
+	 * @throws {TypeError} When name is not a string.
+	 * @throws {Error} For an unknown layout name, or a layout that is not the registered one.
+	 */
+	constructor(layout, name) {
+		super();
+		if (typeof name !== "string") throw new TypeError("the name of an ldata must be a string");
+		if (new.target === Ldata) {
+			const registered = resolve_layout(layout);
+			return new (Ldata.#class_of(registered))(registered, name);
+		}
+		this.#name = name;
+		this.#layout = new.target.layout;
+		this.#compiled = new.target.compiled;
+		this.setMaxListeners(100);
+		this.#buffer = Buffer.alloc(this.#layout.size, 0);
+		// init values in layout order: the bits of a combined word after the word
+		for (const { codec, byte, mask, init_value } of this.#compiled.entries.values()) {
+			codec.set(this.#buffer, byte, mask, init_value);
+		}
+		this.#observer = new Observer(this.#buffer, this.#layout.name, this.#compiled, (entry, old_value, new_value, errors) => {
+			// the data block event first, as when it relayed the tag events
+			emit_all(this, "change", [entry.name, old_value, new_value], errors);
+			emit_all(this.#handles.get(entry.name), "change", [old_value, new_value], errors);
+		});
+	}
+}