A simple key-value store with node:sqlite.

⚠️ Node.js v22 or higher is required.

Installation

npm install node-sqlite-kv
# or
yarn add node-sqlite-kv
# or
pnpm add node-sqlite-kv
# or
bun add node-sqlite-kv

Example

import { JournalModes, KVSync } from "node-sqlite-kv"

// none of these options are required
const kv = new KVSync({
    // sqlite journal mode; defaults to DELETE for
    // in-memory stores, or WAL for persistent ones
    journalMode: JournalModes.WAL,

    // whether the database is open upon
    // being instantiated; defaults to true
    open: true,

    // defaults to :memory: (in-memory storage)
    path: "./data.sqlite",

    // override the default table name of "kv"
    // note: it's not recommended to use one file for
    // multiple key value stores; this is only
    // for the ability of changing the default name
    tableName: "kv",
})

// set values
kv.set("number", 123)
kv.set("string", "hello world")
kv.set("boolean", true)
kv.set("null", null)
kv.set("array", [1, 2, 3])
kv.set("object", { settings: { theme: "dark" } })
kv.set("date", new Date())

// get values
kv.get("number") // 123
kv.get("string") // "hello world"
kv.get("boolean") // true
kv.get("null") // null
kv.get("array") // [1, 2, 3]
kv.get("object") // { settings: { theme: "dark" } }
kv.get("date") // Date

// update values
kv.set("number", 999)
kv.get("number") // 999

// delete values
kv.delete("array")
kv.get("array") // undefined

// list all entries
kv.all()
// [
//      { key: "string", value: "hello world" },
//      { key: "number", value: 999 },
//      { key: "boolean", value: true },
//      // ...
// ];

// check if a key exists
kv.exists("string") // true
kv.exists("nonexistent") // false

// get total number of entries
kv.size() // 6

// get all keys
kv.keys() // ["string", "number", "boolean", "null", "object", "date"]

// get all values
kv.values() // ["hello world", 999, true, null, { settings: { theme: "dark" } }, Date]

// transactions
kv.set("user:1", { name: "Andrew", age: 19 })
kv.set("user:2", { name: "Josh", age: 22 })
kv.set("user:3", { name: "Gabe", age: 20 })

// ...store what changed in transactions
const { oldValues, newValues } = kv.transaction((tx) => {
    tx.set("user:1", { name: "Andrew", age: 20 })
    tx.set("user:4", { name: "Kris", age: 21 })
    tx.delete("user:2")
})

// delete all entries
kv.clear()

// close the database
kv.close()

TS Generics Example

import { KVSync } from "node-sqlite-kv"
const kv = new KVSync({ path: "./data.sqlite" })

interface User {
    name: string
}

kv.set("user", { name: "Andrew" })
kv.get<User>("user") // User | null

kv.set("example", 123)
kv.get<number>("example") // number | null

Contributing

pnpm is used throughout this project for packages and scripts. Pull requests are always welcome. For more major changes, please open an issue to discuss what you wish to change.

License

Unlicensed