local-vault
v1.5.0
Published
A Database API that works with local storage.
Downloads
6
Maintainers
Readme
Local Vault
Transform your localStorage into a relational database.
What is Local Vault?
Local Vault is a light weight ORM that allows you to build, develop, and access relational databases in your localStorage
. You can create multiple databases, tables, and relationships such as hasMany
or oneToOne
. All database data is encoded into a base-64 string and persisted to window.localStorage.localVault
.
Local Vault is super easy to set up and can be used in conjunction with any front end framework. This tool can be used either for development or production, depending on the scale and particulars of your project.
Table of Contents
- Getting Started
- Database Creation and Development
- Database Methods
- Table Methods
- Debugging
- Contributing
- License
Getting Started
npm install local-vault --save-dev
On the front end just import
the Local Vault Database ORM
import LocalVault from 'local-vault';
Database Creation and Development
Creating a Database
Creating a database named "school"
using the LocalVault Database ORM utility from Getting Started
LocalVault.init();
LocalVault.create('school');
Fetching a Database
Creating database "school"
and then assigning a variable to it.
LocalVault.create('school');
const database = LocalVault.fetch('school');
Alternatively, you could combine Database creation and fetching in one line with:
const database = LocalVault.create('school');
Confirming a Database's Existence
There are two ways to find out whether or not a database exists.
- Using
fetch()
const database = LocalVault.fetch('school');
// =>
instanceof Database()
const database = LocalVault.fetch('vacation');
// =>
false
- Using
doesExist()
const databaseExists = LocalVault.doesExist('school');
// =>
true
const databaseExists = LocalVault.doesExist('vacation');
// =>
false
Listing all Existing Databases
Assuming Local Vault currently has databases named "larry"
, "curly"
, and "moe"
.
let databaseNames = LocalVault.list();
// =>
['larry', 'curly', 'moe']
Removing a Database
Deleting database "office"
LocalVault.destroy('office');
Therefore...
LocalVault.fetch('office');
// =>
false
Removing all Databases
LocalVault.destroyAll();
Please Note that after you run LocalVault.destoryAll()
you must run LocalVault.init()
before you utilize any of Local Vault's functionality, otherwise an error will be thrown.
Database Methods
To get started, assume we create a database called "school"
.
const dbSchool = LocalVault.create('school');
Creating a Table
The createTable
method accepts to parameters; the table name and the table's schema. The schema is a simple array outlining the table's keys. Note that the primary key, "id"
, is automatically applied to the table. A unique id is automatically added to each new table entry.
const Teacher = dbSchool.createTable('teacher', ['name', 'email', 'phone', 'subject', 'officeHours']);
Fetching a Table
const Teacher = dbSchool.fetchTable('teacher');
Listing all Tables
dbSchool.listTables();
// =>
['teacher', 'student', 'lesson', 'test'];
Dropping Tables
A single table...
dbSchool.dropTable('teacher');
All tables...
dbSchool.dropTables();
Table Methods
For the following examples, assume we have a database, "school"
which has a table, "teacher"
.
LocalVault.init();
const dbSchool = LocalVault.create('school');
const Teacher = dbSchool.createTable('teacher', ['name', 'room', 'officePeriod', 'subject']);
Posting an Entry
let teacherMary = {
name: 'Mary Shippen',
room: '7B',
officePeriod : '3',
subject: 'British Literature'
}
Teacher.add(teacherMary);
The above code would persist the following object to table, "teacher"
.
{
id: AUTOMATICALLY_GENERATED_ID,
created_on: UNIX_TIMESTAMP,
last_updated_on: UNIX_TIMESTAMP,
name: 'Mary Shippen',
room: '7B',
officePeriod: 3,
subject: 'British Literature'
}
Note that the fields "id"
, "created_on"
, and "last_updated_on"
are auto generated and thus reserved by the system.
Posting Multiple Entries
You can post an array of objects to any table.
let teacherArray = [
{
name: 'Mary Shippen',
room: '7B',
officePeriod: '3',
subject: 'British Literature'
},
{
name: 'Dev Patel',
room: '2C',
officePeriod: '1',
subject: 'AP Calculus'
},
{
name: 'Harold Feltch',
room: '6A',
officePeriod: '5',
subject: 'Civics'
}
];
Teacher.seed(teacherArray);
All three objects would be added to the table and given ids
and timestamps
accordingly.
Fetching Entries
There are two ways to fetch and entry, by id
or by key
.
Teacher.fetch(2);
// =>
{
id: 2,
created_on: 1213787327165,
last_updated_on: 1414786657168,
name: 'Dev Patel',
room: '2C',
officePeriod: '1',
subject: 'AP Calculus'
}
When fetching an entry by key, you must pass an existing key-value pair.
Teacher.fetchByKey('name', 'Dev Patel');
// =>
[
{
id: 2,
created_on: 1213787327165,
last_updated_on: 1414786657168,
name: 'Dev Patel',
room: '2C',
officePeriod: '1',
subject: 'AP Calculus'
}
]
Notice that the fetchByKey
method returns an array of objects. This is due to the possibilty of mutliple entries that match the key-value pair passed. fetch
simply returns a single object since ids
are always the primary key and thus unique.
Finally, the fetchAll
method does just that!
Teacher.fetchAll();
// =>
[
{
id: 1,
created_on: 1213527327165,
last_updated_on: 1213527327165,
name: 'Mary Shippen',
room: '7B',
officePeriod: '3',
subject: 'British Literature'
},
{
id: 2,
created_on: 1213787327165,
last_updated_on: 1414786657168,
name: 'Dev Patel',
room: '2C',
officePeriod: '1',
subject: 'AP Calculus'
},
{
id: 3,
created_on: 1313787327165,
last_updated_on: 1314786657168,
name: 'Harold Feltch',
room: '6A',
officePeriod: '5',
subject: 'Civics'
}
];
Updating Entries
You can update entries by either id
or by key-value pair.
let nextSemester = {
room: '5B',
subject: 'World History',
officePeriod: '1'
};
Teacher.update(3, nextSemester);
// =>
{
id: 3,
created_on: 1313787327165,
last_updated_on: 1517791669467,
name: 'Harold Feltch',
room: '5B',
officePeriod: '1',
subject: 'World History'
}
The updateByKey
method can be used to update all entries with "officePeriod" : '1'
.
Teacher.updateByKey('officePeriod', '1', {officePeriod: '2'});
Teacher.fetchByKey('name', 'Harold Feltch')[0].officePeriod === '2';
// =>
true
Teacher.fetch(2).officePeriod === '2';
// =>
true
Establishing Relationships
Currently, Local Vault only supports Has-Many type relationships. There are plans to eventually add One-To-One and Many-To-Many.
Consider the following example where we add a table to keep track of students to the school
database.
const Student = School.createTable('student', ['firstName', 'lastName', 'gender', 'grade']);
Since a teacher typically has many students, we can establish a Has-Many relationship between the Teacher
and Student
tables.
We can do so by passing the instantiated Table
class or table name as a string into the hasMany()
class method.
Teacher.hasMany(Student);
// or
Teacher.hasMany('student');
Establishing this relationship has two major implications:
- The
Student
table now has ateacherId
field added to its schema. TheteacherId
is essentially a foreign key that relates to the primary key (id
field) of theTeacher
table. - When entries are fetched from the
Teacher
table, they will have astudents
field, which points to an array ofStudent
entries whose related foreign key(s) match the pulledTeacher
primary key(s). See the example below.
let students = [
{
firstName: 'Margaret',
lastName: 'Sands',
grade: '10',
gender: 'female',
teacherId: 1
},
{
firstName: 'Jeff',
lastName: 'Becker',
grade: '9',
gender: 'male',
teacherId: 2
},
{
firstName: 'Katie',
lastName: 'Li',
grade: '6',
gender: 'female',
teacherId: 3
},
{
firstName: 'Abdullah',
lastName: 'Jawad',
grade: '10',
gender: 'male',
teacherId: 1
},
{
firstName: 'Amalie',
lastName: 'Danner',
grade: '9',
gender: 'female',
teacherId: 2
},
{
firstName: 'Kent',
lastName: 'Osburne',
grade: '6',
gender: 'male',
teacherId: 3
},
{
firstName: 'Brit',
lastName: 'Wixley',
grade: '10',
gender: 'female',
teacherId: 1
},
]
Student.seed(students)
Teacher.fetch(1)
// =>
{ id: 1,
created_on: 1519066685687,
last_updated_on: 1519066685687,
name: 'Mary Shippen',
room: '7B',
officePeriod: '3',
subject: 'British Literature',
students:
[ { id: 1,
created_on: 1519066685699,
last_updated_on: 1519066685699,
firstName: 'Margaret',
lastName: 'Sands',
grade: '10',
gender: 'female',
teacherId: 1 },
{ id: 4,
created_on: 1519066685712,
last_updated_on: 1519066685712,
firstName: 'Abdullah',
lastName: 'Jawad',
grade: '10',
gender: 'male',
teacherId: 1 },
{ id: 7,
created_on: 1519066685729,
last_updated_on: 1519066685729,
firstName: 'Brit',
lastName: 'Wixley',
grade: '10',
gender: 'female',
teacherId: 1 }
]
}
Removing Entries
You can remove an entry either by id
or key-value pair.
Teacher.remove(3);
// Removes Harold Feltch from the Teacher table
Student.removeByKey('gender', 'female');
// Removes all female students
An entire table's entries can be flushed via:
Student.removeAll();
Debugging
You can turn on debug mode when initializing LocalVault
.
LocalVault.init('debug');
Alternatively, you can switch debug mode on and off via the following methods, respectively.
LocalVault.debugOn();
LocalVault.debugOff();
Contributing
Contributing should be directed toward a specific issue.
Fork the Repo
Clone the Repo
git clone https://github.com/YOUR_GITHUB_USERNAME/local-vault.git
NPM Install
npm install
Create a branch off of master
to address an issue
git checkout -b 'feature/issue-ISSUE_NUMBER'
for example:
git checkout -b 'feature/issue-9'
Make changes and Commit Code
git add .
git commit -m 'thoughtful, concise, high level outline of change'
Push into Your Branch
git push origin feature/issue-ISSUE_NUMBER
Create a Pull Request and tag the relevant issue(s) in that request
And that's it! Thanks for contributing! :tada: :tada: :tada: