layout-data 0.2.0 → 0.3.0

package/src/Ltag.js

@@ -0,0 +1,87 @@
+import { EventEmitter } from "node:events";
+
+/** @import { Endian, Tag_Listener, Tag_Type } from "./typedefs.js" */
+/** @import { Layout_Entry } from "./internal_types.js" */
+
+/**
+ * The interface of one tag of an Ldata (doc/spec-data-api.md §3). It holds no
+ * value: reading `value` decodes it from the buffer of the Ldata, writing it
+ * is the same as `ldata[name] = value`, and `load` / `store` are `load_tag` /
+ * `store_tag` of the Ldata for the name of the tag. `change` events
+ * (old_value, new_value) are emitted by the Observer of the Ldata.
+ */
+export class Ltag extends EventEmitter {
+	/** @type {import("./Ldata.js").Ldata} */
+	#ldata;
+	/** @type {Layout_Entry} */
+	#entry;
+
+	/**
+	 * @param {import("./Ldata.js").Ldata} ldata - The Ldata the tag belongs to.
+	 * @param {Layout_Entry} entry - The compiled entry of the tag.
+	 */
+	constructor(ldata, entry) {
+		super();
+		this.#ldata = ldata;
+		this.#entry = entry;
+		this.setMaxListeners(20);
+	}
+
+	/**
+	 * Subscribes a listener; `change` is typed (old_value, new_value), any
+	 * listener for another event name (doc/spec-data-api.md §3).
+	 *
+	 * @template {string | symbol} E
+	 * @param {E} event
+	 * @param {Tag_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 {Tag_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 {Tag_Listener<E>} listener
+	 * @returns {this}
+	 */
+	off(event, listener) { return super.off(event, listener); }
+
+	/** @returns {string} */
+	get name() { return this.#entry.name; }
+	/** @returns {Tag_Type} Lower case type name. */
+	get type() { return this.#entry.type; }
+	/** @returns {number} Size in bytes; a Bool has the byte it lies in. */
+	get size() { return this.#entry.size; }
+	/** @returns {number | boolean} */
+	get value() { return this.#ldata[this.#entry.name]; }
+	/** @param {number | boolean} value */
+	set value(value) { this.#ldata[this.#entry.name] = value; }
+
+	/**
+	 * Same as `ldata.load_tag(name, io_buffer, endian)` (doc/spec-data-api.md §2.9).
+	 *
+	 * @param {Uint8Array} io_buffer
+	 * @param {Endian} endian
+	 */
+	load(io_buffer, endian) { this.#ldata.load_tag(this.#entry.name, io_buffer, endian); }
+
+	/**
+	 * Same as `ldata.store_tag(name, io_buffer, endian)` (doc/spec-data-api.md §2.9).
+	 *
+	 * @param {Uint8Array} io_buffer
+	 * @param {Endian} endian
+	 */
+	store(io_buffer, endian) { this.#ldata.store_tag(this.#entry.name, io_buffer, endian); }
+}

package/src/codecs.js

@@ -0,0 +1,64 @@
+// Codecs of the tag types on a big-endian buffer (doc/design.md §4).
+// `byte` is the byte offset of the tag; `mask` is the bit mask of a Bool.
+// Device byte order is handled at the IO boundary, not here.
+
+/** The largest finite float32 value; a finite number above it is refused by a Real. */
+export const FLOAT32_MAX = 3.4028234663852886e38;
+
+const read_bool = (buffer, byte, mask) => (buffer[byte] & mask) !== 0;
+const write_bool = (buffer, byte, mask, value) => {
+	buffer[byte] = value ? buffer[byte] | mask : buffer[byte] & ~mask;
+};
+
+/** A Bool takes any value, by truthiness. */
+const check_bool = () => null;
+
+/**
+ * The check of an integer type: a number that is an integer inside the range.
+ *
+ * @param {number} min
+ * @param {number} max
+ * @returns {(value: any) => string | null}
+ */
+const check_integer = (min, max) => (value) => {
+	if (typeof value !== "number") return `a ${typeof value} is not a number`;
+	if (!Number.isInteger(value)) return `${value} is not an integer`;
+	if (value < min || value > max) return `${value} is outside ${min}..${max}`;
+	return null;
+};
+
+/** The check of a Real: any number, NaN and the infinities included, but no finite value beyond float32. */
+const check_real = (value) => {
+	if (typeof value !== "number") return `a ${typeof value} is not a number`;
+	if (Number.isFinite(value) && Math.abs(value) > FLOAT32_MAX) return `${value} is beyond the float32 range`;
+	return null;
+};
+
+const check_byte = check_integer(0, 0xff);
+const check_sint = check_integer(-0x80, 0x7f);
+const check_int = check_integer(-0x8000, 0x7fff);
+const check_uint = check_integer(0, 0xffff);
+const check_dint = check_integer(-0x80000000, 0x7fffffff);
+const check_udint = check_integer(0, 0xffffffff);
+
+/**
+ * Codec of each tag type (lower case): its size in bytes, `check(value)`, which
+ * returns null for a value that can be written and the reason otherwise,
+ * `get(buffer, byte, mask)` and `set(buffer, byte, mask, value)`. `set` is
+ * called with a checked value only (doc/spec-data-api.md §2.3).
+ *
+ * @type {Record<string, import("./internal_types.js").Codec>}
+ */
+export const CODECS = {
+	bool: { size: 1, check: check_bool, get: read_bool, set: write_bool },
+	byte: { size: 1, check: check_byte, get: (b, i) => b.readUInt8(i), set: (b, i, _m, v) => b.writeUInt8(v, i) },
+	usint: { size: 1, check: check_byte, get: (b, i) => b.readUInt8(i), set: (b, i, _m, v) => b.writeUInt8(v, i) },
+	sint: { size: 1, check: check_sint, get: (b, i) => b.readInt8(i), set: (b, i, _m, v) => b.writeInt8(v, i) },
+	int: { size: 2, check: check_int, get: (b, i) => b.readInt16BE(i), set: (b, i, _m, v) => b.writeInt16BE(v, i) },
+	uint: { size: 2, check: check_uint, get: (b, i) => b.readUInt16BE(i), set: (b, i, _m, v) => b.writeUInt16BE(v, i) },
+	word: { size: 2, check: check_uint, get: (b, i) => b.readUInt16BE(i), set: (b, i, _m, v) => b.writeUInt16BE(v, i) },
+	dint: { size: 4, check: check_dint, get: (b, i) => b.readInt32BE(i), set: (b, i, _m, v) => b.writeInt32BE(v, i) },
+	udint: { size: 4, check: check_udint, get: (b, i) => b.readUInt32BE(i), set: (b, i, _m, v) => b.writeUInt32BE(v, i) },
+	dword: { size: 4, check: check_udint, get: (b, i) => b.readUInt32BE(i), set: (b, i, _m, v) => b.writeUInt32BE(v, i) },
+	real: { size: 4, check: check_real, get: (b, i) => b.readFloatBE(i), set: (b, i, _m, v) => b.writeFloatBE(v, i) },
+};

package/src/dispatch.js

@@ -0,0 +1,23 @@
+// Dispatch of events that does not stop at a listener that throws
+// (doc/spec-data-api.md §4.4, doc/design.md §5.1). Internal.
+
+/**
+ * Calls every listener of an event, in the order they subscribed, and pushes
+ * what a listener throws to `errors` instead of letting it stop the others.
+ * A `once` listener removes itself as usual.
+ *
+ * @param {import("node:events").EventEmitter | undefined} emitter - Nothing happens for undefined.
+ * @param {string} event
+ * @param {any[]} args
+ * @param {unknown[]} errors
+ */
+export function emit_all(emitter, event, args, errors) {
+	if (!emitter) return;
+	for (const listener of emitter.rawListeners(event)) {
+		try {
+			listener.apply(emitter, args);
+		} catch (error) {
+			errors.push(error);
+		}
+	}
+}

package/src/endian.js

@@ -0,0 +1,197 @@
+// Conversion between the device byte order of an IO buffer and the big-endian
+// buffer of an Ldata, per compiled layout entry (doc/spec-data-api.md §2.9,
+// doc/design.md §6). Device byte order acts per 16-bit register and per 32-bit
+// value; the IO buffer is indexed like the Ldata buffer. Only io_index_table is
+// exported by the package: Ldata calls the other functions with its own buffer.
+import { compiled_of } from "./registry.js";
+
+/** @import { Endian, Layout } from "./typedefs.js" */
+/** @import { Layout_Entry } from "./internal_types.js" */
+
+// The device byte orders; there are no aliases.
+const ENDIANS = ["BE", "LE", "BEBS", "LEBS"];
+
+// Endians that swap the two bytes of a 16-bit register.
+const BYTE_SWAP_ENDIANS = ["LE", "BEBS"];
+
+/**
+ * Throws for a byte order that is not one of BE, LE, BEBS and LEBS, instead of
+ * treating it as BE and corrupting the data silently.
+ *
+ * @param {string} endian
+ * @throws {RangeError}
+ */
+export function check_endian(endian) {
+	if (!ENDIANS.includes(endian)) {
+		throw new RangeError(`unknown byte order ${endian}: use BE, LE, BEBS or LEBS`);
+	}
+}
+
+/**
+ * Converts the endianness of a 2-byte value between the specified endian format and Big Endian (BE).
+ *
+ * This function performs bidirectional conversion:
+ * - If the data is not in BE, it converts it to BE.
+ * - If the data is in BE, it converts it to the specified endian format.
+ *
+ * @param {Uint8Array} buffer_from - The source buffer containing the data to be converted.
+ * @param {Uint8Array} buffer_to - The destination buffer where the converted data will be written.
+ * @param {number} index - The starting index in the buffers for the 2-byte value.
+ * @param {Endian} endian - The endian format to convert to/from.
+ */
+function convert_endian_2byte(buffer_from, buffer_to, index, endian) {
+	if (BYTE_SWAP_ENDIANS.includes(endian)) { // LE, BEBS: BA
+		buffer_to[index] = buffer_from[index + 1];
+		buffer_to[index + 1] = buffer_from[index];
+	} else { // BE, LEBS: AB
+		buffer_to[index] = buffer_from[index];
+		buffer_to[index + 1] = buffer_from[index + 1];
+	}
+}
+
+/**
+ * Converts the endianness of a 4-byte value between the specified endian format and Big Endian (BE).
+ *
+ * This function performs bidirectional conversion:
+ * - If the data is not in BE, it converts it to BE.
+ * - If the data is in BE, it converts it to the specified endian format.
+ *
+ * The function handles different endian formats:
+ * - LE (Little Endian): DCBA <-> ABCD
+ * - BEBS (Big Endian Byte Swap): BADC <-> ABCD
+ * - LEBS (Little Endian Byte Swap): CDAB <-> ABCD
+ *
+ * @param {Uint8Array} buffer_from - The source buffer containing the data to be converted.
+ * @param {Uint8Array} buffer_to - The destination buffer where the converted data will be written.
+ * @param {number} index - The starting index in the buffers for the 4-byte value.
+ * @param {Endian} endian - The endian format to convert to/from.
+ */
+function convert_endian_4bytes(buffer_from, buffer_to, index, endian) {
+	switch (endian) {
+		case "LE": { // DCBA <-> ABCD
+			buffer_to[index] = buffer_from[index + 3];
+			buffer_to[index + 1] = buffer_from[index + 2];
+			buffer_to[index + 2] = buffer_from[index + 1];
+			buffer_to[index + 3] = buffer_from[index];
+			break;
+		}
+		case "BEBS": { // BADC <-> ABCD
+			buffer_to[index] = buffer_from[index + 1];
+			buffer_to[index + 1] = buffer_from[index];
+			buffer_to[index + 2] = buffer_from[index + 3];
+			buffer_to[index + 3] = buffer_from[index + 2];
+			break;
+		}
+		case "LEBS": { // CDAB <-> ABCD
+			buffer_to[index] = buffer_from[index + 2];
+			buffer_to[index + 1] = buffer_from[index + 3];
+			buffer_to[index + 2] = buffer_from[index];
+			buffer_to[index + 3] = buffer_from[index + 1];
+			break;
+		}
+		default: { // BE
+			for (let k = 0; k < 4; k++) buffer_to[index + k] = buffer_from[index + k];
+		}
+	}
+}
+
+/**
+ * Index in a device-ordered IO buffer of the byte of a single-byte entry
+ * (Bool, Byte, SInt, USInt): when the endian swaps the register bytes, the
+ * byte sits in the other half of its register.
+ *
+ * @param {number} byte - Byte offset of the entry.
+ * @param {Endian} endian - Device byte order.
+ * @returns {number}
+ */
+export function io_index(byte, endian) {
+	return BYTE_SWAP_ENDIANS.includes(endian) ? byte ^ 1 : byte;
+}
+
+/**
+ * The index in a device-ordered IO buffer of every byte of a data block: the
+ * byte `i` of the block is the byte `table[i]` of the IO buffer. The table
+ * makes loading and storing a whole block a plain byte copy, and it agrees
+ * with `load_entry` / `store_entry` for every entry (a Bool or a single-byte
+ * entry maps as `io_index`, a multi-byte entry as its endian).
+ *
+ * @param {Layout} layout - The compiled layout of the data block.
+ * @param {Endian} endian - Device byte order: BE, LE, BEBS or LEBS.
+ * @returns {Int32Array}
+ * @throws {RangeError} For another byte order.
+ */
+export function io_index_table(layout, endian) {
+	check_endian(endian);
+	const table = new Int32Array(layout.size);
+	for (let i = 0; i < table.length; i++) table[i] = io_index(i, endian);
+	for (const { byte, size, type } of compiled_of(layout).entries.values()) {
+		if (size !== 4 || type === "bool") continue;
+		for (let k = 0; k < 4; k++) {
+			switch (endian) {
+				case "LE": table[byte + k] = byte + 3 - k; break;
+				case "BEBS": table[byte + k] = byte + (k ^ 1); break;
+				case "LEBS": table[byte + k] = byte + ((k + 2) % 4); break;
+				default: table[byte + k] = byte + k;
+			}
+		}
+	}
+	return table;
+}
+
+/**
+ * Byte range [start, end) an entry occupies in a device-ordered IO buffer.
+ *
+ * @param {Layout_Entry} entry
+ * @param {Endian} endian - Device byte order.
+ * @returns {{start: number, end: number}}
+ */
+export function io_range(entry, endian) {
+	const start = entry.size === 1 ? io_index(entry.byte, endian) : entry.byte;
+	return { start, end: start + entry.size };
+}
+
+/**
+ * Copies an entry from a device-ordered IO buffer into a big-endian buffer.
+ * A Bool only changes its own bit. No change is detected here, and the byte
+ * order and the range in the IO buffer are not checked (Ldata does).
+ *
+ * @param {Layout_Entry} entry
+ * @param {Uint8Array} io_buffer - The device-ordered source.
+ * @param {Uint8Array} buffer - The big-endian destination.
+ * @param {Endian} endian - Device byte order.
+ */
+export function load_entry(entry, io_buffer, buffer, endian) {
+	const { byte, size, mask } = entry;
+	if (entry.type === "bool") {
+		const value = io_buffer[io_index(byte, endian)] & mask;
+		buffer[byte] = value ? buffer[byte] | mask : buffer[byte] & ~mask;
+	} else if (size === 1) {
+		buffer[byte] = io_buffer[io_index(byte, endian)];
+	} else if (size === 2) {
+		convert_endian_2byte(io_buffer, buffer, byte, endian);
+	} else {
+		convert_endian_4bytes(io_buffer, buffer, byte, endian);
+	}
+}
+
+/**
+ * Copies an entry from a big-endian buffer into a device-ordered IO buffer.
+ *
+ * @param {Layout_Entry} entry
+ * @param {Uint8Array} buffer - The big-endian source.
+ * @param {Uint8Array} io_buffer - The device-ordered destination.
+ * @param {Endian} endian - Device byte order.
+ */
+export function store_entry(entry, buffer, io_buffer, endian) {
+	const { byte, size, mask } = entry;
+	if (entry.type === "bool") {
+		const index = io_index(byte, endian);
+		io_buffer[index] = buffer[byte] & mask ? io_buffer[index] | mask : io_buffer[index] & ~mask;
+	} else if (size === 1) {
+		io_buffer[io_index(byte, endian)] = buffer[byte];
+	} else if (size === 2) {
+		convert_endian_2byte(buffer, io_buffer, byte, endian);
+	} else {
+		convert_endian_4bytes(buffer, io_buffer, byte, endian);
+	}
+}

package/src/index.js

@@ -0,0 +1,8 @@
+// Public interface of the package (doc/design.md §1).
+export { Ldata } from "./Ldata.js";
+export { Ltag } from "./Ltag.js";
+export { register_layout } from "./layout.js";
+export { get_layout } from "./registry.js";
+export { io_index_table } from "./endian.js";
+export { render_types } from "./types.js";
+export * from "./typedefs.js";

package/src/internal_types.js

@@ -0,0 +1,47 @@
+// Type definitions of the internals. This file has no run-time content, and
+// index.js does not export it: the compiled data of a layout is not part of
+// the public interface (doc/spec-data-api.md §6.6).
+
+/**
+ * Codec of one tag type on a big-endian buffer (doc/design.md §4).
+ *
+ * @typedef {object} Codec
+ * @property {number} size - Size in bytes.
+ * @property {(value: any) => string | null} check - The reason a value is refused, null if it can be written.
+ * @property {(buffer: Buffer, byte: number, mask: number) => number | boolean} get
+ * @property {(buffer: Buffer, byte: number, mask: number, value: number | boolean) => void} set
+ */
+
+/**
+ * One tag of a compiled layout.
+ *
+ * @typedef {object} Layout_Entry
+ * @property {string} name
+ * @property {import("./typedefs.js").Tag_Type} type - Lower case type name.
+ * @property {number | boolean} init_value
+ * @property {number} byte - Byte offset.
+ * @property {number} index - Position among the entries of the layout.
+ * @property {number} size - Size in bytes.
+ * @property {number} mask - Bit mask of a Bool, 0xff otherwise.
+ * @property {Codec} codec
+ */
+
+/**
+ * The expanded structure of a data block (the result of build_structure).
+ *
+ * @typedef {object} Data_Struct
+ * @property {string} name
+ * @property {number} length - Total length in bits.
+ * @property {import("./typedefs.js").Layout_Item[]} items
+ */
+
+/**
+ * The compiled data of a layout, kept apart from the public Layout
+ * (doc/design.md §3).
+ *
+ * @typedef {object} Compiled_Layout
+ * @property {Map<string, Layout_Entry>} entries
+ * @property {Layout_Entry[][]} tags_at_byte - The entries covering each byte.
+ */
+
+export {};