fansunited-data-layer 0.15.3 → 0.17.0

package/api/fansunited/sports/livescore/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Raw API response and option types for the Fans United Sports API
+ * livescore endpoint.
+ */
+import type { NextCacheOptions } from "../../http";
+import type { FUSportsLivescoreEventStatus, FUSportsLivescoreSport } from "../../../../types/canonical/sports-livescore.types";
+export interface RawSportsLivescoreStatus {
+    type: string;
+    code: string;
+    sub_type: string;
+}
+export interface RawSportsLivescoreScore {
+    key: string;
+    competitor_one: string;
+    competitor_two: string;
+}
+export interface RawSportsLivescoreCompetitor {
+    id: string;
+    type: string;
+}
+export interface RawSportsLivescoreEvent {
+    id: string;
+    status: RawSportsLivescoreStatus;
+    score?: RawSportsLivescoreScore[];
+    competitor_one: RawSportsLivescoreCompetitor;
+    competitor_two: RawSportsLivescoreCompetitor;
+    start_time: string;
+}
+export interface RawSportsLivescoreCompetitionGroup {
+    competition_id: string;
+    sport: string;
+    events: RawSportsLivescoreEvent[];
+}
+export interface RawSportsLivescoreMeta {
+    total_competitions: number;
+    total_events: number;
+}
+export interface RawSportsLivescoreResponse {
+    data: RawSportsLivescoreCompetitionGroup[];
+    meta: RawSportsLivescoreMeta;
+}
+export interface GetSportsLivescoreOptions {
+    /** Comma-joined or array of competition IDs to filter by. */
+    competitionIds?: string[];
+    /** Match IDs to filter by. */
+    matchIds?: string[];
+    /** Competition IDs defining the order of competition groups in the response. */
+    competitionsOrder?: string[];
+    /** Date in yyyy-MM-dd format. Defaults to the current date (UTC). */
+    date?: string;
+    /** Filter by event status. */
+    eventStatus?: FUSportsLivescoreEventStatus;
+    /** Filter by sport. */
+    sport?: FUSportsLivescoreSport;
+    /** Next.js cache options for ISR/on-demand revalidation. */
+    next?: NextCacheOptions;
+}
+//# sourceMappingURL=types.d.ts.map

package/api/fansunited/sports/livescore/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/lib/api/fansunited/sports/livescore/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EACR,4BAA4B,EAC5B,sBAAsB,EACzB,MAAM,oDAAoD,CAAC;AAM5D,MAAM,WAAW,wBAAwB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,wBAAwB,CAAC;IACjC,KAAK,CAAC,EAAE,uBAAuB,EAAE,CAAC;IAClC,cAAc,EAAE,4BAA4B,CAAC;IAC7C,cAAc,EAAE,4BAA4B,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kCAAkC;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,uBAAuB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACvC,IAAI,EAAE,kCAAkC,EAAE,CAAC;IAC3C,IAAI,EAAE,sBAAsB,CAAC;CAChC;AAMD,MAAM,WAAW,yBAAyB;IACtC,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,WAAW,CAAC,EAAE,4BAA4B,CAAC;IAC3C,uBAAuB;IACvB,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,gBAAgB,CAAC;CAC3B"}

package/cache/__tests__/redis-integration.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Redis L2 integration tests. Skipped unless REDIS_HOST is set, so the
+ * default `npm test` run stays hermetic.
+ *
+ * To run:
+ *   docker compose up -d redis
+ *   REDIS_HOST=redis npm test -- --run src/lib/cache/__tests__/redis-integration.test.ts
+ *
+ * From a host shell (Redis exposed on localhost:6379):
+ *   docker compose up -d redis
+ *   REDIS_HOST=localhost npm test -- --run src/lib/cache/__tests__/redis-integration.test.ts
+ */
+export {};
+//# sourceMappingURL=redis-integration.test.d.ts.map

package/cache/__tests__/redis-integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-integration.test.d.ts","sourceRoot":"","sources":["../../../src/lib/cache/__tests__/redis-integration.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/cache/__tests__/redis-l2-store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Reference Redis L2 adapter — kept under __tests__/ so it ships only with
+ * the dev install (ioredis is a devDependency). Consumers copy this verbatim
+ * (or adapt) into their own codebase per the design spec's "Decision 2":
+ * the Redis client is consumer-supplied so the data-layer stays browser-safe.
+ *
+ * Implementation notes
+ * --------------------
+ *
+ * 1. **Cache envelope.** Each value is a JSON-encoded `CacheEntry<T>`
+ *    (`{ data, storedAt }`). The `storedAt` timestamp is what the cache
+ *    manager uses to decide freshness/expiry — Redis's own TTL is a memory
+ *    safety net, not the source of truth for SWR semantics.
+ *
+ * 2. **Eviction TTL.** Every `set`/`setMany` issues an `EX` matching
+ *    `getEntityTTL(entity).maxTTL`. That keeps Redis from accumulating dead
+ *    entries without needing a periodic cleanup scan. The cache manager
+ *    still defensively rejects entries past `maxTTL` on read via
+ *    `isExpired(entry, maxTTL)`, so the two layers can drift slightly
+ *    without correctness issues.
+ *
+ * 3. **Graceful degradation.** The spec requires that a degraded L2 must
+ *    never throw to the caller. We:
+ *    - report `isInitialized` based on the ioredis status (only `"ready"`
+ *      qualifies);
+ *    - swallow read errors and return `undefined`;
+ *    - swallow write errors and no-op.
+ *    The cache manager will then fall back to L1 + API.
+ *
+ * 4. **`clear()` namespacing.** Uses `SCAN MATCH <prefix>*` + pipelined
+ *    `DEL`. Other keys in the same Redis instance are untouched, which is
+ *    what the `fudl:` prefix is for in the first place.
+ */
+import type { Redis } from "ioredis";
+import type { L2Store } from "../cache-manager";
+export interface RedisL2StoreOptions {
+    /** Connected (or auto-connecting) ioredis client. */
+    client: Redis;
+    /**
+     * Override the prefix used by `clear()` for SCAN. Defaults to the
+     * data-layer's CACHE_KEY_PREFIX so consumers can clear the data-layer's
+     * keys without touching unrelated data in a shared Redis instance.
+     */
+    clearPrefix?: string;
+    /**
+     * Optional logger. Defaults to console. Swap for your structured logger
+     * in production so failures don't get lost in stdout.
+     */
+    log?: (level: "warn" | "error", msg: string, err?: unknown) => void;
+}
+export declare function createRedisL2Store(options: RedisL2StoreOptions): L2Store;
+//# sourceMappingURL=redis-l2-store.d.ts.map

package/cache/__tests__/redis-l2-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-l2-store.d.ts","sourceRoot":"","sources":["../../../src/lib/cache/__tests__/redis-l2-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAUhD,MAAM,WAAW,mBAAmB;IAChC,qDAAqD;IACrD,MAAM,EAAE,KAAK,CAAC;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACvE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAkFxE"}

package/cache/__tests__/test-l2-store.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Async in-memory L2 stub. Used by tests that exercise the async L2 path
+ * (Redis adapters are async). Filename intentionally lacks `.test.ts` so
+ * vitest's `src/**\/*.test.ts` glob does not pick it up.
+ */
+import type { L2Store } from "../cache-manager";
+import type { EntityType } from "../types";
+interface StoredRow {
+    entity: EntityType;
+    data: unknown;
+    storedAt: number;
+}
+export declare function createTestL2Store(): L2Store & {
+    reset(): void;
+    raw: Map<string, StoredRow>;
+};
+export {};
+//# sourceMappingURL=test-l2-store.d.ts.map

package/cache/__tests__/test-l2-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-l2-store.d.ts","sourceRoot":"","sources":["../../../src/lib/cache/__tests__/test-l2-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,UAAU,CAAC;AAEvD,UAAU,SAAS;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,iBAAiB,IAAI,OAAO,GAAG;IAAE,KAAK,IAAI,IAAI,CAAC;IAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;CAAE,CAoD5F"}

package/cache/cache-manager.d.ts

@@ -4,34 +4,139 @@
  * L2 (SQLite) is never statically imported here — it's injected at runtime
  * via initL2() so that browser bundles don't pull in better-sqlite3.
  */
-import type { CacheEntry, EntityCacheConfig, EntityType } from "./types";
-/** Interface that L2 stores must satisfy */
+import type { CacheEntry, EntityCacheConfig, EntityType, MaybePromise } from "./types";
+/** Interface that L2 stores must satisfy. Methods may be sync or async. */
 export interface L2Store {
     get isInitialized(): boolean;
-    get<T>(key: string): CacheEntry<T> | undefined;
-    set(key: string, entity: string, data: unknown): void;
+    get<T>(key: string): MaybePromise<CacheEntry<T> | undefined>;
+    set(key: string, entity: EntityType, data: unknown): MaybePromise<void>;
     setMany(entries: {
         key: string;
-        entity: string;
+        entity: EntityType;
         data: unknown;
-    }[]): void;
-    cleanup(entity: string, maxTTLSeconds: number): number;
-    clear(): void;
+    }[]): MaybePromise<void>;
+    cleanup(entity: EntityType, maxTTLSeconds: number): MaybePromise<number>;
+    clear(): MaybePromise<void>;
 }
 /**
- * Initialize L2 cache layer. Call on server startup.
- * Client-side apps skip this — L2 is never loaded.
+ * Initialize the L2 cache layer. Call once at server startup; the binding
+ * is process-wide and replaces any previously-set store.
+ *
+ * In browser bundles, never call this — L2 is opt-in and the cache will
+ * operate L1-only when uninitialized (correct, just slower).
+ *
+ * In multi-instance deployments (e.g. Cloud Run), L2 should be a shared,
+ * durable store (Redis, DynamoDB, …) so a warm cache from one instance
+ * serves every other instance. A reference Redis adapter is at
+ * `src/lib/cache/__tests__/redis-l2-store.ts`.
+ *
+ * @example Next.js instrumentation hook
+ * ```ts
+ * // instrumentation.ts
+ * export async function register() {
+ *   if (process.env.NEXT_RUNTIME !== "nodejs") return;
+ *   const { initL2 } = await import("fansunited-data-layer");
+ *   const { createRedisL2Store } = await import("./src/lib/cache/redisL2Store");
+ *   const { getRedis } = await import("./src/lib/redis");
+ *   initL2(createRedisL2Store({ client: getRedis() }));
+ * }
+ * ```
+ *
+ * @see {@link L2Store} for the interface a custom store must satisfy.
  */
 export declare function initL2(store: L2Store): void;
 /** Get the L2 store (if initialized) */
 export declare function getL2(): L2Store | null;
 declare const ENTITY_TTL_CONFIG: Record<EntityType, EntityCacheConfig>;
 /**
- * Single-key cache-through with SWR (Stale-While-Revalidate)
+ * Replace the TTL config for an entity type at runtime. The new values
+ * apply to subsequent `cached()` / `cachedBatch()` calls; existing L2
+ * entries keep whatever TTL they were written with.
+ *
+ * Useful for:
+ * - per-environment tuning (dev: short TTLs to see changes; prod: long)
+ * - overriding ahead of a known traffic spike
+ * - tests that need to simulate stale / expired entries in seconds
+ *
+ * @example
+ * ```ts
+ * setEntityTTL("sportsCompetition", { staleTTL: 30, maxTTL: 600 });
+ * ```
+ *
+ * @see ../README.md § 7 for the full list of default TTLs.
+ */
+export declare function setEntityTTL(entity: EntityType, config: EntityCacheConfig): void;
+/**
+ * Read the current TTL config for an entity type.
+ *
+ * Primarily for L2 adapters that translate `entity` into an underlying
+ * eviction TTL (e.g. Redis `EX` seconds = `maxTTL`). The returned object
+ * is a defensive copy — mutating it has no effect on the manager.
+ *
+ * @throws when called with an entity name not in the config.
+ */
+export declare function getEntityTTL(entity: EntityType): EntityCacheConfig;
+/**
+ * Single-key cache-through with stale-while-revalidate.
+ *
+ * Flow:
+ * 1. L1 hit, fresh (< staleTTL)              → return.
+ * 2. L1 hit, stale but valid (< maxTTL)      → return + kick background refresh.
+ * 3. L1 miss, L2 hit, fresh                  → promote to L1 + return.
+ * 4. L1 miss, L2 hit, stale but valid        → promote + return + background refresh.
+ * 5. Full miss                               → await `fetcher`, populate L1+L2, return.
+ *
+ * Background refreshes share a per-key in-flight set, so concurrent
+ * callers don't trigger a thundering herd of upstream fetches.
+ *
+ * The `key` must include the {@link CACHE_KEY_PREFIX} (`"fudl:"`) by
+ * convention so it can be SCANned safely in a shared Redis instance.
+ *
+ * @param key      Fully-qualified cache key (e.g. `"fudl:sports:competition:fb:c:1:active"`).
+ * @param entity   Entity type — drives the SWR window via `ENTITY_TTL_CONFIG`.
+ * @param fetcher  Upstream call, invoked on miss or background refresh.
+ *
+ * @example
+ * ```ts
+ * const data = await cached(
+ *     `${CACHE_KEY_PREFIX}sports:competition:${id}:active`,
+ *     "sportsCompetition",
+ *     () => fetchFromSportsApi(id),
+ * );
+ * ```
  */
 export declare function cached<T>(key: string, entity: EntityType, fetcher: () => Promise<T>): Promise<T>;
 /**
- * Smart batch cache — only fetches uncached IDs from the API
+ * Multi-key cache-through with stale-while-revalidate.
+ *
+ * For each `id`, the cache is checked (L1, then L2) and only the *missing*
+ * IDs are passed to `batchFetcher` in a single upstream call. Stale-but-
+ * valid entries are returned immediately and refreshed in the background
+ * per-key, just like {@link cached}.
+ *
+ * Why a separate function from `cached`? An N-ID lookup is one upstream
+ * batch request, not N parallel single-key calls — which is the whole
+ * reason the Search API supports `?ids=…,…` in the first place.
+ *
+ * @param ids           IDs to resolve, in request order.
+ * @param entity        Entity type — drives the SWR window.
+ * @param batchFetcher  Called with the subset of IDs not in cache.
+ *                      Must return a `Map<id, value>` (missing IDs okay).
+ * @param keyFn         Builds a fully-qualified cache key from an ID.
+ *                      Convention: `(id) => \`${CACHE_KEY_PREFIX}entity:${id}\``.
+ *
+ * @example
+ * ```ts
+ * const entities = await cachedBatch(
+ *     ids,
+ *     "search",
+ *     async (missingIds) => {
+ *         const resp = await searchApi.get({ ids: missingIds, limit: missingIds.length });
+ *         return new Map(resp.data.map((e) => [e.id, e]));
+ *     },
+ *     (id) => `${CACHE_KEY_PREFIX}entity:${id}`,
+ * );
+ * ```
  */
 export declare function cachedBatch<T>(ids: string[], entity: EntityType, batchFetcher: (missingIds: string[]) => Promise<Map<string, T>>, keyFn: (id: string) => string): Promise<Map<string, T>>;
 /**

package/cache/cache-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../src/lib/cache/cache-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEzE,4CAA4C;AAC5C,MAAM,WAAW,OAAO;IACpB,IAAI,aAAa,IAAI,OAAO,CAAC;IAC7B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACtD,OAAO,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,EAAE,GAAG,IAAI,CAAC;IACzE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IACvD,KAAK,IAAI,IAAI,CAAC;CACjB;AAKD;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wCAAwC;AACxC,wBAAgB,KAAK,IAAI,OAAO,GAAG,IAAI,CAEtC;AAED,QAAA,MAAM,iBAAiB,EAAE,MAAM,CAAC,UAAU,EAAE,iBAAiB,CAQ5D,CAAC;AAwCF;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAoCtG;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EAAE,EACb,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAC/D,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CA6DzB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5C;AAGD,OAAO,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../src/lib/cache/cache-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvF,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACpB,IAAI,aAAa,IAAI,OAAO,CAAC;IAC7B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC7D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACxE,OAAO,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3F,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACzE,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAC/B;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE3C;AAED,wCAAwC;AACxC,wBAAgB,KAAK,IAAI,OAAO,GAAG,IAAI,CAEtC;AAED,QAAA,MAAM,iBAAiB,EAAE,MAAM,CAAC,UAAU,EAAE,iBAAiB,CAS5D,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAEhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,iBAAiB,CAElE;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAoCtG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EAAE,EACb,MAAM,EAAE,UAAU,EAClB,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAC/D,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CA6DzB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5C;AAGD,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/cache/cache-manager.js

@@ -4,14 +4,21 @@ function initL2(store) {
   l2 = store;
 }
 const ENTITY_TTL_CONFIG = {
-  competitions: { staleTTL: 24 * 3600, maxTTL: 72 * 3600 },
-  teams: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },
-  athletes: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },
-  venues: { staleTTL: 72 * 3600, maxTTL: 168 * 3600 },
-  countries: { staleTTL: 96 * 3600, maxTTL: 168 * 3600 },
-  coaches: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },
-  search: { staleTTL: 300, maxTTL: 1800 }
+  competitions: { staleTTL: 8 * 3600, maxTTL: 72 * 3600 },
+  teams: { staleTTL: 8 * 3600, maxTTL: 48 * 3600 },
+  athletes: { staleTTL: 8 * 3600, maxTTL: 48 * 3600 },
+  venues: { staleTTL: 7 * 24 * 3600, maxTTL: 14 * 24 * 3600 },
+  countries: { staleTTL: 7 * 24 * 3600, maxTTL: 14 * 24 * 3600 },
+  coaches: { staleTTL: 24 * 3600, maxTTL: 72 * 3600 },
+  search: { staleTTL: 8 * 3600, maxTTL: 2 * 24 * 3600 },
+  sportsCompetition: { staleTTL: 5 * 60, maxTTL: 3600 }
 };
+function setEntityTTL(entity, config) {
+  ENTITY_TTL_CONFIG[entity] = { ...config };
+}
+function getEntityTTL(entity) {
+  return { ...getConfig(entity) };
+}
 const refreshing = /* @__PURE__ */ new Set();
 function getConfig(entity) {
   const config = ENTITY_TTL_CONFIG[entity];
@@ -29,10 +36,10 @@ function isExpired(entry, maxTTL) {
 function backgroundRefresh(key, entity, fetcher) {
   if (refreshing.has(key)) return;
   refreshing.add(key);
-  fetcher().then((data) => {
+  fetcher().then(async (data) => {
     memoryStore.set(key, data);
     if (l2?.isInitialized) {
-      l2.set(key, entity, data);
+      await l2.set(key, entity, data);
     }
   }).catch((err) => {
     console.error(`[cache] Background refresh failed for ${key}:`, err);
@@ -53,7 +60,7 @@ async function cached(key, entity, fetcher) {
     }
   }
   if (l2?.isInitialized) {
-    const l2Entry = l2.get(key);
+    const l2Entry = await l2.get(key);
     if (l2Entry && !isExpired(l2Entry, maxTTL)) {
       memoryStore.set(key, l2Entry.data);
       if (isFresh(l2Entry, staleTTL)) {
@@ -66,7 +73,7 @@ async function cached(key, entity, fetcher) {
   const data = await fetcher();
   memoryStore.set(key, data);
   if (l2?.isInitialized) {
-    l2.set(key, entity, data);
+    await l2.set(key, entity, data);
   }
   return data;
 }
@@ -91,7 +98,7 @@ async function cachedBatch(ids, entity, batchFetcher, keyFn) {
       found = true;
     }
     if (!found && l2?.isInitialized) {
-      const l2Entry = l2.get(key);
+      const l2Entry = await l2.get(key);
       if (l2Entry && !isExpired(l2Entry, maxTTL)) {
         memoryStore.set(key, l2Entry.data);
         results.set(id, l2Entry.data);
@@ -116,7 +123,7 @@ async function cachedBatch(ids, entity, batchFetcher, keyFn) {
       const key = keyFn(id);
       memoryStore.set(key, data);
       if (l2?.isInitialized) {
-        l2.set(key, entity, data);
+        await l2.set(key, entity, data);
       }
       results.set(id, data);
     }
@@ -130,7 +137,9 @@ export {
   ENTITY_TTL_CONFIG,
   cached,
   cachedBatch,
+  getEntityTTL,
   initL2,
-  invalidate
+  invalidate,
+  setEntityTTL
 };
 //# sourceMappingURL=cache-manager.js.map

package/cache/cache-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-manager.js","sources":["../../src/lib/cache/cache-manager.ts"],"sourcesContent":["/**\n * Cache Manager - Orchestrates L1 (memory) + optional L2 with SWR pattern\n *\n * L2 (SQLite) is never statically imported here — it's injected at runtime\n * via initL2() so that browser bundles don't pull in better-sqlite3.\n */\n\nimport { memoryStore } from \"./memory-store\";\nimport type { CacheEntry, EntityCacheConfig, EntityType } from \"./types\";\n\n/** Interface that L2 stores must satisfy */\nexport interface L2Store {\n    get isInitialized(): boolean;\n    get<T>(key: string): CacheEntry<T> | undefined;\n    set(key: string, entity: string, data: unknown): void;\n    setMany(entries: { key: string; entity: string; data: unknown }[]): void;\n    cleanup(entity: string, maxTTLSeconds: number): number;\n    clear(): void;\n}\n\n/** The active L2 store — null until initL2() is called */\nlet l2: L2Store | null = null;\n\n/**\n * Initialize L2 cache layer. Call on server startup.\n * Client-side apps skip this — L2 is never loaded.\n */\nexport function initL2(store: L2Store): void {\n    l2 = store;\n}\n\n/** Get the L2 store (if initialized) */\nexport function getL2(): L2Store | null {\n    return l2;\n}\n\nconst ENTITY_TTL_CONFIG: Record<EntityType, EntityCacheConfig> = {\n    competitions: { staleTTL: 24 * 3600, maxTTL: 72 * 3600 },\n    teams: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },\n    athletes: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },\n    venues: { staleTTL: 72 * 3600, maxTTL: 168 * 3600 },\n    countries: { staleTTL: 96 * 3600, maxTTL: 168 * 3600 },\n    coaches: { staleTTL: 24 * 3600, maxTTL: 48 * 3600 },\n    search: { staleTTL: 300, maxTTL: 1800 },\n};\n\n/** Set of keys currently being refreshed in the background (thundering herd prevention) */\nconst refreshing = new Set<string>();\n\nfunction getConfig(entity: EntityType): EntityCacheConfig {\n    const config = ENTITY_TTL_CONFIG[entity];\n    if (!config) {\n        throw new Error(`Unknown entity type: ${entity}`);\n    }\n    return config;\n}\n\nfunction isFresh(entry: CacheEntry<unknown>, staleTTL: number): boolean {\n    return Date.now() - entry.storedAt < staleTTL * 1000;\n}\n\nfunction isExpired(entry: CacheEntry<unknown>, maxTTL: number): boolean {\n    return Date.now() - entry.storedAt >= maxTTL * 1000;\n}\n\nfunction backgroundRefresh<T>(key: string, entity: EntityType, fetcher: () => Promise<T>): void {\n    if (refreshing.has(key)) return;\n    refreshing.add(key);\n\n    fetcher()\n        .then((data) => {\n            memoryStore.set(key, data);\n            if (l2?.isInitialized) {\n                l2.set(key, entity, data);\n            }\n        })\n        .catch((err) => {\n            console.error(`[cache] Background refresh failed for ${key}:`, err);\n        })\n        .finally(() => {\n            refreshing.delete(key);\n        });\n}\n\n/**\n * Single-key cache-through with SWR (Stale-While-Revalidate)\n */\nexport async function cached<T>(key: string, entity: EntityType, fetcher: () => Promise<T>): Promise<T> {\n    const { staleTTL, maxTTL } = getConfig(entity);\n\n    // L1 check\n    const l1 = memoryStore.get<T>(key);\n    if (l1) {\n        if (isFresh(l1, staleTTL)) {\n            return l1.data;\n        }\n        if (!isExpired(l1, maxTTL)) {\n            backgroundRefresh(key, entity, fetcher);\n            return l1.data;\n        }\n    }\n\n    // L2 check\n    if (l2?.isInitialized) {\n        const l2Entry = l2.get<T>(key);\n        if (l2Entry && !isExpired(l2Entry, maxTTL)) {\n            // Promote to L1\n            memoryStore.set(key, l2Entry.data);\n            if (isFresh(l2Entry, staleTTL)) {\n                return l2Entry.data;\n            }\n            backgroundRefresh(key, entity, fetcher);\n            return l2Entry.data;\n        }\n    }\n\n    // Full miss — await fetcher\n    const data = await fetcher();\n    memoryStore.set(key, data);\n    if (l2?.isInitialized) {\n        l2.set(key, entity, data);\n    }\n    return data;\n}\n\n/**\n * Smart batch cache — only fetches uncached IDs from the API\n */\nexport async function cachedBatch<T>(\n    ids: string[],\n    entity: EntityType,\n    batchFetcher: (missingIds: string[]) => Promise<Map<string, T>>,\n    keyFn: (id: string) => string\n): Promise<Map<string, T>> {\n    const { staleTTL, maxTTL } = getConfig(entity);\n    const results = new Map<string, T>();\n    const missingIds: string[] = [];\n\n    for (const id of ids) {\n        const key = keyFn(id);\n        let found = false;\n\n        // L1 check\n        const l1 = memoryStore.get<T>(key);\n        if (l1 && !isExpired(l1, maxTTL)) {\n            results.set(id, l1.data);\n            if (!isFresh(l1, staleTTL)) {\n                backgroundRefresh(key, entity, async () => {\n                    const fetched = await batchFetcher([id]);\n                    const item = fetched.get(id);\n                    if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);\n                    return item;\n                });\n            }\n            found = true;\n        }\n\n        // L2 check\n        if (!found && l2?.isInitialized) {\n            const l2Entry = l2.get<T>(key);\n            if (l2Entry && !isExpired(l2Entry, maxTTL)) {\n                memoryStore.set(key, l2Entry.data);\n                results.set(id, l2Entry.data);\n                if (!isFresh(l2Entry, staleTTL)) {\n                    backgroundRefresh(key, entity, async () => {\n                        const fetched = await batchFetcher([id]);\n                        const item = fetched.get(id);\n                        if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);\n                        return item;\n                    });\n                }\n                found = true;\n            }\n        }\n\n        if (!found) {\n            missingIds.push(id);\n        }\n    }\n\n    // Fetch missing IDs in a single batch\n    if (missingIds.length > 0) {\n        const fetched = await batchFetcher(missingIds);\n        for (const [id, data] of fetched) {\n            const key = keyFn(id);\n            memoryStore.set(key, data);\n            if (l2?.isInitialized) {\n                l2.set(key, entity, data);\n            }\n            results.set(id, data);\n        }\n    }\n\n    return results;\n}\n\n/**\n * Remove an entry from both cache layers\n */\nexport function invalidate(key: string): void {\n    memoryStore.delete(key);\n}\n\n// Export for testing\nexport { ENTITY_TTL_CONFIG };\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache-manager.js","sources":["../../src/lib/cache/cache-manager.ts"],"sourcesContent":["/**\n * Cache Manager - Orchestrates L1 (memory) + optional L2 with SWR pattern\n *\n * L2 (SQLite) is never statically imported here — it's injected at runtime\n * via initL2() so that browser bundles don't pull in better-sqlite3.\n */\n\nimport { memoryStore } from \"./memory-store\";\nimport type { CacheEntry, EntityCacheConfig, EntityType, MaybePromise } from \"./types\";\n\n/** Interface that L2 stores must satisfy. Methods may be sync or async. */\nexport interface L2Store {\n    get isInitialized(): boolean;\n    get<T>(key: string): MaybePromise<CacheEntry<T> | undefined>;\n    set(key: string, entity: EntityType, data: unknown): MaybePromise<void>;\n    setMany(entries: { key: string; entity: EntityType; data: unknown }[]): MaybePromise<void>;\n    cleanup(entity: EntityType, maxTTLSeconds: number): MaybePromise<number>;\n    clear(): MaybePromise<void>;\n}\n\n/** The active L2 store — null until initL2() is called */\nlet l2: L2Store | null = null;\n\n/**\n * Initialize the L2 cache layer. Call once at server startup; the binding\n * is process-wide and replaces any previously-set store.\n *\n * In browser bundles, never call this — L2 is opt-in and the cache will\n * operate L1-only when uninitialized (correct, just slower).\n *\n * In multi-instance deployments (e.g. Cloud Run), L2 should be a shared,\n * durable store (Redis, DynamoDB, …) so a warm cache from one instance\n * serves every other instance. A reference Redis adapter is at\n * `src/lib/cache/__tests__/redis-l2-store.ts`.\n *\n * @example Next.js instrumentation hook\n * ```ts\n * // instrumentation.ts\n * export async function register() {\n *   if (process.env.NEXT_RUNTIME !== \"nodejs\") return;\n *   const { initL2 } = await import(\"fansunited-data-layer\");\n *   const { createRedisL2Store } = await import(\"./src/lib/cache/redisL2Store\");\n *   const { getRedis } = await import(\"./src/lib/redis\");\n *   initL2(createRedisL2Store({ client: getRedis() }));\n * }\n * ```\n *\n * @see {@link L2Store} for the interface a custom store must satisfy.\n */\nexport function initL2(store: L2Store): void {\n    l2 = store;\n}\n\n/** Get the L2 store (if initialized) */\nexport function getL2(): L2Store | null {\n    return l2;\n}\n\nconst ENTITY_TTL_CONFIG: Record<EntityType, EntityCacheConfig> = {\n    competitions: { staleTTL: 8 * 3600, maxTTL: 72 * 3600 },\n    teams: { staleTTL: 8 * 3600, maxTTL: 48 * 3600 },\n    athletes: { staleTTL: 8 * 3600, maxTTL: 48 * 3600 },\n    venues: { staleTTL: 7 * 24 * 3600, maxTTL: 14 * 24 * 3600 },\n    countries: { staleTTL: 7 * 24 * 3600, maxTTL: 14 * 24 * 3600 },\n    coaches: { staleTTL: 24 * 3600, maxTTL: 72 * 3600 },\n    search: { staleTTL: 8 * 3600, maxTTL: 2 * 24 * 3600 },\n    sportsCompetition: { staleTTL: 5 * 60, maxTTL: 3600 },\n};\n\n/**\n * Replace the TTL config for an entity type at runtime. The new values\n * apply to subsequent `cached()` / `cachedBatch()` calls; existing L2\n * entries keep whatever TTL they were written with.\n *\n * Useful for:\n * - per-environment tuning (dev: short TTLs to see changes; prod: long)\n * - overriding ahead of a known traffic spike\n * - tests that need to simulate stale / expired entries in seconds\n *\n * @example\n * ```ts\n * setEntityTTL(\"sportsCompetition\", { staleTTL: 30, maxTTL: 600 });\n * ```\n *\n * @see ../README.md § 7 for the full list of default TTLs.\n */\nexport function setEntityTTL(entity: EntityType, config: EntityCacheConfig): void {\n    ENTITY_TTL_CONFIG[entity] = { ...config };\n}\n\n/**\n * Read the current TTL config for an entity type.\n *\n * Primarily for L2 adapters that translate `entity` into an underlying\n * eviction TTL (e.g. Redis `EX` seconds = `maxTTL`). The returned object\n * is a defensive copy — mutating it has no effect on the manager.\n *\n * @throws when called with an entity name not in the config.\n */\nexport function getEntityTTL(entity: EntityType): EntityCacheConfig {\n    return { ...getConfig(entity) };\n}\n\n/** Set of keys currently being refreshed in the background (thundering herd prevention) */\nconst refreshing = new Set<string>();\n\nfunction getConfig(entity: EntityType): EntityCacheConfig {\n    const config = ENTITY_TTL_CONFIG[entity];\n    if (!config) {\n        throw new Error(`Unknown entity type: ${entity}`);\n    }\n    return config;\n}\n\nfunction isFresh(entry: CacheEntry<unknown>, staleTTL: number): boolean {\n    return Date.now() - entry.storedAt < staleTTL * 1000;\n}\n\nfunction isExpired(entry: CacheEntry<unknown>, maxTTL: number): boolean {\n    return Date.now() - entry.storedAt >= maxTTL * 1000;\n}\n\nfunction backgroundRefresh<T>(key: string, entity: EntityType, fetcher: () => Promise<T>): void {\n    if (refreshing.has(key)) return;\n    refreshing.add(key);\n\n    fetcher()\n        .then(async (data) => {\n            memoryStore.set(key, data);\n            if (l2?.isInitialized) {\n                await l2.set(key, entity, data);\n            }\n        })\n        .catch((err) => {\n            console.error(`[cache] Background refresh failed for ${key}:`, err);\n        })\n        .finally(() => {\n            refreshing.delete(key);\n        });\n}\n\n/**\n * Single-key cache-through with stale-while-revalidate.\n *\n * Flow:\n * 1. L1 hit, fresh (< staleTTL)              → return.\n * 2. L1 hit, stale but valid (< maxTTL)      → return + kick background refresh.\n * 3. L1 miss, L2 hit, fresh                  → promote to L1 + return.\n * 4. L1 miss, L2 hit, stale but valid        → promote + return + background refresh.\n * 5. Full miss                               → await `fetcher`, populate L1+L2, return.\n *\n * Background refreshes share a per-key in-flight set, so concurrent\n * callers don't trigger a thundering herd of upstream fetches.\n *\n * The `key` must include the {@link CACHE_KEY_PREFIX} (`\"fudl:\"`) by\n * convention so it can be SCANned safely in a shared Redis instance.\n *\n * @param key      Fully-qualified cache key (e.g. `\"fudl:sports:competition:fb:c:1:active\"`).\n * @param entity   Entity type — drives the SWR window via `ENTITY_TTL_CONFIG`.\n * @param fetcher  Upstream call, invoked on miss or background refresh.\n *\n * @example\n * ```ts\n * const data = await cached(\n *     `${CACHE_KEY_PREFIX}sports:competition:${id}:active`,\n *     \"sportsCompetition\",\n *     () => fetchFromSportsApi(id),\n * );\n * ```\n */\nexport async function cached<T>(key: string, entity: EntityType, fetcher: () => Promise<T>): Promise<T> {\n    const { staleTTL, maxTTL } = getConfig(entity);\n\n    // L1 check\n    const l1 = memoryStore.get<T>(key);\n    if (l1) {\n        if (isFresh(l1, staleTTL)) {\n            return l1.data;\n        }\n        if (!isExpired(l1, maxTTL)) {\n            backgroundRefresh(key, entity, fetcher);\n            return l1.data;\n        }\n    }\n\n    // L2 check\n    if (l2?.isInitialized) {\n        const l2Entry = await l2.get<T>(key);\n        if (l2Entry && !isExpired(l2Entry, maxTTL)) {\n            // Promote to L1\n            memoryStore.set(key, l2Entry.data);\n            if (isFresh(l2Entry, staleTTL)) {\n                return l2Entry.data;\n            }\n            backgroundRefresh(key, entity, fetcher);\n            return l2Entry.data;\n        }\n    }\n\n    // Full miss — await fetcher\n    const data = await fetcher();\n    memoryStore.set(key, data);\n    if (l2?.isInitialized) {\n        await l2.set(key, entity, data);\n    }\n    return data;\n}\n\n/**\n * Multi-key cache-through with stale-while-revalidate.\n *\n * For each `id`, the cache is checked (L1, then L2) and only the *missing*\n * IDs are passed to `batchFetcher` in a single upstream call. Stale-but-\n * valid entries are returned immediately and refreshed in the background\n * per-key, just like {@link cached}.\n *\n * Why a separate function from `cached`? An N-ID lookup is one upstream\n * batch request, not N parallel single-key calls — which is the whole\n * reason the Search API supports `?ids=…,…` in the first place.\n *\n * @param ids           IDs to resolve, in request order.\n * @param entity        Entity type — drives the SWR window.\n * @param batchFetcher  Called with the subset of IDs not in cache.\n *                      Must return a `Map<id, value>` (missing IDs okay).\n * @param keyFn         Builds a fully-qualified cache key from an ID.\n *                      Convention: `(id) => \\`${CACHE_KEY_PREFIX}entity:${id}\\``.\n *\n * @example\n * ```ts\n * const entities = await cachedBatch(\n *     ids,\n *     \"search\",\n *     async (missingIds) => {\n *         const resp = await searchApi.get({ ids: missingIds, limit: missingIds.length });\n *         return new Map(resp.data.map((e) => [e.id, e]));\n *     },\n *     (id) => `${CACHE_KEY_PREFIX}entity:${id}`,\n * );\n * ```\n */\nexport async function cachedBatch<T>(\n    ids: string[],\n    entity: EntityType,\n    batchFetcher: (missingIds: string[]) => Promise<Map<string, T>>,\n    keyFn: (id: string) => string\n): Promise<Map<string, T>> {\n    const { staleTTL, maxTTL } = getConfig(entity);\n    const results = new Map<string, T>();\n    const missingIds: string[] = [];\n\n    for (const id of ids) {\n        const key = keyFn(id);\n        let found = false;\n\n        // L1 check\n        const l1 = memoryStore.get<T>(key);\n        if (l1 && !isExpired(l1, maxTTL)) {\n            results.set(id, l1.data);\n            if (!isFresh(l1, staleTTL)) {\n                backgroundRefresh(key, entity, async () => {\n                    const fetched = await batchFetcher([id]);\n                    const item = fetched.get(id);\n                    if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);\n                    return item;\n                });\n            }\n            found = true;\n        }\n\n        // L2 check\n        if (!found && l2?.isInitialized) {\n            const l2Entry = await l2.get<T>(key);\n            if (l2Entry && !isExpired(l2Entry, maxTTL)) {\n                memoryStore.set(key, l2Entry.data);\n                results.set(id, l2Entry.data);\n                if (!isFresh(l2Entry, staleTTL)) {\n                    backgroundRefresh(key, entity, async () => {\n                        const fetched = await batchFetcher([id]);\n                        const item = fetched.get(id);\n                        if (!item) throw new Error(`Batch fetcher did not return ID: ${id}`);\n                        return item;\n                    });\n                }\n                found = true;\n            }\n        }\n\n        if (!found) {\n            missingIds.push(id);\n        }\n    }\n\n    // Fetch missing IDs in a single batch\n    if (missingIds.length > 0) {\n        const fetched = await batchFetcher(missingIds);\n        for (const [id, data] of fetched) {\n            const key = keyFn(id);\n            memoryStore.set(key, data);\n            if (l2?.isInitialized) {\n                await l2.set(key, entity, data);\n            }\n            results.set(id, data);\n        }\n    }\n\n    return results;\n}\n\n/**\n * Remove an entry from both cache layers\n */\nexport function invalidate(key: string): void {\n    memoryStore.delete(key);\n}\n\n// Export for testing\nexport { ENTITY_TTL_CONFIG };\n"],"names":[],"mappings":"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"}

package/cache/cleanup.d.ts

@@ -1,7 +1,7 @@
 /**
  * Periodic L2 cache cleanup
  */
-export declare function runCleanup(): void;
+export declare function runCleanup(): Promise<void>;
 export declare function startCleanupSchedule(intervalMs?: number): void;
 export declare function stopCleanupSchedule(): void;
 //# sourceMappingURL=cleanup.d.ts.map

package/cache/cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/lib/cache/cleanup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,wBAAgB,UAAU,IAAI,IAAI,CAWjC;AAED,wBAAgB,oBAAoB,CAAC,UAAU,SAAiB,GAAG,IAAI,CAGtE;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/lib/cache/cleanup.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAWhD;AAED,wBAAgB,oBAAoB,CAAC,UAAU,SAAiB,GAAG,IAAI,CAGtE;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C"}

package/cache/index.d.ts

@@ -6,8 +6,9 @@
  *   import { initSqliteStore, sqliteStore } from './cache/sqlite-store';
  */
 export { memoryStore } from "./memory-store";
-export { cached, cachedBatch, invalidate, initL2 } from "./cache-manager";
+export { cached, cachedBatch, invalidate, initL2, setEntityTTL, getEntityTTL } from "./cache-manager";
 export type { L2Store } from "./cache-manager";
 export { runCleanup, startCleanupSchedule, stopCleanupSchedule } from "./cleanup";
-export type { CacheEntry, EntityCacheConfig, EntityType } from "./types";
+export type { CacheEntry, EntityCacheConfig, EntityType, MaybePromise } from "./types";
+export { CACHE_KEY_PREFIX } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAC1E,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACtG,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAClF,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/cache/sqlite-store.d.ts

@@ -1,18 +1,18 @@
 /**
  * L2 Cache - SQLite on-disk store (server-only)
  */
-import type { CacheEntry } from "./types";
+import type { CacheEntry, EntityType } from "./types";
 export declare function initSqliteStore(dbPath?: string): void;
 export declare const sqliteStore: {
     readonly isInitialized: boolean;
     get<T>(key: string): CacheEntry<T> | undefined;
-    set(key: string, entity: string, data: unknown): void;
+    set(key: string, entity: EntityType, data: unknown): void;
     setMany(entries: {
         key: string;
-        entity: string;
+        entity: EntityType;
         data: unknown;
     }[]): void;
-    cleanup(entity: string, maxTTLSeconds: number): number;
+    cleanup(entity: EntityType, maxTTLSeconds: number): number;
     clear(): void;
     close(): void;
 };

package/cache/sqlite-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-store.d.ts","sourceRoot":"","sources":["../../src/lib/cache/sqlite-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAW1C,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CA4BrD;AAED,eAAO,MAAM,WAAW;4BACC,OAAO;QAIxB,CAAC,OAAO,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS;aAarC,MAAM,UAAU,MAAM,QAAQ,OAAO,GAAG,IAAI;qBASpC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,EAAE,GAAG,IAAI;oBAgBxD,MAAM,iBAAiB,MAAM,GAAG,MAAM;aAQ7C,IAAI;aAIJ,IAAI;CAMhB,CAAC"}
+{"version":3,"file":"sqlite-store.d.ts","sourceRoot":"","sources":["../../src/lib/cache/sqlite-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAWtD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CA4BrD;AAED,eAAO,MAAM,WAAW;4BACC,OAAO;QAIxB,CAAC,OAAO,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS;aAarC,MAAM,UAAU,UAAU,QAAQ,OAAO,GAAG,IAAI;qBASxC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,EAAE,GAAG,IAAI;oBAgB5D,UAAU,iBAAiB,MAAM,GAAG,MAAM;aAQjD,IAAI;aAIJ,IAAI;CAMhB,CAAC"}

package/cache/types.d.ts

@@ -11,5 +11,13 @@ export interface EntityCacheConfig {
     /** Time in seconds before data is completely expired and must be re-fetched */
     maxTTL: number;
 }
-export type EntityType = "competitions" | "teams" | "athletes" | "venues" | "countries" | "coaches" | "search";
+export type EntityType = "competitions" | "teams" | "athletes" | "venues" | "countries" | "coaches" | "search" | "sportsCompetition";
+/** Convenience: a value that may or may not be wrapped in a Promise. */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Prefix for every cache key emitted by this library.
+ * Namespaces the data-layer's entries inside a shared store (Redis SCAN by `fudl:*`).
+ * Bump the literal (e.g. `"fudl:v2:"`) to invalidate every cached entry across deploys.
+ */
+export declare const CACHE_KEY_PREFIX = "fudl:";
 //# sourceMappingURL=types.d.ts.map

package/cache/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/cache/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAC9B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/cache/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAC9B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,UAAU,GAChB,cAAc,GACd,OAAO,GACP,UAAU,GACV,QAAQ,GACR,WAAW,GACX,SAAS,GACT,QAAQ,GACR,mBAAmB,CAAC;AAE1B,wEAAwE;AACxE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC"}

package/cache/types.js

@@ -0,0 +1,5 @@
+const CACHE_KEY_PREFIX = "fudl:";
+export {
+  CACHE_KEY_PREFIX
+};
+//# sourceMappingURL=types.js.map

package/cache/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["../../src/lib/cache/types.ts"],"sourcesContent":["/**\n * Shared cache types\n */\n\nexport interface CacheEntry<T> {\n    data: T;\n    storedAt: number; // Unix timestamp in ms\n}\n\nexport interface EntityCacheConfig {\n    /** Time in seconds before data is considered stale (triggers background refresh) */\n    staleTTL: number;\n    /** Time in seconds before data is completely expired and must be re-fetched */\n    maxTTL: number;\n}\n\nexport type EntityType =\n    | \"competitions\"\n    | \"teams\"\n    | \"athletes\"\n    | \"venues\"\n    | \"countries\"\n    | \"coaches\"\n    | \"search\"\n    | \"sportsCompetition\";\n\n/** Convenience: a value that may or may not be wrapped in a Promise. */\nexport type MaybePromise<T> = T | Promise<T>;\n\n/**\n * Prefix for every cache key emitted by this library.\n * Namespaces the data-layer's entries inside a shared store (Redis SCAN by `fudl:*`).\n * Bump the literal (e.g. `\"fudl:v2:\"`) to invalidate every cached entry across deploys.\n */\nexport const CACHE_KEY_PREFIX = \"fudl:\";\n"],"names":[],"mappings":"AAkCO,MAAM,mBAAmB;"}

package/fansunited-data-layer.js

@@ -1,10 +1,11 @@
 import { getConfig, isConfigured, setConfig } from "./config/index.js";
 import { memoryStore } from "./cache/memory-store.js";
+import { CACHE_KEY_PREFIX } from "./cache/types.js";
 import { GOAL_EVENT_TYPES } from "./utilities/stats/core/types.js";
 import { addProviderRef, getProviderRefId, toProviderRefArray } from "./api/sportal365-sports/shared/providerRef.helper.js";
 import { aggregatePlayerStatisticsFromMatches, getAllPlayerStatisticsFromMatches, getMostCardedPlayersFromMatches, getTopAssistersFromMatches, getTopGoalContributorsFromMatches, getTopScorersFromMatches } from "./helpers/player.helpers.js";
 import { analyzeMatch, calcAverage, calcPercentage, formatAsAverage, formatPossessionPercentage, formatStatValue, formatWithAverage, getOpponentScore, getTeamScore, isMatchFinished, isTeamAway, isTeamHome, isTeamInMatch } from "./utilities/stats/core/helpers.js";
-import { cached, cachedBatch, initL2, invalidate } from "./cache/cache-manager.js";
+import { cached, cachedBatch, getEntityTTL, initL2, invalidate, setEntityTTL } from "./cache/cache-manager.js";
 import { calculateH2HStats, getRecentH2HMeetings } from "./utilities/stats/match/headToHead.js";
 import { calculateStreak, getTeamStreaks, getTeamStreaksComparison, streakFilters } from "./utilities/stats/team/streaks.js";
 import { getActiveSeason } from "./helpers/competition.helpers.js";
@@ -17,6 +18,10 @@ import { getFansUnitedFootballMatch, getFansUnitedFootballMatches, getFansUnited
 import { getFansUnitedFootballPlayer, getFansUnitedFootballPlayers } from "./api/fansunited/football/players/index.js";
 import { getFansUnitedFootballSearch } from "./api/fansunited/football/search/index.js";
 import { getFansUnitedFootballTeam, getFansUnitedFootballTeams } from "./api/fansunited/football/teams/index.js";
+import { getFansUnitedSportsCompetition } from "./api/fansunited/sports/competition/index.js";
+import { getFansUnitedSportsCompetitionHydrated } from "./api/fansunited/sports/competition/hydrated.js";
+import { getFansUnitedSportsLivescore } from "./api/fansunited/sports/livescore/index.js";
+import { getFansUnitedSportsLivescoreHydrated } from "./api/fansunited/sports/livescore/hydrated.js";
 import { getFootballCompetition, getFootballSeasonDetails } from "./api/sportal365-sports/football/competitions/index.js";
 import { getFootballLivescore, getFootballMatch, getFootballMatchCommentary, getFootballMatchEvents, getFootballMatchLineups, getFootballMatchOdds, getFootballMatchStatistics, getFootballMatches } from "./api/sportal365-sports/football/matches/index.js";
 import { getFootballPlayerCareerStatistics, getFootballPlayerRecentStatistics, getFootballPlayerSeasonStatistics, getFootballPlayerSeasonStatisticsByPlayerIds } from "./api/sportal365-sports/football/statistics/index.js";
@@ -37,6 +42,7 @@ import { search } from "./api/sportal365-sports/search/index.js";
 import { searchFootball } from "./api/sportal365-sports/football/search/index.js";
 import { useAllPlayerStatisticsFromMatches, useMostCardedPlayersFromMatches, usePlayerStatistics, usePlayerStatisticsMap, useTopAssistersFromMatches, useTopGoalContributorsFromMatches, useTopScorersFromMatches } from "./helpers/player.hooks.js";
 export {
+  CACHE_KEY_PREFIX,
   GOAL_EVENT_TYPES,
   addProviderRef,
   aggregatePlayerStatisticsFromMatches,
@@ -56,6 +62,7 @@ export {
   getBasketballLivescore,
   getBatchMatchOdds,
   getConfig,
+  getEntityTTL,
   getFansUnitedCompetitions,
   getFansUnitedCountries,
   getFansUnitedEntitiesByIds,
@@ -74,6 +81,10 @@ export {
   getFansUnitedFootballTeamPreviousMatch,
   getFansUnitedFootballTeams,
   getFansUnitedSearchEntities,
+  getFansUnitedSportsCompetition,
+  getFansUnitedSportsCompetitionHydrated,
+  getFansUnitedSportsLivescore,
+  getFansUnitedSportsLivescoreHydrated,
   getFansUnitedTeamsByCompetition,
   getFansUnitedTeamsByCountry,
   getFansUnitedVenues,
@@ -137,6 +148,7 @@ export {
   search,
   searchFootball,
   setConfig,
+  setEntityTTL,
   streakFilters,
   toProviderRefArray,
   useAllPlayerStatisticsFromMatches,