InlineDB is a portable JSON and file system based database. It is designed to work with node applications that require a simple database to store and maintain data. For example, one could store settings for an app, store user profiles and high scores for a game, an electron app that want to cache various data objects, or hook up with expressjs to serve a todo app.

Explore the API to find more about InlineDB. Since it is a "lite" database, it has some limitations. View the limitations section for more information.

Contents

Getting Started
- Installation
- Basic usage
API
- Database
- Table
Examples
Limitations
Contributing
License

Getting Started

Installation

Install using npm:

npm install inlinedb

Basic Usage

Up and running in no time:

import InlindeDB from 'inlinedb';

// create a new database
const idbName = 'my-database';
const idb = new InlindeDB(idbName);

// and create a new table
const tableName = 'my-table';
idb.createTable(tableName);

View API for more options

API

InlineDB has following APIs:

Database
Table

Database

Database is the main interface in creating and manage a database for an application.

Methods:

Create database
Create table
List tables
Drop table
Drop database

Create database

A database can be created using the new operator:

const idb = new InlineDB(idbName);

Param	Required	Type	Default	Description
idbName	Yes	String	None	Name of the database to create

Throws

When idbName is not provided.
When idbName is not a string.
When idbName does not match [a-zA-Z0-9]+([-_][a-zA-Z0-9]+)* pattern.
- see naming conventions for examples.

Returns

An instance of Database.

Create table

Creates an instance of Table.

idb.createTable(tableName);

Param	Required	Type	Default	Description
tableName	Yes	String	None	Name of the table to create

Throws

When tableName is not provided.
When tableName is not a string.
When tableName does not match [a-zA-Z0-9]+([-_][a-zA-Z0-9]+)* pattern.
- see naming conventions for examples.

Returns

An instance of Table.

List tables

Lists table that are created so far in the database.

idb.listTables();

Returns

An array of table names (Array<String>).

Drop table

Deletes a table permanently.

idb.dropTable(tableName);

Param	Required	Type	Default	Description
tableName	Yes	String	None	Name of the table to drop

Returns

Current instance of Database.

Drop database

Deletes the database permanently.

idb.drop();

Returns

Nothing (undefined).

Naming Conventions

Example for valid names:

my-database
MyTable
my-db-1
myFirstTable
DB1
TaBlE_uSeRs

Example for invalid names:

my database
_table
name_
#mytable
.database

Table

A table is created from a database instance using Database::createTable method. All data manipulation operations are transactional i.e until saved, none of the mutative queries are executed

Methods

Insert rows
Query rows
Update rows
Delete rows
Save queries
Revert queries

Insert rows

Queues a query to insert the given rows.

table.insert(row[, row, ...rows]);

Param	Required	Type	Default	Description
…rows	Yes	Object list	None	One or more objects to be inserted into the table

Throws

When one or more rows is not provided.
When one of the rows is not an object.

Returns

The current instance of Table.

Notes

Does not mutate the table until Table::save is called.
Can be reverted before saving using Table::revert.

Query rows

Queries rows matched by the filter.

table.query([filter]);

Param	Required	Type	Default	Description
filter	No	one of Number Array Function	`[Function:` `()` `=>` `true]`	Takes in an `id` or an array of `ids` or a filter function that will be matched against row

Returns

A Promise that resolves to a an array of rows that is matched by the given filter.

Update rows

Queues a query to update the rows that are matched by the given filter, and run given update on each of the filtered row to get the updated row.

table.update(update[, filter]);

Param	Required	Type	Default	Description
update	Yes	Function	None	A non mutative function that will be run on each row
filter	No	one of Number Array Function	`[Function:` `()` `=>` `true]`	Takes in an `id` or an array of `ids` or a filter function that will be matched against row

Throws

When udpate is not a function.
When udpate might mutate the row.
When udpate might return a value other than an Object.

Returns

The current instance of Table.

Notes

Does not mutate the table until Table::save is called.
Can be reverted before saving using Table::revert.

Delete rows

Queues a query to delete the rows that are matched by the given filter.

table.delete([filter]);

Param	Required	Type	Default	Description
filter	No	one of Number Array Function	`[Function:` `()` `=>` `true]`	Takes in an `id` or an array of `ids` or a filter function that will be matched against row

Returns

The current instance of Table.

Notes

Does not mutate the table until Table::save is called.
Can be reverted before saving using Table::revert.

Save queries

Saves queued queries to the table. Once done, it empties the query queue.

table.save();

Returns

A Promise that would resolve once the queries are successfully saved to table.

Revert queries

Empties the pending query queue.

table.revert();

Returns

The current instance of Table.

Examples

Create a database
Create a table
Insert rows into a table
Query rows from a table
Update rows in a table
Delete rows form a table
Chaining operations
Save queries to a table
Revert queries
Delete a table
List all tables
Drop a database

Create a database

Import the InlineDB library to instantiate a new database.

import InlindeDB from 'inlinedb';

const idbName = 'my-database';
const idb = new InlindeDB(idbName);

If the database is already exists, running new InlineDB will return an instance that runs on the existing database. Otherwise it will create a new database in the system and will return an instance for that.

Create a table

Use the idb instance to create a table. At this point there will be no table created in the system.

const tableName = 'my-table';
const table = idb.createTable(tableName);

Insert rows into a table

Multiple rows can be inserted into the table, but at least one row must be provided.

table.insert(
    {column: 'column awesome'},
    {column: 'column match'},
    {column: 'column random'}
);

There is no rule on how the row should look like, except that it should be an Object and should be serializable. So no Date, Symbol, or Function. Some of these might be supported in future.

There will be an $idbID assigned to each row on insertion. This value is just an auto-incremented value on each insertion. One can maintain their own ID or use this to identify rows in the table.

Query rows from a table

Querying can be achieved using an $idbID, an array of $idbID, or a custom function, or nothing in which case it will return everything. Querying is done asynchronously, so it will return a promise that will resolve to queried data.

Using no filter

table.query()
  .then(rows => console.log(rows));

// [
//   {
//     $idbID: 1,
//     column: 'column 1'
//   },
//   {
//     $idbID: 2,
//     column: 'column 2'
//   },
//   {
//     $idbID: 3,
//     column: 'column match'
//   }
// ]

Using id

table.query(1)
  .then(rows => console.log(rows));

// [
//   {
//     $idbID: 1,
//     column: 'column 1'
//   }
// ]

Using ids

table.query([1, 2])
  .then(rows => console.log(rows));

// [
//   {
//     $idbID: 1,
//     column: 'column 1'
//   },
//   {
//     $idbID: 2,
//     column: 'column 2'
//   }
// ]

Using a function

table.query(row => row.column === 'column match')
  .then(rows => console.log(rows));

// [
//   {
//     $idbID: 3,
//     column: 'column match'
//   }
// ]

Update rows in a table

Updating rows takes two parameters. An update function that is required and an optional filter.

The update function should not mutate the row, instead it should return a new updated row. Also it should return an Object that can be serialized, just like when inserting rows. Returning anything else will result in an error.

The filter function works just like the Table::query filter. It can be an $idbID, an array of $idbID, or a custom function, or nothing in which case it will update everything.

table.update(
  row => ({
    ...row,
    column: 'updated column'
  }),
  row => row.$idbID < 3
);

// [
//   {
//     $idbID: 1,
//     column: 'updated column'
//   },
//   {
//     $idbID: 2,
//     column: 'updated column'
//   },
//   {
//     $idbID: 3,
//     column: 'column match'
//   }
// ]

An update function may return an object too, which will be merged with the original row on ::save.

table.update(() => ({column: 'override'}));

// [
//   {
//     $idbID: 1,
//     column: 'override'
//   },
//   {
//     $idbID: 2,
//     column: 'override'
//   },
//   {
//     $idbID: 3,
//     column: 'override'
//   }
// ]

Delete rows from a table

Deleting rows takes an optional filter similar to Table::query. It can be an $idbID, an array of $idbID, or a custom function, or nothing in which case it will delete everything.

table.delete(1);

// [
//   {
//     $idbID: 2,
//     column: 'updated column'
//   },
//   {
//     $idbID: 3,
//     column: 'column match'
//   }
// ]

Chaining operations

Since its all Promise and this, all the operations can be easily chained.

import InlineDB from 'inlinedb';

const table = new InlineDB('my-database')
  .createTable('my-table')
  .insert(
    {column: 'column 1'},
    {column: 'column 2'},
    {column: 'column 3'}
  )
  .update(
    row => ({
      ...row,
      column: 'updated column'
    }),
    row => row.$idbID < 3
  )
  .delete(1);

table.save()
  .then(() => table.query())
  .then(rows => console.log(rows));

// [
//   {
//     $idbID: 2,
//     column: 'updated column'
//   },
//   {
//     $idbID: 3,
//     column: 'column 3'
//   }
// ]

Save queries to a table

All the mutative queries, ::insert, ::update and ::delete are not executed immediately, until saved. This gives the ability to ::revert the queries and a transactional feeling.

Note that after creating a new table, only on saving the data will be written to the system.

table.query()
  .then(rows =>
    console.log(rows)
    // []
  )
  .then(() => {
    table.insert(
      {column: 'column 1'},
      {column: 'column 2'}
    );
        
    return table.save()
  })
  .then(() => table.query())
  .then(rows =>
    console.log(rows)
    // [
    //   {
    //     $idbID: 1,
    //     column: 'column 1'
    //   },
    //   {
    //     $idbID: 2,
    //     column: 'column 2'
    //   }
    // ]
  );

Revert queries

All the queued queries can reverted to the last ::save.

table.query()
  .then(rows =>
    console.log(rows)
    // [
    //   {
    //     $idbID: 1,
    //     column: 'column 1'
    //   },
    //   {
    //     $idbID: 2,
    //     column: 'column 2'
    //   }
    // ]
  )
  .then(() => {
    table.update(
      () => ({column: 'updated column'})
    );
    
    table.revert();
        
    return table.save()
  })
  .then(() => table.query())
  .then(rows =>
    console.log(rows)
    // [
    //   {
    //     $idbID: 1,
    //     column: 'column 1'
    //   },
    //   {
    //     $idbID: 2,
    //     column: 'column 2'
    //   }
    // ]
  );

Drop table

Deleting a table is irreversible. It will delete the table from the system.

idb.dropTable('my-table');

List all tables

Listing all tables will return an array of table names.

idb.listTables();

// [
//   'my-table'
//   'user-table'
//   'highscores'
//   'todos'
// ]

Drop database

Deleting a database is irreversible. It will delete the database from the system and all the tables associated with it.

idb.drop();

License

MIT License

Copyright © 2017 InlineDB

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.