Novices Performing Miracles

    @adobe/aio-lib-state
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • Public • Published

    Version Downloads/week Node.js CI License Codecov Coverage

    Adobe I/O Lib State

    A Node 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.

    Please note that currently you must be a customer of Adobe Developer App Builder to use this library. App Builder is a complete framework that enables enterprise developers to build and deploy custom web applications that extend Adobe Experience Cloud solutions and run on Adobe infrastructure.

    Install

    npm install @adobe/aio-lib-state

    Use

      const stateLib = require('@adobe/aio-lib-state')
    
      // init when running in an Adobe I/O Runtime action (OpenWhisk) (uses env vars __OW_API_KEY and __OW_NAMESPACE automatically)
      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
    • Non supported characters for state keys are: '/', '\', '?', '#'

    Adobe I/O State Store Consistency Guarantees

    Consistency across State Instances

    Operations across multiple State instances (returned by stateLib.init()) are eventually consistent. For example, let's consider two state instances a and b initialized with the same credentials, then

    const a = await state.init()
    const b = await state.init()
    await a.put('food', 'beans')
    await b.put('food', 'carrots')
    console.log(await a.get('food'))

    might log either beans or carrots but eventually a.get('food') will always return carrots.

    Operations within a single instance however are guaranteed to be strongly consistent.

    Note that atomicity is ensured, i.e. a.get('food') will never return something like beacarronsts.

    Adobe I/O Runtime considerations

    State lib is expected to be used in Adobe I/O Runtime serverless actions. A new State instance can be created on every new invocation inside the main function of the serverless action as follows:

    const State = require('@adobe/aio-sdk').State
    
    function main (params) {
      const state = await State.init()
      // do operations on state

    It's important to understand that in this case, on every invocation a new State instance is created, meaning that operations will be only eventually consistent across invocations but strongly consistent within an invocation.

    Also note that reusing the State instance by storing it in a global variable outside of the main function would not ensure strong consistency across all invocations as the action could be executed in a separate Docker container.

    Here is an example showcasing two invocations of the same action with an initial state { key: 'hello'}:

    Invocation A Invocation B
    state = State.init()
    state.get(key) => returns hello
    state.put(key, 'bonjour')
    state.get(key) => returns bonjour
    state = State.init()
    state.get(key) => hello OR bonjour
    state.put(key, 'bonjour')
    state.get(key) => returns bonjour

    Because of eventual consistency across State instances, in invocation B, the first state.get(key) might return an older value although invocation A has updated the value already.

    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.

    Install

    npm i @adobe/aio-lib-state

    DownloadsWeekly Downloads

    5,867

    Version

    2.1.0

    License

    Apache-2.0

    Unpacked Size

    114 kB

    Total Files

    32

    Last publish

    Collaborators

    • adobehalls
    • fullcolorcoder
    • marbec
    • tripod
    • garthdb
    • lazd
    • adobe-admin
    • patrickfulton
    • trieloff
    • shazron
    • krisnye
    • dcpfsdk
    • natebaldwin
    • devongovett
    • aspro83
    • symanovi
    • dpfister
    • stefan-guggisberg
    • korra
    • rofe
    • kptdobe