@firestore-repository/firebase-js-sdk 0.1.0 → 0.2.1

package/README.md

@@ -15,78 +15,185 @@ A minimum and universal Firestore ORM (Repository Pattern) for TypeScript
 
 ## Installation
 
-### For backend (with `@google-cloud/firestore` or `firebase-admin`)
+### For backend (with [`@google-cloud/firestore`](https://www.npmjs.com/package/@google-cloud/firestore))
 
 ```shell
 npm install firestore-repository @firestore-repository/google-cloud-firestore 
 ````
 
-### For web frontend (with `firebase-js-sdk`)
+### For web frontend (with [`@firebase/firestore`](https://www.npmjs.com/package/@firebase/firestore))
 
 ```shell
 npm install firestore-repository @firestore-repository/firebase-js-sdk
 ```
 
-## Basic usage
+## Usage
+
+### Define a collection and its repository
 
 ```ts
-import { id, implicit, rootCollection } from 'firestore-repository/schema';
-import { condition as $, limit, query, where } from 'firestore-repository/query';
+import { mapTo, data, rootCollection } from 'firestore-repository/schema';
 
 // 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(),
-    }),
-  ),
+const users = rootCollection({
+  name: 'Users',
+  id: mapTo('userId'),
+  data: data<{
+    name: string;
+    profile: {
+      age: number;
+      gender?: 'male' | 'female';
+    };
+    tag: string[];
+  }>(),
 });
 
-// set
+const repository = new Repository(users, db);
+```
+
+### Basic operations for a single document
+
+```ts
+// Set a document
 await repository.set({
-  authorId: 'author1',
+  userId: 'user1',
   name: 'John Doe',
   profile: {
     age: 42,
     gender: 'male',
   },
   tag: ['new'],
-  registeredAt: new Date(),
 });
 
-// get
-const doc = await repository.get({ authorId: 'author1' });
-console.info(doc);
+// Get a document
+const doc = await repository.get({ userId: 'user1' });
+
+// Listen a document
+repository.getOnSnapshot({ userId: 'user1' }, (doc) => {
+  console.log(doc);
+});
+
+// Delete a document
+await repository.delete({ userId: 'user2' });
+```
+
+### Query
 
-// query snapshot
-const q1 = query(authors, where($('profile.age', '>=', 20)), limit(10));
-const docs = await repository.list(q1);
+```ts
+import { condition as $, limit, query, where } from 'firestore-repository/query';
+
+// Define a query
+const query1 = query(users, where($('profile.age', '>=', 20)), limit(10));
+
+// List documents
+const docs = await repository.list(query1);
 console.log(docs);
 
-// listen query
-const q2 = query(authors, where($('tag', 'array-contains', 'new')), limit(10));
-repository.listOnSnapshot(q2, (docs) => { console.log(docs); });
+// Listen documents
+repository.listOnSnapshot(query1, (docs) => {
+  console.log(docs);
+});
+
+// Aggregate
+const result = await repository.aggregate({
+  query: query1,
+  spec: {
+    avgAge: average('profile.age'),
+    sumAge: sum('profile.age'),
+    count: count(),
+  },
+});
+console.log(`avg:${result.avgAge} sum:${result.sumAge} count:${result.count}`);
 ```
+
+### Batch operations
+
+```ts
+// Get multiple documents (backend only)
+const users = await repository.batchGet([{ userId: 'user1' }, { userId: '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: [],
+  },
+]);
+
+// Delete multiple documents
+await repository.batchDelete([{ userId: 'user1' }, { userId: 'user2' }]);
+```
+
+#### Include multiple different operations in a batch
+
+```ts
+// For backend
+const batch = db.writeBatch();
+// For web frontend
+import { writeBatch } from '@firebase/firestore';
+const batch = writeBatch();
+
+await repository.set(
+    {
+      userId: 'user3',
+      name: 'Bob',
+      profile: { age: 20, gender: 'male' },
+      tag: [],
+    },
+    { tx: batch },
+);
+await repository.batchSet([ /* ... */ ], { tx: batch },
+);
+await repository.delete({ userId: 'user4' }, { tx: batch });
+await repository.batchDelete([{ userId: 'user5' }, { userId: 'user6' }], {
+  tx: batch,
+});
+
+await batch.commit();
+```
+
+### Transaction
+
+```ts
+// For web frontend
+import { runTransaction } from '@firebase/firestore';
+
+// Or, please use db.runTransaction for backend
+await runTransaction(async (tx) => {
+  // Get
+  const doc = await repository.get({ userId: 'user1' }, { tx });
+  
+  if (doc) {
+    doc.tag = [...doc.tag, 'new-tag'];
+    // Set
+    await repository.set(doc, { tx });
+    await repository.batchSet([
+      { ...doc, userId: 'user2' },
+      { ...doc, userId: 'user3' },
+    ]);
+  }
+
+  // Delete
+  await repository.delete({ userId: 'user4' }, { tx });
+  await repository.batchDelete([{ userId: 'user5' }, { userId: 'user6' }]);
+});
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firestore-repository/firebase-js-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A minimum and universal Firestore ORM (Repository Pattern) for TypeScript",
   "homepage": "https://github.com/ikenox/firestore-repository",
   "repository": {
@@ -10,7 +10,7 @@
   "type": "module",
   "dependencies": {
     "@firebase/firestore": "^4.7.5",
-    "firestore-repository": "0.1.0"
+    "firestore-repository": "0.2.1"
   },
   "devDependencies": {
     "@firebase/app": "^0.10.16"