Host API Types Reference

RillFieldDef

RillFieldDef describes a single field within a compound type. All four compound collection types use RillFieldDef to represent their element or field definitions.

interface RillFieldDef {
  name?: string;
  type: TypeStructure;
  defaultValue?: RillValue;
}

See TypeStructure for field access patterns per collection type.

TypeStructure

TypeStructure is a discriminated union that describes the structural shape of any rill value. The runtime uses it for type checking, type inference, and formatting.

type TypeStructure =
  | { kind: 'number' }
  | { kind: 'string' }
  | { kind: 'bool' }
  | { kind: 'list'; elementType: TypeStructure }
  | { kind: 'dict'; valueType: TypeStructure }
  | { kind: 'tuple'; fields: RillFieldDef[] }
  | { kind: 'ordered'; fields: RillFieldDef[] }
  | { kind: 'vector'; dimensions: number }
  | { kind: 'closure' }
  | { kind: 'type'; typeName: string }
  | { kind: 'union'; types: TypeStructure[] }
  | { kind: 'stream'; chunk?: TypeStructure; ret?: TypeStructure }
  | { kind: 'any' }
  | { kind: string; data?: unknown }; // catch-all for types without parameterized structure

The kind field is the discriminator. Leaf variants (number, string, bool, closure, any) carry no sub-fields. Compound variants carry their structural sub-fields.

Field Constraints

Exports

// Structural type system
export type { TypeStructure, RillFieldDef, RillFieldDescriptor };
export {
  inferStructure,
  inferElementType,
  commonType,
  structureEquals,
  structureMatches,
  formatStructure,
  buildFieldDescriptor,
  paramsToStructuralType,
  structureToTypeValue,
  serializeValue,
  copyValue,
  deserializeValue,
  isIterator,
};

inferStructure

inferStructure(value: RillValue): TypeStructure

Returns the structural type descriptor for any rill value. Primitive values return leaf variants. Compound values return their respective variants with sub-fields populated from the value’s actual structure. Callable values return { kind: 'closure' }.

Pure function. Result is a frozen object.

inferElementType

inferElementType(elements: RillValue[]): TypeStructure

Infers the element type for a list by folding element types left-to-right using commonType. Starts with the first element’s type and folds each subsequent element’s type via commonType. When commonType returns null, throws RILL-R002.

commonType

commonType(a: TypeStructure, b: TypeStructure): TypeStructure | null

Returns the most specific shared type for two TypeStructure values. Used inside inferElementType to fold element types.

Cascade order:

Pure function, no side effects.

structureEquals

structureEquals(a: TypeStructure, b: TypeStructure): boolean

Compares two structural types for deep structural equality. Switches on the kind discriminator. Leaf variants compare by kind alone. Compound variants compare sub-fields recursively.

Pure function. Variants with different kind values always return false.

structureMatches

structureMatches(value: RillValue, type: TypeStructure): boolean

Checks if a value matches a structural type descriptor. Used by the :? runtime type check operator.

Closure parameter default compatibility:

Pure function.

formatStructure

formatStructure(type: TypeStructure): string

Formats a structural type descriptor as a human-readable string.

buildFieldDescriptor

buildFieldDescriptor(
  structuralType: TypeStructure & { kind: 'dict' },
  fieldName: string,
  location: SourceLocation
): RillFieldDescriptor

Builds a frozen RillFieldDescriptor for a named field within a structural dict type.

structuralType must narrow to { kind: 'dict' } at the call site. The field must exist in valueType or RILL-R003 is thrown.

RillFieldDescriptor

RillFieldDescriptor carries the full RillFieldDef for a specific named field. The runtime produces descriptors when evaluating field-access expressions on typed dicts.

interface RillFieldDescriptor {
  readonly __rill_field_descriptor: true;
  readonly fieldName: string;
  readonly fieldType: RillFieldDef;
}

paramsToStructuralType

paramsToStructuralType(params: RillParam[]): TypeStructure

Builds a TypeStructure closure variant from a parameter list. Return type is always { kind: 'any' }. Result is a frozen object.

structureToTypeValue

structureToTypeValue(type: TypeStructure): RillTypeValue

Converts a TypeStructure descriptor into the RillTypeValue runtime representation used in RillFunction.returnType and RillParam.type fields.

import { structureToTypeValue } from '@rcrsr/rill';

const fn: RillFunction = {
  params: [{ name: 'text', type: { kind: 'string' } }],
  fn: (args) => args.text,
  returnType: structureToTypeValue({ kind: 'string' }),
};

serializeValue

serializeValue(value: RillValue): unknown

Converts a rill value to a JSON-serializable representation. Delegates to TypeProtocol.serialize for host types when registered. Primitive and built-in compound types produce plain JS values.

deserializeValue

deserializeValue(data: unknown, typeName: string): RillValue

Restores a runtime value from serialized data. Looks up the named type’s TypeProtocol.deserialize function and applies it to data. Throws if the type is not registered or the protocol has no deserialize implementation.

copyValue

copyValue(value: RillValue): RillValue

Produces a deep copy of any rill value. Used internally for default value hydration and value isolation. Delegates to TypeProtocol for host types when registered.

isIterator

isIterator(value: RillValue): boolean

Returns true when value is a lazy rill iterator (produced by range, repeat, or similar). Use this to guard code that must not consume a sequence prematurely.

TypeDefinition

TypeDefinition is the registration contract for host-provided types. Pass instances to registerType when configuring the runtime.

interface TypeDefinition {
  name: string;
  identity: (v: RillValue) => boolean;
  isLeaf: boolean;
  immutable: boolean;
  methods: Record<string, RillFunction>;
  protocol: TypeProtocol;
}

import type { TypeDefinition, TypeProtocol } from '@rcrsr/rill';

const dateType: TypeDefinition = {
  name: 'date',
  identity: (v) => v instanceof Date,
  isLeaf: true,
  immutable: true,
  methods: {
    format: {
      params: [{ name: 'pattern', type: { kind: 'string' } }],
      fn: (args) => (args.$self as Date).toLocaleDateString(),
      returnType: structureToTypeValue({ kind: 'string' }),
    },
  },
  protocol: {
    format: (v) => (v as Date).toISOString(),
    serialize: (v) => (v as Date).toISOString(),
    deserialize: (data) => new Date(data as string),
  },
};

TypeProtocol

TypeProtocol defines behavioral contracts for a registered host type. All fields are optional except format.

interface TypeProtocol {
  format: (v: RillValue) => string;
  structure?: (v: RillValue) => TypeStructure;
  eq?: (a: RillValue, b: RillValue) => boolean;
  compare?: (a: RillValue, b: RillValue) => number;
  convertTo?: Record<string, (v: RillValue) => RillValue>;
  serialize?: (v: RillValue) => unknown;
  deserialize?: (data: unknown) => RillValue;
}

import type { TypeProtocol } from '@rcrsr/rill';

const dateProtocol: TypeProtocol = {
  format: (v) => (v as Date).toISOString(),
  eq: (a, b) => (a as Date).getTime() === (b as Date).getTime(),
  compare: (a, b) => (a as Date).getTime() - (b as Date).getTime(),
  serialize: (v) => (v as Date).toISOString(),
  deserialize: (data) => new Date(data as string),
};

See Also

• Host API Reference — Complete TypeScript API for embedding rill
• Host Integration — Embedding guide and runtime configuration
• Extensions — Reusable function packages

Migration: 0.18.0 Renamed Exports

v0.18.0 renames 7 exports in @rcrsr/rill to remove the rill-prefixed naming convention and align with the TypeStructure terminology introduced in v0.17.0. All old names are removed; update imports before upgrading.

Symbol Mapping Table

Codemod

No automated codemod is available for this rename. Use find-and-replace across your codebase for each old name. The old names do not exist in v0.18.0 — TypeScript will report errors at every import site, making all affected locations visible before runtime.