Solid Hooks

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

// Create and start the system
const system = createSystem({ module: myModule });
system.start();

// Pass `system` to hooks in any component – no provider needed

useFact<T>(system: System, factKey: string): Accessor<T | undefined>
useFact<T extends Record<string, unknown>>(system: System, factKeys: string[]): Accessor<T>

import { useFact } from '@directive-run/solid';

function Counter() {
  // Subscribe to a single fact value
  const count = useFact(system, 'count');

  return <p>Count: {count()}</p>;
}

function Status() {
  // Subscribe to multiple facts at once
  const state = useFact(system, ['count', 'phase']);

  return <p>{state().count} – {state().phase}</p>;
}

useDerived<T>(system: System, derivationId: string): Accessor<T>
useDerived<T extends Record<string, unknown>>(system: System, derivationIds: string[]): Accessor<T>

import { useDerived } from '@directive-run/solid';

function CartTotal() {
  // Subscribe to a single derivation
  const total = useDerived(system, 'cartTotal');

  return <p>Total: ${total()}</p>;
}

function Stats() {
  // Subscribe to multiple derivations at once
  const stats = useDerived(system, ['isRed', 'elapsed']);

  return <p>{stats().isRed ? `Red for ${stats().elapsed}s` : 'Not red'}</p>;
}

useSelector<R>(system: System, selector: (state: Record<string, unknown>) => R, equalityFn?: (a: R, b: R) => boolean): Accessor<R>

import { useSelector } from '@directive-run/solid';

function Summary() {
  // Select and combine values from multiple facts
  const summary = useSelector(system, (state) => ({
    userName: state.user?.name,
    itemCount: state.items?.length ?? 0,
  }));

  return <p>{summary().userName} has {summary().itemCount} items</p>;
}

useEvents<M extends ModuleSchema>(system: System<M>): System<M>["events"]

import { useEvents } from '@directive-run/solid';

function Controls() {
  // Get typed event dispatchers for the module
  const events = useEvents(system);

  return <button onClick={() => events.increment()}>+1</button>;
}

useDispatch<M extends ModuleSchema>(system: System<M>): (event: InferEvents<M>) => void

import { useDispatch } from '@directive-run/solid';

function IncrementButton() {
  // Get the low-level dispatch function
  const dispatch = useDispatch(system);

  return (
    <button onClick={() => dispatch({ type: 'increment' })}>
      Increment
    </button>
  );
}

useWatch<T>(system: System, key: string, callback: (newValue: T, previousValue: T | undefined) => void): void

// Deprecated: "fact" discriminator overload (still works)
useWatch<T>(system: System, kind: "fact", factKey: string, callback: (newValue: T | undefined, previousValue: T | undefined) => void): void

import { useWatch } from '@directive-run/solid';

function Analytics() {
  // Watch a derivation – auto-detected
  useWatch(system, 'pageViews', (newValue, prevValue) => {
    analytics.track('pageViews', { from: prevValue, to: newValue });
  });

  // Watch a fact – auto-detected, no "fact" discriminator needed
  useWatch(system, 'count', (next, prev) => {
    console.log(`count changed: ${prev} → ${next}`);
  });

  return null;
}

useInspect(system: System, options?: { throttleMs?: number }): Accessor<InspectState>

import { useInspect } from '@directive-run/solid';

function DebugPanel() {
  // Get reactive system inspection data
  const inspection = useInspect(system);

  return (
    <pre>
      Unmet: {inspection().unmet.length}
      Inflight: {inspection().inflight.length}
    </pre>
  );
}

function ThrottledDebug() {
  // Throttle inspection updates to limit render frequency
  const inspection = useInspect(system, { throttleMs: 200 });

  return <p>Settled: {String(inspection().isSettled)}</p>;
}

useConstraintStatus(system: System): Accessor<ConstraintInfo[]>
useConstraintStatus(system: System, constraintId: string): Accessor<ConstraintInfo | null>

import { useConstraintStatus } from '@directive-run/solid';

function ConstraintList() {
  // Get all constraints for the debug panel
  const constraints = useConstraintStatus(system);

  return (
    <ul>
      <For each={constraints()}>{(c) =>
        <li>{c.id}: {c.active ? 'met' : 'unmet'}</li>
      }</For>
    </ul>
  );
}

function TransitionStatus() {
  // Check a specific constraint by ID
  const constraint = useConstraintStatus(system, 'transition');

  return <p>{constraint()?.active ? 'Ready' : 'Waiting'}</p>;
}

useExplain(system: System, requirementId: string): Accessor<string | null>

import { useExplain } from '@directive-run/solid';

function WhyPanel() {
  // Get a detailed explanation of why a requirement was generated
  const explanation = useExplain(system, 'FETCH_USER');

  return <p>{explanation() ?? 'No explanation available'}</p>;
}

useRequirementStatus(statusPlugin: StatusPlugin, type: string): Accessor<RequirementTypeStatus>
useRequirementStatus(statusPlugin: StatusPlugin, types: string[]): Accessor<Record<string, RequirementTypeStatus>>

import { useRequirementStatus } from '@directive-run/solid';

function UserLoader() {
  // Track the loading state of a specific requirement type
  const status = useRequirementStatus(statusPlugin, 'FETCH_USER');

  return (
    <Switch>
      <Match when={status().isLoading}><Spinner /></Match>
      <Match when={status().hasError}><Error message={status().lastError?.message} /></Match>
      <Match when={true}><UserContent /></Match>
    </Switch>
  );
}

function MultiStatus() {
  // Track multiple requirement types at once
  const statuses = useRequirementStatus(statusPlugin, ['FETCH_USER', 'FETCH_POSTS']);

  return <p>User loading: {String(statuses()['FETCH_USER'].isLoading)}</p>;
}

useSuspenseRequirement(statusPlugin: StatusPlugin, type: string): Accessor<RequirementTypeStatus>
useSuspenseRequirement(statusPlugin: StatusPlugin, types: string[]): Accessor<Record<string, RequirementTypeStatus>>

import { useSuspenseRequirement } from '@directive-run/solid';
import { Suspense } from 'solid-js';

function UserProfile() {
  // Suspends rendering until the requirement resolves
  const status = useSuspenseRequirement(statusPlugin, 'FETCH_USER');

  return <div>User loaded!</div>;
}

function App() {
  return (
    // Show a fallback while the requirement is being resolved
    <Suspense fallback={<Spinner />}>
      <UserProfile />
    </Suspense>
  );
}

useOptimisticUpdate(system: System, statusPlugin?: StatusPlugin, requirementType?: string): {
  mutate: (updateFn: () => void) => void;
  isPending: Accessor<boolean>;
  error: Accessor<Error | null>;
  rollback: () => void;
}

import { useOptimisticUpdate } from '@directive-run/solid';

function LikeButton() {
  // Set up optimistic mutations with automatic rollback
  const { mutate, isPending } = useOptimisticUpdate(system, statusPlugin, 'LIKE_POST');

  const handleLike = () => {
    // Optimistically update the UI before the server responds
    mutate(() => { system.facts.likes = (system.facts.likes ?? 0) + 1; });
  };

  return (
    <button onClick={handleLike} disabled={isPending()}>
      {isPending() ? 'Saving...' : 'Like'}
    </button>
  );
}

useDirective<M extends ModuleSchema>(moduleDef: ModuleDef<M>, config?: {
  facts?: string[];
  derived?: string[];
  plugins?: Plugin[];
  debug?: DebugConfig;
  errorBoundary?: ErrorBoundaryConfig;
  tickMs?: number;
  zeroConfig?: boolean;
  initialFacts?: Record<string, any>;
  status?: boolean;
}): {
  system: System<M>;
  facts: Accessor<InferFacts<M>>;
  derived: Accessor<InferDerivations<M>>;
  events: System<M>["events"];
  dispatch: (event: InferEvents<M>) => void;
  statusPlugin?: StatusPlugin;
}

import { useDirective } from '@directive-run/solid';

// Subscribe all: omit keys for everything
function Counter() {
  const { facts, events } = useDirective(counterModule);

  return (
    <div>
      <p>{facts().count}</p>
      <button onClick={() => events.increment()}>+</button>
    </div>
  );
}

// Selective: subscribe to specific keys only
function CounterSelective() {
  const { facts, derived, dispatch } = useDirective(counterModule, {
    facts: ['count'],
    derived: ['doubled'],
  });

  return <p>{facts().count} (doubled: {derived().doubled})</p>;
}

createTypedHooks<M extends ModuleSchema>(): {
  useDerived: <K extends keyof InferDerivations<M>>(system: System<M>, derivationId: K) => Accessor<InferDerivations<M>[K]>;
  useFact: <K extends keyof InferFacts<M>>(system: System<M>, factKey: K) => Accessor<InferFacts<M>[K] | undefined>;
  useDispatch: (system: System<M>) => (event: InferEvents<M>) => void;
  useEvents: (system: System<M>) => System<M>["events"];
}

import { createTypedHooks } from '@directive-run/solid';
import type { MySchema } from './schema';

// Create typed hooks – full autocomplete for fact keys and event types
const { useFact, useDerived, useDispatch } = createTypedHooks<MySchema>();

function Counter() {
  // Fully typed – fact key autocompletes, return type inferred
  const count = useFact(system, 'count');

  return <p>{count()}</p>;
}

createDerivedSignal<T>(system: System<any>, derivationId: string): [Accessor<T>, () => void]

import { createDerivedSignal } from '@directive-run/solid';

// Create a derivation signal outside of components
const [total, unsub] = createDerivedSignal<number>(system, 'cartTotal');
// total() returns the current value
// unsub() cleans up the subscription

createFactSignal<T>(system: System<any>, factKey: string): [Accessor<T | undefined>, () => void]

import { createFactSignal } from '@directive-run/solid';

// Create a fact signal outside of components
const [count, unsub] = createFactSignal<number>(system, 'count');
// count() returns the current value
// unsub() cleans up the subscription

useTimeTravel(system: System): Accessor<TimeTravelState | null>

interface TimeTravelState {
  canUndo: boolean;
  canRedo: boolean;
  undo: () => void;
  redo: () => void;
  currentIndex: number;
  totalSnapshots: number;
}

import { useTimeTravel } from '@directive-run/solid';

function UndoControls() {
  // Get reactive time-travel controls (null when disabled)
  const tt = useTimeTravel(system);

  return (
    <Show when={tt()}>
      {(state) => (
        <div>
          <button onClick={() => state().undo()} disabled={!state().canUndo}>Undo</button>
          <button onClick={() => state().redo()} disabled={!state().canRedo}>Redo</button>
          <span>{state().currentIndex + 1} / {state().totalSnapshots}</span>
        </div>
      )}
    </Show>
  );
}

shallowEqual(a: unknown, b: unknown): boolean

import { useSelector, shallowEqual } from '@directive-run/solid';

function UserInfo() {
  // Use shallowEqual to prevent updates when name/age haven't changed
  const info = useSelector(system, (state) => ({ name: state.user?.name, age: state.user?.age }), shallowEqual);

  return <p>{info().name}, {info().age}</p>;
}