@laserdata/laser-sdk 0.0.1-rc.21 → 0.0.1-rc.22

package/dist/managed/kv.d.ts

@@ -0,0 +1,144 @@
+import type { Capabilities } from "../client/capabilities.js";
+import { type ManagedTransport } from "../client/managed.js";
+import type { Codec } from "../stream/codecs.js";
+import { type KvEntry, type KvMetadata, type KvNamespaceInfo, type KvPage } from "../wire/kv.js";
+/** A granted advisory lease with its fencing token and effective TTL. */
+export interface Lease {
+    readonly token: bigint;
+    readonly grantedTtlMicros: bigint;
+}
+export type KvBackend = ManagedTransport;
+/** A namespace-scoped managed key-value view. */
+export declare class Kv {
+    private readonly backend;
+    private readonly getCapabilities;
+    readonly namespace: string;
+    constructor(backend: KvBackend, getCapabilities: () => Promise<Capabilities>, namespace: string);
+    static namespaces(backend: KvBackend, getCapabilities: () => Promise<Capabilities>): Promise<readonly KvNamespaceInfo[]>;
+    get(key: Uint8Array): Promise<Uint8Array | undefined>;
+    getEntry(key: Uint8Array): Promise<KvEntry | undefined>;
+    /** Decodes a value with the supplied codec, or returns undefined. */
+    getAs<T>(key: Uint8Array, codec: Codec<T>): Promise<T | undefined>;
+    getTyped<T>(key: Uint8Array, decodeValue: (value: unknown) => T): Promise<T | undefined>;
+    /** Starts a value write or compare-and-swap request. */
+    set(key: Uint8Array): KvSetRequest;
+    /** Starts a compare-and-swap protected by a lease fencing token. */
+    casFenced(key: Uint8Array, fenceKey: Uint8Array, fenceToken: bigint): KvCasFencedRequest;
+    delete(key: Uint8Array): Promise<boolean>;
+    exists(key: Uint8Array): Promise<KvMetadata | undefined>;
+    /** Changes an entry expiry without rewriting its value. */
+    expire(key: Uint8Array, expiresAtMicros?: bigint): Promise<bigint>;
+    /** Applies a codec-specific merge patch and returns the new version. */
+    patch(key: Uint8Array, patch: Uint8Array): Promise<bigint>;
+    lease(key: Uint8Array, leaseTtlMicros: bigint): Promise<Lease>;
+    release(key: Uint8Array, token: bigint): Promise<boolean>;
+    /** Starts an atomic value copy that preserves remaining expiry. */
+    copyTo(key: Uint8Array, toKey: Uint8Array): KvCopyRequest;
+    moveTo(key: Uint8Array, toKey: Uint8Array): KvCopyRequest;
+    /** Reads several keys in one round trip while preserving key order. */
+    getMany(keys: readonly Uint8Array[]): Promise<readonly (Uint8Array | undefined)[]>;
+    /** Starts a filtered bulk delete. */
+    deleteMany(): KvDeleteManyRequest;
+    scan(): KvScanRequest;
+}
+/** Builds a value write or compare-and-swap. */
+export declare class KvSetRequest {
+    private readonly backend;
+    private readonly getCapabilities;
+    private readonly namespace;
+    private readonly key;
+    private value;
+    private expiresAtMicros;
+    private expect;
+    constructor(backend: KvBackend, getCapabilities: () => Promise<Capabilities>, namespace: string, key: Uint8Array);
+    bytes(payload: Uint8Array): this;
+    encodeWith<T>(codec: Codec<T>, value: T): this;
+    json(value: unknown): this;
+    expiresAt(epochMicros: bigint): this;
+    /** Expires the entry after `ttlMicros`. Pass `nowMicros` for deterministic tests. */
+    ttl(ttlMicros: bigint, nowMicros?: bigint): this;
+    expectVersion(version: bigint): this;
+    expectAbsent(): this;
+    send(): Promise<void>;
+    /** Commits the configured compare-and-swap and returns its new version. */
+    commit(): Promise<bigint>;
+}
+/** Builds a compare-and-swap protected by a lease fencing token. */
+export declare class KvCasFencedRequest {
+    private readonly backend;
+    private readonly getCapabilities;
+    private readonly namespace;
+    private readonly key;
+    private readonly fenceKey;
+    private readonly fenceToken;
+    private value;
+    private expiresAtMicros;
+    private expect;
+    constructor(backend: KvBackend, getCapabilities: () => Promise<Capabilities>, namespace: string, key: Uint8Array, fenceKey: Uint8Array, fenceToken: bigint);
+    bytes(payload: Uint8Array): this;
+    encodeWith<T>(codec: Codec<T>, value: T): this;
+    json(value: unknown): this;
+    expiresAt(epochMicros: bigint): this;
+    /** Expires the entry after `ttlMicros`. Pass `nowMicros` for deterministic tests. */
+    ttl(ttlMicros: bigint, nowMicros?: bigint): this;
+    expectVersion(version: bigint): this;
+    expectAbsent(): this;
+    /** Commits the fenced compare-and-swap and returns its new version. */
+    commit(): Promise<bigint>;
+}
+/** Builds a paged namespace scan. */
+export declare class KvScanRequest {
+    private readonly backend;
+    private readonly getCapabilities;
+    private readonly namespace;
+    private boundPrefix;
+    private boundStart;
+    private boundEnd;
+    private boundKeyContains;
+    private boundConversation;
+    private pageLimit;
+    private pageCursor;
+    constructor(backend: KvBackend, getCapabilities: () => Promise<Capabilities>, namespace: string);
+    /** Restricts a memory namespace scan to one conversation. */
+    conversation(conversationId: string): this;
+    prefix(prefix: Uint8Array): this;
+    range(start: Uint8Array, end: Uint8Array): this;
+    keyContains(substring: string): this;
+    limit(n: number): this;
+    cursor(cursor: Uint8Array): this;
+    fetch(): Promise<KvPage>;
+    /** Collects every matching entry across pages. */
+    entries(): Promise<readonly KvEntry[]>;
+    private request;
+}
+/** Builds a filtered bulk delete. */
+export declare class KvDeleteManyRequest {
+    private readonly backend;
+    private readonly getCapabilities;
+    private readonly namespace;
+    private boundPrefix;
+    private boundStart;
+    private boundEnd;
+    private boundKeyContains;
+    private boundConversation;
+    constructor(backend: KvBackend, getCapabilities: () => Promise<Capabilities>, namespace: string);
+    conversation(conversationId: string): this;
+    prefix(prefix: Uint8Array): this;
+    range(start: Uint8Array, end: Uint8Array): this;
+    keyContains(substring: string): this;
+    send(): Promise<number>;
+}
+/** Builds an atomic value copy or move. */
+export declare class KvCopyRequest {
+    private readonly backend;
+    private readonly getCapabilities;
+    private readonly namespace;
+    private readonly key;
+    private readonly toKey;
+    private readonly deleteSource;
+    private toNamespaceOverride;
+    constructor(backend: KvBackend, getCapabilities: () => Promise<Capabilities>, namespace: string, key: Uint8Array, toKey: Uint8Array, deleteSource: boolean);
+    intoNamespace(namespace: string): this;
+    send(): Promise<bigint>;
+}
+//# sourceMappingURL=kv.d.ts.map

package/dist/managed/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/managed/kv.ts"],"names":[],"mappings":"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"}

package/dist/managed/kv.js

@@ -0,0 +1,502 @@
+import { InvalidError, KvExecutionError, ProtocolError, UnsupportedError } from "../client/errors.js";
+import { executeManaged } from "../client/managed.js";
+import { executeBatch } from "./batch.js";
+import { jsonCodec } from "../stream/codecs.js";
+import { KvCasCommand, KvCasFencedCommand, KvCopyCommand, KvDeleteCommand, KvDeleteManyCommand, KvExistsCommand, KvExpireCommand, KvGetCommand, KvLeaseCommand, KvMoveCommand, KvNamespacesCommand, KvPatchCommand, KvReleaseCommand, KvScanCommand, KvSetCommand } from "../wire/commands.js";
+import { validateNamespace } from "../wire/kv.js";
+import { DEFAULT_SCAN_LIMIT, MAX_KEY_BYTES, MAX_VALUE_BYTES } from "../wire/limits.js";
+async function executeKv(backend, capabilities, namespace, command, request) {
+    if (namespace !== undefined)
+        validateNamespace(namespace);
+    const reply = await executeManaged(backend, capabilities, command, request);
+    if (reply.kind === "ok")
+        return reply.outcome;
+    if (reply.kind === "err") {
+        if (reply.error.kind === "unsupported")
+            throw new UnsupportedError(reply.error.message);
+        throw new KvExecutionError(`kv command failed: ${reply.error.kind}`, reply.error);
+    }
+    throw new ProtocolError(`kv: unrecognized reply variant \`${reply.tag}\``, {
+        commandCode: command.code
+    });
+}
+function unexpected(op, outcome) {
+    return new ProtocolError(`kv ${op}: unexpected reply outcome \`${outcome.kind}\``);
+}
+function validatedKey(key) {
+    if (key.byteLength === 0)
+        throw new InvalidError("key must not be empty");
+    if (key.byteLength > MAX_KEY_BYTES) {
+        throw new InvalidError(`key is ${String(key.byteLength)}B, exceeds cap ${String(MAX_KEY_BYTES)}B`);
+    }
+    return key;
+}
+function validatedValue(value) {
+    if (value.byteLength > MAX_VALUE_BYTES) {
+        throw new InvalidError(`value is ${String(value.byteLength)}B, exceeds cap ${String(MAX_VALUE_BYTES)}B`);
+    }
+}
+async function fetchNamespaces(backend, capabilities) {
+    const outcome = await executeKv(backend, capabilities, undefined, KvNamespacesCommand, undefined);
+    if (outcome.kind === "namespaces")
+        return outcome.namespaces;
+    throw unexpected("namespaces", outcome);
+}
+/** A namespace-scoped managed key-value view. */
+export class Kv {
+    backend;
+    getCapabilities;
+    namespace;
+    constructor(backend, getCapabilities, namespace) {
+        this.backend = backend;
+        this.getCapabilities = getCapabilities;
+        this.namespace = namespace;
+    }
+    static async namespaces(backend, getCapabilities) {
+        const capabilities = await getCapabilities();
+        return fetchNamespaces(backend, capabilities);
+    }
+    async get(key) {
+        const entry = await this.getEntry(key);
+        return entry?.value;
+    }
+    async getEntry(key) {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvGetCommand, {
+            namespace: this.namespace,
+            key: validatedKey(key)
+        });
+        if (outcome.kind === "value")
+            return outcome.entry;
+        throw unexpected("get", outcome);
+    }
+    /** Decodes a value with the supplied codec, or returns undefined. */
+    async getAs(key, codec) {
+        const value = await this.get(key);
+        return value === undefined ? undefined : codec.decode(value);
+    }
+    async getTyped(key, decodeValue) {
+        return this.getAs(key, jsonCodec(decodeValue));
+    }
+    /** Starts a value write or compare-and-swap request. */
+    set(key) {
+        return new KvSetRequest(this.backend, this.getCapabilities, this.namespace, validatedKey(key));
+    }
+    /** Starts a compare-and-swap protected by a lease fencing token. */
+    casFenced(key, fenceKey, fenceToken) {
+        return new KvCasFencedRequest(this.backend, this.getCapabilities, this.namespace, validatedKey(key), validatedKey(fenceKey), fenceToken);
+    }
+    async delete(key) {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvDeleteCommand, {
+            namespace: this.namespace,
+            key: validatedKey(key)
+        });
+        if (outcome.kind === "deleted")
+            return outcome.removed;
+        throw unexpected("delete", outcome);
+    }
+    async exists(key) {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvExistsCommand, {
+            namespace: this.namespace,
+            key: validatedKey(key)
+        });
+        if (outcome.kind === "metadata")
+            return outcome.metadata;
+        throw unexpected("exists", outcome);
+    }
+    /** Changes an entry expiry without rewriting its value. */
+    async expire(key, expiresAtMicros) {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvExpireCommand, {
+            namespace: this.namespace,
+            key: validatedKey(key),
+            ...(expiresAtMicros !== undefined ? { expiresAtMicros } : {})
+        });
+        if (outcome.kind === "versioned")
+            return outcome.version;
+        throw unexpected("expire", outcome);
+    }
+    /** Applies a codec-specific merge patch and returns the new version. */
+    async patch(key, patch) {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvPatchCommand, {
+            namespace: this.namespace,
+            key: validatedKey(key),
+            patch
+        });
+        if (outcome.kind === "versioned")
+            return outcome.version;
+        throw unexpected("patch", outcome);
+    }
+    async lease(key, leaseTtlMicros) {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvLeaseCommand, {
+            namespace: this.namespace,
+            key: validatedKey(key),
+            leaseTtlMicros
+        });
+        if (outcome.kind === "leased") {
+            return { token: outcome.leaseToken, grantedTtlMicros: outcome.grantedTtlMicros };
+        }
+        throw unexpected("lease", outcome);
+    }
+    async release(key, token) {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvReleaseCommand, {
+            namespace: this.namespace,
+            key: validatedKey(key),
+            leaseToken: token
+        });
+        if (outcome.kind === "released")
+            return outcome.wasHeld;
+        throw unexpected("release", outcome);
+    }
+    /** Starts an atomic value copy that preserves remaining expiry. */
+    copyTo(key, toKey) {
+        return new KvCopyRequest(this.backend, this.getCapabilities, this.namespace, validatedKey(key), validatedKey(toKey), false);
+    }
+    moveTo(key, toKey) {
+        return new KvCopyRequest(this.backend, this.getCapabilities, this.namespace, validatedKey(key), validatedKey(toKey), true);
+    }
+    /** Reads several keys in one round trip while preserving key order. */
+    async getMany(keys) {
+        const capabilities = await this.getCapabilities();
+        const ops = keys.map((key) => ({
+            code: KvGetCommand.code,
+            payload: KvGetCommand.encode({ namespace: this.namespace, key: validatedKey(key) })
+        }));
+        const results = await executeBatch(this.backend, capabilities, ops);
+        return results.map((slot) => {
+            const reply = KvGetCommand.decode(slot);
+            if (reply.kind === "ok" && reply.outcome.kind === "value")
+                return reply.outcome.entry?.value;
+            if (reply.kind === "ok")
+                throw unexpected("get", reply.outcome);
+            if (reply.kind === "err") {
+                if (reply.error.kind === "unsupported")
+                    throw new UnsupportedError(reply.error.message);
+                throw new KvExecutionError(`kv command failed: ${reply.error.kind}`, reply.error);
+            }
+            throw new ProtocolError(`kv: unrecognized reply variant in a batch slot \`${reply.tag}\``);
+        });
+    }
+    /** Starts a filtered bulk delete. */
+    deleteMany() {
+        return new KvDeleteManyRequest(this.backend, this.getCapabilities, this.namespace);
+    }
+    scan() {
+        return new KvScanRequest(this.backend, this.getCapabilities, this.namespace);
+    }
+}
+/** Builds a value write or compare-and-swap. */
+export class KvSetRequest {
+    backend;
+    getCapabilities;
+    namespace;
+    key;
+    value = new Uint8Array();
+    expiresAtMicros;
+    expect;
+    constructor(backend, getCapabilities, namespace, key) {
+        this.backend = backend;
+        this.getCapabilities = getCapabilities;
+        this.namespace = namespace;
+        this.key = key;
+    }
+    bytes(payload) {
+        this.value = payload;
+        return this;
+    }
+    encodeWith(codec, value) {
+        this.value = codec.encode(value);
+        return this;
+    }
+    json(value) {
+        return this.encodeWith(jsonCodec((decoded) => decoded), value);
+    }
+    expiresAt(epochMicros) {
+        this.expiresAtMicros = epochMicros;
+        return this;
+    }
+    /** Expires the entry after `ttlMicros`. Pass `nowMicros` for deterministic tests. */
+    ttl(ttlMicros, nowMicros = BigInt(Date.now()) * 1000n) {
+        return this.expiresAt(nowMicros + ttlMicros);
+    }
+    expectVersion(version) {
+        this.expect = { kind: "match", version };
+        return this;
+    }
+    expectAbsent() {
+        this.expect = { kind: "absent" };
+        return this;
+    }
+    async send() {
+        validatedValue(this.value);
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvSetCommand, {
+            namespace: this.namespace,
+            key: this.key,
+            value: this.value,
+            ...(this.expiresAtMicros !== undefined ? { expiresAtMicros: this.expiresAtMicros } : {})
+        });
+        if (outcome.kind === "written")
+            return;
+        throw unexpected("set", outcome);
+    }
+    /** Commits the configured compare-and-swap and returns its new version. */
+    async commit() {
+        if (this.expect === undefined) {
+            throw new InvalidError("commit() needs a precondition: call expectVersion(..) or expectAbsent()");
+        }
+        const capabilities = await this.getCapabilities();
+        if (!capabilities.kv.cas) {
+            throw new UnsupportedError("compare-and-swap is not advertised by this deployment");
+        }
+        validatedValue(this.value);
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvCasCommand, {
+            namespace: this.namespace,
+            key: this.key,
+            value: this.value,
+            expect: this.expect,
+            ...(this.expiresAtMicros !== undefined ? { expiresAtMicros: this.expiresAtMicros } : {})
+        });
+        if (outcome.kind === "committed")
+            return outcome.version;
+        throw unexpected("cas", outcome);
+    }
+}
+/** Builds a compare-and-swap protected by a lease fencing token. */
+export class KvCasFencedRequest {
+    backend;
+    getCapabilities;
+    namespace;
+    key;
+    fenceKey;
+    fenceToken;
+    value = new Uint8Array();
+    expiresAtMicros;
+    expect;
+    constructor(backend, getCapabilities, namespace, key, fenceKey, fenceToken) {
+        this.backend = backend;
+        this.getCapabilities = getCapabilities;
+        this.namespace = namespace;
+        this.key = key;
+        this.fenceKey = fenceKey;
+        this.fenceToken = fenceToken;
+    }
+    bytes(payload) {
+        this.value = payload;
+        return this;
+    }
+    encodeWith(codec, value) {
+        this.value = codec.encode(value);
+        return this;
+    }
+    json(value) {
+        return this.encodeWith(jsonCodec((decoded) => decoded), value);
+    }
+    expiresAt(epochMicros) {
+        this.expiresAtMicros = epochMicros;
+        return this;
+    }
+    /** Expires the entry after `ttlMicros`. Pass `nowMicros` for deterministic tests. */
+    ttl(ttlMicros, nowMicros = BigInt(Date.now()) * 1000n) {
+        return this.expiresAt(nowMicros + ttlMicros);
+    }
+    expectVersion(version) {
+        this.expect = { kind: "match", version };
+        return this;
+    }
+    expectAbsent() {
+        this.expect = { kind: "absent" };
+        return this;
+    }
+    /** Commits the fenced compare-and-swap and returns its new version. */
+    async commit() {
+        if (this.expect === undefined) {
+            throw new InvalidError("commit() needs a precondition: call expectVersion(..) or expectAbsent()");
+        }
+        const capabilities = await this.getCapabilities();
+        if (!capabilities.kv.casFenced) {
+            throw new UnsupportedError("fenced compare-and-swap is not advertised by this deployment");
+        }
+        validatedValue(this.value);
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvCasFencedCommand, {
+            namespace: this.namespace,
+            key: this.key,
+            value: this.value,
+            expect: this.expect,
+            fenceKey: this.fenceKey,
+            fenceToken: this.fenceToken,
+            ...(this.expiresAtMicros !== undefined ? { expiresAtMicros: this.expiresAtMicros } : {})
+        });
+        if (outcome.kind === "committed")
+            return outcome.version;
+        throw unexpected("cas_fenced", outcome);
+    }
+}
+/** Builds a paged namespace scan. */
+export class KvScanRequest {
+    backend;
+    getCapabilities;
+    namespace;
+    boundPrefix;
+    boundStart;
+    boundEnd;
+    boundKeyContains;
+    boundConversation;
+    pageLimit = DEFAULT_SCAN_LIMIT;
+    pageCursor;
+    constructor(backend, getCapabilities, namespace) {
+        this.backend = backend;
+        this.getCapabilities = getCapabilities;
+        this.namespace = namespace;
+    }
+    /** Restricts a memory namespace scan to one conversation. */
+    conversation(conversationId) {
+        this.boundConversation = conversationId;
+        return this;
+    }
+    prefix(prefix) {
+        this.boundPrefix = prefix;
+        return this;
+    }
+    range(start, end) {
+        this.boundStart = start;
+        this.boundEnd = end;
+        return this;
+    }
+    keyContains(substring) {
+        this.boundKeyContains = substring;
+        return this;
+    }
+    limit(n) {
+        this.pageLimit = n;
+        return this;
+    }
+    cursor(cursor) {
+        this.pageCursor = cursor;
+        return this;
+    }
+    async fetch() {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvScanCommand, this.request());
+        if (outcome.kind === "page")
+            return outcome.page;
+        throw unexpected("scan", outcome);
+    }
+    /** Collects every matching entry across pages. */
+    async entries() {
+        const capabilities = await this.getCapabilities();
+        const out = [];
+        let request = this.request();
+        for (;;) {
+            const outcome = await executeKv(this.backend, capabilities, this.namespace, KvScanCommand, request);
+            if (outcome.kind !== "page")
+                throw unexpected("scan", outcome);
+            out.push(...outcome.page.entries);
+            if (outcome.page.cursor === undefined)
+                return out;
+            request = { ...request, cursor: outcome.page.cursor };
+        }
+    }
+    request() {
+        return {
+            namespace: this.namespace,
+            ...(this.boundPrefix !== undefined ? { prefix: this.boundPrefix } : {}),
+            ...(this.boundStart !== undefined ? { start: this.boundStart } : {}),
+            ...(this.boundEnd !== undefined ? { end: this.boundEnd } : {}),
+            ...(this.boundKeyContains !== undefined ? { keyContains: this.boundKeyContains } : {}),
+            ...(this.boundConversation !== undefined ? { conversation: this.boundConversation } : {}),
+            limit: this.pageLimit,
+            ...(this.pageCursor !== undefined ? { cursor: this.pageCursor } : {})
+        };
+    }
+}
+/** Builds a filtered bulk delete. */
+export class KvDeleteManyRequest {
+    backend;
+    getCapabilities;
+    namespace;
+    boundPrefix;
+    boundStart;
+    boundEnd;
+    boundKeyContains;
+    boundConversation;
+    constructor(backend, getCapabilities, namespace) {
+        this.backend = backend;
+        this.getCapabilities = getCapabilities;
+        this.namespace = namespace;
+    }
+    conversation(conversationId) {
+        this.boundConversation = conversationId;
+        return this;
+    }
+    prefix(prefix) {
+        this.boundPrefix = prefix;
+        return this;
+    }
+    range(start, end) {
+        this.boundStart = start;
+        this.boundEnd = end;
+        return this;
+    }
+    keyContains(substring) {
+        this.boundKeyContains = substring;
+        return this;
+    }
+    async send() {
+        const capabilities = await this.getCapabilities();
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, KvDeleteManyCommand, {
+            namespace: this.namespace,
+            ...(this.boundPrefix !== undefined ? { prefix: this.boundPrefix } : {}),
+            ...(this.boundStart !== undefined ? { start: this.boundStart } : {}),
+            ...(this.boundEnd !== undefined ? { end: this.boundEnd } : {}),
+            ...(this.boundKeyContains !== undefined ? { keyContains: this.boundKeyContains } : {}),
+            ...(this.boundConversation !== undefined ? { conversation: this.boundConversation } : {})
+        });
+        if (outcome.kind === "deletedMany")
+            return outcome.count;
+        throw unexpected("delete_many", outcome);
+    }
+}
+/** Builds an atomic value copy or move. */
+export class KvCopyRequest {
+    backend;
+    getCapabilities;
+    namespace;
+    key;
+    toKey;
+    deleteSource;
+    toNamespaceOverride;
+    constructor(backend, getCapabilities, namespace, key, toKey, deleteSource) {
+        this.backend = backend;
+        this.getCapabilities = getCapabilities;
+        this.namespace = namespace;
+        this.key = key;
+        this.toKey = toKey;
+        this.deleteSource = deleteSource;
+    }
+    intoNamespace(namespace) {
+        this.toNamespaceOverride = namespace;
+        return this;
+    }
+    async send() {
+        if (this.toNamespaceOverride !== undefined)
+            validateNamespace(this.toNamespaceOverride);
+        const capabilities = await this.getCapabilities();
+        const command = this.deleteSource ? KvMoveCommand : KvCopyCommand;
+        const outcome = await executeKv(this.backend, capabilities, this.namespace, command, {
+            namespace: this.namespace,
+            key: this.key,
+            toKey: this.toKey,
+            ...(this.toNamespaceOverride !== undefined ? { toNamespace: this.toNamespaceOverride } : {})
+        });
+        if (outcome.kind === "committed")
+            return outcome.version;
+        throw unexpected(this.deleteSource ? "move" : "copy", outcome);
+    }
+}
+//# sourceMappingURL=kv.js.map