@keyv/mongo 3.1.0 → 6.0.0-alpha.2

package/dist/index.js

@@ -1,108 +1,203 @@
 // src/index.ts
 import { Buffer } from "buffer";
-import EventEmitter from "events";
+import { Hookified } from "hookified";
+import Keyv from "keyv";
 import {
   GridFSBucket,
   MongoClient as mongoClient
 } from "mongodb";
-var keyvMongoKeys = /* @__PURE__ */ new Set([
-  "url",
-  "collection",
-  "namespace",
-  "serialize",
-  "deserialize",
-  "uri",
-  "useGridFS",
-  "dialect",
-  "db"
-]);
-var KeyvMongo = class extends EventEmitter {
-  ttlSupport = false;
-  opts;
+var KeyvMongo = class extends Hookified {
+  /**
+   * The MongoDB connection URI.
+   * @default 'mongodb://127.0.0.1:27017'
+   */
+  _url = "mongodb://127.0.0.1:27017";
+  /**
+   * The collection name used for storage.
+   * @default 'keyv'
+   */
+  _collection = "keyv";
+  /**
+   * The namespace used to prefix keys for multi-tenant separation.
+   */
+  _namespace;
+  /**
+   * Whether to use GridFS for storing values.
+   * @default false
+   */
+  _useGridFS = false;
+  /**
+   * The database name for the MongoDB connection.
+   * @default undefined
+   */
+  _db;
+  /**
+   * The MongoDB read preference for GridFS operations.
+   * @default undefined
+   */
+  _readPreference;
+  /**
+   * Additional MongoClientOptions passed through to the MongoDB driver.
+   */
+  _mongoOptions = {};
+  /**
+   * Promise that resolves to the MongoDB connection details.
+   */
   connect;
-  namespace;
+  /**
+   * Get the MongoDB connection URI.
+   * @default 'mongodb://127.0.0.1:27017'
+   */
+  get url() {
+    return this._url;
+  }
+  /**
+   * Set the MongoDB connection URI.
+   */
+  set url(value) {
+    this._url = value;
+  }
+  /**
+   * Get the collection name used for storage.
+   * @default 'keyv'
+   */
+  get collection() {
+    return this._collection;
+  }
+  /**
+   * Set the collection name used for storage.
+   */
+  set collection(value) {
+    this._collection = value;
+  }
+  /**
+   * 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 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() {
+    return this._useGridFS;
+  }
+  /**
+   * Get the database name for the MongoDB connection.
+   */
+  get db() {
+    return this._db;
+  }
+  /**
+   * Set the database name for the MongoDB connection.
+   */
+  set db(value) {
+    this._db = value;
+  }
+  /**
+   * Get the MongoDB read preference for GridFS operations.
+   */
+  get readPreference() {
+    return this._readPreference;
+  }
+  /**
+   * Set the MongoDB read preference for GridFS operations.
+   */
+  set readPreference(value) {
+    this._readPreference = value;
+  }
+  /**
+   * Get the options for the adapter. This is provided for backward compatibility.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: type format
+  get opts() {
+    return {
+      url: this._url,
+      uri: this._url,
+      collection: this._collection,
+      useGridFS: this._useGridFS,
+      db: this._db,
+      readPreference: this._readPreference,
+      dialect: "mongo",
+      ...this._mongoOptions
+    };
+  }
+  /**
+   * 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, options) {
-    super();
-    url ??= {};
+    super({ throwOnEmptyListeners: false });
+    let mergedOptions = {};
     if (typeof url === "string") {
-      url = { url };
+      this._url = url;
+      if (options) {
+        mergedOptions = options;
+      }
+    } else if (url) {
+      mergedOptions = { ...url, ...options };
+    } else if (options) {
+      mergedOptions = options;
     }
-    if (url.uri) {
-      url = { url: url.uri, ...url };
+    if (mergedOptions.uri !== void 0) {
+      this._url = mergedOptions.uri;
     }
-    this.opts = {
-      url: "mongodb://127.0.0.1:27017",
-      collection: "keyv",
-      ...url,
-      ...options
-    };
-    delete this.opts.emitErrors;
-    const mongoOptions = Object.fromEntries(
-      Object.entries(this.opts).filter(([k]) => !keyvMongoKeys.has(k))
-    );
-    this.opts = Object.fromEntries(
-      Object.entries(this.opts).filter(([k]) => keyvMongoKeys.has(k))
-    );
-    this.connect = new Promise(async (resolve, _reject) => {
-      try {
-        let url2 = "";
-        if (this.opts.url) {
-          url2 = this.opts.url;
-        }
-        const client = new mongoClient(url2, mongoOptions);
-        await client.connect();
-        const database = client.db(this.opts.db);
-        if (this.opts.useGridFS) {
-          const bucket = new GridFSBucket(database, {
-            readPreference: this.opts.readPreference,
-            bucketName: this.opts.collection
-          });
-          const store = database.collection(`${this.opts.collection}.files`);
-          await store.createIndex({ uploadDate: -1 });
-          await store.createIndex({ "metadata.expiresAt": 1 });
-          await store.createIndex({ "metadata.lastAccessed": 1 });
-          await store.createIndex({ "metadata.filename": 1 });
-          resolve({
-            bucket,
-            store,
-            db: database,
-            mongoClient: client
-          });
-        } else {
-          let collection = "keyv";
-          if (this.opts.collection) {
-            collection = this.opts.collection;
-          }
-          const store = database.collection(collection);
-          await store.createIndex(
-            { key: 1 },
-            { unique: true, background: true }
-          );
-          await store.createIndex(
-            { expiresAt: 1 },
-            { expireAfterSeconds: 0, background: true }
-          );
-          resolve({ store, mongoClient: client });
-        }
-      } catch (error) {
-        this.emit("error", error);
-      }
-    });
+    if (mergedOptions.url !== void 0) {
+      this._url = mergedOptions.url;
+    }
+    if (mergedOptions.collection !== void 0) {
+      this._collection = mergedOptions.collection;
+    }
+    if (mergedOptions.namespace !== void 0) {
+      this._namespace = mergedOptions.namespace;
+    }
+    if (mergedOptions.useGridFS !== void 0) {
+      this._useGridFS = mergedOptions.useGridFS;
+    }
+    if (mergedOptions.db !== void 0) {
+      this._db = mergedOptions.db;
+    }
+    if (mergedOptions.readPreference !== void 0) {
+      this._readPreference = mergedOptions.readPreference;
+    }
+    this._mongoOptions = this.extractMongoOptions(mergedOptions);
+    this.connect = this.initConnection();
   }
+  /**
+   * 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.
+   */
   async get(key) {
     const client = await this.connect;
-    if (this.opts.useGridFS) {
+    const strippedKey = this.removeKeyPrefix(key);
+    const ns = this.getNamespaceValue();
+    if (this._useGridFS) {
+      const file = await client.store.findOne({
+        filename: { $eq: strippedKey },
+        "metadata.namespace": { $eq: ns }
+      });
+      if (!file) {
+        return void 0;
+      }
       await client.store.updateOne(
-        {
-          filename: String(key)
-        },
+        { _id: { $eq: file._id } },
         {
           $set: {
             "metadata.lastAccessed": /* @__PURE__ */ new Date()
           }
         }
       );
-      const stream = client.bucket.openDownloadStreamByName(key);
+      const stream = client.bucket.openDownloadStream(file._id);
       return new Promise((resolve) => {
         const resp = [];
         stream.on("error", () => {
@@ -117,14 +212,23 @@ var KeyvMongo = class extends EventEmitter {
         });
       });
     }
-    const document = await client.store.findOne({ key: { $eq: key } });
+    const document = await client.store.findOne({
+      key: { $eq: strippedKey },
+      namespace: { $eq: ns }
+    });
     if (!document) {
       return void 0;
     }
     return document.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`.
+   */
   async getMany(keys) {
-    if (this.opts.useGridFS) {
+    if (this._useGridFS) {
       const promises = [];
       for (const key of keys) {
         promises.push(this.get(key));
@@ -137,30 +241,38 @@ var KeyvMongo = class extends EventEmitter {
       return data;
     }
     const connect = await this.connect;
-    const values = (
-      // @ts-expect-error need to fix this `s`
-      await connect.store.s.db.collection(this.opts.collection).find({ key: { $in: keys } }).project({ _id: 0, value: 1, key: 1 }).toArray()
-    );
-    const results = [...keys];
-    let i = 0;
-    for (const key of keys) {
+    const strippedKeys = keys.map((k) => this.removeKeyPrefix(k));
+    const ns = this.getNamespaceValue();
+    const values = await connect.store.find({ key: { $in: strippedKeys }, namespace: { $eq: ns } }).project({ _id: 0, value: 1, key: 1 }).toArray();
+    const results = [];
+    for (const key of strippedKeys) {
       const rowIndex = values.findIndex(
         (row) => row.key === key
       );
-      results[i] = rowIndex > -1 ? values[rowIndex].value : void 0;
-      i++;
+      results.push(
+        rowIndex > -1 ? values[rowIndex].value : void 0
+      );
     }
     return results;
   }
+  /**
+   * 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.
+   */
   // biome-ignore lint/suspicious/noExplicitAny: type format
   async set(key, value, ttl) {
     const expiresAt = typeof ttl === "number" ? new Date(Date.now() + ttl) : null;
-    if (this.opts.useGridFS) {
+    const strippedKey = this.removeKeyPrefix(key);
+    const ns = this.getNamespaceValue();
+    if (this._useGridFS) {
       const client2 = await this.connect;
-      const stream = client2.bucket.openUploadStream(key, {
+      const stream = client2.bucket.openUploadStream(strippedKey, {
         metadata: {
           expiresAt,
-          lastAccessed: /* @__PURE__ */ new Date()
+          lastAccessed: /* @__PURE__ */ new Date(),
+          namespace: ns
         }
       });
       return new Promise((resolve) => {
@@ -172,40 +284,96 @@ var KeyvMongo = class extends EventEmitter {
     }
     const client = await this.connect;
     await client.store.updateOne(
-      { key: { $eq: key } },
-      { $set: { key, value, expiresAt } },
+      { key: { $eq: strippedKey }, namespace: { $eq: ns } },
+      { $set: { key: strippedKey, value, namespace: ns, expiresAt } },
       { upsert: true }
     );
   }
+  /**
+   * 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.
+   */
+  async setMany(entries) {
+    if (this._useGridFS) {
+      await Promise.all(
+        entries.map(async ({ key, value, ttl }) => this.set(key, value, ttl))
+      );
+      return;
+    }
+    const client = await this.connect;
+    const ns = this.getNamespaceValue();
+    const operations = entries.map(({ key, value, ttl }) => {
+      const strippedKey = this.removeKeyPrefix(key);
+      const expiresAt = typeof ttl === "number" ? new Date(Date.now() + ttl) : null;
+      return {
+        updateOne: {
+          filter: { key: { $eq: strippedKey }, namespace: { $eq: ns } },
+          update: {
+            $set: { key: strippedKey, value, namespace: ns, expiresAt }
+          },
+          upsert: true
+        }
+      };
+    });
+    await client.store.bulkWrite(operations);
+  }
+  /**
+   * 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.
+   */
   async delete(key) {
     if (typeof key !== "string") {
       return false;
     }
     const client = await this.connect;
-    if (this.opts.useGridFS) {
+    const strippedKey = this.removeKeyPrefix(key);
+    const ns = this.getNamespaceValue();
+    if (this._useGridFS) {
       try {
         const connection = client.db;
         const bucket = new GridFSBucket(connection, {
-          bucketName: this.opts.collection
+          bucketName: this._collection
         });
-        const files = await bucket.find({ filename: key }).toArray();
+        const files = await bucket.find({
+          filename: { $eq: strippedKey },
+          "metadata.namespace": { $eq: ns }
+        }).toArray();
+        if (files.length === 0) {
+          return false;
+        }
         await client.bucket.delete(files[0]._id);
         return true;
       } catch {
         return false;
       }
     }
-    const object = await client.store.deleteOne({ key: { $eq: key } });
+    const object = await client.store.deleteOne({
+      key: { $eq: strippedKey },
+      namespace: { $eq: ns }
+    });
     return object.deletedCount > 0;
   }
+  /**
+   * 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.
+   */
   async deleteMany(keys) {
     const client = await this.connect;
-    if (this.opts.useGridFS) {
+    const strippedKeys = keys.map((k) => this.removeKeyPrefix(k));
+    const ns = this.getNamespaceValue();
+    if (this._useGridFS) {
       const connection = client.db;
       const bucket = new GridFSBucket(connection, {
-        bucketName: this.opts.collection
+        bucketName: this._collection
       });
-      const files = await bucket.find({ filename: { $in: keys } }).toArray();
+      const files = await bucket.find({
+        filename: { $in: strippedKeys },
+        "metadata.namespace": { $eq: ns }
+      }).toArray();
       if (files.length === 0) {
         return false;
       }
@@ -215,31 +383,56 @@ var KeyvMongo = class extends EventEmitter {
       );
       return true;
     }
-    const object = await client.store.deleteMany({ key: { $in: keys } });
+    const object = await client.store.deleteMany({
+      key: { $in: strippedKeys },
+      namespace: { $eq: ns }
+    });
     return object.deletedCount > 0;
   }
+  /**
+   * Delete all keys in the current namespace.
+   */
   async clear() {
     const client = await this.connect;
-    if (this.opts.useGridFS) {
-      await client.bucket.drop();
+    const ns = this.getNamespaceValue();
+    if (this._useGridFS) {
+      const connection = client.db;
+      const bucket = new GridFSBucket(connection, {
+        bucketName: this._collection
+      });
+      const files = await bucket.find({
+        "metadata.namespace": { $eq: ns }
+      }).toArray();
+      await Promise.all(
+        // biome-ignore lint/style/noNonNullAssertion: need to fix
+        files.map(async (file) => client.bucket.delete(file._id))
+      );
+      return;
     }
     await client.store.deleteMany({
-      key: { $regex: this.namespace ? `^${this.namespace}:*` : "" }
+      namespace: { $eq: ns }
     });
   }
+  /**
+   * 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.
+   */
   async clearExpired() {
-    if (!this.opts.useGridFS) {
+    if (!this._useGridFS) {
       return false;
     }
+    const ns = this.getNamespaceValue();
     return this.connect.then(async (client) => {
       const connection = client.db;
       const bucket = new GridFSBucket(connection, {
-        bucketName: this.opts.collection
+        bucketName: this._collection
       });
       return bucket.find({
         "metadata.expiresAt": {
           $lte: new Date(Date.now())
-        }
+        },
+        "metadata.namespace": { $eq: ns }
       }).toArray().then(
         async (expiredFiles) => Promise.all(
           // biome-ignore lint/style/noNonNullAssertion: need to fix
@@ -248,19 +441,27 @@ var KeyvMongo = class extends EventEmitter {
       );
     });
   }
+  /**
+   * 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.
+   */
   async clearUnusedFor(seconds) {
-    if (!this.opts.useGridFS) {
+    if (!this._useGridFS) {
       return false;
     }
+    const ns = this.getNamespaceValue();
     const client = await this.connect;
     const connection = client.db;
     const bucket = new GridFSBucket(connection, {
-      bucketName: this.opts.collection
+      bucketName: this._collection
     });
     const lastAccessedFiles = await bucket.find({
       "metadata.lastAccessed": {
         $lte: new Date(Date.now() - seconds * 1e3)
-      }
+      },
+      "metadata.namespace": { $eq: ns }
     }).toArray();
     await Promise.all(
       // biome-ignore lint/style/noNonNullAssertion: need to fix
@@ -268,33 +469,193 @@ var KeyvMongo = class extends EventEmitter {
     );
     return true;
   }
+  /**
+   * 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.
+   */
   async *iterator(namespace) {
     const client = await this.connect;
-    const regexp = new RegExp(`^${namespace ? namespace + ":" : ".*"}`);
-    const iterator = this.opts.useGridFS ? client.store.find({
-      filename: regexp
-    }).map(async (x) => [
-      x.filename,
-      await this.get(x.filename)
-    ]) : client.store.find({
-      key: regexp
-    }).map((x) => [x.key, x.value]);
+    const namespaceValue = namespace ?? "";
+    if (this._useGridFS) {
+      const gridIterator = client.store.find({ "metadata.namespace": { $eq: namespaceValue } }).map(async (x) => {
+        const prefixedKey = namespace ? `${namespace}:${x.filename}` : x.filename;
+        const stream = client.bucket.openDownloadStream(x._id);
+        const data = await new Promise((resolve) => {
+          const resp = [];
+          stream.on("error", () => {
+            resolve(void 0);
+          });
+          stream.on("end", () => {
+            resolve(Buffer.concat(resp).toString("utf8"));
+          });
+          stream.on("data", (chunk) => {
+            resp.push(chunk);
+          });
+        });
+        return [prefixedKey, data];
+      });
+      yield* gridIterator;
+      return;
+    }
+    const iterator = client.store.find({ namespace: { $eq: namespaceValue } }).map((x) => {
+      const prefixedKey = namespace ? `${namespace}:${x.key}` : x.key;
+      return [prefixedKey, x.value];
+    });
     yield* iterator;
   }
+  /**
+   * Check if a key exists in the store.
+   * @param key - The key to check.
+   * @returns `true` if the key exists, `false` otherwise.
+   */
   async has(key) {
     const client = await this.connect;
-    const filter = { [this.opts.useGridFS ? "filename" : "key"]: { $eq: key } };
-    const document = await client.store.count(filter);
+    const strippedKey = this.removeKeyPrefix(key);
+    const ns = this.getNamespaceValue();
+    if (this._useGridFS) {
+      const document2 = await client.store.count({
+        filename: { $eq: strippedKey },
+        "metadata.namespace": { $eq: ns }
+      });
+      return document2 !== 0;
+    }
+    const document = await client.store.count({
+      key: { $eq: strippedKey },
+      namespace: { $eq: ns }
+    });
     return document !== 0;
   }
+  /**
+   * 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.
+   */
+  async hasMany(keys) {
+    const client = await this.connect;
+    const strippedKeys = keys.map((k) => this.removeKeyPrefix(k));
+    const ns = this.getNamespaceValue();
+    if (this._useGridFS) {
+      const files = await client.store.find({
+        filename: { $in: strippedKeys },
+        "metadata.namespace": { $eq: ns }
+      }).project({ filename: 1 }).toArray();
+      const existingKeys2 = new Set(files.map((f) => f.filename));
+      return strippedKeys.map((key) => existingKeys2.has(key));
+    }
+    const docs = await client.store.find({
+      key: { $in: strippedKeys },
+      namespace: { $eq: ns }
+    }).project({ key: 1 }).toArray();
+    const existingKeys = new Set(docs.map((d) => d.key));
+    return strippedKeys.map((key) => existingKeys.has(key));
+  }
+  /**
+   * Close the MongoDB connection.
+   */
   async disconnect() {
     const client = await this.connect;
     await client.mongoClient.close();
   }
+  /**
+   * 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 query filters.
+   * Returns empty string when no namespace is set.
+   */
+  getNamespaceValue() {
+    return this._namespace ?? "";
+  }
+  /**
+   * Extracts MongoDB driver options from the provided options, filtering out Keyv-specific properties.
+   */
+  extractMongoOptions(options) {
+    const keyvKeys = /* @__PURE__ */ new Set([
+      "url",
+      "collection",
+      "namespace",
+      "serialize",
+      "deserialize",
+      "uri",
+      "useGridFS",
+      "dialect",
+      "db",
+      "readPreference",
+      "emitErrors"
+    ]);
+    const mongoOptions = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (!keyvKeys.has(key)) {
+        mongoOptions[key] = value;
+      }
+    }
+    return mongoOptions;
+  }
+  /**
+   * Initializes the MongoDB connection and sets up indexes.
+   */
+  initConnection() {
+    return new Promise(async (resolve, _reject) => {
+      try {
+        const client = new mongoClient(this._url, this._mongoOptions);
+        await client.connect();
+        const database = client.db(this._db);
+        if (this._useGridFS) {
+          const bucket = new GridFSBucket(database, {
+            readPreference: this._readPreference,
+            bucketName: this._collection
+          });
+          const store = database.collection(`${this._collection}.files`);
+          await store.createIndex({ uploadDate: -1 });
+          await store.createIndex({ "metadata.expiresAt": 1 });
+          await store.createIndex({ "metadata.lastAccessed": 1 });
+          await store.createIndex({ "metadata.filename": 1 });
+          await store.createIndex({ "metadata.namespace": 1 });
+          resolve({
+            bucket,
+            store,
+            db: database,
+            mongoClient: client
+          });
+        } else {
+          const store = database.collection(this._collection);
+          try {
+            await store.dropIndex("key_1");
+          } catch {
+          }
+          await store.createIndex(
+            { key: 1, namespace: 1 },
+            { unique: true, background: true }
+          );
+          await store.createIndex(
+            { expiresAt: 1 },
+            { expireAfterSeconds: 0, background: true }
+          );
+          resolve({ store, mongoClient: client });
+        }
+      } catch (error) {
+        this.emit("error", error);
+      }
+    });
+  }
+};
+var createKeyv = (options) => {
+  const store = new KeyvMongo(options);
+  const namespace = typeof options === "object" ? options?.namespace : void 0;
+  return new Keyv({ store, namespace });
 };
 var index_default = KeyvMongo;
 export {
   KeyvMongo,
+  createKeyv,
   index_default as default
 };
 /* v8 ignore next -- @preserve */