"LargeLocalStorage" Methods
LargeLocalStorage(config) - Constructor
LargeLocalStorage (or LLS) gives you a large capacity (up to several gig with permission from the user) key-value store in the browser.
For storage, LLS uses the FilesystemAPI when running in Crome and Opera, InexedDB in Firefox and IE and WebSQL in Safari.
When IndexedDB becomes available in Safari, LLS will update to take advantage of that storage implementation.
Upon construction a LargeLocalStorage (LLS) object will be immediately returned but not necessarily immediately ready for use.
A LLS object has an initialized property which is a promise
that is resolved when the LLS object is ready for us.
Usage of LLS would typically be:
var storage = new LargeLocalStorage({size: 75*1024*1024});
storage.initialized.then(function(grantedCapacity) {
// storage ready to be used.
});The reason that LLS may not be immediately ready for use is that some browsers require confirmation from the user before a storage area may be created. Also, the browser's native storage APIs are asynchronous.
If an LLS instance is used before the storage area is ready then any calls to it will throw an exception with code: "NO_IMPLEMENTATION"
This behavior is useful when you want the application to continue to function--regardless of whether or not the user has allowed it to store data--and would like to know when your storage calls fail at the point of those calls.
LLS-contrib has utilities to queue storage calls until the implementation is ready. If an implementation is never ready this could obviously lead to memory issues which is why it is not the default behavior.
config (Object): {size: sizeInByes, [forceProvider: force a specific implementation]}(LargeLocalStorage):
var desiredCapacity = 50 * 1024 * 1024; // 50MB
var storage = new LargeLocalStorage({
// desired capacity, in bytes.
size: desiredCapacity,
// optional name for your LLS database. Defaults to lls.
// This is the name given to the underlying
// IndexedDB or WebSQL DB or FSAPI Folder.
// LLS's with different names are independent.
name: 'myStorage'
// the following is an optional param
// that is useful for debugging.
// force LLS to use a specific storage implementation
// forceProvider: 'IndexedDB' or 'WebSQL' or 'FilesystemAPI'
});
storage.initialized.then(function(capacity) {
if (capacity != -1 && capacity != desiredCapacity) {
// the user didn't authorize your storage request
// so instead you have some limitation on your storage
}
})
lls.getAllAttachments([docKey])
Gets all of the attachments for a document.
docKey (String): Identifies the document. Defaults to __emptydoc__(Promise): Promise that is resolved with all of the attachments for the given document.
storage.getAllAttachments('exampleDoc').then(function(attachEntries) {
attachEntries.map(function(entry) {
var a = entry.data;
// do something with it...
if (a.type.indexOf('image') == 0) {
// show image...
} else if (a.type.indexOf('audio') == 0) {
// play audio...
} else ...
})
})
lls.getAllAttachmentURLs([docKey])
Gets all attachments URLs for a document.
docKey (String): Identifies the document. Defaults to the __emptydoc__ document.(Promise): Promise that is resolved with all of the attachment urls for the given doc.
storage.getAllAttachmentURLs('exampleDoc').then(function(urlEntries) {
urlEntries.map(function(entry) {
var url = entry.url;
// do something with the url...
})
})
lls.getAttachment([docKey], attachKey)
Get the attachment identified by docKey and attachKey
docKey (String): Defaults to __emptydoc__attachKey (String): key of the attachment(Promise): fulfilled with the attachment or rejected if it could not be found. code: 1
storage.getAttachment('exampleDoc', 'examplePic').then(function(attachment) {
var url = URL.createObjectURL(attachment);
var image = new Image(url);
document.body.appendChild(image);
URL.revokeObjectURL(url);
})
lls.getAttachmentURL([docKey], attachKey)
Get the URL for a given attachment.
docKey (String): Identifies the document. Defaults to __emptydoc__attachKey (String): Identifies the attachment.(Promose): promise that is resolved with the attachment url.
storage.getAttachmentURL('myDoc', 'myPic').then(function(url) {
var image = new Image();
image.src = url;
document.body.appendChild(image);
storage.revokeAttachmentURL(url);
})This is preferrable to getting the attachment and then getting the
URL via createObjectURL (on some systems) as LLS can take advantage of
lower level details to improve performance.
lls.getCapacity()
Returns the actual capacity of the storage or -1 if it is unknown. If the user denies your request for storage you'll get back some smaller amount of storage than what you actually requested.
TODO: return an estimated capacity if actual capacity is unknown? -Firefox is 50MB until authorized to go above, -Chrome is some % of available disk space, -Safari unlimited as long as the user keeps authorizing size increases -Opera same as safari?
(Number): Capacity, in bytes, of the storage. -1 if unknown.
// the initialized property will call you back with the capacity
storage.initialized.then(function(capacity) {
console.log('Authorized to store: ' + capacity + ' bytes');
});
// or if you know your storage is already available
// you can call getCapacity directly
storage.getCapacity()
lls.getContents(docKey)
Get the contents of a document identified by docKey
TODO: normalize all implementations to allow storage
and retrieval of JS objects?
docKey (String): (Promise): resolved with the contents when the get completes
storage.getContents('exampleDoc').then(function(contents) {
alert(contents);
});
lls.ls([docKey])
List all attachments under a given key.
List all documents if no key is provided.
Returns a promise that is fulfilled with the listing.
docKey (String): (Promise): resolved with the listing, rejected if the listing fails.
storage.ls().then(function(docKeys) {
console.log(docKeys);
})
lls.ready()
Whether or not LLS is ready to store data.
The initialized property can be used to
await initialization.
():
// may or may not be true
storage.ready();
storage.initialized.then(function() {
// always true
storage.ready();
})
lls.revokeAttachmentURL(url)
Revoke the attachment URL as required by the underlying storage system.
This is akin to URL.revokeObjectURL(url)
URLs that come from getAttachmentURL or getAllAttachmentURLs
should be revoked by LLS and not URL.revokeObjectURL
url (String): The URL as returned by getAttachmentURL or getAttachmentURLs(Void):
storage.getAttachmentURL('doc', 'attach').then(function(url) {
// do something with the URL
storage.revokeAttachmentURL(url);
})
lls.rm(docKey)
Remove the specified document and all of its attachments.
Returns a promise that is fulfilled when the removal completes.
If no docKey is specified, this throws an error.
To remove all files in LargeLocalStorage call
lls.clear();
To remove all attachments that were written without
a docKey, call lls.rm('__emptydoc__');
rm works this way to ensure you don't lose data due to an accidently undefined variable.
docKey (String): (Promise): resolved when removal completes, rejected if the removal fails.
stoarge.rm('exampleDoc').then(function() {
alert('doc and all attachments were removed');
})
lls.rmAttachment(docKey, attachKey)
Remove an attachment from a document.
docKey (String): attachKey (String): (Promise): Promise that is resolved once the remove completes
storage.rmAttachment('exampleDoc', 'someAttachment').then(function() {
alert('exampleDoc/someAttachment removed');
}).catch(function(e) {
alert('Attachment removal failed: ' + e);
});
lls.setAttachment([docKey], attachKey, attachment)
Set an attachment for a given document. Identified
by docKey and attachKey.
docKey (String): Defaults to __emptydoc__attachKey (String): key for the attachmentattachment (Any): data(Promise): resolved when the write completes. Rejected if an error occurs.
storage.setAttachment('myDoc', 'myPic', blob).then(function() {
alert('Attachment written');
})
lls.setContents(docKey, data)
Set the contents identified by docKey to data.
The document will be created if it does not exist.
docKey (String): data (Any): (Promise): fulfilled when set completes
storage.setContents('exampleDoc', 'some data...').then(function() {
alert('doc written');
});