@rcrsr/rill 0.16.0 → 0.18.0

package/dist/runtime/core/types/registrations.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 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) iterate registrations and delegate to per-type
+ * protocol implementations.
+ *
+ * Registration order:
+ *   primitives -> discriminator-based -> structural -> list -> dict fallback
+ *
+ * @internal
+ */
+import type { TypeStructure, RillValue, RillFieldDef, RillTuple, RillOrdered, RillVector, RillTypeValue, RillIterator, RillStream } from './structures.js';
+import type { RillFunction } from '../callable.js';
+import { isStream, isTuple, isVector, isOrdered, isTypeValue, isIterator } from './guards.js';
+import { createTuple, createOrdered, createVector } from './constructors.js';
+/**
+ * Protocol functions that define per-type behavior.
+ * Every type must provide `format`. All other protocols are optional.
+ */
+export interface TypeProtocol {
+    format: (v: RillValue) => string;
+    structure?: ((v: RillValue) => TypeStructure) | undefined;
+    eq?: ((a: RillValue, b: RillValue) => boolean) | undefined;
+    compare?: ((a: RillValue, b: RillValue) => number) | undefined;
+    convertTo?: Record<string, (v: RillValue) => RillValue> | undefined;
+    serialize?: ((v: RillValue) => unknown) | undefined;
+    deserialize?: ((data: unknown) => RillValue) | undefined;
+}
+/**
+ * A single type registration record. Each of the 12 built-in types
+ * has exactly one TypeDefinition in the BUILT_IN_TYPES array.
+ */
+export interface TypeDefinition {
+    name: string;
+    identity: (v: RillValue) => boolean;
+    isLeaf: boolean;
+    immutable: boolean;
+    methods: Record<string, RillFunction>;
+    protocol: TypeProtocol;
+}
+/**
+ * All 13 built-in type registrations.
+ *
+ * Registration order:
+ * 1. Primitives: string, number, bool
+ * 2. Discriminator-based: tuple, ordered, vector, type, closure, field_descriptor
+ * 3. Structural: iterator, stream
+ * 4. list
+ * 5. dict (fallback, must be last)
+ *
+ * AC-1: 13 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 RuntimeError (RILL-R067).
+ */
+export declare const BUILT_IN_TYPES: readonly TypeDefinition[];
+/**
+ * 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 declare function inferType(value: RillValue): 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 declare function formatValue(value: RillValue): string;
+/**
+ * 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 declare function deepEquals(a: RillValue, b: RillValue): boolean;
+/**
+ * Serialize a Rill value for JSON transport.
+ * Dispatches to protocol.serialize; container types recurse.
+ *
+ * IR-7: Renamed from valueToJSON.
+ */
+export declare function serializeValue(value: RillValue): unknown;
+/**
+ * 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 declare function deserializeValue(data: unknown, typeName: string): RillValue;
+/**
+ * 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 declare function populateBuiltinMethods(builtinMethods: Record<string, Record<string, RillFunction>>): void;
+export { createTuple, createOrdered, createVector };
+export { isStream, isTuple, isVector, isTypeValue, isOrdered, isIterator };
+export type { TypeStructure };
+export type { RillValue, RillTuple, RillOrdered, RillVector, RillTypeValue, RillIterator, RillStream, RillFieldDef, };