durcno 1.0.0-alpha.0

package/dist/src/columns/timestamp.mjs

@@ -0,0 +1,47 @@
+import { Column } from "./common.mjs";
+import { Sql } from "../sql.mjs";
+import * as z from "zod";
+//#region src/columns/timestamp.ts
+var TimestampColumn = class extends Column {
+	static id = "Column.Timestamp";
+	#withTimezone;
+	#precision;
+	constructor(config) {
+		super(config);
+		this.#withTimezone = config.withTimezone ?? true;
+		this.#precision = config.precision;
+	}
+	get sqlTypeScalar() {
+		return `timestamp${this.#precision !== void 0 ? `(${this.#precision})` : ""}${this.#withTimezone ? " with time zone" : ""}`;
+	}
+	get zodTypeScaler() {
+		return z.iso.datetime({ precision: this.#precision });
+	}
+	toDriverScalar(value) {
+		if (value === null) return null;
+		return value instanceof Sql ? value.string : value.toISOString();
+	}
+	toSQLScalar(value) {
+		if (value === null) return "NULL";
+		return value instanceof Sql ? value.string : `'${value.toISOString()}'`;
+	}
+	fromDriverScalar(value) {
+		return value;
+	}
+};
+/**
+* Creates a `timestamp` column. Date and time, maps to `Date`.
+*
+* @example
+* ```ts
+* timestamp({ withTimezone: true, precision: 3, notNull }) // timestamp(3) with time zone NOT NULL
+* ```
+*
+* @param config.withTimezone - Include timezone info (default: `true`)
+* @param config.precision - Fractional seconds precision (0–6)
+*/
+function timestamp(config) {
+	return new TimestampColumn(config);
+}
+//#endregion
+export { timestamp };

package/dist/src/columns/uuid.d.mts

@@ -0,0 +1,33 @@
+import { Sql } from "../sql.mjs";
+import { Column, ColumnConfig } from "./common.mjs";
+import * as z from "zod";
+
+//#region src/columns/uuid.d.ts
+type UuidValType = string;
+/** Supported UUID versions for validation. */
+type UuidVersion = "v1" | "v2" | "v3" | "v4" | "v5" | "v6" | "v7" | "v8";
+type UuidConfig = ColumnConfig & {
+  /** UUID version to validate against in the Zod schema (e.g. `"v4"`, `"v7"`). */version?: UuidVersion;
+};
+declare class UuidColumn<TConfig extends UuidConfig> extends Column<TConfig, UuidValType> {
+  static readonly id = "Column.Uuid";
+  get sqlTypeScalar(): string;
+  get zodTypeScaler(): z.ZodUUID;
+  toDriverScalar(value: UuidValType | Sql | null): string | null;
+  toSQLScalar(value: UuidValType | Sql | null): string;
+  fromDriverScalar(value: string | null): UuidValType | null;
+}
+/**
+ * Creates a `uuid` column. PostgreSQL universally unique identifier type, maps to `string`.
+ *
+ * @example
+ * ```ts
+ * uuid({ notNull })                // uuid NOT NULL, zod validates v7 (default)
+ * uuid({ notNull, version: "v4" }) // uuid NOT NULL, zod validates v4
+ * ```
+ *
+ * @param config.version - UUID version to validate in the Zod schema (default: `"v7"`)
+ */
+declare function uuid<TConfig extends UuidConfig>(config: TConfig): UuidColumn<TConfig>;
+//#endregion
+export { UuidVersion, uuid };

package/dist/src/columns/uuid.mjs

@@ -0,0 +1,44 @@
+import { Column } from "./common.mjs";
+import { Sql } from "../sql.mjs";
+import * as z from "zod";
+//#region src/columns/uuid.ts
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var UuidColumn = class extends Column {
+	static id = "Column.Uuid";
+	get sqlTypeScalar() {
+		return "uuid";
+	}
+	get zodTypeScaler() {
+		const version = this.config.version ?? "v7";
+		return z.uuid({ version });
+	}
+	toDriverScalar(value) {
+		if (value === null) return null;
+		return value instanceof Sql ? value.string : value;
+	}
+	toSQLScalar(value) {
+		if (value === null) return "NULL";
+		if (value instanceof Sql) return value.string;
+		if (!UUID_REGEX.test(value)) throw new Error(`Invalid UUID value: ${value}`);
+		return `'${value}'`;
+	}
+	fromDriverScalar(value) {
+		return value;
+	}
+};
+/**
+* Creates a `uuid` column. PostgreSQL universally unique identifier type, maps to `string`.
+*
+* @example
+* ```ts
+* uuid({ notNull })                // uuid NOT NULL, zod validates v7 (default)
+* uuid({ notNull, version: "v4" }) // uuid NOT NULL, zod validates v4
+* ```
+*
+* @param config.version - UUID version to validate in the Zod schema (default: `"v7"`)
+*/
+function uuid(config) {
+	return new UuidColumn(config);
+}
+//#endregion
+export { uuid };

package/dist/src/columns/varchar.d.mts

@@ -0,0 +1,32 @@
+import { Sql } from "../sql.mjs";
+import { Column, ColumnConfig } from "./common.mjs";
+import * as z from "zod";
+
+//#region src/columns/varchar.d.ts
+type VarcharValType = string;
+type VarcharConfig = ColumnConfig & {
+  /** Maximum character length (default: 255) */length?: number;
+};
+declare class VarcharColumn<TConfig extends VarcharConfig> extends Column<TConfig, VarcharValType> {
+  #private;
+  static readonly id = "Column.Varchar";
+  constructor(config: TConfig);
+  get sqlTypeScalar(): string;
+  get zodTypeScaler(): z.ZodString;
+  toDriverScalar(value: VarcharValType | Sql | null): string | null;
+  toSQLScalar(value: string | Sql | null): string;
+  fromDriverScalar(value: string | null): VarcharValType | null;
+}
+/**
+ * Creates a `varchar` column. Variable-length string with a maximum length, maps to `string`.
+ *
+ * @example
+ * ```ts
+ * varchar({ length: 255, notNull }) // varchar(255) NOT NULL
+ * ```
+ *
+ * @param config.length - Maximum character length (default: 255)
+ */
+declare function varchar<TConfig extends VarcharConfig>(config: TConfig): VarcharColumn<TConfig>;
+//#endregion
+export { VarcharColumn, varchar };

package/dist/src/columns/varchar.mjs

@@ -0,0 +1,44 @@
+import { Column } from "./common.mjs";
+import { Sql } from "../sql.mjs";
+import * as z from "zod";
+//#region src/columns/varchar.ts
+var VarcharColumn = class extends Column {
+	static id = "Column.Varchar";
+	#length;
+	constructor(config) {
+		super(config);
+		this.#length = config.length ?? 255;
+	}
+	get sqlTypeScalar() {
+		return `varchar(${this.#length})`;
+	}
+	get zodTypeScaler() {
+		return z.string().max(this.#length);
+	}
+	toDriverScalar(value) {
+		if (value === null) return null;
+		return value instanceof Sql ? value.string : value;
+	}
+	toSQLScalar(value) {
+		if (value === null) return "NULL";
+		return value instanceof Sql ? value.string : `'${value.replace(/'/g, "''")}'`;
+	}
+	fromDriverScalar(value) {
+		return value;
+	}
+};
+/**
+* Creates a `varchar` column. Variable-length string with a maximum length, maps to `string`.
+*
+* @example
+* ```ts
+* varchar({ length: 255, notNull }) // varchar(255) NOT NULL
+* ```
+*
+* @param config.length - Maximum character length (default: 255)
+*/
+function varchar(config) {
+	return new VarcharColumn(config);
+}
+//#endregion
+export { varchar };

package/dist/src/connectors/bun.d.mts

@@ -0,0 +1,18 @@
+import { Connector } from "./common.mjs";
+
+//#region src/connectors/bun.d.ts
+/**
+ * Connector implementation for the Bun built-in SQL client.
+ *
+ * Bun provides a native, high-performance PostgreSQL client as part of
+ * its runtime. This connector leverages Bun's built-in SQL API for
+ * optimal performance in Bun environments.
+ *
+ * @see https://bun.sh/docs/api/sql
+ */
+declare class BunConnector extends Connector {
+  getClient(): BunClient;
+  getPool(): BunPool;
+}
+//#endregion
+export { BunConnector };

package/dist/src/connectors/bun.mjs

@@ -0,0 +1,97 @@
+import { $Client, $Pool, Connector } from "./common.mjs";
+import { SQL } from "bun";
+//#region src/connectors/bun.ts
+/**
+* Connector implementation for the Bun built-in SQL client.
+*
+* Bun provides a native, high-performance PostgreSQL client as part of
+* its runtime. This connector leverages Bun's built-in SQL API for
+* optimal performance in Bun environments.
+*
+* @see https://bun.sh/docs/api/sql
+*/
+var BunConnector = class extends Connector {
+	getClient() {
+		return new BunClient(this.url);
+	}
+	getPool() {
+		return new BunPool(this.url, this.config.pool);
+	}
+};
+/**
+* Single-connection client wrapper for Bun's SQL API.
+*
+* Configures Bun's SQL client with `max: 1` to simulate single-connection
+* behavior. Uses Bun's native PostgreSQL protocol implementation.
+*
+* @internal
+*/
+var BunClient = class extends $Client {
+	#client;
+	constructor(connectionString) {
+		super();
+		this.#client = new SQL(connectionString, { max: 1 });
+		this.query = this.#client.unsafe.bind(this.#client);
+	}
+	async connect() {
+		await this.#client.connect();
+	}
+	getRows(response) {
+		return response;
+	}
+	async close() {
+		await this.#client.end();
+	}
+};
+/**
+* Connection pool wrapper for Bun's SQL API.
+*
+* Bun's SQL client has built-in connection pooling. This wrapper configures
+* the pool size via the `max` option for optimal concurrent query handling.
+*
+* @internal
+*/
+var BunPool = class extends $Pool {
+	#pool;
+	constructor(connectionString, pool) {
+		super();
+		this.#pool = new SQL(connectionString, { max: pool?.max ?? 10 });
+		this.query = this.#pool.unsafe.bind(this.#pool);
+	}
+	async connect() {
+		await this.#pool.connect();
+	}
+	getRows(response) {
+		return response;
+	}
+	async close() {
+		await this.#pool.end();
+	}
+	async acquireClient() {
+		return new BunPoolClient(await this.#pool.reserve());
+	}
+};
+/**
+* Client wrapper for a reserved connection from a Bun SQL pool.
+*
+* This client uses a reserved connection that's exclusive until released.
+*
+* @internal
+*/
+var BunPoolClient = class extends $Client {
+	#sql;
+	constructor(sql) {
+		super();
+		this.#sql = sql;
+		this.query = this.#sql.unsafe.bind(this.#sql);
+	}
+	async connect() {}
+	getRows(response) {
+		return response;
+	}
+	async close() {
+		this.#sql.release();
+	}
+};
+//#endregion
+export { BunConnector };

package/dist/src/connectors/common.d.mts

@@ -0,0 +1,148 @@
+import { Config } from "../index.mjs";
+
+//#region src/connectors/common.d.ts
+/**
+ * Abstract base class for all database connectors.
+ *
+ * Connectors provide a unified interface for creating database clients
+ * and connection pools across different PostgreSQL client libraries.
+ * Each connector implementation wraps a specific library (pg, postgres.js,
+ * PGlite, Bun SQL) while exposing a consistent API.
+ *
+ * @abstract
+ */
+declare abstract class Connector {
+  /** The configuration object containing file paths, database credentials, client configs etc. */
+  config: Config;
+  /** The PostgreSQL connection URL derived from the configuration. */
+  url: string;
+  constructor(config: Config);
+  /**
+   * Creates a single-connection client.
+   *
+   * Used by the Transaction class and CLI commands where connection
+   * pooling is not required.
+   *
+   * @returns A client instance for executing queries.
+   */
+  abstract getClient(): $Client;
+  /**
+   * Creates a connection pool.
+   *
+   * Used by the Database class which handles multiple concurrent
+   * database requests.
+   *
+   * @returns A pool instance for executing queries with connection reuse.
+   */
+  abstract getPool(): $Pool;
+}
+/**
+ * Abstract base class for single-connection database clients.
+ *
+ * Implementations wrap specific PostgreSQL client libraries to provide
+ * a unified interface for query execution, connection management, and
+ * result parsing.
+ *
+ * @abstract
+ */
+declare abstract class $Client {
+  /**
+   * Executes a SQL query with optional parameterized arguments.
+   *
+   * @param query - The SQL query string to execute.
+   * @param args - Optional array of parameter values for parameterized queries.
+   * @returns A promise that resolves with the query result.
+   */
+  query: (query: string, args?: (string | number | null)[]) => Promise<unknown>;
+  /**
+   * Establishes a connection to the database.
+   *
+   * @returns A promise that resolves when the connection is established.
+   */
+  abstract connect(): Promise<void>;
+  /**
+   * Extracts the rows array from a query response.
+   *
+   * Different client libraries return results in different formats.
+   * This method normalizes the response to a standard array of rows.
+   *
+   * @param response - The raw query response from the underlying client.
+   * @returns An array of row objects.
+   */
+  abstract getRows(response: any): any[];
+  /**
+   * Closes the database connection and releases resources.
+   *
+   * @returns A promise that resolves when the connection is closed.
+   */
+  abstract close(): Promise<void>;
+}
+/**
+ * Abstract base class for database connection pools.
+ *
+ * Connection pools manage multiple reusable connections to improve
+ * performance for applications with concurrent database access.
+ * Implementations wrap specific PostgreSQL client libraries.
+ *
+ * @abstract
+ */
+declare abstract class $Pool {
+  /**
+   * Executes a SQL query with optional parameterized arguments.
+   *
+   * The pool automatically acquires a connection, executes the query,
+   * and returns the connection to the pool.
+   *
+   * @param query - The SQL query string to execute.
+   * @param args - Optional array of parameter values for parameterized queries.
+   * @returns A promise that resolves with the query result.
+   */
+  query: (query: string, args?: (string | number | null)[]) => Promise<unknown>;
+  /**
+   * Initializes the connection pool.
+   *
+   * Some pool implementations establish connections lazily, so this
+   * method may be a no-op in certain cases.
+   *
+   * @returns A promise that resolves when the pool is ready.
+   */
+  abstract connect(): Promise<void>;
+  /**
+   * Extracts the rows array from a query response.
+   *
+   * Different client libraries return results in different formats.
+   * This method normalizes the response to a standard array of rows.
+   *
+   * @param response - The raw query response from the underlying client.
+   * @returns An array of row objects.
+   */
+  abstract getRows(response: any): any[];
+  /**
+   * Closes all connections in the pool and releases resources.
+   *
+   * @returns A promise that resolves when all connections are closed.
+   */
+  abstract close(): Promise<void>;
+  /**
+   * Acquires a client connection from the pool.
+   *
+   * The returned client has exclusive use of a connection from the pool
+   * until it is released by calling `close()`. This is useful for
+   * transactions or operations that require connection affinity.
+   *
+   * **Important:** Always call `close()` on the returned client when done
+   * to return the connection to the pool.
+   *
+   * @returns A promise that resolves with a client instance.
+   */
+  abstract acquireClient(): Promise<$Client>;
+}
+/**
+ * Union type representing any query executor (client or pool).
+ *
+ * This type is used in contexts where either a single client or a
+ * connection pool can be used interchangeably for query execution.
+ */
+type QueryExecutor = $Client | $Pool;
+//#endregion
+export { $Pool, Connector, QueryExecutor };

package/dist/src/connectors/common.mjs

@@ -0,0 +1,65 @@
+import { getUrlFromDbCredentials } from "../cli/helpers.mjs";
+//#region src/connectors/common.ts
+/**
+* Abstract base class for all database connectors.
+*
+* Connectors provide a unified interface for creating database clients
+* and connection pools across different PostgreSQL client libraries.
+* Each connector implementation wraps a specific library (pg, postgres.js,
+* PGlite, Bun SQL) while exposing a consistent API.
+*
+* @abstract
+*/
+var Connector = class {
+	/** The configuration object containing file paths, database credentials, client configs etc. */
+	config;
+	/** The PostgreSQL connection URL derived from the configuration. */
+	url;
+	constructor(config) {
+		this.config = config;
+		this.url = getUrlFromDbCredentials(config.dbCredentials);
+	}
+};
+/**
+* Abstract base class for single-connection database clients.
+*
+* Implementations wrap specific PostgreSQL client libraries to provide
+* a unified interface for query execution, connection management, and
+* result parsing.
+*
+* @abstract
+*/
+var $Client = class {
+	/**
+	* Executes a SQL query with optional parameterized arguments.
+	*
+	* @param query - The SQL query string to execute.
+	* @param args - Optional array of parameter values for parameterized queries.
+	* @returns A promise that resolves with the query result.
+	*/
+	query;
+};
+/**
+* Abstract base class for database connection pools.
+*
+* Connection pools manage multiple reusable connections to improve
+* performance for applications with concurrent database access.
+* Implementations wrap specific PostgreSQL client libraries.
+*
+* @abstract
+*/
+var $Pool = class {
+	/**
+	* Executes a SQL query with optional parameterized arguments.
+	*
+	* The pool automatically acquires a connection, executes the query,
+	* and returns the connection to the pool.
+	*
+	* @param query - The SQL query string to execute.
+	* @param args - Optional array of parameter values for parameterized queries.
+	* @returns A promise that resolves with the query result.
+	*/
+	query;
+};
+//#endregion
+export { $Client, $Pool, Connector };

package/dist/src/connectors/pg.d.mts

@@ -0,0 +1,18 @@
+import { Connector } from "./common.mjs";
+
+//#region src/connectors/pg.d.ts
+/**
+ * Connector implementation for the `pg` (node-postgres) library.
+ *
+ * Non-blocking PostgreSQL client for Node.js. Pure JavaScript and
+ * optional native libpq bindings.
+ *
+ * @see https://node-postgres.com/
+ * @see https://www.npmjs.com/package/pg
+ */
+declare class PgConnector extends Connector {
+  getClient(): PgClient;
+  getPool(): PgPool;
+}
+//#endregion
+export { PgConnector };

package/dist/src/connectors/pg.mjs

@@ -0,0 +1,103 @@
+import { $Client, $Pool, Connector } from "./common.mjs";
+import { Client, Pool } from "pg";
+//#region src/connectors/pg.ts
+/**
+* Connector implementation for the `pg` (node-postgres) library.
+*
+* Non-blocking PostgreSQL client for Node.js. Pure JavaScript and
+* optional native libpq bindings.
+*
+* @see https://node-postgres.com/
+* @see https://www.npmjs.com/package/pg
+*/
+var PgConnector = class extends Connector {
+	getClient() {
+		return new PgClient(this.url);
+	}
+	getPool() {
+		return new PgPool(this.url, this.config.pool);
+	}
+};
+/**
+* Single-connection client wrapper for the `pg` library.
+*
+* Uses a single dedicated connection to the PostgreSQL database.
+* Best suited for CLI tools, scripts, or scenarios where connection
+* pooling is not required.
+*
+* @internal
+*/
+var PgClient = class extends $Client {
+	#client;
+	constructor(connectionString) {
+		super();
+		this.#client = new Client({ connectionString });
+		this.query = this.#client.query.bind(this.#client);
+	}
+	async connect() {
+		await this.#client.connect();
+	}
+	getRows(response) {
+		return response.rows;
+	}
+	async close() {
+		await this.#client.end();
+	}
+};
+/**
+* Connection pool wrapper for the `pg` library.
+*
+* Manages a pool of reusable connections to the PostgreSQL database.
+* Recommended for web applications and services that handle multiple
+* concurrent database requests.
+*
+* @internal
+*/
+var PgPool = class extends $Pool {
+	#pool;
+	constructor(connectionString, pool) {
+		super();
+		this.#pool = new Pool({
+			connectionString,
+			max: pool?.max ?? 10
+		});
+		this.query = this.#pool.query.bind(this.#pool);
+	}
+	async connect() {
+		await this.#pool.connect();
+	}
+	getRows(response) {
+		return response.rows;
+	}
+	async close() {
+		await this.#pool.end();
+	}
+	async acquireClient() {
+		return new PgPoolClient(await this.#pool.connect());
+	}
+};
+/**
+* Client wrapper for a connection acquired from a pg Pool.
+*
+* This client wraps a PoolClient and releases it back to the pool
+* when closed.
+*
+* @internal
+*/
+var PgPoolClient = class extends $Client {
+	#client;
+	constructor(client) {
+		super();
+		this.#client = client;
+		this.query = this.#client.query.bind(this.#client);
+	}
+	async connect() {}
+	getRows(response) {
+		return response.rows;
+	}
+	async close() {
+		this.#client.release();
+	}
+};
+//#endregion
+export { PgConnector };

package/dist/src/connectors/pglite.d.mts

@@ -0,0 +1,19 @@
+import { Connector } from "./common.mjs";
+
+//#region src/connectors/pglite.d.ts
+/**
+ * Connector implementation for the `@electric-sql/pglite` library.
+ *
+ * PGlite is a lightweight, embeddable PostgreSQL implementation that runs
+ * entirely in-process using WASM. Perfect for local development, testing,
+ * and edge computing scenarios.
+ *
+ * @see https://pglite.dev/
+ * @see https://www.npmjs.com/package/@electric-sql/pglite
+ */
+declare class PgLiteConnector extends Connector {
+  getClient(): PgLiteClient;
+  getPool(): PgLitePool;
+}
+//#endregion
+export { PgLiteConnector };