@reactionary/source 0.0.52 → 0.2.16

package/core/src/client/client.ts

@@ -1,18 +1,18 @@
 import type { AnalyticsProvider } from "../providers/analytics.provider.js";
 import type { ProductProvider } from "../providers/product.provider.js";
-import type { SearchProvider } from "../providers/search.provider.js";
+import type { ProductSearchProvider } from "../providers/product-search.provider.js";
 import type { IdentityProvider } from '../providers/identity.provider.js';
 import type { CartProvider } from "../providers/cart.provider.js";
 import type { PriceProvider } from "../providers/price.provider.js";
 import type { InventoryProvider } from "../providers/inventory.provider.js";
 import type { Cache } from "../cache/cache.interface.js";
-import { RedisCache } from "../cache/redis-cache.js";
 import type { CategoryProvider } from "../providers/category.provider.js";
-import type { CheckoutProvider } from "../providers/index.js";
+import type { CheckoutProvider, OrderProvider, ProfileProvider, StoreProvider } from "../providers/index.js";
+import type { OrderSearchProvider } from "../providers/order-search.provider.js";
 
 export interface Client {
     product: ProductProvider,
-    search: SearchProvider,
+    productSearch: ProductSearchProvider,
     identity: IdentityProvider,
     cache: Cache,
     cart: CartProvider,
@@ -20,48 +20,10 @@ export interface Client {
     analytics: Array<AnalyticsProvider>,
     price: PriceProvider,
     inventory: InventoryProvider,
-    category: CategoryProvider
+    category: CategoryProvider,
+    profile: ProfileProvider,
+    store: StoreProvider,
+    order: OrderProvider,
+    orderSearch: OrderSearchProvider,
 }
 
-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 factory of providerFactories) {
-        const provider = factory(sharedCache);
-        client = {
-            ...client,
-            ...provider
-        }
-
-        if (provider.analytics) {
-            mergedAnalytics.push(...provider.analytics);
-        }
-    }
-
-    client.analytics = mergedAnalytics;
-
-    // Add cache to complete the client
-    const completeClient = {
-        ...client,
-        cache: sharedCache
-    } as Required<T>;
-
-    return completeClient;
-}
-
-// Convenience function to create a shared cache instance
-export function createCache(): Cache {
-    return new RedisCache();
-}

package/core/src/client/index.ts

@@ -0,0 +1,2 @@
+export * from './client-builder.js';
+export * from './client.js';

package/core/src/decorators/index.ts

@@ -0,0 +1 @@
+export * from './reactionary.decorator.js';

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

@@ -1,24 +1,20 @@
+import type { Tracer } from '@opentelemetry/api';
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { z } from 'zod';
 import type { BaseProvider } from '../providers/index.js';
-import type { 
-  Tracer, } from '@opentelemetry/api';
-import { 
-  trace, 
-  SpanKind
-} from '@opentelemetry/api';
+import { getReactionaryMeter } from '../metrics/metrics.js';
+import { error, success, type Result } from '../schemas/result.js';
+import type {
+  InvalidInputError,
+  InvalidOutputError,
+  GenericError,
+} from '../schemas/index.js';
 
 const TRACER_NAME = '@reactionary';
 const TRACER_VERSION = '0.0.1';
 
-let globalTracer: Tracer | null = null;
-
 export function getTracer(): Tracer {
-  if (!globalTracer) {
-    // Simply get the tracer from the API
-    // If the SDK is not initialized by the host application,
-    // this will return a ProxyTracer that produces NonRecordingSpans
-    globalTracer = trace.getTracer(TRACER_NAME, TRACER_VERSION);
-  }
-  return globalTracer;
+  return trace.getTracer(TRACER_NAME, TRACER_VERSION);
 }
 
 /**
@@ -51,7 +47,16 @@ export class ReactionaryDecoratorOptions {
    */
   public cacheTimeToLiveInSeconds = 60;
 
-};
+  /**
+   * The schema for the input (query or mutation) type, for validation purposes
+   */
+  public inputSchema: z.ZodType = z.unknown();
+
+  /**
+   * The schema for the primary output type, for validation purposes
+   */
+  public outputSchema: z.ZodType = z.unknown();
+}
 
 /**
  * Decorator for provider functions to provide functionality such as caching, tracing and type-checked
@@ -67,6 +72,13 @@ export function Reactionary(options: Partial<ReactionaryDecoratorOptions>) {
     const original = descriptor.value;
     const scope = `${target.constructor.name}.${propertyKey.toString()}`;
     const configuration = { ...new ReactionaryDecoratorOptions(), ...options };
+    const meter = getReactionaryMeter();
+    const attributes = {
+      'labels.scope': scope,
+    };
+    const startTime = performance.now();
+    let status = 'ok';
+    let cacheStatus = 'miss';
 
     if (!original) {
       throw new Error(
@@ -75,34 +87,191 @@ export function Reactionary(options: Partial<ReactionaryDecoratorOptions>) {
     }
 
     descriptor.value = async function (this: BaseProvider, ...args: any[]) {
-      const tracer = getTracer();
+      return traceSpan(scope, async () => {
+        meter.requestInProgress.add(1, attributes);
+        try {
+          const input = validateInput(args[0], configuration.inputSchema);
 
-      return tracer.startActiveSpan(
-        propertyKey.toString(),
-        { kind: SpanKind.SERVER },
-        async (span) => {
-          const cacheKey = this.generateCacheKeyForQuery(scope, args[0]);
+          if (!input.success) {
+            return input;
+          }
 
-          const fromCache = await this.cache.get(cacheKey, this.schema);
-          let result = fromCache;
+          const cacheKey = this.generateCacheKeyForQuery(scope, input.value);
+          let fromCache = null;
 
-          if (!result) {
-            result = await original.apply(this, args);
+          if (options.cache) {
+            fromCache = await this.cache.get(
+              cacheKey,
+              options.outputSchema as any
+            );
+          }
 
-            const dependencyIds = this.generateDependencyIdsForModel(result);
+          let result;
+          if (!fromCache) {
+            result = await original.apply(this, [input.value]);
 
-            this.cache.put(cacheKey, result, {
-              ttlSeconds: configuration.cacheTimeToLiveInSeconds,
-              dependencyIds: dependencyIds
-            });
+            const r = result as Result<unknown>;
+
+            if (r.success) {
+              const dependencyIds = this.generateDependencyIdsForModel(r.value);
+
+              if (options.cache) {
+                this.cache.put(cacheKey, r.value, {
+                  ttlSeconds: configuration.cacheTimeToLiveInSeconds,
+                  dependencyIds: dependencyIds,
+                });
+              }
+            }
+          } else {
+            result = success(fromCache);
+            cacheStatus = 'hit';
           }
 
-          span.end();
-          return this.assert(result as any);
+          // TODO: Update the below after fixing the method signature.
+          // That is, making the decorator only applicable to methods with
+          // a signature returning a result.
+          const validatedResult = validateOutput(
+            result as any,
+            configuration.outputSchema
+          );
+
+          if (validatedResult.success) {
+            validatedResult.meta.cache.hit = !!fromCache;
+            validatedResult.meta.cache.key = cacheKey;
+          }
+
+          return validatedResult;
+        } catch (err) {
+          status = 'error';
+          trace
+            .getActiveSpan()
+            ?.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: errorToString(err),
+            });
+
+          // TODO: Decide if we want to redact the error message, since the client should never rely
+          // on the internals. On the other hand, it is REALLY convenient to have it during development...
+          const result = error<GenericError>({
+            type: 'Generic',
+            message: errorToString(err),
+          });
+
+          return result;
+        } finally {
+          const duration = performance.now() - startTime;
+          const finalAttributes = {
+            ...attributes,
+            'labels.status': status,
+            'labels.cache_status': cacheStatus,
+          };
+          meter.requestInProgress.add(-1, finalAttributes);
+          meter.requests.add(1, finalAttributes);
+          meter.requestDuration.record(duration, finalAttributes);
         }
-      );
+      });
     };
 
     return descriptor;
   };
 }
+
+/**
+ * Utility function to handle input validation.
+ */
+export function validateInput<T>(
+  input: T,
+  schema: z.ZodType | undefined
+): Result<T> {
+  if (!schema) {
+    return success(input);
+  }
+
+  let validated: Result<T> = success(input);
+  const parse = schema.safeParse(input);
+
+  if (!parse.success) {
+    validated = error<InvalidInputError>({
+      type: 'InvalidInput',
+      error: parse.error,
+    });
+  }
+
+  return validated;
+}
+
+/**
+ * Utility function to handle output validation.
+ */
+export function validateOutput(
+  output: Result<unknown>,
+  schema: z.ZodType | undefined
+): Result<unknown> {
+  if (!schema) {
+    return output;
+  }
+
+  let validated = output;
+  if (output.success) {
+    const parse = schema.safeParse(output.value);
+
+    if (!parse.success) {
+      validated = error<InvalidOutputError>({
+        type: 'InvalidOutput',
+        error: parse.error,
+      });
+    }
+  }
+
+  return validated;
+}
+
+/**
+ * Utility function to wrap entry / exit into decorated functions in a
+ * traced span for OTEL handling.
+ */
+export async function traceSpan<T>(
+  name: string,
+  fn: () => Promise<T> | T
+): Promise<T> {
+  const tracer: Tracer = getTracer();
+
+  return tracer.startActiveSpan(name, async (span) => {
+    try {
+      return await fn();
+    } catch (err: unknown) {
+      if (err instanceof Error) {
+        span.recordException(err);
+        span.setStatus({ code: 2, message: err.message });
+      } else {
+        span.recordException({ message: String(err) });
+        span.setStatus({ code: 2, message: String(err) });
+      }
+
+      // TODO: Instead of re-throwing here, we might actually want to return a distinct error type
+      // but I am unsure if that is really a task for the decorator (outside of input / output parsing)
+      // it could perhaps always handle an unknown exception as a generic error type, for consolidation
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
+
+/**
+ * Utility function for converting a caught error to a plain
+ * string for reporting back.
+ */
+export function errorToString(err: unknown): string {
+  if (err instanceof Error) {
+    return err.stack ?? err.message;
+  }
+  if (typeof err === 'string') {
+    return err;
+  }
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}

package/core/src/index.ts

@@ -1,19 +1,6 @@
-export * from './cache/cache.interface.js';
-export * from './cache/redis-cache.js';
-export * from './cache/memory-cache.js';
-export * from './cache/noop-cache.js';
-
-export * from './client/client.js';
-export * from './client/client-builder.js';
-
-export * from './decorators/reactionary.decorator.js';
-
-export * from './providers/index.js'
-
-export * from './schemas/capabilities.schema.js';
-export * from './schemas/session.schema.js';
-
-export * from './schemas/models/index.js';
-export * from './schemas/mutations/index.js';
-export * from './schemas/queries/index.js';
-export * from './initialization.js';
+export * from './cache/index.js';
+export * from './client/index.js';
+export * from './decorators/index.js';
+export * from './providers/index.js';
+export * from './schemas/index.js';
+export * from './initialization.js';

package/core/src/initialization.ts

@@ -2,25 +2,8 @@ import type { RequestContext } from "./schemas/session.schema.js";
 
 export function createInitialRequestContext(): RequestContext {
   return {
-    id: '',
-    identity: {
-      type: 'Anonymous',
-      meta: {
-        cache: { hit: false, key: '' },
-        placeholder: false,
-      },
-      id: { userId: 'anonymous' },
-      token: undefined,
-      issued: new Date(),
-      expiry: new Date(new Date().getTime() + 3600 * 1000),
-      logonId: '',
-      createdAt: '',
-      updatedAt: '',
-      keyring: [],
-      currentService: undefined,
-    },
     languageContext: {
-      locale: 'en-US',
+      locale: 'en',
       currencyCode: 'USD',
     },
     storeIdentifier: {

package/core/src/metrics/metrics.ts

@@ -0,0 +1,67 @@
+import type { Counter, Gauge } from '@opentelemetry/api';
+import { metrics, type Histogram, type UpDownCounter } from '@opentelemetry/api';
+
+const METRICS_NAME = '@reactionary';
+const TRACER_VERSION = '0.0.1';
+
+export interface ReactionaryCacheMetrics {
+  items: Gauge;
+  hits: Counter;
+  misses: Counter;
+}
+
+let globalCacheMetrics: ReactionaryCacheMetrics | null = null;
+export function getReactionaryCacheMeter(): ReactionaryCacheMetrics {
+  if (!globalCacheMetrics) {
+    const meter = metrics.getMeter(METRICS_NAME, TRACER_VERSION);
+    globalCacheMetrics = {
+      items: meter.createGauge('reactionary_cache_items', {
+        description: 'Tracks the number of items in the cache',
+      }),
+      hits: meter.createCounter('reactionary_cache_hits', {
+        description: 'Counts the number of cache hits',
+      }),
+      misses: meter.createCounter('reactionary_cache_misses', {
+        description: 'Counts the number of cache misses',
+      }),
+    };
+  }
+  return globalCacheMetrics;
+}
+
+
+export interface ReactionaryMetrics {
+  requests: Counter;
+  requestDuration: Histogram;
+  requestInProgress: UpDownCounter;
+}
+
+let globalMetrics: ReactionaryMetrics | null = null;
+
+export function getReactionaryMeter(): ReactionaryMetrics {
+  if (!globalMetrics) {
+    const meter = metrics.getMeter(METRICS_NAME, TRACER_VERSION);
+    globalMetrics = {
+      requests: meter.createCounter('reactionary_provider_requests', {
+        description:
+          'Counts the number of requests made to provider queries and mutations',
+      }),
+      requestDuration: meter.createHistogram(
+        'reactionary_provider_request_duration',
+        {
+          description:
+            'Records the duration of provider query and mutation requests',
+          unit: 'ms',
+        }
+      ),
+      requestInProgress: meter.createUpDownCounter(
+        'reactionary_provider_requests_in_progress',
+        {
+          description:
+            'Tracks the number of in-progress requests to provider queries and mutations',
+        }
+      ),
+    };
+  }
+  return globalMetrics;
+}

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

@@ -1,11 +1,6 @@
-import type { AnalyticsEvent } from '../schemas/models/analytics.model.js';
 import { BaseProvider } from './base.provider.js';
 
-export abstract class AnalyticsProvider<
-  T extends AnalyticsEvent = AnalyticsEvent
-> extends BaseProvider<T> {
-
-
+export abstract class AnalyticsProvider extends BaseProvider {
   protected override getResourceName(): string {
     return 'analytics';
   }

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

@@ -1,53 +1,18 @@
-import type { z } from 'zod';
-import type {
-  BaseModel} from '../schemas/models/base.model.js';
-import {
-  createPaginatedResponseSchema,
-} from '../schemas/models/base.model.js';
 import type { Cache } from '../cache/cache.interface.js';
-import type { RequestContext, Session } from '../schemas/session.schema.js';
-import type { IdentifierType } from '../schemas/models/identifiers.model.js';
+import { type RequestContext } from '../schemas/session.schema.js';
 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 {
   protected cache: Cache;
+  protected context: RequestContext;
 
-  constructor(public readonly schema: z.ZodType<T>, cache: Cache) {
+  constructor(cache: Cache, context: RequestContext) {
     this.cache = cache;
-  }
-
-  /**
-   * Validates that the final domain model constructed by the provider
-   * fulfills the schema as defined. This will throw an exception.
-   */
-  protected assert(value: T) {
-    return this.schema.parse(value);
-  }
-
-  /**
-   * Creates a new model entity based on the schema defaults.
-   */
-  protected newModel(): T {
-    return this.schema.parse({});
-  }
-
-  /**
-   * Handler for parsing a response from a remote provider and converting it
-   * into the typed domain model.
-   */
-  protected parseSingle(_body: unknown, reqCtx: RequestContext): T {
-    const model = this.newModel();
-
-    return this.assert(model);
-  }
-
-
-  protected parsePaginatedResult(_body: unknown, reqCtx: RequestContext): z.infer<ReturnType<typeof createPaginatedResponseSchema<typeof this.schema>>> {
-    return createPaginatedResponseSchema(this.schema).parse({});
+    this.context = context;
   }
   
   public generateDependencyIdsForModel(model: unknown): Array<string> {
@@ -75,35 +40,6 @@ export abstract class BaseProvider<T extends BaseModel = BaseModel> {
     return `${scope}:${queryHash}`;
   }
 
-  protected generateCacheKeyPaginatedResult(
-    resultSetName: string,
-    res: ReturnType<typeof this.parsePaginatedResult>,
-    reqCtx: RequestContext
-  ): string {
-    const type = this.getResourceName();
-    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,
-    reqCtx: RequestContext
-  ): string {
-    const type = this.getResourceName();
-
-    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.
    */