@dexto/storage 1.6.0

package/dist/database/postgres-store.cjs

@@ -0,0 +1,342 @@
+"use strict";
+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 postgres_store_exports = {};
+__export(postgres_store_exports, {
+  PostgresStore: () => PostgresStore
+});
+module.exports = __toCommonJS(postgres_store_exports);
+var import_pg = require("pg");
+var import_core = require("@dexto/core");
+class PostgresStore {
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger.createChild(import_core.DextoLogComponent.STORAGE);
+  }
+  pool = null;
+  connected = false;
+  logger;
+  async connect() {
+    if (this.connected) return;
+    const connectionString = this.config.connectionString || this.config.url;
+    if (connectionString?.startsWith("$")) {
+      throw import_core.StorageError.connectionFailed(
+        `PostgreSQL: Connection string contains unexpanded environment variable: ${connectionString}. Ensure the environment variable is set in your .env file.`
+      );
+    }
+    if (!connectionString) {
+      throw import_core.StorageError.connectionFailed(
+        "PostgreSQL: No connection string provided. Set url or connectionString in database config."
+      );
+    }
+    const { schema, ...pgOptions } = this.config.options || {};
+    this.logger.info("Connecting to PostgreSQL database...");
+    this.pool = new import_pg.Pool({
+      connectionString,
+      max: this.config.maxConnections || 20,
+      // Shorter idle timeout for serverless DBs (Neon) - connections go stale quickly
+      idleTimeoutMillis: this.config.idleTimeoutMillis || 1e4,
+      connectionTimeoutMillis: this.config.connectionTimeoutMillis || 1e4,
+      // Enable TCP keepalive to detect dead connections
+      keepAlive: true,
+      keepAliveInitialDelayMillis: 1e4,
+      ...pgOptions
+    });
+    this.pool.on("error", (err) => {
+      this.logger.warn(`PostgreSQL pool error (will retry on next query): ${err.message}`);
+    });
+    if (schema) {
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schema)) {
+        throw import_core.StorageError.connectionFailed(
+          `PostgreSQL: Invalid schema name "${schema}". Schema names must start with a letter or underscore and contain only alphanumeric characters and underscores.`
+        );
+      }
+      this.pool.on("connect", async (client2) => {
+        try {
+          await client2.query(`SET search_path TO "${schema}", public`);
+        } catch (err) {
+          this.logger.error(`Failed to set search_path to "${schema}": ${err}`);
+        }
+      });
+      this.logger.info(`Using custom schema: "${schema}"`);
+    }
+    let client;
+    try {
+      client = await this.pool.connect();
+      await client.query("SELECT NOW()");
+      if (schema) {
+        await this.createSchema(client, schema);
+      }
+      await this.createTables(client);
+      this.connected = true;
+      this.logger.info("PostgreSQL database connected successfully");
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`PostgreSQL connection failed: ${errorMessage}`);
+      if (this.pool) {
+        await this.pool.end().catch(() => {
+        });
+        this.pool = null;
+      }
+      throw import_core.StorageError.connectionFailed(`PostgreSQL: ${errorMessage}`);
+    } finally {
+      if (client) {
+        client.release();
+      }
+    }
+  }
+  /**
+   * Creates a PostgreSQL schema if it doesn't exist.
+   */
+  async createSchema(client, schemaName) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schemaName)) {
+      throw import_core.StorageError.connectionFailed(
+        `PostgreSQL: Invalid schema name "${schemaName}". Schema names must start with a letter or underscore and contain only alphanumeric characters and underscores.`
+      );
+    }
+    try {
+      await client.query(`CREATE SCHEMA IF NOT EXISTS "${schemaName}"`);
+      this.logger.debug(`Schema "${schemaName}" ready`);
+    } catch (error) {
+      this.logger.warn(
+        `Could not create schema "${schemaName}": ${error}. Assuming it exists.`
+      );
+    }
+  }
+  async disconnect() {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+    }
+    this.connected = false;
+  }
+  isConnected() {
+    return this.connected && this.pool !== null;
+  }
+  getStoreType() {
+    return "postgres";
+  }
+  // Core operations - all use withRetry for serverless DB resilience
+  async get(key) {
+    try {
+      return await this.withRetry("get", async (client) => {
+        const result = await client.query("SELECT value FROM kv WHERE key = $1", [key]);
+        return result.rows[0] ? result.rows[0].value : void 0;
+      });
+    } catch (error) {
+      throw import_core.StorageError.readFailed(
+        "get",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
+  async set(key, value) {
+    try {
+      await this.withRetry("set", async (client) => {
+        const jsonValue = JSON.stringify(value);
+        await client.query(
+          "INSERT INTO kv (key, value, updated_at) VALUES ($1, $2::jsonb, $3) ON CONFLICT (key) DO UPDATE SET value = $2::jsonb, updated_at = $3",
+          [key, jsonValue, /* @__PURE__ */ new Date()]
+        );
+      });
+    } catch (error) {
+      throw import_core.StorageError.writeFailed(
+        "set",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
+  async delete(key) {
+    await this.withRetry("delete", async (client) => {
+      await client.query("BEGIN");
+      try {
+        await client.query("DELETE FROM kv WHERE key = $1", [key]);
+        await client.query("DELETE FROM lists WHERE key = $1", [key]);
+        await client.query("COMMIT");
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+      }
+    });
+  }
+  // List operations
+  async list(prefix) {
+    return await this.withRetry("list", async (client) => {
+      const kvResult = await client.query("SELECT key FROM kv WHERE key LIKE $1", [
+        `${prefix}%`
+      ]);
+      const listResult = await client.query(
+        "SELECT DISTINCT key FROM lists WHERE key LIKE $1",
+        [`${prefix}%`]
+      );
+      const allKeys = /* @__PURE__ */ new Set([
+        ...kvResult.rows.map((row) => row.key),
+        ...listResult.rows.map((row) => row.key)
+      ]);
+      return Array.from(allKeys).sort();
+    });
+  }
+  async append(key, item) {
+    try {
+      await this.withRetry("append", async (client) => {
+        const jsonItem = JSON.stringify(item);
+        await client.query(
+          "INSERT INTO lists (key, item, created_at) VALUES ($1, $2::jsonb, $3)",
+          [key, jsonItem, /* @__PURE__ */ new Date()]
+        );
+      });
+    } catch (error) {
+      throw import_core.StorageError.writeFailed(
+        "append",
+        error instanceof Error ? error.message : String(error),
+        { key }
+      );
+    }
+  }
+  async getRange(key, start, count) {
+    return await this.withRetry("getRange", async (client) => {
+      const result = await client.query(
+        "SELECT item FROM lists WHERE key = $1 ORDER BY created_at ASC LIMIT $2 OFFSET $3",
+        [key, count, start]
+      );
+      return result.rows.map((row) => row.item);
+    });
+  }
+  // Schema management
+  async createTables(client) {
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS kv (
+        key VARCHAR(255) PRIMARY KEY,
+        value JSONB NOT NULL,
+        updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+      )
+    `);
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS lists (
+        id BIGSERIAL PRIMARY KEY,
+        key VARCHAR(255) NOT NULL,
+        item JSONB NOT NULL,
+        created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+      )
+    `);
+    await client.query("CREATE INDEX IF NOT EXISTS idx_kv_key ON kv(key)");
+    await client.query("CREATE INDEX IF NOT EXISTS idx_lists_key ON lists(key)");
+    await client.query(
+      "CREATE INDEX IF NOT EXISTS idx_lists_created_at ON lists(key, created_at DESC)"
+    );
+  }
+  checkConnection() {
+    if (!this.connected || !this.pool) {
+      throw import_core.StorageError.notConnected("PostgresStore");
+    }
+  }
+  /**
+   * Check if an error is a connection error that should trigger a retry.
+   * Common with serverless databases (Neon) where connections go stale.
+   */
+  isConnectionError(error) {
+    if (!(error instanceof Error)) return false;
+    const code = error.code;
+    const codeString = typeof code === "string" ? code : void 0;
+    return codeString === "ETIMEDOUT" || codeString === "ECONNRESET" || codeString === "ECONNREFUSED" || codeString === "EPIPE" || codeString === "57P01" || // admin_shutdown
+    codeString === "57P02" || // crash_shutdown
+    codeString === "57P03" || // cannot_connect_now
+    error.message.includes("Connection terminated") || error.message.includes("connection lost");
+  }
+  /**
+   * Execute a database operation with automatic retry on connection errors.
+   * Handles serverless DB connection issues (Neon cold starts, stale connections).
+   */
+  async withRetry(operation, fn, maxRetries = 2) {
+    this.checkConnection();
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      let client;
+      try {
+        client = await this.pool.connect();
+        const result = await fn(client);
+        return result;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (client) {
+          client.release(true);
+          client = void 0;
+        }
+        if (this.isConnectionError(error) && attempt < maxRetries) {
+          this.logger.warn(
+            `PostgreSQL ${operation} failed with connection error (attempt ${attempt + 1}/${maxRetries + 1}): ${lastError.message}. Retrying...`
+          );
+          await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+          continue;
+        }
+        throw error;
+      } finally {
+        if (client) {
+          client.release();
+        }
+      }
+    }
+    throw lastError;
+  }
+  // Advanced operations
+  /**
+   * Execute a callback within a database transaction.
+   * Note: On connection failure, the entire callback will be retried on a new connection.
+   * Ensure callback operations are idempotent or use this only for read operations.
+   */
+  async transaction(callback) {
+    return await this.withRetry("transaction", async (client) => {
+      await client.query("BEGIN");
+      try {
+        const result = await callback(client);
+        await client.query("COMMIT");
+        return result;
+      } catch (error) {
+        await client.query("ROLLBACK");
+        throw error;
+      }
+    });
+  }
+  async getStats() {
+    return await this.withRetry("getStats", async (client) => {
+      const kvResult = await client.query("SELECT COUNT(*) as count FROM kv");
+      const listResult = await client.query("SELECT COUNT(*) as count FROM lists");
+      const sizeResult = await client.query(
+        "SELECT pg_size_pretty(pg_total_relation_size($1)) as size",
+        ["kv"]
+      );
+      return {
+        kvCount: parseInt(kvResult.rows[0].count),
+        listCount: parseInt(listResult.rows[0].count),
+        totalSize: sizeResult.rows[0].size
+      };
+    });
+  }
+  // Maintenance operations
+  async vacuum() {
+    await this.withRetry("vacuum", async (client) => {
+      await client.query("VACUUM ANALYZE kv, lists");
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PostgresStore
+});

package/dist/database/postgres-store.d.cts

@@ -0,0 +1,57 @@
+import { PoolClient } from 'pg';
+import { Database, Logger } from '@dexto/core';
+import { PostgresDatabaseConfig } from './schemas.cjs';
+import 'zod';
+
+/**
+ * PostgreSQL database store for production database operations.
+ * Implements the Database interface with connection pooling and JSONB support.
+ * EXPERIMENTAL - NOT FULLY TESTED YET
+ */
+declare class PostgresStore implements Database {
+    private config;
+    private pool;
+    private connected;
+    private logger;
+    constructor(config: PostgresDatabaseConfig, logger: Logger);
+    connect(): Promise<void>;
+    /**
+     * Creates a PostgreSQL schema if it doesn't exist.
+     */
+    private createSchema;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    append<T>(key: string, item: T): Promise<void>;
+    getRange<T>(key: string, start: number, count: number): Promise<T[]>;
+    private createTables;
+    private checkConnection;
+    /**
+     * Check if an error is a connection error that should trigger a retry.
+     * Common with serverless databases (Neon) where connections go stale.
+     */
+    private isConnectionError;
+    /**
+     * Execute a database operation with automatic retry on connection errors.
+     * Handles serverless DB connection issues (Neon cold starts, stale connections).
+     */
+    private withRetry;
+    /**
+     * Execute a callback within a database transaction.
+     * Note: On connection failure, the entire callback will be retried on a new connection.
+     * Ensure callback operations are idempotent or use this only for read operations.
+     */
+    transaction<T>(callback: (client: PoolClient) => Promise<T>): Promise<T>;
+    getStats(): Promise<{
+        kvCount: number;
+        listCount: number;
+        totalSize: string;
+    }>;
+    vacuum(): Promise<void>;
+}
+
+export { PostgresStore };

package/dist/database/postgres-store.d.ts

@@ -0,0 +1,55 @@
+import { PoolClient } from 'pg';
+import type { Database } from './types.js';
+import type { PostgresDatabaseConfig } from './schemas.js';
+import type { Logger } from '@dexto/core';
+/**
+ * PostgreSQL database store for production database operations.
+ * Implements the Database interface with connection pooling and JSONB support.
+ * EXPERIMENTAL - NOT FULLY TESTED YET
+ */
+export declare class PostgresStore implements Database {
+    private config;
+    private pool;
+    private connected;
+    private logger;
+    constructor(config: PostgresDatabaseConfig, logger: Logger);
+    connect(): Promise<void>;
+    /**
+     * Creates a PostgreSQL schema if it doesn't exist.
+     */
+    private createSchema;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStoreType(): string;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    append<T>(key: string, item: T): Promise<void>;
+    getRange<T>(key: string, start: number, count: number): Promise<T[]>;
+    private createTables;
+    private checkConnection;
+    /**
+     * Check if an error is a connection error that should trigger a retry.
+     * Common with serverless databases (Neon) where connections go stale.
+     */
+    private isConnectionError;
+    /**
+     * Execute a database operation with automatic retry on connection errors.
+     * Handles serverless DB connection issues (Neon cold starts, stale connections).
+     */
+    private withRetry;
+    /**
+     * Execute a callback within a database transaction.
+     * Note: On connection failure, the entire callback will be retried on a new connection.
+     * Ensure callback operations are idempotent or use this only for read operations.
+     */
+    transaction<T>(callback: (client: PoolClient) => Promise<T>): Promise<T>;
+    getStats(): Promise<{
+        kvCount: number;
+        listCount: number;
+        totalSize: string;
+    }>;
+    vacuum(): Promise<void>;
+}
+//# sourceMappingURL=postgres-store.d.ts.map

package/dist/database/postgres-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../src/database/postgres-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAE,MAAM,IAAI,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAMtC,OAAO,CAAC,MAAM;IALlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;gBAGX,MAAM,EAAE,sBAAsB,EACtC,MAAM,EAAE,MAAM;IAKZ,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+F9B;;OAEG;YACW,YAAY;IAmBpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,MAAM;IAKhB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAe3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAelC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmBvC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;YAW5D,YAAY;IA4B1B,OAAO,CAAC,eAAe;IAMvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;OAGG;YACW,SAAS;IA8CvB;;;;OAIG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAcxE,QAAQ,IAAI,OAAO,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAC;IAkBI,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}