@keyv/postgres 2.2.3 → 6.0.0-alpha.2

package/dist/index.d.cts

@@ -1,37 +1,297 @@
-import EventEmitter from 'node:events';
+import { ConnectionOptions } from 'node:tls';
+import { Hookified } from 'hookified';
 import Keyv, { KeyvStoreAdapter, KeyvEntry } from 'keyv';
 import { PoolConfig } from 'pg';
 
 type KeyvPostgresOptions = {
     uri?: string;
     table?: string;
-    keySize?: number;
+    keyLength?: number;
+    namespaceLength?: number;
     schema?: string;
-    ssl?: any;
-    dialect?: string;
+    ssl?: boolean | ConnectionOptions;
     iterationLimit?: number;
     useUnloggedTable?: boolean;
+    clearExpiredInterval?: number;
 } & PoolConfig;
-type Query = (sqlString: string, values?: any) => Promise<any[]>;
 
-declare class KeyvPostgres extends EventEmitter implements KeyvStoreAdapter {
-    ttlSupport: boolean;
-    opts: KeyvPostgresOptions;
-    query: Query;
-    namespace?: string;
+/**
+ * PostgreSQL storage adapter for Keyv.
+ * Uses the `pg` library for connection pooling and parameterized queries.
+ */
+declare class KeyvPostgres extends Hookified implements KeyvStoreAdapter {
+    /** Function for executing SQL queries against the PostgreSQL database. */
+    private query;
+    /** Promise that resolves to the query function once initialization completes. */
+    private _connected;
+    /** The namespace used to prefix keys for multi-tenant separation. */
+    private _namespace?;
+    /**
+     * The PostgreSQL connection URI.
+     * @default 'postgresql://localhost:5432'
+     */
+    private _uri;
+    /**
+     * The table name used for storage.
+     * @default 'keyv'
+     */
+    private _table;
+    /**
+     * The maximum key length (VARCHAR length) for the key column.
+     * @default 255
+     */
+    private _keyLength;
+    /**
+     * The maximum namespace length (VARCHAR length) for the namespace column.
+     * @default 255
+     */
+    private _namespaceLength;
+    /**
+     * The PostgreSQL schema name.
+     * @default 'public'
+     */
+    private _schema;
+    /**
+     * The SSL configuration for the PostgreSQL connection.
+     * @default undefined
+     */
+    private _ssl?;
+    /**
+     * The number of rows to fetch per iteration batch.
+     * @default 10
+     */
+    private _iterationLimit;
+    /**
+     * Whether to use a PostgreSQL unlogged table (faster writes, no WAL, data lost on crash).
+     * @default false
+     */
+    private _useUnloggedTable;
+    /**
+     * The interval in milliseconds between automatic expired-entry cleanup runs.
+     * A value of 0 (default) disables the automatic cleanup.
+     * @default 0
+     */
+    private _clearExpiredInterval;
+    /**
+     * The timer reference for the automatic expired-entry cleanup interval.
+     */
+    private _clearExpiredTimer?;
+    /**
+     * Additional PoolConfig properties passed through to the pg connection pool.
+     */
+    private _poolConfig;
+    /**
+     * Creates a new KeyvPostgres instance.
+     * @param options - A PostgreSQL connection URI string or a {@link KeyvPostgresOptions} configuration object.
+     */
     constructor(options?: KeyvPostgresOptions | string);
-    get(key: string): Promise<any>;
-    getMany(keys: string[]): Promise<any[]>;
+    /**
+     * Initializes the database connection and ensures the table schema exists.
+     * Called from the constructor; errors are emitted rather than thrown.
+     */
+    private init;
+    /**
+     * Get the namespace for the adapter. If undefined, no namespace prefix is applied.
+     */
+    get namespace(): string | undefined;
+    /**
+     * Set the namespace for the adapter. Used for key prefixing and scoping operations like `clear()`.
+     */
+    set namespace(value: string | undefined);
+    /**
+     * Get the PostgreSQL connection URI.
+     * @default 'postgresql://localhost:5432'
+     */
+    get uri(): string;
+    /**
+     * Set the PostgreSQL connection URI.
+     */
+    set uri(value: string);
+    /**
+     * Get the table name used for storage.
+     * @default 'keyv'
+     */
+    get table(): string;
+    /**
+     * Set the table name used for storage.
+     */
+    set table(value: string);
+    /**
+     * Get the maximum key length (VARCHAR length) for the key column.
+     * @default 255
+     */
+    get keyLength(): number;
+    /**
+     * Set the maximum key length (VARCHAR length) for the key column.
+     */
+    set keyLength(value: number);
+    /**
+     * Get the maximum namespace length (VARCHAR length) for the namespace column.
+     * @default 255
+     */
+    get namespaceLength(): number;
+    /**
+     * Set the maximum namespace length (VARCHAR length) for the namespace column.
+     */
+    set namespaceLength(value: number);
+    /**
+     * Get the PostgreSQL schema name.
+     * @default 'public'
+     */
+    get schema(): string;
+    /**
+     * Set the PostgreSQL schema name.
+     */
+    set schema(value: string);
+    /**
+     * Get the SSL configuration for the PostgreSQL connection.
+     * @default undefined
+     */
+    get ssl(): boolean | ConnectionOptions | undefined;
+    /**
+     * Set the SSL configuration for the PostgreSQL connection.
+     */
+    set ssl(value: boolean | ConnectionOptions | undefined);
+    /**
+     * Get the number of rows to fetch per iteration batch.
+     * @default 10
+     */
+    get iterationLimit(): number;
+    /**
+     * Set the number of rows to fetch per iteration batch.
+     */
+    set iterationLimit(value: number);
+    /**
+     * Get whether to use a PostgreSQL unlogged table (faster writes, no WAL, data lost on crash).
+     * @default false
+     */
+    get useUnloggedTable(): boolean;
+    /**
+     * Set whether to use a PostgreSQL unlogged table.
+     */
+    set useUnloggedTable(value: boolean);
+    /**
+     * 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(): number;
+    /**
+     * Set the interval in milliseconds between automatic expired-entry cleanup runs.
+     * Setting to 0 disables the automatic cleanup.
+     */
+    set clearExpiredInterval(value: number);
+    /**
+     * Get the options for the adapter. This is required by the KeyvStoreAdapter interface.
+     */
+    get opts(): any;
+    /**
+     * Set the options for the adapter.
+     */
+    set opts(options: KeyvPostgresOptions);
+    /**
+     * Gets a value by key.
+     * @param key - The key to retrieve.
+     * @returns The value associated with the key, or `undefined` if not found.
+     */
+    get<Value>(key: string): Promise<Value | undefined>;
+    /**
+     * 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.
+     */
+    getMany<Value>(keys: string[]): Promise<Array<Value | undefined>>;
+    /**
+     * 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.
+     */
     set(key: string, value: any): Promise<void>;
+    /**
+     * Sets multiple key-value pairs at once using PostgreSQL `UNNEST` for efficient bulk operations.
+     * @param entries - An array of key-value entry objects.
+     */
     setMany(entries: KeyvEntry[]): Promise<void>;
+    /**
+     * Deletes a key from the store.
+     * @param key - The key to delete.
+     * @returns `true` if the key existed and was deleted, `false` otherwise.
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * 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.
+     */
     deleteMany(keys: string[]): Promise<boolean>;
+    /**
+     * Clears all keys in the current namespace. If no namespace is set, all keys are removed.
+     */
     clear(): Promise<void>;
-    iterator(namespace?: string): AsyncGenerator<string[], void, unknown>;
-    has(key: string): Promise<any>;
-    connect(): Promise<(sql: string, values?: any) => Promise<any[]>>;
+    /**
+     * Utility helper method to delete all expired entries from the store where the `expires` column is less than the current timestamp.
+     */
+    clearExpired(): Promise<void>;
+    /**
+     * 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.
+     */
+    iterator(namespace?: string): AsyncGenerator<[string, string], void, unknown>;
+    /**
+     * Checks whether a key exists in the store.
+     * @param key - The key to check.
+     * @returns `true` if the key exists, `false` otherwise.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    hasMany(keys: string[]): Promise<boolean[]>;
+    /**
+     * Establishes a connection to the PostgreSQL database via the connection pool.
+     * @returns A query function that executes SQL statements and returns result rows.
+     */
+    private connect;
+    /**
+     * Disconnects from the PostgreSQL database and releases the connection pool.
+     * Also stops the automatic expired-entry cleanup interval if running.
+     */
     disconnect(): Promise<void>;
+    /**
+     * 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".
+     */
+    private removeKeyPrefix;
+    /**
+     * Returns the namespace value for SQL parameters. Returns null when no namespace is set.
+     */
+    private getNamespaceValue;
+    /**
+     * 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.
+     */
+    private getExpiresFromValue;
+    /**
+     * Starts (or restarts) the automatic expired-entry cleanup interval.
+     * If the interval is 0 or negative, any existing timer is stopped.
+     */
+    private startClearExpiredTimer;
+    /**
+     * Stops the automatic expired-entry cleanup interval if running.
+     */
+    private stopClearExpiredTimer;
+    private setOptions;
 }
+/**
+ * Helper function to create a Keyv instance with KeyvPostgres as the storage adapter.
+ * @param options - Optional {@link KeyvPostgresOptions} configuration object.
+ * @returns A new Keyv instance backed by PostgreSQL.
+ */
 declare const createKeyv: (options?: KeyvPostgresOptions) => Keyv<any>;
 
 export { KeyvPostgres, type KeyvPostgresOptions, createKeyv, KeyvPostgres as default };

package/dist/index.d.ts

@@ -1,37 +1,297 @@
-import EventEmitter from 'node:events';
+import { ConnectionOptions } from 'node:tls';
+import { Hookified } from 'hookified';
 import Keyv, { KeyvStoreAdapter, KeyvEntry } from 'keyv';
 import { PoolConfig } from 'pg';
 
 type KeyvPostgresOptions = {
     uri?: string;
     table?: string;
-    keySize?: number;
+    keyLength?: number;
+    namespaceLength?: number;
     schema?: string;
-    ssl?: any;
-    dialect?: string;
+    ssl?: boolean | ConnectionOptions;
     iterationLimit?: number;
     useUnloggedTable?: boolean;
+    clearExpiredInterval?: number;
 } & PoolConfig;
-type Query = (sqlString: string, values?: any) => Promise<any[]>;
 
-declare class KeyvPostgres extends EventEmitter implements KeyvStoreAdapter {
-    ttlSupport: boolean;
-    opts: KeyvPostgresOptions;
-    query: Query;
-    namespace?: string;
+/**
+ * PostgreSQL storage adapter for Keyv.
+ * Uses the `pg` library for connection pooling and parameterized queries.
+ */
+declare class KeyvPostgres extends Hookified implements KeyvStoreAdapter {
+    /** Function for executing SQL queries against the PostgreSQL database. */
+    private query;
+    /** Promise that resolves to the query function once initialization completes. */
+    private _connected;
+    /** The namespace used to prefix keys for multi-tenant separation. */
+    private _namespace?;
+    /**
+     * The PostgreSQL connection URI.
+     * @default 'postgresql://localhost:5432'
+     */
+    private _uri;
+    /**
+     * The table name used for storage.
+     * @default 'keyv'
+     */
+    private _table;
+    /**
+     * The maximum key length (VARCHAR length) for the key column.
+     * @default 255
+     */
+    private _keyLength;
+    /**
+     * The maximum namespace length (VARCHAR length) for the namespace column.
+     * @default 255
+     */
+    private _namespaceLength;
+    /**
+     * The PostgreSQL schema name.
+     * @default 'public'
+     */
+    private _schema;
+    /**
+     * The SSL configuration for the PostgreSQL connection.
+     * @default undefined
+     */
+    private _ssl?;
+    /**
+     * The number of rows to fetch per iteration batch.
+     * @default 10
+     */
+    private _iterationLimit;
+    /**
+     * Whether to use a PostgreSQL unlogged table (faster writes, no WAL, data lost on crash).
+     * @default false
+     */
+    private _useUnloggedTable;
+    /**
+     * The interval in milliseconds between automatic expired-entry cleanup runs.
+     * A value of 0 (default) disables the automatic cleanup.
+     * @default 0
+     */
+    private _clearExpiredInterval;
+    /**
+     * The timer reference for the automatic expired-entry cleanup interval.
+     */
+    private _clearExpiredTimer?;
+    /**
+     * Additional PoolConfig properties passed through to the pg connection pool.
+     */
+    private _poolConfig;
+    /**
+     * Creates a new KeyvPostgres instance.
+     * @param options - A PostgreSQL connection URI string or a {@link KeyvPostgresOptions} configuration object.
+     */
     constructor(options?: KeyvPostgresOptions | string);
-    get(key: string): Promise<any>;
-    getMany(keys: string[]): Promise<any[]>;
+    /**
+     * Initializes the database connection and ensures the table schema exists.
+     * Called from the constructor; errors are emitted rather than thrown.
+     */
+    private init;
+    /**
+     * Get the namespace for the adapter. If undefined, no namespace prefix is applied.
+     */
+    get namespace(): string | undefined;
+    /**
+     * Set the namespace for the adapter. Used for key prefixing and scoping operations like `clear()`.
+     */
+    set namespace(value: string | undefined);
+    /**
+     * Get the PostgreSQL connection URI.
+     * @default 'postgresql://localhost:5432'
+     */
+    get uri(): string;
+    /**
+     * Set the PostgreSQL connection URI.
+     */
+    set uri(value: string);
+    /**
+     * Get the table name used for storage.
+     * @default 'keyv'
+     */
+    get table(): string;
+    /**
+     * Set the table name used for storage.
+     */
+    set table(value: string);
+    /**
+     * Get the maximum key length (VARCHAR length) for the key column.
+     * @default 255
+     */
+    get keyLength(): number;
+    /**
+     * Set the maximum key length (VARCHAR length) for the key column.
+     */
+    set keyLength(value: number);
+    /**
+     * Get the maximum namespace length (VARCHAR length) for the namespace column.
+     * @default 255
+     */
+    get namespaceLength(): number;
+    /**
+     * Set the maximum namespace length (VARCHAR length) for the namespace column.
+     */
+    set namespaceLength(value: number);
+    /**
+     * Get the PostgreSQL schema name.
+     * @default 'public'
+     */
+    get schema(): string;
+    /**
+     * Set the PostgreSQL schema name.
+     */
+    set schema(value: string);
+    /**
+     * Get the SSL configuration for the PostgreSQL connection.
+     * @default undefined
+     */
+    get ssl(): boolean | ConnectionOptions | undefined;
+    /**
+     * Set the SSL configuration for the PostgreSQL connection.
+     */
+    set ssl(value: boolean | ConnectionOptions | undefined);
+    /**
+     * Get the number of rows to fetch per iteration batch.
+     * @default 10
+     */
+    get iterationLimit(): number;
+    /**
+     * Set the number of rows to fetch per iteration batch.
+     */
+    set iterationLimit(value: number);
+    /**
+     * Get whether to use a PostgreSQL unlogged table (faster writes, no WAL, data lost on crash).
+     * @default false
+     */
+    get useUnloggedTable(): boolean;
+    /**
+     * Set whether to use a PostgreSQL unlogged table.
+     */
+    set useUnloggedTable(value: boolean);
+    /**
+     * 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(): number;
+    /**
+     * Set the interval in milliseconds between automatic expired-entry cleanup runs.
+     * Setting to 0 disables the automatic cleanup.
+     */
+    set clearExpiredInterval(value: number);
+    /**
+     * Get the options for the adapter. This is required by the KeyvStoreAdapter interface.
+     */
+    get opts(): any;
+    /**
+     * Set the options for the adapter.
+     */
+    set opts(options: KeyvPostgresOptions);
+    /**
+     * Gets a value by key.
+     * @param key - The key to retrieve.
+     * @returns The value associated with the key, or `undefined` if not found.
+     */
+    get<Value>(key: string): Promise<Value | undefined>;
+    /**
+     * 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.
+     */
+    getMany<Value>(keys: string[]): Promise<Array<Value | undefined>>;
+    /**
+     * 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.
+     */
     set(key: string, value: any): Promise<void>;
+    /**
+     * Sets multiple key-value pairs at once using PostgreSQL `UNNEST` for efficient bulk operations.
+     * @param entries - An array of key-value entry objects.
+     */
     setMany(entries: KeyvEntry[]): Promise<void>;
+    /**
+     * Deletes a key from the store.
+     * @param key - The key to delete.
+     * @returns `true` if the key existed and was deleted, `false` otherwise.
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * 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.
+     */
     deleteMany(keys: string[]): Promise<boolean>;
+    /**
+     * Clears all keys in the current namespace. If no namespace is set, all keys are removed.
+     */
     clear(): Promise<void>;
-    iterator(namespace?: string): AsyncGenerator<string[], void, unknown>;
-    has(key: string): Promise<any>;
-    connect(): Promise<(sql: string, values?: any) => Promise<any[]>>;
+    /**
+     * Utility helper method to delete all expired entries from the store where the `expires` column is less than the current timestamp.
+     */
+    clearExpired(): Promise<void>;
+    /**
+     * 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.
+     */
+    iterator(namespace?: string): AsyncGenerator<[string, string], void, unknown>;
+    /**
+     * Checks whether a key exists in the store.
+     * @param key - The key to check.
+     * @returns `true` if the key exists, `false` otherwise.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    hasMany(keys: string[]): Promise<boolean[]>;
+    /**
+     * Establishes a connection to the PostgreSQL database via the connection pool.
+     * @returns A query function that executes SQL statements and returns result rows.
+     */
+    private connect;
+    /**
+     * Disconnects from the PostgreSQL database and releases the connection pool.
+     * Also stops the automatic expired-entry cleanup interval if running.
+     */
     disconnect(): Promise<void>;
+    /**
+     * 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".
+     */
+    private removeKeyPrefix;
+    /**
+     * Returns the namespace value for SQL parameters. Returns null when no namespace is set.
+     */
+    private getNamespaceValue;
+    /**
+     * 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.
+     */
+    private getExpiresFromValue;
+    /**
+     * Starts (or restarts) the automatic expired-entry cleanup interval.
+     * If the interval is 0 or negative, any existing timer is stopped.
+     */
+    private startClearExpiredTimer;
+    /**
+     * Stops the automatic expired-entry cleanup interval if running.
+     */
+    private stopClearExpiredTimer;
+    private setOptions;
 }
+/**
+ * Helper function to create a Keyv instance with KeyvPostgres as the storage adapter.
+ * @param options - Optional {@link KeyvPostgresOptions} configuration object.
+ * @returns A new Keyv instance backed by PostgreSQL.
+ */
 declare const createKeyv: (options?: KeyvPostgresOptions) => Keyv<any>;
 
 export { KeyvPostgres, type KeyvPostgresOptions, createKeyv, KeyvPostgres as default };