@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/core/database.js

@@ -0,0 +1,136 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var database_exports = {};
+__export(database_exports, {
+  connectDatabase: () => connectDatabase,
+  createDatabase: () => createDatabase,
+  createMemoryDatabase: () => createMemoryDatabase,
+  openDatabase: () => openDatabase,
+  resolveStorageAdapter: () => import_resolver2.resolveStorageAdapter
+});
+module.exports = __toCommonJS(database_exports);
+var import_contracts = require("./contracts/index.js");
+var import_resolver = require("./resolver.js");
+var import_postgresTarget = require("../shared/postgresTarget.js");
+var import_segment = require("../shared/segment.js");
+var import_resolver2 = require("./resolver.js");
+const configuredPostgresOptions = (options) => {
+  const named = [];
+  if (Object.prototype.hasOwnProperty.call(options, "url"))
+    named.push("url");
+  if (options.postgres !== void 0)
+    named.push("postgres");
+  return named;
+};
+const isCapacitorNative = () => {
+  const scope = globalThis;
+  const capacitor = scope.window?.Capacitor;
+  return Boolean(capacitor?.isNativePlatform?.());
+};
+async function createDatabase(options = {}) {
+  const resolverOptions = {};
+  const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+  const isNode = typeof process !== "undefined" && !!process.versions?.node;
+  const isDeno = typeof globalThis.Deno !== "undefined";
+  if (options.url || options.postgres) {
+    resolverOptions.postgres = {
+      ...options.postgres,
+      connectionString: options.postgres?.connectionString || options.url || void 0
+    };
+  }
+  if (options.file) {
+    resolverOptions.filePath = options.file;
+  }
+  if (options.mobile) {
+    resolverOptions.capacitor = options.mobile;
+  }
+  if (options.indexedDb) {
+    resolverOptions.indexedDb = options.indexedDb;
+  }
+  if (options.segment !== void 0) {
+    resolverOptions.segment = options.segment;
+  }
+  if (options.type) {
+    const typeMap = {
+      postgres: "postgres",
+      sqlite: "better-sqlite3",
+      browser: "sqljs",
+      mobile: "capacitor",
+      memory: "better-sqlite3"
+    };
+    resolverOptions.priority = [typeMap[options.type]];
+    if (options.type === "memory") {
+      resolverOptions.filePath = ":memory:";
+    }
+  }
+  if (options.priority) {
+    resolverOptions.priority = options.priority;
+  }
+  if (options.strict) {
+    resolverOptions.strict = true;
+  }
+  if (options.foreignKeys !== void 0) {
+    resolverOptions.openOptions = { ...resolverOptions.openOptions, foreignKeys: options.foreignKeys };
+  }
+  if (options.logger) {
+    resolverOptions.logger = options.logger;
+  }
+  if (!resolverOptions.priority || resolverOptions.priority.length === 0) {
+    if (isBrowser && options.file !== void 0 && (0, import_segment.namesInMemoryDatabase)(options.file)) {
+      resolverOptions.priority = ["sqljs"];
+    } else if (isBrowser && isCapacitorNative()) {
+      resolverOptions.priority = ["capacitor", "indexeddb", "sqljs"];
+    } else if (isBrowser) {
+      resolverOptions.priority = ["indexeddb", "sqljs"];
+    } else if (isDeno) {
+      resolverOptions.priority = ["sqljs"];
+    } else if (isNode && (0, import_postgresTarget.namesPostgresServer)(resolverOptions.postgres)) {
+      resolverOptions.priority = ["postgres"];
+    } else if (isNode && options.strict && !options.file && configuredPostgresOptions(options).length > 0) {
+      const named = configuredPostgresOptions(options);
+      throw new import_contracts.StorageResolutionError(`[StorageAdapter] Strict resolution: the ${named.join(" and ")} option${named.length > 1 ? "s name" : " names"} no server. Give a connection string, or a host, database or user, or pass file to open a local database.`);
+    } else if (isNode) {
+      resolverOptions.priority = ["better-sqlite3", "sqljs"];
+    } else {
+      throw new Error("[StorageAdapter] Unsupported runtime environment for automatic adapter selection.");
+    }
+  }
+  const adapter = await (0, import_resolver.resolveStorageAdapter)(resolverOptions);
+  await adapter.open(resolverOptions.openOptions);
+  return adapter;
+}
+async function connectDatabase(config) {
+  if (typeof config === "string") {
+    return createDatabase({ url: config });
+  }
+  return createDatabase({ postgres: config });
+}
+async function openDatabase(filePath) {
+  return createDatabase({ file: filePath });
+}
+async function createMemoryDatabase() {
+  return openDatabase(":memory:");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  connectDatabase,
+  createDatabase,
+  createMemoryDatabase,
+  openDatabase,
+  resolveStorageAdapter
+});

package/dist/cjs/core/portable.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The adapter-free entry, `@framers/sql-storage-adapter/core`: the contracts and errors, the SQL dialects, full-text
+ * search, codecs and exporters, `createStorageFeatures`, the schema-migration runner, `isUniqueViolation` and the
+ * logger. It imports no adapter, so a server that takes its adapter from a per-adapter entry
+ * (`@framers/sql-storage-adapter/postgres`) bundles neither sql.js nor the S3 client.
+ *
+ * @module
+ */
+export * from '../types/index.js';
+export { SqliteDialect } from '../dialects/SqliteDialect.js';
+export { PostgresDialect } from '../dialects/PostgresDialect.js';
+export { SqliteFts5 } from '../fts/SqliteFts5.js';
+export { PostgresFts } from '../fts/PostgresFts.js';
+export { NodeBlobCodec } from '../codecs/NodeBlobCodec.js';
+export { BrowserBlobCodec } from '../codecs/BrowserBlobCodec.js';
+export { SqliteFileExporter } from '../exporters/SqliteFileExporter.js';
+export { PostgresExporter } from '../exporters/PostgresExporter.js';
+export { createStorageFeatures } from './contracts/features.js';
+export { isUniqueViolation } from '../shared/errors.js';
+export { setStorageLogger, getStorageLogger, type StorageLogger } from '../shared/logger.js';
+export * from '../features/migrations/schemaMigrations.js';
+export * from '../shared/parameterUtils.js';
+//# sourceMappingURL=portable.d.ts.map

package/dist/cjs/core/portable.js

@@ -0,0 +1,66 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var portable_exports = {};
+__export(portable_exports, {
+  BrowserBlobCodec: () => import_BrowserBlobCodec.BrowserBlobCodec,
+  NodeBlobCodec: () => import_NodeBlobCodec.NodeBlobCodec,
+  PostgresDialect: () => import_PostgresDialect.PostgresDialect,
+  PostgresExporter: () => import_PostgresExporter.PostgresExporter,
+  PostgresFts: () => import_PostgresFts.PostgresFts,
+  SqliteDialect: () => import_SqliteDialect.SqliteDialect,
+  SqliteFileExporter: () => import_SqliteFileExporter.SqliteFileExporter,
+  SqliteFts5: () => import_SqliteFts5.SqliteFts5,
+  createStorageFeatures: () => import_features.createStorageFeatures,
+  getStorageLogger: () => import_logger.getStorageLogger,
+  isUniqueViolation: () => import_errors.isUniqueViolation,
+  setStorageLogger: () => import_logger.setStorageLogger
+});
+module.exports = __toCommonJS(portable_exports);
+__reExport(portable_exports, require("../types/index.js"), module.exports);
+var import_SqliteDialect = require("../dialects/SqliteDialect.js");
+var import_PostgresDialect = require("../dialects/PostgresDialect.js");
+var import_SqliteFts5 = require("../fts/SqliteFts5.js");
+var import_PostgresFts = require("../fts/PostgresFts.js");
+var import_NodeBlobCodec = require("../codecs/NodeBlobCodec.js");
+var import_BrowserBlobCodec = require("../codecs/BrowserBlobCodec.js");
+var import_SqliteFileExporter = require("../exporters/SqliteFileExporter.js");
+var import_PostgresExporter = require("../exporters/PostgresExporter.js");
+var import_features = require("./contracts/features.js");
+var import_errors = require("../shared/errors.js");
+var import_logger = require("../shared/logger.js");
+__reExport(portable_exports, require("../features/migrations/schemaMigrations.js"), module.exports);
+__reExport(portable_exports, require("../shared/parameterUtils.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrowserBlobCodec,
+  NodeBlobCodec,
+  PostgresDialect,
+  PostgresExporter,
+  PostgresFts,
+  SqliteDialect,
+  SqliteFileExporter,
+  SqliteFts5,
+  createStorageFeatures,
+  getStorageLogger,
+  isUniqueViolation,
+  setStorageLogger,
+  ...require("../types/index.js"),
+  ...require("../features/migrations/schemaMigrations.js"),
+  ...require("../shared/parameterUtils.js")
+});

package/dist/cjs/core/resolver.d.ts

@@ -0,0 +1,77 @@
+import type { StorageAdapter, StorageOpenOptions } from './contracts/index.js';
+import type { AdapterKind } from './contracts/context.js';
+import { type CapacitorAdapterOptions } from '../adapters/capacitorSqliteAdapter.js';
+import { type PostgresAdapterOptions } from '../adapters/postgresAdapter.js';
+import { type IndexedDbAdapterOptions } from '../adapters/indexedDbAdapter.js';
+import { type StorageLogger } from '../shared/logger.js';
+export type { AdapterKind } from './contracts/context.js';
+export interface StorageResolutionOptions {
+    /** Absolute path for sqlite file (used by better-sqlite3/sql.js when persistence is desired). */
+    filePath?: string;
+    /**
+     * Explicit adapter priority override. The resolver builds `postgres`,
+     * `better-sqlite3`, `capacitor`, `indexeddb` and `sqljs`; `memory` builds
+     * sql.js, as `sqljs` does. Any other kind (`electron-main`,
+     * `electron-renderer`, `supabase`, or an unknown name) fails as a candidate
+     * with an error that names it, and the resolver goes on to the next one.
+     */
+    priority?: AdapterKind[];
+    /** Options passed to the Capacitor adapter. */
+    capacitor?: CapacitorAdapterOptions;
+    /**
+     * Options passed to the Postgres adapter, all of them: a connection string,
+     * or host, port, database, user and password, and the pool, SSL and timeout
+     * settings. Without a connection string or a host, database or user here,
+     * the connection string comes from DATABASE_URL.
+     */
+    postgres?: PostgresAdapterOptions;
+    /** Options passed to the IndexedDB adapter (browser persistence), all of them. */
+    indexedDb?: IndexedDbAdapterOptions;
+    /** Options forwarded to adapter.open. */
+    openOptions?: StorageOpenOptions;
+    /** Suppress fallback chain logs (adapter not-found warnings). Default: false. */
+    quiet?: boolean;
+    /**
+     * The logger for this call's resolver lines (pino's fits). Default: the one
+     * `setStorageLogger()` set, else the console.
+     */
+    logger?: StorageLogger;
+    /**
+     * Strict resolution, for servers: only the database the options name opens.
+     * Default: false.
+     *
+     * - The postgres candidate is the last one tried. When it fails to open,
+     *   resolution throws a `StorageResolutionError` instead of trying a local
+     *   SQLite database, whatever `priority` lists after it.
+     * - A Postgres server named by `postgres` or `DATABASE_URL`, with no
+     *   `priority`, makes `['postgres']` the whole list.
+     * - An explicit `filePath` outranks `DATABASE_URL`: with a `filePath` and no
+     *   `postgres` options that name a server, `DATABASE_URL` is not read.
+     * - `postgres` options that name no server, with no `DATABASE_URL` to fill
+     *   in and no `filePath`, fail instead of opening the local default.
+     *
+     * Without `strict`, a postgres candidate that fails falls through to the
+     * next candidate, and `DATABASE_URL` puts Postgres first even when a
+     * `filePath` is given.
+     */
+    strict?: boolean;
+    /**
+     * Keeps the resolved adapter's tables apart from other users of the same
+     * database: on PostgreSQL a schema of the segment's name, on better-sqlite3
+     * and sql.js a file with the segment in its name (`app.sqlite3` becomes
+     * `app-agentos.sqlite3`), on IndexedDB and Capacitor a database name with
+     * the segment appended (`app-db-agentos`). Lower-case letters, digits and
+     * underscores; not `public`, `information_schema` or a name beginning with
+     * `pg_`. A name that cannot be a segment is refused before any adapter is
+     * tried, and so is a segment with `postgres.pool`, which the Postgres
+     * adapter cannot start in the segment. Takes the place of a `segment` in
+     * `postgres`, `indexedDb` or `capacitor`.
+     */
+    segment?: string;
+}
+/**
+ * Resolves the most appropriate storage adapter for the current runtime.
+ * Tries candidates in the supplied priority order and falls back when one fails.
+ */
+export declare const resolveStorageAdapter: (options?: StorageResolutionOptions) => Promise<StorageAdapter>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/cjs/core/resolver.js

@@ -0,0 +1,235 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var resolver_exports = {};
+__export(resolver_exports, {
+  resolveStorageAdapter: () => resolveStorageAdapter
+});
+module.exports = __toCommonJS(resolver_exports);
+var import_contracts = require("./contracts/index.js");
+var import_betterSqliteAdapter = require("../adapters/betterSqliteAdapter.js");
+var import_sqlJsAdapter = require("../adapters/sqlJsAdapter.js");
+var import_capacitorSqliteAdapter = require("../adapters/capacitorSqliteAdapter.js");
+var import_postgresAdapter = require("../adapters/postgresAdapter.js");
+var import_indexedDbAdapter = require("../adapters/indexedDbAdapter.js");
+var import_postgresTarget = require("../shared/postgresTarget.js");
+var import_segment = require("../shared/segment.js");
+var import_logger = require("../shared/logger.js");
+const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+const isNode = typeof process !== "undefined" && !!process.versions?.node;
+const joinPath = async (parts) => {
+  if (isBrowser) {
+    return parts.join("/");
+  }
+  if (isNode) {
+    try {
+      const path = await Promise.resolve().then(() => __toESM(require("path")));
+      return path.join(...parts);
+    } catch {
+      return parts.join("/");
+    }
+  }
+  return parts.join("/");
+};
+const getEnv = (key) => {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[key];
+  }
+  return void 0;
+};
+const getCwd = () => {
+  if (isNode && typeof process !== "undefined" && process.cwd) {
+    return process.cwd();
+  }
+  return "/";
+};
+const isCapacitorRuntime = () => {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  const maybeCapacitor = window.Capacitor;
+  return Boolean(maybeCapacitor?.isNativePlatform?.());
+};
+const isElectronMain = () => {
+  return typeof process !== "undefined" && Boolean(process.versions?.electron) && process.type === "browser";
+};
+const isElectronRenderer = () => {
+  return typeof window !== "undefined" && typeof process !== "undefined" && Boolean(process.versions?.electron) && process.type === "renderer";
+};
+const unsupportedKind = (kind) => {
+  switch (kind) {
+    case "electron-main":
+      return new Error(`The resolver cannot build adapter kind "${kind}". Create it with createElectronMainAdapter from '@framers/sql-storage-adapter/electron'.`);
+    case "electron-renderer":
+      return new Error(`The resolver cannot build adapter kind "${kind}". Create it with createElectronRendererAdapter from '@framers/sql-storage-adapter/electron'.`);
+    case "supabase":
+      return new Error(`The resolver cannot build adapter kind "${kind}". Use kind "postgres" with the Supabase connection string, or create a SupabaseAdapter.`);
+    default:
+      return new Error(`Unknown adapter kind "${kind}". The resolver builds postgres, better-sqlite3, capacitor, indexeddb, sqljs and memory.`);
+  }
+};
+const resolveStorageAdapter = async (options = {}) => {
+  const segment = options.segment === void 0 ? void 0 : (0, import_segment.validateSegment)(options.segment);
+  if ((segment ?? options.postgres?.segment) !== void 0 && options.postgres?.pool) {
+    throw new Error("A segment cannot run on a PostgreSQL pool of the caller's (postgres.pool): the segment's search_path is set when each connection of the pool starts, and the adapter does not start the connections of a pool it did not make. Give the connection settings and the segment instead of the pool.");
+  }
+  const segmentFor = (own) => {
+    const chosen = segment ?? own;
+    return chosen === void 0 ? {} : { segment: chosen };
+  };
+  const envOverride = getEnv("STORAGE_ADAPTER");
+  const log = options.logger ?? (0, import_logger.getStorageLogger)();
+  const strict = options.strict === true;
+  const postgresOptions = options.postgres;
+  const explicitConnection = postgresOptions?.connectionString;
+  const fileOutranksEnv = strict && (0, import_postgresTarget.isNonEmpty)(options.filePath);
+  const postgresConnection = (0, import_postgresTarget.isNonEmpty)(explicitConnection) ? explicitConnection : (0, import_postgresTarget.namesPostgresServer)(postgresOptions) || fileOutranksEnv ? void 0 : getEnv("DATABASE_URL") || void 0;
+  const postgresTarget = (0, import_postgresTarget.isNonEmpty)(postgresConnection) || (0, import_postgresTarget.namesPostgresServer)(postgresOptions);
+  const defaultFilePath = isBrowser ? "db_data/app.sqlite3" : await joinPath([getCwd(), "db_data", "app.sqlite3"]);
+  const filePath = options.filePath ?? defaultFilePath;
+  const defaultPriority = (() => {
+    if (options.priority && options.priority.length > 0) {
+      return options.priority;
+    }
+    if (envOverride) {
+      return [envOverride];
+    }
+    if (isElectronMain()) {
+      log.warn({ runtime: "electron-main" }, "Electron main process detected. Consider using the dedicated Electron adapter for full framework support:\n  import { createElectronMainAdapter } from '@framers/sql-storage-adapter/electron';\nFalling back to better-sqlite3 adapter.");
+      return ["better-sqlite3"];
+    }
+    if (isElectronRenderer()) {
+      log.warn({ runtime: "electron-renderer" }, "Electron renderer process detected. For IPC-based database access, use the dedicated Electron adapter:\n  import { createElectronRendererAdapter } from '@framers/sql-storage-adapter/electron';\nNote: Direct database access in renderer is not recommended for security reasons.");
+      return ["indexeddb", "sqljs"];
+    }
+    if (isCapacitorRuntime()) {
+      return ["capacitor", "indexeddb", "sqljs"];
+    }
+    if (postgresTarget) {
+      return strict ? ["postgres"] : ["postgres", "better-sqlite3", "indexeddb", "sqljs"];
+    }
+    if (strict && postgresOptions !== void 0 && !(0, import_postgresTarget.isNonEmpty)(options.filePath)) {
+      return ["postgres"];
+    }
+    if (typeof window !== "undefined" && window.indexedDB) {
+      return ["indexeddb", "sqljs"];
+    }
+    return ["better-sqlite3", "indexeddb", "sqljs"];
+  })();
+  const candidates = defaultPriority.map((name) => {
+    switch (name) {
+      case "postgres": {
+        return {
+          name,
+          factory: async () => {
+            if (!postgresTarget) {
+              throw new Error(fileOutranksEnv ? "A postgres connection string, or a postgres host, database or user is required. Strict resolution does not read DATABASE_URL when a filePath is given." : "DATABASE_URL, a postgres connection string, or a postgres host, database or user is required.");
+            }
+            return (0, import_postgresAdapter.createPostgresAdapter)({
+              ...postgresOptions,
+              ...postgresConnection ? { connectionString: postgresConnection } : {},
+              ...segmentFor(postgresOptions?.segment)
+            });
+          },
+          openOptions: postgresConnection ? { connectionString: postgresConnection } : void 0
+        };
+      }
+      case "better-sqlite3":
+        return {
+          name,
+          factory: async () => (0, import_betterSqliteAdapter.createBetterSqliteAdapter)(filePath, segmentFor(void 0)),
+          openOptions: { filePath }
+        };
+      case "capacitor":
+        return {
+          name,
+          factory: async () => (0, import_capacitorSqliteAdapter.createCapacitorSqliteAdapter)({ ...options.capacitor, ...segmentFor(options.capacitor?.segment) })
+        };
+      case "indexeddb":
+        return {
+          name,
+          factory: async () => {
+            const legacyOptions = options.openOptions?.adapterOptions;
+            return new import_indexedDbAdapter.IndexedDbAdapter({
+              ...options.indexedDb,
+              dbName: options.indexedDb?.dbName || legacyOptions?.dbName || "app-db",
+              autoSave: options.indexedDb?.autoSave ?? true,
+              ...segmentFor(options.indexedDb?.segment)
+            });
+          }
+        };
+      case "sqljs":
+      // Not an AdapterKind, but the README lists it and hosts pass it; it builds
+      // what it has always built.
+      case "memory":
+        return {
+          name: "sqljs",
+          factory: async () => (0, import_sqlJsAdapter.createSqlJsAdapter)(segmentFor(void 0)),
+          openOptions: { filePath }
+        };
+      default:
+        return {
+          name,
+          factory: async () => {
+            throw unsupportedKind(name);
+          }
+        };
+    }
+  });
+  const errors = [];
+  const quiet = options.quiet === true;
+  for (const candidate of candidates) {
+    try {
+      const adapter = await candidate.factory();
+      const openOptions = {
+        ...candidate.openOptions,
+        ...options.openOptions
+      };
+      await adapter.open(openOptions);
+      if (!quiet) {
+        log.info(segment === void 0 ? { adapter: candidate.name } : { adapter: candidate.name, segment }, `Using adapter "${candidate.name}"${segment === void 0 ? "" : ` for segment "${segment}"`}.`);
+      }
+      return adapter;
+    } catch (error) {
+      errors.push(error);
+      if (strict && candidate.name === "postgres") {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new import_contracts.StorageResolutionError(`PostgreSQL could not be opened, and strict resolution does not fall back to a local database. ${msg}`, errors);
+      }
+      if (!quiet) {
+        const msg = error instanceof Error ? error.message : String(error);
+        log.warn({ adapter: candidate.name, error: msg }, `${candidate.name} not available, trying next. ${msg}`);
+      }
+      continue;
+    }
+  }
+  throw new import_contracts.StorageResolutionError("Unable to resolve a storage adapter for the current environment.", errors);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveStorageAdapter
+});

package/dist/cjs/dialects/PostgresDialect.d.ts

@@ -0,0 +1,35 @@
+import type { CastType, ColumnKind, DateBucketUnit, IntervalUnit, JsonValueType, SqlDialect } from '../core/contracts/dialect.js';
+/**
+ * PostgreSQL dialect implementation.
+ *
+ * Generates Postgres-compatible SQL syntax including `ON CONFLICT DO NOTHING`,
+ * `ON CONFLICT ... DO UPDATE SET`, `jsonb` extraction operators, `COALESCE()`,
+ * `GENERATED ALWAYS AS IDENTITY`, and `$N` positional placeholders.
+ */
+export declare class PostgresDialect implements SqlDialect {
+    readonly name: "postgres";
+    insertOrIgnore(table: string, columns: string[], placeholders: string[]): string;
+    insertOrReplace(table: string, columns: string[], placeholders: string[], primaryKey?: string): string;
+    upsert(table: string, columns: string[], placeholders: string[], conflictColumns: string[], updateColumns?: string[]): string;
+    jsonExtract(column: string, jsonPath: string): string;
+    jsonExtractAs(column: string, jsonPath: string, type: JsonValueType): string;
+    jsonArrayContains(jsonArray: string, valueExpr: string): string;
+    ifnull(expr: string, fallback: string): string;
+    autoIncrementPrimaryKey(): string;
+    columnType(kind: ColumnKind): string;
+    pragma(_key: string, _value: string): string | null;
+    placeholder(index: number): string;
+    now(): string;
+    cast(expr: string, type: CastType): string;
+    addInterval(expr: string, amount: number, unit: IntervalUnit): string;
+    dateBucket(unit: DateBucketUnit, expr: string): string;
+    ilike(expr: string, pattern: string): string;
+    inList(expr: string, items: string[]): string;
+    inArray(expr: string, arrayParam: string): string;
+    rowLock(mode: 'update' | 'share', wait?: 'wait' | 'skipLocked' | 'noWait'): string;
+    advisoryTransactionLock(keyExpr: string): string | null;
+    greatest(...exprs: string[]): string;
+    least(...exprs: string[]): string;
+    uuid(): string;
+}
+//# sourceMappingURL=PostgresDialect.d.ts.map