@keyv/postgres 2.2.2 → 6.0.0-alpha.1

package/dist/index.js

@@ -1,161 +1,654 @@
 // src/index.ts
-import EventEmitter from "events";
+import { Hookified } from "hookified";
 import Keyv from "keyv";
 
 // src/pool.ts
 import pg from "pg";
-var postgresPool;
-var globalUri;
-var pool = (uri, options = {}) => {
-  if (globalUri !== uri) {
-    postgresPool = void 0;
-    globalUri = uri;
-  }
-  postgresPool ??= new pg.Pool({ connectionString: uri, ...options });
-  return postgresPool;
-};
-var endPool = async () => {
-  await postgresPool?.end();
-  globalUri = void 0;
+function getCacheKey(uri, options) {
+  const sortedKeys = Object.keys(options).sort();
+  const sorted = {};
+  for (const key of sortedKeys) {
+    sorted[key] = options[key];
+  }
+  return `${uri}::${JSON.stringify(sorted)}`;
+}
+var createPoolManager = () => {
+  const pools = /* @__PURE__ */ new Map();
+  return {
+    getPool(uri, options = {}) {
+      const key = getCacheKey(uri, options);
+      let existingPool = pools.get(key);
+      if (!existingPool) {
+        existingPool = new pg.Pool({ connectionString: uri, ...options });
+        pools.set(key, existingPool);
+      }
+      return existingPool;
+    },
+    async endPool(uri, options = {}) {
+      const key = getCacheKey(uri, options);
+      const existingPool = pools.get(key);
+      if (existingPool) {
+        await existingPool.end();
+        pools.delete(key);
+      }
+    },
+    async endAllPools() {
+      const endings = [];
+      for (const [, p] of pools) {
+        endings.push(p.end());
+      }
+      await Promise.all(endings);
+      pools.clear();
+    }
+  };
 };
+var poolManager = createPoolManager();
+var pool = (uri, options = {}) => poolManager.getPool(uri, options);
+var endPool = async (uri, options = {}) => poolManager.endPool(uri, options);
 
 // src/index.ts
-var KeyvPostgres = class extends EventEmitter {
-  ttlSupport;
-  opts;
+function escapeIdentifier(identifier) {
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+var KeyvPostgres = class extends Hookified {
+  /** Function for executing SQL queries against the PostgreSQL database. */
   query;
-  namespace;
+  /** Promise that resolves to the query function once initialization completes. */
+  _connected;
+  /** The namespace used to prefix keys for multi-tenant separation. */
+  _namespace;
+  /**
+   * The PostgreSQL connection URI.
+   * @default 'postgresql://localhost:5432'
+   */
+  _uri = "postgresql://localhost:5432";
+  /**
+   * The table name used for storage.
+   * @default 'keyv'
+   */
+  _table = "keyv";
+  /**
+   * The maximum key length (VARCHAR length) for the key column.
+   * @default 255
+   */
+  _keyLength = 255;
+  /**
+   * The maximum namespace length (VARCHAR length) for the namespace column.
+   * @default 255
+   */
+  _namespaceLength = 255;
+  /**
+   * The PostgreSQL schema name.
+   * @default 'public'
+   */
+  _schema = "public";
+  /**
+   * The SSL configuration for the PostgreSQL connection.
+   * @default undefined
+   */
+  _ssl;
+  /**
+   * The number of rows to fetch per iteration batch.
+   * @default 10
+   */
+  _iterationLimit = 10;
+  /**
+   * Whether to use a PostgreSQL unlogged table (faster writes, no WAL, data lost on crash).
+   * @default false
+   */
+  _useUnloggedTable = false;
+  /**
+   * The interval in milliseconds between automatic expired-entry cleanup runs.
+   * A value of 0 (default) disables the automatic cleanup.
+   * @default 0
+   */
+  _clearExpiredInterval = 0;
+  /**
+   * The timer reference for the automatic expired-entry cleanup interval.
+   */
+  _clearExpiredTimer;
+  /**
+   * Additional PoolConfig properties passed through to the pg connection pool.
+   */
+  _poolConfig = {};
+  /**
+   * Creates a new KeyvPostgres instance.
+   * @param options - A PostgreSQL connection URI string or a {@link KeyvPostgresOptions} configuration object.
+   */
   constructor(options) {
     super();
-    this.ttlSupport = false;
     if (typeof options === "string") {
-      const uri = options;
-      options = {
-        dialect: "postgres",
-        uri
-      };
-    } else {
-      options = {
-        dialect: "postgres",
-        uri: "postgresql://localhost:5432",
-        ...options
-      };
-    }
-    this.opts = {
-      table: "keyv",
-      schema: "public",
-      keySize: 255,
-      ...options
-    };
-    let createTable = `CREATE${this.opts.useUnloggedTable ? " UNLOGGED " : " "}TABLE IF NOT EXISTS ${this.opts.schema}.${this.opts.table}(key VARCHAR(${Number(this.opts.keySize)}) PRIMARY KEY, value TEXT )`;
-    if (this.opts.schema !== "public") {
-      createTable = `CREATE SCHEMA IF NOT EXISTS ${this.opts.schema}; ${createTable}`;
+      this._uri = options;
+    } else if (options) {
+      this.setOptions(options);
     }
-    const connected = this.connect().then(async (query) => {
-      try {
-        await query(createTable);
-      } catch (error) {
-        if (error.code !== "23505") {
-          this.emit("error", error);
-        }
-        return query;
+    const schemaEsc = escapeIdentifier(this._schema);
+    const tableEsc = escapeIdentifier(this._table);
+    let createTable = `CREATE${this._useUnloggedTable ? " UNLOGGED " : " "}TABLE IF NOT EXISTS ${schemaEsc}.${tableEsc}(key VARCHAR(${Number(this._keyLength)}) NOT NULL, value TEXT, namespace VARCHAR(${Number(this._namespaceLength)}) DEFAULT NULL, expires BIGINT DEFAULT NULL)`;
+    if (this._schema !== "public") {
+      createTable = `CREATE SCHEMA IF NOT EXISTS ${schemaEsc}; ${createTable}`;
+    }
+    const migration = `ALTER TABLE ${schemaEsc}.${tableEsc} ADD COLUMN IF NOT EXISTS namespace VARCHAR(${Number(this._namespaceLength)}) DEFAULT NULL`;
+    const migrationExpires = `ALTER TABLE ${schemaEsc}.${tableEsc} ADD COLUMN IF NOT EXISTS expires BIGINT DEFAULT NULL`;
+    const dropOldPk = `ALTER TABLE ${schemaEsc}.${tableEsc} DROP CONSTRAINT IF EXISTS ${escapeIdentifier(`${this._table}_pkey`)}`;
+    const createIndex = `CREATE UNIQUE INDEX IF NOT EXISTS ${escapeIdentifier(`${this._table}_key_namespace_idx`)} ON ${schemaEsc}.${tableEsc} (key, COALESCE(namespace, ''))`;
+    const createExpiresIndex = `CREATE INDEX IF NOT EXISTS ${escapeIdentifier(`${this._table}_expires_idx`)} ON ${schemaEsc}.${tableEsc} (expires) WHERE expires IS NOT NULL`;
+    this._connected = this.init(
+      createTable,
+      migration,
+      migrationExpires,
+      dropOldPk,
+      createIndex,
+      createExpiresIndex
+    ).catch((error) => {
+      this.emit("error", error);
+      throw error;
+    });
+    this.query = async (sqlString, values) => {
+      const query = await this._connected;
+      return query(sqlString, values);
+    };
+    this.startClearExpiredTimer();
+  }
+  /**
+   * Initializes the database connection and ensures the table schema exists.
+   * Called from the constructor; errors are emitted rather than thrown.
+   */
+  async init(createTable, migration, migrationExpires, dropOldPk, createIndex, createExpiresIndex) {
+    const query = await this.connect();
+    try {
+      await query(createTable);
+      await query(migration);
+      await query(migrationExpires);
+      await query(dropOldPk);
+      await query(createIndex);
+      await query(createExpiresIndex);
+    } catch (error) {
+      if (error.code !== "23505") {
+        this.emit("error", error);
       }
-      return query;
-    }).catch((error) => this.emit("error", error));
-    this.query = async (sqlString, values) => connected.then((query) => query(sqlString, values));
+    }
+    return query;
+  }
+  /**
+   * Get the namespace for the adapter. If undefined, no namespace prefix is applied.
+   */
+  get namespace() {
+    return this._namespace;
+  }
+  /**
+   * Set the namespace for the adapter. Used for key prefixing and scoping operations like `clear()`.
+   */
+  set namespace(value) {
+    this._namespace = value;
+  }
+  /**
+   * Get the PostgreSQL connection URI.
+   * @default 'postgresql://localhost:5432'
+   */
+  get uri() {
+    return this._uri;
+  }
+  /**
+   * Set the PostgreSQL connection URI.
+   */
+  set uri(value) {
+    this._uri = value;
+  }
+  /**
+   * Get the table name used for storage.
+   * @default 'keyv'
+   */
+  get table() {
+    return this._table;
   }
+  /**
+   * Set the table name used for storage.
+   */
+  set table(value) {
+    this._table = value;
+  }
+  /**
+   * Get the maximum key length (VARCHAR length) for the key column.
+   * @default 255
+   */
+  get keyLength() {
+    return this._keyLength;
+  }
+  /**
+   * Set the maximum key length (VARCHAR length) for the key column.
+   */
+  set keyLength(value) {
+    this._keyLength = value;
+  }
+  /**
+   * Get the maximum namespace length (VARCHAR length) for the namespace column.
+   * @default 255
+   */
+  get namespaceLength() {
+    return this._namespaceLength;
+  }
+  /**
+   * Set the maximum namespace length (VARCHAR length) for the namespace column.
+   */
+  set namespaceLength(value) {
+    this._namespaceLength = value;
+  }
+  /**
+   * Get the PostgreSQL schema name.
+   * @default 'public'
+   */
+  get schema() {
+    return this._schema;
+  }
+  /**
+   * Set the PostgreSQL schema name.
+   */
+  set schema(value) {
+    this._schema = value;
+  }
+  /**
+   * Get the SSL configuration for the PostgreSQL connection.
+   * @default undefined
+   */
+  get ssl() {
+    return this._ssl;
+  }
+  /**
+   * Set the SSL configuration for the PostgreSQL connection.
+   */
+  set ssl(value) {
+    this._ssl = value;
+  }
+  /**
+   * Get the number of rows to fetch per iteration batch.
+   * @default 10
+   */
+  get iterationLimit() {
+    return this._iterationLimit;
+  }
+  /**
+   * Set the number of rows to fetch per iteration batch.
+   */
+  set iterationLimit(value) {
+    this._iterationLimit = value;
+  }
+  /**
+   * Get whether to use a PostgreSQL unlogged table (faster writes, no WAL, data lost on crash).
+   * @default false
+   */
+  get useUnloggedTable() {
+    return this._useUnloggedTable;
+  }
+  /**
+   * Set whether to use a PostgreSQL unlogged table.
+   */
+  set useUnloggedTable(value) {
+    this._useUnloggedTable = value;
+  }
+  /**
+   * Get the interval in milliseconds between automatic expired-entry cleanup runs.
+   * A value of 0 means the automatic cleanup is disabled.
+   * @default 0
+   */
+  get clearExpiredInterval() {
+    return this._clearExpiredInterval;
+  }
+  /**
+   * Set the interval in milliseconds between automatic expired-entry cleanup runs.
+   * Setting to 0 disables the automatic cleanup.
+   */
+  set clearExpiredInterval(value) {
+    this._clearExpiredInterval = value;
+    this.startClearExpiredTimer();
+  }
+  /**
+   * Get the options for the adapter. This is required by the KeyvStoreAdapter interface.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: type format
+  get opts() {
+    return {
+      uri: this._uri,
+      table: this._table,
+      keyLength: this._keyLength,
+      namespaceLength: this._namespaceLength,
+      schema: this._schema,
+      ssl: this._ssl,
+      dialect: "postgres",
+      iterationLimit: this._iterationLimit,
+      useUnloggedTable: this._useUnloggedTable,
+      clearExpiredInterval: this._clearExpiredInterval,
+      ...this._poolConfig
+    };
+  }
+  /**
+   * Set the options for the adapter.
+   */
+  set opts(options) {
+    this.setOptions(options);
+  }
+  /**
+   * Gets a value by key.
+   * @param key - The key to retrieve.
+   * @returns The value associated with the key, or `undefined` if not found.
+   */
   async get(key) {
-    const select = `SELECT * FROM ${this.opts.schema}.${this.opts.table} WHERE key = $1`;
-    const rows = await this.query(select, [key]);
+    const strippedKey = this.removeKeyPrefix(key);
+    const select = `SELECT * FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE key = $1 AND COALESCE(namespace, '') = COALESCE($2, '')`;
+    const rows = await this.query(select, [
+      strippedKey,
+      this.getNamespaceValue()
+    ]);
     const row = rows[0];
     return row === void 0 ? void 0 : row.value;
   }
+  /**
+   * Gets multiple values by their keys.
+   * @param keys - An array of keys to retrieve.
+   * @returns An array of values in the same order as the keys, with `undefined` for missing keys.
+   */
   async getMany(keys) {
-    const getMany = `SELECT * FROM ${this.opts.schema}.${this.opts.table} WHERE key = ANY($1)`;
-    const rows = await this.query(getMany, [keys]);
+    const strippedKeys = keys.map((k) => this.removeKeyPrefix(k));
+    const getMany = `SELECT * FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE key = ANY($1) AND COALESCE(namespace, '') = COALESCE($2, '')`;
+    const rows = await this.query(getMany, [
+      strippedKeys,
+      this.getNamespaceValue()
+    ]);
     const rowsMap = new Map(rows.map((row) => [row.key, row]));
-    return keys.map((key) => rowsMap.get(key)?.value);
+    return strippedKeys.map((key) => rowsMap.get(key)?.value);
   }
+  /**
+   * Sets a key-value pair. Uses an upsert operation via `ON CONFLICT` to insert or update.
+   * @param key - The key to set.
+   * @param value - The value to store.
+   */
   // biome-ignore lint/suspicious/noExplicitAny: type format
   async set(key, value) {
-    const upsert = `INSERT INTO ${this.opts.schema}.${this.opts.table} (key, value)
-      VALUES($1, $2) 
-      ON CONFLICT(key) 
-      DO UPDATE SET value=excluded.value;`;
-    await this.query(upsert, [key, value]);
+    const strippedKey = this.removeKeyPrefix(key);
+    const expires = this.getExpiresFromValue(value);
+    const upsert = `INSERT INTO ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} (key, value, namespace, expires)
+      VALUES($1, $2, $3, $4)
+      ON CONFLICT(key, COALESCE(namespace, ''))
+      DO UPDATE SET value=excluded.value, expires=excluded.expires;`;
+    await this.query(upsert, [
+      strippedKey,
+      value,
+      this.getNamespaceValue(),
+      expires
+    ]);
   }
+  /**
+   * Sets multiple key-value pairs at once using PostgreSQL `UNNEST` for efficient bulk operations.
+   * @param entries - An array of key-value entry objects.
+   */
   async setMany(entries) {
     const keys = [];
     const values = [];
+    const expiresArray = [];
     for (const { key, value } of entries) {
-      keys.push(key);
+      keys.push(this.removeKeyPrefix(key));
       values.push(value);
+      expiresArray.push(this.getExpiresFromValue(value));
     }
-    const upsert = `INSERT INTO ${this.opts.schema}.${this.opts.table} (key, value)
-      SELECT * FROM UNNEST($1::text[], $2::text[])
-      ON CONFLICT(key)
-      DO UPDATE SET value=excluded.value;`;
-    await this.query(upsert, [keys, values]);
+    const upsert = `INSERT INTO ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} (key, value, namespace, expires)
+      SELECT k, v, $3, e FROM UNNEST($1::text[], $2::text[], $4::bigint[]) AS t(k, v, e)
+      ON CONFLICT(key, COALESCE(namespace, ''))
+      DO UPDATE SET value=excluded.value, expires=excluded.expires;`;
+    await this.query(upsert, [
+      keys,
+      values,
+      this.getNamespaceValue(),
+      expiresArray
+    ]);
   }
+  /**
+   * Deletes a key from the store.
+   * @param key - The key to delete.
+   * @returns `true` if the key existed and was deleted, `false` otherwise.
+   */
   async delete(key) {
-    const select = `SELECT * FROM ${this.opts.schema}.${this.opts.table} WHERE key = $1`;
-    const del = `DELETE FROM ${this.opts.schema}.${this.opts.table} WHERE key = $1`;
-    const rows = await this.query(select, [key]);
-    if (rows[0] === void 0) {
-      return false;
-    }
-    await this.query(del, [key]);
-    return true;
+    const strippedKey = this.removeKeyPrefix(key);
+    const ns = this.getNamespaceValue();
+    const del = `DELETE FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE key = $1 AND COALESCE(namespace, '') = COALESCE($2, '') RETURNING 1`;
+    const rows = await this.query(del, [strippedKey, ns]);
+    return rows.length > 0;
   }
+  /**
+   * Deletes multiple keys from the store at once.
+   * @param keys - An array of keys to delete.
+   * @returns `true` if any of the keys existed and were deleted, `false` otherwise.
+   */
   async deleteMany(keys) {
-    const select = `SELECT * FROM ${this.opts.schema}.${this.opts.table} WHERE key = ANY($1)`;
-    const del = `DELETE FROM ${this.opts.schema}.${this.opts.table} WHERE key = ANY($1)`;
-    const rows = await this.query(select, [keys]);
-    if (rows[0] === void 0) {
-      return false;
-    }
-    await this.query(del, [keys]);
-    return true;
+    const strippedKeys = keys.map((k) => this.removeKeyPrefix(k));
+    const ns = this.getNamespaceValue();
+    const del = `DELETE FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE key = ANY($1) AND COALESCE(namespace, '') = COALESCE($2, '') RETURNING 1`;
+    const rows = await this.query(del, [strippedKeys, ns]);
+    return rows.length > 0;
   }
+  /**
+   * Clears all keys in the current namespace. If no namespace is set, all keys are removed.
+   */
   async clear() {
-    const del = `DELETE FROM ${this.opts.schema}.${this.opts.table} WHERE key LIKE $1`;
-    await this.query(del, [this.namespace ? `${this.namespace}:%` : "%"]);
+    if (this._namespace) {
+      const del = `DELETE FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE namespace = $1`;
+      await this.query(del, [this._namespace]);
+    } else {
+      const del = `DELETE FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE namespace IS NULL`;
+      await this.query(del);
+    }
   }
+  /**
+   * Utility helper method to delete all expired entries from the store where the `expires` column is less than the current timestamp.
+   */
+  async clearExpired() {
+    const del = `DELETE FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE expires IS NOT NULL AND expires < $1`;
+    await this.query(del, [Date.now()]);
+  }
+  /**
+   * Iterates over all key-value pairs, optionally filtered by namespace.
+   * Uses cursor-based (keyset) pagination with batch size controlled by `iterationLimit`.
+   * @param namespace - Optional namespace to filter keys by.
+   * @yields A `[key, value]` tuple for each entry.
+   */
   async *iterator(namespace) {
-    const limit = Number.parseInt(String(this.opts.iterationLimit), 10) || 10;
-    async function* iterate(offset, options, query) {
-      const select = `SELECT * FROM ${options.schema}.${options.table} WHERE key LIKE $1 LIMIT $2 OFFSET $3`;
-      const entries = await query(select, [
-        // biome-ignore lint/style/useTemplate: need to fix
-        `${namespace ? namespace + ":" : ""}%`,
-        limit,
-        offset
-      ]);
+    const limit = Number.parseInt(String(this._iterationLimit), 10) || 10;
+    const namespaceValue = namespace ?? null;
+    let lastKey = null;
+    while (true) {
+      let entries;
+      try {
+        const where = [];
+        const params = [];
+        if (namespaceValue !== null) {
+          where.push(`namespace = $${params.length + 1}`);
+          params.push(namespaceValue);
+        } else {
+          where.push("namespace IS NULL");
+        }
+        if (lastKey !== null) {
+          where.push(`key > $${params.length + 1}`);
+          params.push(lastKey);
+        }
+        const select = `SELECT * FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE ${where.join(" AND ")} ORDER BY key LIMIT $${params.length + 1}`;
+        params.push(limit);
+        entries = await this.query(select, params);
+      } catch (error) {
+        this.emit(
+          "error",
+          new Error(
+            `Iterator failed at cursor ${lastKey ?? "start"}: ${error.message}`
+          )
+        );
+        return;
+      }
       if (entries.length === 0) {
         return;
       }
       for (const entry of entries) {
-        offset += 1;
-        yield [entry.key, entry.value];
+        if (entry.key !== void 0 && entry.key !== null) {
+          const prefixedKey = namespace ? `${namespace}:${entry.key}` : entry.key;
+          yield [prefixedKey, entry.value];
+        }
+      }
+      lastKey = entries[entries.length - 1].key;
+      if (entries.length < limit) {
+        return;
       }
-      yield* iterate(offset, options, query);
     }
-    yield* iterate(0, this.opts, this.query);
   }
+  /**
+   * Checks whether a key exists in the store.
+   * @param key - The key to check.
+   * @returns `true` if the key exists, `false` otherwise.
+   */
   async has(key) {
-    const exists = `SELECT EXISTS ( SELECT * FROM ${this.opts.schema}.${this.opts.table} WHERE key = $1 )`;
-    const rows = await this.query(exists, [key]);
+    const strippedKey = this.removeKeyPrefix(key);
+    const exists = `SELECT EXISTS ( SELECT * FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE key = $1 AND COALESCE(namespace, '') = COALESCE($2, '') )`;
+    const rows = await this.query(exists, [
+      strippedKey,
+      this.getNamespaceValue()
+    ]);
     return rows[0].exists;
   }
+  /**
+   * Checks whether multiple keys exist in the store.
+   * @param keys - An array of keys to check.
+   * @returns An array of booleans in the same order as the input keys.
+   */
+  async hasMany(keys) {
+    const strippedKeys = keys.map((k) => this.removeKeyPrefix(k));
+    const select = `SELECT key FROM ${escapeIdentifier(this._schema)}.${escapeIdentifier(this._table)} WHERE key = ANY($1) AND COALESCE(namespace, '') = COALESCE($2, '')`;
+    const rows = await this.query(select, [
+      strippedKeys,
+      this.getNamespaceValue()
+    ]);
+    const existingKeys = new Set(rows.map((row) => row.key));
+    return strippedKeys.map((key) => existingKeys.has(key));
+  }
+  /**
+   * Establishes a connection to the PostgreSQL database via the connection pool.
+   * @returns A query function that executes SQL statements and returns result rows.
+   */
   async connect() {
-    const conn = pool(this.opts.uri, this.opts);
+    const conn = pool(this._uri, { ...this._poolConfig, ssl: this._ssl });
     return async (sql, values) => {
       const data = await conn.query(sql, values);
       return data.rows;
     };
   }
+  /**
+   * Disconnects from the PostgreSQL database and releases the connection pool.
+   * Also stops the automatic expired-entry cleanup interval if running.
+   */
   async disconnect() {
-    await endPool();
+    this.stopClearExpiredTimer();
+    await endPool(this._uri, { ...this._poolConfig, ssl: this._ssl });
+  }
+  /**
+   * Strips the namespace prefix from a key that was added by the Keyv core.
+   * For example, if namespace is "ns" and key is "ns:foo", returns "foo".
+   */
+  removeKeyPrefix(key) {
+    if (this._namespace && key.startsWith(`${this._namespace}:`)) {
+      return key.slice(this._namespace.length + 1);
+    }
+    return key;
+  }
+  /**
+   * Returns the namespace value for SQL parameters. Returns null when no namespace is set.
+   */
+  getNamespaceValue() {
+    return this._namespace ?? null;
+  }
+  /**
+   * Extracts the `expires` timestamp from a serialized value.
+   * The Keyv core serializes data as JSON like `{"value":"...","expires":1234567890}`.
+   * Returns the expires value as a number, or null if not present or not parseable.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: type format
+  getExpiresFromValue(value) {
+    let data;
+    if (typeof value === "string") {
+      try {
+        data = JSON.parse(value);
+      } catch {
+        return null;
+      }
+    } else {
+      data = value;
+    }
+    if (data && typeof data === "object" && typeof data.expires === "number") {
+      return data.expires;
+    }
+    return null;
+  }
+  /**
+   * Starts (or restarts) the automatic expired-entry cleanup interval.
+   * If the interval is 0 or negative, any existing timer is stopped.
+   */
+  startClearExpiredTimer() {
+    this.stopClearExpiredTimer();
+    if (this._clearExpiredInterval > 0) {
+      this._clearExpiredTimer = setInterval(async () => {
+        try {
+          await this.clearExpired();
+        } catch (error) {
+          this.emit("error", error);
+        }
+      }, this._clearExpiredInterval);
+      this._clearExpiredTimer.unref();
+    }
+  }
+  /**
+   * Stops the automatic expired-entry cleanup interval if running.
+   */
+  stopClearExpiredTimer() {
+    if (this._clearExpiredTimer) {
+      clearInterval(this._clearExpiredTimer);
+      this._clearExpiredTimer = void 0;
+    }
+  }
+  setOptions(options) {
+    if (options.uri !== void 0) {
+      this._uri = options.uri;
+    }
+    if (options.table !== void 0) {
+      this._table = options.table;
+    }
+    if (options.keyLength !== void 0) {
+      this._keyLength = options.keyLength;
+    }
+    if (options.namespaceLength !== void 0) {
+      this._namespaceLength = options.namespaceLength;
+    }
+    if (options.schema !== void 0) {
+      this._schema = options.schema;
+    }
+    if (options.ssl !== void 0) {
+      this._ssl = options.ssl;
+    }
+    if (options.iterationLimit !== void 0) {
+      this._iterationLimit = options.iterationLimit;
+    }
+    if (options.useUnloggedTable !== void 0) {
+      this._useUnloggedTable = options.useUnloggedTable;
+    }
+    if (options.clearExpiredInterval !== void 0) {
+      this._clearExpiredInterval = options.clearExpiredInterval;
+    }
+    const {
+      uri,
+      table,
+      keyLength,
+      namespaceLength,
+      schema,
+      ssl,
+      iterationLimit,
+      useUnloggedTable,
+      clearExpiredInterval,
+      ...poolConfigRest
+    } = options;
+    this._poolConfig = { ...this._poolConfig, ...poolConfigRest };
   }
 };
 var createKeyv = (options) => new Keyv({ store: new KeyvPostgres(options) });
@@ -166,3 +659,4 @@ export {
   index_default as default
 };
 /* v8 ignore next -- @preserve */
+/* v8 ignore start -- @preserve */