trilean 1.13.9 → 1.13.11

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
@@ -448,7 +448,7 @@ Evaluate `operand` first; if it is indeterminate, the whole leaf is indeterminat
448
448
 
449
449
  ### `exists`
450
450
 
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.
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` (other than an exhausted limit, below), `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. If the result is indeterminate because a resource limit was exhausted (the node budget, the nesting depth or the `treeReference` chain depth), `exists` is indeterminate with that limit's own `domain-error` and message: the operand was not evaluated to its end, so nothing is known about the data point. Every other `domain-error` stays `true`, whatever produced it: an arithmetic or built-in function outside its domain (division, modulo and power by zero, a result out of range or not finite, a logarithm of zero), a registered function's own domain error, a `unique` conditional with more than one matching case, a `max` or `min` fold with no participating item, and a circular `treeReference`. In each the data point resolved to something, or the tree is at fault, and no limit cut the evaluation short; a cycle is detected, not exhausted, so it is not a limit. The one family that propagates is the exhausted resource limits. `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.
452
452
 
453
453
  ### `some`, `every`
454
454
 
@@ -1,6 +1,18 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  const require_evaluation = require("./evaluation.cjs");
3
3
  // src/evaluator-budget.ts
4
+ /** The reason objects that report an exhausted resource limit (node budget, nesting depth, treeReference chain depth). Every such reason has the code `domain-error`, so the code alone cannot tell a limit from any other domain error; membership here is what `exists` reads to let a limit propagate instead of counting as "the value resolved". Identity is preserved by every node that forwards an operand's reason, so a reason keeps its membership as it propagates. */
5
+ const exhaustedReasons = /* @__PURE__ */ new WeakSet();
6
+ /** The indeterminate result for an exhausted resource limit: code `domain-error` with the limit's own message, recorded so `isResourceExhaustion` recognises it. */
7
+ function resourceExhausted(message) {
8
+ const result = require_evaluation.indeterminate("domain-error", message);
9
+ if (result.status === "indeterminate") exhaustedReasons.add(result.reason);
10
+ return result;
11
+ }
12
+ /** Whether `reason` reports an exhausted resource limit, as opposed to any other indeterminacy. */
13
+ function isResourceExhaustion(reason) {
14
+ return exhaustedReasons.has(reason);
15
+ }
4
16
  /** A defense-in-depth guard against a long acyclic `treeReference` chain exhausting the call stack -- distinct from, and layered on top of, the cycle detector in evaluator.ts (`visitedTreeKeys`), which catches an actual repeat immediately and more precisely. */
5
17
  const MAX_TREE_REFERENCE_DEPTH = 100;
6
18
  /** Default cap on the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluator`'s `maxNodes` option, threaded through to `createEvaluationBudget` below. Chosen generously above any realistic hand-authored business-rule, eligibility, or formula tree (see README.md's own consumer use cases), while still bounding an untrusted, adversarially-authored tree's total evaluation cost to a fixed, small amount of work regardless of how it is shaped. */
@@ -13,11 +25,13 @@ function createEvaluationBudget(maxNodes, maxNestingDepth) {
13
25
  let nodesVisited = 0;
14
26
  return { checkNode(nestingDepth) {
15
27
  nodesVisited += 1;
16
- if (nodesVisited > maxNodes) return require_evaluation.indeterminate("domain-error", `evaluation exceeded the maximum of ${maxNodes.toString()} nodes visited in a single call (resource exhausted)`);
17
- if (nestingDepth >= maxNestingDepth) return require_evaluation.indeterminate("domain-error", `evaluation nesting depth exceeds the maximum of ${maxNestingDepth.toString()} (resource exhausted)`);
28
+ if (nodesVisited > maxNodes) return resourceExhausted(`evaluation exceeded the maximum of ${maxNodes.toString()} nodes visited in a single call (resource exhausted)`);
29
+ if (nestingDepth >= maxNestingDepth) return resourceExhausted(`evaluation nesting depth exceeds the maximum of ${maxNestingDepth.toString()} (resource exhausted)`);
18
30
  } };
19
31
  }
20
32
  exports.DEFAULT_MAX_EVALUATION_NODES = DEFAULT_MAX_EVALUATION_NODES;
21
33
  exports.DEFAULT_MAX_NESTING_DEPTH = DEFAULT_MAX_NESTING_DEPTH;
22
34
  exports.MAX_TREE_REFERENCE_DEPTH = MAX_TREE_REFERENCE_DEPTH;
23
35
  exports.createEvaluationBudget = createEvaluationBudget;
36
+ exports.isResourceExhaustion = isResourceExhaustion;
37
+ exports.resourceExhausted = resourceExhausted;
@@ -1,4 +1,8 @@
1
- import { Evaluation } from "./evaluation.cjs";
1
+ import { Evaluation, IndeterminateReason } from "./evaluation.cjs";
2
+ /** The indeterminate result for an exhausted resource limit: code `domain-error` with the limit's own message, recorded so `isResourceExhaustion` recognises it. */
3
+ export declare function resourceExhausted(message: string): Evaluation<never>;
4
+ /** Whether `reason` reports an exhausted resource limit, as opposed to any other indeterminacy. */
5
+ export declare function isResourceExhaustion(reason: Readonly<IndeterminateReason>): boolean;
2
6
  /** A defense-in-depth guard against a long acyclic `treeReference` chain exhausting the call stack -- distinct from, and layered on top of, the cycle detector in evaluator.ts (`visitedTreeKeys`), which catches an actual repeat immediately and more precisely. */
3
7
  export declare const MAX_TREE_REFERENCE_DEPTH = 100;
4
8
  /** Default cap on the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluator`'s `maxNodes` option, threaded through to `createEvaluationBudget` below. Chosen generously above any realistic hand-authored business-rule, eligibility, or formula tree (see README.md's own consumer use cases), while still bounding an untrusted, adversarially-authored tree's total evaluation cost to a fixed, small amount of work regardless of how it is shaped. */
@@ -1,4 +1,8 @@
1
- import { Evaluation } from "./evaluation.js";
1
+ import { Evaluation, IndeterminateReason } from "./evaluation.js";
2
+ /** The indeterminate result for an exhausted resource limit: code `domain-error` with the limit's own message, recorded so `isResourceExhaustion` recognises it. */
3
+ export declare function resourceExhausted(message: string): Evaluation<never>;
4
+ /** Whether `reason` reports an exhausted resource limit, as opposed to any other indeterminacy. */
5
+ export declare function isResourceExhaustion(reason: Readonly<IndeterminateReason>): boolean;
2
6
  /** A defense-in-depth guard against a long acyclic `treeReference` chain exhausting the call stack -- distinct from, and layered on top of, the cycle detector in evaluator.ts (`visitedTreeKeys`), which catches an actual repeat immediately and more precisely. */
3
7
  export declare const MAX_TREE_REFERENCE_DEPTH = 100;
4
8
  /** Default cap on the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluator`'s `maxNodes` option, threaded through to `createEvaluationBudget` below. Chosen generously above any realistic hand-authored business-rule, eligibility, or formula tree (see README.md's own consumer use cases), while still bounding an untrusted, adversarially-authored tree's total evaluation cost to a fixed, small amount of work regardless of how it is shaped. */
@@ -1,5 +1,17 @@
1
1
  import { indeterminate } from "./evaluation.js";
2
2
  // src/evaluator-budget.ts
3
+ /** The reason objects that report an exhausted resource limit (node budget, nesting depth, treeReference chain depth). Every such reason has the code `domain-error`, so the code alone cannot tell a limit from any other domain error; membership here is what `exists` reads to let a limit propagate instead of counting as "the value resolved". Identity is preserved by every node that forwards an operand's reason, so a reason keeps its membership as it propagates. */
4
+ const exhaustedReasons = /* @__PURE__ */ new WeakSet();
5
+ /** The indeterminate result for an exhausted resource limit: code `domain-error` with the limit's own message, recorded so `isResourceExhaustion` recognises it. */
6
+ function resourceExhausted(message) {
7
+ const result = indeterminate("domain-error", message);
8
+ if (result.status === "indeterminate") exhaustedReasons.add(result.reason);
9
+ return result;
10
+ }
11
+ /** Whether `reason` reports an exhausted resource limit, as opposed to any other indeterminacy. */
12
+ function isResourceExhaustion(reason) {
13
+ return exhaustedReasons.has(reason);
14
+ }
3
15
  /** A defense-in-depth guard against a long acyclic `treeReference` chain exhausting the call stack -- distinct from, and layered on top of, the cycle detector in evaluator.ts (`visitedTreeKeys`), which catches an actual repeat immediately and more precisely. */
4
16
  const MAX_TREE_REFERENCE_DEPTH = 100;
5
17
  /** Default cap on the total number of predicate/expression nodes a single `evaluatePredicate`/`evaluateValue` call may visit -- see `createEvaluator`'s `maxNodes` option, threaded through to `createEvaluationBudget` below. Chosen generously above any realistic hand-authored business-rule, eligibility, or formula tree (see README.md's own consumer use cases), while still bounding an untrusted, adversarially-authored tree's total evaluation cost to a fixed, small amount of work regardless of how it is shaped. */
@@ -12,8 +24,8 @@ function createEvaluationBudget(maxNodes, maxNestingDepth) {
12
24
  let nodesVisited = 0;
13
25
  return { checkNode(nestingDepth) {
14
26
  nodesVisited += 1;
15
- if (nodesVisited > maxNodes) return indeterminate("domain-error", `evaluation exceeded the maximum of ${maxNodes.toString()} nodes visited in a single call (resource exhausted)`);
16
- if (nestingDepth >= maxNestingDepth) return indeterminate("domain-error", `evaluation nesting depth exceeds the maximum of ${maxNestingDepth.toString()} (resource exhausted)`);
27
+ if (nodesVisited > maxNodes) return resourceExhausted(`evaluation exceeded the maximum of ${maxNodes.toString()} nodes visited in a single call (resource exhausted)`);
28
+ if (nestingDepth >= maxNestingDepth) return resourceExhausted(`evaluation nesting depth exceeds the maximum of ${maxNestingDepth.toString()} (resource exhausted)`);
17
29
  } };
18
30
  }
19
- export { DEFAULT_MAX_EVALUATION_NODES, DEFAULT_MAX_NESTING_DEPTH, MAX_TREE_REFERENCE_DEPTH, createEvaluationBudget };
31
+ export { DEFAULT_MAX_EVALUATION_NODES, DEFAULT_MAX_NESTING_DEPTH, MAX_TREE_REFERENCE_DEPTH, createEvaluationBudget, isResourceExhaustion, resourceExhausted };
@@ -142,7 +142,7 @@ var NodeCompiler = class {
142
142
  return this.charged(depth, (context, resolvers, budget) => {
143
143
  const result = operand(context, resolvers, budget);
144
144
  if (result.status === "indeterminate") {
145
- if (result.reason.code === "not-yet-known") return result;
145
+ if (result.reason.code === "not-yet-known" || require_evaluator_budget.isResourceExhaustion(result.reason)) return result;
146
146
  if (result.reason.code === "not-found") return require_evaluation.definite(false);
147
147
  }
148
148
  return require_evaluation.definite(true);
@@ -1,5 +1,5 @@
1
1
  import { definite, firstIndeterminate, indeterminate } from "./evaluation.js";
2
- import { createEvaluationBudget } from "./evaluator-budget.js";
2
+ import { createEvaluationBudget, isResourceExhaustion } from "./evaluator-budget.js";
3
3
  import { evaluatePredicateInternal, evaluateValueInternal } from "./evaluator.js";
4
4
  import { runSync, settleSync } from "./evaluator-effect.js";
5
5
  import { literalValue } from "./evaluator-literals.js";
@@ -141,7 +141,7 @@ var NodeCompiler = class {
141
141
  return this.charged(depth, (context, resolvers, budget) => {
142
142
  const result = operand(context, resolvers, budget);
143
143
  if (result.status === "indeterminate") {
144
- if (result.reason.code === "not-yet-known") return result;
144
+ if (result.reason.code === "not-yet-known" || isResourceExhaustion(result.reason)) return result;
145
145
  if (result.reason.code === "not-found") return definite(false);
146
146
  }
147
147
  return definite(true);