sharemd.sh NhyZ0Mvy · v1

Reference: pixeldb API

A complete reference of every method exported by the pixeldb package. For a higher-level overview, see the README.

open(path, options?)

Opens (or creates) a database file at path.

Parameters

Name Type Required Description
path string yes Path to the .pxl file. Created if missing.
options.cacheSize number no Max in-memory entries. Default 1000.
options.fsync boolean no fsync after every write. Default true.
options.compression "none" | "lz4" no Default "none".

Returns

Promise<Database> — resolves once the file is open and the index is loaded.

Example

import { open } from "pixeldb";

const db = await open("./users.pxl", {
  cacheSize: 5000,
  fsync: true,
});

console.log(`opened with ${await db.size()} entries`);

db.set(key, value)

Stores a value at the given key. Replaces any existing value.

await db.set("session:abc", {
  userId: 42,
  createdAt: Date.now(),
});

Values are JSON-serialized internally — anything that survives a round-trip through JSON.stringify is fair game.

db.get(key)

Retrieves the value at key, or null if the key doesn't exist.

const session = await db.get("session:abc");
if (!session) throw new Error("expired");

db.delete(key)

Removes a key. Returns true if the key existed, false otherwise.

db.close()

Flushes pending writes, releases the file handle, and frees the index. After calling close() the database is unusable — calling any other method throws.

⚠️ Always await close() in tests and short-lived scripts. Without it, Node may exit before the final fsync completes and you'll lose the last few writes.

Errors

PixelDB throws these specific error classes — all extend the base PixelError: