• Description
• Installation
• HTTP methods
• Client
• Server
• Query builidng
  • General
  • Request filters
  • Response modifiers
  • Insert and update
  • Run from terminal
• Seeders
  • Setup
  • Usage
  • Example

Description

Lightweight and fast local json database manager

• supports all CRUD operations
• comprehensive querying syntax
• built-in seeder to quickly populate your database up to thousands of records
• a command line tool to run dabase queries from terminal
• 'persist' or 'no_persist' mode if you want to block write operations
• base package comes with no dependencies
• easily extensible, dedicated database modules are under way

Installation

    npm install @db-essentials/base --save

    or

    yarn add @db-essentials/base

HTTP methods

| Method | Http Verb | Description | | ----------- | --------- | ---------------------------------------------------------- | | find | GET | Returns all matching records | | find_one | GET | Returns the first matching record | | count | GET | Returns the number of matching records | | delete_one | DELETE | Deletes matching record filters | | delete_many | DELETE | Deletes multiple records, returns an array of deleted id's | | save_one | POST | Saves a record | | save_many | POST | Saves multiple records | | update_one | PUT | Updates the first matching record | | update_many | PUT | Updates all matching records |

Client

Example with fetch API

// with query parameters

await fetch("somedomain/find/items?_only=price,name,updated_at&_limit=10");

// with body

await fetch("somdedomain/update_one/items", {
  method: "PUT",
  body: JSON.stringify({
    _id: 12,
    _set: {
      price: 169.99,
    },
  }),
});

Server

// Basic setup with express.js

const app = require("express")();

const { Connection, Query } = require("@db-essentials/base");

app.get("/", async (req, res) => {
  const conn = await Connection.create({
    database: "public/db",
    label: "default",
    mode: "no_persist",
  });

  const query = await Query.create({
    connection: conn,
    url: "find/test_data",
    body: null,
  });

  const data = await query.run();

  res.status(200).send(data);
});

app.listen(4000, () => console.log("listening on port 4000"));

This is just a most basic example. The key parts however are:

Connection

| Argument | Accepts | Description | | -------- | ------------------- | ----------------------------------------------------------------------------------------------------- | | label | any unique string | An identifier for this particular connection, since you can have many of them running simultaneously. | | database | string | A valid path to your local json files directory. | | mode | persist, no_persist | It tells whether you want to persist write / delete / update operations or not. |

Query

| Argument | Accepts | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | | connection | object | An instance of active connection. | | url | string | A url that includes a valid http method (see above), name of the collection you wish to address and optional search query. | | body | string | A stringified body object when performing write / update operations. |

Query builidng

General

Query operators always start with underscore

// _exists, _type, _lte, etc...

so they can later be separated and parsed. In general regular field names should not start with underscores.

Nested properties can be accessed using dot notation:

const q = "?field1.nested.value._gte=10";

Array values should be comma separated. Example of selecting fields to return:

const q = "?_only=field1,field2,field3,nested.field1,nested.nested.field3"; // etc...

Some operators precede the field name and some come after:

const q = "?_nor.field=value"

// vs

const q = "?field.someNestedField._in=1,2,3,4"

/*

Search params use a regular '?' and '&' syntax. Some operators allow multiple conditions:

const q =
  "somedomain/find/items?_nor.itemName._in=name1,name2,name3&_nor.someValue._gte=100&optonalField._exists=true";

Same example but using request body object

const body = JSON.stringify({
  _nor: {
    itemName: {
      _in: ["name1", "name2", "name3"],
    },
    someValue: {
      _gte: 100,
    },
  },
  optionalField: {
    _exists: true,
  },
});

Request filters

These are treated as reserved keywords and you should avoid using them as database field names. Filters can access deep nested fields as well

field.nested.nested._exists = true;

Any record has an autogenerated _id field, which holds a numeric value. It'a special field, every other underscore starting fields area treated as operators.

| Param | Usage | Description | | ------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | _gt | field._gt=[any] | Greater than target | | _gte | field._gte=[any] | Equal or greater than target | | _lt | field._lt=[any] | Lower than target | | _lte | field._lte=[any] | Equal or lower than target | | _in | field._in=[array] | Equal to target or one of comma separated target values | | _not_in | field._not_in=[array] | Different than target or comma separated target values | | _equals | field._equals=[any] | Equal to target | | _not_equal | field._not_equal=[any] | Different than target | | _exists | field._exists=[boolean] | Checks if the value exists, pass true or false | | _type | field._type=[string] | Checks if the value is of given type: string, null, date, ...etc.You can also pass an array of types to evaluate, field._type=null,date | | _regex | field._regex=[string] | Evaluates value based on a regex expression | | _array_match | field._array_match=[any] | Checks if an array field contains the requested value | | _array_all | field._array_all=[array] | Checks if an array field contains all requested values | | _array_size | field._array_size=[number] | Checks if the array field is of specified size | | _and | _and.field=[any] | Filters out records that don't match all conditions : _and.name=someName&_and.value._gt=4 | | _or | _or.field=[any] | Returns records that match at least one condition : _or.fieldName=value&_or.orOtherField._gt=4 | | _nor | _nor.field=[any] | Filters out records that match the conditions: _nor.name=book&_nor.price._gt=19.99 |

Response modifiers

These are treated as reserved keywords and you should avoid using them as database table field names.

| Param | Usage | Description | | ------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | _only | _only=[array] | Specifies which fields should be included with the response. Accepts comma separated fields or a single field. Use either this or '_except' | | _except | _except=[array] | Specifies which fields not to icnlude with the response. Accepts comma separated fields or a single field. Use either this or '_only' | | _skip | _skip=[number] | How many records to skip. Accepts an integer value. | | _limit | _limit=[number] | Caps results number to a specified integer value. | | _sort | _sort.field=[number] | Sorts data by a specified field, should be either 1 (ascending order) or -1 (descending order). | | _slice | _slice=[array] | Gets a range of records. | | _array_slice | _array_slice.field=[num] | Specifies how many values to return from an array field. |

Insert and update

Operators to be used inside a body object of POST or PUT http requests

| Param | Usage | Description | | ------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | _set | _set.field=[any] | Updateds a value to the target value, should be used with http PUT call | | _inc | _inc.field=[number] | Increments a number value by specified positive or negative value. | | _cdate | _cdate.field._type=[string] | Updates a field to a current date or timestamp, _cdate.updated_at._type=date or _cdate.updated_at._type=timestamp. | | _save | _save=[array] | Specifies an array of records to be inserted into database |

Run from terminal

Run a database query using a built-in command line interface

Include this line in you package json scripts

The path argument point to you local files

{
  "scripts": {
    "query": "db-essentials-query path=./PATH/TO/LOCAL_DATABASE mode=persist"
  }
}

A query must be wrapped in quotes

    npm run

    // or

    yarn query "find/users?_only=name,age&_limit=15" true

    // pass true at the end if you want to see the result as a string, otherwise you can leave it

Seeders

You can use a built-in command line script to seed your local database.

Setup

Add a line to your package.json scripts as shown in the example below.

• first argument is the path to a directory in your app where seeders are stored.
• second argument is the path which points to your local database files directory.
• the third argument tells whether it should persist the data, by default it does

{
  "scripts": {
    "seed": "db-essentials-seed path/to/seeders path/to/database_files persist"
  }
}

Usage

    // table name is required

    /*
      count number is optional, defaults to 1
      if no number is specified it will run a single seed
      if you want to seed a fixed number of data at once, an array of objects, usually that's what you need
    */

    npm run seed users 77

    npm run seed categories // creates database records from an array of objects returned from the seeder

    or

    yarn seed users 77

Example

Seeder is just a function that returns an object or array of objects structured after you database model schema. Since it would bring an unncessary overhead the package has no built-in fake data generator. There are devoted packages like https://github.com/faker-js/faker you can try.

// products.js

// your seeder logic

const getRandomNumber = (min, max) =>
  Math.floor(Math.random() * (max - min + 1) + min);

const getRandomArrayElement = (arr) =>
  arr[Math.floor(Math.random() * arr.length)];

const items = [
  "Bag",
  "Battery Pack",
  "Camera",
  "Charger",
  "Cooker",
  "Electric Car",
  "Flash Drive",
  "Fridge",
  "Frying Pan",
  "Headphones",
  "Keyboard",
  "Microphone",
  "Monitor",
  "Mouse",
  "Multitool",
  "Notebok",
  "Phone",
  "Power Bank",
  "Printer",
  "Soundsystem",
  "Speakers",
  "SSD",
  "Tablet",
  "Telescope",
  "TV",
  "Vacuum Cleaner",
  "Wallet",
  "Watch",
];

const adjectives = [
  "Aluminium",
  "Cheap",
  "Elite",
  "Flexible",
  "Gaming",
  "Hybrid",
  "Mega",
  "Mini",
  "Mobile",
  "Modern",
  "Pro",
  "Slim",
  "Smart",
  "Ultra",
  "Universal",
  "Waterproof",
  "Wireless",
];

const brands = [
  "Apple",
  "Dell",
  "Essentials",
  "Hitachi",
  "HP",
  "Huawei",
  "IBM",
  "Ilyama",
  "LG",
  "Microsoft",
  "Nintendo",
  "Philips",
  "Samsung",
  "Sony",
];

// function that returns a seeder object

module.exports = async () => {
  // as you might await smth here

  return {
    name: `${getRandomArrayElement(brands)} ${getRandomArrayElement(
      adjectives
    )} ${getRandomArrayElement(items)}`,
    published: getRandomArrayElement([true, false]),
    created: new Date().toISOString(),
    in_stock: getRandomNumber(100, 0),
    sold: getRandomNumber(1001, 0),
    price: (getRandomNumber(2001, 1) + getRandomNumber(2001, 1)).toFixed(2),
  };
};

Returning an array of objects in a single seed

// fetch data from external source or create your own

module.exports = () => {
  return [
    {
      name: "LG Modern Headphones",
      in_stock: 45,
    },
    {
      name: "Samsung Ultra SSD",
      in_stock: 125,
    },
    {
      name: "Apple Slim Wallet",
      in_stock: 15,
    },
    // ...etc
  ];
};