@keyv/mongo 3.1.0 → 6.0.0-alpha.2

package/dist/index.d.cts

@@ -1,20 +1,16 @@
-import EventEmitter from 'node:events';
-import { KeyvStoreAdapter, StoredData } from 'keyv';
-import { ReadPreference, GridFSBucket, Collection, Db, MongoClient } from 'mongodb';
+import { Hookified } from 'hookified';
+import Keyv, { KeyvStoreAdapter, StoredData } from 'keyv';
+import { GridFSBucket, Collection, Db, MongoClient, ReadPreference, MongoClientOptions } from 'mongodb';
 
 type Options = {
-    [key: string]: unknown;
-    url?: string | undefined;
+    url?: string;
     collection?: string;
     namespace?: string;
-    serialize?: any;
-    deserialize?: any;
     useGridFS?: boolean;
     uri?: string;
-    dialect?: string;
     db?: string;
     readPreference?: ReadPreference;
-};
+} & MongoClientOptions;
 type KeyvMongoOptions = Options | string;
 type KeyvMongoConnect = {
     bucket?: GridFSBucket;
@@ -23,23 +19,212 @@ type KeyvMongoConnect = {
     mongoClient: MongoClient;
 };
 
-declare class KeyvMongo extends EventEmitter implements KeyvStoreAdapter {
-    ttlSupport: boolean;
-    opts: Options;
+/**
+ * MongoDB storage adapter for Keyv.
+ * Provides a persistent key-value store using MongoDB as the backend.
+ */
+declare class KeyvMongo extends Hookified implements KeyvStoreAdapter {
+    /**
+     * The MongoDB connection URI.
+     * @default 'mongodb://127.0.0.1:27017'
+     */
+    private _url;
+    /**
+     * The collection name used for storage.
+     * @default 'keyv'
+     */
+    private _collection;
+    /**
+     * The namespace used to prefix keys for multi-tenant separation.
+     */
+    private _namespace?;
+    /**
+     * Whether to use GridFS for storing values.
+     * @default false
+     */
+    private _useGridFS;
+    /**
+     * The database name for the MongoDB connection.
+     * @default undefined
+     */
+    private _db?;
+    /**
+     * The MongoDB read preference for GridFS operations.
+     * @default undefined
+     */
+    private _readPreference?;
+    /**
+     * Additional MongoClientOptions passed through to the MongoDB driver.
+     */
+    private _mongoOptions;
+    /**
+     * Promise that resolves to the MongoDB connection details.
+     */
     connect: Promise<KeyvMongoConnect>;
-    namespace?: string;
+    /**
+     * Get the MongoDB connection URI.
+     * @default 'mongodb://127.0.0.1:27017'
+     */
+    get url(): string;
+    /**
+     * Set the MongoDB connection URI.
+     */
+    set url(value: string);
+    /**
+     * Get the collection name used for storage.
+     * @default 'keyv'
+     */
+    get collection(): string;
+    /**
+     * Set the collection name used for storage.
+     */
+    set collection(value: string);
+    /**
+     * 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 whether GridFS is used for storing values. This is read-only and can only be set via the constructor
+     * because the MongoDB connection shape differs between GridFS and standard modes.
+     * @default false
+     */
+    get useGridFS(): boolean;
+    /**
+     * Get the database name for the MongoDB connection.
+     */
+    get db(): string | undefined;
+    /**
+     * Set the database name for the MongoDB connection.
+     */
+    set db(value: string | undefined);
+    /**
+     * Get the MongoDB read preference for GridFS operations.
+     */
+    get readPreference(): ReadPreference | undefined;
+    /**
+     * Set the MongoDB read preference for GridFS operations.
+     */
+    set readPreference(value: ReadPreference | undefined);
+    /**
+     * Get the options for the adapter. This is provided for backward compatibility.
+     */
+    get opts(): any;
+    /**
+     * Creates a new KeyvMongo instance.
+     * @param url - Configuration options, connection URI string, or undefined for defaults.
+     * @param options - Additional configuration options that override the first parameter.
+     */
     constructor(url?: KeyvMongoOptions, options?: Options);
+    /**
+     * Get a value from the store by key. In GridFS mode, also updates the `lastAccessed` timestamp.
+     * @param key - The key to retrieve.
+     * @returns The stored value, or `undefined` if the key does not exist.
+     */
     get<Value>(key: string): Promise<StoredData<Value>>;
+    /**
+     * Get multiple values from the store at once. In standard mode, uses a single query with the `$in` operator.
+     * In GridFS mode, each key is fetched individually in parallel.
+     * @param keys - Array of keys to retrieve.
+     * @returns Array of values in the same order as the input keys. Missing keys return `undefined`.
+     */
     getMany<Value>(keys: string[]): Promise<StoredData<Value>[]>;
+    /**
+     * Set a value in the store.
+     * @param key - The key to set.
+     * @param value - The value to store.
+     * @param ttl - Time to live in milliseconds. If specified, the key will expire after this duration.
+     */
     set(key: string, value: any, ttl?: number): Promise<unknown>;
+    /**
+     * Set multiple values in the store at once. In standard mode, uses a single `bulkWrite` operation.
+     * In GridFS mode, each entry is set individually in parallel.
+     * @param entries - Array of entries to set. Each entry has a `key`, `value`, and optional `ttl` in milliseconds.
+     */
+    setMany(entries: Array<{
+        key: string;
+        value: any;
+        ttl?: number;
+    }>): Promise<void>;
+    /**
+     * Delete a key from the store.
+     * @param key - The key to delete.
+     * @returns `true` if the key was deleted, `false` if the key was not found.
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * Delete multiple keys from the store at once. In standard mode, uses a single query with the `$in` operator.
+     * In GridFS mode, all matching files are found and deleted in parallel.
+     * @param keys - Array of keys to delete.
+     * @returns `true` if any keys were deleted, `false` if none were found.
+     */
     deleteMany(keys: string[]): Promise<boolean>;
+    /**
+     * Delete all keys in the current namespace.
+     */
     clear(): Promise<void>;
+    /**
+     * Remove all expired files from GridFS. This method only works in GridFS mode
+     * and is a no-op that returns `false` in standard mode.
+     * @returns `true` if running in GridFS mode, `false` otherwise.
+     */
     clearExpired(): Promise<boolean>;
+    /**
+     * Remove all GridFS files that have not been accessed for the specified duration. This method only works
+     * in GridFS mode and is a no-op that returns `false` in standard mode.
+     * @param seconds - The number of seconds of inactivity after which files should be removed.
+     * @returns `true` if running in GridFS mode, `false` otherwise.
+     */
     clearUnusedFor(seconds: number): Promise<boolean>;
+    /**
+     * Iterate over all key-value pairs in the store matching the given namespace.
+     * @param namespace - The namespace to iterate over. When used through Keyv, this is passed automatically.
+     * @yields `[key, value]` pairs as an async generator.
+     */
     iterator(namespace?: string): AsyncGenerator<any[], void, void>;
+    /**
+     * Check if 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>;
+    /**
+     * Check if multiple keys exist in the store at once. Uses a single query with the `$in` operator.
+     * @param keys - Array of keys to check.
+     * @returns Array of booleans in the same order as the input keys.
+     */
+    hasMany(keys: string[]): Promise<boolean[]>;
+    /**
+     * Close the MongoDB connection.
+     */
     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 query filters.
+     * Returns empty string when no namespace is set.
+     */
+    private getNamespaceValue;
+    /**
+     * Extracts MongoDB driver options from the provided options, filtering out Keyv-specific properties.
+     */
+    private extractMongoOptions;
+    /**
+     * Initializes the MongoDB connection and sets up indexes.
+     */
+    private initConnection;
 }
+/**
+ * Helper function to create a Keyv instance with KeyvMongo as the storage adapter.
+ * @param options - Optional {@link KeyvMongoOptions} configuration object or connection URI string.
+ * @returns A new Keyv instance backed by MongoDB.
+ */
+declare const createKeyv: (options?: KeyvMongoOptions) => Keyv<any>;
 
-export { KeyvMongo, type KeyvMongoOptions, KeyvMongo as default };
+export { KeyvMongo, type KeyvMongoOptions, createKeyv, KeyvMongo as default };

package/dist/index.d.ts

@@ -1,20 +1,16 @@
-import EventEmitter from 'node:events';
-import { KeyvStoreAdapter, StoredData } from 'keyv';
-import { ReadPreference, GridFSBucket, Collection, Db, MongoClient } from 'mongodb';
+import { Hookified } from 'hookified';
+import Keyv, { KeyvStoreAdapter, StoredData } from 'keyv';
+import { GridFSBucket, Collection, Db, MongoClient, ReadPreference, MongoClientOptions } from 'mongodb';
 
 type Options = {
-    [key: string]: unknown;
-    url?: string | undefined;
+    url?: string;
     collection?: string;
     namespace?: string;
-    serialize?: any;
-    deserialize?: any;
     useGridFS?: boolean;
     uri?: string;
-    dialect?: string;
     db?: string;
     readPreference?: ReadPreference;
-};
+} & MongoClientOptions;
 type KeyvMongoOptions = Options | string;
 type KeyvMongoConnect = {
     bucket?: GridFSBucket;
@@ -23,23 +19,212 @@ type KeyvMongoConnect = {
     mongoClient: MongoClient;
 };
 
-declare class KeyvMongo extends EventEmitter implements KeyvStoreAdapter {
-    ttlSupport: boolean;
-    opts: Options;
+/**
+ * MongoDB storage adapter for Keyv.
+ * Provides a persistent key-value store using MongoDB as the backend.
+ */
+declare class KeyvMongo extends Hookified implements KeyvStoreAdapter {
+    /**
+     * The MongoDB connection URI.
+     * @default 'mongodb://127.0.0.1:27017'
+     */
+    private _url;
+    /**
+     * The collection name used for storage.
+     * @default 'keyv'
+     */
+    private _collection;
+    /**
+     * The namespace used to prefix keys for multi-tenant separation.
+     */
+    private _namespace?;
+    /**
+     * Whether to use GridFS for storing values.
+     * @default false
+     */
+    private _useGridFS;
+    /**
+     * The database name for the MongoDB connection.
+     * @default undefined
+     */
+    private _db?;
+    /**
+     * The MongoDB read preference for GridFS operations.
+     * @default undefined
+     */
+    private _readPreference?;
+    /**
+     * Additional MongoClientOptions passed through to the MongoDB driver.
+     */
+    private _mongoOptions;
+    /**
+     * Promise that resolves to the MongoDB connection details.
+     */
     connect: Promise<KeyvMongoConnect>;
-    namespace?: string;
+    /**
+     * Get the MongoDB connection URI.
+     * @default 'mongodb://127.0.0.1:27017'
+     */
+    get url(): string;
+    /**
+     * Set the MongoDB connection URI.
+     */
+    set url(value: string);
+    /**
+     * Get the collection name used for storage.
+     * @default 'keyv'
+     */
+    get collection(): string;
+    /**
+     * Set the collection name used for storage.
+     */
+    set collection(value: string);
+    /**
+     * 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 whether GridFS is used for storing values. This is read-only and can only be set via the constructor
+     * because the MongoDB connection shape differs between GridFS and standard modes.
+     * @default false
+     */
+    get useGridFS(): boolean;
+    /**
+     * Get the database name for the MongoDB connection.
+     */
+    get db(): string | undefined;
+    /**
+     * Set the database name for the MongoDB connection.
+     */
+    set db(value: string | undefined);
+    /**
+     * Get the MongoDB read preference for GridFS operations.
+     */
+    get readPreference(): ReadPreference | undefined;
+    /**
+     * Set the MongoDB read preference for GridFS operations.
+     */
+    set readPreference(value: ReadPreference | undefined);
+    /**
+     * Get the options for the adapter. This is provided for backward compatibility.
+     */
+    get opts(): any;
+    /**
+     * Creates a new KeyvMongo instance.
+     * @param url - Configuration options, connection URI string, or undefined for defaults.
+     * @param options - Additional configuration options that override the first parameter.
+     */
     constructor(url?: KeyvMongoOptions, options?: Options);
+    /**
+     * Get a value from the store by key. In GridFS mode, also updates the `lastAccessed` timestamp.
+     * @param key - The key to retrieve.
+     * @returns The stored value, or `undefined` if the key does not exist.
+     */
     get<Value>(key: string): Promise<StoredData<Value>>;
+    /**
+     * Get multiple values from the store at once. In standard mode, uses a single query with the `$in` operator.
+     * In GridFS mode, each key is fetched individually in parallel.
+     * @param keys - Array of keys to retrieve.
+     * @returns Array of values in the same order as the input keys. Missing keys return `undefined`.
+     */
     getMany<Value>(keys: string[]): Promise<StoredData<Value>[]>;
+    /**
+     * Set a value in the store.
+     * @param key - The key to set.
+     * @param value - The value to store.
+     * @param ttl - Time to live in milliseconds. If specified, the key will expire after this duration.
+     */
     set(key: string, value: any, ttl?: number): Promise<unknown>;
+    /**
+     * Set multiple values in the store at once. In standard mode, uses a single `bulkWrite` operation.
+     * In GridFS mode, each entry is set individually in parallel.
+     * @param entries - Array of entries to set. Each entry has a `key`, `value`, and optional `ttl` in milliseconds.
+     */
+    setMany(entries: Array<{
+        key: string;
+        value: any;
+        ttl?: number;
+    }>): Promise<void>;
+    /**
+     * Delete a key from the store.
+     * @param key - The key to delete.
+     * @returns `true` if the key was deleted, `false` if the key was not found.
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * Delete multiple keys from the store at once. In standard mode, uses a single query with the `$in` operator.
+     * In GridFS mode, all matching files are found and deleted in parallel.
+     * @param keys - Array of keys to delete.
+     * @returns `true` if any keys were deleted, `false` if none were found.
+     */
     deleteMany(keys: string[]): Promise<boolean>;
+    /**
+     * Delete all keys in the current namespace.
+     */
     clear(): Promise<void>;
+    /**
+     * Remove all expired files from GridFS. This method only works in GridFS mode
+     * and is a no-op that returns `false` in standard mode.
+     * @returns `true` if running in GridFS mode, `false` otherwise.
+     */
     clearExpired(): Promise<boolean>;
+    /**
+     * Remove all GridFS files that have not been accessed for the specified duration. This method only works
+     * in GridFS mode and is a no-op that returns `false` in standard mode.
+     * @param seconds - The number of seconds of inactivity after which files should be removed.
+     * @returns `true` if running in GridFS mode, `false` otherwise.
+     */
     clearUnusedFor(seconds: number): Promise<boolean>;
+    /**
+     * Iterate over all key-value pairs in the store matching the given namespace.
+     * @param namespace - The namespace to iterate over. When used through Keyv, this is passed automatically.
+     * @yields `[key, value]` pairs as an async generator.
+     */
     iterator(namespace?: string): AsyncGenerator<any[], void, void>;
+    /**
+     * Check if 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>;
+    /**
+     * Check if multiple keys exist in the store at once. Uses a single query with the `$in` operator.
+     * @param keys - Array of keys to check.
+     * @returns Array of booleans in the same order as the input keys.
+     */
+    hasMany(keys: string[]): Promise<boolean[]>;
+    /**
+     * Close the MongoDB connection.
+     */
     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 query filters.
+     * Returns empty string when no namespace is set.
+     */
+    private getNamespaceValue;
+    /**
+     * Extracts MongoDB driver options from the provided options, filtering out Keyv-specific properties.
+     */
+    private extractMongoOptions;
+    /**
+     * Initializes the MongoDB connection and sets up indexes.
+     */
+    private initConnection;
 }
+/**
+ * Helper function to create a Keyv instance with KeyvMongo as the storage adapter.
+ * @param options - Optional {@link KeyvMongoOptions} configuration object or connection URI string.
+ * @returns A new Keyv instance backed by MongoDB.
+ */
+declare const createKeyv: (options?: KeyvMongoOptions) => Keyv<any>;
 
-export { KeyvMongo, type KeyvMongoOptions, KeyvMongo as default };
+export { KeyvMongo, type KeyvMongoOptions, createKeyv, KeyvMongo as default };