@adobe/aio-lib-db 0.1.0-alpha.1

package/lib/DbClient.js

@@ -0,0 +1,114 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+const { dbStatsApi, listCollectionsApi, createCollectionApi } = require('./api/client')
+const DbCollection = require('./DbCollection')
+
+class DbClient {
+  /**
+   * @param {DbBase} db
+   * @hideconstructor
+   */
+  constructor(db) {
+    this.db = db
+    this._activeCursors = new Set()
+  }
+
+  /**
+   * Instantiates and returns a new DbClient object scoped to the configured namespace
+   *
+   * @static
+   * @constructs
+   * @param {DbBase} db
+   * @returns {Promise<DbClient>}
+   */
+  static async init(db) {
+    return new DbClient(db)
+  }
+
+  /**
+   * Get the statistics for the scoped database
+   *
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async dbStats() {
+    return dbStatsApi(this.db)
+  }
+
+  /**
+   * List the collections in the scoped database according to the filter if provided
+   *
+   * @param {Object=} filter
+   * @param {Object=} options
+   * @returns {Promise<Object[]>}
+   * @throws {DbError}
+   */
+  async listCollections(filter = {}, options = {}) {
+    return listCollectionsApi(this.db, filter, options)
+  }
+
+  /**
+   * Close all active cursors
+   *
+   * @returns {Promise<void>}
+   * @throws {DbError}
+   */
+  async close() {
+    for (const cursor of this._activeCursors) {
+      await cursor.close()
+    }
+  }
+
+  /**
+   * Gets the collection with the given name from the scoped database
+   *
+   * @param {string} name
+   * @returns {DbCollection}
+   */
+  collection(name) {
+    return DbCollection.init(name, this.db, this)
+  }
+
+  /**
+   * Creates a new collection in the scoped database
+   *
+   * @param {string} name
+   * @param {Object=} options
+   * @returns {Promise<DbCollection>}
+   * @throws {DbError}
+   */
+  async createCollection(name, options = {}) {
+    await createCollectionApi(this.db, name, options)
+    return DbCollection.init(name, this.db, this)
+  }
+
+  /**
+   * Register an active cursor to be closed by client.close() later
+   *
+   * {AbstractDbCursor} cursor
+   */
+  registerCursor(cursor) {
+    this._activeCursors.add(cursor)
+  }
+
+  /**
+   * Remove a cursor from the active cursors set.
+   * This is called by cursor.close() after it has closed its API session.
+   *
+   * @param {AbstractDbCursor} cursor
+   */
+  unregisterCursor(cursor) {
+    this._activeCursors.delete(cursor)
+  }
+}
+
+module.exports = DbClient

package/lib/DbCollection.js

@@ -0,0 +1,352 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+const {
+  insertOneApi, findOneApi, updateOneApi, replaceOneApi, deleteOneApi, bulkWriteApi, deleteManyApi, updateManyApi,
+  insertManyApi, findOneAndUpdateApi, findOneAndReplaceApi, findOneAndDeleteApi, createIndexApi, dropIndexApi,
+  getIndexesApi, distinctApi, countDocumentsApi, estimatedDocumentCountApi, dropApi, renameCollectionApi, statsApi,
+  findArrayApi
+} = require('./api/collection')
+const FindCursor = require("./FindCursor")
+const AggregateCursor = require("./AggregateCursor")
+
+class DbCollection {
+  /**
+   * @param {string} name
+   * @param {DbBase} db
+   * @param {DbClient} client
+   * @hideconstructor
+   */
+  constructor(name, db, client) {
+    this.name = name
+    this.db = db
+    this.client = client
+  }
+
+  /**
+   * Instantiates and returns a new DbCollection object
+   *
+   * @static
+   * @constructs
+   * @param {string} name
+   * @param {DbBase} db
+   * @param {DbClient} client
+   * @returns {DbCollection}
+   */
+  static init(name, db, client) {
+    return new DbCollection(name, db, client)
+  }
+
+  /**
+   * Inserts a single document into the collection
+   *
+   * @param {Object} document
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async insertOne(document, options = {}) {
+    return insertOneApi(this.db, this.name, document, options)
+  }
+
+  /**
+   * Insert multiple documents into the collection
+   *
+   * @param {Object[]} documents
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async insertMany(documents, options = {}) {
+    return insertManyApi(this.db, this.name, documents, options)
+  }
+
+  /**
+   * Finds the first document matching the filter
+   *
+   * @param {Object} filter
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async findOne(filter, options = {}) {
+    return findOneApi(this.db, this.name, filter, options)
+  }
+
+  /**
+   * Find all documents that match the filter
+   *
+   * @param {Object=} filter
+   * @param {Object=} options
+   * @returns {FindCursor}
+   * @throws {DbError}
+   */
+  find(filter = {}, options = {}) {
+    return new FindCursor(this.db, this.client, this.name, filter, options)
+  }
+
+  /**
+   * Update and return the first document that matches the filter
+   *
+   * @param {Object} filter
+   * @param {Object} update
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async findOneAndUpdate(filter, update, options = {}) {
+    return findOneAndUpdateApi(this.db, this.name, filter, update, options)
+  }
+
+  /**
+   * Replace and return the first document that matches the filter
+   *
+   * @param {Object} filter
+   * @param {Object} replacement
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async findOneAndReplace(filter, replacement, options = {}) {
+    return findOneAndReplaceApi(this.db, this.name, filter, replacement, options)
+  }
+
+  /**
+   * Delete and return the first document that matches the filter
+   *
+   * @param {Object} filter
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async findOneAndDelete(filter, options = {}) {
+    return findOneAndDeleteApi(this.db, this.name, filter, options)
+  }
+
+  /**
+   * Finds the first batch of documents that match the filter and return them as an array.
+   * Does not allow retrieving more than one batch of results.
+   *
+   * @param {Object=} filter
+   * @param {Object=} options
+   * @returns {Promise<Object[]>}
+   */
+  async findArray(filter = {}, options = {}) {
+    return findArrayApi(this.db, this.name, filter, options)
+  }
+
+  /**
+   * Updates the first document that matches the filter
+   *
+   * @param {Object} filter
+   * @param {Object} update
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async updateOne(filter, update, options = {}) {
+    return updateOneApi(this.db, this.name, filter, update, options)
+  }
+
+  /**
+   * Update all documents that match a filter
+   *
+   * @param {Object} filter
+   * @param {Object} update
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async updateMany(filter, update, options = {}) {
+    return updateManyApi(this.db, this.name, filter, update, options)
+  }
+
+  /**
+   * Replaces the first document that matches the filter
+   *
+   * @param {Object} filter
+   * @param {Object} replacement
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async replaceOne(filter, replacement, options = {}) {
+    return replaceOneApi(this.db, this.name, filter, replacement, options)
+  }
+
+  /**
+   * Deletes the first document that matches the filter
+   *
+   * @param {Object} filter
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async deleteOne(filter, options = {}) {
+    return deleteOneApi(this.db, this.name, filter, options)
+  }
+
+  /**
+   * Delete all documents that match a filter
+   *
+   * @param {Object} filter
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async deleteMany(filter, options = {}) {
+    return deleteManyApi(this.db, this.name, filter, options)
+  }
+
+  /**
+   * Executes an aggregation pipeline over the documents in a collection
+   *
+   * @param {Object[]=} pipeline
+   * @param {Object=} options
+   * @returns {AggregateCursor}
+   * @throws {DbError}
+   */
+  aggregate(pipeline = [], options = {}) {
+    return new AggregateCursor(this.db, this.client, this.name, pipeline, options)
+  }
+
+  /**
+   * Execute multiple insert/update/delete commands in one operation
+   *
+   * @param {Object[]} operations
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async bulkWrite(operations, options = {}) {
+    return bulkWriteApi(this.db, this.name, operations, options)
+  }
+
+  /**
+   * Gets the list of indexes in the collection
+   *
+   * @returns {Promise<Object[]>}
+   * @throws {DbError}
+   */
+  async getIndexes() {
+    return getIndexesApi(this.db, this.name)
+  }
+
+  /**
+   * Create an index with the provided specification
+   *
+   * @param {Object} specification
+   * @param {Object=} options
+   * @returns {Promise<String>} The name of the created index
+   * @throws {DbError}
+   */
+  async createIndex(specification, options = {}) {
+    return createIndexApi(this.db, this.name, specification, options)
+  }
+
+  /**
+   * Drops the index with the given name
+   *
+   * @param {string} index
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async dropIndex(index, options = {}) {
+    return dropIndexApi(this.db, this.name, index, options)
+  }
+
+  /**
+   * Find all distinct values for a field, optionally applying a filter
+   *
+   * @param {(Object|string)} field
+   * @param {Object=} filter
+   * @param {Object=} options
+   * @returns {Promise<*[]>}
+   * @throws {DbError}
+   */
+  async distinct(field, filter = {}, options = {}) {
+    return distinctApi(this.db, this.name, field, filter, options)
+  }
+
+  /**
+   * Count the number of documents, optionally applying a filter
+   *
+   * @param {Object=} filter
+   * @param {Object=} options
+   * @returns {Promise<number>}
+   * @throws {DbError}
+   */
+  async countDocuments(filter = {}, options = {}) {
+    return countDocumentsApi(this.db, this.name, filter, options)
+  }
+
+  /**
+   * @deprecated
+   * @see countDocuments
+   *
+   * @param {Object=} filter
+   * @param {Object=} options
+   * @returns {Promise<number>}
+   * @throws {DbError}
+   */
+  async count(filter = {}, options = {}) {
+    return this.countDocuments(filter, options)
+  }
+
+  /**
+   * Estimates the number of documents based on collection metadata
+   *
+   * @param {Object=} options
+   * @returns {Promise<number>}
+   * @throws {DbError}
+   */
+  async estimatedDocumentCount(options = {}) {
+    return estimatedDocumentCountApi(this.db, this.name, options)
+  }
+
+  /**
+   * Drop this collection from the database
+   *
+   * @param {Object=} options
+   * @returns {Promise<void>}
+   * @throws {DbError}
+   */
+  async drop(options = {}) {
+    return dropApi(this.db, this.name, options)
+  }
+
+  /**
+   * Rename this collection
+   *
+   * @param {string} newCollectionName
+   * @param {Object=} options
+   * @returns {Promise<void>}
+   * @throws {DbError}
+   */
+  async renameCollection(newCollectionName, options = {}) {
+    await renameCollectionApi(this.db, this.name, newCollectionName, options)
+    this.name = newCollectionName
+  }
+
+  /**
+   * Get collection statistics
+   *
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async stats(options = {}) {
+    return statsApi(this.db, this.name, options)
+  }
+}
+
+module.exports = DbCollection

package/lib/DbError.js

@@ -0,0 +1,21 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+class DbError extends Error {
+  constructor(message, requestId = null, httpStatusCode = undefined, options = {}) {
+    super(message, options)
+    this.name = 'DbError'
+    this.requestId = requestId
+    this.httpStatusCode = httpStatusCode
+  }
+}
+
+module.exports = DbError

package/lib/FindCursor.js

@@ -0,0 +1,107 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+const AbstractDbCursor = require("./AbstractDbCursor")
+const { findApi } = require("./api/collection")
+
+class FindCursor extends AbstractDbCursor {
+  #filter
+
+  /**
+   * @param {DbBase} db
+   * @param {DbClient} client
+   * @param {string} collectionName
+   * @param {Object} filter
+   * @param {Object} options
+   */
+  constructor(db, client, collectionName, filter, options) {
+    super(db, client, collectionName, options)
+    this.#filter = filter
+  }
+
+  /**
+   * Get the first batch of results from the database
+   *
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   * @protected
+   * @internal
+   */
+  async _firstRequest() {
+    return await findApi(this._db, this._axiosClient, this._collection, this.#filter, this._options)
+  }
+
+  /**
+   * Set the query filter
+   *
+   * @param {Object} filter
+   * @returns {this|Readable}
+   */
+  filter(filter) {
+    this._throwIfInitialized()
+    this.#filter = filter
+    return this
+  }
+
+  /**
+   * Set the sort order for the query
+   *
+   * @param {(string|string[]|Object|number)} sort
+   * @param {(string|Object|number)=} direction
+   * @returns {this}
+   */
+  sort(sort, direction = undefined) {
+    this._throwIfInitialized()
+    // Defer formatting to the service to avoid depending on the mongodb library here
+    this._options.sort = { sort: sort, direction: direction }
+    return this
+  }
+
+  /**
+   * Set the projection for the query
+   *
+   * @param {Object} projection
+   * @returns {this}
+   */
+  project(projection) {
+    // The actual option is 'projection', but project() is the name of the method that sets it
+    // on MongoDb's FindCursor class
+    this._throwIfInitialized()
+    this._options.projection = projection
+    return this
+  }
+
+  /**
+   * Set the limit for the query
+   *
+   * @param {number} limit
+   * @returns {this}
+   */
+  limit(limit) {
+    this._throwIfInitialized()
+    this._options.limit = limit
+    return this
+  }
+
+  /**
+   * Set the number of documents to skip before returning results
+   *
+   * @param {number} skip
+   * @returns {this}
+   */
+  skip(skip) {
+    this._throwIfInitialized()
+    this._options.skip = skip
+    return this
+  }
+}
+
+module.exports = FindCursor

package/lib/api/client.js

@@ -0,0 +1,96 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+const { apiPost, apiGet } = require("../../utils/apiRequest")
+
+/**
+ * Make a post request to the App Builder Database Service API and return the result
+ *
+ * @param {DbBase} db
+ * @param {string} endpoint
+ * @param {Object=} params
+ * @param {Object=} options
+ * @param {AxiosInstance=} axiosClient
+ * @returns {Promise<*>}
+ * @throws {DbError}
+ */
+async function postClientApi(db, endpoint, params = {}, options = {}, axiosClient = undefined) {
+  const client = axiosClient || db.axiosClient;
+  return await apiPost(db, client, `client/${endpoint}`, params, options)
+}
+
+/**
+ * Make a get request to the App Builder Database Service API and return the result
+ *
+ * @param {DbBase} db
+ * @param {string} endpoint
+ * @returns {Promise<*>}
+ * @throws {DbError}
+ */
+async function getClientApi(db, endpoint) {
+  return await apiGet(db, db.axiosClient, `client/${endpoint}`)
+}
+
+/**
+ * Gets the statistics for the scoped database
+ *
+ * @param {DbBase} db
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function dbStats(db) {
+  return await getClientApi(db, 'dbStats')
+}
+
+/**
+ * Create a new collection in the scoped database
+ *
+ * @param {DbBase} db
+ * @param {string} name
+ * @param {Object=} options
+ * @returns {Promise<void>}
+ * @throws {DbError}
+ */
+async function createCollection(db, name, options = {}) {
+  return await postClientApi(db, 'createCollection', { name: name }, options)
+}
+
+/**
+ * List the collections in the scoped database
+ *
+ * @param {DbBase} db
+ * @param {Object=} filter
+ * @param {Object=} options
+ * @returns {Promise<Object[]>}
+ * @throws {DbError}
+ */
+async function listCollections(db, filter = {}, options = {}) {
+  return await postClientApi(db, 'listCollections', { filter: filter }, options)
+}
+
+/**
+ * Close a database session
+ *
+ * @param {DbBase} db
+ * @param {AxiosInstance} axiosClient
+ * @returns {Promise<void>}
+ * @throws {DbError}
+ */
+async function close(db, axiosClient) {
+  return await postClientApi(db, 'close', undefined, undefined, axiosClient)
+}
+
+module.exports = {
+  dbStatsApi: dbStats,
+  closeApi: close,
+  createCollectionApi: createCollection,
+  listCollectionsApi: listCollections
+}