sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ D1/ QueryDatabase.ts

import type * as runtime from "@cloudflare/workers-types";
import * as Binding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Effect from "effect/Effect";
import type { Database } from "./Database.ts";

/**
 * Bind a {@link Database} to a Worker and obtain the Effect-native D1
 * connection client (`prepare`, `exec`, `batch`, `raw`).
 *
 * `QueryDatabase` is a single identifier that is simultaneously the binding's
 * Context tag, its type, and the callable —
 * `yield* Cloudflare.D1.QueryDatabase(db)`.
 *
 * **Example:** Querying a database inside a Worker
 * ```typescript
 * const db = yield* Cloudflare.D1.QueryDatabase(MyDatabase);
 * const rows = yield* db.prepare("SELECT * FROM users").all();
 * ```
 *
 * @binding
 * @product D1
 * @category Storage & Databases
 */
export interface QueryDatabase extends Binding.Service<
  QueryDatabase,
  "Cloudflare.D1.QueryDatabase",
  (database: Database) => Effect.Effect<QueryDatabaseClient>
> {}

export const QueryDatabase = Binding.Service<QueryDatabase>("Cloudflare.D1.QueryDatabase");

/**
 * Effect-native wrapper around a Cloudflare D1 prepared statement.
 *
 * Construction (`prepare`) and binding (`bind`) are synchronous —
 * they're plan builders and don't touch D1. Only the executors
 * (`all`, `first`, `run`, `raw`) round-trip to the database, and
 * those return Effects so they participate in the Effect runtime.
 */
export class PreparedStatement {
  /** @internal */
  constructor(
    private readonly query: string,
    private readonly binds: ReadonlyArray<unknown>,
    private readonly rawEff: Effect.Effect<runtime.D1Database>,
  ) {}

  /**
   * Return a new prepared statement bound to `values`. Subsequent
   * calls replace the previous binding, matching the underlying
   * Cloudflare runtime semantics.
   */
  bind(...values: unknown[]): PreparedStatement {
    return new PreparedStatement(this.query, values, this.rawEff);
  }

  /** Run the query and return all matching rows. */
  all<T = unknown>(): Effect.Effect<runtime.D1Result<T>, never, RuntimeContext> {
    return this.withRuntime((stmt) => stmt.all<T>());
  }

  /** Run the query and return the first row, or `null` if no rows. */
  first<T = unknown>(): Effect.Effect<T | null, never, RuntimeContext>;
  first<T = unknown>(column: string): Effect.Effect<T | null, never, RuntimeContext>;
  first<T = unknown>(column?: string): Effect.Effect<T | null, never, RuntimeContext> {
    return this.withRuntime((stmt) =>
      column !== undefined ? stmt.first<T>(column) : stmt.first<T>(),
    );
  }

  /** Run the query as a mutation; returns row metadata. */
  run<T = unknown>(): Effect.Effect<runtime.D1Result<T>, never, RuntimeContext> {
    return this.withRuntime((stmt) => stmt.run<T>());
  }

  /** Run the query and return rows as flat arrays. */
  raw<T = unknown[]>(): Effect.Effect<T[], never, RuntimeContext>;
  raw<T = unknown[]>(options: {
    columnNames: true;
  }): Effect.Effect<[string[], ...T[]], never, RuntimeContext>;
  raw<T = unknown[]>(options?: {
    columnNames: true;
  }): Effect.Effect<T[] | [string[], ...T[]], never, RuntimeContext> {
    return this.withRuntime((stmt) =>
      options ? stmt.raw<T>(options) : (stmt.raw<T>() as Promise<T[] | [string[], ...T[]]>),
    );
  }

  /**
   * Materialize the underlying Cloudflare prepared statement against
   * a concrete D1 binding. Used by `QueryDatabaseClient.batch` to
   * collect statements for a single transactional call.
   *
   * @internal
   */
  _build(raw: runtime.D1Database): runtime.D1PreparedStatement {
    const stmt = raw.prepare(this.query);
    return this.binds.length > 0 ? stmt.bind(...this.binds) : stmt;
  }

  private withRuntime<A>(
    fn: (stmt: runtime.D1PreparedStatement) => Promise<A>,
  ): Effect.Effect<A, never, RuntimeContext> {
    return Effect.flatMap(this.rawEff, (raw) =>
      Effect.promise(() => fn(this._build(raw))),
    ) as Effect.Effect<A, never, RuntimeContext>;
  }
}

export interface QueryDatabaseClient {
  /**
   * An Effect that resolves to the raw underlying Cloudflare D1Database binding.
   * Use this when you need direct access for libraries like Better Auth.
   */
  raw: Effect.Effect<runtime.D1Database, never, RuntimeContext>;
  /**
   * Prepare a SQL statement. Returns synchronously — the network
   * round-trip happens when you yield one of the statement's
   * executors (`all`, `first`, `run`, `raw`).
   */
  prepare: (query: string) => PreparedStatement;
  /**
   * Execute raw SQL without prepared statements.
   */
  exec: (query: string) => Effect.Effect<runtime.D1ExecResult, never, RuntimeContext>;
  /**
   * Send multiple prepared statements in a single call.
   * Statements execute sequentially and are rolled back on failure.
   */
  batch: <T = unknown>(
    statements: PreparedStatement[],
  ) => Effect.Effect<runtime.D1Result<T>[], never, RuntimeContext>;
}