@pbvision/firestore-orm 0.0.6 → 0.0.7

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pbvision/firestore-orm",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Firestore ORM Library",
   "license": "Apache-2.0",
   "type": "module",
@@ -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/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,