layout-data 0.0.0-stage → 0.3.0

package/src/observer.js

@@ -0,0 +1,147 @@
+import { Buffer } from "node:buffer";
+
+/** @import { Compiled_Layout, Layout_Entry } from "./internal_types.js" */
+
+// a change made by a change handler is detected in a further round
+const MAX_DIFF_ROUNDS = 16;
+
+const same_value = (a, b) => a === b || (Number.isNaN(a) && Number.isNaN(b));
+
+/**
+ * Detects the changes of an Ldata buffer by comparing it with a snapshot
+ * (doc/design.md §5.1) and reports each changed tag once.
+ *
+ * Every write path of the Ldata registers the byte range it wrote with
+ * touch(), then calls diff() (in a transaction: at its commit). Only the
+ * registered range is compared, the other bytes equal the snapshot by
+ * construction. A diff() called while the changes are being reported, by a
+ * handler writing a tag, is only recorded; the outer diff() runs another
+ * round once the current changes are reported.
+ */
+export class Observer {
+	/** @type {Buffer} */
+	#buffer;
+	/** @type {string} */
+	#name;
+	/** @type {Compiled_Layout} */
+	#compiled;
+	/** @type {Buffer} */
+	#snapshot;
+	/** @type {(entry: Layout_Entry, old_value: any, new_value: any, errors: unknown[]) => void} */
+	#report;
+	#diffing = false;
+	#pending = false;
+	/** The byte range [#start, #end) written since the last collection. */
+	#start = Number.POSITIVE_INFINITY;
+	#end = 0;
+	/** @type {Uint32Array} */
+	#seen;
+	#mark = 0;
+
+	/**
+	 * @param {Buffer} buffer - The buffer of the Ldata.
+	 * @param {string} name - The layout name, for errors.
+	 * @param {Compiled_Layout} compiled - The compiled data of the layout of the Ldata.
+	 * @param {(entry: Layout_Entry, old_value: any, new_value: any, errors: unknown[]) => void} report - Called for each change; what a handler throws goes to `errors`.
+	 */
+	constructor(buffer, name, compiled, report) {
+		this.#buffer = buffer;
+		this.#name = name;
+		this.#compiled = compiled;
+		this.#report = report;
+		this.#snapshot = Buffer.from(buffer);
+		this.#seen = new Uint32Array(compiled.entries.size);
+	}
+
+	/**
+	 * Registers the byte range [start, end) as written.
+	 *
+	 * @param {number} start
+	 * @param {number} end - Exclusive.
+	 */
+	touch(start, end) {
+		if (start >= end) return;
+		if (start < this.#start) this.#start = start;
+		if (end > this.#end) this.#end = end;
+	}
+
+	/**
+	 * Forgets the registered range: the buffer was restored to the snapshot.
+	 */
+	discard() {
+		this.#start = Number.POSITIVE_INFINITY;
+		this.#end = 0;
+	}
+
+	/**
+	 * Reports every tag changed since the last diff. Nothing is thrown: what
+	 * the handlers throw, and the exception of changes that do not settle, are
+	 * pushed to `errors` after every change has been reported (doc/spec-data-api.md §4.4).
+	 *
+	 * @param {unknown[]} errors
+	 */
+	diff(errors) {
+		if (this.#diffing) {
+			this.#pending = true;
+			return;
+		}
+		this.#diffing = true;
+		try {
+			let rounds = 0;
+			do {
+				this.#pending = false;
+				if (++rounds > MAX_DIFF_ROUNDS) {
+					errors.push(new Error(`${this.#name}: changes do not settle after ${MAX_DIFF_ROUNDS} rounds`));
+					break;
+				}
+				for (const [entry, old_value, new_value] of this.#collect()) {
+					this.#report(entry, old_value, new_value, errors);
+				}
+			} while (this.#pending);
+		} finally {
+			this.#diffing = false;
+		}
+	}
+
+	/**
+	 * Collects the changed tags, in layout order, and updates the snapshot.
+	 * Old values are decoded from the snapshot, so no value is cached.
+	 */
+	#collect() {
+		const buffer = this.#buffer;
+		const snapshot = this.#snapshot;
+		const tags_at_byte = this.#compiled.tags_at_byte;
+		// entries already checked in this collection, by entry index
+		const seen = this.#seen;
+		if (this.#mark === 0xffffffff) {
+			// the marks wrap around: clear them
+			seen.fill(0);
+			this.#mark = 0;
+		}
+		const mark = ++this.#mark;
+		const changes = [];
+		let in_order = true;
+		let last_index = -1;
+		// a write during the reporting registers its range for the next round
+		const start = this.#start;
+		const end = Math.min(this.#end, buffer.length);
+		this.discard();
+		for (let i = start; i < end; i++) {
+			if (buffer[i] === snapshot[i]) continue;
+			for (const entry of tags_at_byte[i]) {
+				if (seen[entry.index] === mark) continue;
+				seen[entry.index] = mark;
+				const { codec, byte, mask } = entry;
+				const old_value = codec.get(snapshot, byte, mask);
+				const new_value = codec.get(buffer, byte, mask);
+				if (same_value(old_value, new_value)) continue;
+				changes.push([entry, old_value, new_value]);
+				if (entry.index < last_index) in_order = false;
+				last_index = entry.index;
+			}
+		}
+		if (start < end) buffer.copy(snapshot, start, start, end);
+		if (!in_order) changes.sort((a, b) => a[0].index - b[0].index);
+		return changes;
+	}
+}

package/src/registry.js

@@ -0,0 +1,83 @@
+// The registry of the compiled layouts, by layout name (doc/design.md §3).
+// A name identifies one layout: it is the only source of the layouts an Ldata
+// is created from. Written by register_structure (layout.js), read by Ldata.
+
+/** @import { Layout } from "./typedefs.js" */
+/** @import { Compiled_Layout } from "./internal_types.js" */
+
+/**
+ * @typedef {object} Registered
+ * @property {string} key - The canonical text of the structure, to tell the same layout from another one.
+ * @property {Layout} layout
+ */
+
+/** @type {Map<string, Registered>} */
+const registered = new Map();
+
+/**
+ * The compiled data of the layouts (doc/design.md §3), kept here so that the
+ * public Layout holds none of it.
+ *
+ * @type {WeakMap<Layout, Compiled_Layout>}
+ */
+const compiled = new WeakMap();
+
+/**
+ * @param {Layout} layout
+ * @param {Compiled_Layout} data
+ */
+export function set_compiled(layout, data) {
+	compiled.set(layout, data);
+}
+
+/**
+ * The compiled data of a layout made by this package.
+ *
+ * @param {Layout} layout
+ * @returns {Compiled_Layout}
+ * @throws {Error} For an object that is not a compiled layout.
+ */
+export function compiled_of(layout) {
+	const data = compiled.get(layout);
+	if (!data) throw new Error(`${layout?.name} is not a registered layout`);
+	return data;
+}
+
+/**
+ * @param {string} name
+ * @returns {Registered | undefined}
+ */
+export function registered_of(name) {
+	return registered.get(name);
+}
+
+/**
+ * @param {string} name
+ * @param {Registered} entry
+ */
+export function register(name, entry) {
+	registered.set(name, entry);
+}
+
+/**
+ * The registered layout of a name, undefined when there is none.
+ *
+ * @param {string} name
+ * @returns {Layout | undefined}
+ */
+export function find_layout(name) {
+	return registered.get(name)?.layout;
+}
+
+/**
+ * The registered layout of a name (doc/spec-data-api.md §6.5).
+ *
+ * @param {string} name
+ * @returns {Layout}
+ * @throws {Error} When no layout of that name is registered.
+ */
+export function get_layout(name) {
+	const layout = find_layout(name);
+	if (!layout) throw new Error(`unknown layout ${name}`);
+	return layout;
+}

package/src/reserved.js

@@ -0,0 +1,35 @@
+// The reserved names (doc/spec-data-api.md §2.10, doc/design.md §4). Internal:
+// index.js does not export this file.
+
+/**
+ * Names a tag must not have: the members of Ldata, the method and field names
+ * of EventEmitter in Node.js 20.11 and the names of Object.prototype. A static
+ * list, so that it does not depend on the Node.js version that runs the program.
+ */
+const RESERVED_NAMES = new Set([
+	// members of Ldata
+	"name", "layout", "size", "get", "transaction",
+	"read_bytes", "write_bytes", "read_bit", "write_bit", "load_tag", "store_tag",
+	// EventEmitter
+	"addListener", "emit", "eventNames", "getMaxListeners", "listenerCount", "listeners",
+	"off", "on", "once", "prependListener", "prependOnceListener", "rawListeners",
+	"removeAllListeners", "removeListener", "setMaxListeners",
+	"_events", "_eventsCount", "_maxListeners",
+	// Object
+	"constructor", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable",
+	"toLocaleString", "toString", "valueOf", "__proto__",
+	"__defineGetter__", "__defineSetter__", "__lookupGetter__", "__lookupSetter__",
+]);
+
+/** Event names of the library; a user does not emit them or use them for its own events. */
+export const RESERVED_EVENTS = Object.freeze(["change", "write", "access", "read"]);
+
+/**
+ * Whether a tag name would shadow a member of a data block.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function is_reserved_name(name) {
+	return RESERVED_NAMES.has(name);
+}

package/src/structure.js

@@ -0,0 +1,238 @@
+// Expansion and validation of data block structures (doc/spec.md §3,
+// doc/design.md §3.1). Part of the data layer.
+import { FLOAT32_MAX } from "./codecs.js";
+import { is_reserved_name } from "./reserved.js";
+
+/** @import { Layout_Item } from "./typedefs.js" */
+/** @import { Data_Struct } from "./internal_types.js" */
+
+function add_item(data_struct, item, base_offset, name_prefix) {
+	const items = data_struct.items;
+	// every entry that is not a pure inclusion is a tag, whatever its name: duplicated
+	// and invalid names are kept and reported by validate_structure
+	if (item.includes === undefined || item.name !== undefined) items.push(item);
+	if (name_prefix && typeof item.name === "string") item.name = name_prefix + item.name;
+
+	item.offset = item.offset + base_offset;
+	const length = item.offset + item.length;
+	if (data_struct.length < length) data_struct.length = length;
+
+	const includes = item.includes;
+	if (includes && Array.isArray(includes)) {
+		for (const _item of includes) {
+			add_item(data_struct, { ..._item }, item.offset, item.name_prefix);
+		}
+		// The "includes" and "coupling" attributes can only be chosen one at a time.
+		return;
+	}
+
+	const coupling = [];
+	const _coupling = item.coupling;
+	if (_coupling && Array.isArray(_coupling)) {
+		for (const _cp of _coupling) {
+			const cp = { ..._cp };
+			add_item(data_struct, cp, item.offset, item.name_prefix);
+			cp.coupling ??= [];
+			cp.coupling.push(item.name);
+			coupling.push(cp);
+		}
+		share_init_value(item, coupling);
+	}
+	item.coupling = coupling.map((item) => item.name);
+}
+
+// Items whose init_value is given both on the word and on some of its bits,
+// with the names of those bits; reported by validate_structure.
+const init_conflicts = new WeakMap();
+
+/**
+ * Only one side of a combined word gives the init values (doc/spec.md §3):
+ * either the word, whose bits then take theirs from it, or the bits, from
+ * which the word is composed (a bit without init_value is false).
+ */
+function share_init_value(word, bits) {
+	const given = bits.filter((bit) => bit.init_value !== undefined);
+	if (word.init_value !== undefined && given.length > 0) {
+		// keep the given values (the bits are written after the word) and
+		// report the conflict; the other bits still take theirs from the word
+		init_conflicts.set(word, given.map((bit) => bit.name));
+	}
+	const size = word.length >> 3;
+	// big-endian word: byte k of the word holds bits (size - 1 - k) * 8 ..
+	// a bit outside the word has no value in it (reported by validate_structure)
+	const bit_value = (bit) => {
+		const relative = bit.offset - word.offset;
+		if (!(relative >= 0 && relative < word.length)) return 0;
+		return 2 ** ((size - 1 - (relative >> 3)) * 8 + relative % 8);
+	};
+	if (word.init_value === undefined) {
+		word.init_value = 0;
+		for (const bit of bits) {
+			bit.init_value ??= false;
+			if (bit.init_value === true) word.init_value += bit_value(bit);
+		}
+		return;
+	}
+	if (typeof word.init_value !== "number") return;
+	for (const bit of bits) {
+		if (bit.init_value !== undefined) continue;
+		const value = bit_value(bit);
+		bit.init_value = value > 0 && Math.floor(word.init_value / value) % 2 === 1;
+	}
+}
+
+/**
+ * Expands a list of items (resolving `includes` and `coupling`, making offsets
+ * absolute) into the given structure. Internal. It changes the items it is given.
+ *
+ * @param {{name: string}} data_struct - The structure to fill in; only the name is given.
+ * @param {Layout_Item[]} items
+ * @returns {Data_Struct} The same object, now complete.
+ */
+export function build_structure(data_struct, items) {
+	data_struct.length = 0;
+	data_struct.items = [];
+	if (!items) return data_struct;
+	for (const item of items) {
+		add_item(data_struct, item, 0);
+	}
+	return data_struct;
+}
+
+/**
+ * Bit length of each tag type (lower case names).
+ *
+ * @type {Record<string, number>}
+ */
+export const TYPE_BITS = {
+	bool: 1,
+	byte: 8, sint: 8, usint: 8,
+	int: 16, uint: 16, word: 16,
+	dint: 32, udint: 32, dword: 32, real: 32,
+};
+
+/**
+ * A tag name: letters, digits and `_`, not starting with a digit, an
+ * identifier in every language (doc/spec-data-api.md §6.2).
+ */
+const TAG_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// value range of each integer type
+const INTEGER_RANGES = {
+	byte: [0, 0xff], usint: [0, 0xff], sint: [-0x80, 0x7f],
+	int: [-0x8000, 0x7fff], uint: [0, 0xffff], word: [0, 0xffff],
+	dint: [-0x80000000, 0x7fffffff], udint: [0, 0xffffffff], dword: [0, 0xffffffff],
+};
+
+function check_init_value(item, type) {
+	const value = item.init_value;
+	if (type === "bool") return typeof value === "boolean";
+	if (typeof value !== "number") return false;
+	if (type === "real") return Number.isFinite(value) && Math.abs(value) <= FLOAT32_MAX;
+	const [min, max] = INTEGER_RANGES[type];
+	return Number.isInteger(value) && value >= min && value <= max;
+}
+
+/**
+ * Validates a structure built by build_structure against the layout rules
+ * (doc/spec.md §3, doc/design.md §3.1). Internal.
+ *
+ * @param {Data_Struct} data_struct
+ * @returns {string[]} descriptions of all violations, empty when the layout is valid
+ */
+export function validate_structure(data_struct) {
+	const errors = [];
+	const struct_name = data_struct.name;
+	const report = (item, message) => errors.push(`${struct_name}.${item.name}: ${message}`);
+	const items = data_struct.items;
+
+	// names
+	const by_name = new Map();
+	for (const item of items) {
+		if (by_name.has(item.name)) report(item, "duplicated name");
+		else by_name.set(item.name, item);
+		if (typeof item.name !== "string" || !TAG_NAME.test(item.name)) {
+			report(item, "name is not an identifier (letters, digits and \"_\", not starting with a digit)");
+		} else if (is_reserved_name(item.name)) {
+			report(item, "name is a reserved name");
+		}
+	}
+
+	// type, length, alignment and init_value
+	const valid_items = [];
+	for (const item of items) {
+		const type = item.type?.toLowerCase();
+		if (!(type in TYPE_BITS)) {
+			report(item, `unknown type ${item.type}`);
+			continue;
+		}
+		if (item.length !== TYPE_BITS[type]) {
+			report(item, `length ${item.length} does not match type ${item.type}`);
+		}
+		if (type !== "bool") {
+			if (item.offset % 8 !== 0) {
+				report(item, `offset ${item.offset} is not on a byte boundary`);
+			} else if (TYPE_BITS[type] > 8 && (item.offset >> 3) % 2 !== 0) {
+				report(item, `byte offset ${item.offset >> 3} is not even`);
+			}
+		}
+		const conflict = init_conflicts.get(item);
+		if (conflict) {
+			report(item, `init_value is given both on the word and on its bits ${conflict.join(", ")}`);
+		}
+		if (!check_init_value(item, type)) {
+			report(item, `init_value ${item.init_value} is not valid for type ${item.type}`);
+		}
+		valid_items.push({ item, type, end: item.offset + TYPE_BITS[type] });
+	}
+
+	// non-Bool tags must not overlap
+	const words = valid_items
+		.filter(({ type }) => type !== "bool")
+		.sort((a, b) => a.item.offset - b.item.offset);
+	let last = null;
+	for (const word of words) {
+		if (last && word.item.offset < last.end) {
+			report(word.item, `overlaps ${last.item.name}`);
+		}
+		if (!last || word.end > last.end) last = word;
+	}
+
+	// each bit belongs to at most one Bool, and a Bool inside a non-Bool tag
+	// must be one of its coupled bits
+	const bits = new Map();
+	for (const { item, type } of valid_items) {
+		if (type !== "bool") continue;
+		const other = bits.get(item.offset);
+		if (other) report(item, `shares bit ${item.offset} with ${other.name}`);
+		else bits.set(item.offset, item);
+		for (const word of words) {
+			if (item.offset < word.item.offset || item.offset >= word.end) continue;
+			if (!item.coupling?.includes(word.item.name)) {
+				report(item, `lies inside ${word.item.name} but is not one of its coupled bits`);
+			}
+		}
+	}
+
+	// coupled bits of a combined tag must lie inside it
+	for (const { item, type, end } of valid_items) {
+		if (type === "bool" || !item.coupling?.length) continue;
+		for (const bit_name of item.coupling) {
+			const bit = by_name.get(bit_name);
+			if (!bit) {
+				report(item, `coupled bit ${bit_name} does not exist`);
+			} else if (bit.type?.toLowerCase() !== "bool") {
+				report(item, `coupled tag ${bit_name} is not a Bool`);
+			} else if (bit.offset < item.offset || bit.offset >= end) {
+				report(item, `coupled bit ${bit_name} lies outside it`);
+			}
+		}
+	}
+
+	// whole registers
+	if (data_struct.length % 16 !== 0) {
+		errors.push(`${struct_name}: length ${data_struct.length} bits is not a whole number of registers`);
+	}
+
+	return errors;
+}

package/src/typedefs.js

@@ -0,0 +1,143 @@
+// Type definitions of the public interface. This file has no run-time content:
+// the JSDoc here is the source of the generated declaration file (dist/types).
+// The types of the internals are in internal_types.js and are not exported.
+
+/**
+ * An entry of a layout description that defines a tag (doc/spec-data-api.md §6.2).
+ *
+ * @typedef {object} Tag_Item
+ * @property {string} name - Tag name.
+ * @property {string} type - Tag type, case-insensitive (see Tag_Type).
+ * @property {number} offset - Bit offset, relative to the parent entry until expanded.
+ * @property {number} [length] - Length in bits, filled in from the type when omitted.
+ * @property {number | boolean} [init_value] - Initial value.
+ * @property {string} [comment] - Description, rendered into the generated types.
+ * @property {boolean} [is_combined] - Descriptive mark of a combined word; the linkage is decided by `coupling`.
+ * @property {Tag_Item[] | string} [coupling] - The bits of a combined word, as an inline list or the name of a fragment.
+ * @property {never} [includes] - A tag entry does not include entries.
+ */
+
+/**
+ * An entry of a layout description that splices in other entries (doc/spec-data-api.md §6.2).
+ *
+ * @typedef {object} Include_Item
+ * @property {Layout_Item[] | string} includes - The entries to include, as an inline list or the name of a fragment.
+ * @property {number} offset - Bit offset by which the included entries are shifted as a whole.
+ * @property {string} [name_prefix] - Prefix of the names of the included entries.
+ * @property {never} [name] - An inclusion defines no tag.
+ * @property {never} [type] - An inclusion defines no tag.
+ */
+
+/**
+ * One entry of a layout description, as written by the user in a layout file
+ * or given to register_layout (doc/spec-data-api.md §6).
+ *
+ * @typedef {Tag_Item | Include_Item} Layout_Item
+ */
+
+/**
+ * A layout description: `layouts` maps layout names to lists of entries, and
+ * every other key is a fragment, a list of entries that can be named
+ * (doc/spec-data-api.md §6.1).
+ *
+ * @typedef {{ layouts?: Record<string, Layout_Item[]> } & Record<string, Layout_Item[] | Record<string, Layout_Item[]> | undefined>} Layout_Description
+ */
+
+/**
+ * One tag of a compiled layout (doc/spec-data-api.md §6.6), read-only:
+ * `name`; `type`, as written in the description; `offset`, the absolute bit
+ * offset; `length` in bits; `init_value`; `comment`, if given; `coupling`,
+ * the tag names of the bits of a combined word, or of the combined words a
+ * bit belongs to.
+ *
+ * @typedef {Readonly<{
+ *   name: string,
+ *   type: string,
+ *   offset: number,
+ *   length: number,
+ *   init_value: number | boolean,
+ *   comment?: string,
+ *   coupling: readonly string[],
+ * }>} Layout_Tag
+ */
+
+/**
+ * A compiled layout (doc/spec-data-api.md §6.6), read-only and deeply frozen:
+ * `name`; `length` in bits; `size` in bytes; `items`, the tags in layout
+ * order (a combined word before its bits).
+ *
+ * @typedef {Readonly<{
+ *   name: string,
+ *   length: number,
+ *   size: number,
+ *   items: readonly Layout_Tag[],
+ * }>} Layout
+ */
+
+/**
+ * Device byte order of an IO buffer (doc/spec-data-api.md §2.9).
+ *
+ * @typedef {"BE" | "LE" | "BEBS" | "LEBS"} Endian
+ */
+
+/**
+ * A source of layouts: the path of a YAML 1.2 layout file, or a description
+ * that is already parsed (the same structure as the file, doc/spec-data-api.md §6.1).
+ *
+ * @typedef {string | Layout_Description} Layout_Source
+ */
+
+/**
+ * The result of registering a layout description.
+ *
+ * @typedef {object} Registered_Layouts
+ * @property {Record<string, Layout>} layouts
+ * @property {Record<string, Layout_Item[]>} fragments
+ */
+
+/**
+ * Type of a tag, in lower case: the type of `Ltag.type` (doc/spec-data-api.md §1).
+ *
+ * @typedef {"bool" | "byte" | "usint" | "sint" | "int" | "uint" | "word" | "dint" | "udint" | "dword" | "real"} Tag_Type
+ */
+
+/**
+ * The listeners of the events of an Ldata that the library emits.
+ *
+ * @typedef {object} Data_Events
+ * @property {(name: string, old_value: number | boolean, new_value: number | boolean) => void} change
+ * @property {(data: import("./Ldata.js").Ldata) => void} write
+ * @property {(kind: "read" | "write", tags: import("./Ltag.js").Ltag[]) => void} access
+ */
+
+/**
+ * A class-level access listener: called for the accesses to every Ldata
+ * (doc/spec-data-api.md §2.8).
+ *
+ * @typedef {(data: import("./Ldata.js").Ldata, kind: "read" | "write", tags: import("./Ltag.js").Ltag[]) => void} Class_Access_Listener
+ */
+
+/**
+ * The listener of an event of an Ldata: typed for `change` and `write`, any
+ * listener for another name (doc/spec-data-api.md §2.7).
+ *
+ * @template {string | symbol} E
+ * @typedef {E extends keyof Data_Events ? Data_Events[E] : (...args: any[]) => void} Data_Listener
+ */
+
+/**
+ * The listeners of the events of an Ltag that the library emits.
+ *
+ * @typedef {object} Tag_Events
+ * @property {(old_value: number | boolean, new_value: number | boolean) => void} change
+ */
+
+/**
+ * The listener of an event of an Ltag: typed for `change`, any listener for
+ * another name (doc/spec-data-api.md §3).
+ *
+ * @template {string | symbol} E
+ * @typedef {E extends keyof Tag_Events ? Tag_Events[E] : (...args: any[]) => void} Tag_Listener
+ */
+
+export {};