trilean-sql 2.2.41 → 2.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.
package/README.md CHANGED
@@ -84,7 +84,7 @@ Returns `{ sql, params }`. Throws rather than approximating; see [Refusal](#refu
84
84
 
85
85
  ### `findUnpushableNodeKind(node, options?)`
86
86
 
87
- Returns `{ kind, path, reason }` for the first node the compiler will not translate, or `undefined` if the whole tree is pushable. `compilePredicateNode` runs it first and throws on any result, so call it yourself only to *choose* between pushdown and in-process evaluation without provoking an exception:
87
+ Returns `{ kind, path, reason }` for the first node the compiler will not translate, or `undefined` if the whole tree is pushable. When the refusal is a column or table name the mapping returned and the dialect cannot render as an identifier, the result also carries `identifier: { role, key, problem }`: `role` is `"column"` or `"table"`, `key` the reference or collection key the mapping was asked about, and `problem` the same description the thrown `InvalidColumnError` or `InvalidCollectionTableError` gives. `compilePredicateNode` runs it first and throws on any result, so call it yourself only to *choose* between pushdown and in-process evaluation without provoking an exception:
88
88
 
89
89
  ```ts
90
90
  const blocker = findUnpushableNodeKind(rule, options);
@@ -97,7 +97,9 @@ Passing `options` widens the check: without them the walk is purely structural;
97
97
 
98
98
  ### Errors
99
99
 
100
- `UnsupportedNodeError` (carrying `nodeKind`, `path`, `reason`), `InvalidColumnError` (carrying `referenceKey`, `column`) and `InvalidCollectionTableError` (carrying `collectionKey`, `table`), all extending `TrileanSqlError`.
100
+ `UnsupportedNodeError` (carrying `nodeKind`, `path`, `reason`), `InvalidColumnError` (carrying `referenceKey`, `column`) and `InvalidCollectionTableError` (carrying `collectionKey`, `table`), all extending `TrileanSqlError`. The last two are thrown for a name that cannot be rendered as an identifier, and never repeat the name in their message (a message does name the reference key or collection key the mapping was asked about, which are the tree's own keys, and never a name or value taken from data): an empty name or dot-separated segment, a NUL character, an unpaired UTF-16 surrogate, or more segments than the dialect accepts (at most `schema.table.column` for a column and `schema.table` for a table, in both dialects: [SQLite](https://www.sqlite.org/lang_expr.html) accepts no more; [PostgreSQL](https://www.postgresql.org/docs/current/ddl-schemas.html) says that a leading database name "must be the same as the database you are connected to", which the compiler cannot know, so a leading database segment is refused and the caller omits it). Neither engine carries the NUL character inside a quoted identifier ([PostgreSQL](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS), [SQLite](https://www.sqlite.org/c3ref/prepare.html)), and an unpaired surrogate has no UTF-8 form, the encoding both read the statement in. `findUnpushableNodeKind` refuses the same names, so the guard and the compiler agree.
101
+
102
+ **Values.** A text, pattern or instant literal holding an unpaired surrogate is refused for both dialects, since a driver replaces it with U+FFFD and the engine would compare another value than the evaluator saw. A literal holding the NUL character is refused for PostgreSQL, which rejects it with an invalid byte sequence error, and compiles for SQLite, which binds and compares it as text. The pattern of `portableMatches` and `portableNotMatches` is stricter, because it compiles to SQLite's `GLOB`, which reads a pattern only up to its first NUL: a pattern with one is refused for SQLite too. The pattern of `matches` and `notMatches` is an argument of the `regexp` function the caller registers, which receives it whole, so it compiles for SQLite. The subject of a `portableMatches`/`portableNotMatches` under SQLite is read by `GLOB` the same way, so it is wrapped in a subquery that makes a stored value holding a NUL unknown for that comparison (and for its negation): it never selects a row the evaluator would not select, and the evaluator itself would match such a value, so a stored text with a NUL is the one case the SQLite dialect cannot answer as the evaluator does. The wrapper costs an index: SQLite searches an index on the column for a prefix pattern such as `ENA-*`, and with the wrapper it reads every row and evaluates one subquery for each. Where that matters, leave `portableMatches` to in-process evaluation for SQLite on a large table.
101
103
 
102
104
  ## What compiles
103
105
 
@@ -112,7 +114,7 @@ Passing `options` widens the check: without them the walk is purely structural;
112
114
  | `some`, `every` | a correlated scalar subquery over `collectionFor`'s table, combining each participating row's own vote with `MAX`/`CASE` to match the evaluator's OR/AND-fold absorption exactly (see [Collections](#collections)); refused unless `collectionFor` maps the `collection` key | same |
113
115
  | `fold` (`max`/`min`) | the same correlated subquery, aggregating each participating item's own projected value with `MAX`/`MIN`, `NULL` the moment any participating item (or its `filter`) is indeterminate (see [Collections](#collections)); refused unless `collectionFor` maps the `collection` key. `fold` (`reduce`) is always refused — see [Refusal](#refusal) | same |
114
116
  | `reference` | the mapped column, as a quoted identifier | same |
115
- | `textLiteral`, `numberLiteral`, `booleanLiteral`, `instantLiteral` | a bind parameter, cast to `text`, `double precision`, `boolean`, `timestamptz` | a bare `?`, uncast |
117
+ | `textLiteral`, `numberLiteral`, `booleanLiteral`, `instantLiteral` | a bind parameter, cast to `text`, `double precision`, `boolean`, `timestamptz` | a bare `?`, uncast; an `instantLiteral` is a number, the milliseconds since the epoch, see [Dialects](#dialects) |
116
118
 
117
119
  Every literal in the tree becomes a parameter. Nothing but structure, operators and quoted identifiers is ever written into the returned `sql`, so a literal's content cannot alter the statement. Identifier quoting is the same in both: each dot-separated segment double-quoted with any embedded quote doubled, which is ANSI-standard and not a per-dialect rule.
118
120
 
@@ -142,7 +144,7 @@ A `fold(max|min)` whose projected item is statically known to be text or boolean
142
144
 
143
145
  ## Dialects
144
146
 
145
- The dialects differ in three places, and nowhere else. `matches`/`notMatches` compile to each engine's own regular-expression operator; placeholders are `$N::type` under PostgreSQL and a bare `?` under SQLite; and the bare `NULL` in an empty `memberOf` carries a `::boolean` annotation only where there is a boolean type to annotate. Everything else the compiler emits — the connectives, the six comparison operators, `=`/`<>`, `IN`/`NOT IN`, `IS NOT NULL`, quoted identifiers — is ANSI-standard and identical.
147
+ The dialects differ in four places, and nowhere else. `matches`/`notMatches` compile to each engine's own regular-expression operator; placeholders are `$N::type` under PostgreSQL and a bare `?` under SQLite; the bare `NULL` in an empty `memberOf` carries a `::boolean` annotation only where there is a boolean type to annotate; and an instant is compared by its point in time, which PostgreSQL's `timestamptz` is already and SQLite reads from its text (see [Dialects](#dialects)). Everything else the compiler emits — the connectives, the six comparison operators, `=`/`<>`, `IN`/`NOT IN`, `IS NOT NULL`, quoted identifiers — is ANSI-standard and identical.
146
148
 
147
149
  ```ts
148
150
  const { sql, params } = compilePredicateNode(rule, { dialect: "sqlite", columnFor });
@@ -159,7 +161,13 @@ Two things a SQLite caller has to supply that a PostgreSQL caller does not, both
159
161
 
160
162
  A dialect this version does not implement is refused by name, from `compilePredicateNode` and `findUnpushableNodeKind` alike, with `UnknownDialectError`. `SqlDialect` is a closed union so TypeScript source cannot reach that, but a dialect read from configuration and asserted into the union at the boundary can, and reporting such a tree as pushable would promise a compilation that cannot happen.
161
163
 
162
- Instants are the one place to be deliberate rather than merely careful. SQLite has no timestamp type either, so an `instantLiteral` is compared as text against whatever text the column holds. Offset-bearing ISO-8601 in a single common offset (`2020-01-01T00:00:00Z`) sorts chronologically as a string and compares correctly; mixed offsets, or a format that is not ISO-8601, do not. This is the SQLite counterpart of the PostgreSQL session-time-zone caveat under [Refusal](#refusal), and the same advice resolves both.
164
+ **Instants.** SQLite has no timestamp type, and its date functions read far more than an instant: the text `now` is the present time, a time of day is a day in the year 2000, and a number is a Julian day. Text compares by its characters, not by the instant, so a comparison over instants reads both sides as a point in time first, and only if the value is an instant in one grammar. Every ordering and equality comparison and every membership with an instant operand (an `instantLiteral`, a column declared `"timestamp"`, or a `fold` of `max` or `min` over one) compiles each operand to whole milliseconds since the epoch, as an integer. The SQL tests the shape of a stored value itself, with `GLOB` and `substr`, before it converts anything, so no value can make the result depend on the clock or on SQLite's readings of a date; the same grammar is applied to an `instantLiteral` when the tree is compiled, and the parameter is that number.
165
+
166
+ The grammar is: four-digit year, `-`, two-digit month, `-`, two-digit day, `T` or one space, two-digit hour, `:`, minute, `:`, second, an optional `.` and one or more fractional digits, then `Z` or a sign, two-digit hours, `:` and two-digit minutes. The value must also be a real moment: a month 1 to 12, a day the month has (no `02-30`, `04-31` or `1900-02-29`), an hour 0 to 23 (no `24:00:00`), a minute and a second 0 to 59 (no leap second), and an offset of at most `23:59`. A stored value that is not text in exactly this form is NULL, so every comparison over it is unknown: `now`, a time or a date alone, a trailing or leading space, a lower-case `t` or `z`, an offset without its colon, a form with no offset, `toUTCString()` output, an expanded or negative year, a number of any kind (a Julian day, Unix seconds or milliseconds), a blob, and a text with a NUL. An `instantLiteral` outside the grammar is bound as NULL, so a comparison against it is unknown. The fraction is truncated to three digits, as `Date.parse` does.
167
+
168
+ Inside the grammar SQLite, PostgreSQL and the evaluator (`Date.parse`) read the same instant, with three differences that are PostgreSQL's. It keeps microseconds where SQLite's comparison and the evaluator keep milliseconds, so a stored `.9996` is not equal to `.999` there and is equal in the other two (write instants to the millisecond, as `toISOString` does; tracked in [#164](https://github.com/ExaDev/trilean/issues/164)); it does not read year `0000`; and it refuses an offset beyond `15:59` with a query error. Outside the grammar the SQLite result is unknown while the evaluator may read a value: `Date.parse` also reads forms such as `Wed, 01 Jan 2020 00:00:00 GMT`, an offset without a colon, a date alone and a form with no offset (which it reads in the machine's time zone), and it reads `2020-01-01T24:00:00Z`, `2020-02-30T00:00:00Z` and a lower-case `z`. Write instants in the grammar, as `Date.prototype.toISOString` does.
169
+
170
+ **Cost.** The shape test and the conversion are evaluated in SQL for every row, once for each instant operand of a comparison that is a column (a `memberOf` has one; each side of a `compare` that is a column, and each `fold` item, has its own). One evaluation makes 39 scalar function calls (`length`, `substr`, `instr`, `strftime` and `CAST`) and 15 `GLOB` tests, and mentions the column 43 times, so a comparison over a table costs that much work per row scanned. A bare index on the stored text does not serve the comparison; an index on the same expression does, and then the expression is evaluated when the row is written and not when it is read.
163
171
 
164
172
  ## Refusal
165
173
 
@@ -167,7 +175,7 @@ The compiler never degrades. There is no best-effort fragment, no silently dropp
167
175
 
168
176
  The check is an allow-list walk rather than a deny-list, so a node kind added to trilean after this version was written is refused by default instead of falling through to whatever branch happened to be last.
169
177
 
170
- That guarantee is about the tree's structure, and it has one remaining limit that is about the *content* of a string operand rather than any node's kind, and is not reachable by a walk over kinds: an `instantLiteral` is parsed by PostgreSQL rather than by `Date`, so one carrying no UTC offset is read in the *database session's* time zone where trilean reads it in the Node process's, and one PostgreSQL cannot parse at all raises a query error at execution time rather than this exception (trilean answers `indeterminate` for the same string). Pass instants as offset-bearing ISO-8601, which both read identically.
178
+ That guarantee is about the tree's structure, and it has one remaining limit that is about the *content* of a string operand rather than any node's kind, and is not reachable by a walk over kinds: an `instantLiteral` is parsed by PostgreSQL rather than by `Date`, so one carrying no UTC offset is read in the *database session's* time zone where trilean reads it in the Node process's, and one PostgreSQL cannot parse at all raises a query error at execution time rather than this exception (trilean answers `indeterminate` for the same string). Pass instants as offset-bearing ISO-8601, which both read identically; the one grammar on which SQLite, PostgreSQL and the evaluator agree is stated under [Dialects](#dialects).
171
179
 
172
180
  A `matches`/`notMatches` pattern would be the same kind of limit — matched by the server in PostgreSQL's own regular-expression language, not ECMAScript's — which is why it is refused rather than pushed down by default; see [Regular expressions](#regular-expressions). Setting `postgresRegexpPushdown: true` opts back into that limit deliberately, for patterns already known to be portable.
173
181
 
@@ -240,7 +248,7 @@ const { sql, params } = compilePredicateNode(
240
248
  },
241
249
  { dialect: "sqlite", columnFor },
242
250
  );
243
- // sql: ("code" GLOB ?)
251
+ // sql: ((SELECT CASE WHEN instr(CAST("v" AS BLOB), x'00') > 0 THEN NULL ELSE "v" END FROM (SELECT "code" AS "v")) GLOB ?)
244
252
  // params: ["ENA-[0-9]*"]
245
253
  ```
246
254
 
package/dist/compile.cjs CHANGED
@@ -1,8 +1,8 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  const require_errors = require("./errors.cjs");
3
- const require_guard = require("./guard.cjs");
3
+ const require_guard = require("./guard-CCet6aaa.cjs");
4
4
  const require_portable_pattern = require("./portable-pattern.cjs");
5
- const require_options = require("./options.cjs");
5
+ const require_options = require("./options-DOE1_Cwr.cjs");
6
6
  let trilean_regex = require("trilean-regex");
7
7
  // src/compile.ts
8
8
  const COMPARISON_SQL = {
@@ -48,20 +48,20 @@ function placeholder(context, value, castTo) {
48
48
  *
49
49
  * A column name cannot be a bind parameter -- it is part of the statement's structure, not its data -- so it is the one caller-supplied string that reaches the SQL text. Quoting it unconditionally is what keeps that safe: the doubling makes even a name containing `"; DROP TABLE ...` a single, inert identifier that simply does not exist. Quoting also means a name is taken literally rather than case-folded, so `columnFor` must return the column's real, case-exact name.
50
50
  */
51
- function quoteColumn(referenceKey, binding) {
52
- const segments = binding.column.split(".");
53
- if (segments.some((segment) => segment.length === 0)) throw new require_errors.InvalidColumnError(referenceKey, binding.column, binding.column.length === 0 ? "the name is empty" : "a dot-separated segment is empty");
54
- return segments.map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
51
+ function quoteColumn(referenceKey, binding, dialect) {
52
+ const problem = require_guard.identifierProblem("column", binding.column, dialect);
53
+ if (problem !== void 0) throw new require_errors.InvalidColumnError(referenceKey, binding.column, problem);
54
+ return binding.column.split(".").map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
55
55
  }
56
56
  /**
57
57
  * Renders a `collectionFor` result's `table` as a SQL identifier, the same way `quoteColumn` renders a column: each dot-separated segment double-quoted, with any embedded double quote doubled.
58
58
  *
59
59
  * Takes the already-resolved table string rather than the whole `SqlCollectionBinding`, since every call site here has already destructured it -- unlike `quoteColumn`, which reads `binding.column` itself because its own call site still has the whole `SqlColumnBinding` in hand.
60
60
  */
61
- function quoteTable(collectionKey, table) {
62
- const segments = table.split(".");
63
- if (segments.some((segment) => segment.length === 0)) throw new require_errors.InvalidCollectionTableError(collectionKey, table, table.length === 0 ? "the name is empty" : "a dot-separated segment is empty");
64
- return segments.map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
61
+ function quoteTable(collectionKey, table, dialect) {
62
+ const problem = require_guard.identifierProblem("table", table, dialect);
63
+ if (problem !== void 0) throw new require_errors.InvalidCollectionTableError(collectionKey, table, problem);
64
+ return table.split(".").map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
65
65
  }
66
66
  function bindingOf(context, node) {
67
67
  if (node.kind !== "reference" || typeof node.key !== "string") return;
@@ -90,7 +90,7 @@ function refuse(kind, layer) {
90
90
  function compileCollection(node, context, layer) {
91
91
  if (typeof node.collection !== "string" || context.options.collectionFor === void 0) return refuse(node.kind, layer);
92
92
  const binding = context.options.collectionFor(node.collection);
93
- const table = quoteTable(node.collection, binding.table);
93
+ const table = quoteTable(node.collection, binding.table, context.options.dialect);
94
94
  const itemContext = {
95
95
  ...context,
96
96
  options: {
@@ -124,21 +124,47 @@ function compilePortablePattern(node, context) {
124
124
  });
125
125
  }
126
126
  }
127
- function compileExpression(node, context) {
127
+ /**
128
+ * Whether an operand is an instant, as far as the compiler can tell without running anything: an `instantLiteral`, a column declared `"timestamp"`, or a `fold(max|min)` over one. A comparison or membership with any such operand compares all its operands as points in time ({@link DialectConfig.instantColumn}), since the other side of a comparison the evaluator answers definitely is an instant too.
129
+ */
130
+ function isInstant(node, context) {
131
+ if (node.kind === "instantLiteral") return true;
132
+ if (node.kind === "reference") return bindingOf(context, node)?.binding.paramType === "timestamp";
133
+ if (node.kind === "fold" && node.combiner.mode !== "reduce" && typeof node.collection === "string" && context.options.collectionFor !== void 0) {
134
+ const binding = context.options.collectionFor(node.collection);
135
+ return isInstant(node.combiner.item, {
136
+ ...context,
137
+ options: {
138
+ ...context.options,
139
+ columnFor: binding.columnFor
140
+ }
141
+ });
142
+ }
143
+ return false;
144
+ }
145
+ /** Whether any of the operands of a comparison or membership is an instant. */
146
+ function anyInstant(nodes, context) {
147
+ return nodes.some((node) => isInstant(node, context));
148
+ }
149
+ /**
150
+ * Compiles an expression. `asInstant` renders an instant-valued operand as the dialect's comparable point in time rather than as its stored text ({@link DialectConfig.instantColumn}); it is set for every operand of a comparison or membership that has an instant operand, and reaches the item of a `fold` so a maximum or minimum is of points in time, not of text.
151
+ */
152
+ function compileExpression(node, context, asInstant = false) {
128
153
  switch (node.kind) {
129
154
  case "reference": {
130
155
  const resolved = bindingOf(context, node);
131
156
  if (resolved === void 0) return refuse(node.kind, "expression");
132
- return quoteColumn(resolved.referenceKey, resolved.binding);
157
+ const column = quoteColumn(resolved.referenceKey, resolved.binding, context.options.dialect);
158
+ return asInstant ? context.dialect.instantColumn(column) : column;
133
159
  }
160
+ case "instantLiteral": return placeholder(context, asInstant ? context.dialect.instantParameter(node.value) : node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
134
161
  case "textLiteral":
135
162
  case "numberLiteral":
136
- case "booleanLiteral":
137
- case "instantLiteral": return placeholder(context, node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
163
+ case "booleanLiteral": return placeholder(context, node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
138
164
  case "fold": {
139
165
  if (node.combiner.mode === "reduce") return refuse(node.kind, "expression");
140
166
  const { table, join, itemContext, filterSql } = compileCollection(node, context, "expression");
141
- const itemValueSql = compileExpression(node.combiner.item, itemContext);
167
+ const itemValueSql = compileExpression(node.combiner.item, itemContext, asInstant);
142
168
  const participating = `SELECT "filter_ok", "item_value" FROM (SELECT ${filterSql ?? "TRUE"} AS "filter_ok", ${itemValueSql} AS "item_value" FROM ${table} WHERE ${join}) AS "t" WHERE "filter_ok" IS NULL OR "filter_ok"`;
143
169
  return `(SELECT CASE WHEN MAX(CASE WHEN "filter_ok" IS NULL OR "item_value" IS NULL THEN 1 ELSE 0 END) = 1 THEN NULL ELSE ${node.combiner.mode === "max" ? "MAX" : "MIN"}("item_value") END FROM (${participating}) AS "v")`;
144
170
  }
@@ -157,22 +183,25 @@ function compilePredicate(node, context) {
157
183
  return `(${node.operands.map((operand) => compilePredicate(operand, context)).join(joiner)})`;
158
184
  }
159
185
  case "compare": {
160
- const left = compileExpression(node.left, context);
161
- const right = compileExpression(node.right, context);
186
+ const instants = anyInstant([node.left, node.right], context);
187
+ const left = compileExpression(node.left, context, instants);
188
+ const right = compileExpression(node.right, context, instants);
162
189
  return `(${left} ${COMPARISON_SQL[node.op]} ${right})`;
163
190
  }
164
191
  case "textCompare": {
165
- const left = compileExpression(node.left, context);
192
+ const subject = compileExpression(node.left, context);
193
+ const left = context.options.dialect === "sqlite" && (node.op === "portableMatches" || node.op === "portableNotMatches") ? `(SELECT CASE WHEN instr(CAST("v" AS BLOB), x'00') > 0 THEN NULL ELSE "v" END FROM (SELECT ${subject} AS "v"))` : subject;
166
194
  const right = node.op === "portableMatches" || node.op === "portableNotMatches" ? compilePortablePattern(node, context) : compileExpression(node.right, context);
167
195
  return `(${left} ${context.textComparison[node.op]} ${right})`;
168
196
  }
169
197
  case "memberOf": {
170
- const operand = compileExpression(node.operand, context);
198
+ const instants = anyInstant([node.operand, ...node.candidates], context);
199
+ const operand = compileExpression(node.operand, context, instants);
171
200
  if (node.candidates.length === 0) {
172
201
  const nullLiteral = `NULL${context.dialect.emptyMemberOfNullSuffix}`;
173
202
  return node.op === "in" ? `(${operand} IS NULL AND ${nullLiteral})` : `(${operand} IS NOT NULL OR ${nullLiteral})`;
174
203
  }
175
- const candidates = node.candidates.map((candidate) => compileExpression(candidate, context)).join(", ");
204
+ const candidates = node.candidates.map((candidate) => compileExpression(candidate, context, instants)).join(", ");
176
205
  return `(${operand} ${node.op === "in" ? "IN" : "NOT IN"} (${candidates}))`;
177
206
  }
178
207
  case "exists": return `(${compileExpression(node.operand, context)} IS NOT NULL)`;
@@ -195,7 +224,8 @@ function compilePredicate(node, context) {
195
224
  * Every caller-supplied literal becomes a bind parameter. Nothing but structure, operators, and quoted column identifiers is ever written into the returned `sql`.
196
225
  * @throws `UnknownDialectError` if `options.dialect` names a dialect this version does not implement.
197
226
  * @throws `UnsupportedNodeError` if any node in the tree is one this compiler will not translate -- see `findUnpushableNodeKind`, which this runs first and which a caller can run itself to choose between pushdown and in-process evaluation without provoking an exception.
198
- * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier.
227
+ * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier: an empty name or segment, or a character a quoted identifier cannot carry.
228
+ * @throws `InvalidCollectionTableError` if `collectionFor` returns a table that cannot be rendered as an identifier, for the same reasons.
199
229
  */
200
230
  function compilePredicateNode(node, options) {
201
231
  require_options.assertImplementedDialect(options.dialect);
@@ -234,7 +264,14 @@ function compilePredicateNode(node, options) {
234
264
  } }
235
265
  };
236
266
  const unpushable = require_guard.findUnpushableNodeKind(node, memoised);
237
- if (unpushable !== void 0) throw new require_errors.UnsupportedNodeError(unpushable);
267
+ if (unpushable !== void 0) {
268
+ if (unpushable.identifier?.role === "column") throw new require_errors.InvalidColumnError(unpushable.identifier.key, memoised.columnFor(unpushable.identifier.key).column, unpushable.identifier.problem);
269
+ if (unpushable.identifier?.role === "table") {
270
+ const table = memoised.collectionFor?.(unpushable.identifier.key).table;
271
+ throw new require_errors.InvalidCollectionTableError(unpushable.identifier.key, table ?? "", unpushable.identifier.problem);
272
+ }
273
+ throw new require_errors.UnsupportedNodeError(unpushable);
274
+ }
238
275
  const dialect = require_options.DIALECT_CONFIG[options.dialect];
239
276
  const context = {
240
277
  options: memoised,
@@ -8,6 +8,7 @@ import { PredicateNode } from "trilean";
8
8
  * Every caller-supplied literal becomes a bind parameter. Nothing but structure, operators, and quoted column identifiers is ever written into the returned `sql`.
9
9
  * @throws `UnknownDialectError` if `options.dialect` names a dialect this version does not implement.
10
10
  * @throws `UnsupportedNodeError` if any node in the tree is one this compiler will not translate -- see `findUnpushableNodeKind`, which this runs first and which a caller can run itself to choose between pushdown and in-process evaluation without provoking an exception.
11
- * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier.
11
+ * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier: an empty name or segment, or a character a quoted identifier cannot carry.
12
+ * @throws `InvalidCollectionTableError` if `collectionFor` returns a table that cannot be rendered as an identifier, for the same reasons.
12
13
  */
13
14
  export declare function compilePredicateNode(node: PredicateNode, options: Readonly<SqlCompileOptions>): CompiledSql;
package/dist/compile.d.ts CHANGED
@@ -8,6 +8,7 @@ import { PredicateNode } from "trilean";
8
8
  * Every caller-supplied literal becomes a bind parameter. Nothing but structure, operators, and quoted column identifiers is ever written into the returned `sql`.
9
9
  * @throws `UnknownDialectError` if `options.dialect` names a dialect this version does not implement.
10
10
  * @throws `UnsupportedNodeError` if any node in the tree is one this compiler will not translate -- see `findUnpushableNodeKind`, which this runs first and which a caller can run itself to choose between pushdown and in-process evaluation without provoking an exception.
11
- * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier.
11
+ * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier: an empty name or segment, or a character a quoted identifier cannot carry.
12
+ * @throws `InvalidCollectionTableError` if `collectionFor` returns a table that cannot be rendered as an identifier, for the same reasons.
12
13
  */
13
14
  export declare function compilePredicateNode(node: PredicateNode, options: Readonly<SqlCompileOptions>): CompiledSql;
package/dist/compile.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { InvalidCollectionTableError, InvalidColumnError, UnsupportedNodeError } from "./errors.js";
2
- import { findUnpushableNodeKind } from "./guard.js";
2
+ import { n as identifierProblem, t as findUnpushableNodeKind } from "./guard-D4CIUc5h.js";
3
3
  import { renderPostgresPattern, renderSqliteGlobPattern } from "./portable-pattern.js";
4
- import { DIALECT_CONFIG, assertImplementedDialect } from "./options.js";
4
+ import { r as assertImplementedDialect, t as DIALECT_CONFIG } from "./options-c1nHisgX.js";
5
5
  import { parseRegex } from "trilean-regex";
6
6
  // src/compile.ts
7
7
  const COMPARISON_SQL = {
@@ -47,20 +47,20 @@ function placeholder(context, value, castTo) {
47
47
  *
48
48
  * A column name cannot be a bind parameter -- it is part of the statement's structure, not its data -- so it is the one caller-supplied string that reaches the SQL text. Quoting it unconditionally is what keeps that safe: the doubling makes even a name containing `"; DROP TABLE ...` a single, inert identifier that simply does not exist. Quoting also means a name is taken literally rather than case-folded, so `columnFor` must return the column's real, case-exact name.
49
49
  */
50
- function quoteColumn(referenceKey, binding) {
51
- const segments = binding.column.split(".");
52
- if (segments.some((segment) => segment.length === 0)) throw new InvalidColumnError(referenceKey, binding.column, binding.column.length === 0 ? "the name is empty" : "a dot-separated segment is empty");
53
- return segments.map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
50
+ function quoteColumn(referenceKey, binding, dialect) {
51
+ const problem = identifierProblem("column", binding.column, dialect);
52
+ if (problem !== void 0) throw new InvalidColumnError(referenceKey, binding.column, problem);
53
+ return binding.column.split(".").map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
54
54
  }
55
55
  /**
56
56
  * Renders a `collectionFor` result's `table` as a SQL identifier, the same way `quoteColumn` renders a column: each dot-separated segment double-quoted, with any embedded double quote doubled.
57
57
  *
58
58
  * Takes the already-resolved table string rather than the whole `SqlCollectionBinding`, since every call site here has already destructured it -- unlike `quoteColumn`, which reads `binding.column` itself because its own call site still has the whole `SqlColumnBinding` in hand.
59
59
  */
60
- function quoteTable(collectionKey, table) {
61
- const segments = table.split(".");
62
- if (segments.some((segment) => segment.length === 0)) throw new InvalidCollectionTableError(collectionKey, table, table.length === 0 ? "the name is empty" : "a dot-separated segment is empty");
63
- return segments.map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
60
+ function quoteTable(collectionKey, table, dialect) {
61
+ const problem = identifierProblem("table", table, dialect);
62
+ if (problem !== void 0) throw new InvalidCollectionTableError(collectionKey, table, problem);
63
+ return table.split(".").map((segment) => `"${segment.replaceAll("\"", "\"\"")}"`).join(".");
64
64
  }
65
65
  function bindingOf(context, node) {
66
66
  if (node.kind !== "reference" || typeof node.key !== "string") return;
@@ -89,7 +89,7 @@ function refuse(kind, layer) {
89
89
  function compileCollection(node, context, layer) {
90
90
  if (typeof node.collection !== "string" || context.options.collectionFor === void 0) return refuse(node.kind, layer);
91
91
  const binding = context.options.collectionFor(node.collection);
92
- const table = quoteTable(node.collection, binding.table);
92
+ const table = quoteTable(node.collection, binding.table, context.options.dialect);
93
93
  const itemContext = {
94
94
  ...context,
95
95
  options: {
@@ -123,21 +123,47 @@ function compilePortablePattern(node, context) {
123
123
  });
124
124
  }
125
125
  }
126
- function compileExpression(node, context) {
126
+ /**
127
+ * Whether an operand is an instant, as far as the compiler can tell without running anything: an `instantLiteral`, a column declared `"timestamp"`, or a `fold(max|min)` over one. A comparison or membership with any such operand compares all its operands as points in time ({@link DialectConfig.instantColumn}), since the other side of a comparison the evaluator answers definitely is an instant too.
128
+ */
129
+ function isInstant(node, context) {
130
+ if (node.kind === "instantLiteral") return true;
131
+ if (node.kind === "reference") return bindingOf(context, node)?.binding.paramType === "timestamp";
132
+ if (node.kind === "fold" && node.combiner.mode !== "reduce" && typeof node.collection === "string" && context.options.collectionFor !== void 0) {
133
+ const binding = context.options.collectionFor(node.collection);
134
+ return isInstant(node.combiner.item, {
135
+ ...context,
136
+ options: {
137
+ ...context.options,
138
+ columnFor: binding.columnFor
139
+ }
140
+ });
141
+ }
142
+ return false;
143
+ }
144
+ /** Whether any of the operands of a comparison or membership is an instant. */
145
+ function anyInstant(nodes, context) {
146
+ return nodes.some((node) => isInstant(node, context));
147
+ }
148
+ /**
149
+ * Compiles an expression. `asInstant` renders an instant-valued operand as the dialect's comparable point in time rather than as its stored text ({@link DialectConfig.instantColumn}); it is set for every operand of a comparison or membership that has an instant operand, and reaches the item of a `fold` so a maximum or minimum is of points in time, not of text.
150
+ */
151
+ function compileExpression(node, context, asInstant = false) {
127
152
  switch (node.kind) {
128
153
  case "reference": {
129
154
  const resolved = bindingOf(context, node);
130
155
  if (resolved === void 0) return refuse(node.kind, "expression");
131
- return quoteColumn(resolved.referenceKey, resolved.binding);
156
+ const column = quoteColumn(resolved.referenceKey, resolved.binding, context.options.dialect);
157
+ return asInstant ? context.dialect.instantColumn(column) : column;
132
158
  }
159
+ case "instantLiteral": return placeholder(context, asInstant ? context.dialect.instantParameter(node.value) : node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
133
160
  case "textLiteral":
134
161
  case "numberLiteral":
135
- case "booleanLiteral":
136
- case "instantLiteral": return placeholder(context, node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
162
+ case "booleanLiteral": return placeholder(context, node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
137
163
  case "fold": {
138
164
  if (node.combiner.mode === "reduce") return refuse(node.kind, "expression");
139
165
  const { table, join, itemContext, filterSql } = compileCollection(node, context, "expression");
140
- const itemValueSql = compileExpression(node.combiner.item, itemContext);
166
+ const itemValueSql = compileExpression(node.combiner.item, itemContext, asInstant);
141
167
  const participating = `SELECT "filter_ok", "item_value" FROM (SELECT ${filterSql ?? "TRUE"} AS "filter_ok", ${itemValueSql} AS "item_value" FROM ${table} WHERE ${join}) AS "t" WHERE "filter_ok" IS NULL OR "filter_ok"`;
142
168
  return `(SELECT CASE WHEN MAX(CASE WHEN "filter_ok" IS NULL OR "item_value" IS NULL THEN 1 ELSE 0 END) = 1 THEN NULL ELSE ${node.combiner.mode === "max" ? "MAX" : "MIN"}("item_value") END FROM (${participating}) AS "v")`;
143
169
  }
@@ -156,22 +182,25 @@ function compilePredicate(node, context) {
156
182
  return `(${node.operands.map((operand) => compilePredicate(operand, context)).join(joiner)})`;
157
183
  }
158
184
  case "compare": {
159
- const left = compileExpression(node.left, context);
160
- const right = compileExpression(node.right, context);
185
+ const instants = anyInstant([node.left, node.right], context);
186
+ const left = compileExpression(node.left, context, instants);
187
+ const right = compileExpression(node.right, context, instants);
161
188
  return `(${left} ${COMPARISON_SQL[node.op]} ${right})`;
162
189
  }
163
190
  case "textCompare": {
164
- const left = compileExpression(node.left, context);
191
+ const subject = compileExpression(node.left, context);
192
+ const left = context.options.dialect === "sqlite" && (node.op === "portableMatches" || node.op === "portableNotMatches") ? `(SELECT CASE WHEN instr(CAST("v" AS BLOB), x'00') > 0 THEN NULL ELSE "v" END FROM (SELECT ${subject} AS "v"))` : subject;
165
193
  const right = node.op === "portableMatches" || node.op === "portableNotMatches" ? compilePortablePattern(node, context) : compileExpression(node.right, context);
166
194
  return `(${left} ${context.textComparison[node.op]} ${right})`;
167
195
  }
168
196
  case "memberOf": {
169
- const operand = compileExpression(node.operand, context);
197
+ const instants = anyInstant([node.operand, ...node.candidates], context);
198
+ const operand = compileExpression(node.operand, context, instants);
170
199
  if (node.candidates.length === 0) {
171
200
  const nullLiteral = `NULL${context.dialect.emptyMemberOfNullSuffix}`;
172
201
  return node.op === "in" ? `(${operand} IS NULL AND ${nullLiteral})` : `(${operand} IS NOT NULL OR ${nullLiteral})`;
173
202
  }
174
- const candidates = node.candidates.map((candidate) => compileExpression(candidate, context)).join(", ");
203
+ const candidates = node.candidates.map((candidate) => compileExpression(candidate, context, instants)).join(", ");
175
204
  return `(${operand} ${node.op === "in" ? "IN" : "NOT IN"} (${candidates}))`;
176
205
  }
177
206
  case "exists": return `(${compileExpression(node.operand, context)} IS NOT NULL)`;
@@ -194,7 +223,8 @@ function compilePredicate(node, context) {
194
223
  * Every caller-supplied literal becomes a bind parameter. Nothing but structure, operators, and quoted column identifiers is ever written into the returned `sql`.
195
224
  * @throws `UnknownDialectError` if `options.dialect` names a dialect this version does not implement.
196
225
  * @throws `UnsupportedNodeError` if any node in the tree is one this compiler will not translate -- see `findUnpushableNodeKind`, which this runs first and which a caller can run itself to choose between pushdown and in-process evaluation without provoking an exception.
197
- * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier.
226
+ * @throws `InvalidColumnError` if `columnFor` returns a column that cannot be rendered as an identifier: an empty name or segment, or a character a quoted identifier cannot carry.
227
+ * @throws `InvalidCollectionTableError` if `collectionFor` returns a table that cannot be rendered as an identifier, for the same reasons.
198
228
  */
199
229
  function compilePredicateNode(node, options) {
200
230
  assertImplementedDialect(options.dialect);
@@ -233,7 +263,14 @@ function compilePredicateNode(node, options) {
233
263
  } }
234
264
  };
235
265
  const unpushable = findUnpushableNodeKind(node, memoised);
236
- if (unpushable !== void 0) throw new UnsupportedNodeError(unpushable);
266
+ if (unpushable !== void 0) {
267
+ if (unpushable.identifier?.role === "column") throw new InvalidColumnError(unpushable.identifier.key, memoised.columnFor(unpushable.identifier.key).column, unpushable.identifier.problem);
268
+ if (unpushable.identifier?.role === "table") {
269
+ const table = memoised.collectionFor?.(unpushable.identifier.key).table;
270
+ throw new InvalidCollectionTableError(unpushable.identifier.key, table ?? "", unpushable.identifier.problem);
271
+ }
272
+ throw new UnsupportedNodeError(unpushable);
273
+ }
237
274
  const dialect = DIALECT_CONFIG[options.dialect];
238
275
  const context = {
239
276
  options: memoised,
package/dist/errors.cjs CHANGED
@@ -52,7 +52,7 @@ var InvalidColumnError = class extends TrileanSqlError {
52
52
  referenceKey;
53
53
  column;
54
54
  constructor(referenceKey, column, reason) {
55
- super(`columnFor(${JSON.stringify(referenceKey)}) returned ${JSON.stringify(column)}, which is not a usable column identifier: ${reason}`);
55
+ super(`columnFor(${JSON.stringify(referenceKey)}) returned a name that is not a usable column identifier: ${reason}`);
56
56
  this.name = "InvalidColumnError";
57
57
  this.referenceKey = referenceKey;
58
58
  this.column = column;
@@ -67,7 +67,7 @@ var InvalidCollectionTableError = class extends TrileanSqlError {
67
67
  collectionKey;
68
68
  table;
69
69
  constructor(collectionKey, table, reason) {
70
- super(`collectionFor(${JSON.stringify(collectionKey)}) returned ${JSON.stringify(table)}, which is not a usable table identifier: ${reason}`);
70
+ super(`collectionFor(${JSON.stringify(collectionKey)}) returned a name that is not a usable table identifier: ${reason}`);
71
71
  this.name = "InvalidCollectionTableError";
72
72
  this.collectionKey = collectionKey;
73
73
  this.table = table;
package/dist/errors.js CHANGED
@@ -51,7 +51,7 @@ var InvalidColumnError = class extends TrileanSqlError {
51
51
  referenceKey;
52
52
  column;
53
53
  constructor(referenceKey, column, reason) {
54
- super(`columnFor(${JSON.stringify(referenceKey)}) returned ${JSON.stringify(column)}, which is not a usable column identifier: ${reason}`);
54
+ super(`columnFor(${JSON.stringify(referenceKey)}) returned a name that is not a usable column identifier: ${reason}`);
55
55
  this.name = "InvalidColumnError";
56
56
  this.referenceKey = referenceKey;
57
57
  this.column = column;
@@ -66,7 +66,7 @@ var InvalidCollectionTableError = class extends TrileanSqlError {
66
66
  collectionKey;
67
67
  table;
68
68
  constructor(collectionKey, table, reason) {
69
- super(`collectionFor(${JSON.stringify(collectionKey)}) returned ${JSON.stringify(table)}, which is not a usable table identifier: ${reason}`);
69
+ super(`collectionFor(${JSON.stringify(collectionKey)}) returned a name that is not a usable table identifier: ${reason}`);
70
70
  this.name = "InvalidCollectionTableError";
71
71
  this.collectionKey = collectionKey;
72
72
  this.table = table;