npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@growsari/dbal

v2.1.0

Published

Database access layer

Downloads

446

Readme

Database Access Layer

Database Access Layer (DBAL) is a wrapper for DynamoDB Client. It provides the basic create, read, update and delete (CRUD) functionality and lets you group data into an entity.

Installation and Basic Usage

Install the Database Access Layer

npm i @growsari/dbal

Require or import the package as Entity

const Entity = require('@growsari/dbal')

Before we could use it, the project must have the following environment variables

| ENV | Description | Default Value | Other Value | |---|---|---|---| | IS_OFFLINE | Flag for local development | false | true | | DB_ADAPTER | Database to be used | dynamodb | ~ | | DYNAMODB_ENDPOINT | DynamoDB endpoint | http://localhost:8000 | ~ | | TABLE_NAME | DynamoDB table name | ~ | ~ |

Create a new class and extend Entity

'use strict'

const Entity = require('@growsari/dbal')

class User extends Entity {
  constructor() {
    super()
    this.attributes = {
      email: [
        'identifier'
      ],
      group_id: [
        'foreign'
      ]
    }
    this.sort = [
      {
        index: 'SortByCreatedAtIndex',
        field: 'created_at'
      },
      {
        index: 'SortByNameIndex',
        field: 'name'
      }
    ]
  }
}

module.exports = User

Require User entity and create item:

await User.create({
  name: 'John Doe',
  email: '[email protected]',
  group_id: 'BDS45HX47I9CT'
})

// {
//   "id": "659312a0-1b5c-11ea-a271-e732f3f9733b",
//   "created_at": "2019-12-10T14:50:24.330Z",
//   "updated_at": "2019-12-10T14:50:24.330Z",
//   "name": "John Doe",
//   "email": "[email protected]",
//   "group_id": "BDS45HX47I9CT"
// }

Read item by:

await User.getById('659312a0-1b5c-11ea-a271-e732f3f9733b')

Update item by:

await User.updateById('659312a0-1b5c-11ea-a271-e732f3f9733b', {
  name: 'John Doe II'
})

Delete item by:

await User.deleteById('659312a0-1b5c-11ea-a271-e732f3f9733b')

Update item by id based on condition options.

await User.updateByIdWithConditionOrFail('659312a0-1b5c-11ea-a271-e732f3f9733b', {name: 'John'}, ['AND', {name: {'!=': 'John Doe II'}}])

Entity Class Properties

These are the properties for configuring an entity

attributes

Lets you configure a special field in an item which implies uniqueness, foreign key and so on

| Value | Description | |---|---| | identifier | Creates a field with unique value within the entity | | foreign | Creates a foreign key (id in another microservice) | | namespace:field | Creates an identifier within a namespace (determined by field) |

Sample

this.attributes = {
  [attribute_name] : [
    'identifier',
    'foreign',
    'namespace:field'
  ]
}

sort

List of DynamoDB global secondary indexes (GSI) for data retrieval sorting

Entity Class Functions

These are the available functions for managing the data within an entity

async create(data)
async updateById(id, data)
async deleteById(id)
async bulkCreate(collection)
async bulkUpdate(collection)
async bulkDelete(collection)
async getById(id)
async getByIdOrFail(id)
async getByIdentifier(identifier, value)
async getByIdentifierWithinNamespace(namespace, identifier, value)
async getByIds(ids)
async getAll(first, after, sortBy, filterConditions)
async getAllByForeignKey(foreignKey, foreignValue, first, after, sortBy, filterConditions)
async search(query, rawQuery, fields, perPage, page, filters, sort)
async reindex()
async syncWithSearchEngine()

Sort By

A string which is composed of field name and order joined by |.

const sortBy = 'name|asc'
await Product.getAll(first, after, sortBy, filterConditions)

Filter Conditions

NOTE: To effeciently use the filter conditions in terms of DynamoDB RCU and WCU, I recommend using it with getAll() API. If you can't avoid using it with getAllByForeignKey() API please use filter with the defined sort fields.

These are the recognized compound expressions:

AND expression

Asserts that all of the subexpressions' conditions are satisfied.

const filterConditions = [
  'AND',
  { name: 'Coke' },
  { is_available: true },
  // more subexpressions
]
await Product.getAll(first, after, sortBy, filterConditions)

The above condition is equivalent to the following boolean expression:

name === 'COKE' && is_available === true && ...

OR expression

Asserts that at least one of the subexpressions' condtions are satisfied.

const filterConditions = [
  'OR',
  { name: 'Coke' },
  { brand: 'Coke' },
  // more subexpressions
]
await Product.getAll(first, after, sortBy, filterConditions)

The above condition is equivalent to the following boolean expression:

name === 'COKE' || brand === 'Coke' || ...

NOT expression

Asserts that at least one of the subexpressions' condtions are satisfied.

const filterConditions = [
  'AND',
  { name: 'Coke' },
  ['NOT', { is_available: true }]
]
await Product.getAll(first, after, sortBy, filterConditions)

The above condition is equivalent to the following boolean expression:

name === 'COKE' && is_available !== true

Equal expression

An object with one pair of key and value. The object's key represents the field name. The object's value is also an object and it represents the condition where the condition's key is the operation.

== operation creates a condtion which is true if the field is equal to the defined value.

const filterConditions = { name: { '==': 'Coke' } }
// can be simplified to:
// const filterConditions = { name: 'Coke' }
await Product.getAll(first, after, sortBy, filterConditions)

NotEqual expression

!= operation creates a condtion which is true if the field is not equal to the defined value.

const filterConditions = { is_available: { '!=': false } }
await Product.getAll(first, after, sortBy, filterConditions)

LessThan expression

< operation creates a condtion which is true if the field is less than to the defined value.

const filterConditions = { available: { '<': 10 } }
await Product.getAll(first, after, sortBy, filterConditions)

LessThanOrEqualTo expression

<= operation creates a condtion which is true if the field is less than or equal to the defined value.

const filterConditions = { available: { '<=': 10 } }
await Product.getAll(first, after, sortBy, filterConditions)

GreaterThan expression

> operation creates a condtion which is true if the field is greater than to the defined value.

const filterConditions = { available: { '>': 10 } }
await Product.getAll(first, after, sortBy, filterConditions)

GreaterThanOrEqualTo expression

>= operation creates a condtion which is true if the field is greater than or equal to the defined value.

const filterConditions = { available: { '>=': 10 } }
await Product.getAll(first, after, sortBy, filterConditions)

Between expression

between operation creates a condtion which is true if the field is between value[0] and value[1].

const filterConditions = {
  created_at: {
    'between': ['2020-06-01T00:00:00.000Z', '2020-06-15T00:00:00.000Z']
    }
  }
await Product.getAll(first, after, sortBy, filterConditions)

In expression

in operation creates a condtion which is true if the field is equal to an element the defined set of values.

const filterConditions = {
  tags: {
    'in': ['bottle', 'soda', 'promo', 'top_10', 'drink']
    }
  }
await Product.getAll(first, after, sortBy, filterConditions)

BeginsWith expression

NOTE! This operation will only work with sort fields

beginsWith operation creates a condtion which is true if the field is a string and begins with or has a prefix of value.

const filterConditions = { status: { 'beginsWith': 'active_' } }
await Product.getAll(first, after, sortBy, filterConditions)

Contains expression

NOTE! This operation will only work with sort fields

contains operation creates a condtion which is true if the field contains the defined value.

const filterConditions = { status: { 'contains': 'active' } }
await Product.getAll(first, after, sortBy, filterConditions)

Errors

| Code | Message | | --- | --- | | DBAL-001 | Database not supported | | DBAL-002 | Item not found for 'entity' entity | | DBAL-003 | Invalid pagination cursor | | DBAL-004 | Identifier 'field' must be unique | | DBAL-005 | Identifier 'field' within the namespace 'field' must be unique | | DBAL-006 | Sort key 'field' is not provided | | DBAL-007 | Invalid value for foreign key 'field' | | DBAL-008 | Duplicate entries in array as input is not allowed | | DBAL-009 | Invalid search engine setup |