@adobe/aio-lib-db 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -12,49 +12,32 @@ Install `aio-lib-db` from npm:
 npm install @adobe/aio-lib-db
 ```
 
-Or add it to your `package.json`:
-
-```json
-{
-  "dependencies": {
-    "@adobe/aio-lib-db": "^0.1.0"
-  }
-}
-```
-
 ---
 
 ## Quick Start
 
 ### Setup
 
-First, set your credentials in your `.env` file:
+**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.)
 
-```env
-__OW_NAMESPACE=your_namespace
-__OW_API_KEY=user:password
-```
-
-> To find runtime namespace and credentials, click "Download all" in the Adobe Developer Console for your project workspace and the values will be under `project.workspace.details.runtime.namespaces`.
+**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
 
-> When calling `libDb.init()`, you can pass `{ region: '<region>>' }` to specify the region where your database is provisioned, or if region is defined in `app.config.yaml` of aio app, then `libDb.init()` will initialize in specified region.
-> 
-> **Note:** region defined in `app.config.yaml` holds preference over passed in config param.
-> 
-> If region is not specified in any of the above ways, it falls back to default.
-> 
-> Valid regions are `amer` (default), `emea`, and `apac`.
-
 ```javascript
 const libDb = require('@adobe/aio-lib-db');
 
 async function main() {
+  let client;
   try {
-    // Initialize and connect
-    const db = await libDb.init({ region: 'amer' });
-    const client = await db.connect();
+    // 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();
 
     // Get a collection
     const users = client.collection('users');
@@ -67,12 +50,13 @@ async function main() {
     const results = await cursor.toArray();
   }
   finally {
-    // Close any open cursors when the application is done
-    await client.close();
+    if (client) {
+      // Close any open cursors when the application is done
+      await client.close();
+    }
   }
 }
 ```
-
 ---
 
 ## Collection Operations
@@ -291,6 +275,24 @@ const cursor = collection.aggregate()
 
 ## Advanced Features
 
+### Storage Statics
+
+```javascript
+// Get storage statistics for the database
+const dbStats = client.dbStats()
+```
+| 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 in bytes    |
+| storageSize    | space allocated for storage in bytes          |
+| indexSize      | space allocated for indexes in bytes          |
+| ok             | whether the request was successful            |
+| lastUpdated    | when the statistics where last updated        |
+
 ### Indexing
 
 ```javascript
@@ -372,12 +374,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

@@ -58,8 +58,9 @@ class DbBase {
         // Stage environment does not have a separate runtime endpoint
         serviceUrl = STAGE_ENDPOINT
       }
-      else if (process.env.__OW_ACTIVATION_ID) {
-        // If __OW_ACTIVATION_ID is set, the sdk is being used from inside a runtime action
+      else if (process.env.__OW_ACTIVATION_ID && !process.env.AIO_DEV) {
+        // If __OW_ACTIVATION_ID is set, the sdk is being used from inside a runtime action and should use the internal
+        // endpoint unless it's being executed by "aio app dev" (AIO_DEV is set)
         serviceUrl = PROD_ENDPOINT_RUNTIME
       }
       else {
@@ -80,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
    */
@@ -88,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/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.4",
+  "version": "0.1.0-beta.6",
   "description": "An abstraction on top of Document DB storage",
   "main": "index.js",
   "scripts": {