@pikku/kysely-node-sqlite 0.12.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @pikku/kysely-node-sqlite
+
+## 0.12.1
+
+### Patch Changes
+
+- 9060165: New `@pikku/kysely-node-sqlite` provides a Kysely dialect and migrator for Node's built-in `node:sqlite`. `@pikku/kysely-sqlite` adds a `LibsqlWebDialect` for running Kysely against Cloudflare Workers and Turso databases over HTTP.
+- Updated dependencies [9060165]
+  - @pikku/kysely-sqlite@0.12.5

package/dist/src/coercion-plugin.d.ts

@@ -0,0 +1,24 @@
+import type { KyselyPlugin } from 'kysely';
+export type ColumnKind = 'date' | 'bool' | 'json';
+/**
+ * Per-table column kind map. Keys are snake_case table names matching the
+ * physical SQLite tables; inner keys are snake_case column names.
+ * Generated by `pikku db migrate` from `-- @date|@bool|@json` annotations
+ * and naming conventions (col ends in _at/_on → date; starts with is_/has_/can_ → bool).
+ */
+export type CoercionMap = Record<string, Record<string, ColumnKind>>;
+export interface CreateCoercionPluginOptions {
+    map: CoercionMap;
+}
+/**
+ * Convert SQLite-stored values (TEXT/INTEGER) back into the logical types
+ * app code expects (Date / boolean / parsed JSON).
+ *
+ * Write-side coercion (Date → ISO string, boolean → 0/1, object → JSON) is
+ * handled in the NodeSqliteDatabase adapter (always-on), so this plugin is
+ * read-only.
+ *
+ * Place AFTER CamelCasePlugin in the plugin array (or it handles both
+ * orderings via the dual-keyed global map).
+ */
+export declare function createCoercionPlugin(options: CreateCoercionPluginOptions): KyselyPlugin;

package/dist/src/coercion-plugin.js

@@ -0,0 +1,77 @@
+function fromDb(value, kind) {
+    if (value == null)
+        return value;
+    switch (kind) {
+        case 'date':
+            if (typeof value === 'string') {
+                const d = new Date(value);
+                return Number.isNaN(d.getTime()) ? value : d;
+            }
+            return value;
+        case 'bool':
+            if (typeof value === 'number')
+                return value !== 0;
+            if (typeof value === 'bigint')
+                return value !== 0n;
+            return value;
+        case 'json':
+            if (typeof value !== 'string')
+                return value;
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
+    }
+}
+function snakeToCamel(name) {
+    return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Flatten the per-table map into a single column-name → kind lookup.
+ * Indexed by BOTH snake_case and camelCase so it works regardless of
+ * CamelCasePlugin ordering in the plugin array.
+ */
+function buildGlobalMap(map) {
+    const out = {};
+    for (const tbl of Object.values(map)) {
+        for (const [col, kind] of Object.entries(tbl)) {
+            out[col] = kind;
+            out[snakeToCamel(col)] = kind;
+        }
+    }
+    return out;
+}
+/**
+ * Convert SQLite-stored values (TEXT/INTEGER) back into the logical types
+ * app code expects (Date / boolean / parsed JSON).
+ *
+ * Write-side coercion (Date → ISO string, boolean → 0/1, object → JSON) is
+ * handled in the NodeSqliteDatabase adapter (always-on), so this plugin is
+ * read-only.
+ *
+ * Place AFTER CamelCasePlugin in the plugin array (or it handles both
+ * orderings via the dual-keyed global map).
+ */
+export function createCoercionPlugin(options) {
+    const globalMap = buildGlobalMap(options.map);
+    return {
+        transformQuery(args) {
+            return args.node;
+        },
+        async transformResult(args) {
+            const out = [];
+            for (const row of args.result.rows) {
+                const next = { ...row };
+                for (const [col, val] of Object.entries(row)) {
+                    const kind = globalMap[col];
+                    if (kind)
+                        next[col] = fromDb(val, kind);
+                }
+                out.push(next);
+            }
+            return { ...args.result, rows: out };
+        },
+    };
+}

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

@@ -0,0 +1,10 @@
+import { Kysely, type KyselyPlugin } from 'kysely';
+export interface CreateNodeSqliteKyselyOptions {
+    /** Path to the SQLite file. Use ':memory:' for an in-memory DB. */
+    filename: string;
+    /** Apply CamelCasePlugin so DB columns map to camelCase TS fields. Default true. */
+    camelCase?: boolean;
+    /** Extra plugins to layer on top. */
+    plugins?: KyselyPlugin[];
+}
+export declare function createNodeSqliteKysely<DB>(options: CreateNodeSqliteKyselyOptions): Kysely<DB>;

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

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

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { NodeSqliteDatabase } from './node-sqlite-adapter.js';
+export { createNodeSqliteKysely, type CreateNodeSqliteKyselyOptions, } from './create-node-sqlite-kysely.js';
+export { createCoercionPlugin, type CoercionMap, type ColumnKind, type CreateCoercionPluginOptions, } from './coercion-plugin.js';

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export { NodeSqliteDatabase } from './node-sqlite-adapter.js';
+export { createNodeSqliteKysely, } from './create-node-sqlite-kysely.js';
+export { createCoercionPlugin, } from './coercion-plugin.js';

package/dist/src/node-sqlite-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { SqliteDatabase, SqliteStatement } from 'kysely';
+export declare class NodeSqliteDatabase implements SqliteDatabase {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    prepare(sql: string): SqliteStatement;
+    close(): void;
+}

package/dist/src/node-sqlite-adapter.js

@@ -0,0 +1,58 @@
+/**
+ * Always-on write-side coercion: converts JS values that SQLite's node:sqlite
+ * binding cannot accept into their storable equivalents.
+ *   boolean  → 0 | 1
+ *   Date     → ISO 8601 string
+ *   object   → JSON string  (covers arrays and plain objects)
+ */
+function coerce(v) {
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v === 'boolean')
+        return v ? 1 : 0;
+    if (v instanceof Date)
+        return v.toISOString();
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return v;
+}
+/**
+ * Wraps node:sqlite's DatabaseSync as Kysely's SqliteDatabase. The shapes
+ * are close but not identical: node:sqlite's Statement methods take
+ * variadic positional params and always return bigint counters; Kysely's
+ * dialect passes parameters as a ReadonlyArray and expects number|bigint.
+ */
+class NodeSqliteStatement {
+    stmt;
+    reader = true;
+    constructor(stmt) {
+        this.stmt = stmt;
+    }
+    all(parameters) {
+        return this.stmt.all(...parameters.map(coerce));
+    }
+    *iterate(parameters) {
+        for (const row of this.stmt.iterate(...parameters.map(coerce))) {
+            yield row;
+        }
+    }
+    run(parameters) {
+        const result = this.stmt.run(...parameters.map(coerce));
+        return {
+            changes: result.changes,
+            lastInsertRowid: result.lastInsertRowid,
+        };
+    }
+}
+export class NodeSqliteDatabase {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    prepare(sql) {
+        return new NodeSqliteStatement(this.db.prepare(sql));
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/tsconfig.tsbuildinfo

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

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@pikku/kysely-node-sqlite",
+  "version": "0.12.1",
+  "author": "yasser.fadl@gmail.com",
+  "license": "MIT",
+  "module": "dist/src/index.js",
+  "main": "dist/src/index.js",
+  "type": "module",
+  "scripts": {
+    "tsc": "tsc",
+    "ncu": "npx npm-check-updates",
+    "build": "tsc -b",
+    "prepublishOnly": "yarn build"
+  },
+  "engines": {
+    "node": ">=22.10"
+  },
+  "dependencies": {
+    "@pikku/kysely": "^0.12.0",
+    "@pikku/kysely-sqlite": "^0.12.5",
+    "kysely": "^0.28.12"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.9"
+  }
+}

package/src/coercion-plugin.ts

@@ -0,0 +1,92 @@
+import type { KyselyPlugin, UnknownRow } from 'kysely'
+
+export type ColumnKind = 'date' | 'bool' | 'json'
+
+/**
+ * Per-table column kind map. Keys are snake_case table names matching the
+ * physical SQLite tables; inner keys are snake_case column names.
+ * Generated by `pikku db migrate` from `-- @date|@bool|@json` annotations
+ * and naming conventions (col ends in _at/_on → date; starts with is_/has_/can_ → bool).
+ */
+export type CoercionMap = Record<string, Record<string, ColumnKind>>
+
+export interface CreateCoercionPluginOptions {
+  map: CoercionMap
+}
+
+function fromDb(value: unknown, kind: ColumnKind): unknown {
+  if (value == null) return value
+  switch (kind) {
+    case 'date':
+      if (typeof value === 'string') {
+        const d = new Date(value)
+        return Number.isNaN(d.getTime()) ? value : d
+      }
+      return value
+    case 'bool':
+      if (typeof value === 'number') return value !== 0
+      if (typeof value === 'bigint') return value !== 0n
+      return value
+    case 'json':
+      if (typeof value !== 'string') return value
+      try {
+        return JSON.parse(value)
+      } catch {
+        return value
+      }
+  }
+}
+
+function snakeToCamel(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+/**
+ * Flatten the per-table map into a single column-name → kind lookup.
+ * Indexed by BOTH snake_case and camelCase so it works regardless of
+ * CamelCasePlugin ordering in the plugin array.
+ */
+function buildGlobalMap(map: CoercionMap): Record<string, ColumnKind> {
+  const out: Record<string, ColumnKind> = {}
+  for (const tbl of Object.values(map)) {
+    for (const [col, kind] of Object.entries(tbl)) {
+      out[col] = kind
+      out[snakeToCamel(col)] = kind
+    }
+  }
+  return out
+}
+
+/**
+ * Convert SQLite-stored values (TEXT/INTEGER) back into the logical types
+ * app code expects (Date / boolean / parsed JSON).
+ *
+ * Write-side coercion (Date → ISO string, boolean → 0/1, object → JSON) is
+ * handled in the NodeSqliteDatabase adapter (always-on), so this plugin is
+ * read-only.
+ *
+ * Place AFTER CamelCasePlugin in the plugin array (or it handles both
+ * orderings via the dual-keyed global map).
+ */
+export function createCoercionPlugin(
+  options: CreateCoercionPluginOptions
+): KyselyPlugin {
+  const globalMap = buildGlobalMap(options.map)
+  return {
+    transformQuery(args) {
+      return args.node
+    },
+    async transformResult(args) {
+      const out: UnknownRow[] = []
+      for (const row of args.result.rows as UnknownRow[]) {
+        const next: UnknownRow = { ...row }
+        for (const [col, val] of Object.entries(row)) {
+          const kind = globalMap[col]
+          if (kind) next[col] = fromDb(val, kind)
+        }
+        out.push(next)
+      }
+      return { ...args.result, rows: out }
+    },
+  }
+}

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

@@ -0,0 +1,31 @@
+import { DatabaseSync } from 'node:sqlite'
+import {
+  Kysely,
+  SqliteDialect,
+  CamelCasePlugin,
+  type KyselyPlugin,
+} from 'kysely'
+import { NodeSqliteDatabase } from './node-sqlite-adapter.js'
+
+export interface CreateNodeSqliteKyselyOptions {
+  /** Path to the SQLite file. Use ':memory:' for an in-memory DB. */
+  filename: string
+  /** Apply CamelCasePlugin so DB columns map to camelCase TS fields. Default true. */
+  camelCase?: boolean
+  /** Extra plugins to layer on top. */
+  plugins?: KyselyPlugin[]
+}
+
+export function createNodeSqliteKysely<DB>(
+  options: CreateNodeSqliteKyselyOptions
+): Kysely<DB> {
+  const db = new DatabaseSync(options.filename)
+  const plugins: KyselyPlugin[] = []
+  if (options.camelCase ?? true) plugins.push(new CamelCasePlugin())
+  if (options.plugins) plugins.push(...options.plugins)
+
+  return new Kysely<DB>({
+    dialect: new SqliteDialect({ database: new NodeSqliteDatabase(db) }),
+    plugins,
+  })
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { NodeSqliteDatabase } from './node-sqlite-adapter.js'
+export {
+  createNodeSqliteKysely,
+  type CreateNodeSqliteKyselyOptions,
+} from './create-node-sqlite-kysely.js'
+export {
+  createCoercionPlugin,
+  type CoercionMap,
+  type ColumnKind,
+  type CreateCoercionPluginOptions,
+} from './coercion-plugin.js'

package/src/node-sqlite-adapter.ts

@@ -0,0 +1,62 @@
+import type { DatabaseSync, StatementSync, SQLInputValue } from 'node:sqlite'
+import type { SqliteDatabase, SqliteStatement } from 'kysely'
+
+/**
+ * Always-on write-side coercion: converts JS values that SQLite's node:sqlite
+ * binding cannot accept into their storable equivalents.
+ *   boolean  → 0 | 1
+ *   Date     → ISO 8601 string
+ *   object   → JSON string  (covers arrays and plain objects)
+ */
+function coerce(v: unknown): SQLInputValue {
+  if (v === null || v === undefined) return null as unknown as SQLInputValue
+  if (typeof v === 'boolean') return v ? 1 : 0
+  if (v instanceof Date) return v.toISOString()
+  if (typeof v === 'object') return JSON.stringify(v)
+  return v as SQLInputValue
+}
+
+/**
+ * Wraps node:sqlite's DatabaseSync as Kysely's SqliteDatabase. The shapes
+ * are close but not identical: node:sqlite's Statement methods take
+ * variadic positional params and always return bigint counters; Kysely's
+ * dialect passes parameters as a ReadonlyArray and expects number|bigint.
+ */
+class NodeSqliteStatement implements SqliteStatement {
+  readonly reader = true
+
+  constructor(private readonly stmt: StatementSync) {}
+
+  all(parameters: ReadonlyArray<unknown>): unknown[] {
+    return this.stmt.all(...parameters.map(coerce)) as unknown[]
+  }
+
+  *iterate(parameters: ReadonlyArray<unknown>): IterableIterator<unknown> {
+    for (const row of this.stmt.iterate(...parameters.map(coerce))) {
+      yield row
+    }
+  }
+
+  run(parameters: ReadonlyArray<unknown>): {
+    changes: number | bigint
+    lastInsertRowid: number | bigint
+  } {
+    const result = this.stmt.run(...parameters.map(coerce))
+    return {
+      changes: result.changes,
+      lastInsertRowid: result.lastInsertRowid,
+    }
+  }
+}
+
+export class NodeSqliteDatabase implements SqliteDatabase {
+  constructor(private readonly db: DatabaseSync) {}
+
+  prepare(sql: string): SqliteStatement {
+    return new NodeSqliteStatement(this.db.prepare(sql))
+  }
+
+  close(): void {
+    this.db.close()
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "module": "Node18",
+    "outDir": "dist",
+    "target": "esnext",
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.test.ts", "node_modules"]
+}