@reactionary/source 0.0.30 → 0.0.32

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# Verification commands
+- `npx nx affected:build` builds the projects affected by current changes.
+- `npx nx affected:lint` lints and verifies the projects affected by current changes.
+
+# Code style
+- Use ES modules (import/export) syntax, not CommonJS (require).
+- Keep things strongly typed. Do not use `as any` or similar unchecked type casts.
+
+# Workflow
+- Be sure to ensure that changes lint and build.
+- Avoid introducing changes that would be breaking for any client consumer of the library without asking for clearance.

package/core/package.json

@@ -4,6 +4,6 @@
   "dependencies": {
     "zod": "4.0.0-beta.20250430T185432",
     "@upstash/redis": "^1.34.9",
-    "@reactionary/otel": "0.0.1"
+    "reflect-metadata": "0.2.2"
   }
 }

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

@@ -0,0 +1,19 @@
+/**
+ * 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/core/src/cache/cache.interface.ts

@@ -0,0 +1,38 @@
+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/core/src/cache/noop-cache.ts

@@ -0,0 +1,42 @@
+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 class NoOpCache implements Cache {
+  public async get<T>(_key: string, _schema: z.ZodType<T>): Promise<T | null> {
+    // Always return null - never a cache hit
+    return null;
+  }
+
+  public async put(_key: string, _value: unknown, _ttlSeconds?: number): Promise<void> {
+    // No-op - silently ignore cache write requests
+    return;
+  }
+
+  public async del(_keys: string | string[]): Promise<void> {
+    // No-op - silently ignore delete requests
+    return;
+  }
+
+  public async keys(_pattern: string): Promise<string[]> {
+    // Always return empty array
+    return [];
+  }
+
+  public async clear(_pattern?: string): Promise<void> {
+    // No-op - silently ignore clear requests
+    return;
+  }
+
+  public async getStats(): Promise<{ hits: number; misses: number; size: number }> {
+    // Always return zeros
+    return {
+      hits: 0,
+      misses: 0,
+      size: 0
+    };
+  }
+}

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

@@ -1,41 +1,74 @@
 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 class RedisCache {
-  protected strategy: CachingStrategy;
+export class RedisCache implements Cache {
   protected redis: Redis;
 
-  constructor(strategy: CachingStrategy) {
-    this.strategy = strategy;
+  constructor() {
     this.redis = Redis.fromEnv();
   }
 
-  public async get<T extends BaseModel>(query: BaseQuery, session: Session, schema: z.ZodType<T>): Promise<T | null> {
-    let result = null;
+  public async get<T>(key: string, schema: z.ZodType<T>): Promise<T | null> {
+    if (!key) {
+      return null;
+    }
     
-    const cacheInformation = this.strategy.get(query, session);
+    const unvalidated = await this.redis.get(key);
+    const parsed = schema.safeParse(unvalidated);
+
+    if (parsed.success) {
+      return parsed.data;
+    }
     
-    if (cacheInformation.canCache && cacheInformation.key) {
-      const unvalidated = await this.redis.get(cacheInformation.key);
-      const parsed = schema.safeParse(unvalidated);
+    return null;
+  }
 
-      if (parsed.success) {
-        result = parsed.data;
-      }
+  public async put(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+    if (!key) {
+      return;
     }
+
+    const options = ttlSeconds ? { ex: ttlSeconds } : undefined;
+    await this.redis.set(key, value, options);
+  }
+
+  public async del(keys: string | string[]): Promise<void> {
+    const keyArray = Array.isArray(keys) ? keys : [keys];
     
-    return result;
+    for (const key of keyArray) {
+      if (key.includes('*')) {
+        // Handle wildcard patterns
+        const matchingKeys = await this.redis.keys(key);
+        if (matchingKeys.length > 0) {
+          await this.redis.del(...matchingKeys);
+        }
+      } else {
+        // Delete specific key
+        await this.redis.del(key);
+      }
+    }
   }
 
-  public put(query: BaseQuery, session: Session, value: unknown): void {
-    const cacheInformation = this.strategy.get(query, session);
+  public async keys(pattern: string): Promise<string[]> {
+    return await this.redis.keys(pattern);
+  }
 
-    if (cacheInformation.canCache && cacheInformation.key) {
-      this.redis.set(cacheInformation.key, value, { ex: cacheInformation.cacheDurationInSeconds });
+  public async clear(pattern?: string): Promise<void> {
+    const searchPattern = pattern || '*';
+    const keys = await this.redis.keys(searchPattern);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
     }
   }
+
+  public async getStats(): Promise<{ hits: number; misses: number; size: number }> {
+    // Basic cache statistics (could be enhanced with actual Redis metrics)
+    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
+    };
+  }
 }

package/core/src/client/client-builder.ts

@@ -0,0 +1,63 @@
+import { Cache } from "../cache/cache.interface";
+import { NoOpCache } from "../cache/noop-cache";
+import { Client } from "./client";
+import { AnalyticsProvider } from "../providers/analytics.provider";
+
+type CapabilityFactory<T> = (cache: Cache) => T;
+
+type MergeCapabilities<Acc, New> = Omit<Acc, keyof New> & New;
+
+export class ClientBuilder<TClient = object> {
+    private factories: Array<CapabilityFactory<Partial<Client>>> = [];
+    private cache: Cache | undefined;
+
+    withCapability<TNew extends Partial<Client>>(
+        factory: CapabilityFactory<TNew>
+    ): ClientBuilder<MergeCapabilities<TClient, TNew>> {
+        const newBuilder = new ClientBuilder<MergeCapabilities<TClient, TNew>>();
+        newBuilder.factories = [...this.factories, factory];
+        newBuilder.cache = this.cache;
+        return newBuilder;
+    }
+
+    withCache(cache: Cache): ClientBuilder<TClient> {
+        const newBuilder = new ClientBuilder<TClient>();
+        newBuilder.factories = [...this.factories];
+        newBuilder.cache = cache;
+        return newBuilder;
+    }
+
+    build(): TClient & { cache: Cache } {
+        let client = {} as TClient;
+        
+        // Use provided cache or default to NoOpCache
+        const sharedCache = this.cache || new NoOpCache();
+        
+        const mergedAnalytics: AnalyticsProvider[] = [];
+        
+        for (const factory of this.factories) {
+            const provider = factory(sharedCache);
+            client = {
+                ...client,
+                ...provider
+            };
+            
+            if (provider.analytics) {
+                mergedAnalytics.push(...provider.analytics);
+            }
+        }
+        
+        // Add merged analytics if any were collected
+        if (mergedAnalytics.length > 0) {
+            (client as Record<string, unknown>)['analytics'] = mergedAnalytics;
+        }
+        
+        // Add cache to complete the client
+        const completeClient = {
+            ...client,
+            cache: sharedCache
+        } as TClient & { cache: Cache };
+        
+        return completeClient;
+    }
+}

package/core/src/client/client.ts

@@ -5,6 +5,8 @@ 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";
+import { RedisCache } from "../cache/redis-cache";
 
 export interface Client {
     product: ProductProvider,
@@ -17,12 +19,23 @@ export interface Client {
     inventory: InventoryProvider
 }
 
-export function buildClient<T extends Partial<Client>>(providers: Array<T>): Required<T> {
+export interface BuildClientOptions {
+    cache?: Cache;
+}
+
+export function buildClient<T extends Partial<Client>>(
+    providerFactories: Array<(cache: Cache) => T>,
+    options: BuildClientOptions = {}
+): Required<T> {
     let client = { } as Required<T>;
 
+    // Create shared cache instance
+    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
@@ -34,6 +47,17 @@ export function buildClient<T extends Partial<Client>>(providers: Array<T>): Req
     }
 
     client.analytics = mergedAnalytics;
+    
+    // Add cache to complete the client
+    const completeClient = {
+        ...client,
+        cache: sharedCache
+    } as Required<T>;
+
+    return completeClient;
+}
 
-    return client satisfies T;
+// Convenience function to create a shared cache instance
+export function createCache(): Cache {
+    return new RedisCache();
 }

package/core/src/decorators/trpc.decorators.ts

@@ -0,0 +1,144 @@
+import 'reflect-metadata';
+
+/**
+ * Metadata keys for TRPC method decorators
+ */
+export const TRPC_QUERY_METADATA_KEY = Symbol('trpc:query');
+export const TRPC_MUTATION_METADATA_KEY = Symbol('trpc:mutation');
+
+
+
+/**
+ * Options for TRPC method decorators
+ */
+export interface TRPCMethodOptions {
+  /** Custom name for the TRPC procedure (defaults to method name) */
+  name?: string;
+  /** Description for documentation purposes */
+  description?: string;
+}
+
+/**
+ * Decorator to mark a provider method as a TRPC query procedure
+ * Query procedures are read-only operations (GET-like)
+ * 
+ * @example
+ * ```typescript
+ * class ProductProvider extends BaseProvider {
+ *   @trpcQuery()
+ *   async getById(payload: ProductQueryById, session: Session): Promise<Product> {
+ *     // implementation
+ *   }
+ * 
+ *   @trpcQuery({ name: 'findBySlug', description: 'Find product by URL slug' })
+ *   async getBySlug(payload: ProductQueryBySlug, session: Session): Promise<Product> {
+ *     // implementation
+ *   }
+ * }
+ * ```
+ */
+export function trpcQuery(options: TRPCMethodOptions = {}): MethodDecorator {
+  return function (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) {
+    // Store metadata about this method being a TRPC query
+    const metadata = {
+      methodName: String(propertyKey),
+      isQuery: true,
+      isMutation: false,
+      options
+    };
+
+    // Store on the prototype so it's inherited
+    Reflect.defineMetadata(TRPC_QUERY_METADATA_KEY, metadata, target, propertyKey);
+    
+    // Also store a list of all TRPC methods on the class
+    const existingMethods = Reflect.getMetadata(TRPC_QUERY_METADATA_KEY, target.constructor) || [];
+    existingMethods.push({ propertyKey, metadata });
+    Reflect.defineMetadata(TRPC_QUERY_METADATA_KEY, existingMethods, target.constructor);
+  };
+}
+
+/**
+ * Decorator to mark a provider method as a TRPC mutation procedure
+ * Mutation procedures are write operations that modify state (POST/PUT/DELETE-like)
+ * 
+ * @example
+ * ```typescript
+ * class CartProvider extends BaseProvider {
+ *   @trpcMutation()
+ *   async add(payload: CartAddMutation, session: Session): Promise<Cart> {
+ *     // implementation
+ *   }
+ * 
+ *   @trpcMutation({ name: 'removeItem' })
+ *   async remove(payload: CartRemoveMutation, session: Session): Promise<Cart> {
+ *     // implementation  
+ *   }
+ * }
+ * ```
+ */
+export function trpcMutation(options: TRPCMethodOptions = {}): MethodDecorator {
+  return function (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) {
+    // Store metadata about this method being a TRPC mutation
+    const metadata = {
+      methodName: String(propertyKey),
+      isQuery: false,
+      isMutation: true,
+      options
+    };
+
+    // Store on the prototype so it's inherited
+    Reflect.defineMetadata(TRPC_MUTATION_METADATA_KEY, metadata, target, propertyKey);
+    
+    // Also store a list of all TRPC methods on the class
+    const existingMethods = Reflect.getMetadata(TRPC_MUTATION_METADATA_KEY, target.constructor) || [];
+    existingMethods.push({ propertyKey, metadata });
+    Reflect.defineMetadata(TRPC_MUTATION_METADATA_KEY, existingMethods, target.constructor);
+  };
+}
+
+/**
+ * Get all TRPC query methods from a class or instance
+ */
+export function getTRPCQueryMethods(target: any): Array<{ propertyKey: string | symbol; metadata: any }> {
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return Reflect.getMetadata(TRPC_QUERY_METADATA_KEY, constructor) || [];
+}
+
+/**
+ * Get all TRPC mutation methods from a class or instance
+ */
+export function getTRPCMutationMethods(target: any): Array<{ propertyKey: string | symbol; metadata: any }> {
+  const constructor = typeof target === 'function' ? target : target.constructor;
+  return Reflect.getMetadata(TRPC_MUTATION_METADATA_KEY, constructor) || [];
+}
+
+/**
+ * Get all TRPC methods (both queries and mutations) from a class or instance
+ */
+export function getAllTRPCMethods(target: any): Array<{ propertyKey: string | symbol; metadata: any }> {
+  return [
+    ...getTRPCQueryMethods(target),
+    ...getTRPCMutationMethods(target)
+  ];
+}
+
+/**
+ * Check if a method is marked as a TRPC query
+ */
+export function isTRPCQuery(target: any, methodName: string | symbol): boolean {
+  return !!Reflect.getMetadata(TRPC_QUERY_METADATA_KEY, target, methodName);
+}
+
+/**
+ * Check if a method is marked as a TRPC mutation
+ */
+export function isTRPCMutation(target: any, methodName: string | symbol): boolean {
+  return !!Reflect.getMetadata(TRPC_MUTATION_METADATA_KEY, target, methodName);
+}
+
+/**
+ * Check if a method is marked for TRPC exposure (query or mutation)
+ */
+export function isTRPCMethod(target: any, methodName: string | symbol): boolean {
+  return isTRPCQuery(target, methodName) || isTRPCMutation(target, methodName);
+}

package/core/src/index.ts

@@ -1,7 +1,12 @@
-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 './client/client-builder';
+
+export * from './decorators/trpc.decorators';
 
 export * from './providers/analytics.provider';
 export * from './providers/base.provider';

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

@@ -1,10 +1,7 @@
 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';
 
 export abstract class AnalyticsProvider<
-  T extends AnalyticsEvent = AnalyticsEvent,
-  Q extends AnalyticsQuery = AnalyticsQuery,
-  M extends AnalyticsMutation = AnalyticsMutation
-> extends BaseProvider<T, Q, M> {}
+  T extends AnalyticsEvent = AnalyticsEvent
+> extends BaseProvider<T> {
+}

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

@@ -1,23 +1,21 @@
 import { z } from 'zod';
-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';
 
 /**
  * Base capability provider, responsible for mutations (changes) and queries (fetches)
  * for a given business object domain.
  */
 export abstract class BaseProvider<
-  T extends BaseModel = BaseModel,
-  Q extends BaseQuery = BaseQuery,
-  M extends BaseMutation = BaseMutation
+  T extends BaseModel = BaseModel
 > {
-  private instrumentation: ReturnType<typeof createProviderInstrumentation>;
+  protected cache: Cache;
   
-  constructor(public readonly schema: z.ZodType<T>, public readonly querySchema: z.ZodType<Q, Q>, public readonly mutationSchema: z.ZodType<M, M>) {
-    this.instrumentation = createProviderInstrumentation(this.constructor.name);
+  constructor(
+    public readonly schema: z.ZodType<T>,
+    cache: Cache
+  ) {
+    this.cache = cache;
   }
 
   /**
@@ -36,60 +34,12 @@ export abstract class BaseProvider<
   }
 
   /**
-   * Retrieves a set of entities matching the list of queries. The size of
-   * the resulting list WILL always match the size of the query list. The
-   * result list will never contain nulls or undefined. The order
-   * of the results will match the order of the queries.
+   * Handler for parsing a response from a remote provider and converting it
+   * into the typed domain model.
    */
-  public async query(queries: Q[], session: Session): Promise<T[]> {
-    return this.instrumentation.traceQuery(
-      'query',
-      async (span) => {
-        span.setAttribute('provider.query.count', queries.length);
-        const results = await this.fetch(queries, session);
+  protected parseSingle(_body: unknown): T {
+    const model = this.newModel();
 
-        for (const result of results) {
-          this.assert(result);
-        }
-
-        span.setAttribute('provider.result.count', results.length);
-        return results;
-      },
-      { queryCount: queries.length }
-    );
-  }
-
-  /**
-   * Executes the listed mutations in order and returns the final state
-   * resulting from that set of operations.
-   */
-  public async mutate(mutations: M[], session: Session): Promise<T> {
-    return this.instrumentation.traceMutation(
-      'mutate',
-      async (span) => {
-        span.setAttribute('provider.mutation.count', mutations.length);
-        const result = await this.process(mutations, session);
-
-        this.assert(result);
-
-        return result;
-      },
-      { mutationCount: mutations.length }
-    );
+    return this.assert(model);
   }
-
-  /**
-   * The internal extension point for providers implementating query
-   * capabilities.
-   */
-  protected abstract fetch(queries: Q[], session: Session): Promise<T[]>;
-
-  /**
-   * The internal extension point for providers implementing mutation
-   * capabilities.
-   */
-  protected abstract process(
-    mutations: M[],
-    session: Session
-  ): Promise<T>;
 }

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

@@ -1,10 +1,14 @@
-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 { CartQueryById } from "../schemas/queries/cart.query";
+import { Session } from "../schemas/session.schema";
+import { CartMutationItemAdd, CartMutationItemQuantityChange, CartMutationItemRemove } from "../schemas/mutations/cart.mutation";
 
 export abstract class CartProvider<
-  T extends Cart = Cart,
-  Q extends CartQuery = CartQuery,
-  M extends CartMutation = CartMutation
-> extends BaseProvider<T, Q, M> {}
+  T extends Cart = Cart
+> extends BaseProvider<T> {
+  public abstract getById(payload: CartQueryById, session: Session): Promise<T>;
+  public abstract add(payload: CartMutationItemAdd, session: Session): Promise<T>;
+  public abstract remove(payload: CartMutationItemRemove, session: Session): Promise<T>;
+  public abstract changeQuantity(payload: CartMutationItemQuantityChange, session: Session): Promise<T>;
+}

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

@@ -1,10 +1,13 @@
 import { Identity } from "../schemas/models/identity.model";
-import { IdentityQuery } from "../schemas/queries/identity.query";
-import { IdentityMutation } from "../schemas/mutations/identity.mutation";
+import { IdentityMutationLogin, IdentityMutationLogout } from "../schemas/mutations/identity.mutation";
+import { IdentityQuerySelf } from "../schemas/queries/identity.query";
+import { Session } from "../schemas/session.schema";
 import { BaseProvider } from "./base.provider";
 
 export abstract class IdentityProvider<
   T extends Identity = Identity,
-  Q extends IdentityQuery = IdentityQuery,
-  M extends IdentityMutation = IdentityMutation
-> extends BaseProvider<T, Q, M> {}
+> extends BaseProvider<T> {
+  public abstract getSelf(payload: IdentityQuerySelf, session: Session): Promise<T>;
+  public abstract login(payload: IdentityMutationLogin, session: Session): Promise<T>;
+  public abstract logout(payload: IdentityMutationLogout, session: Session): Promise<T>;
+}

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

@@ -1,11 +1,10 @@
-import z from 'zod';
 import { Inventory } from '../schemas/models/inventory.model';
 import { InventoryQuery } from '../schemas/queries/inventory.query';
-import { InventoryMutation } from '../schemas/mutations/inventory.mutation';
+import { Session } from '../schemas/session.schema';
 import { BaseProvider } from './base.provider';
 
 export abstract class InventoryProvider<
-  T extends Inventory = Inventory,
-  Q extends InventoryQuery = InventoryQuery,
-  M extends InventoryMutation = InventoryMutation
-> extends BaseProvider<T, Q, M> {}
+  T extends Inventory = Inventory
+> extends BaseProvider<T> {
+  public abstract getBySKU(payload: InventoryQuery, session: Session): Promise<T>;
+}