@moifort/stack 0.0.0-stage → 0.1.0

package/templates/backend/server/test/fake-firestore.ts

@@ -0,0 +1,483 @@
+/**
+ * In-memory Firestore fake for unit tests. Records every created batch and every
+ * direct (non-batched) write so tests can assert the atomicity contract: all
+ * writes of an operation enlisted into one batch, committed exactly once, and
+ * nothing applied when the commit fails.
+ *
+ * Test files mock the firebase module with the shared holder so file ordering
+ * does not matter:
+ *   mock.module('~/system/firebase', () => ({ db: fakeDb }))
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { FieldValue, type Firestore } from 'firebase-admin/firestore'
+
+type Doc = Record<string, unknown>
+
+export type FakeSnapshot = { exists: boolean; id: string; data: () => Doc | undefined }
+
+export type FakeRef = {
+  /** The collection holding this document. Collections are flat, never nested. */
+  collectionPath: string
+  id: string
+  get: () => Promise<FakeSnapshot>
+  set: (data: Doc, options?: { merge?: boolean }) => Promise<void>
+  update: (data: Doc) => Promise<void>
+  delete: () => Promise<void>
+}
+
+export type BatchOp =
+  | { type: 'set'; ref: FakeRef; data: Doc }
+  | { type: 'update'; ref: FakeRef; data: Doc }
+  | { type: 'merge'; ref: FakeRef; data: Doc }
+  | { type: 'delete'; ref: FakeRef }
+
+export type FakeBatch = {
+  ops: BatchOp[]
+  commits: number
+  set: (ref: FakeRef, data: Doc, options?: { merge?: boolean }) => FakeBatch
+  update: (ref: FakeRef, data: Doc) => FakeBatch
+  delete: (ref: FakeRef) => FakeBatch
+  commit: () => Promise<void>
+}
+
+export type FakeTransaction = {
+  get: (ref: FakeRef) => Promise<FakeSnapshot>
+  set: (ref: FakeRef, data: Doc) => FakeTransaction
+  delete: (ref: FakeRef) => FakeTransaction
+}
+
+export type DirectWrite = { type: 'set' | 'update' | 'delete'; collection: string; id: string }
+
+type FakeQuery = {
+  where: (field: string, op: string, value: unknown) => FakeQuery
+  orderBy: (field: string, direction?: 'asc' | 'desc') => FakeQuery
+  limit: (count: number) => FakeQuery
+  offset: (count: number) => FakeQuery
+  startAfter: (cursor: FakeSnapshot) => FakeQuery
+  get: () => Promise<{ docs: Array<{ data: () => Doc; ref: FakeRef }> }>
+  count: () => { get: () => Promise<{ data: () => { count: number } }> }
+}
+
+type FakeCollection = {
+  withConverter: (converter: unknown) => FakeCollection
+  doc: (id?: string) => FakeRef
+  add: (data: Doc) => Promise<FakeRef>
+  where: FakeQuery['where']
+  orderBy: FakeQuery['orderBy']
+  limit: FakeQuery['limit']
+  get: FakeQuery['get']
+  count: FakeQuery['count']
+}
+
+export const createFakeFirestore = () => {
+  const store = new Map<string, Map<string, Doc>>()
+  const batches: FakeBatch[] = []
+  const directWrites: DirectWrite[] = []
+  // The writes each committed transaction applied, in order — lets a test prove a
+  // read-modify-write went through one transaction rather than a bare set.
+  const transactions: BatchOp[][] = []
+  let commitError: Error | undefined
+  let generatedIds = 0
+  let docReads = 0
+  let queryReads = 0
+  // Documents a query returned: what Firestore actually bills a query for.
+  let queriedDocs = 0
+  // Handed to the next query instead of an answer, once.
+  let queryError: Error | undefined
+  // How long a query takes per document it returns, as a real one takes longer
+  // the more it decodes: zero answers at once, which leaves no query in flight
+  // for requests sent together to share.
+  let queryMsPerDocument = 0
+
+  const docsOf = (collection: string) => {
+    const existing = store.get(collection)
+    if (existing) return existing
+    const created = new Map<string, Doc>()
+    store.set(collection, created)
+    return created
+  }
+
+  // Resolve a document write the way Firestore does: FieldValue.increment
+  // sentinels add to the stored number (`operand` is the transform's runtime
+  // field), nested maps recurse, and a merge keeps whatever the write does not
+  // name. Only direct ref.set supports this — no production code sends
+  // transforms through a batch or a transaction.
+  const resolveWrite = (existing: Doc | undefined, data: Doc, merge: boolean): Doc => {
+    const result: Doc = merge ? { ...(existing ?? {}) } : {}
+    for (const [key, value] of Object.entries(data)) {
+      const current = merge ? existing?.[key] : undefined
+      if (value instanceof FieldValue && 'operand' in value) {
+        const operand = (value as unknown as { operand: number }).operand
+        result[key] = (typeof current === 'number' ? current : 0) + operand
+      } else if (
+        value &&
+        typeof value === 'object' &&
+        !(value instanceof Date) &&
+        !Array.isArray(value)
+      ) {
+        result[key] = resolveWrite(current as Doc | undefined, value as Doc, merge)
+      } else {
+        result[key] = value
+      }
+    }
+    return result
+  }
+
+  // Firestore rejects `undefined` anywhere in a document, including inside an
+  // array. The fake used to accept it, which let a real bug pass a green test:
+  // a series catalogue with one unnumbered volume wrote fine here and was
+  // refused in production. Rejecting it makes the fake honest.
+  const rejectUndefined = (value: unknown, path: string): void => {
+    if (value === undefined) {
+      throw new Error(`Cannot use "undefined" as a Firestore value (found at ${path})`)
+    }
+    if (Array.isArray(value)) {
+      for (const [index, entry] of value.entries()) rejectUndefined(entry, `${path}[${index}]`)
+      return
+    }
+    if (value === null || typeof value !== 'object' || value instanceof Date) return
+    if (value instanceof FieldValue) return
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      rejectUndefined(entry, path ? `${path}.${key}` : key)
+    }
+  }
+
+  const makeRef = (collection: string, id: string): FakeRef => ({
+    collectionPath: collection,
+    id,
+    get: async () => {
+      docReads += 1
+      const doc = docsOf(collection).get(id)
+      return { exists: doc !== undefined, id, data: () => doc }
+    },
+    set: async (data, options) => {
+      rejectUndefined(data, `${collection}/${id}`)
+      directWrites.push({ type: 'set', collection, id })
+      docsOf(collection).set(
+        id,
+        resolveWrite(docsOf(collection).get(id), data, options?.merge === true),
+      )
+    },
+    // Like Firestore's update: merges into an existing document, and refuses to
+    // create one. A caller racing with a deletion must fail, not resurrect a
+    // ghost document holding only the field it wrote.
+    update: async (data) => {
+      const existing = docsOf(collection).get(id)
+      if (existing === undefined) {
+        throw new Error(`NOT_FOUND: no document to update at ${collection}/${id}`)
+      }
+      directWrites.push({ type: 'update', collection, id })
+      docsOf(collection).set(id, resolveWrite(existing, data, true))
+    },
+    delete: async () => {
+      directWrites.push({ type: 'delete', collection, id })
+      docsOf(collection).delete(id)
+    },
+  })
+
+  const sortValue = (value: unknown) =>
+    value instanceof Date ? value.getTime() : (value as number | string)
+
+  type Filter = [field: string, op: string, value: unknown]
+  type QueryState = {
+    filters: Filter[]
+    orders: { field: string; direction: 'asc' | 'desc' }[]
+    limit?: number
+    offset?: number
+    startAfter?: { id: string; data: Doc | undefined }
+  }
+
+  // A dotted field reaches into a map, as `where('series.id', ...)` does in Firestore.
+  const valueAt = (data: Doc, field: string): unknown =>
+    field
+      .split('.')
+      .reduce<unknown>(
+        (value, key) =>
+          value !== null && typeof value === 'object'
+            ? (value as Record<string, unknown>)[key]
+            : undefined,
+        data,
+      )
+
+  // Only the operators production code actually uses — fail loudly otherwise.
+  const matchesFilter = (data: Doc, [field, op, value]: Filter) => {
+    const held = valueAt(data, field)
+    if (op === '==') return held === value
+    if (op === '!=') return held !== undefined && held !== value
+    if (op === '>=')
+      // Firestore leaves out a document missing the field, as it does on order.
+      return held !== undefined && sortValue(held) >= sortValue(value)
+    if (op === 'in') return Array.isArray(value) && value.includes(held)
+    if (op === 'array-contains') return Array.isArray(held) && held.includes(value)
+    if (op === 'array-contains-any')
+      return (
+        Array.isArray(held) && Array.isArray(value) && value.some((wanted) => held.includes(wanted))
+      )
+    throw new Error(
+      `fake-firestore only supports '==', '!=', '>=', 'in', 'array-contains' and ` +
+        `'array-contains-any' queries, got '${op}'`,
+    )
+  }
+
+  const makeQuery = (collection: string, state: QueryState): FakeQuery => ({
+    where: (field, op, value) =>
+      makeQuery(collection, { ...state, filters: [...state.filters, [field, op, value]] }),
+    orderBy: (field, direction = 'asc') =>
+      makeQuery(collection, { ...state, orders: [...state.orders, { field, direction }] }),
+    limit: (count) => makeQuery(collection, { ...state, limit: count }),
+    offset: (count) => makeQuery(collection, { ...state, offset: count }),
+    startAfter: (cursor) =>
+      makeQuery(collection, { ...state, startAfter: { id: cursor.id, data: cursor.data() } }),
+    get: async () => {
+      if (queryError) {
+        const error = queryError
+        queryError = undefined
+        throw error
+      }
+      queryReads += 1
+      let matching = [...docsOf(collection).entries()].filter(([, data]) =>
+        state.filters.every((filter) => matchesFilter(data, filter)),
+      )
+      if (state.orders.length > 0) {
+        const { orders } = state
+        // Firestore leaves out a document missing an ordered field — mirror it,
+        // so a record a migration forgot is as invisible here as in production.
+        matching = matching.filter(([, data]) => orders.every(({ field }) => field in data))
+        const compared = (left: unknown, right: unknown) => {
+          const [a, b] = [sortValue(left), sortValue(right)]
+          return a < b ? -1 : a > b ? 1 : 0
+        }
+        // Firestore uses the document id as an implicit tie-break, in the
+        // direction of the last ordering — mirror it.
+        const last = orders.at(-1)?.direction ?? 'asc'
+        const inOrder = ([idA, a]: [string, Doc], [idB, b]: [string, Doc]) => {
+          for (const { field, direction } of orders) {
+            const comparison = compared(a[field], b[field])
+            if (comparison !== 0) return direction === 'desc' ? -comparison : comparison
+          }
+          const tie = compared(idA, idB)
+          return last === 'desc' ? -tie : tie
+        }
+        matching.sort(inOrder)
+        // A snapshot cursor positions by the values it holds, as Firestore's
+        // does: the cursor need not match the filters, nor still be stored.
+        const cursor = state.startAfter
+        if (cursor?.data)
+          matching = matching.filter((row) => inOrder(row, [cursor.id, cursor.data as Doc]) > 0)
+      } else if (state.startAfter) {
+        const cursorIndex = matching.findIndex(([id]) => id === state.startAfter?.id)
+        if (cursorIndex >= 0) matching = matching.slice(cursorIndex + 1)
+      }
+      if (state.offset !== undefined) matching = matching.slice(state.offset)
+      if (state.limit !== undefined) matching = matching.slice(0, state.limit)
+      queriedDocs += matching.length
+      if (queryMsPerDocument > 0) await Bun.sleep(queryMsPerDocument * matching.length)
+      return {
+        docs: matching.map(([id, data]) => ({ data: () => data, ref: makeRef(collection, id) })),
+      }
+    },
+    // Aggregation count: like Firestore, one billed query round-trip, no documents.
+    count: () => ({
+      get: async () => {
+        queryReads += 1
+        const matching = [...docsOf(collection).values()].filter((data) =>
+          state.filters.every((filter) => matchesFilter(data, filter)),
+        )
+        return { data: () => ({ count: matching.length }) }
+      },
+    }),
+  })
+
+  const makeCollection = (name: string): FakeCollection => ({
+    withConverter: () => makeCollection(name),
+    doc: (id) => makeRef(name, id ?? `generated-${++generatedIds}`),
+    add: async (data) => {
+      const ref = makeRef(name, `generated-${++generatedIds}`)
+      await ref.set(data)
+      return ref
+    },
+    where: (field, op, value) => makeQuery(name, { filters: [[field, op, value]], orders: [] }),
+    orderBy: (field, direction) =>
+      makeQuery(name, { filters: [], orders: [] }).orderBy(field, direction),
+    limit: (count) => makeQuery(name, { filters: [], orders: [] }).limit(count),
+    get: () => makeQuery(name, { filters: [], orders: [] }).get(),
+    count: () => makeQuery(name, { filters: [], orders: [] }).count(),
+  })
+
+  const makeBatch = (): FakeBatch => {
+    const ops: BatchOp[] = []
+    const batch: FakeBatch = {
+      ops,
+      commits: 0,
+      // A merge set is recorded as an update that may create the document, which is
+      // what Firestore does with `{ merge: true }`.
+      set: (ref, data, options) => {
+        ops.push(options?.merge ? { type: 'merge', ref, data } : { type: 'set', ref, data })
+        return batch
+      },
+      update: (ref, data) => {
+        ops.push({ type: 'update', ref, data })
+        return batch
+      },
+      delete: (ref) => {
+        ops.push({ type: 'delete', ref })
+        return batch
+      },
+      commit: async () => {
+        if (commitError) throw commitError
+        // Firestore refuses a batch of more than 500 writes outright.
+        if (ops.length > 500)
+          throw new Error(`INVALID_ARGUMENT: ${ops.length} writes in one batch, 500 at most`)
+        for (const op of ops) {
+          if (op.type === 'set') docsOf(op.ref.collectionPath).set(op.ref.id, op.data)
+          else if (op.type === 'merge') {
+            const existing = docsOf(op.ref.collectionPath).get(op.ref.id)
+            docsOf(op.ref.collectionPath).set(op.ref.id, resolveWrite(existing, op.data, true))
+          } else if (op.type === 'update') {
+            const existing = docsOf(op.ref.collectionPath).get(op.ref.id)
+            if (existing === undefined) {
+              throw new Error(
+                `NOT_FOUND: no document to update at ${op.ref.collectionPath}/${op.ref.id}`,
+              )
+            }
+            docsOf(op.ref.collectionPath).set(op.ref.id, resolveWrite(existing, op.data, true))
+          } else docsOf(op.ref.collectionPath).delete(op.ref.id)
+        }
+        batch.commits += 1
+      },
+    }
+    batches.push(batch)
+    return batch
+  }
+
+  // Transactions run one after another rather than concurrently. Real Firestore
+  // aborts and retries the loser of a contended write; serialising the bodies
+  // reaches the same end state and makes a concurrency test deterministic instead
+  // of retry-dependent.
+  let transactionQueue: Promise<unknown> = Promise.resolve()
+
+  const runTransaction = <T>(run: (tx: FakeTransaction) => Promise<T>): Promise<T> => {
+    const result = transactionQueue.then(async () => {
+      const writes: BatchOp[] = []
+      const tx: FakeTransaction = {
+        get: async (ref) => {
+          docReads += 1
+          const doc = docsOf(ref.collectionPath).get(ref.id)
+          return { exists: doc !== undefined, id: ref.id, data: () => doc }
+        },
+        set: (ref, data) => {
+          writes.push({ type: 'set', ref, data })
+          return tx
+        },
+        delete: (ref) => {
+          writes.push({ type: 'delete', ref })
+          return tx
+        },
+      }
+      const value = await run(tx)
+      // Applied only once the body succeeded — a throw leaves the store untouched.
+      for (const op of writes) {
+        if (op.type === 'set') docsOf(op.ref.collectionPath).set(op.ref.id, op.data)
+        else docsOf(op.ref.collectionPath).delete(op.ref.id)
+      }
+      transactions.push(writes)
+      return value
+    })
+    // The queue must keep flowing even when a transaction throws, or every later
+    // one would inherit the rejection.
+    transactionQueue = result.catch(() => undefined)
+    return result
+  }
+
+  const getAll = async (...refs: FakeRef[]) => {
+    docReads += refs.length
+    return refs.map((ref) => {
+      const doc = docsOf(ref.collectionPath).get(ref.id)
+      return { exists: doc !== undefined, id: ref.id, data: () => doc }
+    })
+  }
+
+  return {
+    db: {
+      collection: makeCollection,
+      batch: makeBatch,
+      getAll,
+      runTransaction,
+    } as unknown as Firestore,
+    seed: (collection: string, id: string, data: Doc) => {
+      docsOf(collection).set(id, { ...data })
+    },
+    snapshot: (collection: string) => new Map(docsOf(collection)),
+    /** One stored document, or null. Subcollections are addressed by their full
+     *  path, e.g. `users/reader-1/books`. */
+    data: (collection: string, id: string) => docsOf(collection).get(id) ?? null,
+    batches,
+    directWrites,
+    transactions,
+    // Firestore round-trips (document gets + query gets) — lets tests assert read budgets
+    get reads() {
+      return docReads + queryReads
+    },
+    // Keyed document gets only (ref.get + getAll) — one read per document fetched
+    get docReads() {
+      return docReads
+    },
+    // Collection query gets only — a scan counts 1 whatever the number of docs returned,
+    // so asserting queryReads === 0 is the proof that a path never scans a collection
+    get queryReads() {
+      return queryReads
+    },
+    get queriedDocs() {
+      return queriedDocs
+    },
+    failCommitsWith: (error: Error) => {
+      commitError = error
+    },
+    failNextQueryWith: (error: Error) => {
+      queryError = error
+    },
+    answerQueriesAfter: (msPerDocument: number) => {
+      queryMsPerDocument = msPerDocument
+    },
+  }
+}
+
+export type FakeFirestore = ReturnType<typeof createFakeFirestore>
+
+const holder = { current: createFakeFirestore() }
+
+export const resetFakeFirestore = () => {
+  holder.current = createFakeFirestore()
+  startFakeRequest()
+  return holder.current
+}
+
+/** Give the next calls a fresh, stable request context so memoizedPerRequest()
+ *  caches within it (mirroring one HTTP request). Each test starts one; a test
+ *  that spans two requests — a screen read, then a mutation — starts the second. */
+export const startFakeRequest = () => {
+  const context: Record<string, unknown> = {}
+  ;(globalThis as unknown as { useEvent: () => unknown }).useEvent = () => ({ context })
+}
+
+/** Run each call as its own HTTP request, all at once, as the app sends the
+ *  sections of a screen: each gets a request context of its own, as
+ *  `startFakeRequest` gives one, for as long as it runs. */
+export const inConcurrentFakeRequests = async <T>(
+  calls: readonly (() => Promise<T>)[],
+): Promise<T[]> => {
+  const requests = new AsyncLocalStorage<Record<string, unknown>>()
+  const global = globalThis as unknown as { useEvent: () => unknown }
+  const outside = global.useEvent
+  global.useEvent = () => {
+    const context = requests.getStore()
+    return context ? { context } : outside()
+  }
+  try {
+    return await Promise.all(calls.map((call) => requests.run({}, call)))
+  } finally {
+    global.useEvent = outside
+  }
+}
+
+export const fakeDb = () => holder.current.db

package/templates/backend/server/utils/apollo.ts

@@ -0,0 +1,13 @@
+import type { ApolloServer } from '@apollo/server'
+import type { GraphQLContext } from '~/domain/shared/graphql/builder'
+
+let instance: ApolloServer<GraphQLContext> | null = null
+
+export const setApollo = (apollo: ApolloServer<GraphQLContext>) => {
+  instance = apollo
+}
+
+export const useApollo = () => {
+  if (!instance) throw new Error('Apollo Server not initialized — plugin not loaded yet')
+  return instance
+}

package/templates/backend/server/utils/fetch.ts

@@ -0,0 +1,5 @@
+/** Whether a fetch failed because its `AbortSignal.timeout` ran out, rather than
+ *  because the host could not be reached or answered badly. The platform throws a
+ *  `DOMException` named `TimeoutError` for it, with no subclass to test against. */
+export const isTimeout = (error: unknown): boolean =>
+  error instanceof DOMException && error.name === 'TimeoutError'

package/templates/backend/server/utils/firestore.ts

@@ -0,0 +1,91 @@
+import type {
+  DocumentData,
+  DocumentReference,
+  FirestoreDataConverter,
+  QueryDocumentSnapshot,
+  Transaction,
+  WriteBatch,
+} from 'firebase-admin/firestore'
+import { chunk } from 'lodash-es'
+import { db } from '~/system/firebase'
+
+// Generic Firestore converter that preserves type information when reading
+// documents and recursively turns Timestamp instances back into JS Date.
+// Pattern from https://github.com/moifort/price-it back/src/utils/firestore.ts
+export const genericDataConverter = <T extends DocumentData>(): FirestoreDataConverter<T> => ({
+  toFirestore: (data: T) => data,
+  fromFirestore: (snapshot: QueryDocumentSnapshot) => toDate(snapshot.data()) as T,
+})
+
+const toDate = (value: unknown): unknown => {
+  if (!value || typeof value !== 'object') return value
+  const obj = value as Record<string, unknown>
+  for (const key of Object.keys(obj)) {
+    const v = obj[key] as { toDate?: () => Date } | unknown
+    if (v && typeof v === 'object' && typeof (v as { toDate?: unknown }).toDate === 'function') {
+      obj[key] = (v as { toDate: () => Date }).toDate()
+    } else if (v && typeof v === 'object') {
+      toDate(v)
+    }
+  }
+  return obj
+}
+
+// Firestore rejects `undefined` field values outright. An absent domain field is
+// meant to disappear from the document, which is exactly what dropping the key
+// does on a full `set`.
+//
+// Recursive, because the shallow version was not enough: a series catalogue is
+// an array of volumes, and a volume with no number (a novella) or no year (one
+// not out yet) carries `undefined` INSIDE the array. Firestore then rejects the
+// whole document, so one unnumbered volume silently cost an entire saga its
+// catalogue.
+export const withoutAbsentFields = <T extends DocumentData>(data: T): T => pruneUndefined(data) as T
+
+const pruneUndefined = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(pruneUndefined)
+  // Dates and other class instances are values, not maps: recursing into them
+  // would flatten a Timestamp into a plain object.
+  if (value === null || typeof value !== 'object' || value instanceof Date) return value
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([, entry]) => entry !== undefined)
+      .map(([key, entry]) => [key, pruneUndefined(entry)]),
+  )
+}
+
+// Firestore batches accept at most 500 operations.
+const BATCH_LIMIT = 400
+
+// Persist many records with bounded write concurrency — individual sets, not a
+// batch (the row count on an import/restore can exceed the 500-op batch cap).
+export const bulkSave = async <T>(rows: T[], save: (row: T) => Promise<unknown>): Promise<void> => {
+  for (const slice of chunk(rows, 50)) await Promise.all(slice.map((row) => save(row)))
+}
+
+export const deleteInBatches = async (refs: DocumentReference[]): Promise<void> => {
+  for (const slice of chunk(refs, BATCH_LIMIT)) {
+    const batch = db().batch()
+    for (const ref of slice) batch.delete(ref)
+    await batch.commit()
+  }
+}
+
+// Runs `enlist` against a fresh WriteBatch and commits it once: either every
+// enlisted write lands or none does. Reads inside `enlist` see pre-batch state —
+// batched writes are invisible until commit. Firestore caps a batch at 500
+// writes; callers enlist a handful of documents, far below the cap.
+export const atomically = async <T>(enlist: (batch: WriteBatch) => Promise<T>): Promise<T> => {
+  const batch = db().batch()
+  const result = await enlist(batch)
+  await batch.commit()
+  return result
+}
+
+// Read-then-write in one go, with the read protected against a concurrent writer.
+// A batch cannot do this: its reads see pre-batch state, so two callers
+// incrementing the same counter would both read the same value and one increment
+// would be lost. Firestore retries the body on contention, so it must stay pure
+// beyond its own reads and writes.
+export const transactionally = <T>(run: (tx: Transaction) => Promise<T>): Promise<T> =>
+  db().runTransaction(run)

package/templates/backend/server/utils/input.ts

@@ -0,0 +1,36 @@
+// Boundary converter: GraphQL nullability → domain "absent key" convention.
+//
+// Pothos optional input fields are typed as `T | null | undefined`; at runtime
+// graphql-js omits absent fields entirely, so the only variant to erase is an
+// explicit `null` sent by the client. Domain types use `T?` (a key is present
+// with a value, or not present at all) and Firestore rejects `undefined`
+// values — dropping the null KEYS (not nulling them) keeps both invariants.
+//
+// Not recursive: every mutation input in the schema is flat.
+type StripNulls<T> = { [K in keyof T]: Exclude<T[K], null> }
+
+export const stripNulls = <T extends Record<string, unknown>>(obj: T): StripNulls<T> => {
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(obj)) {
+    const value = (obj as Record<string, unknown>)[key]
+    if (value !== null) out[key] = value
+  }
+  return out as StripNulls<T>
+}
+
+/** Runs a branded constructor over a value nobody vouches for — a model reading a
+ *  cover, a field of somebody else's API — and drops it if it does not validate.
+ *
+ *  The whole point of the brands is that a hallucinated ISBN or a page count of 0
+ *  never reaches the database, and a single bad field must not sink an otherwise
+ *  good record. */
+export const optionally = <T>(value: unknown, construct: (value: unknown) => T): T | undefined => {
+  if (value === null || value === undefined || value === '') return undefined
+  try {
+    return construct(value)
+  } catch {
+    return undefined
+  }
+}
+
+export const isPresent = <T>(value: T | undefined): value is T => value !== undefined

package/templates/backend/server/utils/input.unit.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'bun:test'
+import { stripNulls } from './input'
+
+// Mirrors how Pothos types optional input fields: `T | null | undefined`.
+type FakeInput = {
+  name: string
+  vintage?: number | null
+  notes?: string | null
+  price?: number | null
+  favorite?: boolean | null
+}
+
+describe('stripNulls', () => {
+  it('drops null keys entirely instead of keeping them', () => {
+    const input: FakeInput = { name: 'Margaux', vintage: null }
+    const out = stripNulls(input)
+    expect(out).toEqual({ name: 'Margaux' })
+    expect('vintage' in out).toBe(false)
+  })
+
+  it('keeps falsy but present values (0, empty string, false)', () => {
+    const input: FakeInput = { name: 'Chinon', price: 0, notes: '', favorite: false }
+    expect(stripNulls(input)).toEqual({ name: 'Chinon', price: 0, notes: '', favorite: false })
+  })
+
+  it('never introduces a null value: every remaining key holds a real value', () => {
+    const input: FakeInput = { name: 'Cornas', vintage: 2019, notes: null, price: null }
+    const out = stripNulls(input)
+    expect(Object.values(out).every((value) => value !== null)).toBe(true)
+    expect(out).toEqual({ name: 'Cornas', vintage: 2019 })
+  })
+
+  it('leaves objects without nulls untouched', () => {
+    const input: FakeInput = { name: 'Chinon', vintage: 2020 }
+    expect(stripNulls(input)).toEqual({ name: 'Chinon', vintage: 2020 })
+  })
+
+  it('is not recursive: nested values pass through as-is', () => {
+    // Every mutation input in the schema is flat; nested objects pass through.
+    const nested = { meta: { inner: null } as { inner: string | null } }
+    expect(stripNulls(nested)).toEqual({ meta: { inner: null } })
+  })
+})