homematic-manager 3.0.0-beta.2 → 3.0.0-beta.21

package/node_modules/@homematic-manager/core/dist/meta/paths.js

@@ -0,0 +1,182 @@
+/**
+ * Refs, ids, names and node paths of the metadata store - the small rules the whole format rests on.
+ *
+ * They are separate from `store.ts` because both the store and the UI need them: the grid has to
+ * turn `room/eg/wohnzimmer` into "Wohnzimmer", and a dialog has to know that a node id may not
+ * contain a slash before it lets somebody type one.
+ */
+import { MAX_ID_LENGTH, MAX_NAME_BYTES, MAX_TREE_DEPTH, MetaError } from './types.js';
+/** Enum ids, node ids and `meta` namespaces share one spelling. */
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+/** Icons are looser: a UI maps the name and ignores one it does not know. */
+const ICON_PATTERN = /^[a-z0-9-]+$/;
+/**
+ * `<interface>.<address>` split at the **first** dot, or `undefined`.
+ *
+ * The interface name never contains a dot; the address may (it does not today, but the rule is the
+ * separator, not the shape of what follows it). `BidCos-RF.JEQ0230153:1` is a channel,
+ * `BidCos-RF.JEQ0230153` the device it belongs to.
+ */
+export function parseRef(ref) {
+    const dot = ref.indexOf('.');
+    if (dot <= 0 || dot === ref.length - 1) {
+        return undefined;
+    }
+    return { interfaceName: ref.slice(0, dot), address: ref.slice(dot + 1) };
+}
+/** The ref of an address on an interface. The inverse of {@link parseRef}. */
+export function makeRef(interfaceName, address) {
+    return `${interfaceName}.${address}`;
+}
+/** Is this a ref the store accepts? */
+export function isValidRef(ref) {
+    return parseRef(ref) !== undefined;
+}
+/** Throws `invalid-ref` when it is not. */
+export function requireRef(ref) {
+    const parsed = parseRef(ref);
+    if (!parsed) {
+        throw new MetaError('invalid-ref', `${ref} is not <interface>.<address>`);
+    }
+    return parsed;
+}
+/** Enum id, node id or `meta` namespace: `[a-z0-9][a-z0-9-]*`, at most 32 characters. */
+export function isValidId(id) {
+    return id.length <= MAX_ID_LENGTH && ID_PATTERN.test(id);
+}
+/** Throws `invalid-id` when it is not. */
+export function requireId(id) {
+    if (!isValidId(id)) {
+        throw new MetaError('invalid-id', `${id} is not a valid id`);
+    }
+    return id;
+}
+/** Icons are optional and lax; an unknown name is ignored by the UI, not an error. */
+export function isValidIcon(icon) {
+    return icon.length <= MAX_ID_LENGTH && ICON_PATTERN.test(icon);
+}
+/**
+ * The name as it will be stored: trimmed.
+ *
+ * Empty after trimming, longer than 255 bytes or carrying a line break is `invalid-name`. The trim
+ * is why `"  Heizung Bad  "` written over `"Heizung Bad"` is not a change and does not bump the
+ * revision - the corpus checks exactly that.
+ */
+export function normaliseName(name) {
+    if (typeof name !== 'string') {
+        throw new MetaError('invalid-name', 'a name has to be a string');
+    }
+    const trimmed = name.trim();
+    if (trimmed === '') {
+        throw new MetaError('invalid-name', 'a name may not be empty');
+    }
+    // eslint-disable-next-line no-control-regex -- that is exactly what this rejects
+    if (/[\u0000-\u001f\u007f]/.test(trimmed)) {
+        throw new MetaError('invalid-name', 'a name may not contain control characters');
+    }
+    if (byteLength(trimmed) > MAX_NAME_BYTES) {
+        throw new MetaError('invalid-name', `a name may not be longer than ${String(MAX_NAME_BYTES)} bytes`);
+    }
+    return trimmed;
+}
+/**
+ * Bytes of UTF-8 in a string.
+ *
+ * `TextEncoder` rather than `Buffer.byteLength`: this package runs in the browser as well as in
+ * Node, and the byte limits of the format are a rule about UTF-8, not about a Node API.
+ */
+export function byteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+/**
+ * `room/eg/wohnzimmer` → `{enumId: 'room', ids: ['eg', 'wohnzimmer']}`.
+ *
+ * `room` alone is a valid *query* target (everything in any room) but never a membership target -
+ * an object belongs to nodes, not to enums. The caller decides which of the two it wants; this
+ * only splits.
+ */
+export function parsePath(path) {
+    const parts = path.split('/');
+    const enumId = parts[0];
+    if (enumId === undefined || enumId === '' || !isValidId(enumId)) {
+        return undefined;
+    }
+    const ids = parts.slice(1);
+    if (ids.some((id) => !isValidId(id))) {
+        return undefined;
+    }
+    return { enumId, ids };
+}
+/** The path of a node under a parent path. */
+export function childPath(parent, id) {
+    return `${parent}/${id}`;
+}
+/**
+ * The path without its last segment, or `undefined` when there is nothing to strip.
+ *
+ * For a root node (`room/eg`) that is the enum id (`room`), which is not a node path - the caller
+ * that moves a node treats "the parent is the bare enum id" as "move to the root".
+ */
+export function parentPath(path) {
+    const index = path.lastIndexOf('/');
+    return index <= 0 ? undefined : path.slice(0, index);
+}
+/** Is `path` the node `target` or anything below it? The subtree rule of a membership query. */
+export function pathMatches(path, target) {
+    return path === target || path.startsWith(`${target}/`);
+}
+/** The node a path addresses inside one enum's tree, or `undefined`. */
+export function findNode(tree, ids) {
+    let nodes = tree;
+    let found;
+    for (const id of ids) {
+        found = nodes.find((node) => node.id === id);
+        if (!found) {
+            return undefined;
+        }
+        nodes = found.children ?? [];
+    }
+    return found;
+}
+/**
+ * Every node of one enum, depth first, in display order.
+ *
+ * This is what turns a tree into the flat things a UI needs: a select with indented entries, the
+ * "all rooms" list, and the check that a path exists at all.
+ */
+export function flattenEnum(enumId, definition) {
+    const flat = [];
+    const walk = (nodes, prefix, depth, trail) => {
+        for (const node of nodes) {
+            const path = childPath(prefix, node.id);
+            const names = [...trail, node.name];
+            flat.push({ path, node, depth, trail: names });
+            walk(node.children ?? [], path, depth + 1, names);
+        }
+    };
+    walk(definition.tree, enumId, 1, []);
+    return flat;
+}
+/** Every path of one enum, as a set - the cheap way to check membership targets in bulk. */
+export function enumPaths(enumId, definition) {
+    return new Set(flattenEnum(enumId, definition).map((entry) => entry.path));
+}
+/** The deepest level any node of this tree sits at; `0` for an empty tree. */
+export function treeDepth(tree) {
+    let deepest = 0;
+    const walk = (nodes, depth) => {
+        for (const node of nodes) {
+            deepest = Math.max(deepest, depth);
+            walk(node.children ?? [], depth + 1);
+        }
+    };
+    walk(tree, 1);
+    return deepest;
+}
+/** Throws `too-deep` when a tree is deeper than the eight levels the format allows. */
+export function requireDepth(tree) {
+    if (treeDepth(tree) > MAX_TREE_DEPTH) {
+        throw new MetaError('too-deep', `a tree may not be deeper than ${String(MAX_TREE_DEPTH)} levels`);
+    }
+}
+//# sourceMappingURL=paths.js.map

package/node_modules/@homematic-manager/core/dist/meta/slug.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A node id out of a name a user typed.
+ *
+ * Ids are `[a-z0-9][a-z0-9-]*`, at most 32 characters, and **stable**: renaming a room never
+ * changes its id, which is what keeps every object's membership pointing at the same node. So the
+ * id is derived once, when the node is created, and never again.
+ *
+ * The transcription is the one openccu-lite's own CCU import uses (`docs/meta-api.md`,
+ * `POST /import/ccu`): umlauts written out, everything else that is not `[a-z0-9]` folded to a
+ * hyphen, and a collision resolved with `-2`, `-3`, … so that "Bad" and "Bäd" cannot silently
+ * become the same room.
+ */
+/** The slug of a name, without the collision check. Empty when nothing survives the fold. */
+export declare function slugOf(name: string): string;
+/**
+ * A slug that is free among `taken`, with `-2`, `-3`, … behind it when it is not.
+ *
+ * A name that folds to nothing at all - an id written only in Cyrillic or in emoji - gets `node`
+ * and its number, because an id is a machine key and the *name* is what the user reads.
+ */
+export declare function slugId(name: string, taken?: Iterable<string>): string;
+//# sourceMappingURL=slug.d.ts.map

package/node_modules/@homematic-manager/core/dist/meta/slug.js

@@ -0,0 +1,59 @@
+/**
+ * A node id out of a name a user typed.
+ *
+ * Ids are `[a-z0-9][a-z0-9-]*`, at most 32 characters, and **stable**: renaming a room never
+ * changes its id, which is what keeps every object's membership pointing at the same node. So the
+ * id is derived once, when the node is created, and never again.
+ *
+ * The transcription is the one openccu-lite's own CCU import uses (`docs/meta-api.md`,
+ * `POST /import/ccu`): umlauts written out, everything else that is not `[a-z0-9]` folded to a
+ * hyphen, and a collision resolved with `-2`, `-3`, … so that "Bad" and "Bäd" cannot silently
+ * become the same room.
+ */
+import { isValidId } from './paths.js';
+import { MAX_ID_LENGTH } from './types.js';
+const TRANSCRIPTIONS = [
+    [/ä/g, 'ae'],
+    [/ö/g, 'oe'],
+    [/ü/g, 'ue'],
+    [/ß/g, 'ss'],
+    [/å/g, 'a'],
+    [/æ/g, 'ae'],
+    [/ø/g, 'oe'],
+];
+/** The slug of a name, without the collision check. Empty when nothing survives the fold. */
+export function slugOf(name) {
+    let slug = name.toLowerCase();
+    for (const [pattern, replacement] of TRANSCRIPTIONS) {
+        slug = slug.replace(pattern, replacement);
+    }
+    slug = slug
+        // decomposes é to e + a combining accent, which the next step then drops
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, MAX_ID_LENGTH);
+    return isValidId(slug) ? slug : '';
+}
+/**
+ * A slug that is free among `taken`, with `-2`, `-3`, … behind it when it is not.
+ *
+ * A name that folds to nothing at all - an id written only in Cyrillic or in emoji - gets `node`
+ * and its number, because an id is a machine key and the *name* is what the user reads.
+ */
+export function slugId(name, taken = []) {
+    const used = new Set(taken);
+    const base = slugOf(name) === '' ? 'node' : slugOf(name);
+    if (!used.has(base)) {
+        return base;
+    }
+    for (let suffix = 2; suffix < 1000; suffix += 1) {
+        const candidate = `${base.slice(0, MAX_ID_LENGTH - String(suffix).length - 1)}-${String(suffix)}`;
+        if (!used.has(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`no free id for ${name}`);
+}
+//# sourceMappingURL=slug.js.map

package/node_modules/@homematic-manager/core/dist/meta/store.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The metadata store, in memory: every operation of the metadata API, with its revisions and its
+ * change stream.
+ *
+ * This is the second implementation of openccu-lite's D-16 - `occulited` in Go is the first - and
+ * the conformance corpus is what keeps the two honest. It is used twice here: it *is* the `local`
+ * provider (a user on Homegear, on a bare rfd or on the desktop gets rooms and functions without
+ * any box at all), and it is the model the `occulite` provider keeps of what the box holds, so the
+ * UI reads the same shapes whichever provider is on.
+ *
+ * Three rules run through all of it:
+ *
+ * - **a write that changes nothing is not a write.** It returns `changed: false` and the revision
+ *   stays where it was. Setting a name to the name it already has must not bump a revision that
+ *   every consumer of the change stream is watching.
+ * - **all or nothing.** A bulk, an import and a move that rewrites member paths are one revision;
+ *   a validation error leaves the store exactly as it was.
+ * - **every refusal is a code**, never a boolean: the UI shows a message per code and the corpus
+ *   compares them.
+ */
+import { isValidId } from './paths.js';
+import { type MetaDocument, type MetaEnum, type MetaEvent, type MetaImportMode, type MetaNodePatch, type MetaObject, type MetaObjectBody, type MetaObjectPatch } from './types.js';
+/** How many events the change stream keeps for a consumer that reconnects. The API asks for 1000. */
+export declare const DEFAULT_EVENT_HISTORY = 1000;
+/** What every mutation answers with. `changed: false` means the revision did not move. */
+export interface MetaWriteResult {
+    readonly revision: number;
+    readonly changed: boolean;
+}
+/** What a replay answers with: the events since a revision, or "fetch the snapshot again". */
+export interface MetaReplay {
+    readonly revision: number;
+    readonly events?: readonly MetaEvent[];
+    readonly resync?: true;
+}
+export interface MetaStoreOptions {
+    /** The document to start from; an empty store (revision 0, the two default enums) by default. */
+    readonly document?: MetaDocument;
+    readonly eventHistory?: number;
+    /** Called once per event, after the mutation that produced it has been applied. */
+    readonly onEvent?: (event: MetaEvent) => void;
+}
+export declare class MetaStore {
+    #private;
+    constructor(options?: MetaStoreOptions);
+    get revision(): number;
+    get size(): number;
+    /** The whole store, as `/snapshot` serves it and as it is written to disk. */
+    document(): MetaDocument;
+    /**
+     * Replaces everything without producing an import event or a revision of our own.
+     *
+     * This is how the `occulite` provider takes a snapshot from the box: the box owns the revision,
+     * and a consumer that renumbered it would break every `?since=` it sends afterwards.
+     */
+    load(document: MetaDocument): void;
+    /** One object, or `unknown-object`. */
+    get(ref: string): MetaObject;
+    /** One object, or `undefined` - the read that a UI does for every row of a grid. */
+    find(ref: string): MetaObject | undefined;
+    /** Every object, keyed by ref. */
+    objects(): Readonly<Record<string, MetaObject>>;
+    /** Every enum with its tree. */
+    enums(): Readonly<Record<string, MetaEnum>>;
+    /** One enum, or `unknown-enum`. */
+    getEnum(id: string): MetaEnum;
+    /**
+     * The refs that belong to a node **or anything below it**, sorted.
+     *
+     * `room/eg` answers with everything on the ground floor, `room` with everything that is in any
+     * room at all. That is what the tree buys and why membership is a path and not an id.
+     */
+    query(target: string, orphaned?: boolean): string[];
+    /**
+     * The change stream since a revision: the events, or "fetch the snapshot again".
+     *
+     * A consumer that was away longer than the history, or that asks for something impossible, is
+     * told to resync rather than served a gap it cannot see.
+     */
+    since(revision: number): MetaReplay;
+    /** `PATCH /objects/{ref}`: create or update; absent fields are left alone. */
+    set(ref: string, patch: MetaObjectPatch): MetaWriteResult;
+    /** `PUT /objects/{ref}`: create or replace; missing optional fields go back to their defaults. */
+    put(ref: string, body: MetaObjectBody): MetaWriteResult;
+    /**
+     * `DELETE /objects/{ref}`: forgets an entry for good.
+     *
+     * Normally unnecessary - `orphaned` is how "gone" is expressed, so that a replaced device keeps
+     * its room - but a user may really want to forget one. Deleting what is not there is not an
+     * error: it is the state the caller asked for, and a bulk that carries one must not fail.
+     */
+    delete(ref: string): MetaWriteResult;
+    /** `POST /objects:bulk`: any number of writes and deletes as **one** revision. */
+    bulk(sets: Readonly<Record<string, MetaObjectPatch>>, deletes?: readonly string[]): MetaWriteResult;
+    /**
+     * The `orphaned` flag, which only the process that owns the addresses may set.
+     *
+     * It is a mutation like any other - a consumer has to learn that a device disappeared - and it
+     * never touches the assignments: a device that comes back is in its room again.
+     */
+    setOrphaned(ref: string, orphaned: boolean): MetaWriteResult;
+    /** `POST /enums`. */
+    createEnum(id: string, name: Readonly<Record<string, string>>): MetaWriteResult;
+    /** `PATCH /enums/{enum}`: the display name, nothing else. */
+    updateEnum(id: string, name: Readonly<Record<string, string>>): MetaWriteResult;
+    /**
+     * `DELETE /enums/{enum}`: the enum and every node in it.
+     *
+     * Refused while anything is a member, unless the caller says `detach` - in which case the
+     * paths are removed from every object **in the same revision**, so no consumer ever sees an
+     * object pointing at a node that is already gone.
+     */
+    deleteEnum(id: string, members?: 'refuse' | 'detach'): MetaWriteResult;
+    /** `POST /enums/{enum}/nodes`: a node under a parent, or at the root when `parent` is null. */
+    createNode(enumId: string, parent: string | null, id: string, name: string, options?: {
+        readonly icon?: string;
+        readonly position?: number;
+    }): MetaWriteResult;
+    /**
+     * `PATCH /enums/{enum}/nodes/{path}`: rename, re-icon, move, reorder.
+     *
+     * A move keeps the id, so every member path is rewritten **in the same revision** and consumers
+     * see one `node.moved` carrying `from` and `to` rather than a delete and a create that would
+     * briefly leave objects pointing nowhere.
+     */
+    updateNode(path: string, patch: MetaNodePatch): MetaWriteResult;
+    /** `DELETE /enums/{enum}/nodes/{path}`: the node and its subtree, with the same `detach` rule. */
+    deleteNode(path: string, members?: 'refuse' | 'detach'): MetaWriteResult;
+    /**
+     * `PUT /import`: a whole document, validated completely and applied as one revision.
+     *
+     * `replace` swaps the store; `merge` keeps the objects and enums the import does not mention
+     * and overwrites the ones it does. Either way the *result* is validated - a merge that would
+     * leave an object pointing at a node the import removed is refused, not repaired.
+     */
+    import(raw: unknown, mode?: MetaImportMode): MetaWriteResult;
+}
+/**
+ * `meta` merged per namespace: `null` removes one, any other value replaces it whole.
+ *
+ * Per namespace and not per key, on purpose: the store does not interpret what is inside a
+ * namespace, so it cannot merge it either - only its owner knows what half an update would mean.
+ */
+export declare function mergeMeta(current: Readonly<Record<string, unknown>>, patch: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+/** Is this a valid enum or node id? Re-exported so a dialog can check before it offers to save. */
+export { isValidId };
+//# sourceMappingURL=store.d.ts.map