@warlock.js/cascade 4.0.174 → 4.1.2

package/README.md

@@ -1,10 +1,10 @@
 # cascade
 
-A powerful and easy to use MongoDB driver for `Nodejs`
+A powerful, model-first TypeScript ORM for **MongoDB and PostgreSQL** on `Node.js`.
 
 ## Features
 
-cascade is a MongoDB driver for Nodejs, it's built on top of the official MongoDB driver, and it provides a simple and easy to use API for working with MongoDB, it is fast, efficient, reliable and will make your life easier with real world apps.
+Cascade is a unified ORM for MongoDB and PostgreSQL — one model-first API runs against both engines. Define a model once (its `@warlock.js/seal` schema doubles as the TypeScript type, the runtime validator, and the DB shape) and query straight off the class. It's fast, type-safe, and built for real-world apps.
 
 Some but not all of the features:
 
@@ -52,14 +52,15 @@ pnpm add @warlock.js/cascade
 Here is a simple example of defining a User model:
 
 ```ts title="src/models/user.ts"
-import { Model } from "@warlock.js/cascade";
+import { Model, RegisterModel } from "@warlock.js/cascade";
 
+@RegisterModel()
 export class User extends Model {
   /**
-   * The collection name
+   * The table / collection name.
    * Must be defined explicitly.
    */
-  public static collection = "users";
+  public static table = "users";
 }
 ```
 

package/bin/cascadejs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../cjs/cli.js";

package/esm/cli/commands/migrate-export-sql.mjs

@@ -0,0 +1,48 @@
+import { exportMigrationsSQL } from "../../operations/migrations.mjs";
+import { loadMigrations } from "../load-migrations.mjs";
+import { withCliConnection } from "../with-cli-connection.mjs";
+import { defineCommand } from "citty";
+
+//#region ../../@warlock.js/cascade/src/cli/commands/migrate-export-sql.ts
+/**
+* `cascade migrate:export-sql` — write phase-ordered `.up.sql` /
+* `.down.sql` files for the registered migrations under
+* `<cwd>/database/sql/`. No DB writes occur.
+*/
+const migrateExportSqlCommand = defineCommand({
+	meta: {
+		name: "migrate:export-sql",
+		description: "Write phase-ordered SQL files for the registered migrations."
+	},
+	args: {
+		"pending-only": {
+			type: "boolean",
+			description: "Export only pending migrations.",
+			default: false
+		},
+		compact: {
+			type: "boolean",
+			alias: "c",
+			description: "Strip generated comments and blank lines.",
+			default: false
+		},
+		path: {
+			type: "string",
+			alias: "p",
+			description: "Glob pattern overriding the default ./migrations/**/*.{ts,js,mjs,cjs}."
+		}
+	},
+	async run({ args }) {
+		await withCliConnection(async () => {
+			await loadMigrations(args.path);
+			await exportMigrationsSQL({
+				pendingOnly: Boolean(args["pending-only"]),
+				compact: Boolean(args.compact)
+			});
+		});
+	}
+});
+
+//#endregion
+export { migrateExportSqlCommand };
+//# sourceMappingURL=migrate-export-sql.mjs.map

package/esm/cli/commands/migrate-export-sql.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-export-sql.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/cli/commands/migrate-export-sql.ts"],"sourcesContent":["import { defineCommand } from \"citty\";\nimport { exportMigrationsSQL } from \"../../operations/migrations\";\nimport { loadMigrations } from \"../load-migrations\";\nimport { withCliConnection } from \"../with-cli-connection\";\n\n/**\n * `cascade migrate:export-sql` — write phase-ordered `.up.sql` /\n * `.down.sql` files for the registered migrations under\n * `<cwd>/database/sql/`. No DB writes occur.\n */\nexport const migrateExportSqlCommand = defineCommand({\n  meta: {\n    name: \"migrate:export-sql\",\n    description: \"Write phase-ordered SQL files for the registered migrations.\",\n  },\n  args: {\n    \"pending-only\": {\n      type: \"boolean\",\n      description: \"Export only pending migrations.\",\n      default: false,\n    },\n    compact: {\n      type: \"boolean\",\n      alias: \"c\",\n      description: \"Strip generated comments and blank lines.\",\n      default: false,\n    },\n    path: {\n      type: \"string\",\n      alias: \"p\",\n      description: \"Glob pattern overriding the default ./migrations/**/*.{ts,js,mjs,cjs}.\",\n    },\n  },\n  async run({ args }) {\n    await withCliConnection(async () => {\n      await loadMigrations(args.path);\n\n      await exportMigrationsSQL({\n        pendingOnly: Boolean(args[\"pending-only\"]),\n        compact: Boolean(args.compact),\n      });\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,0BAA0B,cAAc;CACnD,MAAM;EACJ,MAAM;EACN,aAAa;CACf;CACA,MAAM;EACJ,gBAAgB;GACd,MAAM;GACN,aAAa;GACb,SAAS;EACX;EACA,SAAS;GACP,MAAM;GACN,OAAO;GACP,aAAa;GACb,SAAS;EACX;EACA,MAAM;GACJ,MAAM;GACN,OAAO;GACP,aAAa;EACf;CACF;CACA,MAAM,IAAI,EAAE,QAAQ;EAClB,MAAM,kBAAkB,YAAY;GAClC,MAAM,eAAe,KAAK,IAAI;GAE9B,MAAM,oBAAoB;IACxB,aAAa,QAAQ,KAAK,eAAe;IACzC,SAAS,QAAQ,KAAK,OAAO;GAC/B,CAAC;EACH,CAAC;CACH;AACF,CAAC"}

package/esm/cli/commands/migrate-list.mjs

@@ -0,0 +1,26 @@
+import { listExecutedMigrations } from "../../operations/migrations.mjs";
+import { printExecutedMigrations } from "../printers.mjs";
+import { withCliConnection } from "../with-cli-connection.mjs";
+import { defineCommand } from "citty";
+
+//#region ../../@warlock.js/cascade/src/cli/commands/migrate-list.ts
+/**
+* `cascade migrate:list` — print every migration that has been executed
+* against the configured data source. Reads the migrations table directly;
+* does not load files from disk.
+*/
+const migrateListCommand = defineCommand({
+	meta: {
+		name: "migrate:list",
+		description: "List every migration that has been executed against the data source."
+	},
+	async run() {
+		await withCliConnection(async () => {
+			printExecutedMigrations(await listExecutedMigrations());
+		});
+	}
+});
+
+//#endregion
+export { migrateListCommand };
+//# sourceMappingURL=migrate-list.mjs.map

package/esm/cli/commands/migrate-list.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-list.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/cli/commands/migrate-list.ts"],"sourcesContent":["import { defineCommand } from \"citty\";\nimport { listExecutedMigrations } from \"../../operations/migrations\";\nimport { printExecutedMigrations } from \"../printers\";\nimport { withCliConnection } from \"../with-cli-connection\";\n\n/**\n * `cascade migrate:list` — print every migration that has been executed\n * against the configured data source. Reads the migrations table directly;\n * does not load files from disk.\n */\nexport const migrateListCommand = defineCommand({\n  meta: {\n    name: \"migrate:list\",\n    description: \"List every migration that has been executed against the data source.\",\n  },\n  async run() {\n    await withCliConnection(async () => {\n      const executed = await listExecutedMigrations();\n\n      printExecutedMigrations(executed);\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,qBAAqB,cAAc;CAC9C,MAAM;EACJ,MAAM;EACN,aAAa;CACf;CACA,MAAM,MAAM;EACV,MAAM,kBAAkB,YAAY;GAGlC,wBAAwB,MAFD,uBAAuB,CAEd;EAClC,CAAC;CACH;AACF,CAAC"}

package/esm/cli/commands/migrate-rollback.mjs

@@ -0,0 +1,50 @@
+import { rollbackMigrations } from "../../operations/migrations.mjs";
+import { loadMigrations } from "../load-migrations.mjs";
+import { printRunSummary } from "../printers.mjs";
+import { withCliConnection } from "../with-cli-connection.mjs";
+import { defineCommand } from "citty";
+
+//#region ../../@warlock.js/cascade/src/cli/commands/migrate-rollback.ts
+/**
+* `cascade migrate:rollback` — undo the most recent batch (or every executed
+* migration with `--all`). Migration files are loaded so the runner has the
+* `down()` methods available.
+*/
+const migrateRollbackCommand = defineCommand({
+	meta: {
+		name: "migrate:rollback",
+		description: "Roll back the most recent batch — or everything with --all."
+	},
+	args: {
+		all: {
+			type: "boolean",
+			alias: "a",
+			description: "Roll back every executed migration. Overrides --batches.",
+			default: false
+		},
+		batches: {
+			type: "string",
+			description: "Roll back the last N batches (ignored when --all is set). Default: 1."
+		},
+		path: {
+			type: "string",
+			alias: "p",
+			description: "Glob pattern overriding the default ./migrations/**/*.{ts,js,mjs,cjs}."
+		}
+	},
+	async run({ args }) {
+		await withCliConnection(async () => {
+			await loadMigrations(args.path);
+			const batches = args.batches ? Number(args.batches) : void 0;
+			if (batches !== void 0 && (!Number.isFinite(batches) || batches <= 0)) throw new Error(`Cascade CLI: --batches must be a positive integer, received "${args.batches}".`);
+			printRunSummary(await rollbackMigrations({
+				all: Boolean(args.all),
+				batches
+			}));
+		});
+	}
+});
+
+//#endregion
+export { migrateRollbackCommand };
+//# sourceMappingURL=migrate-rollback.mjs.map

package/esm/cli/commands/migrate-rollback.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-rollback.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/cli/commands/migrate-rollback.ts"],"sourcesContent":["import { defineCommand } from \"citty\";\nimport { rollbackMigrations } from \"../../operations/migrations\";\nimport { loadMigrations } from \"../load-migrations\";\nimport { printRunSummary } from \"../printers\";\nimport { withCliConnection } from \"../with-cli-connection\";\n\n/**\n * `cascade migrate:rollback` — undo the most recent batch (or every executed\n * migration with `--all`). Migration files are loaded so the runner has the\n * `down()` methods available.\n */\nexport const migrateRollbackCommand = defineCommand({\n  meta: {\n    name: \"migrate:rollback\",\n    description: \"Roll back the most recent batch — or everything with --all.\",\n  },\n  args: {\n    all: {\n      type: \"boolean\",\n      alias: \"a\",\n      description: \"Roll back every executed migration. Overrides --batches.\",\n      default: false,\n    },\n    batches: {\n      type: \"string\",\n      description: \"Roll back the last N batches (ignored when --all is set). Default: 1.\",\n    },\n    path: {\n      type: \"string\",\n      alias: \"p\",\n      description: \"Glob pattern overriding the default ./migrations/**/*.{ts,js,mjs,cjs}.\",\n    },\n  },\n  async run({ args }) {\n    await withCliConnection(async () => {\n      await loadMigrations(args.path);\n\n      const batches = args.batches ? Number(args.batches) : undefined;\n\n      if (batches !== undefined && (!Number.isFinite(batches) || batches <= 0)) {\n        throw new Error(\n          `Cascade CLI: --batches must be a positive integer, received \"${args.batches}\".`,\n        );\n      }\n\n      const results = await rollbackMigrations({\n        all: Boolean(args.all),\n        batches,\n      });\n\n      printRunSummary(results);\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,yBAAyB,cAAc;CAClD,MAAM;EACJ,MAAM;EACN,aAAa;CACf;CACA,MAAM;EACJ,KAAK;GACH,MAAM;GACN,OAAO;GACP,aAAa;GACb,SAAS;EACX;EACA,SAAS;GACP,MAAM;GACN,aAAa;EACf;EACA,MAAM;GACJ,MAAM;GACN,OAAO;GACP,aAAa;EACf;CACF;CACA,MAAM,IAAI,EAAE,QAAQ;EAClB,MAAM,kBAAkB,YAAY;GAClC,MAAM,eAAe,KAAK,IAAI;GAE9B,MAAM,UAAU,KAAK,UAAU,OAAO,KAAK,OAAO,IAAI;GAEtD,IAAI,YAAY,WAAc,CAAC,OAAO,SAAS,OAAO,KAAK,WAAW,IACpE,MAAM,IAAI,MACR,gEAAgE,KAAK,QAAQ,GAC/E;GAQF,gBAAgB,MALM,mBAAmB;IACvC,KAAK,QAAQ,KAAK,GAAG;IACrB;GACF,CAAC,CAEsB;EACzB,CAAC;CACH;AACF,CAAC"}

package/esm/cli/commands/migrate.mjs

@@ -0,0 +1,65 @@
+import { exportMigrationsSQL, freshMigrate, runMigrations } from "../../operations/migrations.mjs";
+import { loadMigrations } from "../load-migrations.mjs";
+import { printRunSummary } from "../printers.mjs";
+import { withCliConnection } from "../with-cli-connection.mjs";
+import { defineCommand } from "citty";
+
+//#region ../../@warlock.js/cascade/src/cli/commands/migrate.ts
+/**
+* `cascade migrate` — run all pending migrations against the configured
+* data source. With `--fresh` rolls back everything first and re-runs;
+* with `--sql` writes phase-ordered SQL files instead of executing.
+*/
+const migrateCommand = defineCommand({
+	meta: {
+		name: "migrate",
+		description: "Run all pending migrations against the configured data source."
+	},
+	args: {
+		fresh: {
+			type: "boolean",
+			alias: "f",
+			description: "Roll back every executed migration first, then run them again.",
+			default: false
+		},
+		sql: {
+			type: "boolean",
+			alias: "s",
+			description: "Export migrations to phase-ordered SQL files instead of executing.",
+			default: false
+		},
+		"pending-only": {
+			type: "boolean",
+			description: "When used with --sql, export only pending migrations.",
+			default: false
+		},
+		compact: {
+			type: "boolean",
+			alias: "c",
+			description: "When used with --sql, strip generated comments and blank lines.",
+			default: false
+		},
+		path: {
+			type: "string",
+			alias: "p",
+			description: "Glob pattern overriding the default ./migrations/**/*.{ts,js,mjs,cjs}."
+		}
+	},
+	async run({ args }) {
+		await withCliConnection(async () => {
+			await loadMigrations(args.path);
+			if (args.sql) {
+				await exportMigrationsSQL({
+					pendingOnly: Boolean(args["pending-only"]),
+					compact: Boolean(args.compact)
+				});
+				return;
+			}
+			printRunSummary(args.fresh ? await freshMigrate() : await runMigrations());
+		});
+	}
+});
+
+//#endregion
+export { migrateCommand };
+//# sourceMappingURL=migrate.mjs.map

package/esm/cli/commands/migrate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.mjs","names":[],"sources":["../../../../../../../@warlock.js/cascade/src/cli/commands/migrate.ts"],"sourcesContent":["import { defineCommand } from \"citty\";\nimport {\n  exportMigrationsSQL,\n  freshMigrate,\n  runMigrations,\n} from \"../../operations/migrations\";\nimport { loadMigrations } from \"../load-migrations\";\nimport { printRunSummary } from \"../printers\";\nimport { withCliConnection } from \"../with-cli-connection\";\n\n/**\n * `cascade migrate` — run all pending migrations against the configured\n * data source. With `--fresh` rolls back everything first and re-runs;\n * with `--sql` writes phase-ordered SQL files instead of executing.\n */\nexport const migrateCommand = defineCommand({\n  meta: {\n    name: \"migrate\",\n    description: \"Run all pending migrations against the configured data source.\",\n  },\n  args: {\n    fresh: {\n      type: \"boolean\",\n      alias: \"f\",\n      description: \"Roll back every executed migration first, then run them again.\",\n      default: false,\n    },\n    sql: {\n      type: \"boolean\",\n      alias: \"s\",\n      description: \"Export migrations to phase-ordered SQL files instead of executing.\",\n      default: false,\n    },\n    \"pending-only\": {\n      type: \"boolean\",\n      description: \"When used with --sql, export only pending migrations.\",\n      default: false,\n    },\n    compact: {\n      type: \"boolean\",\n      alias: \"c\",\n      description: \"When used with --sql, strip generated comments and blank lines.\",\n      default: false,\n    },\n    path: {\n      type: \"string\",\n      alias: \"p\",\n      description: \"Glob pattern overriding the default ./migrations/**/*.{ts,js,mjs,cjs}.\",\n    },\n  },\n  async run({ args }) {\n    await withCliConnection(async () => {\n      await loadMigrations(args.path);\n\n      if (args.sql) {\n        await exportMigrationsSQL({\n          pendingOnly: Boolean(args[\"pending-only\"]),\n          compact: Boolean(args.compact),\n        });\n\n        return;\n      }\n\n      const results = args.fresh ? await freshMigrate() : await runMigrations();\n\n      printRunSummary(results);\n    });\n  },\n});\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,iBAAiB,cAAc;CAC1C,MAAM;EACJ,MAAM;EACN,aAAa;CACf;CACA,MAAM;EACJ,OAAO;GACL,MAAM;GACN,OAAO;GACP,aAAa;GACb,SAAS;EACX;EACA,KAAK;GACH,MAAM;GACN,OAAO;GACP,aAAa;GACb,SAAS;EACX;EACA,gBAAgB;GACd,MAAM;GACN,aAAa;GACb,SAAS;EACX;EACA,SAAS;GACP,MAAM;GACN,OAAO;GACP,aAAa;GACb,SAAS;EACX;EACA,MAAM;GACJ,MAAM;GACN,OAAO;GACP,aAAa;EACf;CACF;CACA,MAAM,IAAI,EAAE,QAAQ;EAClB,MAAM,kBAAkB,YAAY;GAClC,MAAM,eAAe,KAAK,IAAI;GAE9B,IAAI,KAAK,KAAK;IACZ,MAAM,oBAAoB;KACxB,aAAa,QAAQ,KAAK,eAAe;KACzC,SAAS,QAAQ,KAAK,OAAO;IAC/B,CAAC;IAED;GACF;GAIA,gBAFgB,KAAK,QAAQ,MAAM,aAAa,IAAI,MAAM,cAAc,CAEjD;EACzB,CAAC;CACH;AACF,CAAC"}

package/esm/cli/connection-from-env.mjs

@@ -0,0 +1,181 @@
+import { dataSourceRegistry } from "../data-source/data-source-registry.mjs";
+import { MongoDbDriver } from "../drivers/mongodb/mongodb-driver.mjs";
+import { PostgresDriver } from "../drivers/postgres/postgres-driver.mjs";
+
+//#region ../../@warlock.js/cascade/src/cli/connection-from-env.ts
+const VALID_PRIMARY_KEYS = [
+	"uuid",
+	"int",
+	"bigInt"
+];
+const VALID_UUID_STRATEGIES = ["v4", "v7"];
+const POSTGRES_URL_PREFIXES = ["postgres://", "postgresql://"];
+const MONGODB_URL_PREFIXES = ["mongodb://", "mongodb+srv://"];
+/**
+* Validate and normalise the `CASCADE_PRIMARY_KEY` env var. Throws a CLI-
+* shaped error when the value is set but unrecognised.
+*/
+function parsePrimaryKey(raw) {
+	if (!raw) return;
+	const trimmed = raw.trim();
+	const match = VALID_PRIMARY_KEYS.find((value) => value.toLowerCase() === trimmed.toLowerCase());
+	if (!match) throw new Error(`Cascade CLI: invalid CASCADE_PRIMARY_KEY="${raw}". Expected one of ${VALID_PRIMARY_KEYS.join(" | ")}.`);
+	return match;
+}
+/**
+* Validate and normalise the `CASCADE_UUID_STRATEGY` env var. Throws a CLI-
+* shaped error when the value is set but unrecognised.
+*/
+function parseUuidStrategy(raw) {
+	if (!raw) return;
+	const trimmed = raw.trim().toLowerCase();
+	const match = VALID_UUID_STRATEGIES.find((value) => value === trimmed);
+	if (!match) throw new Error(`Cascade CLI: invalid CASCADE_UUID_STRATEGY="${raw}". Expected one of ${VALID_UUID_STRATEGIES.join(" | ")}.`);
+	return match;
+}
+/**
+* Read process env and collapse the alias pairs into a single resolved shape.
+*
+* Aliases (canonical → also-accepted):
+* - `DATABASE_URL` → `DB_URL`
+* - `DB_DIALECT` → `DB_DRIVER`
+* - `DB_USER` → `DB_USERNAME`
+*/
+function resolveDbEnv(env) {
+	return {
+		databaseUrl: env.DATABASE_URL?.trim() || env.DB_URL?.trim() || void 0,
+		dialect: env.DB_DIALECT?.trim() || env.DB_DRIVER?.trim() || void 0,
+		host: env.DB_HOST?.trim() || void 0,
+		port: env.DB_PORT?.toString().trim() || void 0,
+		database: env.DB_NAME?.trim() || void 0,
+		user: env.DB_USER?.trim() || env.DB_USERNAME?.trim() || void 0,
+		password: env.DB_PASSWORD !== void 0 ? String(env.DB_PASSWORD) : void 0,
+		primaryKey: parsePrimaryKey(env.CASCADE_PRIMARY_KEY),
+		uuidStrategy: parseUuidStrategy(env.CASCADE_UUID_STRATEGY)
+	};
+}
+/**
+* Build the optional `migrationDefaults` shape passed to the data source.
+* Returns `undefined` when neither env var is set — so consumers get the
+* cascade library defaults (`primaryKey: "int"`, `uuidStrategy: "v4"`).
+*/
+function buildMigrationDefaults(resolved) {
+	if (!resolved.primaryKey && !resolved.uuidStrategy) return;
+	return {
+		primaryKey: resolved.primaryKey,
+		uuidStrategy: resolved.uuidStrategy
+	};
+}
+/**
+* Parse the path portion of a database URL as the database name, returning
+* `undefined` when the URL is malformed or carries no database segment.
+*/
+function extractDatabaseFromUrl(url) {
+	try {
+		return new URL(url).pathname.replace(/^\//, "") || void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Detect the database dialect from env. First inspects the URL scheme, then
+* falls back to an explicit `DB_DIALECT` / `DB_DRIVER` env var.
+*
+* @example
+* const dialect = detectDialect();
+*/
+function detectDialect(env = process.env) {
+	const resolved = resolveDbEnv(env);
+	if (resolved.databaseUrl) {
+		if (POSTGRES_URL_PREFIXES.some((prefix) => resolved.databaseUrl.startsWith(prefix))) return "postgres";
+		if (MONGODB_URL_PREFIXES.some((prefix) => resolved.databaseUrl.startsWith(prefix))) return "mongodb";
+	}
+	const dialect = resolved.dialect?.toLowerCase();
+	if (dialect === "postgres" || dialect === "postgresql") return "postgres";
+	if (dialect === "mongodb" || dialect === "mongo") return "mongodb";
+	throw new Error("Cascade CLI: cannot detect database dialect. Set DATABASE_URL / DB_URL (postgres://… or mongodb://…) or DB_DIALECT / DB_DRIVER = postgres | mongodb.");
+}
+/**
+* Construct a Postgres driver — prefers a connection URL, otherwise builds
+* from discrete env vars.
+*/
+function buildPostgresDriver(resolved) {
+	if (resolved.databaseUrl) {
+		const database = extractDatabaseFromUrl(resolved.databaseUrl);
+		if (!database) throw new Error("Cascade CLI: DATABASE_URL / DB_URL is missing the database name in its path segment.");
+		return new PostgresDriver({
+			connectionString: resolved.databaseUrl,
+			database
+		});
+	}
+	if (!resolved.database) throw new Error("Cascade CLI: missing required env var DB_NAME.");
+	return new PostgresDriver({
+		host: resolved.host ?? "localhost",
+		port: resolved.port ? Number(resolved.port) : 5432,
+		database: resolved.database,
+		user: resolved.user,
+		password: resolved.password
+	});
+}
+/**
+* Construct a MongoDB driver — prefers a connection URI, otherwise builds
+* from discrete env vars.
+*/
+function buildMongoDriver(resolved) {
+	if (resolved.databaseUrl) {
+		const database = resolved.database ?? extractDatabaseFromUrl(resolved.databaseUrl);
+		if (!database) throw new Error("Cascade CLI: cannot resolve MongoDB database name. Either include it in DATABASE_URL / DB_URL or set DB_NAME.");
+		return new MongoDbDriver({
+			uri: resolved.databaseUrl,
+			database
+		});
+	}
+	if (!resolved.database) throw new Error("Cascade CLI: missing required env var DB_NAME.");
+	return new MongoDbDriver({
+		host: resolved.host ?? "localhost",
+		port: resolved.port ? Number(resolved.port) : 27017,
+		database: resolved.database,
+		username: resolved.user,
+		password: resolved.password
+	});
+}
+/**
+* Register a `default` data source on `dataSourceRegistry` derived entirely
+* from environment variables and open the underlying driver connection.
+*
+* Reads (canonical name → accepted aliases):
+* - `DATABASE_URL` → `DB_URL` (preferred when present)
+* - `DB_DIALECT` → `DB_DRIVER` (needed only when no URL)
+* - `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_PASSWORD` (no aliases)
+* - `DB_USER` → `DB_USERNAME`
+*
+* Optional migration defaults — affect how `Migration.create()` chooses the
+* primary-key column and which UUID function the driver emits. Unset means
+* the cascade library defaults apply (`primaryKey: "int"`, `uuidStrategy:
+* "v4"`).
+* - `CASCADE_PRIMARY_KEY` — `uuid` | `int` | `bigInt`
+* - `CASCADE_UUID_STRATEGY` — `v4` | `v7`
+*
+* The driver's pool/socket is opened before this function returns, so the
+* caller can issue queries immediately. Pair every call with
+* `disconnect()` (or use `withCliConnection`) so the process exits cleanly.
+*
+* @example
+* await connectFromEnv();
+* const results = await runMigrations();
+*/
+async function connectFromEnv(env = process.env) {
+	const dialect = detectDialect(env);
+	const resolved = resolveDbEnv(env);
+	const driver = dialect === "postgres" ? buildPostgresDriver(resolved) : buildMongoDriver(resolved);
+	await dataSourceRegistry.register({
+		name: "default",
+		driver,
+		isDefault: true,
+		migrationDefaults: buildMigrationDefaults(resolved)
+	}).driver.connect();
+}
+
+//#endregion
+export { connectFromEnv };
+//# sourceMappingURL=connection-from-env.mjs.map

package/esm/cli/connection-from-env.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-from-env.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/cli/connection-from-env.ts"],"sourcesContent":["import { dataSourceRegistry } from \"../data-source/data-source-registry\";\nimport { MongoDbDriver } from \"../drivers/mongodb/mongodb-driver\";\nimport { PostgresDriver } from \"../drivers/postgres/postgres-driver\";\nimport type { MigrationDefaults, UuidStrategy } from \"../types\";\n\nconst VALID_PRIMARY_KEYS = [\"uuid\", \"int\", \"bigInt\"] as const;\nconst VALID_UUID_STRATEGIES: readonly UuidStrategy[] = [\"v4\", \"v7\"];\n\ntype PrimaryKey = (typeof VALID_PRIMARY_KEYS)[number];\n\n/**\n * Supported database dialects for the standalone Cascade CLI.\n */\nexport type CliDialect = \"postgres\" | \"mongodb\";\n\nconst POSTGRES_URL_PREFIXES = [\"postgres://\", \"postgresql://\"];\nconst MONGODB_URL_PREFIXES = [\"mongodb://\", \"mongodb+srv://\"];\n\n/**\n * Canonical env shape Cascade actually consumes. The CLI accepts two\n * synonymous spellings for every var (canonical + warlock-shaped) so an\n * existing warlock project's `.env` works as-is without duplication.\n */\ntype ResolvedDbEnv = {\n  readonly databaseUrl?: string;\n  readonly dialect?: string;\n  readonly host?: string;\n  readonly port?: string;\n  readonly database?: string;\n  readonly user?: string;\n  readonly password?: string;\n  readonly primaryKey?: PrimaryKey;\n  readonly uuidStrategy?: UuidStrategy;\n};\n\n/**\n * Validate and normalise the `CASCADE_PRIMARY_KEY` env var. Throws a CLI-\n * shaped error when the value is set but unrecognised.\n */\nfunction parsePrimaryKey(raw: string | undefined): PrimaryKey | undefined {\n  if (!raw) {\n    return undefined;\n  }\n\n  const trimmed = raw.trim();\n\n  // Case-insensitive match — accept \"BIGINT\" / \"bigint\" / \"bigInt\".\n  const match = VALID_PRIMARY_KEYS.find((value) => value.toLowerCase() === trimmed.toLowerCase());\n\n  if (!match) {\n    throw new Error(\n      `Cascade CLI: invalid CASCADE_PRIMARY_KEY=\"${raw}\". ` +\n        `Expected one of ${VALID_PRIMARY_KEYS.join(\" | \")}.`,\n    );\n  }\n\n  return match;\n}\n\n/**\n * Validate and normalise the `CASCADE_UUID_STRATEGY` env var. Throws a CLI-\n * shaped error when the value is set but unrecognised.\n */\nfunction parseUuidStrategy(raw: string | undefined): UuidStrategy | undefined {\n  if (!raw) {\n    return undefined;\n  }\n\n  const trimmed = raw.trim().toLowerCase();\n  const match = VALID_UUID_STRATEGIES.find((value) => value === trimmed);\n\n  if (!match) {\n    throw new Error(\n      `Cascade CLI: invalid CASCADE_UUID_STRATEGY=\"${raw}\". ` +\n        `Expected one of ${VALID_UUID_STRATEGIES.join(\" | \")}.`,\n    );\n  }\n\n  return match;\n}\n\n/**\n * Read process env and collapse the alias pairs into a single resolved shape.\n *\n * Aliases (canonical → also-accepted):\n * - `DATABASE_URL` → `DB_URL`\n * - `DB_DIALECT` → `DB_DRIVER`\n * - `DB_USER` → `DB_USERNAME`\n */\nfunction resolveDbEnv(env: NodeJS.ProcessEnv): ResolvedDbEnv {\n  return {\n    databaseUrl: env.DATABASE_URL?.trim() || env.DB_URL?.trim() || undefined,\n    dialect: env.DB_DIALECT?.trim() || env.DB_DRIVER?.trim() || undefined,\n    host: env.DB_HOST?.trim() || undefined,\n    port: env.DB_PORT?.toString().trim() || undefined,\n    database: env.DB_NAME?.trim() || undefined,\n    user: env.DB_USER?.trim() || env.DB_USERNAME?.trim() || undefined,\n    password: env.DB_PASSWORD !== undefined ? String(env.DB_PASSWORD) : undefined,\n    primaryKey: parsePrimaryKey(env.CASCADE_PRIMARY_KEY),\n    uuidStrategy: parseUuidStrategy(env.CASCADE_UUID_STRATEGY),\n  };\n}\n\n/**\n * Build the optional `migrationDefaults` shape passed to the data source.\n * Returns `undefined` when neither env var is set — so consumers get the\n * cascade library defaults (`primaryKey: \"int\"`, `uuidStrategy: \"v4\"`).\n */\nfunction buildMigrationDefaults(resolved: ResolvedDbEnv): MigrationDefaults | undefined {\n  if (!resolved.primaryKey && !resolved.uuidStrategy) {\n    return undefined;\n  }\n\n  return {\n    primaryKey: resolved.primaryKey,\n    uuidStrategy: resolved.uuidStrategy,\n  };\n}\n\n/**\n * Parse the path portion of a database URL as the database name, returning\n * `undefined` when the URL is malformed or carries no database segment.\n */\nfunction extractDatabaseFromUrl(url: string): string | undefined {\n  try {\n    const parsed = new URL(url);\n    const segment = parsed.pathname.replace(/^\\//, \"\");\n\n    return segment || undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Detect the database dialect from env. First inspects the URL scheme, then\n * falls back to an explicit `DB_DIALECT` / `DB_DRIVER` env var.\n *\n * @example\n * const dialect = detectDialect();\n */\nexport function detectDialect(env: NodeJS.ProcessEnv = process.env): CliDialect {\n  const resolved = resolveDbEnv(env);\n\n  if (resolved.databaseUrl) {\n    if (POSTGRES_URL_PREFIXES.some((prefix) => resolved.databaseUrl!.startsWith(prefix))) {\n      return \"postgres\";\n    }\n\n    if (MONGODB_URL_PREFIXES.some((prefix) => resolved.databaseUrl!.startsWith(prefix))) {\n      return \"mongodb\";\n    }\n  }\n\n  const dialect = resolved.dialect?.toLowerCase();\n\n  if (dialect === \"postgres\" || dialect === \"postgresql\") {\n    return \"postgres\";\n  }\n\n  if (dialect === \"mongodb\" || dialect === \"mongo\") {\n    return \"mongodb\";\n  }\n\n  throw new Error(\n    \"Cascade CLI: cannot detect database dialect. \" +\n      \"Set DATABASE_URL / DB_URL (postgres://… or mongodb://…) \" +\n      \"or DB_DIALECT / DB_DRIVER = postgres | mongodb.\",\n  );\n}\n\n/**\n * Construct a Postgres driver — prefers a connection URL, otherwise builds\n * from discrete env vars.\n */\nfunction buildPostgresDriver(resolved: ResolvedDbEnv): PostgresDriver {\n  if (resolved.databaseUrl) {\n    const database = extractDatabaseFromUrl(resolved.databaseUrl);\n\n    if (!database) {\n      throw new Error(\n        \"Cascade CLI: DATABASE_URL / DB_URL is missing the database name in its path segment.\",\n      );\n    }\n\n    return new PostgresDriver({\n      connectionString: resolved.databaseUrl,\n      database,\n    });\n  }\n\n  if (!resolved.database) {\n    throw new Error(\"Cascade CLI: missing required env var DB_NAME.\");\n  }\n\n  return new PostgresDriver({\n    host: resolved.host ?? \"localhost\",\n    port: resolved.port ? Number(resolved.port) : 5432,\n    database: resolved.database,\n    user: resolved.user,\n    password: resolved.password,\n  });\n}\n\n/**\n * Construct a MongoDB driver — prefers a connection URI, otherwise builds\n * from discrete env vars.\n */\nfunction buildMongoDriver(resolved: ResolvedDbEnv): MongoDbDriver {\n  if (resolved.databaseUrl) {\n    const database = resolved.database ?? extractDatabaseFromUrl(resolved.databaseUrl);\n\n    if (!database) {\n      throw new Error(\n        \"Cascade CLI: cannot resolve MongoDB database name. \" +\n          \"Either include it in DATABASE_URL / DB_URL or set DB_NAME.\",\n      );\n    }\n\n    return new MongoDbDriver({\n      uri: resolved.databaseUrl,\n      database,\n    });\n  }\n\n  if (!resolved.database) {\n    throw new Error(\"Cascade CLI: missing required env var DB_NAME.\");\n  }\n\n  return new MongoDbDriver({\n    host: resolved.host ?? \"localhost\",\n    port: resolved.port ? Number(resolved.port) : 27017,\n    database: resolved.database,\n    username: resolved.user,\n    password: resolved.password,\n  });\n}\n\n/**\n * Register a `default` data source on `dataSourceRegistry` derived entirely\n * from environment variables and open the underlying driver connection.\n *\n * Reads (canonical name → accepted aliases):\n * - `DATABASE_URL` → `DB_URL` (preferred when present)\n * - `DB_DIALECT` → `DB_DRIVER` (needed only when no URL)\n * - `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_PASSWORD` (no aliases)\n * - `DB_USER` → `DB_USERNAME`\n *\n * Optional migration defaults — affect how `Migration.create()` chooses the\n * primary-key column and which UUID function the driver emits. Unset means\n * the cascade library defaults apply (`primaryKey: \"int\"`, `uuidStrategy:\n * \"v4\"`).\n * - `CASCADE_PRIMARY_KEY` — `uuid` | `int` | `bigInt`\n * - `CASCADE_UUID_STRATEGY` — `v4` | `v7`\n *\n * The driver's pool/socket is opened before this function returns, so the\n * caller can issue queries immediately. Pair every call with\n * `disconnect()` (or use `withCliConnection`) so the process exits cleanly.\n *\n * @example\n * await connectFromEnv();\n * const results = await runMigrations();\n */\nexport async function connectFromEnv(env: NodeJS.ProcessEnv = process.env): Promise<void> {\n  const dialect = detectDialect(env);\n  const resolved = resolveDbEnv(env);\n\n  const driver =\n    dialect === \"postgres\" ? buildPostgresDriver(resolved) : buildMongoDriver(resolved);\n\n  const dataSource = dataSourceRegistry.register({\n    name: \"default\",\n    driver,\n    isDefault: true,\n    migrationDefaults: buildMigrationDefaults(resolved),\n  });\n\n  await dataSource.driver.connect();\n}\n"],"mappings":"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"}

package/esm/cli/index.mjs

@@ -0,0 +1,31 @@
+import { migrateCommand } from "./commands/migrate.mjs";
+import { migrateExportSqlCommand } from "./commands/migrate-export-sql.mjs";
+import { migrateListCommand } from "./commands/migrate-list.mjs";
+import { migrateRollbackCommand } from "./commands/migrate-rollback.mjs";
+import { defineCommand } from "citty";
+
+//#region ../../@warlock.js/cascade/src/cli/index.ts
+/**
+* Root command for the standalone `cascade` CLI binary. Scope is restricted
+* to migration operations — database management (`db:create` etc.) stays in
+* the warlock-core CLI where the project context is available.
+*
+* Subcommands follow colon-style naming (`cascade migrate:list`) so each
+* verb stays addressable as a single argv token.
+*/
+const main = defineCommand({
+	meta: {
+		name: "cascade",
+		description: "Standalone Cascade ORM migration CLI."
+	},
+	subCommands: {
+		migrate: migrateCommand,
+		"migrate:list": migrateListCommand,
+		"migrate:rollback": migrateRollbackCommand,
+		"migrate:export-sql": migrateExportSqlCommand
+	}
+});
+
+//#endregion
+export { main };
+//# sourceMappingURL=index.mjs.map

package/esm/cli/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/cli/index.ts"],"sourcesContent":["import { defineCommand } from \"citty\";\nimport { migrateCommand } from \"./commands/migrate\";\nimport { migrateExportSqlCommand } from \"./commands/migrate-export-sql\";\nimport { migrateListCommand } from \"./commands/migrate-list\";\nimport { migrateRollbackCommand } from \"./commands/migrate-rollback\";\n\n/**\n * Root command for the standalone `cascade` CLI binary. Scope is restricted\n * to migration operations — database management (`db:create` etc.) stays in\n * the warlock-core CLI where the project context is available.\n *\n * Subcommands follow colon-style naming (`cascade migrate:list`) so each\n * verb stays addressable as a single argv token.\n */\nexport const main = defineCommand({\n  meta: {\n    name: \"cascade\",\n    description: \"Standalone Cascade ORM migration CLI.\",\n  },\n  subCommands: {\n    migrate: migrateCommand,\n    \"migrate:list\": migrateListCommand,\n    \"migrate:rollback\": migrateRollbackCommand,\n    \"migrate:export-sql\": migrateExportSqlCommand,\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;AAcA,MAAa,OAAO,cAAc;CAChC,MAAM;EACJ,MAAM;EACN,aAAa;CACf;CACA,aAAa;EACX,SAAS;EACT,gBAAgB;EAChB,oBAAoB;EACpB,sBAAsB;CACxB;AACF,CAAC"}

package/esm/cli/load-migrations.mjs

@@ -0,0 +1,78 @@
+import { migrationRunner } from "../migration/migration-runner.mjs";
+import path from "path";
+import fastGlob from "fast-glob";
+import { pathToFileURL } from "url";
+
+//#region ../../@warlock.js/cascade/src/cli/load-migrations.ts
+const DEFAULT_PATTERN = "./migrations/**/*.{ts,js,mjs,cjs}";
+/**
+* Resolve the migration name from a filename. Mirrors warlock-core's
+* convention: drop the extension, strip a trailing `-migration` /
+* `_migration` suffix.
+*/
+function inferNameFromFile(file) {
+	return path.basename(file).split(".")[0].replace(/-migration$/, "").replace(/_migration$/, "");
+}
+/**
+* Extract a leading `MM-DD-YYYY_HH-MM-SS` (or `DD-MM-YYYY_HH-MM-SS`)
+* timestamp from a migration filename so the runner can sort migrations
+* deterministically. Returns `undefined` when no timestamp is present.
+*/
+function inferCreatedAtFromFile(file) {
+	const match = path.basename(file).match(/^(\d{2}-\d{2}-\d{4}_\d{2}-\d{2}-\d{2})/);
+	return match ? match[1] : void 0;
+}
+/**
+* Produce a helpful CLI error when Node refuses to import a `.ts` migration
+* file directly — the standalone Cascade CLI ships no TS transpiler, and
+* users hitting this error need to invoke through `tsx`/`tsm` or compile
+* their migrations to JS first.
+*/
+function explainImportFailure(file, error) {
+	const message = error instanceof Error ? error.message : String(error);
+	if (file.endsWith(".ts") || file.endsWith(".tsx")) return /* @__PURE__ */ new Error(`Cascade CLI: failed to load TypeScript migration ${file}.\nNode cannot import .ts files natively — invoke the CLI through a TS runtime, e.g.:\n  npx tsx node_modules/.bin/cascade migrate\nOr pre-compile migrations to JS before running.\nOriginal error: ${message}`);
+	return /* @__PURE__ */ new Error(`Cascade CLI: failed to load migration ${file}. ${message}`);
+}
+/**
+* Discover migration files via `fast-glob`, dynamic-import each, and register
+* the default export on `migrationRunner`. Migration name and `createdAt`
+* are inferred from the filename when the class does not declare them.
+*
+* Default glob: `./migrations/**/*.{ts,js,mjs,cjs}` from `process.cwd()`.
+* Pass an explicit pattern to override.
+*
+* @returns Number of migration files registered.
+*
+* @example
+* await loadMigrations();
+* await loadMigrations("./db/schema/*.migration.js");
+*/
+async function loadMigrations(pattern) {
+	const files = await fastGlob(pattern ?? DEFAULT_PATTERN, {
+		absolute: true,
+		cwd: process.cwd(),
+		onlyFiles: true
+	});
+	for (const file of files) {
+		const fileUrl = pathToFileURL(file).href;
+		let loadedModule;
+		try {
+			loadedModule = await import(fileUrl);
+		} catch (error) {
+			throw explainImportFailure(file, error);
+		}
+		const MigrationClass = loadedModule.default;
+		if (!MigrationClass) throw new Error(`Cascade CLI: ${file} must export a default migration class.`);
+		if (!MigrationClass.migrationName) MigrationClass.migrationName = inferNameFromFile(file);
+		if (!MigrationClass.createdAt) {
+			const createdAt = inferCreatedAtFromFile(file);
+			if (createdAt) MigrationClass.createdAt = createdAt;
+		}
+		migrationRunner.register(MigrationClass);
+	}
+	return files.length;
+}
+
+//#endregion
+export { loadMigrations };
+//# sourceMappingURL=load-migrations.mjs.map

package/esm/cli/load-migrations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-migrations.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/cli/load-migrations.ts"],"sourcesContent":["import fastGlob from \"fast-glob\";\nimport path from \"path\";\nimport { pathToFileURL } from \"url\";\nimport { migrationRunner } from \"../migration/migration-runner\";\n\nconst DEFAULT_PATTERN = \"./migrations/**/*.{ts,js,mjs,cjs}\";\n\n/**\n * Resolve the migration name from a filename. Mirrors warlock-core's\n * convention: drop the extension, strip a trailing `-migration` /\n * `_migration` suffix.\n */\nfunction inferNameFromFile(file: string): string {\n  const basename = path.basename(file).split(\".\")[0];\n\n  return basename.replace(/-migration$/, \"\").replace(/_migration$/, \"\");\n}\n\n/**\n * Extract a leading `MM-DD-YYYY_HH-MM-SS` (or `DD-MM-YYYY_HH-MM-SS`)\n * timestamp from a migration filename so the runner can sort migrations\n * deterministically. Returns `undefined` when no timestamp is present.\n */\nfunction inferCreatedAtFromFile(file: string): string | undefined {\n  const basename = path.basename(file);\n  const match = basename.match(/^(\\d{2}-\\d{2}-\\d{4}_\\d{2}-\\d{2}-\\d{2})/);\n\n  return match ? match[1] : undefined;\n}\n\n/**\n * Produce a helpful CLI error when Node refuses to import a `.ts` migration\n * file directly — the standalone Cascade CLI ships no TS transpiler, and\n * users hitting this error need to invoke through `tsx`/`tsm` or compile\n * their migrations to JS first.\n */\nfunction explainImportFailure(file: string, error: unknown): Error {\n  const message = error instanceof Error ? error.message : String(error);\n\n  if (file.endsWith(\".ts\") || file.endsWith(\".tsx\")) {\n    return new Error(\n      `Cascade CLI: failed to load TypeScript migration ${file}.\\n` +\n        `Node cannot import .ts files natively — invoke the CLI through a TS runtime, e.g.:\\n` +\n        `  npx tsx node_modules/.bin/cascade migrate\\n` +\n        `Or pre-compile migrations to JS before running.\\n` +\n        `Original error: ${message}`,\n    );\n  }\n\n  return new Error(`Cascade CLI: failed to load migration ${file}. ${message}`);\n}\n\n/**\n * Discover migration files via `fast-glob`, dynamic-import each, and register\n * the default export on `migrationRunner`. Migration name and `createdAt`\n * are inferred from the filename when the class does not declare them.\n *\n * Default glob: `./migrations/&#42;&#42;/&#42;.{ts,js,mjs,cjs}` from `process.cwd()`.\n * Pass an explicit pattern to override.\n *\n * @returns Number of migration files registered.\n *\n * @example\n * await loadMigrations();\n * await loadMigrations(\"./db/schema/&#42;.migration.js\");\n */\nexport async function loadMigrations(pattern?: string): Promise<number> {\n  const resolvedPattern = pattern ?? DEFAULT_PATTERN;\n\n  const files = await fastGlob(resolvedPattern, {\n    absolute: true,\n    cwd: process.cwd(),\n    onlyFiles: true,\n  });\n\n  for (const file of files) {\n    const fileUrl = pathToFileURL(file).href;\n\n    let loadedModule: { default?: unknown };\n\n    try {\n      loadedModule = await import(fileUrl);\n    } catch (error) {\n      throw explainImportFailure(file, error);\n    }\n\n    const MigrationClass = loadedModule.default as\n      | (Function & { migrationName?: string; createdAt?: string })\n      | undefined;\n\n    if (!MigrationClass) {\n      throw new Error(`Cascade CLI: ${file} must export a default migration class.`);\n    }\n\n    if (!MigrationClass.migrationName) {\n      MigrationClass.migrationName = inferNameFromFile(file);\n    }\n\n    if (!MigrationClass.createdAt) {\n      const createdAt = inferCreatedAtFromFile(file);\n\n      if (createdAt) {\n        MigrationClass.createdAt = createdAt;\n      }\n    }\n\n    // Cast back through the runner's expected shape; the runner validates\n    // `migrationName` exists before registration succeeds.\n    migrationRunner.register(MigrationClass as never);\n  }\n\n  return files.length;\n}\n"],"mappings":";;;;;;AAKA,MAAM,kBAAkB;;;;;;AAOxB,SAAS,kBAAkB,MAAsB;CAG/C,OAFiB,KAAK,SAAS,IAAI,EAAE,MAAM,GAAG,EAAE,GAEhC,QAAQ,eAAe,EAAE,EAAE,QAAQ,eAAe,EAAE;AACtE;;;;;;AAOA,SAAS,uBAAuB,MAAkC;CAEhE,MAAM,QADW,KAAK,SAAS,IACV,EAAE,MAAM,wCAAwC;CAErE,OAAO,QAAQ,MAAM,KAAK;AAC5B;;;;;;;AAQA,SAAS,qBAAqB,MAAc,OAAuB;CACjE,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CAErE,IAAI,KAAK,SAAS,KAAK,KAAK,KAAK,SAAS,MAAM,GAC9C,uBAAO,IAAI,MACT,oDAAoD,KAAK,uMAIpC,SACvB;CAGF,uBAAO,IAAI,MAAM,yCAAyC,KAAK,IAAI,SAAS;AAC9E;;;;;;;;;;;;;;;AAgBA,eAAsB,eAAe,SAAmC;CAGtE,MAAM,QAAQ,MAAM,SAFI,WAAW,iBAEW;EAC5C,UAAU;EACV,KAAK,QAAQ,IAAI;EACjB,WAAW;CACb,CAAC;CAED,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,UAAU,cAAc,IAAI,EAAE;EAEpC,IAAI;EAEJ,IAAI;GACF,eAAe,MAAM,OAAO;EAC9B,SAAS,OAAO;GACd,MAAM,qBAAqB,MAAM,KAAK;EACxC;EAEA,MAAM,iBAAiB,aAAa;EAIpC,IAAI,CAAC,gBACH,MAAM,IAAI,MAAM,gBAAgB,KAAK,wCAAwC;EAG/E,IAAI,CAAC,eAAe,eAClB,eAAe,gBAAgB,kBAAkB,IAAI;EAGvD,IAAI,CAAC,eAAe,WAAW;GAC7B,MAAM,YAAY,uBAAuB,IAAI;GAE7C,IAAI,WACF,eAAe,YAAY;EAE/B;EAIA,gBAAgB,SAAS,cAAuB;CAClD;CAEA,OAAO,MAAM;AACf"}