Cella.JS

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

• Installation
  • NPM
  • Yarn
  • Browser
• Developing locally
• Usage
  • Importing the Library
    • ES6 Modules
    • NodeJS Modules / Commonjs
    • Browser
  • How to Use
    • Examples
      • Basic Usage
      • Applying Transforms And Encryption
      • Specifying A Custom Database Engine
  • API
    • Cella Class Properties (CellaInstance)
    • Interfaces
      • StorageEngine
      • StorageItem
      • RetrievedStorageItem
      • DeletedStorageItem
      • SpecifiedStorageEngine
      • TransformObject
• Contributing
• License
• Upcoming Features!
• Todo
• Browser Support

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.	SpecifiedStorageEngine OR StorageEngine	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()

Property name	Description	Data type	Required	Default value
key	The key/label that identifies the item in the localstorage.	string	true	-

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	Chrome	Safari	iOS Safari	Samsung	Opera
12	3.5	4	4	3.2	1.0	10.5