@carbonenginejs/runtime-utils 0.1.1 → 0.1.3

package/src/document/CjsDocumentDehydrator.js

@@ -1,142 +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))
-        ));
-    }
-}
+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

@@ -1,156 +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;
-    }
-}
+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;
+    }
+}