npm package: @meck93/kysely-bun-sqlite
Description: A [Kysely](https://kysely.dev/) dialect for [Bun's native SQLite](https://bun.sh/docs/api/sqlite) with opt-in worker thread support.
Latest version: 0.2.16

# @meck93/kysely-bun-sqlite

A [Kysely](https://kysely.dev/) dialect for [Bun's native SQLite](https://bun.sh/docs/api/sqlite) with opt-in worker thread support.

[![npm version](https://img.shields.io/npm/v/@meck93/kysely-bun-sqlite.svg)](https://www.npmjs.com/package/@meck93/kysely-bun-sqlite)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
bun add @meck93/kysely-bun-sqlite kysely
```

## Usage

### In-Process (Default)

```typescript
import { Kysely } from "kysely";
import { BunSqliteDialect } from "@meck93/kysely-bun-sqlite";
import Database from "bun:sqlite";

interface DB {
  person: { id: Generated<number>; name: string; age: number };
}

const db = new Kysely<DB>({
  dialect: new BunSqliteDialect({
    database: new Database("./app.sqlite"),
  }),
});

await db.insertInto("person").values({ name: "John", age: 30 }).execute();
const people = await db.selectFrom("person").selectAll().where("age", ">", 25).execute();

await db.destroy();
```

### Worker Mode (Opt-In)

Runs all queries in a dedicated Bun Worker — keeps the main thread free.

**Main thread:**

```typescript
import { Kysely } from "kysely";
import { BunWorkerDialect } from "@meck93/kysely-bun-sqlite";

const worker = new Worker(new URL("./db-worker.ts", import.meta.url), {
  type: "module",
});

const db = new Kysely<DB>({
  dialect: new BunWorkerDialect({
    worker,
    url: "./app.sqlite",
    requestTimeoutMs: 10_000,
  }),
});
```

**Worker file (`db-worker.ts`):**

```typescript
import { createBunWorkerOnMessageCallback } from "@meck93/kysely-bun-sqlite";

createBunWorkerOnMessageCallback();
```

## API

### `BunSqliteDialect`

```typescript
new BunSqliteDialect({
  database: Database,                    // Required — Bun SQLite instance
  onCreateConnection?: (conn) => void,   // Optional — called once on connection init
})
```

- Synchronous, single-connection (serialized via internal mutex)
- Supports `streamQuery()` via `stmt.iterate()` (Bun 1.1.31+)
- Full transaction and savepoint support

### `BunWorkerDialect`

```typescript
new BunWorkerDialect({
  worker: Worker,                        // Required — Bun Worker instance
  url?: string,                          // Default: ":memory:"
  dbOptions?: DBOptions,                 // Default: { create: true }
  cacheStatements?: boolean,             // Default: false
  requestTimeoutMs?: number,             // Default: 5000
  terminateWorkerOnDestroy?: boolean,    // Default: true
  onCreateConnection?: (conn) => void,   // Optional
})
```

- All queries dispatched via `postMessage` to the worker
- Configurable timeout per query (rejects on expiry)
- Worker terminated on `db.destroy()` by default
- Full transaction and savepoint support

### `createBunWorkerOnMessageCallback`

Sets up the worker-side message handler. Optionally accepts a custom database factory:

```typescript
createBunWorkerOnMessageCallback((url, dbOptions) => {
  return new Database(url, dbOptions);
});
```

## Requirements

- [Bun](https://bun.sh/) runtime
- [Kysely](https://github.com/kysely-org/kysely) ^0.28.11

## License

MIT