trilean 1.0.13 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/evaluator.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { combineUnitsForDivide, combineUnitsForMultiply, unitsEqual } from "./computed-value.js";
2
2
  import { definite, firstIndeterminate, indeterminate } from "./evaluation.js";
3
3
  import { emptyFunctionRegistry } from "./functions.js";
4
+ import { ExpressionNodeSchema, PredicateNodeSchema } from "./tree.js";
4
5
  //#region src/evaluator.ts
5
6
  /**
6
7
  * `evaluatePredicateInternal` and `evaluateValueInternal` are co-located in this one file, rather than split across `predicate-evaluator.ts`/`value-evaluator.ts`, because they are mutually recursive: a predicate leaf (`compare`, `textCompare`, `memberOf`, `exists`) holds `ExpressionNode` operands, and an expression node (`conditional`'s `when`, a fold's `filter`) holds `PredicateNode` operands. Splitting them across modules would make each half import the other, and whichever module finished loading second would see the other's export as `undefined` at its own module-evaluation time -- a genuine circular-import TDZ hazard, not merely a style preference.
@@ -253,17 +254,19 @@ function applyArithmetic(op, left, right) {
253
254
  if (right.kind !== "number") return indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${right.kind}' value`);
254
255
  return applyArithmeticOnNumbers(op, left, right);
255
256
  }
257
+ /** 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 below (`visitedTreeKeys`), which catches an actual repeat immediately and more precisely. */
258
+ const MAX_TREE_REFERENCE_DEPTH = 100;
256
259
  /**
257
260
  * Collection resolution shared by the quantifiers (`some`/`every`, below) and by `fold` (a later phase): resolves the opaque `collection` reference to its concrete candidate list via `resolvers.resolveCollection`, then evaluates each candidate's optional `filter` with that candidate as its own evaluation context and the accumulator reset to `undefined` -- see the README's "Evaluation context" and "Pre-filtering which items participate" sections. Deliberately stops short of deciding how an indeterminate filter combines with the rest of the surrounding node: `some`/`every` fold a filter-indeterminate item in as its own vote via the surrounding OR/AND absorption, while `fold` has no absorbing value at all and goes indeterminate outright on the same condition -- the two callers need genuinely different combination logic over these same per-item outcomes, so this helper only produces the outcomes and leaves combining them to the caller.
258
261
  */
259
- async function resolveParticipatingItems(collection, filter, context, resolvers, functions) {
262
+ async function resolveParticipatingItems(collection, filter, context, resolvers, functions, visitedTreeKeys, treeReferenceDepth) {
260
263
  const candidates = await resolvers.resolveCollection(collection, context);
261
264
  return Promise.all(candidates.map(async (item) => {
262
265
  if (filter === void 0) return {
263
266
  item,
264
267
  filterOutcome: "include"
265
268
  };
266
- const filterResult = await evaluatePredicateInternal(filter, item, resolvers, void 0, functions);
269
+ const filterResult = await evaluatePredicateInternal(filter, item, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth);
267
270
  if (filterResult.status === "indeterminate") return {
268
271
  item,
269
272
  filterOutcome: filterResult
@@ -281,40 +284,40 @@ function firstFilterIndeterminate(participating) {
281
284
  if (filterOutcome.status === "indeterminate") return filterOutcome.reason;
282
285
  }
283
286
  }
284
- async function evaluatePredicateInternal(node, context, resolvers, accumulator, functions) {
287
+ async function evaluatePredicateInternal(node, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth) {
285
288
  switch (node.kind) {
286
289
  case "not": {
287
- const operand = await evaluatePredicateInternal(node.operand, context, resolvers, accumulator, functions);
290
+ const operand = await evaluatePredicateInternal(node.operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
288
291
  if (operand.status === "indeterminate") return operand;
289
292
  return definite(!operand.value);
290
293
  }
291
294
  case "and": {
292
- const [left, right] = await Promise.all([evaluatePredicateInternal(node.left, context, resolvers, accumulator, functions), evaluatePredicateInternal(node.right, context, resolvers, accumulator, functions)]);
295
+ const [left, right] = await Promise.all([evaluatePredicateInternal(node.left, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth), evaluatePredicateInternal(node.right, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)]);
293
296
  return combineAnd(left, right);
294
297
  }
295
298
  case "or": {
296
- const [left, right] = await Promise.all([evaluatePredicateInternal(node.left, context, resolvers, accumulator, functions), evaluatePredicateInternal(node.right, context, resolvers, accumulator, functions)]);
299
+ const [left, right] = await Promise.all([evaluatePredicateInternal(node.left, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth), evaluatePredicateInternal(node.right, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)]);
297
300
  return combineOr(left, right);
298
301
  }
299
- case "allOf": return (await Promise.all(node.operands.map(async (operand) => evaluatePredicateInternal(operand, context, resolvers, accumulator, functions)))).reduce(combineAnd, definite(true));
300
- case "anyOf": return (await Promise.all(node.operands.map(async (operand) => evaluatePredicateInternal(operand, context, resolvers, accumulator, functions)))).reduce(combineOr, definite(false));
302
+ case "allOf": return (await Promise.all(node.operands.map(async (operand) => evaluatePredicateInternal(operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)))).reduce(combineAnd, definite(true));
303
+ case "anyOf": return (await Promise.all(node.operands.map(async (operand) => evaluatePredicateInternal(operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)))).reduce(combineOr, definite(false));
301
304
  case "compare": {
302
- const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions), evaluateValueInternal(node.right, context, resolvers, accumulator, functions)]);
305
+ const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth), evaluateValueInternal(node.right, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)]);
303
306
  if (left.status === "indeterminate") return left;
304
307
  if (right.status === "indeterminate") return right;
305
308
  return compareValues(node.op, left.value, right.value);
306
309
  }
307
310
  case "textCompare": {
308
- const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions), evaluateValueInternal(node.right, context, resolvers, accumulator, functions)]);
311
+ const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth), evaluateValueInternal(node.right, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)]);
309
312
  if (left.status === "indeterminate") return left;
310
313
  if (right.status === "indeterminate") return right;
311
314
  return compareText(node.op, left.value, right.value);
312
315
  }
313
316
  case "memberOf": {
314
- const operandResult = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions);
317
+ const operandResult = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
315
318
  if (operandResult.status === "indeterminate") return operandResult;
316
319
  const candidateOutcomes = await Promise.all(node.candidates.map(async (candidate) => {
317
- const candidateResult = await evaluateValueInternal(candidate, context, resolvers, accumulator, functions);
320
+ const candidateResult = await evaluateValueInternal(candidate, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
318
321
  if (candidateResult.status === "indeterminate") return candidateResult;
319
322
  return computeMembershipMatch(operandResult.value, candidateResult.value);
320
323
  }));
@@ -327,26 +330,37 @@ async function evaluatePredicateInternal(node, context, resolvers, accumulator,
327
330
  return definite(node.op === "notIn");
328
331
  }
329
332
  case "exists": {
330
- const operandResult = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions);
333
+ const operandResult = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
331
334
  if (operandResult.status === "indeterminate" && operandResult.reason.code === "not-found") return definite(false);
332
335
  return definite(true);
333
336
  }
334
337
  case "some":
335
338
  case "every": {
336
- const participating = await resolveParticipatingItems(node.collection, node.filter, context, resolvers, functions);
339
+ const participating = await resolveParticipatingItems(node.collection, node.filter, context, resolvers, functions, visitedTreeKeys, treeReferenceDepth);
337
340
  const votes = (await Promise.all(participating.map(async ({ item, filterOutcome }) => {
338
341
  if (filterOutcome === "exclude") return void 0;
339
342
  if (filterOutcome !== "include") return filterOutcome;
340
- return evaluatePredicateInternal(node.item, item, resolvers, void 0, functions);
343
+ return evaluatePredicateInternal(node.item, item, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth);
341
344
  }))).filter((vote) => vote !== void 0);
342
345
  const combine = node.kind === "some" ? combineOr : combineAnd;
343
346
  const identity = node.kind === "some" ? definite(false) : definite(true);
344
347
  return votes.reduce(combine, identity);
345
348
  }
349
+ case "treeReference": {
350
+ if (resolvers.resolveTree === void 0) return indeterminate("wrong-type", "no tree resolver registered for treeReference nodes");
351
+ const keyString = JSON.stringify(node.key);
352
+ if (visitedTreeKeys.has(keyString)) return indeterminate("domain-error", "circular treeReference detected");
353
+ if (treeReferenceDepth >= MAX_TREE_REFERENCE_DEPTH) return indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${MAX_TREE_REFERENCE_DEPTH.toString()}`);
354
+ const resolution = await resolvers.resolveTree(node.key, context);
355
+ if (!resolution.found) return indeterminate("not-found", "treeReference key did not resolve to a tree");
356
+ const parsed = PredicateNodeSchema.safeParse(resolution.node);
357
+ if (!parsed.success) return indeterminate("wrong-type", "the referenced tree is not a valid PredicateNode");
358
+ return evaluatePredicateInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1);
359
+ }
346
360
  default: throw new Error("unreachable predicate node kind");
347
361
  }
348
362
  }
349
- async function evaluateValueInternal(node, context, resolvers, accumulator, functions) {
363
+ async function evaluateValueInternal(node, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth) {
350
364
  switch (node.kind) {
351
365
  case "reference": {
352
366
  const resolution = await resolvers.resolveValue(node.key, context);
@@ -361,7 +375,7 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
361
375
  if (accumulator === void 0) return indeterminate("wrong-type", "accumulator used outside a reduce fold's combine expression");
362
376
  return definite(accumulator);
363
377
  case "call": {
364
- const argResults = await Promise.all(node.args.map(async (arg) => evaluateValueInternal(arg, context, resolvers, accumulator, functions)));
378
+ const argResults = await Promise.all(node.args.map(async (arg) => evaluateValueInternal(arg, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)));
365
379
  const args = [];
366
380
  for (const result of argResults) {
367
381
  if (result.status === "indeterminate") return result;
@@ -392,18 +406,18 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
392
406
  unit: node.unit
393
407
  });
394
408
  case "arithmetic": {
395
- const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions), evaluateValueInternal(node.right, context, resolvers, accumulator, functions)]);
409
+ const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth), evaluateValueInternal(node.right, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)]);
396
410
  if (left.status === "indeterminate") return left;
397
411
  if (right.status === "indeterminate") return right;
398
412
  return applyArithmetic(node.op, left.value, right.value);
399
413
  }
400
414
  case "negate": {
401
- const operand = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions);
415
+ const operand = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
402
416
  if (operand.status === "indeterminate") return operand;
403
417
  return applyNegate(operand.value);
404
418
  }
405
419
  case "lookup": {
406
- const keyResults = await Promise.all(node.keys.map(async (key) => evaluateValueInternal(key, context, resolvers, accumulator, functions)));
420
+ const keyResults = await Promise.all(node.keys.map(async (key) => evaluateValueInternal(key, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)));
407
421
  const keyValues = [];
408
422
  for (const result of keyResults) {
409
423
  if (result.status === "indeterminate") return result;
@@ -413,15 +427,32 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
413
427
  if (!resolution.found) return indeterminate("not-found", `no match found in lookup table ${JSON.stringify(node.table)}`);
414
428
  return definite(resolution.value);
415
429
  }
416
- case "conditional":
417
- for (const { when, then } of node.cases) {
418
- const whenResult = await evaluatePredicateInternal(when, context, resolvers, accumulator, functions);
419
- if (whenResult.status === "indeterminate") return whenResult;
420
- if (whenResult.value) return evaluateValueInternal(then, context, resolvers, accumulator, functions);
430
+ case "conditional": {
431
+ if ((node.hitPolicy ?? "first") === "first") {
432
+ for (const { when, then } of node.cases) {
433
+ const whenResult = await evaluatePredicateInternal(when, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
434
+ if (whenResult.status === "indeterminate") return whenResult;
435
+ if (whenResult.value) return evaluateValueInternal(then, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
436
+ }
437
+ return evaluateValueInternal(node.fallback, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
421
438
  }
422
- return evaluateValueInternal(node.fallback, context, resolvers, accumulator, functions);
439
+ const evaluatedCases = await Promise.all(node.cases.map(async ({ when, then }) => ({
440
+ then,
441
+ whenResult: await evaluatePredicateInternal(when, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)
442
+ })));
443
+ const matches = evaluatedCases.filter(({ whenResult }) => whenResult.status === "definite" && whenResult.value);
444
+ if (matches.length >= 2) return indeterminate("domain-error", "more than one case matched under the 'unique' hit policy");
445
+ const reason = firstIndeterminate(...evaluatedCases.map(({ whenResult }) => whenResult));
446
+ if (reason !== void 0) return {
447
+ status: "indeterminate",
448
+ reason
449
+ };
450
+ const [match] = matches;
451
+ if (match === void 0) return evaluateValueInternal(node.fallback, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
452
+ return evaluateValueInternal(match.then, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth);
453
+ }
423
454
  case "fold": {
424
- const participating = await resolveParticipatingItems(node.collection, node.filter, context, resolvers, functions);
455
+ const participating = await resolveParticipatingItems(node.collection, node.filter, context, resolvers, functions, visitedTreeKeys, treeReferenceDepth);
425
456
  const filterIndeterminateReason = firstFilterIndeterminate(participating);
426
457
  if (filterIndeterminateReason !== void 0) return {
427
458
  status: "indeterminate",
@@ -429,11 +460,11 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
429
460
  };
430
461
  const includedItems = participating.filter(({ filterOutcome }) => filterOutcome === "include").map(({ item }) => item);
431
462
  if (node.combiner.mode === "reduce") {
432
- const initialResult = await evaluateValueInternal(node.combiner.initial, context, resolvers, void 0, functions);
463
+ const initialResult = await evaluateValueInternal(node.combiner.initial, context, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth);
433
464
  if (initialResult.status === "indeterminate") return initialResult;
434
465
  let runningAccumulator = initialResult.value;
435
466
  for (const item of includedItems) {
436
- const stepResult = await evaluateValueInternal(node.combiner.combine, item, resolvers, runningAccumulator, functions);
467
+ const stepResult = await evaluateValueInternal(node.combiner.combine, item, resolvers, runningAccumulator, functions, visitedTreeKeys, treeReferenceDepth);
437
468
  if (stepResult.status === "indeterminate") return stepResult;
438
469
  runningAccumulator = stepResult.value;
439
470
  }
@@ -443,7 +474,7 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
443
474
  const dominatesOp = node.combiner.mode === "max" ? "gt" : "lt";
444
475
  let runningExtremum;
445
476
  for (const item of includedItems) {
446
- const itemResult = await evaluateValueInternal(node.combiner.item, item, resolvers, void 0, functions);
477
+ const itemResult = await evaluateValueInternal(node.combiner.item, item, resolvers, void 0, functions, visitedTreeKeys, treeReferenceDepth);
447
478
  if (itemResult.status === "indeterminate") return itemResult;
448
479
  if (runningExtremum === void 0) {
449
480
  runningExtremum = itemResult.value;
@@ -462,6 +493,17 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
462
493
  if (!resolution.found) return indeterminate("not-found", `delegate handler for external system '${node.system}' reported no value`);
463
494
  return definite(resolution.value);
464
495
  }
496
+ case "treeReference": {
497
+ if (resolvers.resolveTree === void 0) return indeterminate("wrong-type", "no tree resolver registered for treeReference nodes");
498
+ const keyString = JSON.stringify(node.key);
499
+ if (visitedTreeKeys.has(keyString)) return indeterminate("domain-error", "circular treeReference detected");
500
+ if (treeReferenceDepth >= MAX_TREE_REFERENCE_DEPTH) return indeterminate("domain-error", `treeReference chain exceeds the maximum depth of ${MAX_TREE_REFERENCE_DEPTH.toString()}`);
501
+ const resolution = await resolvers.resolveTree(node.key, context);
502
+ if (!resolution.found) return indeterminate("not-found", "treeReference key did not resolve to a tree");
503
+ const parsed = ExpressionNodeSchema.safeParse(resolution.node);
504
+ if (!parsed.success) return indeterminate("wrong-type", "the referenced tree is not a valid ExpressionNode");
505
+ return evaluateValueInternal(parsed.data, context, resolvers, accumulator, functions, /* @__PURE__ */ new Set([...visitedTreeKeys, keyString]), treeReferenceDepth + 1);
506
+ }
465
507
  default: throw new Error("unreachable expression node kind");
466
508
  }
467
509
  }
@@ -470,8 +512,8 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
470
512
  */
471
513
  function createEvaluator({ functions = emptyFunctionRegistry }) {
472
514
  return {
473
- evaluatePredicate: async (node, context, resolvers) => evaluatePredicateInternal(node, context, resolvers, void 0, functions),
474
- evaluateValue: async (node, context, resolvers) => evaluateValueInternal(node, context, resolvers, void 0, functions)
515
+ evaluatePredicate: async (node, context, resolvers) => evaluatePredicateInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0),
516
+ evaluateValue: async (node, context, resolvers) => evaluateValueInternal(node, context, resolvers, void 0, functions, /* @__PURE__ */ new Set(), 0)
475
517
  };
476
518
  }
477
519
  const { evaluatePredicate, evaluateValue } = createEvaluator({});
package/dist/index.cjs CHANGED
@@ -2,11 +2,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  const require_computed_value = require("./computed-value.cjs");
3
3
  const require_derived_aggregates = require("./derived-aggregates.cjs");
4
4
  const require_derived_connectives = require("./derived-connectives.cjs");
5
+ const require_derived_values = require("./derived-values.cjs");
5
6
  const require_evaluation = require("./evaluation.cjs");
6
7
  const require_functions = require("./functions.cjs");
7
- const require_evaluator = require("./evaluator.cjs");
8
8
  const require_json_value = require("./json-value.cjs");
9
9
  const require_tree = require("./tree.cjs");
10
+ const require_evaluator = require("./evaluator.cjs");
10
11
  exports.AccumulatorNodeSchema = require_tree.AccumulatorNodeSchema;
11
12
  exports.AllOfNodeSchema = require_tree.AllOfNodeSchema;
12
13
  exports.AndNodeSchema = require_tree.AndNodeSchema;
@@ -27,6 +28,7 @@ exports.ExistsNodeSchema = require_tree.ExistsNodeSchema;
27
28
  exports.ExpressionNodeSchema = require_tree.ExpressionNodeSchema;
28
29
  exports.FoldCombinerSchema = require_tree.FoldCombinerSchema;
29
30
  exports.FoldNodeSchema = require_tree.FoldNodeSchema;
31
+ exports.HitPolicySchema = require_tree.HitPolicySchema;
30
32
  exports.IndeterminateReasonSchema = require_evaluation.IndeterminateReasonSchema;
31
33
  exports.InstantLiteralNodeSchema = require_tree.InstantLiteralNodeSchema;
32
34
  exports.JsonValueSchema = require_json_value.JsonValueSchema;
@@ -43,9 +45,11 @@ exports.SomeNodeSchema = require_tree.SomeNodeSchema;
43
45
  exports.TextCompareNodeSchema = require_tree.TextCompareNodeSchema;
44
46
  exports.TextComparisonOperatorSchema = require_tree.TextComparisonOperatorSchema;
45
47
  exports.TextLiteralNodeSchema = require_tree.TextLiteralNodeSchema;
48
+ exports.TreeReferenceNodeSchema = require_tree.TreeReferenceNodeSchema;
46
49
  exports.UnitSchema = require_computed_value.UnitSchema;
47
50
  exports.and = require_derived_connectives.and;
48
51
  exports.average = require_derived_aggregates.average;
52
+ exports.coalesce = require_derived_values.coalesce;
49
53
  exports.combineUnitsForDivide = require_computed_value.combineUnitsForDivide;
50
54
  exports.combineUnitsForMultiply = require_computed_value.combineUnitsForMultiply;
51
55
  exports.count = require_derived_aggregates.count;
package/dist/index.d.cts CHANGED
@@ -1,10 +1,11 @@
1
1
  import { ComputedValue, ComputedValueSchema, DurationUnit, DurationUnitSchema, Unit, UnitSchema, combineUnitsForDivide, combineUnitsForMultiply, unitsEqual } from "./computed-value.cjs";
2
2
  import { n as JsonValueSchema, t as JsonValue } from "./json-value-B1Hjjjri.cjs";
3
- import { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema } from "./tree.cjs";
3
+ import { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, HitPolicy, HitPolicySchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema, TreeReferenceNode, TreeReferenceNodeSchema } from "./tree.cjs";
4
4
  import { average, count, presenceOf, sum } from "./derived-aggregates.cjs";
5
5
  import { and, iff, implies, nand, none, nor, not, or, xor } from "./derived-connectives.cjs";
6
+ import { coalesce } from "./derived-values.cjs";
6
7
  import { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate } from "./evaluation.cjs";
7
8
  import { FunctionRegistry, emptyFunctionRegistry } from "./functions.cjs";
8
- import { EvaluationContext, Resolution, Resolvers } from "./resolvers.cjs";
9
+ import { EvaluationContext, Resolution, Resolvers, TreeResolution } from "./resolvers.cjs";
9
10
  import { createEvaluator, evaluatePredicate, evaluateValue } from "./evaluator.cjs";
10
- export { type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type Evaluation, type EvaluationContext, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionRegistry, type IndeterminateReason, IndeterminateReasonSchema, 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 TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type Unit, UnitSchema, and, average, combineUnitsForDivide, combineUnitsForMultiply, count, createEvaluator, definite, emptyFunctionRegistry, evaluatePredicate, evaluateValue, firstIndeterminate, iff, implies, indeterminate, nand, none, nor, not, or, presenceOf, sum, unitsEqual, xor };
11
+ export { type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type Evaluation, type EvaluationContext, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionRegistry, type HitPolicy, HitPolicySchema, type IndeterminateReason, IndeterminateReasonSchema, 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 TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type TreeReferenceNode, TreeReferenceNodeSchema, type TreeResolution, type Unit, UnitSchema, and, average, coalesce, combineUnitsForDivide, combineUnitsForMultiply, count, createEvaluator, definite, emptyFunctionRegistry, evaluatePredicate, evaluateValue, firstIndeterminate, iff, implies, indeterminate, nand, none, nor, not, or, presenceOf, sum, unitsEqual, xor };
package/dist/index.d.ts CHANGED
@@ -1,10 +1,11 @@
1
1
  import { ComputedValue, ComputedValueSchema, DurationUnit, DurationUnitSchema, Unit, UnitSchema, combineUnitsForDivide, combineUnitsForMultiply, unitsEqual } from "./computed-value.js";
2
2
  import { n as JsonValueSchema, t as JsonValue } from "./json-value-B1Hjjjri.js";
3
- import { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema } from "./tree.js";
3
+ import { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, HitPolicy, HitPolicySchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema, TreeReferenceNode, TreeReferenceNodeSchema } from "./tree.js";
4
4
  import { average, count, presenceOf, sum } from "./derived-aggregates.js";
5
5
  import { and, iff, implies, nand, none, nor, not, or, xor } from "./derived-connectives.js";
6
+ import { coalesce } from "./derived-values.js";
6
7
  import { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate } from "./evaluation.js";
7
8
  import { FunctionRegistry, emptyFunctionRegistry } from "./functions.js";
8
- import { EvaluationContext, Resolution, Resolvers } from "./resolvers.js";
9
+ import { EvaluationContext, Resolution, Resolvers, TreeResolution } from "./resolvers.js";
9
10
  import { createEvaluator, evaluatePredicate, evaluateValue } from "./evaluator.js";
10
- export { type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type Evaluation, type EvaluationContext, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionRegistry, type IndeterminateReason, IndeterminateReasonSchema, 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 TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type Unit, UnitSchema, and, average, combineUnitsForDivide, combineUnitsForMultiply, count, createEvaluator, definite, emptyFunctionRegistry, evaluatePredicate, evaluateValue, firstIndeterminate, iff, implies, indeterminate, nand, none, nor, not, or, presenceOf, sum, unitsEqual, xor };
11
+ export { type AccumulatorNode, AccumulatorNodeSchema, type AllOfNode, AllOfNodeSchema, type AndNode, AndNodeSchema, type AnyOfNode, AnyOfNodeSchema, type ArithmeticNode, ArithmeticNodeSchema, type ArithmeticOperator, ArithmeticOperatorSchema, type CallNode, CallNodeSchema, type CompareNode, CompareNodeSchema, type ComparisonOperator, ComparisonOperatorSchema, type ComputedValue, ComputedValueSchema, type ConditionalCase, ConditionalCaseSchema, type ConditionalNode, ConditionalNodeSchema, type DelegateNode, DelegateNodeSchema, type DurationLiteralNode, DurationLiteralNodeSchema, type DurationUnit, DurationUnitSchema, type Evaluation, type EvaluationContext, type EveryNode, EveryNodeSchema, type ExistsNode, ExistsNodeSchema, type ExpressionNode, ExpressionNodeSchema, type FoldCombiner, FoldCombinerSchema, type FoldNode, FoldNodeSchema, type FunctionRegistry, type HitPolicy, HitPolicySchema, type IndeterminateReason, IndeterminateReasonSchema, 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 TextCompareNode, TextCompareNodeSchema, type TextComparisonOperator, TextComparisonOperatorSchema, type TextLiteralNode, TextLiteralNodeSchema, type TreeReferenceNode, TreeReferenceNodeSchema, type TreeResolution, type Unit, UnitSchema, and, average, coalesce, combineUnitsForDivide, combineUnitsForMultiply, count, createEvaluator, definite, emptyFunctionRegistry, evaluatePredicate, evaluateValue, firstIndeterminate, iff, implies, indeterminate, nand, none, nor, not, or, presenceOf, sum, unitsEqual, xor };
package/dist/index.js CHANGED
@@ -1,9 +1,10 @@
1
1
  import { ComputedValueSchema, DurationUnitSchema, UnitSchema, combineUnitsForDivide, combineUnitsForMultiply, unitsEqual } from "./computed-value.js";
2
2
  import { average, count, presenceOf, sum } from "./derived-aggregates.js";
3
3
  import { and, iff, implies, nand, none, nor, not, or, xor } from "./derived-connectives.js";
4
+ import { coalesce } from "./derived-values.js";
4
5
  import { IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate } from "./evaluation.js";
5
6
  import { emptyFunctionRegistry } from "./functions.js";
6
- import { createEvaluator, evaluatePredicate, evaluateValue } from "./evaluator.js";
7
7
  import { JsonValueSchema } from "./json-value.js";
8
- import { AccumulatorNodeSchema, AllOfNodeSchema, AndNodeSchema, AnyOfNodeSchema, ArithmeticNodeSchema, ArithmeticOperatorSchema, CallNodeSchema, CompareNodeSchema, ComparisonOperatorSchema, ConditionalCaseSchema, ConditionalNodeSchema, DelegateNodeSchema, DurationLiteralNodeSchema, EveryNodeSchema, ExistsNodeSchema, ExpressionNodeSchema, FoldCombinerSchema, FoldNodeSchema, InstantLiteralNodeSchema, LookupNodeSchema, MemberOfNodeSchema, MembershipOperatorSchema, NegateNodeSchema, NotNodeSchema, NumberLiteralNodeSchema, OrNodeSchema, PredicateNodeSchema, ReferenceNodeSchema, SomeNodeSchema, TextCompareNodeSchema, TextComparisonOperatorSchema, TextLiteralNodeSchema } from "./tree.js";
9
- export { AccumulatorNodeSchema, AllOfNodeSchema, AndNodeSchema, AnyOfNodeSchema, ArithmeticNodeSchema, ArithmeticOperatorSchema, CallNodeSchema, CompareNodeSchema, ComparisonOperatorSchema, ComputedValueSchema, ConditionalCaseSchema, ConditionalNodeSchema, DelegateNodeSchema, DurationLiteralNodeSchema, DurationUnitSchema, EveryNodeSchema, ExistsNodeSchema, ExpressionNodeSchema, FoldCombinerSchema, FoldNodeSchema, IndeterminateReasonSchema, InstantLiteralNodeSchema, JsonValueSchema, LookupNodeSchema, MemberOfNodeSchema, MembershipOperatorSchema, NegateNodeSchema, NotNodeSchema, NumberLiteralNodeSchema, OrNodeSchema, PredicateNodeSchema, ReferenceNodeSchema, SomeNodeSchema, TextCompareNodeSchema, TextComparisonOperatorSchema, TextLiteralNodeSchema, UnitSchema, and, average, combineUnitsForDivide, combineUnitsForMultiply, count, createEvaluator, definite, emptyFunctionRegistry, evaluatePredicate, evaluateValue, firstIndeterminate, iff, implies, indeterminate, nand, none, nor, not, or, presenceOf, sum, unitsEqual, xor };
8
+ import { AccumulatorNodeSchema, AllOfNodeSchema, AndNodeSchema, AnyOfNodeSchema, ArithmeticNodeSchema, ArithmeticOperatorSchema, CallNodeSchema, CompareNodeSchema, ComparisonOperatorSchema, ConditionalCaseSchema, ConditionalNodeSchema, DelegateNodeSchema, DurationLiteralNodeSchema, EveryNodeSchema, ExistsNodeSchema, ExpressionNodeSchema, FoldCombinerSchema, FoldNodeSchema, HitPolicySchema, InstantLiteralNodeSchema, LookupNodeSchema, MemberOfNodeSchema, MembershipOperatorSchema, NegateNodeSchema, NotNodeSchema, NumberLiteralNodeSchema, OrNodeSchema, PredicateNodeSchema, ReferenceNodeSchema, SomeNodeSchema, TextCompareNodeSchema, TextComparisonOperatorSchema, TextLiteralNodeSchema, TreeReferenceNodeSchema } from "./tree.js";
9
+ import { createEvaluator, evaluatePredicate, evaluateValue } from "./evaluator.js";
10
+ export { AccumulatorNodeSchema, AllOfNodeSchema, AndNodeSchema, AnyOfNodeSchema, ArithmeticNodeSchema, ArithmeticOperatorSchema, CallNodeSchema, CompareNodeSchema, ComparisonOperatorSchema, ComputedValueSchema, ConditionalCaseSchema, ConditionalNodeSchema, DelegateNodeSchema, DurationLiteralNodeSchema, DurationUnitSchema, EveryNodeSchema, ExistsNodeSchema, ExpressionNodeSchema, FoldCombinerSchema, FoldNodeSchema, HitPolicySchema, IndeterminateReasonSchema, InstantLiteralNodeSchema, JsonValueSchema, LookupNodeSchema, MemberOfNodeSchema, MembershipOperatorSchema, NegateNodeSchema, NotNodeSchema, NumberLiteralNodeSchema, OrNodeSchema, PredicateNodeSchema, ReferenceNodeSchema, SomeNodeSchema, TextCompareNodeSchema, TextComparisonOperatorSchema, TextLiteralNodeSchema, TreeReferenceNodeSchema, UnitSchema, and, average, coalesce, combineUnitsForDivide, combineUnitsForMultiply, count, createEvaluator, definite, emptyFunctionRegistry, evaluatePredicate, evaluateValue, firstIndeterminate, iff, implies, indeterminate, nand, none, nor, not, or, presenceOf, sum, unitsEqual, xor };
@@ -11,8 +11,15 @@ type Resolution = {
11
11
  } | {
12
12
  found: false;
13
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`. */
15
+ type TreeResolution = {
16
+ found: true;
17
+ node: JsonValue;
18
+ } | {
19
+ found: false;
20
+ };
14
21
  /**
15
- * Three independent points of extension, 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.
22
+ * 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.
16
23
  */
17
24
  interface Resolvers {
18
25
  /** Resolver 1 -- a single opaque key to a single value (`reference`). */
@@ -23,6 +30,8 @@ interface Resolvers {
23
30
  resolveCollection: (collection: JsonValue, context: EvaluationContext) => Promise<unknown[]>;
24
31
  /** Optional, separate from the three core contracts -- see the `delegate` node kind. */
25
32
  resolveDelegate?: (system: string, payload: JsonValue, context: EvaluationContext) => Promise<Resolution>;
33
+ /** Optional, separate from the three core contracts -- see the `treeReference` node kind. Absence is `wrong-type`, the same deliberate-absence treatment as an unregistered `resolveDelegate`, not a masked bug -- and keeps this an additive, non-breaking interface change for every existing consumer. */
34
+ resolveTree?: (key: JsonValue, context: EvaluationContext) => Promise<TreeResolution>;
26
35
  }
27
36
  //#endregion
28
- export { EvaluationContext, Resolution, Resolvers };
37
+ export { EvaluationContext, Resolution, Resolvers, TreeResolution };
@@ -11,8 +11,15 @@ type Resolution = {
11
11
  } | {
12
12
  found: false;
13
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`. */
15
+ type TreeResolution = {
16
+ found: true;
17
+ node: JsonValue;
18
+ } | {
19
+ found: false;
20
+ };
14
21
  /**
15
- * Three independent points of extension, 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.
22
+ * 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.
16
23
  */
17
24
  interface Resolvers {
18
25
  /** Resolver 1 -- a single opaque key to a single value (`reference`). */
@@ -23,6 +30,8 @@ interface Resolvers {
23
30
  resolveCollection: (collection: JsonValue, context: EvaluationContext) => Promise<unknown[]>;
24
31
  /** Optional, separate from the three core contracts -- see the `delegate` node kind. */
25
32
  resolveDelegate?: (system: string, payload: JsonValue, context: EvaluationContext) => Promise<Resolution>;
33
+ /** Optional, separate from the three core contracts -- see the `treeReference` node kind. Absence is `wrong-type`, the same deliberate-absence treatment as an unregistered `resolveDelegate`, not a masked bug -- and keeps this an additive, non-breaking interface change for every existing consumer. */
34
+ resolveTree?: (key: JsonValue, context: EvaluationContext) => Promise<TreeResolution>;
26
35
  }
27
36
  //#endregion
28
- export { EvaluationContext, Resolution, Resolvers };
37
+ export { EvaluationContext, Resolution, Resolvers, TreeResolution };
package/dist/tree.cjs CHANGED
@@ -26,6 +26,7 @@ const ArithmeticOperatorSchema = zod.z.enum([
26
26
  "power",
27
27
  "modulo"
28
28
  ]);
29
+ const HitPolicySchema = zod.z.enum(["first", "unique"]);
29
30
  const NotNodeSchema = zod.z.object({
30
31
  kind: zod.z.literal("not"),
31
32
  get operand() {
@@ -118,6 +119,11 @@ const EveryNodeSchema = zod.z.object({
118
119
  return PredicateNodeSchema.optional();
119
120
  }
120
121
  });
122
+ /** Shared by both trees -- the only node kind valid in both PredicateNodeSchema's and ExpressionNodeSchema's own discriminated unions, appended as the last member of each below. Declared once, here, ahead of the predicate union that needs it first; the expression union further down references this exact same schema object again rather than declaring its own copy. See the `treeReference` section of README.md. */
123
+ const TreeReferenceNodeSchema = zod.z.object({
124
+ kind: zod.z.literal("treeReference"),
125
+ key: require_json_value.JsonValueSchema
126
+ });
121
127
  const PredicateNodeSchema = zod.z.discriminatedUnion("kind", [
122
128
  NotNodeSchema,
123
129
  AndNodeSchema,
@@ -129,7 +135,8 @@ const PredicateNodeSchema = zod.z.discriminatedUnion("kind", [
129
135
  MemberOfNodeSchema,
130
136
  ExistsNodeSchema,
131
137
  SomeNodeSchema,
132
- EveryNodeSchema
138
+ EveryNodeSchema,
139
+ TreeReferenceNodeSchema
133
140
  ]);
134
141
  const NumberLiteralNodeSchema = zod.z.object({
135
142
  kind: zod.z.literal("numberLiteral"),
@@ -195,6 +202,8 @@ const ConditionalCaseSchema = zod.z.object({
195
202
  });
196
203
  const ConditionalNodeSchema = zod.z.object({
197
204
  kind: zod.z.literal("conditional"),
205
+ /** Absent means `"first"` -- the exact, unchanged behaviour of every tree serialised before this field existed. A deliberate, meaningful default, not a masked-bug fallback; see the `conditional` section of README.md for `"unique"`'s own absorption rules. */
206
+ hitPolicy: HitPolicySchema.optional(),
198
207
  get cases() {
199
208
  return zod.z.array(ConditionalCaseSchema);
200
209
  },
@@ -252,7 +261,8 @@ const ExpressionNodeSchema = zod.z.discriminatedUnion("kind", [
252
261
  ConditionalNodeSchema,
253
262
  FoldNodeSchema,
254
263
  AccumulatorNodeSchema,
255
- DelegateNodeSchema
264
+ DelegateNodeSchema,
265
+ TreeReferenceNodeSchema
256
266
  ]);
257
267
  //#endregion
258
268
  exports.AccumulatorNodeSchema = AccumulatorNodeSchema;
@@ -273,6 +283,7 @@ exports.ExistsNodeSchema = ExistsNodeSchema;
273
283
  exports.ExpressionNodeSchema = ExpressionNodeSchema;
274
284
  exports.FoldCombinerSchema = FoldCombinerSchema;
275
285
  exports.FoldNodeSchema = FoldNodeSchema;
286
+ exports.HitPolicySchema = HitPolicySchema;
276
287
  exports.InstantLiteralNodeSchema = InstantLiteralNodeSchema;
277
288
  exports.LookupNodeSchema = LookupNodeSchema;
278
289
  exports.MemberOfNodeSchema = MemberOfNodeSchema;
@@ -287,3 +298,4 @@ exports.SomeNodeSchema = SomeNodeSchema;
287
298
  exports.TextCompareNodeSchema = TextCompareNodeSchema;
288
299
  exports.TextComparisonOperatorSchema = TextComparisonOperatorSchema;
289
300
  exports.TextLiteralNodeSchema = TextLiteralNodeSchema;
301
+ exports.TreeReferenceNodeSchema = TreeReferenceNodeSchema;
package/dist/tree.d.cts CHANGED
@@ -31,6 +31,11 @@ declare const ArithmeticOperatorSchema: z.ZodEnum<{
31
31
  modulo: "modulo";
32
32
  }>;
33
33
  type ArithmeticOperator = z.infer<typeof ArithmeticOperatorSchema>;
34
+ declare const HitPolicySchema: z.ZodEnum<{
35
+ first: "first";
36
+ unique: "unique";
37
+ }>;
38
+ type HitPolicy = z.infer<typeof HitPolicySchema>;
34
39
  declare const NotNodeSchema: z.ZodObject<{
35
40
  kind: z.ZodLiteral<"not">;
36
41
  operand: typeof PredicateNodeSchema;
@@ -113,6 +118,12 @@ declare const EveryNodeSchema: z.ZodObject<{
113
118
  filter: z.ZodOptional<typeof PredicateNodeSchema>;
114
119
  }, z.core.$strip>;
115
120
  type EveryNode = z.infer<typeof EveryNodeSchema>;
121
+ /** Shared by both trees -- the only node kind valid in both PredicateNodeSchema's and ExpressionNodeSchema's own discriminated unions, appended as the last member of each below. Declared once, here, ahead of the predicate union that needs it first; the expression union further down references this exact same schema object again rather than declaring its own copy. See the `treeReference` section of README.md. */
122
+ declare const TreeReferenceNodeSchema: z.ZodObject<{
123
+ kind: z.ZodLiteral<"treeReference">;
124
+ key: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
125
+ }, z.core.$strip>;
126
+ type TreeReferenceNode = z.infer<typeof TreeReferenceNodeSchema>;
116
127
  declare const PredicateNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
117
128
  kind: z.ZodLiteral<"not">;
118
129
  operand: typeof PredicateNodeSchema;
@@ -173,6 +184,9 @@ declare const PredicateNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
173
184
  collection: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
174
185
  item: typeof PredicateNodeSchema;
175
186
  filter: z.ZodOptional<typeof PredicateNodeSchema>;
187
+ }, z.core.$strip>, z.ZodObject<{
188
+ kind: z.ZodLiteral<"treeReference">;
189
+ key: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
176
190
  }, z.core.$strip>], "kind">;
177
191
  type PredicateNode = z.infer<typeof PredicateNodeSchema>;
178
192
  declare const NumberLiteralNodeSchema: z.ZodObject<{
@@ -247,6 +261,10 @@ declare const ConditionalCaseSchema: z.ZodObject<{
247
261
  type ConditionalCase = z.infer<typeof ConditionalCaseSchema>;
248
262
  declare const ConditionalNodeSchema: z.ZodObject<{
249
263
  kind: z.ZodLiteral<"conditional">;
264
+ hitPolicy: z.ZodOptional<z.ZodEnum<{
265
+ first: "first";
266
+ unique: "unique";
267
+ }>>;
250
268
  cases: z.ZodArray<typeof ConditionalCaseSchema>;
251
269
  fallback: typeof ExpressionNodeSchema;
252
270
  }, z.core.$strip>;
@@ -339,6 +357,10 @@ declare const ExpressionNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
339
357
  keys: z.ZodArray<typeof ExpressionNodeSchema>;
340
358
  }, z.core.$strip>, z.ZodObject<{
341
359
  kind: z.ZodLiteral<"conditional">;
360
+ hitPolicy: z.ZodOptional<z.ZodEnum<{
361
+ first: "first";
362
+ unique: "unique";
363
+ }>>;
342
364
  cases: z.ZodArray<typeof ConditionalCaseSchema>;
343
365
  fallback: typeof ExpressionNodeSchema;
344
366
  }, z.core.$strip>, z.ZodObject<{
@@ -362,7 +384,10 @@ declare const ExpressionNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
362
384
  kind: z.ZodLiteral<"delegate">;
363
385
  system: z.ZodString;
364
386
  payload: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
387
+ }, z.core.$strip>, z.ZodObject<{
388
+ kind: z.ZodLiteral<"treeReference">;
389
+ key: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
365
390
  }, z.core.$strip>], "kind">;
366
391
  type ExpressionNode = z.infer<typeof ExpressionNodeSchema>;
367
392
  //#endregion
368
- export { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema };
393
+ export { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, HitPolicy, HitPolicySchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema, TreeReferenceNode, TreeReferenceNodeSchema };
package/dist/tree.d.ts CHANGED
@@ -31,6 +31,11 @@ declare const ArithmeticOperatorSchema: z.ZodEnum<{
31
31
  modulo: "modulo";
32
32
  }>;
33
33
  type ArithmeticOperator = z.infer<typeof ArithmeticOperatorSchema>;
34
+ declare const HitPolicySchema: z.ZodEnum<{
35
+ first: "first";
36
+ unique: "unique";
37
+ }>;
38
+ type HitPolicy = z.infer<typeof HitPolicySchema>;
34
39
  declare const NotNodeSchema: z.ZodObject<{
35
40
  kind: z.ZodLiteral<"not">;
36
41
  operand: typeof PredicateNodeSchema;
@@ -113,6 +118,12 @@ declare const EveryNodeSchema: z.ZodObject<{
113
118
  filter: z.ZodOptional<typeof PredicateNodeSchema>;
114
119
  }, z.core.$strip>;
115
120
  type EveryNode = z.infer<typeof EveryNodeSchema>;
121
+ /** Shared by both trees -- the only node kind valid in both PredicateNodeSchema's and ExpressionNodeSchema's own discriminated unions, appended as the last member of each below. Declared once, here, ahead of the predicate union that needs it first; the expression union further down references this exact same schema object again rather than declaring its own copy. See the `treeReference` section of README.md. */
122
+ declare const TreeReferenceNodeSchema: z.ZodObject<{
123
+ kind: z.ZodLiteral<"treeReference">;
124
+ key: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
125
+ }, z.core.$strip>;
126
+ type TreeReferenceNode = z.infer<typeof TreeReferenceNodeSchema>;
116
127
  declare const PredicateNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
117
128
  kind: z.ZodLiteral<"not">;
118
129
  operand: typeof PredicateNodeSchema;
@@ -173,6 +184,9 @@ declare const PredicateNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
173
184
  collection: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
174
185
  item: typeof PredicateNodeSchema;
175
186
  filter: z.ZodOptional<typeof PredicateNodeSchema>;
187
+ }, z.core.$strip>, z.ZodObject<{
188
+ kind: z.ZodLiteral<"treeReference">;
189
+ key: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
176
190
  }, z.core.$strip>], "kind">;
177
191
  type PredicateNode = z.infer<typeof PredicateNodeSchema>;
178
192
  declare const NumberLiteralNodeSchema: z.ZodObject<{
@@ -247,6 +261,10 @@ declare const ConditionalCaseSchema: z.ZodObject<{
247
261
  type ConditionalCase = z.infer<typeof ConditionalCaseSchema>;
248
262
  declare const ConditionalNodeSchema: z.ZodObject<{
249
263
  kind: z.ZodLiteral<"conditional">;
264
+ hitPolicy: z.ZodOptional<z.ZodEnum<{
265
+ first: "first";
266
+ unique: "unique";
267
+ }>>;
250
268
  cases: z.ZodArray<typeof ConditionalCaseSchema>;
251
269
  fallback: typeof ExpressionNodeSchema;
252
270
  }, z.core.$strip>;
@@ -339,6 +357,10 @@ declare const ExpressionNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
339
357
  keys: z.ZodArray<typeof ExpressionNodeSchema>;
340
358
  }, z.core.$strip>, z.ZodObject<{
341
359
  kind: z.ZodLiteral<"conditional">;
360
+ hitPolicy: z.ZodOptional<z.ZodEnum<{
361
+ first: "first";
362
+ unique: "unique";
363
+ }>>;
342
364
  cases: z.ZodArray<typeof ConditionalCaseSchema>;
343
365
  fallback: typeof ExpressionNodeSchema;
344
366
  }, z.core.$strip>, z.ZodObject<{
@@ -362,7 +384,10 @@ declare const ExpressionNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
362
384
  kind: z.ZodLiteral<"delegate">;
363
385
  system: z.ZodString;
364
386
  payload: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
387
+ }, z.core.$strip>, z.ZodObject<{
388
+ kind: z.ZodLiteral<"treeReference">;
389
+ key: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
365
390
  }, z.core.$strip>], "kind">;
366
391
  type ExpressionNode = z.infer<typeof ExpressionNodeSchema>;
367
392
  //#endregion
368
- export { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema };
393
+ export { AccumulatorNode, AccumulatorNodeSchema, AllOfNode, AllOfNodeSchema, AndNode, AndNodeSchema, AnyOfNode, AnyOfNodeSchema, ArithmeticNode, ArithmeticNodeSchema, ArithmeticOperator, ArithmeticOperatorSchema, CallNode, CallNodeSchema, CompareNode, CompareNodeSchema, ComparisonOperator, ComparisonOperatorSchema, ConditionalCase, ConditionalCaseSchema, ConditionalNode, ConditionalNodeSchema, DelegateNode, DelegateNodeSchema, DurationLiteralNode, DurationLiteralNodeSchema, EveryNode, EveryNodeSchema, ExistsNode, ExistsNodeSchema, ExpressionNode, ExpressionNodeSchema, FoldCombiner, FoldCombinerSchema, FoldNode, FoldNodeSchema, HitPolicy, HitPolicySchema, InstantLiteralNode, InstantLiteralNodeSchema, LookupNode, LookupNodeSchema, MemberOfNode, MemberOfNodeSchema, MembershipOperator, MembershipOperatorSchema, NegateNode, NegateNodeSchema, NotNode, NotNodeSchema, NumberLiteralNode, NumberLiteralNodeSchema, OrNode, OrNodeSchema, PredicateNode, PredicateNodeSchema, ReferenceNode, ReferenceNodeSchema, SomeNode, SomeNodeSchema, TextCompareNode, TextCompareNodeSchema, TextComparisonOperator, TextComparisonOperatorSchema, TextLiteralNode, TextLiteralNodeSchema, TreeReferenceNode, TreeReferenceNodeSchema };