@rcrsr/rill 0.8.6 → 0.10.0

package/dist/runtime/core/values.js

@@ -4,6 +4,7 @@
  * Core value types that flow through Rill programs.
  * Public API for host applications.
  */
+import { RuntimeError } from '../../types.js';
 import { callableEquals, isCallable, isDict, isScriptCallable, } from './callable.js';
 /** Type guard for RillTuple (spread args) */
 export function isTuple(value) {
@@ -19,24 +20,27 @@ export function isVector(value) {
         '__rill_vector' in value &&
         value.__rill_vector === true);
 }
-/** Create tuple from a list (positional) */
-export function createTupleFromList(list) {
-    const entries = new Map();
-    for (let i = 0; i < list.length; i++) {
-        const val = list[i];
-        if (val !== undefined) {
-            entries.set(i, val);
-        }
-    }
-    return { __rill_tuple: true, entries };
+/** Type guard for RillOrdered (named spread args) */
+export function isOrdered(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_ordered' in value &&
+        value.__rill_ordered === true);
 }
-/** Create tuple from a dict (named) */
-export function createTupleFromDict(dict) {
-    const entries = new Map();
-    for (const [key, value] of Object.entries(dict)) {
-        entries.set(key, value);
-    }
-    return { __rill_tuple: true, entries };
+/** Type guard for RillTypeValue */
+export function isTypeValue(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_type' in value &&
+        value.__rill_type === true);
+}
+/** Create ordered from entries array (named, preserves insertion order) */
+export function createOrdered(entries) {
+    return Object.freeze({ __rill_ordered: true, entries: [...entries] });
+}
+/** Create tuple from entries array (positional, preserves order) */
+export function createTuple(entries) {
+    return Object.freeze({ __rill_tuple: true, entries: [...entries] });
 }
 /**
  * Create vector from Float32Array with model name.
@@ -60,10 +64,16 @@ export function inferType(value) {
         return 'bool';
     if (isTuple(value))
         return 'tuple';
+    if (isOrdered(value))
+        return 'ordered';
     if (isVector(value))
         return 'vector';
     if (Array.isArray(value))
         return 'list';
+    if (isTypeValue(value))
+        return 'type';
+    if (isRillIterator(value))
+        return 'iterator';
     if (typeof value === 'object' &&
         '__type' in value &&
         value.__type === 'callable') {
@@ -73,6 +83,346 @@ export function inferType(value) {
         return 'dict';
     return 'string'; // fallback
 }
+/**
+ * Infer the element type for a homogeneous list.
+ * Empty arrays return { type: 'any' }.
+ * Mixed types throw RILL-R002.
+ */
+export function inferElementType(elements) {
+    if (elements.length === 0)
+        return { type: 'any' };
+    const firstElem = elements[0];
+    const firstType = inferStructuralType(firstElem);
+    for (let i = 1; i < elements.length; i++) {
+        const elem = elements[i];
+        const elemType = inferStructuralType(elem);
+        if (!structuralTypeEquals(firstType, elemType)) {
+            throw new RuntimeError('RILL-R002', `List elements must be the same type: expected ${formatStructuralType(firstType)}, got ${formatStructuralType(elemType)} at index ${i}`);
+        }
+    }
+    return firstType;
+}
+/** Compare two structural types for equality. */
+export function structuralTypeEquals(a, b) {
+    if (a.type !== b.type)
+        return false;
+    // Leaf variants compare by type alone
+    if (a.type === 'number' ||
+        a.type === 'string' ||
+        a.type === 'bool' ||
+        a.type === 'vector' ||
+        a.type === 'type' ||
+        a.type === 'any') {
+        return true;
+    }
+    if (a.type === 'list' && b.type === 'list') {
+        if (a.element === undefined && b.element === undefined)
+            return true;
+        if (a.element === undefined || b.element === undefined)
+            return false;
+        return structuralTypeEquals(a.element, b.element);
+    }
+    if (a.type === 'dict' && b.type === 'dict') {
+        if (a.fields === undefined && b.fields === undefined)
+            return true;
+        if (a.fields === undefined || b.fields === undefined)
+            return false;
+        const aKeys = Object.keys(a.fields).sort();
+        const bKeys = Object.keys(b.fields).sort();
+        if (aKeys.length !== bKeys.length)
+            return false;
+        for (let i = 0; i < aKeys.length; i++) {
+            const key = aKeys[i];
+            if (key !== bKeys[i])
+                return false;
+            const aField = a.fields[key];
+            const bField = b.fields[key];
+            if (!structuralTypeEquals(aField, bField))
+                return false;
+        }
+        return true;
+    }
+    if (a.type === 'tuple' && b.type === 'tuple') {
+        if (a.elements === undefined && b.elements === undefined)
+            return true;
+        if (a.elements === undefined || b.elements === undefined)
+            return false;
+        if (a.elements.length !== b.elements.length)
+            return false;
+        for (let i = 0; i < a.elements.length; i++) {
+            if (!structuralTypeEquals(a.elements[i], b.elements[i]))
+                return false;
+        }
+        return true;
+    }
+    if (a.type === 'ordered' && b.type === 'ordered') {
+        if (a.fields === undefined && b.fields === undefined)
+            return true;
+        if (a.fields === undefined || b.fields === undefined)
+            return false;
+        if (a.fields.length !== b.fields.length)
+            return false;
+        for (let i = 0; i < a.fields.length; i++) {
+            const aField = a.fields[i];
+            const bField = b.fields[i];
+            if (aField[0] !== bField[0])
+                return false;
+            if (!structuralTypeEquals(aField[1], bField[1]))
+                return false;
+        }
+        return true;
+    }
+    if (a.type === 'closure' && b.type === 'closure') {
+        if (a.params === undefined && b.params === undefined) {
+            // Both absent: compare ret
+        }
+        else if (a.params === undefined || b.params === undefined) {
+            return false;
+        }
+        else {
+            if (a.params.length !== b.params.length)
+                return false;
+            for (let i = 0; i < a.params.length; i++) {
+                const aParam = a.params[i];
+                const bParam = b.params[i];
+                if (aParam[0] !== bParam[0])
+                    return false;
+                if (!structuralTypeEquals(aParam[1], bParam[1]))
+                    return false;
+            }
+        }
+        if (a.ret === undefined && b.ret === undefined)
+            return true;
+        if (a.ret === undefined || b.ret === undefined)
+            return false;
+        return structuralTypeEquals(a.ret, b.ret);
+    }
+    return false;
+}
+/** Infer the structural type descriptor for any Rill value. */
+export function inferStructuralType(value) {
+    if (value === null || typeof value === 'string') {
+        return { type: 'string' };
+    }
+    if (typeof value === 'number') {
+        return { type: 'number' };
+    }
+    if (typeof value === 'boolean') {
+        return { type: 'bool' };
+    }
+    if (isTypeValue(value)) {
+        return { type: 'type' };
+    }
+    if (Array.isArray(value)) {
+        return { type: 'list', element: inferElementType(value) };
+    }
+    if (isTuple(value)) {
+        return {
+            type: 'tuple',
+            elements: value.entries.map(inferStructuralType),
+        };
+    }
+    if (isOrdered(value)) {
+        return {
+            type: 'ordered',
+            fields: value.entries.map(([k, v]) => [k, inferStructuralType(v)]),
+        };
+    }
+    if (isVector(value)) {
+        return { type: 'vector' };
+    }
+    if (isCallable(value)) {
+        if (isScriptCallable(value)) {
+            const params = value.params.map((p) => [
+                p.name,
+                p.typeName !== null
+                    ? { type: p.typeName }
+                    : { type: 'any' },
+            ]);
+            let ret = { type: 'any' };
+            if (isTypeValue(value.returnShape)) {
+                ret = value.returnShape.structure;
+            }
+            return { type: 'closure', params, ret };
+        }
+        // Non-script callables have no annotations
+        return { type: 'closure', params: [], ret: { type: 'any' } };
+    }
+    if (typeof value === 'object') {
+        const dict = value;
+        const fields = {};
+        for (const [k, v] of Object.entries(dict)) {
+            fields[k] = inferStructuralType(v);
+        }
+        return { type: 'dict', fields };
+    }
+    throw new RuntimeError('RILL-R004', `Cannot infer structural type for ${formatValue(value)}`);
+}
+/**
+ * Check if a value matches a structural type descriptor.
+ * Used for runtime type checking (`:?` operator).
+ */
+export function structuralTypeMatches(value, type) {
+    if (typeof value === 'undefined') {
+        throw new RuntimeError('RILL-R004', 'Cannot type-check non-value');
+    }
+    if (type.type === 'any')
+        return true;
+    // Leaf primitive variants: match by inferred type name
+    if (type.type === 'number' ||
+        type.type === 'string' ||
+        type.type === 'bool' ||
+        type.type === 'vector' ||
+        type.type === 'type') {
+        return inferType(value) === type.type;
+    }
+    if (type.type === 'list') {
+        if (!Array.isArray(value))
+            return false;
+        // Absent element sub-field: matches any list value
+        if (type.element === undefined)
+            return true;
+        if (type.element.type === 'any')
+            return true;
+        return value.every((elem) => structuralTypeMatches(elem, type.element));
+    }
+    if (type.type === 'dict') {
+        if (!isDict(value))
+            return false;
+        // Absent fields sub-field: matches any dict value
+        if (type.fields === undefined)
+            return true;
+        const dictKeys = Object.keys(type.fields);
+        // Empty fields object matches any dict
+        if (dictKeys.length === 0)
+            return true;
+        const dict = value;
+        for (const key of dictKeys) {
+            if (!(key in dict))
+                return false;
+            if (!structuralTypeMatches(dict[key], type.fields[key]))
+                return false;
+        }
+        return true;
+    }
+    if (type.type === 'tuple') {
+        if (!isTuple(value))
+            return false;
+        // Absent elements sub-field: matches any tuple value
+        if (type.elements === undefined)
+            return true;
+        if (type.elements.length === 0)
+            return value.entries.length === 0;
+        if (value.entries.length !== type.elements.length)
+            return false;
+        for (let i = 0; i < type.elements.length; i++) {
+            if (!structuralTypeMatches(value.entries[i], type.elements[i]))
+                return false;
+        }
+        return true;
+    }
+    if (type.type === 'ordered') {
+        if (!isOrdered(value))
+            return false;
+        // Absent fields sub-field: matches any ordered value
+        if (type.fields === undefined)
+            return true;
+        if (type.fields.length === 0)
+            return value.entries.length === 0;
+        if (value.entries.length !== type.fields.length)
+            return false;
+        for (let i = 0; i < type.fields.length; i++) {
+            const [expectedName, expectedType] = type.fields[i];
+            const [actualName, actualValue] = value.entries[i];
+            if (actualName !== expectedName)
+                return false;
+            if (!structuralTypeMatches(actualValue, expectedType))
+                return false;
+        }
+        return true;
+    }
+    if (type.type === 'closure') {
+        if (!isCallable(value))
+            return false;
+        // Absent params sub-field: matches any closure value of that compound type
+        if (type.params === undefined)
+            return true;
+        if (!isScriptCallable(value)) {
+            // Non-script callables: match if type has no param constraints
+            return (type.params.every((_, i) => type.params[i][1].type === 'any') &&
+                (type.ret === undefined || type.ret.type === 'any'));
+        }
+        if (value.params.length !== type.params.length)
+            return false;
+        for (let i = 0; i < type.params.length; i++) {
+            const [expectedName, expectedType] = type.params[i];
+            const param = value.params[i];
+            if (param.name !== expectedName)
+                return false;
+            const paramType = param.typeStructure !== undefined
+                ? param.typeStructure
+                : param.typeName !== null
+                    ? { type: param.typeName }
+                    : { type: 'any' };
+            if (!structuralTypeEquals(paramType, expectedType))
+                return false;
+        }
+        let retType = { type: 'any' };
+        if (isTypeValue(value.returnShape)) {
+            retType = value.returnShape.structure;
+        }
+        if (type.ret === undefined)
+            return true;
+        return structuralTypeEquals(retType, type.ret);
+    }
+    return false;
+}
+/** Format a structural type descriptor as a human-readable string. */
+export function formatStructuralType(type) {
+    if (type.type === 'any' ||
+        type.type === 'number' ||
+        type.type === 'string' ||
+        type.type === 'bool' ||
+        type.type === 'vector' ||
+        type.type === 'type') {
+        return type.type;
+    }
+    if (type.type === 'list') {
+        if (type.element === undefined)
+            return 'list';
+        return `list(${formatStructuralType(type.element)})`;
+    }
+    if (type.type === 'dict') {
+        if (type.fields === undefined)
+            return 'dict';
+        const parts = Object.keys(type.fields)
+            .sort()
+            .map((k) => `${k}: ${formatStructuralType(type.fields[k])}`);
+        return `dict(${parts.join(', ')})`;
+    }
+    if (type.type === 'tuple') {
+        if (type.elements === undefined)
+            return 'tuple';
+        const parts = type.elements.map(formatStructuralType);
+        return `tuple(${parts.join(', ')})`;
+    }
+    if (type.type === 'ordered') {
+        if (type.fields === undefined)
+            return 'ordered';
+        const parts = type.fields.map(([k, t]) => `${k}: ${formatStructuralType(t)}`);
+        return `ordered(${parts.join(', ')})`;
+    }
+    if (type.type === 'closure') {
+        if (type.params === undefined)
+            return 'closure';
+        const params = type.params
+            .map(([name, t]) => `${name}: ${formatStructuralType(t)}`)
+            .join(', ');
+        const ret = type.ret !== undefined ? formatStructuralType(type.ret) : 'any';
+        return `|${params}| :${ret}`;
+    }
+    return 'any';
+}
 /**
  * Check if a value is of the expected type.
  * Returns true if the value matches the expected type, false otherwise.
@@ -91,7 +441,9 @@ export function isTruthy(value) {
     if (typeof value === 'string')
         return value.length > 0;
     if (isTuple(value))
-        return value.entries.size > 0;
+        return value.entries.length > 0;
+    if (isOrdered(value))
+        return value.entries.length > 0;
     if (isVector(value))
         return true; // Vectors always truthy (non-empty by construction)
     if (Array.isArray(value))
@@ -110,40 +462,140 @@ export function isEmpty(value) {
 /** Format a value for display */
 export function formatValue(value) {
     if (value === null)
-        return '';
+        return 'type(null)';
     if (typeof value === 'string')
         return value;
     if (typeof value === 'number')
         return String(value);
     if (typeof value === 'boolean')
         return value ? 'true' : 'false';
+    if (isCallable(value)) {
+        return 'type(closure)';
+    }
     if (isTuple(value)) {
-        const parts = [];
-        for (const [key, val] of value.entries) {
-            if (typeof key === 'number') {
-                parts.push(formatValue(val));
-            }
-            else {
-                parts.push(`${key}: ${formatValue(val)}`);
-            }
-        }
-        return `*[${parts.join(', ')}]`;
+        return `tuple[${value.entries.map(formatValue).join(', ')}]`;
+    }
+    if (isOrdered(value)) {
+        const parts = value.entries.map(([k, v]) => `${k}: ${formatValue(v)}`);
+        return `ordered[${parts.join(', ')}]`;
+    }
+    if (isRillIterator(value)) {
+        return 'type(iterator)';
+    }
+    if (Array.isArray(value)) {
+        return `list[${value.map(formatValue).join(', ')}]`;
     }
     if (isVector(value)) {
         return `vector(${value.model}, ${value.data.length}d)`;
     }
+    if (isTypeValue(value)) {
+        return formatStructuralType(value.structure);
+    }
+    // Plain dict
+    if (typeof value === 'object') {
+        const dict = value;
+        const parts = Object.entries(dict).map(([k, v]) => `${k}: ${formatValue(v)}`);
+        return `dict[${parts.join(', ')}]`;
+    }
+    return String(value);
+}
+/**
+ * Convert a RillValue to a JSON-serializable value.
+ * @throws {Error} plain Error (not RuntimeError) for non-serializable types
+ */
+export function valueToJSON(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value)) {
+        return value.map(valueToJSON);
+    }
+    if (isCallable(value)) {
+        throw new Error('closures are not JSON-serializable');
+    }
+    if (isTuple(value)) {
+        throw new Error('tuples are not JSON-serializable');
+    }
+    if (isOrdered(value)) {
+        throw new Error('ordered values are not JSON-serializable');
+    }
+    if (isVector(value)) {
+        throw new Error('vectors are not JSON-serializable');
+    }
+    if (isTypeValue(value)) {
+        throw new Error('type values are not JSON-serializable');
+    }
     if (isRillIterator(value)) {
-        return '[iterator]';
+        throw new Error('iterators are not JSON-serializable');
     }
-    if (typeof value === 'object' &&
-        '__type' in value &&
-        value.__type === 'callable') {
-        // Basic callable formatting - full formatting in callable.ts
-        return '(...) { ... }';
+    // Plain dict
+    const dict = value;
+    const result = {};
+    for (const [k, v] of Object.entries(dict)) {
+        result[k] = valueToJSON(v);
     }
-    if (Array.isArray(value))
-        return JSON.stringify(value);
-    return JSON.stringify(value);
+    return result;
+}
+/**
+ * Convert a RillValue to a NativeResult for host consumption.
+ * Non-representable types (closures, vectors, type values, iterators) produce descriptor objects.
+ * Tuples convert to native arrays. Ordered values convert to plain objects.
+ */
+export function toNative(value) {
+    const rillTypeName = inferType(value);
+    const rillTypeSignature = formatStructuralType(inferStructuralType(value));
+    const nativeValue = toNativeValue(value);
+    return { rillTypeName, rillTypeSignature, value: nativeValue };
+}
+function toNativeValue(value) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value)) {
+        return value.map(toNativeValue);
+    }
+    if (isCallable(value)) {
+        return { signature: formatStructuralType(inferStructuralType(value)) };
+    }
+    if (isTuple(value)) {
+        return value.entries.map(toNativeValue);
+    }
+    if (isOrdered(value)) {
+        const result = {};
+        for (const [k, v] of value.entries) {
+            result[k] = toNativeValue(v);
+        }
+        return result;
+    }
+    if (isVector(value)) {
+        return { model: value.model, dimensions: value.data.length };
+    }
+    if (isTypeValue(value)) {
+        return {
+            name: value.typeName,
+            signature: formatStructuralType(value.structure),
+        };
+    }
+    if (isRillIterator(value)) {
+        return { done: value.done };
+    }
+    // Plain dict
+    const dict = value;
+    const result = {};
+    for (const [k, v] of Object.entries(dict)) {
+        result[k] = toNativeValue(v);
+    }
+    return result;
 }
 /**
  * Deep structural equality for all Rill values.
@@ -165,17 +617,43 @@ export function deepEquals(a, b) {
     // Both are non-null objects at this point
     const aObj = a;
     const bObj = b;
-    // Check for tuples (spread args)
+    // Check for tuples (positional spread args)
     const aIsTuple = isTuple(a);
     const bIsTuple = isTuple(b);
     if (aIsTuple !== bIsTuple)
         return false;
     if (aIsTuple && bIsTuple) {
-        if (a.entries.size !== b.entries.size)
+        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;
+    }
+    // Check for ordered (named spread args)
+    const aIsOrdered = isOrdered(a);
+    const bIsOrdered = isOrdered(b);
+    if (aIsOrdered !== bIsOrdered)
+        return false;
+    if (aIsOrdered && bIsOrdered) {
+        if (a.entries.length !== b.entries.length)
             return false;
-        for (const [key, aVal] of a.entries) {
-            const bVal = b.entries.get(key);
-            if (bVal === undefined || !deepEquals(aVal, bVal))
+        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;
@@ -199,6 +677,14 @@ export function deepEquals(a, b) {
         }
         return true;
     }
+    // Check for type values (first-class type names)
+    const aIsTypeValue = isTypeValue(a);
+    const bIsTypeValue = isTypeValue(b);
+    if (aIsTypeValue !== bIsTypeValue)
+        return false;
+    if (aIsTypeValue && bIsTypeValue) {
+        return structuralTypeEquals(a.structure, b.structure);
+    }
     // Check for arrays (lists)
     const aIsArray = Array.isArray(a);
     const bIsArray = Array.isArray(b);