dialcache 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,93 @@
+import { D as DialCacheKeyConfig, S as Serializer, a as DialCacheConfig, A as Awaitable } from './config-B7bGp-Xj.cjs';
+export { C as CacheConfigProvider, b as CacheLayer, c as CacheMetricLabels, d as CacheRampSample, e as CacheRampSampler, f as CoalescedMetricLabels, g as DEFAULT_WATERMARK_TTL_SEC, h as DialCacheKey, i as DialCacheKeyInit, j as DialCacheMetricsAdapter, k as DialCacheRedisClient, l as DialCacheRedisPayloadEncodingError, m as DialCacheRedisPayloadError, n as DisabledMetricLabels, o as DisabledReason, E as ErrorMetricLabels, I as InvalidationMetricLabels, J as JsonSerializer, L as LayerConfig, p as Logger, M as MetricLayer, P as PrometheusDialCacheMetrics, q as PrometheusMetricsOptions, R as RedisCachePayload, r as RedisClientFactory, s as RedisConfig, t as RedisInvalidationRequest, u as RedisReadRequest, v as RedisWriteRequest, w as SerializationMetricLabels, x as createPrometheusDialCacheMetrics, y as deterministicRampSampler, z as invalidationPrefix, B as normalizeArgs, F as randomRampSampler, G as redisClusterHashTag } from './config-B7bGp-Xj.cjs';
+import 'prom-client';
+
+declare class DialCacheContext {
+    private readonly storage;
+    isEnabled(): boolean;
+    enable<T>(fn: () => T | Promise<T>): Promise<T>;
+    disable<T>(fn: () => T | Promise<T>): Promise<T>;
+    private run;
+}
+
+declare class DialCacheError extends Error {
+    constructor(message: string);
+}
+declare class UseCaseIsAlreadyRegisteredError extends DialCacheError {
+    constructor(useCase: string);
+}
+declare class UseCaseNameIsReservedError extends DialCacheError {
+    constructor(useCase: string);
+}
+declare class MissingKeyConfigError extends DialCacheError {
+    constructor(useCase: string);
+}
+
+type CacheKeyArgs = Record<string, string | number | boolean | bigint | null | undefined>;
+type Id = string | number | bigint;
+/** A cache-key spec: a bare id, or an id plus extra (secondary) key dimensions. */
+type CacheKeySpec = Id | {
+    readonly id: Id;
+    readonly args?: CacheKeyArgs;
+};
+type AnyFn = (...args: never[]) => unknown;
+/** The cached value type, derived from the wrapped function's return. */
+type CachedValue<Fn extends AnyFn> = Awaited<ReturnType<Fn>>;
+type CacheKeySelector<Fn extends AnyFn> = (...args: Parameters<Fn>) => CacheKeySpec;
+interface CachedOptions<Fn extends AnyFn> {
+    readonly keyType: string;
+    readonly useCase: string;
+    readonly defaultConfig?: DialCacheKeyConfig | null;
+    readonly serializer?: Serializer<CachedValue<Fn>> | null;
+    readonly trackForInvalidation?: boolean;
+    /**
+     * Select every input dimension that can affect the returned value. Concurrent
+     * enabled calls with the same cache key may share one in-flight execution.
+     */
+    readonly cacheKey: CacheKeySelector<Fn>;
+}
+type CachedFn<Fn extends AnyFn> = (...args: Parameters<Fn>) => Promise<CachedValue<Fn>>;
+declare class DialCache {
+    private readonly context;
+    private readonly localCache;
+    private readonly useCases;
+    private readonly configProvider;
+    private readonly urnPrefix;
+    private readonly logger;
+    private readonly rampSampler;
+    private readonly redisCache;
+    private readonly metrics;
+    private readonly inFlight;
+    constructor(config?: DialCacheConfig);
+    enable<T>(fn: () => Awaitable<T>): Promise<T>;
+    disable<T>(fn: () => Awaitable<T>): Promise<T>;
+    withEnabled<T>(fn: () => Awaitable<T>): Promise<T>;
+    withDisabled<T>(fn: () => Awaitable<T>): Promise<T>;
+    isEnabled(): boolean;
+    cached<Fn extends AnyFn>(fn: Fn, options: CachedOptions<Fn>): CachedFn<Fn>;
+    /**
+     * Writes a remote invalidation watermark for Redis-tracked entries.
+     *
+     * This does not synchronously evict local cache hits or untracked Redis values.
+     *
+     * @param futureBufferMs Nonnegative safe integer covering source lag and stale fallback work through the Redis write.
+     */
+    invalidateRemote(keyType: string, id: Id, futureBufferMs?: number): Promise<void>;
+    flushAll(): Promise<void>;
+    private getThroughLocalOnly;
+    private getThroughRedisChain;
+    private getThroughRemoteAfterLocal;
+    private finishRedisChain;
+    private readLocal;
+    private resolveRemoteLayerConfig;
+    private readRemote;
+    private readRemoteWithResolvedConfig;
+    private putLocalFailOpen;
+    private callFallback;
+    private recordError;
+    private registerUseCase;
+    private buildKey;
+    private singleFlight;
+}
+
+export { type CacheKeySpec, type CachedFn, type CachedOptions, type CachedValue, DialCache, DialCacheConfig, DialCacheContext, DialCacheError, DialCacheKeyConfig, MissingKeyConfigError, Serializer, UseCaseIsAlreadyRegisteredError, UseCaseNameIsReservedError };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { D as DialCacheKeyConfig, S as Serializer, a as DialCacheConfig, A as Awaitable } from './config-B7bGp-Xj.js';
+export { C as CacheConfigProvider, b as CacheLayer, c as CacheMetricLabels, d as CacheRampSample, e as CacheRampSampler, f as CoalescedMetricLabels, g as DEFAULT_WATERMARK_TTL_SEC, h as DialCacheKey, i as DialCacheKeyInit, j as DialCacheMetricsAdapter, k as DialCacheRedisClient, l as DialCacheRedisPayloadEncodingError, m as DialCacheRedisPayloadError, n as DisabledMetricLabels, o as DisabledReason, E as ErrorMetricLabels, I as InvalidationMetricLabels, J as JsonSerializer, L as LayerConfig, p as Logger, M as MetricLayer, P as PrometheusDialCacheMetrics, q as PrometheusMetricsOptions, R as RedisCachePayload, r as RedisClientFactory, s as RedisConfig, t as RedisInvalidationRequest, u as RedisReadRequest, v as RedisWriteRequest, w as SerializationMetricLabels, x as createPrometheusDialCacheMetrics, y as deterministicRampSampler, z as invalidationPrefix, B as normalizeArgs, F as randomRampSampler, G as redisClusterHashTag } from './config-B7bGp-Xj.js';
+import 'prom-client';
+
+declare class DialCacheContext {
+    private readonly storage;
+    isEnabled(): boolean;
+    enable<T>(fn: () => T | Promise<T>): Promise<T>;
+    disable<T>(fn: () => T | Promise<T>): Promise<T>;
+    private run;
+}
+
+declare class DialCacheError extends Error {
+    constructor(message: string);
+}
+declare class UseCaseIsAlreadyRegisteredError extends DialCacheError {
+    constructor(useCase: string);
+}
+declare class UseCaseNameIsReservedError extends DialCacheError {
+    constructor(useCase: string);
+}
+declare class MissingKeyConfigError extends DialCacheError {
+    constructor(useCase: string);
+}
+
+type CacheKeyArgs = Record<string, string | number | boolean | bigint | null | undefined>;
+type Id = string | number | bigint;
+/** A cache-key spec: a bare id, or an id plus extra (secondary) key dimensions. */
+type CacheKeySpec = Id | {
+    readonly id: Id;
+    readonly args?: CacheKeyArgs;
+};
+type AnyFn = (...args: never[]) => unknown;
+/** The cached value type, derived from the wrapped function's return. */
+type CachedValue<Fn extends AnyFn> = Awaited<ReturnType<Fn>>;
+type CacheKeySelector<Fn extends AnyFn> = (...args: Parameters<Fn>) => CacheKeySpec;
+interface CachedOptions<Fn extends AnyFn> {
+    readonly keyType: string;
+    readonly useCase: string;
+    readonly defaultConfig?: DialCacheKeyConfig | null;
+    readonly serializer?: Serializer<CachedValue<Fn>> | null;
+    readonly trackForInvalidation?: boolean;
+    /**
+     * Select every input dimension that can affect the returned value. Concurrent
+     * enabled calls with the same cache key may share one in-flight execution.
+     */
+    readonly cacheKey: CacheKeySelector<Fn>;
+}
+type CachedFn<Fn extends AnyFn> = (...args: Parameters<Fn>) => Promise<CachedValue<Fn>>;
+declare class DialCache {
+    private readonly context;
+    private readonly localCache;
+    private readonly useCases;
+    private readonly configProvider;
+    private readonly urnPrefix;
+    private readonly logger;
+    private readonly rampSampler;
+    private readonly redisCache;
+    private readonly metrics;
+    private readonly inFlight;
+    constructor(config?: DialCacheConfig);
+    enable<T>(fn: () => Awaitable<T>): Promise<T>;
+    disable<T>(fn: () => Awaitable<T>): Promise<T>;
+    withEnabled<T>(fn: () => Awaitable<T>): Promise<T>;
+    withDisabled<T>(fn: () => Awaitable<T>): Promise<T>;
+    isEnabled(): boolean;
+    cached<Fn extends AnyFn>(fn: Fn, options: CachedOptions<Fn>): CachedFn<Fn>;
+    /**
+     * Writes a remote invalidation watermark for Redis-tracked entries.
+     *
+     * This does not synchronously evict local cache hits or untracked Redis values.
+     *
+     * @param futureBufferMs Nonnegative safe integer covering source lag and stale fallback work through the Redis write.
+     */
+    invalidateRemote(keyType: string, id: Id, futureBufferMs?: number): Promise<void>;
+    flushAll(): Promise<void>;
+    private getThroughLocalOnly;
+    private getThroughRedisChain;
+    private getThroughRemoteAfterLocal;
+    private finishRedisChain;
+    private readLocal;
+    private resolveRemoteLayerConfig;
+    private readRemote;
+    private readRemoteWithResolvedConfig;
+    private putLocalFailOpen;
+    private callFallback;
+    private recordError;
+    private registerUseCase;
+    private buildKey;
+    private singleFlight;
+}
+
+export { type CacheKeySpec, type CachedFn, type CachedOptions, type CachedValue, DialCache, DialCacheConfig, DialCacheContext, DialCacheError, DialCacheKeyConfig, MissingKeyConfigError, Serializer, UseCaseIsAlreadyRegisteredError, UseCaseNameIsReservedError };