trilean-sql 0.0.0 → 1.0.1
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/LICENSE +21 -0
- package/README.md +147 -0
- package/dist/compile.cjs +146 -0
- package/dist/compile.d.cts +16 -0
- package/dist/compile.d.ts +16 -0
- package/dist/compile.js +145 -0
- package/dist/errors.cjs +47 -0
- package/dist/errors.d.cts +34 -0
- package/dist/errors.d.ts +34 -0
- package/dist/errors.js +44 -0
- package/dist/guard.cjs +240 -0
- package/dist/guard.d.cts +22 -0
- package/dist/guard.d.ts +22 -0
- package/dist/guard.js +239 -0
- package/dist/index.cjs +9 -0
- package/dist/index.d.cts +5 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +4 -0
- package/dist/options.cjs +11 -0
- package/dist/options.d.cts +34 -0
- package/dist/options.d.ts +34 -0
- package/dist/options.js +10 -0
- package/package.json +98 -2
package/dist/errors.js
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
//#region src/errors.ts
|
|
2
|
+
/** Base class for every error this package raises, so a caller can distinguish a compilation failure from an error thrown by its own `columnFor` (which is called during compilation and whose exceptions propagate unchanged). */
|
|
3
|
+
var TrileanSqlError = class extends Error {
|
|
4
|
+
constructor(message) {
|
|
5
|
+
super(message);
|
|
6
|
+
this.name = "TrileanSqlError";
|
|
7
|
+
}
|
|
8
|
+
};
|
|
9
|
+
/**
|
|
10
|
+
* A node the compiler refuses to translate. The compiler never degrades: there is no "best effort" fragment, no silently dropped conjunct, and no approximation that answers differently from the in-process evaluator. Either the whole tree compiles to SQL that agrees with `evaluatePredicate` on every row, or this is thrown and the caller evaluates in process instead.
|
|
11
|
+
*
|
|
12
|
+
* That guarantee is about the tree's *structure*, and it stops at two things whose meaning is a property of the operand's own content rather than of any node kind: a `matches`/`notMatches` pattern, which the server matches under PostgreSQL's regular-expression language rather than ECMAScript's, and an `instantLiteral` string the two engines parse differently or that PostgreSQL cannot parse at all (which fails as a query error at execution time, not as this exception). Both are covered in README.md; neither is detectable by a walk over node kinds.
|
|
13
|
+
*
|
|
14
|
+
* `nodeKind` is the offending node's own `kind`, `path` locates it inside the tree, and `reason` says why it is not pushable -- which is not always about the kind alone (a `reference` carrying a `unit`, or a `compare` whose operands are statically of different kinds, are both refused despite `reference` and `compare` being supported kinds).
|
|
15
|
+
*/
|
|
16
|
+
var UnsupportedNodeError = class extends TrileanSqlError {
|
|
17
|
+
nodeKind;
|
|
18
|
+
path;
|
|
19
|
+
reason;
|
|
20
|
+
constructor(unpushable) {
|
|
21
|
+
super(`cannot compile '${unpushable.kind}' at ${unpushable.path}: ${unpushable.reason}`);
|
|
22
|
+
this.name = "UnsupportedNodeError";
|
|
23
|
+
this.nodeKind = unpushable.kind;
|
|
24
|
+
this.path = unpushable.path;
|
|
25
|
+
this.reason = unpushable.reason;
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* A `columnFor` result whose `column` cannot be rendered as a PostgreSQL identifier.
|
|
30
|
+
*
|
|
31
|
+
* A column name is an identifier, not a value, so it is the one part of the emitted SQL that cannot be parameterised -- it has to be written into the statement text. It is always emitted double-quoted with any embedded quote doubled, which makes an arbitrary string safe, so this is not the injection defence; it rejects the two shapes that quoting cannot rescue into a valid identifier, an empty name and an empty dot-separated segment.
|
|
32
|
+
*/
|
|
33
|
+
var InvalidColumnError = class extends TrileanSqlError {
|
|
34
|
+
referenceKey;
|
|
35
|
+
column;
|
|
36
|
+
constructor(referenceKey, column, reason) {
|
|
37
|
+
super(`columnFor(${JSON.stringify(referenceKey)}) returned ${JSON.stringify(column)}, which is not a usable column identifier: ${reason}`);
|
|
38
|
+
this.name = "InvalidColumnError";
|
|
39
|
+
this.referenceKey = referenceKey;
|
|
40
|
+
this.column = column;
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
//#endregion
|
|
44
|
+
export { InvalidColumnError, TrileanSqlError, UnsupportedNodeError };
|
package/dist/guard.cjs
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
+
//#region src/guard.ts
|
|
3
|
+
const STATIC_KIND_OF_PARAM_TYPE = {
|
|
4
|
+
text: "text",
|
|
5
|
+
number: "number",
|
|
6
|
+
boolean: "boolean",
|
|
7
|
+
timestamp: "instant"
|
|
8
|
+
};
|
|
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 PostgreSQL answers them, so a boolean operand under one of these is a real divergence rather than a stylistic one. */
|
|
10
|
+
const ORDERING_OPERATORS = /* @__PURE__ */ new Set([
|
|
11
|
+
"gt",
|
|
12
|
+
"gte",
|
|
13
|
+
"lt",
|
|
14
|
+
"lte"
|
|
15
|
+
]);
|
|
16
|
+
/** A literal's own node kind is its value's kind. Written as a lookup rather than a switch so that every other expression kind falls out as "not statically knowable" by absence, which is the honest answer for all of them, rather than needing a branch each. */
|
|
17
|
+
const STATIC_KIND_OF_LITERAL = {
|
|
18
|
+
textLiteral: "text",
|
|
19
|
+
numberLiteral: "number",
|
|
20
|
+
booleanLiteral: "boolean",
|
|
21
|
+
instantLiteral: "instant"
|
|
22
|
+
};
|
|
23
|
+
function staticValueKindOf(node, options) {
|
|
24
|
+
if (node.kind !== "reference") return STATIC_KIND_OF_LITERAL[node.kind];
|
|
25
|
+
if (options === void 0 || typeof node.key !== "string") return void 0;
|
|
26
|
+
const paramType = options.columnFor(node.key).paramType;
|
|
27
|
+
return paramType === void 0 ? void 0 : STATIC_KIND_OF_PARAM_TYPE[paramType];
|
|
28
|
+
}
|
|
29
|
+
function findUnpushableExpression(node, path) {
|
|
30
|
+
const unrecognisedKind = node.kind;
|
|
31
|
+
switch (node.kind) {
|
|
32
|
+
case "reference":
|
|
33
|
+
if (typeof node.key !== "string") return {
|
|
34
|
+
kind: node.kind,
|
|
35
|
+
path,
|
|
36
|
+
reason: "only a string reference key can be mapped to a column; this key is a non-string JSON value"
|
|
37
|
+
};
|
|
38
|
+
if (node.unit !== void 0) return {
|
|
39
|
+
kind: node.kind,
|
|
40
|
+
path,
|
|
41
|
+
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"
|
|
42
|
+
};
|
|
43
|
+
return;
|
|
44
|
+
case "numberLiteral":
|
|
45
|
+
if (node.unit !== void 0) return {
|
|
46
|
+
kind: node.kind,
|
|
47
|
+
path,
|
|
48
|
+
reason: "a unit-tagged number is only comparable with an operand of the same unit, and SQL has no unit to compare"
|
|
49
|
+
};
|
|
50
|
+
if (Number.isNaN(node.value)) return {
|
|
51
|
+
kind: node.kind,
|
|
52
|
+
path,
|
|
53
|
+
reason: "NaN is equal to nothing in trilean, not even itself, whereas PostgreSQL defines NaN as equal to itself and greater than every other double"
|
|
54
|
+
};
|
|
55
|
+
return;
|
|
56
|
+
case "textLiteral":
|
|
57
|
+
case "booleanLiteral":
|
|
58
|
+
case "instantLiteral": return;
|
|
59
|
+
case "durationLiteral": return {
|
|
60
|
+
kind: node.kind,
|
|
61
|
+
path,
|
|
62
|
+
reason: "trilean compares durations by normalising both operands to milliseconds, which has no column-level equivalent to normalise against"
|
|
63
|
+
};
|
|
64
|
+
case "complexLiteral": return {
|
|
65
|
+
kind: node.kind,
|
|
66
|
+
path,
|
|
67
|
+
reason: "PostgreSQL has no complex number type"
|
|
68
|
+
};
|
|
69
|
+
case "arithmetic":
|
|
70
|
+
case "negate": return {
|
|
71
|
+
kind: node.kind,
|
|
72
|
+
path,
|
|
73
|
+
reason: "arithmetic carries and combines units, and pushing it down would drop that dimensional analysis without saying so"
|
|
74
|
+
};
|
|
75
|
+
case "call": return {
|
|
76
|
+
kind: node.kind,
|
|
77
|
+
path,
|
|
78
|
+
reason: "a function's implementation lives in the caller's FunctionRegistry, not in the database"
|
|
79
|
+
};
|
|
80
|
+
case "lookup": return {
|
|
81
|
+
kind: node.kind,
|
|
82
|
+
path,
|
|
83
|
+
reason: "a lookup table is resolved by the caller's resolvers"
|
|
84
|
+
};
|
|
85
|
+
case "conditional": return {
|
|
86
|
+
kind: node.kind,
|
|
87
|
+
path,
|
|
88
|
+
reason: "conditional evaluation is not implemented in this version of the compiler"
|
|
89
|
+
};
|
|
90
|
+
case "fold": return {
|
|
91
|
+
kind: node.kind,
|
|
92
|
+
path,
|
|
93
|
+
reason: "a fold ranges over a collection the caller's resolvers supply, which is not this query's row set"
|
|
94
|
+
};
|
|
95
|
+
case "accumulator": return {
|
|
96
|
+
kind: node.kind,
|
|
97
|
+
path,
|
|
98
|
+
reason: "an accumulator is only meaningful inside a reduce fold"
|
|
99
|
+
};
|
|
100
|
+
case "delegate": return {
|
|
101
|
+
kind: node.kind,
|
|
102
|
+
path,
|
|
103
|
+
reason: "a delegated decision is made by an external system"
|
|
104
|
+
};
|
|
105
|
+
case "treeReference": return {
|
|
106
|
+
kind: node.kind,
|
|
107
|
+
path,
|
|
108
|
+
reason: "a referenced tree is resolved by the caller's resolvers; inline it before compiling"
|
|
109
|
+
};
|
|
110
|
+
default: return {
|
|
111
|
+
kind: unrecognisedKind,
|
|
112
|
+
path,
|
|
113
|
+
reason: "unrecognised expression node kind"
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
/** Checks the operands of a comparison-shaped predicate for a kind pairing trilean and PostgreSQL would answer differently. Returns the objection against `path` itself, since the divergence is a property of the pairing rather than of either operand alone. */
|
|
118
|
+
function findKindDivergence(kind, path, operands, options) {
|
|
119
|
+
const known = operands.map((operand) => ({
|
|
120
|
+
path: operand.path,
|
|
121
|
+
staticKind: staticValueKindOf(operand.node, options)
|
|
122
|
+
})).filter((entry) => entry.staticKind !== void 0);
|
|
123
|
+
const first = known[0];
|
|
124
|
+
if (first === void 0) return void 0;
|
|
125
|
+
const mismatched = known.find((entry) => entry.staticKind !== first.staticKind);
|
|
126
|
+
if (mismatched !== void 0) return {
|
|
127
|
+
kind,
|
|
128
|
+
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 PostgreSQL may coerce one to the other and answer definitely`
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
function findUnpushablePredicate(node, path, options) {
|
|
133
|
+
const unrecognisedKind = node.kind;
|
|
134
|
+
switch (node.kind) {
|
|
135
|
+
case "not": return findUnpushablePredicate(node.operand, `${path}.operand`, options);
|
|
136
|
+
case "and":
|
|
137
|
+
case "or": return findUnpushablePredicate(node.left, `${path}.left`, options) ?? findUnpushablePredicate(node.right, `${path}.right`, options);
|
|
138
|
+
case "allOf":
|
|
139
|
+
case "anyOf":
|
|
140
|
+
for (const [index, operand] of node.operands.entries()) {
|
|
141
|
+
const unpushable = findUnpushablePredicate(operand, `${path}.operands[${String(index)}]`, options);
|
|
142
|
+
if (unpushable !== void 0) return unpushable;
|
|
143
|
+
}
|
|
144
|
+
return;
|
|
145
|
+
case "compare": {
|
|
146
|
+
const operands = [{
|
|
147
|
+
node: node.left,
|
|
148
|
+
path: `${path}.left`
|
|
149
|
+
}, {
|
|
150
|
+
node: node.right,
|
|
151
|
+
path: `${path}.right`
|
|
152
|
+
}];
|
|
153
|
+
for (const operand of operands) {
|
|
154
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
155
|
+
if (unpushable !== void 0) return unpushable;
|
|
156
|
+
}
|
|
157
|
+
const divergence = findKindDivergence(node.kind, path, operands, options);
|
|
158
|
+
if (divergence !== void 0) return divergence;
|
|
159
|
+
for (const operand of operands) {
|
|
160
|
+
const staticKind = staticValueKindOf(operand.node, options);
|
|
161
|
+
if (staticKind === "text") return {
|
|
162
|
+
kind: node.kind,
|
|
163
|
+
path,
|
|
164
|
+
reason: `'compare' never compares text in trilean -- it returns wrong-type and directs the caller to 'textCompare' -- but PostgreSQL would order the text operand at ${operand.path} collation-wise and answer definitely`
|
|
165
|
+
};
|
|
166
|
+
if (staticKind === "boolean" && ORDERING_OPERATORS.has(node.op)) return {
|
|
167
|
+
kind: node.kind,
|
|
168
|
+
path,
|
|
169
|
+
reason: `booleans have no ordering in trilean, so '${node.op}' against the boolean operand at ${operand.path} is wrong-type there, whereas PostgreSQL orders false before true`
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
return;
|
|
173
|
+
}
|
|
174
|
+
case "textCompare": {
|
|
175
|
+
const operands = [{
|
|
176
|
+
node: node.left,
|
|
177
|
+
path: `${path}.left`
|
|
178
|
+
}, {
|
|
179
|
+
node: node.right,
|
|
180
|
+
path: `${path}.right`
|
|
181
|
+
}];
|
|
182
|
+
for (const operand of operands) {
|
|
183
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
184
|
+
if (unpushable !== void 0) return unpushable;
|
|
185
|
+
const staticKind = staticValueKindOf(operand.node, options);
|
|
186
|
+
if (staticKind !== void 0 && staticKind !== "text") return {
|
|
187
|
+
kind: node.kind,
|
|
188
|
+
path,
|
|
189
|
+
reason: `'textCompare' requires text operands in trilean, and the operand at ${operand.path} is a '${staticKind}' value`
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
return;
|
|
193
|
+
}
|
|
194
|
+
case "memberOf": {
|
|
195
|
+
const operands = [{
|
|
196
|
+
node: node.operand,
|
|
197
|
+
path: `${path}.operand`
|
|
198
|
+
}, ...node.candidates.map((candidate, index) => ({
|
|
199
|
+
node: candidate,
|
|
200
|
+
path: `${path}.candidates[${String(index)}]`
|
|
201
|
+
}))];
|
|
202
|
+
for (const operand of operands) {
|
|
203
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
204
|
+
if (unpushable !== void 0) return unpushable;
|
|
205
|
+
}
|
|
206
|
+
return findKindDivergence(node.kind, path, operands, options);
|
|
207
|
+
}
|
|
208
|
+
case "exists": return findUnpushableExpression(node.operand, `${path}.operand`);
|
|
209
|
+
case "some":
|
|
210
|
+
case "every": return {
|
|
211
|
+
kind: node.kind,
|
|
212
|
+
path,
|
|
213
|
+
reason: "quantification ranges over a collection the caller's resolvers supply, which is not this query's row set"
|
|
214
|
+
};
|
|
215
|
+
case "treeReference": return {
|
|
216
|
+
kind: node.kind,
|
|
217
|
+
path,
|
|
218
|
+
reason: "a referenced tree is resolved by the caller's resolvers; inline it before compiling"
|
|
219
|
+
};
|
|
220
|
+
default: return {
|
|
221
|
+
kind: unrecognisedKind,
|
|
222
|
+
path,
|
|
223
|
+
reason: "unrecognised predicate node kind"
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Walks the tree against the allow-list of what this compiler translates, and reports the first node it will not.
|
|
229
|
+
*
|
|
230
|
+
* The walk is an allow-list rather than a deny-list on purpose: a node kind added to trilean after this package was written is refused by default, instead of falling through to whatever branch happened to be last. That is the difference between a caller learning it must evaluate in process and a caller silently receiving a `WHERE` clause that answers a different question.
|
|
231
|
+
*
|
|
232
|
+
* `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
|
+
*
|
|
234
|
+
* 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`).
|
|
235
|
+
*/
|
|
236
|
+
function findUnpushableNodeKind(node, options) {
|
|
237
|
+
return findUnpushablePredicate(node, "$", options);
|
|
238
|
+
}
|
|
239
|
+
//#endregion
|
|
240
|
+
exports.findUnpushableNodeKind = findUnpushableNodeKind;
|
package/dist/guard.d.cts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { SqlCompileOptions } from "./options.cjs";
|
|
2
|
+
import { PredicateNode } from "trilean";
|
|
3
|
+
//#region src/guard.d.ts
|
|
4
|
+
/** Where the walk stopped, and why. `kind` is the offending node's own `kind` even when the objection is not to the kind itself. */
|
|
5
|
+
interface UnpushableNode {
|
|
6
|
+
kind: string;
|
|
7
|
+
/** A dotted path from the root of the tree, e.g. `$.operands[1].left`. */
|
|
8
|
+
path: string;
|
|
9
|
+
reason: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Walks the tree against the allow-list of what this compiler translates, and reports the first node it will not.
|
|
13
|
+
*
|
|
14
|
+
* The walk is an allow-list rather than a deny-list on purpose: a node kind added to trilean after this package was written is refused by default, instead of falling through to whatever branch happened to be last. That is the difference between a caller learning it must evaluate in process and a caller silently receiving a `WHERE` clause that answers a different question.
|
|
15
|
+
*
|
|
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
|
+
*
|
|
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
|
+
declare function findUnpushableNodeKind(node: PredicateNode, options?: SqlCompileOptions): UnpushableNode | undefined;
|
|
21
|
+
//#endregion
|
|
22
|
+
export { UnpushableNode, findUnpushableNodeKind };
|
package/dist/guard.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { SqlCompileOptions } from "./options.js";
|
|
2
|
+
import { PredicateNode } from "trilean";
|
|
3
|
+
//#region src/guard.d.ts
|
|
4
|
+
/** Where the walk stopped, and why. `kind` is the offending node's own `kind` even when the objection is not to the kind itself. */
|
|
5
|
+
interface UnpushableNode {
|
|
6
|
+
kind: string;
|
|
7
|
+
/** A dotted path from the root of the tree, e.g. `$.operands[1].left`. */
|
|
8
|
+
path: string;
|
|
9
|
+
reason: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Walks the tree against the allow-list of what this compiler translates, and reports the first node it will not.
|
|
13
|
+
*
|
|
14
|
+
* The walk is an allow-list rather than a deny-list on purpose: a node kind added to trilean after this package was written is refused by default, instead of falling through to whatever branch happened to be last. That is the difference between a caller learning it must evaluate in process and a caller silently receiving a `WHERE` clause that answers a different question.
|
|
15
|
+
*
|
|
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
|
+
*
|
|
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
|
+
declare function findUnpushableNodeKind(node: PredicateNode, options?: SqlCompileOptions): UnpushableNode | undefined;
|
|
21
|
+
//#endregion
|
|
22
|
+
export { UnpushableNode, findUnpushableNodeKind };
|
package/dist/guard.js
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
//#region src/guard.ts
|
|
2
|
+
const STATIC_KIND_OF_PARAM_TYPE = {
|
|
3
|
+
text: "text",
|
|
4
|
+
number: "number",
|
|
5
|
+
boolean: "boolean",
|
|
6
|
+
timestamp: "instant"
|
|
7
|
+
};
|
|
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 PostgreSQL answers them, so a boolean operand under one of these is a real divergence rather than a stylistic one. */
|
|
9
|
+
const ORDERING_OPERATORS = /* @__PURE__ */ new Set([
|
|
10
|
+
"gt",
|
|
11
|
+
"gte",
|
|
12
|
+
"lt",
|
|
13
|
+
"lte"
|
|
14
|
+
]);
|
|
15
|
+
/** A literal's own node kind is its value's kind. Written as a lookup rather than a switch so that every other expression kind falls out as "not statically knowable" by absence, which is the honest answer for all of them, rather than needing a branch each. */
|
|
16
|
+
const STATIC_KIND_OF_LITERAL = {
|
|
17
|
+
textLiteral: "text",
|
|
18
|
+
numberLiteral: "number",
|
|
19
|
+
booleanLiteral: "boolean",
|
|
20
|
+
instantLiteral: "instant"
|
|
21
|
+
};
|
|
22
|
+
function staticValueKindOf(node, options) {
|
|
23
|
+
if (node.kind !== "reference") return STATIC_KIND_OF_LITERAL[node.kind];
|
|
24
|
+
if (options === void 0 || typeof node.key !== "string") return void 0;
|
|
25
|
+
const paramType = options.columnFor(node.key).paramType;
|
|
26
|
+
return paramType === void 0 ? void 0 : STATIC_KIND_OF_PARAM_TYPE[paramType];
|
|
27
|
+
}
|
|
28
|
+
function findUnpushableExpression(node, path) {
|
|
29
|
+
const unrecognisedKind = node.kind;
|
|
30
|
+
switch (node.kind) {
|
|
31
|
+
case "reference":
|
|
32
|
+
if (typeof node.key !== "string") return {
|
|
33
|
+
kind: node.kind,
|
|
34
|
+
path,
|
|
35
|
+
reason: "only a string reference key can be mapped to a column; this key is a non-string JSON value"
|
|
36
|
+
};
|
|
37
|
+
if (node.unit !== void 0) return {
|
|
38
|
+
kind: node.kind,
|
|
39
|
+
path,
|
|
40
|
+
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"
|
|
41
|
+
};
|
|
42
|
+
return;
|
|
43
|
+
case "numberLiteral":
|
|
44
|
+
if (node.unit !== void 0) return {
|
|
45
|
+
kind: node.kind,
|
|
46
|
+
path,
|
|
47
|
+
reason: "a unit-tagged number is only comparable with an operand of the same unit, and SQL has no unit to compare"
|
|
48
|
+
};
|
|
49
|
+
if (Number.isNaN(node.value)) return {
|
|
50
|
+
kind: node.kind,
|
|
51
|
+
path,
|
|
52
|
+
reason: "NaN is equal to nothing in trilean, not even itself, whereas PostgreSQL defines NaN as equal to itself and greater than every other double"
|
|
53
|
+
};
|
|
54
|
+
return;
|
|
55
|
+
case "textLiteral":
|
|
56
|
+
case "booleanLiteral":
|
|
57
|
+
case "instantLiteral": return;
|
|
58
|
+
case "durationLiteral": return {
|
|
59
|
+
kind: node.kind,
|
|
60
|
+
path,
|
|
61
|
+
reason: "trilean compares durations by normalising both operands to milliseconds, which has no column-level equivalent to normalise against"
|
|
62
|
+
};
|
|
63
|
+
case "complexLiteral": return {
|
|
64
|
+
kind: node.kind,
|
|
65
|
+
path,
|
|
66
|
+
reason: "PostgreSQL has no complex number type"
|
|
67
|
+
};
|
|
68
|
+
case "arithmetic":
|
|
69
|
+
case "negate": return {
|
|
70
|
+
kind: node.kind,
|
|
71
|
+
path,
|
|
72
|
+
reason: "arithmetic carries and combines units, and pushing it down would drop that dimensional analysis without saying so"
|
|
73
|
+
};
|
|
74
|
+
case "call": return {
|
|
75
|
+
kind: node.kind,
|
|
76
|
+
path,
|
|
77
|
+
reason: "a function's implementation lives in the caller's FunctionRegistry, not in the database"
|
|
78
|
+
};
|
|
79
|
+
case "lookup": return {
|
|
80
|
+
kind: node.kind,
|
|
81
|
+
path,
|
|
82
|
+
reason: "a lookup table is resolved by the caller's resolvers"
|
|
83
|
+
};
|
|
84
|
+
case "conditional": return {
|
|
85
|
+
kind: node.kind,
|
|
86
|
+
path,
|
|
87
|
+
reason: "conditional evaluation is not implemented in this version of the compiler"
|
|
88
|
+
};
|
|
89
|
+
case "fold": return {
|
|
90
|
+
kind: node.kind,
|
|
91
|
+
path,
|
|
92
|
+
reason: "a fold ranges over a collection the caller's resolvers supply, which is not this query's row set"
|
|
93
|
+
};
|
|
94
|
+
case "accumulator": return {
|
|
95
|
+
kind: node.kind,
|
|
96
|
+
path,
|
|
97
|
+
reason: "an accumulator is only meaningful inside a reduce fold"
|
|
98
|
+
};
|
|
99
|
+
case "delegate": return {
|
|
100
|
+
kind: node.kind,
|
|
101
|
+
path,
|
|
102
|
+
reason: "a delegated decision is made by an external system"
|
|
103
|
+
};
|
|
104
|
+
case "treeReference": return {
|
|
105
|
+
kind: node.kind,
|
|
106
|
+
path,
|
|
107
|
+
reason: "a referenced tree is resolved by the caller's resolvers; inline it before compiling"
|
|
108
|
+
};
|
|
109
|
+
default: return {
|
|
110
|
+
kind: unrecognisedKind,
|
|
111
|
+
path,
|
|
112
|
+
reason: "unrecognised expression node kind"
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
/** Checks the operands of a comparison-shaped predicate for a kind pairing trilean and PostgreSQL would answer differently. Returns the objection against `path` itself, since the divergence is a property of the pairing rather than of either operand alone. */
|
|
117
|
+
function findKindDivergence(kind, path, operands, options) {
|
|
118
|
+
const known = operands.map((operand) => ({
|
|
119
|
+
path: operand.path,
|
|
120
|
+
staticKind: staticValueKindOf(operand.node, options)
|
|
121
|
+
})).filter((entry) => entry.staticKind !== void 0);
|
|
122
|
+
const first = known[0];
|
|
123
|
+
if (first === void 0) return void 0;
|
|
124
|
+
const mismatched = known.find((entry) => entry.staticKind !== first.staticKind);
|
|
125
|
+
if (mismatched !== void 0) return {
|
|
126
|
+
kind,
|
|
127
|
+
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 PostgreSQL may coerce one to the other and answer definitely`
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
function findUnpushablePredicate(node, path, options) {
|
|
132
|
+
const unrecognisedKind = node.kind;
|
|
133
|
+
switch (node.kind) {
|
|
134
|
+
case "not": return findUnpushablePredicate(node.operand, `${path}.operand`, options);
|
|
135
|
+
case "and":
|
|
136
|
+
case "or": return findUnpushablePredicate(node.left, `${path}.left`, options) ?? findUnpushablePredicate(node.right, `${path}.right`, options);
|
|
137
|
+
case "allOf":
|
|
138
|
+
case "anyOf":
|
|
139
|
+
for (const [index, operand] of node.operands.entries()) {
|
|
140
|
+
const unpushable = findUnpushablePredicate(operand, `${path}.operands[${String(index)}]`, options);
|
|
141
|
+
if (unpushable !== void 0) return unpushable;
|
|
142
|
+
}
|
|
143
|
+
return;
|
|
144
|
+
case "compare": {
|
|
145
|
+
const operands = [{
|
|
146
|
+
node: node.left,
|
|
147
|
+
path: `${path}.left`
|
|
148
|
+
}, {
|
|
149
|
+
node: node.right,
|
|
150
|
+
path: `${path}.right`
|
|
151
|
+
}];
|
|
152
|
+
for (const operand of operands) {
|
|
153
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
154
|
+
if (unpushable !== void 0) return unpushable;
|
|
155
|
+
}
|
|
156
|
+
const divergence = findKindDivergence(node.kind, path, operands, options);
|
|
157
|
+
if (divergence !== void 0) return divergence;
|
|
158
|
+
for (const operand of operands) {
|
|
159
|
+
const staticKind = staticValueKindOf(operand.node, options);
|
|
160
|
+
if (staticKind === "text") return {
|
|
161
|
+
kind: node.kind,
|
|
162
|
+
path,
|
|
163
|
+
reason: `'compare' never compares text in trilean -- it returns wrong-type and directs the caller to 'textCompare' -- but PostgreSQL would order the text operand at ${operand.path} collation-wise and answer definitely`
|
|
164
|
+
};
|
|
165
|
+
if (staticKind === "boolean" && ORDERING_OPERATORS.has(node.op)) return {
|
|
166
|
+
kind: node.kind,
|
|
167
|
+
path,
|
|
168
|
+
reason: `booleans have no ordering in trilean, so '${node.op}' against the boolean operand at ${operand.path} is wrong-type there, whereas PostgreSQL orders false before true`
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
return;
|
|
172
|
+
}
|
|
173
|
+
case "textCompare": {
|
|
174
|
+
const operands = [{
|
|
175
|
+
node: node.left,
|
|
176
|
+
path: `${path}.left`
|
|
177
|
+
}, {
|
|
178
|
+
node: node.right,
|
|
179
|
+
path: `${path}.right`
|
|
180
|
+
}];
|
|
181
|
+
for (const operand of operands) {
|
|
182
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
183
|
+
if (unpushable !== void 0) return unpushable;
|
|
184
|
+
const staticKind = staticValueKindOf(operand.node, options);
|
|
185
|
+
if (staticKind !== void 0 && staticKind !== "text") return {
|
|
186
|
+
kind: node.kind,
|
|
187
|
+
path,
|
|
188
|
+
reason: `'textCompare' requires text operands in trilean, and the operand at ${operand.path} is a '${staticKind}' value`
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
return;
|
|
192
|
+
}
|
|
193
|
+
case "memberOf": {
|
|
194
|
+
const operands = [{
|
|
195
|
+
node: node.operand,
|
|
196
|
+
path: `${path}.operand`
|
|
197
|
+
}, ...node.candidates.map((candidate, index) => ({
|
|
198
|
+
node: candidate,
|
|
199
|
+
path: `${path}.candidates[${String(index)}]`
|
|
200
|
+
}))];
|
|
201
|
+
for (const operand of operands) {
|
|
202
|
+
const unpushable = findUnpushableExpression(operand.node, operand.path);
|
|
203
|
+
if (unpushable !== void 0) return unpushable;
|
|
204
|
+
}
|
|
205
|
+
return findKindDivergence(node.kind, path, operands, options);
|
|
206
|
+
}
|
|
207
|
+
case "exists": return findUnpushableExpression(node.operand, `${path}.operand`);
|
|
208
|
+
case "some":
|
|
209
|
+
case "every": return {
|
|
210
|
+
kind: node.kind,
|
|
211
|
+
path,
|
|
212
|
+
reason: "quantification ranges over a collection the caller's resolvers supply, which is not this query's row set"
|
|
213
|
+
};
|
|
214
|
+
case "treeReference": return {
|
|
215
|
+
kind: node.kind,
|
|
216
|
+
path,
|
|
217
|
+
reason: "a referenced tree is resolved by the caller's resolvers; inline it before compiling"
|
|
218
|
+
};
|
|
219
|
+
default: return {
|
|
220
|
+
kind: unrecognisedKind,
|
|
221
|
+
path,
|
|
222
|
+
reason: "unrecognised predicate node kind"
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* Walks the tree against the allow-list of what this compiler translates, and reports the first node it will not.
|
|
228
|
+
*
|
|
229
|
+
* The walk is an allow-list rather than a deny-list on purpose: a node kind added to trilean after this package was written is refused by default, instead of falling through to whatever branch happened to be last. That is the difference between a caller learning it must evaluate in process and a caller silently receiving a `WHERE` clause that answers a different question.
|
|
230
|
+
*
|
|
231
|
+
* `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
|
+
*
|
|
233
|
+
* 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`).
|
|
234
|
+
*/
|
|
235
|
+
function findUnpushableNodeKind(node, options) {
|
|
236
|
+
return findUnpushablePredicate(node, "$", options);
|
|
237
|
+
}
|
|
238
|
+
//#endregion
|
|
239
|
+
export { findUnpushableNodeKind };
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
+
const require_errors = require("./errors.cjs");
|
|
3
|
+
const require_guard = require("./guard.cjs");
|
|
4
|
+
const require_compile = require("./compile.cjs");
|
|
5
|
+
exports.InvalidColumnError = require_errors.InvalidColumnError;
|
|
6
|
+
exports.TrileanSqlError = require_errors.TrileanSqlError;
|
|
7
|
+
exports.UnsupportedNodeError = require_errors.UnsupportedNodeError;
|
|
8
|
+
exports.compilePredicateNode = require_compile.compilePredicateNode;
|
|
9
|
+
exports.findUnpushableNodeKind = require_guard.findUnpushableNodeKind;
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { CompiledSql, SqlColumnBinding, SqlCompileOptions, SqlParamType } from "./options.cjs";
|
|
2
|
+
import { compilePredicateNode } from "./compile.cjs";
|
|
3
|
+
import { InvalidColumnError, TrileanSqlError, UnsupportedNodeError } from "./errors.cjs";
|
|
4
|
+
import { UnpushableNode, findUnpushableNodeKind } from "./guard.cjs";
|
|
5
|
+
export { type CompiledSql, InvalidColumnError, type SqlColumnBinding, type SqlCompileOptions, type SqlParamType, TrileanSqlError, type UnpushableNode, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { CompiledSql, SqlColumnBinding, SqlCompileOptions, SqlParamType } from "./options.js";
|
|
2
|
+
import { compilePredicateNode } from "./compile.js";
|
|
3
|
+
import { InvalidColumnError, TrileanSqlError, UnsupportedNodeError } from "./errors.js";
|
|
4
|
+
import { UnpushableNode, findUnpushableNodeKind } from "./guard.js";
|
|
5
|
+
export { type CompiledSql, InvalidColumnError, type SqlColumnBinding, type SqlCompileOptions, type SqlParamType, TrileanSqlError, type UnpushableNode, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { InvalidColumnError, TrileanSqlError, UnsupportedNodeError } from "./errors.js";
|
|
2
|
+
import { findUnpushableNodeKind } from "./guard.js";
|
|
3
|
+
import { compilePredicateNode } from "./compile.js";
|
|
4
|
+
export { InvalidColumnError, TrileanSqlError, UnsupportedNodeError, compilePredicateNode, findUnpushableNodeKind };
|
package/dist/options.cjs
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
+
//#region src/options.ts
|
|
3
|
+
/** 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
|
+
const POSTGRES_TYPE_NAME = {
|
|
5
|
+
text: "text",
|
|
6
|
+
number: "double precision",
|
|
7
|
+
boolean: "boolean",
|
|
8
|
+
timestamp: "timestamptz"
|
|
9
|
+
};
|
|
10
|
+
//#endregion
|
|
11
|
+
exports.POSTGRES_TYPE_NAME = POSTGRES_TYPE_NAME;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
//#region src/options.d.ts
|
|
2
|
+
/** The declared SQL value kind of a mapped column. `"timestamp"` names trilean's `instant` kind, whose values are ISO-8601 strings. */
|
|
3
|
+
type SqlParamType = "text" | "number" | "boolean" | "timestamp";
|
|
4
|
+
/** What a `reference` node's key maps onto in the target schema. */
|
|
5
|
+
interface SqlColumnBinding {
|
|
6
|
+
/** 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
|
+
column: string;
|
|
8
|
+
/**
|
|
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 PostgreSQL may coerce its way to a definite answer where trilean would have returned indeterminate.
|
|
10
|
+
*
|
|
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.
|
|
12
|
+
*/
|
|
13
|
+
paramType?: SqlParamType;
|
|
14
|
+
}
|
|
15
|
+
interface SqlCompileOptions {
|
|
16
|
+
/** PostgreSQL is the only dialect implemented. It is a required field rather than a default so that adding a second dialect later is a new value here, not a change of behaviour for callers who never said which one they meant. */
|
|
17
|
+
dialect: "postgres";
|
|
18
|
+
/**
|
|
19
|
+
* Maps a `reference` node's key onto a column. Called once per reference occurrence.
|
|
20
|
+
*
|
|
21
|
+
* 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
|
+
*/
|
|
23
|
+
columnFor: (referenceKey: string) => SqlColumnBinding;
|
|
24
|
+
}
|
|
25
|
+
interface CompiledSql {
|
|
26
|
+
/** 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
|
+
sql: string;
|
|
28
|
+
/** Positional parameters, in `$1`-first order, to pass alongside `sql`. Every caller-supplied literal in the tree is here; none is ever written into `sql`. */
|
|
29
|
+
params: unknown[];
|
|
30
|
+
}
|
|
31
|
+
/** 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
|
+
declare const POSTGRES_TYPE_NAME: Readonly<Record<SqlParamType, string>>;
|
|
33
|
+
//#endregion
|
|
34
|
+
export { CompiledSql, POSTGRES_TYPE_NAME, SqlColumnBinding, SqlCompileOptions, SqlParamType };
|