@rcrsr/rill 0.16.0 → 0.17.0

package/dist/runtime/core/type-registrations.js

@@ -0,0 +1,749 @@
+/**
+ * Type Registration Definitions
+ *
+ * Defines the TypeDefinition interface, TypeProtocol interface, and
+ * BUILT_IN_TYPES registration array. Each of the 12 built-in types
+ * carries identity predicates, protocol functions (format, eq, compare,
+ * convertTo, serialize), and a methods record populated from BUILTIN_METHODS.
+ *
+ * Dispatch functions (inferType, formatValue, deepEquals, serializeValue,
+ * deserializeValue, copyValue) iterate registrations and delegate to
+ * per-type protocol implementations.
+ *
+ * Registration order:
+ *   primitives -> discriminator-based -> structural -> list -> dict fallback
+ *
+ * @internal
+ */
+import { isTuple, isVector, isOrdered, isTypeValue, isIterator, createTuple, createOrdered, createVector, formatStructure, structureEquals, } from './values.js';
+import { isCallable, isDict, isScriptCallable, callableEquals, } from './callable.js';
+import { RuntimeError } from '../../types.js';
+// ============================================================
+// IDENTITY HELPERS
+// ============================================================
+/** Identity predicate for field_descriptor values. */
+function isFieldDescriptor(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_field_descriptor' in value &&
+        value['__rill_field_descriptor'] === true);
+}
+/** Identity predicate for closure values. */
+function isClosure(value) {
+    return isCallable(value);
+}
+// ============================================================
+// PROTOCOL IMPLEMENTATIONS: FORMAT
+// ============================================================
+function formatString(v) {
+    if (v === null)
+        return 'type(null)';
+    return v;
+}
+function formatNumber(v) {
+    return String(v);
+}
+function formatBool(v) {
+    return v ? 'true' : 'false';
+}
+function formatTuple(v) {
+    const t = v;
+    return `tuple[${t.entries.map(formatValue).join(', ')}]`;
+}
+function formatOrdered(v) {
+    const o = v;
+    const parts = o.entries.map(([k, val]) => `${k}: ${formatValue(val)}`);
+    return `ordered[${parts.join(', ')}]`;
+}
+function formatVector(v) {
+    const vec = v;
+    return `vector(${vec.model}, ${vec.data.length}d)`;
+}
+function formatTypeValue(v) {
+    const tv = v;
+    return formatStructure(tv.structure);
+}
+function formatClosure(_v) {
+    return 'type(closure)';
+}
+function formatFieldDescriptor(_v) {
+    return 'type(field_descriptor)';
+}
+function formatIterator(_v) {
+    return 'type(iterator)';
+}
+function formatList(v) {
+    const arr = v;
+    return `list[${arr.map(formatValue).join(', ')}]`;
+}
+function formatDict(v) {
+    const dict = v;
+    const parts = Object.entries(dict).map(([k, val]) => `${k}: ${formatValue(val)}`);
+    return `dict[${parts.join(', ')}]`;
+}
+// ============================================================
+// PROTOCOL IMPLEMENTATIONS: EQ
+// ============================================================
+function eqString(a, b) {
+    return a === b;
+}
+function eqNumber(a, b) {
+    return a === b;
+}
+function eqBool(a, b) {
+    return a === b;
+}
+function eqTuple(a, b) {
+    if (!isTuple(a) || !isTuple(b))
+        return false;
+    if (a.entries.length !== b.entries.length)
+        return false;
+    for (let i = 0; i < a.entries.length; i++) {
+        const aVal = a.entries[i];
+        const bVal = b.entries[i];
+        if (aVal === undefined || bVal === undefined) {
+            if (aVal !== bVal)
+                return false;
+        }
+        else if (!deepEquals(aVal, bVal)) {
+            return false;
+        }
+    }
+    return true;
+}
+function eqOrdered(a, b) {
+    if (!isOrdered(a) || !isOrdered(b))
+        return false;
+    if (a.entries.length !== b.entries.length)
+        return false;
+    for (let i = 0; i < a.entries.length; i++) {
+        const aEntry = a.entries[i];
+        const bEntry = b.entries[i];
+        if (aEntry === undefined || bEntry === undefined)
+            return false;
+        if (aEntry[0] !== bEntry[0])
+            return false;
+        if (!deepEquals(aEntry[1], bEntry[1]))
+            return false;
+    }
+    return true;
+}
+function eqVector(a, b) {
+    if (!isVector(a) || !isVector(b))
+        return false;
+    if (a.model !== b.model)
+        return false;
+    if (a.data.length !== b.data.length)
+        return false;
+    for (let i = 0; i < a.data.length; i++) {
+        if (a.data[i] !== b.data[i])
+            return false;
+    }
+    return true;
+}
+function eqTypeValue(a, b) {
+    if (!isTypeValue(a) || !isTypeValue(b))
+        return false;
+    return structureEquals(a.structure, b.structure);
+}
+function eqClosure(a, b) {
+    if (!isCallable(a) || !isCallable(b))
+        return false;
+    // Script callables: structural equality
+    if (isScriptCallable(a) && isScriptCallable(b)) {
+        return callableEquals(a, b, deepEquals);
+    }
+    // Runtime/application callables: reference equality
+    return a === b;
+}
+function eqFieldDescriptor(a, b) {
+    // Field descriptors use reference equality
+    return a === b;
+}
+function eqList(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        const aElem = a[i];
+        const bElem = b[i];
+        if (aElem === undefined || bElem === undefined) {
+            if (aElem !== bElem)
+                return false;
+        }
+        else if (!deepEquals(aElem, bElem)) {
+            return false;
+        }
+    }
+    return true;
+}
+function eqDict(a, b) {
+    const aDict = a;
+    const bDict = b;
+    const aKeys = Object.keys(aDict);
+    const bKeys = Object.keys(bDict);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (!(key in bDict))
+            return false;
+        const aVal = aDict[key];
+        const bVal = bDict[key];
+        if (aVal === undefined || bVal === undefined) {
+            if (aVal !== bVal)
+                return false;
+        }
+        else if (!deepEquals(aVal, bVal)) {
+            return false;
+        }
+    }
+    return true;
+}
+// ============================================================
+// PROTOCOL IMPLEMENTATIONS: COMPARE
+// ============================================================
+function compareString(a, b) {
+    const sa = a;
+    const sb = b;
+    if (sa < sb)
+        return -1;
+    if (sa > sb)
+        return 1;
+    return 0;
+}
+function compareNumber(a, b) {
+    return a - b;
+}
+// ============================================================
+// PROTOCOL IMPLEMENTATIONS: CONVERT-TO
+// ============================================================
+/**
+ * String convertTo targets.
+ * - string -> number: parse numeric string
+ * - string -> bool: "true"/"false" only
+ */
+const stringConvertTo = {
+    number: (v) => {
+        const str = v;
+        const parsed = Number(str);
+        if (isNaN(parsed) || str.trim() === '') {
+            throw new Error(`cannot convert string "${str}" to number`);
+        }
+        return parsed;
+    },
+    bool: (v) => {
+        const s = v;
+        if (s === 'true')
+            return true;
+        if (s === 'false')
+            return false;
+        throw new Error(`cannot convert string "${s}" to bool`);
+    },
+};
+/**
+ * Number convertTo targets.
+ * - number -> string: via String()
+ * - number -> bool: 0 -> false, 1 -> true
+ */
+const numberConvertTo = {
+    string: (v) => String(v),
+    bool: (v) => {
+        const n = v;
+        if (n === 0)
+            return false;
+        if (n === 1)
+            return true;
+        throw new Error(`cannot convert number ${n} to bool`);
+    },
+};
+/**
+ * Bool convertTo targets.
+ * - bool -> string: "true"/"false"
+ * - bool -> number: true -> 1, false -> 0
+ */
+const boolConvertTo = {
+    string: (v) => (v ? 'true' : 'false'),
+    number: (v) => (v ? 1 : 0),
+};
+/**
+ * Tuple convertTo targets.
+ * - tuple -> list: extract entries
+ */
+const tupleConvertTo = {
+    list: (v) => v.entries,
+    string: (v) => formatTuple(v),
+};
+/**
+ * Ordered convertTo targets.
+ * - ordered -> dict: convert entries to plain object
+ */
+const orderedConvertTo = {
+    dict: (v) => {
+        const o = v;
+        const result = {};
+        for (const [key, value] of o.entries) {
+            result[key] = value;
+        }
+        return result;
+    },
+    string: (v) => formatOrdered(v),
+};
+/**
+ * List convertTo targets.
+ * - list -> tuple: wrap in tuple
+ * - list -> string: format
+ */
+const listConvertTo = {
+    tuple: (v) => createTuple(v),
+    string: (v) => formatList(v),
+};
+/**
+ * Dict convertTo targets.
+ * - dict -> string: format
+ */
+const dictConvertTo = {
+    string: (v) => formatDict(v),
+};
+/**
+ * Vector convertTo targets.
+ * - vector -> string: format
+ */
+const vectorConvertTo = {
+    string: (v) => formatVector(v),
+};
+/**
+ * Type value convertTo targets.
+ * - type -> string: format
+ */
+const typeConvertTo = {
+    string: (v) => formatTypeValue(v),
+};
+/**
+ * Closure convertTo targets.
+ * - closure -> string: format
+ */
+const closureConvertTo = {
+    string: (_v) => 'type(closure)',
+};
+/**
+ * Iterator convertTo targets.
+ * - iterator -> string: format
+ */
+const iteratorConvertTo = {
+    string: (_v) => 'type(iterator)',
+};
+// ============================================================
+// PROTOCOL IMPLEMENTATIONS: SERIALIZE
+// ============================================================
+function serializeString(v) {
+    if (v === null)
+        return null;
+    return v;
+}
+function serializeNumber(v) {
+    return v;
+}
+function serializeBool(v) {
+    return v;
+}
+function serializeList(v) {
+    return v.map(serializeListElement);
+}
+/** Recursive serialization for list elements. */
+function serializeListElement(v) {
+    if (v === null)
+        return null;
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'boolean')
+        return v;
+    if (Array.isArray(v))
+        return v.map(serializeListElement);
+    if (isCallable(v))
+        throw new Error('closures are not JSON-serializable');
+    if (isTuple(v))
+        throw new Error('tuples are not JSON-serializable');
+    if (isOrdered(v))
+        throw new Error('ordered values are not JSON-serializable');
+    if (isVector(v))
+        throw new Error('vectors are not JSON-serializable');
+    if (isTypeValue(v))
+        throw new Error('type values are not JSON-serializable');
+    if (isIterator(v))
+        throw new Error('iterators are not JSON-serializable');
+    // Plain dict
+    const dict = v;
+    const result = {};
+    for (const [k, val] of Object.entries(dict)) {
+        result[k] = serializeListElement(val);
+    }
+    return result;
+}
+function serializeDict(v) {
+    const dict = v;
+    const result = {};
+    for (const [k, val] of Object.entries(dict)) {
+        result[k] = serializeListElement(val);
+    }
+    return result;
+}
+function throwNotSerializable(typeName) {
+    return (_v) => {
+        throw new Error(`${typeName}s are not JSON-serializable`);
+    };
+}
+// ============================================================
+// BUILT-IN TYPE REGISTRATIONS
+// ============================================================
+/**
+ * All 12 built-in type registrations.
+ *
+ * Registration order:
+ * 1. Primitives: string, number, bool
+ * 2. Discriminator-based: tuple, ordered, vector, type, closure, field_descriptor
+ * 3. Structural: iterator
+ * 4. list
+ * 5. dict (fallback, must be last)
+ *
+ * AC-1: 12 registrations, one per type.
+ * BC-2: Vector identity checked before dict fallback.
+ * EC-3: Iterator has no protocol.eq.
+ * EC-4: Bool has no protocol.compare.
+ * EC-8: Non-serializable types throw plain Error.
+ */
+export const BUILT_IN_TYPES = Object.freeze([
+    // ---- Primitives ----
+    {
+        name: 'string',
+        identity: (v) => typeof v === 'string' || v === null,
+        isLeaf: true,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatString,
+            eq: eqString,
+            compare: compareString,
+            convertTo: stringConvertTo,
+            serialize: serializeString,
+        },
+    },
+    {
+        name: 'number',
+        identity: (v) => typeof v === 'number',
+        isLeaf: true,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatNumber,
+            eq: eqNumber,
+            compare: compareNumber,
+            convertTo: numberConvertTo,
+            serialize: serializeNumber,
+        },
+    },
+    {
+        name: 'bool',
+        // EC-4: no protocol.compare (ordering unsupported for bool)
+        identity: (v) => typeof v === 'boolean',
+        isLeaf: true,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatBool,
+            eq: eqBool,
+            convertTo: boolConvertTo,
+            serialize: serializeBool,
+        },
+    },
+    // ---- Discriminator-based ----
+    {
+        name: 'tuple',
+        identity: (v) => isTuple(v),
+        isLeaf: false,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatTuple,
+            eq: eqTuple,
+            convertTo: tupleConvertTo,
+            serialize: throwNotSerializable('tuple'),
+        },
+    },
+    {
+        name: 'ordered',
+        identity: (v) => isOrdered(v),
+        isLeaf: false,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatOrdered,
+            eq: eqOrdered,
+            convertTo: orderedConvertTo,
+            serialize: throwNotSerializable('ordered value'),
+        },
+    },
+    {
+        // BC-2: Vector identity checked before dict fallback
+        name: 'vector',
+        identity: (v) => isVector(v),
+        isLeaf: true,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatVector,
+            eq: eqVector,
+            convertTo: vectorConvertTo,
+            serialize: throwNotSerializable('vector'),
+        },
+    },
+    {
+        name: 'type',
+        identity: (v) => isTypeValue(v),
+        isLeaf: true,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatTypeValue,
+            eq: eqTypeValue,
+            convertTo: typeConvertTo,
+            serialize: throwNotSerializable('type value'),
+        },
+    },
+    {
+        name: 'closure',
+        identity: (v) => isClosure(v),
+        isLeaf: true,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatClosure,
+            eq: eqClosure,
+            convertTo: closureConvertTo,
+            serialize: throwNotSerializable('closure'),
+        },
+    },
+    {
+        name: 'field_descriptor',
+        identity: isFieldDescriptor,
+        isLeaf: true,
+        immutable: true,
+        methods: {},
+        protocol: {
+            format: formatFieldDescriptor,
+            eq: eqFieldDescriptor,
+            serialize: throwNotSerializable('field_descriptor'),
+        },
+    },
+    // ---- Structural ----
+    {
+        // EC-3: iterator has no protocol.eq (equality raises RILL-R002)
+        name: 'iterator',
+        identity: (v) => isIterator(v),
+        isLeaf: false,
+        immutable: false,
+        methods: {},
+        protocol: {
+            format: formatIterator,
+            convertTo: iteratorConvertTo,
+            serialize: throwNotSerializable('iterator'),
+        },
+    },
+    // ---- List ----
+    {
+        name: 'list',
+        identity: (v) => Array.isArray(v) && !isTuple(v) && !isOrdered(v),
+        isLeaf: false,
+        immutable: false,
+        methods: {},
+        protocol: {
+            format: formatList,
+            eq: eqList,
+            convertTo: listConvertTo,
+            serialize: serializeList,
+        },
+    },
+    // ---- Dict fallback (must be last) ----
+    {
+        name: 'dict',
+        identity: (v) => isDict(v),
+        isLeaf: false,
+        immutable: false,
+        methods: {},
+        protocol: {
+            format: formatDict,
+            eq: eqDict,
+            convertTo: dictConvertTo,
+            serialize: serializeDict,
+        },
+    },
+]);
+// ============================================================
+// DISPATCH FUNCTIONS
+// ============================================================
+/**
+ * Infer the Rill type name from a runtime value.
+ * Iterates registrations in order; returns first matching name.
+ * Returns 'string' as fallback (BC-1: null IS type string, not a coercion).
+ *
+ * IR-2: Return type widens from RillTypeName to string for extensibility.
+ */
+export function inferType(value) {
+    for (const reg of BUILT_IN_TYPES) {
+        if (reg.identity(value))
+            return reg.name;
+    }
+    return 'string';
+}
+/**
+ * Format a value as a human-readable string.
+ * Determines type via inferType, then calls protocol.format.
+ * Falls back to String(value) when no registration matches.
+ *
+ * IR-3: Protocol dispatcher for formatting.
+ */
+export function formatValue(value) {
+    for (const reg of BUILT_IN_TYPES) {
+        if (reg.identity(value))
+            return reg.protocol.format(value);
+    }
+    return String(value);
+}
+/**
+ * Deep equality comparison for two Rill values.
+ * Short-circuit: a === b returns true.
+ * Dispatches to left operand's protocol.eq.
+ * No protocol.eq returns false.
+ *
+ * IR-4: Container protocol.eq calls deepEquals recursively.
+ */
+export function deepEquals(a, b) {
+    if (a === b)
+        return true;
+    for (const reg of BUILT_IN_TYPES) {
+        if (reg.identity(a)) {
+            if (!reg.protocol.eq)
+                return false;
+            return reg.protocol.eq(a, b);
+        }
+    }
+    return false;
+}
+/**
+ * Serialize a Rill value for JSON transport.
+ * Dispatches to protocol.serialize; container types recurse.
+ *
+ * IR-7: Renamed from valueToJSON.
+ */
+export function serializeValue(value) {
+    for (const reg of BUILT_IN_TYPES) {
+        if (reg.identity(value)) {
+            if (reg.protocol.serialize)
+                return reg.protocol.serialize(value);
+            break;
+        }
+    }
+    return value;
+}
+/**
+ * Deserialize raw data into a Rill value.
+ * Dispatches to protocol.deserialize for the given type name.
+ * Falls back to raw value when no protocol.deserialize exists (primitives).
+ *
+ * IR-8: Raw value fallback rejects null/undefined inputs with RILL-R004.
+ * EC-9: Invalid data raises RILL-R004.
+ * EC-10: null/undefined input raises RILL-R004.
+ */
+export function deserializeValue(data, typeName) {
+    if (data === null || data === undefined) {
+        throw new RuntimeError('RILL-R004', `Cannot deserialize null as ${typeName}`);
+    }
+    for (const reg of BUILT_IN_TYPES) {
+        if (reg.name === typeName) {
+            if (reg.protocol.deserialize)
+                return reg.protocol.deserialize(data);
+            return data;
+        }
+    }
+    throw new RuntimeError('RILL-R004', `Cannot deserialize as ${typeName}`);
+}
+/**
+ * Copy a Rill value.
+ * Reads immutable flag from registration.
+ * Immutable types return same reference.
+ * Mutable types (list, dict, iterator) recurse.
+ *
+ * IR-9: Renamed from deepCopyRillValue.
+ */
+export function copyValue(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    for (const reg of BUILT_IN_TYPES) {
+        if (reg.identity(value)) {
+            if (reg.immutable)
+                return value;
+            break;
+        }
+    }
+    // Mutable: list or dict, recurse
+    if (Array.isArray(value)) {
+        return value.map(copyValue);
+    }
+    const dict = value;
+    const copy = {};
+    for (const [k, v] of Object.entries(dict)) {
+        copy[k] = copyValue(v);
+    }
+    return copy;
+}
+// ============================================================
+// METHOD POPULATION
+// ============================================================
+/** Names of types that carry methods from BUILTIN_METHODS. */
+const METHOD_BEARING_TYPES = new Set([
+    'string',
+    'number',
+    'bool',
+    'list',
+    'dict',
+    'vector',
+]);
+/**
+ * Populate registration `methods` fields from BUILTIN_METHODS.
+ *
+ * Called after builtins.ts finishes initialization to avoid circular
+ * dependency at module load time. The 6 method-bearing types (string,
+ * number, bool, list, dict, vector) receive their methods records;
+ * other types keep `methods: {}`.
+ *
+ * AC-3: Consolidates method data into registrations.
+ *
+ * MUTATION NOTE: BUILT_IN_TYPES is shallow-frozen (the array), but each
+ * registration object is mutable. This function relies on that mutability.
+ * If registration objects are ever deep-frozen (e.g. Object.freeze(reg)),
+ * this assignment will throw in strict mode. The runtime guard below catches
+ * that condition early with a clear error rather than a silent no-op.
+ */
+export function populateBuiltinMethods(builtinMethods) {
+    for (const reg of BUILT_IN_TYPES) {
+        if (METHOD_BEARING_TYPES.has(reg.name) && reg.name in builtinMethods) {
+            if (Object.isFrozen(reg)) {
+                throw new Error(`populateBuiltinMethods: registration '${reg.name}' is frozen; cannot assign methods`);
+            }
+            reg.methods =
+                builtinMethods[reg.name];
+        }
+    }
+}
+// ============================================================
+// RE-EXPORTED FACTORY FUNCTIONS
+// ============================================================
+export { createTuple, createOrdered, createVector };
+// ============================================================
+// RE-EXPORTED GUARD FUNCTIONS
+// ============================================================
+export { isTuple, isVector, isTypeValue, isOrdered, isIterator };
+/** @deprecated Use isIterator instead. */
+export const isRillIterator = isIterator;