Quick start
Installation
npm install @merlinnot/firestore-extensions
TypeScript
This library defines multiple entry points, which is not yet supported by TypeScript. To work around this limitation, either:
Manually specify import paths (choose
cjsormjsin your path depending on which flavor you use).{ "compilerOptions": { "paths": { "@merlinnot/firestore-extensions/ids": [ "./node_modules/@merlinnot/firestore-extensions/lib/cjs/ids/index.js" ], "@merlinnot/firestore-extensions/subscriptions": [ "./node_modules/@merlinnot/firestore-extensions/lib/cjs/subscriptions/index.js" ] } } }Use only the main entry point.
import { ids, subscriptions } from '@merlinnot/firestore-extensions'`
Usage
Firestore ID to UUID converter
An extension provides methods to convert Firestore IDs to UUID v4 and back.
import { idToUuid, uuidToId } from '@merlinnot/firestore-extensions/ids';
const uuid = idToUuid('74NS2s2OIUH5KZRLFto4'); // ef8352da-cd8e-4214-87e4-a6512c5b68e0
const firestoreId = uuidToId('ef8352da-cd8e-4214-87e4-a6512c5b68e0'); // 74NS2s2OIUH5KZRLFto4
Subscriptions
An extension that maintains an in memory cache of a Firestore collection's data with a backing subscription ensuring updates as they occur in the database.
Supports pausing and resuming subscriptions, which can optimize database usage. These operations are handled automatically, based on attached event listeners and pending promises. If there are no attached event listeners and no pending promises, the subscription is paused.
Collections expose methods to learn about the current state and better optimize
usage, such as isActive and statistics.
Listen to data changes
import { Repository } from '@merlinnot/firestore-extensions/subscriptions';
const repository = new Repository({ projectId: 'my-project' });
const myCollectionSubscription = repository.makeCollectionSubscription(
{ structuredQuery: { from: [{ collectionId: 'my-collection' }] } },
(document) => document,
);
myCollectionSubscription.on('documentAdded', (document): void => {
// Added document data is available here.
});
Wait for data synchronization
import { Repository } from '@merlinnot/firestore-extensions/subscriptions';
const repository = new Repository({ projectId: 'my-project' });
const myCollectionSubscription = repository.makeCollectionSubscription(
{ structuredQuery: { from: [{ collectionId: 'my-collection' }] } },
(document) => document,
);
await myCollectionSubscription.synchronize();
// Contains current documents.
myCollectionSubscription.data();
Use filters
import { Repository } from '@merlinnot/firestore-extensions/subscriptions';
const repository = new Repository({ projectId: 'my-project' });
const myCollectionSubscription = repository.makeCollectionSubscription(
{
structuredQuery: {
from: [{ collectionId: 'my-collection' }],
where: {
fieldFilter: {
field: { fieldPath: 'my-field-path' },
op: 'EQUAL',
value: { booleanValue: true },
},
},
},
},
},
(document) => document,
);
Use projections (field masks)
import { Repository } from '@merlinnot/firestore-extensions/subscriptions';
const repository = new Repository({ projectId: 'my-project' });
const myCollectionSubscription = repository.makeCollectionSubscription(
{
structuredQuery: {
from: [{ collectionId: 'my-collection' }],
select: {
fields: [{ fieldPath: 'flat' }, { fieldPath: 'nested.field' }],
},
},
},
(document) => document,
);
Access statistics
import { Repository } from '@merlinnot/firestore-extensions/subscriptions';
const repository = new Repository({ projectId: 'my-project' });
const myCollectionSubscription = repository.makeCollectionSubscription(
{ structuredQuery: { from: [{ collectionId: 'my-collection' }] } },
(document) => document,
);
const statistics = myCollectionSubscription.statistics();
Access usage metrics
Firestore usage metrics are collected per subscription. Metrics are reset after
each call to the metrics() method. Returned object has to be logged to be used
as a source for log-based metrics.
import { Repository } from '@merlinnot/firestore-extensions/subscriptions';
const repository = new Repository({ projectId: 'my-project' });
const myCollectionSubscription = repository.makeCollectionSubscription(
{ structuredQuery: { from: [{ collectionId: 'my-collection' }] } },
(document) => document,
);
await myCollectionSubscription.synchronize();
const metrics = myCollectionSubscription.metrics();
logInfo(`Subscription synchronized.`, {
metrics: {
myCollectionSubscription: myCollectionSubscription.metrics(),
},
});
Canonical representation
For best performance, subscriptions default to use the native (API) representation of documents. This is a recommended way to interact with the library.
For convenience purposes, especially when migrating existing code, conversion helpers are provided.
import {
converters,
Repository,
types,
} from '@merlinnot/firestore-extensions/subscriptions';
const repository = new Repository({ projectId: 'my-project' });
const myCollectionSubscription = repository.makeCollectionSubscription(
{ structuredQuery: { from: [{ collectionId: 'my-collection' }] } },
(native: types.ToNativeDocument<MyType>): MyType =>
converters.toCanonical<MyType>({
mapValue: { fields: native.fields },
valueType: 'mapValue',
}),
);
Migrating from Firestore SDK
It is possible to convert Firestore SDK references to native query format with the use of private APIs. This is not recommended, however it can be useful to run locally when migrating.
import { Firestore } from '@google-cloud/firestore';
import { google } from '@google-cloud/firestore/types/protos/firestore_v1_proto_api';
import { Repository } from '@merlinnot/firestore-extensions/subscriptions';
const firestore = new Firestore();
const reference = (
firestore.collection('my-collection') as unknown as {
toProto: () => google.firestore.v1.IRunQueryRequest;
}
).toProto();
// Log the structured query.
console.log(reference.structuredQuery);
// Use directly (not recommended in production environments).
const repository = new Repository({ projectId: 'my-project' });
const subscription = repository.makeCollectionSubscription(
reference,
(document) => document,
);