trilean-sql 2.2.42 → 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
 
@@ -246,7 +248,7 @@ const { sql, params } = compilePredicateNode(
246
248
  },
247
249
  { dialect: "sqlite", columnFor },
248
250
  );
249
- // 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 ?)
250
252
  // params: ["ENA-[0-9]*"]
251
253
  ```
252
254
 
package/dist/compile.cjs CHANGED
@@ -1,6 +1,6 @@
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
5
  const require_options = require("./options-DOE1_Cwr.cjs");
6
6
  let trilean_regex = require("trilean-regex");
@@ -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: {
@@ -154,7 +154,7 @@ function compileExpression(node, context, asInstant = false) {
154
154
  case "reference": {
155
155
  const resolved = bindingOf(context, node);
156
156
  if (resolved === void 0) return refuse(node.kind, "expression");
157
- const column = quoteColumn(resolved.referenceKey, resolved.binding);
157
+ const column = quoteColumn(resolved.referenceKey, resolved.binding, context.options.dialect);
158
158
  return asInstant ? context.dialect.instantColumn(column) : column;
159
159
  }
160
160
  case "instantLiteral": return placeholder(context, asInstant ? context.dialect.instantParameter(node.value) : node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
@@ -189,7 +189,8 @@ function compilePredicate(node, context) {
189
189
  return `(${left} ${COMPARISON_SQL[node.op]} ${right})`;
190
190
  }
191
191
  case "textCompare": {
192
- 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;
193
194
  const right = node.op === "portableMatches" || node.op === "portableNotMatches" ? compilePortablePattern(node, context) : compileExpression(node.right, context);
194
195
  return `(${left} ${context.textComparison[node.op]} ${right})`;
195
196
  }
@@ -223,7 +224,8 @@ function compilePredicate(node, context) {
223
224
  * Every caller-supplied literal becomes a bind parameter. Nothing but structure, operators, and quoted column identifiers is ever written into the returned `sql`.
224
225
  * @throws `UnknownDialectError` if `options.dialect` names a dialect this version does not implement.
225
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.
226
- * @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.
227
229
  */
228
230
  function compilePredicateNode(node, options) {
229
231
  require_options.assertImplementedDialect(options.dialect);
@@ -262,7 +264,14 @@ function compilePredicateNode(node, options) {
262
264
  } }
263
265
  };
264
266
  const unpushable = require_guard.findUnpushableNodeKind(node, memoised);
265
- 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
+ }
266
275
  const dialect = require_options.DIALECT_CONFIG[options.dialect];
267
276
  const context = {
268
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,5 +1,5 @@
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
4
  import { r as assertImplementedDialect, t as DIALECT_CONFIG } from "./options-c1nHisgX.js";
5
5
  import { parseRegex } from "trilean-regex";
@@ -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: {
@@ -153,7 +153,7 @@ function compileExpression(node, context, asInstant = false) {
153
153
  case "reference": {
154
154
  const resolved = bindingOf(context, node);
155
155
  if (resolved === void 0) return refuse(node.kind, "expression");
156
- const column = quoteColumn(resolved.referenceKey, resolved.binding);
156
+ const column = quoteColumn(resolved.referenceKey, resolved.binding, context.options.dialect);
157
157
  return asInstant ? context.dialect.instantColumn(column) : column;
158
158
  }
159
159
  case "instantLiteral": return placeholder(context, asInstant ? context.dialect.instantParameter(node.value) : node.value, PARAM_TYPE_OF_LITERAL[node.kind]);
@@ -188,7 +188,8 @@ function compilePredicate(node, context) {
188
188
  return `(${left} ${COMPARISON_SQL[node.op]} ${right})`;
189
189
  }
190
190
  case "textCompare": {
191
- 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;
192
193
  const right = node.op === "portableMatches" || node.op === "portableNotMatches" ? compilePortablePattern(node, context) : compileExpression(node.right, context);
193
194
  return `(${left} ${context.textComparison[node.op]} ${right})`;
194
195
  }
@@ -222,7 +223,8 @@ function compilePredicate(node, context) {
222
223
  * Every caller-supplied literal becomes a bind parameter. Nothing but structure, operators, and quoted column identifiers is ever written into the returned `sql`.
223
224
  * @throws `UnknownDialectError` if `options.dialect` names a dialect this version does not implement.
224
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.
225
- * @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.
226
228
  */
227
229
  function compilePredicateNode(node, options) {
228
230
  assertImplementedDialect(options.dialect);
@@ -261,7 +263,14 @@ function compilePredicateNode(node, options) {
261
263
  } }
262
264
  };
263
265
  const unpushable = findUnpushableNodeKind(node, memoised);
264
- 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
+ }
265
274
  const dialect = DIALECT_CONFIG[options.dialect];
266
275
  const context = {
267
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;