@wizzard-packages/core 0.3.0 → 0.4.1-canary-20260904173354

package/dist/flow-Bmv_KegP.d.cts

@@ -0,0 +1,166 @@
+/**
+ * The expression language.
+ *
+ * A flow has to survive `JSON.stringify`, so a predicate cannot be a function.
+ * It is a small tagged object instead, evaluated by this module. There is no
+ * `eval` and no `new Function`, so a flow served by a backend is data, not code.
+ *
+ * Ten operators cover the predicates wizards actually express. Anything else —
+ * arithmetic, regular expressions, a remote lookup — goes through `$ref`, which
+ * names a function in the registry. That keeps the grammar small and makes the
+ * one dangerous thing explicit and greppable.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+type Expr = null | boolean | number | string | readonly Expr[] | {
+    $get: string;
+} | {
+    $ref: string;
+    args?: Json;
+} | {
+    $not: Expr;
+} | {
+    $and: readonly Expr[];
+} | {
+    $or: readonly Expr[];
+} | {
+    $eq: readonly [Expr, Expr];
+} | {
+    $ne: readonly [Expr, Expr];
+} | {
+    $gt: readonly [Expr, Expr];
+} | {
+    $gte: readonly [Expr, Expr];
+} | {
+    $lt: readonly [Expr, Expr];
+} | {
+    $lte: readonly [Expr, Expr];
+} | {
+    $in: readonly [Expr, Expr];
+} | {
+    $empty: Expr;
+};
+/** The roots a `$get` path may address. */
+interface Scope {
+    data: Record<string, unknown>;
+    ctx: Record<string, unknown>;
+    /** Present inside a `repeat` group. */
+    loop?: {
+        index: number;
+        item: unknown;
+    };
+}
+type Resolver = (args: Json | undefined, scope: Scope) => unknown;
+type Registry = Readonly<Record<string, Resolver>>;
+/** Thrown when a synchronous evaluation meets a `$ref` it cannot resolve. */
+declare class ExprError extends Error {
+}
+/**
+ * Evaluates synchronously. Throws `ExprError` on a `$ref` that the registry
+ * does not define, or whose resolver returns a promise.
+ *
+ * Most flows contain no `$ref` at all, so `isSync` lets the engine take this
+ * path and know which steps are reachable before the first paint.
+ */
+declare function evaluate(e: Expr, scope: Scope, registry?: Registry): unknown;
+/** Evaluates to a boolean. An absent expression is `true`. */
+declare function test(e: Expr | undefined, scope: Scope, registry?: Registry): boolean;
+/**
+ * True when the expression contains no `$ref`, and can therefore be evaluated
+ * before the first paint. Computed once per flow, not per navigation.
+ */
+declare function isSync(e: Expr | undefined): boolean;
+/**
+ * Evaluates with `$ref` allowed to be asynchronous.
+ *
+ * Used only where the engine is already awaiting — a guard, a load. Reachability
+ * takes the synchronous path when `isSync` allows it, which is the common case
+ * and the reason a flow renders correctly on the first frame.
+ */
+declare function evaluateAsync(e: Expr, scope: Scope, registry?: AsyncRegistry): Promise<unknown>;
+type AsyncResolver = (args: Json | undefined, scope: Scope) => unknown | Promise<unknown>;
+type AsyncRegistry = Readonly<Record<string, AsyncResolver>>;
+/** Evaluates to a boolean, awaiting `$ref`. An absent expression is `true`. */
+declare function testAsync(e: Expr | undefined, scope: Scope, registry?: AsyncRegistry): Promise<boolean>;
+
+/**
+ * The flow definition. Pure JSON — no functions, no class instances, nothing
+ * that `JSON.stringify` would drop. The same object can be written by hand,
+ * served by a backend, or generated; the engine cannot tell which.
+ *
+ * Everything that cannot be serialized is named instead: `view` names a
+ * component, `$ref` names a function, both looked up in a registry the host
+ * supplies.
+ */
+interface FlowDefinition {
+    id: string;
+    /** Bumped by the producer when the shape changes; used to reject stale patches. */
+    version?: number;
+    /** Default linear order. A step missing from `order` is reachable only via `on.next`. */
+    order?: readonly string[];
+    /** Keyed by id, not an array, so a patch can address one step without index maths. */
+    steps: Readonly<Record<string, StepDef>>;
+    policy?: NavigationPolicy;
+    validate?: {
+        on?: 'change' | 'blur' | 'next' | 'manual';
+        debounceMs?: number;
+    };
+}
+type NavigationPolicy = 'sequential' | 'visited' | 'free';
+type Target = string | {
+    to: string;
+    when?: Expr;
+};
+interface StepBase {
+    label?: string;
+    /** Reachability. A step whose `when` is false is skipped, not shown disabled. */
+    when?: Expr;
+    guards?: {
+        enter?: Expr;
+        exit?: Expr;
+    };
+    on?: {
+        next?: Target | readonly Target[];
+        back?: Target | 'auto';
+    };
+    /** Key of this step's slice of `data`. Defaults to the step id. */
+    slice?: string;
+    /** Field schema for the host to render. The engine never reads it. */
+    ui?: Json;
+    /** Loaded on enter, with an abort signal. */
+    load?: {
+        $ref: string;
+        args?: Json;
+    };
+    /** The body of this step arrives later, from the host. */
+    deferred?: boolean;
+}
+interface AtomStep extends StepBase {
+    view?: string;
+    validate?: {
+        $ref: string;
+        args?: Json;
+    };
+}
+/**
+ * A sub-flow. With `repeat` it is also the loop construct — the same machinery,
+ * because a loop is a sub-flow entered once per item. Iteration state lives in
+ * the runtime frame, never in the definition, so the flow stays static and
+ * diffable.
+ */
+interface GroupStep extends StepBase {
+    flow: string | FlowDefinition;
+    repeat?: {
+        over: Expr;
+        keyBy?: string;
+    };
+    /** Parent expressions piped into the child's `ctx`. */
+    input?: Readonly<Record<string, Expr>>;
+}
+type StepDef = AtomStep | GroupStep;
+declare const isGroup: (s: StepDef) => s is GroupStep;
+/** Sentinel target meaning the flow is finished. */
+declare const END: "@end";
+
+export { type AtomStep as A, END as E, type FlowDefinition as F, type GroupStep as G, type Json as J, type NavigationPolicy as N, type Registry as R, type StepDef as S, type Target as T, type AsyncRegistry as a, type Scope as b, type Expr as c, type Resolver as d, ExprError as e, evaluate as f, evaluateAsync as g, type AsyncResolver as h, isSync as i, testAsync as j, isGroup as k, test as t };

package/dist/flow-Bmv_KegP.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The expression language.
+ *
+ * A flow has to survive `JSON.stringify`, so a predicate cannot be a function.
+ * It is a small tagged object instead, evaluated by this module. There is no
+ * `eval` and no `new Function`, so a flow served by a backend is data, not code.
+ *
+ * Ten operators cover the predicates wizards actually express. Anything else —
+ * arithmetic, regular expressions, a remote lookup — goes through `$ref`, which
+ * names a function in the registry. That keeps the grammar small and makes the
+ * one dangerous thing explicit and greppable.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+type Expr = null | boolean | number | string | readonly Expr[] | {
+    $get: string;
+} | {
+    $ref: string;
+    args?: Json;
+} | {
+    $not: Expr;
+} | {
+    $and: readonly Expr[];
+} | {
+    $or: readonly Expr[];
+} | {
+    $eq: readonly [Expr, Expr];
+} | {
+    $ne: readonly [Expr, Expr];
+} | {
+    $gt: readonly [Expr, Expr];
+} | {
+    $gte: readonly [Expr, Expr];
+} | {
+    $lt: readonly [Expr, Expr];
+} | {
+    $lte: readonly [Expr, Expr];
+} | {
+    $in: readonly [Expr, Expr];
+} | {
+    $empty: Expr;
+};
+/** The roots a `$get` path may address. */
+interface Scope {
+    data: Record<string, unknown>;
+    ctx: Record<string, unknown>;
+    /** Present inside a `repeat` group. */
+    loop?: {
+        index: number;
+        item: unknown;
+    };
+}
+type Resolver = (args: Json | undefined, scope: Scope) => unknown;
+type Registry = Readonly<Record<string, Resolver>>;
+/** Thrown when a synchronous evaluation meets a `$ref` it cannot resolve. */
+declare class ExprError extends Error {
+}
+/**
+ * Evaluates synchronously. Throws `ExprError` on a `$ref` that the registry
+ * does not define, or whose resolver returns a promise.
+ *
+ * Most flows contain no `$ref` at all, so `isSync` lets the engine take this
+ * path and know which steps are reachable before the first paint.
+ */
+declare function evaluate(e: Expr, scope: Scope, registry?: Registry): unknown;
+/** Evaluates to a boolean. An absent expression is `true`. */
+declare function test(e: Expr | undefined, scope: Scope, registry?: Registry): boolean;
+/**
+ * True when the expression contains no `$ref`, and can therefore be evaluated
+ * before the first paint. Computed once per flow, not per navigation.
+ */
+declare function isSync(e: Expr | undefined): boolean;
+/**
+ * Evaluates with `$ref` allowed to be asynchronous.
+ *
+ * Used only where the engine is already awaiting — a guard, a load. Reachability
+ * takes the synchronous path when `isSync` allows it, which is the common case
+ * and the reason a flow renders correctly on the first frame.
+ */
+declare function evaluateAsync(e: Expr, scope: Scope, registry?: AsyncRegistry): Promise<unknown>;
+type AsyncResolver = (args: Json | undefined, scope: Scope) => unknown | Promise<unknown>;
+type AsyncRegistry = Readonly<Record<string, AsyncResolver>>;
+/** Evaluates to a boolean, awaiting `$ref`. An absent expression is `true`. */
+declare function testAsync(e: Expr | undefined, scope: Scope, registry?: AsyncRegistry): Promise<boolean>;
+
+/**
+ * The flow definition. Pure JSON — no functions, no class instances, nothing
+ * that `JSON.stringify` would drop. The same object can be written by hand,
+ * served by a backend, or generated; the engine cannot tell which.
+ *
+ * Everything that cannot be serialized is named instead: `view` names a
+ * component, `$ref` names a function, both looked up in a registry the host
+ * supplies.
+ */
+interface FlowDefinition {
+    id: string;
+    /** Bumped by the producer when the shape changes; used to reject stale patches. */
+    version?: number;
+    /** Default linear order. A step missing from `order` is reachable only via `on.next`. */
+    order?: readonly string[];
+    /** Keyed by id, not an array, so a patch can address one step without index maths. */
+    steps: Readonly<Record<string, StepDef>>;
+    policy?: NavigationPolicy;
+    validate?: {
+        on?: 'change' | 'blur' | 'next' | 'manual';
+        debounceMs?: number;
+    };
+}
+type NavigationPolicy = 'sequential' | 'visited' | 'free';
+type Target = string | {
+    to: string;
+    when?: Expr;
+};
+interface StepBase {
+    label?: string;
+    /** Reachability. A step whose `when` is false is skipped, not shown disabled. */
+    when?: Expr;
+    guards?: {
+        enter?: Expr;
+        exit?: Expr;
+    };
+    on?: {
+        next?: Target | readonly Target[];
+        back?: Target | 'auto';
+    };
+    /** Key of this step's slice of `data`. Defaults to the step id. */
+    slice?: string;
+    /** Field schema for the host to render. The engine never reads it. */
+    ui?: Json;
+    /** Loaded on enter, with an abort signal. */
+    load?: {
+        $ref: string;
+        args?: Json;
+    };
+    /** The body of this step arrives later, from the host. */
+    deferred?: boolean;
+}
+interface AtomStep extends StepBase {
+    view?: string;
+    validate?: {
+        $ref: string;
+        args?: Json;
+    };
+}
+/**
+ * A sub-flow. With `repeat` it is also the loop construct — the same machinery,
+ * because a loop is a sub-flow entered once per item. Iteration state lives in
+ * the runtime frame, never in the definition, so the flow stays static and
+ * diffable.
+ */
+interface GroupStep extends StepBase {
+    flow: string | FlowDefinition;
+    repeat?: {
+        over: Expr;
+        keyBy?: string;
+    };
+    /** Parent expressions piped into the child's `ctx`. */
+    input?: Readonly<Record<string, Expr>>;
+}
+type StepDef = AtomStep | GroupStep;
+declare const isGroup: (s: StepDef) => s is GroupStep;
+/** Sentinel target meaning the flow is finished. */
+declare const END: "@end";
+
+export { type AtomStep as A, END as E, type FlowDefinition as F, type GroupStep as G, type Json as J, type NavigationPolicy as N, type Registry as R, type StepDef as S, type Target as T, type AsyncRegistry as a, type Scope as b, type Expr as c, type Resolver as d, ExprError as e, evaluate as f, evaluateAsync as g, type AsyncResolver as h, isSync as i, testAsync as j, isGroup as k, test as t };