trilean 1.1.0 → 1.3.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.
@@ -0,0 +1,94 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ //#region src/derived-patterns.ts
3
+ /**
4
+ * `prefixPattern`/`wildcardPattern`/`hierarchicalGlobPattern` are never their own node kind and add no evaluator branch -- each is a builder function that compiles its pattern string into a portable regular-expression string and assembles an ordinary `textCompare` node with `op: "matches"` around it, exactly the same treatment `derived-connectives.ts`/`derived-aggregates.ts`/`derived-values.ts` already give `xor`/`sum`/`coalesce` (see the "Pattern-matching builders" section of README.md). The compilation happens once, when the tree is built, so what is stored and evaluated is an ordinary `textCompare` tree indistinguishable from one written out by hand.
5
+ */
6
+ /** The characters a compiled pattern must backslash-escape to match literally. Deliberately exactly ECMAScript's own `SyntaxCharacter` set plus `/`: those are the only escapes that stay valid under a `u`/`v`-flagged `RegExp` as well as an unflagged one, so a compiled pattern string remains usable however a consumer chooses to compile it -- including pasted verbatim into a `/.../` literal, which is what `/` earns its place for. Escaping anything outside this set (a quote, say) would be inert under the evaluator's own unflagged `new RegExp` but a `SyntaxError` under `u`. */
7
+ const REGEX_SYNTAX_CHARACTERS = "^$\\.*+?()[]{}|/";
8
+ /** `[\s\S]*` rather than `.*` because the compiled string carries no flags of its own: `.` excludes line terminators unless the `s` flag is set, and `textCompare`'s evaluator compiles the pattern with `new RegExp(right.value)` and no flags at all. A character class covering both `\s` and `\S` is the flag-free spelling of "any character", so the same string behaves identically wherever it is compiled. */
9
+ const ANY_CHARACTERS = "[\\s\\S]*";
10
+ /** A hierarchical glob's single `*`: any run of characters that stays inside one `/`-delimited segment. The separator is written `\/` rather than a bare `/` because `v`-mode reserves `/` as a `ClassSetReservedPunctuator` and rejects it unescaped inside a character class -- a bare `[^/]` is a `SyntaxError` under `v`, while `[^\/]` compiles identically under `v`, `u` and no flags at all, which is the portability `REGEX_SYNTAX_CHARACTERS` already promises for every literal character. */
11
+ const ANY_CHARACTERS_WITHIN_SEGMENT = "[^\\/]*";
12
+ /** A hierarchical glob's `?`: exactly one character, still constrained to a single segment. Escaped for the same `v`-mode reason as `ANY_CHARACTERS_WITHIN_SEGMENT` above. */
13
+ const ANY_CHARACTER_WITHIN_SEGMENT = "[^\\/]";
14
+ function escapeRegexLiteral(character) {
15
+ return REGEX_SYNTAX_CHARACTERS.includes(character) ? `\\${character}` : character;
16
+ }
17
+ /** A prefix match that respects word boundaries: the subject is either the prefix exactly, or the prefix followed by a space and anything at all. `"ls"` therefore matches `"ls"` and `"ls -la"` but never `"lsof"`. The prefix itself is a plain literal -- every character in it is escaped, so it carries no wildcard or escape syntax of its own. */
18
+ function compilePrefixPattern(prefix) {
19
+ return `^${Array.from(prefix, escapeRegexLiteral).join("")}(?: ${ANY_CHARACTERS})?$`;
20
+ }
21
+ /**
22
+ * A flat wildcard dialect with no notion of path segments: an unescaped `*` matches any run of characters, `\*` matches a literal asterisk, and `\\` matches a literal backslash. Compiled in a single left-to-right pass rather than by successive `String.replace` phases over sentinel placeholders, so a pattern containing whatever string a sentinel happened to use cannot be corrupted by its own restoration step.
23
+ *
24
+ * The trailing-single-wildcard convenience is the one non-obvious rule: a pattern whose only wildcard is a trailing `" *"` also matches the bare prefix, so `"git *"` matches `"git"` as well as `"git add file"`. It applies only when that wildcard is the pattern's sole unescaped one -- `"git * *"` keeps requiring both.
25
+ */
26
+ function compileWildcardPattern(pattern) {
27
+ const trimmed = pattern.trim();
28
+ let compiled = "";
29
+ let unescapedWildcards = 0;
30
+ let index = 0;
31
+ while (index < trimmed.length) {
32
+ const character = trimmed.charAt(index);
33
+ if (character === "\\" && index + 1 < trimmed.length) {
34
+ const next = trimmed.charAt(index + 1);
35
+ if (next === "*" || next === "\\") {
36
+ compiled += `\\${next}`;
37
+ index += 2;
38
+ continue;
39
+ }
40
+ }
41
+ if (character === "*") {
42
+ compiled += ANY_CHARACTERS;
43
+ unescapedWildcards += 1;
44
+ index += 1;
45
+ continue;
46
+ }
47
+ compiled += escapeRegexLiteral(character);
48
+ index += 1;
49
+ }
50
+ if (unescapedWildcards === 1 && trimmed.endsWith(" *")) compiled = `${compiled.slice(0, -8)}(?: ${ANY_CHARACTERS})?`;
51
+ return `^${compiled}$`;
52
+ }
53
+ /** A hierarchy-aware glob dialect, distinct from `compileWildcardPattern`'s flat one and never mixed with it: `*` matches within a single `/`-delimited segment, `**` matches across segments, and `?` matches one character within a segment. `**` is consumed as a unit during the same left-to-right pass, so an odd run such as `"***"` reads as `**` followed by `*` -- exactly what successive-replacement would produce, without needing a placeholder to survive between passes. This dialect has no escape syntax: a backslash in the pattern is a literal backslash. */
54
+ function compileHierarchicalGlobPattern(pattern) {
55
+ let compiled = "";
56
+ let index = 0;
57
+ while (index < pattern.length) {
58
+ const character = pattern.charAt(index);
59
+ if (character === "*") {
60
+ if (pattern.charAt(index + 1) === "*") {
61
+ compiled += ANY_CHARACTERS;
62
+ index += 2;
63
+ continue;
64
+ }
65
+ compiled += ANY_CHARACTERS_WITHIN_SEGMENT;
66
+ index += 1;
67
+ continue;
68
+ }
69
+ if (character === "?") {
70
+ compiled += ANY_CHARACTER_WITHIN_SEGMENT;
71
+ index += 1;
72
+ continue;
73
+ }
74
+ compiled += escapeRegexLiteral(character);
75
+ index += 1;
76
+ }
77
+ return `^${compiled}$`;
78
+ }
79
+ const matchesCompiledPattern = (text, compiled) => ({
80
+ kind: "textCompare",
81
+ op: "matches",
82
+ left: text,
83
+ right: {
84
+ kind: "textLiteral",
85
+ value: compiled
86
+ }
87
+ });
88
+ const prefixPattern = (text, prefix) => matchesCompiledPattern(text, compilePrefixPattern(prefix));
89
+ const wildcardPattern = (text, pattern) => matchesCompiledPattern(text, compileWildcardPattern(pattern));
90
+ const hierarchicalGlobPattern = (text, pattern) => matchesCompiledPattern(text, compileHierarchicalGlobPattern(pattern));
91
+ //#endregion
92
+ exports.hierarchicalGlobPattern = hierarchicalGlobPattern;
93
+ exports.prefixPattern = prefixPattern;
94
+ exports.wildcardPattern = wildcardPattern;
@@ -0,0 +1,7 @@
1
+ import { ExpressionNode, PredicateNode } from "./tree.cjs";
2
+ //#region src/derived-patterns.d.ts
3
+ declare const prefixPattern: (text: ExpressionNode, prefix: string) => PredicateNode;
4
+ declare const wildcardPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
5
+ declare const hierarchicalGlobPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
6
+ //#endregion
7
+ export { hierarchicalGlobPattern, prefixPattern, wildcardPattern };
@@ -0,0 +1,7 @@
1
+ import { ExpressionNode, PredicateNode } from "./tree.js";
2
+ //#region src/derived-patterns.d.ts
3
+ declare const prefixPattern: (text: ExpressionNode, prefix: string) => PredicateNode;
4
+ declare const wildcardPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
5
+ declare const hierarchicalGlobPattern: (text: ExpressionNode, pattern: string) => PredicateNode;
6
+ //#endregion
7
+ export { hierarchicalGlobPattern, prefixPattern, wildcardPattern };
@@ -0,0 +1,91 @@
1
+ //#region src/derived-patterns.ts
2
+ /**
3
+ * `prefixPattern`/`wildcardPattern`/`hierarchicalGlobPattern` are never their own node kind and add no evaluator branch -- each is a builder function that compiles its pattern string into a portable regular-expression string and assembles an ordinary `textCompare` node with `op: "matches"` around it, exactly the same treatment `derived-connectives.ts`/`derived-aggregates.ts`/`derived-values.ts` already give `xor`/`sum`/`coalesce` (see the "Pattern-matching builders" section of README.md). The compilation happens once, when the tree is built, so what is stored and evaluated is an ordinary `textCompare` tree indistinguishable from one written out by hand.
4
+ */
5
+ /** The characters a compiled pattern must backslash-escape to match literally. Deliberately exactly ECMAScript's own `SyntaxCharacter` set plus `/`: those are the only escapes that stay valid under a `u`/`v`-flagged `RegExp` as well as an unflagged one, so a compiled pattern string remains usable however a consumer chooses to compile it -- including pasted verbatim into a `/.../` literal, which is what `/` earns its place for. Escaping anything outside this set (a quote, say) would be inert under the evaluator's own unflagged `new RegExp` but a `SyntaxError` under `u`. */
6
+ const REGEX_SYNTAX_CHARACTERS = "^$\\.*+?()[]{}|/";
7
+ /** `[\s\S]*` rather than `.*` because the compiled string carries no flags of its own: `.` excludes line terminators unless the `s` flag is set, and `textCompare`'s evaluator compiles the pattern with `new RegExp(right.value)` and no flags at all. A character class covering both `\s` and `\S` is the flag-free spelling of "any character", so the same string behaves identically wherever it is compiled. */
8
+ const ANY_CHARACTERS = "[\\s\\S]*";
9
+ /** A hierarchical glob's single `*`: any run of characters that stays inside one `/`-delimited segment. The separator is written `\/` rather than a bare `/` because `v`-mode reserves `/` as a `ClassSetReservedPunctuator` and rejects it unescaped inside a character class -- a bare `[^/]` is a `SyntaxError` under `v`, while `[^\/]` compiles identically under `v`, `u` and no flags at all, which is the portability `REGEX_SYNTAX_CHARACTERS` already promises for every literal character. */
10
+ const ANY_CHARACTERS_WITHIN_SEGMENT = "[^\\/]*";
11
+ /** A hierarchical glob's `?`: exactly one character, still constrained to a single segment. Escaped for the same `v`-mode reason as `ANY_CHARACTERS_WITHIN_SEGMENT` above. */
12
+ const ANY_CHARACTER_WITHIN_SEGMENT = "[^\\/]";
13
+ function escapeRegexLiteral(character) {
14
+ return REGEX_SYNTAX_CHARACTERS.includes(character) ? `\\${character}` : character;
15
+ }
16
+ /** A prefix match that respects word boundaries: the subject is either the prefix exactly, or the prefix followed by a space and anything at all. `"ls"` therefore matches `"ls"` and `"ls -la"` but never `"lsof"`. The prefix itself is a plain literal -- every character in it is escaped, so it carries no wildcard or escape syntax of its own. */
17
+ function compilePrefixPattern(prefix) {
18
+ return `^${Array.from(prefix, escapeRegexLiteral).join("")}(?: ${ANY_CHARACTERS})?$`;
19
+ }
20
+ /**
21
+ * A flat wildcard dialect with no notion of path segments: an unescaped `*` matches any run of characters, `\*` matches a literal asterisk, and `\\` matches a literal backslash. Compiled in a single left-to-right pass rather than by successive `String.replace` phases over sentinel placeholders, so a pattern containing whatever string a sentinel happened to use cannot be corrupted by its own restoration step.
22
+ *
23
+ * The trailing-single-wildcard convenience is the one non-obvious rule: a pattern whose only wildcard is a trailing `" *"` also matches the bare prefix, so `"git *"` matches `"git"` as well as `"git add file"`. It applies only when that wildcard is the pattern's sole unescaped one -- `"git * *"` keeps requiring both.
24
+ */
25
+ function compileWildcardPattern(pattern) {
26
+ const trimmed = pattern.trim();
27
+ let compiled = "";
28
+ let unescapedWildcards = 0;
29
+ let index = 0;
30
+ while (index < trimmed.length) {
31
+ const character = trimmed.charAt(index);
32
+ if (character === "\\" && index + 1 < trimmed.length) {
33
+ const next = trimmed.charAt(index + 1);
34
+ if (next === "*" || next === "\\") {
35
+ compiled += `\\${next}`;
36
+ index += 2;
37
+ continue;
38
+ }
39
+ }
40
+ if (character === "*") {
41
+ compiled += ANY_CHARACTERS;
42
+ unescapedWildcards += 1;
43
+ index += 1;
44
+ continue;
45
+ }
46
+ compiled += escapeRegexLiteral(character);
47
+ index += 1;
48
+ }
49
+ if (unescapedWildcards === 1 && trimmed.endsWith(" *")) compiled = `${compiled.slice(0, -8)}(?: ${ANY_CHARACTERS})?`;
50
+ return `^${compiled}$`;
51
+ }
52
+ /** A hierarchy-aware glob dialect, distinct from `compileWildcardPattern`'s flat one and never mixed with it: `*` matches within a single `/`-delimited segment, `**` matches across segments, and `?` matches one character within a segment. `**` is consumed as a unit during the same left-to-right pass, so an odd run such as `"***"` reads as `**` followed by `*` -- exactly what successive-replacement would produce, without needing a placeholder to survive between passes. This dialect has no escape syntax: a backslash in the pattern is a literal backslash. */
53
+ function compileHierarchicalGlobPattern(pattern) {
54
+ let compiled = "";
55
+ let index = 0;
56
+ while (index < pattern.length) {
57
+ const character = pattern.charAt(index);
58
+ if (character === "*") {
59
+ if (pattern.charAt(index + 1) === "*") {
60
+ compiled += ANY_CHARACTERS;
61
+ index += 2;
62
+ continue;
63
+ }
64
+ compiled += ANY_CHARACTERS_WITHIN_SEGMENT;
65
+ index += 1;
66
+ continue;
67
+ }
68
+ if (character === "?") {
69
+ compiled += ANY_CHARACTER_WITHIN_SEGMENT;
70
+ index += 1;
71
+ continue;
72
+ }
73
+ compiled += escapeRegexLiteral(character);
74
+ index += 1;
75
+ }
76
+ return `^${compiled}$`;
77
+ }
78
+ const matchesCompiledPattern = (text, compiled) => ({
79
+ kind: "textCompare",
80
+ op: "matches",
81
+ left: text,
82
+ right: {
83
+ kind: "textLiteral",
84
+ value: compiled
85
+ }
86
+ });
87
+ const prefixPattern = (text, prefix) => matchesCompiledPattern(text, compilePrefixPattern(prefix));
88
+ const wildcardPattern = (text, pattern) => matchesCompiledPattern(text, compileWildcardPattern(pattern));
89
+ const hierarchicalGlobPattern = (text, pattern) => matchesCompiledPattern(text, compileHierarchicalGlobPattern(pattern));
90
+ //#endregion
91
+ export { hierarchicalGlobPattern, prefixPattern, wildcardPattern };
@@ -1,4 +1,5 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ const require_complex = require("./complex.cjs");
2
3
  const require_computed_value = require("./computed-value.cjs");
3
4
  const require_evaluation = require("./evaluation.cjs");
4
5
  const require_functions = require("./functions.cjs");
@@ -76,6 +77,10 @@ function compareValues(op, left, right) {
76
77
  if (!require_computed_value.unitsEqual(left.unit, right.unit)) return require_evaluation.indeterminate("wrong-type", "cannot compare numbers with incompatible units");
77
78
  return require_evaluation.definite(applyComparisonOperator(op, left.value, right.value));
78
79
  case "text": return require_evaluation.indeterminate("wrong-type", "text values are not comparable via 'compare'; use 'textCompare'");
80
+ case "boolean":
81
+ if (right.kind !== "boolean") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'boolean' value with a '${right.kind}' value`);
82
+ if (op !== "eq" && op !== "neq") return require_evaluation.indeterminate("wrong-type", `booleans have no natural ordering; '${op}' is only defined for 'eq'/'neq'`);
83
+ return require_evaluation.definite(op === "eq" ? left.value === right.value : left.value !== right.value);
79
84
  case "instant": {
80
85
  if (right.kind !== "instant") return require_evaluation.indeterminate("wrong-type", `cannot compare an 'instant' value with a '${right.kind}' value`);
81
86
  const leftEpoch = toEpochMilliseconds(left.value);
@@ -87,6 +92,11 @@ function compareValues(op, left, right) {
87
92
  case "duration":
88
93
  if (right.kind !== "duration") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'duration' value with a '${right.kind}' value`);
89
94
  return require_evaluation.definite(applyComparisonOperator(op, toMilliseconds(left.value, left.unit), toMilliseconds(right.value, right.unit)));
95
+ case "complex":
96
+ if (op !== "eq" && op !== "neq") return require_evaluation.indeterminate("wrong-type", `ordering operator '${op}' is not defined for complex values; the complex plane has no total order`);
97
+ if (right.kind !== "complex") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'complex' value with a '${right.kind}' value`);
98
+ if (!require_computed_value.unitsEqual(left.unit, right.unit)) return require_evaluation.indeterminate("wrong-type", "cannot compare complex values with incompatible units");
99
+ return require_evaluation.definite(op === "eq" ? left.re === right.re && left.im === right.im : left.re !== right.re || left.im !== right.im);
90
100
  default: throw new Error("unreachable computed-value kind");
91
101
  }
92
102
  }
@@ -121,6 +131,9 @@ function computeMembershipMatch(operand, candidate) {
121
131
  case "text":
122
132
  if (candidate.kind !== "text") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'text' value with a '${candidate.kind}' value for membership`);
123
133
  return require_evaluation.definite(operand.value === candidate.value);
134
+ case "boolean":
135
+ if (candidate.kind !== "boolean") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'boolean' value with a '${candidate.kind}' value for membership`);
136
+ return require_evaluation.definite(operand.value === candidate.value);
124
137
  case "instant": {
125
138
  if (candidate.kind !== "instant") return require_evaluation.indeterminate("wrong-type", `cannot compare an 'instant' value with a '${candidate.kind}' value for membership`);
126
139
  const operandEpoch = toEpochMilliseconds(operand.value);
@@ -132,6 +145,10 @@ function computeMembershipMatch(operand, candidate) {
132
145
  case "duration":
133
146
  if (candidate.kind !== "duration") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'duration' value with a '${candidate.kind}' value for membership`);
134
147
  return require_evaluation.definite(toMilliseconds(operand.value, operand.unit) === toMilliseconds(candidate.value, candidate.unit));
148
+ case "complex":
149
+ if (candidate.kind !== "complex") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'complex' value with a '${candidate.kind}' value for membership`);
150
+ if (!require_computed_value.unitsEqual(operand.unit, candidate.unit)) return require_evaluation.indeterminate("wrong-type", "cannot compare complex values with incompatible units for membership");
151
+ return require_evaluation.definite(operand.re === candidate.re && operand.im === candidate.im);
135
152
  default: throw new Error("unreachable computed-value kind");
136
153
  }
137
154
  }
@@ -152,8 +169,15 @@ function applyNegate(operand) {
152
169
  value: -operand.value,
153
170
  unit: operand.unit
154
171
  });
172
+ case "complex": return require_evaluation.definite({
173
+ kind: "complex",
174
+ re: -operand.re,
175
+ im: -operand.im,
176
+ unit: operand.unit
177
+ });
155
178
  case "text":
156
- case "instant": return require_evaluation.indeterminate("wrong-type", `cannot negate a '${operand.kind}' value`);
179
+ case "instant":
180
+ case "boolean": return require_evaluation.indeterminate("wrong-type", `cannot negate a '${operand.kind}' value`);
157
181
  default: throw new Error("unreachable computed-value kind");
158
182
  }
159
183
  }
@@ -223,6 +247,75 @@ function applyArithmeticOnDurations(op, left, right) {
223
247
  default: throw new Error("unreachable arithmetic operator");
224
248
  }
225
249
  }
250
+ /** Every real number is a complex number with a zero imaginary part, so promoting one is exact and total -- unlike the temporal cross-kind combinations above, which each had to be enumerated because no such embedding exists between an `instant` and a `duration`. This is what lets a tree mix real and complex terms freely instead of forcing every real literal to be written as a complex one. */
251
+ function toComplexValue(value) {
252
+ if (value.kind === "complex") return value;
253
+ return {
254
+ kind: "complex",
255
+ re: value.value,
256
+ im: 0,
257
+ unit: value.unit
258
+ };
259
+ }
260
+ /** The complex product, as its own component-level helper rather than only a branch of the operator switch below, because `power`'s repeated multiplication needs exactly this and must not re-derive it. */
261
+ function multiplyComplexValues(left, right) {
262
+ return {
263
+ kind: "complex",
264
+ re: left.re * right.re - left.im * right.im,
265
+ im: left.re * right.im + left.im * right.re,
266
+ unit: require_computed_value.combineUnitsForMultiply(left.unit, right.unit)
267
+ };
268
+ }
269
+ /** Complex arithmetic, over the one canonical rectangular representation the `complex` kind stores (see the "Complex values" section of README.md). `add`/`subtract` are component-wise and carry the same identical-units requirement real numbers already have. `power` is deliberately excluded from this operator set rather than handled and rejected here: its exponent must stay an un-promoted real number, so the dispatcher routes it to `applyComplexPower` first, and excluding it from the type is what makes the compiler enforce that routing instead of leaving a dead branch behind. */
270
+ function applyArithmeticOnComplex(op, left, right) {
271
+ switch (op) {
272
+ case "add":
273
+ if (!require_computed_value.unitsEqual(left.unit, right.unit)) return require_evaluation.indeterminate("wrong-type", "cannot add complex values with incompatible units");
274
+ return require_evaluation.definite({
275
+ kind: "complex",
276
+ re: left.re + right.re,
277
+ im: left.im + right.im,
278
+ unit: left.unit
279
+ });
280
+ case "subtract":
281
+ if (!require_computed_value.unitsEqual(left.unit, right.unit)) return require_evaluation.indeterminate("wrong-type", "cannot subtract complex values with incompatible units");
282
+ return require_evaluation.definite({
283
+ kind: "complex",
284
+ re: left.re - right.re,
285
+ im: left.im - right.im,
286
+ unit: left.unit
287
+ });
288
+ case "multiply": return require_evaluation.definite(multiplyComplexValues(left, right));
289
+ case "divide": {
290
+ const divisorSquaredMagnitude = right.re * right.re + right.im * right.im;
291
+ if (divisorSquaredMagnitude === 0) return require_evaluation.indeterminate("domain-error", "division by zero");
292
+ return require_evaluation.definite({
293
+ kind: "complex",
294
+ re: (left.re * right.re + left.im * right.im) / divisorSquaredMagnitude,
295
+ im: (left.im * right.re - left.re * right.im) / divisorSquaredMagnitude,
296
+ unit: require_computed_value.combineUnitsForDivide(left.unit, right.unit)
297
+ });
298
+ }
299
+ case "modulo": return require_evaluation.indeterminate("domain-error", "'modulo' is undefined for complex values");
300
+ default: throw new Error("unreachable arithmetic operator");
301
+ }
302
+ }
303
+ /** `power` with a complex operand on either side, defined for exactly one case: a real integer exponent, evaluated as the repeated multiplication that integer exponentiation *is* (see the "Complex values" section of README.md for why an arbitrary complex exponent stays out of scope). */
304
+ function applyComplexPower(base, exponent) {
305
+ if (exponent.kind !== "number" || !Number.isInteger(exponent.value)) return require_evaluation.indeterminate("wrong-type", "'power' with a complex operand requires a real integer exponent");
306
+ if (!isDimensionless(base.unit) || !isDimensionless(exponent.unit)) return require_evaluation.indeterminate("wrong-type", "'power' requires dimensionless operands");
307
+ const complexUnit = {
308
+ kind: "complex",
309
+ re: 1,
310
+ im: 0,
311
+ unit: {}
312
+ };
313
+ const complexBase = toComplexValue(base);
314
+ let repeatedProduct = complexUnit;
315
+ for (let applied = 0; applied < Math.abs(exponent.value); applied += 1) repeatedProduct = multiplyComplexValues(repeatedProduct, complexBase);
316
+ if (exponent.value >= 0) return require_evaluation.definite(repeatedProduct);
317
+ return applyArithmeticOnComplex("divide", complexUnit, repeatedProduct);
318
+ }
226
319
  /**
227
320
  * Dispatches `arithmetic` by operand kind. The three cross-kind temporal combinations this design defines (`instant - instant`, `instant + duration`, `duration + instant`) are checked explicitly first, in that order, against the exact operator each requires; any other combination touching an `instant` is `wrong-type` (see "Temporal values" in README.md -- e.g. adding two instants, or subtracting a `duration` from an `instant`, are deliberately *not* defined). Same-kind `duration`/`duration` combinations are delegated to `applyArithmeticOnDurations`; a `duration` paired with anything other than an `instant` or another `duration` is `wrong-type`. Everything remaining requires two `number` operands.
228
321
  */
@@ -251,8 +344,12 @@ function applyArithmetic(op, left, right) {
251
344
  if (left.kind === "instant" || right.kind === "instant") return require_evaluation.indeterminate("wrong-type", `arithmetic operator '${op}' is not defined between a '${left.kind}' and a '${right.kind}' value`);
252
345
  if (left.kind === "duration" && right.kind === "duration") return applyArithmeticOnDurations(op, left, right);
253
346
  if (left.kind === "duration" || right.kind === "duration") return require_evaluation.indeterminate("wrong-type", `arithmetic operator '${op}' is not defined between a '${left.kind}' and a '${right.kind}' value`);
254
- if (left.kind !== "number") return require_evaluation.indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${left.kind}' value`);
255
- if (right.kind !== "number") return require_evaluation.indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${right.kind}' value`);
347
+ if (left.kind !== "number" && left.kind !== "complex") return require_evaluation.indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${left.kind}' value`);
348
+ if (right.kind !== "number" && right.kind !== "complex") return require_evaluation.indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${right.kind}' value`);
349
+ if (left.kind === "complex" || right.kind === "complex") {
350
+ if (op === "power") return applyComplexPower(left, right);
351
+ return applyArithmeticOnComplex(op, toComplexValue(left), toComplexValue(right));
352
+ }
256
353
  return applyArithmeticOnNumbers(op, left, right);
257
354
  }
258
355
  /** 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. */
@@ -367,7 +464,7 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
367
464
  const resolution = await resolvers.resolveValue(node.key, context);
368
465
  if (!resolution.found) return require_evaluation.indeterminate("not-found", `no value found for reference key ${JSON.stringify(node.key)}`);
369
466
  if (node.unit !== void 0) {
370
- if (resolution.value.kind !== "number") return require_evaluation.indeterminate("wrong-type", "a unit was expected on a reference that resolved to a non-numeric value");
467
+ if (resolution.value.kind !== "number" && resolution.value.kind !== "complex") return require_evaluation.indeterminate("wrong-type", "a unit was expected on a reference that resolved to a non-numeric value");
371
468
  if (!require_computed_value.unitsEqual(node.unit, resolution.value.unit)) return require_evaluation.indeterminate("wrong-type", "the resolved value's unit does not match the reference's expected unit");
372
469
  }
373
470
  return require_evaluation.definite(resolution.value);
@@ -397,6 +494,10 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
397
494
  kind: "text",
398
495
  value: node.value
399
496
  });
497
+ case "booleanLiteral": return require_evaluation.definite({
498
+ kind: "boolean",
499
+ value: node.value
500
+ });
400
501
  case "instantLiteral": return require_evaluation.definite({
401
502
  kind: "instant",
402
503
  value: node.value
@@ -406,6 +507,14 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
406
507
  value: node.value,
407
508
  unit: node.unit
408
509
  });
510
+ case "complexLiteral":
511
+ if ("re" in node) return require_evaluation.definite({
512
+ kind: "complex",
513
+ re: node.re,
514
+ im: node.im,
515
+ unit: node.unit
516
+ });
517
+ return require_evaluation.definite(require_complex.complexFromPolar(node.magnitude, node.phase, node.unit));
409
518
  case "arithmetic": {
410
519
  const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth), evaluateValueInternal(node.right, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)]);
411
520
  if (left.status === "indeterminate") return left;
package/dist/evaluator.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { complexFromPolar } from "./complex.js";
1
2
  import { combineUnitsForDivide, combineUnitsForMultiply, unitsEqual } from "./computed-value.js";
2
3
  import { definite, firstIndeterminate, indeterminate } from "./evaluation.js";
3
4
  import { emptyFunctionRegistry } from "./functions.js";
@@ -75,6 +76,10 @@ function compareValues(op, left, right) {
75
76
  if (!unitsEqual(left.unit, right.unit)) return indeterminate("wrong-type", "cannot compare numbers with incompatible units");
76
77
  return definite(applyComparisonOperator(op, left.value, right.value));
77
78
  case "text": return indeterminate("wrong-type", "text values are not comparable via 'compare'; use 'textCompare'");
79
+ case "boolean":
80
+ if (right.kind !== "boolean") return indeterminate("wrong-type", `cannot compare a 'boolean' value with a '${right.kind}' value`);
81
+ if (op !== "eq" && op !== "neq") return indeterminate("wrong-type", `booleans have no natural ordering; '${op}' is only defined for 'eq'/'neq'`);
82
+ return definite(op === "eq" ? left.value === right.value : left.value !== right.value);
78
83
  case "instant": {
79
84
  if (right.kind !== "instant") return indeterminate("wrong-type", `cannot compare an 'instant' value with a '${right.kind}' value`);
80
85
  const leftEpoch = toEpochMilliseconds(left.value);
@@ -86,6 +91,11 @@ function compareValues(op, left, right) {
86
91
  case "duration":
87
92
  if (right.kind !== "duration") return indeterminate("wrong-type", `cannot compare a 'duration' value with a '${right.kind}' value`);
88
93
  return definite(applyComparisonOperator(op, toMilliseconds(left.value, left.unit), toMilliseconds(right.value, right.unit)));
94
+ case "complex":
95
+ if (op !== "eq" && op !== "neq") return indeterminate("wrong-type", `ordering operator '${op}' is not defined for complex values; the complex plane has no total order`);
96
+ if (right.kind !== "complex") return indeterminate("wrong-type", `cannot compare a 'complex' value with a '${right.kind}' value`);
97
+ if (!unitsEqual(left.unit, right.unit)) return indeterminate("wrong-type", "cannot compare complex values with incompatible units");
98
+ return definite(op === "eq" ? left.re === right.re && left.im === right.im : left.re !== right.re || left.im !== right.im);
89
99
  default: throw new Error("unreachable computed-value kind");
90
100
  }
91
101
  }
@@ -120,6 +130,9 @@ function computeMembershipMatch(operand, candidate) {
120
130
  case "text":
121
131
  if (candidate.kind !== "text") return indeterminate("wrong-type", `cannot compare a 'text' value with a '${candidate.kind}' value for membership`);
122
132
  return definite(operand.value === candidate.value);
133
+ case "boolean":
134
+ if (candidate.kind !== "boolean") return indeterminate("wrong-type", `cannot compare a 'boolean' value with a '${candidate.kind}' value for membership`);
135
+ return definite(operand.value === candidate.value);
123
136
  case "instant": {
124
137
  if (candidate.kind !== "instant") return indeterminate("wrong-type", `cannot compare an 'instant' value with a '${candidate.kind}' value for membership`);
125
138
  const operandEpoch = toEpochMilliseconds(operand.value);
@@ -131,6 +144,10 @@ function computeMembershipMatch(operand, candidate) {
131
144
  case "duration":
132
145
  if (candidate.kind !== "duration") return indeterminate("wrong-type", `cannot compare a 'duration' value with a '${candidate.kind}' value for membership`);
133
146
  return definite(toMilliseconds(operand.value, operand.unit) === toMilliseconds(candidate.value, candidate.unit));
147
+ case "complex":
148
+ if (candidate.kind !== "complex") return indeterminate("wrong-type", `cannot compare a 'complex' value with a '${candidate.kind}' value for membership`);
149
+ if (!unitsEqual(operand.unit, candidate.unit)) return indeterminate("wrong-type", "cannot compare complex values with incompatible units for membership");
150
+ return definite(operand.re === candidate.re && operand.im === candidate.im);
134
151
  default: throw new Error("unreachable computed-value kind");
135
152
  }
136
153
  }
@@ -151,8 +168,15 @@ function applyNegate(operand) {
151
168
  value: -operand.value,
152
169
  unit: operand.unit
153
170
  });
171
+ case "complex": return definite({
172
+ kind: "complex",
173
+ re: -operand.re,
174
+ im: -operand.im,
175
+ unit: operand.unit
176
+ });
154
177
  case "text":
155
- case "instant": return indeterminate("wrong-type", `cannot negate a '${operand.kind}' value`);
178
+ case "instant":
179
+ case "boolean": return indeterminate("wrong-type", `cannot negate a '${operand.kind}' value`);
156
180
  default: throw new Error("unreachable computed-value kind");
157
181
  }
158
182
  }
@@ -222,6 +246,75 @@ function applyArithmeticOnDurations(op, left, right) {
222
246
  default: throw new Error("unreachable arithmetic operator");
223
247
  }
224
248
  }
249
+ /** Every real number is a complex number with a zero imaginary part, so promoting one is exact and total -- unlike the temporal cross-kind combinations above, which each had to be enumerated because no such embedding exists between an `instant` and a `duration`. This is what lets a tree mix real and complex terms freely instead of forcing every real literal to be written as a complex one. */
250
+ function toComplexValue(value) {
251
+ if (value.kind === "complex") return value;
252
+ return {
253
+ kind: "complex",
254
+ re: value.value,
255
+ im: 0,
256
+ unit: value.unit
257
+ };
258
+ }
259
+ /** The complex product, as its own component-level helper rather than only a branch of the operator switch below, because `power`'s repeated multiplication needs exactly this and must not re-derive it. */
260
+ function multiplyComplexValues(left, right) {
261
+ return {
262
+ kind: "complex",
263
+ re: left.re * right.re - left.im * right.im,
264
+ im: left.re * right.im + left.im * right.re,
265
+ unit: combineUnitsForMultiply(left.unit, right.unit)
266
+ };
267
+ }
268
+ /** Complex arithmetic, over the one canonical rectangular representation the `complex` kind stores (see the "Complex values" section of README.md). `add`/`subtract` are component-wise and carry the same identical-units requirement real numbers already have. `power` is deliberately excluded from this operator set rather than handled and rejected here: its exponent must stay an un-promoted real number, so the dispatcher routes it to `applyComplexPower` first, and excluding it from the type is what makes the compiler enforce that routing instead of leaving a dead branch behind. */
269
+ function applyArithmeticOnComplex(op, left, right) {
270
+ switch (op) {
271
+ case "add":
272
+ if (!unitsEqual(left.unit, right.unit)) return indeterminate("wrong-type", "cannot add complex values with incompatible units");
273
+ return definite({
274
+ kind: "complex",
275
+ re: left.re + right.re,
276
+ im: left.im + right.im,
277
+ unit: left.unit
278
+ });
279
+ case "subtract":
280
+ if (!unitsEqual(left.unit, right.unit)) return indeterminate("wrong-type", "cannot subtract complex values with incompatible units");
281
+ return definite({
282
+ kind: "complex",
283
+ re: left.re - right.re,
284
+ im: left.im - right.im,
285
+ unit: left.unit
286
+ });
287
+ case "multiply": return definite(multiplyComplexValues(left, right));
288
+ case "divide": {
289
+ const divisorSquaredMagnitude = right.re * right.re + right.im * right.im;
290
+ if (divisorSquaredMagnitude === 0) return indeterminate("domain-error", "division by zero");
291
+ return definite({
292
+ kind: "complex",
293
+ re: (left.re * right.re + left.im * right.im) / divisorSquaredMagnitude,
294
+ im: (left.im * right.re - left.re * right.im) / divisorSquaredMagnitude,
295
+ unit: combineUnitsForDivide(left.unit, right.unit)
296
+ });
297
+ }
298
+ case "modulo": return indeterminate("domain-error", "'modulo' is undefined for complex values");
299
+ default: throw new Error("unreachable arithmetic operator");
300
+ }
301
+ }
302
+ /** `power` with a complex operand on either side, defined for exactly one case: a real integer exponent, evaluated as the repeated multiplication that integer exponentiation *is* (see the "Complex values" section of README.md for why an arbitrary complex exponent stays out of scope). */
303
+ function applyComplexPower(base, exponent) {
304
+ if (exponent.kind !== "number" || !Number.isInteger(exponent.value)) return indeterminate("wrong-type", "'power' with a complex operand requires a real integer exponent");
305
+ if (!isDimensionless(base.unit) || !isDimensionless(exponent.unit)) return indeterminate("wrong-type", "'power' requires dimensionless operands");
306
+ const complexUnit = {
307
+ kind: "complex",
308
+ re: 1,
309
+ im: 0,
310
+ unit: {}
311
+ };
312
+ const complexBase = toComplexValue(base);
313
+ let repeatedProduct = complexUnit;
314
+ for (let applied = 0; applied < Math.abs(exponent.value); applied += 1) repeatedProduct = multiplyComplexValues(repeatedProduct, complexBase);
315
+ if (exponent.value >= 0) return definite(repeatedProduct);
316
+ return applyArithmeticOnComplex("divide", complexUnit, repeatedProduct);
317
+ }
225
318
  /**
226
319
  * Dispatches `arithmetic` by operand kind. The three cross-kind temporal combinations this design defines (`instant - instant`, `instant + duration`, `duration + instant`) are checked explicitly first, in that order, against the exact operator each requires; any other combination touching an `instant` is `wrong-type` (see "Temporal values" in README.md -- e.g. adding two instants, or subtracting a `duration` from an `instant`, are deliberately *not* defined). Same-kind `duration`/`duration` combinations are delegated to `applyArithmeticOnDurations`; a `duration` paired with anything other than an `instant` or another `duration` is `wrong-type`. Everything remaining requires two `number` operands.
227
320
  */
@@ -250,8 +343,12 @@ function applyArithmetic(op, left, right) {
250
343
  if (left.kind === "instant" || right.kind === "instant") return indeterminate("wrong-type", `arithmetic operator '${op}' is not defined between a '${left.kind}' and a '${right.kind}' value`);
251
344
  if (left.kind === "duration" && right.kind === "duration") return applyArithmeticOnDurations(op, left, right);
252
345
  if (left.kind === "duration" || right.kind === "duration") return indeterminate("wrong-type", `arithmetic operator '${op}' is not defined between a '${left.kind}' and a '${right.kind}' value`);
253
- if (left.kind !== "number") return indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${left.kind}' value`);
254
- if (right.kind !== "number") return indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${right.kind}' value`);
346
+ if (left.kind !== "number" && left.kind !== "complex") return indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${left.kind}' value`);
347
+ if (right.kind !== "number" && right.kind !== "complex") return indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${right.kind}' value`);
348
+ if (left.kind === "complex" || right.kind === "complex") {
349
+ if (op === "power") return applyComplexPower(left, right);
350
+ return applyArithmeticOnComplex(op, toComplexValue(left), toComplexValue(right));
351
+ }
255
352
  return applyArithmeticOnNumbers(op, left, right);
256
353
  }
257
354
  /** 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. */
@@ -366,7 +463,7 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
366
463
  const resolution = await resolvers.resolveValue(node.key, context);
367
464
  if (!resolution.found) return indeterminate("not-found", `no value found for reference key ${JSON.stringify(node.key)}`);
368
465
  if (node.unit !== void 0) {
369
- if (resolution.value.kind !== "number") return indeterminate("wrong-type", "a unit was expected on a reference that resolved to a non-numeric value");
466
+ if (resolution.value.kind !== "number" && resolution.value.kind !== "complex") return indeterminate("wrong-type", "a unit was expected on a reference that resolved to a non-numeric value");
370
467
  if (!unitsEqual(node.unit, resolution.value.unit)) return indeterminate("wrong-type", "the resolved value's unit does not match the reference's expected unit");
371
468
  }
372
469
  return definite(resolution.value);
@@ -396,6 +493,10 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
396
493
  kind: "text",
397
494
  value: node.value
398
495
  });
496
+ case "booleanLiteral": return definite({
497
+ kind: "boolean",
498
+ value: node.value
499
+ });
399
500
  case "instantLiteral": return definite({
400
501
  kind: "instant",
401
502
  value: node.value
@@ -405,6 +506,14 @@ async function evaluateValueInternal(node, context, resolvers, accumulator, func
405
506
  value: node.value,
406
507
  unit: node.unit
407
508
  });
509
+ case "complexLiteral":
510
+ if ("re" in node) return definite({
511
+ kind: "complex",
512
+ re: node.re,
513
+ im: node.im,
514
+ unit: node.unit
515
+ });
516
+ return definite(complexFromPolar(node.magnitude, node.phase, node.unit));
408
517
  case "arithmetic": {
409
518
  const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth), evaluateValueInternal(node.right, context, resolvers, accumulator, functions, visitedTreeKeys, treeReferenceDepth)]);
410
519
  if (left.status === "indeterminate") return left;
package/dist/index.cjs CHANGED
@@ -1,7 +1,9 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ const require_complex = require("./complex.cjs");
2
3
  const require_computed_value = require("./computed-value.cjs");
3
4
  const require_derived_aggregates = require("./derived-aggregates.cjs");
4
5
  const require_derived_connectives = require("./derived-connectives.cjs");
6
+ const require_derived_patterns = require("./derived-patterns.cjs");
5
7
  const require_derived_values = require("./derived-values.cjs");
6
8
  const require_evaluation = require("./evaluation.cjs");
7
9
  const require_functions = require("./functions.cjs");
@@ -14,9 +16,13 @@ exports.AndNodeSchema = require_tree.AndNodeSchema;
14
16
  exports.AnyOfNodeSchema = require_tree.AnyOfNodeSchema;
15
17
  exports.ArithmeticNodeSchema = require_tree.ArithmeticNodeSchema;
16
18
  exports.ArithmeticOperatorSchema = require_tree.ArithmeticOperatorSchema;
19
+ exports.BooleanLiteralNodeSchema = require_tree.BooleanLiteralNodeSchema;
17
20
  exports.CallNodeSchema = require_tree.CallNodeSchema;
18
21
  exports.CompareNodeSchema = require_tree.CompareNodeSchema;
19
22
  exports.ComparisonOperatorSchema = require_tree.ComparisonOperatorSchema;
23
+ exports.ComplexLiteralNodeSchema = require_tree.ComplexLiteralNodeSchema;
24
+ exports.ComplexPolarLiteralNodeSchema = require_tree.ComplexPolarLiteralNodeSchema;
25
+ exports.ComplexRectangularLiteralNodeSchema = require_tree.ComplexRectangularLiteralNodeSchema;
20
26
  exports.ComputedValueSchema = require_computed_value.ComputedValueSchema;
21
27
  exports.ConditionalCaseSchema = require_tree.ConditionalCaseSchema;
22
28
  exports.ConditionalNodeSchema = require_tree.ConditionalNodeSchema;
@@ -52,6 +58,10 @@ exports.average = require_derived_aggregates.average;
52
58
  exports.coalesce = require_derived_values.coalesce;
53
59
  exports.combineUnitsForDivide = require_computed_value.combineUnitsForDivide;
54
60
  exports.combineUnitsForMultiply = require_computed_value.combineUnitsForMultiply;
61
+ exports.complexFromPolar = require_complex.complexFromPolar;
62
+ exports.complexLiteralFromPolar = require_complex.complexLiteralFromPolar;
63
+ exports.complexMagnitude = require_complex.complexMagnitude;
64
+ exports.complexPhase = require_complex.complexPhase;
55
65
  exports.count = require_derived_aggregates.count;
56
66
  exports.createEvaluator = require_evaluator.createEvaluator;
57
67
  exports.definite = require_evaluation.definite;
@@ -59,6 +69,7 @@ exports.emptyFunctionRegistry = require_functions.emptyFunctionRegistry;
59
69
  exports.evaluatePredicate = require_evaluator.evaluatePredicate;
60
70
  exports.evaluateValue = require_evaluator.evaluateValue;
61
71
  exports.firstIndeterminate = require_evaluation.firstIndeterminate;
72
+ exports.hierarchicalGlobPattern = require_derived_patterns.hierarchicalGlobPattern;
62
73
  exports.iff = require_derived_connectives.iff;
63
74
  exports.implies = require_derived_connectives.implies;
64
75
  exports.indeterminate = require_evaluation.indeterminate;
@@ -67,7 +78,9 @@ exports.none = require_derived_connectives.none;
67
78
  exports.nor = require_derived_connectives.nor;
68
79
  exports.not = require_derived_connectives.not;
69
80
  exports.or = require_derived_connectives.or;
81
+ exports.prefixPattern = require_derived_patterns.prefixPattern;
70
82
  exports.presenceOf = require_derived_aggregates.presenceOf;
71
83
  exports.sum = require_derived_aggregates.sum;
72
84
  exports.unitsEqual = require_computed_value.unitsEqual;
85
+ exports.wildcardPattern = require_derived_patterns.wildcardPattern;
73
86
  exports.xor = require_derived_connectives.xor;