@qlever-llc/trellis 0.5.1

package/esm/trellis/errors/ValidationError.js

@@ -0,0 +1,77 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ValidationError_normalizedErrors;
+import Type from "typebox";
+import { TrellisError } from "./TrellisError.js";
+function normalizeError(e) {
+    if ("schemaPath" in e) {
+        return { schemaPath: e.schemaPath, message: e.message ?? "Invalid value" };
+    }
+    return { schemaPath: e.path, message: e.message };
+}
+/**
+ * Schema for validation issue in ValidationError.
+ */
+export const ValidationIssueSchema = Type.Object({
+    path: Type.String(),
+    message: Type.String(),
+});
+/**
+ * Schema for ValidationError serialization.
+ */
+export const ValidationErrorDataSchema = Type.Object({
+    id: Type.String(),
+    type: Type.Literal("ValidationError"),
+    message: Type.String(),
+    issues: Type.Array(ValidationIssueSchema),
+    context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+    traceId: Type.Optional(Type.String()),
+});
+/**
+ * Error for data validation failures.
+ * Includes schema validation and missing required data.
+ */
+export class ValidationError extends TrellisError {
+    constructor(options) {
+        const { errors: rawErrors, ...baseOptions } = options;
+        const errors = [...rawErrors].map(normalizeError);
+        const msg = errors
+            .map((e) => `Validation failed. ${e.schemaPath}: ${e.message}.`)
+            .join("\n");
+        super(msg.length ? msg : "Data validation failed.", baseOptions);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "ValidationError"
+        });
+        _ValidationError_normalizedErrors.set(this, void 0);
+        __classPrivateFieldSet(this, _ValidationError_normalizedErrors, errors, "f");
+    }
+    /**
+     * Serializes error to a plain object.
+     * Transforms internal errors array to issues array for serialization.
+     *
+     * @returns Plain object representation of the error
+     */
+    toSerializable() {
+        return {
+            ...this.baseSerializable(),
+            type: this.name,
+            issues: __classPrivateFieldGet(this, _ValidationError_normalizedErrors, "f").map((e) => ({
+                path: e.schemaPath,
+                message: e.message,
+            })),
+        };
+    }
+}
+_ValidationError_normalizedErrors = new WeakMap();

package/esm/trellis/errors/index.d.ts

@@ -0,0 +1,38 @@
+import { AuthError } from "./AuthError.js";
+import { ValidationError } from "./ValidationError.js";
+import { RemoteError } from "./RemoteError.js";
+import { KVError } from "./KVError.js";
+export { UnexpectedError } from "@qlever-llc/trellis-result";
+export { TrellisError } from "./TrellisError.js";
+export { AuthError } from "./AuthError.js";
+export { ValidationError } from "./ValidationError.js";
+export { RemoteError } from "./RemoteError.js";
+export { KVError } from "./KVError.js";
+export { type AuthErrorData, AuthErrorDataSchema } from "./AuthError.js";
+export { type ValidationErrorData, ValidationErrorDataSchema, type ValidationIssue, ValidationIssueSchema, } from "./ValidationError.js";
+export { type RemoteErrorData, RemoteErrorDataSchema } from "./RemoteError.js";
+export { type KVErrorData, KVErrorDataSchema } from "./KVError.js";
+/**
+ * Single source of truth for all Trellis errors.
+ * This object is used for compile-time type inference.
+ */
+declare const TRELLIS_ERRORS: {
+    readonly UnexpectedError: any;
+    readonly AuthError: typeof AuthError;
+    readonly ValidationError: typeof ValidationError;
+    readonly RemoteError: typeof RemoteError;
+    readonly KVError: typeof KVError;
+};
+/**
+ * Compile-time mapping from error names to their instance types.
+ * Derived from TRELLIS_ERRORS to ensure types stay in sync with runtime.
+ */
+export type TrellisErrorMap = {
+    [K in keyof typeof TRELLIS_ERRORS]: InstanceType<(typeof TRELLIS_ERRORS)[K]>;
+};
+export type TrellisErrorName = keyof TrellisErrorMap;
+export type TrellisErrorInstance = TrellisErrorMap[TrellisErrorName];
+export type MapErrorNamesToTypes<T extends readonly TrellisErrorName[]> = {
+    [K in keyof T]: T[K] extends TrellisErrorName ? TrellisErrorMap[T[K]] : never;
+}[number];
+//# sourceMappingURL=index.d.ts.map

package/esm/trellis/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/trellis/errors/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,KAAK,aAAa,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EACL,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,eAAe,EACpB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,eAAe,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,KAAK,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEnE;;;GAGG;AACH,QAAA,MAAM,cAAc;;;;;;CAMV,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;KAC3B,CAAC,IAAI,MAAM,OAAO,cAAc,GAAG,YAAY,CAAC,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7E,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,eAAe,CAAC;AACrD,MAAM,MAAM,oBAAoB,GAAG,eAAe,CAAC,gBAAgB,CAAC,CAAC;AACrE,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,SAAS,gBAAgB,EAAE,IAAI;KACvE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,gBAAgB,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK;CAC9E,CAAC,MAAM,CAAC,CAAC"}

package/esm/trellis/errors/index.js

@@ -0,0 +1,26 @@
+import { UnexpectedError } from "@qlever-llc/trellis-result";
+import { AuthError } from "./AuthError.js";
+import { ValidationError } from "./ValidationError.js";
+import { RemoteError } from "./RemoteError.js";
+import { KVError } from "./KVError.js";
+export { UnexpectedError } from "@qlever-llc/trellis-result";
+export { TrellisError } from "./TrellisError.js";
+export { AuthError } from "./AuthError.js";
+export { ValidationError } from "./ValidationError.js";
+export { RemoteError } from "./RemoteError.js";
+export { KVError } from "./KVError.js";
+export { AuthErrorDataSchema } from "./AuthError.js";
+export { ValidationErrorDataSchema, ValidationIssueSchema, } from "./ValidationError.js";
+export { RemoteErrorDataSchema } from "./RemoteError.js";
+export { KVErrorDataSchema } from "./KVError.js";
+/**
+ * Single source of truth for all Trellis errors.
+ * This object is used for compile-time type inference.
+ */
+const TRELLIS_ERRORS = {
+    UnexpectedError,
+    AuthError,
+    ValidationError,
+    RemoteError,
+    KVError,
+};

package/esm/trellis/globals.d.ts

@@ -0,0 +1,2 @@
+export declare const logger: import("pino").Logger<never, boolean>;
+//# sourceMappingURL=globals.d.ts.map

package/esm/trellis/globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../../src/trellis/globals.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,MAAM,uCAGjB,CAAC"}

package/esm/trellis/globals.js

@@ -0,0 +1,8 @@
+import { pino } from "pino";
+import { getEnv } from "./env.js";
+// Support Deno and browser (+ Svelte's strict TS rules)
+const level = getEnv("PINO_LEVEL") || "info";
+export const logger = pino({
+    level,
+    base: { library: "@qlever-llc/trellis" },
+});

package/esm/trellis/helpers.d.ts

@@ -0,0 +1,12 @@
+import type { Paginated } from "@qlever-llc/trellis-contracts";
+/**
+ * Compute the subject template from the message itself
+ */
+export declare function template(template: string, data: Record<string, string | number | boolean>, opts?: {
+    allowWildcards: boolean;
+}): string;
+export declare function escapeNats(token: string): string;
+export declare function escapeKvKey(key: string): string;
+export declare function decodeSubject(token: string): string;
+export declare function makePaginated(offset: number, limit: number, count: number): Paginated;
+//# sourceMappingURL=helpers.d.ts.map

package/esm/trellis/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/trellis/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAG/D;;GAEG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAC/C,IAAI,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC5D,MAAM,CAWR;AAGD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYhD;AAGD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAW/C;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUnD;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,SAAS,CAQX"}

package/esm/trellis/helpers.js

@@ -0,0 +1,47 @@
+import { Pointer } from "typebox/value";
+/**
+ * Compute the subject template from the message itself
+ */
+export function template(template, data, opts = { allowWildcards: false }) {
+    return template.replace(/\{([^}]+)\}/g, (_, key) => {
+        const token = Pointer.Get(data, key);
+        const v = token ? escapeNats(`${token}`) : "*";
+        if (!opts.allowWildcards && v === "*") {
+            throw new Error("All option templates must have values at runtime.");
+        }
+        return v;
+    });
+}
+const NATS_SUBJECT_TOKEN_FORBIDDEN = /[\u0000\s.*>~]/gu;
+export function escapeNats(token) {
+    const out = token.replace(NATS_SUBJECT_TOKEN_FORBIDDEN, (ch) => `~${ch.codePointAt(0).toString(16).toUpperCase()}~`);
+    // Protect start with $ due to NATS internal use of it
+    if (out.length === 0 || out.startsWith("$")) {
+        return `_${out}`;
+    }
+    return out;
+}
+const NATS_KV_KEY_FORBIDDEN = /[\u0000\s*>~]/gu;
+export function escapeKvKey(key) {
+    const out = key.replace(NATS_KV_KEY_FORBIDDEN, (ch) => `~${ch.codePointAt(0).toString(16).toUpperCase()}~`);
+    if (out.length === 0 || out.startsWith("$")) {
+        return `_${out}`;
+    }
+    return out;
+}
+export function decodeSubject(token) {
+    const out = token.replace(/~([0-9A-F]{1,6})~/g, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)));
+    if (out.startsWith("_$")) {
+        return out.slice(1);
+    }
+    return out;
+}
+export function makePaginated(offset, limit, count) {
+    return {
+        count,
+        offset,
+        limit,
+        next: offset + limit >= count ? undefined : offset + limit,
+        prev: offset - limit <= 0 ? undefined : offset - limit,
+    };
+}

package/esm/trellis/index.d.ts

@@ -0,0 +1,11 @@
+import "../_dnt.polyfills.js";
+export type { TrellisAPI } from "@qlever-llc/trellis-contracts";
+export { err, isErr, isOk, ok, Result } from "@qlever-llc/trellis-result";
+export type { ClientOpts } from "./client.js";
+export { createClient } from "./client.js";
+export type { TrellisErrorInstance } from "./errors/index.js";
+export { AuthError, KVError, RemoteError, TrellisError, UnexpectedError, ValidationError, } from "./errors/index.js";
+export { TypedKV } from "./kv.js";
+export type { TrellisAuth, TrellisSigner } from "./trellis.js";
+export { Trellis, TrellisServer } from "./trellis.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/trellis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/trellis/index.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAC1E,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EACL,SAAS,EACT,OAAO,EACP,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/esm/trellis/index.js

@@ -0,0 +1,6 @@
+import "../_dnt.polyfills.js";
+export { err, isErr, isOk, ok, Result } from "@qlever-llc/trellis-result";
+export { createClient } from "./client.js";
+export { AuthError, KVError, RemoteError, TrellisError, UnexpectedError, ValidationError, } from "./errors/index.js";
+export { TypedKV } from "./kv.js";
+export { Trellis, TrellisServer } from "./trellis.js";

package/esm/trellis/kv.d.ts

@@ -0,0 +1,67 @@
+import { type KV, type KvEntry } from "@nats-io/kv";
+import type { NatsConnection } from "@nats-io/nats-core/internal";
+import { Result } from "@qlever-llc/trellis-result";
+import type { StaticDecode, TSchema } from "typebox";
+import { KVError, ValidationError } from "./errors/index.js";
+/**
+ * Represents a watch event emitted when a KV entry changes.
+ */
+export type WatchEvent<S extends TSchema> = {
+    /** The type of change: "update" for new/modified values, "delete" for deletions */
+    type: "update" | "delete";
+    /** The key that changed */
+    key: string;
+    /** The new value (only present for update events) */
+    value?: StaticDecode<S>;
+    /** The revision number of this change */
+    revision: number;
+    /** The timestamp when this change occurred */
+    timestamp: Date;
+};
+/**
+ * Options for the watch() method.
+ */
+export type WatchOptions = {
+    /** If true, include delete events in the watch stream. Defaults to false. */
+    includeDeletes?: boolean;
+};
+export declare class TypedKV<S extends TSchema> {
+    readonly schema: S;
+    readonly kv: KV;
+    private constructor();
+    static open<S extends TSchema>(nats: NatsConnection, name: string, schema: S, options: {
+        history?: number;
+        ttl?: number;
+        bindOnly?: boolean;
+        maxValueBytes?: number;
+    }): Promise<Result<TypedKV<S>, KVError>>;
+    get(key: string): Promise<Result<TypedKVEntry<S>, KVError | ValidationError>>;
+    create(key: string, value: StaticDecode<S>): Promise<Result<void, KVError>>;
+    put(key: string, value: StaticDecode<S>): Promise<Result<void, KVError>>;
+    delete(key: string): Promise<Result<void, KVError>>;
+    keys(filter?: string | string[]): Promise<Result<AsyncIterable<string>, KVError>>;
+    status(): Promise<Result<{
+        values: number;
+    }, KVError>>;
+}
+export declare class TypedKVEntry<S extends TSchema> {
+    private schema;
+    private kv;
+    private entry;
+    readonly value: StaticDecode<S>;
+    constructor(schema: S, kv: KV, entry: KvEntry, value: StaticDecode<S>);
+    static create<S extends TSchema>(schema: S, kv: KV, entry: KvEntry): Promise<Result<TypedKVEntry<S>, ValidationError>>;
+    get key(): string;
+    /**
+     * Watch this KV entry for changes.
+     *
+     * @param callback - Function called when the entry changes
+     * @param opts - Watch options (e.g., includeDeletes)
+     * @returns A function to stop watching
+     */
+    watch(callback: (event: WatchEvent<S>) => void, opts?: WatchOptions): Promise<() => void>;
+    merge(value: Partial<StaticDecode<S>>, vcc?: boolean): Promise<Result<void, KVError | ValidationError>>;
+    put(value: StaticDecode<S>, vcc?: boolean): Promise<Result<void, KVError>>;
+    delete(vcc?: boolean): Promise<Result<void, KVError>>;
+}
+//# sourceMappingURL=kv.d.ts.map

package/esm/trellis/kv.d.ts.map

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

package/esm/trellis/kv.js

@@ -0,0 +1,326 @@
+// @ts-nocheck -- svelte-check hits pathological generic instantiation in this file
+import { Kvm } from "@nats-io/kv";
+import { Result } from "@qlever-llc/trellis-result";
+import { merge } from "ts-deepmerge";
+import Value, { ParseError } from "typebox/value";
+import { KVError, ValidationError } from "./errors/index.js";
+import { decodeSubject, escapeKvKey } from "./helpers.js";
+function externalizeValue(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(externalizeValue);
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry !== undefined) {
+                out[key] = externalizeValue(entry);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+function parseExternalValue(schema, value) {
+    if (Value.HasCodec(schema)) {
+        return Value.Decode(schema, value);
+    }
+    return Value.Parse(schema, value);
+}
+function serializeValue(schema, value) {
+    return JSON.stringify(Value.Parse(schema, externalizeValue(value)));
+}
+function serializeExternalValue(schema, value) {
+    return serializeValue(schema, value);
+}
+export class TypedKV {
+    constructor(schema, kv) {
+        Object.defineProperty(this, "schema", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: schema
+        });
+        Object.defineProperty(this, "kv", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: kv
+        });
+    }
+    static async open(nats, name, schema, options) {
+        try {
+            const kvm = new Kvm(nats);
+            const kv = options.bindOnly
+                ? await kvm.open(name)
+                : await kvm.create(name, {
+                    history: options.history ?? 1,
+                    ttl: options.ttl ?? 0,
+                    ...(options.maxValueBytes ? { maxValueSize: options.maxValueBytes } : {}),
+                });
+            const typedKv = new TypedKV(schema, kv);
+            return Result.ok(typedKv);
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "open", cause }));
+        }
+    }
+    async get(key) {
+        let s;
+        try {
+            s = await this.kv.get(escapeKvKey(key));
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "get", cause, context: { key } }));
+        }
+        if (!s) {
+            return Result.err(new KVError({
+                operation: "get",
+                context: { key, reason: "not found" },
+            }));
+        }
+        return await createTypedKvEntry(this.schema, this.kv, s);
+    }
+    async create(key, value) {
+        const schema = this.schema;
+        const rawValue = value;
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const serialized = serializeExternalValue(schema, rawValue);
+        try {
+            await this.kv.create(escapeKvKey(key), serialized);
+            return Result.ok(undefined);
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "create", cause, context: { key } }));
+        }
+    }
+    async put(key, value) {
+        const schema = this.schema;
+        const rawValue = value;
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const serialized = serializeExternalValue(schema, rawValue);
+        try {
+            await this.kv.put(escapeKvKey(key), serialized);
+            return Result.ok(undefined);
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "put", cause, context: { key } }));
+        }
+    }
+    async delete(key) {
+        try {
+            await this.kv.delete(escapeKvKey(key));
+            return Result.ok(undefined);
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "delete", cause, context: { key } }));
+        }
+    }
+    async keys(filter = ">") {
+        try {
+            return Result.ok(await this.kv.keys(filter));
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "keys", cause, context: { filter } }));
+        }
+    }
+    async status() {
+        try {
+            const status = await this.kv.status();
+            return Result.ok({ values: status.values });
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "status", cause }));
+        }
+    }
+}
+export class TypedKVEntry {
+    constructor(schema, kv, entry, value) {
+        Object.defineProperty(this, "schema", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: schema
+        });
+        Object.defineProperty(this, "kv", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: kv
+        });
+        Object.defineProperty(this, "entry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: entry
+        });
+        Object.defineProperty(this, "value", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // @ts-expect-error svelte-check hits excessive type instantiation on assignment
+        this.value = value;
+    }
+    static async create(schema, kv, entry) {
+        return await createTypedKvEntry(schema, kv, entry);
+    }
+    get key() {
+        return decodeSubject(this.entry.key);
+    }
+    /**
+     * Watch this KV entry for changes.
+     *
+     * @param callback - Function called when the entry changes
+     * @param opts - Watch options (e.g., includeDeletes)
+     * @returns A function to stop watching
+     */
+    async watch(callback, opts) {
+        const watcher = await this.kv.watch({
+            key: this.entry.key,
+            include: opts?.includeDeletes ? "history" : "updates",
+        });
+        const abortController = new AbortController();
+        // Start the async iteration in the background
+        (async () => {
+            for await (const entry of watcher) {
+                if (abortController.signal.aborted)
+                    break;
+                if (entry.operation === "DEL" || entry.operation === "PURGE") {
+                    if (opts?.includeDeletes) {
+                        callback({
+                            type: "delete",
+                            key: decodeSubject(entry.key),
+                            revision: entry.revision,
+                            timestamp: entry.created,
+                        });
+                    }
+                }
+                else {
+                    let validated;
+                    try {
+                        const json = entry.json();
+                        validated = parseExternalValue(this.schema, json);
+                    }
+                    catch {
+                        try {
+                            await this.kv.delete(entry.key, {
+                                previousSeq: entry.revision,
+                            });
+                        }
+                        catch {
+                            // Best-effort cleanup of invalid entries.
+                        }
+                        continue;
+                    }
+                    callback({
+                        type: "update",
+                        key: decodeSubject(entry.key),
+                        value: validated,
+                        revision: entry.revision,
+                        timestamp: entry.created,
+                    });
+                }
+            }
+        })();
+        return () => {
+            abortController.abort();
+            watcher.stop();
+        };
+    }
+    async merge(value, vcc) {
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const mergedData = merge(this.value, value);
+        const schema = this.schema;
+        const mergedRawValue = mergedData;
+        // @ts-expect-error svelte-check hits excessive type instantiation here
+        const mergeResult = Result.try(() => serializeExternalValue(schema, mergedRawValue));
+        if (mergeResult.isErr()) {
+            const cause = mergeResult.error.cause;
+            if (cause instanceof ParseError) {
+                const errors = Value.Errors(schema, externalizeValue(mergedData));
+                return Result.err(new ValidationError({ errors, cause }));
+            }
+            return Result.err(new KVError({ operation: "merge", cause: mergeResult.error, context: { key: this.key } }));
+        }
+        return this.put(mergedData, vcc);
+    }
+    async put(value, vcc) {
+        const schema = this.schema;
+        const serialized = serializeValue(schema, value);
+        try {
+            await this.kv.put(this.entry.key, serialized, {
+                previousSeq: vcc ? this.entry.revision : undefined,
+            });
+            return Result.ok(undefined);
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "put", cause, context: { key: this.key } }));
+        }
+    }
+    async delete(vcc) {
+        try {
+            await this.kv.delete(this.entry.key, {
+                previousSeq: vcc ? this.entry.revision : undefined,
+            });
+            return Result.ok(undefined);
+        }
+        catch (cause) {
+            return Result.err(new KVError({ operation: "delete", cause, context: { key: this.key } }));
+        }
+    }
+}
+async function createTypedKvEntry(schema, kv, entry) {
+    async function deleteInvalidEntry(reason) {
+        try {
+            await kv.delete(entry.key, {
+                previousSeq: entry.revision,
+            });
+            return {
+                key: decodeSubject(entry.key),
+                revision: entry.revision,
+                invalidEntryDeleted: true,
+                invalidEntryReason: reason,
+            };
+        }
+        catch (cause) {
+            return {
+                key: decodeSubject(entry.key),
+                revision: entry.revision,
+                invalidEntryDeleted: false,
+                invalidEntryDeleteError: cause instanceof Error ? cause.message : String(cause),
+                invalidEntryReason: reason,
+            };
+        }
+    }
+    const jsonResult = Result.try(() => entry.json());
+    if (jsonResult.isErr()) {
+        const context = await deleteInvalidEntry(`decode failed: ${jsonResult.error.message}`);
+        return Result.err(new ValidationError({
+            errors: [{ path: "", message: `Failed to decode KV value: ${jsonResult.error.message}` }],
+            cause: jsonResult.error,
+            context,
+        }));
+    }
+    const json = jsonResult.take();
+    const parseResult = Result.try(() => parseExternalValue(schema, json));
+    if (parseResult.isErr()) {
+        const cause = parseResult.error.cause;
+        if (cause instanceof ParseError) {
+            const errors = Value.Errors(schema, json);
+            const context = await deleteInvalidEntry("schema parse failed");
+            return Result.err(new ValidationError({ errors, cause, context }));
+        }
+        const context = await deleteInvalidEntry(parseResult.error.message);
+        return Result.err(new ValidationError({
+            errors: [{ path: "", message: parseResult.error.message }],
+            cause: parseResult.error,
+            context,
+        }));
+    }
+    const typedEntry = new TypedKVEntry(schema, kv, entry, parseResult.take());
+    return Result.ok(typedEntry);
+}