firetender 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# FireTender
+
+FireTender is a wrapper for Firestore documents to make reading and writing them
+simpler and safer.  A Firestore doc looks like any other Typescript object, and
+they are validated upon reading and writing.
+
+Querying and concurrency are not yet supported.  I'm adding features as I need
+them, but contributions are most welcome.  See the list of [alternative
+packages](#alternatives) at the end of this README if you're looking for
+something more mature.
+
+## Usage
+
+To illustrate, let's run through the basics of defining, creating, reading, and
+modifying a Firestore document.
+
+### Define your schemas
+
+First, we define the document schemas and their validation criteria with
+[Zod](https://github.com/colinhacks/zod).  If you've used Joi or Yup, you will
+find Zod very similar.  Optional collections should use `.default({})` or
+`.default([])` to simplify later access.  Here we define a schema for types of
+pizza, because I was hungry when I first wrote this.
+
+Then create `pizzaWrapper`, which is a factory that makes objects to wrap
+Firestore documents and enforce the given schema.
+
+```javascript
+import { doc } from "firebase/firestore";
+import { DocWrapper } from "firetender";
+import { z } from "zod";
+
+const pizzaSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  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"],
+      })
+  ),
+  tags: z.array(z.string()).default([]),
+});
+
+const pizzaWrapper = new DocWrapper(pizzaSchema);
+```
+
+### Add a document
+
+Let's add a document to the `pizzas` collection with an ID of `margherita`.  We
+use `DocWrapper.prototype.createNew()` to create a validated local object
+representing a new document in the collection.  We then add the doc to Firestore
+by calling its `.write()` method.
+
+```javascript
+const docRef = doc(db, "pizzas", "margherita");
+const pizza = pizzaWrapper.createNew(docRef, {
+  name: "Margherita",
+  toppings: { "fresh mozzarella": {}, "fresh basil": {} },
+  tags: ["traditional"],
+});
+await pizza.write();
+```
+
+If we don't care about the doc ID, we can also pass a collection reference
+(e.g., `collection(db, "pizzas")`) to `.createNew()`.  Firestore will assign a
+random ID.
+
+### Read and modify a document
+
+To read or modify an existing document, we instantiate a doc wrapper using
+`DocWrapper.prototype.wrapExisting()`, passing in the doc's Firestore reference.
+To read from it, we call `.load()` and access the data with `.ro` (read only);
+to write, we modify the `.rw` accessor and then call `.write()`.  They can be
+used in combination, like so:
+
+```javascript
+const meats = ["pepperoni", "chicken", "sausage"];
+const pizza = await pizzaWrapper.wrapExisting(docRef).load();
+const isMeatIncluded = Object.entries(pizza.ro.toppings).some(
+  ([name, topping]) => topping.isIncluded && name in meats
+);
+if (!isMeatIncluded) {
+  pizza.rw.toppings.tags.push("vegetarian");
+}
+await pizza.write();
+```
+
+### Make a copy
+
+Here we create a new pizza in the same collection.  Alternatively, a document
+can be copied to elsewhere by specifying a document or collection reference.
+
+```javascript
+const sourceRef = doc(db, "pizza", "margherita");
+const sourcePizza = await pizzaWrapper.wrapExisting(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.toppings["fresh basil"];
+delete newPizza.tags.vegetarian;
+newPizza.write();
+```
+
+## TODO
+
+* Concurrency
+  * Listen for changes and update the object if it has not been locally
+    modified.  Provide an onChange() callback option.
+  * Support the Firestore transaction API.
+* Queries
+* Document deletion
+* Improved timestamp handling
+* Prod releases
+  * Block on failing tests
+  * Minify code (esbuild?)
+  * Release on github
+
+## Alternatives
+
+This project is not at all 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 are a
+  functional programming aficionado.
+
+* [simplyfire](https://github.com/coturiv/simplyfire): A brilliantly named
+  simplified API that is focused more on querying.
+
+I'm sure there are many more, and apologies if I missed your favorite.

package/dist/DocWrapper.d.ts

@@ -0,0 +1,15 @@
+import { CollectionReference, DocumentReference } from "firebase/firestore";
+import { z } from "zod";
+import { FireTenderDoc, FireTenderDocOptions } from "./FireTenderDoc";
+/**
+ * Factory for FireTenderDoc objects based on the given schema.
+ */
+export declare class DocWrapper<SchemaType extends z.SomeZodObject, DataType extends {
+    [x: string]: any;
+} = z.infer<SchemaType>> {
+    private schema;
+    constructor(schema: SchemaType);
+    createNew(ref: DocumentReference | CollectionReference, initialData: any, // TODO: change to "DataType," after defaults are dropped.
+    options?: FireTenderDocOptions): FireTenderDoc<SchemaType, DataType>;
+    wrapExisting(ref: DocumentReference | CollectionReference, options?: FireTenderDocOptions): FireTenderDoc<SchemaType, DataType>;
+}

package/dist/DocWrapper.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocWrapper = void 0;
+const FireTenderDoc_1 = require("./FireTenderDoc");
+/**
+ * Factory for FireTenderDoc objects based on the given schema.
+ */
+class DocWrapper {
+    constructor(schema) {
+        this.schema = schema;
+    }
+    createNew(ref, initialData, // TODO: change to "DataType," after defaults are dropped.
+    options = {}) {
+        const mergedOptions = {
+            ...options,
+            createDoc: true,
+            initialData,
+        };
+        return new FireTenderDoc_1.FireTenderDoc(this.schema, ref, mergedOptions);
+    }
+    wrapExisting(ref, options = {}) {
+        return new FireTenderDoc_1.FireTenderDoc(this.schema, ref, options);
+    }
+}
+exports.DocWrapper = DocWrapper;
+//# sourceMappingURL=DocWrapper.js.map

package/dist/DocWrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocWrapper.js","sourceRoot":"","sources":["../src/DocWrapper.ts"],"names":[],"mappings":";;;AAEA,mDAAsE;AAEtE;;GAEG;AACH,MAAa,UAAU;IAErB,YAAoB,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAE1C,SAAS,CACP,GAA4C,EAC5C,WAAgB,EAAE,0DAA0D;IAC5E,UAAgC,EAAE;QAElC,MAAM,aAAa,GAAyB;YAC1C,GAAG,OAAO;YACV,SAAS,EAAE,IAAI;YACf,WAAW;SACZ,CAAC;QACF,OAAO,IAAI,6BAAa,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;IAC5D,CAAC;IAED,YAAY,CACV,GAA4C,EAC5C,UAAgC,EAAE;QAElC,OAAO,IAAI,6BAAa,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;CACF;AAvBD,gCAuBC"}

package/dist/FireTenderDoc.d.ts

@@ -0,0 +1,32 @@
+import { CollectionReference, DocumentReference } from "firebase/firestore";
+import { z } from "zod";
+export declare type DeepReadonly<T> = T extends Array<infer ArrKey> ? ReadonlyArray<DeepReadonly<ArrKey>> : T extends Map<infer MapKey, infer MapVal> ? ReadonlyMap<DeepReadonly<MapKey>, DeepReadonly<MapVal>> : T extends Set<infer SetKey> ? ReadonlySet<DeepReadonly<SetKey>> : T extends Record<any, unknown> ? {
+    readonly [ObjKey in keyof T]: DeepReadonly<T[ObjKey]>;
+} : T;
+export declare type FireTenderDocOptions = {
+    createDoc?: true;
+    initialData?: any;
+};
+/**
+ * Helper class for reading and writing Firestore data based on Zod schemas.
+ */
+export declare class FireTenderDoc<SchemaType extends z.SomeZodObject, DataType extends {
+    [x: string]: any;
+} = z.infer<SchemaType>> {
+    readonly schema: SchemaType;
+    private ref;
+    private isNewDoc;
+    private docID;
+    private data;
+    private dataProxy;
+    private updates;
+    constructor(schema: SchemaType, ref: DocumentReference | CollectionReference, options?: FireTenderDocOptions);
+    get id(): string | undefined;
+    get docRef(): DocumentReference;
+    copy(dest?: DocumentReference | CollectionReference | string | undefined, options?: FireTenderDocOptions): FireTenderDoc<SchemaType, DataType>;
+    load(force?: boolean): Promise<this>;
+    get ro(): DeepReadonly<DataType>;
+    get rw(): DataType;
+    write(): Promise<void>;
+    private onChange;
+}

package/dist/FireTenderDoc.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireTenderDoc = void 0;
+const firestore_1 = require("firebase/firestore");
+const proxies_1 = require("./proxies");
+function assertIsDefined(value) {
+    if (value === undefined || value === null) {
+        throw new TypeError(`${value} is not defined`);
+    }
+}
+/**
+ * Helper class for reading and writing Firestore data based on Zod schemas.
+ */
+class FireTenderDoc {
+    constructor(schema, ref, options = {}) {
+        this.docID = undefined;
+        this.data = undefined;
+        this.dataProxy = undefined;
+        this.updates = new Map();
+        this.schema = schema;
+        this.ref = ref;
+        this.isNewDoc = options.createDoc ?? false;
+        console.log(ref, ref instanceof firestore_1.DocumentReference, options);
+        if (this.isNewDoc) {
+            if (!options.initialData) {
+                throw ReferenceError("Initial data must be given when creating a new doc.");
+            }
+            this.data = schema.parse(options.initialData);
+        }
+        if (this.ref.type === "document") {
+            this.docID = this.ref.path.split("/").pop();
+        }
+        else if (!this.isNewDoc) {
+            throw TypeError("FireTender can only take a collection reference when creating a new document.  Use FireTender.createDoc() if this is your intent.");
+        }
+    }
+    get id() {
+        return this.docID;
+    }
+    get docRef() {
+        if (this.ref.type === "document") {
+            return this.ref;
+        }
+        throw Error("docRef can only be accessed after the new doc has been written.");
+    }
+    copy(dest = undefined, options = {}) {
+        if (!this.data) {
+            throw Error("You must call load() before making a copy.");
+        }
+        let ref;
+        if (dest && typeof dest !== "string") {
+            ref = dest;
+        }
+        else {
+            const collectionRef = this.ref.type === "document" ? this.ref.parent : this.ref;
+            if (dest) {
+                ref = (0, firestore_1.doc)(collectionRef, dest);
+            }
+            else {
+                ref = collectionRef;
+            }
+        }
+        const mergedOptions = {
+            ...options,
+            createDoc: true,
+            initialData: this.data,
+        };
+        return new FireTenderDoc(this.schema, ref, mergedOptions);
+    }
+    async load(force = false) {
+        if (this.isNewDoc || this.ref.type === "collection") {
+            throw Error("load() should not be called for new documents.");
+        }
+        if (!this.data || force) {
+            const snapshot = await (0, firestore_1.getDoc)(this.ref);
+            if (!snapshot.exists()) {
+                throw new Error("Document does not exist.");
+            }
+            this.data = this.schema.parse(snapshot.data());
+            // Dereference the old proxy, if any, to force a recapture of data.
+            this.dataProxy = undefined;
+        }
+        return this;
+    }
+    get ro() {
+        if (!this.data) {
+            throw Error("You must call load() before using the .ro accessor.");
+        }
+        return this.data;
+    }
+    get rw() {
+        if (this.isNewDoc) {
+            // No need to monitor changes if we're creating rather than updating.
+            return this.data;
+        }
+        if (!this.dataProxy) {
+            if (!this.data) {
+                throw Error("You must call load() before using the .rw accessor.");
+            }
+            this.dataProxy = (0, proxies_1.watchFieldForChanges)([], this.schema, this.data, this.onChange.bind(this));
+        }
+        return this.dataProxy;
+    }
+    async write() {
+        if (this.isNewDoc) {
+            assertIsDefined(this.data);
+            if (this.ref.type === "document") {
+                await (0, firestore_1.setDoc)(this.ref, this.data);
+            }
+            else {
+                this.ref = await (0, firestore_1.addDoc)(this.ref, this.data);
+                this.docID = this.ref.path.split("/").pop();
+            }
+            this.isNewDoc = false;
+        }
+        else {
+            if (!(this.ref.type === "document")) {
+                // We should never get here.
+                throw Error("Internal error.  FireTender object should always reference a document when updating an existing doc.");
+            }
+            if (this.updates.size === 0) {
+                return;
+            }
+            const flatUpdateList = Array.from(this.updates.entries()).flat();
+            await (0, firestore_1.updateDoc)(this.ref, flatUpdateList[0], flatUpdateList[1], ...flatUpdateList.slice(2));
+        }
+    }
+    onChange(fieldPath, newValue) {
+        this.updates.set(fieldPath.join("."), newValue);
+    }
+}
+exports.FireTenderDoc = FireTenderDoc;
+//# sourceMappingURL=FireTenderDoc.js.map

package/dist/FireTenderDoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FireTenderDoc.js","sourceRoot":"","sources":["../src/FireTenderDoc.ts"],"names":[],"mappings":"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"}

package/dist/Timestamps.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * Timestamp representation used by Firestore: seconds and nanoseconds since the
+ * epoch.
+ */
+export declare const timestampSchema: z.ZodObject<{
+    seconds: z.ZodNumber;
+    nanoseconds: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    seconds: number;
+    nanoseconds: number;
+}, {
+    seconds: number;
+    nanoseconds: number;
+}>;
+export declare type TimestampData = z.infer<typeof timestampSchema>;
+export declare function dateFromTimestamp(timestamp: TimestampData): Date;
+export declare function makeTTL(daysFromNow?: number): {
+    seconds: number;
+    nanoseconds: number;
+};
+export declare function timestampFromDate(date: Date): TimestampData;
+export declare function timestampFromUnixMillis(msSinceEpoch: number): TimestampData;
+export declare function nowTimestamp(): {
+    seconds: number;
+    nanoseconds: number;
+};

package/dist/Timestamps.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nowTimestamp = exports.timestampFromUnixMillis = exports.timestampFromDate = exports.makeTTL = exports.dateFromTimestamp = exports.timestampSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Timestamp representation used by Firestore: seconds and nanoseconds since the
+ * epoch.
+ */
+exports.timestampSchema = zod_1.z.object({
+    seconds: zod_1.z.number().positive().int(),
+    nanoseconds: zod_1.z.number().nonnegative().int(),
+});
+// TODO: probably want to move these timestamp functions into their own helper
+// module
+function dateFromTimestamp(timestamp) {
+    return new Date(timestamp.seconds * 1e3 + timestamp.nanoseconds / 1e6);
+}
+exports.dateFromTimestamp = dateFromTimestamp;
+function makeTTL(daysFromNow = 30) {
+    // TODO: is there a way to use the server time rather than Date.now()?
+    return timestampFromUnixMillis(Date.now() + daysFromNow * 24 * 60 * 60 * 1000);
+}
+exports.makeTTL = makeTTL;
+function timestampFromDate(date) {
+    return timestampFromUnixMillis(date.getTime());
+}
+exports.timestampFromDate = timestampFromDate;
+function timestampFromUnixMillis(msSinceEpoch) {
+    return {
+        seconds: Math.floor(msSinceEpoch / 1000),
+        nanoseconds: Math.floor((msSinceEpoch % 1000) * 1000000),
+    };
+}
+exports.timestampFromUnixMillis = timestampFromUnixMillis;
+function nowTimestamp() {
+    // TODO: is there a way to use the server time rather than Date.now()?
+    return timestampFromUnixMillis(Date.now());
+}
+exports.nowTimestamp = nowTimestamp;
+//# sourceMappingURL=Timestamps.js.map

package/dist/Timestamps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timestamps.js","sourceRoot":"","sources":["../src/Timestamps.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB;;;GAGG;AACU,QAAA,eAAe,GAAG,OAAC,CAAC,MAAM,CAAC;IACtC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE;IACpC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE;CAC5C,CAAC,CAAC;AAGH,8EAA8E;AAC9E,SAAS;AAET,SAAgB,iBAAiB,CAAC,SAAwB;IACxD,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,GAAG,GAAG,SAAS,CAAC,WAAW,GAAG,GAAG,CAAC,CAAC;AACzE,CAAC;AAFD,8CAEC;AAED,SAAgB,OAAO,CAAC,WAAW,GAAG,EAAE;IACtC,sEAAsE;IACtE,OAAO,uBAAuB,CAC5B,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAC/C,CAAC;AACJ,CAAC;AALD,0BAKC;AAED,SAAgB,iBAAiB,CAAC,IAAU;IAC1C,OAAO,uBAAuB,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AACjD,CAAC;AAFD,8CAEC;AAED,SAAgB,uBAAuB,CAAC,YAAoB;IAC1D,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;QACxC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC;KACzD,CAAC;AACJ,CAAC;AALD,0DAKC;AAED,SAAgB,YAAY;IAC1B,sEAAsE;IACtE,OAAO,uBAAuB,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AAC7C,CAAC;AAHD,oCAGC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { DocWrapper } from "./DocWrapper";
+export { FireTenderDoc } from "./FireTenderDoc";
+export * from "./Timestamps";

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FireTenderDoc = exports.DocWrapper = void 0;
+var DocWrapper_1 = require("./DocWrapper");
+Object.defineProperty(exports, "DocWrapper", { enumerable: true, get: function () { return DocWrapper_1.DocWrapper; } });
+var FireTenderDoc_1 = require("./FireTenderDoc");
+Object.defineProperty(exports, "FireTenderDoc", { enumerable: true, get: function () { return FireTenderDoc_1.FireTenderDoc; } });
+__exportStar(require("./Timestamps"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AACtB,+CAA6B"}

package/dist/proxies.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+export declare function watchArrayForChanges<ArrayElementType, FieldSchemaType extends z.ZodTypeAny>(arrayPath: string[], array: ArrayElementType[], fieldSchema: FieldSchemaType, field: z.infer<FieldSchemaType>, onChange: (path: string[], newValue: any) => void): z.infer<FieldSchemaType>;
+export declare function watchFieldForChanges<FieldSchemaType extends z.ZodTypeAny>(fieldPath: string[], fieldSchema: FieldSchemaType, field: z.infer<FieldSchemaType>, onChange: (path: string[], newValue: any) => void): z.infer<FieldSchemaType>;

package/dist/proxies.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchFieldForChanges = exports.watchArrayForChanges = void 0;
+const firestore_1 = require("firebase/firestore");
+const zod_1 = require("zod");
+function assertKeyIsString(key) {
+    if (typeof key !== "string") {
+        throw TypeError("Property access using symbols is not supported.");
+    }
+}
+function unwrapSchema(schema) {
+    if (schema instanceof zod_1.z.ZodOptional || schema instanceof zod_1.z.ZodNullable) {
+        return unwrapSchema(schema.unwrap());
+    }
+    if (schema instanceof zod_1.z.ZodDefault) {
+        return unwrapSchema(schema.removeDefault());
+    }
+    if (schema instanceof zod_1.z.ZodEffects) {
+        return unwrapSchema(schema.innerType());
+    }
+    return schema;
+}
+function getPropertySchema(parentSchema, propertyKey) {
+    const schema = unwrapSchema(parentSchema);
+    if (schema instanceof zod_1.z.ZodRecord) {
+        return schema.valueSchema;
+    }
+    if (schema instanceof zod_1.z.ZodArray) {
+        return schema.element;
+    }
+    if (schema instanceof zod_1.z.ZodObject) {
+        return schema.shape[propertyKey];
+    }
+    throw TypeError(`Unsupported schema type for property "${propertyKey}": ${schema.constructor.name}`);
+}
+function watchArrayForChanges(arrayPath, array, fieldSchema, field, onChange) {
+    return new Proxy(field, {
+        get(target, propertyKey) {
+            assertKeyIsString(propertyKey);
+            const property = target[propertyKey];
+            if (property instanceof Function) {
+                const result = (...args) => property.apply(field, args);
+                // TODO (easy): have a list of functions that don't trigger onChange.
+                // TODO (harder): also handle at, foreach, etc. methods to chain proxies
+                // down from them.  But life's too short for that.
+                onChange(arrayPath, array);
+                return result;
+            }
+            if (property instanceof Object) {
+                return watchArrayForChanges(arrayPath, array, getPropertySchema(fieldSchema, propertyKey), property, onChange);
+            }
+            return property;
+        },
+        set(target, propertyKey, value) {
+            assertKeyIsString(propertyKey);
+            const propertySchema = getPropertySchema(fieldSchema, propertyKey);
+            const parsedValue = propertySchema.parse(value);
+            const result = Reflect.set(target, propertyKey, parsedValue);
+            onChange(arrayPath, array);
+            return result;
+        },
+        deleteProperty(target, propertyKey) {
+            assertKeyIsString(propertyKey);
+            // Calling Reflect.deleteProperty on an array item sets it to undefined,
+            // which causes Firestore updates to fail unless ignoreUndefinedProperties
+            // is set, and which is generally not what we want.  Hence splice.
+            const removedValues = array.splice(Number(propertyKey), 1);
+            if (removedValues.length !== 1) {
+                throw RangeError(`Failed to delete array item with index ${propertyKey}.  Out of bounds?`);
+            }
+            if (target === array) {
+                onChange(arrayPath, (0, firestore_1.arrayRemove)(removedValues[0]));
+            }
+            else {
+                onChange(arrayPath, array);
+            }
+            return true;
+        },
+    });
+}
+exports.watchArrayForChanges = watchArrayForChanges;
+function watchFieldForChanges(fieldPath, fieldSchema, field, onChange) {
+    return new Proxy(field, {
+        get(target, propertyKey) {
+            assertKeyIsString(propertyKey);
+            const property = target[propertyKey];
+            if (property instanceof Function) {
+                return (...args) => property.apply(field, args);
+            }
+            if (property instanceof Array) {
+                return watchArrayForChanges([...fieldPath, propertyKey], property, getPropertySchema(fieldSchema, propertyKey), property, onChange);
+            }
+            if (property instanceof Object) {
+                return watchFieldForChanges([...fieldPath, propertyKey], getPropertySchema(fieldSchema, propertyKey), property, onChange);
+            }
+            return property;
+        },
+        set(target, propertyKey, value) {
+            assertKeyIsString(propertyKey);
+            const propertySchema = getPropertySchema(fieldSchema, propertyKey);
+            const parsedValue = propertySchema.parse(value);
+            onChange([...fieldPath, propertyKey], parsedValue);
+            return Reflect.set(target, propertyKey, parsedValue);
+        },
+        deleteProperty(target, propertyKey) {
+            assertKeyIsString(propertyKey);
+            onChange([...fieldPath, propertyKey], (0, firestore_1.deleteField)());
+            return Reflect.deleteProperty(target, propertyKey);
+        },
+    });
+}
+exports.watchFieldForChanges = watchFieldForChanges;
+//# sourceMappingURL=proxies.js.map

package/dist/proxies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxies.js","sourceRoot":"","sources":["../src/proxies.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "firetender",
+  "displayName": "FireTender",
+  "description": "Typescript wrapper for Firestore documents",
+  "version": "0.1.0",
+  "author": "Jake Hartman",
+  "license": "MIT",
+  "homepage": "https://github.com/jakes-space/firetender",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jakes-space/firetender.git"
+  },
+  "keywords": [
+    "firestore",
+    "typescript",
+    "schema"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "lint": "eslint",
+    "test": "jest"
+  },
+  "dependencies": {
+    "firebase": "^9.13.0",
+    "zod": "^3.19.1"
+  },
+  "devDependencies": {
+    "@firebase/rules-unit-testing": "^2.0.5",
+    "@rushstack/eslint-patch": "^1.2.0",
+    "@types/jest": "^29.2.0",
+    "@typescript-eslint/eslint-plugin": "^5.41.0",
+    "@typescript-eslint/parser": "^5.41.0",
+    "eslint": "^8.26.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-import-resolver-typescript": "^3.5.2",
+    "eslint-plugin-import": "^2.26.0",
+    "jest": "^29.2.2",
+    "prettier": "^2.7.1",
+    "ts-jest": "^29.0.3",
+    "tslib": "^2.4.1",
+    "typescript": "^4.8.4"
+  }
+}