@pbvision/firestore-orm 0.0.6 → 0.0.8

package/README.md

@@ -8,6 +8,8 @@ high-level abstractions to structure data and prevent race conditions.
   - [Minimal Example](#minimal-example)
   - [Collections](#collections)
     - [Keys](#keys)
+      - [Semantic Keys](#semantic-keys)
+      - [Random Keys](#random-keys)
     - [Fields](#fields)
     - [Schema Enforcement](#schema-enforcement)
     - [Custom Methods](#custom-methods)
@@ -117,6 +119,7 @@ Access each component of a key just like any other field:
   }
 ```
 
+#### Semantic Keys
 It is best practice for keys to have semantic meaning whenever possible. In
 this example, each runner finishes each race just one time so making the key a
 combination of those values is ideal. This is better than a meaningless random
@@ -133,6 +136,13 @@ value because this:
 Note: Keys are collection-specific. Two different docs in different collections may have
 the same key.
 
+#### Random Keys
+If keys are random, then you can use `db.makeAutoIdSchema()` to generate a
+schema for validating them. That schema object also has a `newId()` method
+which generates IDs which conform to that schema. You can configure the length
+of the IDs (20 by default) and whether uppercase letters are included (false by
+default) by passing parameters to the `makeAutoIdSchema()` function.
+
 
 ### Fields
 Fields are pieces of data attached to a doc. They are defined similar to

package/environment.js

@@ -1,2 +1 @@
-process.env.INDEBUGGER = 1
 process.env.FIRESTORE_EMULATOR_HOST = '[::1]:8404'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pbvision/firestore-orm",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Firestore ORM Library",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,7 @@
   "scripts": {
     "build-doc": "./docs/build.sh",
     "check-markdown-link": "./scripts/ci/markdown-link.sh",
-    "debug": "yarn start-local-db && ./node_modules/nodemon/bin/nodemon.js --no-lazy --legacy-watch --watch ./src --watch ./example --watch ./test --inspect=9229 ./node_modules/jest/bin/jest.js --coverage --config=./jest.config.json --runInBand",
+    "debug": "yarn start-local-db && INDEBUGGER=1 ./node_modules/nodemon/bin/nodemon.js --no-lazy --legacy-watch --watch ./src --watch ./example --watch ./test --inspect=9229 ./node_modules/jest/bin/jest.js --coverage --config=./jest.config.json --runInBand",
     "lint": "./scripts/ci/lint-format-js.sh",
     "setup": "yarn install --frozen-lockfile && pip install -r requirements.txt",
     "start-local-db": "./scripts/start-local-db.sh",
@@ -40,7 +40,7 @@
   ],
   "dependencies": {
     "@google-cloud/firestore": "^7.1.0",
-    "@pbvision/schema": "^0.2.15",
+    "@pbvision/schema": "^0.2.22",
     "deep-object-diff": "^1.1.7",
     "fast-deep-equal": "^3.1.3",
     "fast-json-stable-stringify": "^2.1.0",

package/src/context.js

@@ -103,9 +103,9 @@ export class Context {
     return {
       readOnly: false,
       consistentReads: true,
-      initialBackoff: process.env.INDEBUGGER ? 1 : 500,
+      initialBackoff: process.env.FIRESTORE_EMULATOR_HOST ? 1 : 500,
       maxBackoff: 10000,
-      retries: process.env.INDEBUGGER ? 0 : 4, // no retry by default in unit tests for speed
+      retries: process.env.FIRESTORE_EMULATOR_HOST ? 0 : 4, // no retry by default in unit tests for speed
       cacheModels: false
     }
   }

package/src/firestore.js

@@ -1,3 +1,5 @@
+import assert from 'node:assert'
+
 import S from '@pbvision/schema'
 
 import {
@@ -38,6 +40,57 @@ import { Model } from './models.js'
  * @private
  */
 export default function setup (firestoreDB) {
+  /**
+   * Generates a globally unique ID.
+   *
+   * newId() generates IDs that are statistically globally unique using
+   * firestoreDB's AutoId class. These IDs by default are 20 characters long
+   * and may include numbers and letters (both lowercase and uppercase). This
+   * function allows a shorter string to be returned for cases where the
+   * identifier doesn't need to be so long. Of course, if it's too short and
+   * too many are generated then duplicates may be generated. For
+   * implementation details see https://github.com/googleapis/nodejs-firestore
+   *
+   * @param {Object} params
+   * @param {integer} [len=20] can be modified to shorten the IDs length (at
+   *   the expense of curtailing its statistical global uniqueness guarantee)
+   * @param {boolean} [lowercaseOnly=true] whether to include only lowercase
+   *   letters and digits in the generated ID (defaults to true)
+   * @returns {string} the new ID string
+   */
+  function newId (len = 20, lowercaseOnly = true) {
+    let id = firestoreDB.collection('tmp').doc().id
+    assert(id.length >= len,
+      `AutoId does not support generating ${len} length IDs (too long)`)
+    if (lowercaseOnly) {
+      id = id.toLowerCase()
+    }
+    return id.substring(0, len)
+  }
+
+  /**
+   * Returns a schema for an automatic ID with the specified params.
+   *
+   * Parameters mirror newId().
+   * @param {string} title title for the schema
+   *
+   * The returned schema has a newId() function on it which takes no params and
+   * generates random new IDs which conform to the schema.
+   */
+  function makeAutoIdSchema (len = 20, lowercaseOnly = true, title = undefined) {
+    const allowedChars = `${lowercaseOnly ? '' : 'A-Z'}a-z0-9`
+    let schema = S.str
+      .pattern(`[${allowedChars}]{${len}}`)
+      .min(len).max(len)
+      .desc(`a unique ID consisting of ${len} digits and letters
+             (${lowercaseOnly ? 'lowercase only' : 'uppercase and lowercase'})`)
+    if (title) {
+      schema = schema.title(title)
+    }
+    schema.newId = () => newId(len, lowercaseOnly)
+    return schema
+  }
+
   Key.firestoreDB = firestoreDB
   const toExport = {
     S,
@@ -45,6 +98,8 @@ export default function setup (firestoreDB) {
     UniqueKeyList,
     Context,
     firestoreDB,
+    makeAutoIdSchema,
+    newId,
 
     // Errors
     DeletedTwiceError,
@@ -56,7 +111,7 @@ export default function setup (firestoreDB) {
     TransactionFailedError,
     WriteAttemptedInReadOnlyTxError
   }
-  if (Number(process.env.INDEBUGGER)) {
+  if (Number(process.env.FIRESTORE_EMULATOR_HOST)) {
     toExport.__private = {
       __Field,
       fields: [