@firestore-repository/firebase-js-sdk 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,40 @@
+import { type DocumentReference, type DocumentSnapshot, type Firestore, type Query as FirestoreQuery, Transaction, type WriteBatch } from '@firebase/firestore';
+import type { AggregateQuery, 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';
+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 AggregateQuery<T>>(aggregate: 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;

package/build/esm/index.js

@@ -0,0 +1,212 @@
+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 { 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(aggregate) {
+        const aggregateSpec = {};
+        for (const [k, v] of Object.entries(aggregate.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 res = await getAggregateFromServer(toFirestoreQuery(this.db, aggregate.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 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 = writeBatch(this.db);
+            targets.forEach((target) => 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': {
+                const filter = toFirestoreQueryFilterConstraint(constraint.filter);
+                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);
+    }
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@firestore-repository/firebase-js-sdk",
+  "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": {
+    "@firebase/firestore": "^4.7.5",
+    "firestore-repository": "0.1.0"
+  },
+  "devDependencies": {
+    "@firebase/app": "^0.10.16"
+  },
+  "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-js-sdk"
+  ],
+  "author": "Naoto Ikeno <ikenox@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf build/ && tsc -b tsconfig.build.json"
+  }
+}