@pikku/kysely-node-sqlite 0.12.3 → 0.12.4

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @pikku/kysely-node-sqlite
 
+## 0.12.4
+
+### Patch Changes
+
+- 9d62571: Make user-defined SQL functions an explicit, checked capability of the SQLite drivers.
+
+  `node:sqlite` can register scalar UDFs (`db.function()`); `bun:sqlite` cannot. Until now
+  neither driver mentioned that, so an app that registered a UDF by reaching for the raw
+  connection worked on Node and, on bun, failed as `no such function: …` from whichever
+  query used it — typically one endpoint breaking in production while everything else
+  looked healthy.
+
+  Both drivers now export `registerSqliteFunctions(db, functions)` and accept a
+  `functions` option on `createNodeSqliteKysely` / `createBunSqliteKysely`. The Node
+  implementation registers them as deterministic; the bun implementation throws
+  `SqliteFunctionsUnsupportedError` — exported from `@pikku/kysely-sqlite`, and naming
+  every function requested — so the incompatibility surfaces at wiring time with a message
+  saying what to do about it.
+
+- Updated dependencies [32277d5]
+- Updated dependencies [ea8aabf]
+- Updated dependencies [33e96ab]
+- Updated dependencies [fd72e58]
+- Updated dependencies [cabd9dc]
+- Updated dependencies [fd72e58]
+- Updated dependencies [fd72e58]
+- Updated dependencies [894b2f8]
+- Updated dependencies [dd19aa7]
+- Updated dependencies [50ec500]
+- Updated dependencies [9d62571]
+  - @pikku/core@0.12.75
+  - @pikku/kysely@0.13.8
+  - @pikku/kysely-sqlite@0.12.10
+
 ## 0.12.3
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 - present Yasser Fadl and Pikku contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @pikku/kysely-node-sqlite
+
+Kysely driver for Pikku backed by Node's built-in `node:sqlite` module — no
+native dependency to install or compile.
+
+Ships a coercion plugin that maps SQLite's storage classes back to the types
+your schema declares (booleans, dates, JSON).
+
+## Install
+
+```bash
+npm install @pikku/kysely-node-sqlite
+```
+
+Requires a Node version with `node:sqlite` available.
+
+## Usage
+
+```typescript
+import { createNodeSqliteKysely } from '@pikku/kysely-node-sqlite'
+import type { KyselyPikkuDB } from '@pikku/kysely'
+
+const db = createNodeSqliteKysely<KyselyPikkuDB>({
+  filename: 'app.db',
+})
+```
+
+`camelCase` (default `true`) applies Kysely's `CamelCasePlugin`; pass extra
+`plugins` to layer more on top. Use `':memory:'` for an in-memory database.
+
+## User-defined SQL functions
+
+`node:sqlite` can register scalar functions, so SQL can call your own code:
+
+```typescript
+const db = createNodeSqliteKysely<KyselyPikkuDB>({
+  filename: 'app.db',
+  functions: {
+    similarity: (a, b) => trigramSimilarity(String(a), String(b)),
+  },
+})
+```
+
+They are registered as **deterministic**, which is what allows SQLite to use
+them in an index and to cache repeated calls. Do not register a function whose
+result depends on the clock, a random source, or anything mutable.
+
+If you build the connection yourself — as you must when you need pragmas like
+WAL or `busy_timeout` — call `registerSqliteFunctions(db, { … })` on it directly.
+
+**This option has no bun equivalent.** `bun:sqlite` cannot register functions at
+all, so `@pikku/kysely-bun-sqlite` throws `SqliteFunctionsUnsupportedError`
+rather than accepting them. Using this is a decision to stay on Node; if you may
+want to move, do the computation outside SQL over an indexed candidate set
+instead.
+
+## Docs
+
+https://pikku.dev/docs

package/dist/src/create-node-sqlite-kysely.d.ts

@@ -1,4 +1,5 @@
 import { Kysely, type KyselyPlugin } from 'kysely';
+import type { SqliteFunctionMap } from '@pikku/kysely-sqlite';
 export interface CreateNodeSqliteKyselyOptions {
     /** Path to the SQLite file. Use ':memory:' for an in-memory DB. */
     filename: string;
@@ -6,5 +7,14 @@ export interface CreateNodeSqliteKyselyOptions {
     camelCase?: boolean;
     /** Extra plugins to layer on top. */
     plugins?: KyselyPlugin[];
+    /**
+     * Scalar user-defined SQL functions to register, keyed by the name SQL calls
+     * them by. Registered as deterministic.
+     *
+     * Note that this is the one option with no bun equivalent:
+     * `createBunSqliteKysely` throws if it is set, because bun:sqlite cannot
+     * register functions. Using it is a decision to stay on Node.
+     */
+    functions?: SqliteFunctionMap;
 }
 export declare function createNodeSqliteKysely<DB>(options: CreateNodeSqliteKyselyOptions): Kysely<DB>;

package/dist/src/create-node-sqlite-kysely.js

@@ -1,8 +1,11 @@
 import { DatabaseSync } from 'node:sqlite';
 import { Kysely, SqliteDialect, CamelCasePlugin, } from 'kysely';
 import { NodeSqliteDatabase } from './node-sqlite-adapter.js';
+import { registerSqliteFunctions } from './register-functions.js';
 export function createNodeSqliteKysely(options) {
     const db = new DatabaseSync(options.filename);
+    if (options.functions)
+        registerSqliteFunctions(db, options.functions);
     const plugins = [];
     if (options.camelCase ?? true)
         plugins.push(new CamelCasePlugin());

package/dist/src/index.d.ts

@@ -1,3 +1,5 @@
 export { NodeSqliteDatabase } from './node-sqlite-adapter.js';
 export { createNodeSqliteKysely, type CreateNodeSqliteKyselyOptions, } from './create-node-sqlite-kysely.js';
+export { registerSqliteFunctions } from './register-functions.js';
+export { SqliteFunctionsUnsupportedError, type SqliteFunction, type SqliteFunctionMap, } from '@pikku/kysely-sqlite';
 export { createCoercionPlugin, type CoercionMap, type ColumnKind, type CreateCoercionPluginOptions, } from './coercion-plugin.js';

package/dist/src/index.js

@@ -1,3 +1,5 @@
 export { NodeSqliteDatabase } from './node-sqlite-adapter.js';
 export { createNodeSqliteKysely, } from './create-node-sqlite-kysely.js';
+export { registerSqliteFunctions } from './register-functions.js';
+export { SqliteFunctionsUnsupportedError, } from '@pikku/kysely-sqlite';
 export { createCoercionPlugin, } from './coercion-plugin.js';

package/dist/src/register-functions.d.ts

@@ -0,0 +1,19 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { SqliteFunctionMap } from '@pikku/kysely-sqlite';
+/**
+ * Registers scalar user-defined SQL functions on a node:sqlite connection.
+ *
+ * Exported separately from `createNodeSqliteKysely` because an app that needs
+ * pragmas — WAL, `foreign_keys`, `busy_timeout` — has to build the connection
+ * itself, and would otherwise have no supported way to add UDFs to it.
+ *
+ * Registered as `deterministic`, which is what makes them usable in indexes and
+ * lets SQLite cache repeated calls with the same arguments. That is a promise
+ * about the function, not a hint: one whose output depends on the clock, a
+ * random source or anything mutable must not go through here.
+ *
+ * There is no bun counterpart. `@pikku/kysely-bun-sqlite` exports the same name
+ * so the import resolves either way, but it throws — see
+ * SqliteFunctionsUnsupportedError.
+ */
+export declare function registerSqliteFunctions(db: DatabaseSync, functions: SqliteFunctionMap): void;

package/dist/src/register-functions.js

@@ -0,0 +1,21 @@
+/**
+ * Registers scalar user-defined SQL functions on a node:sqlite connection.
+ *
+ * Exported separately from `createNodeSqliteKysely` because an app that needs
+ * pragmas — WAL, `foreign_keys`, `busy_timeout` — has to build the connection
+ * itself, and would otherwise have no supported way to add UDFs to it.
+ *
+ * Registered as `deterministic`, which is what makes them usable in indexes and
+ * lets SQLite cache repeated calls with the same arguments. That is a promise
+ * about the function, not a hint: one whose output depends on the clock, a
+ * random source or anything mutable must not go through here.
+ *
+ * There is no bun counterpart. `@pikku/kysely-bun-sqlite` exports the same name
+ * so the import resolves either way, but it throws — see
+ * SqliteFunctionsUnsupportedError.
+ */
+export function registerSqliteFunctions(db, functions) {
+    for (const [name, fn] of Object.entries(functions)) {
+        db.function(name, { deterministic: true }, fn);
+    }
+}

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/coercion-plugin.ts","../src/create-node-sqlite-kysely.ts","../src/index.ts","../src/node-sqlite-adapter.ts"],"version":"6.0.3"}
+{"root":["../src/coercion-plugin.ts","../src/create-node-sqlite-kysely.ts","../src/index.ts","../src/node-sqlite-adapter.ts","../src/register-functions.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pikku/kysely-node-sqlite",
-  "version": "0.12.3",
+  "version": "0.12.4",
+  "description": "Kysely driver for Pikku backed by the built-in node:sqlite module",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/src/index.js",
@@ -10,22 +11,26 @@
     "tsc": "tsc",
     "ncu": "npx npm-check-updates",
     "build": "tsc -b",
+    "test": "bash run-tests.sh",
+    "test:watch": "bash run-tests.sh --watch",
+    "test:coverage": "bash run-tests.sh --coverage",
     "prepublishOnly": "yarn build"
   },
   "engines": {
     "node": ">=22.10"
   },
   "dependencies": {
-    "@pikku/kysely": "^0.13.0",
-    "@pikku/kysely-sqlite": "^0.12.7",
+    "@pikku/kysely": "^0.13.8",
+    "@pikku/kysely-sqlite": "^0.12.10",
     "kysely": "^0.29.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.44"
+    "@pikku/core": "^0.12.75"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.44",
+    "@pikku/core": "^0.12.75",
     "@types/node": "^22",
+    "tsx": "^4.19.2",
     "typescript": "^6.0.3"
   },
   "exports": {

package/run-tests.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# Parse command line arguments
+WATCH_MODE=false
+COVERAGE_MODE=false
+
+for arg in "$@"
+do
+    case $arg in
+        --watch)
+        WATCH_MODE=true
+        shift
+        ;;
+        --coverage)
+        COVERAGE_MODE=true
+        shift
+        ;;
+    esac
+done
+
+# Build the command
+CMD="node --import tsx --test --test-force-exit src/**/*.test.ts"
+
+if [ "$WATCH_MODE" = true ]; then
+    CMD="$CMD --watch"
+fi
+
+if [ "$COVERAGE_MODE" = true ]; then
+    CMD="$CMD --experimental-test-coverage"
+fi
+
+# Execute the command
+eval $CMD

package/src/create-node-sqlite-kysely.ts

@@ -5,7 +5,9 @@ import {
   CamelCasePlugin,
   type KyselyPlugin,
 } from 'kysely'
+import type { SqliteFunctionMap } from '@pikku/kysely-sqlite'
 import { NodeSqliteDatabase } from './node-sqlite-adapter.js'
+import { registerSqliteFunctions } from './register-functions.js'
 
 export interface CreateNodeSqliteKyselyOptions {
   /** Path to the SQLite file. Use ':memory:' for an in-memory DB. */
@@ -14,12 +16,22 @@ export interface CreateNodeSqliteKyselyOptions {
   camelCase?: boolean
   /** Extra plugins to layer on top. */
   plugins?: KyselyPlugin[]
+  /**
+   * Scalar user-defined SQL functions to register, keyed by the name SQL calls
+   * them by. Registered as deterministic.
+   *
+   * Note that this is the one option with no bun equivalent:
+   * `createBunSqliteKysely` throws if it is set, because bun:sqlite cannot
+   * register functions. Using it is a decision to stay on Node.
+   */
+  functions?: SqliteFunctionMap
 }
 
 export function createNodeSqliteKysely<DB>(
   options: CreateNodeSqliteKyselyOptions
 ): Kysely<DB> {
   const db = new DatabaseSync(options.filename)
+  if (options.functions) registerSqliteFunctions(db, options.functions)
   const plugins: KyselyPlugin[] = []
   if (options.camelCase ?? true) plugins.push(new CamelCasePlugin())
   if (options.plugins) plugins.push(...options.plugins)

package/src/index.ts

@@ -3,6 +3,12 @@ export {
   createNodeSqliteKysely,
   type CreateNodeSqliteKyselyOptions,
 } from './create-node-sqlite-kysely.js'
+export { registerSqliteFunctions } from './register-functions.js'
+export {
+  SqliteFunctionsUnsupportedError,
+  type SqliteFunction,
+  type SqliteFunctionMap,
+} from '@pikku/kysely-sqlite'
 export {
   createCoercionPlugin,
   type CoercionMap,

package/src/register-functions.test.ts

@@ -0,0 +1,52 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { DatabaseSync } from 'node:sqlite'
+import { sql } from 'kysely'
+import { registerSqliteFunctions } from './register-functions.js'
+import { createNodeSqliteKysely } from './create-node-sqlite-kysely.js'
+
+describe('registerSqliteFunctions', () => {
+  test('makes the function callable from SQL', () => {
+    const db = new DatabaseSync(':memory:')
+    registerSqliteFunctions(db, {
+      shout: (value) => `${String(value).toUpperCase()}!`,
+    })
+
+    const row = db.prepare(`SELECT shout('hello') AS v`).get() as { v: string }
+    assert.equal(row.v, 'HELLO!')
+    db.close()
+  })
+
+  test('registers as deterministic, so it is usable in an index', () => {
+    const db = new DatabaseSync(':memory:')
+    registerSqliteFunctions(db, { half: (n) => Number(n) / 2 })
+
+    db.exec('CREATE TABLE t (n INTEGER)')
+    // SQLite rejects non-deterministic functions in an index outright, so this
+    // statement succeeding IS the assertion about how they were registered.
+    db.exec('CREATE INDEX t_half ON t (half(n))')
+    db.close()
+  })
+
+  test('registers every entry in the map', () => {
+    const db = new DatabaseSync(':memory:')
+    registerSqliteFunctions(db, { a: () => 1, b: () => 2 })
+
+    const row = db.prepare('SELECT a() + b() AS v').get() as { v: number }
+    assert.equal(row.v, 3)
+    db.close()
+  })
+
+  test('createNodeSqliteKysely registers them on the connection it builds', async () => {
+    const db = createNodeSqliteKysely<{ t: { id: number } }>({
+      filename: ':memory:',
+      functions: { double: (n) => Number(n) * 2 },
+    })
+
+    const result = await sql<{
+      v: number
+    }>`SELECT double(21) AS v`.execute(db)
+    assert.equal(result.rows[0]!.v, 42)
+    await db.destroy()
+  })
+})

package/src/register-functions.ts

@@ -0,0 +1,27 @@
+import type { DatabaseSync } from 'node:sqlite'
+import type { SqliteFunctionMap } from '@pikku/kysely-sqlite'
+
+/**
+ * Registers scalar user-defined SQL functions on a node:sqlite connection.
+ *
+ * Exported separately from `createNodeSqliteKysely` because an app that needs
+ * pragmas — WAL, `foreign_keys`, `busy_timeout` — has to build the connection
+ * itself, and would otherwise have no supported way to add UDFs to it.
+ *
+ * Registered as `deterministic`, which is what makes them usable in indexes and
+ * lets SQLite cache repeated calls with the same arguments. That is a promise
+ * about the function, not a hint: one whose output depends on the clock, a
+ * random source or anything mutable must not go through here.
+ *
+ * There is no bun counterpart. `@pikku/kysely-bun-sqlite` exports the same name
+ * so the import resolves either way, but it throws — see
+ * SqliteFunctionsUnsupportedError.
+ */
+export function registerSqliteFunctions(
+  db: DatabaseSync,
+  functions: SqliteFunctionMap
+): void {
+  for (const [name, fn] of Object.entries(functions)) {
+    db.function(name, { deterministic: true }, fn as never)
+  }
+}