Have ideas to improve npm?Join in the discussion! »

db-json

0.1.0 • Public • Published

db-json

db-json is a database completely in json. The database, queries and results are all json data.
It works both on client-side and server side.
The databse is structured, with tables composed of typed fields, with optional verifications (pattern, length, range)
The library works both on browser and node.

The json code of the dabase is human-readable, and can be easily edited at hand.
If any errors are made, they will be detected when instancing a new Database object with that json code.

Queries

Query form: [<operation name>, arg1, arg2, ...]

Operations

  • string getName() (Alias: name)
    Return the database name

  • void setName(string name) (Alias: name=)
    Change the name of the database (must be a non-empty string)

  • string getVersion() (Alias: v)
    Return the version of the database

  • void setVersion(string version) (Alias: v=)
    Change the name of the database (must be a non-empty string, no versionning convention to respect)

  • int getCreated() (Alias: ctime)
    Return the timestamp of creation of the dabase in ms

  • int getUpdated() (Alias: utime)
    Return the timestamp of the last modification of the database in ms

  • string[] listTables() (Alias: ls)
    Return the names of the tables in the database

  • void createTable(JSON json) (Alias: tmk)
    Add a new table to the database (See table representation for more info)

  • void removeTable(string name) (Alias: trm)
    Remove a table from the database

  • void renameTable(string oldName, string newName) (Alias: tmv)
    Change the name of a table in the database (the new name bust me a non-empty string)

  • void clearTables() (Alias: cl) Remove all entries from all the tables in the database

  • void removeTables() (Alias: rm*)
    Remove all the tables of the database

  • int tableGetCreated(string name) (Alias: tctime)
    Return the timestamp of creation of a table in ms
    name: table name

  • int tableGetUpdated(string name) (Alias: tutime)
    Return the timestamp of the last modification of a table in ms
    name: table name

  • Field[] tableGetFields(string name) (Alias: tfi)
    Return a copy of the raw fields object (See table representation for more info)
    name: table name

  • Entry insert(string name, Entry entry) (Alias: tput)
    Insert an entry into a table and returns the inserted entry (with all fields)
    name: table name
    entry: litteral object of the form {field: value, field:value, ...}

  • Entry[] select(string name, JSON filter, JSON orderer, string[] fields, int offset, int limit) (Alias: tget)
    Find and return entries from a table
    name: table name
    filter: select the entries (See filters for more info)
    orderer (default: null): order the select entries (See orderers for more info)
    fields (default: null): list of returned fields. If null, all fields are returned
    offset (default: 0): index of the first entry selected
    limit (default: -1): maximum number of selected entries. If -1, all entries are selected

  • Entry[] remove(string name, JSON filter) (Alias: trm)
    Find and remove entries from a table. Removed entries are returned.
    name: table name
    filter: select the entries

  • Entry[] update(string name, JSON filter), Entry modifs) (Alias: tset)
    Find and updates entries in a table. Updated entries are returned.
    name: table name filter: select the entries modifs: modifications applied to the selected entries. Litteral object of the form {field:value, field: value, ..}

  • void clear(string name) (Alias: tcl)
    Removes all entries in a table
    name: table name

Filters

  • Field Filter : [$, op1, args..s, op2, args..., ops...]
    Select entries that validates all the ops.
    Possible ops :
    =: value => test ===
    !=: value => test !===
    !: => test null
    !!: => test not null
    >: value => test >
    >=: value => test >=
    <: value => <
    <=: value => test <=
    len[: n => test length >= n (string only)
    len]: n => test length <= n (string only)
    len[]: l, h => test l <= length <= h (string only)
    reg: regex => regex.test() (char / string only)
    regf: regex, flags => regex.test() (char / string only)

  • And filter : [and, filter1, filter2, ...]
    Select entries validated by each filter

  • Or filter: [or, filter, filter2, ...]
    Select entries validated by any filter

  • "*"
    Select all entries

Orderers

An orderer is an array of string with the following pattern :
[field1, +/-, field2, ...]

field is the field to compare.
The prefix before the type can be a + to sort by ascending order, or a - to sort by descending order.
The type is the type of comparaison on the field:

  • val: compare by value using javascript operators
  • len: compare by length (string only)

Methods

var jdb = require("db-json");
var db = new jdb.Database(/*json content*/); //See database representation
 
var res = db.query(/*json query*/) //Executes the query and returns the result or throws an error
var res = db.queries(/*array of json queries*/) //Executes the queries and returns an array of results or throws an error
var res = db.squeries(...) //Same as before, but the database isn't edited at all if any error occurs.

JSON representation

Database representation

It's a litteral object with several properties :

  • name: Name of the database
    non-empty string
    required

  • version: Version of the database
    non-empty string (no versionning convention to respect)
    required

  • created: Timestamp of creation of the database in ms
    int
    default: current timestamp

  • updated: Timestamp of the last modification of the database in ms
    int
    default: current timestamp

  • tables: Tables in the database
    Array of json representation of tables
    default: []

Table representation

  • name: Name of the table
    non-empty string
    required

  • created: Timestamp of creation of the table in ms
    int
    default: current timestamp

  • updated: Timestamp of the last modification of the table in ms
    int
    default: current timestamp

  • fields: Fields of the table
    Non empty array of json representation of fields
    Required

  • entries: All entries in the table
    Array of objects {field: value, field: value, ...}
    default: []

Field representation

  • name: Name of the field
    Non-empty string (Two fields cannot have the same name)
    required

  • nullable: If the field can be null
    boolean
    default: false

  • unique: If two values cannot have the same value for this field
    boolean
    default: false

  • type: Type of the field
    string
    Possible types are: string, char, number, integer, boolean, id, or date (timestamp)
    required

  • generated: If the value is automatically generated when omitted
    boolean
    No test property can be used when generated is true (regex, minValue, ...) default: false

  • default: The default field value
    same type as the field
    Cannot be used with generated and unique fields

  • regex: Regex to test if a value is valid
    string available for types string, char, number and integer optional

  • regexFlags: the flags of the regex
    string
    can only be used with regex
    optional

  • minValue: value of the field must be >= minValue
    same type as the field
    available for integer and number
    optional

  • maxValue: value of the field must be <= maxValue
    same type as the field
    available for integer and number
    optional

  • minLength: minimum length of the value
    int >= 0
    available for string
    optional

  • maxLength: maximum length of the value
    int >= 0
    available for string
    optional

Install

npm i db-json

DownloadsWeekly Downloads

8

Version

0.1.0

License

none

Last publish

Collaborators

  • avatar