ActiveClass Methods

All ActiveClasses - that is, all ES6 classes that extend ActiveClass - come with some default methods, used for interacting with your Firebase Realtime Database.

import { ActiveClass, Schema } from 'fireactive'
const schema = {
name: Schema.string,
age: Schema.number
}
class Person extends ActiveClass(schema) {}
typeof Person.create // => 'function'
typeof Person.find // => 'function'
typeof Person.update // => 'function'
typeof Person.delete // => 'function'
Have you initialized?

To interact with your Firebase Realtime Database, you must first initialize a connection to your Firebase Realtime Database.

import { initialize } from 'fireactive'
import { Person } from './models/Person'
await Person.create({ name: 'Helen', age: 27 })
/*
* ActiveClassError: Failed to create Person.
* Could not connect to your Firebase database.
* This might be because you have not initialized your Firebase app.
* Try calling Fireactive.initialize
*/
initialize({
databaseURL: 'https://your-database.firebase.io'
})
await Person.create({ name: 'Helen', age: 27 }) // runs

Basic CRUD methods

create

Creates a new model from an object and saves it to the database.

Parameters:

  • props: an object of properties that conforms to the ActiveClass's Schema

Returns: Promise<ActiveDocument>, a promise that resolves into the ActiveDocument that has been created

Example

const helen = await Person.create({ name: 'Helen', age: 27 })
helen.name // => 'Helen'
helen.age // => 27
await Person.create({ name: 'Helen' })
// ActiveClassError: Could not create Person. The required property 'age' is missing
await Person.create({ name: 'Helen', age: '27' })
// ActiveClassError: Could not create Person. The property 'age' is of the wrong type

delete

Deletes all matching documents that partially match the passed in object.

Parameters:

  • props: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties)

Returns: Promise<number>, a promise that resolves with the count of matched documents deleted

Example

await Person.delete({})
// this will delete all entries in the database,
// since all properties of an empty object match
// any other entry
// let's create three Persons
await Person.create({ name: 'Harry', age: 40 })
await Person.create({ name: 'Hermione', age: 41 })
await Person.create({ name: 'Ron', age: 40 })
// delete all Persons with age of 40
await Person.delete({ age: 40 }) // => 2
// delete all Persons with a name of 'Harry'
// this should resolve to 0, since Harry has
// already been deleted by the above #delete
await Person.delete({ name: 'Harry' }) // => 0
// let's finish up by deleting our one remaining
// Person, Hermione (aged 41), with a delete all
await Person.delete({}) // => 1

deleteOne

Deletes the first document that partially matches the passed in object.

Parameters:

  • props: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties)

Returns: Promise<boolean>, a promise that resolves with whether or not a document was deleted

Example

// assuming we're starting with a fresh database
await Person.create({ name: 'Harry', age: 40 })
await Person.create({ name: 'Hermione', age: 41 })
await Person.delete({ name: 'Harry' }) // => true
await Person.delete({ name: 'Ron' }) // => false
await Person.delete({ age: 40 }) // => false (Harry is already deleted, so nothing to delete)

find

Instantiates an ActiveDocument for every document in the database that partially matches the passed in object.

Parameters:

  • props: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties)

Returns: Promise<ActiveDocument[]>, a promise that resolves with an array of ActiveDocuments

Example

// assuming we're starting with a fresh database
await Person.create({ name: 'Harry', age: 40 })
await Person.create({ name: 'Hermione', age: 41 })
await Person.create({ name: 'Ron', age: 40 })
const aged40 = await Person.find({ age: 40 })
aged40[0].name // => 'Harry'
aged40[1].name // => 'Ron'

findById

Instantiates an ActiveDocument for a document with the passed in id.

Parameters:

  • id: string

Returns: Promise<ActiveDocument | null>, a promise that resolves with the matching ActiveDocument if it exists, and null otherwise

Example

// assuming we're starting with a fresh database
const harry = await Person.create({ name: 'Harry', age: 40 })
const hermione = await Person.create({ name: 'Hermione', age: 41 })
harry._id // => '-at293f...'
hermione.getId() // => '-au492p...'
const matchOne = await Person.findById(harry._id)
const matchTwo = await Person.findById(hermione.getId())
matchOne.name // => 'Harry'
matchTwo.name // => 'Hermione'
const matchThree = await Person.findById('this is a really implausible id')
matchThree // => null

findByIdOrFail

Instantiates an ActiveDocument for a document with the passed in id, throwing an error if no document matches.

Parameters:

  • id: string

Returns: Promise<ActiveDocument>, a promise that resolves with the matching ActiveDocument, or otherwise throws an error

Example

// assuming we're starting with a fresh database
const harry = await Person.create({ name: 'Harry', age: 40 })
const hermione = await Person.create({ name: 'Hermione', age: 41 })
harry._id // => '-at293f...'
hermione.getId() // => '-au492p...'
const matchOne = await Person.findByIdOrFail(harry._id)
const matchTwo = await Person.findByIdOrFail(hermione.getId())
matchOne.name // => 'Harry'
matchTwo.name // => 'Hermione'
await Person.findByIdOrFail('this is a really implausible id')
/*
* Could not find a Person with that id.
* No Person with that id exists in the
* connected Firebase Realtime Database
*/

findOne

Instantiates an ActiveDocument for the first document in the database that partially matches the passed in object.

Parameters:

  • props: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties)

Returns: Promise<ActiveDocument | null>, a promise that resolves with the first matching ActiveDocument if any exists, and null otherwise

Example

// assuming we're starting with a fresh database
await Person.create({ name: 'Harry', age: 40 })
await Person.create({ name: 'Hermione', age: 41 })
await Person.create({ name: 'Ron', age: 40 })
const aged40 = await Person.findOne({ age: 40 })
aged40?.name // => 'Harry'
const aged50 = await Person.findOne({ age: 50 })
aged50 // => null

update

Updates documents that partially match a first object using the properties of a second object.

Parameters:

  • matchProps: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties), used to match documents to update
  • updateProps: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties), used to update all matched documents

Returns: Promise<ActiveDocument[]>, a promise that resolves with an array of updated ActiveDocuments

Example

// assuming we're starting with a fresh database
await Person.create({ name: 'Harry', age: 40 })
await Person.create({ name: 'Hermione', age: 41 })
await Person.create({ name: 'Ron', age: 40 })
const updatedPersons = await Person.update({ age: 40 }, { age: 50 })
aged50[0].name // => 'Harry'
aged50[0].age // => 50
aged50[1].name // => 'Ron'
aged50[1].age // => 50

updateOne

Updates the first document that partially matches an object using the properties of a second object.

Parameters:

  • matchProps: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties), used to find a document to update
  • updateProps: an object of properties that is consistent with the ActiveClass's Schema (but needn't include all properties), used to update the first matching document

Returns: Promise<ActiveDocument | null>, a promise that resolves with the updated ActiveDocument if it exists, or null otherwise

Example

// assuming we're starting with a fresh database
await Person.create({ name: 'Harry', age: 40 })
await Person.create({ name: 'Ron', age: 40 })
const updatedHarry = await Person.update({ age: 40 }, { age: 50 })
updatedHarry.name // => 'Harry'
updatedHarry.age // => 50

Other methods

ref

Returns a Firebase Realtime Database Reference for the ActiveClass 'table', or a specified child reference within it.

Parameters:

  • path (string, optional): if specified, retrieves the Reference following this path from the root of the ActiveClass's Reference

Returns: Reference, a Firebase Realtime Database Reference to the ActiveClass 'table', following the (optionally) specified child path

Example

Person.ref().toString()
// => 'https://your-database.firebase.io/People'
Person.ref('some/arbitrary/path').toString()
// => 'https://your-database.firebase.io/People/some/arbitrary/path'
Person.ref().child('chained').child('path').toString()
// => 'https://your-database.firebase.io/People/chained/path'
Edit this page