durcno 1.0.0-alpha.0 → 1.0.0-alpha.2

package/README.md

@@ -1,8 +1,11 @@
 <p align="center">
-  <img src="https://img.shields.io/npm/v/durcno?style=flat&color=blue" alt="npm version" />
+  <a href="https://npmjs.com/package/durcno" target="_blank">
+    <img src="https://img.shields.io/npm/v/durcno?style=flat&logo=npm&color=339933" alt="npm version" />
+  </a>
+  <img src="https://img.shields.io/badge/Node.js-24%2B-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 24+" />
   <img src="https://img.shields.io/badge/PostgreSQL-14%2B-336791?style=flat&logo=postgresql&logoColor=white" alt="PostgreSQL 14+" />
-  <img src="https://img.shields.io/badge/Node.js-25%2B-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js" />
   <img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat" alt="License" />
+  <img src="https://img.shields.io/badge/vitest--green?logo=vitest" alt="License" />
 </p>
 
 <h1 align="center">Durcno</h1>
@@ -17,7 +20,7 @@
 
 ---
 
-## ✨ Features
+## Features
 
 - **🔗 Relation Mapping** — Intuitive `many`, `one`, and `fk` relations with full type inference.
 - **🦾 Robust Migrations** — Auto-generated, reversible, and squashable migrations for production applications.
@@ -25,17 +28,17 @@
 - **🔌 Multiple Drivers** — Support for `pg`, `postgres`, `bun`, and `pglite` drivers.
 - **🌍 PostGIS Support** — First-class geographic column types for spatial queries.
 
-## 📦 Setup
+## Setup
 
 ```bash
 npm install durcno
 ```
 
 ```bash
-npx durcno init
+npm exec durcno init
 ```
 
-## 🚀 Getting Started
+## Getting Started
 
 Get started with Durcno by following our comprehensive documentation.
 
@@ -45,11 +48,11 @@ Get started with Durcno by following our comprehensive documentation.
 > Durcno is currently in the alpha stage.
 > Avoid using it in any critical or large project until it reaches beta. Expect bugs and breaking changes. However, your feedback is invaluable to help us shape the future of Durcno!
 
-## 🤝 Contributing
+## Contributing
 
 Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting PRs.
 
-## 📄 License
+## License
 
 Apache License 2.0 - see [LICENSE](LICENSE) for details.
 

package/dist/bin.cjs

@@ -8903,9 +8903,9 @@ function resolveConfigPath(argPath) {
   }
   return (0, import_node_path2.resolve)(process.cwd(), DURCNO_CONFIG_NAME);
 }
-function getSetup(argPath) {
+async function getSetup(argPath) {
   const absPath = resolveConfigPath(argPath);
-  const mod = require(absPath);
+  const mod = await import(absPath);
   const { default: setup } = mod;
   return setup;
 }
@@ -8914,7 +8914,7 @@ function getSetup(argPath) {
 var { bgGreen, dim, cyan: cyan2, yellow: yellow2, red: red2 } = source_default;
 async function down(m, options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector, config: config2 } = getSetup(configPath);
+  const { connector, config: config2 } = await getSetup(configPath);
   config2.pool = { ...config2.pool, max: 1 };
   const migrationsDir = (0, import_node_path3.resolve)(
     (0, import_node_path3.dirname)(configPath),
@@ -8962,13 +8962,20 @@ async function runDownMigration(migrationDirName, isFirstMigration, migrationsDi
     const statements = migrationModule.statements;
     const options = migrationModule.options ?? {};
     const useTransaction = options.transaction ?? true;
+    const execution = options.execution ?? "joined";
     if (useTransaction) {
       await client.query("BEGIN;");
     }
     try {
       if (statements.length > 0) {
-        const sql = `${statements.map((st) => st.toSQL()).join(";\n")};`;
-        await client.query(sql);
+        if (execution === "sequential") {
+          for (const st of statements) {
+            await client.query(st.toSQL());
+          }
+        } else {
+          const sql = `${statements.map((st) => st.toSQL()).join("\n")}`;
+          await client.query(sql);
+        }
       }
       if (useTransaction) {
         await client.query("COMMIT;");
@@ -11688,8 +11695,11 @@ var Arg = class {
   index = 0;
   key = "";
   handler;
-  constructor(handler) {
+  /** PostgreSQL cast type suffix (e.g. `"boolean"`, `"geography"`), or `null` if no cast needed. */
+  cast = null;
+  constructor(handler, cast = null) {
     this.handler = handler;
+    this.cast = cast;
   }
 };
 
@@ -11795,6 +11805,14 @@ var Column = class {
     const suffix = this.config.dimension.map((d) => d === null ? "[]" : `[${d}]`).join("");
     return `${base}${suffix}`;
   }
+  /** Returns the full PostgreSQL cast type including array dimensions, or `null` if no cast is needed. */
+  get sqlCast() {
+    const base = this.sqlCastScalar;
+    if (base === null) return null;
+    if (!this.config.dimension) return base;
+    const suffix = this.config.dimension.map((d) => d === null ? "[]" : `[${d}]`).join("");
+    return `${base}${suffix}`;
+  }
   get zodType() {
     let schema = this.zodTypeScaler;
     if (!this.config.dimension) {
@@ -11845,29 +11863,33 @@ var Column = class {
    * Converts a JavaScript value to SQL string literal.
    * Handles array dimensions with ARRAY[...] syntax if configured.
    */
-  toSQL(value) {
+  toSQL(value, options) {
+    if (value === null) return "NULL";
     if (value instanceof Sql) return value.string;
     if (!this.config.dimension) {
-      return this.toSQLScalar(value);
+      if (!options?.cast || !this.sqlCastScalar) return this.toSQLScalar(value);
+      return `${this.toSQLScalar(value)}::${this.sqlCastScalar}`;
     }
-    return this.#toSQLArray(value, 0);
+    return this.#toSQLArray(value, 0, options);
   }
   /**
    * Helper to recursively process multi-dimensional arrays for toSQL.
    */
-  #toSQLArray(arr, dimIndex) {
+  #toSQLArray(arr, dimIndex, options) {
     const dimensions = this.config.dimension;
     if (arr.length === 0) {
       return "'{}'";
     }
     if (dimIndex >= dimensions.length - 1) {
-      const elements2 = arr.map(
-        (item) => this.toSQLScalar(item)
-      );
+      const elements2 = arr.map((item) => {
+        if (!options?.cast || !this.sqlCastScalar)
+          return this.toSQLScalar(item);
+        return `${this.toSQLScalar(item)}::${this.sqlCastScalar}`;
+      });
       return `ARRAY[${elements2.join(", ")}]`;
     }
     const elements = arr.map(
-      (item) => this.#toSQLArray(item, dimIndex + 1)
+      (item) => this.#toSQLArray(item, dimIndex + 1, options)
     );
     return `ARRAY[${elements.join(", ")}]`;
   }
@@ -12037,7 +12059,7 @@ var Column = class {
    * @returns an `Arg` instance with the type of this column
    */
   arg() {
-    return new Arg(this.toDriver.bind(this));
+    return new Arg(this.toDriver.bind(this), this.sqlCast);
   }
 };
 
@@ -12212,7 +12234,7 @@ async function promptColumnRenames(prev, curr, renamedTables) {
 }
 async function generate(options) {
   const configPath = resolveConfigPath(options.config);
-  const { config: config2 } = getSetup(configPath);
+  const { config: config2 } = await getSetup(configPath);
   const migrationsDir = (0, import_node_path4.resolve)(
     (0, import_node_path4.dirname)(configPath),
     config2.out || DEFAULT_MIGRATIONS_DIR
@@ -12224,7 +12246,7 @@ async function generate(options) {
   const ssPrevious = (0, import_migration2.createEmptySnapshot)();
   for (const migrationFolder of migrationFolderNames.sort()) {
     const upTsPath = (0, import_node_path4.resolve)(migrationsDir, migrationFolder, "up.ts");
-    const upModule = require(upTsPath);
+    const upModule = await import(upTsPath);
     const statements = upModule.statements;
     for (const statement of statements) {
       statement.applyToSnapshot(ssPrevious);
@@ -12234,7 +12256,7 @@ async function generate(options) {
     configPath ? (0, import_node_path4.dirname)(configPath) : process.cwd(),
     config2.schema
   );
-  const exports2 = require(schemaFile);
+  const exports2 = await import(schemaFile);
   ensureNoEntityCollisions(exports2);
   const entities = Object.values(exports2);
   const ssCurrent = (0, import_migration2.snapshot)(entities);
@@ -12577,6 +12599,22 @@ function generateAlterTableStmts(prevTable, currTable, tableName, curr, statemen
           alterStatements.push(`.dropDefault("${colName}")`);
         }
       }
+      const prevRefJson = JSON.stringify(prevCol.references ?? null);
+      const currRefJson = JSON.stringify(currCol.references ?? null);
+      if (prevRefJson !== currRefJson) {
+        if (prevCol.references) {
+          const constraintName = `${currTable.name}_${colName}_fkey`;
+          alterStatements.push(
+            `.dropForeignKey("${constraintName}", "${colName}")`
+          );
+        }
+        if (currCol.references) {
+          const constraintName = `${currTable.name}_${colName}_fkey`;
+          alterStatements.push(
+            `.addForeignKey("${constraintName}", "${colName}", ${JSON.stringify(currCol.references)})`
+          );
+        }
+      }
     }
   }
   for (const idxName in currTable.indexes) {
@@ -12733,11 +12771,11 @@ var CONNECTOR_PACKAGES = {
   bun: []
   // Built-in
 };
-var CONNECTOR_CLASS_NAMES = {
-  pg: "PgConnector",
-  postgres: "PostgresConnector",
-  bun: "BunConnector",
-  pglite: "PgLiteConnector"
+var CONNECTOR_FUNCTION_NAMES = {
+  pg: "pg",
+  postgres: "postgres",
+  bun: "bun",
+  pglite: "pglite"
 };
 var LOADER_PACKAGES = {
   node: ["dotenv"],
@@ -12757,15 +12795,15 @@ var pm = (() => {
 })();
 function generateConfigFile(config2) {
   const { connector, connectionUrl, schemaPath, migrationsDir } = config2;
-  const className = CONNECTOR_CLASS_NAMES[connector];
+  const funcName = CONNECTOR_FUNCTION_NAMES[connector];
   const urlValue = connectionUrl === "" ? "process.env.DATABASE_URL!" : `"${connectionUrl}"`;
   const envLoader = connectionUrl === "" ? runtime === "bun" ? "" : runtime === "deno" ? `import "@std/dotenv/load";
 ` : `import "dotenv/config";
 ` : "";
   return `${envLoader}import { defineConfig } from "durcno";
-import { ${className} } from "durcno/connectors/${connector}";
+import { ${funcName} } from "durcno/connectors/${connector}";
 
-export default defineConfig(${className}, {
+export default defineConfig(${funcName}(), {
   schema: "${schemaPath}",
   out: "${migrationsDir}",
   dbCredentials: {
@@ -12789,43 +12827,14 @@ export const Users = table("public", "users", {
 `;
 }
 function generateIndexFile(schemaPath) {
-  const schemaImport = schemaPath.replace(/\.ts$/, "").replace(/^db\//, "./");
+  const schemaImport = schemaPath.replace(/^db\//, "./");
   return `import { database } from "durcno";
 import * as schema from "${schemaImport}";
-import setup from "../durcno.config";
+import setup from "../durcno.config.ts";
 
 export const db = database(schema, setup);
 `;
 }
-function setTypeModule() {
-  const pkgPath = (0, import_node_path5.resolve)(process.cwd(), "package.json");
-  if (!(0, import_node_fs3.existsSync)(pkgPath)) {
-    (0, import_node_fs3.writeFileSync)(pkgPath, `${JSON.stringify({ type: "module" }, null, 2)}
-`);
-    console.log(
-      bold(
-        `${green("\u2714")} Created ${cyan4("package.json")} with "type": "module"`
-      )
-    );
-    return;
-  }
-  try {
-    const pkgContent = (0, import_node_fs3.readFileSync)(pkgPath, "utf-8");
-    const pkg = JSON.parse(pkgContent);
-    if (pkg.type !== "module") {
-      pkg.type = "module";
-      (0, import_node_fs3.writeFileSync)(pkgPath, `${JSON.stringify(pkg, null, 2)}
-`);
-      console.log(
-        bold(
-          `${green("\u2714")} Updated ${cyan4("package.json")} with "type": "module"`
-        )
-      );
-    }
-  } catch (err) {
-    console.log(yellow4(`Warning: Failed to update package.json: ${err}`));
-  }
-}
 async function promptConfig() {
   const response = await (0, import_prompts2.default)(
     [
@@ -12918,7 +12927,6 @@ async function init(options) {
     config2 = DEFAULTS;
   }
   await writeFiles(config2, options);
-  setTypeModule();
   console.log(green.bold("\n\u{1F4E6} Setup dependencies\n"));
   const toInstall = [];
   const toInstallDrivers = [];
@@ -12972,7 +12980,7 @@ Installation failed with exit code ${exitCode}`)
   }
   console.log(green.bold("\n\u2728 Durcno Setuped!\n"));
   console.log(dim2("Next steps:"));
-  const execCmd = pm === "npm" ? "npx" : pm === "pnpm" ? "pnpm exec" : pm === "bun" ? "bun x" : pm;
+  const execCmd = pm === "npm" ? "npm exec" : pm === "pnpm" ? "pnpm exec" : pm === "bun" ? "bunx" : pm;
   const nextSteps = [
     ["Edit your schema in", magenta.bold(config2.schemaPath)],
     ["Run", cyan4.bold(`${execCmd} durcno generate`), "to create migrations"],
@@ -12993,7 +13001,7 @@ var import_durcno3 = require("durcno");
 var { bgGreen: bgGreen3, bgYellow, dim: dim3, gray: gray4, yellow: yellow5, green: green2, cyan: cyan5 } = source_default;
 async function migrate(options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector, config: config2 } = getSetup(configPath);
+  const { connector, config: config2 } = await getSetup(configPath);
   config2.pool = { ...config2.pool, max: 1 };
   const migrationsDir = (0, import_node_path6.resolve)(
     (0, import_node_path6.dirname)(configPath),
@@ -13052,13 +13060,20 @@ async function runUpMigration(migrationDirName, migrationsDir, client, setup) {
   const statements = migrationModule.statements;
   const options = migrationModule.options ?? {};
   const useTransaction = options.transaction ?? true;
+  const execution = options.execution ?? "joined";
   if (useTransaction) {
     await client.query("BEGIN;");
   }
   try {
     if (statements.length > 0) {
-      const sql = `${statements.map((st) => st.toSQL()).join(";\n")};`;
-      await client.query(sql);
+      if (execution === "sequential") {
+        for (const st of statements) {
+          await client.query(st.toSQL());
+        }
+      } else {
+        const sql = `${statements.map((st) => st.toSQL()).join("\n")}`;
+        await client.query(sql);
+      }
     }
     if (useTransaction) {
       await client.query("COMMIT;");
@@ -13091,7 +13106,7 @@ var import_node_readline = require("node:readline");
 var { cyan: cyan6, green: green3, red: red4, yellow: yellow6, gray: gray5, bgCyan, bold: bold2 } = source_default;
 async function shell(options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector } = getSetup(configPath);
+  const { connector } = await getSetup(configPath);
   const client = connector.getClient();
   console.log(gray5("Connecting to database..."));
   await client.connect();
@@ -13337,7 +13352,7 @@ var import_migration3 = require("durcno/migration");
 var { bgGreen: bgGreen4, bgRed: bgRed2, yellow: yellow7, red: red5, green: green4, cyan: cyan7, gray: gray6 } = source_default;
 async function squash(start, end, options) {
   const configPath = resolveConfigPath(options.config);
-  const { config: config2 } = getSetup(configPath);
+  const { config: config2 } = await getSetup(configPath);
   const migrationsDir = (0, import_node_path7.resolve)(
     (0, import_node_path7.dirname)(configPath),
     config2.out || DEFAULT_MIGRATIONS_DIR
@@ -13375,7 +13390,7 @@ async function squash(start, end, options) {
   let hasCustomStatements = false;
   for (const migrationDirName of range) {
     const upPath = (0, import_node_path7.join)(migrationsDir, migrationDirName, "up.ts");
-    const upModule = require(upPath);
+    const upModule = await import(upPath);
     const statements = upModule.statements;
     if (statements.some((st) => st.isCustom)) {
       hasCustomStatements = true;
@@ -13393,7 +13408,7 @@ async function squash(start, end, options) {
   const beforeSnapshot = (0, import_migration3.createEmptySnapshot)();
   for (const migrationDirName of before) {
     const upPath = (0, import_node_path7.join)(migrationsDir, migrationDirName, "up.ts");
-    const upModule = require(upPath);
+    const upModule = await import(upPath);
     const statements = upModule.statements;
     for (const statement of statements) {
       statement.applyToSnapshot(beforeSnapshot);
@@ -13402,7 +13417,7 @@ async function squash(start, end, options) {
   const afterRangeSnapshot = (0, import_migration3.createEmptySnapshot)();
   for (const migrationDirName of [...before, ...range]) {
     const upPath = (0, import_node_path7.join)(migrationsDir, migrationDirName, "up.ts");
-    const upModule = require(upPath);
+    const upModule = await import(upPath);
     const statements = upModule.statements;
     for (const statement of statements) {
       statement.applyToSnapshot(afterRangeSnapshot);
@@ -13444,7 +13459,7 @@ var import_durcno4 = require("durcno");
 var { dim: dim4, cyan: cyan8, yellow: yellow8, green: green5 } = source_default;
 async function status(options) {
   const configPath = resolveConfigPath(options.config);
-  const { connector, config: config2 } = getSetup(configPath);
+  const { connector, config: config2 } = await getSetup(configPath);
   config2.pool = { ...config2.pool, max: 1 };
   const migrationsDir = (0, import_node_path8.resolve)(
     (0, import_node_path8.dirname)(configPath),
@@ -13489,7 +13504,7 @@ async function status(options) {
 }
 
 // src/cli/index.ts
-program.version("1.0.0-alpha.0");
+program.version("1.0.0-alpha.1");
 var Options = {
   config: ["--config <path>", "Path to the config file"]
 };

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

@@ -8,6 +8,7 @@ type BigintConfig = ColumnConfig;
 declare class BigintColumn<TConfig extends BigintConfig> extends Column<TConfig, BigintValType> {
   static readonly id = "Column.Bigint";
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): null;
   get zodTypeScaler(): z.ZodCoercedNumber<unknown>;
   toDriverScalar(value: BigintValType | Sql | null): string | number | null;
   toSQLScalar(value: number | Sql | null): string;

package/dist/src/columns/bigint.mjs

@@ -7,6 +7,9 @@ var BigintColumn = class extends Column {
 	get sqlTypeScalar() {
 		return "bigint";
 	}
+	get sqlCastScalar() {
+		return null;
+	}
 	get zodTypeScaler() {
 		return z.coerce.number();
 	}

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

@@ -13,6 +13,7 @@ declare class BigserialColumn<TConfig extends BigserialConfig> extends Column<Bi
   static readonly id = "Column.Bigserial";
   constructor(config: TConfig);
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): null;
   get zodTypeScaler(): z.ZodCoercedNumber<unknown>;
   toDriverScalar(value: BigserialValType | Sql | null): string | number | null;
   toSQLScalar(value: number | Sql | null): string;

package/dist/src/columns/bigserial.mjs

@@ -10,6 +10,9 @@ var BigserialColumn = class extends Column {
 	get sqlTypeScalar() {
 		return "bigserial";
 	}
+	get sqlCastScalar() {
+		return null;
+	}
 	get zodTypeScaler() {
 		return z.coerce.number();
 	}

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

@@ -8,6 +8,7 @@ type BooleanConfig = ColumnConfig;
 declare class BooleanColumn<TConfig extends BooleanConfig> extends Column<TConfig, BooleanValType> {
   static readonly id = "Column.Boolean";
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): string;
   get zodTypeScaler(): z.ZodBoolean;
   toDriverScalar(value: BooleanValType | Sql | null): string | null;
   toSQLScalar(value: boolean | Sql | null): string;

package/dist/src/columns/boolean.mjs

@@ -7,6 +7,9 @@ var BooleanColumn = class extends Column {
 	get sqlTypeScalar() {
 		return "boolean";
 	}
+	get sqlCastScalar() {
+		return "boolean";
+	}
 	get zodTypeScaler() {
 		return z.boolean();
 	}

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

@@ -8,6 +8,7 @@ type ByteaConfig = ColumnConfig;
 declare class ByteaColumn<TConfig extends ByteaConfig> extends Column<TConfig, ByteaValType> {
   static readonly id = "Column.Bytea";
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): string;
   get zodTypeScaler(): z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>;
   toDriverScalar(value: ByteaValType | Sql | null): string | null;
   toSQLScalar(value: ByteaValType | Sql | null): string;

package/dist/src/columns/bytea.mjs

@@ -7,6 +7,9 @@ var ByteaColumn = class extends Column {
 	get sqlTypeScalar() {
 		return "bytea";
 	}
+	get sqlCastScalar() {
+		return "bytea";
+	}
 	get zodTypeScaler() {
 		return z.instanceof(Buffer);
 	}

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

@@ -12,6 +12,7 @@ declare class CharColumn<TConfig extends CharConfig> extends Column<TConfig, Cha
   static readonly id = "Column.Char";
   constructor(config: TConfig);
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): null;
   get zodTypeScaler(): z.ZodString;
   toDriverScalar(value: CharValType | Sql | null): string | null;
   toSQLScalar(value: string | Sql | null): string;

package/dist/src/columns/char.mjs

@@ -12,6 +12,9 @@ var CharColumn = class extends Column {
 	get sqlTypeScalar() {
 		return `char(${this.#length})`;
 	}
+	get sqlCastScalar() {
+		return null;
+	}
 	get zodTypeScaler() {
 		return z.string().length(this.#length);
 	}

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

@@ -8,6 +8,7 @@ type CidrConfig = ColumnConfig;
 declare class CidrColumn<TConfig extends CidrConfig> extends Column<TConfig, CidrValType> {
   static readonly id = "Column.Cidr";
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): string;
   get zodTypeScaler(): z.ZodUnion<readonly [z.ZodCIDRv4, z.ZodCIDRv6]>;
   toDriverScalar(value: CidrValType | Sql | null): string | null;
   toSQLScalar(value: string | Sql | null): string;

package/dist/src/columns/cidr.mjs

@@ -7,6 +7,9 @@ var CidrColumn = class extends Column {
 	get sqlTypeScalar() {
 		return "cidr";
 	}
+	get sqlCastScalar() {
+		return "cidr";
+	}
 	get zodTypeScaler() {
 		return z.union([z.cidrv4(), z.cidrv6()]);
 	}

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

@@ -158,6 +158,10 @@ declare abstract class Column<TConfig extends ColumnConfig, TColVal> {
   } ? true : false;
   abstract get sqlTypeScalar(): string;
   get sqlType(): string;
+  /** Returns the PostgreSQL cast type for this column's scalar value, or `null` if no cast is needed. */
+  abstract get sqlCastScalar(): string | null;
+  /** Returns the full PostgreSQL cast type including array dimensions, or `null` if no cast is needed. */
+  get sqlCast(): string | null;
   abstract get zodTypeScaler(): z.ZodType;
   get zodType(): GetZodTypeArray<this["zodTypeScaler"], this["config"]>;
   /**
@@ -177,7 +181,9 @@ declare abstract class Column<TConfig extends ColumnConfig, TColVal> {
    * Converts a JavaScript value to SQL string literal.
    * Handles array dimensions with ARRAY[...] syntax if configured.
    */
-  toSQL(value: this["ValType"] | Sql | null): string;
+  toSQL(value: this["ValType"] | Sql | null, options?: {
+    cast?: boolean;
+  }): string;
   /**
    * Converts a PostgreSQL result back to JavaScript value.
    * Handles array dimensions if configured, otherwise delegates to scalar implementation.

package/dist/src/columns/common.mjs

@@ -77,6 +77,13 @@ var Column = class {
 		if (!this.config.dimension) return base;
 		return `${base}${this.config.dimension.map((d) => d === null ? "[]" : `[${d}]`).join("")}`;
 	}
+	/** Returns the full PostgreSQL cast type including array dimensions, or `null` if no cast is needed. */
+	get sqlCast() {
+		const base = this.sqlCastScalar;
+		if (base === null) return null;
+		if (!this.config.dimension) return base;
+		return `${base}${this.config.dimension.map((d) => d === null ? "[]" : `[${d}]`).join("")}`;
+	}
 	get zodType() {
 		let schema = this.zodTypeScaler;
 		if (!this.config.dimension) return schema;
@@ -112,19 +119,26 @@ var Column = class {
 	* Converts a JavaScript value to SQL string literal.
 	* Handles array dimensions with ARRAY[...] syntax if configured.
 	*/
-	toSQL(value) {
+	toSQL(value, options) {
+		if (value === null) return "NULL";
 		if (value instanceof Sql) return value.string;
-		if (!this.config.dimension) return this.toSQLScalar(value);
-		return this.#toSQLArray(value, 0);
+		if (!this.config.dimension) {
+			if (!options?.cast || !this.sqlCastScalar) return this.toSQLScalar(value);
+			return `${this.toSQLScalar(value)}::${this.sqlCastScalar}`;
+		}
+		return this.#toSQLArray(value, 0, options);
 	}
 	/**
 	* Helper to recursively process multi-dimensional arrays for toSQL.
 	*/
-	#toSQLArray(arr, dimIndex) {
+	#toSQLArray(arr, dimIndex, options) {
 		const dimensions = this.config.dimension;
 		if (arr.length === 0) return "'{}'";
-		if (dimIndex >= dimensions.length - 1) return `ARRAY[${arr.map((item) => this.toSQLScalar(item)).join(", ")}]`;
-		return `ARRAY[${arr.map((item) => this.#toSQLArray(item, dimIndex + 1)).join(", ")}]`;
+		if (dimIndex >= dimensions.length - 1) return `ARRAY[${arr.map((item) => {
+			if (!options?.cast || !this.sqlCastScalar) return this.toSQLScalar(item);
+			return `${this.toSQLScalar(item)}::${this.sqlCastScalar}`;
+		}).join(", ")}]`;
+		return `ARRAY[${arr.map((item) => this.#toSQLArray(item, dimIndex + 1, options)).join(", ")}]`;
 	}
 	/**
 	* Converts a PostgreSQL result back to JavaScript value.
@@ -269,7 +283,7 @@ var Column = class {
 	* @returns an `Arg` instance with the type of this column
 	*/
 	arg() {
-		return new Arg(this.toDriver.bind(this));
+		return new Arg(this.toDriver.bind(this), this.sqlCast);
 	}
 };
 //#endregion

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

@@ -8,6 +8,7 @@ type DateConfig = ColumnConfig;
 declare class DateColumn<TConfig extends DateConfig> extends Column<TConfig, DateValType> {
   static readonly id = "Column.Date";
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): string;
   get zodTypeScaler(): z.ZodDate;
   toDriverScalar(value: DateValType | Sql | null): string | null;
   toSQLScalar(value: Date | Sql | null): string;

package/dist/src/columns/date.mjs

@@ -7,6 +7,9 @@ var DateColumn = class extends Column {
 	get sqlTypeScalar() {
 		return "date";
 	}
+	get sqlCastScalar() {
+		return "date";
+	}
 	get zodTypeScaler() {
 		return z.date();
 	}

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

@@ -10,6 +10,7 @@ declare class EnumedColumn<TValue extends string, TConfig extends EnumedConfig>
   static readonly id = "Column.Enumed";
   constructor(enm: Enum<TValue>, config: TConfig);
   get sqlTypeScalar(): string;
+  get sqlCastScalar(): string;
   get zodTypeScaler(): z.ZodEnum<{ [k_1 in TValue]: k_1 } extends infer T ? { [k in keyof T]: T[k] } : never>;
   toDriverScalar(value: TValue | Sql | null): string | null;
   toSQLScalar(value: TValue | Sql | null): string;

package/dist/src/columns/enum.mjs

@@ -12,6 +12,9 @@ var EnumedColumn = class extends Column {
 	get sqlTypeScalar() {
 		return `"${this.#enum.schema}"."${this.#enum.name}"`;
 	}
+	get sqlCastScalar() {
+		return this.sqlTypeScalar;
+	}
 	get zodTypeScaler() {
 		return z.enum(this.#enum.values);
 	}