new PersistentStorage()
PersistentStorage is a small wrapper around localforage that adds TTL
expiration, optional in-memory caching, and per-key locking to prevent
concurrent writes from stepping on each other. Use the static `get()`
helper to ensure a single instance per namespace and schema version is
used.
- Since:
- Source:
Methods
clear(optionsopt) → {Promise.<void>}
Clear the entire store.
Parameters:
| Name |
Type |
Attributes |
Description |
options |
object
|
<optional>
|
Optional settings
Properties
| Name |
Type |
Attributes |
Description |
awaitLocks |
boolean
|
<optional>
|
Wait for in-flight lock operations
before clearing. Defaults to true. |
|
- Source:
Returns:
-
Type
-
Promise.<void>
clearExpired() → {Promise.<Array.<string>>}
Clear all expired records from the store.
- Source:
Returns:
Array of removed keys
-
Type
-
Promise.<Array.<string>>
getItem(key) → {Promise.<(*|null)>}
Get only the stored value for a key.
Parameters:
| Name |
Type |
Description |
key |
string
|
The storage key |
- Source:
Returns:
The stored value, or null if not found/expired
-
Type
-
Promise.<(*|null)>
getRecord(key) → {Promise.<(object|null)>}
Get the full record (value + metadata) for a key.
Parameters:
| Name |
Type |
Description |
key |
string
|
The storage key |
- Source:
Returns:
The record, or null if not found/expired
-
Type
-
Promise.<(object|null)>
hasRecord(key) → {Promise.<boolean>}
Check if a record exists and is not expired for a given key. It will
return true for non-expired records even when the value is falsey
Parameters:
| Name |
Type |
Description |
key |
string
|
The storage key |
- Source:
Returns:
True if the record exists
-
Type
-
Promise.<boolean>
isExpired(record) → {boolean}
Determine if a record is expired. (Instance method version that calls the
static method for convenience.)
Parameters:
| Name |
Type |
Description |
record |
object
|
The record to check |
- Source:
Returns:
True if expired
-
Type
-
boolean
keys() → {Promise.<Array.<string>>}
Get all keys in the store.
- Source:
Returns:
Array of keys
-
Type
-
Promise.<Array.<string>>
length() → {Promise.<number>}
Get the number of keys in the store.
- Source:
Returns:
Number of keys
-
Type
-
Promise.<number>
removeItem(key) → {Promise.<void>}
Remove a key from storage.
Parameters:
| Name |
Type |
Description |
key |
string
|
The storage key |
- Source:
Returns:
-
Type
-
Promise.<void>
setItem(key, value, optionsopt) → {Promise.<*>}
Persist a value with optional TTL override.
Parameters:
| Name |
Type |
Attributes |
Description |
key |
string
|
|
The storage key |
value |
*
|
|
The value to store |
options |
object
|
<optional>
|
Optional settings
Properties
| Name |
Type |
Attributes |
Description |
ttlMs |
number
|
null
|
<optional>
|
TTL in milliseconds. Null disables
expiration. |
|
- Source:
Returns:
The saved value
-
Type
-
Promise.<*>
withLock(key, fn, onPreviousErroropt) → {Promise.<*>}
Serialize otherwise async operations for a given key. For example, use
this to avoid concurrent writes to IndexedDB/localForage for the same
PID. Each new job is chained onto the promise of the previous job for
that key. Calls for different keys run independently.
Important:
- Concurrency is only controlled within the same JS environment (same
tab, worker, or process). This does not synchronize work across
multiple browser tabs or windows.
- You must pass a shared locks Map instance. If each caller creates its
own Map, locking will not work.
Parameters:
| Name |
Type |
Attributes |
Default |
Description |
key |
string
|
|
|
The lock name. All calls sharing this key are
serialized. |
fn |
function
|
|
|
The async or sync function to run once any previous
jobs for this key complete. May return a value or a Promise. |
onPreviousError |
function
|
<optional>
|
null
|
Callback invoked with errors from
earlier jobs in the chain. |
- Source:
Returns:
The resolved value of fn.
-
Type
-
Promise.<*>
buildInstanceKey(options) → {string}
Build a unique namespace string for the PersistentStorage instance based
on the options provided to the constructor. This is used to create
singleton instances of PersistentStorage, so that different parts of the
app can share the same store if they use the same options.
Parameters:
| Name |
Type |
Description |
options |
object
|
Options for the PersistentStorage instance |
- Source:
Returns:
The namespace string
-
Type
-
string
Get a singleton PersistentStorage instance for the provided namespace and
schema version.
Parameters:
| Name |
Type |
Description |
options |
object
|
Options for the PersistentStorage instance |
- Source:
Returns:
The PersistentStorage instance
-
Type
-
PersistentStorage
isExpired(record) → {boolean}
Determine if a record is expired.
Parameters:
| Name |
Type |
Description |
record |
object
|
The record to check |
- Source:
Returns:
True if expired
-
Type
-
boolean
isQuotaError(e) → {boolean}
Detect quota errors across storage backends.
Parameters:
| Name |
Type |
Description |
e |
Error
|
string
|
The error to check |
- Source:
Returns:
True if the error indicates a quota/exceeded storage
condition
-
Type
-
boolean
normalizeOptions(options) → {object}
Normalize the options for creating a PersistentStorage instance.
Parameters:
- Source:
Returns:
Options with defaults applied and values standardized
-
Type
-
object
sanitizeNamespacePart(part) → {string}
Normalize a string so it is safe to use in a PersistentStorage namespace.
Parameters:
| Name |
Type |
Description |
part |
string
|
A part of a namespace |
- Source:
Returns:
Sanitized part
-
Type
-
string