Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lcavadas/browser-storage-js

Javascript library that wraps storage logic ( localStorage, WebSQL, IndexedDB) for all browsers.
https://github.com/lcavadas/browser-storage-js

Last synced: 3 months ago
JSON representation

Javascript library that wraps storage logic ( localStorage, WebSQL, IndexedDB) for all browsers.

Lists

README 

        
# Browser Storage JS



JavaScript Library for Cross Browser Persistence using WebStorage (LocalStorage, SessionStorage, WebSQL and IndexedDB) for all browsers.



Basically it allows us to use any of the storage technologies in a standard way.



## Usage



Note: All objects are expected to have a unique ID in a property called ```id```.



### Get the instance

The simplest way to get an instance is to call the function 



```

storage(readyCallback [, type])

```



* readyCallback - Callback that is called when the storage is ready. The passed function receives the instance of the common API and should be used to retrieve it. function(SJS sjs){}

* type - This is an optional parameter that specifies which implementation of WebStorage you wish to use. I not specified the library will try to use IndexedDB falling back to WebSQL and LocalStorage if none of the previous two are available. Valid values are:

    * 'LocalStorage'

    * 'SessionStorage'

    * 'WebSQL'

    * 'IndexedDB'



### The SJS object

The SJS object is the central part of the library. This is the object that exposes, in a common way, the storage and retrieval operations.



The possible operations are set, setAll, get, getAll, remove, removeAll and close.



#### set

Stores an object of a given entity. If an object with the same id exists it updates the stored object.



```

set(entity, value, callback)

```



* entity - Name of the entity to which this object should be associated.

* value - The Object to be stored.

* callback - Function called when the operation is complete. This function does not pass parameters.



#### setAll

Stores all objects of a given entity. If objects with the same ids exist it updates the stored objects.



```

setAll(entity, values, callback)

```



* entity - Name of the entity to which these objects should be associated.

* value - The Objects to be stored, in an array.

* callback - Function called when the operation is complete. This function does not pass parameters.



#### get

Retrieves a specified object of a given entity. This function has no return. The results are passed through the callback.



```

get(entity, id, callback)

```



* entity - Name of the entity from which you want to retrieve the object.

* id - The id of the object to be retrieved.

* callback - Function called when the operation is complete. The callback should be ```callback(sv){...}``` where sv is the retrieved object.



#### getAll

Retrieves all objects of a given entity. This function has no return. The results are passed through the callback.



```

getAll(entity, callback)

```



* entity - Name of the entity from which you wish to retrieve all entries.

* id - The id of the object to be retrieved.

* callback - Function called when the operation is complete. The callback should be ```callback(svs){...}``` where svs is an array of the retrieved objects.



#### remove



Removes a specific entry for a given entity.



```

remove(entity, id, callback)

```



* entity - Name of the entity from which you wish to remove the identified entry.

* id - The id of the object to be removed.

* callback - Function called when the operation is complete. This function does not pass parameters.



#### removeAll

Removes all the extries for a given entity.



```

removeAll(entity, callback)

```



* entity - Name of the entity from which you wish to remove all entries.

* id - The id of the object to be retrieved.

* callback - Function called when the operation is complete. This function does not pass parameters.



#### close

Closes the database connection. While this is not important for all implementations, it is good practice to close it if you no longer need it.



```

close()

```



## Practical examples

For practical example consult the unit tests. The unit tests can be run here. The source code for the tests can be viewed here.



## Known Limitations

If IndexedDB is used only one connection can be established at a given time as external upgrades are not yet implemented.



## Future Versions

* Implement the capability of external upgrades under IndexedDB.

* Allow the indexing of fields other than the object's id.

* Ability to query by something more than the object's id.



## Version History

ver 1.1.1:

Fixing issues arising from the non-existance of the underlying collection.



ver 1.1.0:

Improved the IndexedDB implementation and made it compatible with latest changes.



ver 1.0.0:

Added a minified version.



ver 0.1.0:

First working version of the API that is able to run the four implementations of WebStorage.