@relkit/cache 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rel-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @relkit/cache
+
+Caches declare typed keys, values, logical profiles, and TTL policy. Runtime
+clients are available only to functions that declare the cache dependency.
+
+```ts
+import { defineCache } from "@relkit/app/cache";
+import { z } from "@relkit/app/schema";
+
+export default defineCache({
+  id: "prices",
+  profile: "low-latency",
+  key: z.object({ sku: z.string() }),
+  value: z.number().int().nonnegative(),
+  defaultTtlMs: 60_000,
+  maxTtlMs: 300_000,
+});
+```
+
+Declared functions receive a Promise client with schema-validated keys and
+values. TTL options use the descriptor policy; numeric value schemas also
+expose `increment`.

package/dist/client-operations.d.ts

@@ -0,0 +1,14 @@
+import type { MaybePromise } from "@relkit/contracts";
+import type { InferInput, InferOutput, StandardSchemaV1 } from "@relkit/schema";
+import { type CacheClient, type CacheOperation, type CacheOperationContext, type CacheProvider } from "./client-types.js";
+interface CacheOperationDependencies<KeySchema extends StandardSchemaV1, ValueSchema extends StandardSchemaV1> {
+    readonly provider: CacheProvider;
+    readonly keySchema: KeySchema | undefined;
+    readonly valueSchema: ValueSchema | undefined;
+    readonly defaultTtlMs: number | undefined;
+    readonly maxTtlMs: number | undefined;
+    readonly call: <A>(operation: CacheOperation, work: (context: CacheOperationContext) => MaybePromise<A>, validate: (value: A) => MaybePromise<A>, capability?: "increment") => Promise<A>;
+}
+export declare function createCacheOperations<const KeySchema extends StandardSchemaV1, const ValueSchema extends StandardSchemaV1>(dependencies: CacheOperationDependencies<KeySchema, ValueSchema>): CacheClient<InferInput<KeySchema>, InferOutput<ValueSchema>>;
+export {};
+//# sourceMappingURL=client-operations.d.ts.map

package/dist/client-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-operations.d.ts","sourceRoot":"","sources":["../src/client-operations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAE1B,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAS3B,UAAU,0BAA0B,CAClC,SAAS,SAAS,gBAAgB,EAClC,WAAW,SAAS,gBAAgB;IAEpC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EACf,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,YAAY,CAAC,CAAC,CAAC,EACzD,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,EACvC,UAAU,CAAC,EAAE,WAAW,KACrB,OAAO,CAAC,CAAC,CAAC,CAAC;CACjB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,CAAC,SAAS,SAAS,gBAAgB,EACxC,KAAK,CAAC,WAAW,SAAS,gBAAgB,EAE1C,YAAY,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,GAC/D,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC,CA0F9D"}

package/dist/client-operations.js

@@ -0,0 +1,38 @@
+import { CacheIncrementUnsupportedError, } from "./client-types.js";
+import { normalizeTtl, required, validateBoolean, validateIncrementDelta, validateSchema, } from "./client-utils.js";
+export function createCacheOperations(dependencies) {
+    const { provider, keySchema, valueSchema, defaultTtlMs, maxTtlMs, call } = dependencies;
+    const parseKey = (key) => validateSchema(keySchema, key, "key");
+    const parseValue = (value) => validateSchema(valueSchema, value, "value");
+    const ttl = (optionsValue) => normalizeTtl(optionsValue?.ttlMs, defaultTtlMs, maxTtlMs);
+    const client = {
+        get: (key) => call("get", async (context) => required(provider.get, "get")(await parseKey(key), context), async (value) => (value === undefined ? undefined : await parseValue(value))),
+        set: (key, value, optionsValue) => call("set", async (context) => required(provider.set, "set")(await parseKey(key), await parseValue(value), ttl(optionsValue), context), () => undefined),
+        delete: (key) => call("delete", async (context) => required(provider.delete, "delete")(await parseKey(key), context), () => undefined),
+        has: (key) => call("has", async (context) => required(provider.has, "has")(await parseKey(key), context), validateBoolean),
+        getOrSet: (key, produce, optionsValue) => call("getOrSet", async (context) => required(provider.getOrSet, "getOrSet")(await parseKey(key), async () => parseValue(await produce()), ttl(optionsValue), context), (value) => parseValue(value)),
+        increment: (key, delta = 1, optionsValue) => call("increment", async (context) => {
+            const amount = validateIncrementDelta(delta);
+            if (valueSchema !== undefined) {
+                try {
+                    const zero = await parseValue(0);
+                    if (typeof zero !== "number")
+                        throw new CacheIncrementUnsupportedError();
+                }
+                catch (cause) {
+                    if (cause instanceof CacheIncrementUnsupportedError)
+                        throw cause;
+                    throw new CacheIncrementUnsupportedError();
+                }
+            }
+            return required(provider.increment, "increment")(await parseKey(key), amount, ttl(optionsValue), context);
+        }, async (value) => {
+            const parsed = await parseValue(value);
+            if (typeof parsed !== "number")
+                throw new CacheIncrementUnsupportedError();
+            return parsed;
+        }, "increment"),
+    };
+    return Object.freeze(client);
+}
+//# sourceMappingURL=client-operations.js.map

package/dist/client-operations.js.map

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

package/dist/client-types.d.ts

@@ -0,0 +1,118 @@
+import type { MaybePromise } from "@relkit/contracts";
+import type { StandardIssue, StandardSchemaV1 } from "@relkit/schema";
+export type CacheOperation = "get" | "set" | "delete" | "has" | "getOrSet" | "increment";
+export type CacheCapability = "increment";
+export type CacheOperationOutcome = "success" | "provider-failure" | "cancelled" | "timeout" | "unsupported" | "validation-error";
+export interface CacheOperationOptions {
+    readonly ttlMs?: number;
+}
+export interface CacheOperationContext {
+    readonly operation: CacheOperation;
+    readonly signal: AbortSignal;
+    readonly deadlineMs?: number;
+}
+export interface CacheCapabilities {
+    readonly increment?: boolean;
+}
+export interface CacheProvider {
+    readonly capabilities?: CacheCapabilities | readonly CacheCapability[];
+    readonly get?: (key: unknown, context?: CacheOperationContext) => MaybePromise<unknown | undefined>;
+    readonly set?: (key: unknown, value: unknown, options?: CacheOperationOptions, context?: CacheOperationContext) => MaybePromise<void>;
+    readonly delete?: (key: unknown, context?: CacheOperationContext) => MaybePromise<void>;
+    readonly has?: (key: unknown, context?: CacheOperationContext) => MaybePromise<boolean>;
+    readonly getOrSet?: (key: unknown, produce: () => MaybePromise<unknown>, options?: CacheOperationOptions, context?: CacheOperationContext) => MaybePromise<unknown>;
+    readonly increment?: (key: unknown, delta: number, options?: CacheOperationOptions, context?: CacheOperationContext) => MaybePromise<unknown>;
+}
+export interface CacheClientBase<Key, Value> {
+    get(key: Key): Promise<Value | undefined>;
+    set(key: Key, value: Value, options?: CacheOperationOptions): Promise<void>;
+    delete(key: Key): Promise<void>;
+    has(key: Key): Promise<boolean>;
+    getOrSet(key: Key, produce: () => MaybePromise<Value>, options?: CacheOperationOptions): Promise<Value>;
+}
+export type CacheNumericClient<Key, Value extends number> = {
+    increment(key: Key, delta?: number, options?: CacheOperationOptions): Promise<Value>;
+};
+/** Numeric increment is intentionally absent from non-numeric value contracts. */
+export type CacheClient<Key, Value> = CacheClientBase<Key, Value> & ([Value] extends [number] ? CacheNumericClient<Key, Value> : object);
+export interface CacheBridgeOptions {
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, unknown>>;
+    readonly signal: AbortSignal;
+}
+export interface CacheInvocationBridge {
+    readonly run: <A>(operation: () => MaybePromise<A>, options?: CacheBridgeOptions) => Promise<A>;
+}
+export interface CacheObservedEdge {
+    readonly relationship: "uses-cache";
+    readonly from: string;
+    readonly to: string;
+}
+export interface CacheOperationObservation {
+    readonly capability: "cache";
+    readonly operation: CacheOperation;
+    readonly ownerId: string;
+    readonly cacheId: string;
+    readonly outcome: CacheOperationOutcome;
+}
+export interface CacheDescriptorPolicy {
+    readonly key?: StandardSchemaV1;
+    readonly value?: StandardSchemaV1;
+    readonly defaultTtlMs?: number;
+    readonly maxTtlMs?: number;
+}
+export interface CacheClientOptions<KeySchema extends StandardSchemaV1 = StandardSchemaV1, ValueSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    readonly ownerId: string;
+    readonly cacheId: string;
+    readonly source: unknown;
+    readonly keySchema?: KeySchema;
+    readonly valueSchema?: ValueSchema;
+    readonly key?: KeySchema;
+    readonly value?: ValueSchema;
+    readonly descriptor?: CacheDescriptorPolicy;
+    readonly defaultTtlMs?: number;
+    readonly maxTtlMs?: number;
+    readonly bridge?: CacheInvocationBridge;
+    readonly signal?: () => AbortSignal;
+    readonly deadline?: () => number | undefined;
+    readonly declared?: boolean;
+    readonly onObservedEdge?: (edge: CacheObservedEdge) => void;
+    readonly onOperation?: (operation: CacheOperationObservation) => void;
+}
+export declare class CacheCapabilityError extends Error {
+    readonly capability: CacheCapability;
+    readonly operation: CacheOperation;
+    readonly code: "RELKIT_CACHE_CAPABILITY_UNSUPPORTED";
+    constructor(capability: CacheCapability, operation: CacheOperation);
+}
+export declare class CacheDependencyError extends Error {
+    readonly code: "RELKIT_CACHE_DEPENDENCY_UNDECLARED";
+    constructor(cacheId: string);
+}
+export declare class CacheProviderError extends Error {
+    readonly code: "RELKIT_CACHE_PROVIDER_UNAVAILABLE";
+    constructor(operation: CacheOperation);
+}
+export declare class CacheSchemaValidationError extends TypeError {
+    readonly phase: "key" | "value";
+    readonly issues: readonly StandardIssue[];
+    readonly code: "RELKIT_CACHE_SCHEMA_VALIDATION";
+    constructor(phase: "key" | "value", issues: readonly StandardIssue[]);
+}
+export declare class CacheTtlPolicyError extends RangeError {
+    readonly code: "RELKIT_CACHE_TTL_POLICY";
+    constructor(message: string);
+}
+export declare class CacheIncrementUnsupportedError extends Error {
+    readonly code: "RELKIT_CACHE_INCREMENT_UNSUPPORTED";
+    constructor();
+}
+export declare class CacheOperationCancelledError extends Error {
+    readonly code: "ABORT_ERR";
+    constructor();
+}
+export declare class CacheOperationTimeoutError extends Error {
+    readonly code: "ETIMEDOUT";
+    constructor();
+}
+//# sourceMappingURL=client-types.d.ts.map

package/dist/client-types.d.ts.map

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

package/dist/client-types.js

@@ -0,0 +1,65 @@
+export class CacheCapabilityError extends Error {
+    capability;
+    operation;
+    code = "RELKIT_CACHE_CAPABILITY_UNSUPPORTED";
+    constructor(capability, operation) {
+        super(`Cache operation "${operation}" requires unsupported capability "${capability}"`);
+        this.capability = capability;
+        this.operation = operation;
+        this.name = "CacheCapabilityError";
+    }
+}
+export class CacheDependencyError extends Error {
+    code = "RELKIT_CACHE_DEPENDENCY_UNDECLARED";
+    constructor(cacheId) {
+        super(`Cache dependency "${cacheId}" is not declared on this function`);
+        this.name = "CacheDependencyError";
+    }
+}
+export class CacheProviderError extends Error {
+    code = "RELKIT_CACHE_PROVIDER_UNAVAILABLE";
+    constructor(operation) {
+        super(`Cache provider does not implement "${operation}"`);
+        this.name = "CacheProviderError";
+    }
+}
+export class CacheSchemaValidationError extends TypeError {
+    phase;
+    issues;
+    code = "RELKIT_CACHE_SCHEMA_VALIDATION";
+    constructor(phase, issues) {
+        super(`Cache ${phase} validation failed`);
+        this.phase = phase;
+        this.issues = issues;
+        this.name = "CacheSchemaValidationError";
+    }
+}
+export class CacheTtlPolicyError extends RangeError {
+    code = "RELKIT_CACHE_TTL_POLICY";
+    constructor(message) {
+        super(message);
+        this.name = "CacheTtlPolicyError";
+    }
+}
+export class CacheIncrementUnsupportedError extends Error {
+    code = "RELKIT_CACHE_INCREMENT_UNSUPPORTED";
+    constructor() {
+        super("Cache increment requires a numeric value contract");
+        this.name = "CacheIncrementUnsupportedError";
+    }
+}
+export class CacheOperationCancelledError extends Error {
+    code = "ABORT_ERR";
+    constructor() {
+        super("Cache operation cancelled");
+        this.name = "AbortError";
+    }
+}
+export class CacheOperationTimeoutError extends Error {
+    code = "ETIMEDOUT";
+    constructor() {
+        super("Cache operation timed out");
+        this.name = "TimeoutError";
+    }
+}
+//# sourceMappingURL=client-types.js.map

package/dist/client-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-types.js","sourceRoot":"","sources":["../src/client-types.ts"],"names":[],"mappings":"AA2HA,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAIlC;IACA;IAJF,IAAI,GAAG,qCAA8C,CAAC;IAE/D,YACW,UAA2B,EAC3B,SAAyB;QAElC,KAAK,CAAC,oBAAoB,SAAS,sCAAsC,UAAU,GAAG,CAAC,CAAC;QAH/E,eAAU,GAAV,UAAU,CAAiB;QAC3B,cAAS,GAAT,SAAS,CAAgB;QAGlC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,oCAA6C,CAAC;IAE9D,YAAY,OAAe;QACzB,KAAK,CAAC,qBAAqB,OAAO,oCAAoC,CAAC,CAAC;QACxE,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,mCAA4C,CAAC;IAE7D,YAAY,SAAyB;QACnC,KAAK,CAAC,sCAAsC,SAAS,GAAG,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,SAAS;IAI5C;IACA;IAJF,IAAI,GAAG,gCAAyC,CAAC;IAE1D,YACW,KAAsB,EACtB,MAAgC;QAEzC,KAAK,CAAC,SAAS,KAAK,oBAAoB,CAAC,CAAC;QAHjC,UAAK,GAAL,KAAK,CAAiB;QACtB,WAAM,GAAN,MAAM,CAA0B;QAGzC,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,UAAU;IACxC,IAAI,GAAG,yBAAkC,CAAC;IAEnD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAC9C,IAAI,GAAG,oCAA6C,CAAC;IAE9D;QACE,KAAK,CAAC,mDAAmD,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAC5C,IAAI,GAAG,WAAoB,CAAC;IAErC;QACE,KAAK,CAAC,2BAA2B,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,GAAG,WAAoB,CAAC;IAErC;QACE,KAAK,CAAC,2BAA2B,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/client-utils.d.ts

@@ -0,0 +1,15 @@
+import type { MaybePromise } from "@relkit/contracts";
+import { type CacheCapability, type CacheOperation, type CacheOperationOutcome, type CacheOperationOptions, type CacheProvider } from "./client-types.js";
+import type { StandardSchemaV1 } from "@relkit/schema";
+export declare function required<A>(value: ((...args: any[]) => MaybePromise<A>) | undefined, operation: CacheOperation): (...args: any[]) => MaybePromise<A>;
+export declare function asProvider(value: unknown): CacheProvider;
+export declare function supports(value: CacheProvider["capabilities"], capability: CacheCapability): boolean;
+export declare function runAbortable<A>(signal: AbortSignal, deadlineMs: number | undefined, work: () => MaybePromise<A>): Promise<A>;
+export declare function validateSchema(schema: StandardSchemaV1 | undefined, value: unknown, phase: "key" | "value"): Promise<unknown>;
+export declare function normalizeTtl(value: unknown, defaultTtlMs: number | undefined, maxTtlMs: number | undefined): CacheOperationOptions | undefined;
+export declare function validatePolicy(value: number | undefined, name: string): void;
+export declare function validateBoolean(value: unknown): boolean;
+export declare function validateIncrementDelta(value: unknown): number;
+export declare function classify(value: unknown): CacheOperationOutcome;
+export declare function notify<T>(hook: ((value: T) => void) | undefined, value: T): void;
+//# sourceMappingURL=client-utils.d.ts.map

package/dist/client-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-utils.d.ts","sourceRoot":"","sources":["../src/client-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EASL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,EACxD,SAAS,EAAE,cAAc,GACxB,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,YAAY,CAAC,CAAC,CAAC,CAGrC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAIxD;AAED,wBAAgB,QAAQ,CACtB,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,EACpC,UAAU,EAAE,eAAe,GAC1B,OAAO,CAIT;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAoCZ;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,KAAK,GAAG,OAAO,GACrB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,qBAAqB,GAAG,SAAS,CAUnC;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI5E;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGvD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAK7D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAQ9D;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAMhF"}

package/dist/client-utils.js

@@ -0,0 +1,123 @@
+import { CacheCapabilityError, CacheIncrementUnsupportedError, CacheOperationCancelledError, CacheOperationTimeoutError, CacheProviderError, CacheSchemaValidationError, CacheTtlPolicyError, } from "./client-types.js";
+export function required(value, operation) {
+    if (value === undefined)
+        throw new CacheProviderError(operation);
+    return value;
+}
+export function asProvider(value) {
+    if (value === undefined)
+        return {};
+    if (value === null || typeof value !== "object")
+        throw new CacheProviderError("get");
+    return value;
+}
+export function supports(value, capability) {
+    if (value === undefined)
+        return true;
+    if (Array.isArray(value))
+        return value.includes(capability);
+    return value[capability] === true;
+}
+export function runAbortable(signal, deadlineMs, work) {
+    if (signal.aborted)
+        return Promise.reject(new CacheOperationCancelledError());
+    if (deadlineMs !== undefined && deadlineMs <= Date.now())
+        return Promise.reject(new CacheOperationTimeoutError());
+    const pending = Promise.resolve().then(work);
+    return new Promise((resolve, reject) => {
+        let timer;
+        const cleanup = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+        };
+        const abort = () => {
+            cleanup();
+            reject(new CacheOperationCancelledError());
+        };
+        if (deadlineMs !== undefined) {
+            timer = setTimeout(() => {
+                cleanup();
+                reject(new CacheOperationTimeoutError());
+            }, Math.max(0, deadlineMs - Date.now()));
+        }
+        signal.addEventListener("abort", abort, { once: true });
+        pending.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (cause) => {
+            cleanup();
+            reject(cause);
+        });
+    });
+}
+export async function validateSchema(schema, value, phase) {
+    if (schema === undefined)
+        return value;
+    let result;
+    try {
+        result = await schema["~standard"].validate(value);
+    }
+    catch {
+        throw new CacheSchemaValidationError(phase, [{ message: `Invalid cache ${phase}` }]);
+    }
+    if ("issues" in result && result.issues !== undefined) {
+        throw new CacheSchemaValidationError(phase, freezeIssues(result.issues));
+    }
+    return result.value;
+}
+export function normalizeTtl(value, defaultTtlMs, maxTtlMs) {
+    const ttlMs = value === undefined ? defaultTtlMs : value;
+    if (ttlMs === undefined)
+        return undefined;
+    if (typeof ttlMs !== "number" || !Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+        throw new CacheTtlPolicyError("Cache ttlMs must be a positive integer");
+    }
+    if (maxTtlMs !== undefined && ttlMs > maxTtlMs) {
+        throw new CacheTtlPolicyError("Cache ttlMs exceeds the configured maximum");
+    }
+    return { ttlMs };
+}
+export function validatePolicy(value, name) {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+        throw new CacheTtlPolicyError(`Cache ${name} must be a positive integer`);
+    }
+}
+export function validateBoolean(value) {
+    if (typeof value !== "boolean")
+        throw new TypeError("Cache has must return a boolean");
+    return value;
+}
+export function validateIncrementDelta(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new TypeError("Cache increment delta must be a finite number");
+    }
+    return value;
+}
+export function classify(value) {
+    const name = value?.name;
+    if (value instanceof CacheSchemaValidationError)
+        return "validation-error";
+    if (value instanceof CacheCapabilityError || value instanceof CacheIncrementUnsupportedError)
+        return "unsupported";
+    if (value instanceof CacheOperationCancelledError || name === "AbortError")
+        return "cancelled";
+    if (value instanceof CacheOperationTimeoutError || name === "TimeoutError")
+        return "timeout";
+    return "provider-failure";
+}
+export function notify(hook, value) {
+    try {
+        hook?.(Object.freeze(value));
+    }
+    catch {
+        // Hooks are advisory and cannot change cache behavior.
+    }
+}
+function freezeIssues(issues) {
+    return Object.freeze(issues.map((issue) => Object.freeze({
+        message: issue.message,
+        ...(issue.path === undefined ? {} : { path: Object.freeze([...issue.path]) }),
+    })));
+}
+//# sourceMappingURL=client-utils.js.map

package/dist/client-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-utils.js","sourceRoot":"","sources":["../src/client-utils.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,8BAA8B,EAC9B,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,GAOpB,MAAM,mBAAmB,CAAC;AAG3B,MAAM,UAAU,QAAQ,CACtB,KAAwD,EACxD,SAAyB;IAEzB,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACjE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACrF,OAAO,KAAsB,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,KAAoC,EACpC,UAA2B;IAE3B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC5D,OAAQ,KAA2B,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,MAAmB,EACnB,UAA8B,EAC9B,IAA2B;IAE3B,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,4BAA4B,EAAE,CAAC,CAAC;IAC9E,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE;QACtD,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,0BAA0B,EAAE,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,IAAI,KAAgD,CAAC;QACrD,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,IAAI,KAAK,KAAK,SAAS;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC7C,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,GAAS,EAAE;YACvB,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,IAAI,4BAA4B,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC;QACF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE;gBACH,OAAO,EAAE,CAAC;gBACV,MAAM,CAAC,IAAI,0BAA0B,EAAE,CAAC,CAAC;YAC3C,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CACrC,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,OAAO,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;YACR,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAoC,EACpC,KAAc,EACd,KAAsB;IAEtB,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,MAAsE,CAAC;IAC3E,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,0BAA0B,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,QAAQ,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,IAAI,0BAA0B,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,YAAgC,EAChC,QAA4B;IAE5B,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC;IACzD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,mBAAmB,CAAC,wCAAwC,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,QAAQ,KAAK,SAAS,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;QAC/C,MAAM,IAAI,mBAAmB,CAAC,4CAA4C,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAyB,EAAE,IAAY;IACpE,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,mBAAmB,CAAC,SAAS,IAAI,6BAA6B,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,MAAM,IAAI,GAAI,KAA4B,EAAE,IAAI,CAAC;IACjD,IAAI,KAAK,YAAY,0BAA0B;QAAE,OAAO,kBAAkB,CAAC;IAC3E,IAAI,KAAK,YAAY,oBAAoB,IAAI,KAAK,YAAY,8BAA8B;QAC1F,OAAO,aAAa,CAAC;IACvB,IAAI,KAAK,YAAY,4BAA4B,IAAI,IAAI,KAAK,YAAY;QAAE,OAAO,WAAW,CAAC;IAC/F,IAAI,KAAK,YAAY,0BAA0B,IAAI,IAAI,KAAK,cAAc;QAAE,OAAO,SAAS,CAAC;IAC7F,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,MAAM,CAAI,IAAsC,EAAE,KAAQ;IACxE,IAAI,CAAC;QACH,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,MAAgC;IACpD,OAAO,MAAM,CAAC,MAAM,CAClB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACnB,MAAM,CAAC,MAAM,CAAC;QACZ,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;KAC9E,CAAC,CACH,CACF,CAAC;AACJ,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import { type CacheClient, type CacheClientOptions } from "./client-types.js";
+import type { InferInput, InferOutput, StandardSchemaV1 } from "@relkit/schema";
+export { CacheCapabilityError, CacheDependencyError, CacheIncrementUnsupportedError, CacheOperationCancelledError, CacheOperationTimeoutError, CacheProviderError, CacheSchemaValidationError, CacheTtlPolicyError, } from "./client-types.js";
+export type * from "./client-types.js";
+export declare function createCacheClient<const KeySchema extends StandardSchemaV1 = StandardSchemaV1, const ValueSchema extends StandardSchemaV1 = StandardSchemaV1>(options: CacheClientOptions<KeySchema, ValueSchema>): CacheClient<InferInput<KeySchema>, InferOutput<ValueSchema>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EAIxB,MAAM,mBAAmB,CAAC;AAU3B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,8BAA8B,EAC9B,4BAA4B,EAC5B,0BAA0B,EAC1B,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,mBAAmB,mBAAmB,CAAC;AAEvC,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EAC3D,KAAK,CAAC,WAAW,SAAS,gBAAgB,GAAG,gBAAgB,EAE7D,OAAO,EAAE,kBAAkB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC,CA+E9D"}

package/dist/client.js

@@ -0,0 +1,88 @@
+import { CacheCapabilityError, CacheDependencyError, CacheTtlPolicyError, } from "./client-types.js";
+import { asProvider, classify, notify, runAbortable, supports, validatePolicy, } from "./client-utils.js";
+import { createCacheOperations } from "./client-operations.js";
+export { CacheCapabilityError, CacheDependencyError, CacheIncrementUnsupportedError, CacheOperationCancelledError, CacheOperationTimeoutError, CacheProviderError, CacheSchemaValidationError, CacheTtlPolicyError, } from "./client-types.js";
+export function createCacheClient(options) {
+    assertText(options.ownerId, "ownerId");
+    assertText(options.cacheId, "cacheId");
+    const provider = asProvider(options.source);
+    const keySchema = (options.keySchema ?? options.key ?? options.descriptor?.key);
+    const valueSchema = (options.valueSchema ?? options.value ?? options.descriptor?.value);
+    assertSchema(keySchema, "key");
+    assertSchema(valueSchema, "value");
+    const defaultTtlMs = options.defaultTtlMs ?? options.descriptor?.defaultTtlMs;
+    const maxTtlMs = options.maxTtlMs ?? options.descriptor?.maxTtlMs;
+    validatePolicy(defaultTtlMs, "defaultTtlMs");
+    validatePolicy(maxTtlMs, "maxTtlMs");
+    if (defaultTtlMs !== undefined && maxTtlMs !== undefined && defaultTtlMs > maxTtlMs) {
+        throw new CacheTtlPolicyError("Cache defaultTtlMs must not exceed maxTtlMs");
+    }
+    const declared = options.declared !== false;
+    const run = (operation, capability, work, validate) => {
+        const signal = options.signal?.() ?? new AbortController().signal;
+        const deadlineMs = options.deadline?.();
+        let outcome = "provider-failure";
+        const execute = async () => {
+            if (!declared)
+                throw new CacheDependencyError(options.cacheId);
+            if (capability !== undefined && !supports(provider.capabilities, capability)) {
+                throw new CacheCapabilityError(capability, operation);
+            }
+            const context = { operation, signal, ...(deadlineMs === undefined ? {} : { deadlineMs }) };
+            const value = await (options.bridge
+                ? work(context)
+                : runAbortable(signal, deadlineMs, () => work(context)));
+            const result = await validate(value);
+            outcome = "success";
+            return result;
+        };
+        if (declared) {
+            notify(options.onObservedEdge, {
+                relationship: "uses-cache",
+                from: options.ownerId,
+                to: options.cacheId,
+            });
+        }
+        const bridgeOptions = {
+            name: `relkit.cache.${options.cacheId}.${operation}`,
+            attributes: { "relkit.cache.id": options.cacheId, "relkit.cache.operation": operation },
+            signal,
+        };
+        const promise = options.bridge ? options.bridge.run(execute, bridgeOptions) : execute();
+        return Promise.resolve(promise)
+            .catch((cause) => {
+            outcome = classify(cause);
+            throw cause;
+        })
+            .finally(() => notify(options.onOperation, {
+            capability: "cache",
+            operation,
+            ownerId: options.ownerId,
+            cacheId: options.cacheId,
+            outcome,
+        }));
+    };
+    const client = createCacheOperations({
+        provider,
+        keySchema,
+        valueSchema,
+        defaultTtlMs,
+        maxTtlMs,
+        call: (operation, work, validate, capability) => run(operation, capability, work, validate),
+    });
+    return client;
+}
+function assertText(value, name) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new TypeError(`Cache ${name} must be non-empty`);
+    }
+}
+function assertSchema(value, name) {
+    if (value === undefined)
+        return;
+    const standard = value["~standard"];
+    if (standard?.version !== 1 || typeof standard.validate !== "function") {
+        throw new TypeError(`Cache ${name} must be a Standard Schema v1 validator`);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/define-cache.d.ts

@@ -0,0 +1,38 @@
+import { type DescriptorBase, type DescriptorMetadata } from "@relkit/contracts";
+import { type InferInput, type InferOutput, type StandardSchemaV1 } from "@relkit/schema";
+export interface CacheDescriptor<Id extends string, Key, Value, KeySchema extends StandardSchemaV1 = StandardSchemaV1, ValueSchema extends StandardSchemaV1 = StandardSchemaV1> extends DescriptorBase<"cache", Id> {
+    readonly profile?: string;
+    readonly key: KeySchema;
+    readonly value: ValueSchema;
+    readonly defaultTtlMs?: number;
+    readonly maxTtlMs?: number;
+    readonly __key?: Key;
+    readonly __value?: Value;
+}
+export type CacheDescriptorAny = CacheDescriptor<string, unknown, unknown>;
+export interface DefineCacheOptions<Id extends string, KeySchema extends StandardSchemaV1, ValueSchema extends StandardSchemaV1> extends DescriptorMetadata {
+    readonly id: Id;
+    readonly profile?: string;
+    readonly key: KeySchema;
+    readonly value: ValueSchema;
+    readonly defaultTtlMs?: number;
+    readonly maxTtlMs?: number;
+}
+/**
+ * Defines a typed cache contract with validated key/value schemas and TTL bounds.
+ *
+ * @example
+ * ```ts
+ * import { defineCache } from "@relkit/app/cache"
+ * import { z } from "@relkit/app/schema"
+ *
+ * const prices = defineCache({ id: "prices", key: z.string(), value: z.number(), defaultTtlMs: 60_000 })
+ * void prices
+ * ```
+ * @category Resources
+ * @since 0.1.0
+ */
+export declare function defineCache<const Id extends string, const KeySchema extends StandardSchemaV1, const ValueSchema extends StandardSchemaV1>(options: DefineCacheOptions<Id, KeySchema, ValueSchema>): CacheDescriptor<Id, InferInput<KeySchema>, InferOutput<ValueSchema>, KeySchema, ValueSchema>;
+export declare function isCacheDescriptor(value: unknown): value is CacheDescriptorAny;
+export declare function assertCacheDescriptor(value: unknown): asserts value is CacheDescriptorAny;
+//# sourceMappingURL=define-cache.d.ts.map

package/dist/define-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-cache.d.ts","sourceRoot":"","sources":["../src/define-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE1F,MAAM,WAAW,eAAe,CAC9B,EAAE,SAAS,MAAM,EACjB,GAAG,EACH,KAAK,EACL,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EACrD,WAAW,SAAS,gBAAgB,GAAG,gBAAgB,CACvD,SAAQ,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAE3E,MAAM,WAAW,kBAAkB,CACjC,EAAE,SAAS,MAAM,EACjB,SAAS,SAAS,gBAAgB,EAClC,WAAW,SAAS,gBAAgB,CACpC,SAAQ,kBAAkB;IAC1B,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,EAAE,SAAS,MAAM,EACvB,KAAK,CAAC,SAAS,SAAS,gBAAgB,EACxC,KAAK,CAAC,WAAW,SAAS,gBAAgB,EAE1C,OAAO,EAAE,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,GACtD,eAAe,CAAC,EAAE,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,CA4B9F;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAa7E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,kBAAkB,CAEzF"}

package/dist/define-cache.js

@@ -0,0 +1,91 @@
+import { createDescriptorBase, deepFreeze, isDescriptor, normalizeId, } from "@relkit/contracts";
+import {} from "@relkit/schema";
+/**
+ * Defines a typed cache contract with validated key/value schemas and TTL bounds.
+ *
+ * @example
+ * ```ts
+ * import { defineCache } from "@relkit/app/cache"
+ * import { z } from "@relkit/app/schema"
+ *
+ * const prices = defineCache({ id: "prices", key: z.string(), value: z.number(), defaultTtlMs: 60_000 })
+ * void prices
+ * ```
+ * @category Resources
+ * @since 0.1.0
+ */
+export function defineCache(options) {
+    if (!isRecord(options))
+        throw new TypeError("Cache options must be an object");
+    if (hasOwn(options, "handler"))
+        throw new TypeError("Caches cannot own handlers");
+    assertSchema(options.key, "key");
+    assertSchema(options.value, "value");
+    const profile = options.profile === undefined ? undefined : normalizeId(options.profile);
+    const defaultTtlMs = validateTtl(options.defaultTtlMs, "defaultTtlMs");
+    const maxTtlMs = validateTtl(options.maxTtlMs, "maxTtlMs");
+    if (defaultTtlMs !== undefined && maxTtlMs !== undefined && defaultTtlMs > maxTtlMs) {
+        throw new TypeError("defaultTtlMs must not exceed maxTtlMs");
+    }
+    const base = createDescriptorBase("cache", options.id, options);
+    return deepFreeze({
+        ...base,
+        key: options.key,
+        value: options.value,
+        ...(profile === undefined ? {} : { profile }),
+        ...(defaultTtlMs === undefined ? {} : { defaultTtlMs }),
+        ...(maxTtlMs === undefined ? {} : { maxTtlMs }),
+    });
+}
+export function isCacheDescriptor(value) {
+    if (!isRecord(value) || !isDescriptor(value, "cache"))
+        return false;
+    const descriptor = value;
+    const defaultTtlMs = descriptor.defaultTtlMs;
+    const maxTtlMs = descriptor.maxTtlMs;
+    return (isSchema(descriptor.key) &&
+        isSchema(descriptor.value) &&
+        (descriptor.profile === undefined || isStableProfile(descriptor.profile)) &&
+        (defaultTtlMs === undefined || isPositiveInteger(defaultTtlMs)) &&
+        (maxTtlMs === undefined || isPositiveInteger(maxTtlMs)) &&
+        (defaultTtlMs === undefined || maxTtlMs === undefined || defaultTtlMs <= maxTtlMs));
+}
+export function assertCacheDescriptor(value) {
+    if (!isCacheDescriptor(value))
+        throw new TypeError("Invalid cache descriptor");
+}
+function validateTtl(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (!isPositiveInteger(value))
+        throw new TypeError(`${name} must be a positive integer`);
+    return value;
+}
+function assertSchema(value, name) {
+    if (!isSchema(value))
+        throw new TypeError(`${name} must be a Standard Schema v1 validator`);
+}
+function isSchema(value) {
+    if (!isRecord(value) || !isRecord(value["~standard"]))
+        return false;
+    return value["~standard"].version === 1 && typeof value["~standard"].validate === "function";
+}
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+function isStableProfile(value) {
+    try {
+        normalizeId(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+//# sourceMappingURL=define-cache.js.map

package/dist/define-cache.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./define-cache.js";
+export * from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./define-cache.js";
+export * from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@relkit/cache",
+  "version": "0.0.0",
+  "description": "RELKIT cache authoring API; prefer @relkit/app/cache in applications.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rel-kit/relkit.git",
+    "directory": "packages/cache"
+  },
+  "homepage": "https://github.com/rel-kit/relkit#readme",
+  "bugs": {
+    "url": "https://github.com/rel-kit/relkit/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.10"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@relkit/contracts": "0.0.0",
+    "@relkit/schema": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "check": "tsc -b --pretty false",
+    "typecheck": "tsc -b --pretty false"
+  }
+}