trilean-sql 3.0.0 → 3.0.2
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 +1 -1
- package/dist/compile.js +3 -6
- package/dist/{guard-D4CIUc5h.js → guard-CZ7Cvyh2.js} +10 -7
- package/dist/guard.d.ts +2 -1
- package/dist/guard.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +3 -2
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. 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:
|
|
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, name, problem }`: `role` is `"column"` or `"table"`, `key` the reference or collection key the mapping was asked about, `name` the name the mapping returned (for a column inside a collection, that collection's own mapping, not the outer one), 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);
|
package/dist/compile.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { InvalidCollectionTableError, InvalidColumnError, UnsupportedNodeError } from "./errors.js";
|
|
2
|
-
import { n as identifierProblem, t as findUnpushableNodeKind } from "./guard-
|
|
2
|
+
import { n as identifierProblem, t as findUnpushableNodeKind } from "./guard-CZ7Cvyh2.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";
|
|
@@ -264,11 +264,8 @@ function compilePredicateNode(node, options) {
|
|
|
264
264
|
};
|
|
265
265
|
const unpushable = findUnpushableNodeKind(node, memoised);
|
|
266
266
|
if (unpushable !== void 0) {
|
|
267
|
-
if (unpushable.identifier?.role === "column") throw new InvalidColumnError(unpushable.identifier.key,
|
|
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
|
-
}
|
|
267
|
+
if (unpushable.identifier?.role === "column") throw new InvalidColumnError(unpushable.identifier.key, unpushable.identifier.name, unpushable.identifier.problem);
|
|
268
|
+
if (unpushable.identifier?.role === "table") throw new InvalidCollectionTableError(unpushable.identifier.key, unpushable.identifier.name, unpushable.identifier.problem);
|
|
272
269
|
throw new UnsupportedNodeError(unpushable);
|
|
273
270
|
}
|
|
274
271
|
const dialect = DIALECT_CONFIG[options.dialect];
|
|
@@ -74,7 +74,7 @@ const DIALECT_DIVERGENCE = {
|
|
|
74
74
|
},
|
|
75
75
|
sqlite: {
|
|
76
76
|
complexNumbers: "SQLite has no complex number type",
|
|
77
|
-
nan: "NaN is equal to nothing in trilean, not even itself, whereas SQLite has no NaN at all and a driver binding one substitutes SQL NULL
|
|
77
|
+
nan: "NaN is equal to nothing in trilean, not even itself, whereas SQLite has no NaN at all and a driver binding one substitutes SQL NULL, so 'NaN = NaN' is indeterminate there rather than definitely false, and its negation matches every row instead of none",
|
|
78
78
|
crossKindCoercion: "SQLite's type affinity may coerce one to the other and answer definitely",
|
|
79
79
|
textOrdering: (operandPath) => `SQLite would answer definitely for the text operand at ${operandPath}, comparing it under the text affinity it applies to the other side ('9' > 5 is true there, while '10' > 5 is not)`,
|
|
80
80
|
booleanOrdering: "SQLite stores booleans as the integers 0 and 1 and orders them as integers"
|
|
@@ -112,6 +112,7 @@ function resolveCollectionForGuard(kind, collection, path, options) {
|
|
|
112
112
|
identifier: {
|
|
113
113
|
role: "table",
|
|
114
114
|
key: collection,
|
|
115
|
+
name: binding.table,
|
|
115
116
|
problem: tableProblem
|
|
116
117
|
}
|
|
117
118
|
};
|
|
@@ -135,7 +136,8 @@ function findUnpushableExpression(node, path, divergence, options) {
|
|
|
135
136
|
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"
|
|
136
137
|
};
|
|
137
138
|
if (options !== void 0) {
|
|
138
|
-
const
|
|
139
|
+
const column = options.columnFor(node.key).column;
|
|
140
|
+
const columnProblem = identifierProblem("column", column, options.dialect);
|
|
139
141
|
if (columnProblem !== void 0) return {
|
|
140
142
|
kind: node.kind,
|
|
141
143
|
path,
|
|
@@ -143,6 +145,7 @@ function findUnpushableExpression(node, path, divergence, options) {
|
|
|
143
145
|
identifier: {
|
|
144
146
|
role: "column",
|
|
145
147
|
key: node.key,
|
|
148
|
+
name: column,
|
|
146
149
|
problem: columnProblem
|
|
147
150
|
}
|
|
148
151
|
};
|
|
@@ -221,12 +224,12 @@ function findUnpushableExpression(node, path, divergence, options) {
|
|
|
221
224
|
if (itemKind === "text") return {
|
|
222
225
|
kind: node.kind,
|
|
223
226
|
path: itemPath,
|
|
224
|
-
reason: `a '${node.combiner.mode}' fold orders participating items by comparing them, and trilean never orders text values ('compare' returns wrong-type for text; use 'textCompare')
|
|
227
|
+
reason: `a '${node.combiner.mode}' fold orders participating items by comparing them, and trilean never orders text values ('compare' returns wrong-type for text; use 'textCompare'); but ${divergence.textOrdering(itemPath)}`
|
|
225
228
|
};
|
|
226
229
|
if (itemKind === "boolean") return {
|
|
227
230
|
kind: node.kind,
|
|
228
231
|
path: itemPath,
|
|
229
|
-
reason: `a '${node.combiner.mode}' fold orders participating items by comparing them, and booleans have no ordering in trilean
|
|
232
|
+
reason: `a '${node.combiner.mode}' fold orders participating items by comparing them, and booleans have no ordering in trilean; whereas ${divergence.booleanOrdering}`
|
|
230
233
|
};
|
|
231
234
|
return;
|
|
232
235
|
}
|
|
@@ -299,7 +302,7 @@ function findUnpushablePredicate(node, path, options, divergence) {
|
|
|
299
302
|
if (staticKind === "text") return {
|
|
300
303
|
kind: node.kind,
|
|
301
304
|
path,
|
|
302
|
-
reason: `'compare' never compares text in trilean
|
|
305
|
+
reason: `'compare' never compares text in trilean: it returns wrong-type and directs the caller to 'textCompare'; but ${divergence.textOrdering(operand.path)}`
|
|
303
306
|
};
|
|
304
307
|
if (staticKind === "boolean" && ORDERING_OPERATORS.has(node.op)) return {
|
|
305
308
|
kind: node.kind,
|
|
@@ -344,13 +347,13 @@ function findUnpushablePredicate(node, path, options, divergence) {
|
|
|
344
347
|
if (dialect === "postgres" && (node.op === "matches" || node.op === "notMatches") && options?.postgresRegexpPushdown !== true) return {
|
|
345
348
|
kind: node.kind,
|
|
346
349
|
path,
|
|
347
|
-
reason: `'${node.op}' matches trilean's own ECMAScript 'RegExp' against the pattern, whereas PostgreSQL's '~'/'!~' would match it under PostgreSQL's own regular-expression dialect (POSIX ARE)
|
|
350
|
+
reason: `'${node.op}' matches trilean's own ECMAScript 'RegExp' against the pattern, whereas PostgreSQL's '~'/'!~' would match it under PostgreSQL's own regular-expression dialect (POSIX ARE), a different language that can silently answer a different set of rows for the same pattern and data (for example, PostgreSQL's '.' matches a newline by default where ECMAScript's does not, and PostgreSQL's '\\w' follows the database's locale where ECMAScript's is ASCII-only), so this is refused unless 'postgresRegexpPushdown' is explicitly set 'true'`
|
|
348
351
|
};
|
|
349
352
|
if (node.op === "portableMatches" || node.op === "portableNotMatches") {
|
|
350
353
|
if (node.right.kind !== "textLiteral") return {
|
|
351
354
|
kind: node.kind,
|
|
352
355
|
path,
|
|
353
|
-
reason: "a 'portableMatches'/'portableNotMatches' pattern must be a literal, known at compile time
|
|
356
|
+
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"
|
|
354
357
|
};
|
|
355
358
|
try {
|
|
356
359
|
const ast = parseRegex(node.right.value);
|
package/dist/guard.d.ts
CHANGED
|
@@ -6,10 +6,11 @@ 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
|
|
9
|
+
/** Set when the refusal is a mapped name the dialect cannot render as an identifier: which mapping returned it, under which key, and the name it returned: the name of the mapping that was refused, which for a column inside a collection is that collection's own column and not the outer mapping's. `compilePredicateNode` reports it as `InvalidColumnError` or `InvalidCollectionTableError`. */
|
|
10
10
|
identifier?: {
|
|
11
11
|
role: "column" | "table";
|
|
12
12
|
key: string;
|
|
13
|
+
name: string;
|
|
13
14
|
problem: string;
|
|
14
15
|
};
|
|
15
16
|
}
|
package/dist/guard.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { t as findUnpushableNodeKind } from "./guard-
|
|
1
|
+
export { t as findUnpushableNodeKind } from "./guard-CZ7Cvyh2.js";
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { t as findUnpushableNodeKind } from "./guard-
|
|
1
|
+
import { t as findUnpushableNodeKind } from "./guard-CZ7Cvyh2.js";
|
|
2
2
|
import { compilePredicateNode } from "./compile.js";
|
|
3
3
|
import { InvalidCollectionTableError, InvalidColumnError, TrileanSqlError, UnknownDialectError, UnsupportedNodeError } from "./errors.js";
|
|
4
4
|
export { InvalidCollectionTableError, InvalidColumnError, TrileanSqlError, UnknownDialectError, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
package/package.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "trilean-sql",
|
|
3
3
|
"description": "Compiles a trilean predicate tree into a parameterised SQL WHERE fragment, pushing three-valued logic down onto the database's own NULL propagation instead of evaluating it in process.",
|
|
4
|
-
"version": "3.0.
|
|
4
|
+
"version": "3.0.2",
|
|
5
5
|
"bugs": {
|
|
6
6
|
"url": "https://github.com/ExaDev/trilean/issues"
|
|
7
7
|
},
|
|
8
8
|
"dependencies": {
|
|
9
|
-
"trilean": "2.0.
|
|
9
|
+
"trilean": "2.0.1",
|
|
10
10
|
"trilean-regex": "2.0.0"
|
|
11
11
|
},
|
|
12
12
|
"devDependencies": {
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
"@types/node": "^26.6.5",
|
|
19
19
|
"@types/pg": "^8.15.6",
|
|
20
20
|
"@vitest/coverage-v8": "^5.0.4",
|
|
21
|
+
"ajv": "8.20.0",
|
|
21
22
|
"better-sqlite3": "^13.0.3",
|
|
22
23
|
"eslint": "^10.14.0",
|
|
23
24
|
"eslint-config-prettier": "^10.1.8",
|