# cella.js
> Easily and securely manage data storage within the browser with a simple API.
Latest version **0.2.1** (published 2024-01-08) · ISC license · 0 weekly downloads
## Install
```sh
npm install cella.js
pnpm add cella.js
yarn add cella.js
bun add cella.js
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.2.1 |
| Published | 2024-01-08 |
| First published | 2021-01-07 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 39.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | J. Ignatius Aggrey |
| Maintainers | greyjnr |
| Keywords | localStorage, encrypt, encrypt storage |
## Links
- npm: https://www.npmjs.com/package/cella.js
- Repository: https://github.com/IggsGrey/cella.js
- Homepage: https://iggsgrey.github.io/cella.js/
- Issues: https://github.com/IggsGrey/cella.js/issues
- npm.io page: https://npm.io/package/cella.js
## Dependencies (1)
- [crypto-js](https://npm.io/package/crypto-js.md) ^4.0.0
## Alternatives
- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads
## Recent versions
- 0.2.1 (latest) — 2024-01-08
- 0.2.0 — 2024-01-08
- 0.0.0 — 2021-01-07
## README
# Cella.JS
   [](https://github.com/IggsGrey/cella.js/blob/main/LICENSE) 
[](https://github.com/IggsGrey/cella.js#todo) [](https://github.com/IggsGrey/cella.js#contributing) [](https://github.com/IggsGrey/cella.js/compare)
 
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](#installation)
* [NPM](#npm)
* [Yarn](#yarn)
* [Browser](#browser)
- [Developing locally](#developing-locally)
- [Usage](#usage)
* [Importing the Library](#importing-the-library)
+ [ES6 Modules](#es6-modules)
+ [NodeJS Modules / Commonjs](#nodejs-modules---commonjs)
+ [Browser](#browser-1)
* [How to Use](#how-to-use)
+ [Examples](#examples)
- [Basic Usage](#basic-usage)
- [Applying Transforms And Encryption](#applying-transforms-and-encryption)
- [Specifying A Custom Database Engine](#specifying-a-custom-database-engine)
* [API](#api)
+ [Cella Class Properties (CellaInstance)](#cella-class-properties--cellainstance-)
+ [Interfaces](#interfaces)
- [StorageEngine](#storageengine)
- [StorageItem](#storageitem)
- [RetrievedStorageItem](#retrievedstorageitem)
- [DeletedStorageItem](#deletedstorageitem)
- [SpecifiedStorageEngine](#specifiedstorageengine)
- [TransformObject](#transformobject)
- [Contributing](#contributing)
- [License](#license)
- [Upcoming Features!](#upcoming-features-)
- [Todo](#todo)
- [Browser Support](#browser-support)
Table of contents generated with markdown-toc
# Installation
## NPM
```sh
$ npm install cella.js
```
## Yarn
```sh
$ yarn add cella.js
```
## Browser
`https://unpkg.com/cella.js@0.0.0/dist/index.js`
# Developing locally
To clone and build this project locally, run the following commands:
```sh
$ git clone https://github.com/IggsGrey/cella.js.git
$ npm i
$ npm run dev
```
# Usage
## Importing the Library
### ES6 Modules
```js
import Cella from 'cella.js';
```
### NodeJS Modules / Commonjs
```js
const Cella = require('cella.js');
```
### Browser
Import the library with a script tag and the Cella API shall be made available.
```js
Cella
```
## How to Use
Usage is unbelievably simple.
- Import the library
- Create an instance of Cella.
- Specify properties (optional) ([CellaInstance](https://github.com/IggsGrey/cella.js#cella-class-properties-cellainstance))
- Operation methods are made available to the newly instantiated class.
([StorageItem](https://github.com/IggsGrey/cella.js#storageitem), [RetrievedStorageItem](https://github.com/IggsGrey/cella.js#retrievedstorageitem), [DeletedStorageItem](https://github.com/IggsGrey/cella.js#deletedstorageitem))
### Examples
#### Basic Usage
```js
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
// retrieve an item
const retrievedItem = cella.get({
key: 'sample-key'
}).then((res) => {
console.log('got',res);
});
// Promise
// delete an item
cella.eject({
key: 'sample-key',
}).then(() => {
console.log('void');
});
// Promise
```
#### Applying Transforms And Encryption
```js
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
```js
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](https://github.com/IggsGrey/cella.js#storageengine) interface. | [SpecifiedStorageEngine](https://github.com/IggsGrey/cella.js#specifiedstorageengine)
OR
[StorageEngine](https://github.com/IggsGrey/cella.js#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](https://github.com/IggsGrey/cella.js#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](https://github.com/IggsGrey/cella.js#storageitem):
{
`key: string` (required)
`value: string` (required)
} |
| get | The function that retrieves data from the local database. | Function | [RetrievedStorageItem](https://github.com/IggsGrey/cella.js#retrievedstorageitem):
{
`key: string` (required)
} |
| eject | The function that deletes data from the local database. | Function | [DeletedStorageItem](https://github.com/IggsGrey/cella.js#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](https://github.com/IggsGrey/cella.js#cella-class-properties-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](https://github.com/IggsGrey/cella.js#cella-class-properties-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](https://github.com/IggsGrey/cella.js/blob/main/CONTRIBUTING.md)
You may also contact [@IggsGrey](https://github.com/IggsGrey) on:
- [](mailto:jaygrey.jg@gmail.com)
- 
- 
- [](https://twitter.com/devx_gh)
# License
This project uses the ISC license and it can be found here: [LICENSE](https://github.com/IggsGrey/cella.js/blob/main/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
---
_Source: https://npm.io/package/cella.js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._