@better-schemic/core 0.1.0-alpha.1

package/lib/chunk-RSGP7GVO.js

@@ -0,0 +1,252 @@
+// src/cli-kit/config.ts
+import { existsSync, statSync } from "fs";
+import { basename, dirname, resolve } from "path";
+import { createJiti } from "jiti";
+var CONFIG_NAMES = [
+  "better-schemic.config.ts",
+  "better-schemic.config.mjs",
+  "better-schemic.config.js",
+  "better-schemic.ts",
+  // Legacy aliases (pre-rename) — still discovered, after the canonical names.
+  "schemic.config.ts",
+  "schemic.config.mjs",
+  "schemic.config.js",
+  "schemic.ts"
+];
+function schemaIsFilePath(path) {
+  if (existsSync(path)) return statSync(path).isFile();
+  return /\.[mc]?[jt]s$/.test(path);
+}
+function loadDotEnv(dir) {
+  const proc = process;
+  if (typeof proc.loadEnvFile !== "function") return;
+  for (const name of [".env.local", ".env"]) {
+    const file = resolve(dir, name);
+    if (!existsSync(file)) continue;
+    try {
+      proc.loadEnvFile(file);
+    } catch {
+    }
+  }
+}
+function makeJiti() {
+  return createJiti(import.meta.url, {
+    interopDefault: true,
+    fsCache: false,
+    moduleCache: false
+  });
+}
+async function loadProject(opts) {
+  const cwd = opts?.cwd ?? process.cwd();
+  const candidates = opts?.config ? [resolve(cwd, opts.config)] : CONFIG_NAMES.map((n) => resolve(cwd, n)).filter((p) => existsSync(p));
+  if (!candidates.length || !existsSync(candidates[0])) {
+    throw new Error(
+      "No better-schemic.ts / better-schemic.config.ts found \u2014 run `better-schemic init` first."
+    );
+  }
+  const jiti = makeJiti();
+  for (const path of candidates) {
+    const root = dirname(path);
+    loadDotEnv(root);
+    const loaded = await jiti.import(path);
+    const config = [
+      loaded.default,
+      loaded.betterSchemic,
+      loaded.schemic,
+      loaded
+    ].find(
+      (c) => !!c && typeof c === "object" && "connections" in c
+    );
+    if (config?.connections && Object.keys(config.connections).length > 0) {
+      return { config, root };
+    }
+    if (!opts?.config && (basename(path) === "better-schemic.ts" || basename(path) === "schemic.ts"))
+      continue;
+    throw new Error(`Invalid config at ${path}: expected a "connections" map.`);
+  }
+  throw new Error(
+    'No Better-schemic config found \u2014 ./better-schemic.ts exists but doesn\'t export a config with a "connections" map. Run `better-schemic init`, or export one via defineConfig.'
+  );
+}
+function resolveConnectionConfig(config, connection, conn, driver, root) {
+  const { schema, migrations, key, ...params } = conn;
+  const schemaPath = resolve(root, schema);
+  const migrationsDir = migrations ? resolve(root, migrations) : resolve(schemaPath, "..", "migrations");
+  return {
+    connection: key ? `${connection}:${key}` : connection,
+    driver,
+    root,
+    schemaPath,
+    schemaIsFile: schemaIsFilePath(schemaPath),
+    migrationsDir,
+    metaDir: resolve(migrationsDir, "meta"),
+    migrationsTable: config.migrationsTable ?? "_migrations",
+    params,
+    seed: config.seed
+  };
+}
+async function loadConfig(opts) {
+  const { config, root } = await loadProject(opts);
+  const names = Object.keys(config.connections);
+  const name = config.defaultConnection ?? (names.length === 1 ? names[0] : "default");
+  const entry = config.connections[name];
+  if (!entry) {
+    throw new Error(
+      `No connection named "${name}". Set "defaultConnection" or pass --connection. Known: ${names.join(", ")}.`
+    );
+  }
+  const ctx = { connections: {}, env: process.env };
+  const resolved = await entry.resolve(ctx);
+  if (resolved.length !== 1) {
+    throw new Error(
+      `Connection "${name}" resolved to ${resolved.length} connections (a collection); pass --connection ${name}:<key>.`
+    );
+  }
+  return resolveConnectionConfig(config, name, resolved[0], entry.driver, root);
+}
+
+// src/client.ts
+function asyncDisposable(proto) {
+  proto[Symbol.asyncDispose] = function() {
+    return this.close();
+  };
+}
+function makeRuntimeContext(config, root) {
+  const opened = /* @__PURE__ */ new Map();
+  const resolving = /* @__PURE__ */ new Set();
+  const open = async (name) => {
+    if (resolving.has(name)) {
+      throw new Error(
+        `cyclic connection resolution: "${name}" is already resolving (a resolver reached back into itself via ctx.connections)`
+      );
+    }
+    const entry = config.connections[name];
+    if (!entry) throw new Error(`ctx.connections.${name}: no such connection`);
+    if (!entry.client) {
+      throw new Error(
+        `ctx.connections.${name}: the "${entry.driver}" connection factory predates runtime cross-connection access \u2014 update @better-schemic/${entry.driver}`
+      );
+    }
+    resolving.add(name);
+    try {
+      const bases = await entry.resolve(context, void 0);
+      if (bases.length !== 1) {
+        throw new Error(
+          `ctx.connections.${name}: resolved to ${bases.length} configs \u2014 a sibling reached via ctx.connections must resolve to exactly one`
+        );
+      }
+      const rc = resolveConnectionConfig(
+        config,
+        name,
+        bases[0],
+        entry.driver,
+        root
+      );
+      return await entry.client(rc);
+    } finally {
+      resolving.delete(name);
+    }
+  };
+  const context = {
+    env: process.env,
+    connections: new Proxy(
+      {},
+      {
+        get(_t, name) {
+          const openOnce = () => {
+            let client = opened.get(name);
+            if (!client) {
+              client = open(name);
+              opened.set(name, client);
+            }
+            return client;
+          };
+          return {
+            query: async (sql, vars) => {
+              const db = await openOnce();
+              return db.query(sql, vars);
+            },
+            then: (onOk, onErr) => openOnce().then(onOk, onErr)
+          };
+        }
+      }
+    )
+  };
+  const closeOpened = async () => {
+    for (const c of opened.values()) {
+      try {
+        await (await c).close?.();
+      } catch {
+      }
+    }
+    opened.clear();
+  };
+  return { context, closeOpened, resolving };
+}
+async function resolveConnection(opts = {}) {
+  const { config, root } = await loadProject({
+    config: opts.config,
+    cwd: opts.cwd
+  });
+  return exactlyOne(
+    await resolveFromConfig(config, root, { name: opts.name, args: opts.args })
+  );
+}
+async function resolveFromConfig(config, root, opts = {}) {
+  const names = Object.keys(config.connections);
+  const name = opts.name ?? config.defaultConnection ?? (names.length === 1 ? names[0] : "default");
+  const entry = config.connections[name];
+  if (!entry) {
+    throw new Error(
+      `connection "${name}" is not defined in the config (have: ${names.join(", ") || "none"})`
+    );
+  }
+  const rt = makeRuntimeContext(config, root);
+  rt.resolving.add(name);
+  try {
+    const bases = await entry.resolve(rt.context, opts.args);
+    if (!bases.length) {
+      throw new Error(`connection "${name}" resolved to no config`);
+    }
+    const resolved = bases.map(
+      (b) => resolveConnectionConfig(config, name, b, entry.driver, root)
+    );
+    const labels = resolved.map(
+      (rc, i) => bases[i].key ?? entry.label?.(rc) ?? `${name}[${i}]`
+    );
+    return { entry, name, resolved, labels };
+  } finally {
+    rt.resolving.delete(name);
+    await rt.closeOpened();
+  }
+}
+function exactlyOne(r) {
+  if (r.resolved.length !== 1) {
+    throw new Error(
+      `connection "${r.name}" resolved to ${r.resolved.length} configs (${r.labels.join(", ")}) \u2014 a parameterized/bulk connection. Pass args selecting exactly one, e.g. betterSchemic.connect("${r.name}", { ... }).`
+    );
+  }
+  return r.resolved[0];
+}
+async function connectFromConfig(config, name, args) {
+  const r = await resolveFromConfig(config, process.cwd(), { name, args });
+  const resolved = exactlyOne(r);
+  if (!r.entry.client) {
+    throw new Error(
+      `the "${r.entry.driver}" connection factory predates config.connect() \u2014 update @better-schemic/${r.entry.driver} to a version whose ${r.entry.driver}Connection embeds a client opener`
+    );
+  }
+  return r.entry.client(resolved);
+}
+
+export {
+  makeJiti,
+  loadProject,
+  resolveConnectionConfig,
+  loadConfig,
+  asyncDisposable,
+  resolveConnection,
+  resolveFromConfig,
+  connectFromConfig
+};
+//# sourceMappingURL=chunk-RSGP7GVO.js.map

package/lib/chunk-RSGP7GVO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli-kit/config.ts","../src/client.ts"],"sourcesContent":["import { existsSync, statSync } from \"node:fs\";\nimport { basename, dirname, resolve } from \"node:path\";\nimport type { BetterSchemicConfig } from \"@better-schemic/core/config\";\nimport { createJiti } from \"jiti\";\nimport type { ConnectionConfigBase, ResolveContext } from \"../connection\";\n\n// `better-schemic.ts` is the scaffolded name (the config IS the app's DB module — `betterSchemic.connect()`);\n// the legacy `schemic.config.*` / `schemic.ts` spellings keep working. Checked LAST + shape-guarded, so an unrelated\n// `./better-schemic.ts` helper module in a project never shadows a real `better-schemic.config.ts`.\nconst CONFIG_NAMES = [\n  \"better-schemic.config.ts\",\n  \"better-schemic.config.mjs\",\n  \"better-schemic.config.js\",\n  \"better-schemic.ts\",\n  // Legacy aliases (pre-rename) — still discovered, after the canonical names.\n  \"schemic.config.ts\",\n  \"schemic.config.mjs\",\n  \"schemic.config.js\",\n  \"schemic.ts\",\n];\n\n/**\n * Is the schema path a single file (vs a directory of schema modules)? Determined by `stat` when\n * it exists, else inferred from a `.ts`/`.js`-ish extension.\n */\nfunction schemaIsFilePath(path: string): boolean {\n  if (existsSync(path)) return statSync(path).isFile();\n  return /\\.[mc]?[jt]s$/.test(path);\n}\n\n/**\n * Load `.env(.local)` from the project root into `process.env` so the config's own explicit\n * `process.env.X` reads resolve when run under node (bun loads `.env` itself). Does not override\n * already-set variables, so shell env still wins; load `.env.local` first so it beats `.env`.\n */\nfunction loadDotEnv(dir: string): void {\n  const proc = process as typeof process & {\n    loadEnvFile?: (path: string) => void;\n  };\n  if (typeof proc.loadEnvFile !== \"function\") return;\n  for (const name of [\".env.local\", \".env\"]) {\n    const file = resolve(dir, name);\n    if (!existsSync(file)) continue;\n    try {\n      proc.loadEnvFile(file);\n    } catch {\n      // ignore a malformed .env file\n    }\n  }\n}\n\n/**\n * A resolved, per-CONNECTION config — the dialect-NEUTRAL shape every command operates on (one\n * connection at a time). `params` are the driver-specific connection params (opaque to core; the\n * driver's `connect` reads them). Built by resolving one entry of `config.connections`.\n */\nexport interface ResolvedConfig {\n  /** Resolved connection name (e.g. `default`, or `tenants:abc` within a collection). */\n  connection: string;\n  /** The driver this connection uses (the package the CLI dynamically loads). */\n  driver: string;\n  /** Project root (the directory containing the config file). */\n  root: string;\n  /** Absolute schema path — a single `.ts` module, or a directory of them. */\n  schemaPath: string;\n  /** Whether `schemaPath` is a single file (vs a directory of schema modules). */\n  schemaIsFile: boolean;\n  /** Absolute migrations directory (per connection's schema). */\n  migrationsDir: string;\n  /** Absolute migration meta directory (the snapshot). */\n  metaDir: string;\n  /** Name of the table that records applied migrations. */\n  migrationsTable: string;\n  /** Driver-specific connection params (url/namespace/… or whatever the driver defines). Opaque to core. */\n  params: Record<string, unknown>;\n  /** Optional seed script (project-level). */\n  seed?: string;\n}\n\n/**\n * A jiti instance for loading the project's TS/ESM modules. Caches are off so `--watch` re-reads\n * edited schema files. (Bare deps like `@better-schemic/core` are native-imported, so registries stay shared.)\n */\nexport function makeJiti() {\n  return createJiti(import.meta.url, {\n    interopDefault: true,\n    fsCache: false,\n    moduleCache: false,\n  });\n}\n\n/** Find + load `better-schemic.ts` / `better-schemic.config.ts` (legacy `schemic.*` aliases included) into the dialect-neutral {@link BetterSchemicConfig}. */\nexport async function loadProject(opts?: {\n  config?: string;\n  cwd?: string;\n}): Promise<{ config: BetterSchemicConfig; root: string }> {\n  const cwd = opts?.cwd ?? process.cwd();\n  const candidates = opts?.config\n    ? [resolve(cwd, opts.config)]\n    : CONFIG_NAMES.map((n) => resolve(cwd, n)).filter((p) => existsSync(p));\n  if (!candidates.length || !existsSync(candidates[0])) {\n    throw new Error(\n      \"No better-schemic.ts / better-schemic.config.ts found — run `better-schemic init` first.\",\n    );\n  }\n  const jiti = makeJiti();\n  for (const path of candidates) {\n    const root = dirname(path);\n    loadDotEnv(root); // populate process.env before the config module's explicit reads\n    const loaded = (await jiti.import(path)) as {\n      default?: BetterSchemicConfig;\n      betterSchemic?: BetterSchemicConfig;\n      schemic?: BetterSchemicConfig;\n    } & BetterSchemicConfig;\n    // Accept a default export OR the named `betterSchemic` export (legacy: `schemic`) — the scaffolded\n    // form is the NAMED one (`export const betterSchemic = defineConfig(...)`), so app code auto-imports\n    // a deterministic identifier (`import { betterSchemic } from \"./better-schemic.config\"` ->\n    // `betterSchemic.connect()`). Selected by SHAPE, not presence: jiti's interopDefault makes\n    // `loaded.default` a truthy proxy even when the module has no real default export, so a presence\n    // chain would shadow the named export.\n    const config = [\n      loaded.default,\n      loaded.betterSchemic,\n      loaded.schemic,\n      loaded,\n    ].find(\n      (c): c is BetterSchemicConfig =>\n        !!c && typeof c === \"object\" && \"connections\" in c,\n    );\n    if (config?.connections && Object.keys(config.connections).length > 0) {\n      return { config, root };\n    }\n    // An AUTO-discovered bare `better-schemic.ts` (or legacy `schemic.ts`) without a connections map is\n    // an unrelated helper module, not a config — skip it (an explicitly-passed or `*.config.*` file\n    // still errors loudly).\n    if (\n      !opts?.config &&\n      (basename(path) === \"better-schemic.ts\" ||\n        basename(path) === \"schemic.ts\")\n    )\n      continue;\n    throw new Error(`Invalid config at ${path}: expected a \"connections\" map.`);\n  }\n  throw new Error(\n    'No Better-schemic config found — ./better-schemic.ts exists but doesn\\'t export a config with a \"connections\" map. Run `better-schemic init`, or export one via defineConfig.',\n  );\n}\n\n/**\n * Build the {@link ResolvedConfig} for one connection of the project. `ctx` carries the lazy\n * cross-connection proxy + CLI `--arg`s (the CLI provides the real one; a static connection ignores\n * it). A resolver returning a COLLECTION yields one ResolvedConfig per keyed entry.\n *\n * NOTE (WIP — multi-connection): the full resolution engine (lazy proxy DAG, `--connection`/`--all`\n * addressing, collection fan-out) lives in `@better-schemic/cli`; this builder handles a single resolved\n * connection config. See docs/MULTI-CONNECTION.md.\n */\nexport function resolveConnectionConfig(\n  config: BetterSchemicConfig,\n  connection: string,\n  conn: ConnectionConfigBase,\n  driver: string,\n  root: string,\n): ResolvedConfig {\n  const { schema, migrations, key, ...params } = conn;\n  const schemaPath = resolve(root, schema);\n  // Default migrations dir is RELATIVE TO THE SCHEMA (the documented contract): the sibling\n  // `migrations` dir next to the schema dir (or next to a single-file schema). For the standard\n  // scaffold (`schema: \"./database/schema\"`) that is `./database/migrations`, unchanged; a nested\n  // schema (`./src/database/schema`) correctly gets `./src/database/migrations` instead of a\n  // root-fixed default that split state across two locations.\n  const migrationsDir = migrations\n    ? resolve(root, migrations)\n    : resolve(schemaPath, \"..\", \"migrations\");\n  return {\n    connection: key ? `${connection}:${key}` : connection,\n    driver,\n    root,\n    schemaPath,\n    schemaIsFile: schemaIsFilePath(schemaPath),\n    migrationsDir,\n    metaDir: resolve(migrationsDir, \"meta\"),\n    migrationsTable: config.migrationsTable ?? \"_migrations\",\n    params: params as Record<string, unknown>,\n    seed: config.seed,\n  };\n}\n\n/**\n * Load the project and resolve the DEFAULT connection to a {@link ResolvedConfig} — the single-\n * connection convenience path. (Multi-connection addressing + resolver context are added by the CLI;\n * here a static default connection is resolved with an empty context.)\n */\nexport async function loadConfig(opts?: {\n  config?: string;\n  cwd?: string;\n}): Promise<ResolvedConfig> {\n  const { config, root } = await loadProject(opts);\n  const names = Object.keys(config.connections);\n  const name =\n    config.defaultConnection ?? (names.length === 1 ? names[0] : \"default\");\n  const entry = config.connections[name];\n  if (!entry) {\n    throw new Error(\n      `No connection named \"${name}\". Set \"defaultConnection\" or pass --connection. Known: ${names.join(\", \")}.`,\n    );\n  }\n  const ctx: ResolveContext = { connections: {}, env: process.env };\n  const resolved = await entry.resolve(ctx);\n  if (resolved.length !== 1) {\n    throw new Error(\n      `Connection \"${name}\" resolved to ${resolved.length} connections (a collection); pass --connection ${name}:<key>.`,\n    );\n  }\n  return resolveConnectionConfig(config, name, resolved[0], entry.driver, root);\n}\n\n/** Per-command connection flag overrides (CLI args, applied by the driver over `params`). */\nexport interface ConnectionOverrides {\n  url?: string;\n  namespace?: string;\n  database?: string;\n  username?: string;\n  password?: string;\n  authLevel?: string;\n}\n","// The neutral foundation for the bound ORM CLIENT (P1) — the runtime read/write handle each driver\n// builds on. Core owns only the dialect-agnostic parts: the disposable lifecycle contract and the\n// managed-connection resolution. A driver's client (`@better-schemic/<driver>/client`) extends `OrmClientBase`,\n// binds its native connection, and adds its TYPED `select`/`call` (+ writes in P2). See\n// docs/proposals/managed-connections-and-orm-client.md.\n\nimport {\n  loadProject,\n  type ResolvedConfig,\n  resolveConnectionConfig,\n} from \"./cli-kit/config\";\nimport type { BetterSchemicConfig } from \"./config\";\nimport type { AnyConnectionEntry, ResolveContext } from \"./connection\";\n\n/**\n * The neutral bound-client contract. A driver's client extends this and adds its typed query surface.\n * It is an `AsyncDisposable`, so `await using db = await connect()` closes it at block exit.\n *\n * DISPOSE RULE (hard): a MANAGED client (opened by {@link resolveConnection} + the driver's `connect`)\n * closes the connection it opened; a BYO client (wrapping the user's own pool) MUST make `close` a\n * NO-OP — we never close a connection the user owns. The driver enforces this at construction.\n */\nexport interface OrmClientBase extends AsyncDisposable {\n  /** Close the underlying connection (managed only; a BYO client is a no-op — see the dispose rule). */\n  close(): Promise<void>;\n}\n\n/** Mixin the default `[Symbol.asyncDispose]` (= `close`) onto a client class's prototype. */\nexport function asyncDisposable<T extends { close(): Promise<void> }>(\n  proto: T,\n): void {\n  (proto as { [Symbol.asyncDispose]?: () => Promise<void> })[\n    Symbol.asyncDispose\n  ] = function (this: T) {\n    return this.close();\n  };\n}\n\n/** Options for {@link resolveConnection}: which connection, and where the config lives. */\nexport interface ResolveConnectionOptions {\n  /** Connection name; defaults to `defaultConnection`, else the sole connection, else `\"default\"`. */\n  name?: string;\n  /** Path to `better-schemic.config.ts` (else auto-discovered from `cwd`). */\n  config?: string;\n  /** Working directory to discover the config + resolve relative paths from. */\n  cwd?: string;\n  /** The resolver's typed args (its declared 2nd param) for a PARAMETERIZED connection. */\n  args?: unknown;\n}\n\n/**\n * A live resolution context for RUNTIME connects: `ctx.connections.<name>` lazily opens the sibling\n * via ITS entry's embedded client opener (so a resolver can query another connection to enumerate a\n * fleet), with CYCLE detection; everything opened during resolution is closed when it settles.\n */\nfunction makeRuntimeContext(config: BetterSchemicConfig, root: string) {\n  const opened = new Map<string, Promise<unknown>>();\n  const resolving = new Set<string>();\n\n  const open = async (name: string): Promise<unknown> => {\n    if (resolving.has(name)) {\n      throw new Error(\n        `cyclic connection resolution: \"${name}\" is already resolving (a resolver reached back into itself via ctx.connections)`,\n      );\n    }\n    const entry = config.connections[name];\n    if (!entry) throw new Error(`ctx.connections.${name}: no such connection`);\n    if (!entry.client) {\n      throw new Error(\n        `ctx.connections.${name}: the \"${entry.driver}\" connection factory predates runtime cross-connection access — update @better-schemic/${entry.driver}`,\n      );\n    }\n    resolving.add(name);\n    try {\n      const bases = await entry.resolve(context, undefined);\n      if (bases.length !== 1) {\n        throw new Error(\n          `ctx.connections.${name}: resolved to ${bases.length} configs — a sibling reached via ctx.connections must resolve to exactly one`,\n        );\n      }\n      const rc = resolveConnectionConfig(\n        config,\n        name,\n        bases[0],\n        entry.driver,\n        root,\n      );\n      return await entry.client(rc);\n    } finally {\n      resolving.delete(name);\n    }\n  };\n\n  const context: ResolveContext = {\n    env: process.env,\n    connections: new Proxy(\n      {},\n      {\n        get(_t, name: string) {\n          const openOnce = () => {\n            let client = opened.get(name);\n            if (!client) {\n              client = open(name);\n              opened.set(name, client);\n            }\n            return client;\n          };\n          // The handle is THENABLE to the sibling's FULL ORM client (typed in the chained form:\n          // `const main = await ctx.connections.main; main.select(...)`) and keeps a direct\n          // `.query` for the neutral/literal form. Do NOT stash the client past resolution — it is\n          // closed when resolution settles.\n          return {\n            query: async (sql: string, vars?: Record<string, unknown>) => {\n              const db = (await openOnce()) as {\n                query(sql: string, vars?: unknown): Promise<unknown>;\n              };\n              return db.query(sql, vars);\n            },\n            then: (\n              onOk?: (v: unknown) => unknown,\n              onErr?: (e: unknown) => unknown,\n            ) => openOnce().then(onOk, onErr),\n          };\n        },\n      },\n    ) as ResolveContext[\"connections\"],\n  };\n\n  const closeOpened = async () => {\n    for (const c of opened.values()) {\n      try {\n        await ((await c) as { close?: () => Promise<void> }).close?.();\n      } catch {\n        // best-effort cleanup of resolution-time siblings\n      }\n    }\n    opened.clear();\n  };\n\n  return { context, closeOpened, resolving };\n}\n\n/**\n * Resolve ONE named connection from the disk-discovered project config — the MANAGED path a driver's\n * standalone `connect(name?)` uses before `driver.connect(config)`. Single-config or a teaching\n * error (a bulk resolution must be arg-selected).\n */\nexport async function resolveConnection(\n  opts: ResolveConnectionOptions = {},\n): Promise<ResolvedConfig> {\n  const { config, root } = await loadProject({\n    config: opts.config,\n    cwd: opts.cwd,\n  });\n  return exactlyOne(\n    await resolveFromConfig(config, root, { name: opts.name, args: opts.args }),\n  );\n}\n\n/**\n * The shared single-name resolution over an IN-MEMORY config: pick the entry (named /\n * defaultConnection / sole / `\"default\"`), run the resolver with its typed `args`, and build one\n * {@link ResolvedConfig} per returned config, each with a display label (config `key` > the entry's\n * `label` hook > positional `name[i]`). Resolvers may query siblings via `ctx.connections` (lazy,\n * cycle-checked; opened siblings are closed when resolution settles). Used by both\n * {@link resolveConnection} (disk-discovered config) and {@link connectFromConfig} (`config.connect`).\n */\nexport async function resolveFromConfig(\n  config: BetterSchemicConfig,\n  root: string,\n  opts: { name?: string; args?: unknown } = {},\n): Promise<{\n  entry: AnyConnectionEntry;\n  name: string;\n  resolved: ResolvedConfig[];\n  labels: string[];\n}> {\n  const names = Object.keys(config.connections);\n  const name =\n    opts.name ??\n    config.defaultConnection ??\n    (names.length === 1 ? names[0] : \"default\");\n  const entry = config.connections[name];\n  if (!entry) {\n    throw new Error(\n      `connection \"${name}\" is not defined in the config (have: ${names.join(\", \") || \"none\"})`,\n    );\n  }\n\n  const rt = makeRuntimeContext(config, root);\n  rt.resolving.add(name); // the target itself is mid-resolution — a self-reference is a cycle\n  try {\n    const bases = await entry.resolve(rt.context, opts.args);\n    if (!bases.length) {\n      throw new Error(`connection \"${name}\" resolved to no config`);\n    }\n    const resolved = bases.map((b) =>\n      resolveConnectionConfig(config, name, b, entry.driver, root),\n    );\n    const labels = resolved.map(\n      (rc, i) => bases[i].key ?? entry.label?.(rc) ?? `${name}[${i}]`,\n    );\n    return { entry, name, resolved, labels };\n  } finally {\n    rt.resolving.delete(name);\n    await rt.closeOpened();\n  }\n}\n\n/** Single-config resolution or a TEACHING error — bulk (array) resolutions must be arg-selected. */\nfunction exactlyOne(r: {\n  name: string;\n  resolved: ResolvedConfig[];\n  labels: string[];\n}): ResolvedConfig {\n  if (r.resolved.length !== 1) {\n    throw new Error(\n      `connection \"${r.name}\" resolved to ${r.resolved.length} configs (${r.labels.join(\", \")}) — ` +\n        `a parameterized/bulk connection. Pass args selecting exactly one, e.g. betterSchemic.connect(\"${r.name}\", { ... }).`,\n    );\n  }\n  return r.resolved[0];\n}\n\n/**\n * The runtime behind `config.connect(name, args?)` (see `defineConfig`): resolve the entry from the\n * in-memory config and open its bound ORM client via the factory-embedded\n * {@link AnyConnectionEntry.client} opener. The static return type is the entry's own client type\n * (inferred per entry in `BetterSchemicProject`).\n */\nexport async function connectFromConfig(\n  config: BetterSchemicConfig,\n  name?: string,\n  args?: unknown,\n): Promise<unknown> {\n  const r = await resolveFromConfig(config, process.cwd(), { name, args });\n  const resolved = exactlyOne(r);\n  if (!r.entry.client) {\n    throw new Error(\n      `the \"${r.entry.driver}\" connection factory predates config.connect() — update @better-schemic/${r.entry.driver} to a version whose ${r.entry.driver}Connection embeds a client opener`,\n    );\n  }\n  return r.entry.client(resolved);\n}\n"],"mappings":"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","names":[]}

package/lib/client-HZF4ZWGO.js

@@ -0,0 +1,13 @@
+import {
+  asyncDisposable,
+  connectFromConfig,
+  resolveConnection,
+  resolveFromConfig
+} from "./chunk-RSGP7GVO.js";
+export {
+  asyncDisposable,
+  connectFromConfig,
+  resolveConnection,
+  resolveFromConfig
+};
+//# sourceMappingURL=client-HZF4ZWGO.js.map

package/lib/client-HZF4ZWGO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/lib/config-BYh7WA4P.d.ts

@@ -0,0 +1,259 @@
+import * as jiti from 'jiti';
+
+/**
+ * A resolved, per-CONNECTION config — the dialect-NEUTRAL shape every command operates on (one
+ * connection at a time). `params` are the driver-specific connection params (opaque to core; the
+ * driver's `connect` reads them). Built by resolving one entry of `config.connections`.
+ */
+interface ResolvedConfig {
+    /** Resolved connection name (e.g. `default`, or `tenants:abc` within a collection). */
+    connection: string;
+    /** The driver this connection uses (the package the CLI dynamically loads). */
+    driver: string;
+    /** Project root (the directory containing the config file). */
+    root: string;
+    /** Absolute schema path — a single `.ts` module, or a directory of them. */
+    schemaPath: string;
+    /** Whether `schemaPath` is a single file (vs a directory of schema modules). */
+    schemaIsFile: boolean;
+    /** Absolute migrations directory (per connection's schema). */
+    migrationsDir: string;
+    /** Absolute migration meta directory (the snapshot). */
+    metaDir: string;
+    /** Name of the table that records applied migrations. */
+    migrationsTable: string;
+    /** Driver-specific connection params (url/namespace/… or whatever the driver defines). Opaque to core. */
+    params: Record<string, unknown>;
+    /** Optional seed script (project-level). */
+    seed?: string;
+}
+/**
+ * A jiti instance for loading the project's TS/ESM modules. Caches are off so `--watch` re-reads
+ * edited schema files. (Bare deps like `@better-schemic/core` are native-imported, so registries stay shared.)
+ */
+declare function makeJiti(): jiti.Jiti;
+/** Find + load `better-schemic.ts` / `better-schemic.config.ts` (legacy `schemic.*` aliases included) into the dialect-neutral {@link BetterSchemicConfig}. */
+declare function loadProject(opts?: {
+    config?: string;
+    cwd?: string;
+}): Promise<{
+    config: BetterSchemicConfig;
+    root: string;
+}>;
+/**
+ * Build the {@link ResolvedConfig} for one connection of the project. `ctx` carries the lazy
+ * cross-connection proxy + CLI `--arg`s (the CLI provides the real one; a static connection ignores
+ * it). A resolver returning a COLLECTION yields one ResolvedConfig per keyed entry.
+ *
+ * NOTE (WIP — multi-connection): the full resolution engine (lazy proxy DAG, `--connection`/`--all`
+ * addressing, collection fan-out) lives in `@better-schemic/cli`; this builder handles a single resolved
+ * connection config. See docs/MULTI-CONNECTION.md.
+ */
+declare function resolveConnectionConfig(config: BetterSchemicConfig, connection: string, conn: ConnectionConfigBase, driver: string, root: string): ResolvedConfig;
+/**
+ * Load the project and resolve the DEFAULT connection to a {@link ResolvedConfig} — the single-
+ * connection convenience path. (Multi-connection addressing + resolver context are added by the CLI;
+ * here a static default connection is resolved with an empty context.)
+ */
+declare function loadConfig(opts?: {
+    config?: string;
+    cwd?: string;
+}): Promise<ResolvedConfig>;
+
+type MaybePromise<T> = T | Promise<T>;
+/** Minimal Standard Schema v1 surface — what a connection's `args` schema must expose. */
+interface StandardSchemaLike {
+    "~standard": {
+        validate(value: unknown): MaybePromise<{
+            value: unknown;
+        } | {
+            issues: readonly {
+                message: string;
+            }[];
+        }>;
+    };
+}
+/** The dialect-neutral fields the orchestration reads off every connection config. */
+interface ConnectionConfigBase {
+    /** Schema dir (the desired state + its migration files/snapshot). Shared dir = shared schema. */
+    schema: string;
+    /** Optional DISPLAY label for this config within a bulk (array) resolution — reporting/logs only. */
+    key?: string;
+    /** Migrations dir override; defaults relative to `schema`. */
+    migrations?: string;
+}
+/** A live, queryable handle to ANOTHER (already-resolved) connection, for use inside a resolver. */
+interface ResolvedConnectionHandle {
+    query<T = unknown>(sql: string, vars?: Record<string, unknown>): Promise<T[]>;
+}
+/**
+ * What a connection RESOLVER receives. `connections` is a LAZY proxy of the other connections —
+ * touching one resolves + connects it on demand (so the dependency graph falls out of access; cycles
+ * error). `args` are CLI `--arg k=v` values (so a resolver can yield a SUBSET without resolving all).
+ */
+interface ResolveContext {
+    connections: Record<string, ResolvedConnectionHandle>;
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * The opaque, branded output of a `<driver>Connection(...)` factory — the only thing `defineConfig`'s
+ * `connections` map accepts. Never hand-authored. `driver` is the package the CLI dynamically loads;
+ * `resolve` always normalizes to an ARRAY (a single connection -> one element, a collection -> many).
+ */
+interface ConnectionEntry<Client = unknown, Args = undefined> {
+    readonly __betterSchemic: "connection";
+    readonly driver: string;
+    resolve(ctx: ResolveContext, args?: Args): Promise<ConnectionConfigBase[]>;
+    /**
+     * Lazily open this connection's bound ORM CLIENT for a resolved config — embedded by the driver
+     * factory (with a lazy `import()` of its own client module, so authoring a config never pulls the
+     * engine). This is what powers the typed `config.connect(name)` on `defineConfig`'s return.
+     */
+    client?(config: ResolvedConfig): Promise<Client>;
+    /**
+     * Dialect-specific DISPLAY identity for a resolved config (bulk reporting / errors / logs) —
+     * e.g. surreal `ns/db`. Precedence: config `key` > this hook > positional `name[i]`.
+     */
+    label?(config: ResolvedConfig): string;
+    /** PHANTOM (never assigned) — anchors `Client`/`Args` so `config.connect` can infer them per entry. */
+    readonly __types?: {
+        client: Client;
+        args: Args;
+    };
+}
+/** Cross-driver erasure of the entry generics (like `AnyField`) — the shape neutral maps hold. */
+type AnyConnectionEntry = ConnectionEntry<any, any>;
+/** A connection factory's input: a static config, or a resolver yielding one config or a keyed collection. */
+type ConnectionInput<C extends ConnectionConfigBase, Args = undefined> = C | ((ctx: ResolveContext, args: Args) => MaybePromise<C | C[]>);
+/**
+ * Build a {@link ConnectionEntry} from a driver tag + a static config or resolver — the primitive each
+ * driver package wraps in its typed `<driver>Connection(...)` factory (which fixes `C` to the driver's
+ * own connection shape and overloads the array form to require `key`). Returns a branded entry whose
+ * `resolve` always yields an array. `extras` carries the factory-embedded client opener (for
+ * `config.connect`) and the optional args schema.
+ */
+declare function connectionEntry<C extends ConnectionConfigBase, Client = unknown, Args = undefined>(driver: string, input: ConnectionInput<C, Args>, extras?: {
+    client?: (config: ResolvedConfig) => Promise<Client>;
+    label?: (config: ResolvedConfig) => string;
+}): ConnectionEntry<Client, Args>;
+/** Type guard: is a `connections` map value a real factory output (vs a stray object)? */
+declare function isConnectionEntry(v: unknown): v is ConnectionEntry;
+
+/**
+ * Configuration for the `better-schemic` CLI — author it in `better-schemic.config.ts`
+ * (`schemic.config.ts` still loads as a legacy alias).
+ *
+ * A project declares one or more named CONNECTIONS, each built by a per-driver factory
+ * (`<driver>Connection(...)` exported from `@better-schemic/<driver>/connection`). Connection values are EXPLICIT —
+ * there is no env-var magic; read env yourself where you want it (`url: process.env.MY_URL`).
+ * See `@better-schemic/core` docs/MULTI-CONNECTION.md.
+ *
+ * ```ts
+ * import { defineConfig } from "@better-schemic/core/config";
+ * import { surrealConnection } from "@better-schemic/surrealdb/connection";
+ *
+ * export default defineConfig({
+ *   connections: {
+ *     default: surrealConnection({
+ *       schema: "./database/schema",
+ *       url: "ws://localhost:8000",
+ *       namespace: "app",
+ *       database: "app",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * For MULTIPLE databases (multi-tenant / heterogeneous / DB-per-user), add more named connections;
+ * a connection may be a resolver (incl. an array → a collection). See docs/MULTI-CONNECTION.md.
+ *
+ * NOTE: this file is dialect-NEUTRAL. Driver-specific connection shapes (SurrealDB's
+ * url/namespace/authLevel, its check-engine options, …) live in the driver package's
+ * `<driver>Connection` factory, not here.
+ */
+
+interface BetterSchemicConfig {
+    /** Named database connections — each produced by a per-driver `<driver>Connection(...)` factory. */
+    connections: Record<string, AnyConnectionEntry>;
+    /**
+     * With more than one connection, the connection a bare command targets (must name a single static
+     * connection). Absent + ambiguous → a live command errors asking for `--connection`.
+     */
+    defaultConnection?: string;
+    /** Table that records applied migrations (per connection). Default `_migrations`. */
+    migrationsTable?: string;
+    /** Optional seed script run by `better-schemic seed`. */
+    seed?: string;
+}
+/**
+ * Legacy alias — prefer {@link BetterSchemicConfig}.
+ */
+type SchemicConfig = BetterSchemicConfig;
+/** The bound ORM client type a {@link ConnectionEntry} opens (inferred from the driver factory). */
+type EntryClient<E> = E extends ConnectionEntry<infer Client, any> ? Client : never;
+/** The typed resolver `args` a {@link ConnectionEntry} accepts (from its `args` schema). */
+type EntryArgs<E> = E extends ConnectionEntry<any, infer Args> ? Args : never;
+/**
+ * What {@link defineConfig} ADDS to your config: the config IS the app's typed entry point to its
+ * databases. `connect(name, args?)` autocompletes your connection names, types `args` per connection
+ * (the resolver's declared 2nd param — absent for a static/argless connection), and returns that
+ * entry's own client type (a heterogeneous-driver project types per-connection). A PARAMETERIZED
+ * connection whose resolver returns an ARRAY is bulk-only: `connect` throws a teaching error — pass
+ * `args` selecting ONE config. The client is disposable: `await using db = await betterSchemic.connect()`.
+ */
+interface BetterSchemicProject<Conns extends Record<string, AnyConnectionEntry>> {
+    connect<N extends keyof Conns & string>(name?: N, args?: EntryArgs<Conns[N]>): Promise<EntryClient<Conns[N]>>;
+}
+/**
+ * Type + enrich a Better-schemic config: returns the config with a typed `connect()` attached — the config
+ * itself is the factory. The loader accepts a `default` export OR the NAMED `betterSchemic` export
+ * (`schemic` still loads as a legacy alias); the scaffolded form is the named one
+ * (deterministic auto-import, no file rename needed):
+ *
+ * ```ts
+ * // better-schemic.config.ts (better-schemic.ts, schemic.config.ts, and schemic.ts also load)
+ * export const betterSchemic = defineConfig({ connections: { ... } });
+ * // app code: import { betterSchemic } from "./better-schemic.config";  →  await using db = await betterSchemic.connect();
+ * ```
+ */
+/**
+ * A resolver's `ctx` in the CHAINED form: `connections` is typed with the ACCUMULATED prior
+ * connections — each handle is thenable to that entry's FULL ORM client (`const main = await
+ * ctx.connections.main; main.select(...)`) and keeps a direct `.query`. Order = visibility: a
+ * resolver only sees connections declared BEFORE it (structural cycle prevention). Do not stash a
+ * sibling client — it is closed when resolution settles.
+ */
+type ChainCtx<Conns extends Record<string, AnyConnectionEntry>> = Omit<ResolveContext, "connections"> & {
+    connections: {
+        [K in keyof Conns]: PromiseLike<EntryClient<Conns[K]>> & ResolvedConnectionHandle;
+    };
+};
+/** The shape a driver connection factory must have to be used as the `.connection()` driver marker. */
+interface ChainableDriverFactory<C extends ConnectionConfigBase, Client> {
+    (input: ConnectionInput<C, any>): ConnectionEntry<Client, any>;
+}
+/**
+ * The CHAINED config builder (`defineConfig().connection(...)`): each `.connection(name, factory,
+ * input)` uses the driver FACTORY ITSELF as the driver marker and contextually types the resolver's
+ * `ctx.connections` with everything declared so far. The literal `defineConfig({ connections })`
+ * form remains for static maps.
+ */
+interface ChainedConfig<Conns extends Record<string, AnyConnectionEntry>> extends BetterSchemicProject<Conns> {
+    connections: Conns;
+    defaultConnection?: string;
+    migrationsTable?: string;
+    seed?: string;
+    connection<N extends string, C extends ConnectionConfigBase, Client, Args = undefined>(name: N, factory: ChainableDriverFactory<C, Client>, input: C | ((ctx: ChainCtx<Conns>, args: Args) => C | C[] | Promise<C | C[]>)): ChainedConfig<Conns & {
+        [K in N]: ConnectionEntry<Client, Args>;
+    }>;
+}
+/** Start a CHAINED config: `defineConfig().connection("main", surrealConnection, {...})`. */
+declare function defineConfig(base?: Omit<BetterSchemicConfig, "connections">): ChainedConfig<Record<never, never>>;
+/** Type + enrich a literal config — returns it with the typed `connect()` attached. */
+declare function defineConfig<const C extends BetterSchemicConfig>(config: C): C & BetterSchemicProject<C["connections"]>;
+/**
+ * Legacy alias — prefer {@link BetterSchemicProject}.
+ */
+type SchemicProject<Conns extends Record<string, AnyConnectionEntry>> = BetterSchemicProject<Conns>;
+
+export { type AnyConnectionEntry as A, type BetterSchemicConfig as B, type ChainCtx as C, type EntryArgs as E, type ResolvedConfig as R, type SchemicConfig as S, type BetterSchemicProject as a, type ChainableDriverFactory as b, type ChainedConfig as c, type ConnectionConfigBase as d, type ConnectionEntry as e, type ConnectionInput as f, type EntryClient as g, type ResolveContext as h, type ResolvedConnectionHandle as i, type SchemicProject as j, type StandardSchemaLike as k, connectionEntry as l, isConnectionEntry as m, loadConfig as n, loadProject as o, makeJiti as p, defineConfig as q, resolveConnectionConfig as r };

package/lib/config.d.ts

@@ -0,0 +1,2 @@
+export { B as BetterSchemicConfig, a as BetterSchemicProject, C as ChainCtx, b as ChainableDriverFactory, c as ChainedConfig, E as EntryArgs, g as EntryClient, S as SchemicConfig, j as SchemicProject, q as defineConfig } from './config-BYh7WA4P.js';
+import 'jiti';

package/lib/config.js

@@ -0,0 +1,27 @@
+// src/config.ts
+function defineConfig(config) {
+  const isLiteral = !!config && "connections" in config;
+  const base = isLiteral ? config : {
+    ...config,
+    connections: {}
+  };
+  const withApi = (cfg) => ({
+    ...cfg,
+    async connect(name, args) {
+      const { connectFromConfig } = await import("./client-HZF4ZWGO.js");
+      return connectFromConfig(cfg, name, args);
+    },
+    connection(name, factory, input) {
+      const entry = factory(input);
+      return withApi({
+        ...cfg,
+        connections: { ...cfg.connections, [name]: entry }
+      });
+    }
+  });
+  return withApi(base);
+}
+export {
+  defineConfig
+};
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["/**\n * Configuration for the `better-schemic` CLI — author it in `better-schemic.config.ts`\n * (`schemic.config.ts` still loads as a legacy alias).\n *\n * A project declares one or more named CONNECTIONS, each built by a per-driver factory\n * (`<driver>Connection(...)` exported from `@better-schemic/<driver>/connection`). Connection values are EXPLICIT —\n * there is no env-var magic; read env yourself where you want it (`url: process.env.MY_URL`).\n * See `@better-schemic/core` docs/MULTI-CONNECTION.md.\n *\n * ```ts\n * import { defineConfig } from \"@better-schemic/core/config\";\n * import { surrealConnection } from \"@better-schemic/surrealdb/connection\";\n *\n * export default defineConfig({\n *   connections: {\n *     default: surrealConnection({\n *       schema: \"./database/schema\",\n *       url: \"ws://localhost:8000\",\n *       namespace: \"app\",\n *       database: \"app\",\n *     }),\n *   },\n * });\n * ```\n *\n * For MULTIPLE databases (multi-tenant / heterogeneous / DB-per-user), add more named connections;\n * a connection may be a resolver (incl. an array → a collection). See docs/MULTI-CONNECTION.md.\n *\n * NOTE: this file is dialect-NEUTRAL. Driver-specific connection shapes (SurrealDB's\n * url/namespace/authLevel, its check-engine options, …) live in the driver package's\n * `<driver>Connection` factory, not here.\n */\nimport type {\n  AnyConnectionEntry,\n  ConnectionConfigBase,\n  ConnectionEntry,\n  ConnectionInput,\n  ResolveContext,\n  ResolvedConnectionHandle,\n} from \"./connection\";\n\nexport interface BetterSchemicConfig {\n  /** Named database connections — each produced by a per-driver `<driver>Connection(...)` factory. */\n  connections: Record<string, AnyConnectionEntry>;\n  /**\n   * With more than one connection, the connection a bare command targets (must name a single static\n   * connection). Absent + ambiguous → a live command errors asking for `--connection`.\n   */\n  defaultConnection?: string;\n  /** Table that records applied migrations (per connection). Default `_migrations`. */\n  migrationsTable?: string;\n  /** Optional seed script run by `better-schemic seed`. */\n  seed?: string;\n}\n\n/**\n * Legacy alias — prefer {@link BetterSchemicConfig}.\n */\nexport type SchemicConfig = BetterSchemicConfig;\n\n/** The bound ORM client type a {@link ConnectionEntry} opens (inferred from the driver factory). */\n// biome-ignore lint/suspicious/noExplicitAny: matching the erased Args slot.\nexport type EntryClient<E> =\n  E extends ConnectionEntry<infer Client, any> ? Client : never;\n/** The typed resolver `args` a {@link ConnectionEntry} accepts (from its `args` schema). */\n// biome-ignore lint/suspicious/noExplicitAny: matching the erased Client slot.\nexport type EntryArgs<E> =\n  E extends ConnectionEntry<any, infer Args> ? Args : never;\n\n/**\n * What {@link defineConfig} ADDS to your config: the config IS the app's typed entry point to its\n * databases. `connect(name, args?)` autocompletes your connection names, types `args` per connection\n * (the resolver's declared 2nd param — absent for a static/argless connection), and returns that\n * entry's own client type (a heterogeneous-driver project types per-connection). A PARAMETERIZED\n * connection whose resolver returns an ARRAY is bulk-only: `connect` throws a teaching error — pass\n * `args` selecting ONE config. The client is disposable: `await using db = await betterSchemic.connect()`.\n */\nexport interface BetterSchemicProject<\n  Conns extends Record<string, AnyConnectionEntry>,\n> {\n  connect<N extends keyof Conns & string>(\n    name?: N,\n    args?: EntryArgs<Conns[N]>,\n  ): Promise<EntryClient<Conns[N]>>;\n}\n\n/**\n * Type + enrich a Better-schemic config: returns the config with a typed `connect()` attached — the config\n * itself is the factory. The loader accepts a `default` export OR the NAMED `betterSchemic` export\n * (`schemic` still loads as a legacy alias); the scaffolded form is the named one\n * (deterministic auto-import, no file rename needed):\n *\n * ```ts\n * // better-schemic.config.ts (better-schemic.ts, schemic.config.ts, and schemic.ts also load)\n * export const betterSchemic = defineConfig({ connections: { ... } });\n * // app code: import { betterSchemic } from \"./better-schemic.config\";  →  await using db = await betterSchemic.connect();\n * ```\n */\n/**\n * A resolver's `ctx` in the CHAINED form: `connections` is typed with the ACCUMULATED prior\n * connections — each handle is thenable to that entry's FULL ORM client (`const main = await\n * ctx.connections.main; main.select(...)`) and keeps a direct `.query`. Order = visibility: a\n * resolver only sees connections declared BEFORE it (structural cycle prevention). Do not stash a\n * sibling client — it is closed when resolution settles.\n */\nexport type ChainCtx<Conns extends Record<string, AnyConnectionEntry>> = Omit<\n  ResolveContext,\n  \"connections\"\n> & {\n  connections: {\n    [K in keyof Conns]: PromiseLike<EntryClient<Conns[K]>> &\n      ResolvedConnectionHandle;\n  };\n};\n\n/** The shape a driver connection factory must have to be used as the `.connection()` driver marker. */\nexport interface ChainableDriverFactory<\n  C extends ConnectionConfigBase,\n  Client,\n> {\n  // biome-ignore lint/suspicious/noExplicitAny: the chain re-types input/args itself (variance cast).\n  (input: ConnectionInput<C, any>): ConnectionEntry<Client, any>;\n}\n\n/**\n * The CHAINED config builder (`defineConfig().connection(...)`): each `.connection(name, factory,\n * input)` uses the driver FACTORY ITSELF as the driver marker and contextually types the resolver's\n * `ctx.connections` with everything declared so far. The literal `defineConfig({ connections })`\n * form remains for static maps.\n */\nexport interface ChainedConfig<Conns extends Record<string, AnyConnectionEntry>>\n  extends BetterSchemicProject<Conns> {\n  connections: Conns;\n  defaultConnection?: string;\n  migrationsTable?: string;\n  seed?: string;\n  connection<\n    N extends string,\n    C extends ConnectionConfigBase,\n    Client,\n    Args = undefined,\n  >(\n    name: N,\n    factory: ChainableDriverFactory<C, Client>,\n    input:\n      | C\n      | ((ctx: ChainCtx<Conns>, args: Args) => C | C[] | Promise<C | C[]>),\n  ): ChainedConfig<Conns & { [K in N]: ConnectionEntry<Client, Args> }>;\n}\n\n/** Start a CHAINED config: `defineConfig().connection(\"main\", surrealConnection, {...})`. */\nexport function defineConfig(\n  base?: Omit<BetterSchemicConfig, \"connections\">,\n): ChainedConfig<Record<never, never>>;\n/** Type + enrich a literal config — returns it with the typed `connect()` attached. */\nexport function defineConfig<const C extends BetterSchemicConfig>(\n  config: C,\n): C & BetterSchemicProject<C[\"connections\"]>;\nexport function defineConfig(\n  config?: BetterSchemicConfig | Omit<BetterSchemicConfig, \"connections\">,\n): unknown {\n  const isLiteral = !!config && \"connections\" in config;\n  const base: BetterSchemicConfig = isLiteral\n    ? (config as BetterSchemicConfig)\n    : {\n        ...(config as Omit<BetterSchemicConfig, \"connections\"> | undefined),\n        connections: {},\n      };\n\n  const withApi = (cfg: BetterSchemicConfig): unknown => ({\n    ...cfg,\n    async connect(name?: string, args?: unknown) {\n      // Lazy: authoring/loading a config stays light; the client machinery loads only when used.\n      const { connectFromConfig } = await import(\"./client\");\n      return connectFromConfig(cfg, name, args);\n    },\n    connection(\n      name: string,\n      factory: (input: unknown) => AnyConnectionEntry,\n      input: unknown,\n    ) {\n      // The factory IS the driver marker: it stamps the driver tag, config type, and client opener.\n      // The chain re-types ctx/args itself, so the factory is called through a variance cast.\n      const entry = factory(input as never);\n      return withApi({\n        ...cfg,\n        connections: { ...cfg.connections, [name]: entry },\n      });\n    },\n  });\n\n  return withApi(base);\n}\n\n/**\n * Legacy alias — prefer {@link BetterSchemicProject}.\n */\nexport type SchemicProject<Conns extends Record<string, AnyConnectionEntry>> =\n  BetterSchemicProject<Conns>;\n"],"mappings":";AA8JO,SAAS,aACd,QACS;AACT,QAAM,YAAY,CAAC,CAAC,UAAU,iBAAiB;AAC/C,QAAM,OAA4B,YAC7B,SACD;AAAA,IACE,GAAI;AAAA,IACJ,aAAa,CAAC;AAAA,EAChB;AAEJ,QAAM,UAAU,CAAC,SAAuC;AAAA,IACtD,GAAG;AAAA,IACH,MAAM,QAAQ,MAAe,MAAgB;AAE3C,YAAM,EAAE,kBAAkB,IAAI,MAAM,OAAO,sBAAU;AACrD,aAAO,kBAAkB,KAAK,MAAM,IAAI;AAAA,IAC1C;AAAA,IACA,WACE,MACA,SACA,OACA;AAGA,YAAM,QAAQ,QAAQ,KAAc;AACpC,aAAO,QAAQ;AAAA,QACb,GAAG;AAAA,QACH,aAAa,EAAE,GAAG,IAAI,aAAa,CAAC,IAAI,GAAG,MAAM;AAAA,MACnD,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO,QAAQ,IAAI;AACrB;","names":[]}