pannh / swift-database

A light-weight module to interact with your local JSON database.

🗃 swift-database

swift-database is a module that allows you to interact easily with your local JSON file.

🔰 Getting started

1. Install the module

 npm install swift-database

2. Initialize the database class

const { default: JSONDatabase } = require('swift-database');

const database = new Database({
   filePath: 'path/to/file.json'
});

3. Create your first table and load it

database.createTable('users');

const users = database.table('users');

4. Interact with that table

users.createOne({
   fullName: 'John Doe',
   hobbies: ['programming', 'sport']
});

const userDocument = users.findOne(
   (userDocument) => userDocument.value.fullName === 'John Doe'
);

users.deleteOne(userDocument.id);

📖 Documentation

JSONDatabase

Represents the database.

Constructor

Parameter	Type	Required	Default	Description
options	{ filePath: string }	✓	None	The database options.

Example :

const database = new JSONDatabase({
   filePath: 'path/to/file.json'
});

JSONDatabase.tables

Returns an array of each table's name.

Type: string[]

JSONDatabase.table(name)

Loads a table from the database.

Parameter	Type	Required	Default	Description
name	string	✓	None	The name of the table you want to load.

Returns: DatabaseTable

Example :

const users = database.table('users');

JSONDatabase.createTable(name)

Creates a new table into the database.

Parameter	Type	Required	Default	Description
name	string	✓	None	The name of the table you want to create.

Returns: DatabaseTable

Example :

const users = database.createTable('users');

JSONDatabase.deleteTable(name)

Delete an existing table from the database.

Parameter	Type	Required	Default	Description
name	string	✓	None	The name of the table you want to delete.

Returns: void

Example :

database.deleteTable('users');

---

DatabaseTable

Represents a database table.

DatabaseTable.size

Returns the amount of documents inside the table.

Type: number

DatabaseTable.all

Returns an array of every table documents.

Type: TableDocument[]

DatabaseTable.getById(documentId)

Returns the table document that matches the specified id.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to get.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

const userDocument = users.getById(DOCUMENT_ID);

DatabaseTable.findOne(predicate)

Returns the first table document that matches the predicate.

Parameter	Type	Required	Default	Description
predicate	PredicateFunction	✓	None	The predicate function you want to filter the documents by.

💡 PredicateFunction = (document: TableDocument, index: number, table: object[]) => boolean

Returns: TableDocument

Example :

const userDocument = users.findOne(
   (userDocument) => userDocument.value.fullName === 'John Doe'
);

DatabaseTable.findMany(predicate)

Returns every documents that match the predicate.

Parameter	Type	Required	Default	Description
predicate	PredicateFunction	✓	None	The predicate function you want to filter the documents by.

💡 PredicateFunction = (document: TableDocument, index: number, table: object[]) => boolean

Returns: TableDocument[]

Example :

const userDocuments = users.findMany((userDocument) =>
   userDocument.value.hobbies.includes('programming')
);

DatabaseTable.createOne(data)

Creates a new table document and returns it.

Parameter	Type	Required	Default	Description
data	object	✓	None	The document's data.

Returns: TableDocument

Example :

const createdUserDocument = users.createOne({
   fullName: 'John Doe',
   hobbies: ['programming', 'sport']
});

DatabaseTable.createMany(...data)

Creates many table documents and returns them.

Parameter	Type	Required	Default	Description
data	object[]	✓	None	An array of each document's data.

Returns: TableDocument[]

Example :

const createdUserDocuments = users.createMany(
   {
      fullName: 'John Doe',
      hobbies: ['programming', 'sport']
   },
   {
      fullName: 'Alice Doe',
      hobbies: ['studying', 'videogames']
   }
);

DatabaseTable.deleteOne(documentId)

Deletes a table document.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to delete.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

const deletedUserDocument = users.deleteOne(DOCUMENT_ID);

DatabaseTable.deleteMany(...documentIds)

Deletes many table documents.

Parameter	Type	Required	Default	Description
documentIds	string[]	✓	None	An array of each document's id you want to delete.

Returns: TableDocument[]

Example :

const DOCUMENT_IDS = [
   '0557f4db-5688-4d99-8f85-a83605cf8c1e',
   '2fe5a45e-1ffe-47ba-ab14-ac94ee26ec68'
];

const deletedUserDocuments = users.deleteMany(DOCUMENT_IDS);

DatabaseTable.update(documentId, data)

Updates a table document.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to update.
data	object	✓	None	The data you want to update.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

// Before: TableDocument { id: ..., value: { fullName: 'Alice Doe', ... } }
const updatedUserDocument = users.update(DOCUMENT_ID, {
   fullName: 'Alice Dart'
});
// After: TableDocument { id: ..., value: { fullName: 'Alice Dart', ... } }

DatabaseTable.increment(documentId, propertyKey, value)

Increments a document's property.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to make changes on.
propertyKey	string	✓	None	The key of the property you want to increment.
value	string	X	1	The value you want to increment the property by.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

// Before: TableDocument { id: ..., value: { age: 21, ... } }
const updatedUserDocument = users.increment(DOCUMENT_ID, 'age');
// After: TableDocument { id: ..., value: { age: 22, ... } }

DatabaseTable.decrement(documentId, propertyKey, value)

Decrements a document's property.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to make changes on.
propertyKey	string	✓	None	The key of the property you want to decrement.
value	string	X	1	The value you want to decrement the property by.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

// Before: TableDocument: { id: ..., value: { lives: 3, ... } }
const updatedUserDocument = users.decrement(DOCUMENT_ID, 'lives');
// After: TableDocument: { id: ..., value: { lives: 2, ... } }

DatabaseTable.multiply(documentId, propertyKey, value)

Multiplies a document's property.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to make changes on.
propertyKey	string	✓	None	The key of the property you want to multiply.
value	string	✓	None	The value you want to multiply the property by.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

// Before: TableDocument: { id: ..., value: { chances: 10, ... } }
const updatedUserDocument = users.multiply(DOCUMENT_ID, 'chances', 1.5);
// After: TableDocument: { id: ..., value: { chances: 15, ... } }

DatabaseTable.divide(documentId, propertyKey, value)

Divides a document's property.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to make changes on.
propertyKey	string	✓	None	The key of the property you want to divide.
value	string	✓	None	The value you want to divide the property by.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

// Before: TableDocument: { id: ..., value: { chances: 10, ... } }
const updatedUserDocument = users.divide(DOCUMENT_ID, 'chances', 2);
// Before: TableDocument: { id: ..., value: { chances: 5, ... } }

DatabaseTable.deleteProperty(documentId, key)

Deletes a document's property.

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to make changes on.
key	string	✓	None	The key of the property you want to delete.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

// Before: TableDocument: { id: ..., value: { fullName: 'John Doe', age: 21 } }
const updatedUserDocument = users.deleteProperty(DOCUMENT_ID, 'fullName');
// Before: TableDocument: { id: ..., value: { age: 21 } }

DatabaseTable.push(documentId, propertyKey, ...items)

Pushes items into an array document's property;

Parameter	Type	Required	Default	Description
documentId	string	✓	None	The id of the document you want to make changes on.
propertyKey	string	✓	None	The key to the array property you want to push the item to.
items	any[]	✓	None	The items you want to push into the array.

Returns: TableDocument

Example :

const DOCUMENT_ID = '0557f4db-5688-4d99-8f85-a83605cf8c1e';

// Before: TableDocument: { id: ..., value: { hobbies: ['programming'], ... } }
const updatedUserDocument = users.push(DOCUMENT_ID, 'hobbies', 'tennis');
// Before: TableDocument: { id: ..., value: { hobbies: ['programming', 'tennis'], ... } }

---

TableDocument

Represents a table document.

TableDocument.id

Returns the document's id.

Type: string

TableDocument.value

Returns the document's data.

Type: object