trilean-sql 2.2.42 → 3.0.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.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.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;
@@ -1,7 +1,48 @@
1
- Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_options = require("./options-DOE1_Cwr.cjs");
3
- const require_portable_pattern = require("./portable-pattern.cjs");
4
- let trilean_regex = require("trilean-regex");
1
+ import { r as assertImplementedDialect } from "./options-c1nHisgX.js";
2
+ import { renderPostgresPattern, renderSqliteGlobPattern } from "./portable-pattern.js";
3
+ import { parseRegex } from "trilean-regex";
4
+ // src/internal/identifier.ts
5
+ /**
6
+ * What a dialect can carry in a quoted identifier and in a bound text value, in one place: the guard decides with it before compilation and the compiler's own drift checks use it, so the two cannot disagree.
7
+ *
8
+ * The reasons describe the character or the count and never repeat the input, so an error built from one cannot carry a caller's value into a log.
9
+ */
10
+ const NUL = "\0";
11
+ /** The most dot-separated segments a column may have: `schema.table.column`. SQLite's expression syntax is `schema-name.table-name.column-name` (https://www.sqlite.org/lang_expr.html). PostgreSQL's page on schemas says that "the even more general syntax database.schema.table can be used too, but at present this is just for pro forma compliance with the SQL standard. If you write a database name, it must be the same as the database you are connected to" (https://www.postgresql.org/docs/current/ddl-schemas.html). The compiler does not know the database the connection is on, so a leading database segment is refused as a choice, and the caller omits it. */
12
+ const MAX_COLUMN_SEGMENTS = {
13
+ postgres: 3,
14
+ sqlite: 3
15
+ };
16
+ /** The most dot-separated segments a table may have: `schema.table`. SQLite's `FROM` takes `schema-name.table-name` (https://www.sqlite.org/syntax/table-or-subquery.html), and for PostgreSQL a leading database segment is refused for the reason given at {@link MAX_COLUMN_SEGMENTS}. */
17
+ const MAX_TABLE_SEGMENTS = {
18
+ postgres: 2,
19
+ sqlite: 2
20
+ };
21
+ /**
22
+ * Why a column or table name cannot be rendered as a quoted identifier for `dialect`, or `undefined` when it can.
23
+ *
24
+ * Refused: an empty name or segment; the NUL character, which neither engine accepts in a quoted identifier (PostgreSQL: "Quoted identifiers can contain any character, except the character with code zero", https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS) and which ends the statement text SQLite is given ("zSql is read up to the first zero terminator", https://www.sqlite.org/c3ref/prepare.html); an unpaired UTF-16 surrogate, which has no UTF-8 form, the encoding both engines read the statement in; and more segments than the dialect accepts. Every other character, a quote included, is carried by doubling the quote.
25
+ */
26
+ function identifierProblem(role, name, dialect) {
27
+ if (name.length === 0) return "the name is empty";
28
+ if (name.includes(NUL)) return "the name contains a NUL character, which a quoted identifier cannot carry";
29
+ if (!name.isWellFormed()) return "the name contains an unpaired surrogate, which has no UTF-8 form";
30
+ const segments = name.split(".");
31
+ if (segments.some((segment) => segment.length === 0)) return "a dot-separated segment is empty";
32
+ const most = role === "column" ? MAX_COLUMN_SEGMENTS[dialect] : MAX_TABLE_SEGMENTS[dialect];
33
+ if (segments.length > most) return dialect === "postgres" ? `the name has ${String(segments.length)} dot-separated segments and at most ${String(most)} are accepted for a ${role}: PostgreSQL takes a leading database name only when it is the database the connection is on, which the compiler cannot know` : `the name has ${String(segments.length)} dot-separated segments and SQLite accepts at most ${String(most)} for a ${role}`;
34
+ }
35
+ /**
36
+ * Why a text, pattern or instant value cannot be bound for `dialect`, or `undefined` when it can.
37
+ *
38
+ * An unpaired surrogate has no UTF-8 form, and a driver silently replaces it with U+FFFD, so the engine would compare a value other than the one the evaluator saw. The NUL character is carried by SQLite as text but not by PostgreSQL, which rejects it with an invalid byte sequence error (a string constant "cannot contain the character with code zero", https://www.postgresql.org/docs/current/sql-syntax-lexical.html). The pattern of `portableMatches` and `portableNotMatches` is compiled to SQLite's `GLOB`, which reads it only up to its first NUL, so a NUL there is refused for SQLite as well; the pattern of `matches` and `notMatches` is a `REGEXP` argument and a registered function receives it whole.
39
+ */
40
+ function valueProblem(value, dialect, role) {
41
+ if (!value.isWellFormed()) return "the value contains an unpaired surrogate, which has no UTF-8 form and would be replaced before the engine compared it";
42
+ if (!value.includes(NUL)) return void 0;
43
+ if (dialect === "postgres") return "PostgreSQL cannot carry the NUL character in a text value and rejects the statement with an invalid byte sequence error";
44
+ return role === "glob-pattern" ? "SQLite's GLOB reads a pattern only up to its first NUL character, so the pattern would match as a shorter one" : void 0;
45
+ }
5
46
  // src/guard.ts
6
47
  const STATIC_KIND_OF_PARAM_TYPE = {
7
48
  text: "text",
@@ -63,6 +104,17 @@ function resolveCollectionForGuard(kind, collection, path, options) {
63
104
  reason: "no 'collectionFor' option is set: describe how this collection maps onto a correlated table ({ table, join, columnFor }) to compile this node, or it falls back to in-process evaluation"
64
105
  };
65
106
  const binding = options.collectionFor(collection);
107
+ const tableProblem = identifierProblem("table", binding.table, options.dialect);
108
+ if (tableProblem !== void 0) return {
109
+ kind,
110
+ path,
111
+ reason: `the table mapped for this collection cannot be used: ${tableProblem}`,
112
+ identifier: {
113
+ role: "table",
114
+ key: collection,
115
+ problem: tableProblem
116
+ }
117
+ };
66
118
  return { itemOptions: {
67
119
  ...options,
68
120
  columnFor: binding.columnFor
@@ -82,6 +134,19 @@ function findUnpushableExpression(node, path, divergence, options) {
82
134
  path,
83
135
  reason: "a reference declaring a unit asserts that the resolved value carries that same unit, and a SQL column carries no unit for that assertion to be checked against"
84
136
  };
137
+ if (options !== void 0) {
138
+ const columnProblem = identifierProblem("column", options.columnFor(node.key).column, options.dialect);
139
+ if (columnProblem !== void 0) return {
140
+ kind: node.kind,
141
+ path,
142
+ reason: `the column mapped for this reference cannot be used: ${columnProblem}`,
143
+ identifier: {
144
+ role: "column",
145
+ key: node.key,
146
+ problem: columnProblem
147
+ }
148
+ };
149
+ }
85
150
  return;
86
151
  case "numberLiteral":
87
152
  if (node.unit !== void 0) return {
@@ -96,8 +161,15 @@ function findUnpushableExpression(node, path, divergence, options) {
96
161
  };
97
162
  return;
98
163
  case "textLiteral":
99
- case "booleanLiteral":
100
- case "instantLiteral": return;
164
+ case "instantLiteral": {
165
+ const problem = valueProblem(node.value, options?.dialect ?? "postgres", "text");
166
+ return problem === void 0 ? void 0 : {
167
+ kind: node.kind,
168
+ path,
169
+ reason: problem
170
+ };
171
+ }
172
+ case "booleanLiteral": return;
101
173
  case "durationLiteral": return {
102
174
  kind: node.kind,
103
175
  path,
@@ -260,6 +332,14 @@ function findUnpushablePredicate(node, path, options, divergence) {
260
332
  reason: `'textCompare' requires text operands in trilean, and the operand at ${operand.path} is a '${staticKind}' value`
261
333
  };
262
334
  }
335
+ if (node.right.kind === "textLiteral" && (node.op === "portableMatches" || node.op === "portableNotMatches")) {
336
+ const patternProblem = valueProblem(node.right.value, options?.dialect ?? "postgres", "glob-pattern");
337
+ if (patternProblem !== void 0) return {
338
+ kind: node.kind,
339
+ path: `${path}.right`,
340
+ reason: patternProblem
341
+ };
342
+ }
263
343
  const dialect = options?.dialect ?? "postgres";
264
344
  if (dialect === "postgres" && (node.op === "matches" || node.op === "notMatches") && options?.postgresRegexpPushdown !== true) return {
265
345
  kind: node.kind,
@@ -273,9 +353,9 @@ function findUnpushablePredicate(node, path, options, divergence) {
273
353
  reason: "a 'portableMatches'/'portableNotMatches' pattern must be a literal, known at compile time -- translating it into this dialect's own pattern syntax happens once, at compile time, not per row"
274
354
  };
275
355
  try {
276
- const ast = (0, trilean_regex.parseRegex)(node.right.value);
277
- if (dialect === "postgres") require_portable_pattern.renderPostgresPattern(ast);
278
- else require_portable_pattern.renderSqliteGlobPattern(ast);
356
+ const ast = parseRegex(node.right.value);
357
+ if (dialect === "postgres") renderPostgresPattern(ast);
358
+ else renderSqliteGlobPattern(ast);
279
359
  } catch (error) {
280
360
  return {
281
361
  kind: node.kind,
@@ -332,12 +412,12 @@ function findUnpushablePredicate(node, path, options, divergence) {
332
412
  *
333
413
  * Passing `options` widens the check: without them the walk is purely structural, and with them it also applies the operand-kind rules that depend on each mapped column's declared `paramType` (and therefore calls `columnFor`).
334
414
  *
335
- * Which nodes are refused does not depend on the dialect -- every divergence refused here is real in both -- so a structural walk given no `options` refuses exactly what a walk given them would. What `options` also settles is which engine each `reason` describes; with none to read a dialect from, the reasons describe PostgreSQL, the dialect these refusals were first derived against.
415
+ * Which nodes are refused does not depend on the dialect -- every divergence refused here is real in both -- except what a dialect cannot carry (see `valueProblem` and `identifierProblem`), which is decided for the dialect `options` names, and for PostgreSQL when there are none. A structural walk given no `options` otherwise refuses exactly what a walk given them would. What `options` also settles is which engine each `reason` describes; with none to read a dialect from, the reasons describe PostgreSQL, the dialect these refusals were first derived against.
336
416
  * @throws `UnknownDialectError` if `options` names a dialect this version does not implement. Reporting a tree as pushable is a promise that `compilePredicateNode` will compile it, and under a dialect that does not exist it cannot -- so this is refused here rather than left to surface from the compiler, which is the one caller this function's answer is for.
337
417
  */
338
418
  function findUnpushableNodeKind(node, options) {
339
419
  const dialect = options?.dialect ?? "postgres";
340
- require_options.assertImplementedDialect(dialect);
420
+ assertImplementedDialect(dialect);
341
421
  return findUnpushablePredicate(node, "$", options, DIALECT_DIVERGENCE[dialect]);
342
422
  }
343
- exports.findUnpushableNodeKind = findUnpushableNodeKind;
423
+ export { identifierProblem as n, findUnpushableNodeKind as t };
package/dist/guard.d.ts CHANGED
@@ -6,6 +6,12 @@ export interface UnpushableNode {
6
6
  /** A dotted path from the root of the tree, e.g. `$.operands[1].left`. */
7
7
  path: string;
8
8
  reason: string;
9
+ /** Set when the refusal is a mapped name the dialect cannot render as an identifier: which mapping returned it and under which key. `compilePredicateNode` reports it as `InvalidColumnError` or `InvalidCollectionTableError`. */
10
+ identifier?: {
11
+ role: "column" | "table";
12
+ key: string;
13
+ problem: string;
14
+ };
9
15
  }
10
16
  /**
11
17
  * Walks the tree against the allow-list of what this compiler translates, and reports the first node it will not.
@@ -16,7 +22,7 @@ export interface UnpushableNode {
16
22
  *
17
23
  * Passing `options` widens the check: without them the walk is purely structural, and with them it also applies the operand-kind rules that depend on each mapped column's declared `paramType` (and therefore calls `columnFor`).
18
24
  *
19
- * Which nodes are refused does not depend on the dialect -- every divergence refused here is real in both -- so a structural walk given no `options` refuses exactly what a walk given them would. What `options` also settles is which engine each `reason` describes; with none to read a dialect from, the reasons describe PostgreSQL, the dialect these refusals were first derived against.
25
+ * Which nodes are refused does not depend on the dialect -- every divergence refused here is real in both -- except what a dialect cannot carry (see `valueProblem` and `identifierProblem`), which is decided for the dialect `options` names, and for PostgreSQL when there are none. A structural walk given no `options` otherwise refuses exactly what a walk given them would. What `options` also settles is which engine each `reason` describes; with none to read a dialect from, the reasons describe PostgreSQL, the dialect these refusals were first derived against.
20
26
  * @throws `UnknownDialectError` if `options` names a dialect this version does not implement. Reporting a tree as pushable is a promise that `compilePredicateNode` will compile it, and under a dialect that does not exist it cannot -- so this is refused here rather than left to surface from the compiler, which is the one caller this function's answer is for.
21
27
  */
22
28
  export declare function findUnpushableNodeKind(node: PredicateNode, options?: SqlCompileOptions): UnpushableNode | undefined;