@pepys/kysely-turso 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@pepys/kysely-turso</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@pepys/kysely-turso"><img src="https://img.shields.io/npm/v/@pepys/kysely-turso" alt="npm version"></a>
+    <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/README.md">Documentation</a>
+  </p>
+</div>
+
+A Kysely dialect for Turso databases on Bun.
+
+`createTursoDialect` takes a function that opens a `@tursodatabase/database` database, and gives
+Kysely a dialect that queries it. The pepys test store and the pepys API use it.
+
+## Install
+
+```sh
+bun add @pepys/kysely-turso
+```
+
+## Features
+
+- `createTursoDialect`: the dialect to pass to `new Kysely({ dialect })`.
+
+## Documentation
+
+The [pepys docs](../../docs/README.md) hold the design of the store.

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@pepys/kysely-turso",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A Kysely dialect for Turso databases on Bun",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/pepys.git",
+    "directory": "packages/kysely-turso"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-utils"
+  ],
+  "type": "module",
+  "exports": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tursodatabase/database": "0.8.3",
+    "kysely": "0.29.8",
+    "tiny-invariant": "1.3.3"
+  }
+}

package/src/create-turso-connection.ts

@@ -0,0 +1,59 @@
+import type { Database } from '@tursodatabase/database';
+import type { CompiledQuery, DatabaseConnection, QueryResult } from 'kysely';
+
+export function createTursoConnection(database: Database): DatabaseConnection {
+  return {
+    // Kysely's DatabaseConnection fixes this name
+    // oxlint-disable-next-line zgeoff/function-verb
+    executeQuery: (compiledQuery) => runQuery(database, compiledQuery),
+    streamQuery: (compiledQuery) => streamRows(database, compiledQuery),
+  };
+}
+
+async function runQuery<Row>(
+  database: Database,
+  compiledQuery: CompiledQuery,
+): Promise<QueryResult<Row>> {
+  const statement = await database.prepare(compiledQuery.sql);
+
+  try {
+    if (statement.reader) {
+      const rows: unknown[] = await statement.all(...compiledQuery.parameters);
+
+      return { rows: narrowRows<Row>(rows) };
+    }
+
+    const result = await statement.run(...compiledQuery.parameters);
+
+    return {
+      insertId: BigInt(result.lastInsertRowid),
+      numAffectedRows: BigInt(result.changes),
+      rows: [],
+    };
+  } finally {
+    statement.close();
+  }
+}
+
+// Kysely owns the row type: the caller's query builder declares it, and the driver only hands over
+// what the database returned.
+function narrowRows<Row>(rows: unknown[]): Row[] {
+  return rows.filter((value): value is Row => value !== undefined);
+}
+
+async function* streamRows<Row>(
+  database: Database,
+  compiledQuery: CompiledQuery,
+): AsyncIterableIterator<QueryResult<Row>> {
+  const statement = await database.prepare(compiledQuery.sql);
+
+  try {
+    for await (const row of statement.iterate(...compiledQuery.parameters)) {
+      const rows: unknown[] = [row];
+
+      yield { rows: narrowRows<Row>(rows) };
+    }
+  } finally {
+    statement.close();
+  }
+}

package/src/create-turso-dialect.ts

@@ -0,0 +1,17 @@
+import type { Database } from '@tursodatabase/database';
+import { SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler } from 'kysely';
+import type { Dialect, Kysely } from 'kysely';
+import { createTursoDriver } from './create-turso-driver.ts';
+
+export interface TursoDialectConfig {
+  readonly database: () => Promise<Database>;
+}
+
+export function createTursoDialect(config: TursoDialectConfig): Dialect {
+  return {
+    createDriver: () => createTursoDriver(config.database),
+    createQueryCompiler: () => new SqliteQueryCompiler(),
+    createAdapter: () => new SqliteAdapter(),
+    createIntrospector: (db: Kysely<unknown>) => new SqliteIntrospector(db),
+  };
+}

package/src/create-turso-driver.ts

@@ -0,0 +1,63 @@
+import type { Database } from '@tursodatabase/database';
+import type { DatabaseConnection, Driver } from 'kysely';
+import invariant from 'tiny-invariant';
+import { createTursoConnection } from './create-turso-connection.ts';
+
+export function createTursoDriver(openDatabase: () => Promise<Database>): Driver {
+  let database: Database | undefined;
+  let connection: DatabaseConnection | undefined;
+  let queue: Promise<void> = Promise.resolve();
+  let releaseCurrent: (() => void) | undefined;
+
+  const getDatabase = (): Database => {
+    invariant(database, 'Kysely initialises the Turso driver before it uses it');
+
+    return database;
+  };
+
+  return {
+    init: async () => {
+      database = await openDatabase();
+
+      connection = createTursoConnection(database);
+    },
+
+    // one connection serves every query, so a transaction holds it until it ends
+    acquireConnection: async () => {
+      invariant(connection, 'Kysely initialises the Turso driver before it acquires a connection');
+
+      const acquired = connection;
+      const previous = queue;
+      const turn = Promise.withResolvers<void>();
+
+      queue = turn.promise;
+
+      await previous;
+
+      releaseCurrent = turn.resolve;
+
+      return acquired;
+    },
+    beginTransaction: async () => {
+      await getDatabase().exec('begin');
+    },
+    commitTransaction: async () => {
+      await getDatabase().exec('commit');
+    },
+    rollbackTransaction: async () => {
+      await getDatabase().exec('rollback');
+    },
+    releaseConnection: () => {
+      invariant(releaseCurrent, 'Kysely releases only a connection it acquired');
+      releaseCurrent();
+
+      return Promise.resolve();
+    },
+
+    // a connection in use finishes before the database closes
+    destroy: async () => {
+      await queue;
+      await getDatabase().close();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { TursoDialectConfig } from './create-turso-dialect.ts';
+export { createTursoDialect } from './create-turso-dialect.ts';