@reactionary/source 0.0.42 → 0.0.48

package/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx nx build:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx nx lint:*)",
+      "Bash(npx nx test:*)",
+      "Bash(npx nx run:*)",
+      "Bash(npx ts-node:*)",
+      "Bash(npx tsx:*)",
+      "Bash(grep:*)",
+      "Bash(pnpm list:*)",
+      "Bash(npx nx affected:build:*)",
+      "Bash(npx nx affected:lint:*)",
+      "Bash(cat:*)",
+      "Bash(npx nx show projects:*)",
+      "Bash(npx nx g:*)",
+      "Bash(pnpm add:*)",
+      "Bash(npx nx show project:*)",
+      "Bash(npx nx reset:*)",
+      "WebSearch",
+      "Bash(node:*)",
+      "Bash(npm view:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "typescript.preferences.importModuleSpecifierEnding": "auto",
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.preferences.preferTypeOnlyAutoImports": true
+}

package/core/package.json

@@ -5,6 +5,8 @@
   "types": "src/index.d.ts",
   "dependencies": {
     "zod": "4.1.9",
-    "@upstash/redis": "^1.34.9"
+    "@upstash/redis": "^1.34.9",
+    "@reactionary/otel": "0.0.1",
+    "node-object-hash": "^3.1.1"
   }
 }

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

@@ -1,4 +1,10 @@
-import { z } from 'zod';
+import type { z } from 'zod';
+import type { BaseModel } from '../schemas/models';
+
+export interface CacheEntryOptions {
+  ttlSeconds: number;
+  dependencyIds: Array<string>;
+}
 
 /**
  * Generic cache interface that can be implemented by different cache backends
@@ -8,31 +14,21 @@ 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>;
+  get<T extends BaseModel>(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[]>;
+  put(key: string, value: unknown, options: CacheEntryOptions): Promise<void>;
 
   /**
-   * Clears all cache entries or entries matching a pattern
+   * Removes entries from the cache based on a set of dependency
+   * ids
    */
-  clear(pattern?: string): Promise<void>;
+  invalidate(dependencyIds: Array<string>): Promise<void>;
 
   /**
-   * Gets basic cache statistics (implementation dependent)
+   * Removes all entries from cache, wiping it completely
    */
-  getStats(): Promise<{ hits: number; misses: number; size: number }>;
+  clear(): Promise<void>;
 }

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

@@ -0,0 +1,56 @@
+import type { BaseModel } from '../schemas/models';
+import type { Cache, CacheEntryOptions } from './cache.interface';
+import type z from 'zod';
+
+/**
+ * Memory version of the cache. Primarily useful for local development.
+ * This is NOT suited for production use.
+ */
+export class MemoryCache implements Cache {
+  protected entries = new Array<{ key: string; value: unknown, options: CacheEntryOptions }>();
+
+  public async get<T extends BaseModel>(key: string, schema: z.ZodType<T>): Promise<T | null> {
+    const c = this.entries.find((x) => x.key === key);
+
+    if (!c) {
+      return null;
+    }
+
+    const parsed = schema.parse(c.value);
+
+    parsed.meta.cache.hit = true;
+
+    return parsed;
+  }
+
+  public async put(
+    key: string,
+    value: unknown,
+    options: CacheEntryOptions
+  ): Promise<void> {
+    this.entries.push({
+        key,
+        value,
+        options
+    });
+
+    return;
+  }
+
+  public async invalidate(dependencyIds: Array<string>): Promise<void> {
+    let index = 0;
+    for (const entry of this.entries) {
+      for (const entryDependency of entry.options.dependencyIds) {
+        if (dependencyIds.indexOf(entryDependency) > -1) {
+          this.entries.splice(index, 1);
+        }
+      }
+
+      index++;
+    }
+  }
+
+  public async clear(): Promise<void> {
+    this.entries = [];
+  }
+}

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

@@ -1,5 +1,5 @@
-import { Cache } from './cache.interface';
-import z from 'zod';
+import type { Cache, CacheEntryOptions } from './cache.interface';
+import type z from 'zod';
 
 /**
  * No-op cache implementation that never stores or returns data.
@@ -7,36 +7,18 @@ import z from 'zod';
  */
 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
+  public async put(_key: string, _value: unknown, options: CacheEntryOptions): Promise<void> {
     return;
   }
 
-  public async del(_keys: string | string[]): Promise<void> {
-    // No-op - silently ignore delete requests
+  public async invalidate(dependencyIds: Array<string>): Promise<void> {
     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
+  public async clear(): Promise<void> {
     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,6 +1,6 @@
 import { Redis } from '@upstash/redis';
-import { Cache } from './cache.interface';
-import z from 'zod';
+import type { Cache, CacheEntryOptions } from './cache.interface';
+import type z from 'zod';
 
 export class RedisCache implements Cache {
   protected redis: Redis;
@@ -13,62 +13,52 @@ export class RedisCache implements Cache {
     if (!key) {
       return null;
     }
-    
+
     const unvalidated = await this.redis.get(key);
     const parsed = schema.safeParse(unvalidated);
 
     if (parsed.success) {
       return parsed.data;
     }
-    
+
     return null;
   }
 
-  public async put(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+  public async put(
+    key: string,
+    value: unknown,
+    options: CacheEntryOptions
+  ): Promise<void> {
     if (!key) {
       return;
     }
 
-    const options = ttlSeconds ? { ex: ttlSeconds } : undefined;
-    await this.redis.set(key, value, options);
-  }
+    const serialized = JSON.stringify(value);
+    const multi = this.redis.multi();
 
-  public async del(keys: string | string[]): Promise<void> {
-    const keyArray = Array.isArray(keys) ? keys : [keys];
-    
-    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);
-      }
+    multi.set(key, serialized, { ex: options.ttlSeconds });
+
+    for (const depId of options.dependencyIds) {
+      multi.sadd(`dep:${depId}`, key);
     }
-  }
 
-  public async keys(pattern: string): Promise<string[]> {
-    return await this.redis.keys(pattern);
+    await multi.exec();
   }
 
-  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 invalidate(dependencyIds: Array<string>): Promise<void> {
+    for (const id of dependencyIds) {
+      const depKey = `dep:${id}`;
+      const keys = await this.redis.smembers(depKey);
+
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+
+      await this.redis.del(depKey);
     }
   }
 
-  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
-    };
+  public async clear(): Promise<void> {
+    // Not sure about supporting this on Redis.
   }
 }

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

@@ -1,7 +1,7 @@
-import { Cache } from "../cache/cache.interface";
+import type { Cache } from "../cache/cache.interface";
 import { NoOpCache } from "../cache/noop-cache";
-import { Client } from "./client";
-import { AnalyticsProvider } from "../providers/analytics.provider";
+import type { Client } from "./client";
+import type { AnalyticsProvider } from "../providers/analytics.provider";
 
 type CapabilityFactory<T> = (cache: Cache) => T;
 

package/core/src/client/client.ts

@@ -1,14 +1,14 @@
-import { AnalyticsProvider } from "../providers/analytics.provider";
-import { ProductProvider } from "../providers/product.provider";
-import { SearchProvider } from "../providers/search.provider";
-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 type { AnalyticsProvider } from "../providers/analytics.provider";
+import type { ProductProvider } from "../providers/product.provider";
+import type { SearchProvider } from "../providers/search.provider";
+import type { IdentityProvider } from '../providers/identity.provider';
+import type { CartProvider } from "../providers/cart.provider";
+import type { PriceProvider } from "../providers/price.provider";
+import type { InventoryProvider } from "../providers/inventory.provider";
+import type { Cache } from "../cache/cache.interface";
 import { RedisCache } from "../cache/redis-cache";
-import { CategoryProvider } from "../providers/category.provider";
-import { CartPaymentProvider } from "../providers";
+import type { CategoryProvider } from "../providers/category.provider";
+import type { CartPaymentProvider } from "../providers";
 
 export interface Client {
     product: ProductProvider,

package/core/src/decorators/reactionary.decorator.ts

@@ -1,16 +1,88 @@
-export function Reactionary(options: unknown): MethodDecorator {
+import type { BaseProvider } from '../providers';
+import { getTracer, SpanKind } from '@reactionary/otel';
+
+/**
+ * The options associated with annotating a provider function and marking
+ * it as a reactionary entrypoint to be called
+ */
+export class ReactionaryDecoratorOptions {
+  /**
+   * Whether or not the query is eligible for caching. Queries that depend
+   * heavily on personalization, for example, are likely to be a poor fit
+   * for caching.
+   */
+  public cache = false;
+
+  /**
+   * Whether or not the cache entry should be variable based on the locale
+   * of the context in which it is querried.
+   */
+  public localeDependentCaching = false;
+
+  /**
+   * Whether or not the cache entry should be variable based on the currency
+   * of the context in which it is querried.
+   */
+  public currencyDependentCaching = false;
+
+  /**
+   * The number of seconds which a cache entry should be considered valid for the
+   * given query.
+   */
+  public cacheTimeToLiveInSeconds = 60;
+
+};
+
+/**
+ * Decorator for provider functions to provide functionality such as caching, tracing and type-checked
+ * assertion through Zod. It should only be used with publically accessible queries or mutations on
+ * providers.
+ */
+export function Reactionary(options: Partial<ReactionaryDecoratorOptions>) {
   return function (
-    target: any,
+    target: BaseProvider,
     propertyKey: string | symbol,
     descriptor: PropertyDescriptor
   ): PropertyDescriptor {
     const original = descriptor.value;
-    
-    descriptor.value = function (...args: any[]) {
-      console.log('calling through reactionary decoration!');
-      return original.apply(this, args);
+    const scope = `${target.constructor.name}.${propertyKey.toString()}`;
+    const configuration = { ...new ReactionaryDecoratorOptions(), ...options };
+
+    if (!original) {
+      throw new Error(
+        '@Reactionary decorator may only be applied to methods on classes extending BaseProvider.'
+      );
+    }
+
+    descriptor.value = async function (this: BaseProvider, ...args: any[]) {
+      const tracer = getTracer();
+
+      return tracer.startActiveSpan(
+        propertyKey.toString(),
+        { kind: SpanKind.SERVER },
+        async (span) => {
+          const cacheKey = this.generateCacheKeyForQuery(scope, args[0]);
+
+          const fromCache = await this.cache.get(cacheKey, this.schema);
+          let result = fromCache;
+
+          if (!result) {
+            result = await original.apply(this, args);
+
+            const dependencyIds = this.generateDependencyIdsForModel(result);
+
+            this.cache.put(cacheKey, result, {
+              ttlSeconds: configuration.cacheTimeToLiveInSeconds,
+              dependencyIds: dependencyIds
+            });
+          }
+
+          span.end();
+          return this.assert(result as any);
+        }
+      );
     };
-    
+
     return descriptor;
   };
-}
+}

package/core/src/index.ts

@@ -1,6 +1,6 @@
 export * from './cache/cache.interface';
-export * from './cache/cache-evaluation.interface';
 export * from './cache/redis-cache';
+export * from './cache/memory-cache';
 export * from './cache/noop-cache';
 
 export * from './client/client';
@@ -16,3 +16,4 @@ export * from './schemas/session.schema';
 export * from './schemas/models/';
 export * from './schemas/mutations/';
 export * from './schemas/queries';
+export * from './initialization';

package/{examples/node/src/test-utils.ts → core/src/initialization.ts}

@@ -1,10 +1,8 @@
-import { Session } from '@reactionary/core';
+import type { RequestContext } from "./schemas/session.schema";
 
-
-
-export function createAnonymousTestSession(): Session {
+export function createInitialRequestContext(): RequestContext {
   return {
-    id: 'test-session-id',
+    id: '',
     identity: {
       type: 'Anonymous',
       meta: {
@@ -15,19 +13,31 @@ export function createAnonymousTestSession(): Session {
       token: undefined,
       issued: new Date(),
       expiry: new Date(new Date().getTime() + 3600 * 1000),
-      logonId: "",
-      createdAt: "",
-      updatedAt: "",
+      logonId: '',
+      createdAt: '',
+      updatedAt: '',
       keyring: [],
-      currentService: undefined
+      currentService: undefined,
     },
     languageContext: {
       locale: 'en-US',
       currencyCode: 'USD',
-      countryCode: 'US',
     },
     storeIdentifier: {
       key: 'the-good-store',
     },
+    taxJurisdiction: {
+      countryCode: 'US',
+      stateCode: '',
+      countyCode: '',
+      cityCode: '',
+    },
+    session: {},
+
+    correlationId: '',
+    isBot: false,
+    clientIp: '',
+    userAgent: '',
+    referrer: '',
   };
 }

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

@@ -1,4 +1,4 @@
-import { AnalyticsEvent } from '../schemas/models/analytics.model';
+import type { AnalyticsEvent } from '../schemas/models/analytics.model';
 import { BaseProvider } from './base.provider';
 
 export abstract class AnalyticsProvider<

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

@@ -1,22 +1,22 @@
-import { z } from 'zod';
-import { BaseModel, createPaginatedResponseSchema } from '../schemas/models/base.model';
-import { Cache } from '../cache/cache.interface';
-import { Session } from '../schemas/session.schema';
-import { IdentifierType } from '../schemas/models/identifiers.model';
+import type { z } from 'zod';
+import type {
+  BaseModel} from '../schemas/models/base.model';
+import {
+  createPaginatedResponseSchema,
+} from '../schemas/models/base.model';
+import type { Cache } from '../cache/cache.interface';
+import type { RequestContext, Session } from '../schemas/session.schema';
+import type { IdentifierType } from '../schemas/models/identifiers.model';
+import { hasher } from "node-object-hash";
 
 /**
  * Base capability provider, responsible for mutations (changes) and queries (fetches)
  * for a given business object domain.
  */
-export abstract class BaseProvider<
-  T extends BaseModel = BaseModel
-> {
+export abstract class BaseProvider<T extends BaseModel = BaseModel> {
   protected cache: Cache;
 
-  constructor(
-    public readonly schema: z.ZodType<T>,
-    cache: Cache
-  ) {
+  constructor(public readonly schema: z.ZodType<T>, cache: Cache) {
     this.cache = cache;
   }
 
@@ -39,37 +39,73 @@ export abstract class BaseProvider<
    * Handler for parsing a response from a remote provider and converting it
    * into the typed domain model.
    */
-  protected parseSingle(_body: unknown, session: Session): T {
+  protected parseSingle(_body: unknown, reqCtx: RequestContext): T {
     const model = this.newModel();
 
     return this.assert(model);
   }
 
 
-  protected parsePaginatedResult(_body: unknown, session: Session): z.infer<ReturnType<typeof createPaginatedResponseSchema<typeof this.schema>>> {
+  protected parsePaginatedResult(_body: unknown, reqCtx: RequestContext): z.infer<ReturnType<typeof createPaginatedResponseSchema<typeof this.schema>>> {
     return createPaginatedResponseSchema(this.schema).parse({});
   }
+  
+  public generateDependencyIdsForModel(model: unknown): Array<string> {
+    // TODO: Messy because we can't guarantee that a model has an identifier (type-wise)
+   const identifier = (model as any)?.identifier;
 
-  protected generateCacheKeyPaginatedResult(resultSetName: string, res:  ReturnType<typeof this.parsePaginatedResult>, session: Session): string {
+   if (!identifier) {
+    return [];
+   }
+
+   const h = hasher({ sort: true, coerce: false });
+   const hash = h.hash(identifier);
+
+   return [hash];
+  }
+
+  protected generateCacheKeyForQuery(scope: string, query: object): string {
+    const h = hasher({ sort: true, coerce: false });
+
+    const queryHash = h.hash(query);
+
+    // TODO: This really should include the internationalization parts as well (locale, currency, etc), or at least provide the option
+    // for specifying in the decorator whether they do (eg categories don't really seem to depend on currency...)
+
+    return `${scope}:${queryHash}`;
+  }
+
+  protected generateCacheKeyPaginatedResult(
+    resultSetName: string,
+    res: ReturnType<typeof this.parsePaginatedResult>,
+    reqCtx: RequestContext
+  ): string {
     const type = this.getResourceName();
-    const langPart = session.languageContext.locale;
-    const currencyPart = session.languageContext.currencyCode || 'default';
-    const storePart = session.storeIdentifier?.key || 'default';
+    const langPart = reqCtx.languageContext.locale;
+    const currencyPart = reqCtx.languageContext.currencyCode || 'default';
+    const storePart = reqCtx.storeIdentifier?.key || 'default';
     return `${type}-${resultSetName}-paginated|pageNumber:${res.pageNumber}|pageSize:${res.pageSize}|store:${storePart}|lang:${langPart}|currency:${currencyPart}`;
   }
 
-
-  protected generateCacheKeySingle(identifier: IdentifierType, session: Session): string {
+  protected generateCacheKeySingle(
+    identifier: IdentifierType,
+    reqCtx: RequestContext
+  ): string {
     const type = this.getResourceName();
-    const idPart = Object.entries(identifier).map(([k, v]) => `${k}:${(v as any).key}`).join('#');
-    const langPart = session.languageContext.locale;
-    const currencyPart = session.languageContext.currencyCode || 'default';
-    const storePart = session.storeIdentifier?.key || 'default';
+
+    const idPart = Object.entries(identifier)
+      .map(([k, v]) => `${k}:${v}`)
+      .join('#');
+
+    const langPart = reqCtx.languageContext.locale;
+    const currencyPart = reqCtx.languageContext.currencyCode || 'default';
+    const storePart = reqCtx.storeIdentifier?.key || 'default';
+
     return `${type}-${idPart}|store:${storePart}|lang:${langPart}|currency:${currencyPart}`;
   }
 
   /**
    * Returns the abstract resource name provided by the remote system.
    */
-  protected abstract getResourceName(): string ;
+  protected abstract getResourceName(): string;
 }

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

@@ -1,6 +1,7 @@
-import { CartPaymentInstruction } from '../schemas/models/payment.model';
-import { CartPaymentMutationAddPayment, CartPaymentMutationCancelPayment } from '../schemas/mutations/cart-payment.mutation';
-import { CartPaymentQueryByCart } from '../schemas/queries/cart-payment.query';
+import type { CartPaymentInstruction } from '../schemas/models/payment.model';
+import type { CartPaymentMutationAddPayment, CartPaymentMutationCancelPayment } from '../schemas/mutations/cart-payment.mutation';
+import type { CartPaymentQueryByCart } from '../schemas/queries/cart-payment.query';
+import type { RequestContext} from '../schemas/session.schema';
 import { Session } from '../schemas/session.schema';
 import { BaseProvider } from './base.provider';
 
@@ -20,7 +21,7 @@ export abstract class CartPaymentProvider<
    * @param cartIdentifier
    * @param session
    */
-  public abstract getByCartIdentifier(payload: CartPaymentQueryByCart, session: Session): Promise<T[]>;
+  public abstract getByCartIdentifier(payload: CartPaymentQueryByCart, reqCtx: RequestContext): Promise<T[]>;
 
 
   /**
@@ -33,7 +34,7 @@ export abstract class CartPaymentProvider<
    * @param payload
    * @param session
    */
-  public abstract initiatePaymentForCart(payload: CartPaymentMutationAddPayment, session: Session): Promise<T>;
+  public abstract initiatePaymentForCart(payload: CartPaymentMutationAddPayment, reqCtx: RequestContext): Promise<T>;
 
 
 
@@ -48,7 +49,7 @@ export abstract class CartPaymentProvider<
    * @param session
    * @returns
    */
-  public abstract cancelPaymentInstruction(payload: CartPaymentMutationCancelPayment, session: Session): Promise<T>;
+  public abstract cancelPaymentInstruction(payload: CartPaymentMutationCancelPayment, reqCtx: RequestContext): Promise<T>;
 
   protected override getResourceName(): string {
     return 'cart-payment-instruction';