@fragno-dev/db 0.1.14 → 0.2.0

package/src/schema/type-conversion/create-sql-type-mapper.ts

@@ -0,0 +1,28 @@
+import type { SupportedDatabase } from "../../adapters/generic-sql/driver-config";
+import { PostgreSQLTypeMapper } from "./dialect/postgres";
+import { MySQLTypeMapper } from "./dialect/mysql";
+import { SQLiteTypeMapper } from "./dialect/sqlite";
+
+/**
+ * Factory function to create a dialect-specific SQL type mapper.
+ *
+ * Based on the database type, returns the appropriate mapper implementation
+ * (PostgreSQL, MySQL, or SQLite).
+ *
+ * @param database - The database type (sqlite, postgresql, or mysql)
+ * @returns Dialect-specific SQLTypeMapper instance
+ */
+export function createSQLTypeMapper(database: SupportedDatabase) {
+  switch (database) {
+    case "postgresql":
+      return new PostgreSQLTypeMapper(database);
+    case "mysql":
+      return new MySQLTypeMapper(database);
+    case "sqlite":
+      return new SQLiteTypeMapper(database);
+    default: {
+      const exhaustiveCheck: never = database;
+      throw new Error(`Unsupported database type: ${exhaustiveCheck}`);
+    }
+  }
+}

package/src/schema/type-conversion/dialect/mysql.ts

@@ -0,0 +1,64 @@
+import type { AnyColumn } from "../../create";
+import { SQLTypeMapper, type MySQLDatabaseType } from "../type-mapping";
+
+/**
+ * MySQL-specific type mapper.
+ *
+ * MySQL supports:
+ * - BIGINT for large integers (with AUTO_INCREMENT for internal IDs)
+ * - INTEGER for integers
+ * - BOOLEAN for booleans (alias for TINYINT(1))
+ * - JSON for JSON data (native support in MySQL 5.7+)
+ * - TEXT for strings
+ * - VARCHAR(n) for variable-length strings
+ * - LONGBLOB for binary data
+ * - DATETIME for timestamps without timezone
+ * - DATE for dates
+ * - DECIMAL for decimals
+ */
+export class MySQLTypeMapper extends SQLTypeMapper<MySQLDatabaseType> {
+  protected getInternalIdType(): MySQLDatabaseType {
+    // MySQL uses bigint with AUTO_INCREMENT applied separately
+    return "bigint";
+  }
+
+  protected mapInteger(_column: AnyColumn | Pick<AnyColumn, "type">): MySQLDatabaseType {
+    return "integer";
+  }
+
+  protected mapBigint(_column: AnyColumn | Pick<AnyColumn, "type">): MySQLDatabaseType {
+    return "bigint";
+  }
+
+  protected mapString(): MySQLDatabaseType {
+    return "text";
+  }
+
+  protected mapVarchar(length: number): MySQLDatabaseType {
+    return `varchar(${length})`;
+  }
+
+  protected mapBinary(): MySQLDatabaseType {
+    return "longblob";
+  }
+
+  protected mapBool(): MySQLDatabaseType {
+    return "boolean";
+  }
+
+  protected mapDecimal(): MySQLDatabaseType {
+    return "decimal";
+  }
+
+  protected mapTimestamp(): MySQLDatabaseType {
+    return "datetime";
+  }
+
+  protected mapDate(): MySQLDatabaseType {
+    return "date";
+  }
+
+  protected mapJson(): MySQLDatabaseType {
+    return "json";
+  }
+}

package/src/schema/type-conversion/dialect/postgres.ts

@@ -0,0 +1,62 @@
+import type { AnyColumn } from "../../create";
+import { SQLTypeMapper, type PostgreSQLDatabaseType } from "../type-mapping";
+
+/**
+ * PostgreSQL-specific type mapper.
+ *
+ * PostgreSQL supports:
+ * - BIGSERIAL for auto-increment
+ * - BOOLEAN for booleans
+ * - JSON for JSON data
+ * - TEXT for strings
+ * - VARCHAR(n) for variable-length strings
+ * - BYTEA for binary data
+ * - Full timestamp and date support
+ * - BIGINT and INTEGER for integers
+ * - DECIMAL for decimals
+ */
+export class PostgreSQLTypeMapper extends SQLTypeMapper<PostgreSQLDatabaseType> {
+  protected getInternalIdType(): PostgreSQLDatabaseType {
+    return "bigserial";
+  }
+
+  protected mapInteger(_column: AnyColumn | Pick<AnyColumn, "type">): PostgreSQLDatabaseType {
+    return "integer";
+  }
+
+  protected mapBigint(_column: AnyColumn | Pick<AnyColumn, "type">): PostgreSQLDatabaseType {
+    return "bigint";
+  }
+
+  protected mapString(): PostgreSQLDatabaseType {
+    return "text";
+  }
+
+  protected mapVarchar(length: number): PostgreSQLDatabaseType {
+    return `varchar(${length})`;
+  }
+
+  protected mapBinary(): PostgreSQLDatabaseType {
+    return "bytea";
+  }
+
+  protected mapBool(): PostgreSQLDatabaseType {
+    return "boolean";
+  }
+
+  protected mapDecimal(): PostgreSQLDatabaseType {
+    return "decimal";
+  }
+
+  protected mapTimestamp(): PostgreSQLDatabaseType {
+    return "timestamp";
+  }
+
+  protected mapDate(): PostgreSQLDatabaseType {
+    return "date";
+  }
+
+  protected mapJson(): PostgreSQLDatabaseType {
+    return "json";
+  }
+}

package/src/schema/type-conversion/dialect/sqlite.ts

@@ -0,0 +1,63 @@
+import type { AnyColumn } from "../../create";
+import { SQLTypeMapper, type SQLiteDatabaseType } from "../type-mapping";
+
+/**
+ * SQLite-specific type mapper.
+ *
+ * SQLite has a limited type system with only 4 storage classes:
+ * - INTEGER for integers, booleans, timestamps, dates (and reference columns)
+ * - BLOB for binary data and bigints (except for reference columns)
+ * - TEXT for strings, JSON, and varchar
+ * - REAL for decimals
+ */
+export class SQLiteTypeMapper extends SQLTypeMapper<SQLiteDatabaseType> {
+  protected getInternalIdType(): SQLiteDatabaseType {
+    // SQLite uses INTEGER for auto-increment (INTEGER PRIMARY KEY)
+    return "integer";
+  }
+
+  protected mapInteger(_column: AnyColumn | Pick<AnyColumn, "type">): SQLiteDatabaseType {
+    return "integer";
+  }
+
+  protected mapBigint(column: AnyColumn | Pick<AnyColumn, "type">): SQLiteDatabaseType {
+    // SQLite special case: reference columns should use integer even if type is bigint
+    if ("role" in column && column.role === "reference") {
+      return "integer";
+    }
+    return "blob";
+  }
+
+  protected mapString(): SQLiteDatabaseType {
+    return "text";
+  }
+
+  protected mapVarchar(_length: number): SQLiteDatabaseType {
+    // SQLite doesn't support varchar - convert to text
+    return "text";
+  }
+
+  protected mapBinary(): SQLiteDatabaseType {
+    return "blob";
+  }
+
+  protected mapBool(): SQLiteDatabaseType {
+    return "integer";
+  }
+
+  protected mapDecimal(): SQLiteDatabaseType {
+    return "real";
+  }
+
+  protected mapTimestamp(): SQLiteDatabaseType {
+    return "integer";
+  }
+
+  protected mapDate(): SQLiteDatabaseType {
+    return "integer";
+  }
+
+  protected mapJson(): SQLiteDatabaseType {
+    return "text";
+  }
+}

package/src/schema/type-conversion/type-mapping.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import { column } from "../create";
+import { createSQLTypeMapper } from "./create-sql-type-mapper";
+
+describe("SQLTypeMapper", () => {
+  describe("error handling", () => {
+    it("should throw error for varchar without length", () => {
+      const mapper = createSQLTypeMapper("postgresql");
+      // @ts-expect-error - Testing runtime error handling for invalid type
+      expect(() => mapper.getDatabaseType({ type: "varchar" })).toThrow(
+        'Invalid varchar format: "varchar". Expected format: varchar(number), e.g., varchar(255)',
+      );
+    });
+
+    it("should throw error for varchar with non-numeric length", () => {
+      const mapper = createSQLTypeMapper("mysql");
+      // @ts-expect-error - Testing runtime error handling for invalid type
+      expect(() => mapper.getDatabaseType({ type: "varchar(abc)" })).toThrow(
+        'Invalid varchar format: "varchar(abc)". Expected format: varchar(number), e.g., varchar(255)',
+      );
+    });
+
+    it("should throw error for malformed varchar", () => {
+      const mapper = createSQLTypeMapper("sqlite");
+      // @ts-expect-error - Testing runtime error handling for invalid type
+      expect(() => mapper.getDatabaseType({ type: "varchar(100" })).toThrow(
+        'Invalid varchar format: "varchar(100". Expected format: varchar(number), e.g., varchar(255)',
+      );
+    });
+
+    it("should throw error for completely unsupported type", () => {
+      const mapper = createSQLTypeMapper("postgresql");
+      // @ts-expect-error - Testing runtime error handling for invalid type
+      expect(() => mapper.getDatabaseType({ type: "unsupported" })).toThrow(
+        "Unsupported column type: unsupported",
+      );
+    });
+  });
+
+  describe("sqlite", () => {
+    const mapper = createSQLTypeMapper("sqlite");
+
+    it("should convert integer types to integer", () => {
+      expect(mapper.getDatabaseType(column("integer"))).toBe("integer");
+    });
+
+    it("should convert timestamp to integer", () => {
+      expect(mapper.getDatabaseType(column("timestamp"))).toBe("integer");
+    });
+
+    it("should convert date to integer", () => {
+      expect(mapper.getDatabaseType(column("date"))).toBe("integer");
+    });
+
+    it("should convert bool to integer", () => {
+      expect(mapper.getDatabaseType(column("bool"))).toBe("integer");
+    });
+
+    it("should convert binary to blob", () => {
+      expect(mapper.getDatabaseType(column("binary"))).toBe("blob");
+    });
+
+    it("should convert bigint to blob", () => {
+      expect(mapper.getDatabaseType(column("bigint"))).toBe("blob");
+    });
+
+    it("should convert json to text", () => {
+      expect(mapper.getDatabaseType(column("json"))).toBe("text");
+    });
+
+    it("should convert string to text", () => {
+      expect(mapper.getDatabaseType(column("string"))).toBe("text");
+    });
+
+    it("should convert varchar to text", () => {
+      expect(mapper.getDatabaseType({ type: "varchar(255)" })).toBe("text");
+    });
+
+    it("should convert decimal to real", () => {
+      expect(mapper.getDatabaseType(column("decimal"))).toBe("real");
+    });
+  });
+
+  describe("postgresql", () => {
+    const mapper = createSQLTypeMapper("postgresql");
+
+    it("should convert bool to boolean", () => {
+      expect(mapper.getDatabaseType(column("bool"))).toBe("boolean");
+    });
+
+    it("should convert json to json", () => {
+      expect(mapper.getDatabaseType(column("json"))).toBe("json");
+    });
+
+    it("should convert string to text", () => {
+      expect(mapper.getDatabaseType(column("string"))).toBe("text");
+    });
+
+    it("should convert binary to bytea", () => {
+      expect(mapper.getDatabaseType(column("binary"))).toBe("bytea");
+    });
+
+    it("should preserve varchar with length", () => {
+      expect(mapper.getDatabaseType({ type: "varchar(200)" })).toBe("varchar(200)");
+    });
+
+    it("should preserve other types", () => {
+      expect(mapper.getDatabaseType(column("timestamp"))).toBe("timestamp");
+      expect(mapper.getDatabaseType(column("integer"))).toBe("integer");
+    });
+  });
+
+  describe("mysql", () => {
+    const mapper = createSQLTypeMapper("mysql");
+
+    it("should convert bool to boolean", () => {
+      expect(mapper.getDatabaseType(column("bool"))).toBe("boolean");
+    });
+
+    it("should convert string to text", () => {
+      expect(mapper.getDatabaseType(column("string"))).toBe("text");
+    });
+
+    it("should convert binary to longblob", () => {
+      expect(mapper.getDatabaseType(column("binary"))).toBe("longblob");
+    });
+
+    it("should preserve varchar with length", () => {
+      expect(mapper.getDatabaseType({ type: "varchar(150)" })).toBe("varchar(150)");
+    });
+
+    it("should preserve other types", () => {
+      expect(mapper.getDatabaseType(column("integer"))).toBe("integer");
+      expect(mapper.getDatabaseType(column("json"))).toBe("json");
+    });
+  });
+});

package/src/schema/type-conversion/type-mapping.ts

@@ -0,0 +1,153 @@
+import type { SupportedDatabase } from "../../adapters/generic-sql/driver-config";
+import type { AnyColumn } from "../create";
+
+export interface AdditionalColumnMetadata {
+  length?: number;
+  precision?: number;
+  scale?: number;
+}
+
+/**
+ * PostgreSQL-specific database types
+ */
+export type PostgreSQLDatabaseType =
+  | "bigserial"
+  | "serial"
+  | "boolean"
+  | "json"
+  | "text"
+  | "bytea"
+  | "timestamp"
+  | "timestamptz"
+  | "bigint"
+  | "integer"
+  | "decimal"
+  | "date"
+  | `varchar(${number})`;
+
+/**
+ * MySQL-specific database types
+ */
+export type MySQLDatabaseType =
+  | "bigint"
+  | "boolean"
+  | "text"
+  | "longblob"
+  | "integer"
+  | "decimal"
+  | "date"
+  | "datetime"
+  | "json"
+  | "timestamp"
+  | `varchar(${number})`;
+
+/**
+ * SQLite-specific database types
+ */
+export type SQLiteDatabaseType = "integer" | "blob" | "text" | "real";
+
+/**
+ * Union of all database-specific types
+ */
+export type DatabaseTypeLiteral = PostgreSQLDatabaseType | MySQLDatabaseType | SQLiteDatabaseType;
+
+/**
+ * Abstract base class for SQL type mapping.
+ *
+ * Similar to SQLQueryCompiler and SQLGenerator, this class provides a framework
+ * for mapping schema column types to database-specific column types.
+ *
+ * Each database dialect extends this class and implements abstract methods
+ * for each column type. The base class handles the switch statement logic.
+ *
+ * @template TDatabaseType - The specific database type union for this dialect
+ */
+export abstract class SQLTypeMapper<TDatabaseType extends DatabaseTypeLiteral> {
+  protected readonly database: SupportedDatabase;
+
+  constructor(database: SupportedDatabase) {
+    this.database = database;
+  }
+
+  /**
+   * Get the database type for internal ID columns.
+   */
+  protected abstract getInternalIdType(): TDatabaseType;
+
+  // Abstract methods for each column type that dialects must implement
+  protected abstract mapInteger(column: AnyColumn | Pick<AnyColumn, "type">): TDatabaseType;
+  protected abstract mapBigint(column: AnyColumn | Pick<AnyColumn, "type">): TDatabaseType;
+  protected abstract mapString(): TDatabaseType;
+  protected abstract mapVarchar(length: number): TDatabaseType;
+  protected abstract mapBinary(): TDatabaseType;
+  protected abstract mapBool(): TDatabaseType;
+  protected abstract mapDecimal(): TDatabaseType;
+  protected abstract mapTimestamp(): TDatabaseType;
+  protected abstract mapDate(): TDatabaseType;
+  protected abstract mapJson(): TDatabaseType;
+
+  /**
+   * Map a column type to a database-specific type.
+   * Contains the central switch statement that delegates to abstract methods.
+   */
+  protected mapColumnType(column: AnyColumn | Pick<AnyColumn, "type">): TDatabaseType {
+    const { type } = column;
+
+    // Handle varchar with length parameter
+    if (typeof type === "string" && type.startsWith("varchar")) {
+      const match = type.match(/^varchar\((\d+)\)$/);
+      if (match) {
+        const length = parseInt(match[1], 10);
+        return this.mapVarchar(length);
+      }
+      throw new Error(
+        `Invalid varchar format: "${type}". Expected format: varchar(number), e.g., varchar(255)`,
+      );
+    }
+
+    switch (type) {
+      case "integer":
+        return this.mapInteger(column);
+      case "bigint":
+        return this.mapBigint(column);
+      case "string":
+        return this.mapString();
+      case "binary":
+        return this.mapBinary();
+      case "bool":
+        return this.mapBool();
+      case "decimal":
+        return this.mapDecimal();
+      case "timestamp":
+        return this.mapTimestamp();
+      case "date":
+        return this.mapDate();
+      case "json":
+        return this.mapJson();
+      default:
+        // TypeScript should ensure we never reach here
+        throw new Error(`Unsupported column type: ${type}`);
+    }
+  }
+
+  /**
+   * Map a schema column type to the appropriate database column type.
+   * Used for generating CREATE TABLE statements and migrations.
+   *
+   * Handles common cases like internal-id columns,
+   * then delegates to mapColumnType for other types.
+   *
+   * @param column - The column schema definition
+   * @returns The database-specific column type
+   */
+  getDatabaseType(column: AnyColumn | Pick<AnyColumn, "type">): TDatabaseType {
+    // Handle internal ID columns with auto-increment
+    if ("role" in column && column.role === "internal-id") {
+      return this.getInternalIdType();
+    }
+
+    // Delegate to type mapping logic
+    // This includes reference columns, which should use their specified type
+    return this.mapColumnType(column);
+  }
+}

package/src/shared/connection-pool.ts

@@ -1,8 +1,8 @@
 /**
  * Represents an active database connection that can be released back to the pool.
  */
-export interface Connection<TDb> {
-  db: TDb;
+export interface Connection<TDatabase> {
+  db: TDatabase;
   release(): Promise<void>;
 }
 
@@ -10,15 +10,15 @@ export interface Connection<TDb> {
  * Connection pool interface for managing database connections.
  * Adapter-specific implementations should be used (e.g., createKyselyConnectionPool, createDrizzleConnectionPool).
  */
-export interface ConnectionPool<TDb> {
+export interface ConnectionPool<TDatabase> {
   /** Acquire a connection from the pool */
-  connect(): Promise<Connection<TDb>>;
+  connect(): Promise<Connection<TDatabase>>;
   /**
    * Get the database instance synchronously. Only works if the pool has already been initialized
    * via connect().
    * @throws an error if called before the pool is initialized.
    */
-  getDatabaseSync(): TDb;
+  getDatabaseSync(): TDatabase;
   /** Close the pool and cleanup resources */
   close(): Promise<void>;
 }

package/src/sql-driver/better-sqlite3.test.ts

@@ -0,0 +1,126 @@
+import SQLite from "better-sqlite3";
+import { describe, expect, it } from "vitest";
+import { SqlDriverAdapter } from "./sql-driver-adapter";
+import type { GenericSQLPlugin } from "./query-executor/plugin";
+import { sql } from "./sql";
+import { SqliteDialect } from "kysely";
+
+describe("better-sqlite3", () => {
+  it("Should be able to execute queries using better-sqlite3", async () => {
+    const dialect = new SqliteDialect({
+      database: new SQLite(":memory:"),
+    });
+
+    const adapter = new SqlDriverAdapter(dialect);
+
+    const query = sql`SELECT 5`.compile(dialect);
+    const result = await adapter.executeQuery(query);
+    expect(result.rows).toEqual([{ 5: 5 }]);
+
+    await adapter.destroy();
+  });
+
+  it("should execute queries in a transaction and commit", async () => {
+    const dialect = new SqliteDialect({
+      database: new SQLite(":memory:"),
+    });
+    const adapter = new SqlDriverAdapter(dialect);
+
+    // Create table outside transaction
+    await adapter.executeQuery(sql`CREATE TABLE test (id INTEGER, name TEXT)`.compile(dialect));
+
+    // Execute queries in transaction
+    await adapter.transaction(async (trx) => {
+      await trx.executeQuery(sql`INSERT INTO test VALUES (1, 'Alice')`.compile(dialect));
+      await trx.executeQuery(sql`INSERT INTO test VALUES (2, 'Bob')`.compile(dialect));
+    });
+
+    // Verify data persists after transaction
+    const result = await adapter.executeQuery(sql`SELECT * FROM test ORDER BY id`.compile(dialect));
+    expect(result.rows).toEqual([
+      { id: 1, name: "Alice" },
+      { id: 2, name: "Bob" },
+    ]);
+
+    await adapter.destroy();
+  });
+
+  it("should rollback transaction on error", async () => {
+    const dialect = new SqliteDialect({
+      database: new SQLite(":memory:"),
+    });
+    const adapter = new SqlDriverAdapter(dialect);
+
+    // Create table outside transaction
+    await adapter.executeQuery(
+      sql`CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)`.compile(dialect),
+    );
+    await adapter.executeQuery(sql`INSERT INTO test VALUES (1, 'Alice')`.compile(dialect));
+
+    // Try to execute queries in transaction with duplicate key error
+    await expect(
+      adapter.transaction(async (trx) => {
+        await trx.executeQuery(sql`INSERT INTO test VALUES (2, 'Bob')`.compile(dialect));
+        // This should cause a duplicate key error
+        await trx.executeQuery(sql`INSERT INTO test VALUES (1, 'Charlie')`.compile(dialect));
+      }),
+    ).rejects.toThrow();
+
+    // Verify Bob was not inserted (transaction rolled back)
+    const result = await adapter.executeQuery(sql`SELECT * FROM test ORDER BY id`.compile(dialect));
+    expect(result.rows).toEqual([{ id: 1, name: "Alice" }]);
+
+    await adapter.destroy();
+  });
+
+  it("should support plugins that transform results", async () => {
+    const dialect = new SqliteDialect({
+      database: new SQLite(":memory:"),
+    });
+    const adapter = new SqlDriverAdapter(dialect);
+
+    // Create a plugin that adds metadata to results
+    const metadataPlugin: GenericSQLPlugin = {
+      async transformResult({ result }) {
+        return {
+          ...result,
+          rows: result.rows.map((row) => ({
+            ...(row as object),
+            __metadata: { transformed: true },
+          })),
+        };
+      },
+    };
+
+    const adapterWithPlugin = adapter.withPlugin(metadataPlugin);
+
+    await adapterWithPlugin.executeQuery(
+      sql`CREATE TABLE test (id INTEGER, name TEXT)`.compile(dialect),
+    );
+    await adapterWithPlugin.executeQuery(
+      sql`INSERT INTO test VALUES (1, 'Alice')`.compile(dialect),
+    );
+
+    const result = await adapterWithPlugin.executeQuery(sql`SELECT * FROM test`.compile(dialect));
+
+    expect(result.rows).toEqual([{ id: 1, name: "Alice", __metadata: { transformed: true } }]);
+
+    await adapter.destroy();
+  });
+
+  it("should properly destroy and release resources", async () => {
+    const dialect = new SqliteDialect({
+      database: new SQLite(":memory:"),
+    });
+    const adapter = new SqlDriverAdapter(dialect);
+
+    // Execute some queries
+    await adapter.executeQuery(sql`SELECT 1`.compile(dialect));
+
+    // Destroy should complete without error
+    await expect(adapter.destroy()).resolves.toBeUndefined();
+
+    // Multiple destroy calls should be safe
+    await expect(adapter.destroy()).resolves.toBeUndefined();
+  });
+});

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

@@ -0,0 +1,27 @@
+import type { DatabaseConnection, Driver } from "../sql-driver";
+
+export interface ConnectionProvider {
+  /**
+   * Provides a connection for the callback and takes care of disposing
+   * the connection after the callback has been run.
+   */
+  provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
+}
+
+export class DefaultConnectionProvider implements ConnectionProvider {
+  readonly #driver: Driver;
+
+  constructor(driver: Driver) {
+    this.#driver = driver;
+  }
+
+  async provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T> {
+    const connection = await this.#driver.acquireConnection();
+
+    try {
+      return await consumer(connection);
+    } finally {
+      await this.#driver.releaseConnection(connection);
+    }
+  }
+}