clay-lump

Lump of clay-db

Table of Contents

• Installation
• Usage
• Advanced Usage
  • Applying Policies
  • Listening to events
• API Guide
• License
• Links

Installation

$ npm install clay-lump --save

Usage

Three steps to use use clay lump.

• Create lump instance with clayLump(config).
• Access resource with lump.resource(resourceName)
• Use resource methods like resource.create() or resource.list() to handle data

'use strict'

const clayLump = require('clay-lump')
const {SqliteDriver} = require('clay-driver-sqlite')

async function exampleClayLump () {
  let lump01 = clayLump('lump01', {
    driver: new SqliteDriver('var/example-lump01.db')
  })

  {
    const Dog = lump01.resource('Dog@default')

    let john = await Dog.create({name: 'john', type: 'Saint Bernard', age: 3})
    console.log(john) // -> { id: '1a6358694adb4aa89c15f94be50d5b78', name: 'john', type: 'Saint Bernard', age: 3 }

    let dogs = await Dog.list({
      filter: {type: 'Saint Bernard'},
      page: {number: 1, size: 25}
    })
  }

  let lump02 = clayLump('lump02')
  {
    const Dog = lump02.resource('Dog@foo')
    let bess = await Dog.create({name: 'bess', type: 'Chihuahua', age: 1})

    const Dog2 = lump02.resource('Dog@bar')
    let bess2 = await Dog.create({name: 'bess2', type: 'Chihuahua', age: 1})
  }

  // Sync lumps01 to lump02
  await lump02.sync(lump01) // Both lumps will be updated
  {
    const Dog = lump02.resource('Dog')
    let [john] = (await Dog.list({filter: {name: 'john'}})).entities // Synced from lump01
    console.log(john) // -> { id: '1a6358694adb4aa89c15f94be50d5b78', name: 'john', type: 'Saint Bernard', age: 3 }
  }
}

exampleClayLump().catch((err) => console.error(err))

For more detail, see API Guide

Advanced Usage

Applying Policies

To restrict data structure of resources, you can pass ClayPolicy to policies options of clay lump constructor.

'use strict'

const clayLump = require('clay-lump')
const {STRING, DATE} = clayLump.Types

async function exampleClayLump () {
  let lump02 = clayLump('lump02')

  // Define policy on resource
  lump02.resource('User').policy({
    username: {
      type: STRING,
      required: true
    },
    birthday: {
      type: DATE
    },
    rank: {
      type: STRING,
      oneOf: ['GOLD', 'SLIVER', 'BRONZE']
    }
  })

  // Use the resource with policy
  {
    const User = lump02.resource('User')
    let user01 = await User.create({username: 'foo', rank: '__INVALID_RANK__'}) // -> Throws policy error
    /* ... */
  }

  // Use policy as validator
  {
    const User = lump02.resource('User')
    let policy = User.getPolicy()
    policy.validateToThrow({foo: 'bar'})
  }
}

exampleClayLump().catch((err) => console.error(err))

Listening to events

Resources are instances of EventEmitter and fires events. See ResourceEvents to know what you can listen.

'use strict'

const clayLump = require('clay-lump')
const {ResourceEvents} = clayLump

// Events fired from resource
const {
  ENTITY_CREATE,
  ENTITY_CREATE_BULK,
  ENTITY_UPDATE,
  ENTITY_UPDATE_BULK,
  ENTITY_DESTROY,
  ENTITY_DESTROY_BULK,
  ENTITY_DROP
} = ResourceEvents

async function exampleClayLump () {
  let lump02 = clayLump('lump02')

  // Add listener on resource
  lump02.resource('User')
    .on(ENTITY_CREATE, ({created}) => { /* ... */ })
    .on(ENTITY_CREATE_BULK, ({created}) => { /* ... */ })
    .on(ENTITY_UPDATE, ({id, updated}) => { /* ... */ })
    .on(ENTITY_UPDATE_BULK, ({ids, updated}) => { /* ... */ })
    .on(ENTITY_DESTROY, ({id, destroyed}) => { /* ... */ })
    .on(ENTITY_DESTROY_BULK, ({ids, destroyed}) => { /* ... */ })
    .on(ENTITY_DROP, ({dropped}) => { /* ... */ })

  // Use the resource with policy
  {
    const User = lump02.resource('User')
    console.log(User.getPolicy()) // -> Returns policy info

    let user01 = await User.create({username: 'foo', rank: '__INVALID_RANK__'}) // -> Throws policy error
    /* ... */
  }
}

exampleClayLump().catch((err) => console.error(err))

API Guide

• clay-lump@4.4.31
  • create()
  • isLump(instance)
  • ClayLump
  • DriverMixed
  • MergeMixed
  • PolicyMixed
  • RefMixed
  • ResourceMixed

License

This software is released under the Apache-2.0 License.

Links

• ClayDB
• Realglobe, Inc.