firestore-schema-kit 1.0.0

package/collection.js

@@ -0,0 +1,98 @@
+import { z } from 'zod'
+import { s } from './fields.js'
+
+// ─── Schema Validation Error ───────────────────────────────────────────────────
+
+export class SchemaValidationError extends Error {
+  constructor(collectionName, zodError) {
+    const issues = zodError.issues
+      .map((i) => `  • ${i.path.join('.')}: ${i.message}`)
+      .join('\n')
+
+    super(`[${collectionName}] Schema validation failed:\n${issues}`)
+    this.name       = 'SchemaValidationError'
+    this.collection = collectionName
+    this.issues     = zodError.issues
+  }
+}
+
+// ─── defineCollection ─────────────────────────────────────────────────────────
+
+/**
+ * Define a typed Firestore collection with schema validation.
+ *
+ * @param {string} collectionName - Firestore collection path (e.g. 'users', 'posts/comments')
+ * @param {(s: SchemaBuilder) => Record<string, BaseField>} builder - Field definition callback
+ * @returns {CollectionSchema}
+ *
+ * @example
+ * export const usersSchema = defineCollection('users', (s) => ({
+ *   name:      s.string().min(1),
+ *   email:     s.string().email(),
+ *   age:       s.number().optional(),
+ *   role:      s.enum(['admin', 'user']).default('user'),
+ *   createdAt: s.timestamp(),
+ * }))
+ */
+export function defineCollection(collectionName, builder) {
+  if (typeof collectionName !== 'string' || !collectionName.trim()) {
+    throw new Error('defineCollection: collectionName must be a non-empty string')
+  }
+  if (typeof builder !== 'function') {
+    throw new Error('defineCollection: builder must be a function')
+  }
+
+  // Call builder with the schema builder (s)
+  const fieldDefs = builder(s)
+
+  if (!fieldDefs || typeof fieldDefs !== 'object') {
+    throw new Error('defineCollection: builder must return an object of field definitions')
+  }
+
+  // Convert field definitions → Zod schema shape
+  const zodShape = {}
+  for (const [key, field] of Object.entries(fieldDefs)) {
+    if (typeof field?.toZod !== 'function') {
+      throw new Error(
+        `defineCollection [${collectionName}]: field "${key}" is not a valid schema field. ` +
+        `Use s.string(), s.number(), etc.`
+      )
+    }
+    zodShape[key] = field.toZod()
+  }
+
+  const zodSchema        = z.object(zodShape)
+  const zodPartialSchema = zodSchema.partial()
+
+  return {
+    // ── Metadata ────────────────────────────────────────────────────────────
+    _name:      collectionName,
+    _fieldDefs: fieldDefs,
+    _type:      'CollectionSchema',
+
+    // ── Validation ──────────────────────────────────────────────────────────
+
+    /** Full validation — use for createDoc / setDoc */
+    validate(data) {
+      const result = zodSchema.safeParse(data)
+      if (!result.success) throw new SchemaValidationError(collectionName, result.error)
+      return result.data
+    },
+
+    /** Partial validation — use for updateDoc (only validates fields present in data) */
+    validatePartial(data) {
+      const result = zodPartialSchema.safeParse(data)
+      if (!result.success) throw new SchemaValidationError(collectionName, result.error)
+      return result.data
+    },
+
+    /** Safe (non-throwing) full validation */
+    safeParse(data) {
+      const result = zodSchema.safeParse(data)
+      if (!result.success) {
+        return { success: false, error: new SchemaValidationError(collectionName, result.error) }
+      }
+      return { success: true, data: result.data }
+    },
+  }
+}

package/fields.js

@@ -0,0 +1,245 @@
+import { z } from 'zod'
+
+// ─── Base Field ───────────────────────────────────────────────────────────────
+
+class BaseField {
+  constructor() {
+    this._optional   = false
+    this._nullable   = false
+    this._hasDefault = false
+    this._defaultVal = undefined
+  }
+
+  optional() {
+    this._optional = true
+    return this
+  }
+
+  nullable() {
+    this._nullable = true
+    return this
+  }
+
+  default(val) {
+    this._hasDefault = true
+    this._defaultVal = val
+    return this
+  }
+
+  // Subclasses implement this — returns a raw Zod schema with no optional/default wrapping
+  _baseZod() {
+    throw new Error(`_baseZod() not implemented on ${this.constructor.name}`)
+  }
+
+  // Builds the final Zod schema, applying nullable → default → optional in the correct order
+  toZod() {
+    let schema = this._baseZod()
+    if (this._nullable)   schema = schema.nullable()
+    if (this._hasDefault) schema = schema.default(this._defaultVal)
+    if (this._optional)   schema = schema.optional()
+    return schema
+  }
+}
+
+// ─── String ───────────────────────────────────────────────────────────────────
+
+export class StringField extends BaseField {
+  constructor() {
+    super()
+    this._min   = null
+    this._max   = null
+    this._email = false
+    this._url   = false
+    this._uuid  = false
+    this._regex = null
+  }
+
+  min(n)      { this._min   = n; return this }
+  max(n)      { this._max   = n; return this }
+  email()     { this._email = true; return this }
+  url()       { this._url   = true; return this }
+  uuid()      { this._uuid  = true; return this }
+  regex(r)    { this._regex = r; return this }
+
+  _baseZod() {
+    let schema = z.string()
+    if (this._min   !== null) schema = schema.min(this._min)
+    if (this._max   !== null) schema = schema.max(this._max)
+    if (this._email)          schema = schema.email()
+    if (this._url)            schema = schema.url()
+    if (this._uuid)           schema = schema.uuid()
+    if (this._regex !== null) schema = schema.regex(this._regex)
+    return schema
+  }
+}
+
+// ─── Number ───────────────────────────────────────────────────────────────────
+
+export class NumberField extends BaseField {
+  constructor() {
+    super()
+    this._min      = null
+    this._max      = null
+    this._int      = false
+    this._positive = false
+    this._negative = false
+  }
+
+  min(n)      { this._min      = n;    return this }
+  max(n)      { this._max      = n;    return this }
+  int()       { this._int      = true; return this }
+  positive()  { this._positive = true; return this }
+  negative()  { this._negative = true; return this }
+
+  _baseZod() {
+    let schema = this._int ? z.number().int() : z.number()
+    if (this._min      !== null) schema = schema.min(this._min)
+    if (this._max      !== null) schema = schema.max(this._max)
+    if (this._positive)          schema = schema.positive()
+    if (this._negative)          schema = schema.negative()
+    return schema
+  }
+}
+
+// ─── Boolean ──────────────────────────────────────────────────────────────────
+
+export class BooleanField extends BaseField {
+  _baseZod() {
+    return z.boolean()
+  }
+}
+
+// ─── Timestamp ────────────────────────────────────────────────────────────────
+// Accepts: JS Date, Firestore Timestamp, serverTimestamp() sentinel
+
+export class TimestampField extends BaseField {
+  _baseZod() {
+    return z.custom(
+      (val) => {
+        if (!val) return false
+        // JS Date
+        if (val instanceof Date) return true
+        // Firestore Timestamp (has toDate method)
+        if (typeof val.toDate === 'function') return true
+        // serverTimestamp() sentinel — has _methodName internally
+        if (typeof val === 'object' && '_methodName' in val) return true
+        return false
+      },
+      { message: 'Expected a Date, Firestore Timestamp, or serverTimestamp()' }
+    )
+  }
+}
+
+// ─── Array ────────────────────────────────────────────────────────────────────
+
+export class ArrayField extends BaseField {
+  constructor(itemField) {
+    super()
+    this._itemField = itemField
+    this._min       = null
+    this._max       = null
+  }
+
+  min(n) { this._min = n; return this }
+  max(n) { this._max = n; return this }
+
+  _baseZod() {
+    let schema = z.array(this._itemField.toZod())
+    if (this._min !== null) schema = schema.min(this._min)
+    if (this._max !== null) schema = schema.max(this._max)
+    return schema
+  }
+}
+
+// ─── Map (nested object) ──────────────────────────────────────────────────────
+
+export class MapField extends BaseField {
+  constructor(shape) {
+    super()
+    this._shape = shape
+  }
+
+  _baseZod() {
+    const zodShape = {}
+    for (const [key, field] of Object.entries(this._shape)) {
+      zodShape[key] = field.toZod()
+    }
+    return z.object(zodShape)
+  }
+}
+
+// ─── Enum ─────────────────────────────────────────────────────────────────────
+
+export class EnumField extends BaseField {
+  constructor(values) {
+    super()
+    this._values = values
+  }
+
+  _baseZod() {
+    return z.enum(this._values)
+  }
+}
+
+// ─── Literal ──────────────────────────────────────────────────────────────────
+
+export class LiteralField extends BaseField {
+  constructor(value) {
+    super()
+    this._value = value
+  }
+
+  _baseZod() {
+    return z.literal(this._value)
+  }
+}
+
+// ─── Reference (Firestore DocumentReference) ──────────────────────────────────
+
+export class ReferenceField extends BaseField {
+  _baseZod() {
+    return z.custom(
+      (val) => val && typeof val.path === 'string' && typeof val.id === 'string',
+      { message: 'Expected a Firestore DocumentReference' }
+    )
+  }
+}
+
+// ─── Union ────────────────────────────────────────────────────────────────────
+
+export class UnionField extends BaseField {
+  constructor(fields) {
+    super()
+    this._fields = fields
+  }
+
+  _baseZod() {
+    const schemas = this._fields.map((f) => f.toZod())
+    return z.union(schemas)
+  }
+}
+
+// ─── Any (escape hatch) ───────────────────────────────────────────────────────
+
+export class AnyField extends BaseField {
+  _baseZod() {
+    return z.any()
+  }
+}
+
+// ─── Schema Builder (s) ───────────────────────────────────────────────────────
+// This is what gets passed into the defineCollection callback
+
+export const s = {
+  string:    ()           => new StringField(),
+  number:    ()           => new NumberField(),
+  boolean:   ()           => new BooleanField(),
+  timestamp: ()           => new TimestampField(),
+  array:     (itemField)  => new ArrayField(itemField),
+  map:       (shape)      => new MapField(shape),
+  enum:      (values)     => new EnumField(values),
+  literal:   (value)      => new LiteralField(value),
+  reference: ()           => new ReferenceField(),
+  union:     (fields)     => new UnionField(fields),
+  any:       ()           => new AnyField(),
+}

package/index.js

@@ -0,0 +1,3 @@
+export { s } from './fields.js'
+export { defineCollection, SchemaValidationError } from './collection.js'
+export { initFirestoreSchema } from './operations.js'

package/operations.js

@@ -0,0 +1,419 @@
+import {
+  collection,
+  doc,
+  addDoc,
+  setDoc      as _setDoc,
+  updateDoc   as _updateDoc,
+  deleteDoc   as _deleteDoc,
+  getDoc      as _getDoc,
+  getDocs     as _getDocs,
+  onSnapshot  as _onSnapshot,
+  query,
+  writeBatch,
+  runTransaction as _runTransaction,
+  serverTimestamp,
+  Timestamp,
+} from 'firebase/firestore'
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Validate that `schema` is a CollectionSchema produced by defineCollection().
+ */
+function assertSchema(schema, opName) {
+  if (!schema || schema._type !== 'CollectionSchema') {
+    throw new TypeError(
+      `${opName}: first argument must be a CollectionSchema from defineCollection(). Got: ${typeof schema}`
+    )
+  }
+}
+
+/**
+ * Resolve a string ID or an existing DocumentReference into a DocumentReference.
+ */
+function resolveDocRef(db, schema, idOrRef) {
+  if (typeof idOrRef === 'string') {
+    return doc(db, schema._name, idOrRef)
+  }
+  // Already a DocumentReference
+  if (idOrRef && typeof idOrRef.path === 'string') {
+    return idOrRef
+  }
+  throw new TypeError(
+    `Expected a document ID (string) or DocumentReference, got: ${typeof idOrRef}`
+  )
+}
+
+/**
+ * Get a CollectionReference for the schema.
+ */
+function collectionRef(db, schema) {
+  return collection(db, schema._name)
+}
+
+/**
+ * Map a Firestore DocumentSnapshot → plain data object with `id` field attached.
+ * Returns null if the document doesn't exist.
+ */
+function docToData(snapshot) {
+  if (!snapshot.exists()) return null
+  return { id: snapshot.id, ...snapshot.data() }
+}
+
+/**
+ * Map a QuerySnapshot → array of plain data objects with `id` field attached.
+ */
+function snapshotToArray(querySnapshot) {
+  return querySnapshot.docs.map((d) => ({ id: d.id, ...d.data() }))
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+// All operations are created via initFirestoreSchema(db) so db doesn't need
+// to be passed on every call.
+
+export function initFirestoreSchema(db) {
+  if (!db) throw new Error('initFirestoreSchema: db (Firestore instance) is required')
+
+  // ── createDoc ─────────────────────────────────────────────────────────────
+  /**
+   * Add a new document with an auto-generated ID.
+   * Equivalent to Firestore's addDoc().
+   *
+   * @returns {Promise<DocumentReference>}
+   *
+   * @example
+   * const ref = await createDoc(usersSchema, {
+   *   name: 'Alice',
+   *   email: 'alice@example.com',
+   *   createdAt: serverTimestamp(),
+   * })
+   * console.log(ref.id) // auto-generated ID
+   */
+  async function createDoc(schema, data) {
+    assertSchema(schema, 'createDoc')
+    const validated = schema.validate(data)
+    return addDoc(collectionRef(db, schema), validated)
+  }
+
+  // ── setDoc ────────────────────────────────────────────────────────────────
+  /**
+   * Write a document with a specific ID (overwrites by default).
+   * Pass { merge: true } to merge instead of overwrite.
+   * Equivalent to Firestore's setDoc().
+   *
+   * @param {CollectionSchema} schema
+   * @param {string | DocumentReference} idOrRef
+   * @param {object} data
+   * @param {{ merge?: boolean, mergeFields?: string[] }} [options]
+   *
+   * @example
+   * await setDoc(usersSchema, 'user-123', { name: 'Alice', email: 'alice@example.com', createdAt: serverTimestamp() })
+   * await setDoc(usersSchema, 'user-123', { name: 'Alice Updated' }, { merge: true })
+   */
+  async function setDoc(schema, idOrRef, data, options = {}) {
+    assertSchema(schema, 'setDoc')
+    const ref       = resolveDocRef(db, schema, idOrRef)
+    // merge/mergeFields: only validate fields present in data (partial)
+    const validated = (options.merge || options.mergeFields)
+      ? schema.validatePartial(data)
+      : schema.validate(data)
+    return _setDoc(ref, validated, options)
+  }
+
+  // ── updateDoc ─────────────────────────────────────────────────────────────
+  /**
+   * Partially update a document — only fields provided will be written.
+   * The document must already exist.
+   * Equivalent to Firestore's updateDoc().
+   *
+   * @example
+   * await updateDoc(usersSchema, 'user-123', { name: 'Alice Updated' })
+   */
+  async function updateDoc(schema, idOrRef, data) {
+    assertSchema(schema, 'updateDoc')
+    const ref       = resolveDocRef(db, schema, idOrRef)
+    const validated = schema.validatePartial(data)
+    return _updateDoc(ref, validated)
+  }
+
+  // ── deleteDoc ─────────────────────────────────────────────────────────────
+  /**
+   * Delete a document by ID or ref.
+   * No schema validation needed — it's just a deletion.
+   *
+   * @example
+   * await deleteDoc(usersSchema, 'user-123')
+   */
+  async function deleteDoc(schema, idOrRef) {
+    assertSchema(schema, 'deleteDoc')
+    const ref = resolveDocRef(db, schema, idOrRef)
+    return _deleteDoc(ref)
+  }
+
+  // ── getDoc ────────────────────────────────────────────────────────────────
+  /**
+   * Fetch a single document by ID or ref.
+   * Returns { id, ...data } or null if not found.
+   *
+   * @returns {Promise<{ id: string } & T | null>}
+   *
+   * @example
+   * const user = await getDoc(usersSchema, 'user-123')
+   * if (!user) console.log('Not found')
+   */
+  async function getDoc(schema, idOrRef) {
+    assertSchema(schema, 'getDoc')
+    const ref      = resolveDocRef(db, schema, idOrRef)
+    const snapshot = await _getDoc(ref)
+    return docToData(snapshot)
+  }
+
+  // ── getDocs ───────────────────────────────────────────────────────────────
+  /**
+   * Fetch multiple documents from a collection, with optional query constraints.
+   * Returns an array of { id, ...data } objects.
+   *
+   * @param {CollectionSchema} schema
+   * @param {...QueryConstraint} constraints - where(), orderBy(), limit(), startAfter(), etc.
+   * @returns {Promise<Array<{ id: string } & T>>}
+   *
+   * @example
+   * import { where, orderBy, limit } from 'firebase/firestore'
+   *
+   * const users = await getDocs(usersSchema)
+   * const admins = await getDocs(usersSchema, where('role', '==', 'admin'))
+   * const recent = await getDocs(usersSchema, orderBy('createdAt', 'desc'), limit(10))
+   */
+  async function getDocs(schema, ...constraints) {
+    assertSchema(schema, 'getDocs')
+    const ref        = collectionRef(db, schema)
+    const q          = constraints.length ? query(ref, ...constraints) : ref
+    const snapshot   = await _getDocs(q)
+    return snapshotToArray(snapshot)
+  }
+
+  // ── getDocRef ─────────────────────────────────────────────────────────────
+  /**
+   * Get a Firestore DocumentReference for a given schema and ID.
+   * Useful when you need the ref itself (e.g. for storing references).
+   *
+   * @example
+   * const ref = getDocRef(usersSchema, 'user-123')
+   * await setDoc(postsSchema, 'post-1', { author: ref, ... })
+   */
+  function getDocRef(schema, id) {
+    assertSchema(schema, 'getDocRef')
+    return doc(db, schema._name, id)
+  }
+
+  /**
+   * Get a Firestore CollectionReference for a schema.
+   *
+   * @example
+   * const ref = getCollectionRef(usersSchema)
+   */
+  function getCollectionRef(schema) {
+    assertSchema(schema, 'getCollectionRef')
+    return collectionRef(db, schema)
+  }
+
+  // ── onDocSnapshot ─────────────────────────────────────────────────────────
+  /**
+   * Listen to real-time updates on a single document.
+   * Returns an unsubscribe function.
+   *
+   * @param {CollectionSchema} schema
+   * @param {string | DocumentReference} idOrRef
+   * @param {(data: T | null) => void} callback - called with { id, ...data } or null
+   * @param {(error: Error) => void} [onError]
+   * @returns {Unsubscribe}
+   *
+   * @example
+   * const unsub = onDocSnapshot(usersSchema, 'user-123', (user) => {
+   *   if (user) console.log(user.name)
+   * })
+   * // Later: unsub()
+   */
+  function onDocSnapshot(schema, idOrRef, callback, onError) {
+    assertSchema(schema, 'onDocSnapshot')
+    const ref = resolveDocRef(db, schema, idOrRef)
+    return _onSnapshot(
+      ref,
+      (snapshot) => callback(docToData(snapshot)),
+      onError
+    )
+  }
+
+  // ── onCollectionSnapshot ──────────────────────────────────────────────────
+  /**
+   * Listen to real-time updates on a collection or query.
+   * Returns an unsubscribe function.
+   *
+   * @param {CollectionSchema} schema
+   * @param {(docs: Array<T>) => void} callback - called with array of { id, ...data }
+   * @param {...QueryConstraint} constraints - optional where(), orderBy(), limit(), etc.
+   * @returns {Unsubscribe}
+   *
+   * @example
+   * const unsub = onCollectionSnapshot(
+   *   usersSchema,
+   *   (users) => console.log(users),
+   *   where('role', '==', 'admin'),
+   *   orderBy('name')
+   * )
+   * // Later: unsub()
+   */
+  function onCollectionSnapshot(schema, callback, ...constraints) {
+    assertSchema(schema, 'onCollectionSnapshot')
+    const ref = collectionRef(db, schema)
+    const q   = constraints.length ? query(ref, ...constraints) : ref
+    return _onSnapshot(
+      q,
+      (snapshot) => callback(snapshotToArray(snapshot)),
+    )
+  }
+
+  // ── Batch Writes ──────────────────────────────────────────────────────────
+  /**
+   * Create a schema-aware write batch.
+   * All operations are validated before being added to the batch.
+   *
+   * @example
+   * const batch = createBatch()
+   *
+   * batch.create(usersSchema, { name: 'Alice', email: 'alice@example.com', createdAt: serverTimestamp() })
+   * batch.set(usersSchema, 'user-456', { name: 'Bob', email: 'bob@example.com', createdAt: serverTimestamp() })
+   * batch.update(usersSchema, 'user-123', { name: 'Alice Updated' })
+   * batch.delete(usersSchema, 'user-789')
+   *
+   * await batch.commit()
+   */
+  function createBatch() {
+    const batch = writeBatch(db)
+
+    return {
+      /**
+       * Add a new document with auto-generated ID to the batch.
+       * Note: Firestore's batch doesn't support addDoc — this uses doc() with a generated ref.
+       */
+      create(schema, data) {
+        assertSchema(schema, 'batch.create')
+        const validated = schema.validate(data)
+        const ref       = doc(collectionRef(db, schema))
+        batch.set(ref, validated)
+        return ref // return ref so caller can use the ID
+      },
+
+      /** Set (overwrite) a document in the batch */
+      set(schema, idOrRef, data, options = {}) {
+        assertSchema(schema, 'batch.set')
+        const ref       = resolveDocRef(db, schema, idOrRef)
+        const validated = (options.merge || options.mergeFields)
+          ? schema.validatePartial(data)
+          : schema.validate(data)
+        batch.set(ref, validated, options)
+        return this
+      },
+
+      /** Partially update a document in the batch */
+      update(schema, idOrRef, data) {
+        assertSchema(schema, 'batch.update')
+        const ref       = resolveDocRef(db, schema, idOrRef)
+        const validated = schema.validatePartial(data)
+        batch.update(ref, validated)
+        return this
+      },
+
+      /** Delete a document in the batch */
+      delete(schema, idOrRef) {
+        assertSchema(schema, 'batch.delete')
+        const ref = resolveDocRef(db, schema, idOrRef)
+        batch.delete(ref)
+        return this
+      },
+
+      /** Commit all batched operations */
+      commit() {
+        return batch.commit()
+      },
+    }
+  }
+
+  // ── Transactions ──────────────────────────────────────────────────────────
+  /**
+   * Run a schema-aware transaction.
+   * The transaction callback receives a schema-aware transaction object.
+   *
+   * @param {(t: SchemaTransaction) => Promise<T>} updateFn
+   * @returns {Promise<T>}
+   *
+   * @example
+   * await runTransaction(async (t) => {
+   *   const user = await t.get(usersSchema, 'user-123')
+   *   if (!user) throw new Error('User not found')
+   *
+   *   await t.update(usersSchema, 'user-123', {
+   *     points: user.points + 10
+   *   })
+   * })
+   */
+  async function runTransaction(updateFn) {
+    return _runTransaction(db, (firestoreTx) => {
+      const t = {
+        /** Get a document within the transaction. Returns { id, ...data } or null. */
+        async get(schema, idOrRef) {
+          assertSchema(schema, 'transaction.get')
+          const ref      = resolveDocRef(db, schema, idOrRef)
+          const snapshot = await firestoreTx.get(ref)
+          return docToData(snapshot)
+        },
+
+        /** Set (overwrite) a document within the transaction */
+        set(schema, idOrRef, data, options = {}) {
+          assertSchema(schema, 'transaction.set')
+          const ref       = resolveDocRef(db, schema, idOrRef)
+          const validated = (options.merge || options.mergeFields)
+            ? schema.validatePartial(data)
+            : schema.validate(data)
+          firestoreTx.set(ref, validated, options)
+          return this
+        },
+
+        /** Partially update a document within the transaction */
+        update(schema, idOrRef, data) {
+          assertSchema(schema, 'transaction.update')
+          const ref       = resolveDocRef(db, schema, idOrRef)
+          const validated = schema.validatePartial(data)
+          firestoreTx.update(ref, validated)
+          return this
+        },
+
+        /** Delete a document within the transaction */
+        delete(schema, idOrRef) {
+          assertSchema(schema, 'transaction.delete')
+          const ref = resolveDocRef(db, schema, idOrRef)
+          firestoreTx.delete(ref)
+          return this
+        },
+      }
+
+      return updateFn(t)
+    })
+  }
+
+  // ── Return all operations ─────────────────────────────────────────────────
+  return {
+    createDoc,
+    setDoc,
+    updateDoc,
+    deleteDoc,
+    getDoc,
+    getDocs,
+    getDocRef,
+    getCollectionRef,
+    onDocSnapshot,
+    onCollectionSnapshot,
+    createBatch,
+    runTransaction,
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "firestore-schema-kit",
+  "version": "1.0.0",
+  "main": "index.js",
+  "exports": "./index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "Bonanza Narayan",
+  "license": "ISC",
+  "description": "Drizzle-style schema validation for Firebase Firestore.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BonanzaNarayan/firebase-schema.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BonanzaNarayan/firebase-schema/issues"
+  },
+  "homepage": "https://github.com/BonanzaNarayan/firebase-schema#readme",
+  "dependencies": {
+    "firebase": "^12.11.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {}
+}

package/readme.md

@@ -0,0 +1,301 @@
+# firebase-schema
+
+Drizzle-style schema validation for Firebase Firestore. Define your collections once, get validated reads and writes everywhere — with zero schema leaking to your app layer.
+
+Zod handles validation internally. You never touch Zod directly.
+
+---
+
+## Install
+
+```bash
+npm install zod firebase
+```
+
+Copy `src/` into your project (e.g. `lib/firebase-schema/`).
+
+---
+
+## Quick start
+
+### 1. Define your schemas
+
+```js
+// schema.js
+import { defineCollection } from './lib/firebase-schema'
+
+export const usersSchema = defineCollection('users', (s) => ({
+  name:      s.string().min(1),
+  email:     s.string().email(),
+  role:      s.enum(['admin', 'user']).default('user'),
+  age:       s.number().int().optional(),
+  isActive:  s.boolean().default(true),
+  createdAt: s.timestamp(),
+  updatedAt: s.timestamp(),
+}))
+
+export const postsSchema = defineCollection('posts', (s) => ({
+  title:     s.string().min(1).max(200),
+  body:      s.string(),
+  authorRef: s.reference(),
+  tags:      s.array(s.string()).default([]),
+  status:    s.enum(['draft', 'published']).default('draft'),
+  createdAt: s.timestamp(),
+}))
+```
+
+### 2. Init Firebase and bind operations
+
+```js
+// firebase.js
+import { initializeApp }     from 'firebase/app'
+import { getFirestore }      from 'firebase/firestore'
+import { initFirestoreSchema } from './lib/firebase-schema'
+
+const app = initializeApp({ /* your config */ })
+const db  = getFirestore(app)
+
+export const {
+  createDoc,
+  setDoc,
+  updateDoc,
+  deleteDoc,
+  getDoc,
+  getDocs,
+  getDocRef,
+  getCollectionRef,
+  onDocSnapshot,
+  onCollectionSnapshot,
+  createBatch,
+  runTransaction,
+} = initFirestoreSchema(db)
+
+export { db }
+```
+
+### 3. Use everywhere
+
+```js
+import { serverTimestamp, where, orderBy, limit } from 'firebase/firestore'
+import { createDoc, updateDoc, getDocs }          from './firebase.js'
+import { usersSchema }                            from './schema.js'
+
+// Create
+await createDoc(usersSchema, {
+  name:      'Alice',
+  email:     'alice@example.com',
+  createdAt: serverTimestamp(),
+  updatedAt: serverTimestamp(),
+})
+
+// Update (partial — only validates fields you provide)
+await updateDoc(usersSchema, 'user-123', {
+  name:      'Alice Smith',
+  updatedAt: serverTimestamp(),
+})
+
+// Query
+const admins = await getDocs(
+  usersSchema,
+  where('role', '==', 'admin'),
+  orderBy('name'),
+  limit(20)
+)
+```
+
+---
+
+## Field types
+
+| Field | Example | Options |
+|-------|---------|---------|
+| `s.string()` | `s.string().min(1).max(100)` | `.min()` `.max()` `.email()` `.url()` `.uuid()` `.regex()` |
+| `s.number()` | `s.number().int().positive()` | `.min()` `.max()` `.int()` `.positive()` `.negative()` |
+| `s.boolean()` | `s.boolean().default(false)` | — |
+| `s.timestamp()` | `s.timestamp()` | Accepts `Date`, Firestore `Timestamp`, `serverTimestamp()` |
+| `s.array(item)` | `s.array(s.string()).min(1)` | `.min()` `.max()` |
+| `s.map(shape)` | `s.map({ x: s.number(), y: s.number() })` | Nested schema |
+| `s.enum(values)` | `s.enum(['a', 'b', 'c'])` | — |
+| `s.reference()` | `s.reference()` | Accepts `DocumentReference` |
+| `s.literal(val)` | `s.literal('active')` | — |
+| `s.union(fields)` | `s.union([s.string(), s.number()])` | — |
+| `s.any()` | `s.any()` | Escape hatch |
+
+### Modifiers (available on all field types)
+
+```js
+s.string().optional()         // field can be absent from the object
+s.string().nullable()         // field can be null
+s.string().default('hello')   // use this value if field is absent
+```
+
+---
+
+## All operations
+
+### `createDoc(schema, data)` — addDoc equivalent
+Auto-generated ID. Full schema validation.
+
+```js
+const ref = await createDoc(usersSchema, { name: 'Alice', email: 'alice@example.com', createdAt: serverTimestamp(), updatedAt: serverTimestamp() })
+console.log(ref.id)
+```
+
+### `setDoc(schema, id, data, options?)` — setDoc equivalent
+Specific ID. Full validation. Pass `{ merge: true }` to merge (partial validation).
+
+```js
+await setDoc(usersSchema, 'user-123', { name: 'Alice', email: 'alice@example.com', createdAt: serverTimestamp(), updatedAt: serverTimestamp() })
+await setDoc(usersSchema, 'user-123', { bio: 'Hello' }, { merge: true })
+```
+
+### `updateDoc(schema, id, data)` — updateDoc equivalent
+Partial update. Only validates the fields you provide. Document must exist.
+
+```js
+await updateDoc(usersSchema, 'user-123', { name: 'Alice Updated', updatedAt: serverTimestamp() })
+```
+
+### `deleteDoc(schema, id)` — deleteDoc equivalent
+
+```js
+await deleteDoc(usersSchema, 'user-123')
+```
+
+### `getDoc(schema, id)` — getDoc equivalent
+Returns `{ id, ...data }` or `null`.
+
+```js
+const user = await getDoc(usersSchema, 'user-123')
+if (!user) return // not found
+console.log(user.name)
+```
+
+### `getDocs(schema, ...constraints)` — getDocs equivalent
+Returns `Array<{ id, ...data }>`. All Firestore query constraints work.
+
+```js
+import { where, orderBy, limit } from 'firebase/firestore'
+
+const users   = await getDocs(usersSchema)
+const admins  = await getDocs(usersSchema, where('role', '==', 'admin'))
+const recent  = await getDocs(usersSchema, orderBy('createdAt', 'desc'), limit(10))
+```
+
+### `getDocRef(schema, id)` — get a DocumentReference
+Useful for storing references in other documents.
+
+```js
+const authorRef = getDocRef(usersSchema, 'user-123')
+await createDoc(postsSchema, { title: 'Hello', authorRef, ... })
+```
+
+### `onDocSnapshot(schema, id, callback, onError?)` — real-time single doc
+
+```js
+const unsub = onDocSnapshot(usersSchema, 'user-123', (user) => {
+  if (!user) return
+  console.log(user.name)
+})
+unsub() // stop listening
+```
+
+### `onCollectionSnapshot(schema, callback, ...constraints)` — real-time collection
+
+```js
+const unsub = onCollectionSnapshot(
+  usersSchema,
+  (users) => console.log(users),
+  where('isActive', '==', true),
+  orderBy('name')
+)
+unsub()
+```
+
+### `createBatch()` — batch writes
+
+```js
+const batch = createBatch()
+
+const ref = batch.create(usersSchema, { name: 'Bob', email: 'bob@example.com', createdAt: serverTimestamp(), updatedAt: serverTimestamp() })
+
+batch
+  .set(usersSchema, 'user-456', { name: 'Charlie', email: 'charlie@example.com', createdAt: serverTimestamp(), updatedAt: serverTimestamp() })
+  .update(usersSchema, 'user-123', { isActive: false, updatedAt: serverTimestamp() })
+  .delete(usersSchema, 'user-old')
+
+await batch.commit()
+```
+
+### `runTransaction(fn)` — transactions
+
+```js
+await runTransaction(async (t) => {
+  const post = await t.get(postsSchema, 'post-123')
+  if (!post) throw new Error('Post not found')
+
+  t.update(postsSchema, 'post-123', { viewCount: post.viewCount + 1 })
+  t.set(commentsSchema, `c-${Date.now()}`, {
+    postRef: getDocRef(postsSchema, 'post-123'),
+    body: 'Nice!',
+    createdAt: serverTimestamp(),
+  })
+})
+```
+
+---
+
+## Validation errors
+
+All validation errors throw a `SchemaValidationError` before any Firestore write happens.
+
+```js
+import { SchemaValidationError } from './lib/firebase-schema'
+
+try {
+  await createDoc(usersSchema, { email: 'not-an-email' })
+} catch (err) {
+  if (err instanceof SchemaValidationError) {
+    console.log(err.collection) // 'users'
+    console.log(err.issues)     // Zod issue array
+    console.log(err.message)
+    // [users] Schema validation failed:
+    //   • name: Required
+    //   • email: Invalid email
+  }
+}
+```
+
+For safe (non-throwing) validation:
+
+```js
+const result = usersSchema.safeParse(data)
+if (!result.success) {
+  console.error(result.error.message)
+} else {
+  console.log(result.data)
+}
+```
+
+---
+
+## Nested collections (subcollections)
+
+Use the Firestore path format for subcollections:
+
+```js
+export const commentsSchema = defineCollection('posts/{postId}/comments', (s) => ({
+  body:      s.string().min(1),
+  authorRef: s.reference(),
+  createdAt: s.timestamp(),
+}))
+```
+
+For subcollections you'll typically use `getDocRef` or `getCollectionRef` with a concrete path:
+
+```js
+import { collection, doc } from 'firebase/firestore'
+
+// Direct Firestore ref for the specific post's comments
+const commentsRef = collection(db, 'posts', postId, 'comments')
+```