@rcrsr/rill 0.17.0 → 0.18.0

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

@@ -0,0 +1,42 @@
+/**
+ * Type Guards
+ *
+ * Centralized type guard functions for all Rill value types.
+ * Extracted from values.ts and callable.ts to break the circular
+ * dependency between those modules.
+ *
+ * Import constraints:
+ * - Imports ONLY from ./markers.js and ./structures.js
+ * - No imports from values.ts or callable.ts
+ */
+import type { CallableMarker } from './markers.js';
+import type { RillIterator, RillOrdered, RillStream, RillTuple, RillTypeValue, RillValue, RillVector } from './structures.js';
+/** Type guard for RillTuple (spread args) */
+export declare function isTuple(value: RillValue): value is RillTuple;
+/** Type guard for RillVector */
+export declare function isVector(value: RillValue): value is RillVector;
+/** Type guard for RillOrdered (named spread args) */
+export declare function isOrdered(value: RillValue): value is RillOrdered;
+/** Type guard for RillTypeValue */
+export declare function isTypeValue(value: RillValue): value is RillTypeValue;
+/** Type guard for any callable */
+export declare function isCallable(value: RillValue): value is CallableMarker;
+/** Type guard for dict (plain object, not array, not callable, not tuple) */
+export declare function isDict(value: RillValue): value is Record<string, RillValue>;
+/**
+ * Type guard for RillStream (async lazy sequence with resolution).
+ * A stream has the __rill_stream discriminator set to true.
+ * Must precede isIterator in dispatch order because streams
+ * satisfy the iterator structural shape.
+ */
+export declare function isStream(value: RillValue): value is RillStream;
+/** Public API alias for isStream */
+export declare const isRillStream: (value: RillValue) => value is RillStream;
+/**
+ * Type guard for Rill iterator (lazy sequence).
+ * An iterator is a dict with:
+ * - done: boolean - whether iteration is complete
+ * - next: callable - function to get next iterator
+ * - value: any (only required when not done) - current element
+ */
+export declare function isIterator(value: RillValue): value is RillIterator;

package/dist/runtime/core/types/guards.js

@@ -0,0 +1,88 @@
+/**
+ * Type Guards
+ *
+ * Centralized type guard functions for all Rill value types.
+ * Extracted from values.ts and callable.ts to break the circular
+ * dependency between those modules.
+ *
+ * Import constraints:
+ * - Imports ONLY from ./markers.js and ./structures.js
+ * - No imports from values.ts or callable.ts
+ */
+/** Type guard for RillTuple (spread args) */
+export function isTuple(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_tuple' in value &&
+        value.__rill_tuple === true);
+}
+/** Type guard for RillVector */
+export function isVector(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_vector' in value &&
+        value.__rill_vector === true);
+}
+/** 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);
+}
+/** Type guard for RillTypeValue */
+export function isTypeValue(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_type' in value &&
+        value.__rill_type === true);
+}
+/** Type guard for any callable */
+export function isCallable(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__type' in value &&
+        value.__type === 'callable');
+}
+/** Type guard for dict (plain object, not array, not callable, not tuple) */
+export function isDict(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !isCallable(value) &&
+        !isTuple(value));
+}
+/**
+ * Type guard for RillStream (async lazy sequence with resolution).
+ * A stream has the __rill_stream discriminator set to true.
+ * Must precede isIterator in dispatch order because streams
+ * satisfy the iterator structural shape.
+ */
+export function isStream(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__rill_stream' in value &&
+        value.__rill_stream === true);
+}
+/** Public API alias for isStream */
+export const isRillStream = isStream;
+/**
+ * Type guard for Rill iterator (lazy sequence).
+ * An iterator is a dict with:
+ * - done: boolean - whether iteration is complete
+ * - next: callable - function to get next iterator
+ * - value: any (only required when not done) - current element
+ */
+export function isIterator(value) {
+    if (!isDict(value))
+        return false;
+    const dict = value;
+    if (!('done' in dict && typeof dict['done'] === 'boolean'))
+        return false;
+    if (!('next' in dict && isCallable(dict['next'])))
+        return false;
+    // 'value' field only required when not done
+    if (!dict['done'] && !('value' in dict))
+        return false;
+    return true;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Types Module Barrel
+ *
+ * Re-exports all public symbols from the types/ sub-modules.
+ * Internal runtime code may import sub-modules directly;
+ * this barrel provides a single import path for runtime/index.ts
+ * and other consumers.
+ */
+export type { RillFieldDef, RillIterator, RillOrdered, RillStream, RillTuple, RillTypeValue, RillValue, RillVector, TypeStructure, } from './structures.js';
+export type { CallableMarker, FieldDescriptorMarker } from './markers.js';
+export { isCallable, isDict, isIterator, isOrdered, isRillStream, isStream, isTuple, isTypeValue, isVector, } from './guards.js';
+export { copyValue, createOrdered, createRillStream, createTuple, createVector, emptyForType, } from './constructors.js';
+export type { DictStructure, FieldComparisonCallbacks, OrderedStructure, TupleStructure, } from './operations.js';
+export { commonType, compareStructuredFields, formatRillLiteral, formatStructure, inferElementType, inferStructure, paramToFieldDef, structureEquals, structureMatches, } from './operations.js';
+export type { TypeDefinition, TypeProtocol } from './registrations.js';
+export { BUILT_IN_TYPES, deepEquals, deserializeValue, formatValue, inferType, populateBuiltinMethods, serializeValue, } from './registrations.js';
+export type { CaptureEvent, ErrorEvent, ExecutionResult, ExecutionStepper, ExtensionEvent, FunctionReturnEvent, HostCallEvent, NativeArray, NativePlainObject, NativeValue, ObservabilityCallbacks, ResolverResult, RuntimeCallbacks, RuntimeContext, RuntimeOptions, SchemeResolver, StepEndEvent, StepResult, StepStartEvent, } from './runtime.js';
+export { bindDictCallables } from './runtime.js';

package/dist/runtime/core/types/index.js

@@ -0,0 +1,19 @@
+/**
+ * Types Module Barrel
+ *
+ * Re-exports all public symbols from the types/ sub-modules.
+ * Internal runtime code may import sub-modules directly;
+ * this barrel provides a single import path for runtime/index.ts
+ * and other consumers.
+ */
+// ============================================================
+// GUARDS (type guard functions for all Rill value types)
+// ============================================================
+export { isCallable, isDict, isIterator, isOrdered, isRillStream, isStream, isTuple, isTypeValue, isVector, } from './guards.js';
+// ============================================================
+// CONSTRUCTORS (factory functions for compound values)
+// ============================================================
+export { copyValue, createOrdered, createRillStream, createTuple, createVector, emptyForType, } from './constructors.js';
+export { commonType, compareStructuredFields, formatRillLiteral, formatStructure, inferElementType, inferStructure, paramToFieldDef, structureEquals, structureMatches, } from './operations.js';
+export { BUILT_IN_TYPES, deepEquals, deserializeValue, formatValue, inferType, populateBuiltinMethods, serializeValue, } from './registrations.js';
+export { bindDictCallables } from './runtime.js';

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

@@ -0,0 +1,98 @@
+/**
+ * Type Structure Operations
+ *
+ * Structural comparison, matching, inference, and formatting functions
+ * extracted from values.ts. Provides `compareStructuredFields()` to
+ * deduplicate dict/tuple/ordered dispatch across structureEquals,
+ * structureMatches, and formatStructure.
+ *
+ * Import constraints:
+ * - Imports from ./structures.js, ./guards.js, ./registrations.js
+ * - Circular with registrations.ts (runtime-safe: no init-time cross-calls)
+ */
+import type { RillFieldDef, RillValue, TypeStructure } from './structures.js';
+export type DictStructure = {
+    kind: 'dict';
+    fields?: Record<string, RillFieldDef>;
+    valueType?: TypeStructure;
+};
+export type TupleStructure = {
+    kind: 'tuple';
+    elements?: RillFieldDef[];
+    valueType?: TypeStructure;
+};
+export type OrderedStructure = {
+    kind: 'ordered';
+    fields?: RillFieldDef[];
+    valueType?: TypeStructure;
+};
+/**
+ * Callbacks for kind-specific field dispatch in dict/tuple/ordered types.
+ * `compareStructuredFields` handles the common valueType check and
+ * kind-based field extraction, then delegates to these callbacks.
+ */
+export interface FieldComparisonCallbacks<T> {
+    /** Both structures carry a uniform valueType */
+    onValueType(aValueType: TypeStructure, bValueType: TypeStructure): T;
+    /** One structure has valueType, the other does not */
+    onValueTypeMismatch(): T;
+    /** Neither structure has fields/elements */
+    onBothEmpty(): T;
+    /** One structure has fields/elements, the other does not */
+    onFieldPresenceMismatch(): T;
+    /** Dict with keyed fields on both sides */
+    onDictFields(aFields: Record<string, RillFieldDef>, bFields: Record<string, RillFieldDef>): T;
+    /** Tuple with positional elements on both sides */
+    onTupleElements(aElements: RillFieldDef[], bElements: RillFieldDef[]): T;
+    /** Ordered with named positional fields on both sides */
+    onOrderedFields(aFields: RillFieldDef[], bFields: RillFieldDef[]): T;
+}
+/**
+ * Shared dispatch for dict/tuple/ordered field comparison.
+ * Handles valueType check and field iteration across
+ * structureEquals, structureMatches, and formatStructure.
+ *
+ * Constraints:
+ * - Dict: keyed fields, sorted key comparison
+ * - Tuple: positional elements
+ * - Ordered: named positional fields
+ * - Recurses via caller-provided callbacks
+ *
+ * Callers validate that a.kind === b.kind before calling.
+ * Invalid kind values fall through to the final return.
+ */
+export declare function compareStructuredFields<T>(a: TypeStructure, b: TypeStructure, callbacks: FieldComparisonCallbacks<T>, fallback: T): T;
+/** Format a RillValue as a rill literal for use in type signatures. */
+export declare function formatRillLiteral(value: RillValue): string;
+/** Compare two structural types for equality. */
+export declare function structureEquals(a: TypeStructure, b: TypeStructure): boolean;
+/**
+ * Check if a value matches a structural type descriptor.
+ * Used for runtime type checking (`:?` operator).
+ */
+export declare function structureMatches(value: RillValue, type: TypeStructure): boolean;
+/** Format a structural type descriptor as a human-readable string. */
+export declare function formatStructure(type: TypeStructure): string;
+/** Build a closure param field definition from name, type, and optional default. */
+export declare function paramToFieldDef(name: string, type: TypeStructure, defaultValue: RillValue | undefined): RillFieldDef;
+/**
+ * Infer the element type for a homogeneous list.
+ * Empty arrays return { kind: 'any' }.
+ * Mixed types throw RILL-R002.
+ */
+export declare function inferElementType(elements: RillValue[]): TypeStructure;
+/** Infer the structural type descriptor for any Rill value. */
+export declare function inferStructure(value: RillValue): TypeStructure;
+/**
+ * Return the most specific shared type for two TypeStructure values.
+ * Returns null when types are incompatible at the top level.
+ *
+ * Cascade priority:
+ * 1. Any-narrowing: if either side is `any`, return the other
+ * 2. Structural match: delegate to structureEquals; on true, return a
+ * 3. Recursive list: merge inner element types
+ * 3b. Uniform valueType: merge dict/tuple/ordered value types
+ * 4. Bare type fallback: same compound type but structural mismatch
+ * 5. Incompatible: different top-level types return null
+ */
+export declare function commonType(a: TypeStructure, b: TypeStructure): TypeStructure | null;