@reactionary/source 0.0.27

package/.editorconfig

@@ -0,0 +1,13 @@
+# Editor configuration, see http://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/.github/workflows/pull-request.yml

@@ -0,0 +1,37 @@
+name: pull request
+
+on:
+  pull_request:
+  merge_group:
+
+permissions:
+  actions: read
+  contents: read
+  pull-requests: read
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          filter: tree:0
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - run: pnpm dlx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="build"
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 23
+          cache: 'pnpm'
+      
+      - run: pnpm install
+      
+      - uses: nrwl/nx-set-shas@v4
+
+      - run: pnpm exec nx affected -t lint build

package/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: release
+
+on:
+  push:
+    branches:
+      main
+
+permissions:
+  actions: read
+  contents: write
+  pull-requests: read
+  id-token: write
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          filter: tree:0
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 23
+          cache: 'pnpm'
+          registry-url: https://registry.npmjs.org/
+
+      - run: pnpm install
+
+      - run: |
+          git config --global user.email "martin.rogne@solteq.com"
+          git config --global user.name "Martin Rogne"
+          pnpm exec nx release patch --yes -- --no-agents
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
+          NPM_CONFIG_PROVENANCE: false
+          NPM_CONFIG_ACCESS: public
+
+
+
+
+

package/.nvmrc

@@ -0,0 +1 @@
+v23.7.0

package/.prettierignore

@@ -0,0 +1,6 @@
+# Add files here to ignore them from prettier formatting
+/dist
+/coverage
+/.nx/cache
+/.nx/workspace-data
+.angular

package/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "singleQuote": true
+}

package/.verdaccio/config.yml

@@ -0,0 +1,28 @@
+# path to a directory with all packages
+storage: ../tmp/local-registry/storage
+
+# a list of other known repositories we can talk to
+uplinks:
+  npmjs:
+    url: https://registry.npmjs.org/
+    maxage: 60m
+
+packages:
+  '**':
+    # give all users (including non-authenticated users) full access
+    # because it is a local registry
+    access: $all
+    publish: $all
+    unpublish: $all
+
+    # if package is not available locally, proxy requests to npm registry
+    proxy: npmjs
+
+# log settings
+log:
+  type: stdout
+  format: pretty
+  level: warn
+
+publish:
+  allow_offline: true # set offline to true to allow publish offline

package/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "nrwl.angular-console",
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "firsttris.vscode-jest-runner",
+    "ms-playwright.playwright"
+  ]
+}

package/README.md

@@ -0,0 +1,39 @@
+# Reactionary
+
+Reactionary is a framework-agnostic client library for standardized data access, building upon the previous learnings from Perpendicular. It is decidedly opinionated. Compared to Perpendicular it:
+
+- it favors keeping the providers on the server in order to:
+  - keep the client bundle minimal for performance.
+  - allow for cross transactional caching.
+  - standardize observability.
+  - control access, allowing for session features like rate limiting.
+- it favors serializable, parseable domain models because it:
+  - allows for caching and state transfer.
+  - allows for extensible, typesafe data at runtime.
+
+## Contributing
+
+### Running locally
+
+The includes examples generally require `.env` to be configured with the relevant API keys. We can likely create a setup for this in Vault, for easy bootstrapping.
+
+### Pull requests
+
+For new features, branch from `main` and create a pull request towards `main` upon feature completion. Please observe the following guidelines:
+
+- Preserve a linear history. This means rebasing on `main`, rather than merging. PR's containing merge commits should be considered unmergeable.
+- Observe [https://www.conventionalcommits.org/en/v1.0.0/#summary][conventional commit message guidelines] for the rebased pull request commits.
+- Ensure that the PR is linked to an issue.
+
+## Glossary
+
+The following is a short list of commonly used terms and phrases, to keep guessing to a minimum.
+
+- *Provider:* a backend service providing an API that can be consumed. HCL or Commercetools would be examples of ecom providers, while Algolia would be an example of a search provider.
+- *Capability:* a capability (or more fully, a business capability) is a discrete area of functionality that may be provided to the consuming party. An example would be *Cart*, providing a domain model and a set of discrete operations that can be performed on it, like adding a product or removing a product.
+- *Gateway:* a serverside process encapsulating a set of capabilities. This could be a trpc router, or it could be react server. The purpose here is to ensure that all of the dependencies and environmental configuration stays on the server, rather than the client.
+- *Client:* the client facade to the gateway. In trpc this is would be the trpc client. It can be bundled into client-side rendering code.
+- *Observability:* means of providing insights into the workings of the system, in a production context. This is distinct from analytics in that it provides information on the workings of the *system* rather than the workings of the *user*. OTEL (opentelemetry) provides a standardized specification for this in the form of *traces* and *metrics*.
+- *Fake:* an implementation that provides a functional response, but with in a limited capacity. A fake provider may, for example, provide *Cart* functionality, but only store it in-memory and throw it away on a whim. As such it can be used for prototyping, but never for a production scenario.
+- *Product Analytics:* structured analytics that relate to how the the product is being used.
+- *Microsite:* an application of a limited scope. It may focus solely on this limited functionality, making it ideal for demonstration purposes.

package/core/README.md

@@ -0,0 +1,11 @@
+# core
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build core` to build the library.
+
+## Running unit tests
+
+Run `nx test core` to execute the unit tests via [Vitest](https://vitest.dev/).

package/core/eslint.config.mjs

@@ -0,0 +1,23 @@
+import baseConfig from '../eslint.config.mjs';
+
+export default [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: [
+            '{projectRoot}/eslint.config.{js,cjs,mjs}',
+            '{projectRoot}/esbuild.config.{js,ts,mjs,mts}',
+            '{projectRoot}/vite.config.{js,ts,mjs,mts}',
+          ],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: await import('jsonc-eslint-parser'),
+    },
+  },
+];

package/core/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@reactionary/core",
+  "version": "0.0.1",
+  "dependencies": {
+    "zod": "4.0.0-beta.20250430T185432",
+    "@upstash/redis": "^1.34.9"
+  }
+}

package/core/project.json

@@ -0,0 +1,33 @@
+{
+  "name": "core",
+  "$schema": "../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "core/src",
+  "projectType": "library",
+  "release": {
+    "version": {
+      "currentVersionResolver": "git-tag",
+      "fallbackCurrentVersionResolver": "disk",
+      "preserveLocalDependencyProtocols": false,
+      "manifestRootsToUpdate": ["dist/{projectRoot}"]
+    }
+  },
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/esbuild:esbuild",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/core",
+        "main": "core/src/index.ts",
+        "tsConfig": "core/tsconfig.lib.json",
+        "assets": ["core/*.md"],
+        "format": ["esm"]
+      }
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/{projectRoot}"
+      }
+    }
+  }
+}

package/core/src/cache/caching-strategy.ts

@@ -0,0 +1,25 @@
+import { BaseQuery } from "../schemas/queries/base.query";
+import { InventoryQuery } from "../schemas/queries/inventory.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 class BaseCachingStrategy implements CachingStrategy {
+    public get(query: BaseQuery, session: Session): CachingStrategyEvaluation {
+        const q = query as InventoryQuery;
+
+        return {
+            key: q.sku,
+            cacheDurationInSeconds: 300,
+            canCache: true
+        }
+    }
+}

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

@@ -0,0 +1,41 @@
+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 z from 'zod';
+
+export class RedisCache {
+  protected strategy: CachingStrategy;
+  protected redis: Redis;
+
+  constructor(strategy: CachingStrategy) {
+    this.strategy = strategy;
+    this.redis = Redis.fromEnv();
+  }
+
+  public async get<T extends BaseModel>(query: BaseQuery, session: Session, schema: z.ZodType<T>): Promise<T | null> {
+    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;
+      }
+    }
+    
+    return result;
+  }
+
+  public put(query: BaseQuery, session: Session, value: unknown): void {
+    const cacheInformation = this.strategy.get(query, session);
+
+    if (cacheInformation.canCache && cacheInformation.key) {
+      this.redis.set(cacheInformation.key, value, { ex: cacheInformation.cacheDurationInSeconds });
+    }
+  }
+}

package/core/src/client/client.ts

@@ -0,0 +1,39 @@
+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";
+
+export interface Client {
+    product: ProductProvider,
+    search: SearchProvider,
+    identity: IdentityProvider,
+    cache: Cache,
+    cart: CartProvider,
+    analytics: Array<AnalyticsProvider>,
+    price: PriceProvider,
+    inventory: InventoryProvider
+}
+
+export function buildClient<T extends Partial<Client>>(providers: Array<T>): Required<T> {
+    let client = { } as Required<T>;
+
+    const mergedAnalytics = [];
+
+    for (const provider of providers) {
+        client = {
+            ...client,
+            ...provider
+        }
+
+        if (provider.analytics) {
+            mergedAnalytics.push(...provider.analytics);
+        }
+    }
+
+    client.analytics = mergedAnalytics;
+
+    return client satisfies T;
+}

package/core/src/index.ts

@@ -0,0 +1,42 @@
+export * from './cache/caching-strategy';
+export * from './cache/redis-cache';
+
+export * from './client/client';
+
+export * from './providers/analytics.provider';
+export * from './providers/base.provider';
+export * from './providers/cart.provider';
+export * from './providers/identity.provider';
+export * from './providers/inventory.provider';
+export * from './providers/price.provider';
+export * from './providers/product.provider';
+export * from './providers/search.provider';
+
+export * from './schemas/capabilities.schema';
+export * from './schemas/session.schema';
+
+export * from './schemas/models/base.model';
+export * from './schemas/models/cart.model';
+export * from './schemas/models/currency.model';
+export * from './schemas/models/identifiers.model';
+export * from './schemas/models/identity.model';
+export * from './schemas/models/inventory.model';
+export * from './schemas/models/price.model';
+export * from './schemas/models/product.model';
+export * from './schemas/models/search.model';
+
+export * from './schemas/mutations/base.mutation';
+export * from './schemas/mutations/cart.mutation';
+export * from './schemas/mutations/identity.mutation';
+export * from './schemas/mutations/inventory.mutation';
+export * from './schemas/mutations/price.mutation';
+export * from './schemas/mutations/product.mutation';
+export * from './schemas/mutations/search.mutation';
+
+export * from './schemas/queries/base.query';
+export * from './schemas/queries/cart.query';
+export * from './schemas/queries/identity.query';
+export * from './schemas/queries/inventory.query';
+export * from './schemas/queries/price.query';
+export * from './schemas/queries/product.query';
+export * from './schemas/queries/search.query';

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

@@ -0,0 +1,10 @@
+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> {}

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

@@ -0,0 +1,75 @@
+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';
+
+/**
+ * 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
+> {
+  constructor(public readonly schema: z.ZodType<T>, public readonly querySchema: z.ZodType<Q, Q>, public readonly mutationSchema: z.ZodType<M, M>) {}
+
+  /**
+   * 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({});
+  }
+
+  /**
+   * 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.
+   */
+  public async query(queries: Q[], session: Session): Promise<T[]> {
+    const results = await this.fetch(queries, session);
+
+    for (const result of results) {
+      this.assert(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * 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> {
+    const result = await this.process(mutations, session);
+
+    this.assert(result);
+
+    return result;
+  }
+
+  /**
+   * 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

@@ -0,0 +1,10 @@
+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";
+
+export abstract class CartProvider<
+  T extends Cart = Cart,
+  Q extends CartQuery = CartQuery,
+  M extends CartMutation = CartMutation
+> extends BaseProvider<T, Q, M> {}

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

@@ -0,0 +1,10 @@
+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";
+
+export abstract class IdentityProvider<
+  T extends Identity = Identity,
+  Q extends IdentityQuery = IdentityQuery,
+  M extends IdentityMutation = IdentityMutation
+> extends BaseProvider<T, Q, M> {}

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

@@ -0,0 +1,11 @@
+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 { 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> {}

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

@@ -0,0 +1,10 @@
+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';
+
+export abstract class PriceProvider<
+  T extends Price = Price,
+  Q extends PriceQuery = PriceQuery,
+  M extends PriceMutation = PriceMutation
+> extends BaseProvider<T, Q, M> {}

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

@@ -0,0 +1,11 @@
+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';
+
+export abstract class ProductProvider<
+  T extends Product = Product,
+  Q extends ProductQuery = ProductQuery,
+  M extends ProductMutation = ProductMutation
+> extends BaseProvider<T, Q, M> {
+}

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

@@ -0,0 +1,12 @@
+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';
+
+export abstract class SearchProvider<
+  T extends SearchResult = SearchResult,
+  Q extends SearchQuery = SearchQuery,
+  M extends SearchMutation = SearchMutation
+> extends BaseProvider<T, Q, M> {}
+
+

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

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+export const CapabilitiesSchema = z.looseInterface({
+    product: z.boolean(),
+    search: z.boolean(),
+    analytics: z.boolean(),
+    identity: z.boolean(),
+    cart: z.boolean(),
+    inventory: z.boolean(),
+    price: z.boolean()
+});
+
+export type Capabilities = z.infer<typeof CapabilitiesSchema>;

package/core/src/schemas/models/analytics.model.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+import { BaseModelSchema } from './base.model';
+
+export const AnalyticsEventSchema = BaseModelSchema.extend({
+});
+
+export type AnalyticsEvent = z.infer<typeof AnalyticsEventSchema>;

package/core/src/schemas/models/base.model.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+export const CacheInformationSchema = z.looseInterface({
+    hit: z.boolean().default(false),
+    key: z.string().default('')
+})
+
+export const MetaSchema = z.looseInterface({
+    cache: CacheInformationSchema.default(() => CacheInformationSchema.parse({})),
+    placeholder: z.boolean().default(false).describe('Whether or not the entity exists in a remote system, or is a default placeholder.')
+});
+
+export const BaseModelSchema = z.looseInterface({
+    meta: MetaSchema.default(() => MetaSchema.parse({}))
+});
+
+export type CacheInformation = z.infer<typeof CacheInformationSchema>;
+export type Meta = z.infer<typeof MetaSchema>;
+export type BaseModel = z.infer<typeof BaseModelSchema>;

package/core/src/schemas/models/cart.model.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { CartIdentifierSchema, CartItemIdentifierSchema, ProductIdentifierSchema } from '../models/identifiers.model';
+import { BaseModelSchema } from './base.model';
+
+export const CartItemSchema = z.looseInterface({
+    identifier: CartItemIdentifierSchema.default(() => CartItemIdentifierSchema.parse({})),
+    product: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})),
+    quantity: z.number().default(0)
+});
+
+export const CartSchema = BaseModelSchema.extend({
+    identifier: CartIdentifierSchema.default(() => CartIdentifierSchema.parse({})),
+    items: z.array(CartItemSchema).default(() => [])
+});
+
+export type CartItem = z.infer<typeof CartItemSchema>;
+export type Cart = z.infer<typeof CartSchema>;