cella.js

v0.2.1

Published

2 years ago

Easily and securely manage data storage within the browser with a simple API.

Downloads

0High
0Medium
0Low

greyjnr

localStorage encrypt encrypt storage

Cella.JS

Build Status Made with Typescript

Cella.JS is a JavaScript package that helps you manage data storage within the browser. It basically serves as a basic wrapper around the browser's default local storage APIs in order to provide extra functionality. Cella.JS eliminates the need to write extra code when working with the browser's local storage. It provides features such as:

In-built support for encryption.
Store abstract data types without needing to convert to a string first.
Ability to add custom storage engine.
Ability to add custom (data-transformational) functions to be executed before or after data is stored or retrieved.
#Working on in-built support for indexedDB.

Table of contents generated with markdown-toc

Installation

NPM

$ npm install cella.js

Yarn

$ yarn add cella.js

Browser

https://unpkg.com/[email protected]/dist/index.js

Developing locally

To clone and build this project locally, run the following commands:

$ git clone https://github.com/IggsGrey/cella.js.git
$ npm i
$ npm run dev

Usage

Importing the Library

ES6 Modules

import Cella from 'cella.js';

NodeJS Modules / Commonjs

const Cella = require('cella.js');

Browser

Import the library with a script tag and the Cella API shall be made available.

Cella

How to Use

Usage is unbelievably simple.

Import the library
Create an instance of Cella.
Specify properties (optional) (CellaInstance)
Operation methods are made available to the newly instantiated class. (StorageItem, RetrievedStorageItem, DeletedStorageItem)

Examples

Basic Usage

import Cella from 'cella.js';

// create an instance of Cella!
const cella = new Cella();


// store an item
cella.store({
	key: 'sample-key',
	value: ['item1', 'item2', 'item3', 'item4']
}).then(() => {
    console.log('void');
});
// Promise<void>


// retrieve an item
const retrievedItem = cella.get({
	key: 'sample-key'
}).then((res) => {
    console.log('got',res);
});
// Promise<Array ['item1', 'item2', 'item3', 'item4']>


// delete an item
cella.eject({
	key: 'sample-key',
}).then(() => {
    console.log('void');
});
// Promise<void>

Applying Transforms And Encryption

import Cella from 'cella.js'

const mySetData = new Set(['pineapples', 'are', 'great']);

console.log(mySetData);

const cella = new Cella({
	encrypt: {
		secret: 'my-secret-key' // yup that's it!
	},
	transforms: [
		{
			inbound: function(yourSetData) {
				// convert set to array
				return [...yourSetData];
			},
			outbound: function(yourConvertedSetData) {
				// convert array back to set
				return new Set(yourConvertedSetData);
			}
		},
		// ...unlimitedTransforms
	]
});


cella.store({
	key: 'my-key',
	value: mySetData
});

cella.get({ key: 'my-key' }).then(res => console.log(res));

Specifying A Custom Storage Engine

import Cella from 'cella.js';

// create an instance of Cella!
const cella = new Cella({
    storage: {
        store: (key, value) => {
            // code to implement custom storing
        },
        get: (key) => {
            // code to implement custom retrieval
        },
        eject: (key) => {
            // code to implement custom deletion
        }
    }
});

API

Cella Class Properties (CellaInstance)

Properties you can pass to the new Cella class

| Property name | Description | Data type | Required | Default value | | ------ | ------ | ------ | ------ | ------ | | storage | Specify the StorageEngine to use and additional options. NOTE: If you specify a custom database storage engine object, it must implement the StorageEngine interface. | SpecifiedStorageEngineORStorageEngine | no | { type: 'localStorage' } | encrypt | An object that specifies encryption details including the encryption secret | Record<'secret', string> Eg: { secret: 'some-string' } | no | - | | transforms | Array of objects defining function inbound and outbound functions. Useful for modifying data before storing and retrieving. | TransformObject[] | no | - |

Interfaces

StorageEngine

All instances of the in-built storage engines implement this interface, and all custom storage engines must implement this interface as well.

| Property name | Description | Data type | Parameters | | ------ | ------ | ------ | ------ | | store | The function that inserts data into the local database. | Function | StorageItem: {key: string (required)value: string (required)} | | get | The function that retrieves data from the local database. | Function | RetrievedStorageItem: {key: string (required)} | | eject | The function that deletes data from the local database. | Function | DeletedStorageItem: {key: string (required)} |

StorageItem

The object parameter properties for each time you call cella.store()

| Property name | Description | Data type | Required | Default value | | ------ | ------ | ------ | ------ | ------ | | key | The key/label that identifies the item in the localstorage. | string | true | - | | value | The value of the item to be stored. | any | true | - | | encrypt | Encryption properties for the data to be stored. | { secret: string } | false | null |

RetrievedStorageItem

The object parameter properties for each time you call cella.get()

| Property name | Description | Data type | Required | Default value | | ------ | ------ | ------ | ------ | ------ | | key | The key/label that identifies the item in the localstorage. | string | true | - | | decrypt | Decryption properties for the data to be stored. | { secret: string } | false | null |

DeletedStorageItem

The object parameter properties for each time you call cella.eject()

SpecifiedStorageEngine

These properties are valid for the storage object value in the CellaInstance.

| Property name | Description | Data type | Required | Default value | | ------ | ------ | ------ | ------ | ------ | | type | The preferred type of in-built storage. | 'localStorage' | 'indexedDB' | true | 'localStorage' | | name | The preferred name of the indexedDB storage. | string | required only when type == 'indexedDB' | - |

NOTE: IN-BUILT SUPPORT FOR INDEXEDDB IS NOT YET IMPLEMENTED

TransformObject

These properties are valid for an object value in the transforms array specified in a CellaInstance.

| Property name | Description | Data type | Required | Default value | | ------ | ------ | ------ | ------ | ------ | | inbound | Function that is executed ech time data is being stored. This function is executed before any other changes are made to the data. | (args0: T) => any | yes | - | | outbound | Function that is executed ech time data is being retrieved. This function is executed after all other changes have been made to the data. | (args0: T) => any | yes | - |

Contributing

Want to contribute? Great! I am currently seeking contributors for remaining features including adding in-built support for more DB engines. You can get started by reading the current issues or opening one yourself. Don't forget to read the ethics and conduct code for contributors in the CONTRIBUTING.md You may also contact @IggsGrey on:

License

This project uses the ISC license and it can be found here: LICENSE

Upcoming Features!

In-built support for indexedDB.
Integration with web workers.
Data compression.
Smart fallbacks for browser support issues. Eg: fallback to localStorage in browsers that do not support indexedDB (optional ofcourse).

Todo

Write tests.
Implement features above (obviously Tom!).
Build docs site with demos
Work on browser support docs
Codesandbox examples

Browser Support

| IE / Edge | Firefox Firefox | Chrome Chrome | Safari Safari | iOS Safari | Samsung Samsung | Opera Opera | | --------- | --------- | --------- | --------- | --------- | --------- | --------- | | 12| 3.5 | 4 | 4 | 3.2 | 1.0 | 10.5