@carbonenginejs/runtime-utils 0.1.0

package/src/document/CjsDocumentDehydrator.js

@@ -0,0 +1,142 @@
+import { exportCarbonValue } from "../types/index.js";
+import { CjsSchema } from "../schema/index.js";
+import { CjsCarbonDocument } from "./CjsCarbonDocument.js";
+
+/** Converts runtime object graphs into neutral Carbon documents. */
+export class CjsDocumentDehydrator
+{
+    Dehydrate(value, options = {})
+    {
+        return CjsDocumentDehydrator.dehydrate(value, options);
+    }
+
+    static dehydrate(value, options = {})
+    {
+        const state = {
+            nextId: options.firstId || 1,
+            objectIds: new Map(),
+            nodes: [],
+            refs: {},
+            includeClassMetadata: Boolean(options.includeClassMetadata || options.trace || options.debug),
+            includeRefIndex: Boolean(options.includeRefIndex || options.trace || options.debug)
+        };
+
+        const rootRef = CjsDocumentDehydrator.dehydrateValue(value, state);
+        if (!CjsCarbonDocument.isRef(rootRef))
+        {
+            throw new TypeError("CarbonDocument roots must be source-shaped objects");
+        }
+
+        if (state.includeRefIndex)
+        {
+            for (const node of state.nodes)
+            {
+                state.refs[String(node.id)] = {
+                    kind: node.kind
+                };
+            }
+        }
+
+        return CjsCarbonDocument.create({
+            format: options.format || { id: "runtime", version: 1 },
+            roots: [{ name: options.rootName || "default", ref: rootRef }],
+            nodes: state.nodes.sort((a, b) => a.id - b.id),
+            refs: state.includeRefIndex ? state.refs : null,
+            metadata: options.metadata || {},
+            reports: options.reports || []
+        });
+    }
+
+    static dehydrateValue(value, state)
+    {
+        if (CjsDocumentDehydrator.isSourceShapedObject(value)) return CjsDocumentDehydrator.dehydrateSourceObject(value, state);
+        if (Array.isArray(value)) return value.map(item => CjsDocumentDehydrator.dehydrateValue(item, state));
+        if (value instanceof Map) return Object.fromEntries(Array.from(value.entries()).map(([key, item]) => [key, CjsDocumentDehydrator.dehydrateValue(item, state)]));
+        if (value instanceof Set) return Array.from(value.values()).map(item => CjsDocumentDehydrator.dehydrateValue(item, state));
+        if (value && typeof value === "object" && !ArrayBuffer.isView(value))
+        {
+            return Object.fromEntries(
+                Object.entries(value)
+                    .filter(([key]) => !key.startsWith("_"))
+                    .map(([key, item]) => [key, CjsDocumentDehydrator.dehydrateValue(item, state)])
+            );
+        }
+        return exportCarbonValue(value);
+    }
+
+    static dehydrateSourceObject(value, state)
+    {
+        if (state.objectIds.has(value)) return CjsCarbonDocument.createRef(state.objectIds.get(value));
+
+        const id = state.nextId++;
+        state.objectIds.set(value, id);
+
+        const shape = value._sourceShape || null;
+        const schemaName = typeof value.GetValues === "function"
+            ? CjsSchema.getClassName(value.constructor)
+            : null;
+        const kind = schemaName || value._sourceClassName;
+        if (!kind)
+        {
+            throw new TypeError("Hydratable objects require an explicit schema className.");
+        }
+        const fields = {};
+        const fieldNames = new Set();
+
+        if (shape?.fields)
+        {
+            for (const field of shape.fields)
+            {
+                if (schemaName && CjsSchema.isFieldHidden(value.constructor, field.name)) continue;
+                fieldNames.add(field.name);
+                fields[field.name] = CjsDocumentDehydrator.dehydrateValue(value[field.name], state);
+            }
+        }
+        else if (typeof value.GetValues === "function")
+        {
+            for (const [key, item] of Object.entries(value.GetValues()))
+            {
+                fieldNames.add(key);
+                fields[key] = CjsDocumentDehydrator.dehydrateValue(item, state);
+            }
+        }
+
+        const raw = {};
+        for (const [key, item] of Object.entries(value))
+        {
+            if (key.startsWith("_") || fieldNames.has(key)) continue;
+            if (schemaName && CjsSchema.isFieldHidden(value.constructor, key)) continue;
+            raw[key] = CjsDocumentDehydrator.dehydrateValue(item, state);
+        }
+
+        const node = {
+            id,
+            kind,
+            fields
+        };
+
+        if (state.includeClassMetadata)
+        {
+            node.source = shape?.source || {};
+            node.meta = {
+                family: shape?.family || null,
+                hashes: shape?.hashes || null,
+                blue: shape?.blue || null
+            };
+        }
+
+        if (Object.keys(raw).length) node.raw = raw;
+
+        state.nodes.push(node);
+
+        return CjsCarbonDocument.createRef(id);
+    }
+
+    static isSourceShapedObject(value)
+    {
+        return Boolean(value && typeof value === "object" && (
+            value._sourceClassName
+            || (typeof value.GetValues === "function" && CjsSchema.getClassName(value.constructor))
+        ));
+    }
+}

package/src/document/CjsDocumentHydrator.js

@@ -0,0 +1,156 @@
+import { normalizeCarbonValue } from "../types/index.js";
+import { CjsSchema } from "../schema/index.js";
+import { CjsCarbonDocument } from "./CjsCarbonDocument.js";
+import { resolveHydrationAdapter } from "./hydrationAdapter.js";
+
+/** Constructs runtime object graphs from neutral Carbon documents. */
+export class CjsDocumentHydrator
+{
+    Hydrate(document, options = {})
+    {
+        return CjsDocumentHydrator.hydrate(document, options);
+    }
+
+    HydrateRoot(document, options = {})
+    {
+        return CjsDocumentHydrator.hydrateRoot(document, options);
+    }
+
+    static hydrate(document, options = {})
+    {
+        const normalized = CjsCarbonDocument.normalize(document);
+        const nodeById = new Map(normalized.nodes.map(node => [node.id, node]));
+        const instanceById = new Map();
+        const reports = [];
+        const adapter = resolveHydrationAdapter(options);
+
+        for (const node of normalized.nodes)
+        {
+            instanceById.set(node.id, CjsDocumentHydrator.createNodeTarget(node, options, reports, adapter));
+        }
+
+        for (const node of normalized.nodes)
+        {
+            CjsDocumentHydrator.applyNodeValues(instanceById.get(node.id), node, instanceById, options, adapter);
+        }
+
+        // Phase 3: every instance is constructed and valued, so references are
+        // resolved - now let callers run their own post-graph init.
+        for (const node of normalized.nodes)
+        {
+            adapter.finalize(instanceById.get(node.id), { kind: node.kind, node, options });
+        }
+
+        const roots = normalized.roots.map(root => ({
+            name: root.name,
+            value: CjsDocumentHydrator.resolveDocumentValue(root.ref, instanceById, options)
+        }));
+
+        return {
+            root: roots[0]?.value ?? null,
+            roots,
+            document: normalized,
+            reports,
+            get(id)
+            {
+                return instanceById.get(Number(id)) || null;
+            },
+            getNode(id)
+            {
+                return nodeById.get(Number(id)) || null;
+            }
+        };
+    }
+
+    static hydrateRoot(document, options = {})
+    {
+        return CjsDocumentHydrator.hydrate(document, options).root;
+    }
+
+    static createNodeTarget(node, options, reports, adapter)
+    {
+        if (adapter)
+        {
+            const built = adapter.construct(node.kind, { kind: node.kind, node, options });
+            if (built !== undefined) return built;
+        }
+
+        const ClassConstructor = CjsDocumentHydrator.resolveClass(node.kind, options);
+        if (ClassConstructor)
+        {
+            return new ClassConstructor();
+        }
+
+        throw new TypeError(`No class is registered for hydratable type ${node.kind}.`);
+    }
+
+    static applyNodeValues(target, node, instanceById, options, adapter)
+    {
+        const registeredSchema = target?.constructor
+            ? CjsSchema.getSchema(target.constructor)
+            : null;
+        const shape = target?._sourceShape || (registeredSchema?.className ? registeredSchema : null);
+        const fieldByName = new Map((shape?.fields || []).map(field => [field.name, field]));
+        const values = {};
+
+        for (const [key, item] of Object.entries(node.fields || {}))
+        {
+            if (CjsSchema.isFieldHidden(target?.constructor, key)) continue;
+            const field = fieldByName.get(key) || null;
+            values[key] = CjsDocumentHydrator.hydrateFieldValue(item, field, instanceById, options);
+        }
+
+        for (const [key, item] of Object.entries(node.raw || {}))
+        {
+            if (CjsSchema.isFieldHidden(target?.constructor, key)) continue;
+            values[key] = CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options);
+        }
+
+        const apply = adapter || resolveHydrationAdapter(options);
+        apply.applyValues(target, values, { kind: node.kind, shape, node, options });
+        return target;
+    }
+
+    static hydrateFieldValue(value, field, instanceById, options)
+    {
+        const resolved = CjsDocumentHydrator.resolveDocumentValue(value, instanceById, options);
+        const descriptor = field?.type || field?.jsType || null;
+        const kind = descriptor?.kind;
+
+        if ((kind === "array" || kind === "list") && Array.isArray(resolved)) return resolved;
+        if ((kind === "model" || kind === "objectRef" || kind === "struct" || kind === "rawStruct" || kind === "unknown") && resolved && typeof resolved === "object") return resolved;
+        if (CjsDocumentHydrator.isShapeIncompatibleMathArray(resolved, descriptor)) return resolved;
+
+        return descriptor ? normalizeCarbonValue(resolved, descriptor) : resolved;
+    }
+
+    static resolveDocumentValue(value, instanceById, options)
+    {
+        if (CjsCarbonDocument.isRef(value))
+        {
+            const id = Number(value.$ref);
+            if (instanceById.has(id)) return instanceById.get(id);
+            if (options.allowMissingRefs) return null;
+            throw new TypeError(`CarbonDocument ref ${id} does not exist`);
+        }
+
+        if (Array.isArray(value)) return value.map(item => CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options));
+        if (value && typeof value === "object")
+        {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, CjsDocumentHydrator.resolveDocumentValue(item, instanceById, options)]));
+        }
+        return value;
+    }
+
+    static resolveClass(kind, options)
+    {
+        const Schema = options.registry || CjsSchema;
+        return Schema.GetConstructor(kind);
+    }
+
+    static isShapeIncompatibleMathArray(value, descriptor)
+    {
+        const expectedLength = descriptor?.length;
+        return Array.isArray(value) && Number.isInteger(expectedLength) && value.length !== expectedLength;
+    }
+}

package/src/document/CjsStructRegistry.js

@@ -0,0 +1,348 @@
+/** Maps serialized Carbon struct names to explicit constructors and layouts. */
+export class CjsStructRegistry
+{
+    constructor(options = {})
+    {
+        const {
+            name = "structs",
+            family = "",
+            constructors = null,
+            layouts = null,
+            entries = [],
+            aliases = null,
+            metadata = {}
+        } = options;
+
+        this.name = String(name || "structs");
+        this.family = String(family || "");
+        this.metadata = { ...metadata };
+        this.entries = new Map();
+        this.aliases = new Map();
+        this.reports = [];
+
+        if (constructors || layouts)
+        {
+            this.RegisterMaps({ constructors, layouts, aliases });
+        }
+
+        this.RegisterMany(entries);
+        this.RegisterAliases(aliases);
+    }
+
+    get size()
+    {
+        return this.entries.size;
+    }
+
+    RegisterMaps(options = {})
+    {
+        const {
+            constructors = {},
+            layouts = {},
+            aliases = {}
+        } = options;
+
+        const names = new Set([
+            ...Object.keys(constructors || {}).filter(name => typeof constructors[name] === "function"),
+            ...Object.keys(layouts || {})
+        ]);
+
+        for (const structName of names)
+        {
+            this.Register({
+                structName,
+                constructor: typeof constructors?.[structName] === "function" ? constructors[structName] : null,
+                layout: layouts?.[structName] || null,
+                aliases: aliasesForStructName(structName, aliases),
+                family: layouts?.[structName]?.family || this.family
+            });
+        }
+
+        return this;
+    }
+
+    RegisterMany(entries = [])
+    {
+        const list = Array.isArray(entries) ? entries : Object.values(entries || {});
+        for (const entry of list)
+        {
+            this.Register(entry);
+        }
+        return this;
+    }
+
+    Register(entry)
+    {
+        const normalized = normalizeStructEntry(entry, this.family);
+        const existing = this.entries.get(normalized.structName);
+
+        if (existing)
+        {
+            this.entries.set(normalized.structName, mergeStructEntries(existing, normalized));
+            this.ReportEntryClashes(existing, normalized);
+        }
+        else
+        {
+            this.entries.set(normalized.structName, normalized);
+        }
+
+        for (const alias of normalized.aliases)
+        {
+            this.RegisterAlias(alias, normalized.structName);
+        }
+
+        return this;
+    }
+
+    RegisterAliases(aliases = null)
+    {
+        if (!aliases) return this;
+
+        if (Array.isArray(aliases))
+        {
+            for (const item of aliases)
+            {
+                if (Array.isArray(item)) this.RegisterAlias(item[0], item[1]);
+                else this.RegisterAlias(item.alias, item.structName || item.name || item.target);
+            }
+            return this;
+        }
+
+        for (const [key, value] of Object.entries(aliases))
+        {
+            if (Array.isArray(value))
+            {
+                for (const alias of value)
+                {
+                    this.RegisterAlias(alias, key);
+                }
+            }
+            else
+            {
+                this.RegisterAlias(key, value);
+            }
+        }
+
+        return this;
+    }
+
+    RegisterAlias(alias, structName)
+    {
+        if (!alias || !structName) return this;
+
+        const normalizedAlias = String(alias);
+        const normalizedStructName = String(structName);
+        const existing = this.aliases.get(normalizedAlias);
+
+        if (existing && existing !== normalizedStructName)
+        {
+            this.reports.push({
+                level: "warning",
+                code: "alias-clash",
+                alias: normalizedAlias,
+                existingStructName: existing,
+                structName: normalizedStructName,
+                message: `Struct alias ${normalizedAlias} already points to ${existing}`
+            });
+            return this;
+        }
+
+        if (this.entries.has(normalizedAlias) && normalizedAlias !== normalizedStructName)
+        {
+            this.reports.push({
+                level: "warning",
+                code: "alias-struct-clash",
+                alias: normalizedAlias,
+                structName: normalizedStructName,
+                message: `Struct alias ${normalizedAlias} also names a registered struct`
+            });
+        }
+
+        this.aliases.set(normalizedAlias, normalizedStructName);
+        return this;
+    }
+
+    ResolveName(name)
+    {
+        let current = String(name || "");
+        const seen = new Set();
+
+        while (this.aliases.has(current) && !seen.has(current))
+        {
+            seen.add(current);
+            current = this.aliases.get(current);
+        }
+
+        return current;
+    }
+
+    GetEntry(name)
+    {
+        return this.entries.get(this.ResolveName(name)) || null;
+    }
+
+    Has(name)
+    {
+        return Boolean(this.GetEntry(name));
+    }
+
+    GetConstructor(name)
+    {
+        return this.GetEntry(name)?.constructor || null;
+    }
+
+    GetLayout(name)
+    {
+        return this.GetEntry(name)?.layout || null;
+    }
+
+    Create(name, values = {})
+    {
+        const StructConstructor = this.GetConstructor(name);
+        return StructConstructor ? new StructConstructor(values) : { ...values };
+    }
+
+    GetReports()
+    {
+        return this.reports.map(report => ({ ...report }));
+    }
+
+    ToJSON()
+    {
+        return {
+            name: this.name,
+            family: this.family,
+            metadata: { ...this.metadata },
+            entries: Array.from(this.entries.values()).map(entry => ({
+                structName: entry.structName,
+                family: entry.family,
+                aliases: [...entry.aliases],
+                hasConstructor: Boolean(entry.constructor),
+                hasLayout: Boolean(entry.layout),
+                layout: summarizeLayout(entry.layout)
+            })),
+            aliases: Object.fromEntries(this.aliases),
+            reports: this.GetReports()
+        };
+    }
+
+    [Symbol.iterator]()
+    {
+        return this.entries.values();
+    }
+
+    ReportEntryClashes(existing, incoming)
+    {
+        if (existing.constructor && incoming.constructor && existing.constructor !== incoming.constructor)
+        {
+            this.reports.push(createStructClash("constructor-clash", existing, incoming));
+        }
+
+        if (existing.layout && incoming.layout && existing.layout !== incoming.layout)
+        {
+            this.reports.push(createStructClash("layout-clash", existing, incoming));
+        }
+    }
+
+    static from(options = {})
+    {
+        return options instanceof CjsStructRegistry ? options : new CjsStructRegistry(options);
+    }
+
+    static fromMaps(options = {})
+    {
+        return new CjsStructRegistry(options);
+    }
+}
+
+function normalizeStructEntry(entry, defaultFamily)
+{
+    if (!entry || typeof entry !== "object")
+    {
+        throw new TypeError("Struct registry entry must be an object");
+    }
+
+    const entryConstructor = Object.hasOwn(entry, "constructor") ? entry.constructor : null;
+    const constructor = typeof entryConstructor === "function" ? entryConstructor : null;
+    const layout = entry.layout || null;
+    const structName = String(entry.structName || entry.name || layout?.structName || constructor?.sourceStruct || "");
+
+    if (!structName)
+    {
+        throw new TypeError("Struct registry entry is missing a structName");
+    }
+
+    return {
+        structName,
+        constructor,
+        layout,
+        aliases: normalizeAliases(entry.aliases),
+        family: String(entry.family || layout?.family || defaultFamily || ""),
+        metadata: { ...(entry.metadata || {}) }
+    };
+}
+
+function mergeStructEntries(existing, incoming)
+{
+    return {
+        structName: existing.structName,
+        constructor: existing.constructor || incoming.constructor,
+        layout: existing.layout || incoming.layout,
+        aliases: Array.from(new Set([...existing.aliases, ...incoming.aliases])),
+        family: existing.family || incoming.family,
+        metadata: { ...existing.metadata, ...incoming.metadata }
+    };
+}
+
+function normalizeAliases(aliases)
+{
+    if (!aliases) return [];
+    if (Array.isArray(aliases)) return aliases.map(String).filter(Boolean);
+    return [String(aliases)].filter(Boolean);
+}
+
+function aliasesForStructName(structName, aliases)
+{
+    if (!aliases || Array.isArray(aliases)) return [];
+
+    const direct = aliases[structName];
+    if (Array.isArray(direct)) return direct;
+
+    const matched = [];
+    for (const [alias, target] of Object.entries(aliases))
+    {
+        if (target === structName) matched.push(alias);
+    }
+    return matched;
+}
+
+function createStructClash(code, existing, incoming)
+{
+    return {
+        level: "warning",
+        code,
+        structName: existing.structName,
+        message: `${existing.structName} has conflicting struct registry metadata`,
+        existing: summarizeEntry(existing),
+        incoming: summarizeEntry(incoming)
+    };
+}
+
+function summarizeEntry(entry)
+{
+    return {
+        structName: entry.structName,
+        hasConstructor: Boolean(entry.constructor),
+        hasLayout: Boolean(entry.layout)
+    };
+}
+
+function summarizeLayout(layout)
+{
+    if (!layout || typeof layout !== "object") return null;
+    return {
+        structName: layout.structName || layout.name || null,
+        byteSize: layout.byteSize ?? layout.structureSize ?? null,
+        fieldCount: Array.isArray(layout.fields) ? layout.fields.length : null
+    };
+}