ocel 0.0.1-alpha.1 → 0.0.1

package/dist/kv/entries.js

@@ -0,0 +1,325 @@
+import { declarationSite } from "../declaration/callsite.js";
+import { describeIssues } from "../env/standard.js";
+import { KvShape } from "../gen/proto/app/resources/v1/resources_pb.js";
+import { InvalidKVValueError } from "./errors.js";
+import { buildKey, hasParameters, parsePattern, } from "./pattern.js";
+import { parseTTL, resolveTTL } from "./ttl.js";
+export const shapes = {
+    text: KvShape.TEXT,
+    counter: KvShape.COUNTER,
+    json: KvShape.JSON,
+    list: KvShape.LIST,
+    set: KvShape.SET,
+};
+export function declareEntry(shape, pattern, options) {
+    const declaration = { shape, pattern };
+    declared.set(declaration, {
+        shape,
+        pattern,
+        parsed: parsePattern(pattern),
+        ttl: options.ttl === undefined ? undefined : parseTTL(options.ttl),
+        schema: options.schema,
+        missOnInvalid: options.onInvalid === "miss",
+        source: declarationSite(),
+    });
+    return declaration;
+}
+const declared = new WeakMap();
+export function readDeclaredEntry(declaration) {
+    const found = declared.get(declaration);
+    if (!found) {
+        throw new TypeError("an entry of a store is declared with kv.text, kv.counter, kv.json, kv.list or kv.set");
+    }
+    return found;
+}
+class Entry {
+    name;
+    declaration;
+    openClient;
+    keyed;
+    constructor(name, declaration, openClient) {
+        this.name = name;
+        this.declaration = declaration;
+        this.openClient = openClient;
+        this.keyed = hasParameters(declaration.parsed);
+    }
+    open(operation) {
+        return this.openClient(`${this.name}.${operation}`);
+    }
+    split(args) {
+        if (!this.keyed)
+            return [buildKey(this.declaration.parsed, undefined), args];
+        const [key, ...rest] = args;
+        return [buildKey(this.declaration.parsed, key), rest];
+    }
+    keyOf(key) {
+        return buildKey(this.declaration.parsed, key);
+    }
+    ttl(options) {
+        return resolveTTL(this.declaration.ttl, options?.ttl);
+    }
+    async setString(client, key, value, ttl) {
+        switch (ttl.kind) {
+            case "expire":
+                await client.set(key, value, "PX", ttl.milliseconds);
+                return;
+            case "keep":
+                await client.set(key, value, "KEEPTTL");
+                return;
+            case "clear":
+                await client.set(key, value);
+        }
+    }
+    async write(client, key, ttl, command) {
+        let transaction = command(client.multi());
+        if (ttl.kind === "expire")
+            transaction = transaction.pexpire(key, ttl.milliseconds);
+        if (ttl.kind === "clear")
+            transaction = transaction.persist(key);
+        const results = (await transaction.exec()) ?? [];
+        for (const [error] of results) {
+            if (error)
+                throw error;
+        }
+        return results[0]?.[1];
+    }
+    async readMany(operation, keys) {
+        const client = this.open(operation);
+        if (keys.length === 0)
+            return [];
+        const pipeline = client.pipeline();
+        for (const key of keys)
+            pipeline.get(this.keyOf(key));
+        const results = (await pipeline.exec()) ?? [];
+        return results.map(([error, value]) => {
+            if (error)
+                throw error;
+            return value;
+        });
+    }
+    async deleteKey(operation, args) {
+        const client = this.open(operation);
+        const [key] = this.split(args);
+        return (await client.del(key)) > 0;
+    }
+}
+export class TextHandle extends Entry {
+    async get(...args) {
+        const client = this.open("get");
+        const [key] = this.split(args);
+        return (await client.get(key)) ?? undefined;
+    }
+    async getMany(keys) {
+        return (await this.readMany("getMany", keys)).map((value) => value ?? undefined);
+    }
+    async set(...args) {
+        const client = this.open("set");
+        const [key, [value, options]] = this.split(args);
+        if (typeof value !== "string") {
+            throw new TypeError(`${this.name}.set takes a string, not ${typeof value}`);
+        }
+        await this.setString(client, key, value, this.ttl(options));
+    }
+    async delete(...args) {
+        return this.deleteKey("delete", args);
+    }
+}
+const integer = /^(0|-?[1-9]\d*)$/;
+const safeRange = "past the integers a number holds exactly, ±(2^53 - 1)";
+function refuseUnsafeCount(key, count) {
+    const value = Number(count);
+    if (!Number.isSafeInteger(value)) {
+        throw new RangeError(`key "${key}" holds ${count}, ${safeRange}: read it through the client as a string`);
+    }
+    return value;
+}
+export class CounterHandle extends Entry {
+    decode(key, value) {
+        if (value === null)
+            return undefined;
+        if (!integer.test(value)) {
+            throw new InvalidKVValueError(key, `holds "${value}", which is no integer`);
+        }
+        return refuseUnsafeCount(key, value);
+    }
+    async get(...args) {
+        const client = this.open("get");
+        const [key] = this.split(args);
+        return this.decode(key, await client.get(key));
+    }
+    async getMany(keys) {
+        const values = await this.readMany("getMany", keys);
+        return values.map((value, i) => this.decode(this.keyOf(keys[i]), value));
+    }
+    async set(...args) {
+        const client = this.open("set");
+        const [key, [value, options]] = this.split(args);
+        if (!Number.isSafeInteger(value)) {
+            throw new TypeError(`${this.name}.set takes an integer, not ${String(value)}`);
+        }
+        await this.setString(client, key, String(value), this.ttl(options));
+    }
+    async increment(...args) {
+        return this.add("increment", args, 1);
+    }
+    async decrement(...args) {
+        return this.add("decrement", args, -1);
+    }
+    async add(operation, args, sign) {
+        const client = this.open(operation);
+        const [key, [by = 1, options]] = this.split(args);
+        if (!Number.isSafeInteger(by)) {
+            throw new TypeError(`${this.name}.${operation} takes an integer step, not ${String(by)}`);
+        }
+        const count = await this.write(client, key, this.ttl(options), (transaction) => transaction.incrby(key, sign * by));
+        if (!Number.isSafeInteger(count)) {
+            throw new RangeError(`${this.name}.${operation} left key "${key}" holding a count ${safeRange}: read it through the client as a string`);
+        }
+        return count;
+    }
+    async delete(...args) {
+        return this.deleteKey("delete", args);
+    }
+}
+export class JsonHandle extends Entry {
+    get schema() {
+        return this.declaration.schema;
+    }
+    async decode(key, raw) {
+        if (raw === null)
+            return undefined;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return this.refuseRead(key, "holds a value that is no JSON");
+        }
+        const result = await this.schema["~standard"].validate(parsed);
+        if (result.issues) {
+            return this.refuseRead(key, `holds a value that fails its schema: ${describeIssues(result.issues)}`);
+        }
+        return result.value;
+    }
+    refuseRead(key, reason) {
+        if (this.declaration.missOnInvalid)
+            return undefined;
+        throw new InvalidKVValueError(key, reason);
+    }
+    async get(...args) {
+        const client = this.open("get");
+        const [key] = this.split(args);
+        return this.decode(key, await client.get(key));
+    }
+    async getMany(keys) {
+        const values = await this.readMany("getMany", keys);
+        return Promise.all(values.map((value, i) => this.decode(this.keyOf(keys[i]), value)));
+    }
+    async set(...args) {
+        const client = this.open("set");
+        const [key, [value, options]] = this.split(args);
+        const result = await this.schema["~standard"].validate(value);
+        if (result.issues) {
+            throw new InvalidKVValueError(key, `would hold a value that fails its schema: ${describeIssues(result.issues)}`);
+        }
+        await this.setString(client, key, JSON.stringify(result.value), this.ttl(options));
+    }
+    async delete(...args) {
+        return this.deleteKey("delete", args);
+    }
+}
+function listOf(values, operation) {
+    const list = typeof values === "string" ? [values] : values;
+    if (!Array.isArray(list) ||
+        list.length === 0 ||
+        list.some((value) => typeof value !== "string")) {
+        throw new TypeError(`${operation} takes a string or a non-empty array of strings`);
+    }
+    return list;
+}
+export class ListHandle extends Entry {
+    async push(...args) {
+        return this.insert("push", args, "rpush");
+    }
+    async unshift(...args) {
+        return this.insert("unshift", args, "lpush");
+    }
+    async insert(operation, args, command) {
+        const client = this.open(operation);
+        const [key, [values, options]] = this.split(args);
+        const list = listOf(values, `${this.name}.${operation}`);
+        const ordered = command === "lpush" ? [...list].reverse() : list;
+        return this.write(client, key, this.ttl(options), (transaction) => transaction[command](key, ...ordered));
+    }
+    async pop(...args) {
+        const client = this.open("pop");
+        const [key] = this.split(args);
+        return (await client.rpop(key)) ?? undefined;
+    }
+    async shift(...args) {
+        const client = this.open("shift");
+        const [key] = this.split(args);
+        return (await client.lpop(key)) ?? undefined;
+    }
+    async at(...args) {
+        const client = this.open("at");
+        const [key, [index]] = this.split(args);
+        return (await client.lindex(key, index)) ?? undefined;
+    }
+    async slice(...args) {
+        const client = this.open("slice");
+        const [key, [start = 0, end]] = this.split(args);
+        if (end === 0)
+            return [];
+        return client.lrange(key, start, end === undefined ? -1 : end - 1);
+    }
+    async length(...args) {
+        const client = this.open("length");
+        const [key] = this.split(args);
+        return client.llen(key);
+    }
+    async delete(...args) {
+        return this.deleteKey("delete", args);
+    }
+}
+export class SetHandle extends Entry {
+    async add(...args) {
+        const client = this.open("add");
+        const [key, [members, options]] = this.split(args);
+        const list = listOf(members, `${this.name}.add`);
+        return this.write(client, key, this.ttl(options), (transaction) => transaction.sadd(key, ...list));
+    }
+    async delete(...args) {
+        const client = this.open("delete");
+        const [key, [member]] = this.split(args);
+        if (typeof member !== "string") {
+            throw new TypeError(`${this.name}.delete takes a string member, not ${typeof member}`);
+        }
+        return (await client.srem(key, member)) === 1;
+    }
+    async has(...args) {
+        const client = this.open("has");
+        const [key, [member]] = this.split(args);
+        return (await client.sismember(key, member)) === 1;
+    }
+    async size(...args) {
+        const client = this.open("size");
+        const [key] = this.split(args);
+        return client.scard(key);
+    }
+    async values(...args) {
+        const client = this.open("values");
+        const [key] = this.split(args);
+        return new Set(await client.smembers(key));
+    }
+    async clear(...args) {
+        return this.deleteKey("clear", args);
+    }
+}
+export const handles = {
+    text: TextHandle,
+    counter: CounterHandle,
+    json: JsonHandle,
+    list: ListHandle,
+    set: SetHandle,
+};

package/dist/kv/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Thrown when a value written to an entry, or read from one, is not a value of the entry's
+ * shape: a `json` value that fails its schema, or a `counter` that holds no integer.
+ */
+export declare class InvalidKVValueError extends Error {
+    /** The key whose value is invalid. */
+    readonly key: string;
+    name: string;
+    constructor(
+    /** The key whose value is invalid. */
+    key: string, reason: string);
+}

package/dist/kv/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Thrown when a value written to an entry, or read from one, is not a value of the entry's
+ * shape: a `json` value that fails its schema, or a `counter` that holds no integer.
+ */
+export class InvalidKVValueError extends Error {
+    key;
+    name = "InvalidKVValueError";
+    constructor(
+    /** The key whose value is invalid. */
+    key, reason) {
+        super(`key "${key}" ${reason}`);
+        this.key = key;
+    }
+}

package/dist/kv/index.d.ts

@@ -0,0 +1,6 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export type { CounterEntry, EntryDeclaration, EntryOptions, JsonEntry, JsonEntryOptions, ListEntry, SetEntry, TextEntry, } from "./entries.js";
+export { InvalidKVValueError } from "./errors.js";
+export { type Eviction, type KVEntries, type KVMemory, type KVOptions, type KVStore, kv, } from "./kv.js";
+export type { KeyOf } from "./pattern.js";
+export type { KVDuration, WriteOptions, WriteTTL } from "./ttl.js";

package/dist/kv/index.js

@@ -0,0 +1,3 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export { InvalidKVValueError } from "./errors.js";
+export { kv, } from "./kv.js";

package/dist/kv/ioredis.d.ts

@@ -0,0 +1,2 @@
+import type { Redis, RedisOptions } from "ioredis";
+export declare function newRedis(options: RedisOptions): Redis;

package/dist/kv/ioredis.js

@@ -0,0 +1,20 @@
+const ioredis = await import("ioredis").then((module) => ({ module }), (error) => ({ error }));
+function isIoredisMissing(error) {
+    for (let cause = error; cause instanceof Error; cause = cause.cause) {
+        const code = cause.code;
+        if ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") &&
+            /['"]ioredis['"]/.test(cause.message)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function newRedis(options) {
+    if ("error" in ioredis) {
+        if (isIoredisMissing(ioredis.error)) {
+            throw new Error("a kv store is reached with ioredis, which is not installed. Install it: npm install ioredis", { cause: ioredis.error });
+        }
+        throw ioredis.error;
+    }
+    return new ioredis.module.Redis(options);
+}

package/dist/kv/kv.d.ts

@@ -0,0 +1,84 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Redis } from "ioredis";
+import { type EntryDeclaration, type EntryOf, type EntryOptions, type JsonEntryOptions } from "./entries.js";
+/** The policy a store evicts keys by once it reaches its memory. */
+export type Eviction = "noeviction" | "allkeys-lru" | "allkeys-lfu" | "allkeys-random" | "volatile-lru" | "volatile-lfu" | "volatile-random" | "volatile-ttl";
+/** A size written with its unit, such as `"256mb"` or `"1gb"`. */
+export type KVMemory = `${number}${"kb" | "mb" | "gb"}`;
+/** The entries of a store, by the member name each is reached through. */
+export type KVEntries = Record<string, EntryDeclaration>;
+/** How a store is declared. */
+export interface KVOptions<TEntries extends KVEntries> {
+    /** The major Valkey version the store runs; without it, the provider's default. */
+    version?: "8" | "9";
+    /** The policy keys are evicted by once the store is full; without it, `noeviction`. */
+    eviction?: Eviction;
+    /** The memory the store holds, which eviction acts at; without it, the provider's default. */
+    memory?: KVMemory;
+    /**
+     * The typed entries the store holds, each a member of the store under its name: a letter,
+     * then letters, digits and _, at most 63 characters. `client`, `connectionString`,
+     * `connection_string`, `then` and `constructor` are members a store has in some SDK, and
+     * are refused.
+     */
+    entries?: TEntries & {
+        [Name in keyof TEntries]: Name extends ReservedName ? never : unknown;
+    };
+}
+declare const reservedNames: readonly ["client", "connectionString", "connection_string", "then", "constructor"];
+type ReservedName = (typeof reservedNames)[number];
+/** A declared store: its entries as members, beside the client that reaches the rest. */
+export type KVStore<TEntries extends KVEntries> = {
+    readonly [Name in keyof TEntries]: EntryOf<TEntries[Name]>;
+} & {
+    /**
+     * The ioredis client connected to the store, opened on first use and shared after. Over
+     * TLS it trusts only the store's own certificate authority when the provider names one.
+     * Reading it throws when the delivered authority holds no PEM certificate.
+     */
+    readonly client: Redis;
+    /** The store's URL, `redis://` or `rediss://` when it requires TLS, for tools that take one. */
+    readonly connectionString: string;
+};
+declare function declareStore<TEntries extends KVEntries = Record<never, never>>(name: string, options?: KVOptions<TEntries>): KVStore<TEntries>;
+declare function text<TPattern extends string>(pattern: TPattern, options?: EntryOptions): EntryDeclaration<"text", TPattern, string, string>;
+declare function counter<TPattern extends string>(pattern: TPattern, options?: EntryOptions): EntryDeclaration<"counter", TPattern, number, number>;
+declare function json<TPattern extends string, TSchema extends StandardSchemaV1>(pattern: TPattern, options: JsonEntryOptions<TSchema>): EntryDeclaration<"json", TPattern, StandardSchemaV1.InferInput<TSchema>, StandardSchemaV1.InferOutput<TSchema>>;
+declare function list<TPattern extends string>(pattern: TPattern, options?: EntryOptions): EntryDeclaration<"list", TPattern, string[], string[]>;
+declare function set<TPattern extends string>(pattern: TPattern, options?: EntryOptions): EntryDeclaration<"set", TPattern, string[], string[]>;
+/**
+ * Declares a key-value store named `name`, one Valkey instance of its own, and returns it
+ * with each of its `entries` as a member, beside its `client` and `connectionString`.
+ *
+ * An entry's keys are built from its pattern, `/`-separated segments that are each a
+ * literal or a `:parameter`, and every operation takes the parameters as its key:
+ *
+ * ```ts
+ * export const cache = kv("cache", {
+ *   eviction: "allkeys-lru",
+ *   entries: {
+ *     requests: kv.counter("requests/:userId", { ttl: "10s" }),
+ *     session: kv.json("session/:id", { schema: Session, ttl: "30d" }),
+ *   },
+ * });
+ *
+ * await cache.requests.increment({ userId });
+ * await cache.session.get({ id }); // Session | undefined
+ * ```
+ *
+ * Two entries whose patterns could name the same key are refused when the store is
+ * declared. During discovery every member throws an `UnprovisionedResourceError`.
+ */
+export declare const kv: typeof declareStore & {
+    /** Declares a `text` entry: a string under each key. */
+    text: typeof text;
+    /** Declares a `counter` entry: an integer under each key, changed atomically. */
+    counter: typeof counter;
+    /** Declares a `json` entry: a value its Standard Schema checks on write and on read. */
+    json: typeof json;
+    /** Declares a `list` entry: a list of strings under each key. */
+    list: typeof list;
+    /** Declares a `set` entry: a set of strings under each key. */
+    set: typeof set;
+};
+export {};

package/dist/kv/kv.js

@@ -0,0 +1,177 @@
+import { X509Certificate } from "node:crypto";
+import { bindingKey, getConfig } from "../binding/binding.js";
+import { unprovisioned, unprovisionedPhase } from "../binding/unprovisioned.js";
+import { declarationSite } from "../declaration/callsite.js";
+import { defer } from "../declaration/defer.js";
+import { ResourceType } from "../gen/proto/app/resources/v1/resources_pb.js";
+import { BindingType } from "../gen/proto/common/bindings/v1/bindings_pb.js";
+import { rpc } from "../runtime/rpc.js";
+import { declareEntry, handles, readDeclaredEntry, shapes, } from "./entries.js";
+import { newRedis } from "./ioredis.js";
+import { patternsOverlap } from "./pattern.js";
+const reservedNames = [
+    "client",
+    "connectionString",
+    "connection_string",
+    "then",
+    "constructor",
+];
+const entryName = /^[A-Za-z][A-Za-z0-9_]{0,62}$/;
+function declareStore(name, options = {}) {
+    const entries = Object.entries(options.entries ?? {}).map(([entry, declaration]) => [entry, readDeclaredEntry(declaration)]);
+    refuseEntries(name, entries);
+    if (process.env.OCEL_PHASE === "discovery") {
+        defer(rpc.resource.declare({
+            resource: { name, type: ResourceType.KV },
+            config: {
+                case: "kv",
+                value: {
+                    version: options.version ?? "",
+                    eviction: options.eviction ?? "",
+                    memory: options.memory ?? "",
+                    entries: entries.map(([entry, declaration]) => ({
+                        name: entry,
+                        pattern: declaration.pattern,
+                        shape: shapes[declaration.shape],
+                        source: declaration.source,
+                    })),
+                },
+            },
+            source: declarationSite(),
+        }));
+    }
+    let client;
+    const openClient = (access) => {
+        if (unprovisionedPhase()) {
+            throw unprovisioned(`kv("${name}")`, access);
+        }
+        client ??= newRedis(clientOptions(name, getConfig(name, "kv")));
+        return client;
+    };
+    const store = {};
+    for (const [entry, declaration] of entries) {
+        store[entry] = new handles[declaration.shape](entry, declaration, openClient);
+    }
+    Object.defineProperties(store, {
+        client: { get: () => openClient("client") },
+        connectionString: {
+            get: () => {
+                if (unprovisionedPhase())
+                    throw unprovisioned(`kv("${name}")`, "connectionString");
+                return connectionStringOf(getConfig(name, "kv"));
+            },
+        },
+    });
+    return store;
+}
+function refuseEntries(store, entries) {
+    for (const [i, [name, declaration]] of entries.entries()) {
+        if (reservedNames.includes(name)) {
+            throw new Error(`kv("${store}"): entry name "${name}" is reserved, since a store already has a member of that name in some SDK: name the entry otherwise`);
+        }
+        if (!entryName.test(name)) {
+            throw new Error(`kv("${store}"): entry name "${name}" is no name every SDK can hold: it starts with a letter and goes on in letters, digits and _, at most 63 characters`);
+        }
+        for (const [prior, priorDeclaration] of entries.slice(0, i)) {
+            if (patternsOverlap(priorDeclaration.parsed, declaration.parsed)) {
+                throw new Error(`kv("${store}"): entry "${name}" declared at ${declaration.source || "an unknown line"} has pattern "${declaration.pattern}", which overlaps pattern "${priorDeclaration.pattern}" of entry "${prior}" declared at ${priorDeclaration.source || "an unknown line"}: some key would match both, so neither entry could tell its keys from the other's`);
+            }
+        }
+    }
+}
+function clientOptions(store, properties) {
+    const { host, port, username, password, tls, caPem } = properties;
+    return {
+        host,
+        port,
+        username: username || undefined,
+        password: password || undefined,
+        tls: tls ? tlsOptions(store, host, caPem) : undefined,
+    };
+}
+function tlsOptions(store, host, caPem) {
+    if (caPem && !holdsCertificates(caPem)) {
+        throw new Error(`${bindingKey(store, BindingType.KV)} delivers a caPem for its kv store that holds no PEM certificate`);
+    }
+    return {
+        ...(isAddress(host) ? {} : { servername: host }),
+        ...(caPem ? { ca: caPem } : {}),
+    };
+}
+const pemBlock = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/g;
+function holdsCertificates(pem) {
+    const certificates = [...pem.matchAll(pemBlock)].filter(([, label]) => label === "CERTIFICATE");
+    return certificates.length > 0 && certificates.every(([block]) => isCertificate(block));
+}
+function isCertificate(block) {
+    try {
+        new X509Certificate(block);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isAddress(host) {
+    return /^[\d.]+$/.test(host) || host.includes(":");
+}
+function connectionStringOf(properties) {
+    const { host, port, username, password, tls } = properties;
+    const url = new URL(`${tls ? "rediss" : "redis"}://${host}:${port}`);
+    url.username = username;
+    url.password = password;
+    return url.toString().replace(/\/$/, "");
+}
+function text(pattern, options = {}) {
+    return declareEntry("text", pattern, options);
+}
+function counter(pattern, options = {}) {
+    return declareEntry("counter", pattern, options);
+}
+function json(pattern, options) {
+    if (!options?.schema?.["~standard"]) {
+        throw new Error(`kv.json("${pattern}") takes a Standard Schema as its schema, and was given none`);
+    }
+    return declareEntry("json", pattern, options);
+}
+function list(pattern, options = {}) {
+    return declareEntry("list", pattern, options);
+}
+function set(pattern, options = {}) {
+    return declareEntry("set", pattern, options);
+}
+/**
+ * Declares a key-value store named `name`, one Valkey instance of its own, and returns it
+ * with each of its `entries` as a member, beside its `client` and `connectionString`.
+ *
+ * An entry's keys are built from its pattern, `/`-separated segments that are each a
+ * literal or a `:parameter`, and every operation takes the parameters as its key:
+ *
+ * ```ts
+ * export const cache = kv("cache", {
+ *   eviction: "allkeys-lru",
+ *   entries: {
+ *     requests: kv.counter("requests/:userId", { ttl: "10s" }),
+ *     session: kv.json("session/:id", { schema: Session, ttl: "30d" }),
+ *   },
+ * });
+ *
+ * await cache.requests.increment({ userId });
+ * await cache.session.get({ id }); // Session | undefined
+ * ```
+ *
+ * Two entries whose patterns could name the same key are refused when the store is
+ * declared. During discovery every member throws an `UnprovisionedResourceError`.
+ */
+export const kv = Object.assign(declareStore, {
+    /** Declares a `text` entry: a string under each key. */
+    text,
+    /** Declares a `counter` entry: an integer under each key, changed atomically. */
+    counter,
+    /** Declares a `json` entry: a value its Standard Schema checks on write and on read. */
+    json,
+    /** Declares a `list` entry: a list of strings under each key. */
+    list,
+    /** Declares a `set` entry: a set of strings under each key. */
+    set,
+});

package/dist/kv/pattern.d.ts

@@ -0,0 +1,27 @@
+type Segment = {
+    literal: string;
+} | {
+    parameter: string;
+};
+export interface Pattern {
+    readonly written: string;
+    readonly segments: readonly Segment[];
+}
+/** The parameter names a pattern such as `"rooms/:room/members/:member"` holds. */
+export type PatternParameters<TPattern extends string> = TPattern extends `${infer Head}/${infer Rest}` ? SegmentParameter<Head> | PatternParameters<Rest> : SegmentParameter<TPattern>;
+type SegmentParameter<TSegment extends string> = TSegment extends `:${infer Name}` ? Name : never;
+/**
+ * The key of an entry: one value for each parameter of its pattern, a string or a safe
+ * integer. A number that is not a safe integer is refused when the key is built.
+ */
+export type KeyOf<TPattern extends string> = {
+    [Name in PatternParameters<TPattern>]: string | number;
+};
+/** The leading argument an entry's operations take: its key, or nothing for a pattern without parameters. */
+export type KeyArgs<TPattern extends string> = [PatternParameters<TPattern>] extends [never] ? [] : [key: KeyOf<TPattern>];
+export declare function parsePattern(written: string): Pattern;
+export declare function patternsOverlap(a: Pattern, b: Pattern): boolean;
+export declare function hasParameters(pattern: Pattern): boolean;
+export declare function encodeParameter(value: string): string;
+export declare function buildKey(pattern: Pattern, key: Record<string, unknown> | undefined): string;
+export {};