trilean 1.10.1 → 1.11.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
@@ -225,28 +225,31 @@ type Evaluation<T> =
225
225
  | { status: "indeterminate"; reason: IndeterminateReason };
226
226
 
227
227
  interface IndeterminateReason {
228
- /** Which of the three reason categories applies. */
229
- code: "not-found" | "wrong-type" | "domain-error";
228
+ /** Which of the four reason categories applies. */
229
+ code: "not-found" | "not-yet-known" | "wrong-type" | "domain-error";
230
230
  /** A human-readable explanation, for logging and debugging. */
231
231
  message: string;
232
232
  }
233
233
  ```
234
234
 
235
- The three reason codes are:
235
+ The four reason codes are:
236
236
 
237
237
  | Code | Meaning |
238
238
  |---|---|
239
239
  | `not-found` | A value a node needed did not exist in the underlying data at all. |
240
+ | `not-yet-known` | A value a node needed has not been supplied yet, so it may exist later. Unlike the other three, this is a statement about the evaluation's input rather than about the data: evaluating a partial assignment, a resolver reports a value it has not been given with `{ found: false, notYetKnown: true }` (see [Resolvers](#resolvers)), and the result is indeterminate with this code until it is. |
240
241
  | `wrong-type` | A value existed but was not of a kind the operation could use (e.g. non-numeric where a number was required). |
241
242
  | `domain-error` | A mathematical operation was attempted outside its valid domain (division by zero, a function given an input outside its allowed range, an aggregation with nothing to aggregate). |
242
243
 
244
+ `not-yet-known` propagates exactly as `not-found` does, except in [`exists`](#exists), which stays indeterminate on it instead of answering `false`. That is what makes a definite result on a partial assignment safe to act on: whatever the values still to come turn out to be, the result on the completed assignment is the same (the Kleene monotonicity property), including through [`coalesce`](#derived-values), which therefore waits for an earlier candidate instead of falling through to the next.
245
+
243
246
  `domain-error` is not a separate error type, exception, or crash — it uses exactly the same `Evaluation`/`IndeterminateReason` mechanism as the other two. This three-outcome model applies uniformly to every node kind in both trees: arithmetic, comparison, and boolean logic alike. It never collapses to a plain boolean or number at any intermediate point inside the tree; only the code that consumes the final top-level `Evaluation` decides what to do with an indeterminate outcome (reject, default, surface to a user, etc.) — that decision is deliberately outside this package's scope.
244
247
 
245
248
  **Infrastructure failures are a different concern.** If a resolver itself throws (a network error, a database outage), that propagates as an ordinary rejected promise from `evaluatePredicate`/`evaluateValue`, exactly like any other function call failure. The three-outcome model exists to describe *data-quality* states inside the domain being modelled — it does not, and should not, attempt to also model transport-level failure.
246
249
 
247
250
  ### Where an indeterminate outcome can carry more than one candidate reason
248
251
 
249
- Some nodes combine several sub-evaluations that could each independently be indeterminate for a different reason (e.g. an `and` node whose both operands are indeterminate, one `not-found` and one `wrong-type`). This design resolves ties with a single, consistently-applied rule: **take the first indeterminate reason encountered in the node's own declared operand order** (left before right; list order for N-ary/collection operands). This is an implementation decision this document makes explicitly, once, so every node kind's evaluator can apply the same rule without re-deriving it.
252
+ Some nodes combine several sub-evaluations that could each independently be indeterminate for a different reason (e.g. an `and` node whose both operands are indeterminate, one `not-found` and one `wrong-type`). This design resolves ties with a single, consistently-applied rule: **take the first indeterminate reason encountered in the node's own declared operand order** (left before right; list order for N-ary/collection operands), with one exception: `not-yet-known` outranks every other reason in the nodes where a later operand could still absorb an indeterminate one (`and`, `or`, `allOf`, `anyOf`, `some`, `every`, `memberOf` and a `unique` `conditional`). Reporting `not-found` there while another operand is not yet known would be wrong, because that operand might settle as an absorbing value and turn the node definite, after `exists` had already reported its absence. In every other node an earlier reason is final, since no later operand can change the outcome, so the first one is kept. This is an implementation decision this document makes explicitly, once, so every node kind's evaluator can apply the same rule without re-deriving it.
250
253
 
251
254
  ## Three-valued propagation rules
252
255
 
@@ -445,7 +448,7 @@ Evaluate `operand` first; if it is indeterminate, the whole leaf is indeterminat
445
448
 
446
449
  ### `exists`
447
450
 
448
- Evaluates `true` if the given `ExpressionNode` can be resolved to some value at all, `false` if it definitely cannot be resolved (the data point is genuinely absent), independent of whether that value would itself be usable in further computation. Concretely: evaluate the operand; if the result is definite, `exists` is `true`; if the result is indeterminate with reason `not-found`, `exists` is `false`; if the result is indeterminate with reason `wrong-type` or `domain-error`, `exists` is still `true` — the underlying data point *did* resolve to something, it merely wasn't usable for whatever computation was attempted around it, which is exactly why section [The evaluation model](#the-evaluation-model) distinguishes "did not exist" from "existed but unusable" in the first place. `exists` itself is never indeterminate — it always produces a definite boolean.
451
+ Evaluates `true` if the given `ExpressionNode` can be resolved to some value at all, `false` if it definitely cannot be resolved (the data point is genuinely absent), independent of whether that value would itself be usable in further computation. Concretely: evaluate the operand; if the result is definite, `exists` is `true`; if the result is indeterminate with reason `not-found`, `exists` is `false`; if the result is indeterminate with reason `wrong-type` or `domain-error`, `exists` is still `true` — the underlying data point *did* resolve to something, it merely wasn't usable for whatever computation was attempted around it, which is exactly why section [The evaluation model](#the-evaluation-model) distinguishes "did not exist" from "existed but unusable" in the first place. If the result is indeterminate with reason `not-yet-known`, `exists` is indeterminate with that same reason: the value may still arrive, so neither `true` nor `false` is yet an answer a later evaluation could not contradict. `exists` is otherwise never indeterminate, and always produces a definite boolean for a value that is known to be present or known to be absent.
449
452
 
450
453
  ### `some`, `every`
451
454
 
@@ -590,7 +593,7 @@ A piecewise/conditional-value node: an ordered, possibly-empty list of `{ when,
590
593
  **`hitPolicy: "unique"`** asserts that at most one case is expected to match, and treats two or more matches as a data error rather than silently taking the first. Every case's `when` is evaluated concurrently (there is no "earlier case" to short-circuit on), then resolved in this order:
591
594
 
592
595
  1. **Two or more cases are definitely `true`** — `domain-error` ("more than one case matched under the 'unique' hit policy"), regardless of any other case's own indeterminacy. This mirrors `memberOf`/`some`/`every`'s existing absorption: a confirmed outcome (here, "there is a genuine ambiguity") cannot be undone by an unrelated case's data problem.
593
- 2. Otherwise, **any case's `when` is indeterminate** — the whole node is indeterminate with that reason (first such candidate, in declared case order, per [The evaluation model](#the-evaluation-model)'s tie-break rule). This is deliberately **not** absorbed by a single already-confirmed match, unlike step 1 above and unlike `memberOf`/`some`/`every`'s own absorption: an unresolved case might still turn out to be a second match, so "exactly one match so far" cannot be trusted as final until every other case is known to not also match.
596
+ 2. Otherwise, **any case's `when` is indeterminate** — the whole node is indeterminate with that reason (first such candidate, in declared case order, per [The evaluation model](#the-evaluation-model)'s tie-break rule, where a `not-yet-known` case outranks the others). This is deliberately **not** absorbed by a single already-confirmed match, unlike step 1 above and unlike `memberOf`/`some`/`every`'s own absorption: an unresolved case might still turn out to be a second match, so "exactly one match so far" cannot be trusted as final until every other case is known to not also match.
594
597
  3. Otherwise, **exactly one case is definitely `true`** — evaluate and return that case's `then`. No other case's `then` is ever evaluated.
595
598
  4. Otherwise (zero matches, and nothing indeterminate) — evaluate and return `fallback`, exactly as `"first"` already does.
596
599
 
@@ -692,10 +695,11 @@ Built right-to-left over the full candidate list via `reduceRight`, needing no s
692
695
  |---|---|---|---|
693
696
  | A definite value | definite `true` | matches | The candidate's value (re-evaluated as `then`, same result) |
694
697
  | Indeterminate, `not-found` | definite `false` | does not match | The next candidate (the enclosing `fallback`), evaluated fresh |
698
+ | Indeterminate, `not-yet-known` | indeterminate `not-yet-known` | indeterminate, so the `conditional` is | Indeterminate `not-yet-known`: the later candidates are not reached while this one may still turn out to exist |
695
699
  | Indeterminate, `wrong-type` | definite `true` | matches | The candidate's own `wrong-type` result (re-evaluated as `then`) |
696
700
  | Indeterminate, `domain-error` | definite `true` | matches | The candidate's own `domain-error` result (re-evaluated as `then`) |
697
701
 
698
- Falling through to the next candidate therefore happens only on `exists`'s own `false` — a genuinely absent value (`not-found`) — never on a candidate that resolved to something merely unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line, and `coalesce` inherits it unmodified rather than re-deciding it. This is the one behaviour a naive reimplementation is likely to get backwards (treating *any* indeterminate candidate as "try the next one"), so it is worth stating explicitly rather than leaving it to be inferred from the composition alone.
702
+ Falling through to the next candidate therefore happens only on `exists`'s own `false` — a genuinely absent value (`not-found`) — never on a candidate that resolved to something merely unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line, and `coalesce` inherits it unmodified rather than re-deciding it. This is the one behaviour a naive reimplementation is likely to get backwards (treating *any* indeterminate candidate as "try the next one"), so it is worth stating explicitly rather than leaving it to be inferred from the composition alone. A candidate that is `not-yet-known` is neither skipped nor propagated as its own value: the whole `coalesce` is indeterminate with that reason until the candidate is known, because falling through to the next candidate now would give an answer the candidate's arrival could change.
699
703
 
700
704
  A real implementation may memoise a candidate's single evaluation rather than running its resolver twice — once for the `exists` probe, once again for `then` — exactly the same performance caveat [Derived aggregates](#derived-aggregates)'s `presenceOf` already documents for its own `memberOf` probe; resolvers are pure functions of their inputs throughout this design, so this is a performance choice, not a correctness one.
701
705
 
@@ -765,13 +769,15 @@ An item whose `filter` is itself indeterminate is never silently included or exc
765
769
  Three core, required points of extension, plus two further independent optional ones, each supplied separately by the embedding consumer, each treated by the schema as pure data to hand over — never as resolver logic living inside the schema itself:
766
770
 
767
771
  ```ts
768
- type Resolution =
769
- | { found: true; value: ComputedValue }
770
- | { found: false };
772
+ type Absence = {
773
+ found: false;
774
+ /** `true`: the value has not been supplied yet and may exist later. Absent or `false`: it is known to be absent. */
775
+ notYetKnown?: boolean;
776
+ };
777
+
778
+ type Resolution = { found: true; value: ComputedValue } | Absence;
771
779
 
772
- type TreeResolution =
773
- | { found: true; node: JsonValue }
774
- | { found: false };
780
+ type TreeResolution = { found: true; node: JsonValue } | Absence;
775
781
 
776
782
  interface Resolvers {
777
783
  /** Resolver 1 — a single opaque key to a single value (IV.reference). */
@@ -795,6 +801,8 @@ interface Resolvers {
795
801
 
796
802
  `resolveTree` returns a `TreeResolution`, deliberately shaped like `Resolution` but distinct from it: `node` carries opaque JSON — the referenced tree, re-validated by the evaluator rather than trusted (see [`treeReference`](#treereference)) — where `Resolution`'s `value` carries an already-typed `ComputedValue`. It is otherwise the same "found" envelope for the same reason: a `treeReference`'s absence needs to be distinguishable from any tree the resolver might otherwise legitimately return, exactly as a `reference`'s absence needs to be distinguishable from any value. `resolveDelegate` and `resolveTree` solve different problems and are never a substitute for one another: `resolveDelegate` hands a payload to an *external* system this package never evaluates; `resolveTree` hands back *more of this same schema*, for this same evaluator to keep evaluating.
797
803
 
804
+ A resolver reports a value it has no answer for in one of two ways, and the difference is the one between a fact about the data and a fact about the evaluation. `{ found: false }` says the value is known to be absent: the result is indeterminate `not-found`, and [`exists`](#exists) answers `false`. `{ found: false, notYetKnown: true }` says the value has not been supplied yet: the result is indeterminate `not-yet-known` and `exists` stays indeterminate. A consumer evaluating a partial assignment (some inputs supplied, the rest still to come) reports every unsupplied input the second way, so a definite result it gets back holds for every way the remaining inputs could turn out. `resolveValue`, `resolveLookup`, `resolveDelegate` and `resolveTree` can each report it, in both the asynchronous and the synchronous flavour; `resolveCollection` cannot, since it has no absence to report (an empty list is its own answer) and a collection that is not yet known is better modelled by not evaluating the node that needs it.
805
+
798
806
  ## Evaluator entry points
799
807
 
800
808
  ```ts
@@ -859,6 +867,8 @@ The node rules are written once and run by either driver, so the two evaluators
859
867
 
860
868
  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).
861
869
 
870
+ `not-yet-known` has no column of its own because it arises at exactly the sites where `not-found` does (a `reference`, `lookup`, `delegate` or `treeReference` whose resolver reports `notYetKnown: true`) and then propagates through every row below exactly as `not-found` does, absorbed by the same definite values. The only rows where it differs are `exists`, which is indeterminate with that reason instead of answering `false`, and the nodes where the tie-break rule above ranks it first. `coalesce` is `exists` composed with `conditional`, so it follows `exists`.
871
+
862
872
  | Node kind | `not-found` | `wrong-type` | `domain-error` |
863
873
  |---|---|---|---|
864
874
  | `not` | propagates from operand | propagates from operand | propagates from operand |
@@ -1,7 +1,7 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  //#region src/derived-values.ts
3
3
  /**
4
- * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it.
4
+ * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it. A candidate that is `not-yet-known` (a resolver reported it as not yet supplied) is not a known absence, so `exists` is indeterminate on it and the whole `coalesce` stays indeterminate: falling through would answer with a later candidate that the earlier one's arrival could displace.
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
  */
@@ -1,7 +1,7 @@
1
1
  import { ExpressionNode } from "./tree.cjs";
2
2
  //#region src/derived-values.d.ts
3
3
  /**
4
- * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it.
4
+ * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it. A candidate that is `not-yet-known` (a resolver reported it as not yet supplied) is not a known absence, so `exists` is indeterminate on it and the whole `coalesce` stays indeterminate: falling through would answer with a later candidate that the earlier one's arrival could displace.
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
  */
@@ -1,7 +1,7 @@
1
1
  import { ExpressionNode } from "./tree.js";
2
2
  //#region src/derived-values.d.ts
3
3
  /**
4
- * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it.
4
+ * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it. A candidate that is `not-yet-known` (a resolver reported it as not yet supplied) is not a known absence, so `exists` is indeterminate on it and the whole `coalesce` stays indeterminate: falling through would answer with a later candidate that the earlier one's arrival could displace.
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
  */
@@ -1,6 +1,6 @@
1
1
  //#region src/derived-values.ts
2
2
  /**
3
- * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it.
3
+ * `coalesce` is never its own evaluated node kind -- it assembles an ordinary `conditional` whose single case's `when` is an `exists` probe of the current candidate, the same "derived = composition, not new logic" treatment derived-connectives.ts and derived-aggregates.ts already give `xor`/`sum`/`average` (see the "Derived values" section of README.md). Falling through to the next candidate happens only on `exists`'s own `false` -- a genuinely absent value (`not-found`) -- never on a candidate that resolved to something unusable (`wrong-type`/`domain-error`): `exists` already draws exactly that line (see the `exists` section of README.md), and `coalesce` inherits it unmodified rather than re-deciding it. A candidate that is `not-yet-known` (a resolver reported it as not yet supplied) is not a known absence, so `exists` is indeterminate on it and the whole `coalesce` stays indeterminate: falling through would answer with a later candidate that the earlier one's arrival could displace.
4
4
  *
5
5
  * 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.
6
6
  */
@@ -2,9 +2,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  let zod = require("zod");
3
3
  //#region src/evaluation.ts
4
4
  const IndeterminateReasonSchema = zod.z.object({
5
- /** Which of the three reason categories applies. */
5
+ /** Which of the four reason categories applies. `not-yet-known` is the only one that is not a property of the data: it says a resolver has not been supplied the value yet, so a later evaluation may settle it either way. */
6
6
  code: zod.z.enum([
7
7
  "not-found",
8
+ "not-yet-known",
8
9
  "wrong-type",
9
10
  "domain-error"
10
11
  ]),
@@ -27,10 +28,18 @@ function indeterminate(code, message) {
27
28
  };
28
29
  }
29
30
  /**
30
- * 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.
31
+ * 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, except that a `not-yet-known` reason outranks every other. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
32
+ *
33
+ * The exception exists because this function is only called where a later outcome can still absorb an indeterminate one (`and`, `or`, `memberOf`, a `unique` conditional). Reporting `not-found` for such a node while another operand is still `not-yet-known` would be wrong: that operand might settle as a definite absorbing value, and the node would then be definite where `exists` had already reported its absence. Preferring `not-yet-known` keeps every non-`not-yet-known` reason a statement that no completion of the unknown values can overturn.
31
34
  */
32
35
  function firstIndeterminate(...results) {
33
- for (const result of results) if (result?.status === "indeterminate") return result.reason;
36
+ let first;
37
+ for (const result of results) {
38
+ if (result?.status !== "indeterminate") continue;
39
+ if (result.reason.code === "not-yet-known") return result.reason;
40
+ first ??= result.reason;
41
+ }
42
+ return first;
34
43
  }
35
44
  //#endregion
36
45
  exports.IndeterminateReasonSchema = IndeterminateReasonSchema;
@@ -13,6 +13,7 @@ export type Evaluation<T> = {
13
13
  export declare const IndeterminateReasonSchema: z.ZodObject<{
14
14
  code: z.ZodEnum<{
15
15
  "not-found": "not-found";
16
+ "not-yet-known": "not-yet-known";
16
17
  "wrong-type": "wrong-type";
17
18
  "domain-error": "domain-error";
18
19
  }>;
@@ -22,7 +23,9 @@ export type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
22
23
  export declare function definite<T>(value: T): Evaluation<T>;
23
24
  export declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
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
+ * 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, except that a `not-yet-known` reason outranks every other. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
27
+ *
28
+ * The exception exists because this function is only called where a later outcome can still absorb an indeterminate one (`and`, `or`, `memberOf`, a `unique` conditional). Reporting `not-found` for such a node while another operand is still `not-yet-known` would be wrong: that operand might settle as a definite absorbing value, and the node would then be definite where `exists` had already reported its absence. Preferring `not-yet-known` keeps every non-`not-yet-known` reason a statement that no completion of the unknown values can overturn.
26
29
  */
27
30
  export declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
28
31
  //#endregion
@@ -13,6 +13,7 @@ export type Evaluation<T> = {
13
13
  export declare const IndeterminateReasonSchema: z.ZodObject<{
14
14
  code: z.ZodEnum<{
15
15
  "not-found": "not-found";
16
+ "not-yet-known": "not-yet-known";
16
17
  "wrong-type": "wrong-type";
17
18
  "domain-error": "domain-error";
18
19
  }>;
@@ -22,7 +23,9 @@ export type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
22
23
  export declare function definite<T>(value: T): Evaluation<T>;
23
24
  export declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
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
+ * 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, except that a `not-yet-known` reason outranks every other. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
27
+ *
28
+ * The exception exists because this function is only called where a later outcome can still absorb an indeterminate one (`and`, `or`, `memberOf`, a `unique` conditional). Reporting `not-found` for such a node while another operand is still `not-yet-known` would be wrong: that operand might settle as a definite absorbing value, and the node would then be definite where `exists` had already reported its absence. Preferring `not-yet-known` keeps every non-`not-yet-known` reason a statement that no completion of the unknown values can overturn.
26
29
  */
27
30
  export declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
28
31
  //#endregion
@@ -1,9 +1,10 @@
1
1
  import { z } from "zod";
2
2
  //#region src/evaluation.ts
3
3
  const IndeterminateReasonSchema = z.object({
4
- /** Which of the three reason categories applies. */
4
+ /** Which of the four reason categories applies. `not-yet-known` is the only one that is not a property of the data: it says a resolver has not been supplied the value yet, so a later evaluation may settle it either way. */
5
5
  code: z.enum([
6
6
  "not-found",
7
+ "not-yet-known",
7
8
  "wrong-type",
8
9
  "domain-error"
9
10
  ]),
@@ -26,10 +27,18 @@ function indeterminate(code, message) {
26
27
  };
27
28
  }
28
29
  /**
29
- * 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.
30
+ * 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, except that a `not-yet-known` reason outranks every other. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
31
+ *
32
+ * The exception exists because this function is only called where a later outcome can still absorb an indeterminate one (`and`, `or`, `memberOf`, a `unique` conditional). Reporting `not-found` for such a node while another operand is still `not-yet-known` would be wrong: that operand might settle as a definite absorbing value, and the node would then be definite where `exists` had already reported its absence. Preferring `not-yet-known` keeps every non-`not-yet-known` reason a statement that no completion of the unknown values can overturn.
30
33
  */
31
34
  function firstIndeterminate(...results) {
32
- for (const result of results) if (result?.status === "indeterminate") return result.reason;
35
+ let first;
36
+ for (const result of results) {
37
+ if (result?.status !== "indeterminate") continue;
38
+ if (result.reason.code === "not-yet-known") return result.reason;
39
+ first ??= result.reason;
40
+ }
41
+ return first;
33
42
  }
34
43
  //#endregion
35
44
  export { IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate };
@@ -6,6 +6,10 @@ const require_evaluation = require("./evaluation.cjs");
6
6
  const require_integer_power = require("./integer-power.cjs");
7
7
  let trilean_regex = require("trilean-regex");
8
8
  //#region src/evaluator-operations.ts
9
+ /** The indeterminate result for a resolver's report of absence: `not-yet-known` when the resolver said the value has not been supplied yet, `not-found` otherwise. The two share every propagation rule except `exists` (and so `coalesce`), which is why every resolver call site goes through this one function. */
10
+ function absenceEvaluation(absence, notFoundMessage, notYetKnownMessage) {
11
+ return absence.notYetKnown === true ? require_evaluation.indeterminate("not-yet-known", notYetKnownMessage) : require_evaluation.indeterminate("not-found", notFoundMessage);
12
+ }
9
13
  /** The three-valued AND table: `false` is absorbing regardless of the other operand's indeterminacy; otherwise both-definite folds to a boolean AND; otherwise indeterminate, with the tie-break rule (declared operand order, left before right) applied via `firstIndeterminate`. */
10
14
  function combineAnd(left, right) {
11
15
  if (left.status === "definite" && !left.value) return require_evaluation.definite(false);
@@ -425,6 +429,7 @@ function invokeRegisteredFunction(functions, fnName, args) {
425
429
  return require_evaluation.definite(outcome);
426
430
  }
427
431
  //#endregion
432
+ exports.absenceEvaluation = absenceEvaluation;
428
433
  exports.applyArithmetic = applyArithmetic;
429
434
  exports.applyNegate = applyNegate;
430
435
  exports.checkReferenceUnit = checkReferenceUnit;
@@ -2,7 +2,10 @@ import { a as Unit, t as ComputedValue } from "./computed-value-CbRF0Izc.cjs";
2
2
  import { FunctionRegistry } from "./functions.cjs";
3
3
  import { ArithmeticOperator, ComparisonOperator, TextComparisonOperator } from "./tree.cjs";
4
4
  import { Evaluation } from "./evaluation.cjs";
5
+ import { Absence } from "./resolvers.cjs";
5
6
  //#region src/evaluator-operations.d.ts
7
+ /** The indeterminate result for a resolver's report of absence: `not-yet-known` when the resolver said the value has not been supplied yet, `not-found` otherwise. The two share every propagation rule except `exists` (and so `coalesce`), which is why every resolver call site goes through this one function. */
8
+ export declare function absenceEvaluation(absence: Readonly<Absence>, notFoundMessage: string, notYetKnownMessage: string): Evaluation<never>;
6
9
  /** The three-valued AND table: `false` is absorbing regardless of the other operand's indeterminacy; otherwise both-definite folds to a boolean AND; otherwise indeterminate, with the tie-break rule (declared operand order, left before right) applied via `firstIndeterminate`. */
7
10
  export declare function combineAnd(left: Evaluation<boolean>, right: Evaluation<boolean>): Evaluation<boolean>;
8
11
  /** The three-valued OR table: mirror image of `combineAnd`, with `true` absorbing. */
@@ -2,7 +2,10 @@ import { a as Unit, t as ComputedValue } from "./computed-value-CbRF0Izc.js";
2
2
  import { FunctionRegistry } from "./functions.js";
3
3
  import { ArithmeticOperator, ComparisonOperator, TextComparisonOperator } from "./tree.js";
4
4
  import { Evaluation } from "./evaluation.js";
5
+ import { Absence } from "./resolvers.js";
5
6
  //#region src/evaluator-operations.d.ts
7
+ /** The indeterminate result for a resolver's report of absence: `not-yet-known` when the resolver said the value has not been supplied yet, `not-found` otherwise. The two share every propagation rule except `exists` (and so `coalesce`), which is why every resolver call site goes through this one function. */
8
+ export declare function absenceEvaluation(absence: Readonly<Absence>, notFoundMessage: string, notYetKnownMessage: string): Evaluation<never>;
6
9
  /** The three-valued AND table: `false` is absorbing regardless of the other operand's indeterminacy; otherwise both-definite folds to a boolean AND; otherwise indeterminate, with the tie-break rule (declared operand order, left before right) applied via `firstIndeterminate`. */
7
10
  export declare function combineAnd(left: Evaluation<boolean>, right: Evaluation<boolean>): Evaluation<boolean>;
8
11
  /** The three-valued OR table: mirror image of `combineAnd`, with `true` absorbing. */
@@ -5,6 +5,10 @@ import { definite, firstIndeterminate, indeterminate } from "./evaluation.js";
5
5
  import { powerByRepeatedSquaring } from "./integer-power.js";
6
6
  import { RegexParseError, compilePattern } from "trilean-regex";
7
7
  //#region src/evaluator-operations.ts
8
+ /** The indeterminate result for a resolver's report of absence: `not-yet-known` when the resolver said the value has not been supplied yet, `not-found` otherwise. The two share every propagation rule except `exists` (and so `coalesce`), which is why every resolver call site goes through this one function. */
9
+ function absenceEvaluation(absence, notFoundMessage, notYetKnownMessage) {
10
+ return absence.notYetKnown === true ? indeterminate("not-yet-known", notYetKnownMessage) : indeterminate("not-found", notFoundMessage);
11
+ }
8
12
  /** The three-valued AND table: `false` is absorbing regardless of the other operand's indeterminacy; otherwise both-definite folds to a boolean AND; otherwise indeterminate, with the tie-break rule (declared operand order, left before right) applied via `firstIndeterminate`. */
9
13
  function combineAnd(left, right) {
10
14
  if (left.status === "definite" && !left.value) return definite(false);
@@ -424,4 +428,4 @@ function invokeRegisteredFunction(functions, fnName, args) {
424
428
  return definite(outcome);
425
429
  }
426
430
  //#endregion
427
- export { applyArithmetic, applyNegate, checkReferenceUnit, combineAnd, combineOr, compareText, compareValues, computeMembershipMatch, invokeRegisteredFunction };
431
+ export { absenceEvaluation, applyArithmetic, applyNegate, checkReferenceUnit, combineAnd, combineOr, compareText, compareValues, computeMembershipMatch, invokeRegisteredFunction };
@@ -59,7 +59,10 @@ function* evaluatePredicateInternal(node, context, resolvers, accumulator, funct
59
59
  }
60
60
  case "exists": {
61
61
  const operandResult = yield* evaluateValueInternal(node.operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth + 1);
62
- if (operandResult.status === "indeterminate" && operandResult.reason.code === "not-found") return require_evaluation.definite(false);
62
+ if (operandResult.status === "indeterminate") {
63
+ if (operandResult.reason.code === "not-yet-known") return operandResult;
64
+ if (operandResult.reason.code === "not-found") return require_evaluation.definite(false);
65
+ }
63
66
  return require_evaluation.definite(true);
64
67
  }
65
68
  case "some":
@@ -80,7 +83,7 @@ function* evaluatePredicateInternal(node, context, resolvers, accumulator, funct
80
83
  if (visitedTreeKeys.has(keyString)) return require_evaluation.indeterminate("domain-error", "circular treeReference detected");
81
84
  if (treeReferenceDepth >= 100) return require_evaluation.indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${100 .toString()}`);
82
85
  const resolution = yield* require_evaluator_effect.wait(resolvers.resolveTree(node.key, context));
83
- if (!resolution.found) return require_evaluation.indeterminate("not-found", "treeReference key did not resolve to a tree");
86
+ if (!resolution.found) return require_evaluator_operations.absenceEvaluation(resolution, "treeReference key did not resolve to a tree", "the tree for the treeReference key is not yet known");
84
87
  const parsed = require_tree.PredicateNodeSchema.safeParse(resolution.node);
85
88
  if (!parsed.success) return require_evaluation.indeterminate("wrong-type", "the referenced tree is not a valid PredicateNode");
86
89
  return yield* evaluatePredicateInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1, budget, nestingDepth + 1);
@@ -94,7 +97,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
94
97
  switch (node.kind) {
95
98
  case "reference": {
96
99
  const resolution = yield* require_evaluator_effect.wait(resolvers.resolveValue(node.key, context));
97
- if (!resolution.found) return require_evaluation.indeterminate("not-found", `no value found for reference key ${JSON.stringify(node.key)}`);
100
+ if (!resolution.found) return require_evaluator_operations.absenceEvaluation(resolution, `no value found for reference key ${JSON.stringify(node.key)}`, `the value for reference key ${JSON.stringify(node.key)} is not yet known`);
98
101
  const unitError = require_evaluator_operations.checkReferenceUnit(node.unit, resolution.value);
99
102
  if (unitError !== void 0) return unitError;
100
103
  return require_evaluation.definite(resolution.value);
@@ -160,7 +163,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
160
163
  keyValues.push(result.value);
161
164
  }
162
165
  const resolution = yield* require_evaluator_effect.wait(resolvers.resolveLookup(node.table, keyValues, context));
163
- if (!resolution.found) return require_evaluation.indeterminate("not-found", `no match found in lookup table ${JSON.stringify(node.table)}`);
166
+ if (!resolution.found) return require_evaluator_operations.absenceEvaluation(resolution, `no match found in lookup table ${JSON.stringify(node.table)}`, `the match in lookup table ${JSON.stringify(node.table)} is not yet known`);
164
167
  return require_evaluation.definite(resolution.value);
165
168
  }
166
169
  case "conditional": {
@@ -228,7 +231,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
228
231
  case "delegate": {
229
232
  if (resolvers.resolveDelegate === void 0) return require_evaluation.indeterminate("wrong-type", `no delegate handler registered for external system '${node.system}'`);
230
233
  const resolution = yield* require_evaluator_effect.wait(resolvers.resolveDelegate(node.system, node.payload, context));
231
- if (!resolution.found) return require_evaluation.indeterminate("not-found", `delegate handler for external system '${node.system}' reported no value`);
234
+ if (!resolution.found) return require_evaluator_operations.absenceEvaluation(resolution, `delegate handler for external system '${node.system}' reported no value`, `the value from the delegate handler for external system '${node.system}' is not yet known`);
232
235
  return require_evaluation.definite(resolution.value);
233
236
  }
234
237
  case "treeReference": {
@@ -237,7 +240,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
237
240
  if (visitedTreeKeys.has(keyString)) return require_evaluation.indeterminate("domain-error", "circular treeReference detected");
238
241
  if (treeReferenceDepth >= 100) return require_evaluation.indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${100 .toString()}`);
239
242
  const resolution = yield* require_evaluator_effect.wait(resolvers.resolveTree(node.key, context));
240
- if (!resolution.found) return require_evaluation.indeterminate("not-found", "treeReference key did not resolve to a tree");
243
+ if (!resolution.found) return require_evaluator_operations.absenceEvaluation(resolution, "treeReference key did not resolve to a tree", "the tree for the treeReference key is not yet known");
241
244
  const parsed = require_tree.ExpressionNodeSchema.safeParse(resolution.node);
242
245
  if (!parsed.success) return require_evaluation.indeterminate("wrong-type", "the referenced tree is not a valid ExpressionNode");
243
246
  return yield* evaluateValueInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1, budget, nestingDepth + 1);
package/dist/evaluator.js CHANGED
@@ -3,7 +3,7 @@ import { definite, firstIndeterminate, indeterminate } from "./evaluation.js";
3
3
  import "./evaluator-budget.js";
4
4
  import { all, wait } from "./evaluator-effect.js";
5
5
  import { firstFilterIndeterminate, resolveParticipatingItems } from "./evaluator-collection.js";
6
- import { applyArithmetic, applyNegate, checkReferenceUnit, combineAnd, combineOr, compareText, compareValues, computeMembershipMatch, invokeRegisteredFunction } from "./evaluator-operations.js";
6
+ import { absenceEvaluation, applyArithmetic, applyNegate, checkReferenceUnit, combineAnd, combineOr, compareText, compareValues, computeMembershipMatch, invokeRegisteredFunction } from "./evaluator-operations.js";
7
7
  import { ExpressionNodeSchema, PredicateNodeSchema } from "./tree.js";
8
8
  //#region src/evaluator.ts
9
9
  /**
@@ -58,7 +58,10 @@ function* evaluatePredicateInternal(node, context, resolvers, accumulator, funct
58
58
  }
59
59
  case "exists": {
60
60
  const operandResult = yield* evaluateValueInternal(node.operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth + 1);
61
- if (operandResult.status === "indeterminate" && operandResult.reason.code === "not-found") return definite(false);
61
+ if (operandResult.status === "indeterminate") {
62
+ if (operandResult.reason.code === "not-yet-known") return operandResult;
63
+ if (operandResult.reason.code === "not-found") return definite(false);
64
+ }
62
65
  return definite(true);
63
66
  }
64
67
  case "some":
@@ -79,7 +82,7 @@ function* evaluatePredicateInternal(node, context, resolvers, accumulator, funct
79
82
  if (visitedTreeKeys.has(keyString)) return indeterminate("domain-error", "circular treeReference detected");
80
83
  if (treeReferenceDepth >= 100) return indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${100 .toString()}`);
81
84
  const resolution = yield* wait(resolvers.resolveTree(node.key, context));
82
- if (!resolution.found) return indeterminate("not-found", "treeReference key did not resolve to a tree");
85
+ if (!resolution.found) return absenceEvaluation(resolution, "treeReference key did not resolve to a tree", "the tree for the treeReference key is not yet known");
83
86
  const parsed = PredicateNodeSchema.safeParse(resolution.node);
84
87
  if (!parsed.success) return indeterminate("wrong-type", "the referenced tree is not a valid PredicateNode");
85
88
  return yield* evaluatePredicateInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1, budget, nestingDepth + 1);
@@ -93,7 +96,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
93
96
  switch (node.kind) {
94
97
  case "reference": {
95
98
  const resolution = yield* wait(resolvers.resolveValue(node.key, context));
96
- if (!resolution.found) return indeterminate("not-found", `no value found for reference key ${JSON.stringify(node.key)}`);
99
+ if (!resolution.found) return absenceEvaluation(resolution, `no value found for reference key ${JSON.stringify(node.key)}`, `the value for reference key ${JSON.stringify(node.key)} is not yet known`);
97
100
  const unitError = checkReferenceUnit(node.unit, resolution.value);
98
101
  if (unitError !== void 0) return unitError;
99
102
  return definite(resolution.value);
@@ -159,7 +162,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
159
162
  keyValues.push(result.value);
160
163
  }
161
164
  const resolution = yield* wait(resolvers.resolveLookup(node.table, keyValues, context));
162
- if (!resolution.found) return indeterminate("not-found", `no match found in lookup table ${JSON.stringify(node.table)}`);
165
+ if (!resolution.found) return absenceEvaluation(resolution, `no match found in lookup table ${JSON.stringify(node.table)}`, `the match in lookup table ${JSON.stringify(node.table)} is not yet known`);
163
166
  return definite(resolution.value);
164
167
  }
165
168
  case "conditional": {
@@ -227,7 +230,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
227
230
  case "delegate": {
228
231
  if (resolvers.resolveDelegate === void 0) return indeterminate("wrong-type", `no delegate handler registered for external system '${node.system}'`);
229
232
  const resolution = yield* wait(resolvers.resolveDelegate(node.system, node.payload, context));
230
- if (!resolution.found) return indeterminate("not-found", `delegate handler for external system '${node.system}' reported no value`);
233
+ if (!resolution.found) return absenceEvaluation(resolution, `delegate handler for external system '${node.system}' reported no value`, `the value from the delegate handler for external system '${node.system}' is not yet known`);
231
234
  return definite(resolution.value);
232
235
  }
233
236
  case "treeReference": {
@@ -236,7 +239,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
236
239
  if (visitedTreeKeys.has(keyString)) return indeterminate("domain-error", "circular treeReference detected");
237
240
  if (treeReferenceDepth >= 100) return indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${100 .toString()}`);
238
241
  const resolution = yield* wait(resolvers.resolveTree(node.key, context));
239
- if (!resolution.found) return indeterminate("not-found", "treeReference key did not resolve to a tree");
242
+ if (!resolution.found) return absenceEvaluation(resolution, "treeReference key did not resolve to a tree", "the tree for the treeReference key is not yet known");
240
243
  const parsed = ExpressionNodeSchema.safeParse(resolution.node);
241
244
  if (!parsed.success) return indeterminate("wrong-type", "the referenced tree is not a valid ExpressionNode");
242
245
  return yield* evaluateValueInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1, budget, nestingDepth + 1);
package/dist/index.d.cts CHANGED
@@ -10,7 +10,7 @@ import { hierarchicalGlobPattern, prefixPattern, wildcardPattern } from "./deriv
10
10
  import { coalesce } from "./derived-values.cjs";
11
11
  import { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate } from "./evaluation.cjs";
12
12
  import { DocumentEvaluation, EvaluateDocumentOptions, TreeKind, evaluateDocument } from "./evaluate-document.cjs";
13
- import { EvaluationContext, Resolution, Resolvers, SyncResolvers, TreeResolution } from "./resolvers.cjs";
13
+ import { Absence, EvaluationContext, Resolution, Resolvers, SyncResolvers, TreeResolution } from "./resolvers.cjs";
14
14
  import { EvaluatorOptions, createEvaluator, createSyncEvaluator, evaluatePredicate, evaluateValue } from "./evaluator-factory.cjs";
15
15
  import { InputItem, InputsParseResult, createInputResolvers, parseInputs } from "./input-resolvers.cjs";
16
- export { type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type BooleanLiteralNode, BooleanLiteralNodeSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComplexLiteralNode, ComplexLiteralNodeSchema, type ComplexPolarLiteralNode, ComplexPolarLiteralNodeSchema, type ComplexRectangularLiteralNode, ComplexRectangularLiteralNodeSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DocumentEvaluation, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type EvaluateDocumentOptions, type Evaluation, type EvaluationContext, type EvaluatorOptions, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionFailure, type FunctionRegistry, type HitPolicy, HitPolicySchema, type IndeterminateReason, IndeterminateReasonSchema, type InputItem, type InputsParseResult, type InstantLiteralNode, InstantLiteralNodeSchema, type JsonValue, JsonValueSchema, type LookupNode, LookupNodeSchema, type MemberOfNode, MemberOfNodeSchema, type MembershipOperator, MembershipOperatorSchema, type NegateNode, NegateNodeSchema, type NotNode, NotNodeSchema, type NumberLiteralNode, NumberLiteralNodeSchema, type OrNode, OrNodeSchema, type PredicateNode, PredicateNodeSchema, type ReferenceNode, ReferenceNodeSchema, type Resolution, type Resolvers, type SomeNode, SomeNodeSchema, type SyncResolvers, type TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type TreeKind, type TreeReferenceNode, TreeReferenceNodeSchema, type TreeResolution, type Unit, UnitSchema, and, average, builtinFunctions, coalesce, combineUnitsForDivide, combineUnitsForMultiply, complexFromPolar, complexLiteralFromPolar, complexMagnitude, complexPhase, count, createEvaluator, createInputResolvers, createSyncEvaluator, definite, emptyFunctionRegistry, evaluateDocument, evaluatePredicate, evaluateValue, firstIndeterminate, hierarchicalGlobPattern, iff, implies, indeterminate, nand, none, nor, not, or, parseInputs, prefixPattern, presenceOf, sum, unitsEqual, wildcardPattern, xor };
16
+ export { type Absence, type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type BooleanLiteralNode, BooleanLiteralNodeSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComplexLiteralNode, ComplexLiteralNodeSchema, type ComplexPolarLiteralNode, ComplexPolarLiteralNodeSchema, type ComplexRectangularLiteralNode, ComplexRectangularLiteralNodeSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DocumentEvaluation, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type EvaluateDocumentOptions, type Evaluation, type EvaluationContext, type EvaluatorOptions, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionFailure, type FunctionRegistry, type HitPolicy, HitPolicySchema, type IndeterminateReason, IndeterminateReasonSchema, type InputItem, type InputsParseResult, type InstantLiteralNode, InstantLiteralNodeSchema, type JsonValue, JsonValueSchema, type LookupNode, LookupNodeSchema, type MemberOfNode, MemberOfNodeSchema, type MembershipOperator, MembershipOperatorSchema, type NegateNode, NegateNodeSchema, type NotNode, NotNodeSchema, type NumberLiteralNode, NumberLiteralNodeSchema, type OrNode, OrNodeSchema, type PredicateNode, PredicateNodeSchema, type ReferenceNode, ReferenceNodeSchema, type Resolution, type Resolvers, type SomeNode, SomeNodeSchema, type SyncResolvers, type TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type TreeKind, type TreeReferenceNode, TreeReferenceNodeSchema, type TreeResolution, type Unit, UnitSchema, and, average, builtinFunctions, coalesce, combineUnitsForDivide, combineUnitsForMultiply, complexFromPolar, complexLiteralFromPolar, complexMagnitude, complexPhase, count, createEvaluator, createInputResolvers, createSyncEvaluator, definite, emptyFunctionRegistry, evaluateDocument, evaluatePredicate, evaluateValue, firstIndeterminate, hierarchicalGlobPattern, iff, implies, indeterminate, nand, none, nor, not, or, parseInputs, prefixPattern, presenceOf, sum, unitsEqual, wildcardPattern, xor };
package/dist/index.d.ts CHANGED
@@ -10,7 +10,7 @@ import { hierarchicalGlobPattern, prefixPattern, wildcardPattern } from "./deriv
10
10
  import { coalesce } from "./derived-values.js";
11
11
  import { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate } from "./evaluation.js";
12
12
  import { DocumentEvaluation, EvaluateDocumentOptions, TreeKind, evaluateDocument } from "./evaluate-document.js";
13
- import { EvaluationContext, Resolution, Resolvers, SyncResolvers, TreeResolution } from "./resolvers.js";
13
+ import { Absence, EvaluationContext, Resolution, Resolvers, SyncResolvers, TreeResolution } from "./resolvers.js";
14
14
  import { EvaluatorOptions, createEvaluator, createSyncEvaluator, evaluatePredicate, evaluateValue } from "./evaluator-factory.js";
15
15
  import { InputItem, InputsParseResult, createInputResolvers, parseInputs } from "./input-resolvers.js";
16
- export { type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type BooleanLiteralNode, BooleanLiteralNodeSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComplexLiteralNode, ComplexLiteralNodeSchema, type ComplexPolarLiteralNode, ComplexPolarLiteralNodeSchema, type ComplexRectangularLiteralNode, ComplexRectangularLiteralNodeSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DocumentEvaluation, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type EvaluateDocumentOptions, type Evaluation, type EvaluationContext, type EvaluatorOptions, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionFailure, type FunctionRegistry, type HitPolicy, HitPolicySchema, type IndeterminateReason, IndeterminateReasonSchema, type InputItem, type InputsParseResult, type InstantLiteralNode, InstantLiteralNodeSchema, type JsonValue, JsonValueSchema, type LookupNode, LookupNodeSchema, type MemberOfNode, MemberOfNodeSchema, type MembershipOperator, MembershipOperatorSchema, type NegateNode, NegateNodeSchema, type NotNode, NotNodeSchema, type NumberLiteralNode, NumberLiteralNodeSchema, type OrNode, OrNodeSchema, type PredicateNode, PredicateNodeSchema, type ReferenceNode, ReferenceNodeSchema, type Resolution, type Resolvers, type SomeNode, SomeNodeSchema, type SyncResolvers, type TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type TreeKind, type TreeReferenceNode, TreeReferenceNodeSchema, type TreeResolution, type Unit, UnitSchema, and, average, builtinFunctions, coalesce, combineUnitsForDivide, combineUnitsForMultiply, complexFromPolar, complexLiteralFromPolar, complexMagnitude, complexPhase, count, createEvaluator, createInputResolvers, createSyncEvaluator, definite, emptyFunctionRegistry, evaluateDocument, evaluatePredicate, evaluateValue, firstIndeterminate, hierarchicalGlobPattern, iff, implies, indeterminate, nand, none, nor, not, or, parseInputs, prefixPattern, presenceOf, sum, unitsEqual, wildcardPattern, xor };
16
+ export { type Absence, type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type BooleanLiteralNode, BooleanLiteralNodeSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComplexLiteralNode, ComplexLiteralNodeSchema, type ComplexPolarLiteralNode, ComplexPolarLiteralNodeSchema, type ComplexRectangularLiteralNode, ComplexRectangularLiteralNodeSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DocumentEvaluation, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type EvaluateDocumentOptions, type Evaluation, type EvaluationContext, type EvaluatorOptions, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionFailure, type FunctionRegistry, type HitPolicy, HitPolicySchema, type IndeterminateReason, IndeterminateReasonSchema, type InputItem, type InputsParseResult, type InstantLiteralNode, InstantLiteralNodeSchema, type JsonValue, JsonValueSchema, type LookupNode, LookupNodeSchema, type MemberOfNode, MemberOfNodeSchema, type MembershipOperator, MembershipOperatorSchema, type NegateNode, NegateNodeSchema, type NotNode, NotNodeSchema, type NumberLiteralNode, NumberLiteralNodeSchema, type OrNode, OrNodeSchema, type PredicateNode, PredicateNodeSchema, type ReferenceNode, ReferenceNodeSchema, type Resolution, type Resolvers, type SomeNode, SomeNodeSchema, type SyncResolvers, type TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type TreeKind, type TreeReferenceNode, TreeReferenceNodeSchema, type TreeResolution, type Unit, UnitSchema, and, average, builtinFunctions, coalesce, combineUnitsForDivide, combineUnitsForMultiply, complexFromPolar, complexLiteralFromPolar, complexMagnitude, complexPhase, count, createEvaluator, createInputResolvers, createSyncEvaluator, definite, emptyFunctionRegistry, evaluateDocument, evaluatePredicate, evaluateValue, firstIndeterminate, hierarchicalGlobPattern, iff, implies, indeterminate, nand, none, nor, not, or, parseInputs, prefixPattern, presenceOf, sum, unitsEqual, wildcardPattern, xor };
@@ -5,19 +5,22 @@ import { t as JsonValue } from "./json-value-B1Hjjjri.cjs";
5
5
  * An opaque, purely in-process value supplied by the caller, never itself part of the serialised tree and never required to be JSON-serialisable. Descending into a `fold` or a quantifier replaces the context for the sub-node's evaluation with the single resolved item.
6
6
  */
7
7
  export type EvaluationContext = unknown;
8
+ /**
9
+ * A resolver's report that it has no value to give. `{ found: false }` says the value is known to be absent, and evaluates to an indeterminate `not-found`, which `exists` reads as a definite `false`. `{ found: false, notYetKnown: true }` says the value has not been supplied yet and may exist later, and evaluates to an indeterminate `not-yet-known`, which `exists` leaves indeterminate. Use it when evaluating a partial assignment, so that a definite result on the partial input is also the result on every completion of it. `notYetKnown: false` is the same as leaving it out.
10
+ */
11
+ export interface Absence {
12
+ found: false;
13
+ notYetKnown?: boolean;
14
+ }
8
15
  export type Resolution = {
9
16
  found: true;
10
17
  value: ComputedValue;
11
- } | {
12
- found: false;
13
- };
14
- /** The `resolveTree` counterpart to `Resolution`: `found: true` carries the referenced tree as opaque JSON, re-validated by the evaluator (see the `treeReference` node kind) rather than trusted as already-shaped `PredicateNode`/`ExpressionNode`. */
18
+ } | Absence;
19
+ /** The `resolveTree` counterpart to `Resolution`: `found: true` carries the referenced tree as opaque JSON, re-validated by the evaluator (see the `treeReference` node kind) rather than trusted as already-shaped `PredicateNode`/`ExpressionNode`. Absence, known or not yet known, is reported exactly as it is for `Resolution`. */
15
20
  export type TreeResolution = {
16
21
  found: true;
17
22
  node: JsonValue;
18
- } | {
19
- found: false;
20
- };
23
+ } | Absence;
21
24
  /**
22
25
  * Three core, required points of extension, plus two further independent optional ones (`resolveDelegate`, `resolveTree`), each supplied separately by the embedding consumer, each treated as pure data to hand over -- never as resolver logic living inside the schema itself. Plain TypeScript interfaces, not Zod schemas: resolvers are never serialised, only ever supplied in-process at evaluation time.
23
26
  */
@@ -5,19 +5,22 @@ import { t as JsonValue } from "./json-value-B1Hjjjri.js";
5
5
  * An opaque, purely in-process value supplied by the caller, never itself part of the serialised tree and never required to be JSON-serialisable. Descending into a `fold` or a quantifier replaces the context for the sub-node's evaluation with the single resolved item.
6
6
  */
7
7
  export type EvaluationContext = unknown;
8
+ /**
9
+ * A resolver's report that it has no value to give. `{ found: false }` says the value is known to be absent, and evaluates to an indeterminate `not-found`, which `exists` reads as a definite `false`. `{ found: false, notYetKnown: true }` says the value has not been supplied yet and may exist later, and evaluates to an indeterminate `not-yet-known`, which `exists` leaves indeterminate. Use it when evaluating a partial assignment, so that a definite result on the partial input is also the result on every completion of it. `notYetKnown: false` is the same as leaving it out.
10
+ */
11
+ export interface Absence {
12
+ found: false;
13
+ notYetKnown?: boolean;
14
+ }
8
15
  export type Resolution = {
9
16
  found: true;
10
17
  value: ComputedValue;
11
- } | {
12
- found: false;
13
- };
14
- /** The `resolveTree` counterpart to `Resolution`: `found: true` carries the referenced tree as opaque JSON, re-validated by the evaluator (see the `treeReference` node kind) rather than trusted as already-shaped `PredicateNode`/`ExpressionNode`. */
18
+ } | Absence;
19
+ /** The `resolveTree` counterpart to `Resolution`: `found: true` carries the referenced tree as opaque JSON, re-validated by the evaluator (see the `treeReference` node kind) rather than trusted as already-shaped `PredicateNode`/`ExpressionNode`. Absence, known or not yet known, is reported exactly as it is for `Resolution`. */
15
20
  export type TreeResolution = {
16
21
  found: true;
17
22
  node: JsonValue;
18
- } | {
19
- found: false;
20
- };
23
+ } | Absence;
21
24
  /**
22
25
  * Three core, required points of extension, plus two further independent optional ones (`resolveDelegate`, `resolveTree`), each supplied separately by the embedding consumer, each treated as pure data to hand over -- never as resolver logic living inside the schema itself. Plain TypeScript interfaces, not Zod schemas: resolvers are never serialised, only ever supplied in-process at evaluation time.
23
26
  */
@@ -4,7 +4,7 @@ import { parseArgs } from "node:util";
4
4
  import { z } from "zod";
5
5
  import { RegexParseError, compilePattern } from "trilean-regex";
6
6
  //#region package.json
7
- var version = "1.10.1";
7
+ var version = "1.11.1";
8
8
  //#endregion
9
9
  //#region src/computed-value.ts
10
10
  /** Dimension symbol -\> exponent, e.g. `{ m: 1, s: -1 }` for metres per second. A bare symbol like `"kg"` is shorthand for `{ kg: 1 }`. */
@@ -79,9 +79,10 @@ function combineUnitsForDivide(a, b) {
79
79
  return normalizeUnit(combined);
80
80
  }
81
81
  z.object({
82
- /** Which of the three reason categories applies. */
82
+ /** Which of the four reason categories applies. `not-yet-known` is the only one that is not a property of the data: it says a resolver has not been supplied the value yet, so a later evaluation may settle it either way. */
83
83
  code: z.enum([
84
84
  "not-found",
85
+ "not-yet-known",
85
86
  "wrong-type",
86
87
  "domain-error"
87
88
  ]),
@@ -104,10 +105,18 @@ function indeterminate(code, message) {
104
105
  };
105
106
  }
106
107
  /**
107
- * 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.
108
+ * 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, except that a `not-yet-known` reason outranks every other. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
109
+ *
110
+ * The exception exists because this function is only called where a later outcome can still absorb an indeterminate one (`and`, `or`, `memberOf`, a `unique` conditional). Reporting `not-found` for such a node while another operand is still `not-yet-known` would be wrong: that operand might settle as a definite absorbing value, and the node would then be definite where `exists` had already reported its absence. Preferring `not-yet-known` keeps every non-`not-yet-known` reason a statement that no completion of the unknown values can overturn.
108
111
  */
109
112
  function firstIndeterminate(...results) {
110
- for (const result of results) if (result?.status === "indeterminate") return result.reason;
113
+ let first;
114
+ for (const result of results) {
115
+ if (result?.status !== "indeterminate") continue;
116
+ if (result.reason.code === "not-yet-known") return result.reason;
117
+ first ??= result.reason;
118
+ }
119
+ return first;
111
120
  }
112
121
  //#endregion
113
122
  //#region src/evaluator-budget.ts
@@ -369,6 +378,10 @@ function powerByRepeatedSquaring({ base, exponent, identity, multiply }) {
369
378
  }
370
379
  //#endregion
371
380
  //#region src/evaluator-operations.ts
381
+ /** The indeterminate result for a resolver's report of absence: `not-yet-known` when the resolver said the value has not been supplied yet, `not-found` otherwise. The two share every propagation rule except `exists` (and so `coalesce`), which is why every resolver call site goes through this one function. */
382
+ function absenceEvaluation(absence, notFoundMessage, notYetKnownMessage) {
383
+ return absence.notYetKnown === true ? indeterminate("not-yet-known", notYetKnownMessage) : indeterminate("not-found", notFoundMessage);
384
+ }
372
385
  /** The three-valued AND table: `false` is absorbing regardless of the other operand's indeterminacy; otherwise both-definite folds to a boolean AND; otherwise indeterminate, with the tie-break rule (declared operand order, left before right) applied via `firstIndeterminate`. */
373
386
  function combineAnd(left, right) {
374
387
  if (left.status === "definite" && !left.value) return definite(false);
@@ -1140,7 +1153,10 @@ function* evaluatePredicateInternal(node, context, resolvers, accumulator, funct
1140
1153
  }
1141
1154
  case "exists": {
1142
1155
  const operandResult = yield* evaluateValueInternal(node.operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth, budget, nestingDepth + 1);
1143
- if (operandResult.status === "indeterminate" && operandResult.reason.code === "not-found") return definite(false);
1156
+ if (operandResult.status === "indeterminate") {
1157
+ if (operandResult.reason.code === "not-yet-known") return operandResult;
1158
+ if (operandResult.reason.code === "not-found") return definite(false);
1159
+ }
1144
1160
  return definite(true);
1145
1161
  }
1146
1162
  case "some":
@@ -1160,7 +1176,7 @@ function* evaluatePredicateInternal(node, context, resolvers, accumulator, funct
1160
1176
  if (visitedTreeKeys.has(keyString)) return indeterminate("domain-error", "circular treeReference detected");
1161
1177
  if (treeReferenceDepth >= 100) return indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${100 .toString()}`);
1162
1178
  const resolution = yield* wait(resolvers.resolveTree(node.key, context));
1163
- if (!resolution.found) return indeterminate("not-found", "treeReference key did not resolve to a tree");
1179
+ if (!resolution.found) return absenceEvaluation(resolution, "treeReference key did not resolve to a tree", "the tree for the treeReference key is not yet known");
1164
1180
  const parsed = PredicateNodeSchema.safeParse(resolution.node);
1165
1181
  if (!parsed.success) return indeterminate("wrong-type", "the referenced tree is not a valid PredicateNode");
1166
1182
  return yield* evaluatePredicateInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1, budget, nestingDepth + 1);
@@ -1174,7 +1190,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
1174
1190
  switch (node.kind) {
1175
1191
  case "reference": {
1176
1192
  const resolution = yield* wait(resolvers.resolveValue(node.key, context));
1177
- if (!resolution.found) return indeterminate("not-found", `no value found for reference key ${JSON.stringify(node.key)}`);
1193
+ if (!resolution.found) return absenceEvaluation(resolution, `no value found for reference key ${JSON.stringify(node.key)}`, `the value for reference key ${JSON.stringify(node.key)} is not yet known`);
1178
1194
  const unitError = checkReferenceUnit(node.unit, resolution.value);
1179
1195
  if (unitError !== void 0) return unitError;
1180
1196
  return definite(resolution.value);
@@ -1240,7 +1256,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
1240
1256
  keyValues.push(result.value);
1241
1257
  }
1242
1258
  const resolution = yield* wait(resolvers.resolveLookup(node.table, keyValues, context));
1243
- if (!resolution.found) return indeterminate("not-found", `no match found in lookup table ${JSON.stringify(node.table)}`);
1259
+ if (!resolution.found) return absenceEvaluation(resolution, `no match found in lookup table ${JSON.stringify(node.table)}`, `the match in lookup table ${JSON.stringify(node.table)} is not yet known`);
1244
1260
  return definite(resolution.value);
1245
1261
  }
1246
1262
  case "conditional": {
@@ -1308,7 +1324,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
1308
1324
  case "delegate": {
1309
1325
  if (resolvers.resolveDelegate === void 0) return indeterminate("wrong-type", `no delegate handler registered for external system '${node.system}'`);
1310
1326
  const resolution = yield* wait(resolvers.resolveDelegate(node.system, node.payload, context));
1311
- if (!resolution.found) return indeterminate("not-found", `delegate handler for external system '${node.system}' reported no value`);
1327
+ if (!resolution.found) return absenceEvaluation(resolution, `delegate handler for external system '${node.system}' reported no value`, `the value from the delegate handler for external system '${node.system}' is not yet known`);
1312
1328
  return definite(resolution.value);
1313
1329
  }
1314
1330
  case "treeReference": {
@@ -1317,7 +1333,7 @@ function* evaluateValueInternal(node, context, resolvers, accumulator, functions
1317
1333
  if (visitedTreeKeys.has(keyString)) return indeterminate("domain-error", "circular treeReference detected");
1318
1334
  if (treeReferenceDepth >= 100) return indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${100 .toString()}`);
1319
1335
  const resolution = yield* wait(resolvers.resolveTree(node.key, context));
1320
- if (!resolution.found) return indeterminate("not-found", "treeReference key did not resolve to a tree");
1336
+ if (!resolution.found) return absenceEvaluation(resolution, "treeReference key did not resolve to a tree", "the tree for the treeReference key is not yet known");
1321
1337
  const parsed = ExpressionNodeSchema.safeParse(resolution.node);
1322
1338
  if (!parsed.success) return indeterminate("wrong-type", "the referenced tree is not a valid ExpressionNode");
1323
1339
  return yield* evaluateValueInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1, budget, nestingDepth + 1);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "trilean",
3
3
  "description": "Three-valued predicate and expression evaluation trees, stored as JSON and evaluated against injected resolvers, for domain logic — business rules, eligibility checks, formulas, search filters, and more — that needs to be data instead of code.",
4
- "version": "1.10.1",
4
+ "version": "1.11.1",
5
5
  "bin": {
6
6
  "trilean": "./dist-cli/trilean.mjs"
7
7
  },
@@ -1 +1 @@
1
- {"$defs":{"ExpressionNode":{"anyOf":[{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"numberLiteral","type":"string"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"},"value":{"type":"number"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"textLiteral","type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"booleanLiteral","type":"string"},"value":{"type":"boolean"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"instantLiteral","type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"durationLiteral","type":"string"},"unit":{"enum":["ms","s","min","h","d"],"type":"string"},"value":{"type":"number"}},"required":["kind","value","unit"],"type":"object"},{"additionalProperties":false,"properties":{"key":{"$ref":"#/$defs/schema0"},"kind":{"const":"reference","type":"string"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"}},"required":["kind","key"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"arithmetic","type":"string"},"left":{"$ref":"#/$defs/ExpressionNode"},"op":{"enum":["add","subtract","multiply","divide","power","modulo"],"type":"string"},"right":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"negate","type":"string"},"operand":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","operand"],"type":"object"},{"additionalProperties":false,"properties":{"args":{"items":{"$ref":"#/$defs/ExpressionNode"},"type":"array"},"fn":{"type":"string"},"kind":{"const":"call","type":"string"}},"required":["kind","fn","args"],"type":"object"},{"additionalProperties":false,"properties":{"keys":{"items":{"$ref":"#/$defs/ExpressionNode"},"type":"array"},"kind":{"const":"lookup","type":"string"},"table":{"$ref":"#/$defs/schema0"}},"required":["kind","table","keys"],"type":"object"},{"additionalProperties":false,"properties":{"cases":{"items":{"additionalProperties":false,"properties":{"then":{"$ref":"#/$defs/ExpressionNode"},"when":{"$ref":"#/$defs/PredicateNode"}},"required":["when","then"],"type":"object"},"type":"array"},"fallback":{"$ref":"#/$defs/ExpressionNode"},"hitPolicy":{"enum":["first","unique"],"type":"string"},"kind":{"const":"conditional","type":"string"}},"required":["kind","cases","fallback"],"type":"object"},{"additionalProperties":false,"properties":{"collection":{"$ref":"#/$defs/schema0"},"combiner":{"oneOf":[{"additionalProperties":false,"properties":{"item":{"$ref":"#/$defs/ExpressionNode"},"mode":{"const":"max","type":"string"}},"required":["mode","item"],"type":"object"},{"additionalProperties":false,"properties":{"item":{"$ref":"#/$defs/ExpressionNode"},"mode":{"const":"min","type":"string"}},"required":["mode","item"],"type":"object"},{"additionalProperties":false,"properties":{"combine":{"$ref":"#/$defs/ExpressionNode"},"initial":{"$ref":"#/$defs/ExpressionNode"},"mode":{"const":"reduce","type":"string"}},"required":["mode","initial","combine"],"type":"object"}]},"filter":{"$ref":"#/$defs/PredicateNode"},"kind":{"const":"fold","type":"string"}},"required":["kind","collection","combiner"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"accumulator","type":"string"}},"required":["kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"delegate","type":"string"},"payload":{"$ref":"#/$defs/schema0"},"system":{"type":"string"}},"required":["kind","system","payload"],"type":"object"},{"additionalProperties":false,"properties":{"key":{"$ref":"#/$defs/schema0"},"kind":{"const":"treeReference","type":"string"}},"required":["kind","key"],"type":"object"}]},{"anyOf":[{"additionalProperties":false,"properties":{"im":{"type":"number"},"kind":{"const":"complexLiteral","type":"string"},"re":{"type":"number"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"}},"required":["kind","re","im"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"complexLiteral","type":"string"},"magnitude":{"type":"number"},"phase":{"type":"number"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"}},"required":["kind","magnitude","phase"],"type":"object"}]}]},"PredicateNode":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"not","type":"string"},"operand":{"$ref":"#/$defs/PredicateNode"}},"required":["kind","operand"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"and","type":"string"},"left":{"$ref":"#/$defs/PredicateNode"},"right":{"$ref":"#/$defs/PredicateNode"}},"required":["kind","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"or","type":"string"},"left":{"$ref":"#/$defs/PredicateNode"},"right":{"$ref":"#/$defs/PredicateNode"}},"required":["kind","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"allOf","type":"string"},"operands":{"items":{"$ref":"#/$defs/PredicateNode"},"type":"array"}},"required":["kind","operands"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"anyOf","type":"string"},"operands":{"items":{"$ref":"#/$defs/PredicateNode"},"type":"array"}},"required":["kind","operands"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"compare","type":"string"},"left":{"$ref":"#/$defs/ExpressionNode"},"op":{"enum":["gt","gte","lt","lte","eq","neq"],"type":"string"},"right":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"textCompare","type":"string"},"left":{"$ref":"#/$defs/ExpressionNode"},"op":{"enum":["equals","notEquals","matches","notMatches","portableMatches","portableNotMatches"],"type":"string"},"right":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"candidates":{"items":{"$ref":"#/$defs/ExpressionNode"},"type":"array"},"kind":{"const":"memberOf","type":"string"},"op":{"enum":["in","notIn"],"type":"string"},"operand":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","operand","candidates"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"exists","type":"string"},"operand":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","operand"],"type":"object"},{"additionalProperties":false,"properties":{"collection":{"$ref":"#/$defs/schema0"},"filter":{"$ref":"#/$defs/PredicateNode"},"item":{"$ref":"#/$defs/PredicateNode"},"kind":{"const":"some","type":"string"}},"required":["kind","collection","item"],"type":"object"},{"additionalProperties":false,"properties":{"collection":{"$ref":"#/$defs/schema0"},"filter":{"$ref":"#/$defs/PredicateNode"},"item":{"$ref":"#/$defs/PredicateNode"},"kind":{"const":"every","type":"string"}},"required":["kind","collection","item"],"type":"object"},{"additionalProperties":false,"properties":{"key":{"$ref":"#/$defs/schema0"},"kind":{"const":"treeReference","type":"string"}},"required":["kind","key"],"type":"object"}]},"schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"items":{"$ref":"#/$defs/schema0"},"type":"array"},{"additionalProperties":{"$ref":"#/$defs/schema0"},"propertyNames":{"type":"string"},"type":"object"}]}},"$id":"https://cdn.jsdelivr.net/npm/trilean@1.10.1/schemas/trilean.schema.json","$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"$ref":"#/$defs/PredicateNode"},{"$ref":"#/$defs/ExpressionNode"}]}
1
+ {"$defs":{"ExpressionNode":{"anyOf":[{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"numberLiteral","type":"string"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"},"value":{"type":"number"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"textLiteral","type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"booleanLiteral","type":"string"},"value":{"type":"boolean"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"instantLiteral","type":"string"},"value":{"type":"string"}},"required":["kind","value"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"durationLiteral","type":"string"},"unit":{"enum":["ms","s","min","h","d"],"type":"string"},"value":{"type":"number"}},"required":["kind","value","unit"],"type":"object"},{"additionalProperties":false,"properties":{"key":{"$ref":"#/$defs/schema0"},"kind":{"const":"reference","type":"string"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"}},"required":["kind","key"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"arithmetic","type":"string"},"left":{"$ref":"#/$defs/ExpressionNode"},"op":{"enum":["add","subtract","multiply","divide","power","modulo"],"type":"string"},"right":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"negate","type":"string"},"operand":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","operand"],"type":"object"},{"additionalProperties":false,"properties":{"args":{"items":{"$ref":"#/$defs/ExpressionNode"},"type":"array"},"fn":{"type":"string"},"kind":{"const":"call","type":"string"}},"required":["kind","fn","args"],"type":"object"},{"additionalProperties":false,"properties":{"keys":{"items":{"$ref":"#/$defs/ExpressionNode"},"type":"array"},"kind":{"const":"lookup","type":"string"},"table":{"$ref":"#/$defs/schema0"}},"required":["kind","table","keys"],"type":"object"},{"additionalProperties":false,"properties":{"cases":{"items":{"additionalProperties":false,"properties":{"then":{"$ref":"#/$defs/ExpressionNode"},"when":{"$ref":"#/$defs/PredicateNode"}},"required":["when","then"],"type":"object"},"type":"array"},"fallback":{"$ref":"#/$defs/ExpressionNode"},"hitPolicy":{"enum":["first","unique"],"type":"string"},"kind":{"const":"conditional","type":"string"}},"required":["kind","cases","fallback"],"type":"object"},{"additionalProperties":false,"properties":{"collection":{"$ref":"#/$defs/schema0"},"combiner":{"oneOf":[{"additionalProperties":false,"properties":{"item":{"$ref":"#/$defs/ExpressionNode"},"mode":{"const":"max","type":"string"}},"required":["mode","item"],"type":"object"},{"additionalProperties":false,"properties":{"item":{"$ref":"#/$defs/ExpressionNode"},"mode":{"const":"min","type":"string"}},"required":["mode","item"],"type":"object"},{"additionalProperties":false,"properties":{"combine":{"$ref":"#/$defs/ExpressionNode"},"initial":{"$ref":"#/$defs/ExpressionNode"},"mode":{"const":"reduce","type":"string"}},"required":["mode","initial","combine"],"type":"object"}]},"filter":{"$ref":"#/$defs/PredicateNode"},"kind":{"const":"fold","type":"string"}},"required":["kind","collection","combiner"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"accumulator","type":"string"}},"required":["kind"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"delegate","type":"string"},"payload":{"$ref":"#/$defs/schema0"},"system":{"type":"string"}},"required":["kind","system","payload"],"type":"object"},{"additionalProperties":false,"properties":{"key":{"$ref":"#/$defs/schema0"},"kind":{"const":"treeReference","type":"string"}},"required":["kind","key"],"type":"object"}]},{"anyOf":[{"additionalProperties":false,"properties":{"im":{"type":"number"},"kind":{"const":"complexLiteral","type":"string"},"re":{"type":"number"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"}},"required":["kind","re","im"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"complexLiteral","type":"string"},"magnitude":{"type":"number"},"phase":{"type":"number"},"unit":{"additionalProperties":{"type":"number"},"propertyNames":{"type":"string"},"type":"object"}},"required":["kind","magnitude","phase"],"type":"object"}]}]},"PredicateNode":{"oneOf":[{"additionalProperties":false,"properties":{"kind":{"const":"not","type":"string"},"operand":{"$ref":"#/$defs/PredicateNode"}},"required":["kind","operand"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"and","type":"string"},"left":{"$ref":"#/$defs/PredicateNode"},"right":{"$ref":"#/$defs/PredicateNode"}},"required":["kind","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"or","type":"string"},"left":{"$ref":"#/$defs/PredicateNode"},"right":{"$ref":"#/$defs/PredicateNode"}},"required":["kind","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"allOf","type":"string"},"operands":{"items":{"$ref":"#/$defs/PredicateNode"},"type":"array"}},"required":["kind","operands"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"anyOf","type":"string"},"operands":{"items":{"$ref":"#/$defs/PredicateNode"},"type":"array"}},"required":["kind","operands"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"compare","type":"string"},"left":{"$ref":"#/$defs/ExpressionNode"},"op":{"enum":["gt","gte","lt","lte","eq","neq"],"type":"string"},"right":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"textCompare","type":"string"},"left":{"$ref":"#/$defs/ExpressionNode"},"op":{"enum":["equals","notEquals","matches","notMatches","portableMatches","portableNotMatches"],"type":"string"},"right":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","left","right"],"type":"object"},{"additionalProperties":false,"properties":{"candidates":{"items":{"$ref":"#/$defs/ExpressionNode"},"type":"array"},"kind":{"const":"memberOf","type":"string"},"op":{"enum":["in","notIn"],"type":"string"},"operand":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","op","operand","candidates"],"type":"object"},{"additionalProperties":false,"properties":{"kind":{"const":"exists","type":"string"},"operand":{"$ref":"#/$defs/ExpressionNode"}},"required":["kind","operand"],"type":"object"},{"additionalProperties":false,"properties":{"collection":{"$ref":"#/$defs/schema0"},"filter":{"$ref":"#/$defs/PredicateNode"},"item":{"$ref":"#/$defs/PredicateNode"},"kind":{"const":"some","type":"string"}},"required":["kind","collection","item"],"type":"object"},{"additionalProperties":false,"properties":{"collection":{"$ref":"#/$defs/schema0"},"filter":{"$ref":"#/$defs/PredicateNode"},"item":{"$ref":"#/$defs/PredicateNode"},"kind":{"const":"every","type":"string"}},"required":["kind","collection","item"],"type":"object"},{"additionalProperties":false,"properties":{"key":{"$ref":"#/$defs/schema0"},"kind":{"const":"treeReference","type":"string"}},"required":["kind","key"],"type":"object"}]},"schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"items":{"$ref":"#/$defs/schema0"},"type":"array"},{"additionalProperties":{"$ref":"#/$defs/schema0"},"propertyNames":{"type":"string"},"type":"object"}]}},"$id":"https://cdn.jsdelivr.net/npm/trilean@1.11.1/schemas/trilean.schema.json","$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"$ref":"#/$defs/PredicateNode"},{"$ref":"#/$defs/ExpressionNode"}]}