🗃 swift-database
swift-database
is a module that allows you to interact easily with your local JSON file.
🔰 Getting started
- Install the module
npm install swift-database
- Initialize the database class
const { default: JSONDatabase } = require('swift-database');
const database = new Database({
filePath: 'path/to/file.json'
});
- Create your first table and load it
database.createTable('users');
const users = database.table('users');
- 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