trilean-sql 1.1.0 → 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 CHANGED
@@ -123,7 +123,7 @@ What compiles, what is refused, and the row-for-row agreement with `evaluatePred
123
123
 
124
124
  Two things a SQLite caller has to supply that a PostgreSQL caller does not, both of which fail loudly rather than silently:
125
125
 
126
- - **A `REGEXP` function**, if the tree uses `matches` or `notMatches`. See [Regular expressions](#regular-expressions).
126
+ - **A `REGEXP` function**, if the tree uses `matches` or `notMatches` — unless you set `sqliteRegexpAvailable: false`, in which case those two are refused at compile time instead. See [Regular expressions](#regular-expressions).
127
127
  - **Booleans bound as `0`/`1`.** SQLite has no boolean type, and drivers do not agree on whether a JS boolean is bindable at all — better-sqlite3 rejects one outright (*"SQLite3 can only bind numbers, strings, bigints, buffers, and null"*). `params` carries the tree's own literals unchanged in every dialect, so converting them is the binding caller's job: `params.map((v) => (typeof v === "boolean" ? Number(v) : v))`.
128
128
 
129
129
  A dialect this version does not implement is refused by name, from `compilePredicateNode` and `findUnpushableNodeKind` alike, with `UnknownDialectError`. `SqlDialect` is a closed union so TypeScript source cannot reach that, but a dialect read from configuration and asserted into the union at the boundary can, and reporting such a tree as pushable would promise a compilation that cannot happen.
@@ -173,6 +173,8 @@ db.function("regexp", (pattern, text) =>
173
173
 
174
174
  Both details are load-bearing rather than stylistic. Returning `null` for a NULL argument is what keeps the third value intact: SQLite does not propagate NULL through a user function on its own, so one answering `0` for a NULL value would make `NOT REGEXP` answer `TRUE` for a row whose value is unknown — the two-valued collapse this package exists to avoid. Returning `1`/`0` rather than a JS boolean is what better-sqlite3 accepts; a boolean is rejected from a user function (*"returned an invalid value"*) for the same reason it is rejected as a bound parameter.
175
175
 
176
+ Some SQLite-wire-compatible targets have no way to register a function at all — Cloudflare D1's Workers Binding API is the motivating case, with no hook for it in its API and [cloudflare/workers-sdk#2802](https://github.com/cloudflare/workers-sdk/issues/2802) still open. Against a target like that, the registration above is simply not possible, and compiling `matches`/`notMatches` to `REGEXP`/`NOT REGEXP` anyway produces SQL that always fails at query execution with `no such function: REGEXP` rather than failing at compile time the way every other unpushable shape does. Set `sqliteRegexpAvailable: false` in `SqlCompileOptions` for a target like this, and the SQLite dialect refuses `matches`/`notMatches` with `UnsupportedNodeError` — and `findUnpushableNodeKind` reports them unpushable — at compile time instead, so the caller falls back to in-process evaluation the same way it would for any other unpushable node. It defaults to `true`, so a caller with a registered function (better-sqlite3, say) sees no change. It has no effect under the `postgres` dialect, which never needs a registered function in the first place.
177
+
176
178
  ## Tests
177
179
 
178
180
  The unit suite asserts compiled SQL text and parameter arrays per node kind. It cannot, on its own, establish anything about three-valued behaviour: `("age" > $1)` is only indeterminate-preserving because of what PostgreSQL's planner does with a `NULL` age, which is a fact about PostgreSQL rather than about the string.
package/dist/compile.cjs CHANGED
@@ -138,7 +138,8 @@ function compilePredicateNode(node, options) {
138
138
  const binding = options.columnFor(referenceKey);
139
139
  bindings.set(referenceKey, binding);
140
140
  return binding;
141
- }
141
+ },
142
+ sqliteRegexpAvailable: options.sqliteRegexpAvailable
142
143
  };
143
144
  const unpushable = require_guard.findUnpushableNodeKind(node, memoised);
144
145
  if (unpushable !== void 0) throw new require_errors.UnsupportedNodeError(unpushable);
package/dist/compile.js CHANGED
@@ -137,7 +137,8 @@ function compilePredicateNode(node, options) {
137
137
  const binding = options.columnFor(referenceKey);
138
138
  bindings.set(referenceKey, binding);
139
139
  return binding;
140
- }
140
+ },
141
+ sqliteRegexpAvailable: options.sqliteRegexpAvailable
141
142
  };
142
143
  const unpushable = findUnpushableNodeKind(node, memoised);
143
144
  if (unpushable !== void 0) throw new UnsupportedNodeError(unpushable);
package/dist/guard.cjs CHANGED
@@ -189,6 +189,11 @@ function findUnpushablePredicate(node, path, options, divergence) {
189
189
  return;
190
190
  }
191
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
+ };
192
197
  const operands = [{
193
198
  node: node.left,
194
199
  path: `${path}.left`
package/dist/guard.js CHANGED
@@ -188,6 +188,11 @@ function findUnpushablePredicate(node, path, options, divergence) {
188
188
  return;
189
189
  }
190
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
+ };
191
196
  const operands = [{
192
197
  node: node.left,
193
198
  path: `${path}.left`
@@ -23,6 +23,12 @@ interface SqlCompileOptions {
23
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.
24
24
  */
25
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;
26
32
  }
27
33
  interface CompiledSql {
28
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. */
package/dist/options.d.ts CHANGED
@@ -23,6 +23,12 @@ interface SqlCompileOptions {
23
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.
24
24
  */
25
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;
26
32
  }
27
33
  interface CompiledSql {
28
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. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "trilean-sql",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "repository": {