trilean 1.6.2 → 1.7.0
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 +13 -0
- package/dist/complex.d.cts +5 -6
- package/dist/complex.d.ts +5 -6
- package/dist/derived-aggregates.d.cts +5 -6
- package/dist/derived-aggregates.d.ts +5 -6
- package/dist/derived-connectives.d.cts +10 -11
- package/dist/derived-connectives.d.ts +10 -11
- package/dist/derived-patterns.d.cts +4 -5
- package/dist/derived-patterns.d.ts +4 -5
- package/dist/derived-values.d.cts +2 -3
- package/dist/derived-values.d.ts +2 -3
- package/dist/evaluation.d.cts +7 -8
- package/dist/evaluation.d.ts +7 -8
- package/dist/evaluator-budget.d.cts +6 -7
- package/dist/evaluator-budget.d.ts +6 -7
- package/dist/evaluator-collection.cjs +5 -4
- package/dist/evaluator-collection.d.cts +7 -7
- package/dist/evaluator-collection.d.ts +7 -7
- package/dist/evaluator-collection.js +5 -4
- package/dist/evaluator-effect.cjs +54 -0
- package/dist/evaluator-effect.d.cts +37 -0
- package/dist/evaluator-effect.d.ts +37 -0
- package/dist/evaluator-effect.js +50 -0
- package/dist/evaluator-factory.cjs +13 -2
- package/dist/evaluator-factory.d.cts +17 -6
- package/dist/evaluator-factory.d.ts +17 -6
- package/dist/evaluator-factory.js +13 -3
- package/dist/evaluator-indeterminacy-helpers.d.cts +26 -27
- package/dist/evaluator-indeterminacy-helpers.d.ts +26 -27
- package/dist/evaluator-operations.d.cts +10 -11
- package/dist/evaluator-operations.d.ts +10 -11
- package/dist/evaluator-test-helpers.d.cts +6 -7
- package/dist/evaluator-test-helpers.d.ts +6 -7
- package/dist/evaluator.cjs +43 -40
- package/dist/evaluator.d.cts +5 -5
- package/dist/evaluator.d.ts +5 -5
- package/dist/evaluator.js +43 -40
- package/dist/functions.d.cts +3 -4
- package/dist/functions.d.ts +3 -4
- package/dist/index.cjs +1 -0
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/resolvers.d.cts +22 -6
- package/dist/resolvers.d.ts +22 -6
- package/dist/tree.d.cts +77 -78
- package/dist/tree.d.ts +77 -78
- package/package.json +3 -3
- package/schemas/trilean.schema.json +1 -1
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).
|
package/dist/complex.d.cts
CHANGED
|
@@ -12,12 +12,11 @@ type ComplexValue = Extract<ComputedValue, {
|
|
|
12
12
|
type NumberValue = Extract<ComputedValue, {
|
|
13
13
|
kind: "number";
|
|
14
14
|
}>;
|
|
15
|
-
declare const complexFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexValue;
|
|
15
|
+
export declare const complexFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexValue;
|
|
16
16
|
/** The `complexLiteral` node counterpart of `complexFromPolar`, for authoring a tree in polar terms; the conversion itself is done once, there, rather than repeated here. */
|
|
17
|
-
declare const complexLiteralFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexLiteralNode;
|
|
17
|
+
export declare const complexLiteralFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexLiteralNode;
|
|
18
18
|
/** |z|, as a real number in the same unit the complex value itself carries -- the magnitude of an impedance in ohms is a real quantity in ohms. */
|
|
19
|
-
declare const complexMagnitude: (value: ComplexValue) => NumberValue;
|
|
19
|
+
export declare const complexMagnitude: (value: ComplexValue) => NumberValue;
|
|
20
20
|
/** arg(z), as a dimensionless real number of radians: an angle is a ratio of two lengths, so it carries no unit of its own regardless of what the value it was read from carried. */
|
|
21
|
-
declare const complexPhase: (value: ComplexValue) => NumberValue;
|
|
22
|
-
//#endregion
|
|
23
|
-
export { complexFromPolar, complexLiteralFromPolar, complexMagnitude, complexPhase };
|
|
21
|
+
export declare const complexPhase: (value: ComplexValue) => NumberValue;
|
|
22
|
+
//#endregion
|
package/dist/complex.d.ts
CHANGED
|
@@ -12,12 +12,11 @@ type ComplexValue = Extract<ComputedValue, {
|
|
|
12
12
|
type NumberValue = Extract<ComputedValue, {
|
|
13
13
|
kind: "number";
|
|
14
14
|
}>;
|
|
15
|
-
declare const complexFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexValue;
|
|
15
|
+
export declare const complexFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexValue;
|
|
16
16
|
/** The `complexLiteral` node counterpart of `complexFromPolar`, for authoring a tree in polar terms; the conversion itself is done once, there, rather than repeated here. */
|
|
17
|
-
declare const complexLiteralFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexLiteralNode;
|
|
17
|
+
export declare const complexLiteralFromPolar: (magnitude: number, phase: number, unit?: Unit) => ComplexLiteralNode;
|
|
18
18
|
/** |z|, as a real number in the same unit the complex value itself carries -- the magnitude of an impedance in ohms is a real quantity in ohms. */
|
|
19
|
-
declare const complexMagnitude: (value: ComplexValue) => NumberValue;
|
|
19
|
+
export declare const complexMagnitude: (value: ComplexValue) => NumberValue;
|
|
20
20
|
/** arg(z), as a dimensionless real number of radians: an angle is a ratio of two lengths, so it carries no unit of its own regardless of what the value it was read from carried. */
|
|
21
|
-
declare const complexPhase: (value: ComplexValue) => NumberValue;
|
|
22
|
-
//#endregion
|
|
23
|
-
export { complexFromPolar, complexLiteralFromPolar, complexMagnitude, complexPhase };
|
|
21
|
+
export declare const complexPhase: (value: ComplexValue) => NumberValue;
|
|
22
|
+
//#endregion
|
|
@@ -4,9 +4,8 @@ import { ExpressionNode, PredicateNode } from "./tree.cjs";
|
|
|
4
4
|
/**
|
|
5
5
|
* `sum`, `count`, and `average` are never their own `FoldCombiner` mode -- each is a builder function that assembles an ordinary `fold` (and, for `average`, one `arithmetic` division of two ordinary folds), exactly the same treatment `derived-connectives.ts` already gives `xor`/`nand`/`nor`/`implies`/`iff`/`none` (see the "Derived aggregates" section of README.md).
|
|
6
6
|
*/
|
|
7
|
-
declare const sum: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
8
|
-
declare const presenceOf: (probe: ExpressionNode) => ExpressionNode;
|
|
9
|
-
declare const count: (collection: JsonValue, filter?: PredicateNode, probe?: ExpressionNode) => ExpressionNode;
|
|
10
|
-
declare const average: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
11
|
-
//#endregion
|
|
12
|
-
export { average, count, presenceOf, sum };
|
|
7
|
+
export declare const sum: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
8
|
+
export declare const presenceOf: (probe: ExpressionNode) => ExpressionNode;
|
|
9
|
+
export declare const count: (collection: JsonValue, filter?: PredicateNode, probe?: ExpressionNode) => ExpressionNode;
|
|
10
|
+
export declare const average: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
11
|
+
//#endregion
|
|
@@ -4,9 +4,8 @@ import { ExpressionNode, PredicateNode } from "./tree.js";
|
|
|
4
4
|
/**
|
|
5
5
|
* `sum`, `count`, and `average` are never their own `FoldCombiner` mode -- each is a builder function that assembles an ordinary `fold` (and, for `average`, one `arithmetic` division of two ordinary folds), exactly the same treatment `derived-connectives.ts` already gives `xor`/`nand`/`nor`/`implies`/`iff`/`none` (see the "Derived aggregates" section of README.md).
|
|
6
6
|
*/
|
|
7
|
-
declare const sum: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
8
|
-
declare const presenceOf: (probe: ExpressionNode) => ExpressionNode;
|
|
9
|
-
declare const count: (collection: JsonValue, filter?: PredicateNode, probe?: ExpressionNode) => ExpressionNode;
|
|
10
|
-
declare const average: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
11
|
-
//#endregion
|
|
12
|
-
export { average, count, presenceOf, sum };
|
|
7
|
+
export declare const sum: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
8
|
+
export declare const presenceOf: (probe: ExpressionNode) => ExpressionNode;
|
|
9
|
+
export declare const count: (collection: JsonValue, filter?: PredicateNode, probe?: ExpressionNode) => ExpressionNode;
|
|
10
|
+
export declare const average: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
|
|
11
|
+
//#endregion
|
|
@@ -4,14 +4,13 @@ import { PredicateNode } from "./tree.cjs";
|
|
|
4
4
|
/**
|
|
5
5
|
* `not`/`and`/`or` are the primitive `PredicateNode` object-constructors -- everything else in this file is built purely by composing these three, so its three-valued correctness is inherited from the already-verified AND/OR/NOT tables rather than requiring a separate proof (see the "Derived connectives" section of README.md).
|
|
6
6
|
*/
|
|
7
|
-
declare const not: (a: PredicateNode) => PredicateNode;
|
|
8
|
-
declare const and: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
9
|
-
declare const or: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
10
|
-
declare const xor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
11
|
-
declare const nand: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
12
|
-
declare const nor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
13
|
-
declare const implies: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
14
|
-
declare const iff: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
15
|
-
declare const none: (collection: JsonValue, item: PredicateNode, filter?: PredicateNode) => PredicateNode;
|
|
16
|
-
//#endregion
|
|
17
|
-
export { and, iff, implies, nand, none, nor, not, or, xor };
|
|
7
|
+
export declare const not: (a: PredicateNode) => PredicateNode;
|
|
8
|
+
export declare const and: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
9
|
+
export declare const or: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
10
|
+
export declare const xor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
11
|
+
export declare const nand: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
12
|
+
export declare const nor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
13
|
+
export declare const implies: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
14
|
+
export declare const iff: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
15
|
+
export declare const none: (collection: JsonValue, item: PredicateNode, filter?: PredicateNode) => PredicateNode;
|
|
16
|
+
//#endregion
|
|
@@ -4,14 +4,13 @@ import { PredicateNode } from "./tree.js";
|
|
|
4
4
|
/**
|
|
5
5
|
* `not`/`and`/`or` are the primitive `PredicateNode` object-constructors -- everything else in this file is built purely by composing these three, so its three-valued correctness is inherited from the already-verified AND/OR/NOT tables rather than requiring a separate proof (see the "Derived connectives" section of README.md).
|
|
6
6
|
*/
|
|
7
|
-
declare const not: (a: PredicateNode) => PredicateNode;
|
|
8
|
-
declare const and: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
9
|
-
declare const or: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
10
|
-
declare const xor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
11
|
-
declare const nand: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
12
|
-
declare const nor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
13
|
-
declare const implies: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
14
|
-
declare const iff: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
15
|
-
declare const none: (collection: JsonValue, item: PredicateNode, filter?: PredicateNode) => PredicateNode;
|
|
16
|
-
//#endregion
|
|
17
|
-
export { and, iff, implies, nand, none, nor, not, or, xor };
|
|
7
|
+
export declare const not: (a: PredicateNode) => PredicateNode;
|
|
8
|
+
export declare const and: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
9
|
+
export declare const or: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
10
|
+
export declare const xor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
11
|
+
export declare const nand: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
12
|
+
export declare const nor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
13
|
+
export declare const implies: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
14
|
+
export declare const iff: (a: PredicateNode, b: PredicateNode) => PredicateNode;
|
|
15
|
+
export declare const none: (collection: JsonValue, item: PredicateNode, filter?: PredicateNode) => PredicateNode;
|
|
16
|
+
//#endregion
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { ExpressionNode, PredicateNode } from "./tree.cjs";
|
|
2
2
|
//#region src/derived-patterns.d.ts
|
|
3
|
-
declare const prefixPattern: (text: ExpressionNode, prefix: string) => PredicateNode;
|
|
4
|
-
declare const wildcardPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
5
|
-
declare const hierarchicalGlobPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
6
|
-
//#endregion
|
|
7
|
-
export { hierarchicalGlobPattern, prefixPattern, wildcardPattern };
|
|
3
|
+
export declare const prefixPattern: (text: ExpressionNode, prefix: string) => PredicateNode;
|
|
4
|
+
export declare const wildcardPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
5
|
+
export declare const hierarchicalGlobPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
6
|
+
//#endregion
|
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { ExpressionNode, PredicateNode } from "./tree.js";
|
|
2
2
|
//#region src/derived-patterns.d.ts
|
|
3
|
-
declare const prefixPattern: (text: ExpressionNode, prefix: string) => PredicateNode;
|
|
4
|
-
declare const wildcardPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
5
|
-
declare const hierarchicalGlobPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
6
|
-
//#endregion
|
|
7
|
-
export { hierarchicalGlobPattern, prefixPattern, wildcardPattern };
|
|
3
|
+
export declare const prefixPattern: (text: ExpressionNode, prefix: string) => PredicateNode;
|
|
4
|
+
export declare const wildcardPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
5
|
+
export declare const hierarchicalGlobPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
|
|
6
|
+
//#endregion
|
|
@@ -5,6 +5,5 @@ import { ExpressionNode } from "./tree.cjs";
|
|
|
5
5
|
*
|
|
6
6
|
* Built right-to-left over the full `[first, second, ...rest]` candidate list via `reduceRight`, which needs no seed value here -- `first`/`second` being required arguments (rather than accepting a single `ExpressionNode[]`) guarantees the list always has at least two elements, so the no-initial-value overload of `reduceRight` never hits an empty array.
|
|
7
7
|
*/
|
|
8
|
-
declare const coalesce: (first: ExpressionNode, second: ExpressionNode, ...rest: readonly ExpressionNode[]) => ExpressionNode;
|
|
9
|
-
//#endregion
|
|
10
|
-
export { coalesce };
|
|
8
|
+
export declare const coalesce: (first: ExpressionNode, second: ExpressionNode, ...rest: readonly ExpressionNode[]) => ExpressionNode;
|
|
9
|
+
//#endregion
|
package/dist/derived-values.d.ts
CHANGED
|
@@ -5,6 +5,5 @@ import { ExpressionNode } from "./tree.js";
|
|
|
5
5
|
*
|
|
6
6
|
* Built right-to-left over the full `[first, second, ...rest]` candidate list via `reduceRight`, which needs no seed value here -- `first`/`second` being required arguments (rather than accepting a single `ExpressionNode[]`) guarantees the list always has at least two elements, so the no-initial-value overload of `reduceRight` never hits an empty array.
|
|
7
7
|
*/
|
|
8
|
-
declare const coalesce: (first: ExpressionNode, second: ExpressionNode, ...rest: readonly ExpressionNode[]) => ExpressionNode;
|
|
9
|
-
//#endregion
|
|
10
|
-
export { coalesce };
|
|
8
|
+
export declare const coalesce: (first: ExpressionNode, second: ExpressionNode, ...rest: readonly ExpressionNode[]) => ExpressionNode;
|
|
9
|
+
//#endregion
|
package/dist/evaluation.d.cts
CHANGED
|
@@ -3,14 +3,14 @@ import { z } from "zod";
|
|
|
3
3
|
/**
|
|
4
4
|
* Every evaluation -- of a predicate node or an expression node -- produces exactly one of two outcomes: a definite result, or an indeterminate result carrying a reason. Never a bare boolean/number, and never a thrown exception for a data-quality problem.
|
|
5
5
|
*/
|
|
6
|
-
type Evaluation<T> = {
|
|
6
|
+
export type Evaluation<T> = {
|
|
7
7
|
status: "definite";
|
|
8
8
|
value: T;
|
|
9
9
|
} | {
|
|
10
10
|
status: "indeterminate";
|
|
11
11
|
reason: IndeterminateReason;
|
|
12
12
|
};
|
|
13
|
-
declare const IndeterminateReasonSchema: z.ZodObject<{
|
|
13
|
+
export declare const IndeterminateReasonSchema: z.ZodObject<{
|
|
14
14
|
code: z.ZodEnum<{
|
|
15
15
|
"not-found": "not-found";
|
|
16
16
|
"wrong-type": "wrong-type";
|
|
@@ -18,12 +18,11 @@ declare const IndeterminateReasonSchema: z.ZodObject<{
|
|
|
18
18
|
}>;
|
|
19
19
|
message: z.ZodString;
|
|
20
20
|
}, z.core.$strip>;
|
|
21
|
-
type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
|
|
22
|
-
declare function definite<T>(value: T): Evaluation<T>;
|
|
23
|
-
declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
|
|
21
|
+
export type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
|
|
22
|
+
export declare function definite<T>(value: T): Evaluation<T>;
|
|
23
|
+
export declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
|
|
24
24
|
/**
|
|
25
25
|
* Implements the tie-break rule from "The evaluation model": when several sub-evaluations could each independently be indeterminate for a different reason, take the first indeterminate reason encountered in the node's own declared operand order. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
|
|
26
26
|
*/
|
|
27
|
-
declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
|
|
28
|
-
//#endregion
|
|
29
|
-
export { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate };
|
|
27
|
+
export declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
|
|
28
|
+
//#endregion
|
package/dist/evaluation.d.ts
CHANGED
|
@@ -3,14 +3,14 @@ import { z } from "zod";
|
|
|
3
3
|
/**
|
|
4
4
|
* Every evaluation -- of a predicate node or an expression node -- produces exactly one of two outcomes: a definite result, or an indeterminate result carrying a reason. Never a bare boolean/number, and never a thrown exception for a data-quality problem.
|
|
5
5
|
*/
|
|
6
|
-
type Evaluation<T> = {
|
|
6
|
+
export type Evaluation<T> = {
|
|
7
7
|
status: "definite";
|
|
8
8
|
value: T;
|
|
9
9
|
} | {
|
|
10
10
|
status: "indeterminate";
|
|
11
11
|
reason: IndeterminateReason;
|
|
12
12
|
};
|
|
13
|
-
declare const IndeterminateReasonSchema: z.ZodObject<{
|
|
13
|
+
export declare const IndeterminateReasonSchema: z.ZodObject<{
|
|
14
14
|
code: z.ZodEnum<{
|
|
15
15
|
"not-found": "not-found";
|
|
16
16
|
"wrong-type": "wrong-type";
|
|
@@ -18,12 +18,11 @@ declare const IndeterminateReasonSchema: z.ZodObject<{
|
|
|
18
18
|
}>;
|
|
19
19
|
message: z.ZodString;
|
|
20
20
|
}, z.core.$strip>;
|
|
21
|
-
type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
|
|
22
|
-
declare function definite<T>(value: T): Evaluation<T>;
|
|
23
|
-
declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
|
|
21
|
+
export type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
|
|
22
|
+
export declare function definite<T>(value: T): Evaluation<T>;
|
|
23
|
+
export declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
|
|
24
24
|
/**
|
|
25
25
|
* Implements the tie-break rule from "The evaluation model": when several sub-evaluations could each independently be indeterminate for a different reason, take the first indeterminate reason encountered in the node's own declared operand order. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
|
|
26
26
|
*/
|
|
27
|
-
declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
|
|
28
|
-
//#endregion
|
|
29
|
-
export { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate };
|
|
27
|
+
export declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
|
|
28
|
+
//#endregion
|
|
@@ -1,21 +1,20 @@
|
|
|
1
1
|
import { Evaluation } from "./evaluation.cjs";
|
|
2
2
|
//#region src/evaluator-budget.d.ts
|
|
3
3
|
/** A defense-in-depth guard against a long acyclic `treeReference` chain exhausting the call stack -- distinct from, and layered on top of, the cycle detector in evaluator.ts (`visitedTreeKeys`), which catches an actual repeat immediately and more precisely. */
|
|
4
|
-
declare const MAX_TREE_REFERENCE_DEPTH = 100;
|
|
4
|
+
export declare const MAX_TREE_REFERENCE_DEPTH = 100;
|
|
5
5
|
/** Default cap on the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluator`'s `maxNodes` option, threaded through to `createEvaluationBudget` below. Chosen generously above any realistic hand-authored business-rule, eligibility, or formula tree (see README.md's own consumer use cases), while still bounding an untrusted, adversarially-authored tree's total evaluation cost to a fixed, small amount of work regardless of how it is shaped. */
|
|
6
|
-
declare const DEFAULT_MAX_EVALUATION_NODES = 10000;
|
|
6
|
+
export declare const DEFAULT_MAX_EVALUATION_NODES = 10000;
|
|
7
7
|
/** Default cap on ordinary recursive-descent nesting depth -- see `createEvaluator`'s `maxNestingDepth` option, threaded through to `createEvaluationBudget` below. Set comfortably below the depth at which this evaluator's own recursive descent has been observed to exhaust the host call stack (a chain of plain `not` nodes wrapped around a single leaf, evaluated directly against this file under Node.js, failed consistently somewhere in the low thousands of nesting levels, with some run-to-run variance from whatever else already occupied the stack), while remaining far deeper than any legitimate hand-authored tree is ever likely to nest. Kept well clear of that measured failure point because the exact threshold varies by host runtime (a Cloudflare Workers isolate's own stack is smaller than Node's) and by how much of the stack the rest of the call chain has already used. */
|
|
8
|
-
declare const DEFAULT_MAX_NESTING_DEPTH = 500;
|
|
8
|
+
export declare const DEFAULT_MAX_NESTING_DEPTH = 500;
|
|
9
9
|
/**
|
|
10
10
|
* A single `evaluatePredicate`/`evaluateValue` call's resource limits, independent of and layered underneath `MAX_TREE_REFERENCE_DEPTH`'s own cross-tree chain guard above: that guard only advances at an actual `treeReference` resolution and says nothing about a plain, self-contained tree built from ordinary `and`/`or`/`fold`/`conditional`/quantifier nesting, with no `treeReference` node anywhere in it. This closes that gap for a consumer evaluating a tree it did not author and cannot fully trust before evaluation (e.g. a tree embedded in a signed but otherwise attacker-controlled payload).
|
|
11
11
|
*
|
|
12
12
|
* Exposed as a single `checkNode` method rather than a raw mutable counter, following the same all-callback shape `Resolvers` and `FunctionRegistry` use in evaluator.ts: every recursive call site threads this object through as `Readonly<EvaluationBudget>`, and that wrapper genuinely prevents tampering because the running node count lives in `createEvaluationBudget`'s own closure, never as an assignable property on the object itself.
|
|
13
13
|
*/
|
|
14
|
-
interface EvaluationBudget {
|
|
14
|
+
export interface EvaluationBudget {
|
|
15
15
|
/** Charges one node visit and checks both caps, returning the `Evaluation` to return immediately if either is now exceeded, or `undefined` if evaluation of this node may proceed. Called as the very first action inside `evaluatePredicateInternal`/`evaluateValueInternal`, before any of that node's own work or further recursion, so an exceeded budget is discovered before it can be spent on additional descent. */
|
|
16
16
|
checkNode: (nestingDepth: number) => Evaluation<never> | undefined;
|
|
17
17
|
}
|
|
18
18
|
/** Constructs a fresh `EvaluationBudget` for one top-level `evaluatePredicate`/`evaluateValue` call -- see `createEvaluator`'s `maxNodes`/`maxNestingDepth` options, which supply `maxNodes`/`maxNestingDepth` here. A fresh closure per call is what keeps `nodesVisited` from leaking between unrelated evaluations. */
|
|
19
|
-
declare function createEvaluationBudget(maxNodes: number, maxNestingDepth: number): EvaluationBudget;
|
|
20
|
-
//#endregion
|
|
21
|
-
export { DEFAULT_MAX_EVALUATION_NODES, DEFAULT_MAX_NESTING_DEPTH, EvaluationBudget, MAX_TREE_REFERENCE_DEPTH, createEvaluationBudget };
|
|
19
|
+
export declare function createEvaluationBudget(maxNodes: number, maxNestingDepth: number): EvaluationBudget;
|
|
20
|
+
//#endregion
|
|
@@ -1,21 +1,20 @@
|
|
|
1
1
|
import { Evaluation } from "./evaluation.js";
|
|
2
2
|
//#region src/evaluator-budget.d.ts
|
|
3
3
|
/** A defense-in-depth guard against a long acyclic `treeReference` chain exhausting the call stack -- distinct from, and layered on top of, the cycle detector in evaluator.ts (`visitedTreeKeys`), which catches an actual repeat immediately and more precisely. */
|
|
4
|
-
declare const MAX_TREE_REFERENCE_DEPTH = 100;
|
|
4
|
+
export declare const MAX_TREE_REFERENCE_DEPTH = 100;
|
|
5
5
|
/** Default cap on the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluator`'s `maxNodes` option, threaded through to `createEvaluationBudget` below. Chosen generously above any realistic hand-authored business-rule, eligibility, or formula tree (see README.md's own consumer use cases), while still bounding an untrusted, adversarially-authored tree's total evaluation cost to a fixed, small amount of work regardless of how it is shaped. */
|
|
6
|
-
declare const DEFAULT_MAX_EVALUATION_NODES = 10000;
|
|
6
|
+
export declare const DEFAULT_MAX_EVALUATION_NODES = 10000;
|
|
7
7
|
/** Default cap on ordinary recursive-descent nesting depth -- see `createEvaluator`'s `maxNestingDepth` option, threaded through to `createEvaluationBudget` below. Set comfortably below the depth at which this evaluator's own recursive descent has been observed to exhaust the host call stack (a chain of plain `not` nodes wrapped around a single leaf, evaluated directly against this file under Node.js, failed consistently somewhere in the low thousands of nesting levels, with some run-to-run variance from whatever else already occupied the stack), while remaining far deeper than any legitimate hand-authored tree is ever likely to nest. Kept well clear of that measured failure point because the exact threshold varies by host runtime (a Cloudflare Workers isolate's own stack is smaller than Node's) and by how much of the stack the rest of the call chain has already used. */
|
|
8
|
-
declare const DEFAULT_MAX_NESTING_DEPTH = 500;
|
|
8
|
+
export declare const DEFAULT_MAX_NESTING_DEPTH = 500;
|
|
9
9
|
/**
|
|
10
10
|
* A single `evaluatePredicate`/`evaluateValue` call's resource limits, independent of and layered underneath `MAX_TREE_REFERENCE_DEPTH`'s own cross-tree chain guard above: that guard only advances at an actual `treeReference` resolution and says nothing about a plain, self-contained tree built from ordinary `and`/`or`/`fold`/`conditional`/quantifier nesting, with no `treeReference` node anywhere in it. This closes that gap for a consumer evaluating a tree it did not author and cannot fully trust before evaluation (e.g. a tree embedded in a signed but otherwise attacker-controlled payload).
|
|
11
11
|
*
|
|
12
12
|
* Exposed as a single `checkNode` method rather than a raw mutable counter, following the same all-callback shape `Resolvers` and `FunctionRegistry` use in evaluator.ts: every recursive call site threads this object through as `Readonly<EvaluationBudget>`, and that wrapper genuinely prevents tampering because the running node count lives in `createEvaluationBudget`'s own closure, never as an assignable property on the object itself.
|
|
13
13
|
*/
|
|
14
|
-
interface EvaluationBudget {
|
|
14
|
+
export interface EvaluationBudget {
|
|
15
15
|
/** Charges one node visit and checks both caps, returning the `Evaluation` to return immediately if either is now exceeded, or `undefined` if evaluation of this node may proceed. Called as the very first action inside `evaluatePredicateInternal`/`evaluateValueInternal`, before any of that node's own work or further recursion, so an exceeded budget is discovered before it can be spent on additional descent. */
|
|
16
16
|
checkNode: (nestingDepth: number) => Evaluation<never> | undefined;
|
|
17
17
|
}
|
|
18
18
|
/** Constructs a fresh `EvaluationBudget` for one top-level `evaluatePredicate`/`evaluateValue` call -- see `createEvaluator`'s `maxNodes`/`maxNestingDepth` options, which supply `maxNodes`/`maxNestingDepth` here. A fresh closure per call is what keeps `nodesVisited` from leaking between unrelated evaluations. */
|
|
19
|
-
declare function createEvaluationBudget(maxNodes: number, maxNestingDepth: number): EvaluationBudget;
|
|
20
|
-
//#endregion
|
|
21
|
-
export { DEFAULT_MAX_EVALUATION_NODES, DEFAULT_MAX_NESTING_DEPTH, EvaluationBudget, MAX_TREE_REFERENCE_DEPTH, createEvaluationBudget };
|
|
19
|
+
export declare function createEvaluationBudget(maxNodes: number, maxNestingDepth: number): EvaluationBudget;
|
|
20
|
+
//#endregion
|
|
@@ -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
|
-
|
|
7
|
-
const candidates =
|
|
8
|
-
return
|
|
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 =
|
|
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,20 +4,20 @@ 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 {
|
|
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
|
-
type EvaluatePredicate = (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<
|
|
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
|
-
interface ResolvedCollectionItem {
|
|
13
|
+
export interface ResolvedCollectionItem {
|
|
13
14
|
readonly item: unknown;
|
|
14
15
|
readonly filterOutcome: "include" | "exclude" | Evaluation<never>;
|
|
15
16
|
}
|
|
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
|
-
declare function resolveParticipatingItems(evaluatePredicate: EvaluatePredicate, collection: JsonValue, filter: PredicateNode | undefined, context: EvaluationContext, resolvers: Readonly<
|
|
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
|
-
declare function firstFilterIndeterminate(participating: readonly ResolvedCollectionItem[]): IndeterminateReason | undefined;
|
|
22
|
-
//#endregion
|
|
23
|
-
export { EvaluatePredicate, ResolvedCollectionItem, firstFilterIndeterminate, resolveParticipatingItems };
|
|
22
|
+
export declare function firstFilterIndeterminate(participating: readonly ResolvedCollectionItem[]): IndeterminateReason | undefined;
|
|
23
|
+
//#endregion
|
|
@@ -4,20 +4,20 @@ 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 {
|
|
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
|
-
type EvaluatePredicate = (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<
|
|
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
|
-
interface ResolvedCollectionItem {
|
|
13
|
+
export interface ResolvedCollectionItem {
|
|
13
14
|
readonly item: unknown;
|
|
14
15
|
readonly filterOutcome: "include" | "exclude" | Evaluation<never>;
|
|
15
16
|
}
|
|
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
|
-
declare function resolveParticipatingItems(evaluatePredicate: EvaluatePredicate, collection: JsonValue, filter: PredicateNode | undefined, context: EvaluationContext, resolvers: Readonly<
|
|
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
|
-
declare function firstFilterIndeterminate(participating: readonly ResolvedCollectionItem[]): IndeterminateReason | undefined;
|
|
22
|
-
//#endregion
|
|
23
|
-
export { EvaluatePredicate, ResolvedCollectionItem, firstFilterIndeterminate, resolveParticipatingItems };
|
|
22
|
+
export declare function firstFilterIndeterminate(participating: readonly ResolvedCollectionItem[]): IndeterminateReason | undefined;
|
|
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
|
-
|
|
6
|
-
const candidates =
|
|
7
|
-
return
|
|
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 =
|
|
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
|