@supersuit/firestore-double 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release, extracted from the hand-rolled doubles in continental-works-web (`src/lib/suits.test.mjs`, `src/lib/operator-number.test.mjs`) and supersuit-room-host (`src/lib/rooms/memory-store.ts`), after two of them let a read-after-write transaction pass tests and fail in production (2026-10-15, 2026-10-17).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+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

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @supersuit/firestore-double
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An in-memory Firestore for tests that refuses what production refuses: reads after writes in a transaction, updates of missing documents, undefined values.
+
+A test double is only worth having if it is at least as strict as the thing it stands in for. A hand-rolled one is usually laxer, and then the tests pass and production fails. This one is shaped like `firebase-admin`'s `Firestore`, so the code under test runs unchanged, and it throws Firestore's own errors where Firestore would.
+
+## 30 seconds
+
+```bash
+npm i -D @supersuit/firestore-double
+```
+
+```js
+import { createFirestore } from "@supersuit/firestore-double";
+
+const db = createFirestore();               // hand it wherever your code takes a Firestore
+await db.collection("accounts").doc("a").set({ email: "a@x" });
+
+await db.runTransaction(async (tx) => {
+  tx.set(db.doc("accounts/b"), { email: "b@x" });
+  await tx.get(db.doc("accounts/a"));       // throws, exactly as production does:
+});                                         // "Firestore transactions require all reads to be executed before all writes."
+
+db.peek("accounts/a");                      // test helper: the stored data
+```
+
+## What it enforces
+
+| Rule | What you get |
+| --- | --- |
+| Reads before writes in a transaction | `Firestore transactions require all reads to be executed before all writes.` (synchronous, like the SDK) |
+| Transaction writes are atomic | Nothing lands if the function throws or a precondition fails at commit |
+| `update()` needs the document | `5 NOT_FOUND: No document to update: <path>`, `err.code === 5` |
+| `create()` needs it absent | `6 ALREADY_EXISTS: Document already exists: <path>`, `err.code === 6` |
+| No `undefined` in data | Refused, unless `createFirestore({ ignoreUndefinedProperties: true })`, which drops it as Firestore does |
+| Read-only transactions | `runTransaction(fn, { readOnly: true })` refuses writes |
+| Path parity | `doc()` needs an even path, `collection()` an odd one |
+| Queries | `where` (`== != < <= > >= in not-in array-contains array-contains-any`) and `orderBy` drop documents lacking the field; range filters match their own type only; default order is by document id |
+| Copies | Everything read is a copy; mutating it never edits the store |
+
+Supported surface: `collection(path)`, `doc(path)`, `runTransaction(fn, opts)`; on a reference `get set update create delete collection parent`; on a query `where orderBy limit get count`; on a collection `doc() add()`; in a transaction `get(ref | query) getAll set update create delete`.
+
+Test helpers that real Firestore does not have: `db.docs` (a `Map` of full path to data), `db.peek(path)` or `db.peek("coll", "id")`, `db.seed(path, data)`.
+
+## Not modelled
+
+Composite-index requirements, `Timestamp` conversion (a `Date` comes back a `Date`), `FieldValue` sentinels, contention and retries, listeners, batches. Each would be a welcome addition, with a test that fails without it.
+
+## TypeScript
+
+Types ship in `src/index.d.mts`. Code typed against `Firestore` takes the double with a cast: `createFirestore() as unknown as Firestore`.

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@supersuit/firestore-double",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An in-memory Firestore for tests that refuses what production refuses: reads after writes in a transaction, updates of missing documents, undefined values.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "default": "./src/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SupersuitUp/firestore-double.git"
+  },
+  "dependencies": {},
+  "types": "./src/index.d.mts"
+}

package/src/index.d.mts

@@ -0,0 +1,66 @@
+// Types for @supersuit/firestore-double. The double is shaped like firebase-admin's Firestore, so
+// production code typed against `Firestore` accepts it with a cast (`db as unknown as Firestore`).
+export declare const READ_AFTER_WRITE: string
+export declare const READ_ONLY_WRITE: string
+
+type Data = Record<string, any>
+
+export interface DocumentSnapshot {
+  id: string
+  ref: DocumentReference
+  exists: boolean
+  data(): Data | undefined
+  get(field: string): any
+}
+export interface QuerySnapshot {
+  docs: DocumentSnapshot[]
+  size: number
+  empty: boolean
+  forEach(fn: (d: DocumentSnapshot) => void): void
+}
+export interface Query {
+  where(field: string, op: string, value: unknown): Query
+  orderBy(field: string, dir?: 'asc' | 'desc'): Query
+  limit(n: number): Query
+  get(): Promise<QuerySnapshot>
+  count(): { get(): Promise<{ data(): { count: number } }> }
+}
+export interface DocumentReference {
+  id: string
+  path: string
+  readonly parent: CollectionReference
+  collection(sub: string): CollectionReference
+  get(): Promise<DocumentSnapshot>
+  set(data: Data, opts?: { merge?: boolean }): Promise<unknown>
+  update(data: Data): Promise<unknown>
+  create(data: Data): Promise<unknown>
+  delete(): Promise<unknown>
+  isEqual(other: DocumentReference): boolean
+}
+export interface CollectionReference extends Query {
+  id: string
+  path: string
+  doc(id?: string): DocumentReference
+  add(data: Data): Promise<DocumentReference>
+}
+export interface Transaction {
+  get(ref: DocumentReference): Promise<DocumentSnapshot>
+  get(query: Query): Promise<QuerySnapshot>
+  getAll(...refs: DocumentReference[]): Promise<DocumentSnapshot[]>
+  set(ref: DocumentReference, data: Data, opts?: { merge?: boolean }): Transaction
+  update(ref: DocumentReference, data: Data): Transaction
+  create(ref: DocumentReference, data: Data): Transaction
+  delete(ref: DocumentReference): Transaction
+}
+export interface FirestoreDouble {
+  collection(path: string): CollectionReference
+  doc(path: string): DocumentReference
+  runTransaction<T>(fn: (tx: Transaction) => Promise<T>, opts?: { readOnly?: boolean }): Promise<T>
+  /** Test helper: every stored document, keyed by full path. */
+  docs: Map<string, Data>
+  /** Test helper: the stored data at a path ("a/b", or "a", "b"). */
+  peek(...parts: string[]): Data | undefined
+  /** Test helper: put a document in place without validation. */
+  seed(path: string, data: Data): void
+}
+export declare function createFirestore(settings?: { ignoreUndefinedProperties?: boolean }): FirestoreDouble

package/src/index.mjs

@@ -0,0 +1,264 @@
+// @supersuit/firestore-double: an in-memory stand-in for firebase-admin's Firestore, for tests.
+//
+// WHY IT EXISTS. Twice in three days a hand-rolled double was laxer than Firestore, the tests
+// passed, and production failed: Supersuit Rooms' retireMember (2026-10-15) and the account
+// server's registerSuit (2026-10-17) both read inside a transaction after writing, which
+// Firestore refuses. A double is only worth having if it refuses what production refuses, so
+// every rule below is one Firestore enforces, with Firestore's own error text where a caller
+// might match on it.
+//
+// Enforced: reads before writes in a transaction (the SDK's exact message), transaction writes
+// landing together or not at all, update() of a missing document (5 NOT_FOUND), create() of an
+// existing one (6 ALREADY_EXISTS), undefined anywhere in written data (unless the caller opts
+// into ignoreUndefinedProperties, as Firestore does), writes inside a readOnly transaction,
+// document and collection paths of the right parity, and query filters and orderBy dropping
+// documents that lack the field. Results are copies, so mutating one never edits the store.
+//
+// NOT modelled: composite-index requirements, Timestamp conversion (a Date comes back a Date,
+// where Firestore returns a Timestamp), FieldValue sentinels, contention and retries, listeners.
+import { isDeepStrictEqual } from "node:util";
+
+/** firebase-admin's text, copied from @google-cloud/firestore build/src/transaction.js. */
+export const READ_AFTER_WRITE = "Firestore transactions require all reads to be executed before all writes.";
+export const READ_ONLY_WRITE = "Firestore read-only transactions cannot execute writes.";
+
+const AUTO_ID = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const autoId = () => Array.from({ length: 20 }, () => AUTO_ID[Math.floor(Math.random() * AUTO_ID.length)]).join("");
+
+const isPlain = (v) => v !== null && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype;
+const clone = (v) => (v === undefined ? undefined : structuredClone(v));
+
+function grpcError(code, status, message) {
+  const e = new Error(`${code} ${status}: ${message}`);
+  e.code = code;
+  e.details = message;
+  return e;
+}
+
+function segments(path, kind) {
+  if (typeof path !== "string" || path === "") throw new Error(`Value for argument "${kind}Path" is not a valid resource path. Path must be a non-empty string.`);
+  const parts = path.split("/");
+  if (parts.some((p) => p === "")) throw new Error(`Value for argument "${kind}Path" is not a valid resource path. Paths must not contain //.`);
+  const wantOdd = kind === "collection";
+  if ((parts.length % 2 === 1) !== wantOdd) {
+    throw new Error(`Value for argument "${kind}Path" must point to a ${kind}, but was "${path}". Your path does not contain an ${wantOdd ? "odd" : "even"} number of components.`);
+  }
+  return parts;
+}
+
+function fieldValue(data, field) {
+  let cur = data;
+  for (const k of field.split(".")) {
+    if (!isPlain(cur) || !(k in cur)) return { has: false };
+    cur = cur[k];
+  }
+  return { has: true, value: cur };
+}
+
+function validate(data, ignoreUndefined, where = "") {
+  if (!isPlain(data)) throw new Error(`Value for argument "data" is not a valid Firestore document. Input is not a plain JavaScript object.`);
+  const walk = (v, at) => {
+    if (v === undefined) {
+      if (ignoreUndefined) return;
+      throw new Error(`Value for argument "data" is not a valid Firestore document. Cannot use "undefined" as a Firestore value (found in field "${at}"). If you want to ignore undefined values, enable \`ignoreUndefinedProperties\`.`);
+    }
+    if (typeof v === "function" || typeof v === "symbol") throw new Error(`Value for argument "data" is not a valid Firestore document. Couldn't serialize object of type "${typeof v}" (found in field "${at}").`);
+    if (Array.isArray(v)) v.forEach((x, i) => { if (Array.isArray(x)) throw new Error(`Value for argument "data" is not a valid Firestore document. Cannot use nested arrays (found in field "${at}.${i}").`); walk(x, at); });
+    else if (isPlain(v)) for (const [k, x] of Object.entries(v)) walk(x, at ? `${at}.${k}` : k);
+  };
+  for (const [k, v] of Object.entries(data)) walk(v, where ? `${where}.${k}` : k);
+}
+
+function strip(v) {
+  // With ignoreUndefinedProperties, Firestore drops the field rather than storing it.
+  if (Array.isArray(v)) return v.filter((x) => x !== undefined).map(strip);
+  if (isPlain(v)) return Object.fromEntries(Object.entries(v).filter(([, x]) => x !== undefined).map(([k, x]) => [k, strip(x)]));
+  return v;
+}
+
+function deepMerge(base, patch) {
+  const out = isPlain(base) ? { ...base } : {};
+  for (const [k, v] of Object.entries(patch)) out[k] = isPlain(v) && isPlain(out[k]) ? deepMerge(out[k], v) : v;
+  return out;
+}
+
+function setPath(obj, field, value) {
+  const keys = field.split(".");
+  let cur = obj;
+  for (const k of keys.slice(0, -1)) { if (!isPlain(cur[k])) cur[k] = {}; cur = cur[k]; }
+  cur[keys.at(-1)] = value;
+}
+
+// Firestore orders values of different types by type first; within a type, by value.
+const TYPE_ORDER = (v) => v === null ? 0 : typeof v === "boolean" ? 1 : typeof v === "number" ? 2 : v instanceof Date ? 3 : typeof v === "string" ? 4 : Array.isArray(v) ? 6 : 7;
+function compare(a, b) {
+  const ta = TYPE_ORDER(a), tb = TYPE_ORDER(b);
+  if (ta !== tb) return ta - tb;
+  if (a instanceof Date) return a.getTime() - b.getTime();
+  if (typeof a === "number" || typeof a === "string" || typeof a === "boolean") return a < b ? -1 : a > b ? 1 : 0;
+  return 0;
+}
+const sameType = (a, b) => TYPE_ORDER(a) === TYPE_ORDER(b);
+
+const MATCH = {
+  "==": (v, x) => isDeepStrictEqual(v, x),
+  "!=": (v, x) => v !== null && !isDeepStrictEqual(v, x),
+  "<": (v, x) => sameType(v, x) && compare(v, x) < 0,
+  "<=": (v, x) => sameType(v, x) && compare(v, x) <= 0,
+  ">": (v, x) => sameType(v, x) && compare(v, x) > 0,
+  ">=": (v, x) => sameType(v, x) && compare(v, x) >= 0,
+  "in": (v, xs) => xs.some((x) => isDeepStrictEqual(v, x)),
+  "not-in": (v, xs) => v !== null && !xs.some((x) => isDeepStrictEqual(v, x)),
+  "array-contains": (v, x) => Array.isArray(v) && v.some((e) => isDeepStrictEqual(e, x)),
+  "array-contains-any": (v, xs) => Array.isArray(v) && v.some((e) => xs.some((x) => isDeepStrictEqual(e, x))),
+};
+
+/**
+ * A fresh, empty in-memory Firestore shaped like firebase-admin's.
+ * @param {{ ignoreUndefinedProperties?: boolean }} [settings]
+ */
+export function createFirestore(settings = {}) {
+  const ignoreUndefined = !!settings.ignoreUndefinedProperties;
+  /** Every document, keyed by its full path ("rooms/r1/members/m1"). Tests may read and seed it. */
+  const docs = new Map();
+
+  const prepare = (data) => { validate(data, ignoreUndefined); return clone(ignoreUndefined ? strip(data) : data); };
+
+  function snapshot(ref, data) {
+    return {
+      id: ref.id, ref, exists: data !== undefined,
+      data: () => clone(data),
+      get: (field) => (data === undefined ? undefined : clone(fieldValue(data, field).value)),
+    };
+  }
+
+  // Write operations as pure functions of a document map, so a transaction can run them on a copy.
+  const ops = {
+    set(map, path, data, opts) { map.set(path, opts?.merge ? deepMerge(map.get(path), data) : data); },
+    update(map, path, data) {
+      if (!map.has(path)) throw grpcError(5, "NOT_FOUND", `No document to update: ${path}`);
+      const next = structuredClone(map.get(path));
+      for (const [k, v] of Object.entries(data)) setPath(next, k, v);
+      map.set(path, next);
+    },
+    create(map, path, data) {
+      if (map.has(path)) throw grpcError(6, "ALREADY_EXISTS", `Document already exists: ${path}`);
+      map.set(path, data);
+    },
+    delete(map, path) { map.delete(path); },
+  };
+  function prepareUpdate(data) {
+    if (!isPlain(data) || Object.keys(data).length === 0) throw new Error("At least one field must be updated.");
+    validate(data, ignoreUndefined);
+    return clone(ignoreUndefined ? strip(data) : data);
+  }
+
+  function docRef(path) {
+    const parts = segments(path, "document");
+    const ref = {
+      id: parts.at(-1), path, firestore: db,
+      get parent() { return collectionRef(parts.slice(0, -1).join("/")); },
+      collection: (sub) => collectionRef(`${path}/${sub}`),
+      get: async () => snapshot(ref, docs.get(path)),
+      set: async (data, opts) => { ops.set(docs, path, prepare(data), opts); return {}; },
+      update: async (data) => { ops.update(docs, path, prepareUpdate(data)); return {}; },
+      create: async (data) => { ops.create(docs, path, prepare(data)); return {}; },
+      delete: async () => { ops.delete(docs, path); return {}; },
+      isEqual: (other) => other?.path === path,
+    };
+    return ref;
+  }
+
+  function query(collPath, filters = [], orders = [], lim = null) {
+    const depth = collPath.split("/").length + 1;
+    const run = () => {
+      let rows = [];
+      for (const [path, data] of docs) {
+        if (!path.startsWith(collPath + "/") || path.split("/").length !== depth) continue;
+        rows.push([path, data]);
+      }
+      rows = rows.filter(([, d]) => filters.every(([f, op, x]) => { const { has, value } = fieldValue(d, f); return has && MATCH[op](value, x); }));
+      rows = rows.filter(([, d]) => orders.every(([f]) => fieldValue(d, f).has));
+      rows.sort(([pa, a], [pb, b]) => {
+        for (const [f, dir] of orders) {
+          const c = compare(fieldValue(a, f).value, fieldValue(b, f).value);
+          if (c) return dir === "desc" ? -c : c;
+        }
+        return pa < pb ? -1 : pa > pb ? 1 : 0; // then by document id, as Firestore does
+      });
+      if (lim !== null) rows = rows.slice(0, lim);
+      const out = rows.map(([p, d]) => snapshot(docRef(p), d));
+      return { docs: out, size: out.length, empty: out.length === 0, forEach: (fn) => out.forEach(fn) };
+    };
+    return {
+      where(field, op, value) {
+        if (!MATCH[op]) throw new Error(`Invalid value for argument "opStr". Acceptable values are: ${Object.keys(MATCH).join(", ")}`);
+        if (value === undefined) throw new Error(`Value for argument "value" is not a valid query constraint. Cannot use "undefined" as a Firestore value.`);
+        if ((op === "in" || op === "not-in" || op === "array-contains-any") && !Array.isArray(value)) throw new Error(`Invalid Query. A non-empty array is required for '${op}' filters.`);
+        return query(collPath, [...filters, [field, op, value]], orders, lim);
+      },
+      orderBy(field, dir = "asc") {
+        if (dir !== "asc" && dir !== "desc") throw new Error(`Invalid value for argument "directionStr". Acceptable values are: asc, desc`);
+        return query(collPath, filters, [...orders, [field, dir]], lim);
+      },
+      limit(n) { return query(collPath, filters, orders, n); },
+      get: async () => run(),
+      count: () => ({ get: async () => { const n = run().size; return { data: () => ({ count: n }) }; } }),
+      _run: run,
+    };
+  }
+
+  function collectionRef(path) {
+    const parts = segments(path, "collection");
+    return {
+      ...query(path),
+      id: parts.at(-1), path, firestore: db,
+      doc: (id) => docRef(`${path}/${id === undefined ? autoId() : id}`),
+      add: async (data) => { const ref = docRef(`${path}/${autoId()}`); await ref.create(data); return ref; },
+    };
+  }
+
+  async function runTransaction(fn, opts = {}) {
+    const writes = [];
+    const readOnly = !!opts.readOnly;
+    const write = (op) => (ref, data, setOpts) => {
+      if (readOnly) throw new Error(READ_ONLY_WRITE);
+      const prepared = op === "delete" ? undefined : op === "update" ? prepareUpdate(data) : prepare(data);
+      writes.push([op, ref.path, prepared, setOpts]);
+      return tx;
+    };
+    const tx = {
+      // Synchronous throw, as the SDK does: Transaction.get is not async.
+      get(refOrQuery) {
+        if (writes.length) throw new Error(READ_AFTER_WRITE);
+        if (typeof refOrQuery?._run === "function") return Promise.resolve(refOrQuery._run());
+        return refOrQuery.get();
+      },
+      getAll(...refs) {
+        if (writes.length) throw new Error(READ_AFTER_WRITE);
+        return Promise.all(refs.map((r) => r.get()));
+      },
+      set: write("set"), update: write("update"), create: write("create"), delete: write("delete"),
+    };
+    const result = await fn(tx);
+    // Commit: every write lands, or (on a failed precondition) none does.
+    const next = new Map(docs);
+    for (const [op, path, data, setOpts] of writes) ops[op](next, path, data, setOpts);
+    docs.clear();
+    for (const [k, v] of next) docs.set(k, v);
+    return result;
+  }
+
+  const db = {
+    collection: (path) => collectionRef(path),
+    doc: (path) => docRef(path),
+    runTransaction,
+    /** Test helper: everything stored, keyed by full document path. */
+    docs,
+    /** Test helper: the stored data at a path, given whole ("a/b") or in segments ("a", "b"). */
+    peek: (...parts) => clone(docs.get(parts.join("/"))),
+    /** Test helper: put a document in place without going through validation. */
+    seed: (path, data) => { segments(path, "document"); docs.set(path, clone(data)); },
+  };
+  return db;
+}