firetender-admin 0.10.0

package/LICENSE

@@ -0,0 +1,20 @@
+# MIT License
+
+Copyright 2022 Jacob M. Hartman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,349 @@
+# Firetender
+
+Firetender takes your [Zod](https://github.com/colinhacks/zod) data schema ...
+
+```javascript
+const itemSchema = z.object({
+  description: z.string().optional(),
+  count: z.number().nonnegative().integer(),
+  tags: z.array(z.string()).default([]),
+});
+```
+
+associates it with a Firestore collection ...
+
+```javascript
+const itemCollection = new FiretenderCollection(itemSchema, db, "items");
+```
+
+and provides you with typesafe, validated Firestore documents that are easy to
+use and understand.
+
+```javascript
+// Add a document to the collection.
+await itemCollection.newDoc("foo", { count: 0, tags: ["needs +1"] }).write();
+
+// Read the document "bar", then update it.
+const itemDoc = await itemCollection.existingDoc("bar").load();
+const count = itemDoc.r.count;
+await itemDoc.update((item) => {
+  item.tags.push("needs +1");
+});
+
+// Increment the count of all docs with a "needs +1" tag.
+await Promise.all(
+  itemCollection
+    .query(where("tags", "array-contains", "needs +1"))
+    .map((itemDoc) =>
+      itemDoc.update((item) => {
+        item.count += 1;
+        delete item.tags["needs +1"];
+      })
+    )
+);
+```
+
+Changes to the document data are monitored, and only modified fields are updated
+on Firestore.
+
+## Usage
+
+To illustrate in more detail, let's run through the basics of defining,
+creating, modifying, and copying a Firestore document.
+
+### Initialize Cloud Firestore
+
+The first step is the usual Firestore configuration and initialization.  See
+the [Firestore
+quickstart](https://firebase.google.com/docs/firestore/quickstart) for details.
+
+```javascript
+import { doc, initializeApp } from "firebase/app";
+import { getFirestore } from "firebase/firestore";
+
+// TODO: Replace the following with your app's Firebase project configuration.
+// See: https://firebase.google.com/docs/web/learn-more#config-object
+const firebaseConfig = {
+    // ...
+};
+
+const app = initializeApp(firebaseConfig);
+const firestore = getFirestore(app);
+```
+
+### Define a collection and its schema
+
+Firetender uses [Zod](https://github.com/colinhacks/zod) to define the schema
+and validation rules for a collection's documents; if you've used Joi or Yup,
+you will find Zod very similar.  In the example below, I've defined a schema for
+types of pizza.  I was a little hungry when I wrote this.
+
+```javascript
+import {
+  FiretenderCollection,
+  nowTimestamp,
+  timestampSchema
+} from "firetender";
+import { z } from "zod";
+
+const pizzaSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  creationTime: timestampSchema,
+  toppings: z.record(
+    z.string(),
+    z.object({
+        isIncluded: z.boolean().default(true),
+        surcharge: z.number().positive().optional(),
+        placement: z.enum(["left", "right", "entire"]).default("entire"),
+      })
+      .refine((topping) => topping.isIncluded || topping.surcharge, {
+        message: "Toppings that are not included must have a surcharge.",
+        path: ["surcharge"],
+      })
+  ),
+  basePrice: z.number().optional(),
+  tags: z.array(z.string()).default([]),
+});
+
+const pizzaCollection = new FiretenderCollection(
+  pizzaSchema,
+  firestore,
+  "pizzas",
+  { creationTime: nowTimestamp() }
+);
+```
+
+Optional records and arrays should typically use `.default()` to provide an
+empty instances when missing.  That isn't required, but it makes accessing these
+fields simpler because they will always be defined.  The downside is that empty
+fields are not pruned and will appear in Firestore.
+
+### Add a document
+
+Let's add a document to the `pizzas` collection, with an ID of `margherita`.  We
+use the collection's `.newDoc()` to produce a `FiretenderDoc` representing a new
+document, initialized with validated data.  This object is purely local until it
+is written to Firestore by calling `.write()`.  Don't forget to do that.
+
+```javascript
+const docRef = doc(db, "pizzas", "margherita");
+const pizza = pizzaFactory.newDoc(docRef, {
+  name: "Margherita",
+  description: "Neapolitan style pizza"
+  toppings: { "fresh mozzarella": {}, "fresh basil": {} },
+  tags: ["traditional"],
+});
+await pizza.write();
+```
+
+If you don't care about the doc ID, pass a collection reference to `.newDoc()`
+and Firestore will assign an ID at random.  This ID can be read from `.id` or
+`.docRef` after the document has been written.
+
+### Read and modify a document
+
+To access an existing document, pass its reference to the collection's
+`.existingDoc()` method.  To read it, call `.load()` and access its data with
+ the `.r` property; see the example below.  To make changes, use `.w` then call
+`.write()`.  Reading and updating can be done in combination:
+
+```javascript
+const meats = ["pepperoni", "chicken", "sausage"];
+const pizza = await pizzaCollection.existingDoc(docRef).load();
+const isMeatIncluded = Object.entries(pizza.r.toppings).some(
+  ([name, topping]) => topping.isIncluded && name in meats
+);
+if (!isMeatIncluded) {
+  pizza.w.toppings.tags.push("vegetarian");
+}
+await pizza.write();
+```
+
+The `.r` and `.w` properties point to the same data, with the read-only accessor
+typed accordingly.  Reading from `.r` is more efficient, as `.w` builds a chain
+of proxies to track updates.
+
+### Update a document in a single call
+
+The `.update()` method is a convenience method to load and update a document.
+It allows a slightly cleaner implementation of the above example --- and saves
+you from forgetting to call `.write()`!
+
+```javascript
+const meats = ["pepperoni", "chicken", "sausage"];
+await pizzaCollection.existingDoc(docRef).update((pizza) => {
+  const isMeatIncluded = Object.entries(pizza.r.toppings).some(
+    ([name, topping]) => topping.isIncluded && name in meats
+  );
+  if (!isMeatIncluded) {
+    pizza.w.toppings.tags.push("vegetarian");
+  }
+});
+```
+
+### Make a copy
+
+Finally, use `.copy()` to get a deep copy of the document.  If an ID is not
+specified, it will be assigned randomly when the new doc is added to Firestore.
+The copy is solely local until `.write()` is called.
+
+```javascript
+const sourceRef = doc(db, "pizza", "margherita");
+const sourcePizza = await pizzaCollection.existingDoc(sourceRef).load();
+const newPizza = sourcePizza.copy("meaty margh");
+newPizza.name = "Meaty Margh";
+newPizza.toppings.sausage = {};
+newPizza.toppings.pepperoni = { included: false, surcharge: 1.25 };
+newPizza.toppings.chicken = { included: false, surcharge: 1.50 };
+delete newPizza.description;
+delete newPizza.toppings["fresh basil"];
+delete newPizza.tags.vegetarian;
+newPizza.write();
+```
+
+Note the use of the `delete` operator to remove optional fields and record and
+array items.
+
+### Get all docs in a collection
+
+You can retrieve all the documents in a collection or subcollection:
+
+```javascript
+const docs = await pizzaCollection().getAllDocs();
+```
+
+`docs` will contain an array of `FiretenderDoc` objects for all entries in the
+pizzas collection.  To get the contents of a subcollection, provide the ID(s) of
+its parent collection (and subcollections) to `getAllDocs()`.
+
+### Query a collection or subcollection
+
+To query a collection, call `query()` and pass in `where` clauses.  The
+[Firestore how-to
+guide](https://firebase.google.com/docs/firestore/query-data/queries) provides
+many examples of simple and compound queries.
+
+```javascript
+const veggieOptions = await pizzaCollection.query(
+  where("tags", "array-contains", "vegetarian")
+);
+const cheapClassics = await pizzaCollection.query(
+  where("baseprice", "<=", 10),
+  where("tags", "array-contains", "traditional")
+);
+```
+
+To query a specific subcollection, provide the ID(s) of its parent collection
+(and subcollections) as the first argument of `query()`.
+
+To perform a collection group query across all instances of a particular
+subcollection, leave out the IDs.  From the [Firestore how-to
+example](https://firebase.google.com/docs/firestore/query-data/queries#collection-group-query),
+you could retrieve all parks from all cities with this query:
+
+```javascript
+const cityLandmarkSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+});
+const cityLandmarkCollection = new FiretenderCollection(
+  cityLandmarkSchema,
+  [firestore, "cities", "landmarks"],
+  {}
+);
+
+const beijingParks = await cityLandmarkCollection.query(
+  "BJ",
+  where("type", "==", "park"))
+);
+// Resulting array contains the document for Jingshan Park.
+
+const allParks = await cityLandmarkCollection.query(
+  where("type", "==", "park")
+);
+// Resulting array has docs for Griffith Park, Ueno Park, and Jingshan Park.
+```
+
+### Delete a document
+
+To delete a document from the cities example:
+
+```javascript
+const citySchema = z.object({ /* ... */ });
+const cityCollection = new FiretenderCollection(
+  citySchema, [firestore, "cities"], {}
+);
+await cityCollection.delete("LA");
+```
+
+Subcollections are not deleted; in this example, the LA landmark docs would
+remain.  To also delete a document's subcollections, use `query()` to get lists
+of its subcollections' docs, then call `delete()` on each doc.  The Firestore
+guide recommends only performing such unbounded batched deletions from a trusted
+server environment.
+
+### Update all matching documents
+
+In an inventory of items, markup by 10% all items awaiting a price increase.
+
+```javascript
+const itemSchema = z.object({
+  name: z.string(),
+  price: z.number().nonnegative(),
+  tags: z.array(z.string()),
+});
+const inventoryCollection = new FiretenderCollection(itemSchema, [
+  firestore,
+  "inventory",
+]);
+
+await Promise.all(
+  inventoryCollection
+    .query(where("tags", "array-contains", "awaiting-price-increase"))
+    .map((itemDoc) =>
+      itemDoc.update((data) => {
+        data.price *= 1.1;
+        delete data.tags["awaiting-price-increase"];
+      })
+    )
+);
+```
+
+## TODO
+
+The [full list of issues](https://github.com/jakes-space/firetender/issues) is
+tracked on Github.  Here are some features on the roadmap:
+
+* Documentation
+  * Compile JSDoc to an API reference page in markdown.
+    ([#13](https://github.com/jakes-space/firetender/issues/13))
+* Concurrency
+  * Listen for changes and update the object if it has not been locally
+    modified.  Provide an onChange() callback option.
+    ([#14](https://github.com/jakes-space/firetender/issues/14))
+  * Support the Firestore transaction API.
+    ([#15](https://github.com/jakes-space/firetender/issues/15))
+* Improved timestamp handling, tests ([multiple
+  issues](https://github.com/jakes-space/firetender/issues?q=timestamp))
+
+## Alternatives
+
+This project is not stable yet.  If you're looking for a more mature Firestore
+helper, check out:
+
+* [Vuefire](https://github.com/vuejs/vuefire) and
+  [Reactfire](https://github.com/FirebaseExtended/reactfire) for integration
+  with their respective frameworks.
+
+* [Fireschema](https://github.com/yarnaimo/fireschema): Another strongly typed
+  framework for building and using schemas in Firestore.
+  
+* [firestore-fp](https://github.com/mobily/firestore-fp): If you like functional
+  programming.
+
+* [simplyfire](https://github.com/coturiv/simplyfire): Another
+  simplified API that is focused more on querying.  (And kudos to the author for
+  its great name.)
+
+I'm sure there are many more, and apologies if I missed your favorite.

package/dist/FiretenderCollection.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { CollectionReference, DocumentReference, Firestore, QueryConstraint } from "./firestore-deps";
+import { FiretenderDoc, FiretenderDocOptions } from "./FiretenderDoc";
+import { DeepPartial } from "./ts-helpers";
+/**
+ * A representation of a Firestore collection or subcollection.
+ *
+ * It represents a given "collection path": the collection names from a document
+ * reference, sans IDs.  All docs at /databases/{db}/documents/foo/{*}/bar/{*}
+ * are covered by a FiretenderCollection for the path ["foo", "bar"].
+ */
+export declare class FiretenderCollection<SchemaType extends z.SomeZodObject> {
+    /** Zod schema used to parse and validate the document's data */
+    readonly schema: SchemaType;
+    /** Firestore object: the thing you get from getFirestore() */
+    readonly firestore: Firestore;
+    /** The collection path of this object: a series of collection names */
+    readonly collectionPath: string[];
+    /** Function to return the initial values when creating a new document. */
+    readonly baseInitialDataFactory: (() => DeepPartial<z.input<SchemaType>>) | undefined;
+    /**
+     * @param schema the Zod object schema describing the documents in this
+     *   collection.
+     * @param firestore the thing you get from getFirestore().
+     * @param collectionPath the path of this collection in Firestore: the names
+     *   of any parent collections and of this collection.
+     * @param baseInitialData (optional) an object or object factory providing
+     *   default field values for this collection.
+     */
+    constructor(schema: SchemaType, firestore: Firestore, collectionPath: [string, ...string[]] | string, baseInitialData?: (() => DeepPartial<z.input<SchemaType>>) | DeepPartial<z.input<SchemaType>> | undefined);
+    /**
+     * Returns a FiretenderDoc representing a new document in this collection.
+     *
+     * This method initializes the FiretenderDoc but does not create it in
+     * Firestore.  To do so, call the doc's write() method.
+     *
+     * @param id the ID or array of IDs giving the path of the new document.
+     *   Firestore will generate a random doc ID if it is omitted.  If this is a
+     *   subcollection, the ID(s) for the parent collection(s) are required.
+     * @param initialData the document's initial data, which is merged with (and
+     *   potentially overwrites) field values specified in the constructor.
+     * @param options optional parameters for the resulting FiretenderDoc; see
+     *   FiretenderDocOptions for detail.
+     */
+    newDoc(id?: string[] | string | undefined, initialData?: DeepPartial<z.input<SchemaType>> | undefined, options?: FiretenderDocOptions): FiretenderDoc<SchemaType>;
+    /**
+     * Returns a FiretenderDoc representing an existing Firestore document in this
+     * collection.
+     *
+     * This method initializes the FiretenderDoc but does not load its data.  If
+     * the doc does not exist in Firestore, calling load() will throw an error.
+     *
+     * @param id the ID or array of IDs specifying the desired document.
+     * @param options optional parameters for the resulting FiretenderDoc; see
+     *   FiretenderDocOptions for detail.
+     */
+    existingDoc(id: string[] | string, options?: FiretenderDocOptions): FiretenderDoc<SchemaType>;
+    /**
+     * Returns an array of all the documents in this collection.
+     *
+     * If the collection may contain a large number of documents, use query() with
+     * the limit() and startAfter() constraints to paginate the results.
+     *
+     * @param id (optional) when querying a subcollection, the ID(s) of its parent
+     *   collection(s).
+     */
+    getAllDocs(id?: string[] | string | undefined): Promise<FiretenderDoc<SchemaType>[]>;
+    /**
+     * Returns an array of the documents matching the given query.
+     *
+     * @param id (optional) when querying a subcollection, the ID(s) of its parent
+     *   collection(s); omit when querying a top-level collection or when querying
+     *   all docs in this subcollection, regardless of parent.
+     * @param ...whereClauses the where(), limit(), orderBy(), startAfter(), etc.
+     *   constraints defining this query.
+     */
+    query(idOrWhereClause: string | string[] | QueryConstraint, ...moreWhereClauses: QueryConstraint[]): Promise<FiretenderDoc<SchemaType>[]>;
+    /**
+     * Deletes the given document from this collection.
+     *
+     * The document's subcollections (if any) are not deleted.  To delete them,
+     * first use query() to get its subcollection docs, then call delete() on each
+     * one.  Please note that the Firestore guide recommends only performing such
+     * unbounded batched deletions from a trusted server environment.
+     *
+     * @param id full path ID of the target document.
+     */
+    delete(id: string[] | string): Promise<void>;
+    /**
+     * Returns a document reference for the specified ID.
+     *
+     * @param id the ID or array of IDs specifying the desired document.
+     */
+    makeDocRef(id: string[] | string): DocumentReference;
+    /**
+     * Returns a collection reference for the specified ID.
+     *
+     * @param id the ID or array of IDs specifying the desired collection.
+     */
+    makeCollectionRef(id?: string[] | string | undefined): CollectionReference;
+    /**
+     * Builds a doc ref from the given IDs, or returns "undefined" if the IDs do
+     * not correctly specify a doc path.
+     */
+    private makeDocRefInternal;
+    /**
+     * Builds a collection ref from the given IDs, or returns "undefined" if the
+     * IDs do not correctly specify a collection path.
+     */
+    private makeCollectionRefInternal;
+    /**
+     * Executes the given query and returns an array of the results, wrapped in
+     * FiretenderDoc objects.
+     */
+    private getAndWrapDocs;
+}