char/avril

git clone https://git.t4t.associates/char/avril

Charlotte Somadd `avril:kv` module78f47482026-10-21

import {
  openKv,
  type KvAccess,
  type KvAtomic,
  type KvAtomicResult,
  type KvDatabase,
  type KvEntry,
  type KvKey,
  type KvKeyspace,
  type KvListOptions,
  type KvOpenOptions,
  type KvPathUrl,
  type KvValue,
  type KvVersionstamp,
} from "avril:kv";

const access: KvAccess = "exclusive";
const options: KvOpenOptions = { access, create: true };
const url: KvPathUrl = { href: "file:///tmp/kv.redb" };

const db: KvDatabase = await openKv("/tmp/kv.redb", options);
const same: KvDatabase = await openKv(url);
void same;

const space: KvKeyspace = db.keyspace("events");
const spaceName: string = space.name;
void spaceName;

const key: KvKey = "users:42";
const bytesKey: KvKey = new Uint8Array([1, 2, 3]);
void bytesKey;

const raw: Uint8Array | null = await space.get(key);
void raw;
const text: string | null = await space.getText(key);
void text;

const batch: (Uint8Array | null)[] = await space.getMany([key, "other"]);
void batch;
const textBatch: (string | null)[] = await space.getTextMany([key, "other"]);
void textBatch;

const entry: KvEntry | null = await space.entry(key);
if (entry !== null) {
  const stamp: bigint = entry.versionstamp;
  const owner: string = entry.keyspace;
  const back: Uint8Array = entry.key;
  const stored: Uint8Array = entry.value;
  void stamp;
  void owner;
  void back;
  void stored;
}

const entries: (KvEntry | null)[] = await space.entries([key, "other"]);
void entries;

const written: { readonly versionstamp: KvVersionstamp } = await space.set(key, "v1");
void written;
const writtenBytes: { readonly versionstamp: KvVersionstamp } = await space.set(
  new Uint8Array([9]),
  new Uint8Array([8]),
);
void writtenBytes;
await space.delete(key);
await space.clear();

const listOptions: KvListOptions = { prefix: "user:", limit: 10, reverse: true };
for await (const listed of space.list(listOptions)) {
  const again: KvEntry = listed;
  void again;
}
for await (const viaBytes of space.list({ prefix: new Uint8Array([117]) })) {
  const again: KvEntry = viaBytes;
  void again;
}

const names: string[] = await db.keyspaces();
void names;

const result: KvAtomicResult = await db.atomic((tx: KvAtomic) => {
  tx.check(space, key, null);
  tx.set(space, key, "1");
  tx.delete(space, "gone");
});
if (entry !== null) {
  await db.atomic((tx) => tx.check(space, key, entry.versionstamp));
}
if (result.ok) {
  const stamp: KvVersionstamp | null = result.versionstamp;
  void stamp;
}

const value: KvValue = "text";
void value;

const genericDefault: KvEntry = entry as KvEntry;
void genericDefault;

// @ts-expect-error get returns bytes, not an entry object.
const asEntry: { value: unknown } = await space.get(key);
void asEntry;
// @ts-expect-error getText returns a string, not an entry object.
const asTextEntry: { value: Uint8Array } = await space.getText(key);
void asTextEntry;
// @ts-expect-error openKv requires a path.
await openKv(42);
// @ts-expect-error keyspace names must be strings.
db.keyspace(1);
// @ts-expect-error set rejects numbers.
await space.set("k", 42);
// @ts-expect-error set rejects objects.
await space.set("k", { nested: true });
// @ts-expect-error get rejects numbers.
await space.get(42);
// @ts-expect-error versionstamp is a bigint, not a number.
const numberStamp: KvVersionstamp = 42;
void numberStamp;
// @ts-expect-error versionstamp is a bigint, not a string.
const stringStamp: KvVersionstamp = "1";
void stringStamp;
if (entry !== null) {
  // @ts-expect-error versionstamps do not narrow to strings.
  const asString: string = entry.versionstamp;
  // @ts-expect-error versionstamps do not narrow to numbers.
  const asNumber: number = entry.versionstamp;
  void asString;
  void asNumber;
}
await db.atomic((tx) => {
  // @ts-expect-error check expects a bigint stamp or null.
  tx.check(space, key, "1");
});
// @ts-expect-error list limit must be a number.
space.list({ limit: "many" });
// @ts-expect-error list options must be an object.
space.list(42);
// @ts-expect-error access must be a valid mode.
await openKv("/tmp/kv.redb", { access: "sometimes" });