A collection of Firestore utilities.
npm install @merlinnot/firestore-extensions
This library defines multiple entry points, which is not yet supported by TypeScript. To work around this limitation, either:
-
Manually specify import paths (choose
cjs
ormjs
in 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'`
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
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
.
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.
});
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();
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,
);
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,
);
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();
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(),
},
});
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',
}),
);
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,
);
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See usage notes on how to consume this package in your project.
Minimal requirements to set up the project:
- Node.js v16, installation instructions can be found on the official website, a recommended installation option is to use Node Version Manager. It can be installed in a few commands.
- A package manager npm. All instructions in the documentation will follow the npm syntax.
- Optionally a Git client.
Start by cloning the repository:
git clone [email protected]:merlinnot/firestore-extensions.git
In case you don't have a git client, you can get the latest version directly by using this link and extracting the downloaded archive.
Go the the right directory and install dependencies:
cd ./firestore-extensions
npm install
That's it! You can now go to the next step.
This project uses Prettier to automate formatting. All supported files are being reformatted in a pre-commit hook. You can also use one of the two scripts to validate and optionally fix all of the files:
npm run format
npm run format:fix
This project uses ESLint to enable static analysis. TypeScript files are linted using a custom configuration. You can use one of the following scripts to validate and optionally fix all of the files:
npm run lint
npm run lint:fix
Publishing is handled in an automated way and must not be performed manually.
Each commit to the master branch is automatically deployed to the NPM registry
with a version specified in package.json
. All other commits are published as
pre-releases.
See CONTRIBUTING.md.
This project adheres to Semantic Versioning v2.