trilean-sql 1.0.1 → 1.2.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 +65 -24
- package/dist/compile.cjs +30 -17
- package/dist/compile.d.cts +2 -1
- package/dist/compile.d.ts +2 -1
- package/dist/compile.js +30 -17
- package/dist/errors.cjs +20 -2
- package/dist/errors.d.cts +15 -3
- package/dist/errors.d.ts +15 -3
- package/dist/errors.js +20 -3
- package/dist/guard.cjs +49 -21
- package/dist/guard.d.cts +4 -0
- package/dist/guard.d.ts +4 -0
- package/dist/guard.js +49 -21
- package/dist/index.cjs +1 -0
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/options.cjs +27 -0
- package/dist/options.d.cts +38 -6
- package/dist/options.d.ts +38 -6
- package/dist/options.js +26 -1
- package/package.json +4 -1
package/dist/guard.cjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
+
const require_options = require("./options.cjs");
|
|
2
3
|
//#region src/guard.ts
|
|
3
4
|
const STATIC_KIND_OF_PARAM_TYPE = {
|
|
4
5
|
text: "text",
|
|
@@ -6,7 +7,7 @@ const STATIC_KIND_OF_PARAM_TYPE = {
|
|
|
6
7
|
boolean: "boolean",
|
|
7
8
|
timestamp: "instant"
|
|
8
9
|
};
|
|
9
|
-
/** The comparison operators that impose an ordering, as opposed to testing equality. trilean refuses these on booleans -- `true > false` is not a fact about the domain -- while
|
|
10
|
+
/** The comparison operators that impose an ordering, as opposed to testing equality. trilean refuses these on booleans -- `true > false` is not a fact about the domain -- while both dialects answer them, so a boolean operand under one of these is a real divergence rather than a stylistic one. */
|
|
10
11
|
const ORDERING_OPERATORS = /* @__PURE__ */ new Set([
|
|
11
12
|
"gt",
|
|
12
13
|
"gte",
|
|
@@ -20,13 +21,29 @@ const STATIC_KIND_OF_LITERAL = {
|
|
|
20
21
|
booleanLiteral: "boolean",
|
|
21
22
|
instantLiteral: "instant"
|
|
22
23
|
};
|
|
24
|
+
const DIALECT_DIVERGENCE = {
|
|
25
|
+
postgres: {
|
|
26
|
+
complexNumbers: "PostgreSQL has no complex number type",
|
|
27
|
+
nan: "NaN is equal to nothing in trilean, not even itself, whereas PostgreSQL defines NaN as equal to itself and greater than every other double",
|
|
28
|
+
crossKindCoercion: "PostgreSQL may coerce one to the other and answer definitely",
|
|
29
|
+
textOrdering: (operandPath) => `PostgreSQL would order the text operand at ${operandPath} collation-wise and answer definitely`,
|
|
30
|
+
booleanOrdering: "PostgreSQL orders false before true"
|
|
31
|
+
},
|
|
32
|
+
sqlite: {
|
|
33
|
+
complexNumbers: "SQLite has no complex number type",
|
|
34
|
+
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",
|
|
35
|
+
crossKindCoercion: "SQLite's type affinity may coerce one to the other and answer definitely",
|
|
36
|
+
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)`,
|
|
37
|
+
booleanOrdering: "SQLite stores booleans as the integers 0 and 1 and orders them as integers"
|
|
38
|
+
}
|
|
39
|
+
};
|
|
23
40
|
function staticValueKindOf(node, options) {
|
|
24
41
|
if (node.kind !== "reference") return STATIC_KIND_OF_LITERAL[node.kind];
|
|
25
42
|
if (options === void 0 || typeof node.key !== "string") return void 0;
|
|
26
43
|
const paramType = options.columnFor(node.key).paramType;
|
|
27
44
|
return paramType === void 0 ? void 0 : STATIC_KIND_OF_PARAM_TYPE[paramType];
|
|
28
45
|
}
|
|
29
|
-
function findUnpushableExpression(node, path) {
|
|
46
|
+
function findUnpushableExpression(node, path, divergence) {
|
|
30
47
|
const unrecognisedKind = node.kind;
|
|
31
48
|
switch (node.kind) {
|
|
32
49
|
case "reference":
|
|
@@ -50,7 +67,7 @@ function findUnpushableExpression(node, path) {
|
|
|
50
67
|
if (Number.isNaN(node.value)) return {
|
|
51
68
|
kind: node.kind,
|
|
52
69
|
path,
|
|
53
|
-
reason:
|
|
70
|
+
reason: divergence.nan
|
|
54
71
|
};
|
|
55
72
|
return;
|
|
56
73
|
case "textLiteral":
|
|
@@ -64,7 +81,7 @@ function findUnpushableExpression(node, path) {
|
|
|
64
81
|
case "complexLiteral": return {
|
|
65
82
|
kind: node.kind,
|
|
66
83
|
path,
|
|
67
|
-
reason:
|
|
84
|
+
reason: divergence.complexNumbers
|
|
68
85
|
};
|
|
69
86
|
case "arithmetic":
|
|
70
87
|
case "negate": return {
|
|
@@ -114,8 +131,8 @@ function findUnpushableExpression(node, path) {
|
|
|
114
131
|
};
|
|
115
132
|
}
|
|
116
133
|
}
|
|
117
|
-
/** Checks the operands of a comparison-shaped predicate for a kind pairing trilean and
|
|
118
|
-
function findKindDivergence(kind, path, operands, options) {
|
|
134
|
+
/** Checks the operands of a comparison-shaped predicate for a kind pairing trilean and the target engine would answer differently. Returns the objection against `path` itself, since the divergence is a property of the pairing rather than of either operand alone. */
|
|
135
|
+
function findKindDivergence(kind, path, operands, options, divergence) {
|
|
119
136
|
const known = operands.map((operand) => ({
|
|
120
137
|
path: operand.path,
|
|
121
138
|
staticKind: staticValueKindOf(operand.node, options)
|
|
@@ -126,19 +143,19 @@ function findKindDivergence(kind, path, operands, options) {
|
|
|
126
143
|
if (mismatched !== void 0) return {
|
|
127
144
|
kind,
|
|
128
145
|
path,
|
|
129
|
-
reason: `trilean treats a comparison between a '${first.staticKind}' value (${first.path}) and a '${mismatched.staticKind}' value (${mismatched.path}) as wrong-type, whereas
|
|
146
|
+
reason: `trilean treats a comparison between a '${first.staticKind}' value (${first.path}) and a '${mismatched.staticKind}' value (${mismatched.path}) as wrong-type, whereas ${divergence.crossKindCoercion}`
|
|
130
147
|
};
|
|
131
148
|
}
|
|
132
|
-
function findUnpushablePredicate(node, path, options) {
|
|
149
|
+
function findUnpushablePredicate(node, path, options, divergence) {
|
|
133
150
|
const unrecognisedKind = node.kind;
|
|
134
151
|
switch (node.kind) {
|
|
135
|
-
case "not": return findUnpushablePredicate(node.operand, `${path}.operand`, options);
|
|
152
|
+
case "not": return findUnpushablePredicate(node.operand, `${path}.operand`, options, divergence);
|
|
136
153
|
case "and":
|
|
137
|
-
case "or": return findUnpushablePredicate(node.left, `${path}.left`, options) ?? findUnpushablePredicate(node.right, `${path}.right`, options);
|
|
154
|
+
case "or": return findUnpushablePredicate(node.left, `${path}.left`, options, divergence) ?? findUnpushablePredicate(node.right, `${path}.right`, options, divergence);
|
|
138
155
|
case "allOf":
|
|
139
156
|
case "anyOf":
|
|
140
157
|
for (const [index, operand] of node.operands.entries()) {
|
|
141
|
-
const unpushable = findUnpushablePredicate(operand, `${path}.operands[${String(index)}]`, options);
|
|
158
|
+
const unpushable = findUnpushablePredicate(operand, `${path}.operands[${String(index)}]`, options, divergence);
|
|
142
159
|
if (unpushable !== void 0) return unpushable;
|
|
143
160
|
}
|
|
144
161
|
return;
|
|
@@ -151,27 +168,32 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
151
168
|
path: `${path}.right`
|
|
152
169
|
}];
|
|
153
170
|
for (const operand of operands) {
|
|
154
|
-
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
171
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path, divergence);
|
|
155
172
|
if (unpushable !== void 0) return unpushable;
|
|
156
173
|
}
|
|
157
|
-
const
|
|
158
|
-
if (
|
|
174
|
+
const mismatch = findKindDivergence(node.kind, path, operands, options, divergence);
|
|
175
|
+
if (mismatch !== void 0) return mismatch;
|
|
159
176
|
for (const operand of operands) {
|
|
160
177
|
const staticKind = staticValueKindOf(operand.node, options);
|
|
161
178
|
if (staticKind === "text") return {
|
|
162
179
|
kind: node.kind,
|
|
163
180
|
path,
|
|
164
|
-
reason: `'compare' never compares text in trilean -- it returns wrong-type and directs the caller to 'textCompare' -- but
|
|
181
|
+
reason: `'compare' never compares text in trilean -- it returns wrong-type and directs the caller to 'textCompare' -- but ${divergence.textOrdering(operand.path)}`
|
|
165
182
|
};
|
|
166
183
|
if (staticKind === "boolean" && ORDERING_OPERATORS.has(node.op)) return {
|
|
167
184
|
kind: node.kind,
|
|
168
185
|
path,
|
|
169
|
-
reason: `booleans have no ordering in trilean, so '${node.op}' against the boolean operand at ${operand.path} is wrong-type there, whereas
|
|
186
|
+
reason: `booleans have no ordering in trilean, so '${node.op}' against the boolean operand at ${operand.path} is wrong-type there, whereas ${divergence.booleanOrdering}`
|
|
170
187
|
};
|
|
171
188
|
}
|
|
172
189
|
return;
|
|
173
190
|
}
|
|
174
191
|
case "textCompare": {
|
|
192
|
+
if ((node.op === "matches" || node.op === "notMatches") && options?.dialect === "sqlite" && options.sqliteRegexpAvailable === false) return {
|
|
193
|
+
kind: node.kind,
|
|
194
|
+
path,
|
|
195
|
+
reason: `options.sqliteRegexpAvailable is false: the caller has stated no regexp(pattern, value) function can be registered on this SQLite target, so '${node.op}' would compile to SQL that fails at query execution time with "no such function: REGEXP" instead of at compile time`
|
|
196
|
+
};
|
|
175
197
|
const operands = [{
|
|
176
198
|
node: node.left,
|
|
177
199
|
path: `${path}.left`
|
|
@@ -180,7 +202,7 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
180
202
|
path: `${path}.right`
|
|
181
203
|
}];
|
|
182
204
|
for (const operand of operands) {
|
|
183
|
-
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
205
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path, divergence);
|
|
184
206
|
if (unpushable !== void 0) return unpushable;
|
|
185
207
|
const staticKind = staticValueKindOf(operand.node, options);
|
|
186
208
|
if (staticKind !== void 0 && staticKind !== "text") return {
|
|
@@ -200,12 +222,12 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
200
222
|
path: `${path}.candidates[${String(index)}]`
|
|
201
223
|
}))];
|
|
202
224
|
for (const operand of operands) {
|
|
203
|
-
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
225
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path, divergence);
|
|
204
226
|
if (unpushable !== void 0) return unpushable;
|
|
205
227
|
}
|
|
206
|
-
return findKindDivergence(node.kind, path, operands, options);
|
|
228
|
+
return findKindDivergence(node.kind, path, operands, options, divergence);
|
|
207
229
|
}
|
|
208
|
-
case "exists": return findUnpushableExpression(node.operand, `${path}.operand
|
|
230
|
+
case "exists": return findUnpushableExpression(node.operand, `${path}.operand`, divergence);
|
|
209
231
|
case "some":
|
|
210
232
|
case "every": return {
|
|
211
233
|
kind: node.kind,
|
|
@@ -232,9 +254,15 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
232
254
|
* `compilePredicateNode` runs this first and throws `UnsupportedNodeError` on any result, so calling it separately is only necessary to *decide* between pushdown and in-process evaluation without provoking an exception.
|
|
233
255
|
*
|
|
234
256
|
* 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`).
|
|
257
|
+
*
|
|
258
|
+
* 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.
|
|
259
|
+
*
|
|
260
|
+
* @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.
|
|
235
261
|
*/
|
|
236
262
|
function findUnpushableNodeKind(node, options) {
|
|
237
|
-
|
|
263
|
+
const dialect = options?.dialect ?? "postgres";
|
|
264
|
+
require_options.assertImplementedDialect(dialect);
|
|
265
|
+
return findUnpushablePredicate(node, "$", options, DIALECT_DIVERGENCE[dialect]);
|
|
238
266
|
}
|
|
239
267
|
//#endregion
|
|
240
268
|
exports.findUnpushableNodeKind = findUnpushableNodeKind;
|
package/dist/guard.d.cts
CHANGED
|
@@ -16,6 +16,10 @@ interface UnpushableNode {
|
|
|
16
16
|
* `compilePredicateNode` runs this first and throws `UnsupportedNodeError` on any result, so calling it separately is only necessary to *decide* between pushdown and in-process evaluation without provoking an exception.
|
|
17
17
|
*
|
|
18
18
|
* 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`).
|
|
19
|
+
*
|
|
20
|
+
* 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.
|
|
21
|
+
*
|
|
22
|
+
* @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.
|
|
19
23
|
*/
|
|
20
24
|
declare function findUnpushableNodeKind(node: PredicateNode, options?: SqlCompileOptions): UnpushableNode | undefined;
|
|
21
25
|
//#endregion
|
package/dist/guard.d.ts
CHANGED
|
@@ -16,6 +16,10 @@ interface UnpushableNode {
|
|
|
16
16
|
* `compilePredicateNode` runs this first and throws `UnsupportedNodeError` on any result, so calling it separately is only necessary to *decide* between pushdown and in-process evaluation without provoking an exception.
|
|
17
17
|
*
|
|
18
18
|
* 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`).
|
|
19
|
+
*
|
|
20
|
+
* 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.
|
|
21
|
+
*
|
|
22
|
+
* @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.
|
|
19
23
|
*/
|
|
20
24
|
declare function findUnpushableNodeKind(node: PredicateNode, options?: SqlCompileOptions): UnpushableNode | undefined;
|
|
21
25
|
//#endregion
|
package/dist/guard.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { assertImplementedDialect } from "./options.js";
|
|
1
2
|
//#region src/guard.ts
|
|
2
3
|
const STATIC_KIND_OF_PARAM_TYPE = {
|
|
3
4
|
text: "text",
|
|
@@ -5,7 +6,7 @@ const STATIC_KIND_OF_PARAM_TYPE = {
|
|
|
5
6
|
boolean: "boolean",
|
|
6
7
|
timestamp: "instant"
|
|
7
8
|
};
|
|
8
|
-
/** The comparison operators that impose an ordering, as opposed to testing equality. trilean refuses these on booleans -- `true > false` is not a fact about the domain -- while
|
|
9
|
+
/** The comparison operators that impose an ordering, as opposed to testing equality. trilean refuses these on booleans -- `true > false` is not a fact about the domain -- while both dialects answer them, so a boolean operand under one of these is a real divergence rather than a stylistic one. */
|
|
9
10
|
const ORDERING_OPERATORS = /* @__PURE__ */ new Set([
|
|
10
11
|
"gt",
|
|
11
12
|
"gte",
|
|
@@ -19,13 +20,29 @@ const STATIC_KIND_OF_LITERAL = {
|
|
|
19
20
|
booleanLiteral: "boolean",
|
|
20
21
|
instantLiteral: "instant"
|
|
21
22
|
};
|
|
23
|
+
const DIALECT_DIVERGENCE = {
|
|
24
|
+
postgres: {
|
|
25
|
+
complexNumbers: "PostgreSQL has no complex number type",
|
|
26
|
+
nan: "NaN is equal to nothing in trilean, not even itself, whereas PostgreSQL defines NaN as equal to itself and greater than every other double",
|
|
27
|
+
crossKindCoercion: "PostgreSQL may coerce one to the other and answer definitely",
|
|
28
|
+
textOrdering: (operandPath) => `PostgreSQL would order the text operand at ${operandPath} collation-wise and answer definitely`,
|
|
29
|
+
booleanOrdering: "PostgreSQL orders false before true"
|
|
30
|
+
},
|
|
31
|
+
sqlite: {
|
|
32
|
+
complexNumbers: "SQLite has no complex number type",
|
|
33
|
+
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",
|
|
34
|
+
crossKindCoercion: "SQLite's type affinity may coerce one to the other and answer definitely",
|
|
35
|
+
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)`,
|
|
36
|
+
booleanOrdering: "SQLite stores booleans as the integers 0 and 1 and orders them as integers"
|
|
37
|
+
}
|
|
38
|
+
};
|
|
22
39
|
function staticValueKindOf(node, options) {
|
|
23
40
|
if (node.kind !== "reference") return STATIC_KIND_OF_LITERAL[node.kind];
|
|
24
41
|
if (options === void 0 || typeof node.key !== "string") return void 0;
|
|
25
42
|
const paramType = options.columnFor(node.key).paramType;
|
|
26
43
|
return paramType === void 0 ? void 0 : STATIC_KIND_OF_PARAM_TYPE[paramType];
|
|
27
44
|
}
|
|
28
|
-
function findUnpushableExpression(node, path) {
|
|
45
|
+
function findUnpushableExpression(node, path, divergence) {
|
|
29
46
|
const unrecognisedKind = node.kind;
|
|
30
47
|
switch (node.kind) {
|
|
31
48
|
case "reference":
|
|
@@ -49,7 +66,7 @@ function findUnpushableExpression(node, path) {
|
|
|
49
66
|
if (Number.isNaN(node.value)) return {
|
|
50
67
|
kind: node.kind,
|
|
51
68
|
path,
|
|
52
|
-
reason:
|
|
69
|
+
reason: divergence.nan
|
|
53
70
|
};
|
|
54
71
|
return;
|
|
55
72
|
case "textLiteral":
|
|
@@ -63,7 +80,7 @@ function findUnpushableExpression(node, path) {
|
|
|
63
80
|
case "complexLiteral": return {
|
|
64
81
|
kind: node.kind,
|
|
65
82
|
path,
|
|
66
|
-
reason:
|
|
83
|
+
reason: divergence.complexNumbers
|
|
67
84
|
};
|
|
68
85
|
case "arithmetic":
|
|
69
86
|
case "negate": return {
|
|
@@ -113,8 +130,8 @@ function findUnpushableExpression(node, path) {
|
|
|
113
130
|
};
|
|
114
131
|
}
|
|
115
132
|
}
|
|
116
|
-
/** Checks the operands of a comparison-shaped predicate for a kind pairing trilean and
|
|
117
|
-
function findKindDivergence(kind, path, operands, options) {
|
|
133
|
+
/** Checks the operands of a comparison-shaped predicate for a kind pairing trilean and the target engine would answer differently. Returns the objection against `path` itself, since the divergence is a property of the pairing rather than of either operand alone. */
|
|
134
|
+
function findKindDivergence(kind, path, operands, options, divergence) {
|
|
118
135
|
const known = operands.map((operand) => ({
|
|
119
136
|
path: operand.path,
|
|
120
137
|
staticKind: staticValueKindOf(operand.node, options)
|
|
@@ -125,19 +142,19 @@ function findKindDivergence(kind, path, operands, options) {
|
|
|
125
142
|
if (mismatched !== void 0) return {
|
|
126
143
|
kind,
|
|
127
144
|
path,
|
|
128
|
-
reason: `trilean treats a comparison between a '${first.staticKind}' value (${first.path}) and a '${mismatched.staticKind}' value (${mismatched.path}) as wrong-type, whereas
|
|
145
|
+
reason: `trilean treats a comparison between a '${first.staticKind}' value (${first.path}) and a '${mismatched.staticKind}' value (${mismatched.path}) as wrong-type, whereas ${divergence.crossKindCoercion}`
|
|
129
146
|
};
|
|
130
147
|
}
|
|
131
|
-
function findUnpushablePredicate(node, path, options) {
|
|
148
|
+
function findUnpushablePredicate(node, path, options, divergence) {
|
|
132
149
|
const unrecognisedKind = node.kind;
|
|
133
150
|
switch (node.kind) {
|
|
134
|
-
case "not": return findUnpushablePredicate(node.operand, `${path}.operand`, options);
|
|
151
|
+
case "not": return findUnpushablePredicate(node.operand, `${path}.operand`, options, divergence);
|
|
135
152
|
case "and":
|
|
136
|
-
case "or": return findUnpushablePredicate(node.left, `${path}.left`, options) ?? findUnpushablePredicate(node.right, `${path}.right`, options);
|
|
153
|
+
case "or": return findUnpushablePredicate(node.left, `${path}.left`, options, divergence) ?? findUnpushablePredicate(node.right, `${path}.right`, options, divergence);
|
|
137
154
|
case "allOf":
|
|
138
155
|
case "anyOf":
|
|
139
156
|
for (const [index, operand] of node.operands.entries()) {
|
|
140
|
-
const unpushable = findUnpushablePredicate(operand, `${path}.operands[${String(index)}]`, options);
|
|
157
|
+
const unpushable = findUnpushablePredicate(operand, `${path}.operands[${String(index)}]`, options, divergence);
|
|
141
158
|
if (unpushable !== void 0) return unpushable;
|
|
142
159
|
}
|
|
143
160
|
return;
|
|
@@ -150,27 +167,32 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
150
167
|
path: `${path}.right`
|
|
151
168
|
}];
|
|
152
169
|
for (const operand of operands) {
|
|
153
|
-
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
170
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path, divergence);
|
|
154
171
|
if (unpushable !== void 0) return unpushable;
|
|
155
172
|
}
|
|
156
|
-
const
|
|
157
|
-
if (
|
|
173
|
+
const mismatch = findKindDivergence(node.kind, path, operands, options, divergence);
|
|
174
|
+
if (mismatch !== void 0) return mismatch;
|
|
158
175
|
for (const operand of operands) {
|
|
159
176
|
const staticKind = staticValueKindOf(operand.node, options);
|
|
160
177
|
if (staticKind === "text") return {
|
|
161
178
|
kind: node.kind,
|
|
162
179
|
path,
|
|
163
|
-
reason: `'compare' never compares text in trilean -- it returns wrong-type and directs the caller to 'textCompare' -- but
|
|
180
|
+
reason: `'compare' never compares text in trilean -- it returns wrong-type and directs the caller to 'textCompare' -- but ${divergence.textOrdering(operand.path)}`
|
|
164
181
|
};
|
|
165
182
|
if (staticKind === "boolean" && ORDERING_OPERATORS.has(node.op)) return {
|
|
166
183
|
kind: node.kind,
|
|
167
184
|
path,
|
|
168
|
-
reason: `booleans have no ordering in trilean, so '${node.op}' against the boolean operand at ${operand.path} is wrong-type there, whereas
|
|
185
|
+
reason: `booleans have no ordering in trilean, so '${node.op}' against the boolean operand at ${operand.path} is wrong-type there, whereas ${divergence.booleanOrdering}`
|
|
169
186
|
};
|
|
170
187
|
}
|
|
171
188
|
return;
|
|
172
189
|
}
|
|
173
190
|
case "textCompare": {
|
|
191
|
+
if ((node.op === "matches" || node.op === "notMatches") && options?.dialect === "sqlite" && options.sqliteRegexpAvailable === false) return {
|
|
192
|
+
kind: node.kind,
|
|
193
|
+
path,
|
|
194
|
+
reason: `options.sqliteRegexpAvailable is false: the caller has stated no regexp(pattern, value) function can be registered on this SQLite target, so '${node.op}' would compile to SQL that fails at query execution time with "no such function: REGEXP" instead of at compile time`
|
|
195
|
+
};
|
|
174
196
|
const operands = [{
|
|
175
197
|
node: node.left,
|
|
176
198
|
path: `${path}.left`
|
|
@@ -179,7 +201,7 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
179
201
|
path: `${path}.right`
|
|
180
202
|
}];
|
|
181
203
|
for (const operand of operands) {
|
|
182
|
-
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
204
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path, divergence);
|
|
183
205
|
if (unpushable !== void 0) return unpushable;
|
|
184
206
|
const staticKind = staticValueKindOf(operand.node, options);
|
|
185
207
|
if (staticKind !== void 0 && staticKind !== "text") return {
|
|
@@ -199,12 +221,12 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
199
221
|
path: `${path}.candidates[${String(index)}]`
|
|
200
222
|
}))];
|
|
201
223
|
for (const operand of operands) {
|
|
202
|
-
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
224
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path, divergence);
|
|
203
225
|
if (unpushable !== void 0) return unpushable;
|
|
204
226
|
}
|
|
205
|
-
return findKindDivergence(node.kind, path, operands, options);
|
|
227
|
+
return findKindDivergence(node.kind, path, operands, options, divergence);
|
|
206
228
|
}
|
|
207
|
-
case "exists": return findUnpushableExpression(node.operand, `${path}.operand
|
|
229
|
+
case "exists": return findUnpushableExpression(node.operand, `${path}.operand`, divergence);
|
|
208
230
|
case "some":
|
|
209
231
|
case "every": return {
|
|
210
232
|
kind: node.kind,
|
|
@@ -231,9 +253,15 @@ function findUnpushablePredicate(node, path, options) {
|
|
|
231
253
|
* `compilePredicateNode` runs this first and throws `UnsupportedNodeError` on any result, so calling it separately is only necessary to *decide* between pushdown and in-process evaluation without provoking an exception.
|
|
232
254
|
*
|
|
233
255
|
* 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`).
|
|
256
|
+
*
|
|
257
|
+
* 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.
|
|
258
|
+
*
|
|
259
|
+
* @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.
|
|
234
260
|
*/
|
|
235
261
|
function findUnpushableNodeKind(node, options) {
|
|
236
|
-
|
|
262
|
+
const dialect = options?.dialect ?? "postgres";
|
|
263
|
+
assertImplementedDialect(dialect);
|
|
264
|
+
return findUnpushablePredicate(node, "$", options, DIALECT_DIVERGENCE[dialect]);
|
|
237
265
|
}
|
|
238
266
|
//#endregion
|
|
239
267
|
export { findUnpushableNodeKind };
|
package/dist/index.cjs
CHANGED
|
@@ -4,6 +4,7 @@ const require_guard = require("./guard.cjs");
|
|
|
4
4
|
const require_compile = require("./compile.cjs");
|
|
5
5
|
exports.InvalidColumnError = require_errors.InvalidColumnError;
|
|
6
6
|
exports.TrileanSqlError = require_errors.TrileanSqlError;
|
|
7
|
+
exports.UnknownDialectError = require_errors.UnknownDialectError;
|
|
7
8
|
exports.UnsupportedNodeError = require_errors.UnsupportedNodeError;
|
|
8
9
|
exports.compilePredicateNode = require_compile.compilePredicateNode;
|
|
9
10
|
exports.findUnpushableNodeKind = require_guard.findUnpushableNodeKind;
|
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { CompiledSql, SqlColumnBinding, SqlCompileOptions, SqlParamType } from "./options.cjs";
|
|
1
|
+
import { CompiledSql, SqlColumnBinding, SqlCompileOptions, SqlDialect, SqlParamType } from "./options.cjs";
|
|
2
2
|
import { compilePredicateNode } from "./compile.cjs";
|
|
3
|
-
import { InvalidColumnError, TrileanSqlError, UnsupportedNodeError } from "./errors.cjs";
|
|
3
|
+
import { InvalidColumnError, TrileanSqlError, UnknownDialectError, UnsupportedNodeError } from "./errors.cjs";
|
|
4
4
|
import { UnpushableNode, findUnpushableNodeKind } from "./guard.cjs";
|
|
5
|
-
export { type CompiledSql, InvalidColumnError, type SqlColumnBinding, type SqlCompileOptions, type SqlParamType, TrileanSqlError, type UnpushableNode, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
|
5
|
+
export { type CompiledSql, InvalidColumnError, type SqlColumnBinding, type SqlCompileOptions, type SqlDialect, type SqlParamType, TrileanSqlError, UnknownDialectError, type UnpushableNode, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { CompiledSql, SqlColumnBinding, SqlCompileOptions, SqlParamType } from "./options.js";
|
|
1
|
+
import { CompiledSql, SqlColumnBinding, SqlCompileOptions, SqlDialect, SqlParamType } from "./options.js";
|
|
2
2
|
import { compilePredicateNode } from "./compile.js";
|
|
3
|
-
import { InvalidColumnError, TrileanSqlError, UnsupportedNodeError } from "./errors.js";
|
|
3
|
+
import { InvalidColumnError, TrileanSqlError, UnknownDialectError, UnsupportedNodeError } from "./errors.js";
|
|
4
4
|
import { UnpushableNode, findUnpushableNodeKind } from "./guard.js";
|
|
5
|
-
export { type CompiledSql, InvalidColumnError, type SqlColumnBinding, type SqlCompileOptions, type SqlParamType, TrileanSqlError, type UnpushableNode, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
|
5
|
+
export { type CompiledSql, InvalidColumnError, type SqlColumnBinding, type SqlCompileOptions, type SqlDialect, type SqlParamType, TrileanSqlError, UnknownDialectError, type UnpushableNode, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { InvalidColumnError, TrileanSqlError, UnsupportedNodeError } from "./errors.js";
|
|
1
|
+
import { InvalidColumnError, TrileanSqlError, UnknownDialectError, UnsupportedNodeError } from "./errors.js";
|
|
2
2
|
import { findUnpushableNodeKind } from "./guard.js";
|
|
3
3
|
import { compilePredicateNode } from "./compile.js";
|
|
4
|
-
export { InvalidColumnError, TrileanSqlError, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
|
4
|
+
export { InvalidColumnError, TrileanSqlError, UnknownDialectError, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
package/dist/options.cjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
+
const require_errors = require("./errors.cjs");
|
|
2
3
|
//#region src/options.ts
|
|
3
4
|
/** The PostgreSQL type each declared value kind is cast to. `timestamptz` rather than `timestamp`: trilean's `instant` is an ISO-8601 string that may carry an offset, and parsing one as a naive `timestamp` would silently discard it. */
|
|
4
5
|
const POSTGRES_TYPE_NAME = {
|
|
@@ -7,5 +8,31 @@ const POSTGRES_TYPE_NAME = {
|
|
|
7
8
|
boolean: "boolean",
|
|
8
9
|
timestamp: "timestamptz"
|
|
9
10
|
};
|
|
11
|
+
const DIALECT_CONFIG = {
|
|
12
|
+
postgres: {
|
|
13
|
+
matches: "~",
|
|
14
|
+
notMatches: "!~",
|
|
15
|
+
placeholder: (index, castTo) => `$${String(index)}::${POSTGRES_TYPE_NAME[castTo]}`,
|
|
16
|
+
emptyMemberOfNullSuffix: "::boolean"
|
|
17
|
+
},
|
|
18
|
+
sqlite: {
|
|
19
|
+
matches: "REGEXP",
|
|
20
|
+
notMatches: "NOT REGEXP",
|
|
21
|
+
placeholder: () => "?",
|
|
22
|
+
emptyMemberOfNullSuffix: ""
|
|
23
|
+
}
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Refuses a dialect this version does not implement, before anything indexes a per-dialect table with it.
|
|
27
|
+
*
|
|
28
|
+
* Both entry points check their own argument, because both are reachable with a name the type describes but cannot enforce -- a dialect is exactly the sort of value that arrives as a configuration string asserted into the union at the boundary. Left unchecked, that name is not caught anywhere: the compiler reads an operator off `undefined` and throws a `TypeError` naming an internal field, and the guard, whose tables are only consulted for a node it actually objects to, answers "pushable" for a tree the compiler then fails on -- the one thing `findUnpushableNodeKind` exists to decide, decided wrongly.
|
|
29
|
+
*
|
|
30
|
+
* `DIALECT_CONFIG` is the list, rather than a second constant, so implementing a dialect cannot leave this behind.
|
|
31
|
+
*/
|
|
32
|
+
function assertImplementedDialect(dialect) {
|
|
33
|
+
if (!Object.hasOwn(DIALECT_CONFIG, dialect)) throw new require_errors.UnknownDialectError(dialect, Object.keys(DIALECT_CONFIG));
|
|
34
|
+
}
|
|
10
35
|
//#endregion
|
|
36
|
+
exports.DIALECT_CONFIG = DIALECT_CONFIG;
|
|
11
37
|
exports.POSTGRES_TYPE_NAME = POSTGRES_TYPE_NAME;
|
|
38
|
+
exports.assertImplementedDialect = assertImplementedDialect;
|
package/dist/options.d.cts
CHANGED
|
@@ -1,34 +1,66 @@
|
|
|
1
1
|
//#region src/options.d.ts
|
|
2
2
|
/** The declared SQL value kind of a mapped column. `"timestamp"` names trilean's `instant` kind, whose values are ISO-8601 strings. */
|
|
3
3
|
type SqlParamType = "text" | "number" | "boolean" | "timestamp";
|
|
4
|
+
/** The SQL dialects this compiler emits. A dialect is named rather than inferred: the same tree compiles to different text for each, and a caller that never said which one it meant would be relying on whichever happened to be the default. */
|
|
5
|
+
type SqlDialect = "postgres" | "sqlite";
|
|
4
6
|
/** What a `reference` node's key maps onto in the target schema. */
|
|
5
7
|
interface SqlColumnBinding {
|
|
6
8
|
/** The column, optionally qualified with a table or schema by dots (`"orders.total"`). Each dot-separated segment is emitted as its own double-quoted identifier, so a segment may contain any character except a dot itself. */
|
|
7
9
|
column: string;
|
|
8
10
|
/**
|
|
9
|
-
* The column's value kind, if the caller knows it. Optional, and worth supplying: it is the only thing that lets the compiler check a comparison against the column for the kind mismatches trilean itself treats as `wrong-type` -- comparing a text column with `compare` rather than `textCompare`, ordering a boolean, comparing a number against an instant. Left undeclared, those comparisons compile, and
|
|
11
|
+
* The column's value kind, if the caller knows it. Optional, and worth supplying: it is the only thing that lets the compiler check a comparison against the column for the kind mismatches trilean itself treats as `wrong-type` -- comparing a text column with `compare` rather than `textCompare`, ordering a boolean, comparing a number against an instant. Left undeclared, those comparisons compile, and the database may coerce its way to a definite answer where trilean would have returned indeterminate.
|
|
10
12
|
*
|
|
11
|
-
* It does not affect the emitted SQL, only whether the comparison is emitted at all. Every literal placeholder is already cast to the type its own trilean kind implies, and a comparison that survives the check is one whose operand kinds agree, so there is nothing left for the column's declared kind to change.
|
|
13
|
+
* It does not affect the emitted SQL, only whether the comparison is emitted at all. Every literal placeholder is already cast to the type its own trilean kind implies (in the dialects that cast at all), and a comparison that survives the check is one whose operand kinds agree, so there is nothing left for the column's declared kind to change.
|
|
12
14
|
*/
|
|
13
15
|
paramType?: SqlParamType;
|
|
14
16
|
}
|
|
15
17
|
interface SqlCompileOptions {
|
|
16
|
-
/**
|
|
17
|
-
dialect:
|
|
18
|
+
/** Which dialect to emit. It is a required field rather than a default so that a caller states the engine it is compiling for, instead of inheriting whichever one this package happened to implement first. */
|
|
19
|
+
dialect: SqlDialect;
|
|
18
20
|
/**
|
|
19
21
|
* Maps a `reference` node's key onto a column. Called once per reference occurrence.
|
|
20
22
|
*
|
|
21
23
|
* Only string reference keys reach it: trilean allows any JSON value as a key, and a non-string one is refused as unpushable before this is called. Throwing from here is how a caller rejects a key it has no column for -- the exception propagates out of `compilePredicateNode` unchanged, rather than being wrapped or swallowed.
|
|
22
24
|
*/
|
|
23
25
|
columnFor: (referenceKey: string) => SqlColumnBinding;
|
|
26
|
+
/**
|
|
27
|
+
* Whether the SQLite target can resolve a `regexp(pattern, value)` function for `textCompare`'s `matches`/`notMatches` to compile to. Ignored under the `postgres` dialect, which matches patterns with its own native `~`/`!~` operators and never needs this.
|
|
28
|
+
*
|
|
29
|
+
* Defaults to `true`, preserving the historical behaviour of always compiling to `REGEXP`/`NOT REGEXP`, which is correct for a driver a caller can register a function on (better-sqlite3, for instance). Set explicitly to `false` for a SQLite-wire-compatible target with no such registration hook -- Cloudflare D1 is the motivating case -- so `matches`/`notMatches` are refused by `UnsupportedNodeError` at compile time instead of compiling to SQL that fails at query execution with "no such function: REGEXP". See the "Regular expressions" section in README.md.
|
|
30
|
+
*/
|
|
31
|
+
sqliteRegexpAvailable?: boolean;
|
|
24
32
|
}
|
|
25
33
|
interface CompiledSql {
|
|
26
34
|
/** A self-contained boolean expression, always parenthesised, suitable for dropping straight into a `WHERE` clause (or a `CHECK`, a `HAVING`, or a filtered index predicate). It carries no `WHERE` keyword of its own. */
|
|
27
35
|
sql: string;
|
|
28
|
-
/** Positional parameters, in
|
|
36
|
+
/** Positional parameters, in emission order, to pass alongside `sql`. Every caller-supplied literal in the tree is here; none is ever written into `sql`. */
|
|
29
37
|
params: unknown[];
|
|
30
38
|
}
|
|
31
39
|
/** The PostgreSQL type each declared value kind is cast to. `timestamptz` rather than `timestamp`: trilean's `instant` is an ISO-8601 string that may carry an offset, and parsing one as a naive `timestamp` would silently discard it. */
|
|
32
40
|
declare const POSTGRES_TYPE_NAME: Readonly<Record<SqlParamType, string>>;
|
|
41
|
+
/**
|
|
42
|
+
* Everything about the emitted SQL that is a property of the dialect rather than of the tree.
|
|
43
|
+
*
|
|
44
|
+
* It is deliberately this small. Most of what the compiler emits is ANSI-standard and identical in both engines -- the six comparison operators, `=` and `<>` for `textCompare`'s `equals`/`notEquals`, `AND`/`OR`/`NOT`, `IN`/`NOT IN`, `IS NOT NULL`, and double-quoted identifiers with an embedded quote doubled -- so branching on the dialect anywhere else would be a branch that can never change the output. Three things genuinely differ, and they are the three fields below.
|
|
45
|
+
*/
|
|
46
|
+
interface DialectConfig {
|
|
47
|
+
/** The regular-expression match operator `textCompare`'s `matches` compiles to. */
|
|
48
|
+
matches: string;
|
|
49
|
+
/** The negated regular-expression match operator `textCompare`'s `notMatches` compiles to. */
|
|
50
|
+
notMatches: string;
|
|
51
|
+
/** Renders the `index`-th (1-based) bind placeholder, for a literal whose own trilean kind implies `castTo`. A dialect that does not need the cast ignores both arguments. */
|
|
52
|
+
placeholder: (index: number, castTo: SqlParamType) => string;
|
|
53
|
+
/** Appended to the bare `NULL` in the two forms an empty `memberOf` candidate list compiles to, for a dialect that needs the resulting expression annotated with a boolean type. */
|
|
54
|
+
emptyMemberOfNullSuffix: string;
|
|
55
|
+
}
|
|
56
|
+
declare const DIALECT_CONFIG: Readonly<Record<SqlDialect, DialectConfig>>;
|
|
57
|
+
/**
|
|
58
|
+
* Refuses a dialect this version does not implement, before anything indexes a per-dialect table with it.
|
|
59
|
+
*
|
|
60
|
+
* Both entry points check their own argument, because both are reachable with a name the type describes but cannot enforce -- a dialect is exactly the sort of value that arrives as a configuration string asserted into the union at the boundary. Left unchecked, that name is not caught anywhere: the compiler reads an operator off `undefined` and throws a `TypeError` naming an internal field, and the guard, whose tables are only consulted for a node it actually objects to, answers "pushable" for a tree the compiler then fails on -- the one thing `findUnpushableNodeKind` exists to decide, decided wrongly.
|
|
61
|
+
*
|
|
62
|
+
* `DIALECT_CONFIG` is the list, rather than a second constant, so implementing a dialect cannot leave this behind.
|
|
63
|
+
*/
|
|
64
|
+
declare function assertImplementedDialect(dialect: SqlDialect): void;
|
|
33
65
|
//#endregion
|
|
34
|
-
export { CompiledSql, POSTGRES_TYPE_NAME, SqlColumnBinding, SqlCompileOptions, SqlParamType };
|
|
66
|
+
export { CompiledSql, DIALECT_CONFIG, DialectConfig, POSTGRES_TYPE_NAME, SqlColumnBinding, SqlCompileOptions, SqlDialect, SqlParamType, assertImplementedDialect };
|
package/dist/options.d.ts
CHANGED
|
@@ -1,34 +1,66 @@
|
|
|
1
1
|
//#region src/options.d.ts
|
|
2
2
|
/** The declared SQL value kind of a mapped column. `"timestamp"` names trilean's `instant` kind, whose values are ISO-8601 strings. */
|
|
3
3
|
type SqlParamType = "text" | "number" | "boolean" | "timestamp";
|
|
4
|
+
/** The SQL dialects this compiler emits. A dialect is named rather than inferred: the same tree compiles to different text for each, and a caller that never said which one it meant would be relying on whichever happened to be the default. */
|
|
5
|
+
type SqlDialect = "postgres" | "sqlite";
|
|
4
6
|
/** What a `reference` node's key maps onto in the target schema. */
|
|
5
7
|
interface SqlColumnBinding {
|
|
6
8
|
/** The column, optionally qualified with a table or schema by dots (`"orders.total"`). Each dot-separated segment is emitted as its own double-quoted identifier, so a segment may contain any character except a dot itself. */
|
|
7
9
|
column: string;
|
|
8
10
|
/**
|
|
9
|
-
* The column's value kind, if the caller knows it. Optional, and worth supplying: it is the only thing that lets the compiler check a comparison against the column for the kind mismatches trilean itself treats as `wrong-type` -- comparing a text column with `compare` rather than `textCompare`, ordering a boolean, comparing a number against an instant. Left undeclared, those comparisons compile, and
|
|
11
|
+
* The column's value kind, if the caller knows it. Optional, and worth supplying: it is the only thing that lets the compiler check a comparison against the column for the kind mismatches trilean itself treats as `wrong-type` -- comparing a text column with `compare` rather than `textCompare`, ordering a boolean, comparing a number against an instant. Left undeclared, those comparisons compile, and the database may coerce its way to a definite answer where trilean would have returned indeterminate.
|
|
10
12
|
*
|
|
11
|
-
* It does not affect the emitted SQL, only whether the comparison is emitted at all. Every literal placeholder is already cast to the type its own trilean kind implies, and a comparison that survives the check is one whose operand kinds agree, so there is nothing left for the column's declared kind to change.
|
|
13
|
+
* It does not affect the emitted SQL, only whether the comparison is emitted at all. Every literal placeholder is already cast to the type its own trilean kind implies (in the dialects that cast at all), and a comparison that survives the check is one whose operand kinds agree, so there is nothing left for the column's declared kind to change.
|
|
12
14
|
*/
|
|
13
15
|
paramType?: SqlParamType;
|
|
14
16
|
}
|
|
15
17
|
interface SqlCompileOptions {
|
|
16
|
-
/**
|
|
17
|
-
dialect:
|
|
18
|
+
/** Which dialect to emit. It is a required field rather than a default so that a caller states the engine it is compiling for, instead of inheriting whichever one this package happened to implement first. */
|
|
19
|
+
dialect: SqlDialect;
|
|
18
20
|
/**
|
|
19
21
|
* Maps a `reference` node's key onto a column. Called once per reference occurrence.
|
|
20
22
|
*
|
|
21
23
|
* Only string reference keys reach it: trilean allows any JSON value as a key, and a non-string one is refused as unpushable before this is called. Throwing from here is how a caller rejects a key it has no column for -- the exception propagates out of `compilePredicateNode` unchanged, rather than being wrapped or swallowed.
|
|
22
24
|
*/
|
|
23
25
|
columnFor: (referenceKey: string) => SqlColumnBinding;
|
|
26
|
+
/**
|
|
27
|
+
* Whether the SQLite target can resolve a `regexp(pattern, value)` function for `textCompare`'s `matches`/`notMatches` to compile to. Ignored under the `postgres` dialect, which matches patterns with its own native `~`/`!~` operators and never needs this.
|
|
28
|
+
*
|
|
29
|
+
* Defaults to `true`, preserving the historical behaviour of always compiling to `REGEXP`/`NOT REGEXP`, which is correct for a driver a caller can register a function on (better-sqlite3, for instance). Set explicitly to `false` for a SQLite-wire-compatible target with no such registration hook -- Cloudflare D1 is the motivating case -- so `matches`/`notMatches` are refused by `UnsupportedNodeError` at compile time instead of compiling to SQL that fails at query execution with "no such function: REGEXP". See the "Regular expressions" section in README.md.
|
|
30
|
+
*/
|
|
31
|
+
sqliteRegexpAvailable?: boolean;
|
|
24
32
|
}
|
|
25
33
|
interface CompiledSql {
|
|
26
34
|
/** A self-contained boolean expression, always parenthesised, suitable for dropping straight into a `WHERE` clause (or a `CHECK`, a `HAVING`, or a filtered index predicate). It carries no `WHERE` keyword of its own. */
|
|
27
35
|
sql: string;
|
|
28
|
-
/** Positional parameters, in
|
|
36
|
+
/** Positional parameters, in emission order, to pass alongside `sql`. Every caller-supplied literal in the tree is here; none is ever written into `sql`. */
|
|
29
37
|
params: unknown[];
|
|
30
38
|
}
|
|
31
39
|
/** The PostgreSQL type each declared value kind is cast to. `timestamptz` rather than `timestamp`: trilean's `instant` is an ISO-8601 string that may carry an offset, and parsing one as a naive `timestamp` would silently discard it. */
|
|
32
40
|
declare const POSTGRES_TYPE_NAME: Readonly<Record<SqlParamType, string>>;
|
|
41
|
+
/**
|
|
42
|
+
* Everything about the emitted SQL that is a property of the dialect rather than of the tree.
|
|
43
|
+
*
|
|
44
|
+
* It is deliberately this small. Most of what the compiler emits is ANSI-standard and identical in both engines -- the six comparison operators, `=` and `<>` for `textCompare`'s `equals`/`notEquals`, `AND`/`OR`/`NOT`, `IN`/`NOT IN`, `IS NOT NULL`, and double-quoted identifiers with an embedded quote doubled -- so branching on the dialect anywhere else would be a branch that can never change the output. Three things genuinely differ, and they are the three fields below.
|
|
45
|
+
*/
|
|
46
|
+
interface DialectConfig {
|
|
47
|
+
/** The regular-expression match operator `textCompare`'s `matches` compiles to. */
|
|
48
|
+
matches: string;
|
|
49
|
+
/** The negated regular-expression match operator `textCompare`'s `notMatches` compiles to. */
|
|
50
|
+
notMatches: string;
|
|
51
|
+
/** Renders the `index`-th (1-based) bind placeholder, for a literal whose own trilean kind implies `castTo`. A dialect that does not need the cast ignores both arguments. */
|
|
52
|
+
placeholder: (index: number, castTo: SqlParamType) => string;
|
|
53
|
+
/** Appended to the bare `NULL` in the two forms an empty `memberOf` candidate list compiles to, for a dialect that needs the resulting expression annotated with a boolean type. */
|
|
54
|
+
emptyMemberOfNullSuffix: string;
|
|
55
|
+
}
|
|
56
|
+
declare const DIALECT_CONFIG: Readonly<Record<SqlDialect, DialectConfig>>;
|
|
57
|
+
/**
|
|
58
|
+
* Refuses a dialect this version does not implement, before anything indexes a per-dialect table with it.
|
|
59
|
+
*
|
|
60
|
+
* Both entry points check their own argument, because both are reachable with a name the type describes but cannot enforce -- a dialect is exactly the sort of value that arrives as a configuration string asserted into the union at the boundary. Left unchecked, that name is not caught anywhere: the compiler reads an operator off `undefined` and throws a `TypeError` naming an internal field, and the guard, whose tables are only consulted for a node it actually objects to, answers "pushable" for a tree the compiler then fails on -- the one thing `findUnpushableNodeKind` exists to decide, decided wrongly.
|
|
61
|
+
*
|
|
62
|
+
* `DIALECT_CONFIG` is the list, rather than a second constant, so implementing a dialect cannot leave this behind.
|
|
63
|
+
*/
|
|
64
|
+
declare function assertImplementedDialect(dialect: SqlDialect): void;
|
|
33
65
|
//#endregion
|
|
34
|
-
export { CompiledSql, POSTGRES_TYPE_NAME, SqlColumnBinding, SqlCompileOptions, SqlParamType };
|
|
66
|
+
export { CompiledSql, DIALECT_CONFIG, DialectConfig, POSTGRES_TYPE_NAME, SqlColumnBinding, SqlCompileOptions, SqlDialect, SqlParamType, assertImplementedDialect };
|