@fragno-dev/db 0.1.14 → 0.2.0

package/src/sql-driver/connection/single-connection-provider.ts

@@ -0,0 +1,42 @@
+/**
+ * Adapted from Kysely's SingleConnectionProvider
+ * Modified from: https://github.com/kysely-org/kysely
+ * License: MIT
+ * Copyright (c) 2022 Sami Koskimäki
+ */
+
+import type { DatabaseConnection } from "../sql-driver";
+import type { ConnectionProvider } from "./connection-provider";
+
+const ignoreError = () => {};
+
+export class SingleConnectionProvider implements ConnectionProvider {
+  readonly #connection: DatabaseConnection;
+  // oxlint-disable-next-line no-explicit-any
+  #runningPromise?: Promise<any>;
+
+  constructor(connection: DatabaseConnection) {
+    this.#connection = connection;
+  }
+
+  async provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T> {
+    while (this.#runningPromise) {
+      await this.#runningPromise.catch(ignoreError);
+    }
+
+    // `#runningPromise` must be set to undefined before it's
+    // resolved or rejected. Otherwise the while loop above
+    // will misbehave.
+    this.#runningPromise = this.#run(consumer).finally(() => {
+      this.#runningPromise = undefined;
+    });
+
+    return this.#runningPromise;
+  }
+
+  // Run the runner in an async function to make sure it doesn't
+  // throw synchronous errors.
+  async #run<T>(runner: (connection: DatabaseConnection) => Promise<T>): Promise<T> {
+    return await runner(this.#connection);
+  }
+}

package/src/sql-driver/dialect-adapter/dialect-adapter.ts

@@ -0,0 +1,9 @@
+export interface DialectAdapter {
+  readonly supportsReturning: boolean;
+}
+
+export abstract class DialectAdapterBase implements DialectAdapter {
+  get supportsReturning(): boolean {
+    return false;
+  }
+}

package/src/sql-driver/dialect-adapter/sqlite-dialect-adapter.ts

@@ -0,0 +1,7 @@
+import { DialectAdapterBase } from "./dialect-adapter";
+
+export class SqliteDialectAdapter extends DialectAdapterBase {
+  override get supportsReturning(): boolean {
+    return true;
+  }
+}

package/src/sql-driver/dialects/dialects.ts

@@ -0,0 +1 @@
+export { SqliteDialect, PostgresDialect, MysqlDialect } from "kysely";

package/src/sql-driver/dialects/durable-object-dialect.ts

@@ -0,0 +1,260 @@
+import {
+  CompiledQuery,
+  Kysely,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+  type DatabaseConnection,
+  type DatabaseIntrospector,
+  type Dialect,
+  type Driver,
+  type QueryCompiler,
+  type QueryResult,
+} from "kysely";
+
+interface DurableObjectId {
+  toString(): string;
+  equals(other: DurableObjectId): boolean;
+  readonly name?: string;
+}
+
+interface DurableObjectTransaction {
+  rollback(): void;
+}
+
+type SqlStorageValue = ArrayBuffer | string | number | null;
+
+interface SqlStorage {
+  exec<T extends Record<string, SqlStorageValue>>(
+    query: string,
+    // oxlint-disable-next-line no-explicit-any
+    ...bindings: any[]
+  ): SqlStorageCursor<T>;
+  Cursor: typeof SqlStorageCursor;
+  Statement: typeof SqlStorageStatement;
+}
+
+declare abstract class SqlStorageStatement {}
+declare abstract class SqlStorageCursor<T extends Record<string, SqlStorageValue>> {
+  next():
+    | {
+        done?: false;
+        value: T;
+      }
+    | {
+        done: true;
+        value?: never;
+      };
+  toArray(): T[];
+  one(): T;
+  raw<U extends SqlStorageValue[]>(): IterableIterator<U>;
+  columnNames: string[];
+  get rowsRead(): number;
+  get rowsWritten(): number;
+  [Symbol.iterator](): IterableIterator<T>;
+}
+
+interface DurableObjectStorage {
+  transaction<T>(closure: (txn: DurableObjectTransaction) => Promise<T>): Promise<T>;
+
+  readonly sql: SqlStorage;
+}
+
+interface DurableObjectState {
+  readonly id: DurableObjectId;
+  readonly storage: DurableObjectStorage;
+}
+
+/**
+ * Config for the Durable Objects dialect. Pass your Durable Object state to this object.
+ */
+export interface DODialectConfig {
+  ctx: DurableObjectState;
+}
+
+/**
+ * DO dialect that adds support for [Cloudflare Durable Objects][0] in [Kysely][1].
+ * The constructor takes the Durable Object state context.
+ *
+ * ```typescript
+ * new DurableObjectDialect({
+ *   ctx: this.ctx,
+ * })
+ * ```
+ *
+ * [0]: https://developers.cloudflare.com/durable-objects/
+ * [1]: https://github.com/koskimas/kysely
+ */
+export class DurableObjectDialect implements Dialect {
+  #config: DODialectConfig;
+
+  constructor(config: DODialectConfig) {
+    this.#config = config;
+  }
+
+  createAdapter() {
+    return new SqliteAdapter();
+  }
+
+  createDriver(): Driver {
+    return new DurableObjectDriver(this.#config);
+  }
+
+  createQueryCompiler(): QueryCompiler {
+    return new SqliteQueryCompiler();
+  }
+
+  createIntrospector(db: Kysely<unknown>): DatabaseIntrospector {
+    return new SqliteIntrospector(db);
+  }
+}
+
+class DurableObjectDriver implements Driver {
+  #config: DODialectConfig;
+  #connection: DOConnection | null = null;
+
+  constructor(config: DODialectConfig) {
+    this.#config = config;
+  }
+
+  async init(): Promise<void> {}
+
+  async acquireConnection(): Promise<DatabaseConnection> {
+    // Ensure only one connection exists
+    if (!this.#connection) {
+      this.#connection = new DOConnection(this.#config);
+    }
+    return this.#connection;
+  }
+
+  async beginTransaction(conn: DOConnection): Promise<void> {
+    return await conn.beginTransaction();
+  }
+
+  async commitTransaction(conn: DOConnection): Promise<void> {
+    return await conn.commitTransaction();
+  }
+
+  async rollbackTransaction(conn: DOConnection): Promise<void> {
+    return await conn.rollbackTransaction();
+  }
+
+  async releaseConnection(_conn: DOConnection): Promise<void> {
+    this.#connection = null;
+  }
+
+  async destroy(): Promise<void> {
+    this.#connection = null;
+  }
+}
+
+class DOConnection implements DatabaseConnection {
+  #config: DODialectConfig;
+  #transactionPromise: Promise<void> | null = null;
+  #transactionControl: {
+    resolve: () => void;
+    reject: (error: Error) => void;
+  } | null = null;
+  #txn: DurableObjectTransaction | null = null;
+
+  constructor(config: DODialectConfig) {
+    this.#config = config;
+  }
+
+  async executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>> {
+    const cursor = this.#config.ctx.storage.sql.exec(
+      compiledQuery.sql,
+      ...compiledQuery.parameters,
+    );
+
+    const rows = cursor.toArray() as O[];
+    const numAffectedRows = cursor.rowsWritten > 0 ? BigInt(cursor.rowsWritten) : undefined;
+
+    return {
+      insertId: undefined, // Durable Objects doesn't provide last_row_id like D1
+      rows: rows || [],
+      numAffectedRows,
+    };
+  }
+
+  async beginTransaction() {
+    if (this.#transactionPromise) {
+      throw new Error("Transaction already in progress");
+    }
+
+    // Use a promise to wait for the transaction closure to actually start
+    let transactionReady: (() => void) | null = null;
+    const readyPromise = new Promise<void>((resolve) => {
+      transactionReady = resolve;
+    });
+
+    // Start the transaction - all queries executed will be inside this closure
+    this.#transactionPromise = this.#config.ctx.storage
+      .transaction(async (txn) => {
+        this.#txn = txn;
+
+        // Wait for commit or rollback to be called
+        await new Promise<void>((resolve, reject) => {
+          this.#transactionControl = { resolve, reject };
+          // Signal that transaction is ready
+          if (transactionReady) {
+            transactionReady();
+          }
+        });
+      })
+      .catch((error) => {
+        // Don't clear state here - let commit/rollback handle it
+        throw error;
+      });
+
+    // Wait for the transaction closure to set up before returning
+    await readyPromise;
+  }
+
+  async commitTransaction() {
+    if (!this.#transactionPromise || !this.#transactionControl) {
+      throw new Error("No transaction to commit");
+    }
+
+    try {
+      // Signal commit and wait for transaction to complete
+      this.#transactionControl.resolve();
+      await this.#transactionPromise;
+    } finally {
+      this.#transactionPromise = null;
+      this.#transactionControl = null;
+      this.#txn = null;
+    }
+  }
+
+  async rollbackTransaction() {
+    if (!this.#transactionPromise || !this.#transactionControl) {
+      throw new Error("No transaction to rollback");
+    }
+
+    try {
+      // Signal rollback
+      if (this.#txn) {
+        this.#txn.rollback();
+      }
+      this.#transactionControl.reject(new Error("Transaction rolled back"));
+
+      // Wait for transaction to complete (will reject, but we catch it)
+      await this.#transactionPromise.catch(() => {
+        /* Expected to reject on rollback */
+      });
+    } finally {
+      this.#transactionPromise = null;
+      this.#transactionControl = null;
+      this.#txn = null;
+    }
+  }
+
+  // oxlint-disable-next-line require-yield
+  async *streamQuery<O>(
+    _compiledQuery: CompiledQuery,
+    _chunkSize: number,
+  ): AsyncIterableIterator<QueryResult<O>> {
+    throw new Error("DO Driver does not support streaming");
+  }
+}

package/src/sql-driver/driver/runtime-driver.ts

@@ -0,0 +1,91 @@
+/**
+ * Adapted from Kysely's RuntimeDriver
+ * Modified from: https://github.com/kysely-org/kysely
+ * License: MIT
+ * Copyright (c) 2022 Sami Koskimäki
+ */
+
+import type { DatabaseConnection, Driver, TransactionSettings } from "../sql-driver";
+
+/**
+ * A small wrapper around {@link Driver} that makes sure the driver is
+ * initialized before it is used, only initialized and destroyed
+ * once etc.
+ */
+export class RuntimeDriver implements Driver {
+  readonly #driver: Driver;
+
+  #initPromise?: Promise<void>;
+  #initDone: boolean;
+  #destroyPromise?: Promise<void>;
+
+  constructor(driver: Driver) {
+    this.#initDone = false;
+    this.#driver = driver;
+  }
+
+  async init(): Promise<void> {
+    if (this.#destroyPromise) {
+      throw new Error("driver has already been destroyed");
+    }
+
+    if (!this.#initPromise) {
+      this.#initPromise = this.#driver
+        .init()
+        .then(() => {
+          this.#initDone = true;
+        })
+        .catch((err) => {
+          this.#initPromise = undefined;
+          return Promise.reject(err);
+        });
+    }
+
+    await this.#initPromise;
+  }
+
+  async acquireConnection(): Promise<DatabaseConnection> {
+    if (this.#destroyPromise) {
+      throw new Error("driver has already been destroyed");
+    }
+
+    if (!this.#initDone) {
+      await this.init();
+    }
+
+    return await this.#driver.acquireConnection();
+  }
+
+  async releaseConnection(connection: DatabaseConnection): Promise<void> {
+    await this.#driver.releaseConnection(connection);
+  }
+
+  beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void> {
+    return this.#driver.beginTransaction(connection, settings);
+  }
+
+  commitTransaction(connection: DatabaseConnection): Promise<void> {
+    return this.#driver.commitTransaction(connection);
+  }
+
+  rollbackTransaction(connection: DatabaseConnection): Promise<void> {
+    return this.#driver.rollbackTransaction(connection);
+  }
+
+  async destroy(): Promise<void> {
+    if (!this.#initPromise) {
+      return;
+    }
+
+    await this.#initPromise;
+
+    if (!this.#destroyPromise) {
+      this.#destroyPromise = this.#driver.destroy().catch((err) => {
+        this.#destroyPromise = undefined;
+        return Promise.reject(err);
+      });
+    }
+
+    await this.#destroyPromise;
+  }
+}

package/src/sql-driver/query-executor/default-query-executor.ts

@@ -0,0 +1,38 @@
+/**
+ * Adapted from Kysely's DefaultQueryExecutor
+ * Modified from: https://github.com/kysely-org/kysely
+ * License: MIT
+ * Copyright (c) 2022 Sami Koskimäki
+ *
+ * Simplified to remove query compilation.
+ */
+
+import type { DatabaseConnection } from "../sql-driver";
+import type { ConnectionProvider } from "../connection/connection-provider";
+import type { GenericSQLPlugin } from "./plugin";
+import { QueryExecutorBase } from "./query-executor-base";
+
+export class DefaultQueryExecutor extends QueryExecutorBase {
+  readonly #connectionProvider: ConnectionProvider;
+
+  constructor(connectionProvider: ConnectionProvider, plugins: GenericSQLPlugin[] = []) {
+    super(plugins);
+    this.#connectionProvider = connectionProvider;
+  }
+
+  provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T> {
+    return this.#connectionProvider.provideConnection(consumer);
+  }
+
+  withConnectionProvider(connectionProvider: ConnectionProvider): DefaultQueryExecutor {
+    return new DefaultQueryExecutor(connectionProvider, [...this.plugins]);
+  }
+
+  withPlugin(plugin: GenericSQLPlugin): DefaultQueryExecutor {
+    return new DefaultQueryExecutor(this.#connectionProvider, [...this.plugins, plugin]);
+  }
+
+  withoutPlugins(): DefaultQueryExecutor {
+    return new DefaultQueryExecutor(this.#connectionProvider, []);
+  }
+}

package/src/sql-driver/query-executor/plugin.ts

@@ -0,0 +1,22 @@
+/**
+ * Adapted from Kysely's KyselyPlugin
+ * Modified from: https://github.com/kysely-org/kysely
+ * License: MIT
+ * Copyright (c) 2022 Sami Koskimäki
+ *
+ * Simplified to only support transformResult.
+ */
+
+import type { QueryResult } from "../sql-driver";
+
+export interface GenericSQLPlugin {
+  /**
+   * This method is called for each query after it has been executed.
+   * You can modify the result and return the modified result.
+   */
+  transformResult(args: PluginTransformResultArgs): Promise<QueryResult<unknown>>;
+}
+
+export interface PluginTransformResultArgs {
+  readonly result: QueryResult<unknown>;
+}

package/src/sql-driver/query-executor/query-executor-base.ts

@@ -0,0 +1,53 @@
+/**
+ * Adapted from Kysely's QueryExecutorBase
+ * Modified from: https://github.com/kysely-org/kysely
+ * License: MIT
+ * Copyright (c) 2022 Sami Koskimäki
+ *
+ * Simplified to remove query compilation, streaming, and batching.
+ */
+
+import type { DatabaseConnection, CompiledQuery, QueryResult } from "../sql-driver";
+import type { ConnectionProvider } from "../connection/connection-provider";
+import type { GenericSQLPlugin } from "./plugin";
+import type { QueryExecutor } from "./query-executor";
+
+const NO_PLUGINS: ReadonlyArray<GenericSQLPlugin> = Object.freeze([]);
+
+export abstract class QueryExecutorBase implements QueryExecutor {
+  readonly #plugins: ReadonlyArray<GenericSQLPlugin>;
+
+  constructor(plugins: ReadonlyArray<GenericSQLPlugin> = NO_PLUGINS) {
+    this.#plugins = plugins;
+  }
+
+  get plugins(): ReadonlyArray<GenericSQLPlugin> {
+    return this.#plugins;
+  }
+
+  abstract provideConnection<T>(
+    consumer: (connection: DatabaseConnection) => Promise<T>,
+  ): Promise<T>;
+
+  async executeQuery<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>> {
+    return await this.provideConnection(async (connection) => {
+      const result = await connection.executeQuery(compiledQuery);
+      return await this.#transformResult(result);
+    });
+  }
+
+  abstract withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutorBase;
+
+  abstract withPlugin(plugin: GenericSQLPlugin): QueryExecutorBase;
+
+  abstract withoutPlugins(): QueryExecutorBase;
+
+  // oxlint-disable-next-line no-explicit-any
+  async #transformResult<T>(result: QueryResult<any>): Promise<QueryResult<T>> {
+    for (const plugin of this.#plugins) {
+      result = await plugin.transformResult({ result });
+    }
+
+    return result;
+  }
+}

package/src/sql-driver/query-executor/query-executor.ts

@@ -0,0 +1,44 @@
+/**
+ * Adapted from Kysely's QueryExecutor
+ * Modified from: https://github.com/kysely-org/kysely
+ * License: MIT
+ * Copyright (c) 2022 Sami Koskimäki
+ *
+ * Simplified to remove query compilation, streaming, and batching.
+ */
+
+import type { CompiledQuery, QueryResult } from "../sql-driver";
+import type { ConnectionProvider } from "../connection/connection-provider";
+import type { GenericSQLPlugin } from "./plugin";
+
+/**
+ * This interface abstracts away the details of how to execute a query.
+ */
+export interface QueryExecutor extends ConnectionProvider {
+  /**
+   * Returns all installed plugins.
+   */
+  get plugins(): ReadonlyArray<GenericSQLPlugin>;
+
+  /**
+   * Executes a compiled query and runs the result through all plugins'
+   * `transformResult` method.
+   */
+  executeQuery<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>>;
+
+  /**
+   * Returns a copy of this executor with a new connection provider.
+   */
+  withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutor;
+
+  /**
+   * Returns a copy of this executor with a plugin added as the
+   * last plugin.
+   */
+  withPlugin(plugin: GenericSQLPlugin): QueryExecutor;
+
+  /**
+   * Returns a copy of this executor without any plugins.
+   */
+  withoutPlugins(): QueryExecutor;
+}

package/src/sql-driver/sql-driver-adapter.ts

@@ -0,0 +1,96 @@
+/**
+ * Adapted from Kysely patterns
+ * Modified from: https://github.com/kysely-org/kysely
+ * License: MIT
+ * Copyright (c) 2022 Sami Koskimäki
+ */
+
+import type { CompiledQuery, Dialect, QueryResult } from "./sql-driver";
+import { DefaultConnectionProvider } from "./connection/connection-provider";
+import { SingleConnectionProvider } from "./connection/single-connection-provider";
+import { RuntimeDriver } from "./driver/runtime-driver";
+import type { GenericSQLPlugin } from "./query-executor/plugin";
+import type { QueryExecutor } from "./query-executor/query-executor";
+import { DefaultQueryExecutor } from "./query-executor/default-query-executor";
+
+export class SqlDriverAdapter {
+  readonly #dialect: Dialect;
+  readonly #driver: RuntimeDriver | null;
+  readonly #executor: QueryExecutor;
+
+  constructor(dialect: Dialect);
+  constructor(dialect: Dialect, executor: QueryExecutor, driver: RuntimeDriver | null);
+  constructor(dialect: Dialect, executor?: QueryExecutor, driver?: RuntimeDriver | null) {
+    this.#dialect = dialect;
+
+    if (executor) {
+      this.#driver = driver ?? null;
+      this.#executor = executor;
+    } else {
+      const rawDriver = dialect.createDriver();
+      const runtimeDriver = new RuntimeDriver(rawDriver);
+      const connectionProvider = new DefaultConnectionProvider(runtimeDriver);
+      this.#driver = runtimeDriver;
+      this.#executor = new DefaultQueryExecutor(connectionProvider);
+    }
+  }
+
+  async executeQuery(query: CompiledQuery): Promise<QueryResult<Record<string, unknown>>> {
+    return await this.#executor.executeQuery(query);
+  }
+
+  async transaction<T>(callback: (trx: SqlDriverAdapter) => Promise<T>): Promise<T> {
+    if (this.#driver === null) {
+      throw new Error("Cannot start transaction: adapter was created with custom executor");
+    }
+
+    const driver = this.#driver;
+
+    return await this.#executor.provideConnection(async (connection) => {
+      const singleConnectionProvider = new SingleConnectionProvider(connection);
+      const transactionExecutor = this.#executor.withConnectionProvider(singleConnectionProvider);
+      const transactionAdapter = new SqlDriverAdapter(this.#dialect, transactionExecutor, driver);
+
+      let transactionBegun = false;
+      try {
+        await driver.beginTransaction(connection, {});
+        transactionBegun = true;
+
+        const result = await callback(transactionAdapter);
+
+        await driver.commitTransaction(connection);
+
+        return result;
+      } catch (error) {
+        if (transactionBegun) {
+          await driver.rollbackTransaction(connection);
+        }
+
+        throw error;
+      }
+    });
+  }
+
+  /**
+   * Returns a copy of this adapter with the given plugin installed.
+   */
+  withPlugin(plugin: GenericSQLPlugin): SqlDriverAdapter {
+    return new SqlDriverAdapter(this.#dialect, this.#executor.withPlugin(plugin), this.#driver);
+  }
+
+  /**
+   * Returns a copy of this adapter without any plugins.
+   */
+  withoutPlugins(): SqlDriverAdapter {
+    return new SqlDriverAdapter(this.#dialect, this.#executor.withoutPlugins(), this.#driver);
+  }
+
+  /**
+   * Releases all resources and disconnects from the database.
+   */
+  async destroy(): Promise<void> {
+    if (this.#driver !== null) {
+      await this.#driver.destroy();
+    }
+  }
+}