Flamev0.7.0

Create an Access that can be used to screen Objects using a role-basd mask.

Parameters

mask (Object)

An Object that mirrors defaults on the target Model, where the value of each field is an Array of roles allowed to access the given field.

Returns

value (Access)

Returns the new Access.

Example

Access = require 'flame-odm/access'

access = new Access({

  name: [ 'user', 'self' ]

  age:  [ 'self' ]

})

List the fields allowed by an Access, given one or more roles.

Parameters

roles (Array)

The roles used to determine allowed fields.

Returns

value (Array)

Returns an array of allowed fields.

Example

Access = require 'flame-odm/access'

access = new Access({

  name: [ 'user', 'self' ]

  age:  [ 'self' ]

})

fields = access.fields([ 'self' ])

# => [ 'name', 'age' ]

Creates a copy of obj including only role-allowed fields.

Parameters

obj (Object)

The object to be screened.

roles (Array)

The roles used to determine allowed fields.

Returns

value (Object)

Returns the new, screened object.

Example

Access = require 'flame-odm/access'

access = new Access({

  name: [ 'user', 'self' ]

  age:  [ 'self' ]

})

screened = access.screen({ name: 'Emma', age: 28 }, [ 'user' ])

# => { name: 'Emma' }

Create an Adapter which can be used as a mixin when creating a Model or Record.

Parameters

service_account (Function|Object|String) Optional

When service_account is 'firebase-function' or 'google-cloud' the service account will be retrieved automatically from the respective platform.

When service_account is 'process-env' Flame will look for the service account as a JSON string stored at process.env.FB_SERVICE_ACCOUNT.

When service_account is an Object, Flame assumes the Object is the service account.

When service_account is a Function, Flame will invoke service_account(), which should return a Promise that resolves to a service account Object.

When unspecified, Flame will default to using 'firebase-function'.

Note: If you are using Flame in a Firebase Function, you do not need to define or use an Adapter. Flame will automatically use the default Adapter and connect as needed.

app_name (String) Optional

Create multiple Adapters with different app_names to connect to multiple Firestore databases.

If service_account is: 'google-cloud', 'firebase-function', or null then app_name is ignored.

Returns

value (Adapter)

Returns the new Adapter.

Example

Adapter = require 'flame-odm/adapter'

service_account = {

  type: "service_account"

  project_id: "..."

  # ...

}

adapter = new Adapter(service_account)

Connect to Firestore.

Returns

value (Promise → Nothing)

Returns a Promise that resolves empty.

Example

Adapter = require 'flame-odm/adapter'

service_account = {

  type: "service_account"

  project_id: "..."

  # ...

}

adapter = new Adapter(service_account)

await adapter.connect()

Executes a set of database operations as a transaction.

The argument fn is a Function invoked with one argument: T (Transaction) which may be passed to any read or write methods carried out within the context of Adatper.transact.

Parameters

fn (Function)

The Function that wraps the read/write operations to be handled as a transaction.

Returns

value (Promise → Any)

Returns the return value of fn.

Example

Adapter  = require 'flame-odm/adapter'

Alphabet = require '◆/lib/flame/models/alphabet.coffee'

Query    = require 'flame-odm/query'

alphabet_query = new Query([

  [ 'eq', 'letter', 'a' ]

])

ok = await Adapter.transact((T) ->

  letter_a = await Alphabet.find(alphabet_query, T)

  if !letter_a

    leter_a2 = Alphabet.create({ letter: 'a' })

    saved = await letter_a2.save(T)

  return (!!letter_a || saved)

)

console.log(ok)

# => true

Create a Config which is used to store and pass configuration options to other constructors.

Parameters

obj (Object)

An Object of { field: value, ...} entries allowed by the constructor or method that will recieve Config.

Returns

value (Config)

Returns the new Config.

Example

Config = require 'flame-odm/config'

Model  = require 'flame-odm/model'

rand   = require '@stablelib/random'

config = new Config({

  id_field: 'id'

})

User = new Model('User', {

  id: -> 'user-' + rand.randomString(32)

}, config)

# The id field of each User model will now be used as its Document ID Firestore.

Create a Model. A Model defines the structure of the documents to be stored in Firestore.

Parameters

type (String)

This Model's type.

By default, type will be the collection in Firestore for documents saved by Records created from this Model. However, the collection can be overriden with a custom Config.

defaults (Object)

The structure of your Model defined by an Object of {field: value, ...} entries, where value can be any of: Array, Boolean, Number, Null, Object, String, or Function.

When value is a Function, it will be invoked with two arguments: type and values where type is the Model's type and values is a clone of defaults.

mixins... (Adapter|Config|Serializer|Validator) Optional

For each additional argument passed to the Model's constructor of (Type), the Model's corresponding default (Type) will be overridden.

Returns

value (Model)

Returns the new Model.

Example

Model = require 'flame-odm/model'

User = new Model('User', {

  id:   null

  name: null

})

Count the number of documents in a collection that satisfy query.

Parameters

query Optional

The Query that determines what to count. If query is not specified, all documents in the collection are counted.

Returns

value (Promise → Integer|Null)

Returns a Promise that resolves to the Integer number of documents in the collection that satisfy query, or Null if Model.count() fails.

Example

map   = require 'lodash/map'

split = require 'lodash/split'

Model = require 'flame-odm/model'

Query = require 'flame-odm/query'

Alphabet = new Model('Alphabet', {

  letter: null

})

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

query = new Query([

  [ 'gt',  'letter', 'b' ]

  [ 'lte', 'letter', 'f' ]

])

cdef = await Alphabet.count(query)

# => 4

Create a new Record.

Parameters

values (Object)

An Object of the values for Record. values will be merged with the Model's defaults.

mixins... (Adapter|Config|Serializer|Validator) Optional

For each additional argument passed to Model.create() of (Type), the created Record's corresponding default (Type) will be overridden.

Returns

value (Record)

Returns the new Record.

Example

Model = require 'flame-odm/model'

Alphabet = new Model('Alphabet', {

  letter: null

})

record = Alphabet.create({ letter: 'a' })

# => (Record)

Extend a Model.

Parameters

type (String)

This Model's type.

By default type will be the collection used in Firestore when saving a Record. However, the collection can be overriden with a custom Config.

defaults (Object)

The structure of your Model defined by an Object of {field: value, ...} entries, where value can be any of: Array, Boolean, Number, Null, Object, String, or Function. defaults will be merged with the extended Model's defaults.

When value is a Function, it will be invoked with two arguments: type and values where type is the Model's type and values is a clone of defaults.

mixins... (Adapter|Config|Serializer|Validator) Optional

For each additional argument passed to the Model's constructor of (Type), the Model's corresponding default (Type) will be overridden.

Returns

value (Model)

Returns the new Model.

Example

Model = require 'flame-odm/model'

Vehicle = new Model('Vehicle', {

  weight: null

})

Car = Vehicle.extend('Car', {

  wheels: 4

})

Retrieve the first document in a collection that satisfies query.

Parameters

query Optional

The Query that determines what documents are elliglbe. If query is not specified, the first document in the collection is returned

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Model.find() within the context of Adapter.transact().

Returns

value (Promise → Object|Null)

Returns the return the document Object, or Null if there is no match.

Example

map   = require 'lodash/map'

split = require 'lodash/split'

Model = require 'flame-odm/model'

Query = require 'flame-odm/query'

Alphabet = new Model('Alphabet', {

  letter: null

})

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

query = new Query([

  [ 'gt',  'letter', 'b' ]

])

c = await Alphabet.find(query)

# => { letter: 'c' }

Retrieve all documents in a collection that satisfy query.

Parameters

query Optional

The Query that determines what documents will be included. If query is not specified, all documents in the collection will be included.

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Model.findAll() within the context of Adapter.transact().

Returns

value (Promise → Array|Null)

Returns an array of matching document Objects, or Null if there are no matches.

Example

map   = require 'lodash/map'

split = require 'lodash/split'

Model = require 'flame-odm/model'

Query = require 'flame-odm/query'

Alphabet = new Model('Alphabet', {

  letter: null

})

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

query = new Query([

  [ 'eq-any', 'letter', [ 'a', 'e', 'i', 'o', 'u', 'y' ]]

])

vowels = await Alphabet.findAll(query)

# => [{ letter: 'a' }, { letter: 'e' }, { letter: 'i' }, { letter: 'o' }, { letter: 'u' }, { letter: 'y' }]

Create a partial Record using an existing document ID.

Parameters

id (String)

The the document ID

values (Object)

An Object of the values for Record. values will be merged with the Model's defaults.

mixins... (Adapter|Config|Serializer|Validator) Optional

For each additional argument passed to Model.fragment() of (Type), the created Record's corresponding default (Type) will be overridden.

Returns

value (Record)

Returns the new Record.

Example

Model = require 'flame-odm/model'

rand  = require '@stablelib/random'

User = new Model('User', {

  id:   -> 'user-' + rand.randomString(4)

  name: null

  bday: null

})

record = User.create({

  name: 'Ella'

})

await record.save()

record_v2 = User.fragment(record.obj().id, {

  bday: '2020-02-02'

})

await record_v2.update([ 'bday' ])

# => true

Retrieve a single document from a collection.

Parameters

id (String)

The document ID.

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Model.get() within the context of Adapter.transact().

Returns

value (Promise → Object|Null)

Returns the Record Object, or Null if there is no document with the given id.

Example

map   = require 'lodash/map'

split = require 'lodash/split'

Config = require 'flame-odm/config'

Model  = require 'flame-odm/model'

Query  = require 'flame-odm/query'

C = new Config({

  id_field: 'letter'

})

Alphabet = new Model('Alphabet', {

  letter: null

}, C)

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

a = await Alphabet.get('a')

# => { letter: 'a' }

Retreive multiple documents from a collection.

Parameters

ids (Array<String>)

The document IDs of the documents to retrieve.

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Model.getAll() within the context of Adapter.transact().

Returns

value (Promise → Array<Object>|Null)

Returns an Array of the document Objects, or Null if any of the provided ids do not correspond to a document in Firestore.

Example

map   = require 'lodash/map'

split = require 'lodash/split'

Config = require 'flame-odm/config'

Model  = require 'flame-odm/model'

Query  = require 'flame-odm/query'

C = new Config({

  id_field: 'letter'

})

Alphabet = new Model('Alphabet', {

  letter: null

}, C)

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

a = await Alphabet.getAll([ 'a', 't', 'z' ])

# => [{ letter: 'a' }, { letter: 't' }, { letter: 'z' }]

Retrieve a page of documents from a collection.

Parameters

pager (Pager)

The Pager to use.

cursor (Object) Optional

An Object that defines the current cursor and it's position.

When unspecified or Null, cursor defaults to the first document in the collection that satisfies pager.

fields (Array<String>) Optional

The fields that should be included in the returned documents.

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Model.getAll() within the context of Adapter.transact().

Returns

value (Promise → Object|Null)

Returns a page Object, or Null if there are no documents that satisfy the supplied pager and cursor.

Example

map   = require 'lodash/map'

split = require 'lodash/split'

Config = require 'flame-odm/config'

Model  = require 'flame-odm/model'

Pager  = require 'flame-odm/pager'

Alphabet = new Model('Alphabet', {

  letter: null

})

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

pager = (new Pager [

  [ 'order-by', 'letter', 'asc' ]

], { size: 4 })

cursor = {

  obj: { letter: 'd' }

  position: 'page-start'

}

page = await Alphabet.page(pager, cursor)

# => {

#   counts: { total: 26, before: 3, page: 4, after: 19 },

#   collection: {

#     first: { letter: 'a', },

#     last: { letter: 'z', }

#   },

#   page: {

#     first: { letter: 'd'},

#     items: [

#       { letter: 'd', },

#       { letter: 'e', },

#       { letter: 'f', },

#       { letter: 'g', }

#     ],

#     last: { letter: 'g', }

#   },

#   cursors: {

#     previous: {

#       obj: { letter: 'c', },

#       position: 'page-end'

#     },

#     current: {

#       obj: { letter: 'd' },

#       position: 'page-start'

#     },

#     next: {

#       obj: { letter: 'h' },

#       position: 'page-start'

#     }

#   }

# }

Traverse all documents in a collection that satisify the constraints of pager. fn is invoked once with each record as its first argument.

Parameters

pager (Pager)

The Pager to use. When Pager is initalized with { size: 1 }, each invocation of fn will be in serial. Otherwise, fn will be invoked on all records in a given page in parallel.

Use size as a rate-limiter to ensure Model.traverse() doesn't exceed read or write limits.

fn (Function)

An Object that defines the current cursor and it's position.

When unspecified or Null, the cursor defaults to the first document in the collection that satisfies pager.

fields (Array<String>) Optional

The fields that should be included in the returned documents.

Returns

value (Promise → Object|Null)

Returns a page Object, or Null if there are no documents that satisfy the supplied pager.

Example

map    = require 'lodash/map'

repeat = require 'lodash/repeat'

split  = require 'lodash/split'

Config = require 'flame-odm/config'

Model  = require 'flame-odm/model'

Pager  = require 'flame-odm/pager'

Alphabet = new Model('Alphabet', {

  letter: null

})

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

pager = (new Pager [

  [ 'order-by', 'letter', 'asc' ]

], { size: 6 })

await Alphabet.traverse(pager, ((record) ->

  await Alphabet.create({ letter: repeat(record.letter, 2) }).save()

  return

))

# The 'alphabet' collection will now have records with with { letter: 'a' }, { letter: 'aa' }, { letter: 'b' }, { letter: 'bb' }, ...

Creates a Pager that can be used to in combination with Model.page() to retrieve cursor-based pages from a collection in Firestore.

Parameters

q (Array<Array>)

An Array of constraint tuples that defines what documents are included when retrieving a page using this Pager in combination with Model.page(). Each constraint tuple is represented using an Array in the form [constraint, field, value(s)].

The allowed constraint tuples are:

Constraint Tuples
'eq'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'eq-any'	field (String)	values (Array<Array|Boolean|Number|Null|Object|String>)
'gt'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'gte'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'includes'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'includes-any'	field (String)	values (Array<Array|Boolean|Number|Null|Object|String>)
'lt'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'lte'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'not-eq'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'not-eq-any'	field (String)	values (Array<Array|Boolean|Number|Null|Object|String>)
'order-by'	field (String)	values (Array<String>)

opts (Object)

An Object of the form { size: value (Integer) } where value is the number of documents per page.

Returns

value (Pager)

Returns the new Pager.

Example

Pager  = require 'flame-odm/pager'

pager = new Pager([

  [ 'gt',       'letter', 'f' ]

  [ 'order-by', 'letter', 'asc' ]

], { size: 6 })

Create a Query that can be used with Model.count(), Model.find(), and Model.findAll() to count and retrieve documents from Firestore.

Parameters

q (Array<Array>)

An Array of constraint tuples that defines what documents are included when using this Query in combination with Model.count(), Model.find(), or Model.findAll(). Each constraint tuple is represented using an Array in the form [constraint, field, value(s)] or [constraint, value(s)].

The allowed constraint tuples are:

Constraint Tuples
'eq'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'eq-any'	field (String)	values (Array<Array|Boolean|Number|Null|Object|String>)
'gt'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'gte'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'includes'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'includes-any'	field (String)	values (Array<Array|Boolean|Number|Null|Object|String>)
'limit'	value (Integer)
'lt'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'lte'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'not-eq'	field (String)	value  (Array|Boolean|Number|Null|Object|String)
'not-eq-any'	field (String)	values (Array<Array|Boolean|Number|Null|Object|String>)
'order-by'	field (String)	values (Array<String>)
'start-at'	value (Array<Strings>)

Returns

value (Query)

Returns the new Query.

Example

Query  = require 'flame-odm/query'

query = new Query([

  [ 'gte',    'letter', 'm' ]

  [ 'eq-any', 'letter', [ 'a', 'e', 'i', 'o', 'u', 'y', ]]

])

Permanently removes the document represented by this Record from Firestore.

Parameters

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Record.destroy() within the context of Adapter.transact().

Returns

value (Promise → Boolean|Null)

Returns the true if successful, otherwise false.

Example

map    = require 'lodash/map'

split  = require 'lodash/split'

Config = require 'flame-odm/model'

Model  = require 'flame-odm/config'

config = new Config({

  id_field: 'letter'

})

Alphabet = new Model('Alphabet', {

  letter: null

})

letters = split('abcdefghijklmnopqrstuvwxyz')

await all(map(letters, (letter) -> Alphabet.create({ letter }).save()))

record = Model.fragment('a')

await record.destroy()

# => true

Produces an Object of the Record's fields that are not valid.

Parameters

fields (Array) Optional

An Array of fields to validate. When unspecified or Null, all fields are validated.

Returns

value (Object)

An Object in the form of { field: value (Boolean), ... } where each field is a field in the Record, and each value is true if the field fails this Record's corresponding Validator function.

Example

Model     = require 'flame-odm/config'

Validator = require 'flame-odm/validator'

validator = new Validator({

  letter: (value, object) -> /^[a-z]+$/.test(value)

})

Alphabet = new Model('Alphabet', {

  letter: null

}, validator)

record = Model.create({ letter: 10 })

errors = record.errors()

# => { letter: true }

Produces the Object representation of this Record's fields and values.

Returns

value (Object)

Returns the Record's as an Object.

Example

Model = require 'flame-odm/model'

Alphabet = new Model('Alphabet', {

  letter: null

})

record = Record.create({ letter: 'z' })

record.obj()

# => { letter: 'z' }

Check if all fields of the Record are valid.

Parameters

fields (Array<String>)

The fields to check, if unspecified or Null all fields are checked.

Returns

value (Boolean)

Returns true if all fields are valid, otherwise false.

Example

Model     = require 'flame-odm/config'

Validator = require 'flame-odm/validator'

validator = new Validator({

  letter: (value, object) -> /^[a-z]+$/.test(value)

})

Alphabet = new Model('Alphabet', {

  letter: null

}, validator)

record = Model.create({ letter: 10 })

ok = record.ok()

# => false

Save this Record to Firestore as a document.

Parameters

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Record.save() within the context of Adapter.transact().

Returns

value (Promise → Boolean)

Returns true when successful, otherwise false.

Example

Model = require 'flame-odm/model'

Alphabet = new Model('Alphabet', {

  letter: null

})

record = Record.create({ letter: 'm' })

await record.save()

# => true

Update this Record's corresponding document in Firestore.

Parameters

fields (Object)

The fields to update in this Record's document in Firestore.

T (Transaction) Optional

A Firestore transaction Object. Use when invoking Record.update() within the context of Adapter.transact().

Returns

value (Promise → Boolean)

Returns true when successful, otherwise false.

Example

Model = require 'flame-odm/model'

rand  = require '@stablelib/random'

User = new Model('User', {

  id:   -> 'user-' + rand.randomString(4)

  name: null

  bday: null

})

record = User.create({

  name: 'Billy'

})

await record.save()

record_v2 = User.fragment(record.obj().id, {

  bday: '2011-11-02'

})

await record_v2.update([ 'bday' ])

# => true

Create a Serializer that can be used to transform Record Object format into a Firestore document Object format, and vice-a-versa.

Parameters

opts (Object)

opts is an Object with three allowed fields: prefixes, separator, and fmt.

prefixes is an Array of prefixes that can be used to create 2-level Records that will be automatically flattened by Flame as they are written to Firestore, and documents retrieved from Firestore will automatically be expanded back into 2-level Objects.

separator is used as field concatenator between the prefixes and the 2nd-level field names for 2-level Records stored in Firestore.

fmt normalizes the casing for field names when in Firestore, and as Objects. Snake, kebabk, pascal, and camel cases are supported.

Returns

value (Serializer)

Returns the new Serializer.

Example

Serializer = require 'flame-odm/serializer'

serializer = new Serializer({

  prefixes: [ 'ext', 'index', 'meta', 'rel', 'val' ]

  separator: '-'

  fmt: {

    field: {

      db:    'kebab'

      plain: 'snake'

    }

  }

})

Create a Validator that can be used to check if a Record's fields are valid.

Parameters

v (Object)

An Object of the form { field: validator } that mirrors the structure of the target Model, where the validator of each field is a Function.

Each validator is invoked with two arguments, value and object. value is the Record's corresponding field value, and object is the full Object representation of the Record.

Each validator should evaluate true if valid, false otherwise.

Returns

value (Validator)

Returns the new Validator.

Example

Model     = require 'flame-odm/model'

Validator = require 'flame-odm/validator'

validator = new Validator({

  letter: (value, object) -> /^[a-z]+$/.test(value)

})

Alphabet = new Model('Alphabet', {

  letter: null

}, validator)