@reactionary/core 0.0.30 → 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,7 +99,14 @@ function buildClient(providers) {
     }
   }
   client.analytics = mergedAnalytics;
-  return client;
+  const completeClient = {
+    ...client,
+    cache: sharedCache
+  };
+  return completeClient;
+}
+function createCache() {
+  return new RedisCache();
 }
 
 // otel/src/trpc-middleware.ts
@@ -286,12 +341,14 @@ function createProviderInstrumentation(providerName) {
 }
 
 // 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
@@ -317,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 }
@@ -343,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
@@ -828,7 +1023,6 @@ var SearchQueryByTermSchema = BaseQuerySchema.extend({
 var SearchQuerySchema = z25.union([SearchQueryByTermSchema]);
 export {
   AnalyticsProvider,
-  BaseCachingStrategy,
   BaseModelSchema,
   BaseMutationSchema,
   BaseProvider,
@@ -863,6 +1057,7 @@ export {
   InventorySchema,
   MetaSchema,
   MonetaryAmountSchema,
+  NoOpCache,
   PriceIdentifierSchema,
   PriceMutationSchema,
   PriceProvider,
@@ -890,5 +1085,6 @@ export {
   SearchResultProductSchema,
   SearchResultSchema,
   SessionSchema,
-  buildClient
+  buildClient,
+  createCache
 };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@reactionary/core",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "dependencies": {
     "zod": "4.0.0-beta.20250430T185432",
     "@upstash/redis": "^1.34.9",
-    "@reactionary/otel": "0.0.30"
+    "@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;
-}