@reactionary/core 0.0.29 → 0.0.31

package/index.js

@@ -1,47 +1,95 @@
-// core/src/cache/caching-strategy.ts
-var BaseCachingStrategy = class {
-  get(query, session) {
-    const q = query;
-    return {
-      key: q.sku,
-      cacheDurationInSeconds: 300,
-      canCache: true
-    };
-  }
-};
-
 // core/src/cache/redis-cache.ts
 import { Redis } from "@upstash/redis";
 var RedisCache = class {
-  constructor(strategy) {
-    this.strategy = strategy;
+  constructor() {
     this.redis = Redis.fromEnv();
   }
-  async get(query, session, schema) {
-    let result = null;
-    const cacheInformation = this.strategy.get(query, session);
-    if (cacheInformation.canCache && cacheInformation.key) {
-      const unvalidated = await this.redis.get(cacheInformation.key);
-      const parsed = schema.safeParse(unvalidated);
-      if (parsed.success) {
-        result = parsed.data;
+  async get(key, schema) {
+    if (!key) {
+      return null;
+    }
+    const unvalidated = await this.redis.get(key);
+    const parsed = schema.safeParse(unvalidated);
+    if (parsed.success) {
+      return parsed.data;
+    }
+    return null;
+  }
+  async put(key, value, ttlSeconds) {
+    if (!key) {
+      return;
+    }
+    const options = ttlSeconds ? { ex: ttlSeconds } : void 0;
+    await this.redis.set(key, value, options);
+  }
+  async del(keys) {
+    const keyArray = Array.isArray(keys) ? keys : [keys];
+    for (const key of keyArray) {
+      if (key.includes("*")) {
+        const matchingKeys = await this.redis.keys(key);
+        if (matchingKeys.length > 0) {
+          await this.redis.del(...matchingKeys);
+        }
+      } else {
+        await this.redis.del(key);
       }
     }
-    return result;
   }
-  put(query, session, value) {
-    const cacheInformation = this.strategy.get(query, session);
-    if (cacheInformation.canCache && cacheInformation.key) {
-      this.redis.set(cacheInformation.key, value, { ex: cacheInformation.cacheDurationInSeconds });
+  async keys(pattern) {
+    return await this.redis.keys(pattern);
+  }
+  async clear(pattern) {
+    const searchPattern = pattern || "*";
+    const keys = await this.redis.keys(searchPattern);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
     }
   }
+  async getStats() {
+    const keys = await this.redis.keys("*");
+    return {
+      hits: 0,
+      // Would need to track this separately
+      misses: 0,
+      // Would need to track this separately  
+      size: keys.length
+    };
+  }
+};
+
+// core/src/cache/noop-cache.ts
+var NoOpCache = class {
+  async get(_key, _schema) {
+    return null;
+  }
+  async put(_key, _value, _ttlSeconds) {
+    return;
+  }
+  async del(_keys) {
+    return;
+  }
+  async keys(_pattern) {
+    return [];
+  }
+  async clear(_pattern) {
+    return;
+  }
+  async getStats() {
+    return {
+      hits: 0,
+      misses: 0,
+      size: 0
+    };
+  }
 };
 
 // core/src/client/client.ts
-function buildClient(providers) {
+function buildClient(providerFactories, options = {}) {
   let client = {};
+  const sharedCache = options.cache || new RedisCache();
   const mergedAnalytics = [];
-  for (const provider of providers) {
+  for (const factory of providerFactories) {
+    const provider = factory(sharedCache);
     client = {
       ...client,
       ...provider
@@ -51,184 +99,48 @@ function buildClient(providers) {
     }
   }
   client.analytics = mergedAnalytics;
-  return client;
+  const completeClient = {
+    ...client,
+    cache: sharedCache
+  };
+  return completeClient;
+}
+function createCache() {
+  return new RedisCache();
 }
 
-// otel/src/sdk.ts
-import { NodeSDK } from "@opentelemetry/sdk-node";
-import { resourceFromAttributes, defaultResource } from "@opentelemetry/resources";
-import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT } from "@opentelemetry/semantic-conventions";
+// otel/src/trpc-middleware.ts
+import { TRPCError } from "@trpc/server";
 import {
-  BatchSpanProcessor
-} from "@opentelemetry/sdk-trace-base";
-import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
-import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+  SpanKind as SpanKind2,
+  SpanStatusCode as SpanStatusCode3
+} from "@opentelemetry/api";
 
-// otel/src/config.ts
-import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { PeriodicExportingMetricReader, ConsoleMetricExporter } from "@opentelemetry/sdk-metrics";
-function isBrowser() {
-  return typeof window !== "undefined" && typeof process === "undefined";
-}
-function getConfigFromEnv() {
-  if (isBrowser()) {
-    return {
-      serviceName: "browser-service",
-      serviceVersion: void 0,
-      environment: "browser",
-      otlpEndpoint: void 0,
-      otlpHeaders: void 0,
-      traceEnabled: false,
-      metricsEnabled: false,
-      metricExportIntervalMillis: 6e4
-    };
-  }
-  const tracesExporter = process.env["OTEL_TRACES_EXPORTER"] || "console";
-  const metricsExporter = process.env["OTEL_METRICS_EXPORTER"] || "console";
-  return {
-    serviceName: process.env["OTEL_SERVICE_NAME"] || "unknown_service",
-    serviceVersion: process.env["OTEL_SERVICE_VERSION"],
-    environment: process.env["DEPLOYMENT_ENVIRONMENT"] || process.env["NODE_ENV"] || "development",
-    otlpEndpoint: process.env["OTEL_EXPORTER_OTLP_ENDPOINT"],
-    otlpHeaders: process.env["OTEL_EXPORTER_OTLP_HEADERS"] ? parseHeaders(process.env["OTEL_EXPORTER_OTLP_HEADERS"]) : void 0,
-    traceEnabled: tracesExporter !== "none",
-    metricsEnabled: metricsExporter !== "none",
-    metricExportIntervalMillis: process.env["OTEL_METRIC_EXPORT_INTERVAL"] ? parseInt(process.env["OTEL_METRIC_EXPORT_INTERVAL"], 10) : 6e4
-    // Default 60 seconds per OTEL spec
-  };
-}
-function parseHeaders(headerString) {
-  const headers = {};
-  headerString.split(",").forEach((header) => {
-    const [key, value] = header.split("=");
-    if (key && value) {
-      headers[key.trim()] = value.trim();
-    }
-  });
-  return headers;
-}
-function createTraceExporter(config) {
-  if (!config.traceEnabled) {
-    return void 0;
-  }
-  const tracesExporter = process.env["OTEL_TRACES_EXPORTER"] || "console";
-  switch (tracesExporter) {
-    case "otlp":
-    case "otlp/http": {
-      if (!config.otlpEndpoint) {
-        console.warn("OTEL_EXPORTER_OTLP_ENDPOINT not set, falling back to console");
-        return new ConsoleSpanExporter();
-      }
-      const tracesEndpoint = process.env["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] || `${config.otlpEndpoint}/v1/traces`;
-      return new OTLPTraceExporter({
-        url: tracesEndpoint,
-        headers: config.otlpHeaders
-      });
-    }
-    case "console":
-      return new ConsoleSpanExporter();
-    case "none":
-    default:
-      return void 0;
-  }
-}
-function createMetricReader(config) {
-  if (!config.metricsEnabled) {
-    return void 0;
-  }
-  const metricsExporter = process.env["OTEL_METRICS_EXPORTER"] || "console";
-  let exporter;
-  switch (metricsExporter) {
-    case "otlp":
-    case "otlp/http": {
-      if (!config.otlpEndpoint) {
-        console.warn("OTEL_EXPORTER_OTLP_ENDPOINT not set, falling back to console");
-        exporter = new ConsoleMetricExporter();
-      } else {
-        const metricsEndpoint = process.env["OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"] || `${config.otlpEndpoint}/v1/metrics`;
-        exporter = new OTLPMetricExporter({
-          url: metricsEndpoint,
-          headers: config.otlpHeaders
-        });
-      }
-      break;
-    }
-    case "console":
-      exporter = new ConsoleMetricExporter();
-      break;
-    case "none":
-    default:
-      return void 0;
-  }
-  return new PeriodicExportingMetricReader({
-    exporter,
-    exportIntervalMillis: config.metricExportIntervalMillis
-  });
-}
+// otel/src/tracer.ts
+import {
+  trace,
+  SpanStatusCode,
+  context as otelContext
+} from "@opentelemetry/api";
 
 // otel/src/sdk.ts
+import { NodeSDK } from "@opentelemetry/sdk-node";
 var sdk = null;
 var isInitialized = false;
 var initializationPromise = null;
-function isBrowser2() {
+function isBrowser() {
   return typeof window !== "undefined" && typeof process === "undefined";
 }
 function ensureInitialized() {
   if (isInitialized || initializationPromise) {
     return;
   }
-  if (isBrowser2()) {
+  if (isBrowser()) {
     isInitialized = true;
     return;
   }
   initializationPromise = Promise.resolve().then(() => {
-    const config = getConfigFromEnv();
-    if (process.env["OTEL_LOG_LEVEL"] === "debug") {
-      console.log("OpenTelemetry auto-initializing with config:", {
-        serviceName: config.serviceName,
-        environment: config.environment,
-        tracesExporter: process.env["OTEL_TRACES_EXPORTER"] || "console",
-        metricsExporter: process.env["OTEL_METRICS_EXPORTER"] || "console"
-      });
-    }
-    const attributes = {
-      [SEMRESATTRS_SERVICE_NAME]: config.serviceName
-    };
-    if (config.serviceVersion) {
-      attributes[SEMRESATTRS_SERVICE_VERSION] = config.serviceVersion;
-    }
-    if (config.environment) {
-      attributes[SEMRESATTRS_DEPLOYMENT_ENVIRONMENT] = config.environment;
-    }
-    const customResource = resourceFromAttributes(attributes);
-    const resource = defaultResource().merge(customResource);
-    const traceExporter = createTraceExporter(config);
-    const metricReader = createMetricReader(config);
-    const instrumentations = [
-      new HttpInstrumentation({
-        requestHook: (span, request) => {
-          const req = request;
-          if (req.headers) {
-            span.setAttribute("http.request.body.size", req.headers["content-length"] || 0);
-          }
-        },
-        responseHook: (span, response) => {
-          const res = response;
-          if (res.headers) {
-            span.setAttribute("http.response.body.size", res.headers["content-length"] || 0);
-          }
-        }
-      }),
-      new ExpressInstrumentation()
-    ];
-    sdk = new NodeSDK({
-      resource,
-      spanProcessors: traceExporter ? [new BatchSpanProcessor(traceExporter)] : [],
-      metricReader,
-      instrumentations
-    });
+    sdk = new NodeSDK();
     sdk.start();
     isInitialized = true;
     process.on("SIGTERM", async () => {
@@ -256,11 +168,6 @@ function isOtelInitialized() {
 }
 
 // otel/src/tracer.ts
-import {
-  trace,
-  SpanStatusCode,
-  context as otelContext
-} from "@opentelemetry/api";
 import { SpanKind, SpanStatusCode as SpanStatusCode2 } from "@opentelemetry/api";
 var TRACER_NAME = "@reactionary/otel";
 var TRACER_VERSION = "0.0.1";
@@ -356,13 +263,6 @@ function getMetrics() {
   return metricsInstance;
 }
 
-// otel/src/trpc-middleware.ts
-import { TRPCError } from "@trpc/server";
-import {
-  SpanKind as SpanKind2,
-  SpanStatusCode as SpanStatusCode3
-} from "@opentelemetry/api";
-
 // otel/src/provider-instrumentation.ts
 import { SpanKind as SpanKind3 } from "@opentelemetry/api";
 async function withProviderSpan(options, fn) {
@@ -440,16 +340,15 @@ function createProviderInstrumentation(providerName) {
   };
 }
 
-// otel/src/index.ts
-import { trace as trace2, context, SpanKind as SpanKind4, SpanStatusCode as SpanStatusCode4 } from "@opentelemetry/api";
-
 // core/src/providers/base.provider.ts
+import * as crypto from "crypto";
 var BaseProvider = class {
-  constructor(schema, querySchema, mutationSchema) {
+  constructor(schema, querySchema, mutationSchema, cache) {
     this.schema = schema;
     this.querySchema = querySchema;
     this.mutationSchema = mutationSchema;
     this.instrumentation = createProviderInstrumentation(this.constructor.name);
+    this.cache = cache;
   }
   /**
    * Validates that the final domain model constructed by the provider
@@ -475,11 +374,44 @@ var BaseProvider = class {
       "query",
       async (span) => {
         span.setAttribute("provider.query.count", queries.length);
-        const results = await this.fetch(queries, session);
-        for (const result of results) {
-          this.assert(result);
+        let cacheHits = 0;
+        let cacheMisses = 0;
+        const results = [];
+        for (const query of queries) {
+          let result = null;
+          const cacheInfo = this.getCacheEvaluation(query, session);
+          if (cacheInfo.canCache && cacheInfo.key) {
+            try {
+              result = await this.cache.get(cacheInfo.key, this.schema);
+              if (result) {
+                cacheHits++;
+                span.setAttribute("provider.cache.hit", true);
+              }
+            } catch (error) {
+              console.warn(`Cache get error for ${this.constructor.name}:`, error);
+            }
+          }
+          if (!result) {
+            const singleResult = await this.fetch([query], session);
+            result = singleResult[0];
+            cacheMisses++;
+            if (result && cacheInfo.canCache && cacheInfo.key) {
+              try {
+                await this.cache.put(cacheInfo.key, result, cacheInfo.cacheDurationInSeconds);
+              } catch (error) {
+                console.warn(`Cache put error for ${this.constructor.name}:`, error);
+              }
+            }
+          }
+          if (result) {
+            this.assert(result);
+            results.push(result);
+          }
         }
         span.setAttribute("provider.result.count", results.length);
+        span.setAttribute("provider.cache.hits", cacheHits);
+        span.setAttribute("provider.cache.misses", cacheMisses);
+        span.setAttribute("provider.cache.hit_ratio", cacheHits / (cacheHits + cacheMisses));
         return results;
       },
       { queryCount: queries.length }
@@ -501,34 +433,139 @@ var BaseProvider = class {
       { mutationCount: mutations.length }
     );
   }
+  /**
+   * Provider-specific cache evaluation logic.
+   * Returns information about how this query should be cached.
+   * Override this method to enable caching with custom keys and TTL.
+   * Default implementation returns no caching.
+   */
+  getCacheEvaluation(query, session) {
+    const providerName = this.constructor.name.toLowerCase();
+    const userId = session.identity?.id || "anonymous";
+    const queryHash = crypto.createHash("md5").update(JSON.stringify(query)).digest("hex").substring(0, 12);
+    const key = `${providerName}:${userId}:${queryHash}`;
+    return {
+      key,
+      cacheDurationInSeconds: 0,
+      canCache: false
+    };
+  }
 };
 
 // core/src/providers/analytics.provider.ts
+import * as crypto2 from "crypto";
 var AnalyticsProvider = class extends BaseProvider {
+  getCacheEvaluation(query, _session) {
+    const providerName = this.constructor.name.toLowerCase();
+    const relevantFields = {
+      type: typeof query === "object" && query !== null && "type" in query ? query.type : void 0,
+      dateRange: typeof query === "object" && query !== null && "dateRange" in query ? query.dateRange : void 0,
+      filters: typeof query === "object" && query !== null && "filters" in query ? query.filters : void 0
+    };
+    const analyticsHash = crypto2.createHash("md5").update(JSON.stringify(relevantFields)).digest("hex").substring(0, 12);
+    const key = `${providerName}:analytics:${analyticsHash}`;
+    return {
+      key,
+      cacheDurationInSeconds: 0,
+      canCache: false
+    };
+  }
 };
 
 // core/src/providers/cart.provider.ts
+import * as crypto3 from "crypto";
 var CartProvider = class extends BaseProvider {
+  getCacheEvaluation(query, session) {
+    const providerName = this.constructor.name.toLowerCase();
+    const userId = session.identity?.id || "anonymous";
+    const queryHash = crypto3.createHash("md5").update(JSON.stringify(query)).digest("hex").substring(0, 12);
+    const key = `${providerName}:cart:${userId}:${queryHash}`;
+    return {
+      key,
+      cacheDurationInSeconds: 0,
+      canCache: false
+    };
+  }
 };
 
 // core/src/providers/identity.provider.ts
 var IdentityProvider = class extends BaseProvider {
+  getCacheEvaluation(_query, session) {
+    const providerName = this.constructor.name.toLowerCase();
+    const userId = session.identity?.id;
+    const key = userId ? `${providerName}:identity:${userId}` : `${providerName}:identity:anonymous`;
+    return {
+      key,
+      cacheDurationInSeconds: 0,
+      canCache: false
+    };
+  }
 };
 
 // core/src/providers/inventory.provider.ts
 var InventoryProvider = class extends BaseProvider {
+  getCacheEvaluation(query, _session) {
+    const providerName = this.constructor.name.toLowerCase();
+    const key = `${providerName}:inventory:${query.sku}`;
+    return {
+      key,
+      cacheDurationInSeconds: 0,
+      canCache: false
+    };
+  }
 };
 
 // core/src/providers/price.provider.ts
+import * as crypto4 from "crypto";
 var PriceProvider = class extends BaseProvider {
+  getCacheEvaluation(query, _session) {
+    const providerName = this.constructor.name.toLowerCase();
+    const skuHash = crypto4.createHash("md5").update(JSON.stringify(query.sku)).digest("hex").substring(0, 12);
+    const key = `${providerName}:price:${skuHash}`;
+    return {
+      key,
+      cacheDurationInSeconds: 0,
+      canCache: false
+    };
+  }
 };
 
 // core/src/providers/product.provider.ts
+import * as crypto5 from "crypto";
 var ProductProvider = class extends BaseProvider {
+  getCacheEvaluation(query, _session) {
+    const providerName = this.constructor.name.toLowerCase();
+    let key;
+    if (query.query === "slug") {
+      key = `${providerName}:product:slug:${query.slug}`;
+    } else if (query.query === "id") {
+      key = `${providerName}:product:id:${query.id}`;
+    } else {
+      const queryHash = crypto5.createHash("md5").update(JSON.stringify(query)).digest("hex").substring(0, 12);
+      key = `${providerName}:product:${queryHash}`;
+    }
+    return {
+      key,
+      cacheDurationInSeconds: 300,
+      // Products are moderately stable - 5 minutes
+      canCache: true
+    };
+  }
 };
 
 // core/src/providers/search.provider.ts
+import * as crypto6 from "crypto";
 var SearchProvider = class extends BaseProvider {
+  getCacheEvaluation(query, _session) {
+    const providerName = this.constructor.name.toLowerCase();
+    const searchHash = crypto6.createHash("md5").update(JSON.stringify(query.search)).digest("hex").substring(0, 12);
+    const key = `${providerName}:search:${searchHash}`;
+    return {
+      key,
+      cacheDurationInSeconds: 0,
+      canCache: false
+    };
+  }
 };
 
 // core/src/schemas/capabilities.schema.ts
@@ -986,7 +1023,6 @@ var SearchQueryByTermSchema = BaseQuerySchema.extend({
 var SearchQuerySchema = z25.union([SearchQueryByTermSchema]);
 export {
   AnalyticsProvider,
-  BaseCachingStrategy,
   BaseModelSchema,
   BaseMutationSchema,
   BaseProvider,
@@ -1021,6 +1057,7 @@ export {
   InventorySchema,
   MetaSchema,
   MonetaryAmountSchema,
+  NoOpCache,
   PriceIdentifierSchema,
   PriceMutationSchema,
   PriceProvider,
@@ -1048,5 +1085,6 @@ export {
   SearchResultProductSchema,
   SearchResultSchema,
   SessionSchema,
-  buildClient
+  buildClient,
+  createCache
 };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@reactionary/core",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "dependencies": {
     "zod": "4.0.0-beta.20250430T185432",
     "@upstash/redis": "^1.34.9",
-    "@reactionary/otel": "0.0.29"
+    "@reactionary/otel": "0.0.31"
   }
 }

package/src/cache/cache-evaluation.interface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cache evaluation result that determines how and if a query should be cached
+ */
+export interface CacheEvaluation {
+    /**
+     * The cache key to use for storing/retrieving the value
+     */
+    key: string;
+    /**
+     * How long to cache the value in seconds
+     */
+    cacheDurationInSeconds: number;
+    /**
+     * Whether this query result can be cached
+     */
+    canCache: boolean;
+}

package/src/cache/cache.interface.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/**
+ * Generic cache interface that can be implemented by different cache backends
+ * (Redis, memory, file-based, etc.)
+ */
+export interface Cache {
+    /**
+     * Retrieves a value from cache and validates it against the provided schema
+     */
+    get<T>(key: string, schema: z.ZodType<T>): Promise<T | null>;
+    /**
+     * Stores a value in cache with optional expiration time
+     */
+    put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /**
+     * Removes one or more keys from cache
+     * Supports wildcard patterns (implementation dependent)
+     */
+    del(keys: string | string[]): Promise<void>;
+    /**
+     * Finds all keys matching a pattern (implementation dependent)
+     */
+    keys(pattern: string): Promise<string[]>;
+    /**
+     * Clears all cache entries or entries matching a pattern
+     */
+    clear(pattern?: string): Promise<void>;
+    /**
+     * Gets basic cache statistics (implementation dependent)
+     */
+    getStats(): Promise<{
+        hits: number;
+        misses: number;
+        size: number;
+    }>;
+}

package/src/cache/noop-cache.d.ts

@@ -0,0 +1,18 @@
+import { Cache } from './cache.interface';
+import z from 'zod';
+/**
+ * No-op cache implementation that never stores or returns data.
+ * Useful for testing or when caching should be disabled.
+ */
+export declare class NoOpCache implements Cache {
+    get<T>(_key: string, _schema: z.ZodType<T>): Promise<T | null>;
+    put(_key: string, _value: unknown, _ttlSeconds?: number): Promise<void>;
+    del(_keys: string | string[]): Promise<void>;
+    keys(_pattern: string): Promise<string[]>;
+    clear(_pattern?: string): Promise<void>;
+    getStats(): Promise<{
+        hits: number;
+        misses: number;
+        size: number;
+    }>;
+}

package/src/cache/redis-cache.d.ts

@@ -1,13 +1,17 @@
 import { Redis } from '@upstash/redis';
-import { CachingStrategy } from './caching-strategy';
-import { BaseQuery } from '../schemas/queries/base.query';
-import { Session } from '../schemas/session.schema';
-import { BaseModel } from '../schemas/models/base.model';
+import { Cache } from './cache.interface';
 import z from 'zod';
-export declare class RedisCache {
-    protected strategy: CachingStrategy;
+export declare class RedisCache implements Cache {
     protected redis: Redis;
-    constructor(strategy: CachingStrategy);
-    get<T extends BaseModel>(query: BaseQuery, session: Session, schema: z.ZodType<T>): Promise<T | null>;
-    put(query: BaseQuery, session: Session, value: unknown): void;
+    constructor();
+    get<T>(key: string, schema: z.ZodType<T>): Promise<T | null>;
+    put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    del(keys: string | string[]): Promise<void>;
+    keys(pattern: string): Promise<string[]>;
+    clear(pattern?: string): Promise<void>;
+    getStats(): Promise<{
+        hits: number;
+        misses: number;
+        size: number;
+    }>;
 }

package/src/client/client.d.ts

@@ -5,6 +5,7 @@ import { IdentityProvider } from '../providers/identity.provider';
 import { CartProvider } from "../providers/cart.provider";
 import { PriceProvider } from "../providers/price.provider";
 import { InventoryProvider } from "../providers/inventory.provider";
+import { Cache } from "../cache/cache.interface";
 export interface Client {
     product: ProductProvider;
     search: SearchProvider;
@@ -15,4 +16,8 @@ export interface Client {
     price: PriceProvider;
     inventory: InventoryProvider;
 }
-export declare function buildClient<T extends Partial<Client>>(providers: Array<T>): Required<T>;
+export interface BuildClientOptions {
+    cache?: Cache;
+}
+export declare function buildClient<T extends Partial<Client>>(providerFactories: Array<(cache: Cache) => T>, options?: BuildClientOptions): Required<T>;
+export declare function createCache(): Cache;

package/src/index.d.ts

@@ -1,5 +1,7 @@
-export * from './cache/caching-strategy';
+export * from './cache/cache.interface';
+export * from './cache/cache-evaluation.interface';
 export * from './cache/redis-cache';
+export * from './cache/noop-cache';
 export * from './client/client';
 export * from './providers/analytics.provider';
 export * from './providers/base.provider';

package/src/providers/analytics.provider.d.ts

@@ -2,5 +2,8 @@ import { AnalyticsEvent } from '../schemas/models/analytics.model';
 import { AnalyticsMutation } from '../schemas/mutations/analytics.mutation';
 import { AnalyticsQuery } from '../schemas/queries/analytics.query';
 import { BaseProvider } from './base.provider';
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
+import { Session } from '../schemas/session.schema';
 export declare abstract class AnalyticsProvider<T extends AnalyticsEvent = AnalyticsEvent, Q extends AnalyticsQuery = AnalyticsQuery, M extends AnalyticsMutation = AnalyticsMutation> extends BaseProvider<T, Q, M> {
+    protected getCacheEvaluation(query: Q, _session: Session): CacheEvaluation;
 }

package/src/providers/base.provider.d.ts

@@ -3,6 +3,9 @@ import { Session } from '../schemas/session.schema';
 import { BaseQuery } from '../schemas/queries/base.query';
 import { BaseMutation } from '../schemas/mutations/base.mutation';
 import { BaseModel } from '../schemas/models/base.model';
+import { createProviderInstrumentation } from '@reactionary/otel';
+import { Cache } from '../cache/cache.interface';
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
 /**
  * Base capability provider, responsible for mutations (changes) and queries (fetches)
  * for a given business object domain.
@@ -11,8 +14,9 @@ export declare abstract class BaseProvider<T extends BaseModel = BaseModel, Q ex
     readonly schema: z.ZodType<T>;
     readonly querySchema: z.ZodType<Q, Q>;
     readonly mutationSchema: z.ZodType<M, M>;
-    private instrumentation;
-    constructor(schema: z.ZodType<T>, querySchema: z.ZodType<Q, Q>, mutationSchema: z.ZodType<M, M>);
+    protected instrumentation: ReturnType<typeof createProviderInstrumentation>;
+    protected cache: Cache;
+    constructor(schema: z.ZodType<T>, querySchema: z.ZodType<Q, Q>, mutationSchema: z.ZodType<M, M>, cache: Cache);
     /**
      * Validates that the final domain model constructed by the provider
      * fulfills the schema as defined. This will throw an exception.
@@ -44,4 +48,11 @@ export declare abstract class BaseProvider<T extends BaseModel = BaseModel, Q ex
      * capabilities.
      */
     protected abstract process(mutations: M[], session: Session): Promise<T>;
+    /**
+     * Provider-specific cache evaluation logic.
+     * Returns information about how this query should be cached.
+     * Override this method to enable caching with custom keys and TTL.
+     * Default implementation returns no caching.
+     */
+    protected getCacheEvaluation(query: Q, session: Session): CacheEvaluation;
 }

package/src/providers/cart.provider.d.ts

@@ -2,5 +2,8 @@ import { CartQuery } from "../schemas/queries/cart.query";
 import { CartMutation } from "../schemas/mutations/cart.mutation";
 import { BaseProvider } from "./base.provider";
 import { Cart } from "../schemas/models/cart.model";
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
+import { Session } from '../schemas/session.schema';
 export declare abstract class CartProvider<T extends Cart = Cart, Q extends CartQuery = CartQuery, M extends CartMutation = CartMutation> extends BaseProvider<T, Q, M> {
+    protected getCacheEvaluation(query: Q, session: Session): CacheEvaluation;
 }

package/src/providers/identity.provider.d.ts

@@ -2,5 +2,8 @@ import { Identity } from "../schemas/models/identity.model";
 import { IdentityQuery } from "../schemas/queries/identity.query";
 import { IdentityMutation } from "../schemas/mutations/identity.mutation";
 import { BaseProvider } from "./base.provider";
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
+import { Session } from '../schemas/session.schema';
 export declare abstract class IdentityProvider<T extends Identity = Identity, Q extends IdentityQuery = IdentityQuery, M extends IdentityMutation = IdentityMutation> extends BaseProvider<T, Q, M> {
+    protected getCacheEvaluation(_query: Q, session: Session): CacheEvaluation;
 }

package/src/providers/inventory.provider.d.ts

@@ -2,5 +2,8 @@ import { Inventory } from '../schemas/models/inventory.model';
 import { InventoryQuery } from '../schemas/queries/inventory.query';
 import { InventoryMutation } from '../schemas/mutations/inventory.mutation';
 import { BaseProvider } from './base.provider';
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
+import { Session } from '../schemas/session.schema';
 export declare abstract class InventoryProvider<T extends Inventory = Inventory, Q extends InventoryQuery = InventoryQuery, M extends InventoryMutation = InventoryMutation> extends BaseProvider<T, Q, M> {
+    protected getCacheEvaluation(query: Q, _session: Session): CacheEvaluation;
 }

package/src/providers/price.provider.d.ts

@@ -2,5 +2,8 @@ import { Price } from '../schemas/models/price.model';
 import { PriceMutation } from '../schemas/mutations/price.mutation';
 import { PriceQuery } from '../schemas/queries/price.query';
 import { BaseProvider } from './base.provider';
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
+import { Session } from '../schemas/session.schema';
 export declare abstract class PriceProvider<T extends Price = Price, Q extends PriceQuery = PriceQuery, M extends PriceMutation = PriceMutation> extends BaseProvider<T, Q, M> {
+    protected getCacheEvaluation(query: Q, _session: Session): CacheEvaluation;
 }

package/src/providers/product.provider.d.ts

@@ -2,5 +2,8 @@ import { Product } from '../schemas/models/product.model';
 import { ProductMutation } from '../schemas/mutations/product.mutation';
 import { ProductQuery } from '../schemas/queries/product.query';
 import { BaseProvider } from './base.provider';
+import { Session } from '../schemas/session.schema';
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
 export declare abstract class ProductProvider<T extends Product = Product, Q extends ProductQuery = ProductQuery, M extends ProductMutation = ProductMutation> extends BaseProvider<T, Q, M> {
+    protected getCacheEvaluation(query: Q, _session: Session): CacheEvaluation;
 }

package/src/providers/search.provider.d.ts

@@ -2,5 +2,8 @@ import { SearchResult } from '../schemas/models/search.model';
 import { SearchQuery } from '../schemas/queries/search.query';
 import { SearchMutation } from '../schemas/mutations/search.mutation';
 import { BaseProvider } from './base.provider';
+import { CacheEvaluation } from '../cache/cache-evaluation.interface';
+import { Session } from '../schemas/session.schema';
 export declare abstract class SearchProvider<T extends SearchResult = SearchResult, Q extends SearchQuery = SearchQuery, M extends SearchMutation = SearchMutation> extends BaseProvider<T, Q, M> {
+    protected getCacheEvaluation(query: Q, _session: Session): CacheEvaluation;
 }

package/src/cache/caching-strategy.d.ts

@@ -1,13 +0,0 @@
-import { BaseQuery } from "../schemas/queries/base.query";
-import { Session } from "../schemas/session.schema";
-export interface CachingStrategyEvaluation {
-    key: string;
-    cacheDurationInSeconds: number;
-    canCache: boolean;
-}
-export interface CachingStrategy {
-    get(query: BaseQuery, session: Session): CachingStrategyEvaluation;
-}
-export declare class BaseCachingStrategy implements CachingStrategy {
-    get(query: BaseQuery, session: Session): CachingStrategyEvaluation;
-}