@shlomoa/openui-spec 0.1.0

package/dist/src/index.js

@@ -0,0 +1,260 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenUiJson = exports.OpenUiValidationError = exports.OpenUiJsonError = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const _2020_1 = __importDefault(require("ajv/dist/2020"));
+class OpenUiJsonError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "OpenUiJsonError";
+    }
+}
+exports.OpenUiJsonError = OpenUiJsonError;
+class OpenUiValidationError extends OpenUiJsonError {
+    constructor(message) {
+        super(message);
+        this.name = "OpenUiValidationError";
+    }
+}
+exports.OpenUiValidationError = OpenUiValidationError;
+class OpenUiJson {
+    document;
+    options;
+    constructor(document = null, options = {}) {
+        this.document = document;
+        this.options = options;
+    }
+    static load(path, options = {}) {
+        let document;
+        try {
+            document = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+        }
+        catch (error) {
+            throw new OpenUiJsonError(`cannot load JSON document ${path}: ${errorMessage(error)}`);
+        }
+        if (!isJsonObject(document)) {
+            throw new OpenUiJsonError("an OpenUI JSON document must be an object");
+        }
+        return new OpenUiJson(document, options);
+    }
+    static parse(content, options = {}) {
+        let document;
+        try {
+            document = JSON.parse(content);
+        }
+        catch (error) {
+            throw new OpenUiJsonError(`cannot parse JSON document: ${errorMessage(error)}`);
+        }
+        if (!isJsonObject(document)) {
+            throw new OpenUiJsonError("an OpenUI JSON document must be an object");
+        }
+        return new OpenUiJson(document, options);
+    }
+    save(filePath) {
+        if (this.document === null) {
+            throw new OpenUiJsonError("cannot save a removed root object");
+        }
+        (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(filePath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(filePath, this.serialize(), "utf8");
+    }
+    serialize(indent = 2) {
+        if (this.document === null) {
+            throw new OpenUiJsonError("cannot serialize a removed root object");
+        }
+        return escapeNonAscii(JSON.stringify(this.document, null, indent)) + "\n";
+    }
+    validate() {
+        if (this.document === null) {
+            throw new OpenUiValidationError("the root object has been removed");
+        }
+        const schema = this.loadJson(this.options.schema, this.options.schemaPath, "schema");
+        const catalog = this.loadJson(this.options.catalog, this.options.catalogPath, "catalog");
+        const validator = this.createValidator(schema, OpenUiValidationError);
+        if (!validator(this.document)) {
+            throw new OpenUiValidationError(formatValidationErrors(validator.errors));
+        }
+        const supportedTypes = new Set([...this.walk(catalog)].map((node) => node.type));
+        const seenIds = new Set();
+        for (const node of this.walk(this.document)) {
+            if (seenIds.has(node.id)) {
+                throw new OpenUiValidationError(`duplicate object id: ${node.id}`);
+            }
+            seenIds.add(node.id);
+            if (!supportedTypes.has(node.type)) {
+                throw new OpenUiValidationError(`unsupported object type: ${node.type}`);
+            }
+        }
+    }
+    add(parentId, child) {
+        const parent = this.find(parentId);
+        if (parent === undefined) {
+            throw new OpenUiJsonError(`parent object not found: ${parentId}`);
+        }
+        const candidate = structuredClone(child);
+        this.validateChild(candidate);
+        const existingIds = new Set([...this.walk(this.document)].map((node) => node.id));
+        const duplicateId = [...this.walk(candidate)].map((node) => node.id).find((id) => existingIds.has(id));
+        if (duplicateId !== undefined) {
+            throw new OpenUiJsonError(`object id already exists: ${duplicateId}`);
+        }
+        (parent.children ??= []).push(candidate);
+    }
+    remove(objectId, options = {}) {
+        if (this.document === null) {
+            throw new OpenUiJsonError("the root object has already been removed");
+        }
+        if (this.document.id === objectId) {
+            if (options.parentId !== undefined) {
+                throw new OpenUiJsonError("the root object has no parent");
+            }
+            this.document = null;
+            return;
+        }
+        const parent = this.findParent(objectId);
+        if (parent === undefined) {
+            throw new OpenUiJsonError(`object not found: ${objectId}`);
+        }
+        if (options.parentId !== undefined && parent.node.id !== options.parentId) {
+            throw new OpenUiJsonError(`object ${objectId} does not belong to parent ${options.parentId}`);
+        }
+        parent.node.children?.splice(parent.index, 1);
+    }
+    replace(objectId, replacement, options = {}) {
+        const candidate = structuredClone(replacement);
+        this.validateChild(candidate);
+        if (candidate.id !== objectId) {
+            throw new OpenUiJsonError("replacement object id must match the replaced object id");
+        }
+        if (this.document !== null && this.document.id === objectId) {
+            if (options.parentId !== undefined) {
+                throw new OpenUiJsonError("the root object has no parent");
+            }
+            this.document = candidate;
+            return;
+        }
+        const parent = this.findParent(objectId);
+        if (parent === undefined) {
+            throw new OpenUiJsonError(`object not found: ${objectId}`);
+        }
+        if (options.parentId !== undefined && parent.node.id !== options.parentId) {
+            throw new OpenUiJsonError(`object ${objectId} does not belong to parent ${options.parentId}`);
+        }
+        parent.node.children[parent.index] = candidate;
+    }
+    updateAttributes(objectId, attributes) {
+        const node = this.find(objectId);
+        if (node === undefined) {
+            throw new OpenUiJsonError(`object not found: ${objectId}`);
+        }
+        if (!Object.entries(attributes).every(([key, value]) => typeof key === "string" && (value === null || typeof value === "string"))) {
+            throw new OpenUiJsonError("attribute changes must map strings to strings or null");
+        }
+        const updated = structuredClone(node);
+        if (!Object.hasOwn(updated, "attrs")) {
+            updated.attrs = {};
+        }
+        Object.assign(updated.attrs, attributes);
+        this.validateNode(updated, node === this.document);
+        node.attrs = updated.attrs;
+    }
+    validateChild(child) {
+        this.validateNode(child, false);
+        const catalog = this.loadJson(this.options.catalog, this.options.catalogPath, "catalog");
+        const supportedTypes = new Set([...this.walk(catalog)].map((node) => node.type));
+        const seenIds = new Set();
+        for (const node of this.walk(child)) {
+            if (seenIds.has(node.id)) {
+                throw new OpenUiJsonError(`duplicate object id: ${node.id}`);
+            }
+            seenIds.add(node.id);
+            if (!supportedTypes.has(node.type)) {
+                throw new OpenUiJsonError(`unsupported object type: ${node.type}`);
+            }
+        }
+    }
+    validateNode(node, isRoot) {
+        const schema = this.loadJson(this.options.schema, this.options.schemaPath, "schema");
+        const definition = isRoot ? schema : { $ref: "#/$defs/element", $defs: schema.$defs };
+        const validator = this.createValidator(definition, OpenUiJsonError);
+        if (!validator(node)) {
+            throw new OpenUiJsonError(formatValidationErrors(validator.errors));
+        }
+    }
+    find(objectId) {
+        if (this.document === null) {
+            return undefined;
+        }
+        return [...this.walk(this.document)].find((node) => node.id === objectId);
+    }
+    findParent(objectId) {
+        if (this.document === null) {
+            return undefined;
+        }
+        for (const node of this.walk(this.document)) {
+            const index = node.children?.findIndex((child) => child.id === objectId) ?? -1;
+            if (index >= 0) {
+                return { node, index };
+            }
+        }
+        return undefined;
+    }
+    *walk(node) {
+        yield node;
+        for (const child of node.children ?? []) {
+            yield* this.walk(child);
+        }
+    }
+    loadJson(value, filePath, name) {
+        if (value !== undefined) {
+            if (!isJsonObject(value)) {
+                throw new OpenUiValidationError(`OpenUI ${name} must be an object`);
+            }
+            return value;
+        }
+        const resolvedPath = filePath ?? node_path_1.default.resolve(__dirname, "..", "..", "spec", `openui${name === "schema" ? ".schema" : ""}.json`);
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)(resolvedPath, "utf8"));
+            if (!isJsonObject(parsed)) {
+                throw new OpenUiValidationError(`OpenUI ${name} must be an object`);
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error instanceof OpenUiValidationError) {
+                throw error;
+            }
+            throw new OpenUiValidationError(`cannot load ${name} ${resolvedPath}: ${errorMessage(error)}`);
+        }
+    }
+    createValidator(schema, ErrorType) {
+        try {
+            return new _2020_1.default({ allErrors: true, strict: false }).compile(schema);
+        }
+        catch (error) {
+            throw new ErrorType(`invalid OpenUI schema: ${errorMessage(error)}`);
+        }
+    }
+}
+exports.OpenUiJson = OpenUiJson;
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function formatValidationErrors(errors) {
+    return [...(errors ?? [])]
+        .sort((left, right) => left.instancePath.localeCompare(right.instancePath))
+        .map((error) => `${jsonPath(error.instancePath)}: ${error.message}`)
+        .join("\n");
+}
+function jsonPath(instancePath) {
+    return instancePath === "" ? "$" : `$.${instancePath.split("/").filter(Boolean).join(".")}`;
+}
+function escapeNonAscii(value) {
+    return value.replace(/[\u007f-\uffff]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@shlomoa/openui-spec",
+  "version": "0.1.0",
+  "description": "Load, validate, and edit OpenUI JSON documents.",
+  "license": "Apache-2.0",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "ng-openui-spec": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "spec/openui.json",
+    "spec/openui.schema.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/tests/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shlomoa/openui-spec.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "ajv": "8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.4.0",
+    "typescript": "7.0.2"
+  }
+}