@adobe/aio-lib-db 0.1.0-beta.5 → 0.1.0-beta.8

package/README.md

@@ -20,7 +20,7 @@ npm install @adobe/aio-lib-db
 
 **aio-lib-db** is intended to be used by AIO Runtime Actions and the DB Plugin for the AIO CLI, and these are always executed within a specific runtime namespace. Before use, a Workspace Database must be provisioned. (See [Provisioning a Workspace Database](https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/storage/database#provisioning-a-workspace-database) in the [Getting Started with Database Storage](https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/storage/database) guide for details.)
 
-**aio-lib-db** must always be initialized in a specific region. This region is normally defined in the `app.config.yaml` application manifest. If it is not, it will default to the `amer` region. Another option is to pass `{ region: '<region>' }` to the `libDb.init()` method to override the default.
+**aio-lib-db** must be initialized in the region the workspace database was provisioned. Otherwise, the connection will fail.  To explicitly initialize the library in a specific region, pass the `{region: "<region>"}` argument to the `libDb.init()` method. Called with no arguments, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable.
 
 ### Basic Usage
 
@@ -30,8 +30,12 @@ const libDb = require('@adobe/aio-lib-db');
 async function main() {
   let client;
   try {
-    // initialize library in region is defined in app.config.yaml and defaults to amer
+    // initialize library with the default amer region or what is defined in AIO_DB_REGION
     const db = await libDb.init();
+
+    // initialize library with an explicit region
+    // const db = await libDb.init({region: "emea"});
+
     // connect to the database
     client = await db.connect();
 
@@ -53,7 +57,6 @@ async function main() {
   }
 }
 ```
-
 ---
 
 ## Collection Operations
@@ -272,6 +275,57 @@ const cursor = collection.aggregate()
 
 ## Advanced Features
 
+### Storage Statics
+
+#### Individual database statistics:
+
+```javascript
+// Get storage statistics for the database with the default scale factor (bytes)
+const dbStats = client.dbStats()
+
+// Get storage statistics for the database with a scale factor (e.g. KB)
+const dbStatsKb = client.dbStats({ scale: 1024 })
+```
+| field returned | description                                                                                     |
+|----------------|-------------------------------------------------------------------------------------------------|
+| collections    | the number of collections                                                                       |
+| objects        | the number of objects/documents                                                                 |
+| views          | the number of views (not currently supported)                                                   |
+| indexes        | the number of indexes                                                                           |
+| dataSize       | the actual amount of storage used (default bytes)                                               |
+| storageSize    | space allocated for storage (default bytes)                                                     |
+| indexSize      | space allocated for indexes (default bytes)                                                     |
+| ok             | whether the request was successful                                                              |
+| scaleFactor    | the scale factor used for the size fields, ex: 1024 for kilobyte-scale (default is 1 for bytes) |
+| lastUpdated    | when the statistics were last updated                                                           |
+
+#### Organization storage statistics:
+
+```javascript
+// Get combined storage statistics across databases in the organization with the default scale factor (bytes)
+const orgStats = client.orgStats()
+
+// Get combined storage statistics across databases in the organization with a scale factor (e.g. MB)
+const orgStatsMb = client.orgStats({ scale: 1024 * 1024 })
+```
+| field returned            | description                                                                                                                |
+|---------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| ok                        | whether the request was successful                                                                                         |
+| databases                 | the number of databases in the organization                                                                                |
+| collections               | the total number of collections across databases                                                                           |
+| dataSize                  | the total actual amount of storage used across databases (default bytes)                                                   |
+| storageSize               | space allocated for storage (default bytes)                                                                                |
+| indexSize                 | space allocated for indexes (default bytes)                                                                                |
+| scaleFactor               | the scale factor used for the size fields, ex: 1024 for kilobyte-scale (default is 1 for bytes)                            |
+| databaseStats             | an array of statistics for individual databases in the organization                                                        |
+| databaseStats.namespace   | the runtime namespace the database corresponds to                                                                          |
+| databaseStats.dataSize    | the actual amount of storage used by the database (default bytes)                                                          |
+| databaseStats.storageSize | space allocated for storage for the database (default bytes)                                                               |
+| databaseStats.indexSize   | space allocated for indexes for the database (default bytes)                                                               |
+| databaseStats.collections | the number of collections in the database                                                                                  |
+| databaseStats.scaleFactor | the scale factor used for the size fields in the databaseStats array, ex: 1024 for kilobyte-scale (default is 1 for bytes) |
+| databaseStats.lastUpdated | when the database statistics were last updated                                                                             |
+
 ### Indexing
 
 ```javascript
@@ -353,12 +407,10 @@ const cursor = collection.find({ status: 'active' })
 ## Error Handling
 
 ```javascript
-const { DbError } = require('@adobe/aio-lib-db');
-
 try {
   await collection.insertOne({ email: 'invalid-email' });
 } catch (error) {
-  if (error instanceof DbError) {
+  if (error.name == 'DbError') {
     console.error('Database error:', error.message);
   } else {
     console.error('Unexpected error:', error);

package/lib/DbBase.js

@@ -81,7 +81,7 @@ class DbBase {
    * @param {Object=} config
    * @param {string=} config.namespace required here or as __OW_API_NAMESPACE in .env
    * @param {string=} config.apikey required here or as __OW_API_KEY in .env
-   * @param {string=} config.region optional, default is 'amer'. Allowed prod values are 'amer', 'emea', 'apac'
+   * @param {string=} config.region optional, default is 'amer'. Allowed prod values are 'amer', 'emea', 'apac', 'aus'
    * @returns {Promise<DbBase>} a new DbBase instance
    * @memberof DbBase
    */
@@ -89,7 +89,7 @@ class DbBase {
     const namespace = config.namespace || process.env.__OW_NAMESPACE
     const apikey = config.apikey || process.env.__OW_API_KEY
     let aioAppRegion = null
-    
+
     try {
       aioAppRegion = getRegionFromAppConfig(process.cwd())
     } catch (e) {

package/lib/DbClient.js

@@ -9,7 +9,7 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 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 { dbStatsApi, listCollectionsApi, createCollectionApi, orgStatsApi } = require('./api/client')
 const DbCollection = require('./DbCollection')
 
 class DbClient {
@@ -37,11 +37,23 @@ class DbClient {
   /**
    * Get the statistics for the scoped database
    *
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async dbStats(options = {}) {
+    return dbStatsApi(this.db, options)
+  }
+
+  /**
+   * Gets the combined statistics for all databases that fall under the same organization as the scoped database
+   *
+   * @param {Object=} options
    * @returns {Promise<Object>}
    * @throws {DbError}
    */
-  async dbStats() {
-    return dbStatsApi(this.db)
+  async orgStats(options = {}) {
+    return orgStatsApi(this.db, options)
   }
 
   /**

package/lib/api/client.js

@@ -43,11 +43,24 @@ async function getClientApi(db, endpoint) {
  * Gets the statistics for the scoped database
  *
  * @param {DbBase} db
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function dbStats(db, options = {}) {
+  return await postClientApi(db, 'dbStats', undefined, options)
+}
+
+/**
+ * Gets the combined statistics for all databases that fall under the same organization as the scoped database
+ *
+ * @param {DbBase} db
+ * @param {Object=} options
  * @returns {Promise<Object>}
  * @throws {DbError}
  */
-async function dbStats(db) {
-  return await getClientApi(db, 'dbStats')
+async function orgStats(db, options = {}) {
+  return await postClientApi(db, 'orgStats', undefined, options)
 }
 
 /**
@@ -90,6 +103,7 @@ async function close(db, axiosClient) {
 
 module.exports = {
   dbStatsApi: dbStats,
+  orgStatsApi: orgStats,
   closeApi: close,
   createCollectionApi: createCollection,
   listCollectionsApi: listCollections

package/lib/constants.js

@@ -21,7 +21,7 @@ const STAGE_ENV = 'stage'
 
 const ALLOWED_REGIONS = {
   // First region in an environment's array is the default
-  [PROD_ENV]: ['amer', 'emea', 'apac'],
+  [PROD_ENV]: ['amer', 'emea', 'apac', 'aus'],
   [STAGE_ENV]: ['amer', 'amer2']
 }
 

package/lib/init.js

@@ -21,7 +21,7 @@ require('dotenv/config')
  * `__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 {('amer'|'apac'|'emea'|'aus')=} [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]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aio-lib-db",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.8",
   "description": "An abstraction on top of Document DB storage",
   "main": "index.js",
   "scripts": {
@@ -26,7 +26,7 @@
     "tough-cookie": "^5.1.2"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
+    "jest": "^30.2.0",
     "uuid": "^11.1.0"
   },
   "keywords": [