trilean 1.6.3 → 1.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -818,6 +818,19 @@ const { evaluateValue } = createEvaluator({
818
818
  });
819
819
  ```
820
820
 
821
+ ### Synchronous evaluation
822
+
823
+ When every resolver is a plain in-memory read, `createSyncEvaluator` builds the same pair with no promises at all, taking `SyncResolvers` (each resolver returns its result directly) and returning the `Evaluation` directly:
824
+
825
+ ```ts
826
+ function createSyncEvaluator(options: { functions?: FunctionRegistry; maxNodes?: number; maxNestingDepth?: number }): {
827
+ evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: SyncResolvers) => Evaluation<boolean>;
828
+ evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: SyncResolvers) => Evaluation<ComputedValue>;
829
+ };
830
+ ```
831
+
832
+ The node rules are written once and run by either driver, so the two evaluators agree on every node kind and every three-valued rule. A resolver that returns a promise (or any thenable) to a synchronous evaluator makes the evaluation throw a `TypeError`, since there is nothing to await it with. Because nothing is concurrent, independent operands (both sides of an `and`, the candidates of a `memberOf`, the items of a collection) are evaluated one after another; when a `maxNodes` or `maxNestingDepth` limit is exhausted partway through a tree, which operand meets it first can therefore differ from the asynchronous evaluator.
833
+
821
834
  ## Indeterminacy reference
822
835
 
823
836
  How each reason category can arise, per node kind. "Propagates" means: an indeterminate operand/sub-result, with no other rule overriding it, makes the whole node indeterminate with that same reason (subject to the tie-break rule in [The evaluation model](#the-evaluation-model) when more than one candidate reason is present, and to the absorbing-value exceptions called out explicitly below).
@@ -1,16 +1,17 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ const require_evaluator_effect = require("./evaluator-effect.cjs");
2
3
  //#region src/evaluator-collection.ts
3
4
  /**
4
5
  * Collection resolution shared by the quantifiers (`some`/`every`) and by `fold` in evaluator.ts: resolves the opaque `collection` reference to its concrete candidate list via `resolvers.resolveCollection`, then evaluates each candidate's optional `filter` (via the injected `evaluatePredicate`, see `EvaluatePredicate`'s own doc comment) with that candidate as its own evaluation context and the accumulator reset to `undefined` -- see the README's "Evaluation context" and "Pre-filtering which items participate" sections. Deliberately stops short of deciding how an indeterminate filter combines with the rest of the surrounding node: `some`/`every` fold a filter-indeterminate item in as its own vote via the surrounding OR/AND absorption, while `fold` has no absorbing value at all and goes indeterminate outright on the same condition -- the two callers need genuinely different combination logic over these same per-item outcomes, so this helper only produces the outcomes and leaves combining them to the caller.
5
6
  */
6
- async function resolveParticipatingItems(evaluatePredicate, collection, filter, context, resolvers, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth) {
7
- const candidates = await resolvers.resolveCollection(collection, context);
8
- return Promise.all(candidates.map(async (item) => {
7
+ function* resolveParticipatingItems(evaluatePredicate, collection, filter, context, resolvers, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth) {
8
+ const candidates = yield* require_evaluator_effect.wait(resolvers.resolveCollection(collection, context));
9
+ return yield* require_evaluator_effect.all(candidates.map(function* (item) {
9
10
  if (filter === void 0) return {
10
11
  item,
11
12
  filterOutcome: "include"
12
13
  };
13
- const filterResult = await evaluatePredicate(filter, item, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth + 1);
14
+ const filterResult = yield* evaluatePredicate(filter, item, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth + 1);
14
15
  if (filterResult.status === "indeterminate") return {
15
16
  item,
16
17
  filterOutcome: filterResult
@@ -4,10 +4,11 @@ import { PredicateNode } from "./tree.cjs";
4
4
  import { Evaluation, IndeterminateReason } from "./evaluation.cjs";
5
5
  import { EvaluationBudget } from "./evaluator-budget.cjs";
6
6
  import { FunctionRegistry } from "./functions.cjs";
7
- import { EvaluationContext, Resolvers } from "./resolvers.cjs";
7
+ import { Task } from "./evaluator-effect.cjs";
8
+ import { EvaluationContext, EvaluatorResolvers } from "./resolvers.cjs";
8
9
  //#region src/evaluator-collection.d.ts
9
10
  /** `resolveParticipatingItems`'s own view of `evaluatePredicateInternal` -- the exact signature that function has in evaluator.ts, injected here rather than imported directly so this module has no dependency back on evaluator.ts. Evaluating a `filter` genuinely does need the full recursive predicate evaluator (a filter can itself be arbitrarily nested), but taking it as a parameter rather than an import means this collection-resolution logic and evaluator.ts's mutually-recursive `evaluatePredicateInternal`/`evaluateValueInternal` pair never import each other, so there is no circular-import hazard between the two files. */
10
- export type EvaluatePredicate = (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>, accumulator: ComputedValue | undefined, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number) => Promise<Evaluation<boolean>>;
11
+ export type EvaluatePredicate = (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<EvaluatorResolvers>, accumulator: ComputedValue | undefined, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number) => Task<Evaluation<boolean>>;
11
12
  /** A collection candidate paired with its own pre-filter outcome: `"include"`/`"exclude"` when `filter` resolved definitely, or the filter's own indeterminate `Evaluation` when it did not (there is no third, definite-but-neither branch -- see `resolveParticipatingItems` below). */
12
13
  export interface ResolvedCollectionItem {
13
14
  readonly item: unknown;
@@ -16,7 +17,7 @@ export interface ResolvedCollectionItem {
16
17
  /**
17
18
  * Collection resolution shared by the quantifiers (`some`/`every`) and by `fold` in evaluator.ts: resolves the opaque `collection` reference to its concrete candidate list via `resolvers.resolveCollection`, then evaluates each candidate's optional `filter` (via the injected `evaluatePredicate`, see `EvaluatePredicate`'s own doc comment) with that candidate as its own evaluation context and the accumulator reset to `undefined` -- see the README's "Evaluation context" and "Pre-filtering which items participate" sections. Deliberately stops short of deciding how an indeterminate filter combines with the rest of the surrounding node: `some`/`every` fold a filter-indeterminate item in as its own vote via the surrounding OR/AND absorption, while `fold` has no absorbing value at all and goes indeterminate outright on the same condition -- the two callers need genuinely different combination logic over these same per-item outcomes, so this helper only produces the outcomes and leaves combining them to the caller.
18
19
  */
19
- export declare function resolveParticipatingItems(evaluatePredicate: EvaluatePredicate, collection: JsonValue, filter: PredicateNode | undefined, context: EvaluationContext, resolvers: Readonly<Resolvers>, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number): Promise<ResolvedCollectionItem[]>;
20
+ export declare function resolveParticipatingItems(evaluatePredicate: EvaluatePredicate, collection: JsonValue, filter: PredicateNode | undefined, context: EvaluationContext, resolvers: Readonly<EvaluatorResolvers>, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number): Task<ResolvedCollectionItem[]>;
20
21
  /** The first participating item (in declared collection order) whose `filter` evaluation was itself indeterminate, or `undefined` if every participating item's filter resolved definitely -- a filter-excluded item's own `"exclude"` outcome never counts here. Used only by `fold`, which -- unlike `some`/`every`'s OR/AND absorption -- has no absorbing value at all: any participating item's indeterminate filter makes the whole fold indeterminate outright, with no other item's outcome able to override it. */
21
22
  export declare function firstFilterIndeterminate(participating: readonly ResolvedCollectionItem[]): IndeterminateReason | undefined;
22
23
  //#endregion
@@ -4,10 +4,11 @@ import { PredicateNode } from "./tree.js";
4
4
  import { Evaluation, IndeterminateReason } from "./evaluation.js";
5
5
  import { EvaluationBudget } from "./evaluator-budget.js";
6
6
  import { FunctionRegistry } from "./functions.js";
7
- import { EvaluationContext, Resolvers } from "./resolvers.js";
7
+ import { Task } from "./evaluator-effect.js";
8
+ import { EvaluationContext, EvaluatorResolvers } from "./resolvers.js";
8
9
  //#region src/evaluator-collection.d.ts
9
10
  /** `resolveParticipatingItems`'s own view of `evaluatePredicateInternal` -- the exact signature that function has in evaluator.ts, injected here rather than imported directly so this module has no dependency back on evaluator.ts. Evaluating a `filter` genuinely does need the full recursive predicate evaluator (a filter can itself be arbitrarily nested), but taking it as a parameter rather than an import means this collection-resolution logic and evaluator.ts's mutually-recursive `evaluatePredicateInternal`/`evaluateValueInternal` pair never import each other, so there is no circular-import hazard between the two files. */
10
- export type EvaluatePredicate = (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>, accumulator: ComputedValue | undefined, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number) => Promise<Evaluation<boolean>>;
11
+ export type EvaluatePredicate = (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<EvaluatorResolvers>, accumulator: ComputedValue | undefined, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number) => Task<Evaluation<boolean>>;
11
12
  /** A collection candidate paired with its own pre-filter outcome: `"include"`/`"exclude"` when `filter` resolved definitely, or the filter's own indeterminate `Evaluation` when it did not (there is no third, definite-but-neither branch -- see `resolveParticipatingItems` below). */
12
13
  export interface ResolvedCollectionItem {
13
14
  readonly item: unknown;
@@ -16,7 +17,7 @@ export interface ResolvedCollectionItem {
16
17
  /**
17
18
  * Collection resolution shared by the quantifiers (`some`/`every`) and by `fold` in evaluator.ts: resolves the opaque `collection` reference to its concrete candidate list via `resolvers.resolveCollection`, then evaluates each candidate's optional `filter` (via the injected `evaluatePredicate`, see `EvaluatePredicate`'s own doc comment) with that candidate as its own evaluation context and the accumulator reset to `undefined` -- see the README's "Evaluation context" and "Pre-filtering which items participate" sections. Deliberately stops short of deciding how an indeterminate filter combines with the rest of the surrounding node: `some`/`every` fold a filter-indeterminate item in as its own vote via the surrounding OR/AND absorption, while `fold` has no absorbing value at all and goes indeterminate outright on the same condition -- the two callers need genuinely different combination logic over these same per-item outcomes, so this helper only produces the outcomes and leaves combining them to the caller.
18
19
  */
19
- export declare function resolveParticipatingItems(evaluatePredicate: EvaluatePredicate, collection: JsonValue, filter: PredicateNode | undefined, context: EvaluationContext, resolvers: Readonly<Resolvers>, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number): Promise<ResolvedCollectionItem[]>;
20
+ export declare function resolveParticipatingItems(evaluatePredicate: EvaluatePredicate, collection: JsonValue, filter: PredicateNode | undefined, context: EvaluationContext, resolvers: Readonly<EvaluatorResolvers>, functions: Readonly<FunctionRegistry>, visitedTreeKeys: ReadonlySet<string>, treeReferenceDepth: number, budget: Readonly<EvaluationBudget>, nestingDepth: number): Task<ResolvedCollectionItem[]>;
20
21
  /** The first participating item (in declared collection order) whose `filter` evaluation was itself indeterminate, or `undefined` if every participating item's filter resolved definitely -- a filter-excluded item's own `"exclude"` outcome never counts here. Used only by `fold`, which -- unlike `some`/`every`'s OR/AND absorption -- has no absorbing value at all: any participating item's indeterminate filter makes the whole fold indeterminate outright, with no other item's outcome able to override it. */
21
22
  export declare function firstFilterIndeterminate(participating: readonly ResolvedCollectionItem[]): IndeterminateReason | undefined;
22
23
  //#endregion
@@ -1,15 +1,16 @@
1
+ import { all, wait } from "./evaluator-effect.js";
1
2
  //#region src/evaluator-collection.ts
2
3
  /**
3
4
  * Collection resolution shared by the quantifiers (`some`/`every`) and by `fold` in evaluator.ts: resolves the opaque `collection` reference to its concrete candidate list via `resolvers.resolveCollection`, then evaluates each candidate's optional `filter` (via the injected `evaluatePredicate`, see `EvaluatePredicate`'s own doc comment) with that candidate as its own evaluation context and the accumulator reset to `undefined` -- see the README's "Evaluation context" and "Pre-filtering which items participate" sections. Deliberately stops short of deciding how an indeterminate filter combines with the rest of the surrounding node: `some`/`every` fold a filter-indeterminate item in as its own vote via the surrounding OR/AND absorption, while `fold` has no absorbing value at all and goes indeterminate outright on the same condition -- the two callers need genuinely different combination logic over these same per-item outcomes, so this helper only produces the outcomes and leaves combining them to the caller.
4
5
  */
5
- async function resolveParticipatingItems(evaluatePredicate, collection, filter, context, resolvers, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth) {
6
- const candidates = await resolvers.resolveCollection(collection, context);
7
- return Promise.all(candidates.map(async (item) => {
6
+ function* resolveParticipatingItems(evaluatePredicate, collection, filter, context, resolvers, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth) {
7
+ const candidates = yield* wait(resolvers.resolveCollection(collection, context));
8
+ return yield* all(candidates.map(function* (item) {
8
9
  if (filter === void 0) return {
9
10
  item,
10
11
  filterOutcome: "include"
11
12
  };
12
- const filterResult = await evaluatePredicate(filter, item, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth + 1);
13
+ const filterResult = yield* evaluatePredicate(filter, item, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth + 1);
13
14
  if (filterResult.status === "indeterminate") return {
14
15
  item,
15
16
  filterOutcome: filterResult
@@ -0,0 +1,54 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ //#region src/evaluator-effect.ts
3
+ /**
4
+ * Suspends until `value` is available. The driver resumes the task with exactly that value (awaited, in the async driver), and the generator's own "next" type is `T`, so the result is typed without an assertion.
5
+ */
6
+ function* wait(value) {
7
+ return yield {
8
+ kind: "wait",
9
+ value
10
+ };
11
+ }
12
+ /**
13
+ * Suspends until every task has finished and returns their results in order. The tasks are independent of one another by construction, so a driver may interleave them (async) or run them in sequence (sync).
14
+ */
15
+ function* all(tasks) {
16
+ return yield {
17
+ kind: "all",
18
+ tasks
19
+ };
20
+ }
21
+ function isThenable(value) {
22
+ return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
23
+ }
24
+ /** Runs a task to completion, awaiting each suspension and running an `all` group's tasks concurrently. */
25
+ async function runAsync(task) {
26
+ let step = task.next();
27
+ while (step.done !== true) {
28
+ const suspension = step.value;
29
+ const result = suspension.kind === "wait" ? await suspension.value : await Promise.all(suspension.tasks.map(runAsync));
30
+ step = task.next(result);
31
+ }
32
+ return step.value;
33
+ }
34
+ /**
35
+ * Runs a task to completion without awaiting anything: an `all` group's tasks run one after another, and a `wait` on a promise throws, since a synchronous evaluator has nothing to do with one.
36
+ */
37
+ function runSync(task) {
38
+ let step = task.next();
39
+ while (step.done !== true) {
40
+ const suspension = step.value;
41
+ let result;
42
+ if (suspension.kind === "wait") {
43
+ if (isThenable(suspension.value)) throw new TypeError("a resolver supplied to a synchronous evaluator returned a promise; use the asynchronous evaluator for asynchronous resolvers");
44
+ result = suspension.value;
45
+ } else result = suspension.tasks.map(runSync);
46
+ step = task.next(result);
47
+ }
48
+ return step.value;
49
+ }
50
+ //#endregion
51
+ exports.all = all;
52
+ exports.runAsync = runAsync;
53
+ exports.runSync = runSync;
54
+ exports.wait = wait;
@@ -0,0 +1,37 @@
1
+ //#region src/evaluator-effect.d.ts
2
+ /**
3
+ * The evaluator's node rules are written once, as generator functions that describe *what* to wait for rather than *how* to wait for it. `evaluator.ts` `yield*`s two kinds of suspension and never touches a promise itself:
4
+ * - `wait`: a single resolver result that is either already a value or a promise of one.
5
+ * - `all`: sub-evaluations that are independent of one another, which the async driver runs concurrently and the synchronous driver runs one after another.
6
+ * Two drivers then run the same generator: `runAsync` awaits every suspension, `runSync` requires every one to already be a value. Because both drive one implementation of the node rules, the synchronous and asynchronous evaluators cannot drift apart in how a node is evaluated.
7
+ */
8
+ /** A single value that may still be a promise; `wait` resolves it in whichever driver runs the surrounding task. */
9
+ type Awaitable<T> = T | Promise<T>;
10
+ /** What a task suspends on: one resolver result (`wait`) or independent sub-tasks (`all`). */
11
+ export type Suspension = {
12
+ readonly kind: "wait";
13
+ readonly value: unknown;
14
+ } | {
15
+ readonly kind: "all";
16
+ readonly tasks: readonly Runnable<unknown>[];
17
+ };
18
+ /** A suspendable computation: yields `Suspension`s and returns `T`. Its "next" type is `never` so that only a `yield*` of `wait` or `all` (whose results are typed by their own operands) can sit inside one; a driver resumes it through `Runnable`, which is deliberately looser. */
19
+ export type Task<T> = Generator<Suspension, T, never>;
20
+ /** What a driver needs from a task: resume it with whatever the last suspension produced. Generator methods are bivariant, so every `Task` is a `Runnable`. */
21
+ type Runnable<T> = Iterator<Suspension, T, unknown>;
22
+ type TaskResults<T extends readonly Runnable<unknown>[]> = { -readonly [K in keyof T]: T[K] extends Task<infer R> ? R : never; };
23
+ /**
24
+ * Suspends until `value` is available. The driver resumes the task with exactly that value (awaited, in the async driver), and the generator's own "next" type is `T`, so the result is typed without an assertion.
25
+ */
26
+ export declare function wait<T>(value: Awaitable<T>): Generator<Suspension, T, T>;
27
+ /**
28
+ * Suspends until every task has finished and returns their results in order. The tasks are independent of one another by construction, so a driver may interleave them (async) or run them in sequence (sync).
29
+ */
30
+ export declare function all<const T extends readonly Runnable<unknown>[]>(tasks: T): Generator<Suspension, TaskResults<T>, TaskResults<T>>;
31
+ /** Runs a task to completion, awaiting each suspension and running an `all` group's tasks concurrently. */
32
+ export declare function runAsync<T>(task: Readonly<Runnable<T>>): Promise<T>;
33
+ /**
34
+ * Runs a task to completion without awaiting anything: an `all` group's tasks run one after another, and a `wait` on a promise throws, since a synchronous evaluator has nothing to do with one.
35
+ */
36
+ export declare function runSync<T>(task: Readonly<Runnable<T>>): T;
37
+ //#endregion
@@ -0,0 +1,37 @@
1
+ //#region src/evaluator-effect.d.ts
2
+ /**
3
+ * The evaluator's node rules are written once, as generator functions that describe *what* to wait for rather than *how* to wait for it. `evaluator.ts` `yield*`s two kinds of suspension and never touches a promise itself:
4
+ * - `wait`: a single resolver result that is either already a value or a promise of one.
5
+ * - `all`: sub-evaluations that are independent of one another, which the async driver runs concurrently and the synchronous driver runs one after another.
6
+ * Two drivers then run the same generator: `runAsync` awaits every suspension, `runSync` requires every one to already be a value. Because both drive one implementation of the node rules, the synchronous and asynchronous evaluators cannot drift apart in how a node is evaluated.
7
+ */
8
+ /** A single value that may still be a promise; `wait` resolves it in whichever driver runs the surrounding task. */
9
+ type Awaitable<T> = T | Promise<T>;
10
+ /** What a task suspends on: one resolver result (`wait`) or independent sub-tasks (`all`). */
11
+ export type Suspension = {
12
+ readonly kind: "wait";
13
+ readonly value: unknown;
14
+ } | {
15
+ readonly kind: "all";
16
+ readonly tasks: readonly Runnable<unknown>[];
17
+ };
18
+ /** A suspendable computation: yields `Suspension`s and returns `T`. Its "next" type is `never` so that only a `yield*` of `wait` or `all` (whose results are typed by their own operands) can sit inside one; a driver resumes it through `Runnable`, which is deliberately looser. */
19
+ export type Task<T> = Generator<Suspension, T, never>;
20
+ /** What a driver needs from a task: resume it with whatever the last suspension produced. Generator methods are bivariant, so every `Task` is a `Runnable`. */
21
+ type Runnable<T> = Iterator<Suspension, T, unknown>;
22
+ type TaskResults<T extends readonly Runnable<unknown>[]> = { -readonly [K in keyof T]: T[K] extends Task<infer R> ? R : never; };
23
+ /**
24
+ * Suspends until `value` is available. The driver resumes the task with exactly that value (awaited, in the async driver), and the generator's own "next" type is `T`, so the result is typed without an assertion.
25
+ */
26
+ export declare function wait<T>(value: Awaitable<T>): Generator<Suspension, T, T>;
27
+ /**
28
+ * Suspends until every task has finished and returns their results in order. The tasks are independent of one another by construction, so a driver may interleave them (async) or run them in sequence (sync).
29
+ */
30
+ export declare function all<const T extends readonly Runnable<unknown>[]>(tasks: T): Generator<Suspension, TaskResults<T>, TaskResults<T>>;
31
+ /** Runs a task to completion, awaiting each suspension and running an `all` group's tasks concurrently. */
32
+ export declare function runAsync<T>(task: Readonly<Runnable<T>>): Promise<T>;
33
+ /**
34
+ * Runs a task to completion without awaiting anything: an `all` group's tasks run one after another, and a `wait` on a promise throws, since a synchronous evaluator has nothing to do with one.
35
+ */
36
+ export declare function runSync<T>(task: Readonly<Runnable<T>>): T;
37
+ //#endregion
@@ -0,0 +1,50 @@
1
+ //#region src/evaluator-effect.ts
2
+ /**
3
+ * Suspends until `value` is available. The driver resumes the task with exactly that value (awaited, in the async driver), and the generator's own "next" type is `T`, so the result is typed without an assertion.
4
+ */
5
+ function* wait(value) {
6
+ return yield {
7
+ kind: "wait",
8
+ value
9
+ };
10
+ }
11
+ /**
12
+ * Suspends until every task has finished and returns their results in order. The tasks are independent of one another by construction, so a driver may interleave them (async) or run them in sequence (sync).
13
+ */
14
+ function* all(tasks) {
15
+ return yield {
16
+ kind: "all",
17
+ tasks
18
+ };
19
+ }
20
+ function isThenable(value) {
21
+ return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
22
+ }
23
+ /** Runs a task to completion, awaiting each suspension and running an `all` group's tasks concurrently. */
24
+ async function runAsync(task) {
25
+ let step = task.next();
26
+ while (step.done !== true) {
27
+ const suspension = step.value;
28
+ const result = suspension.kind === "wait" ? await suspension.value : await Promise.all(suspension.tasks.map(runAsync));
29
+ step = task.next(result);
30
+ }
31
+ return step.value;
32
+ }
33
+ /**
34
+ * Runs a task to completion without awaiting anything: an `all` group's tasks run one after another, and a `wait` on a promise throws, since a synchronous evaluator has nothing to do with one.
35
+ */
36
+ function runSync(task) {
37
+ let step = task.next();
38
+ while (step.done !== true) {
39
+ const suspension = step.value;
40
+ let result;
41
+ if (suspension.kind === "wait") {
42
+ if (isThenable(suspension.value)) throw new TypeError("a resolver supplied to a synchronous evaluator returned a promise; use the asynchronous evaluator for asynchronous resolvers");
43
+ result = suspension.value;
44
+ } else result = suspension.tasks.map(runSync);
45
+ step = task.next(result);
46
+ }
47
+ return step.value;
48
+ }
49
+ //#endregion
50
+ export { all, runAsync, runSync, wait };
@@ -1,5 +1,6 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  const require_evaluator_budget = require("./evaluator-budget.cjs");
3
+ const require_evaluator_effect = require("./evaluator-effect.cjs");
3
4
  const require_evaluator = require("./evaluator.cjs");
4
5
  const require_functions = require("./functions.cjs");
5
6
  //#region src/evaluator-factory.ts
@@ -8,12 +9,22 @@ const require_functions = require("./functions.cjs");
8
9
  */
9
10
  function createEvaluator({ functions = require_functions.emptyFunctionRegistry, maxNodes = require_evaluator_budget.DEFAULT_MAX_EVALUATION_NODES, maxNestingDepth = 500 }) {
10
11
  return {
11
- evaluatePredicate: async (node, context, resolvers) => require_evaluator.evaluatePredicateInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, require_evaluator_budget.createEvaluationBudget(maxNodes, maxNestingDepth), 0),
12
- evaluateValue: async (node, context, resolvers) => require_evaluator.evaluateValueInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, require_evaluator_budget.createEvaluationBudget(maxNodes, maxNestingDepth), 0)
12
+ evaluatePredicate: async (node, context, resolvers) => require_evaluator_effect.runAsync(require_evaluator.evaluatePredicateInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, require_evaluator_budget.createEvaluationBudget(maxNodes, maxNestingDepth), 0)),
13
+ evaluateValue: async (node, context, resolvers) => require_evaluator_effect.runAsync(require_evaluator.evaluateValueInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, require_evaluator_budget.createEvaluationBudget(maxNodes, maxNestingDepth), 0))
14
+ };
15
+ }
16
+ /**
17
+ * The synchronous counterpart of `createEvaluator`: the same node rules, options and `Evaluation` results, over `SyncResolvers`, returning the result directly instead of a promise. It runs the same implementation as the asynchronous evaluator, so the two cannot disagree about a node. One difference follows from having nothing to wait on: independent operands (both sides of an `and`, the candidates of a `memberOf`, the items of a collection) are evaluated one after another rather than concurrently, so when a `maxNodes` or `maxNestingDepth` budget is exhausted partway through a tree, which operand meets the limit first can differ from the asynchronous evaluator.
18
+ */
19
+ function createSyncEvaluator({ functions = require_functions.emptyFunctionRegistry, maxNodes = require_evaluator_budget.DEFAULT_MAX_EVALUATION_NODES, maxNestingDepth = 500 }) {
20
+ return {
21
+ evaluatePredicate: (node, context, resolvers) => require_evaluator_effect.runSync(require_evaluator.evaluatePredicateInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, require_evaluator_budget.createEvaluationBudget(maxNodes, maxNestingDepth), 0)),
22
+ evaluateValue: (node, context, resolvers) => require_evaluator_effect.runSync(require_evaluator.evaluateValueInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, require_evaluator_budget.createEvaluationBudget(maxNodes, maxNestingDepth), 0))
13
23
  };
14
24
  }
15
25
  const { evaluatePredicate, evaluateValue } = createEvaluator({});
16
26
  //#endregion
17
27
  exports.createEvaluator = createEvaluator;
28
+ exports.createSyncEvaluator = createSyncEvaluator;
18
29
  exports.evaluatePredicate = evaluatePredicate;
19
30
  exports.evaluateValue = evaluateValue;
@@ -2,20 +2,32 @@ import { t as ComputedValue } from "./computed-value-CbRF0Izc.cjs";
2
2
  import { ExpressionNode, PredicateNode } from "./tree.cjs";
3
3
  import { Evaluation } from "./evaluation.cjs";
4
4
  import { FunctionRegistry } from "./functions.cjs";
5
- import { EvaluationContext, Resolvers } from "./resolvers.cjs";
5
+ import { EvaluationContext, Resolvers, SyncResolvers } from "./resolvers.cjs";
6
6
  //#region src/evaluator-factory.d.ts
7
7
  /**
8
8
  * Builds a bound `{ evaluatePredicate, evaluateValue }` pair over a caller-supplied function registry for `call` nodes -- the registry is bound once, at construction time, unlike `resolvers`, which are supplied fresh to every call. `maxNodes` and `maxNestingDepth` configure that same pair's own `EvaluationBudget` (see its doc comment in evaluator-budget.ts), created fresh for every top-level `evaluatePredicate`/`evaluateValue` invocation so budgets never leak between unrelated calls. The bare module-level `evaluatePredicate`/`evaluateValue` exports below are `createEvaluator({})`'s output, so both caps default to `DEFAULT_MAX_EVALUATION_NODES`/`DEFAULT_MAX_NESTING_DEPTH` for every caller that does not explicitly configure them.
9
9
  */
10
- export declare function createEvaluator({ functions, maxNodes, maxNestingDepth }: {
10
+ /** Options shared by `createEvaluator` and `createSyncEvaluator`. */
11
+ export interface EvaluatorOptions {
11
12
  functions?: FunctionRegistry;
12
13
  /** Caps the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluationBudget`. Defaults to `DEFAULT_MAX_EVALUATION_NODES`. */
13
14
  maxNodes?: number;
14
15
  /** Caps ordinary recursive-descent nesting depth, independent of `MAX_TREE_REFERENCE_DEPTH`'s own `treeReference` chain-depth cap -- see `createEvaluationBudget`. Defaults to `DEFAULT_MAX_NESTING_DEPTH`. */
15
16
  maxNestingDepth?: number;
16
- }): {
17
+ }
18
+ /**
19
+ * Builds a bound `{ evaluatePredicate, evaluateValue }` pair over a caller-supplied function registry for `call` nodes -- the registry is bound once, at construction time, unlike `resolvers`, which are supplied fresh to every call. `maxNodes` and `maxNestingDepth` configure that same pair's own `EvaluationBudget` (see its doc comment in evaluator-budget.ts), created fresh for every top-level `evaluatePredicate`/`evaluateValue` invocation so budgets never leak between unrelated calls. The bare module-level `evaluatePredicate`/`evaluateValue` exports below are `createEvaluator({})`'s output, so both caps default to `DEFAULT_MAX_EVALUATION_NODES`/`DEFAULT_MAX_NESTING_DEPTH` for every caller that does not explicitly configure them.
20
+ */
21
+ export declare function createEvaluator({ functions, maxNodes, maxNestingDepth }: EvaluatorOptions): {
17
22
  evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>;
18
23
  evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
19
24
  };
25
+ /**
26
+ * The synchronous counterpart of `createEvaluator`: the same node rules, options and `Evaluation` results, over `SyncResolvers`, returning the result directly instead of a promise. It runs the same implementation as the asynchronous evaluator, so the two cannot disagree about a node. One difference follows from having nothing to wait on: independent operands (both sides of an `and`, the candidates of a `memberOf`, the items of a collection) are evaluated one after another rather than concurrently, so when a `maxNodes` or `maxNestingDepth` budget is exhausted partway through a tree, which operand meets the limit first can differ from the asynchronous evaluator.
27
+ */
28
+ export declare function createSyncEvaluator({ functions, maxNodes, maxNestingDepth }: EvaluatorOptions): {
29
+ evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<SyncResolvers>) => Evaluation<boolean>;
30
+ evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<SyncResolvers>) => Evaluation<ComputedValue>;
31
+ };
20
32
  export declare const evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>, evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
21
33
  //#endregion
@@ -2,20 +2,32 @@ import { t as ComputedValue } from "./computed-value-CbRF0Izc.js";
2
2
  import { ExpressionNode, PredicateNode } from "./tree.js";
3
3
  import { Evaluation } from "./evaluation.js";
4
4
  import { FunctionRegistry } from "./functions.js";
5
- import { EvaluationContext, Resolvers } from "./resolvers.js";
5
+ import { EvaluationContext, Resolvers, SyncResolvers } from "./resolvers.js";
6
6
  //#region src/evaluator-factory.d.ts
7
7
  /**
8
8
  * Builds a bound `{ evaluatePredicate, evaluateValue }` pair over a caller-supplied function registry for `call` nodes -- the registry is bound once, at construction time, unlike `resolvers`, which are supplied fresh to every call. `maxNodes` and `maxNestingDepth` configure that same pair's own `EvaluationBudget` (see its doc comment in evaluator-budget.ts), created fresh for every top-level `evaluatePredicate`/`evaluateValue` invocation so budgets never leak between unrelated calls. The bare module-level `evaluatePredicate`/`evaluateValue` exports below are `createEvaluator({})`'s output, so both caps default to `DEFAULT_MAX_EVALUATION_NODES`/`DEFAULT_MAX_NESTING_DEPTH` for every caller that does not explicitly configure them.
9
9
  */
10
- export declare function createEvaluator({ functions, maxNodes, maxNestingDepth }: {
10
+ /** Options shared by `createEvaluator` and `createSyncEvaluator`. */
11
+ export interface EvaluatorOptions {
11
12
  functions?: FunctionRegistry;
12
13
  /** Caps the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluationBudget`. Defaults to `DEFAULT_MAX_EVALUATION_NODES`. */
13
14
  maxNodes?: number;
14
15
  /** Caps ordinary recursive-descent nesting depth, independent of `MAX_TREE_REFERENCE_DEPTH`'s own `treeReference` chain-depth cap -- see `createEvaluationBudget`. Defaults to `DEFAULT_MAX_NESTING_DEPTH`. */
15
16
  maxNestingDepth?: number;
16
- }): {
17
+ }
18
+ /**
19
+ * Builds a bound `{ evaluatePredicate, evaluateValue }` pair over a caller-supplied function registry for `call` nodes -- the registry is bound once, at construction time, unlike `resolvers`, which are supplied fresh to every call. `maxNodes` and `maxNestingDepth` configure that same pair's own `EvaluationBudget` (see its doc comment in evaluator-budget.ts), created fresh for every top-level `evaluatePredicate`/`evaluateValue` invocation so budgets never leak between unrelated calls. The bare module-level `evaluatePredicate`/`evaluateValue` exports below are `createEvaluator({})`'s output, so both caps default to `DEFAULT_MAX_EVALUATION_NODES`/`DEFAULT_MAX_NESTING_DEPTH` for every caller that does not explicitly configure them.
20
+ */
21
+ export declare function createEvaluator({ functions, maxNodes, maxNestingDepth }: EvaluatorOptions): {
17
22
  evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>;
18
23
  evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
19
24
  };
25
+ /**
26
+ * The synchronous counterpart of `createEvaluator`: the same node rules, options and `Evaluation` results, over `SyncResolvers`, returning the result directly instead of a promise. It runs the same implementation as the asynchronous evaluator, so the two cannot disagree about a node. One difference follows from having nothing to wait on: independent operands (both sides of an `and`, the candidates of a `memberOf`, the items of a collection) are evaluated one after another rather than concurrently, so when a `maxNodes` or `maxNestingDepth` budget is exhausted partway through a tree, which operand meets the limit first can differ from the asynchronous evaluator.
27
+ */
28
+ export declare function createSyncEvaluator({ functions, maxNodes, maxNestingDepth }: EvaluatorOptions): {
29
+ evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<SyncResolvers>) => Evaluation<boolean>;
30
+ evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<SyncResolvers>) => Evaluation<ComputedValue>;
31
+ };
20
32
  export declare const evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>, evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
21
33
  //#endregion
@@ -1,4 +1,5 @@
1
1
  import { DEFAULT_MAX_EVALUATION_NODES, createEvaluationBudget } from "./evaluator-budget.js";
2
+ import { runAsync, runSync } from "./evaluator-effect.js";
2
3
  import { evaluatePredicateInternal, evaluateValueInternal } from "./evaluator.js";
3
4
  import { emptyFunctionRegistry } from "./functions.js";
4
5
  //#region src/evaluator-factory.ts
@@ -7,10 +8,19 @@ import { emptyFunctionRegistry } from "./functions.js";
7
8
  */
8
9
  function createEvaluator({ functions = emptyFunctionRegistry, maxNodes = DEFAULT_MAX_EVALUATION_NODES, maxNestingDepth = 500 }) {
9
10
  return {
10
- evaluatePredicate: async (node, context, resolvers) => evaluatePredicateInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, createEvaluationBudget(maxNodes, maxNestingDepth), 0),
11
- evaluateValue: async (node, context, resolvers) => evaluateValueInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, createEvaluationBudget(maxNodes, maxNestingDepth), 0)
11
+ evaluatePredicate: async (node, context, resolvers) => runAsync(evaluatePredicateInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, createEvaluationBudget(maxNodes, maxNestingDepth), 0)),
12
+ evaluateValue: async (node, context, resolvers) => runAsync(evaluateValueInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, createEvaluationBudget(maxNodes, maxNestingDepth), 0))
13
+ };
14
+ }
15
+ /**
16
+ * The synchronous counterpart of `createEvaluator`: the same node rules, options and `Evaluation` results, over `SyncResolvers`, returning the result directly instead of a promise. It runs the same implementation as the asynchronous evaluator, so the two cannot disagree about a node. One difference follows from having nothing to wait on: independent operands (both sides of an `and`, the candidates of a `memberOf`, the items of a collection) are evaluated one after another rather than concurrently, so when a `maxNodes` or `maxNestingDepth` budget is exhausted partway through a tree, which operand meets the limit first can differ from the asynchronous evaluator.
17
+ */
18
+ function createSyncEvaluator({ functions = emptyFunctionRegistry, maxNodes = DEFAULT_MAX_EVALUATION_NODES, maxNestingDepth = 500 }) {
19
+ return {
20
+ evaluatePredicate: (node, context, resolvers) => runSync(evaluatePredicateInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, createEvaluationBudget(maxNodes, maxNestingDepth), 0)),
21
+ evaluateValue: (node, context, resolvers) => runSync(evaluateValueInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0, createEvaluationBudget(maxNodes, maxNestingDepth), 0))
12
22
  };
13
23
  }
14
24
  const { evaluatePredicate, evaluateValue } = createEvaluator({});
15
25
  //#endregion
16
- export { createEvaluator, evaluatePredicate, evaluateValue };
26
+ export { createEvaluator, createSyncEvaluator, evaluatePredicate, evaluateValue };