@firestore-repository/google-cloud-firestore 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Naoto Ikeno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+[![npm version](https://badge.fury.io/js/firestore-repository.svg)](https://badge.fury.io/js/firestore-repository)
+[![CI](https://github.com/ikenox/firestore-repository/actions/workflows/check-and-test.yaml/badge.svg)](https://github.com/ikenox/firestore-repository/actions/workflows/check-and-test.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# firestore-repository
+
+A minimum and universal Firestore ORM (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.
+- 🌐 **Unopinionated**: This library does not introduce any additional concepts, and respects an interface 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.
+- 🗄️ **Repository Pattern**: A simple and consistent way to access Firestore data.
+
+## Installation
+
+### For backend (with `@google-cloud/firestore` or `firebase-admin`)
+
+```shell
+npm install firestore-repository @firestore-repository/google-cloud-firestore 
+````
+
+### For web frontend (with `firebase-js-sdk`)
+
+```shell
+npm install firestore-repository @firestore-repository/firebase-js-sdk
+```
+
+## Basic usage
+
+```ts
+import { id, implicit, rootCollection } from 'firestore-repository/schema';
+import { condition as $, limit, query, where } from 'firestore-repository/query';
+
+// For backend
+import { Firestore } from '@google-cloud/firestore';
+import { Repository } from '@firestore-repository/google-cloud-firestore';
+const db = new Firestore();
+const repository = new Repository(authors, db);
+
+// For web frontend
+import { getFirestore } from '@firebase/firestore';
+import { Repository } from '@firestore-repository/firebase-js-sdk';
+const db = getFirestore();
+const repository = new Repository(authors, db);
+
+// define a collection
+const authors = rootCollection({
+  name: 'Authors',
+  id: id('authorId'),
+  data: implicit(
+    (data: {
+      name: string;
+      profile: {
+        age: number;
+        gender?: 'male' | 'female';
+      };
+      tag: string[];
+      registeredAt: Timestamp;
+    }) => ({
+      ...data,
+      registeredAt: data.registeredAt.toDate(),
+    }),
+  ),
+});
+
+// set
+await repository.set({
+  authorId: 'author1',
+  name: 'John Doe',
+  profile: {
+    age: 42,
+    gender: 'male',
+  },
+  tag: ['new'],
+  registeredAt: new Date(),
+});
+
+// get
+const doc = await repository.get({ authorId: 'author1' });
+console.info(doc);
+
+// query snapshot
+const q1 = query(authors, where($('profile.age', '>=', 20)), limit(10));
+const docs = await repository.list(q1);
+console.log(docs);
+
+// listen query
+const q2 = query(authors, where($('tag', 'array-contains', 'new')), limit(10));
+repository.listOnSnapshot(q2, (docs) => { console.log(docs); });
+```

package/build/esm/index.d.ts

@@ -0,0 +1,59 @@
+import { type DocumentReference, type DocumentSnapshot, Filter, type Firestore, type Query as FirestoreQuery, Transaction, type WriteBatch } from '@google-cloud/firestore';
+import type { AggregateQuery, 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';
+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): 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 AggregateQuery<T>>(aggregate: U): Promise<Aggregated<U>>;
+    /**
+     * Create 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>;
+    /**
+     * Get documents by multiple ID
+     * example: [{id:1},{id:2},{id:5},{id:1}] -> [doc1,doc2,undefined,doc1]
+     */
+    batchGet(ids: Id<T>[], options?: TransactionOption): Promise<(Model<T> | undefined)[]>;
+    batchSet(docs: Model<T>[], options?: WriteTransactionOption): Promise<void>;
+    /**
+     * Create multiple documents
+     * The entire operation will fail if one creation fails
+     */
+    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;
+}
+/**
+ * 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;

package/build/esm/index.js

@@ -0,0 +1,215 @@
+import { AggregateField, Filter, Transaction, } from '@google-cloud/firestore';
+import { collectionPath, docPath, } from 'firestore-repository/schema';
+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(aggregate) {
+        const aggregateSpec = {};
+        for (const [k, v] of Object.entries(aggregate.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 res = await toFirestoreQuery(this.db, aggregate.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 tx = options?.tx;
+        if (tx) {
+            if (tx instanceof Transaction) {
+                targets.forEach((target) => runner.transaction(tx, target));
+            }
+            else {
+                targets.forEach((target) => runner.batch(tx, target));
+            }
+        }
+        else {
+            const batch = this.db.batch();
+            targets.forEach((target) => 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':
+                return q.where(toFirestoreFilter(constraint.filter));
+            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);
+    }
+};
+/**
+ * A query offset constraint
+ */
+export const offset = (offset) => ({ kind: 'offset', offset });

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@firestore-repository/google-cloud-firestore",
+  "version": "0.1.0",
+  "description": "A minimum and universal Firestore ORM (Repository Pattern) for TypeScript",
+  "homepage": "https://github.com/ikenox/firestore-repository",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ikenox/firestore-repository.git"
+  },
+  "type": "module",
+  "dependencies": {
+    "@google-cloud/firestore": "^7.10.0",
+    "firestore-repository": "0.1.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./build/esm/index.d.ts",
+        "default": "./build/esm/index.js"
+      }
+    },
+    "./*": {
+      "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"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf build/ && tsc -b tsconfig.build.json"
+  }
+}