cf-bun-mocks 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Lilienblum
+
+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,161 @@
+# cf-bun-mocks
+
+Cloudflare Workers mocks and helpers for Bun testing.
+
+## Installation
+
+```bash
+bun add -d cf-bun-mocks
+```
+
+## D1 Mock
+
+The D1 mock provides a drop-in replacement for Cloudflare's D1 database, backed by Bun's native SQLite.
+
+### Basic Usage
+
+```typescript
+import { D1Mock } from "cf-bun-mocks";
+
+// In-memory database (recommended for tests)
+const db = new D1Mock(":memory:");
+
+// Or persist to a file
+const db = new D1Mock("./test.db");
+```
+
+### With Migrations
+
+Use `initD1` to create an in-memory database and run your migrations:
+
+```typescript
+import { initD1 } from "cf-bun-mocks";
+
+const db = await initD1("./migrations");
+```
+
+This reads all `.sql` files from the migrations directory in sorted order and executes them.
+
+### Example Test
+
+```typescript
+import { describe, test, expect, beforeEach } from "bun:test";
+import { D1Mock } from "cf-bun-mocks";
+import type { D1Database } from "@cloudflare/workers-types";
+
+describe("my worker", () => {
+  let db: D1Database;
+
+  beforeEach(async () => {
+    db = new D1Mock(":memory:");
+    await db.exec(`
+      CREATE TABLE users (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT UNIQUE
+      )
+    `);
+  });
+
+  test("insert and query", async () => {
+    await db
+      .prepare("INSERT INTO users (name, email) VALUES (?, ?)")
+      .bind("Alice", "alice@example.com")
+      .run();
+
+    const user = await db
+      .prepare("SELECT * FROM users WHERE email = ?")
+      .bind("alice@example.com")
+      .first();
+
+    expect(user).toEqual({
+      id: 1,
+      name: "Alice",
+      email: "alice@example.com",
+    });
+  });
+
+  test("batch operations", async () => {
+    const results = await db.batch([
+      db
+        .prepare("INSERT INTO users (name, email) VALUES (?, ?)")
+        .bind("Bob", "bob@example.com"),
+      db
+        .prepare("INSERT INTO users (name, email) VALUES (?, ?)")
+        .bind("Carol", "carol@example.com"),
+      db.prepare("SELECT * FROM users"),
+    ]);
+
+    expect(results[2].results).toHaveLength(2);
+  });
+});
+```
+
+### Injecting into Workers
+
+Pass the mock as your D1 binding when testing your worker:
+
+```typescript
+import { D1Mock } from "cf-bun-mocks";
+import type { Env } from "./worker";
+
+const env: Env = {
+  DB: new D1Mock(":memory:"),
+};
+
+// Test your worker with the mock env
+const response = await worker.fetch(request, env);
+```
+
+## Environment Mock
+
+Use `useEnv` to mock `cloudflare:env` imports in your tests:
+
+```typescript
+import { describe, test, expect } from "bun:test";
+import { useEnv, D1Mock } from "cf-bun-mocks";
+import type { Env } from "./worker";
+
+describe("my worker", () => {
+  useEnv<Env>(async () => ({
+    DB: new D1Mock(":memory:"),
+    MY_SECRET: "test-secret",
+  }));
+
+  test("uses mocked env", async () => {
+    // Your worker code that imports from "cloudflare:env" will get the mock
+    const { myFunction } = await import("./worker");
+    const result = await myFunction();
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## API
+
+### `D1Mock`
+
+Implements the full `D1Database` interface from `@cloudflare/workers-types`:
+
+- `prepare(query: string)` - Create a prepared statement
+- `batch(statements: D1PreparedStatement[])` - Execute multiple statements
+- `exec(query: string)` - Execute raw SQL
+- `dump()` - Serialize the database to an ArrayBuffer
+- `withSession(constraint?)` - Get a session (bookmark tracking is stubbed)
+
+### `initD1(migrationsPath: string)`
+
+Creates an in-memory D1Mock and runs all `.sql` files from the specified directory.
+
+### `useEnv<TEnv>(setup: () => TEnv | Promise<TEnv>)`
+
+Registers `beforeEach`/`afterEach` hooks to mock `cloudflare:env` for each test. Call at the top of your `describe` block.
+
+## Requirements
+
+- Bun v1.0+
+- TypeScript 5+
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "cf-bun-mocks",
+  "version": "0.1.0-alpha.0",
+  "description": "Cloudflare Workers mocks and helpers for Bun testing",
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./d1": {
+      "import": "./src/d1.ts",
+      "types": "./src/d1.ts"
+    },
+    "./env": {
+      "import": "./src/env.ts",
+      "types": "./src/env.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "cloudflare",
+    "workers",
+    "d1",
+    "mock",
+    "bun",
+    "testing"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260103.0",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/d1.ts

@@ -0,0 +1,186 @@
+import { Database, type SQLQueryBindings } from "bun:sqlite";
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import type {
+  D1PreparedStatement,
+  D1Result,
+  D1Database,
+  D1DatabaseSession,
+  D1SessionBookmark,
+  D1SessionConstraint,
+  D1ExecResult,
+} from "@cloudflare/workers-types";
+
+class D1PreparedStatementMock implements D1PreparedStatement {
+  #stmt: ReturnType<Database["prepare"]>;
+  #boundValues: SQLQueryBindings[] = [];
+
+  constructor(stmt: ReturnType<Database["prepare"]>) {
+    this.#stmt = stmt;
+  }
+
+  bind(...values: unknown[]): D1PreparedStatement {
+    this.#boundValues = values as SQLQueryBindings[];
+    return this as D1PreparedStatement;
+  }
+
+  async first<T = Record<string, unknown>>(
+    colName?: string
+  ): Promise<T | null> {
+    const result = this.#stmt.get(...this.#boundValues);
+    if (result === null || result === undefined) {
+      return null;
+    }
+    if (colName) {
+      return (result as Record<string, unknown>)[colName] as T;
+    }
+    return result as T;
+  }
+
+  async run<T = Record<string, unknown>>(): Promise<D1Result<T>> {
+    const changes = this.#stmt.run(...this.#boundValues);
+    return {
+      success: true,
+      meta: {
+        duration: 0,
+        size_after: 0,
+        rows_read: 0,
+        rows_written: changes.changes,
+        last_row_id: Number(changes.lastInsertRowid),
+        changed_db: changes.changes > 0,
+        changes: changes.changes,
+      },
+      results: [] as T[],
+    };
+  }
+
+  async all<T = Record<string, unknown>>(): Promise<D1Result<T>> {
+    const results = this.#stmt.all(...this.#boundValues);
+    return {
+      success: true,
+      meta: {
+        duration: 0,
+        size_after: 0,
+        rows_read: results.length,
+        rows_written: 0,
+        last_row_id: 0,
+        changed_db: false,
+        changes: 0,
+      },
+      results: results as T[],
+    };
+  }
+
+  async raw<T = unknown[]>(options: {
+    columnNames: true;
+  }): Promise<[string[], ...T[]]>;
+  async raw<T = unknown[]>(options?: { columnNames?: false }): Promise<T[]>;
+  async raw<T = unknown[]>(options?: {
+    columnNames?: boolean;
+  }): Promise<T[] | [string[], ...T[]]> {
+    const values = this.#stmt.values(...this.#boundValues);
+    if (options?.columnNames) {
+      return [this.#stmt.columnNames, ...(values as T[])] as [string[], ...T[]];
+    }
+    return values as T[];
+  }
+}
+
+class D1DatabaseSessionMock implements D1DatabaseSession {
+  #db: D1Mock;
+  #bookmark: D1SessionBookmark | null = null;
+
+  constructor(db: D1Mock) {
+    this.#db = db;
+  }
+
+  prepare(query: string): D1PreparedStatement {
+    return this.#db.prepare(query);
+  }
+
+  async batch<T = unknown>(
+    statements: D1PreparedStatement[]
+  ): Promise<D1Result<T>[]> {
+    return this.#db.batch(statements);
+  }
+
+  getBookmark(): D1SessionBookmark | null {
+    return this.#bookmark;
+  }
+}
+
+export class D1Mock implements D1Database {
+  #db: Database;
+
+  constructor(
+    filename?: string,
+    options?:
+      | number
+      | {
+          readonly?: boolean;
+          create?: boolean;
+          readwrite?: boolean;
+          safeIntegers?: boolean;
+          strict?: boolean;
+        }
+  ) {
+    this.#db = new Database(filename, options);
+  }
+
+  prepare(query: string): D1PreparedStatement {
+    const stmt = this.#db.prepare(query);
+    return new D1PreparedStatementMock(stmt);
+  }
+
+  async batch<T = unknown>(
+    statements: D1PreparedStatement[]
+  ): Promise<D1Result<T>[]> {
+    const results: D1Result<T>[] = [];
+    for (const stmt of statements) {
+      if (stmt instanceof D1PreparedStatementMock) {
+        const result = await stmt.all<T>();
+        results.push(result);
+      }
+    }
+    return results;
+  }
+
+  async exec(query: string): Promise<D1ExecResult> {
+    const start = performance.now();
+    const { changes: count } = this.#db.run(query);
+    const duration = performance.now() - start;
+    return {
+      count,
+      duration,
+    };
+  }
+
+  withSession(
+    _constraintOrBookmark?: D1SessionBookmark | D1SessionConstraint
+  ): D1DatabaseSession {
+    return new D1DatabaseSessionMock(this);
+  }
+
+  async dump(): Promise<ArrayBuffer> {
+    const serialized = this.#db.serialize();
+    const buffer = serialized.buffer;
+    if (buffer instanceof SharedArrayBuffer) {
+      const newBuffer = new ArrayBuffer(buffer.byteLength);
+      new Uint8Array(newBuffer).set(new Uint8Array(buffer));
+      return newBuffer;
+    }
+    return buffer;
+  }
+}
+
+export async function initD1(migrationsPath: string): Promise<D1Mock> {
+  const files = readdirSync(migrationsPath)
+    .filter((file) => file.endsWith(".sql"))
+    .sort();
+  const db = new D1Mock(":memory:");
+  for (const file of files) {
+    const migration = await Bun.file(path.join(migrationsPath, file)).text();
+    await db.exec(migration);
+  }
+  return db;
+}

package/src/env.ts

@@ -0,0 +1,15 @@
+/// <reference types="@cloudflare/workers-types" />
+import { beforeEach, afterEach, mock } from "bun:test";
+
+export function useEnv<TEnv extends Cloudflare.Env = Cloudflare.Env>(
+  setup: () => Bun.MaybePromise<TEnv>
+) {
+  beforeEach(async () => {
+    const env = await setup();
+    mock.module("cloudflare:env", () => env);
+  });
+
+  afterEach(() => {
+    mock.module("cloudflare:env", () => {});
+  });
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./d1.ts";
+export * from "./env.ts";