Stores
Where Kaji records requests and results, and how to write your own store.
Kaji needs a store to remember which requests it has seen and what happened. Pass one to createKaji():
const kaji = createKaji({ store: memoryStore() });
Memory store
Keeps records in memory. It is meant for development, tests, and examples. It only works inside one process, and it loses everything when the process exits.
Custom stores
For production, write a store backed by a database. A store has two methods:
type ExecutionStore = {
claim(claim: ExecutionClaim): Promise<ClaimResult>;
record(execution: StoredExecution): Promise<void>;
};
claim() is called for every request, right after input validation:
type ExecutionClaim = {
readonly capability: string;
readonly principalId: string;
readonly idempotencyKey: string;
readonly inputFingerprint: string;
};
type ClaimResult =
| { status: "claimed"; executionId: string }
| { status: "existing"; outcome: Promise<StoredExecution> }
| { status: "conflict"; executionId: string };
claimed: a new request. Kaji goes ahead.existing: the same request was already made. Return its saved result, or a promise for it if it is still running. If the original request runs in another process, the promise must resolve once that process records its result.conflict: the same capability,principalId, andidempotencyKeycame with different input (itsinputFingerprint, a hash of the validated input, differs).
If two callers send the same new request at once, exactly one must get claimed. Use a unique constraint or a transaction.
record() saves the final result of a claimed request. It must never overwrite a result that is already saved, in particular never replace unknown with something else.
Example: SQLite store
This store keeps records in one SQLite file, so every process on the machine that opens the file shares them. It uses Bun’s built-in bun:sqlite.
import { Database } from "bun:sqlite";
import type { ClaimResult, ExecutionClaim, ExecutionStore, StoredExecution } from "@hiyorios/kaji";
const MAX_WAIT_MS = 30_000;
export function sqliteStore(db: Database): ExecutionStore {
// Let several processes share one file: wait for locks instead of failing.
db.run("PRAGMA busy_timeout = 5000");
db.run("PRAGMA journal_mode = WAL");
db.run(`CREATE TABLE IF NOT EXISTS kaji_executions (
capability TEXT NOT NULL,
principal_id TEXT NOT NULL,
idempotency_key TEXT NOT NULL,
input_fingerprint TEXT NOT NULL,
execution_id TEXT NOT NULL,
outcome TEXT,
PRIMARY KEY (capability, principal_id, idempotency_key)
)`);
const insert = db.query(
`INSERT OR IGNORE INTO kaji_executions
(capability, principal_id, idempotency_key, input_fingerprint, execution_id)
VALUES (?, ?, ?, ?, ?)`,
);
const select = db.query(
`SELECT input_fingerprint, execution_id, outcome FROM kaji_executions
WHERE capability = ? AND principal_id = ? AND idempotency_key = ?`,
);
const update = db.query(
`UPDATE kaji_executions SET outcome = ? WHERE execution_id = ? AND outcome IS NULL`,
);
type Row = { input_fingerprint: string; execution_id: string; outcome: string | null };
const read = (claim: ExecutionClaim) =>
select.get(claim.capability, claim.principalId, claim.idempotencyKey) as Row;
return {
async claim(claim: ExecutionClaim): Promise<ClaimResult> {
const { changes } = insert.run(
claim.capability,
claim.principalId,
claim.idempotencyKey,
claim.inputFingerprint,
crypto.randomUUID(),
);
const row = read(claim);
if (changes === 1) return { status: "claimed", executionId: row.execution_id };
if (row.input_fingerprint !== claim.inputFingerprint) {
return { status: "conflict", executionId: row.execution_id };
}
return { status: "existing", outcome: waitForOutcome(claim) };
},
async record(execution: StoredExecution): Promise<void> {
let json: string;
try {
json = serialize(execution);
} catch (cause) {
// The result cannot be stored (for example a bigint). Save an
// `unknown` so duplicates do not wait for a result that never
// comes, then fail so the caller gets `unknown` too.
update.run(
serialize({
status: "unknown",
error: new Error("The result could not be saved."),
evidence: execution.evidence,
}),
execution.evidence.executionId,
);
throw cause;
}
const { changes } = update.run(json, execution.evidence.executionId);
if (changes !== 1) throw new Error("No open claim to record.");
},
};
async function waitForOutcome(claim: ExecutionClaim): Promise<StoredExecution> {
const deadline = Date.now() + MAX_WAIT_MS;
for (;;) {
const row = read(claim);
if (row.outcome !== null) return JSON.parse(row.outcome);
if (Date.now() >= deadline) {
// The original request never recorded a result, for example
// because its process crashed. Report `unknown`, not a guess.
return {
status: "unknown",
error: new Error("The original request did not record a result."),
evidence: {
executionId: row.execution_id,
capability: claim.capability,
principalId: claim.principalId,
idempotencyKey: claim.idempotencyKey,
inputFingerprint: claim.inputFingerprint,
},
};
}
await new Promise((resolve) => setTimeout(resolve, 50));
}
}
}
function serialize(execution: StoredExecution): string {
return JSON.stringify(execution, (_key, value) =>
value instanceof Error ? { name: value.name, message: value.message } : value,
);
}
How it meets the contract:
- Atomic claim. The primary key on
(capability, principal_id, idempotency_key)makesINSERT OR IGNOREsucceed for exactly one caller. Everyone else reads the existing row and getsexistingorconflict. - Waiting. An
existingcaller polls untilrecord()fills inoutcome. If the original never records, for example because its process crashed, the poll gives up after 30 seconds and returnsunknown. - Record once.
UPDATE ... WHERE outcome IS NULLnever overwrites a saved result, includingunknown. - Locking.
busy_timeoutand WAL mode make concurrent processes wait for each other instead of failing with “database is locked”. Setbusy_timeoutfirst.bun:sqliteis synchronous, so a long wait blocks the event loop. - Unsavable results. If a result cannot be turned into JSON (a
bigint, for example), the store savesunknownand fails, so Kaji reportsunknownand duplicates do not wait. - Errors.
erroris stored as{ name, message }, so a replayed result carries a plain object, not the originalError. Dates and other non-JSON values inresultcome back as their JSON form.
In a test, 8 processes sharing one file sent 1,600 requests for 200 actions, and each action ran exactly once. SQLite suits a single machine. For several machines use Postgres or MySQL with the same structure: a unique key on the identity, an insert that does nothing on conflict, and a conditional update.
Production checklist
Check that your store:
- claims atomically, so concurrent duplicates get one
claimed - is shared by every process that runs the capability
- keeps its records across restarts
- has a plan for requests that were claimed but never recorded, such as a process that crashed mid-action
- has a plan for how long to keep records
Failures
If claim() fails, kaji.execute() rejects with a KajiConfigurationError and nothing ran. If record() fails, you get unknown, because the action may already have run.