README
Adobe I/O Lib State
A JavaScript abstraction on top of distributed/cloud DBs that exposes a simple state persistence API.
You can initialize the lib with your Adobe I/O Runtime (a.k.a OpenWhisk) credentials.
Alternatively, you can bring your own cloud db keys. As of now we only support Azure Cosmos.
Install
npm install @adobe/aio-lib-state
Use
const stateLib = require('@adobe/aio-lib-state')
// init
// init sdk using OpenWhisk credentials
const state = await stateLib.init({ ow: { namespace, auth } })
// init when env vars __OW_API_KEY and __OW_NAMESPACE are set (e.g. when running in an OpenWhisk action)
const state = await stateLib.init()
// or if you want to use your own cloud DB account (make sure your partition key path is /partitionKey)
const state = await stateLib.init({ cosmos: { endpoint, masterKey, databaseId, containerId, partitionKey } })
// get
const res = await state.get('key') // res = { value, expiration }
const value = res.value
// put
await state.put('key', 'value')
await state.put('key', { anObject: 'value' }, { ttl: -1 }) // -1 for no expiry, defaults to 86400 (24 hours)
// delete
await state.delete('key')
Explore
goto
API
Debug
set DEBUG=@adobe/aio-lib-state*
to see debug logs.
Adobe I/O State Store Limitations (per user)
Apply when init with OW credentials (and not own cloud DB credentials):
- Max state value size:
2MB
- Max state key size:
1024 bytes
- Max total state size:
10 GB
- Token expiry (need to re-init after expiry):
1 hour
Adobe I/O State Store Consistency Guarantees
Strong consistency is guaranteed for reads and writes within a single instance of the state sdk (returned by stateLib.init()
).
However, operations across multiple instances are eventually consistent. For example, let's consider two state instances a
and b
initialized with the same credentials, then
await a.put('key', 'value')
await b.put('key', 'yolo')
console.log(await a.get('key'))
might log either value
or yolo
but eventually a.get('key')
will always return yolo
. Note that atomicity is ensured, i.e. a.get('key')
will never return something like valyoloue
.
Troubleshooting
"[StateLib:ERROR_INTERNAL] unknown error response from provider with status: unknown"
- when using
@adobe/aio-lib-state
in an action bundled with webpack please make sure to turn off minification and enable resolving of es6 modules. Add the following lines to your webpack config:
optimization: {
minimize: false
},
resolve: {
extensions: ['.js'],
mainFields: ['main']
}
Contributing
Contributions are welcomed! Read the Contributing Guide for more information.
Licensing
This project is licensed under the Apache V2 License. See LICENSE for more information.