README

@feathersjs-offline/localforage

@featherjs-offline/localforage is a database service adapter wrapping localForage that persists to either IndexedDB, WebSQL, or LocalStorage making it very useful for mobile and offline-first applications with the additional ability to seamlessly handle Blobs, TypedArrays, and other JS objects.

$ npm install --save @feathersjs-offline/localforage

Important: @feathersjs-offline/localforage implements the Feathers Common database adapter API and querying syntax.

API

`service(options)`

Returns a new service instance initialized with the given options.

const service = require('@feathersjs-offline/localforage');

app.use('/messages', service({
  storage: ['IndexedDB', 'localStorage']
}));
app.use('/messages', service({ storage, id, startId, name, store, paginate }));

Options:

storage (optional, default: 'INDEXEDDB') - The storage backend. Must be one or more of 'INDEXEDDB', 'WEBSQL', or 'LOCALSTORAGE'. The adapter will use the same sequence as fall-back if the desired storage type is not supported on the actual device. Alternatively, you can supply an array of storage backends determining the priority of your choice.
version (optional, default: 1.0) - localforage driver version to use. Currently only 1.0 exists.
size (optional, default 4980736) - The maximum database size required. Default DB size is JUST UNDER 5MB, as it's the highest size we can use without a prompt in any browser.
id (optional, default: 'id') - The name of the id field property.
name (optional, default: 'feathers') - The key to store data under in local or async storage.
store (optional) - An object with id to item assignments to pre-initialize the data store.
dates (optional, default false) - Convert ISO-formatted date strings to Date objects in result sets.
events (optional) - A list of custom service events sent by this service.
paginate (optional) - A pagination object containing a default and max page size.
whitelist (optional) - A list of additional query parameters to allow.
multi (optional) - Allow create with arrays and update and remove with id null to change multiple items. Can be true for all methods or an array of allowed methods (e.g. [ 'remove', 'create' ]).
reuseKeys (optional, default: false) Allow duplicate keys (see name) i.e. last definition wins. Mostly useful for demonstration and testing purposes.

Storing Blobs, TypedArrays, and other JS objects

As this is an implementation on top of localForage you can store any type in @feathersjs-offline/localforage; you aren't limited to strings like in localStorage. Even if localStorage is your storage backend, @feathersjs-offline/localforage automatically does JSON.parse() and JSON.stringify() when getting/setting values.

feathers-localforage supports storing all native JS objects that can be serialized to JSON, as well as ArrayBuffers, Blobs, and TypedArrays. Check the localForage API docs for a full list of types supported. In addition, setting the option dates to true will make sure any ISO-formatted dates in your results will in fact be date objects and not text strings.

All types are supported in every storage backend, though storage limits in localStorage make storing many large Blobs impossible.

We default to indexedDB if available and fall-back to localStorage as a last resort.

Example

See the clients chapter for more information about using Feathers in the browser and React Native.

Browser

<script type="text/javascript" src="//unpkg.com/@feathersjs/client@^4.5.11/dist/feathers.js"></script>
<script type="text/javascript" src="//unpkg.com/@feathersjs-offline/localforage@^1.0.0/dist/localforage.js"></script>
<script type="text/javascript">
  var service = feathersjsOfflineLocalforage.init({
    storage: ['indexeddb', 'websql', 'localStorage']
  });
  var app = feathers().use('/messages', service);

  var messages = app.service('messages');

  messages.on('created', function(message) {
    console.log('Someone created a message', message);
  });

  messages.create({
    text: 'Message created in browser'
  });
</script>

License

Licensed under the MIT license.

Usage no npm install needed!