A persistent Map-compatible API backed by SQLite using Node.js's built-in node:sqlite module. No external database dependencies — just a file (or :memory:).
- Node.js >= 22.5.0 (for
node:sqlite)
npm install node-sqlite-map
# or
pnpm add node-sqlite-mapimport { SqliteMap } from "node-sqlite-map"
const map = new SqliteMap("./data.db")
map.set("user:1", { name: "Kyle", role: "admin" })
map.get("user:1") // { name: "Kyle", role: "admin" }
map.has("user:1") // true
map.size // 1Use :memory: for an in-memory database that does not persist:
const map = new SqliteMap(":memory:")new SqliteMap<K extends string, V>(path: string, options?: DatabaseSyncOptions)| Parameter | Type | Description |
|---|---|---|
path |
string |
Path to SQLite database file, or ":memory:" |
options |
DatabaseSyncOptions |
Optional Node.js DatabaseSync options |
Inserts or replaces a key-value pair. Returns this for chaining.
map.set("a", 1).set("b", 2).set("c", 3)Returns the value for the key, or undefined if not found.
map.get("a") // 1
map.get("z") // undefinedReturns true if the key exists.
map.has("a") // trueRemoves the entry. Returns true if it existed, false otherwise.
map.delete("a") // true
map.delete("a") // falseRemoves all entries.
map.clear()
map.size // 0Returns the existing value if the key exists, otherwise inserts defaultValue and returns it.
map.getOrInsert("count", 0) // inserts 0 and returns 0
map.getOrInsert("count", 99) // returns 0 (already exists)Like getOrInsert but the default value is computed lazily via a callback — only called if the key is missing.
map.getOrInsertComputed("slug", (key) => key.toLowerCase().replace(" ", "-"))All iteration methods reflect the insertion order of keys.
for (const key of map.keys()) console.log(key) // "a", "b", "c"
console.log([...map.keys()]) // ["a", "b", "c"]console.log([...map.values()]) // [1, 2, 3]console.log([...map.entries()]) // [["a", 1], ["b", 2], ["c", 3]]map.forEach((value, key, map) => {
console.log(key, value)
})Makes the map directly iterable — equivalent to entries().
for (const [key, value] of map) {
console.log(key, value)
}Returns the number of entries.
map.size // 3Returns a plain object representation. Called automatically by JSON.stringify.
map.set("x", 1)
map.toJSON() // { x: 1 }
JSON.stringify(map) // '{"x":1}'Returns "SqliteMap".
Object.prototype.toString.call(map) // "[object SqliteMap]"SqliteMap<K extends string, V>| Parameter | Constraint | Description |
|---|---|---|
K |
string |
Key type — must be a string |
V |
any | Value type — must be JSON-serializable |
Values are stored as JSON strings internally, so any JSON-serializable value is supported: objects, arrays, numbers, booleans, strings, null.
const cache = new SqliteMap<string, { data: unknown; expiresAt: number }>("./cache.db")
cache.getOrInsertComputed("api:users", () => ({
data: fetchUsers(),
expiresAt: Date.now() + 60_000
}))const hits = new SqliteMap<string, number>("./hits.db")
hits.getOrInsert("/home", 0)
hits.set("/home", (hits.get("/home") ?? 0) + 1)// To plain object
const obj = sqliteMap.toJSON()
// To native Map
const native = new Map(sqliteMap.entries())
// From array of entries
for (const [k, v] of entries) sqliteMap.set(k, v)| Feature | Map |
SqliteMap |
|---|---|---|
| Persistence | ❌ In-memory only | ✅ File-backed |
| Key type | Any | string only |
| Value type | Any | JSON-serializable |
| Iteration order | Insertion order | Insertion order |
JSON.stringify |
{} (empty) |
✅ Full object |
This project is licensed under the MIT License - see the LICENSE file for details.
| Resource | URL |
|---|---|
| GitHub repository | https://github.com/xcfio/node-sqlite-map |
| npm package | https://www.npmjs.com/package/node-sqlite-map |
| Homepage | https://github.com/xcfio/node-sqlite-map#readme |
| Bug reports | https://github.com/xcfio/node-sqlite-map/issues |
Join the community on Discord for help, and discussion:
Made with ❤️ by xcfio