🗃 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

Represents the database.

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

Example :

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

Returns an array of each table's name.

Type: string[]

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');

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');

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');

Represents a database table.

Returns the amount of documents inside the table.

Type: number

Returns an array of every table documents.

Type: TableDocument[]

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);

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'
);

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')
);

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']
});

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']
   }
);

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);

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);

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', ... } }

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, ... } }

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, ... } }

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, ... } }

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, ... } }

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 } }

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'], ... } }

Represents a table document.

Returns the document's id.

Type: string

Returns the document's data.

Type: object