trilean-sql 3.0.4 → 3.0.6
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 +2 -2
- package/dist/compile.js +1 -1
- package/dist/{guard-CZ7Cvyh2.js → guard-nU_rPgh2.js} +19 -1
- package/dist/guard.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -97,7 +97,7 @@ Passing `options` widens the check: without them the walk is purely structural;
|
|
|
97
97
|
|
|
98
98
|
### Errors
|
|
99
99
|
|
|
100
|
-
`UnsupportedNodeError` (carrying `nodeKind`, `path`, `reason`), `InvalidColumnError` (carrying `referenceKey`, `column`) and `InvalidCollectionTableError` (carrying `collectionKey`, `table`), all extending `TrileanSqlError`. The last two are thrown for a name that cannot be rendered as an identifier, and never repeat the name in their message (a message does name the reference key or collection key the mapping was asked about, which are the tree's own keys, and never a name or value taken from data): an empty name or dot-separated segment, a NUL character, an unpaired UTF-16 surrogate,
|
|
100
|
+
`UnsupportedNodeError` (carrying `nodeKind`, `path`, `reason`), `InvalidColumnError` (carrying `referenceKey`, `column`) and `InvalidCollectionTableError` (carrying `collectionKey`, `table`), all extending `TrileanSqlError`. The last two are thrown for a name that cannot be rendered as an identifier, and never repeat the name in their message (a message does name the reference key or collection key the mapping was asked about, which are the tree's own keys, and never a name or value taken from data): an empty name or dot-separated segment, a NUL character, an unpaired UTF-16 surrogate, more segments than the dialect accepts, or, for PostgreSQL, a segment of more than 63 bytes in UTF-8 (PostgreSQL keeps at most 63 bytes of an identifier, which is its default `NAMEDATALEN` of 64 less one and is fixed when the server is compiled, so a server built with another value keeps another number of bytes and this limit assumes the default; it cuts a longer name silently, so two names that agree in their first 63 bytes would name one column: [lexical structure](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS); SQLite has no such limit) (at most `schema.table.column` for a column and `schema.table` for a table, in both dialects: [SQLite](https://www.sqlite.org/lang_expr.html) accepts no more; [PostgreSQL](https://www.postgresql.org/docs/current/ddl-schemas.html) says that a leading database name "must be the same as the database you are connected to", which the compiler cannot know, so a leading database segment is refused and the caller omits it). Neither engine carries the NUL character inside a quoted identifier ([PostgreSQL](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS), [SQLite](https://www.sqlite.org/c3ref/prepare.html)), and an unpaired surrogate has no UTF-8 form, the encoding both read the statement in. `findUnpushableNodeKind` refuses the same names, so the guard and the compiler agree.
|
|
101
101
|
|
|
102
102
|
**Values.** A text, pattern or instant literal holding an unpaired surrogate is refused for both dialects, since a driver replaces it with U+FFFD and the engine would compare another value than the evaluator saw. A literal holding the NUL character is refused for PostgreSQL, which rejects it with an invalid byte sequence error, and compiles for SQLite, which binds and compares it as text. The pattern of `portableMatches` and `portableNotMatches` is stricter, because it compiles to SQLite's `GLOB`, which reads a pattern only up to its first NUL: a pattern with one is refused for SQLite too. The pattern of `matches` and `notMatches` is an argument of the `regexp` function the caller registers, which receives it whole, so it compiles for SQLite. The subject of a `portableMatches`/`portableNotMatches` under SQLite is read by `GLOB` the same way, so it is wrapped in a subquery that makes a stored value holding a NUL unknown for that comparison (and for its negation): it never selects a row the evaluator would not select, and the evaluator itself would match such a value, so a stored text with a NUL is the one case the SQLite dialect cannot answer as the evaluator does. The wrapper costs an index: SQLite searches an index on the column for a prefix pattern such as `ENA-*`, and with the wrapper it reads every row and evaluates one subquery for each. Where that matters, leave `portableMatches` to in-process evaluation for SQLite on a large table.
|
|
103
103
|
|
|
@@ -134,7 +134,7 @@ interface SqlCollectionBinding {
|
|
|
134
134
|
}
|
|
135
135
|
```
|
|
136
136
|
|
|
137
|
-
`join` is caller-authored rather than assembled from a join-column pair, because only the caller knows the real join shape — a single foreign key, a composite key, or an entity-attribute-value table's foreign key plus a literal discriminator (`"attrs"."nodeId" = "graph_nodes"."id" AND "attrs"."attrName" = 'voltageLevel'`). `columnFor` is a second, independent mapping from the outer one: it resolves a reference inside the collection's own `item`/`filter`, exactly as trilean's own evaluator re-points its `EvaluationContext` at the collection item before evaluating either. A tree that never uses `some`, `every`, or `fold(max|min)` never calls `collectionFor` — leaving it unset is fully backward compatible. A tree that does use one of those kinds without it set is refused with `UnsupportedNodeError`, the same refused outcome those kinds had before this option existed.
|
|
137
|
+
`join` is caller-authored rather than assembled from a join-column pair, because only the caller knows the real join shape — a single foreign key, a composite key, or an entity-attribute-value table's foreign key plus a literal discriminator (`"attrs"."nodeId" = "graph_nodes"."id" AND "attrs"."attrName" = 'voltageLevel'`). `columnFor` is a second, independent mapping from the outer one: it resolves a reference inside the collection's own `item`/`filter`, exactly as trilean's own evaluator re-points its `EvaluationContext` at the collection item before evaluating either. A tree that never uses `some`, `every`, or `fold(max|min)` never calls `collectionFor` — leaving it unset is fully backward compatible. A tree that does use one of those kinds without it set is refused with `UnsupportedNodeError`, the same refused outcome those kinds had before this option existed. The one thing judged is whether the text can be carried: a `join` holding the NUL character (which ends the statement text SQLite is given and which PostgreSQL does not accept) or an unpaired UTF-16 surrogate (which has no UTF-8 form) is refused, in both dialects, with an `UnsupportedNodeError` whose reason names the join, never repeats it, and `findUnpushableNodeKind` refuses the same tree.
|
|
138
138
|
|
|
139
139
|
`some`/`every` compile to a correlated scalar subquery: `SELECT filter, item FROM table WHERE join`, filtered down to the participating rows (`filter IS NULL OR filter`, dropping only the rows `filter` excluded outright), then combined with `MAX`/`CASE` to match the evaluator's own OR/AND-fold absorption exactly — `some` is true the moment any participating row's `item` is true, regardless of another row's indeterminacy; indeterminate only once no row voted true and at least one participated indeterminately (an indeterminate `filter`, or an indeterminate `item`); false once neither, including an empty participating set (no rows, or every row filtered out), which is `some`'s own identity. `every` is the mirror image: false the moment any participating row's `item` is definitely false, indeterminate only once neither that nor "every row voted true" holds, and true — including on an empty participating set — otherwise.
|
|
140
140
|
|
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-nU_rPgh2.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";
|
|
@@ -8,6 +8,7 @@ import { parseRegex } from "trilean-regex";
|
|
|
8
8
|
* The reasons describe the character or the count and never repeat the input, so an error built from one cannot carry a caller's value into a log.
|
|
9
9
|
*/
|
|
10
10
|
const NUL = "\0";
|
|
11
|
+
const encoder = new TextEncoder();
|
|
11
12
|
/** The most dot-separated segments a column may have: `schema.table.column`. SQLite's expression syntax is `schema-name.table-name.column-name` (https://www.sqlite.org/lang_expr.html). PostgreSQL's page on schemas says that "the even more general syntax database.schema.table can be used too, but at present this is just for pro forma compliance with the SQL standard. If you write a database name, it must be the same as the database you are connected to" (https://www.postgresql.org/docs/current/ddl-schemas.html). The compiler does not know the database the connection is on, so a leading database segment is refused as a choice, and the caller omits it. */
|
|
12
13
|
const MAX_COLUMN_SEGMENTS = {
|
|
13
14
|
postgres: 3,
|
|
@@ -21,7 +22,7 @@ const MAX_TABLE_SEGMENTS = {
|
|
|
21
22
|
/**
|
|
22
23
|
* Why a column or table name cannot be rendered as a quoted identifier for `dialect`, or `undefined` when it can.
|
|
23
24
|
*
|
|
24
|
-
* Refused: an empty name or segment; the NUL character, which neither engine accepts in a quoted identifier (PostgreSQL: "Quoted identifiers can contain any character, except the character with code zero", https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS) and which ends the statement text SQLite is given ("zSql is read up to the first zero terminator", https://www.sqlite.org/c3ref/prepare.html); an unpaired UTF-16 surrogate, which has no UTF-8 form, the encoding both engines read the statement in;
|
|
25
|
+
* Refused: an empty name or segment; the NUL character, which neither engine accepts in a quoted identifier (PostgreSQL: "Quoted identifiers can contain any character, except the character with code zero", https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS) and which ends the statement text SQLite is given ("zSql is read up to the first zero terminator", https://www.sqlite.org/c3ref/prepare.html); an unpaired UTF-16 surrogate, which has no UTF-8 form, the encoding both engines read the statement in; more segments than the dialect accepts; and, for PostgreSQL, a segment of more than {@link POSTGRES_IDENTIFIER_BYTES} bytes in UTF-8. Every other character, a quote included, is carried by doubling the quote.
|
|
25
26
|
*/
|
|
26
27
|
function identifierProblem(role, name, dialect) {
|
|
27
28
|
if (name.length === 0) return "the name is empty";
|
|
@@ -31,6 +32,10 @@ function identifierProblem(role, name, dialect) {
|
|
|
31
32
|
if (segments.some((segment) => segment.length === 0)) return "a dot-separated segment is empty";
|
|
32
33
|
const most = role === "column" ? MAX_COLUMN_SEGMENTS[dialect] : MAX_TABLE_SEGMENTS[dialect];
|
|
33
34
|
if (segments.length > most) return dialect === "postgres" ? `the name has ${String(segments.length)} dot-separated segments and at most ${String(most)} are accepted for a ${role}: PostgreSQL takes a leading database name only when it is the database the connection is on, which the compiler cannot know` : `the name has ${String(segments.length)} dot-separated segments and SQLite accepts at most ${String(most)} for a ${role}`;
|
|
35
|
+
if (dialect === "postgres") {
|
|
36
|
+
const longest = Math.max(...segments.map((segment) => encoder.encode(segment).length));
|
|
37
|
+
if (longest > 63) return `a dot-separated segment of the name is ${String(longest)} bytes in UTF-8 and PostgreSQL keeps at most ${String(63)} bytes of an identifier, so a longer name is cut short and two names that agree in their first ${String(63)} bytes would be one`;
|
|
38
|
+
}
|
|
34
39
|
}
|
|
35
40
|
/**
|
|
36
41
|
* Why a text, pattern or instant value cannot be bound for `dialect`, or `undefined` when it can.
|
|
@@ -43,6 +48,13 @@ function valueProblem(value, dialect, role) {
|
|
|
43
48
|
if (dialect === "postgres") return "PostgreSQL cannot carry the NUL character in a text value and rejects the statement with an invalid byte sequence error";
|
|
44
49
|
return role === "glob-pattern" ? "SQLite's GLOB reads a pattern only up to its first NUL character, so the pattern would match as a shorter one" : void 0;
|
|
45
50
|
}
|
|
51
|
+
/**
|
|
52
|
+
* Why SQL text a caller wrote, which the compiler writes into the statement as given (a collection's `join`), cannot be carried, or `undefined` when it can. The same two classes a name is refused for apply, in both dialects: the NUL character, which ends the statement text SQLite is given ("zSql is read up to the first zero terminator", https://www.sqlite.org/c3ref/prepare.html) and which PostgreSQL does not accept in a statement (a string constant "cannot contain the character with code zero", https://www.postgresql.org/docs/current/sql-syntax-lexical.html), so the engine would read a statement other than the one compiled; and an unpaired UTF-16 surrogate, which has no UTF-8 form, the encoding both engines read the statement in. Nothing else of the text is judged: it is the caller's SQL.
|
|
53
|
+
*/
|
|
54
|
+
function statementTextProblem(text) {
|
|
55
|
+
if (text.includes(NUL)) return "the SQL text contains a NUL character, which a statement cannot carry";
|
|
56
|
+
if (!text.isWellFormed()) return "the SQL text contains an unpaired surrogate, which has no UTF-8 form";
|
|
57
|
+
}
|
|
46
58
|
// src/guard.ts
|
|
47
59
|
const STATIC_KIND_OF_PARAM_TYPE = {
|
|
48
60
|
text: "text",
|
|
@@ -116,6 +128,12 @@ function resolveCollectionForGuard(kind, collection, path, options) {
|
|
|
116
128
|
problem: tableProblem
|
|
117
129
|
}
|
|
118
130
|
};
|
|
131
|
+
const joinProblem = statementTextProblem(binding.join);
|
|
132
|
+
if (joinProblem !== void 0) return {
|
|
133
|
+
kind,
|
|
134
|
+
path,
|
|
135
|
+
reason: `the join mapped for this collection cannot be used: ${joinProblem}`
|
|
136
|
+
};
|
|
119
137
|
return { itemOptions: {
|
|
120
138
|
...options,
|
|
121
139
|
columnFor: binding.columnFor
|
package/dist/guard.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { t as findUnpushableNodeKind } from "./guard-
|
|
1
|
+
export { t as findUnpushableNodeKind } from "./guard-nU_rPgh2.js";
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { t as findUnpushableNodeKind } from "./guard-
|
|
1
|
+
import { t as findUnpushableNodeKind } from "./guard-nU_rPgh2.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,7 +1,7 @@
|
|
|
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.6",
|
|
5
5
|
"bugs": {
|
|
6
6
|
"url": "https://github.com/ExaDev/trilean/issues"
|
|
7
7
|
},
|