@feathersjs-offline/localforage
v1.1.1
Published
A FeathersJS client side service based on localforage that persists to IndexedDB, WebSQL, or LocalStorage
Downloads
5,108
Maintainers
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 only1.0
exists.size
(optional, default4980736
) - 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, defaultfalse
) - Convert ISO-formatted date strings toDate
objects in result sets.events
(optional) - A list of custom service events sent by this service.paginate
(optional) - A pagination object containing adefault
andmax
page size.whitelist
(optional) - A list of additional query parameters to allow.multi
(optional) - Allowcreate
with arrays andupdate
andremove
withid
null
to change multiple items. Can betrue
for all methods or an array of allowed methods (e.g.[ 'remove', 'create' ]
).reuseKeys
(optional, default:false
) Allow duplicate keys (seename
) 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
Copyright (c) 2021 by Feathers
Licensed under the MIT license.