Need help with typesaurus?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

kossnocorp
279 Stars 25 Forks 169 Commits 34 Opened issues

Description

🦕 Type-safe TypeScript-first ODM for Firestore

Services available

!
?

Need anything else?

Contributors list

# 3,322
HTML
Firefox
phantom...
React
151 commits
# 197,162
iOS
Dart
Flutter
Go
4 commits
# 1,451
Rails
JavaScr...
idris
React N...
3 commits
# 120,292
Ruby
fluentd
Arduino
s3
2 commits
# 90,670
Scala
apache
Angular
cloud-f...
1 commit
# 248,048
pipelin...
iac
F#
.NET
1 commit
# 8,239
TypeScr...
React
vercel
nextjs
1 commit
# 756,214
JavaScr...
TypeScr...
1 commit
# 63,010
csv-par...
Clojure
HTML
Shell
1 commit
# 711,436
JavaScr...
TypeScr...
1 commit
# 334,011
nfc
iOS
HTML
Node.js
1 commit

🦕 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!


🔥🔥🔥 The project is sponsored by Backup Fire, backup service for Firebase 🔥🔥🔥

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.

Configuration

Typesaurus does not require additional configuration, however when using with ESM-enabled bundler, 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, initialize Firebase normally.

In the web environment (see Firebase docs):

import * as firebase from 'firebase/app'
import 'firebase/firestore'

firebase.initializeApp({ // Project configuration })

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('users')

// Add a document to a collection with auto-generated id add(users, { name: 'Sasha' }) //=> Promise>

// Set or overwrite a document with given id set(users, '42', { name: 'Sasha' }) //=> Promise>

// Update a document with given id update(users, '42', { name: 'Sasha' }) //=> Promise

Read data

import { collection, get, all, query, where } from 'typesaurus'

type User = { name: string } const users = collection('users')

// Get a document with given id get(users, '42') //=> Promise | null>

// Get all documents in a collection all(users) //=> Promise[]>

// Query collection query(users, [where('name', '===', 'Sasha')]) //=> Promise[]>

Remove data

import { collection, remove } from 'typesaurus'

type User = { name: string } const users = collection('users')

// Remove a document with given id remove(users, '42') //=> Promise

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

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.

Changelog

See the changelog.

License

MIT © Sasha Koss

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.