layout-data 0.0.0-stage → 0.2.0

package/dist/types/typedefs.d.ts

@@ -0,0 +1,155 @@
+/**
+ * An entry of a layout description that defines a tag (doc/spec-data-api.md §6.2).
+ */
+export type Tag_Item = {
+    /**
+     * - Tag name.
+     */
+    name: string;
+    /**
+     * - Tag type, case-insensitive (see Tag_Type).
+     */
+    type: string;
+    /**
+     * - Bit offset, relative to the parent entry until expanded.
+     */
+    offset: number;
+    /**
+     * - Length in bits, filled in from the type when omitted.
+     */
+    length?: number;
+    /**
+     * - Initial value.
+     */
+    init_value?: number | boolean;
+    /**
+     * - Description, rendered into the generated types.
+     */
+    comment?: string;
+    /**
+     * - Descriptive mark of a combined word; the linkage is decided by `coupling`.
+     */
+    is_combined?: boolean;
+    /**
+     * - The bits of a combined word, as an inline list or the name of a fragment.
+     */
+    coupling?: Tag_Item[] | string;
+    /**
+     * - A tag entry does not include entries.
+     */
+    includes?: never;
+};
+/**
+ * An entry of a layout description that splices in other entries (doc/spec-data-api.md §6.2).
+ */
+export type Include_Item = {
+    /**
+     * - The entries to include, as an inline list or the name of a fragment.
+     */
+    includes: Layout_Item[] | string;
+    /**
+     * - Bit offset by which the included entries are shifted as a whole.
+     */
+    offset: number;
+    /**
+     * - Prefix of the names of the included entries.
+     */
+    name_prefix?: string;
+    /**
+     * - An inclusion defines no tag.
+     */
+    name?: never;
+    /**
+     * - An inclusion defines no tag.
+     */
+    type?: never;
+};
+/**
+ * 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).
+ */
+export type Layout_Item = Tag_Item | Include_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).
+ */
+export type Layout_Description = {
+    layouts?: Record<string, Layout_Item[]>;
+} & Record<string, Layout_Item[] | Record<string, Layout_Item[]> | undefined>;
+/**
+ * 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.
+ */
+export type Layout_Tag = Readonly<{
+    name: string;
+    type: string;
+    offset: number;
+    length: number;
+    init_value: number | boolean;
+    comment?: string;
+    coupling: readonly string[];
+}>;
+/**
+ * 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).
+ */
+export type Layout = Readonly<{
+    name: string;
+    length: number;
+    size: number;
+    items: readonly Layout_Tag[];
+}>;
+/**
+ * Device byte order of an IO buffer (doc/spec-data-api.md §2.9).
+ */
+export type Endian = "BE" | "LE" | "BEBS" | "LEBS";
+/**
+ * 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).
+ */
+export type Layout_Source = string | Layout_Description;
+/**
+ * The result of registering a layout description.
+ */
+export type Registered_Layouts = {
+    layouts: Record<string, Layout>;
+    fragments: Record<string, Layout_Item[]>;
+};
+/**
+ * Type of a tag, in lower case: the type of `Ltag.type` (doc/spec-data-api.md §1).
+ */
+export type Tag_Type = "bool" | "byte" | "usint" | "sint" | "int" | "uint" | "word" | "dint" | "udint" | "dword" | "real";
+/**
+ * The listeners of the events of an Ldata that the library emits.
+ */
+export type Data_Events = {
+    change: (name: string, old_value: number | boolean, new_value: number | boolean) => void;
+    write: (data: import("./Ldata.js").Ldata) => void;
+    access: (kind: "read" | "write", tags: import("./Ltag.js").Ltag[]) => void;
+};
+/**
+ * A class-level access listener: called for the accesses to every Ldata
+ * (doc/spec-data-api.md §2.8).
+ */
+export type Class_Access_Listener = (data: import("./Ldata.js").Ldata, kind: "read" | "write", tags: import("./Ltag.js").Ltag[]) => void;
+/**
+ * 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).
+ */
+export type Data_Listener<E extends string | symbol> = E extends keyof Data_Events ? Data_Events[E] : (...args: any[]) => void;
+/**
+ * The listeners of the events of an Ltag that the library emits.
+ */
+export type Tag_Events = {
+    change: (old_value: number | boolean, new_value: number | boolean) => void;
+};
+/**
+ * The listener of an event of an Ltag: typed for `change`, any listener for
+ * another name (doc/spec-data-api.md §3).
+ */
+export type Tag_Listener<E extends string | symbol> = E extends keyof Tag_Events ? Tag_Events[E] : (...args: any[]) => void;

package/dist/types/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Renders a declaration file with, for each layout, an interface of its tags
+ * (`<Layout>_Tags`, one property per tag) and the type of its data block
+ * (`<Layout>_Ldata`). The layout name is used as it is, with the case it has,
+ * so that the type names are those of `new Ldata("<Layout>", ...)` and layouts
+ * with different names never get the same type name.
+ *
+ * In JavaScript a JSDoc cast names the type of the value, which an editor
+ * uses for completion and, with `checkJs`, to check the tags:
+ *
+ * ```js
+ * const pump = /** @type {import("./layout_types.js").Pump_Ldata} *\/ (new Ldata("Pump", "pump_1"));
+ * ```
+ *
+ * @param {Record<string, import("./typedefs.js").Layout>} layouts - Registered layouts by name.
+ * @param {object} [options]
+ * @param {string} [options.source] - The layout file, named in the header; the header names none when it is omitted.
+ * @param {string} [options.ldata_module] - Module specifier of Ldata, relative to the output file; "layout-data" by default.
+ * @returns {string}
+ * @throws {Error} With `errors`, when the name of a layout is not an identifier, which a type name needs.
+ */
+export function render_types(layouts: Record<string, import("./typedefs.js").Layout>, { source, ldata_module }?: {
+    source?: string;
+    ldata_module?: string;
+}): string;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "layout-data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "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"
+  },
+  "keywords": [
+    "buffer",
+    "struct",
+    "tag",
+    "PLC",
+    "layout"
+  ],
+  "author": "Goosy Jo <goosy.jo@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goosy/data_block.git"
+  },
+  "license": "MPL-2.0",
+  "scripts": {
+    "build": "rolldown -c",
+    "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",
+    "lint": "eslint .",
+    "bench": "node bench/change_detection_bench.js"
+  }
 }