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.
- 🌐 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.
- 🗄️ Repository Pattern: A simple and consistent way to access Firestore data.

Installation

$3

``shell
npm install firestore-repository @firestore-repository/google-cloud-firestore
``

$3

`shell
npm install firestore-repository @firestore-repository/firebase-js-sdk
`

Usage

$3

`ts
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();

// For web frontend
import { getFirestore } from '@firebase/firestore';
import { Repository } 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[];
}>(),
});

const repository = new Repository(users, db);
`

$3

`ts
// Set a document
await repository.set({
userId: 'user1',
name: 'John Doe',
profile: {
age: 42,
gender: 'male',
},
tag: ['new'],
});

// 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' });
`

$3

`ts
import { condition as $, limit, query } from 'firestore-repository/query';

// Define a query
const q = query(
users,
$('profile.age', '>=', 20),
$('profile.gender', '==', 'male'),
limit(10),
);

// List documents
const docs = await repository.list(q);
console.log(docs);

// Listen documents
repository.listOnSnapshot(q, (docs) => {
console.log(docs);
});

// Aggregate
const result = await repository.aggregate(q, {
avgAge: average('profile.age'),
sumAge: sum('profile.age'),
count: count(),
});
console.log(avg:${result.avgAge} sum:${result.sumAge} count:${result.count});
`

$3

`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();
`

$3

`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' },
], { tx });
}

// Delete
await repository.delete({ userId: 'user4' }, { tx });
await repository.batchDelete([{ userId: 'user5' }, { userId: 'user6' }], { tx });
});
``