This is a small file/directory based app for Node JS that provides some basic database functionality for storing key-value pairs in table/row/entry format as .json files.
The purpose of this library is to provide a simple database-like storage system for things like small personal projects or prototyping. It is written to be easy to setup and use.
This library requires no dependencies.
Note: sketchdb requires Node.js v18 or higher.
run
npm install sketchdbin your project's directory to install a local node module.
run
npm exec sketchdb-setupfrom the top level of your project directory to setup an instance of sketchdb.
Alternatively, call sketchdb.setup() from inside a script (note - sketchdb.setup() is async and returns a promise)
The setup application will create a new directory in that top level directory of the project named "sketchdb_store" where data will be stored, along with a subdirectory named "tables". (That's all sketchdb-setup does)
External edits to directories and files in sketchdb_store will reflect in the database as long as they are proper JSON.
All function calls to sketchdb return a Promise.
Calls to retrieve data will resolve to that data or reject with an error.
Calls to write data or perform a delete operation will resolve with true on success (this will probably change to an object of some sort with more info but haven't decided yet)
- sketchdb.list_tables
- sketchdb.create_table
- sketchdb.insert
- sketchdb.get_row
- sketchdb.get_all
- sketchdb.update
- sketchdb.delete_row
- sketchdb.delete_table
- sketchdb.filter
- sketchdb.rename_table
For your convenience, all main API functions in sketchdb are available in both snake_case and camelCase formats. You can use whichever naming style fits your project best—they are fully interchangeable.
Examples:
sketchdb.createTable = sketchdb.create_table;
sketchdb.listTables = sketchdb.list_tables;
sketchdb.getRow = sketchdb.get_row;
sketchdb.getAll = sketchdb.get_all;
sketchdb.deleteRow = sketchdb.delete_row;
sketchdb.deleteTable = sketchdb.delete_table;
sketchdb.renameTable = sketchdb.rename_table;
sketchdb.moveRow = sketchdb.move_row;
sketchdb.insert
sketchdb.update List the tables in the database in array format.
Syntax:
sketchdb.list_tables()Parameters:
none
Return value: Returns a Promise. When resolved, Promise returns an array of the table names as strings.
Example usage:
sketchdb.list_tables()
.then(function(results) {
do_something_with_results(results);
// Results will be an array like ["users","posts","authors"]
});Creates a new table in the database.
Syntax:
sketchdb.create_table('table_name')Parameters:
table_name: The name of the table to create (as a string)
Return value: Returns a Promise. Resolves with true. Rejects with an error if the table exists.
Example usage:
sketchdb.create_table('users')
.then(success_function)
.catch(error_handler);Note: You can also create a table by making a subdirectory in "./sketchdb_store/tables/" with the table name.
Insert a new row into a given table in the database.
Syntax:
sketchdb.insert(table_name, id, data)Or let sketchdb generate a unique id:
sketchdb.insert(table_name, data)Parameters:
- table_name (string): Table to insert into.
- id (string, optional): Unique row id. (Optional, will auto-generate if omitted)
- data (object or JSON string): Data to store as JSON.
Return value: Returns a Promise. Resolves with the id.
Example usage:
const user = { name: 'John', group: '1' };
sketchdb.insert('users', user)
.then(function(id) {
// use the returned unique id
});or
const id = '1234'
const user = { name: 'John', group: '1' };
sketchdb.insert('users', id, user)
.then(function(id) {
// do something next, id is the given id
});Retrieve a row from a given table.
Syntax:
sketchdb.get_row(table_name, id)Parameters:
- table_name (string): Table name
- id (string): Row id
Return value: Resolves to the data object for the row, or rejects if not found.
Example usage:
sketchdb.get_row('users', '178')
.then(user => {
// Do something with the user data
console.log('User name:', user.name);
console.log('User group:', user.group);
})
.catch(error => {
// Handle the error
console.error('Error fetching row:', error.message);
});Retrieve all rows from a given table as an array.
Syntax:
sketchdb.get_all(table_name)Return value: Resolves to an array of row objects. Rejects if table not found.
Example usage:
sketchdb.get_all('users')
.then(users => {
//do something with the users array
handle_users(users);
})
.catch(handle_error);Update a row with new or replacement data.
Syntax:
sketchdb.update(table_name, id, data)Parameters:
- table_name (string): Table name
- id (string): Row id
- data (object): Data to merge/update
Return value: Resolves with true on success, rejects on error.
Example usage:
sketchdb.update('users', 'uq13g564d', { group: '2' })
.then(success_function)
.catch(handle_error);Delete a row from a table.
Syntax:
sketchdb.delete_row(table_name, id)Return value: Resolves with true on success.
Example usage:
sketchdb.delete_row('users', '178')
.then(success_function)
.catch(handle_error);Delete an entire table and its rows.
Syntax:
sketchdb.delete_table(table_name)Return value: Resolves with true on success.
Example usage:
sketchdb.delete_table('students')
.then(success_function)
.catch(handle_error);Return an array of all rows in a table with a given key/value pair.
Syntax:
sketchdb.filter(table_name, key, value)Return value: Resolves to array of row objects with matching key/value.
Example usage:
sketchdb.filter('users', 'group', 'superuser')
.then(users => {
// Do something with the array of objects
handle_users_array(users);
})
.catch(error => {
// Handle the error
console.error('Error fetching array:', error.message);
});Rename a table.
Syntax:
sketchdb.rename_table(table, new_name)Return value: Resolves with true on success.
Example usage:
sketchdb.rename_table('authors', 'contributors')
.then(success_function)
.catch(handle_error);Move a row from one table to another (retaining the same row id).
Syntax:
sketchdb.move_row(from_table, to_table, id)Parameters:
- from_table (string): The table to move the row from
- to_table (string): The table to move the row to
- id (string): The id of the row to move
Return value: Resolves with true on success. Rejects with an error if the source row does not exist, or the destination already has the id.
Example usage:
sketchdb.move_row('drafts', 'posts', '12345')
.then(() => console.log('Row moved!'))
.catch(handle_error);