trilean 1.7.11 → 1.8.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.
Files changed (56) hide show
  1. package/README.md +33 -13
  2. package/dist/builtin-functions.cjs +129 -0
  3. package/dist/builtin-functions.d.cts +13 -0
  4. package/dist/builtin-functions.d.ts +13 -0
  5. package/dist/builtin-functions.js +128 -0
  6. package/dist/complex-division.cjs +48 -0
  7. package/dist/complex-division.d.cts +25 -0
  8. package/dist/complex-division.d.ts +25 -0
  9. package/dist/complex-division.js +47 -0
  10. package/dist/duration-order.cjs +84 -0
  11. package/dist/duration-order.d.cts +22 -0
  12. package/dist/duration-order.d.ts +22 -0
  13. package/dist/duration-order.js +82 -0
  14. package/dist/evaluate-document.cjs +87 -0
  15. package/dist/evaluate-document.d.cts +40 -0
  16. package/dist/evaluate-document.d.ts +40 -0
  17. package/dist/evaluate-document.js +86 -0
  18. package/dist/evaluator-collection.d.cts +1 -1
  19. package/dist/evaluator-collection.d.ts +1 -1
  20. package/dist/evaluator-factory.d.cts +1 -1
  21. package/dist/evaluator-factory.d.ts +1 -1
  22. package/dist/evaluator-indeterminacy-helpers.cjs +1 -1
  23. package/dist/evaluator-indeterminacy-helpers.d.cts +1 -1
  24. package/dist/evaluator-indeterminacy-helpers.d.ts +1 -1
  25. package/dist/evaluator-indeterminacy-helpers.js +1 -1
  26. package/dist/evaluator-operations.cjs +75 -24
  27. package/dist/evaluator-operations.d.cts +3 -3
  28. package/dist/evaluator-operations.d.ts +3 -3
  29. package/dist/evaluator-operations.js +74 -23
  30. package/dist/evaluator-test-helpers.cjs +1 -1
  31. package/dist/evaluator-test-helpers.js +1 -1
  32. package/dist/evaluator.d.cts +1 -1
  33. package/dist/evaluator.d.ts +1 -1
  34. package/dist/functions.d.cts +8 -4
  35. package/dist/functions.d.ts +8 -4
  36. package/dist/{index.C4tKZ0yW-CfMRGP9u.js → index.C4tKZ0yW-ICJbIYnA.js} +11 -11
  37. package/dist/{index.C4tKZ0yW-CZW6CdWn.cjs → index.C4tKZ0yW-q5POG9-K.cjs} +10 -10
  38. package/dist/index.cjs +8 -1
  39. package/dist/index.d.cts +5 -2
  40. package/dist/index.d.ts +5 -2
  41. package/dist/index.js +5 -2
  42. package/dist/input-resolvers.cjs +63 -0
  43. package/dist/input-resolvers.d.cts +19 -0
  44. package/dist/input-resolvers.d.ts +19 -0
  45. package/dist/input-resolvers.js +61 -0
  46. package/dist/integer-power.cjs +20 -0
  47. package/dist/integer-power.d.cts +13 -0
  48. package/dist/integer-power.d.ts +13 -0
  49. package/dist/integer-power.js +19 -0
  50. package/dist/plain-record.cjs +8 -0
  51. package/dist/plain-record.d.cts +4 -0
  52. package/dist/plain-record.d.ts +4 -0
  53. package/dist/plain-record.js +7 -0
  54. package/dist-cli/trilean.mjs +1745 -0
  55. package/package.json +7 -3
  56. package/schemas/trilean.schema.json +1 -1
@@ -0,0 +1,84 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ //#region src/duration-order.ts
3
+ /** How many milliseconds one of each duration unit is. Every unit is a whole multiple of every finer one, which is what lets a value be divided down into a coarser unit by an exact integer. */
4
+ const millisecondsPerDurationUnit = {
5
+ ms: 1,
6
+ s: 1e3,
7
+ min: 6e4,
8
+ h: 36e5,
9
+ d: 864e5
10
+ };
11
+ const ONE = 1n;
12
+ const FRACTION_BITS = 52n;
13
+ const FRACTION_MASK = (ONE << FRACTION_BITS) - ONE;
14
+ const IMPLICIT_LEADING_BIT = ONE << FRACTION_BITS;
15
+ const EXPONENT_FIELD_MASK = 2047n;
16
+ const EXPONENT_BIAS_WITH_FRACTION = 1075;
17
+ const SUBNORMAL_EXPONENT = -1074;
18
+ const scratchValue = /* @__PURE__ */ new Float64Array(1);
19
+ const scratchBits = new BigUint64Array(scratchValue.buffer);
20
+ /** A finite double as `significand * 2 ** exponent` with an integer significand, exactly, read from its bit pattern. Zero has a zero significand. */
21
+ function exactParts(magnitude) {
22
+ scratchValue[0] = magnitude;
23
+ const bits = scratchBits[0];
24
+ if (bits === void 0) throw new Error("a one-element array always has an element zero");
25
+ const exponentField = Number(bits >> FRACTION_BITS & EXPONENT_FIELD_MASK);
26
+ const fraction = bits & FRACTION_MASK;
27
+ if (exponentField === 0) return {
28
+ significand: fraction,
29
+ exponent: SUBNORMAL_EXPONENT
30
+ };
31
+ return {
32
+ significand: fraction | IMPLICIT_LEADING_BIT,
33
+ exponent: exponentField - EXPONENT_BIAS_WITH_FRACTION
34
+ };
35
+ }
36
+ function orderOf(left, right) {
37
+ if (left < right) return -1;
38
+ return left > right ? 1 : 0;
39
+ }
40
+ /** The exact order of `left * leftSize` and `right * rightSize` for finite doubles and positive integer sizes, by comparing the products as integers once both are written over a common power of two. */
41
+ function exactOrder(left, right) {
42
+ const leftSign = Math.sign(left.value);
43
+ const rightSign = Math.sign(right.value);
44
+ if (leftSign !== rightSign) return leftSign < rightSign ? -1 : 1;
45
+ if (leftSign === 0) return 0;
46
+ const leftParts = exactParts(Math.abs(left.value));
47
+ const rightParts = exactParts(Math.abs(right.value));
48
+ let leftProduct = leftParts.significand * BigInt(left.size);
49
+ let rightProduct = rightParts.significand * BigInt(right.size);
50
+ const shift = leftParts.exponent - rightParts.exponent;
51
+ if (shift > 0) leftProduct <<= BigInt(shift);
52
+ else rightProduct <<= BigInt(-shift);
53
+ return leftSign < 0 ? orderOf(rightProduct, leftProduct) : orderOf(leftProduct, rightProduct);
54
+ }
55
+ /**
56
+ * The order of two durations: -1, 0 or 1, or `undefined` when a NaN makes them unordered.
57
+ *
58
+ * A value that is not finite is handled first, as numbers are: a NaN is unordered against everything (so every comparison with it is false, and `neq` true), and an infinity is equal to the same infinity and greater or less than anything finite whatever the units, since a unit only scales by a positive amount. The bit-pattern comparison below reads a finite double's exact value and has no meaning for these.
59
+ *
60
+ * Two finite durations are ordered exactly, with no overflow and no underflow. Both are divided into the coarser of the two units. A division by an exact integer is correctly rounded and rounding is monotone, so it can collapse a difference into equality but never reverse an order: when the two rounded values differ their order is the true order, and that settles almost every comparison without leaving floating point. Dividing can lose the difference, though: two close values round to the same double, and a subnormal rounds to zero. Only when the rounded values are equal is the answer settled exactly, from the doubles' binary expansions, by comparing each value times its unit's size in milliseconds as integers.
61
+ *
62
+ * Converting both to milliseconds by multiplying instead overflows for spans of days beyond roughly 1e300, which is why it is not done here.
63
+ */
64
+ function compareDurations(left, right) {
65
+ if (Number.isNaN(left.value) || Number.isNaN(right.value)) return void 0;
66
+ if (!Number.isFinite(left.value) || !Number.isFinite(right.value)) return orderOf(left.value, right.value);
67
+ const leftSize = millisecondsPerDurationUnit[left.unit];
68
+ const rightSize = millisecondsPerDurationUnit[right.unit];
69
+ const sharedSize = Math.max(leftSize, rightSize);
70
+ const leftInShared = left.value / (sharedSize / leftSize);
71
+ const rightInShared = right.value / (sharedSize / rightSize);
72
+ if (leftInShared < rightInShared) return -1;
73
+ if (leftInShared > rightInShared) return 1;
74
+ return exactOrder({
75
+ value: left.value,
76
+ size: leftSize
77
+ }, {
78
+ value: right.value,
79
+ size: rightSize
80
+ });
81
+ }
82
+ //#endregion
83
+ exports.compareDurations = compareDurations;
84
+ exports.millisecondsPerDurationUnit = millisecondsPerDurationUnit;
@@ -0,0 +1,22 @@
1
+ import { r as DurationUnit } from "./computed-value-CbRF0Izc.cjs";
2
+ //#region src/duration-order.d.ts
3
+ /** How many milliseconds one of each duration unit is. Every unit is a whole multiple of every finer one, which is what lets a value be divided down into a coarser unit by an exact integer. */
4
+ export declare const millisecondsPerDurationUnit: Record<DurationUnit, number>;
5
+ type Ordering = -1 | 0 | 1;
6
+ /**
7
+ * The order of two durations: -1, 0 or 1, or `undefined` when a NaN makes them unordered.
8
+ *
9
+ * A value that is not finite is handled first, as numbers are: a NaN is unordered against everything (so every comparison with it is false, and `neq` true), and an infinity is equal to the same infinity and greater or less than anything finite whatever the units, since a unit only scales by a positive amount. The bit-pattern comparison below reads a finite double's exact value and has no meaning for these.
10
+ *
11
+ * Two finite durations are ordered exactly, with no overflow and no underflow. Both are divided into the coarser of the two units. A division by an exact integer is correctly rounded and rounding is monotone, so it can collapse a difference into equality but never reverse an order: when the two rounded values differ their order is the true order, and that settles almost every comparison without leaving floating point. Dividing can lose the difference, though: two close values round to the same double, and a subnormal rounds to zero. Only when the rounded values are equal is the answer settled exactly, from the doubles' binary expansions, by comparing each value times its unit's size in milliseconds as integers.
12
+ *
13
+ * Converting both to milliseconds by multiplying instead overflows for spans of days beyond roughly 1e300, which is why it is not done here.
14
+ */
15
+ export declare function compareDurations(left: Readonly<{
16
+ value: number;
17
+ unit: DurationUnit;
18
+ }>, right: Readonly<{
19
+ value: number;
20
+ unit: DurationUnit;
21
+ }>): Ordering | undefined;
22
+ //#endregion
@@ -0,0 +1,22 @@
1
+ import { r as DurationUnit } from "./computed-value-CbRF0Izc.js";
2
+ //#region src/duration-order.d.ts
3
+ /** How many milliseconds one of each duration unit is. Every unit is a whole multiple of every finer one, which is what lets a value be divided down into a coarser unit by an exact integer. */
4
+ export declare const millisecondsPerDurationUnit: Record<DurationUnit, number>;
5
+ type Ordering = -1 | 0 | 1;
6
+ /**
7
+ * The order of two durations: -1, 0 or 1, or `undefined` when a NaN makes them unordered.
8
+ *
9
+ * A value that is not finite is handled first, as numbers are: a NaN is unordered against everything (so every comparison with it is false, and `neq` true), and an infinity is equal to the same infinity and greater or less than anything finite whatever the units, since a unit only scales by a positive amount. The bit-pattern comparison below reads a finite double's exact value and has no meaning for these.
10
+ *
11
+ * Two finite durations are ordered exactly, with no overflow and no underflow. Both are divided into the coarser of the two units. A division by an exact integer is correctly rounded and rounding is monotone, so it can collapse a difference into equality but never reverse an order: when the two rounded values differ their order is the true order, and that settles almost every comparison without leaving floating point. Dividing can lose the difference, though: two close values round to the same double, and a subnormal rounds to zero. Only when the rounded values are equal is the answer settled exactly, from the doubles' binary expansions, by comparing each value times its unit's size in milliseconds as integers.
12
+ *
13
+ * Converting both to milliseconds by multiplying instead overflows for spans of days beyond roughly 1e300, which is why it is not done here.
14
+ */
15
+ export declare function compareDurations(left: Readonly<{
16
+ value: number;
17
+ unit: DurationUnit;
18
+ }>, right: Readonly<{
19
+ value: number;
20
+ unit: DurationUnit;
21
+ }>): Ordering | undefined;
22
+ //#endregion
@@ -0,0 +1,82 @@
1
+ //#region src/duration-order.ts
2
+ /** How many milliseconds one of each duration unit is. Every unit is a whole multiple of every finer one, which is what lets a value be divided down into a coarser unit by an exact integer. */
3
+ const millisecondsPerDurationUnit = {
4
+ ms: 1,
5
+ s: 1e3,
6
+ min: 6e4,
7
+ h: 36e5,
8
+ d: 864e5
9
+ };
10
+ const ONE = 1n;
11
+ const FRACTION_BITS = 52n;
12
+ const FRACTION_MASK = (ONE << FRACTION_BITS) - ONE;
13
+ const IMPLICIT_LEADING_BIT = ONE << FRACTION_BITS;
14
+ const EXPONENT_FIELD_MASK = 2047n;
15
+ const EXPONENT_BIAS_WITH_FRACTION = 1075;
16
+ const SUBNORMAL_EXPONENT = -1074;
17
+ const scratchValue = /* @__PURE__ */ new Float64Array(1);
18
+ const scratchBits = new BigUint64Array(scratchValue.buffer);
19
+ /** A finite double as `significand * 2 ** exponent` with an integer significand, exactly, read from its bit pattern. Zero has a zero significand. */
20
+ function exactParts(magnitude) {
21
+ scratchValue[0] = magnitude;
22
+ const bits = scratchBits[0];
23
+ if (bits === void 0) throw new Error("a one-element array always has an element zero");
24
+ const exponentField = Number(bits >> FRACTION_BITS & EXPONENT_FIELD_MASK);
25
+ const fraction = bits & FRACTION_MASK;
26
+ if (exponentField === 0) return {
27
+ significand: fraction,
28
+ exponent: SUBNORMAL_EXPONENT
29
+ };
30
+ return {
31
+ significand: fraction | IMPLICIT_LEADING_BIT,
32
+ exponent: exponentField - EXPONENT_BIAS_WITH_FRACTION
33
+ };
34
+ }
35
+ function orderOf(left, right) {
36
+ if (left < right) return -1;
37
+ return left > right ? 1 : 0;
38
+ }
39
+ /** The exact order of `left * leftSize` and `right * rightSize` for finite doubles and positive integer sizes, by comparing the products as integers once both are written over a common power of two. */
40
+ function exactOrder(left, right) {
41
+ const leftSign = Math.sign(left.value);
42
+ const rightSign = Math.sign(right.value);
43
+ if (leftSign !== rightSign) return leftSign < rightSign ? -1 : 1;
44
+ if (leftSign === 0) return 0;
45
+ const leftParts = exactParts(Math.abs(left.value));
46
+ const rightParts = exactParts(Math.abs(right.value));
47
+ let leftProduct = leftParts.significand * BigInt(left.size);
48
+ let rightProduct = rightParts.significand * BigInt(right.size);
49
+ const shift = leftParts.exponent - rightParts.exponent;
50
+ if (shift > 0) leftProduct <<= BigInt(shift);
51
+ else rightProduct <<= BigInt(-shift);
52
+ return leftSign < 0 ? orderOf(rightProduct, leftProduct) : orderOf(leftProduct, rightProduct);
53
+ }
54
+ /**
55
+ * The order of two durations: -1, 0 or 1, or `undefined` when a NaN makes them unordered.
56
+ *
57
+ * A value that is not finite is handled first, as numbers are: a NaN is unordered against everything (so every comparison with it is false, and `neq` true), and an infinity is equal to the same infinity and greater or less than anything finite whatever the units, since a unit only scales by a positive amount. The bit-pattern comparison below reads a finite double's exact value and has no meaning for these.
58
+ *
59
+ * Two finite durations are ordered exactly, with no overflow and no underflow. Both are divided into the coarser of the two units. A division by an exact integer is correctly rounded and rounding is monotone, so it can collapse a difference into equality but never reverse an order: when the two rounded values differ their order is the true order, and that settles almost every comparison without leaving floating point. Dividing can lose the difference, though: two close values round to the same double, and a subnormal rounds to zero. Only when the rounded values are equal is the answer settled exactly, from the doubles' binary expansions, by comparing each value times its unit's size in milliseconds as integers.
60
+ *
61
+ * Converting both to milliseconds by multiplying instead overflows for spans of days beyond roughly 1e300, which is why it is not done here.
62
+ */
63
+ function compareDurations(left, right) {
64
+ if (Number.isNaN(left.value) || Number.isNaN(right.value)) return void 0;
65
+ if (!Number.isFinite(left.value) || !Number.isFinite(right.value)) return orderOf(left.value, right.value);
66
+ const leftSize = millisecondsPerDurationUnit[left.unit];
67
+ const rightSize = millisecondsPerDurationUnit[right.unit];
68
+ const sharedSize = Math.max(leftSize, rightSize);
69
+ const leftInShared = left.value / (sharedSize / leftSize);
70
+ const rightInShared = right.value / (sharedSize / rightSize);
71
+ if (leftInShared < rightInShared) return -1;
72
+ if (leftInShared > rightInShared) return 1;
73
+ return exactOrder({
74
+ value: left.value,
75
+ size: leftSize
76
+ }, {
77
+ value: right.value,
78
+ size: rightSize
79
+ });
80
+ }
81
+ //#endregion
82
+ export { compareDurations, millisecondsPerDurationUnit };
@@ -0,0 +1,87 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ const require_computed_value = require("./computed-value.cjs");
3
+ const require_builtin_functions = require("./builtin-functions.cjs");
4
+ const require_tree = require("./tree.cjs");
5
+ const require_evaluator_factory = require("./evaluator-factory.cjs");
6
+ const require_plain_record = require("./plain-record.cjs");
7
+ const require_input_resolvers = require("./input-resolvers.cjs");
8
+ //#region src/evaluate-document.ts
9
+ const predicateKinds = new Set(require_tree.PredicateNodeSchema.options.map((option) => option.shape.kind.value));
10
+ /** What a definite expression result that `ComputedValueSchema` refuses is reported as: the only way a result fails it is a non-finite number, which JSON would write as `null`. The evaluator's arithmetic and the built-in functions already keep one from forming, so this is the last check before a value leaves the document boundary, and it fails loudly rather than print a different value from the one computed. */
11
+ const NOT_REPRESENTABLE = "(result): the value is not a finite number";
12
+ const AMBIGUOUS_TREE_KIND = "(root): a treeReference is valid as a predicate and as an expression; set `as` to \"predicate\" or \"expression\"";
13
+ const evaluator = require_evaluator_factory.createSyncEvaluator({ functions: require_builtin_functions.builtinFunctions });
14
+ /** Turns zod's issues into `path: message` lines. A failed union wraps one list of issues per branch, each path relative to the union; the branch the input got furthest into (the deepest path) is the one it was meant to match, so only that branch's issues are reported, under the union's own path. */
15
+ function describeIssues(issues, parentPath = []) {
16
+ return issues.flatMap((issue) => {
17
+ const path = [...parentPath, ...issue.path];
18
+ if (issue.code === "invalid_union" && issue.errors.length > 0) return describeIssues(issue.errors.reduce((best, branch) => maxPathLength(branch) > maxPathLength(best) ? branch : best), path);
19
+ return [`${path.length === 0 ? "(root)" : path.join(".")}: ${issue.message}`];
20
+ });
21
+ }
22
+ function maxPathLength(issues) {
23
+ return Math.max(0, ...issues.map((issue) => issue.path.length));
24
+ }
25
+ function resolveTreeKind(tree, requested) {
26
+ if (requested !== void 0) return requested;
27
+ const kind = require_plain_record.isPlainRecord(tree) ? tree.kind : void 0;
28
+ if (kind === "treeReference") return "ambiguous";
29
+ return typeof kind === "string" && predicateKinds.has(kind) ? "predicate" : "expression";
30
+ }
31
+ /**
32
+ * Validates a tree and its named inputs and evaluates it with the built-in function registry (`builtinFunctions`), the evaluation the `trilean evaluate` command performs. The tree kind is read from the root node's `kind` unless `as` names it. There are three outcomes:
33
+ *
34
+ * - `evaluated`: an `Evaluation`, definite or indeterminate.
35
+ * - `rejected`: nothing was evaluated, because a tree or an input failed validation (`invalid`) or a root `treeReference` was given without `as` (`ambiguous-tree-kind`). `issues` has one `path: message` line per problem.
36
+ * - `unrepresentable`: the tree was evaluated and the result is a number JSON cannot carry (`Infinity` or `NaN`), which would otherwise be printed as `null`. The built-in registry never produces one, and the evaluator's arithmetic turns an overflow into a `domain-error`, so this is a guard on the document boundary against a change that stops doing so.
37
+ *
38
+ * Resolution is limited to what `createInputResolvers` provides, and its collection error propagates for a tree that folds or quantifies over one.
39
+ */
40
+ function evaluateDocument({ tree, inputs, as }) {
41
+ const parsedInputs = require_input_resolvers.parseInputs(inputs ?? {});
42
+ if (!parsedInputs.ok) return {
43
+ outcome: "rejected",
44
+ reason: "invalid",
45
+ issues: parsedInputs.issues
46
+ };
47
+ const resolvers = require_input_resolvers.createInputResolvers(parsedInputs.inputs);
48
+ const treeKind = resolveTreeKind(tree, as);
49
+ if (treeKind === "ambiguous") return {
50
+ outcome: "rejected",
51
+ reason: "ambiguous-tree-kind",
52
+ issues: [AMBIGUOUS_TREE_KIND]
53
+ };
54
+ if (treeKind === "predicate") {
55
+ const parsed = require_tree.PredicateNodeSchema.safeParse(tree);
56
+ if (!parsed.success) return {
57
+ outcome: "rejected",
58
+ reason: "invalid",
59
+ issues: describeIssues(parsed.error.issues)
60
+ };
61
+ const node = parsed.data;
62
+ return {
63
+ outcome: "evaluated",
64
+ treeKind,
65
+ evaluation: evaluator.evaluatePredicate(node, void 0, resolvers)
66
+ };
67
+ }
68
+ const parsed = require_tree.ExpressionNodeSchema.safeParse(tree);
69
+ if (!parsed.success) return {
70
+ outcome: "rejected",
71
+ reason: "invalid",
72
+ issues: describeIssues(parsed.error.issues)
73
+ };
74
+ const node = parsed.data;
75
+ const evaluation = evaluator.evaluateValue(node, void 0, resolvers);
76
+ if (evaluation.status === "definite" && !require_computed_value.ComputedValueSchema.safeParse(evaluation.value).success) return {
77
+ outcome: "unrepresentable",
78
+ issues: [NOT_REPRESENTABLE]
79
+ };
80
+ return {
81
+ outcome: "evaluated",
82
+ treeKind,
83
+ evaluation
84
+ };
85
+ }
86
+ //#endregion
87
+ exports.evaluateDocument = evaluateDocument;
@@ -0,0 +1,40 @@
1
+ import { t as ComputedValue } from "./computed-value-CbRF0Izc.cjs";
2
+ import { Evaluation } from "./evaluation.cjs";
3
+ //#region src/evaluate-document.d.ts
4
+ export type TreeKind = "predicate" | "expression";
5
+ export interface EvaluateDocumentOptions {
6
+ /** The tree as parsed from JSON, not yet validated. */
7
+ tree: unknown;
8
+ /** Named inputs as parsed from JSON (see `parseInputs`); absent means none. */
9
+ inputs?: unknown;
10
+ /** Which tree `tree` is. Needed only when its root is a `treeReference`, the one node kind valid in both. */
11
+ as?: TreeKind;
12
+ }
13
+ export type DocumentEvaluation = {
14
+ outcome: "evaluated";
15
+ treeKind: "predicate";
16
+ evaluation: Evaluation<boolean>;
17
+ } | {
18
+ outcome: "evaluated";
19
+ treeKind: "expression";
20
+ evaluation: Evaluation<ComputedValue>;
21
+ } | {
22
+ outcome: "rejected";
23
+ /** `ambiguous-tree-kind` is a root `treeReference` evaluated without `as`; every other rejection is `invalid`, a tree or an input that fails validation. */
24
+ reason: "invalid" | "ambiguous-tree-kind";
25
+ issues: readonly string[];
26
+ } | {
27
+ outcome: "unrepresentable";
28
+ issues: readonly string[];
29
+ };
30
+ /**
31
+ * Validates a tree and its named inputs and evaluates it with the built-in function registry (`builtinFunctions`), the evaluation the `trilean evaluate` command performs. The tree kind is read from the root node's `kind` unless `as` names it. There are three outcomes:
32
+ *
33
+ * - `evaluated`: an `Evaluation`, definite or indeterminate.
34
+ * - `rejected`: nothing was evaluated, because a tree or an input failed validation (`invalid`) or a root `treeReference` was given without `as` (`ambiguous-tree-kind`). `issues` has one `path: message` line per problem.
35
+ * - `unrepresentable`: the tree was evaluated and the result is a number JSON cannot carry (`Infinity` or `NaN`), which would otherwise be printed as `null`. The built-in registry never produces one, and the evaluator's arithmetic turns an overflow into a `domain-error`, so this is a guard on the document boundary against a change that stops doing so.
36
+ *
37
+ * Resolution is limited to what `createInputResolvers` provides, and its collection error propagates for a tree that folds or quantifies over one.
38
+ */
39
+ export declare function evaluateDocument({ tree, inputs, as }: EvaluateDocumentOptions): DocumentEvaluation;
40
+ //#endregion
@@ -0,0 +1,40 @@
1
+ import { t as ComputedValue } from "./computed-value-CbRF0Izc.js";
2
+ import { Evaluation } from "./evaluation.js";
3
+ //#region src/evaluate-document.d.ts
4
+ export type TreeKind = "predicate" | "expression";
5
+ export interface EvaluateDocumentOptions {
6
+ /** The tree as parsed from JSON, not yet validated. */
7
+ tree: unknown;
8
+ /** Named inputs as parsed from JSON (see `parseInputs`); absent means none. */
9
+ inputs?: unknown;
10
+ /** Which tree `tree` is. Needed only when its root is a `treeReference`, the one node kind valid in both. */
11
+ as?: TreeKind;
12
+ }
13
+ export type DocumentEvaluation = {
14
+ outcome: "evaluated";
15
+ treeKind: "predicate";
16
+ evaluation: Evaluation<boolean>;
17
+ } | {
18
+ outcome: "evaluated";
19
+ treeKind: "expression";
20
+ evaluation: Evaluation<ComputedValue>;
21
+ } | {
22
+ outcome: "rejected";
23
+ /** `ambiguous-tree-kind` is a root `treeReference` evaluated without `as`; every other rejection is `invalid`, a tree or an input that fails validation. */
24
+ reason: "invalid" | "ambiguous-tree-kind";
25
+ issues: readonly string[];
26
+ } | {
27
+ outcome: "unrepresentable";
28
+ issues: readonly string[];
29
+ };
30
+ /**
31
+ * Validates a tree and its named inputs and evaluates it with the built-in function registry (`builtinFunctions`), the evaluation the `trilean evaluate` command performs. The tree kind is read from the root node's `kind` unless `as` names it. There are three outcomes:
32
+ *
33
+ * - `evaluated`: an `Evaluation`, definite or indeterminate.
34
+ * - `rejected`: nothing was evaluated, because a tree or an input failed validation (`invalid`) or a root `treeReference` was given without `as` (`ambiguous-tree-kind`). `issues` has one `path: message` line per problem.
35
+ * - `unrepresentable`: the tree was evaluated and the result is a number JSON cannot carry (`Infinity` or `NaN`), which would otherwise be printed as `null`. The built-in registry never produces one, and the evaluator's arithmetic turns an overflow into a `domain-error`, so this is a guard on the document boundary against a change that stops doing so.
36
+ *
37
+ * Resolution is limited to what `createInputResolvers` provides, and its collection error propagates for a tree that folds or quantifies over one.
38
+ */
39
+ export declare function evaluateDocument({ tree, inputs, as }: EvaluateDocumentOptions): DocumentEvaluation;
40
+ //#endregion
@@ -0,0 +1,86 @@
1
+ import { ComputedValueSchema } from "./computed-value.js";
2
+ import { builtinFunctions } from "./builtin-functions.js";
3
+ import { ExpressionNodeSchema, PredicateNodeSchema } from "./tree.js";
4
+ import { createSyncEvaluator } from "./evaluator-factory.js";
5
+ import { isPlainRecord } from "./plain-record.js";
6
+ import { createInputResolvers, parseInputs } from "./input-resolvers.js";
7
+ //#region src/evaluate-document.ts
8
+ const predicateKinds = new Set(PredicateNodeSchema.options.map((option) => option.shape.kind.value));
9
+ /** What a definite expression result that `ComputedValueSchema` refuses is reported as: the only way a result fails it is a non-finite number, which JSON would write as `null`. The evaluator's arithmetic and the built-in functions already keep one from forming, so this is the last check before a value leaves the document boundary, and it fails loudly rather than print a different value from the one computed. */
10
+ const NOT_REPRESENTABLE = "(result): the value is not a finite number";
11
+ const AMBIGUOUS_TREE_KIND = "(root): a treeReference is valid as a predicate and as an expression; set `as` to \"predicate\" or \"expression\"";
12
+ const evaluator = createSyncEvaluator({ functions: builtinFunctions });
13
+ /** Turns zod's issues into `path: message` lines. A failed union wraps one list of issues per branch, each path relative to the union; the branch the input got furthest into (the deepest path) is the one it was meant to match, so only that branch's issues are reported, under the union's own path. */
14
+ function describeIssues(issues, parentPath = []) {
15
+ return issues.flatMap((issue) => {
16
+ const path = [...parentPath, ...issue.path];
17
+ if (issue.code === "invalid_union" && issue.errors.length > 0) return describeIssues(issue.errors.reduce((best, branch) => maxPathLength(branch) > maxPathLength(best) ? branch : best), path);
18
+ return [`${path.length === 0 ? "(root)" : path.join(".")}: ${issue.message}`];
19
+ });
20
+ }
21
+ function maxPathLength(issues) {
22
+ return Math.max(0, ...issues.map((issue) => issue.path.length));
23
+ }
24
+ function resolveTreeKind(tree, requested) {
25
+ if (requested !== void 0) return requested;
26
+ const kind = isPlainRecord(tree) ? tree.kind : void 0;
27
+ if (kind === "treeReference") return "ambiguous";
28
+ return typeof kind === "string" && predicateKinds.has(kind) ? "predicate" : "expression";
29
+ }
30
+ /**
31
+ * Validates a tree and its named inputs and evaluates it with the built-in function registry (`builtinFunctions`), the evaluation the `trilean evaluate` command performs. The tree kind is read from the root node's `kind` unless `as` names it. There are three outcomes:
32
+ *
33
+ * - `evaluated`: an `Evaluation`, definite or indeterminate.
34
+ * - `rejected`: nothing was evaluated, because a tree or an input failed validation (`invalid`) or a root `treeReference` was given without `as` (`ambiguous-tree-kind`). `issues` has one `path: message` line per problem.
35
+ * - `unrepresentable`: the tree was evaluated and the result is a number JSON cannot carry (`Infinity` or `NaN`), which would otherwise be printed as `null`. The built-in registry never produces one, and the evaluator's arithmetic turns an overflow into a `domain-error`, so this is a guard on the document boundary against a change that stops doing so.
36
+ *
37
+ * Resolution is limited to what `createInputResolvers` provides, and its collection error propagates for a tree that folds or quantifies over one.
38
+ */
39
+ function evaluateDocument({ tree, inputs, as }) {
40
+ const parsedInputs = parseInputs(inputs ?? {});
41
+ if (!parsedInputs.ok) return {
42
+ outcome: "rejected",
43
+ reason: "invalid",
44
+ issues: parsedInputs.issues
45
+ };
46
+ const resolvers = createInputResolvers(parsedInputs.inputs);
47
+ const treeKind = resolveTreeKind(tree, as);
48
+ if (treeKind === "ambiguous") return {
49
+ outcome: "rejected",
50
+ reason: "ambiguous-tree-kind",
51
+ issues: [AMBIGUOUS_TREE_KIND]
52
+ };
53
+ if (treeKind === "predicate") {
54
+ const parsed = PredicateNodeSchema.safeParse(tree);
55
+ if (!parsed.success) return {
56
+ outcome: "rejected",
57
+ reason: "invalid",
58
+ issues: describeIssues(parsed.error.issues)
59
+ };
60
+ const node = parsed.data;
61
+ return {
62
+ outcome: "evaluated",
63
+ treeKind,
64
+ evaluation: evaluator.evaluatePredicate(node, void 0, resolvers)
65
+ };
66
+ }
67
+ const parsed = ExpressionNodeSchema.safeParse(tree);
68
+ if (!parsed.success) return {
69
+ outcome: "rejected",
70
+ reason: "invalid",
71
+ issues: describeIssues(parsed.error.issues)
72
+ };
73
+ const node = parsed.data;
74
+ const evaluation = evaluator.evaluateValue(node, void 0, resolvers);
75
+ if (evaluation.status === "definite" && !ComputedValueSchema.safeParse(evaluation.value).success) return {
76
+ outcome: "unrepresentable",
77
+ issues: [NOT_REPRESENTABLE]
78
+ };
79
+ return {
80
+ outcome: "evaluated",
81
+ treeKind,
82
+ evaluation
83
+ };
84
+ }
85
+ //#endregion
86
+ export { evaluateDocument };
@@ -1,9 +1,9 @@
1
1
  import { t as ComputedValue } from "./computed-value-CbRF0Izc.cjs";
2
+ import { FunctionRegistry } from "./functions.cjs";
2
3
  import { t as JsonValue } from "./json-value-B1Hjjjri.cjs";
3
4
  import { PredicateNode } from "./tree.cjs";
4
5
  import { Evaluation, IndeterminateReason } from "./evaluation.cjs";
5
6
  import { EvaluationBudget } from "./evaluator-budget.cjs";
6
- import { FunctionRegistry } from "./functions.cjs";
7
7
  import { Task } from "./evaluator-effect.cjs";
8
8
  import { EvaluationContext, EvaluatorResolvers } from "./resolvers.cjs";
9
9
  //#region src/evaluator-collection.d.ts
@@ -1,9 +1,9 @@
1
1
  import { t as ComputedValue } from "./computed-value-CbRF0Izc.js";
2
+ import { FunctionRegistry } from "./functions.js";
2
3
  import { t as JsonValue } from "./json-value-B1Hjjjri.js";
3
4
  import { PredicateNode } from "./tree.js";
4
5
  import { Evaluation, IndeterminateReason } from "./evaluation.js";
5
6
  import { EvaluationBudget } from "./evaluator-budget.js";
6
- import { FunctionRegistry } from "./functions.js";
7
7
  import { Task } from "./evaluator-effect.js";
8
8
  import { EvaluationContext, EvaluatorResolvers } from "./resolvers.js";
9
9
  //#region src/evaluator-collection.d.ts
@@ -1,7 +1,7 @@
1
1
  import { t as ComputedValue } from "./computed-value-CbRF0Izc.cjs";
2
+ import { FunctionRegistry } from "./functions.cjs";
2
3
  import { ExpressionNode, PredicateNode } from "./tree.cjs";
3
4
  import { Evaluation } from "./evaluation.cjs";
4
- import { FunctionRegistry } from "./functions.cjs";
5
5
  import { EvaluationContext, Resolvers, SyncResolvers } from "./resolvers.cjs";
6
6
  //#region src/evaluator-factory.d.ts
7
7
  /**
@@ -1,7 +1,7 @@
1
1
  import { t as ComputedValue } from "./computed-value-CbRF0Izc.js";
2
+ import { FunctionRegistry } from "./functions.js";
2
3
  import { ExpressionNode, PredicateNode } from "./tree.js";
3
4
  import { Evaluation } from "./evaluation.js";
4
- import { FunctionRegistry } from "./functions.js";
5
5
  import { EvaluationContext, Resolvers, SyncResolvers } from "./resolvers.js";
6
6
  //#region src/evaluator-factory.d.ts
7
7
  /**
@@ -1,5 +1,5 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_index_C4tKZ0yW = require("./index.C4tKZ0yW-CZW6CdWn.cjs");
2
+ const require_index_C4tKZ0yW = require("./index.C4tKZ0yW-q5POG9-K.cjs");
3
3
  const require_evaluator_factory = require("./evaluator-factory.cjs");
4
4
  //#region src/evaluator-indeterminacy-helpers.ts
5
5
  /**
@@ -1,6 +1,6 @@
1
+ import { FunctionRegistry } from "./functions.cjs";
1
2
  import { ExpressionNode, PredicateNode } from "./tree.cjs";
2
3
  import { IndeterminateReason } from "./evaluation.cjs";
3
- import { FunctionRegistry } from "./functions.cjs";
4
4
  import { EvaluationContext, Resolvers } from "./resolvers.cjs";
5
5
  //#region src/evaluator-indeterminacy-helpers.d.ts
6
6
  /**
@@ -1,6 +1,6 @@
1
+ import { FunctionRegistry } from "./functions.js";
1
2
  import { ExpressionNode, PredicateNode } from "./tree.js";
2
3
  import { IndeterminateReason } from "./evaluation.js";
3
- import { FunctionRegistry } from "./functions.js";
4
4
  import { EvaluationContext, Resolvers } from "./resolvers.js";
5
5
  //#region src/evaluator-indeterminacy-helpers.d.ts
6
6
  /**
@@ -1,5 +1,5 @@
1
1
  import { createEvaluator, evaluatePredicate, evaluateValue } from "./evaluator-factory.js";
2
- import { t as globalExpect } from "./index.C4tKZ0yW-CfMRGP9u.js";
2
+ import { t as globalExpect } from "./index.C4tKZ0yW-ICJbIYnA.js";
3
3
  //#region src/evaluator-indeterminacy-helpers.ts
4
4
  /**
5
5
  * Shared fixture machinery for the two split indeterminacy test files (evaluator.indeterminacy-table.unit.test.ts, evaluator.indeterminacy-cases.unit.test.ts): systematic, table-driven coverage of README.md's "Indeterminacy reference" section, one fixture per node-kind x reason-code combination that section documents, for every `PredicateNode`/`ExpressionNode` kind implemented. This complements, rather than replaces, the ad hoc behavioural tests already spread across the evaluator.*.test.ts files and truth-tables.unit.test.ts.