@coldsmirk/abacus-core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,495 @@
+import { InitInput } from "@gorules/zen-engine-wasm";
+
+//#region src/engine/intellisense.d.ts
+/**
+ * Whether an expression is a standard value expression or a unary (test) expression.
+ */
+type ExpressionMode = "standard" | "unary";
+/**
+ * A ZEN type descriptor — the shape the engine understands for type-aware
+ * completion and validation: a primitive kind name or one of the structural
+ * variants `{ Const }`, `{ Enum }`, `{ Array }`, `{ Object }`.
+ *
+ * Defined here rather than aliasing the wasm `VariableTypeJson` because the
+ * engine also emits and accepts `"Date"` — its sole method-receiver kind — which
+ * that type omits. Aliasing it would make a Date-typed variable unrepresentable
+ * and break `kind === "Date"` narrowing; the structural variants mirror the wasm
+ * shape exactly so a value crosses the boundary unchanged.
+ */
+type ExpressionType = "Any" | "Null" | "Bool" | "String" | "Number" | "Date" | {
+  Const: string;
+} | {
+  Enum: [string | undefined, string[]];
+} | {
+  Array: ExpressionType;
+} | {
+  Object: Record<string, ExpressionType>;
+};
+/**
+ * A single syntax / type diagnostic, positioned by character offset.
+ */
+interface ExpressionDiagnostic {
+  /**
+   * Start offset in the source.
+   */
+  from: number;
+  /**
+   * End offset in the source.
+   */
+  to: number;
+  /**
+   * Human-readable error message.
+   */
+  message: string;
+  /**
+   * Diagnostic origin label (e.g. `"Parser error"`).
+   */
+  source: string;
+}
+/**
+ * An autocomplete suggestion for a ZEN built-in (function / method / variable).
+ */
+interface ExpressionCompletion {
+  type: "function" | "method" | "variable";
+  label: string;
+  detail: string;
+  info: string;
+  boost: number | null;
+  /**
+   * For methods, the type-kind they attach to (e.g. `"Date"`); otherwise `null`.
+   */
+  methodFor: string | null;
+}
+/**
+ * The inferred type of one span of the source, produced by type-checking.
+ */
+interface ExpressionTypeSpan {
+  error: string | null;
+  kind: ExpressionType;
+  nodeKind: string;
+  span: [number, number];
+}
+/**
+ * The result of type-checking an expression against a variable context.
+ */
+interface ExpressionAnalysis {
+  /**
+   * The root context type (the variables object).
+   */
+  rootKind: ExpressionType;
+  /**
+   * Per-span inferred types; `spans[0]` is the whole-expression result type.
+   */
+  spans: ExpressionTypeSpan[];
+}
+/**
+ * Validate an expression, loading the engine on first use. Resolves to `null`
+ * when the expression is valid, or a positioned diagnostic otherwise.
+ */
+declare function getDiagnostics(expression: string, mode: ExpressionMode): Promise<ExpressionDiagnostic | null>;
+/**
+ * Synchronous {@link getDiagnostics}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet — use only behind a readiness gate.
+ */
+declare function getDiagnosticsSync(expression: string, mode: ExpressionMode): ExpressionDiagnostic | null;
+/**
+ * Return the ZEN built-in completion list, loading the engine on first use.
+ */
+declare function getCompletionItems(): Promise<ExpressionCompletion[]>;
+/**
+ * Synchronous {@link getCompletionItems}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet.
+ */
+declare function getCompletionItemsSync(): ExpressionCompletion[];
+/**
+ * Type-check an expression against a `variables` context, loading the engine on
+ * first use. See {@link ExpressionAnalysis}.
+ */
+declare function analyzeTypes(variables: ExpressionType, source: string, mode: ExpressionMode): Promise<ExpressionAnalysis>;
+/**
+ * Synchronous {@link analyzeTypes}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet.
+ */
+declare function analyzeTypesSync(variables: ExpressionType, source: string, mode: ExpressionMode): ExpressionAnalysis;
+/**
+ * Whether `actual` satisfies (is assignable to) `expected`, loading the engine on
+ * first use. Used for expected-return-type validation.
+ */
+declare function satisfiesType(actual: ExpressionType, expected: ExpressionType): Promise<boolean>;
+/**
+ * Synchronous {@link satisfiesType}. Throws `ExpressionNotReadyError` if the
+ * engine has not loaded yet.
+ */
+declare function satisfiesTypeSync(actual: ExpressionType, expected: ExpressionType): boolean;
+//#endregion
+//#region src/engine/errors.d.ts
+/**
+ * Error raised when the ZEN engine fails to load or an expression cannot be
+ * evaluated. The original failure is preserved on {@link cause} and the
+ * offending expression (if any) on {@link expression}.
+ */
+declare class ExpressionError extends Error {
+  readonly expression?: string;
+  constructor(message: string, expression?: string, cause?: unknown);
+}
+/**
+ * Raised by the synchronous evaluation helpers when the engine has not finished
+ * initializing yet. Await {@link loadEngine} (or render under
+ * `<ExpressionEngineProvider>`) before evaluating synchronously.
+ */
+declare class ExpressionNotReadyError extends ExpressionError {
+  constructor(message?: string);
+}
+//#endregion
+//#region src/engine/loader.d.ts
+/**
+ * The data an expression reads from. Property paths in the expression (e.g.
+ * `customer.name`) resolve against this object.
+ */
+type ExpressionContext = Record<string, unknown>;
+interface LoadEngineOptions {
+  /**
+   * Override how the wasm binary is located. By default the engine resolves the
+   * co-located `.wasm` through the GoRules package's own `import.meta.url`,
+   * which the host bundler (Vite / webpack) rewrites to a served asset URL — no
+   * option is needed in normal browser app setups. Supply a URL / Response /
+   * bytes for exotic hosting (CDN, embedded buffer) or for a non-browser host
+   * (Node / SSR), where `import.meta.url` asset resolution does not work and the
+   * input must be provided explicitly. Aliased to the wasm initializer's own
+   * `InitInput` so it never drifts from the dependency.
+   */
+  wasmInput?: InitInput;
+}
+/**
+ * The initialized ZEN expression engine. Every method is synchronous — obtain
+ * an instance via {@link loadEngine} (async, loads the wasm) before calling.
+ */
+interface ExpressionEngine {
+  /**
+   * Evaluate a standard ZEN expression, returning its computed value.
+   */
+  evaluate: <T = unknown>(expression: string, context?: ExpressionContext) => T;
+  /**
+   * Evaluate a ZEN unary (test) expression, returning a boolean.
+   */
+  evaluateUnary: (expression: string, context?: ExpressionContext) => boolean;
+  /**
+   * Validate a standard expression; returns ZEN's diagnostic payload (`null`
+   * when the expression parses, an error object otherwise).
+   */
+  validate: (expression: string) => unknown;
+  /**
+   * Validate a unary expression; returns ZEN's diagnostic payload.
+   */
+  validateUnary: (expression: string) => unknown;
+  /**
+   * Return ZEN's completion metadata, for building an expression editor.
+   */
+  getCompletions: () => unknown;
+  /**
+   * Type-check `source` against a `variables` context, returning the root context
+   * type and the inferred type of every span (`unary` selects test-expression
+   * checking). Powers an editor's type-aware completion / hover / diagnostics.
+   */
+  analyze: (variables: ExpressionType, source: string, unary: boolean) => ExpressionAnalysis;
+  /**
+   * Whether `actual` satisfies (is assignable to) `expected`. Powers
+   * expected-return-type validation in an editor.
+   */
+  satisfies: (actual: ExpressionType, expected: ExpressionType) => boolean;
+  /**
+   * Whether the underlying wasm module reports itself ready.
+   */
+  isReady: () => boolean;
+}
+/**
+ * Configure how the wasm binary is located, before the engine loads. Must be
+ * called before the first {@link loadEngine} (or any evaluation), so that the
+ * configured input is the one actually used — calling it after the engine has
+ * started loading throws, rather than silently taking no effect.
+ */
+declare function configureEngine(options: LoadEngineOptions): void;
+/**
+ * Load and initialize the ZEN expression engine exactly once. Concurrent and
+ * subsequent calls share the same in-flight promise / resolved instance. Set a
+ * custom wasm source up front with {@link configureEngine}.
+ *
+ * The GoRules wasm dependency is reached via a dynamic `import()` on purpose: it
+ * keeps this module usable from the package's CommonJS build (the dep is
+ * ESM-only, so a static `require` would throw) and defers the multi-megabyte
+ * wasm download until the engine is actually needed. Do NOT convert this to a
+ * static import.
+ *
+ * A failed load is not cached: the rejected promise is dropped (the error is
+ * latched on {@link getEngineError} for inspection), so calling `loadEngine()`
+ * again retries from scratch. This is the clear-and-reload retry primitive after
+ * a transient failure — an error boundary should call it before resetting.
+ */
+declare function loadEngine(): Promise<ExpressionEngine>;
+/**
+ * Whether the engine has finished initializing and is ready for sync use.
+ */
+declare function isEngineReady(): boolean;
+/**
+ * The error from the last failed {@link loadEngine} attempt, or `null`. Used by
+ * the React provider to surface a wasm-load failure to an error boundary rather
+ * than suspending forever, and by imperative pollers to tell "failed" apart from
+ * "still loading". Cleared when a new load starts or {@link resetEngine}.
+ */
+declare function getEngineError(): ExpressionError | null;
+/**
+ * Return the already-initialized engine synchronously, or throw
+ * {@link ExpressionNotReadyError} if {@link loadEngine} has not resolved yet.
+ */
+declare function getEngineSync(): ExpressionEngine;
+/**
+ * Reset the engine singleton — drops the loaded engine, the cached type context,
+ * the latched error, and the configured wasm input. Mainly for tests, but also the
+ * way to re-run {@link configureEngine} after a load (configure throws once the
+ * engine has started loading).
+ */
+declare function resetEngine(): void;
+//#endregion
+//#region src/condition/types.d.ts
+/**
+ * Structural shapes for the visual condition model compiled to ZEN. They mirror
+ * the condition types used in the form and flow editors so a host can map those
+ * definitions to {@link compileCondition} / {@link selectBranch} without this
+ * package depending on either editor. The editors keep a flat working model for
+ * form ergonomics (a row can hold both a half-typed field triple and an
+ * expression while the author toggles between them); this discriminated input is
+ * the narrowed, compiler-facing shape where each kind carries only what it uses.
+ */
+/**
+ * The closed operator vocabulary understood by {@link compileCondition}, as a
+ * runtime constant so validators can build allow-lists from it instead of
+ * re-declaring the set. The {@link ConditionOperator} type derives from this
+ * array — one definition site for both the type and the runtime list.
+ */
+declare const CONDITION_OPERATORS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "contains", "not_contains", "starts_with", "ends_with", "in", "not_in", "is_empty", "is_not_empty"];
+/**
+ * Operators understood by {@link compileCondition}. The compiler maps each to a
+ * ZEN expression; this closed set is the single source of truth for the operator
+ * vocabulary (the flow editor shares it instead of re-declaring its own).
+ */
+type ConditionOperator = typeof CONDITION_OPERATORS[number];
+/**
+ * A field/operator/value condition.
+ */
+interface FieldConditionInput {
+  kind: "field";
+  /**
+   * The field path the operator tests. Emitted **verbatim** into the compiled
+   * ZEN source as a path expression (guarded by an identifier-path pattern that
+   * also rejects ZEN reserved words such as `true` or `not` as segments), unlike
+   * `value`, which is serialized to a ZEN literal — so callers must supply a
+   * valid identifier path, not arbitrary user text.
+   */
+  subject: string;
+  operator: ConditionOperator;
+  value: unknown;
+}
+/**
+ * A raw ZEN expression condition, passed through to the engine verbatim.
+ */
+interface ExpressionConditionInput {
+  kind: "expression";
+  expression: string;
+}
+/**
+ * A single condition: either a field/operator/value triple or a raw expression.
+ */
+type ConditionInput = FieldConditionInput | ExpressionConditionInput;
+/**
+ * A group of conditions, combined with AND.
+ */
+interface ConditionGroupInput {
+  conditions: readonly ConditionInput[];
+}
+/**
+ * A branch guarded by one or more condition groups (combined with OR).
+ */
+interface ConditionBranchInput {
+  id: string;
+  priority: number;
+  isDefault?: boolean;
+  conditionGroups?: readonly ConditionGroupInput[];
+}
+/**
+ * The branch chosen by {@link selectBranch}. `matched` is true only when a
+ * non-default branch's expression evaluated true (then `branchId` is that
+ * branch's id). On the default-branch fallback `matched` is false while
+ * `branchId` is the default's id; `branchId` is null only when nothing matched
+ * and there is no default branch.
+ */
+type BranchSelection = {
+  matched: true;
+  branchId: string;
+} | {
+  matched: false;
+  branchId: string | null;
+};
+//#endregion
+//#region src/condition/compile.d.ts
+/**
+ * Serialize a JavaScript value into a ZEN literal. Nullish becomes `null`;
+ * numbers / booleans / bigints are emitted verbatim; strings are quoted via
+ * {@link encodeZenString}; arrays become `[a, b, ...]`.
+ *
+ * Throws {@link ExpressionError} for a value with no faithful ZEN
+ * representation — an object, symbol, or function, or a string containing both
+ * quote styles. Callers that need a sentinel instead of a throw go through
+ * {@link compileCondition}, which degrades such a value to a non-compiling
+ * (null) condition.
+ */
+declare function toZenLiteral(value: unknown): string;
+/**
+ * Compile a single condition into a ZEN boolean expression. Field conditions map
+ * their operator to ZEN; expression conditions are wrapped in parentheses to
+ * preserve their grouping. Returns `null` when the condition is empty, its
+ * subject is not an identifier path, or its value has no ZEN representation.
+ */
+declare function compileCondition(condition: ConditionInput): string | null;
+/**
+ * Compile a condition group (its conditions joined with AND). Returns `null`
+ * when the group has no compilable conditions.
+ */
+declare function compileGroup(group: ConditionGroupInput): string | null;
+/**
+ * Compile a branch's condition groups into a single ZEN expression (groups
+ * joined with OR). Returns `null` when the branch has no compilable groups
+ * (e.g. a default branch).
+ */
+declare function compileBranch(branch: ConditionBranchInput): string | null;
+/**
+ * Pick the matching branch for the given context using a pre-loaded engine.
+ * Non-default branches are tested in ascending `priority` order; the first whose
+ * compiled expression evaluates to `true` wins. Falls back to the default
+ * branch, or a `null` id when neither matches.
+ *
+ * A branch whose expression throws for the given context (e.g. ZEN's `>`
+ * throws when the subject is missing or non-numeric) is treated as not matching
+ * rather than propagating — so a missing field degrades to the default branch
+ * instead of crashing the caller.
+ */
+declare function selectBranchWith(branches: readonly ConditionBranchInput[], context: ExpressionContext, engine: Pick<ExpressionEngine, "evaluate" | "validate">): BranchSelection;
+/**
+ * Pick the matching branch for the given context, loading the ZEN engine on
+ * first use. See {@link selectBranchWith} for the selection semantics.
+ */
+declare function selectBranch(branches: readonly ConditionBranchInput[], context: ExpressionContext): Promise<BranchSelection>;
+//#endregion
+//#region src/engine/evaluate.d.ts
+/**
+ * Evaluate a standard ZEN expression, loading the engine on first use.
+ *
+ * `T` is an **unchecked** assertion — the value is returned as `T` with no
+ * runtime validation, and ZEN's result type depends on the expression and
+ * context. Prefer the `unknown` default and narrow at the call site.
+ */
+declare function evaluate<T = unknown>(expression: string, context?: ExpressionContext): Promise<T>;
+/**
+ * Evaluate a ZEN unary (test) expression, loading the engine on first use.
+ */
+declare function evaluateUnary(expression: string, context?: ExpressionContext): Promise<boolean>;
+/**
+ * Evaluate a standard ZEN expression synchronously. Throws
+ * {@link ExpressionNotReadyError} when the engine has not loaded yet — use this
+ * only behind a readiness gate (e.g. under `<ExpressionEngineProvider>`).
+ */
+declare function evaluateSync<T = unknown>(expression: string, context?: ExpressionContext): T;
+/**
+ * Evaluate a ZEN unary (test) expression synchronously. Throws
+ * {@link ExpressionNotReadyError} when the engine has not loaded yet.
+ */
+declare function evaluateUnarySync(expression: string, context?: ExpressionContext): boolean;
+//#endregion
+//#region src/engine/messages.d.ts
+/**
+ * The locales the library ships with out of the box.
+ */
+type BuiltInExpressionLocale = "en-US" | "zh-CN";
+/**
+ * A locale key for editor-produced text (built-in descriptions, type-check prose,
+ * and diagnostic origin labels — the wasm engine's own error bodies, identifiers,
+ * and type signatures are never translated). The built-in locales surface in
+ * autocomplete, while any string is accepted so a host can select a locale
+ * registered through {@link registerExpressionLocale}.
+ */
+type ExpressionLocale = BuiltInExpressionLocale | (string & {});
+/**
+ * The catalog of editor-produced messages for one locale. All localized text the
+ * editor surfaces flows through this interface, so a host can switch language or
+ * override individual strings in one typed place — and add a language the library
+ * does not ship by passing a full `messages` object to
+ * {@link configureExpressionMessages}.
+ */
+interface ExpressionMessages {
+  /**
+   * The diagnostic origin label for a wasm error `type` (`"parserError"` →
+   * `"Parser error"`), falling back to a generic label for an unknown type.
+   */
+  sourceLabel: (type?: string) => string;
+  /**
+   * Translate a built-in's English `info` description to this locale. Returns the
+   * input unchanged for English or when no translation exists.
+   */
+  completionInfo: (englishInfo: string) => string;
+  /**
+   * The `source` label shown on type-check (as opposed to syntax) diagnostics.
+   */
+  typeCheckSource: string;
+  /**
+   * Warning shown when a unary (test) expression does not evaluate to a boolean.
+   */
+  expectedBoolean: (actualType: string) => string;
+  /**
+   * Warning shown when a standard expression's result type does not satisfy the
+   * configured expected type.
+   */
+  expectedType: (expectedType: string, actualType: string) => string;
+}
+/**
+ * Built-in English message catalog (the default).
+ */
+declare const enMessages: ExpressionMessages;
+/**
+ * Built-in Simplified Chinese message catalog.
+ */
+declare const zhCNMessages: ExpressionMessages;
+/**
+ * Register (or replace) the message catalog for a locale key, making it selectable
+ * via {@link configureExpressionMessages}. This is how a host adds a language the
+ * library does not ship — the built-in locales are registered the same way, so
+ * there is no privileged path.
+ */
+declare function registerExpressionLocale(locale: string, messages: ExpressionMessages): void;
+interface ConfigureMessagesOptions {
+  /**
+   * A registered locale to use as the base — built-in or registered through
+   * {@link registerExpressionLocale}. An unknown key keeps the current base; omit
+   * to keep the current base.
+   */
+  locale?: ExpressionLocale;
+  /**
+   * Per-message overrides merged over the base — a quick way to tweak a few strings
+   * without registering a whole locale.
+   */
+  messages?: Partial<ExpressionMessages>;
+}
+/**
+ * Configure the active message catalog. Pass a `locale`, a partial `messages`
+ * override, or both (overrides win). Idempotent and module-global, so a host
+ * configures it once (e.g. through `ExpressionConfigProvider`).
+ */
+declare function configureExpressionMessages({
+  locale,
+  messages
+}: ConfigureMessagesOptions): void;
+/**
+ * The active {@link ExpressionMessages} catalog (English by default).
+ */
+declare function getExpressionMessages(): ExpressionMessages;
+//#endregion
+export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileGroup, configureEngine, configureExpressionMessages, enMessages, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, isEngineReady, loadEngine, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, toZenLiteral, zhCNMessages };
+//# sourceMappingURL=index.d.ts.map