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

package/lib/api/collection.js

@@ -0,0 +1,425 @@
+/*
+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 } = require("../../utils/apiRequest")
+
+/**
+ * Make a post request to the App Builder Database Service collection API and return the result
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {string} endpoint
+ * @param {Object=} params
+ * @param {Object=} options
+ * @param {AxiosInstance=} axiosClient
+ * @returns {Promise<*>}
+ * @throws {DbError}
+ */
+async function postCollectionApi(db, collectionName, endpoint, params = {}, options = {}, axiosClient = undefined) {
+  if (!axiosClient) {
+    axiosClient = db.axiosClient
+  }
+  return await apiPost(db, axiosClient, `collection/${collectionName}/${endpoint}`, params, options)
+}
+
+/**
+ * Insert a single document into the collection
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} document
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function insertOne(db, collectionName, document, options = {}) {
+  return await postCollectionApi(db, collectionName, 'insertOne', { document: document }, options)
+}
+
+/**
+ * Inserts multiple documents into the collection
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object[]} documents
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function insertMany(db, collectionName, documents, options = {}) {
+  return await postCollectionApi(db, collectionName, 'insertMany', { documents: documents }, options)
+}
+
+/**
+ * Retrieve the first document that matches the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function findOne(db, collectionName, filter, options = {}) {
+  return await postCollectionApi(db, collectionName, 'findOne', { filter: filter }, options)
+}
+
+/**
+ * Update and return the first document that matches the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object} update
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function findOneAndUpdate(db, collectionName, filter, update, options = {}) {
+  return await postCollectionApi(db, collectionName, 'findOneAndUpdate', { filter: filter, update: update }, options)
+}
+
+/**
+ * Replace and return the first document that matches the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object} replacement
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function findOneAndReplace(db, collectionName, filter, replacement, options = {}) {
+  return await postCollectionApi(
+    db,
+    collectionName,
+    'findOneAndReplace',
+    { filter: filter, replacement: replacement },
+    options
+  )
+}
+
+/**
+ * Delete and return the first document that matches the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function findOneAndDelete(db, collectionName, filter, options = {}) {
+  return await postCollectionApi(db, collectionName, 'findOneAndDelete', { filter: 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 {DbBase} db
+ * @param {string} collectionName
+ * @param {Object=} filter
+ * @param {Object=} options
+ * @returns {Object[]}
+ * @throws {DbError}
+ */
+async function findArray(db, collectionName, filter, options = {}) {
+  return await postCollectionApi(db, collectionName, 'findArray', { filter: filter }, options)
+}
+
+/**
+ * Update the first document that matches the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object} update
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function updateOne(db, collectionName, filter, update, options = {}) {
+  return await postCollectionApi(db, collectionName, 'updateOne', { filter: filter, update: update }, options)
+}
+
+/**
+ * Updates all documents that match the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object} update
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function updateMany(db, collectionName, filter, update, options = {}) {
+  return await postCollectionApi(db, collectionName, 'updateMany', { filter: filter, update: update }, options)
+}
+
+/**
+ * Replace the first document that matches the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object} replacement
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function replaceOne(db, collectionName, filter, replacement, options = {}) {
+  return await postCollectionApi(
+    db,
+    collectionName,
+    'replaceOne',
+    { filter: filter, replacement: replacement },
+    options
+  )
+}
+
+/**
+ * Delete the first document that matches the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function deleteOne(db, collectionName, filter, options = {}) {
+  return await postCollectionApi(db, collectionName, 'deleteOne', { filter: filter }, options)
+}
+
+/**
+ * Deletes all documents that match the filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} filter
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function deleteMany(db, collectionName, filter, options = {}) {
+  return await postCollectionApi(db, collectionName, 'deleteMany', { filter: filter }, options)
+}
+
+/**
+ * Execute multiple insert/update/delete commands in one operation
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object[]} operations
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function bulkWrite(db, collectionName, operations, options = {}) {
+  return await postCollectionApi(db, collectionName, 'bulkWrite', { operations: operations }, options)
+}
+
+/**
+ * Find all documents that match the filter
+ *
+ * @param {DbBase} db
+ * @param {AxiosInstance} axiosClient
+ * @param {string} collectionName
+ * @param {Object=} filter
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function find(db, axiosClient, collectionName, filter = {}, options = {}) {
+  return await postCollectionApi(db, collectionName, 'find', { filter: filter }, options, axiosClient)
+}
+
+/**
+ * Executes an aggregation pipeline over the documents in a collection
+ *
+ * @param {DbBase} db
+ * @param {AxiosInstance} axiosClient
+ * @param {string} collectionName
+ * @param {Object[]=} pipeline
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function aggregate(db, axiosClient, collectionName, pipeline = [], options = {}) {
+  return await postCollectionApi(db, collectionName, 'aggregate', { pipeline: pipeline }, options, axiosClient)
+}
+
+/**
+ * Get more results from a cursor
+ *
+ * @param {DbBase} db
+ * @param {AxiosInstance} axiosClient
+ * @param {string} collectionName
+ * @param {(import('bson').Long|number)} cursorId
+ * @param {Object=} options
+ * @return {Promise<*>}
+ */
+async function getMore(db, axiosClient, collectionName, cursorId, options = {}) {
+  return await postCollectionApi(db, collectionName, 'getMore', { cursorId: cursorId }, options, axiosClient)
+}
+
+/**
+ * Get the list of indexes from the collection
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @returns {Promise<Object[]>}
+ * @throws {DbError}
+ */
+async function getIndexes(db, collectionName) {
+  return await postCollectionApi(db, collectionName, 'getIndexes')
+}
+
+/**
+ * Create an index with the provided specification
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object} specification
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function createIndex(db, collectionName, specification, options = {}) {
+  return await postCollectionApi(db, collectionName, 'createIndex', { specification: specification }, options)
+}
+
+/**
+ * Drop the index with the provided name
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {string} index
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function dropIndex(db, collectionName, index, options = {}) {
+  return await postCollectionApi(db, collectionName, 'dropIndex', { index: index }, options)
+}
+
+/**
+ * Find all distinct values for a field, optionally applying a filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {(Object|string)} field
+ * @param {Object=} filter
+ * @param {Object=} options
+ * @returns {Promise<*[]>}
+ * @throws {DbError}
+ */
+async function distinct(db, collectionName, field, filter = {}, options = {}) {
+  return await postCollectionApi(db, collectionName, 'distinct', { field: field, filter: filter }, options)
+}
+
+/**
+ * Count the number of documents in a collection, optionally applying a filter
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object=} filter
+ * @param {Object=} options
+ * @returns {Promise<number>}
+ * @throws {DbError}
+ */
+async function countDocuments(db, collectionName, filter = {}, options = {}) {
+  return await postCollectionApi(db, collectionName, 'countDocuments', { filter: filter }, options)
+}
+
+/**
+ * Estimates the number of documents in a collection based on collection metadata
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object=} options
+ * @returns {Promise<number>}
+ * @throws {DbError}
+ */
+async function estimatedDocumentCount(db, collectionName, options = {}) {
+  return await postCollectionApi(db, collectionName, 'estimatedDocumentCount', {}, options)
+}
+
+/**
+ * Drop this collection from the database
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object=} options
+ * @returns {Promise<void>}
+ * @throws {DbError}
+ */
+async function drop(db, collectionName, options = {}) {
+  await postCollectionApi(db, collectionName, 'drop', undefined, options)
+}
+
+/**
+ * Rename this collection
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {string} newCollectionName
+ * @param {Object=} options
+ * @returns {Promise<void>}
+ * @throws {DbError}
+ */
+async function renameCollection(db, collectionName, newCollectionName, options = {}) {
+  await postCollectionApi(db, collectionName, 'renameCollection', { name: newCollectionName }, options)
+}
+
+/**
+ * Get collection statistics
+ *
+ * @param {DbBase} db
+ * @param {string} collectionName
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function stats(db, collectionName, options = {}) {
+  return await postCollectionApi(db, collectionName, 'stats', undefined, options)
+}
+
+module.exports = {
+  insertOneApi: insertOne,
+  insertManyApi: insertMany,
+  findOneApi: findOne,
+  findOneAndUpdateApi: findOneAndUpdate,
+  findOneAndReplaceApi: findOneAndReplace,
+  findOneAndDeleteApi: findOneAndDelete,
+  findArrayApi: findArray,
+  updateOneApi: updateOne,
+  updateManyApi: updateMany,
+  replaceOneApi: replaceOne,
+  deleteOneApi: deleteOne,
+  deleteManyApi: deleteMany,
+  bulkWriteApi: bulkWrite,
+  findApi: find,
+  aggregateApi: aggregate,
+  getMoreApi: getMore,
+  getIndexesApi: getIndexes,
+  createIndexApi: createIndex,
+  dropIndexApi: dropIndex,
+  distinctApi: distinct,
+  countDocumentsApi: countDocuments,
+  estimatedDocumentCountApi: estimatedDocumentCount,
+  dropApi: drop,
+  renameCollectionApi: renameCollection,
+  statsApi: stats
+}

package/lib/api/db.js

@@ -0,0 +1,90 @@
+/*
+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 db API and return the result
+ *
+ * @param {DbBase} db
+ * @param {AxiosInstance} axiosClient
+ * @param {string} endpoint
+ * @param {Object=} params
+ * @param {Object=} options
+ * @returns {Promise<*>}
+ * @throws {DbError}
+ */
+async function postDbApi(db, axiosClient, endpoint, params = {}, options = {}) {
+  return await apiPost(db, axiosClient, `db/${endpoint}`, params, options)
+}
+
+/**
+ * Make a get request to the App Builder Database Service db API and return the result
+ *
+ * @param {DbBase} db
+ * @param {string} endpoint
+ * @returns {Promise<*>}
+ * @throws {DbError}
+ */
+async function getDbApi(db, endpoint) {
+  return await apiGet(db, db.axiosClient, `db/${endpoint}`)
+}
+
+/**
+ * Submit a request to provision a new database for the current runtime namespace
+ *
+ * @param {DbBase} db
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function provisionRequest(db) {
+  return await postDbApi(db, db.axiosClient, 'provision/request')
+}
+
+/**
+ * Gets the provisioning status for the current runtime namespace
+ *
+ * @param {DbBase} db
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function provisionStatus(db) {
+  return await postDbApi(db, db.axiosClient, 'provision/status')
+}
+
+/**
+ * Checks connectivity with the App Builder Database Service
+ *
+ * @param {DbBase} db
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function ping(db) {
+  return await getDbApi(db, 'ping')
+}
+
+/**
+ * Delete the tenant database for the current runtime namespace
+ *
+ * @param {DbBase} db
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function deleteDatabase(db) {
+  return await postDbApi(db, db.axiosClient, 'delete')
+}
+
+module.exports = {
+  provisionRequestApi: provisionRequest,
+  provisionStatusApi: provisionStatus,
+  pingApi: ping,
+  deleteDatabaseApi: deleteDatabase
+}

package/lib/constants.js

@@ -0,0 +1,44 @@
+/*
+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.
+*/
+require('dotenv/config')
+
+const RUNTIME_HEADER = 'x-runtime-namespace'
+const REQUEST_ID_HEADER = 'x-request-id'
+
+const CURSOR_INIT_ERR_MESSAGE = 'Cursor has already been initialized, cannot modify request.'
+
+const PROD_ENV = 'prod'
+const STAGE_ENV = 'stage'
+
+const ALLOWED_REGIONS = {
+  // First region in an environment's array is the default
+  [PROD_ENV]: ['amer', 'emea', 'apac'],
+  [STAGE_ENV]: ['amer', 'amer2']
+}
+
+// For stage we use the public endpoints for interacting with Production I/O runtime as connecting
+// cross envs is not allowed in MCT.
+const STAGE_ENDPOINT = 'https://storage-database-<region>.stg.app-builder.adp.adobe.io'
+const PROD_ENDPOINT_RUNTIME = 'https://storage-database-<region>.app-builder.int.adp.adobe.io'
+const PROD_ENDPOINT_EXTERNAL = 'https://storage-database-<region>.app-builder.adp.adobe.io'
+
+module.exports = {
+  RUNTIME_HEADER,
+  REQUEST_ID_HEADER,
+  CURSOR_INIT_ERR_MESSAGE,
+  PROD_ENV,
+  STAGE_ENV,
+  ALLOWED_REGIONS,
+  STAGE_ENDPOINT,
+  PROD_ENDPOINT_RUNTIME,
+  PROD_ENDPOINT_EXTERNAL
+}

package/lib/init.js

@@ -0,0 +1,35 @@
+/*
+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 DbBase = require('./DbBase')
+require('dotenv/config')
+
+/* *********************************** helpers & init() *********************************** */
+
+/**
+ * Initializes and returns the ADP Storage Database SDK.
+ *
+ * To use the SDK you must either provide your OpenWhisk credentials in `config.ow` or in the environment variables
+ * `__OW_NAMESPACE` and `__OW_API_KEY`.
+ *
+ * @param {Object=} [config] used to init the sdk
+ * @param {('amer'|'apac'|'emea')=} [config.region] optional region to use, default: `amer`
+ * @param {Object=} [config.ow] Set those if you want to use ootb credentials to access the database service
+ * @param {string=} [config.ow.namespace]
+ * @param {string=} [config.ow.auth]
+ * @returns {Promise<DbBase>} A DbBase instance
+ */
+async function init (config = {}) {
+  const { auth: apikey, namespace } = (config.ow ?? {})
+  return DbBase.init({ apikey, namespace, region: config.region })
+}
+
+module.exports = { init }

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@adobe/aio-lib-db",
+  "version": "0.1.0-alpha.1",
+  "description": "An abstraction on top of Document DB storage",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest --passWithNoTests"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "author": "Adobe Inc.",
+  "license": "Apache-2.0",
+  "maintainers": [
+    "Adobe Inc."
+  ],
+  "contributors": [],
+  "dependencies": {
+    "@adobe/aio-lib-env": "^3.0.1",
+    "axios": "^1.8.4",
+    "bson": "^6.10.3",
+    "dotenv": "^17.0.0",
+    "http-cookie-agent": "^7.0.1",
+    "tough-cookie": "^5.1.2"
+  },
+  "devDependencies": {
+    "jest": "^30.0.0",
+    "uuid": "^11.1.0"
+  },
+  "keywords": [
+    "adobe",
+    "aio",
+    "database",
+    "document-db",
+    "mongodb",
+    "runtime",
+    "adobe-io",
+    "serverless"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adobe/aio-lib-db.git"
+  },
+  "bugs": "https://github.com/adobe/aio-lib-db/issues",
+  "homepage": "https://github.com/adobe/aio-lib-db#readme",
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/adobe"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}