National Puppy Menace

    idb-kv

    2.1.1 • Public • Published

    Idb-kv

    Greenkeeper badge Travis badge standard badge npm

    IndexedDB Key Value Store

    A tiny and simple API for IndexedDB with automatic batching for out of the box performance.

    All operations called within a 10ms interval are queued and executed in a single batch transaction. This improves performance when lots of reads and/or writes are performed quickly.

    Goals

    • Simple and small API
    • Minimize bundle size
    • Good performance
    • Fully tested

    Usage

    Install

    $ npm install idb-kv

    Require

    let Idbkv = require('idb-kv')
     
    let store = new Idbkv('example-store')
     
    store.set('animals', ['dog', 'cat', 'koala', 'moose', 'chinchilla'])
    store.set('pastas', ['spaghetti', 'linguine', 'macaroni', 'fettuccine'])
    const animals = await store.get('animals')
    animals[2] // >> 'koala'
    // new Session
    let Idbkv = require('idb-kv')
     
    let store = new Idbkv('example-store') // using the same name loads previous data
     
    const pastas = await store.get('pastas')
    pastas[1] // >> "linguine"

    Batching

    Because actions are batched, you only have to listen to a single promise for every set or delete in a synchronous block of code because they all share a common promise that indicates the success or failure of the entire batch transaction.

    This may provide a performance benefit with a large number of writes by eliminating promise handler overhead.

    store.set(0, 'first')
    store.set(1, 'second')
    store.set(2, 'third')
    store.set(3, 'fourth')
    store.delete(3)
      .then(() => console.log('all 4 sets and delete completed successfully'))

    The order of actions is maintained when batching.

    store.delete(0)
    store.get(0) // resolves with >> undefined
    store.set(0, 'first')
    store.get(0) // resolves with >> "first"

    API

    new Idbkv(dbName, [{batchInterval: 10}])

    let store = new Idbkv('example-store')
     
    // this store will gather actions for 1000ms before executing a transaction
    let slowStore = new Idbkv('slow-store', {batchInterval: 1000})

    Create a new Idbkv store instance using indexedDB.open(dbName) for data. Two instances created with the same name will use the same data store.

    batchInterval is the number of milliseconds to wait for more actions before a batch transaction is performed. The default is 10ms. Higher values improve batching, but also increase the delay for actions to complete including get().

    async get(key)

    Read a value from the store

    store.get('animals') // resolves with >> ['dog', 'cat', 'koala', 'moose', 'chinchilla']
    store.get('nonexistent') // resolves with >> undefined

    Returns a promise that resolves with the value corresponding to key, or rejects due to errors thrown by IndexedDB.

    If the key doesn't exist in the database, then get() resolves with undefined.

    async set(key, value)

    Write a value to the store

    store.set('pastas', ['spaghetti', 'linguine', 'macaroni', 'fettuccine'])
    const pastas = await store.get('pastas')
    pastas[1] // >> "linguine"

    Returns a promise that resolves when the data is successfully written to the disk, or rejects on IndexedDB errors.

    async delete(key)

    Remove a value from the store

    let store = new Idbkv('example-store')
    store.set('pastas', ['spaghetti', 'linguine', 'macaroni', 'fettuccine'])
    store.delete('pastas')
    store.get('pastas') // resolves with >> undefined

    Returns a promise that resolves when the data is successfully deleted from the disk or rejects on indexedDB errors.

    async destroy()

    Delete the database, and tear down the Idbkv instance

    let store = new Idbkv('example-store')
    store.get('color') // resolves with >> "blue"
    await store.destroy()
     
    store = new Idbkv('example-store')
    store.get('color') // resolves with >> undefined

    Closes and then deletes the underlying IndexedDB database. This is basically equivalent to calling store.delete() on every existing key in the store.

    Returns a promise that resolves when the database is successfully deleted or rejects on an error.

    Install

    npm i idb-kv

    DownloadsWeekly Downloads

    5

    Version

    2.1.1

    License

    MIT

    Unpacked Size

    17.1 kB

    Total Files

    6

    Last publish

    Collaborators

    • kayleepop