@firestore-repository/firebase-js-sdk 0.4.2 → 0.5.0

package/README.md

@@ -4,14 +4,14 @@
 
 # firestore-repository
 
-A minimum and universal Firestore ORM (Repository Pattern) for TypeScript
+A minimal and universal Firestore client (Repository Pattern) for TypeScript
 
 ## Features
 
-- 🚀 **Minimum**: Only a few straightforward interfaces and classes. You can easily start to use it immediately without learning a lot of things.
+- 🚀 **Minimal**: Only a few straightforward interfaces and classes. You can start using it immediately without a steep learning curve.
 - 🌐 **Universal**: You can share most code, including schema and query definitions, between backend and frontend.
-- 🤝 **Unopinionated**: This library does not introduce any additional concepts, and respects vocabulary of the official Firestore client library.
-- ✅ **Type-safe**: This library provides the type-safe interface. It also covers the untyped parts of the official Firestore library.
+- 🤝 **Unopinionated**: This library does not introduce any additional concepts, and respects the vocabulary of the official Firestore client library.
+- ✅ **Type-safe**: This library provides a type-safe interface. It also covers the untyped parts of the official Firestore library.
 - 🗄️ **Repository Pattern**: A simple and consistent way to access Firestore data.
 
 ## Installation
@@ -19,8 +19,8 @@ A minimum and universal Firestore ORM (Repository Pattern) for TypeScript
 ### For backend (with [`@google-cloud/firestore`](https://www.npmjs.com/package/@google-cloud/firestore))
 
 ```shell
-npm install firestore-repository @firestore-repository/google-cloud-firestore 
-````
+npm install firestore-repository @firestore-repository/google-cloud-firestore
+```
 
 ### For web frontend (with [`@firebase/firestore`](https://www.npmjs.com/package/@firebase/firestore))
 
@@ -33,79 +33,91 @@ npm install firestore-repository @firestore-repository/firebase-js-sdk
 ### Define a collection and its repository
 
 ```ts
-import { mapTo, data, rootCollection } from 'firestore-repository/schema';
+import {
+  rootCollection,
+  string,
+  double,
+  map,
+  optional,
+  literal,
+  array,
+} from 'firestore-repository/schema';
 
 // For backend
 import { Firestore } from '@google-cloud/firestore';
-import { Repository } from '@firestore-repository/google-cloud-firestore';
+import { rootCollectionRepository } from '@firestore-repository/google-cloud-firestore';
 const db = new Firestore();
 
 // For web frontend
 import { getFirestore } from '@firebase/firestore';
-import { Repository } from '@firestore-repository/firebase-js-sdk';
+import { rootCollectionRepository } from '@firestore-repository/firebase-js-sdk';
 const db = getFirestore();
 
 // define a collection
 const users = rootCollection({
   name: 'Users',
-  id: mapTo('userId'),
-  data: data<{
-    name: string;
-    profile: {
-      age: number;
-      gender?: 'male' | 'female';
-    };
-    tag: string[];
-  }>(),
+  schema: {
+    name: string(),
+    profile: map({ age: double(), gender: optional(literal('male', 'female')) }),
+    tag: array(string()),
+  },
 });
 
-const repository = new Repository(users, db);
+const repository = rootCollectionRepository(db, users);
 ```
 
 ### Basic operations for a single document
 
+All operations are **type-safe** based on the schema you defined. The `data` field is typed according to your schema, so invalid data structures are caught at compile time.
+
 ```ts
 // Set a document
 await repository.set({
-  userId: 'user1',
-  name: 'John Doe',
-  profile: {
-    age: 42,
-    gender: 'male',
-  },
-  tag: ['new'],
+  ref: 'user1',
+  data: { name: 'John Doe', profile: { age: 42, gender: 'male' }, tag: ['new'] },
+});
+
+// Create a document (backend only)
+await repository.create({
+  ref: 'user2',
+  data: { name: 'Charlie', profile: { age: 25, gender: 'male' }, tag: [] },
 });
 
 // Get a document
-const doc = await repository.get({ userId: 'user1' });
+const doc = await repository.get('user1');
 
-// Listen a document
-repository.getOnSnapshot({ userId: 'user1' }, (doc) => {
+// Listen to a document
+repository.getOnSnapshot('user1', (doc) => {
   console.log(doc);
 });
 
 // Delete a document
-await repository.delete({ userId: 'user2' });
+await repository.delete('user2');
 ```
 
 ### Query
 
+Field paths in query conditions are **automatically derived from the schema type**, not just plain strings — so typos and invalid paths are caught at compile time. The filter value is also **type-checked based on the field type and operator** (e.g., `array-contains` expects an element type of the array field).
+
 ```ts
-import { condition as $, limit, query } from 'firestore-repository/query';
+import { eq, gte, limit, query, where } from 'firestore-repository/query';
+import { average, count, sum } from 'firestore-repository/aggregate';
 
 // Define a query
+// Field paths like 'profile.age' are auto-completed and type-checked against the schema.
+// The value `20` is validated as `number` because `profile.age` is `number`.
 const q = query(
-    users,
-    $('profile.age', '>=', 20),
-    $('profile.gender', '==', 'male'),
-    limit(10),
+  { collection: users },
+  where(gte('profile.age', 20), eq('profile.gender', 'male')),
+  // where(gte('profile.age', 'foo')) // ← Compile error: string is not assignable to number
+  // where(eq('nonExistent', 1))      // ← Compile error: invalid field path
+  limit(10),
 );
 
 // List documents
 const docs = await repository.list(q);
-console.log(docs);
 
-// Listen documents
+// Listen to documents
 repository.listOnSnapshot(q, (docs) => {
   console.log(docs);
 });
@@ -123,52 +135,39 @@ console.log(`avg:${result.avgAge} sum:${result.sumAge} count:${result.count}`);
 
 ```ts
 // Get multiple documents (backend only)
-const users = await repository.batchGet([{ userId: 'user1' }, { userId: 'user2' }]);
+const users = await repository.batchGet(['user1', 'user2']);
 
 // Set multiple documents
 await repository.batchSet([
-  {
-    userId: 'user1',
-    name: 'Alice',
-    profile: { age: 30, gender: 'female' },
-    tag: ['new'],
-  },
-  {
-    userId: 'user2',
-    name: 'Bob',
-    profile: { age: 20, gender: 'male' },
-    tag: [],
-  },
+  { ref: 'user1', data: { name: 'Alice', profile: { age: 30, gender: 'female' }, tag: ['new'] } },
+  { ref: 'user2', data: { name: 'Bob', profile: { age: 20, gender: 'male' }, tag: [] } },
 ]);
 
 // Delete multiple documents
-await repository.batchDelete([{ userId: 'user1' }, { userId: 'user2' }]);
+await repository.batchDelete(['user1', 'user2']);
 ```
 
 #### Include multiple different operations in a batch
 
 ```ts
 // For backend
-const batch = db.writeBatch();
+const batch = db.batch();
 // For web frontend
 import { writeBatch } from '@firebase/firestore';
-const batch = writeBatch();
+const batch = writeBatch(db);
 
 await repository.set(
-    {
-      userId: 'user3',
-      name: 'Bob',
-      profile: { age: 20, gender: 'male' },
-      tag: [],
-    },
-    { tx: batch },
+  { ref: 'user3', data: { name: 'Bob', profile: { age: 20, gender: 'male' }, tag: [] } },
+  { tx: batch },
 );
-await repository.batchSet([ /* ... */ ], { tx: batch },
+await repository.batchSet(
+  [
+    /* ... */
+  ],
+  { tx: batch },
 );
-await repository.delete({ userId: 'user4' }, { tx: batch });
-await repository.batchDelete([{ userId: 'user5' }, { userId: 'user6' }], {
-  tx: batch,
-});
+await repository.delete('user4', { tx: batch });
+await repository.batchDelete(['user5', 'user6'], { tx: batch });
 
 await batch.commit();
 ```
@@ -179,24 +178,105 @@ await batch.commit();
 // For web frontend
 import { runTransaction } from '@firebase/firestore';
 
-// Or, please use db.runTransaction for backend
-await runTransaction(async (tx) => {
+// Or use db.runTransaction for backend
+await runTransaction(db, async (tx) => {
   // Get
-  const doc = await repository.get({ userId: 'user1' }, { tx });
-  
+  const doc = await repository.get('user1', { tx });
+
   if (doc) {
-    doc.tag = [...doc.tag, 'new-tag'];
+    doc.data.tag = [...doc.data.tag, 'new-tag'];
     // Set
     await repository.set(doc, { tx });
-    await repository.batchSet([
-      { ...doc, userId: 'user2' },
-      { ...doc, userId: 'user3' },
-    ], { tx });
+    await repository.batchSet(
+      [
+        { ...doc, ref: 'user2' },
+        { ...doc, ref: 'user3' },
+      ],
+      { tx },
+    );
   }
 
   // Delete
-  await repository.delete({ userId: 'user4' }, { tx });
-  await repository.batchDelete([{ userId: 'user5' }, { userId: 'user6' }], { tx });
+  await repository.delete('user4', { tx });
+  await repository.batchDelete(['user5', 'user6'], { tx });
+});
+```
+
+### Subcollection
+
+Subcollections are defined with `subCollection`, specifying the parent collection path. The only difference from root collections is that the document ref becomes a tuple (array of parent doc ID + doc ID). All other operations (query, batch, transaction, etc.) work the same.
+
+```ts
+import { subCollection, string } from 'firestore-repository/schema';
+
+// For backend
+import { subcollectionRepository } from '@firestore-repository/google-cloud-firestore';
+
+// For web frontend
+import { subcollectionRepository } from '@firestore-repository/firebase-js-sdk';
+
+const posts = subCollection({
+  name: 'Posts',
+  schema: { title: string() },
+  parent: ['Users'] as const,
 });
+
+const postRepository = subcollectionRepository(db, posts);
+
+// Set a document (ref is [parentDocId, docId])
+await postRepository.set({ ref: ['user1', 'post1'], data: { title: 'My first post' } });
+
+// Get a document
+const post = await postRepository.get(['user1', 'post1']);
 ```
 
+### Custom Mapper
+
+By default, `rootCollectionRepository` returns a repository with `{ ref: string, data: ... }` as its model type. If you want to use your own application model types, you can define a custom `Mapper` and use `repositoryWithMapper` to create a repository that automatically converts between Firestore documents and your models.
+
+A `Mapper` consists of three functions:
+
+- `toDocRef`: Converts your model's ID to a Firestore document reference
+- `fromFirestore`: Converts a Firestore document to your read model
+- `toFirestore`: Converts your write model to a Firestore document
+
+You can also define different types for reading and writing via `AppModel<Id, Read, Write>` (e.g., omitting server-managed fields from the write type).
+
+```ts
+import { type AppModel, type Mapper } from 'firestore-repository/repository';
+
+// For backend
+import { repositoryWithMapper } from '@firestore-repository/google-cloud-firestore';
+// For web frontend
+import { repositoryWithMapper } from '@firestore-repository/firebase-js-sdk';
+
+// Define your application model type
+type User = {
+  id: string;
+  name: string;
+  profile: { age: number; gender?: 'male' | 'female' };
+  tag: string[];
+};
+
+// Define a mapper
+const userMapper: Mapper<typeof users, AppModel<string, User, User>> = {
+  toDocRef: (id) => [id],
+  fromFirestore: (doc) => ({ id: doc.ref[0], ...doc.data }),
+  toFirestore: (user) => ({
+    ref: [user.id],
+    data: { name: user.name, profile: user.profile, tag: user.tag },
+  }),
+};
+
+const repository = repositoryWithMapper(db, users, userMapper);
+
+// Now the repository accepts and returns your custom User type directly
+await repository.set({
+  id: 'user1',
+  name: 'Alice',
+  profile: { age: 30, gender: 'female' },
+  tag: ['new'],
+});
+const user: User | undefined = await repository.get('user1');
+await repository.delete('user1');
+```

package/build/esm/codec.d.ts

@@ -0,0 +1,5 @@
+import { Firestore } from '@firebase/firestore';
+import type { DocumentSchema } from 'firestore-repository/schema';
+import * as z from 'zod';
+export declare function buildDecodeSchema(schema: DocumentSchema): z.ZodObject<z.ZodRawShape>;
+export declare function buildEncodeSchema(schema: DocumentSchema, db: Firestore): z.ZodObject<z.ZodRawShape>;

package/build/esm/codec.js

@@ -0,0 +1,176 @@
+import { Bytes as FirestoreBytes, DocumentReference as FirestoreDocumentReference, GeoPoint as FirestoreGeoPoint, Timestamp as FirestoreTimestamp, VectorValue as FirestoreVectorValue, arrayRemove as firestoreArrayRemove, arrayUnion as firestoreArrayUnion, doc, increment as firestoreIncrement, serverTimestamp as firestoreServerTimestamp, vector, } from '@firebase/firestore';
+import { documentPath } from 'firestore-repository/path';
+import { _optional, serverOperation } from 'firestore-repository/schema';
+import { assertNever } from 'firestore-repository/util';
+import * as z from 'zod';
+const isServerOp = (v, op) => v != null && typeof v === 'object' && Reflect.get(v, serverOperation) === op;
+export function buildDecodeSchema(schema) {
+    return z.object(Object.fromEntries(Object.entries(schema).map(([k, v]) => {
+        const s = buildDecodeField(v);
+        return [k, v[_optional] ? s.optional() : s];
+    })));
+}
+function buildDecodeField(fieldType) {
+    switch (fieldType.type) {
+        case 'string':
+            return z.string();
+        case 'bool':
+            return z.boolean();
+        case 'int64':
+        case 'double':
+            return z.number();
+        case 'null':
+            return z.null();
+        case 'bytes':
+            // oxlint-disable-next-line typescript/no-explicit-any
+            return z.custom((v) => v instanceof FirestoreBytes).transform((b) => b.toUint8Array());
+        case 'timestamp':
+            // oxlint-disable-next-line typescript/no-explicit-any
+            return z.custom((v) => v instanceof FirestoreTimestamp).transform((ts) => ts.toDate());
+        case 'geoPoint':
+            // oxlint-disable-next-line typescript/no-explicit-any
+            return z
+                .custom((v) => v instanceof FirestoreGeoPoint)
+                .transform((gp) => ({ latitude: gp.latitude, longitude: gp.longitude }));
+        case 'vector':
+            // oxlint-disable-next-line typescript/no-explicit-any
+            return z
+                .custom((v) => v instanceof FirestoreVectorValue)
+                .transform((vv) => vv.toArray());
+        case 'docRef':
+            // oxlint-disable-next-line typescript/no-explicit-any
+            return z
+                .custom((v) => v instanceof FirestoreDocumentReference)
+                .transform((ref) => {
+                const ids = [];
+                let current = ref;
+                while (current != null) {
+                    ids.push(current.id);
+                    current = current.parent.parent;
+                }
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+                return ids.reverse();
+            });
+        case 'map': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return z.object(Object.fromEntries(Object.entries(ft.fields).map(([k, v]) => {
+                const s = buildDecodeField(v);
+                return [k, v[_optional] ? s.optional() : s];
+            })));
+        }
+        case 'array': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return z.array(buildDecodeField(ft.dynamicPart));
+        }
+        case 'union': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return zodUnion(ft.elements.map(buildDecodeField));
+        }
+        case 'const': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return zodUnion(ft.values.map((v) => z.literal(v)));
+        }
+        default:
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            return assertNever(fieldType);
+    }
+}
+export function buildEncodeSchema(schema, db) {
+    return z.object(Object.fromEntries(Object.entries(schema).map(([k, v]) => {
+        const s = buildEncodeField(v, db);
+        return [k, v[_optional] ? s.optional() : s];
+    })));
+}
+function buildEncodeField(fieldType, db) {
+    switch (fieldType.type) {
+        case 'string':
+            return z.string();
+        case 'bool':
+            return z.boolean();
+        case 'null':
+            return z.null();
+        case 'bytes':
+            return z.instanceof(Uint8Array).transform((b) => FirestoreBytes.fromUint8Array(b));
+        case 'geoPoint':
+            return z
+                .object({ latitude: z.number(), longitude: z.number() })
+                .transform((gp) => new FirestoreGeoPoint(gp.latitude, gp.longitude));
+        case 'vector':
+            return z.array(z.number()).transform((arr) => vector(arr));
+        case 'int64':
+        case 'double':
+            return zodUnion([
+                // oxlint-disable-next-line typescript/no-explicit-any
+                z
+                    .custom((v) => isServerOp(v, 'increment'))
+                    .transform((v) => firestoreIncrement(v.amount)),
+                z.number(),
+            ]);
+        case 'timestamp':
+            return zodUnion([
+                // oxlint-disable-next-line typescript/no-explicit-any
+                z
+                    .custom((v) => isServerOp(v, 'serverTimestamp'))
+                    .transform(() => firestoreServerTimestamp()),
+                z.date().transform((d) => FirestoreTimestamp.fromDate(d)),
+            ]);
+        case 'docRef': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return z.array(z.string()).transform((ref) => 
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            doc(db, documentPath(ft.collection, ref)));
+        }
+        case 'map': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return z.object(Object.fromEntries(Object.entries(ft.fields).map(([k, v]) => {
+                const s = buildEncodeField(v, db);
+                return [k, v[_optional] ? s.optional() : s];
+            })));
+        }
+        case 'array': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return zodUnion([
+                // oxlint-disable-next-line typescript/no-explicit-any
+                z
+                    .custom((v) => isServerOp(v, 'arrayRemove'))
+                    .transform((v) => firestoreArrayRemove(...v.values)),
+                // oxlint-disable-next-line typescript/no-explicit-any
+                z
+                    .custom((v) => isServerOp(v, 'arrayUnion'))
+                    .transform((v) => firestoreArrayUnion(...v.values)),
+                z.array(buildEncodeField(ft.dynamicPart, db)),
+            ]);
+        }
+        case 'union': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return zodUnion(ft.elements.map((e) => buildEncodeField(e, db)));
+        }
+        case 'const': {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            const ft = fieldType;
+            return zodUnion(ft.values.map((v) => z.literal(v)));
+        }
+        default:
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+            return assertNever(fieldType);
+    }
+}
+function zodUnion(schemas) {
+    if (schemas.length === 0) {
+        throw new Error('union must have at least one element');
+    }
+    if (schemas.length === 1) {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        return schemas[0];
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return z.union(schemas);
+}

package/build/esm/index.d.ts

@@ -1,40 +1,16 @@
-import { type DocumentReference, type DocumentSnapshot, type Firestore, type Query as FirestoreQuery, Transaction, type WriteBatch } from '@firebase/firestore';
-import type { AggregateSpec, Aggregated } from 'firestore-repository/aggregate';
-import type { WriteDocumentData } from 'firestore-repository/document';
-import type { Query } from 'firestore-repository/query';
-import type * as repository from 'firestore-repository/repository';
-import { type CollectionSchema, type DocPathElement, type Id, type Model, type ParentId } from 'firestore-repository/schema';
+import type { Firestore, Query as FirestoreQuery, WriteBatch } from '@firebase/firestore';
+import { Transaction } from '@firebase/firestore';
+import { type AppModel, type Mapper, type PlainModel, type Repository, type RootCollectionPlainModel } from 'firestore-repository/repository';
+import type { Collection, RootCollection, SubCollection } from 'firestore-repository/schema';
+/** Platform-specific environment types for Firebase JS SDK */
 export type Env = {
     transaction: Transaction;
     writeBatch: WriteBatch;
     query: FirestoreQuery;
 };
-export type TransactionOption = repository.TransactionOption<Env>;
-export type WriteTransactionOption = repository.WriteTransactionOption<Env>;
-export declare class Repository<T extends CollectionSchema = CollectionSchema> implements repository.Repository<T, Env> {
-    readonly collection: T;
-    readonly db: Firestore;
-    constructor(collection: T, db: Firestore);
-    get(id: Id<T>, options?: TransactionOption): Promise<Model<T> | undefined>;
-    getOnSnapshot(id: Id<T>, next: (snapshot: Model<T> | undefined) => void, error?: (error: Error) => void, complete?: () => void): repository.Unsubscribe;
-    list(query: Query<T>): Promise<Model<T>[]>;
-    listOnSnapshot(query: Query<T>, next: (snapshot: Model<T>[]) => void, error?: (error: Error) => void, complete?: () => void): repository.Unsubscribe;
-    aggregate<U extends AggregateSpec<T>>(query: Query<T>, spec: U): Promise<Aggregated<U>>;
-    set(doc: Model<T>, options?: WriteTransactionOption): Promise<void>;
-    delete(id: Id<T>, options?: WriteTransactionOption): Promise<void>;
-    batchSet(docs: Model<T>[], options?: WriteTransactionOption): Promise<void>;
-    batchDelete(ids: Id<T>[], options?: WriteTransactionOption): Promise<void>;
-    protected batchWriteOperation<U>(targets: U[], runner: {
-        batch: (batch: WriteBatch, target: U) => void;
-        transaction: (transaction: Transaction, target: U) => void;
-    }, options?: WriteTransactionOption): Promise<void>;
-    protected docRef(id: Id<T>): DocumentReference<import("@firebase/firestore").DocumentData, import("@firebase/firestore").DocumentData>;
-    protected collectionRef(parentId: ParentId<T>): import("@firebase/firestore").CollectionReference<import("@firebase/firestore").DocumentData, import("@firebase/firestore").DocumentData>;
-    protected fromFirestore(doc: DocumentSnapshot): Model<T> | undefined;
-    protected toFirestoreData(data: Model<T>): WriteDocumentData;
-}
-/**
- * Obtain document path elements from DocumentReference
- */
-export declare const docPathElements: (doc: DocumentReference) => [DocPathElement, ...DocPathElement[]];
-export declare const toFirestoreQuery: (db: Firestore, query: Query) => FirestoreQuery;
+/** Creates a repository for a root collection using plain document types */
+export declare const rootCollectionRepository: <T extends RootCollection>(db: Firestore, collection: T) => Repository<T, RootCollectionPlainModel<T>, Env>;
+/** Creates a repository for a subcollection using plain document types */
+export declare const subcollectionRepository: <T extends SubCollection>(db: Firestore, collection: T) => Repository<T, PlainModel<T>, Env>;
+/** Creates a repository with a custom mapper for transforming between Firestore documents and application models */
+export declare const repositoryWithMapper: <T extends Collection, Model extends AppModel>(db: Firestore, collection: T, mapper: Mapper<T, Model>) => Repository<T, Model, Env>;

package/build/esm/index.js

@@ -1,214 +1,232 @@
-import { QueryCompositeFilterConstraint, Transaction, and, average, collection, collectionGroup, count, deleteDoc, doc, endAt, endBefore, query as firestoreQuery, getAggregateFromServer, getDoc, getDocs, limit, limitToLast, onSnapshot, or, orderBy, setDoc, startAfter, startAt, sum, where, writeBatch, } from '@firebase/firestore';
-import { collectionPath, docPath, } from 'firestore-repository/schema';
+import { and, average, collection, collectionGroup, count, deleteDoc, doc, endAt, endBefore, getAggregateFromServer, getDoc, getDocs, limit, limitToLast, onSnapshot, or, orderBy, query as firestoreQuery, setDoc, startAfter, startAt, sum, Transaction, where, writeBatch, } from '@firebase/firestore';
+import { collectionPath, documentPath } from 'firestore-repository/path';
+import { plainMapper, rootCollectionPlainMapper, } from 'firestore-repository/repository';
 import { assertNever } from 'firestore-repository/util';
-export class Repository {
-    collection;
-    db;
-    constructor(collection, db) {
-        this.collection = collection;
-        this.db = db;
-    }
-    async get(id, options) {
-        const doc = await (options?.tx ? options.tx.get(this.docRef(id)) : getDoc(this.docRef(id)));
-        return this.fromFirestore(doc);
-    }
-    getOnSnapshot(id, next, error, complete) {
-        return onSnapshot(this.docRef(id), {
-            next: (doc) => {
-                next(this.fromFirestore(doc));
-            },
-            error: (e) => error?.(e),
-            complete: () => {
-                complete?.();
-            },
-        });
-    }
-    async list(query) {
-        const { docs } = await getDocs(toFirestoreQuery(this.db, query));
-        return docs.map((doc) => 
-        // biome-ignore lint/style/noNonNullAssertion: query result item should not be null
-        this.fromFirestore(doc));
-    }
-    listOnSnapshot(query, next, error, complete) {
-        return onSnapshot(toFirestoreQuery(this.db, query), {
-            next: ({ docs }) => {
-                // biome-ignore lint/style/noNonNullAssertion: query result item should not be null
-                next(docs.map((doc) => this.fromFirestore(doc)));
-            },
-            error: (e) => error?.(e),
-            complete: () => {
-                complete?.();
-            },
-        });
-    }
-    async aggregate(query, spec) {
-        const aggregateSpec = {};
-        for (const [k, v] of Object.entries(spec)) {
-            switch (v.kind) {
-                case 'count':
-                    aggregateSpec[k] = count();
-                    break;
-                case 'sum':
-                    aggregateSpec[k] = sum(v.path);
-                    break;
-                case 'average':
-                    aggregateSpec[k] = average(v.path);
-                    break;
+import { buildDecodeSchema, buildEncodeSchema } from './codec.js';
+/** Creates a repository for a root collection using plain document types */
+export const rootCollectionRepository = (db, collection) => repositoryWithMapper(db, collection, rootCollectionPlainMapper(collection));
+/** Creates a repository for a subcollection using plain document types */
+export const subcollectionRepository = (db, collection) => repositoryWithMapper(db, collection, plainMapper(collection));
+/** Creates a repository with a custom mapper for transforming between Firestore documents and application models */
+export const repositoryWithMapper = (db, collection, mapper) => {
+    const { toFirestore, fromFirestore, batchWriteOperation, encodeSchema } = buildFirestoreUtilities(db, collection);
+    // oxlint-disable-next-line typescript/no-explicit-any -- Zod output is passed to Firestore SDK
+    const encode = (data) => encodeSchema.parse(data);
+    return {
+        collection,
+        get: async (ref, options) => {
+            const docRef = toFirestore.docRef(mapper.toDocRef(ref));
+            const documentSnapshot = await (options?.tx ? options.tx.get(docRef) : getDoc(docRef));
+            const doc = fromFirestore.document(documentSnapshot);
+            if (!doc) {
+                return undefined;
+            }
+            return mapper.fromFirestore(doc);
+        },
+        getOnSnapshot: (ref, next, error) => {
+            const docRef = toFirestore.docRef(mapper.toDocRef(ref));
+            return onSnapshot(docRef, {
+                next: (snapshot) => {
+                    const doc = fromFirestore.document(snapshot);
+                    next(doc ? mapper.fromFirestore(doc) : undefined);
+                },
+                error: (e) => error?.(e),
+            });
+        },
+        list: async (query) => {
+            const firestoreQueryObj = toFirestore.query(query);
+            const { docs } = await getDocs(firestoreQueryObj);
+            return docs.values().map((doc) => mapper.fromFirestore(fromFirestore.documentMustExist(doc)));
+        },
+        listOnSnapshot: (query, next, error) => {
+            const firestoreQueryObj = toFirestore.query(query);
+            return onSnapshot(firestoreQueryObj, {
+                next: ({ docs }) => next(docs.map((doc) => mapper.fromFirestore(fromFirestore.documentMustExist(doc)))),
+                error: (e) => error?.(e),
+            });
+        },
+        aggregate: async (query, spec) => {
+            const aggregateSpec = {};
+            for (const [k, v] of Object.entries(spec)) {
+                switch (v.kind) {
+                    case 'count':
+                        aggregateSpec[k] = count();
+                        break;
+                    case 'sum':
+                        aggregateSpec[k] = sum(v.path);
+                        break;
+                    case 'average':
+                        aggregateSpec[k] = average(v.path);
+                        break;
+                    default:
+                        return assertNever(v);
+                }
+            }
+            const firestoreQueryObj = toFirestore.query(query);
+            const res = await getAggregateFromServer(firestoreQueryObj, aggregateSpec);
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- there is no way to infer correct type
+            return res.data();
+        },
+        set: async (model, options) => {
+            const docToWrite = mapper.toFirestore(model);
+            const docRef = toFirestore.docRef(docToWrite.ref);
+            const data = encode(docToWrite.data);
+            await (options?.tx
+                ? options.tx instanceof Transaction
+                    ? options.tx.set(docRef, data)
+                    : options.tx.set(docRef, data)
+                : setDoc(docRef, data));
+        },
+        delete: async (ref, options) => {
+            const docRef = toFirestore.docRef(mapper.toDocRef(ref));
+            await (options?.tx ? options.tx.delete(docRef) : deleteDoc(docRef));
+        },
+        batchSet: async (models, options) => {
+            const docs = models.map((m) => {
+                const d = mapper.toFirestore(m);
+                return { ref: d.ref, data: encode(d.data) };
+            });
+            await batchWriteOperation(docs, {
+                batch: (batch, d) => batch.set(toFirestore.docRef(d.ref), d.data),
+                transaction: (tx, d) => tx.set(toFirestore.docRef(d.ref), d.data),
+            }, options);
+        },
+        batchDelete: async (refs, options) => {
+            const docRefs = refs.map(mapper.toDocRef);
+            await batchWriteOperation(docRefs, {
+                batch: (batch, ref) => batch.delete(toFirestore.docRef(ref)),
+                transaction: (tx, ref) => tx.delete(toFirestore.docRef(ref)),
+            }, options);
+        },
+    };
+};
+const buildFirestoreUtilities = (db, coll) => {
+    const decodeSchema = buildDecodeSchema(coll.schema);
+    const encodeSchema = buildEncodeSchema(coll.schema, db);
+    const toFirestore = {
+        docRef: (ref) => doc(db, documentPath(coll, ref)),
+        query: (query) => {
+            let base;
+            if ('collection' in query.base) {
+                base = query.base.group
+                    ? collectionGroup(db, query.base.collection.name)
+                    : collection(db, collectionPath(query.base.collection, query.base.parent));
+            }
+            else if ('extends' in query.base) {
+                base = toFirestore.query(query.base.extends);
+            }
+            else {
+                return assertNever(query.base);
+            }
+            if (!query.constraints || query.constraints.length === 0) {
+                return base;
+            }
+            const { filter, nonFilter } = query.constraints.reduce((acc, constraint) => {
+                switch (constraint.kind) {
+                    case 'where': {
+                        const f = toFirestore.filter(constraint.condition);
+                        acc.filter = acc.filter ? and(acc.filter, f) : f;
+                        break;
+                    }
+                    case 'orderBy':
+                        acc.nonFilter.push(orderBy(constraint.field, constraint.direction));
+                        break;
+                    case 'limit':
+                        acc.nonFilter.push(limit(constraint.limit));
+                        break;
+                    case 'limitToLast':
+                        acc.nonFilter.push(limitToLast(constraint.limit));
+                        break;
+                    case 'offset':
+                        // https://github.com/firebase/firebase-js-sdk/issues/479
+                        throw new Error('firebase-js-sdk does not support offset constraint');
+                    case 'startAt': {
+                        const { cursor } = constraint;
+                        acc.nonFilter.push(startAt(...cursor));
+                        break;
+                    }
+                    case 'startAfter': {
+                        const { cursor } = constraint;
+                        acc.nonFilter.push(startAfter(...cursor));
+                        break;
+                    }
+                    case 'endAt': {
+                        const { cursor } = constraint;
+                        acc.nonFilter.push(endAt(...cursor));
+                        break;
+                    }
+                    case 'endBefore': {
+                        const { cursor } = constraint;
+                        acc.nonFilter.push(endBefore(...cursor));
+                        break;
+                    }
+                    default:
+                        return assertNever(constraint);
+                }
+                return acc;
+            }, { nonFilter: [] });
+            // Wrap single filter in and() to satisfy QueryCompositeFilterConstraint overload
+            return filter
+                ? firestoreQuery(base, and(filter), ...nonFilter)
+                : firestoreQuery(base, ...nonFilter);
+        },
+        filter: (expr) => {
+            switch (expr.kind) {
+                case 'fieldValueCondition':
+                    return where(expr.fieldPath, expr.opStr, expr.value);
+                case 'and':
+                    return and(...expr.filters.map(toFirestore.filter));
+                case 'or':
+                    return or(...expr.filters.map(toFirestore.filter));
                 default:
-                    return assertNever(v);
+                    return assertNever(expr);
             }
-        }
-        const res = await getAggregateFromServer(toFirestoreQuery(this.db, query), aggregateSpec);
-        return res.data();
-    }
-    async set(doc, options) {
-        const data = this.toFirestoreData(doc);
-        await (options?.tx
-            ? options.tx instanceof Transaction
-                ? options.tx.set(this.docRef(doc), data)
-                : options.tx.set(this.docRef(doc), data)
-            : setDoc(this.docRef(doc), data));
-    }
-    async delete(id, options) {
-        await (options?.tx ? options.tx.delete(this.docRef(id)) : deleteDoc(this.docRef(id)));
-    }
-    async batchSet(docs, options) {
-        await this.batchWriteOperation(docs, {
-            batch: (batch, doc) => batch.set(this.docRef(doc), this.toFirestoreData(doc)),
-            transaction: (tx, doc) => tx.set(this.docRef(doc), this.toFirestoreData(doc)),
-        }, options);
-    }
-    async batchDelete(ids, options) {
-        await this.batchWriteOperation(ids, {
-            batch: (batch, id) => batch.delete(this.docRef(id)),
-            transaction: (tx, id) => tx.delete(this.docRef(id)),
-        }, options);
-    }
-    async batchWriteOperation(targets, runner, options) {
+        },
+    };
+    const fromFirestore = {
+        documentMustExist: (document) => {
+            const data = document.data();
+            if (!data) {
+                throw new Error('document must exist');
+            }
+            return {
+                ref: fromFirestore.docRef(document.ref),
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Zod output is typed by schema
+                data: decodeSchema.parse(data),
+            };
+        },
+        document: (document) => {
+            if (!document.exists()) {
+                return undefined;
+            }
+            return fromFirestore.documentMustExist(document);
+        },
+        docRef: (ref) => {
+            const docRef = [];
+            let currentRef = ref;
+            while (currentRef != null) {
+                docRef.push(currentRef.id);
+                currentRef = currentRef.parent.parent;
+            }
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- cannot infer type here
+            return docRef.reverse();
+        },
+    };
+    const batchWriteOperation = async (targets, runner, options) => {
         const tx = options?.tx;
         if (tx) {
             if (tx instanceof Transaction) {
-                targets.forEach((target) => runner.transaction(tx, target));
+                targets.forEach((target) => void runner.transaction(tx, target));
             }
             else {
-                targets.forEach((target) => runner.batch(tx, target));
+                targets.forEach((target) => void runner.batch(tx, target));
             }
         }
         else {
-            const batch = writeBatch(this.db);
-            targets.forEach((target) => runner.batch(batch, target));
+            const batch = writeBatch(db);
+            targets.forEach((target) => void runner.batch(batch, target));
             await batch.commit();
         }
-    }
-    docRef(id) {
-        return doc(this.db, docPath(this.collection, id));
-    }
-    collectionRef(parentId) {
-        return collection(this.db, collectionPath(this.collection, parentId));
-    }
-    fromFirestore(doc) {
-        const data = doc.data();
-        const [id, ...parentPath] = docPathElements(doc.ref);
-        return data
-            ? {
-                ...this.collection.data.from(data),
-                ...this.collection.collectionPath.from(parentPath),
-                ...this.collection.id.from(id.id),
-            }
-            : undefined;
-    }
-    toFirestoreData(data) {
-        return this.collection.data.to(data);
-    }
-}
-/**
- * Obtain document path elements from DocumentReference
- */
-export const docPathElements = (doc) => {
-    const parentPath = [];
-    let cursor = doc.parent.parent;
-    while (cursor) {
-        parentPath.push({ id: cursor.id, collection: cursor.parent.id });
-        cursor = cursor.parent.parent;
-    }
-    return [{ collection: doc.parent.id, id: doc.id }, ...parentPath];
-};
-export const toFirestoreQuery = (db, query) => {
-    const { filter, nonFilter } = (query.constraints ?? []).reduce((acc, constraint) => {
-        switch (constraint.kind) {
-            case 'where':
-            case 'and':
-            case 'or': {
-                const filter = toFirestoreQueryFilterConstraint(constraint);
-                acc.filter = acc.filter ? and(acc.filter, filter) : filter;
-                break;
-            }
-            case 'orderBy':
-                acc.nonFilter.push(orderBy(constraint.field, constraint.direction));
-                break;
-            case 'limit':
-                acc.nonFilter.push(limit(constraint.limit));
-                break;
-            case 'limitToLast':
-                acc.nonFilter.push(limitToLast(constraint.limit));
-                break;
-            case 'offset':
-                // https://github.com/firebase/firebase-js-sdk/issues/479
-                throw new Error('firestore-js-sdk does not support offset constraint');
-            case 'startAt': {
-                const { cursor } = constraint;
-                acc.nonFilter.push(startAt(...cursor));
-                break;
-            }
-            case 'startAfter': {
-                const { cursor } = constraint;
-                acc.nonFilter.push(startAfter(...cursor));
-                break;
-            }
-            case 'endAt': {
-                const { cursor } = constraint;
-                acc.nonFilter.push(endAt(...cursor));
-                break;
-            }
-            case 'endBefore': {
-                const { cursor } = constraint;
-                acc.nonFilter.push(endBefore(...cursor));
-                break;
-            }
-            default:
-                return assertNever(constraint);
-        }
-        return acc;
-    }, { nonFilter: [] });
-    let base;
-    switch (query.base.kind) {
-        case 'collection':
-            base = collection(db, collectionPath(query.base.collection, query.base.parentId));
-            break;
-        case 'collectionGroup':
-            base = collectionGroup(db, query.base.collection.name);
-            break;
-        case 'extends':
-            base = toFirestoreQuery(db, query.base.query);
-            break;
-        default:
-            base = assertNever(query.base);
-    }
-    return filter
-        ? filter instanceof QueryCompositeFilterConstraint
-            ? firestoreQuery(base, filter, ...nonFilter)
-            : firestoreQuery(base, filter, ...nonFilter)
-        : firestoreQuery(base, ...nonFilter);
-};
-const toFirestoreQueryFilterConstraint = (expr) => {
-    switch (expr.kind) {
-        case 'where':
-            return where(expr.fieldPath, expr.opStr, expr.value);
-        case 'or':
-            return or(...expr.filters.map(toFirestoreQueryFilterConstraint));
-        case 'and':
-            return and(...expr.filters.map(toFirestoreQueryFilterConstraint));
-        default:
-            return assertNever(expr);
-    }
+    };
+    return { fromFirestore, toFirestore, batchWriteOperation, encodeSchema };
 };

package/package.json

@@ -1,53 +1,58 @@
 {
   "name": "@firestore-repository/firebase-js-sdk",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A minimum and universal Firestore ORM (Repository Pattern) for TypeScript",
+  "keywords": [
+    "database",
+    "firebase",
+    "firebase-js-sdk",
+    "firestore",
+    "orm",
+    "repository"
+  ],
   "homepage": "https://github.com/ikenox/firestore-repository",
+  "license": "MIT",
+  "author": "Naoto Ikeno <ikenox@gmail.com>",
   "repository": {
     "type": "git",
     "url": "https://github.com/ikenox/firestore-repository.git"
   },
+  "files": [
+    "build",
+    "!**/*.tsbuildinfo"
+  ],
   "type": "module",
-  "dependencies": {
-    "@firebase/firestore": "^4.7.5",
-    "firestore-repository": "0.4.2"
-  },
-  "devDependencies": {
-    "@firebase/app": "^0.10.16"
-  },
   "exports": {
     ".": {
+      "@firestore-repository/source": "./src/index.ts",
       "import": {
         "types": "./build/esm/index.d.ts",
         "default": "./build/esm/index.js"
       }
     },
     "./*": {
+      "@firestore-repository/source": "./src/*.ts",
       "import": {
         "types": "./build/esm/*.d.ts",
         "default": "./build/esm/*.js"
       }
     }
   },
-  "files": [
-    "build",
-    "!**/*.tsbuildinfo"
-  ],
-  "keywords": [
-    "firestore",
-    "orm",
-    "database",
-    "repository",
-    "firebase",
-    "firebase-js-sdk"
-  ],
-  "author": "Naoto Ikeno <ikenox@gmail.com>",
-  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@firebase/firestore": "^4.12.0",
+    "zod": "^4.3.6",
+    "firestore-repository": "0.5.0"
+  },
+  "devDependencies": {
+    "@firebase/app": "^0.14.9"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
-    "typecheck": "tsc --noEmit",
     "build": "rm -rf build/ && tsc -b tsconfig.build.json"
   }
 }