@firestore-repository/google-cloud-firestore 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 type * as firestore from '@google-cloud/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.Firestore): z.ZodObject<z.ZodRawShape>;

package/build/esm/codec.js

@@ -0,0 +1,173 @@
+import { DocumentReference as FirestoreDocumentReference, FieldValue, GeoPoint as FirestoreGeoPoint, Timestamp as FirestoreTimestamp, VectorValue as FirestoreVectorValue, } from '@google-cloud/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':
+            return z.instanceof(Buffer).transform((b) => new Uint8Array(b));
+        case 'timestamp':
+            return z.instanceof(FirestoreTimestamp).transform((ts) => ts.toDate());
+        case 'geoPoint':
+            return z
+                .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) => Buffer.from(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) => FieldValue.vector(arr));
+        case 'int64':
+        case 'double':
+            return zodUnion([
+                // oxlint-disable-next-line typescript/no-explicit-any
+                z
+                    .custom((v) => isServerOp(v, 'increment'))
+                    .transform((v) => FieldValue.increment(v.amount)),
+                z.number(),
+            ]);
+        case 'timestamp':
+            return zodUnion([
+                // oxlint-disable-next-line typescript/no-explicit-any
+                z
+                    .custom((v) => isServerOp(v, 'serverTimestamp'))
+                    .transform(() => FieldValue.serverTimestamp()),
+                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
+            db.doc(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) => FieldValue.arrayRemove(...v.values)),
+                // oxlint-disable-next-line typescript/no-explicit-any
+                z
+                    .custom((v) => isServerOp(v, 'arrayUnion'))
+                    .transform((v) => FieldValue.arrayUnion(...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,59 +1,33 @@
-import { type DocumentReference, type DocumentSnapshot, Filter, type Firestore, type Query as FirestoreQuery, Transaction, type WriteBatch } from '@google-cloud/firestore';
-import type { AggregateSpec, Aggregated } from 'firestore-repository/aggregate';
-import type { WriteDocumentData } from 'firestore-repository/document';
-import type { FilterExpression, Offset, Query } from 'firestore-repository/query';
-import type * as repository from 'firestore-repository/repository';
-import { type CollectionSchema, type DocPathElement, type Id, type Model } from 'firestore-repository/schema';
+import type * as firestore from '@google-cloud/firestore';
+import { type AppModel, type Mapper, type PlainModel, type Repository, type RootCollectionPlainModel, type TransactionOption, type WriteTransactionOption } from 'firestore-repository/repository';
+import type { Collection, RootCollection, SubCollection } from 'firestore-repository/schema';
+/** Platform-specific environment types for Google Cloud Firestore */
 export type Env = {
-    transaction: Transaction;
-    writeBatch: WriteBatch;
-    query: FirestoreQuery;
+    transaction: firestore.Transaction;
+    writeBatch: firestore.WriteBatch;
+    query: firestore.Query;
 };
-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): repository.Unsubscribe;
-    list(query: Query<T>): Promise<Model<T>[]>;
-    listOnSnapshot(query: Query<T>, next: (snapshot: Model<T>[]) => void, error?: (error: Error) => void): repository.Unsubscribe;
-    aggregate<U extends AggregateSpec<T>>(query: Query<T>, spec: U): Promise<Aggregated<U>>;
+/** Extended repository interface for Google Cloud Firestore with additional methods (create, batchCreate, batchGet) */
+export interface GoogleCloudFirestoreRepository<T extends Collection, Model extends AppModel> extends Repository<T, Model, Env> {
     /**
-     * Create a new document
+     * Creates a new document
      * @throws If the document already exists
      */
-    create(doc: Model<T>, options?: WriteTransactionOption): Promise<void>;
-    set(doc: Model<T>, options?: WriteTransactionOption): Promise<void>;
-    delete(id: Id<T>, options?: WriteTransactionOption): Promise<void>;
+    create: (docToWrite: Model['write'], options?: WriteTransactionOption<Env>) => Promise<void>;
     /**
-     * Get documents by multiple ID
-     * example: [{id:1},{id:2},{id:5},{id:1}] -> [doc1,doc2,undefined,doc1]
+     * Creates multiple documents.
+     * The entire operation fails if any creation fails.
      */
-    batchGet(ids: Id<T>[], options?: TransactionOption): Promise<(Model<T> | undefined)[]>;
-    batchSet(docs: Model<T>[], options?: WriteTransactionOption): Promise<void>;
+    batchCreate: (docs: Model['write'][], options?: WriteTransactionOption<Env>) => Promise<void>;
     /**
-     * Create multiple documents
-     * The entire operation will fail if one creation fails
+     * Gets multiple documents by their IDs.
+     * @example [{id:1}, {id:2}, {id:5}, {id:1}] -> [doc1, doc2, undefined, doc1]
      */
-    batchCreate(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<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
-    protected fromFirestore(doc: DocumentSnapshot): Model<T> | undefined;
-    protected toFirestoreData(data: Model<T>): WriteDocumentData;
+    batchGet: (refs: Model['id'][], options?: TransactionOption<Env>) => Promise<(Model['read'] | undefined)[]>;
 }
-/**
- * Obtain document path elements from DocumentReference
- */
-export declare const docPathElements: (doc: DocumentReference) => [DocPathElement, ...DocPathElement[]];
-export declare const toFirestoreQuery: (db: Firestore, query: Query) => FirestoreQuery;
-export declare const toFirestoreFilter: (expr: FilterExpression) => Filter;
-/**
- * A query offset constraint
- */
-export declare const offset: (offset: number) => Offset;
+/** Creates a repository for a root collection using plain document types */
+export declare const rootCollectionRepository: <T extends RootCollection>(db: firestore.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.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.Firestore, collection: T, mapper: Mapper<T, Model>) => GoogleCloudFirestoreRepository<T, Model>;

package/build/esm/index.js

@@ -1,217 +1,236 @@
-import { AggregateField, Filter, Transaction, } from '@google-cloud/firestore';
-import { collectionPath, docPath, } from 'firestore-repository/schema';
+import { AggregateField, Filter, Transaction } from '@google-cloud/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)) : this.docRef(id).get());
-        return this.fromFirestore(doc);
-    }
-    getOnSnapshot(id, next, error) {
-        return this.docRef(id).onSnapshot((snapshot) => {
-            next(this.fromFirestore(snapshot));
-        }, error);
-    }
-    async list(query) {
-        const { docs } = await toFirestoreQuery(this.db, query).get();
-        return docs.map((doc) => 
-        // biome-ignore lint/style/noNonNullAssertion: Query result items should have data
-        this.fromFirestore(doc));
-    }
-    listOnSnapshot(query, next, error) {
-        return toFirestoreQuery(this.db, query).onSnapshot((snapshot) => {
-            // biome-ignore lint/style/noNonNullAssertion: Query result items should have data
-            next(snapshot.docs.map((doc) => this.fromFirestore(doc)));
-        }, error);
-    }
-    async aggregate(query, spec) {
-        const aggregateSpec = {};
-        for (const [k, v] of Object.entries(spec)) {
-            switch (v.kind) {
-                case 'count':
-                    aggregateSpec[k] = AggregateField.count();
-                    break;
-                case 'sum':
-                    aggregateSpec[k] = AggregateField.sum(v.path);
-                    break;
-                case 'average':
-                    aggregateSpec[k] = AggregateField.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) : docRef.get());
+            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 docRef.onSnapshot((snapshot) => {
+                const doc = fromFirestore.document(snapshot);
+                next(doc ? mapper.fromFirestore(doc) : undefined);
+            }, error);
+        },
+        list: async (query) => {
+            const firestoreQuery = toFirestore.query(query);
+            const { docs } = await firestoreQuery.get();
+            return docs.values().map((doc) => mapper.fromFirestore(fromFirestore.documentMustExist(doc)));
+        },
+        listOnSnapshot: (query, next, error) => {
+            const firestoreQuery = toFirestore.query(query);
+            return firestoreQuery.onSnapshot((snapshot) => {
+                next(snapshot.docs.map((doc) => mapper.fromFirestore(fromFirestore.documentMustExist(doc))));
+            }, error);
+        },
+        aggregate: async (query, spec) => {
+            const aggregateSpec = {};
+            for (const [k, v] of Object.entries(spec)) {
+                switch (v.kind) {
+                    case 'count':
+                        aggregateSpec[k] = AggregateField.count();
+                        break;
+                    case 'sum':
+                        aggregateSpec[k] = AggregateField.sum(v.path);
+                        break;
+                    case 'average':
+                        aggregateSpec[k] = AggregateField.average(v.path);
+                        break;
+                    default:
+                        return assertNever(v);
+                }
+            }
+            const firestoreQuery = toFirestore.query(query);
+            const res = await firestoreQuery.aggregate(aggregateSpec).get();
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- there is no way to infer correct type
+            return res.data();
+        },
+        create: async (model, options) => {
+            const docToWrite = mapper.toFirestore(model);
+            const docRef = toFirestore.docRef(docToWrite.ref);
+            const data = encode(docToWrite.data);
+            await (options?.tx ? options.tx.create(docRef, data) : docRef.create(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)
+                : docRef.set(data));
+        },
+        delete: async (ref, options) => {
+            const docRef = toFirestore.docRef(mapper.toDocRef(ref));
+            await (options?.tx ? options.tx.delete(docRef) : docRef.delete());
+        },
+        batchGet: async (refs, options) => {
+            if (refs.length === 0) {
+                return [];
+            }
+            const docRefs = refs.map((ref) => toFirestore.docRef(mapper.toDocRef(ref)));
+            const docs = await (options?.tx ? options.tx.getAll(...docRefs) : db.getAll(...docRefs));
+            return docs.map((doc) => {
+                const d = fromFirestore.document(doc);
+                return d ? mapper.fromFirestore(d) : undefined;
+            });
+        },
+        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, doc) => batch.set(toFirestore.docRef(doc.ref), doc.data),
+                transaction: (tx, doc) => tx.set(toFirestore.docRef(doc.ref), doc.data),
+            }, options);
+        },
+        batchCreate: 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, doc) => batch.create(toFirestore.docRef(doc.ref), doc.data),
+                transaction: (tx, doc) => tx.create(toFirestore.docRef(doc.ref), doc.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, collection) => {
+    const decodeSchema = buildDecodeSchema(collection.schema);
+    const encodeSchema = buildEncodeSchema(collection.schema, db);
+    const toFirestore = {
+        docRef: (ref) => db.doc(documentPath(collection, ref)),
+        query: (query) => {
+            let base;
+            if ('collection' in query.base) {
+                base = query.base.group
+                    ? db.collectionGroup(query.base.collection.name)
+                    : db.collection(collectionPath(query.base.collection, query.base.parent));
+            }
+            else if ('extends' in query.base) {
+                base = toFirestore.query(query.base.extends);
+            }
+            else {
+                return assertNever(query.base);
+            }
+            return (query.constraints?.reduce((q, constraint) => {
+                switch (constraint.kind) {
+                    case 'where':
+                        return q.where(toFirestore.filter(constraint.condition));
+                    case 'orderBy':
+                        return q.orderBy(constraint.field, constraint.direction);
+                    case 'limit':
+                        return q.limit(constraint.limit);
+                    case 'limitToLast':
+                        return q.limitToLast(constraint.limit);
+                    case 'offset':
+                        return q.offset(constraint.offset);
+                    case 'startAt': {
+                        const { cursor } = constraint;
+                        return q.startAt(...cursor);
+                    }
+                    case 'startAfter': {
+                        const { cursor } = constraint;
+                        return q.startAfter(...cursor);
+                    }
+                    case 'endAt': {
+                        const { cursor } = constraint;
+                        return q.endAt(...cursor);
+                    }
+                    case 'endBefore': {
+                        const { cursor } = constraint;
+                        return q.endBefore(...cursor);
+                    }
+                    default:
+                        return assertNever(constraint);
+                }
+            }, base) ?? base);
+        },
+        filter: (expr) => {
+            switch (expr.kind) {
+                case 'fieldValueCondition':
+                    return Filter.where(expr.fieldPath, expr.opStr, expr.value);
+                case 'and':
+                    return Filter.and(...expr.filters.map(toFirestore.filter));
+                case 'or':
+                    return Filter.or(...expr.filters.map(toFirestore.filter));
                 default:
-                    return assertNever(v);
+                    return assertNever(expr);
             }
-        }
-        const res = await toFirestoreQuery(this.db, query).aggregate(aggregateSpec).get();
-        return res.data();
-    }
-    /**
-     * Create a new document
-     * @throws If the document already exists
-     */
-    async create(doc, options) {
-        const data = this.toFirestoreData(doc);
-        await (options?.tx ? options.tx.create(this.docRef(doc), data) : this.docRef(doc).create(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)
-            : this.docRef(doc).set(data));
-    }
-    async delete(id, options) {
-        await (options?.tx ? options.tx.delete(this.docRef(id)) : this.docRef(id).delete());
-    }
-    /**
-     * Get documents by multiple ID
-     * example: [{id:1},{id:2},{id:5},{id:1}] -> [doc1,doc2,undefined,doc1]
-     */
-    async batchGet(ids, options) {
-        if (ids.length === 0) {
-            return [];
-        }
-        const docRefs = ids.map((id) => this.docRef(id));
-        const docs = await (options?.tx ? options.tx.getAll(...docRefs) : this.db.getAll(...docRefs));
-        return docs.map((doc) => this.fromFirestore(doc));
-    }
-    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);
-    }
-    /**
-     * Create multiple documents
-     * The entire operation will fail if one creation fails
-     */
-    async batchCreate(docs, options) {
-        await this.batchWriteOperation(docs, {
-            batch: (batch, doc) => batch.create(this.docRef(doc), this.toFirestoreData(doc)),
-            transaction: (tx, doc) => tx.create(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 = this.db.batch();
-            targets.forEach((target) => runner.batch(batch, target));
+            const batch = db.batch();
+            targets.forEach((target) => void runner.batch(batch, target));
             await batch.commit();
         }
-    }
-    docRef(id) {
-        return this.db.doc(docPath(this.collection, id));
-    }
-    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];
-};
-// OPTIMIZE: cache query
-export const toFirestoreQuery = (db, query) => {
-    let base;
-    switch (query.base.kind) {
-        case 'collection':
-            base = db.collection(collectionPath(query.base.collection, query.base.parentId));
-            break;
-        case 'collectionGroup':
-            base = db.collectionGroup(query.base.collection.name);
-            break;
-        case 'extends':
-            base = toFirestoreQuery(db, query.base.query);
-            break;
-        default:
-            base = assertNever(query.base);
-    }
-    return (query.constraints?.reduce((q, constraint) => {
-        switch (constraint.kind) {
-            case 'where':
-            case 'or':
-            case 'and':
-                return q.where(toFirestoreFilter(constraint));
-            case 'orderBy':
-                return q.orderBy(constraint.field, constraint.direction);
-            case 'limit':
-                return q.limit(constraint.limit);
-            case 'limitToLast':
-                return q.limitToLast(constraint.limit);
-            case 'offset':
-                return q.offset(constraint.offset);
-            case 'startAt': {
-                const { cursor } = constraint;
-                return q.startAt(...cursor);
-            }
-            case 'startAfter': {
-                const { cursor } = constraint;
-                return q.startAfter(...cursor);
-            }
-            case 'endAt': {
-                const { cursor } = constraint;
-                return q.endAt(...cursor);
-            }
-            case 'endBefore': {
-                const { cursor } = constraint;
-                return q.endBefore(...cursor);
-            }
-            default:
-                return assertNever(constraint);
-        }
-    }, base) ?? base);
-};
-export const toFirestoreFilter = (expr) => {
-    switch (expr.kind) {
-        case 'where':
-            return Filter.where(expr.fieldPath, expr.opStr, expr.value);
-        case 'and':
-            return Filter.and(...expr.filters.map(toFirestoreFilter));
-        case 'or':
-            return Filter.or(...expr.filters.map(toFirestoreFilter));
-        default:
-            return assertNever(expr);
-    }
+    };
+    return { fromFirestore, toFirestore, batchWriteOperation, encodeSchema };
 };
-/**
- * A query offset constraint
- */
-export const offset = (offset) => ({ kind: 'offset', offset });

package/build/esm/query.d.ts

@@ -0,0 +1,5 @@
+import type { Offset } from 'firestore-repository/query';
+/**
+ * Creates an offset constraint
+ */
+export declare const offset: (offset: number) => Offset;

package/build/esm/query.js

@@ -0,0 +1,4 @@
+/**
+ * Creates an offset constraint
+ */
+export const offset = (offset) => ({ kind: 'offset', offset });

package/package.json

@@ -1,51 +1,56 @@
 {
   "name": "@firestore-repository/google-cloud-firestore",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "A minimum and universal Firestore ORM (Repository Pattern) for TypeScript",
+  "keywords": [
+    "database",
+    "firebase",
+    "firebase-admin",
+    "firestore",
+    "google-cloud",
+    "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": {
-    "@google-cloud/firestore": "^7.10.0",
-    "firestore-repository": "0.4.2"
-  },
   "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-admin",
-    "google-cloud"
-  ],
-  "author": "Naoto Ikeno <ikenox@gmail.com>",
-  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@google-cloud/firestore": "^8.3.0",
+    "zod": "^4.3.6",
+    "firestore-repository": "0.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
-    "typecheck": "tsc --noEmit",
     "build": "rm -rf build/ && tsc -b tsconfig.build.json"
   }
 }