dialcache 0.1.1

package/dist/config-B7bGp-Xj.d.cts

@@ -0,0 +1,205 @@
+import { Registry } from 'prom-client';
+
+interface Serializer<T = unknown> {
+    dump(value: T): Awaitable<string | Buffer>;
+    load(value: string | Buffer): Awaitable<T>;
+}
+declare class JsonSerializer<T = unknown> implements Serializer<T> {
+    dump(value: T): Promise<string>;
+    load(value: string | Buffer): Promise<T>;
+}
+
+interface DialCacheKeyInit {
+    readonly keyType: string;
+    readonly id: string;
+    readonly useCase: string;
+    readonly args?: ReadonlyArray<readonly [string, string]>;
+    readonly urnPrefix?: string;
+    readonly defaultConfig?: DialCacheKeyConfig | null;
+    readonly serializer?: Serializer<unknown> | null;
+    readonly trackForInvalidation?: boolean;
+}
+declare class DialCacheKey {
+    readonly keyType: string;
+    readonly id: string;
+    readonly useCase: string;
+    readonly args: ReadonlyArray<readonly [string, string]>;
+    readonly urnPrefix: string;
+    readonly prefix: string;
+    readonly urn: string;
+    readonly defaultConfig: DialCacheKeyConfig | null;
+    readonly serializer: Serializer<unknown> | null;
+    readonly trackForInvalidation: boolean;
+    constructor(init: DialCacheKeyInit);
+    toString(): string;
+}
+declare function normalizeArgs(args: Record<string, string | number | boolean | bigint | null | undefined>): Array<[string, string]>;
+declare function invalidationPrefix(urnPrefix: string, keyType: string, id: string): string;
+declare function redisClusterHashTag(value: string): string;
+
+declare const NO_CACHE_LAYER = "noop";
+type NoCacheLayer = typeof NO_CACHE_LAYER;
+type MetricLayer = CacheLayer | NoCacheLayer;
+type DisabledReason = "context" | "missing_config" | "invalid_ttl" | "ramped_down" | "config_error";
+interface CacheMetricLabels {
+    readonly useCase: string;
+    readonly keyType: string;
+    readonly layer: MetricLayer;
+}
+interface DisabledMetricLabels extends CacheMetricLabels {
+    readonly reason: DisabledReason;
+}
+interface ErrorMetricLabels extends CacheMetricLabels {
+    readonly error: string;
+    readonly inFallback: boolean;
+}
+interface SerializationMetricLabels extends CacheMetricLabels {
+    readonly operation: "dump" | "load";
+}
+interface InvalidationMetricLabels {
+    readonly keyType: string;
+    readonly layer: CacheLayer;
+}
+interface CoalescedMetricLabels {
+    readonly useCase: string;
+    readonly keyType: string;
+}
+interface DialCacheMetricsAdapter {
+    request(labels: CacheMetricLabels): void;
+    miss(labels: CacheMetricLabels): void;
+    disabled(labels: DisabledMetricLabels): void;
+    error(labels: ErrorMetricLabels): void;
+    invalidation(labels: InvalidationMetricLabels): void;
+    coalesced?(labels: CoalescedMetricLabels): void;
+    observeGet(labels: CacheMetricLabels, seconds: number): void;
+    observeFallback(labels: CacheMetricLabels, seconds: number): void;
+    observeSerialization(labels: SerializationMetricLabels, seconds: number): void;
+    observeSize(labels: CacheMetricLabels, bytes: number): void;
+}
+interface PrometheusMetricsOptions {
+    readonly prefix?: string;
+    readonly registry?: Registry;
+}
+declare class PrometheusDialCacheMetrics implements DialCacheMetricsAdapter {
+    private readonly requestCounter;
+    private readonly missCounter;
+    private readonly disabledCounter;
+    private readonly errorCounter;
+    private readonly invalidationCounter;
+    private readonly coalescedCounter;
+    private readonly getTimer;
+    private readonly fallbackTimer;
+    private readonly serializationTimer;
+    private readonly sizeHistogram;
+    constructor(options?: PrometheusMetricsOptions);
+    request(labels: CacheMetricLabels): void;
+    miss(labels: CacheMetricLabels): void;
+    disabled(labels: DisabledMetricLabels): void;
+    error(labels: ErrorMetricLabels): void;
+    invalidation(labels: InvalidationMetricLabels): void;
+    coalesced(labels: CoalescedMetricLabels): void;
+    observeGet(labels: CacheMetricLabels, seconds: number): void;
+    observeFallback(labels: CacheMetricLabels, seconds: number): void;
+    observeSerialization(labels: SerializationMetricLabels, seconds: number): void;
+    observeSize(labels: CacheMetricLabels, bytes: number): void;
+}
+declare function createPrometheusDialCacheMetrics(options?: PrometheusMetricsOptions): DialCacheMetricsAdapter;
+
+declare class DialCacheRedisPayloadError extends Error {
+    constructor(message: string);
+}
+declare class DialCacheRedisPayloadEncodingError extends Error {
+    constructor(message: string);
+}
+/** Serialized cache data, independent of any Redis client or wire framing. */
+type RedisCachePayload = string | Buffer;
+interface RedisValueRequest {
+    readonly valueKey: string;
+}
+interface TrackedRedisValueRequest extends RedisValueRequest {
+    readonly watermarkKey: string;
+}
+interface UntrackedRedisValueRequest extends RedisValueRequest {
+    readonly watermarkKey?: never;
+}
+type RedisReadRequest = TrackedRedisValueRequest | UntrackedRedisValueRequest;
+interface RedisWriteBase extends RedisValueRequest {
+    readonly cacheTtlMs: number;
+    readonly value: RedisCachePayload;
+}
+interface TrackedRedisWriteRequest extends RedisWriteBase, TrackedRedisValueRequest {
+    readonly watermarkTtlFloorMs: number;
+}
+interface UntrackedRedisWriteRequest extends RedisWriteBase, UntrackedRedisValueRequest {
+    readonly watermarkTtlFloorMs?: never;
+}
+type RedisWriteRequest = TrackedRedisWriteRequest | UntrackedRedisWriteRequest;
+interface RedisInvalidationRequest {
+    readonly watermarkKey: string;
+    readonly futureBufferMs: number;
+    readonly watermarkTtlFloorMs: number;
+}
+interface DialCacheRedisClient {
+    /** Atomically read and validate a value against its watermark when tracked. */
+    read(request: RedisReadRequest): Awaitable<RedisCachePayload | null>;
+    /** Atomically write using server time. False means invalidation blocked the write. */
+    write(request: RedisWriteRequest): Awaitable<boolean>;
+    /** Advance the watermark monotonically after the source mutation commits. */
+    invalidate(request: RedisInvalidationRequest): Awaitable<void>;
+    /** Remove cached values from every backing shard. */
+    flushAll(): Awaitable<void>;
+}
+type RedisClientFactory = () => Awaitable<DialCacheRedisClient>;
+
+interface RedisConfig {
+    readonly client?: DialCacheRedisClient;
+    readonly createClient?: RedisClientFactory;
+    readonly keyPrefix?: string;
+    readonly serializer?: Serializer<unknown>;
+    readonly watermarkTtlSec?: number;
+}
+
+declare enum CacheLayer {
+    LOCAL = "local",
+    REMOTE = "remote"
+}
+type Awaitable<T> = T | Promise<T>;
+type LayerConfig = Partial<Record<CacheLayer, number>>;
+interface CacheRampSample {
+    readonly key: DialCacheKey;
+    readonly layer: CacheLayer;
+    readonly ramp: number;
+}
+type CacheRampSampler = (sample: CacheRampSample) => Awaitable<number>;
+declare const deterministicRampSampler: CacheRampSampler;
+declare const randomRampSampler: CacheRampSampler;
+declare const DEFAULT_WATERMARK_TTL_SEC: number;
+declare class DialCacheKeyConfig {
+    readonly ttlSec: LayerConfig;
+    readonly ramp: LayerConfig;
+    constructor(config: {
+        ttlSec: LayerConfig;
+        ramp: LayerConfig;
+    });
+    static enabled(ttlSec: number): DialCacheKeyConfig;
+}
+type CacheConfigProvider = (key: DialCacheKey) => Awaitable<DialCacheKeyConfig | null>;
+type Logger = Pick<Console, "debug" | "error" | "warn">;
+interface DialCacheConfig {
+    readonly cacheConfigProvider?: CacheConfigProvider;
+    readonly urnPrefix?: string;
+    readonly logger?: Logger;
+    /**
+     * Maximum local entries across every use case in this DialCache instance.
+     * Must be a nonnegative safe integer.
+     * Zero disables local storage. Defaults to 10,000.
+     */
+    readonly localMaxSize?: number;
+    readonly redis?: RedisConfig;
+    readonly rampSampler?: CacheRampSampler;
+    readonly metrics?: DialCacheMetricsAdapter | false;
+    readonly metricsPrefix?: string;
+    readonly metricsRegistry?: Registry;
+}
+
+export { type Awaitable as A, normalizeArgs as B, type CacheConfigProvider as C, DialCacheKeyConfig as D, type ErrorMetricLabels as E, randomRampSampler as F, redisClusterHashTag as G, type InvalidationMetricLabels as I, JsonSerializer as J, type LayerConfig as L, type MetricLayer as M, PrometheusDialCacheMetrics as P, type RedisCachePayload as R, type Serializer as S, type DialCacheConfig as a, CacheLayer as b, type CacheMetricLabels as c, type CacheRampSample as d, type CacheRampSampler as e, type CoalescedMetricLabels as f, DEFAULT_WATERMARK_TTL_SEC as g, DialCacheKey as h, type DialCacheKeyInit as i, type DialCacheMetricsAdapter as j, type DialCacheRedisClient as k, DialCacheRedisPayloadEncodingError as l, DialCacheRedisPayloadError as m, type DisabledMetricLabels as n, type DisabledReason as o, type Logger as p, type PrometheusMetricsOptions as q, type RedisClientFactory as r, type RedisConfig as s, type RedisInvalidationRequest as t, type RedisReadRequest as u, type RedisWriteRequest as v, type SerializationMetricLabels as w, createPrometheusDialCacheMetrics as x, deterministicRampSampler as y, invalidationPrefix as z };

package/dist/config-B7bGp-Xj.d.ts

@@ -0,0 +1,205 @@
+import { Registry } from 'prom-client';
+
+interface Serializer<T = unknown> {
+    dump(value: T): Awaitable<string | Buffer>;
+    load(value: string | Buffer): Awaitable<T>;
+}
+declare class JsonSerializer<T = unknown> implements Serializer<T> {
+    dump(value: T): Promise<string>;
+    load(value: string | Buffer): Promise<T>;
+}
+
+interface DialCacheKeyInit {
+    readonly keyType: string;
+    readonly id: string;
+    readonly useCase: string;
+    readonly args?: ReadonlyArray<readonly [string, string]>;
+    readonly urnPrefix?: string;
+    readonly defaultConfig?: DialCacheKeyConfig | null;
+    readonly serializer?: Serializer<unknown> | null;
+    readonly trackForInvalidation?: boolean;
+}
+declare class DialCacheKey {
+    readonly keyType: string;
+    readonly id: string;
+    readonly useCase: string;
+    readonly args: ReadonlyArray<readonly [string, string]>;
+    readonly urnPrefix: string;
+    readonly prefix: string;
+    readonly urn: string;
+    readonly defaultConfig: DialCacheKeyConfig | null;
+    readonly serializer: Serializer<unknown> | null;
+    readonly trackForInvalidation: boolean;
+    constructor(init: DialCacheKeyInit);
+    toString(): string;
+}
+declare function normalizeArgs(args: Record<string, string | number | boolean | bigint | null | undefined>): Array<[string, string]>;
+declare function invalidationPrefix(urnPrefix: string, keyType: string, id: string): string;
+declare function redisClusterHashTag(value: string): string;
+
+declare const NO_CACHE_LAYER = "noop";
+type NoCacheLayer = typeof NO_CACHE_LAYER;
+type MetricLayer = CacheLayer | NoCacheLayer;
+type DisabledReason = "context" | "missing_config" | "invalid_ttl" | "ramped_down" | "config_error";
+interface CacheMetricLabels {
+    readonly useCase: string;
+    readonly keyType: string;
+    readonly layer: MetricLayer;
+}
+interface DisabledMetricLabels extends CacheMetricLabels {
+    readonly reason: DisabledReason;
+}
+interface ErrorMetricLabels extends CacheMetricLabels {
+    readonly error: string;
+    readonly inFallback: boolean;
+}
+interface SerializationMetricLabels extends CacheMetricLabels {
+    readonly operation: "dump" | "load";
+}
+interface InvalidationMetricLabels {
+    readonly keyType: string;
+    readonly layer: CacheLayer;
+}
+interface CoalescedMetricLabels {
+    readonly useCase: string;
+    readonly keyType: string;
+}
+interface DialCacheMetricsAdapter {
+    request(labels: CacheMetricLabels): void;
+    miss(labels: CacheMetricLabels): void;
+    disabled(labels: DisabledMetricLabels): void;
+    error(labels: ErrorMetricLabels): void;
+    invalidation(labels: InvalidationMetricLabels): void;
+    coalesced?(labels: CoalescedMetricLabels): void;
+    observeGet(labels: CacheMetricLabels, seconds: number): void;
+    observeFallback(labels: CacheMetricLabels, seconds: number): void;
+    observeSerialization(labels: SerializationMetricLabels, seconds: number): void;
+    observeSize(labels: CacheMetricLabels, bytes: number): void;
+}
+interface PrometheusMetricsOptions {
+    readonly prefix?: string;
+    readonly registry?: Registry;
+}
+declare class PrometheusDialCacheMetrics implements DialCacheMetricsAdapter {
+    private readonly requestCounter;
+    private readonly missCounter;
+    private readonly disabledCounter;
+    private readonly errorCounter;
+    private readonly invalidationCounter;
+    private readonly coalescedCounter;
+    private readonly getTimer;
+    private readonly fallbackTimer;
+    private readonly serializationTimer;
+    private readonly sizeHistogram;
+    constructor(options?: PrometheusMetricsOptions);
+    request(labels: CacheMetricLabels): void;
+    miss(labels: CacheMetricLabels): void;
+    disabled(labels: DisabledMetricLabels): void;
+    error(labels: ErrorMetricLabels): void;
+    invalidation(labels: InvalidationMetricLabels): void;
+    coalesced(labels: CoalescedMetricLabels): void;
+    observeGet(labels: CacheMetricLabels, seconds: number): void;
+    observeFallback(labels: CacheMetricLabels, seconds: number): void;
+    observeSerialization(labels: SerializationMetricLabels, seconds: number): void;
+    observeSize(labels: CacheMetricLabels, bytes: number): void;
+}
+declare function createPrometheusDialCacheMetrics(options?: PrometheusMetricsOptions): DialCacheMetricsAdapter;
+
+declare class DialCacheRedisPayloadError extends Error {
+    constructor(message: string);
+}
+declare class DialCacheRedisPayloadEncodingError extends Error {
+    constructor(message: string);
+}
+/** Serialized cache data, independent of any Redis client or wire framing. */
+type RedisCachePayload = string | Buffer;
+interface RedisValueRequest {
+    readonly valueKey: string;
+}
+interface TrackedRedisValueRequest extends RedisValueRequest {
+    readonly watermarkKey: string;
+}
+interface UntrackedRedisValueRequest extends RedisValueRequest {
+    readonly watermarkKey?: never;
+}
+type RedisReadRequest = TrackedRedisValueRequest | UntrackedRedisValueRequest;
+interface RedisWriteBase extends RedisValueRequest {
+    readonly cacheTtlMs: number;
+    readonly value: RedisCachePayload;
+}
+interface TrackedRedisWriteRequest extends RedisWriteBase, TrackedRedisValueRequest {
+    readonly watermarkTtlFloorMs: number;
+}
+interface UntrackedRedisWriteRequest extends RedisWriteBase, UntrackedRedisValueRequest {
+    readonly watermarkTtlFloorMs?: never;
+}
+type RedisWriteRequest = TrackedRedisWriteRequest | UntrackedRedisWriteRequest;
+interface RedisInvalidationRequest {
+    readonly watermarkKey: string;
+    readonly futureBufferMs: number;
+    readonly watermarkTtlFloorMs: number;
+}
+interface DialCacheRedisClient {
+    /** Atomically read and validate a value against its watermark when tracked. */
+    read(request: RedisReadRequest): Awaitable<RedisCachePayload | null>;
+    /** Atomically write using server time. False means invalidation blocked the write. */
+    write(request: RedisWriteRequest): Awaitable<boolean>;
+    /** Advance the watermark monotonically after the source mutation commits. */
+    invalidate(request: RedisInvalidationRequest): Awaitable<void>;
+    /** Remove cached values from every backing shard. */
+    flushAll(): Awaitable<void>;
+}
+type RedisClientFactory = () => Awaitable<DialCacheRedisClient>;
+
+interface RedisConfig {
+    readonly client?: DialCacheRedisClient;
+    readonly createClient?: RedisClientFactory;
+    readonly keyPrefix?: string;
+    readonly serializer?: Serializer<unknown>;
+    readonly watermarkTtlSec?: number;
+}
+
+declare enum CacheLayer {
+    LOCAL = "local",
+    REMOTE = "remote"
+}
+type Awaitable<T> = T | Promise<T>;
+type LayerConfig = Partial<Record<CacheLayer, number>>;
+interface CacheRampSample {
+    readonly key: DialCacheKey;
+    readonly layer: CacheLayer;
+    readonly ramp: number;
+}
+type CacheRampSampler = (sample: CacheRampSample) => Awaitable<number>;
+declare const deterministicRampSampler: CacheRampSampler;
+declare const randomRampSampler: CacheRampSampler;
+declare const DEFAULT_WATERMARK_TTL_SEC: number;
+declare class DialCacheKeyConfig {
+    readonly ttlSec: LayerConfig;
+    readonly ramp: LayerConfig;
+    constructor(config: {
+        ttlSec: LayerConfig;
+        ramp: LayerConfig;
+    });
+    static enabled(ttlSec: number): DialCacheKeyConfig;
+}
+type CacheConfigProvider = (key: DialCacheKey) => Awaitable<DialCacheKeyConfig | null>;
+type Logger = Pick<Console, "debug" | "error" | "warn">;
+interface DialCacheConfig {
+    readonly cacheConfigProvider?: CacheConfigProvider;
+    readonly urnPrefix?: string;
+    readonly logger?: Logger;
+    /**
+     * Maximum local entries across every use case in this DialCache instance.
+     * Must be a nonnegative safe integer.
+     * Zero disables local storage. Defaults to 10,000.
+     */
+    readonly localMaxSize?: number;
+    readonly redis?: RedisConfig;
+    readonly rampSampler?: CacheRampSampler;
+    readonly metrics?: DialCacheMetricsAdapter | false;
+    readonly metricsPrefix?: string;
+    readonly metricsRegistry?: Registry;
+}
+
+export { type Awaitable as A, normalizeArgs as B, type CacheConfigProvider as C, DialCacheKeyConfig as D, type ErrorMetricLabels as E, randomRampSampler as F, redisClusterHashTag as G, type InvalidationMetricLabels as I, JsonSerializer as J, type LayerConfig as L, type MetricLayer as M, PrometheusDialCacheMetrics as P, type RedisCachePayload as R, type Serializer as S, type DialCacheConfig as a, CacheLayer as b, type CacheMetricLabels as c, type CacheRampSample as d, type CacheRampSampler as e, type CoalescedMetricLabels as f, DEFAULT_WATERMARK_TTL_SEC as g, DialCacheKey as h, type DialCacheKeyInit as i, type DialCacheMetricsAdapter as j, type DialCacheRedisClient as k, DialCacheRedisPayloadEncodingError as l, DialCacheRedisPayloadError as m, type DisabledMetricLabels as n, type DisabledReason as o, type Logger as p, type PrometheusMetricsOptions as q, type RedisClientFactory as r, type RedisConfig as s, type RedisInvalidationRequest as t, type RedisReadRequest as u, type RedisWriteRequest as v, type SerializationMetricLabels as w, createPrometheusDialCacheMetrics as x, deterministicRampSampler as y, invalidationPrefix as z };