@reactionary/source 0.0.52 → 0.2.16

package/core/src/schemas/queries/checkout.query.ts

@@ -1,22 +1,20 @@
 import type { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
 import { CheckoutIdentifierSchema } from '../models/identifiers.model.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const CheckoutQueryByIdSchema = BaseQuerySchema.extend({
-    identifier: CheckoutIdentifierSchema.required()
+    identifier: CheckoutIdentifierSchema
 });
 
-
 export const CheckoutQueryForAvailableShippingMethodsSchema = BaseQuerySchema.extend({
-    checkout: CheckoutIdentifierSchema.required()
+    checkout: CheckoutIdentifierSchema
 });
 
 export const CheckoutQueryForAvailablePaymentMethodsSchema = BaseQuerySchema.extend({
-    checkout: CheckoutIdentifierSchema.required()
+    checkout: CheckoutIdentifierSchema
 });
 
-
-
-export type CheckoutQueryForAvailableShippingMethods = z.infer<typeof CheckoutQueryForAvailableShippingMethodsSchema>;
-export type CheckoutQueryForAvailablePaymentMethods = z.infer<typeof CheckoutQueryForAvailablePaymentMethodsSchema>;
-export type CheckoutQueryById = z.infer<typeof CheckoutQueryByIdSchema>;
+export type CheckoutQueryForAvailableShippingMethods = InferType<typeof CheckoutQueryForAvailableShippingMethodsSchema>;
+export type CheckoutQueryForAvailablePaymentMethods = InferType<typeof CheckoutQueryForAvailablePaymentMethodsSchema>;
+export type CheckoutQueryById = InferType<typeof CheckoutQueryByIdSchema>;

package/core/src/schemas/queries/identity.query.ts

@@ -1,8 +1,9 @@
 import type { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const IdentityQuerySelfSchema = BaseQuerySchema.extend({
 
 });
 
-export type IdentityQuerySelf = z.infer<typeof IdentityQuerySelfSchema>;
+export type IdentityQuerySelf = InferType<typeof IdentityQuerySelfSchema>;

package/core/src/schemas/queries/index.ts

@@ -7,7 +7,8 @@ export * from './inventory.query.js';
 export * from './price.query.js';
 export * from './product.query.js';
 export * from './profile.query.js';
-export * from './search.query.js';
+export * from './product-search.query.js';
 export * from './store.query.js';
 export * from './order.query.js';
 export * from './checkout.query.js';
+export * from './order-search.query.js'

package/core/src/schemas/queries/inventory.query.ts

@@ -1,11 +1,11 @@
 import type { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
-import { FulfillmentCenterIdentifierSchema, ProductIdentifierSchema } from '../models/identifiers.model.js';
+import { FulfillmentCenterIdentifierSchema, ProductVariantIdentifierSchema } from '../models/identifiers.model.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const InventoryQueryBySKUSchema = BaseQuerySchema.extend({
-    sku: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})).nonoptional(),
-    fulfilmentCenter: FulfillmentCenterIdentifierSchema.default(() => FulfillmentCenterIdentifierSchema.parse({})).nonoptional()
+    variant: ProductVariantIdentifierSchema.describe('The unique identifier for the product variant (SKU).'),
+    fulfilmentCenter: FulfillmentCenterIdentifierSchema
 });
 
-//export type InventoryQuery = z.infer<typeof InventoryQuerySchema>;
-export type InventoryQueryBySKU = z.infer<typeof InventoryQueryBySKUSchema>;
+export type InventoryQueryBySKU = InferType<typeof InventoryQueryBySKUSchema>;

package/core/src/schemas/queries/order-search.query.ts

@@ -0,0 +1,10 @@
+import type { InferType } from "../../zod-utils.js";
+import { OrderSearchIdentifierSchema } from "../models/identifiers.model.js";
+import { BaseQuerySchema } from "./base.query.js";
+
+export const OrderSearchQueryByTermSchema = BaseQuerySchema.extend({
+    search: OrderSearchIdentifierSchema
+});
+
+
+export type OrderSearchQueryByTerm = InferType<typeof OrderSearchQueryByTermSchema>;

package/core/src/schemas/queries/order.query.ts

@@ -1,9 +1,10 @@
 import type { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
 import { OrderIdentifierSchema } from '../models/identifiers.model.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const OrderQueryByIdSchema = BaseQuerySchema.extend({
-    order: OrderIdentifierSchema.required()
+    order: OrderIdentifierSchema
 });
 
-export type OrderQueryById = z.infer<typeof OrderQueryByIdSchema>;
+export type OrderQueryById = InferType<typeof OrderQueryByIdSchema>;

package/core/src/schemas/queries/price.query.ts

@@ -1,9 +1,15 @@
 import type { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
-import { SKUIdentifierSchema } from '../models/identifiers.model.js';
+import { ProductVariantIdentifierSchema } from '../models/identifiers.model.js';
+import type { InferType } from '../../zod-utils.js';
 
-export const PriceQueryBySkuSchema = BaseQuerySchema.extend({
-    sku: SKUIdentifierSchema.required(),
+export const ListPriceQuerySchema = BaseQuerySchema.extend({
+    variant: ProductVariantIdentifierSchema
 });
 
-export type PriceQueryBySku = z.infer<typeof PriceQueryBySkuSchema>;
+export const CustomerPriceQuerySchema = BaseQuerySchema.extend({
+    variant: ProductVariantIdentifierSchema
+});
+
+export type ListPriceQuery = InferType<typeof ListPriceQuerySchema>;
+export type CustomerPriceQuery = InferType<typeof CustomerPriceQuerySchema>;

package/core/src/schemas/queries/product-search.query.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { InferType } from '../../zod-utils.js';
+import { CategorySchema } from '../models/category.model.js';
+import { ProductSearchIdentifierSchema } from '../models/identifiers.model.js';
+import { BaseQuerySchema } from './base.query.js';
+
+export const ProductSearchQueryByTermSchema = BaseQuerySchema.extend({
+    search: ProductSearchIdentifierSchema
+});
+
+export const ProductSearchQueryCreateNavigationFilterSchema = z.looseObject({
+    categoryPath: z.array(CategorySchema).describe('An array representing the breadcrumb path to a category, from root to the specific category.')
+}).describe('Payload to create a category navigation filter from a breadcrumb path.');
+
+export type ProductSearchQueryByTerm = InferType<typeof ProductSearchQueryByTermSchema>;
+export type ProductSearchQueryCreateNavigationFilter = InferType<typeof ProductSearchQueryCreateNavigationFilterSchema>;

package/core/src/schemas/queries/product.query.ts

@@ -1,20 +1,27 @@
 import { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
-import { SKUIdentifierSchema } from '../models/index.js';
+import { PaginationOptionsSchema, ProductIdentifierSchema, ProductVariantIdentifierSchema } from '../models/index.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const ProductQueryBySlugSchema = BaseQuerySchema.extend({
     slug: z.string()
 });
 
 export const ProductQueryByIdSchema = BaseQuerySchema.extend({
-    id: z.string()
+    identifier: ProductIdentifierSchema
 });
 
 export const ProductQueryBySKUSchema = BaseQuerySchema.extend({
-    sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+    variant: ProductVariantIdentifierSchema,
+});
+
+export const ProductQueryVariantsSchema = BaseQuerySchema.extend({
+    parentId: ProductIdentifierSchema,
+    paginationOptions: PaginationOptionsSchema,
 });
 
 
-export type ProductQueryBySlug = z.infer<typeof ProductQueryBySlugSchema>;
-export type ProductQueryById = z.infer<typeof ProductQueryByIdSchema>;
-export type ProductQueryBySKU = z.infer<typeof ProductQueryBySKUSchema>;
+export type ProductQueryBySlug = InferType<typeof ProductQueryBySlugSchema>;
+export type ProductQueryById = InferType<typeof ProductQueryByIdSchema>;
+export type ProductQueryBySKU = InferType<typeof ProductQueryBySKUSchema>;
+export type ProductQueryVariants = InferType<typeof ProductQueryVariantsSchema>;

package/core/src/schemas/queries/profile.query.ts

@@ -1,7 +1,10 @@
 import type { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
+import type { InferType } from '../../zod-utils.js';
+import { IdentityIdentifierSchema } from '../models/identifiers.model.js';
 
-export const ProfileQuerySelfSchema = BaseQuerySchema.extend({
+export const ProfileQueryByIdSchema = BaseQuerySchema.extend({
+  identifier: IdentityIdentifierSchema,
 });
 
-export type ProfileQuerySelf = z.infer<typeof ProfileQuerySelfSchema>;
+export type ProfileQuerySelf = InferType<typeof ProfileQueryByIdSchema>;

package/core/src/schemas/queries/store.query.ts

@@ -1,11 +1,12 @@
 import { z } from 'zod';
 import { BaseQuerySchema } from './base.query.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const StoreQueryByProximitySchema = BaseQuerySchema.extend({
-    longitude: z.number().default(0),
-    latitude: z.number().default(0),
-    distance: z.number().default(0),
-    limit: z.number().default(10)
+    longitude: z.number(),
+    latitude: z.number(),
+    distance: z.number(),
+    limit: z.number(),
 });
 
-export type StoreQueryByProximity = z.infer<typeof StoreQueryByProximitySchema>;
+export type StoreQueryByProximity = InferType<typeof StoreQueryByProximitySchema>;

package/core/src/schemas/result.ts

@@ -0,0 +1,107 @@
+import { trace } from "@opentelemetry/api";
+import type { GenericError } from "./errors/generic.error.js";
+import type { InvalidInputError } from "./errors/invalid-input.error.js";
+import type { InvalidOutputError } from "./errors/invalid-output.error.js";
+
+export type Ok<T> = {
+  success: true;
+  value: T;
+  meta: {
+    trace: string;
+    cache: {
+      hit: boolean,
+      key: string
+    }
+  }
+};
+
+export type Fail<E> = {
+  success: false;
+  error: E | GenericError | InvalidInputError | InvalidOutputError;
+  meta: {
+    trace: string
+  }
+};
+
+export type Result<T, E = { type: string }> = Ok<T> | Fail<E>;
+
+/**
+ * Utility function for asserting and unwrapping the value of a success.
+ * It is an assert, so treat it as such (similar to any unwrap, assert or similar function).
+ * You are guaranteeing that this will ALWAYS succeed, and can expect a runtime error if
+ * that assertion ever fails.
+ * 
+ * This is primarily useful for cases where you KNOW that it shouldn't fail, or where failure
+ * has no known mechanism of recovery besides simply crashing.
+ */
+export function assertSuccess<T, E = Error>(
+  result: Result<T, E>
+): asserts result is Ok<T> {
+  if (!result.success) {
+    throw new Error(
+      `Expected Result.success = true, but got false. Error: ${result.error}`
+    );
+  }
+}
+
+/**
+ * Utility function for asserting an error. This is primarily useful for testing scenarios
+ * that trigger errors as part of their validation.
+ */
+export function assertError<T, E = Error>(
+  result: Result<T, E>
+): asserts result is Fail<E> {
+  if (result.success) {
+    throw new Error(`Expected failure but got success: ${result.value}`);
+  }
+}
+
+/**
+ * Utility function for unwrapping a value from a result. Internally this
+ * WILL assert success, so the caller needs to guarantee that this will
+ * always be a valid operation, or expect a thrown exception.
+ */
+export function unwrapValue<T, E = Error>(result: Result<T, E>): T {
+  assertSuccess(result);
+  return result.value;
+}
+
+/**
+ * Utility function for unwrapping an error. Primarily useful for testing.
+ */
+export function unwrapError<T, E>(
+  result: Result<T, E>
+): Fail<E>['error'] {
+  assertError(result);
+  return result.error;
+}
+
+/**
+ * Helper function for wrapping a success as an Ok<T> type
+ */
+export function success<T>(value: T): Ok<T> {
+  return {
+    success: true,
+    value,
+    meta: {
+      trace: trace.getActiveSpan()?.spanContext().traceId || '',
+      cache: {
+        hit: false,
+        key: ''
+      }
+    }
+  }
+}
+
+/**
+ * Helper function for wrapping an error as a Fail<E> type
+ */
+export function error<E>(error: E): Fail<E> {
+  return {
+    success: false,
+    error,
+    meta: {
+      trace: trace.getActiveSpan()?.spanContext().traceId || '',
+    }
+  }
+}

package/core/src/schemas/session.schema.ts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { IdentitySchema } from './models/identity.model.js';
 import { WebStoreIdentifierSchema } from './models/identifiers.model.js';
 import { CurrencySchema } from './models/currency.model.js';
 
@@ -11,7 +10,7 @@ export const LanguageContextSchema = z.looseObject( {
     currencyCode: CurrencySchema.default(() => CurrencySchema.parse({})),
 })
 
-export const SessionSchema = z.record( z.string(), z.any());
+export const SessionSchema = z.record(z.string(), z.any());
 
 export const TaxJurisdictionSchema = z.object( {
     countryCode: z.string().default('US'),
@@ -21,7 +20,6 @@ export const TaxJurisdictionSchema = z.object( {
 });
 
 export const RequestContextSchema = z.looseObject( {
-    identity: IdentitySchema.default(() => IdentitySchema.parse({})).describe('Read/Write. The identity of the current user. Caller is responsible for persisting any changes to the identity'),
     session: SessionSchema.default(() => SessionSchema.parse({})).describe('Read/Write session storage. Caller is responsible for persisting any changes. Providers will prefix own values'),
 
     languageContext: LanguageContextSchema.default(() => LanguageContextSchema.parse({})).describe('ReadOnly. The language and locale context for the current request.'),
@@ -34,11 +32,13 @@ export const RequestContextSchema = z.looseObject( {
     clientIp: z.string().default('').describe('The IP address of the client making the request, if available. Mostly for logging purposes'),
     userAgent: z.string().default('').describe('The user agent string of the client making the request, if available.'),
     referrer: z.string().default('').describe('The referrer URL, if available.'),
-
 })
 
 
 
+// Note, for this ONE type (which is effectively a dictionary), we currently don't want
+// to strip [key: string]: unknown, hence the manual zod infer over the helper.
+// Maybe there is a better solution, with a different typing for SessionSchema...
 export type Session = z.infer<typeof SessionSchema>;
 export type LanguageContext = z.infer<typeof LanguageContextSchema>;
 export type RequestContext = z.infer<typeof RequestContextSchema>;

package/core/src/test/reactionary.decorator.spec.ts

@@ -0,0 +1,249 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { BaseProvider } from '../providers/base.provider.js';
+import type { RequestContext } from '../schemas/session.schema.js';
+import type { Cache } from '../cache/cache.interface.js';
+import {
+  Reactionary,
+  type ReactionaryDecoratorOptions,
+} from '../decorators/reactionary.decorator.js';
+import { createInitialRequestContext } from '../initialization.js';
+import { z } from 'zod';
+import { success, MemoryCache, type Result } from '../index.js';
+import { assert } from 'vitest';
+import {
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { hrTimeToMilliseconds } from '@opentelemetry/core';
+
+export function createTestableProvider(
+  decoratorOptions: Partial<ReactionaryDecoratorOptions>,
+  fn?: any
+) {
+  class TestableProvider extends BaseProvider {
+    constructor(
+      public override cache: Cache,
+      public override context: RequestContext
+    ) {
+      super(cache, context);
+    }
+
+    @Reactionary({
+      inputSchema: z.undefined(),
+      outputSchema: z.string(),
+      ...decoratorOptions,
+    })
+    public async decoratedFunction(
+      ...args: unknown[]
+    ): Promise<Result<unknown>> {
+      if (fn) {
+        return await fn(args);
+      }
+
+      return success('BASE');
+    }
+
+    public override generateCacheKeyForQuery(
+      scope: string,
+      query: object
+    ): string {
+      return super.generateCacheKeyForQuery(scope, query);
+    }
+
+    public getResourceName(): string {
+      return 'TestableProvider';
+    }
+  }
+
+  const cache = new MemoryCache();
+  const context = createInitialRequestContext();
+
+  return new TestableProvider(cache, context);
+}
+
+describe('@Reactionary decorator', () => {
+  describe('Input validation', () => {
+    it('should reject invalid input with a failure', async () => {
+      const provider = createTestableProvider({
+        cache: false,
+        inputSchema: z.string(),
+      });
+
+      const result = await provider.decoratedFunction(42);
+
+      expect(result.success).toBe(false);
+    });
+
+    it('should allow valid input through with a success', async () => {
+      const provider = createTestableProvider({
+        cache: false,
+        inputSchema: z.string(),
+      });
+
+      const result = await provider.decoratedFunction('42');
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('Output validation', () => {
+    it('should reject invalid output with a failure', async () => {
+      const provider = createTestableProvider(
+        {
+          cache: false,
+          outputSchema: z.string(),
+        },
+        function () {
+          return success(42);
+        }
+      );
+
+      const result = await provider.decoratedFunction();
+
+      expect(result.success).toBe(false);
+    });
+
+    it('should allow valid output with a success', async () => {
+      const provider = createTestableProvider(
+        {
+          cache: false,
+          outputSchema: z.string(),
+        },
+        function () {
+          return success('42');
+        }
+      );
+
+      const result = await provider.decoratedFunction();
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('Error handling', () => {
+    it('will wrap errors thrown by the provider in a GenericError', async () => {
+      const provider = createTestableProvider({}, function () {
+        throw new Error('42');
+      });
+
+      const result = await provider.decoratedFunction();
+
+      if (result.success) {
+        assert.fail();
+      }
+
+      expect(result.error.type).toBe('Generic');
+    });
+  });
+
+  describe('Tracing', () => {
+    let exporter: InMemorySpanExporter;
+    let provider: NodeTracerProvider;
+
+    beforeEach(() => {
+      exporter = new InMemorySpanExporter();
+      provider = new NodeTracerProvider({
+        spanProcessors: [new SimpleSpanProcessor(exporter)],
+      });
+
+      provider.register();
+    });
+
+    afterEach(() => {
+      exporter.reset();
+      trace.disable();
+    });
+
+    it('records a timed span for entering the decorated function', async () => {
+      const provider = createTestableProvider({
+        cache: false,
+      }, async function() { 
+        await new Promise(resolve => setTimeout(resolve, 200));
+
+        return "42";
+      });
+      const result = await provider.decoratedFunction();
+      const spans = exporter.getFinishedSpans();
+
+      expect(spans.length).toBe(1);
+
+      const span = spans[0];
+      const duration = hrTimeToMilliseconds(span.duration);
+      const name = span.name;
+      const status = span.status;
+
+      console.log('unset expected: ', status);
+
+      expect(name).toBe('TestableProvider.decoratedFunction');
+      expect(duration).toBeGreaterThanOrEqual(200);
+      expect(duration).toBeLessThanOrEqual(300);
+      expect(status.code).toBe(SpanStatusCode.UNSET);
+    });
+
+    it('records exceptions as events and marks the span as an error', async () => {
+      const provider = createTestableProvider({
+        cache: false,
+      }, async function() { 
+        throw new Error('42');
+      });
+
+      const result = await provider.decoratedFunction();
+      const spans = exporter.getFinishedSpans();
+
+      expect(spans.length).toBe(1);
+
+      const span = spans[0];
+      const name = span.name;
+      const status = span.status;
+
+      expect(name).toBe('TestableProvider.decoratedFunction');
+      expect(status.code).toBe(SpanStatusCode.ERROR);
+    });
+  });
+
+  describe('Caching', () => {
+    it('should not cache repeat lookups if the decorator is set to uncached', async () => {
+      const provider = createTestableProvider({
+        cache: false,
+      });
+      const result = await provider.decoratedFunction();
+
+      if (!result.success) {
+        assert.fail();
+      }
+
+      expect(result.meta.cache.hit).toBe(false);
+
+      const secondResult = await provider.decoratedFunction();
+
+      if (!secondResult.success) {
+        assert.fail();
+      }
+
+      expect(secondResult.meta.cache.hit).toBe(false);
+    });
+
+    it('should cache repeat lookups if the decorator is set to cached', async () => {
+      const provider = createTestableProvider({
+        cache: true,
+      });
+      const result = await provider.decoratedFunction();
+
+      if (!result.success) {
+        assert.fail();
+      }
+
+      expect(result.meta.cache.hit).toBe(false);
+
+      const secondResult = await provider.decoratedFunction();
+
+      if (!secondResult.success) {
+        assert.fail();
+      }
+
+      expect(secondResult.meta.cache.hit).toBe(true);
+    });
+  });
+});

package/core/src/zod-utils.ts

@@ -0,0 +1,19 @@
+import type z from "zod";
+
+export type StripIndexSignature<T> =
+  T extends (infer U)[] ? StripIndexSignature<U>[] :
+  T extends readonly (infer U)[] ? readonly StripIndexSignature<U>[] :
+  T extends Set<infer U> ? Set<StripIndexSignature<U>> :
+  T extends Map<infer K, infer V> ? Map<StripIndexSignature<K>, StripIndexSignature<V>> :
+  T extends Promise<infer U> ? Promise<StripIndexSignature<U>> :
+  T extends object ? {
+    [K in keyof T as K extends string
+      ? string extends K
+        ? never
+        : K
+      : K
+    ]: StripIndexSignature<T[K]>
+  } :
+  T;
+
+export type InferType<T extends z.ZodTypeAny> = StripIndexSignature<z.infer<T>>;

package/core/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "extends": "../tsconfig.base.json",
   "compilerOptions": {
-    "module": "nodenext",
+    "module": "NodeNext",
     "moduleResolution": "nodenext",
     "forceConsistentCasingInFileNames": true,
     "strict": true,

package/core/tsconfig.spec.json

@@ -1,28 +1,4 @@
 {
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../dist/out-tsc",
-    "types": [
-      "vitest/globals",
-      "vitest/importMeta",
-      "vite/client",
-      "node",
-      "vitest"
-    ]
-  },
-  "include": [
-    "vite.config.ts",
-    "vite.config.mts",
-    "vitest.config.ts",
-    "vitest.config.mts",
-    "src/**/*.test.ts",
-    "src/**/*.spec.ts",
-    "src/**/*.test.tsx",
-    "src/**/*.spec.tsx",
-    "src/**/*.test.js",
-    "src/**/*.spec.js",
-    "src/**/*.test.jsx",
-    "src/**/*.spec.jsx",
-    "src/**/*.d.ts"
-  ]
+  "extends": "./tsconfig.lib.json",
+  "exclude": []
 }

package/core/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig, defineProject } from 'vitest/config';
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { resolve } from 'path';
+import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
+
+export default defineProject({
+  plugins: [nxViteTsPaths()],
+  test: {
+    root: resolve(__dirname),
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.spec.ts', 'src/**/*.test.ts']
+  },
+});