🦕 Typesaurus
TypeScript-first ODM for Firestore.
Looking for React adaptor? Check Typesaurus React!
Why?
- Designed with TypeScript's type inference in mind
- Universal code (browser & Node.js)
- Functional API
- Maximum type-safety
- Autocomplete
- Say goodbye to
any
! - Say goodbye to exceptions!
Installation
The library is available as an npm package. To install Typesaurus run:
npm install typesaurus --save
# Or using Yarn:
yarn add typesaurus
Note that Typesaurus requires firebase
package to work in the web environment and firebase-admin
to work in Node.js. These packages aren't listed as dependencies,
so that they won't install automatically along with the Typesaurus package.
Additionally, when using with ESM-enabled bundler (like webpack), you'll need to install lazyfire
that enables asynchronous importing of Firebase modules in the web environment:
npm install lazyfire --save
# Or using Yarn:
yarn add lazyfire
Configuration
Typesaurus does not require additional configuration, however when using with ESM-enabled bundler (like webpack), you should transpile node_modules
. TypeScript preserves many modern languages features when it compiles to ESM code. So if you have to support older browsers, use Babel to process the dependencies code.
Get started
Initialization
To start working with Typesaurus, you'll need to initialize Firebase.
Web environment
In the web environment when using ESM-enabled bundler (like webpack), use Lazy Fire to configure the Firebase application:
import { configureApp } from 'lazyfire'
configureApp({
// Firebase app configuration
})
Legacy web environment
In the web environment with ESM-disabled (see Firebase docs):
import * as firebase from 'firebase/app'
import 'firebase/firestore'
firebase.initializeApp({
// Firebase app configuration
})
Node.js environment
In Node.js (see Firebase docs):
import * as admin from 'firebase-admin'
admin.initializeApp()
Add data
import { collection, add, set, update } from 'typesaurus'
type User = { name: string }
const users = collection<User>('users')
// Add a document to a collection with auto-generated id
add(users, { name: 'Sasha' })
//=> Promise<Doc<User>>
// Set or overwrite a document with given id
set(users, '42', { name: 'Sasha' })
//=> Promise<Doc<User>>
// Update a document with given id
update(users, '42', { name: 'Sasha' })
//=> Promise<void>
Read data
import { collection, get, all, query, where } from 'typesaurus'
type User = { name: string }
const users = collection<User>('users')
// Get a document with given id
get(users, '42')
//=> Promise<Doc<User> | null>
// Get all documents in a collection
all(users)
//=> Promise<Doc<User>[]>
// Query collection
query(users, [where('name', '===', 'Sasha')])
//=> Promise<Doc<User>[]>
Remove data
import { collection, remove } from 'typesaurus'
type User = { name: string }
const users = collection<User>('users')
// Remove a document with given id
remove(users, '42')
//=> Promise<void>
API Reference
Query data
-
all
- Returns all documents in a collection. -
get
- Retrieves a document from a collection. -
getMany
- Retrieves multiple documents from a collection. -
query
- Queries passed collection using query objects (order
,where
,limit
).
Query helpers:
-
order
- Creates order query object with given field, ordering method and pagination cursors. -
limit
- Creates a limit query object. It's used to paginate queries. -
where
- Creates where query with array-contains filter operation. -
docId
- Constant-helper that allows to sort or order by the document ID.
Pagination helpers:
-
endAt
- Ends the query results on the given value. -
endBefore
- Ends the query results before the given value. -
startAfter
- Start the query results after the given value. -
startAt
- Start the query results on the given value.
Real-time:
-
onAll
- Subscribes to all documents in a collection. -
onGet
- Subscribes to the given document. -
onGetMany
- Subscribes to multiple documents from a collection. -
onQuery
- Subscribes to a collection query built using query objects (order
,where
,limit
).
Operations
-
add
- Adds a new document with a random id to a collection. -
set
- Sets a document to the given data. -
update
- Updates a document. -
upset
- Updates or sets a document. -
remove
- Removes a document.
Operation helpers:
-
field
- Creates a field object. It's used to update nested maps. -
value
- Creates a value object. It's used to update map values using special operations i.e.arrayRemove
,serverDate
,increment
, etc.
Constructors
-
collection
- Creates a collection object. -
subcollection
- Creates a subcollection function which accepts parent document reference and returns the subcollection transformed into a collection object. -
group
- Creates a collection group object. -
doc
- Creates a document object. -
ref
- Creates reference object to a document in given collection with given id.
Transactions and batched writes
-
batch
- Inits batched writes. -
transaction
- Performs transaction.
Testing
Functions to be used with @firebase/rules-unit-testing
:
-
injectTestingAdaptor
- Injects the testing adaptor and sets the given app to be used for Firestore operations. -
injectApp
- Sets the given app to be used for Firestore operations.
Settings
You may change Typesaurus settings with the typesaurusSettings(settings: Partial<TypesaurusSettings>): void
function.
The settings are:
undefinedToNull
: boolean
If Typesaurus shall convert any undefined
values in write operations to null
.
If false
, the undefined
behavior is handled by Firestore ignoreUndefinedProperties
setting. You can change it via firebase.firestore().settings({ignoreUndefinedProperties: boolean})
, in Node env.
Default: true
Changelog
See the changelog.