layout-data 0.0.0-stage → 0.2.0

package/dist/types/Ldata.d.ts

@@ -0,0 +1,169 @@
+export class Ldata extends EventEmitter<[never]> {
+    /**
+     * 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 "__#private@#class_of"(layout: Layout): typeof Ldata;
+    /**
+     * 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 "__#private@#build_class"(layout: Layout): typeof Ldata;
+    /**
+     * 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: Class_Access_Listener): void;
+    /**
+     * 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_Listener): void;
+    /**
+     * 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: Layout | string, name: string);
+    /** @returns {number} Size of the data block in bytes. */
+    get size(): number;
+    /** @returns {string} The name given at creation, used in logs and error messages. */
+    get name(): string;
+    /**
+     * 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(): Layout;
+    /**
+     * 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<E extends string | symbol>(event: E, listener: Data_Listener<E>): this;
+    /**
+     * Subscribes a listener for one emission, typed like `on`.
+     *
+     * @template {string | symbol} E
+     * @param {E} event
+     * @param {Data_Listener<E>} listener
+     * @returns {this}
+     */
+    once<E extends string | symbol>(event: E, listener: Data_Listener<E>): this;
+    /**
+     * Removes a listener, typed like `on`.
+     *
+     * @template {string | symbol} E
+     * @param {E} event
+     * @param {Data_Listener<E>} listener
+     * @returns {this}
+     */
+    off<E extends string | symbol>(event: E, listener: Data_Listener<E>): this;
+    /**
+     * 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: 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.
+     *
+     * @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<T>(fn: () => T): T;
+    /**
+     * 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?: number, length?: number): Buffer;
+    /**
+     * 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: number, source: Uint8Array): void;
+    /**
+     * 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: number, mask: number, value: boolean): void;
+    /**
+     * 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: string, io_buffer: Uint8Array, endian: Endian): void;
+    /**
+     * 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: string, io_buffer: Uint8Array, endian: Endian): void;
+    #private;
+}
+import { EventEmitter } from "node:events";
+import type { Layout } from "./typedefs.js";
+import type { Data_Listener } from "./typedefs.js";
+import { Ltag } from "./Ltag.js";
+import { Buffer } from "node:buffer";
+import type { Endian } from "./typedefs.js";
+import type { Class_Access_Listener } from "./typedefs.js";

package/dist/types/Ltag.d.ts

@@ -0,0 +1,74 @@
+/** @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<[never]> {
+    /**
+     * @param {import("./Ldata.js").Ldata} ldata - The Ldata the tag belongs to.
+     * @param {Layout_Entry} entry - The compiled entry of the tag.
+     */
+    constructor(ldata: import("./Ldata.js").Ldata, entry: Layout_Entry);
+    /**
+     * 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<E extends string | symbol>(event: E, listener: Tag_Listener<E>): this;
+    /**
+     * Subscribes a listener for one emission, typed like `on`.
+     *
+     * @template {string | symbol} E
+     * @param {E} event
+     * @param {Tag_Listener<E>} listener
+     * @returns {this}
+     */
+    once<E extends string | symbol>(event: E, listener: Tag_Listener<E>): this;
+    /**
+     * Removes a listener, typed like `on`.
+     *
+     * @template {string | symbol} E
+     * @param {E} event
+     * @param {Tag_Listener<E>} listener
+     * @returns {this}
+     */
+    off<E extends string | symbol>(event: E, listener: Tag_Listener<E>): this;
+    /** @returns {string} */
+    get name(): string;
+    /** @returns {Tag_Type} Lower case type name. */
+    get type(): Tag_Type;
+    /** @returns {number} Size in bytes; a Bool has the byte it lies in. */
+    get size(): number;
+    /** @param {number | boolean} value */
+    set value(value: number | boolean);
+    /** @returns {number | boolean} */
+    get value(): number | boolean;
+    /**
+     * 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: Uint8Array, endian: Endian): void;
+    /**
+     * 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: Uint8Array, endian: Endian): void;
+    #private;
+}
+import { EventEmitter } from "node:events";
+import type { Tag_Listener } from "./typedefs.js";
+import type { Tag_Type } from "./typedefs.js";
+import type { Endian } from "./typedefs.js";
+import type { Layout_Entry } from "./internal_types.js";

package/dist/types/codecs.d.ts

@@ -0,0 +1,11 @@
+/** The largest finite float32 value; a finite number above it is refused by a Real. */
+export const FLOAT32_MAX: 3.4028234663852886e+38;
+/**
+ * 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: Record<string, import("./internal_types.js").Codec>;

package/dist/types/dispatch.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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: import("node:events").EventEmitter | undefined, event: string, args: any[], errors: unknown[]): void;

package/dist/types/endian.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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: string): void;
+/**
+ * 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: number, endian: Endian): number;
+/**
+ * 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: Layout, endian: Endian): Int32Array;
+/**
+ * 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: Layout_Entry, endian: Endian): {
+    start: number;
+    end: number;
+};
+/**
+ * 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: Layout_Entry, io_buffer: Uint8Array, buffer: Uint8Array, endian: Endian): void;
+/**
+ * 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: Layout_Entry, buffer: Uint8Array, io_buffer: Uint8Array, endian: Endian): void;
+import type { Endian } from "./typedefs.js";
+import type { Layout } from "./typedefs.js";
+import type { Layout_Entry } from "./internal_types.js";

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+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/dist/types/internal_types.d.ts

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

package/dist/types/layout.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Compiles an expanded structure (the result of build_structure) into a Layout
+ * (doc/design.md §3) and registers it under its name, the one source of the
+ * layouts an Ldata is created from. Registering a structure whose canonical
+ * text equals the registered one of that name gives the registered Layout, so
+ * the same layout described twice is compiled once; another structure under a
+ * used name throws. Throws on an unknown type or a duplicated tag name; the
+ * other layout rules are checked by validate_structure. Internal.
+ *
+ * @param {Data_Struct} data_struct
+ * @returns {Layout}
+ * @throws {Error} When the name is used by another layout.
+ */
+export function register_structure(data_struct: Data_Struct): Layout;
+/**
+ * Reads the sources of the layouts (doc/design.md §3), merges their layouts
+ * and fragments into one description and registers it with
+ * register_layout_data. Each source is the path of a YAML layout file or a
+ * parsed description; a list of sources is merged, so a layout may name a
+ * fragment of any source whatever the order. The root key `layouts` of a
+ * source maps layout names to item lists; every other root key is a fragment
+ * referenced by name.
+ *
+ * @param {Layout_Source | Layout_Source[]} sources
+ * @returns {Registered_Layouts}
+ * @throws {Error} With `errors`, every violation found, when the sources are not valid.
+ */
+export function register_sources(sources: Layout_Source | Layout_Source[]): Registered_Layouts;
+/**
+ * Registers the layouts of the sources, once per process: a layout is
+ * described, registered under its name, and then used by that name
+ * (doc/spec-data-api.md §6.4). Nothing is registered when a source is not
+ * valid, and such a call does not use up the single call.
+ *
+ * @param {Layout_Source | Layout_Source[]} sources - The path of a YAML layout file, a parsed description, or a list of them.
+ * @returns {Registered_Layouts}
+ * @throws {Error} With `errors`, every violation found, when the sources are not valid.
+ * @throws {Error} When the layouts were registered by an earlier call.
+ */
+export function register_layout(sources: Layout_Source | Layout_Source[]): Registered_Layouts;
+/**
+ * Registers the layouts of one description that is parsed and complete: the
+ * root key `layouts` and the fragments the layouts name. Internal.
+ *
+ * @param {Record<string, any>} root - The parsed description: `layouts` and the fragments.
+ * @param {string} [origin] - Names the source in errors.
+ * @returns {Registered_Layouts}
+ * @throws {Error} With `errors`, every violation found, when the description is not valid.
+ */
+export function register_layout_data(root: Record<string, any>, origin?: string): Registered_Layouts;
+import type { Data_Struct } from "./internal_types.js";
+import type { Layout } from "./typedefs.js";
+import type { Layout_Source } from "./typedefs.js";
+import type { Registered_Layouts } from "./typedefs.js";

package/dist/types/observer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 {
+    /**
+     * @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: Buffer, name: string, compiled: Compiled_Layout, report: (entry: Layout_Entry, old_value: any, new_value: any, errors: unknown[]) => void);
+    /**
+     * Registers the byte range [start, end) as written.
+     *
+     * @param {number} start
+     * @param {number} end - Exclusive.
+     */
+    touch(start: number, end: number): void;
+    /**
+     * Forgets the registered range: the buffer was restored to the snapshot.
+     */
+    discard(): void;
+    /**
+     * 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: unknown[]): void;
+    #private;
+}
+import { Buffer } from "node:buffer";
+import type { Compiled_Layout } from "./internal_types.js";
+import type { Layout_Entry } from "./internal_types.js";

package/dist/types/registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @param {Layout} layout
+ * @param {Compiled_Layout} data
+ */
+export function set_compiled(layout: Layout, data: Compiled_Layout): void;
+/**
+ * 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: Layout): Compiled_Layout;
+/**
+ * @param {string} name
+ * @returns {Registered | undefined}
+ */
+export function registered_of(name: string): Registered | undefined;
+/**
+ * @param {string} name
+ * @param {Registered} entry
+ */
+export function register(name: string, entry: Registered): void;
+/**
+ * The registered layout of a name, undefined when there is none.
+ *
+ * @param {string} name
+ * @returns {Layout | undefined}
+ */
+export function find_layout(name: string): Layout | undefined;
+/**
+ * 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: string): Layout;
+export type Registered = {
+    /**
+     * - The canonical text of the structure, to tell the same layout from another one.
+     */
+    key: string;
+    layout: Layout;
+};
+import type { Layout } from "./typedefs.js";
+import type { Compiled_Layout } from "./internal_types.js";

package/dist/types/reserved.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a tag name would shadow a member of a data block.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function is_reserved_name(name: string): boolean;
+/** Event names of the library; a user does not emit them or use them for its own events. */
+export const RESERVED_EVENTS: readonly string[];

package/dist/types/structure.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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: {
+    name: string;
+}, items: Layout_Item[]): Data_Struct;
+/**
+ * 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: Data_Struct): string[];
+/**
+ * Bit length of each tag type (lower case names).
+ *
+ * @type {Record<string, number>}
+ */
+export const TYPE_BITS: Record<string, number>;
+import type { Layout_Item } from "./typedefs.js";
+import type { Data_Struct } from "./internal_types.js";