Core API Reference

// Define a module's schema, constraints, resolvers, and effects
function createModule<M extends ModuleSchema>(
  name: string,       // unique identifier for this module
  config: ModuleConfig<M>
): ModuleDef<M>

function createModuleFactory<M extends ModuleSchema>(
  config: ModuleConfig<M>
): (name: string) => ModuleDef<M>

const chatRoom = createModuleFactory({
  schema: { facts: { messages: t.array<string>() } },
  init: (facts) => { facts.messages = []; },
});

const system = createSystem({
  modules: {
    lobby: chatRoom("lobby"),
    support: chatRoom("support"),
  },
});

// Create a live runtime from a module definition
function createSystem<M extends ModuleSchema>(
  config: SystemConfig<M>
): SingleModuleSystem<M>

// Write a fact (triggers constraint evaluation and effects)
system.facts.count = 10;

// Read a fact (fully typed from your schema)
const count = system.facts.count;

// Read derivations (recompute automatically when tracked facts change)
const total = system.derive.cartTotal;

// Runtime registration
system.derive.register("tripled", (facts) => facts.count * 3);
system.derive.assign("doubled", (facts) => facts.count * 20);
system.derive.unregister("tripled");
system.derive.call("doubled");            // recompute, ignoring cache
system.derive.isDynamic("tripled");       // true
system.derive.listDynamic();              // ["tripled"]

system.constraints.disable("myConstraint");
system.constraints.enable("myConstraint");
system.constraints.register("newRule", { when: ..., require: ... });
system.constraints.assign("newRule", { when: ..., require: ... });
system.constraints.unregister("newRule");

system.effects.disable("myEffect");
system.effects.enable("myEffect");
system.effects.register("logger", { run: (facts) => console.log(facts) });

system.resolvers.register("loadData", { requirement: "LOAD", resolve: ... });
await system.resolvers.call("loadData", { type: "LOAD", id: "123" });

// Time-travel is only available when history is enabled
if (system.history) {
  system.history.goBack();               // undo last state change
  system.history.goForward();            // redo
  console.log(system.history.snapshots); // all captured snapshots
}

system.isRunning;      // true after start() is called
system.isSettled;      // true when all constraints and resolvers finish
system.isInitialized;  // true after module init() completes
system.isReady;        // true after the first reconciliation pass

system.start();

system.stop();

system.destroy();

system.registerModule(name: string, module: ModuleDef): void

system.getOriginal(
  type: "constraint" | "resolver" | "derivation" | "effect",
  id: string
): unknown | undefined

// After overriding a constraint with assign()
const original = system.getOriginal("constraint", "transition");

system.restoreOriginal(
  type: "constraint" | "resolver" | "derivation" | "effect",
  id: string
): boolean

// Restore a previously overridden constraint
system.restoreOriginal("constraint", "transition"); // true

// Send a typed event into the system for constraints and effects to react to
system.dispatch({ type: "EVENT_NAME", payload: data });

// Group multiple writes so constraints evaluate once (not per write)
system.batch(() => {
  system.facts.a = 1;
  system.facts.b = 2;
});

// Read a specific derivation by its string ID
const total = system.read("cartTotal");

// Subscribe to fact changes
system.subscribe(["count"], () => console.log("count changed"));

// Subscribe to derivation changes
system.subscribe(["doubled"], () => console.log("doubled changed"));

// Subscribe to mix of facts and derivations
system.subscribe(["count", "doubled"], () => console.log("something changed"));

subscribe(ids: Array<ObservableKeys<M>>, listener: () => void): () => void

// Watch a fact
system.watch("count", (newVal, oldVal) => {
  console.log(`count: ${oldVal} -> ${newVal}`);
});

// Watch a derivation
system.watch("doubled", (newVal, oldVal) => {
  console.log(`doubled: ${oldVal} -> ${newVal}`);
});

// With custom equality
system.watch("config", callback, {
  equalityFn: (a, b) => JSON.stringify(a) === JSON.stringify(b),
});

// Wait for a condition to become true
await system.when((facts) => facts.phase === "ready");

// With timeout
await system.when(
  (facts) => facts.count > 10,
  { timeout: 5000 }
);

when(predicate: (facts: Facts<M>) => boolean, options?: { timeout?: number }): Promise<void>

// Block until init + first reconciliation completes (useful in tests/SSR)
await system.whenReady();

// Wait for all in-flight constraints and resolvers to finish
await system.settle();

// See what's pending, running, and resolved at this moment
const inspection = system.inspect();
// { unmet, inflight, constraints, resolvers }

// Trace which constraint generated a requirement and why
const explanation = system.explain("requirement-id");

// Serialize current state for persistence or transfer
const snapshot = system.getSnapshot();

// Rehydrate state from a previously captured snapshot
system.restore(snapshot);

// Options
interface DistributableSnapshotOptions {
  includeDerivations?: string[];  // Which derivations to include (default: all)
  excludeDerivations?: string[];  // Derivations to exclude
  includeFacts?: string[];        // Which facts to include (default: none)
  ttlSeconds?: number;            // Snapshot TTL in seconds
  metadata?: Record<string, unknown>; // Custom metadata attached to snapshot
  includeVersion?: boolean;       // Include a version hash for diffing
}

// Export selected derivations (default behavior – safe to distribute)
const snapshot = system.getDistributableSnapshot({
  includeDerivations: ["effectivePlan", "canUseFeature"],
  ttlSeconds: 3600,
});

// Include specific facts alongside derivations
const snapshot = system.getDistributableSnapshot({
  includeDerivations: ["effectivePlan"],
  includeFacts: ["userId", "plan"],
  ttlSeconds: 3600,
});

// Export all derivations with version for cache diffing
const snapshot = system.getDistributableSnapshot({
  includeVersion: true,
  metadata: { region: "us-east-1" },
});

// Automatically push updated snapshots whenever derivations change
const unsubscribe = system.watchDistributableSnapshot(
  { includeDerivations: ["effectivePlan"] },
  (snapshot) => {
    // Push to Redis/edge cache
  }
);

function constraintFactory<S extends Schema>(): {
  create<R extends Requirement>(constraint: TypedConstraint<S, R>): TypedConstraint<S, R>
}

import { constraintFactory, t } from '@directive-run/core';

const schema = { facts: { count: t.number(), threshold: t.number() } };
const factory = constraintFactory<typeof schema>();

const maxCount = factory.create({
  when: (facts) => facts.count > facts.threshold,
  require: { type: "RESET" },
});

// Use in any module with the same schema
const module = createModule("counter", {
  schema,
  constraints: { maxCount },
});

function resolverFactory<S extends Schema>(): {
  create<R extends Requirement>(resolver: TypedResolver<S, R>): TypedResolver<S, R>
}

import { resolverFactory } from '@directive-run/core';

const factory = resolverFactory<typeof schema>();

const fetchUser = factory.create<{ type: "FETCH_USER"; userId: string }>({
  requirement: "FETCH_USER",
  resolve: async (req, context) => {
    context.facts.user = await api.getUser(req.userId);
  },
});

function typedConstraint<S extends Schema, R extends Requirement>(
  constraint: TypedConstraint<S, R>
): TypedConstraint<S, R>

import { typedConstraint } from '@directive-run/core';

const lowStock = typedConstraint<typeof schema, { type: "REORDER" }>({
  when: (facts) => facts.stock < 10,
  require: { type: "REORDER" },
  priority: 50,
});

function typedResolver<S extends Schema, R extends Requirement>(
  resolver: TypedResolver<S, R>
): TypedResolver<S, R>

import { typedResolver } from '@directive-run/core';

const resetResolver = typedResolver<typeof schema, { type: "RESET" }>({
  requirement: "RESET",
  resolve: async (_req, context) => {
    context.facts.count = 0;
  },
});