@nest-yalc-2/api-strategy 1.3.3

package/README.md

@@ -0,0 +1,40 @@
+# @nest-yalc-2/api-strategy
+
+Transport strategy helpers for keeping application code stable while the
+underlying call path changes.
+
+Use this package to code against HTTP call or event interfaces while selecting
+local Nest calls, remote HTTP calls, emitted events, fallback chains, shadow
+calls, or conditional strategies through providers.
+
+## Installation
+
+```bash
+npm install @nest-yalc-2/api-strategy
+```
+
+## Main Exports
+
+- `NestLocalCallStrategy` for in-process Nest/Fastify calls.
+- `NestHttpCallStrategy` and `HttpAbstractCallStrategy` for remote HTTP calls.
+- `NestLocalEventStrategy` and `RabbitMqEventStrategy` for event emission.
+- `FallbackCallStrategy`, `ShadowCallStrategy`, and conditional/composite
+  strategies for staged migrations and resilience.
+- `ContextCallServiceFactory`, `ContextEventServiceFactory`, and strategy
+  selector providers for Nest DI wiring.
+
+## Example
+
+```ts
+import { NestHttpCallStrategy } from '@nest-yalc-2/api-strategy';
+
+const usersApi = new NestHttpCallStrategy(httpService, UserDto, baseUrl);
+const users = await usersApi.get('/users');
+```
+
+## Documentation
+
+- API Strategy guide:
+  https://github.com/Nek97/nestjs-yalc/blob/dev/docs/api-strategy.md
+- API Strategy and EventManager patterns:
+  https://github.com/Nek97/nestjs-yalc/blob/dev/docs/api-strategy-event-manager-patterns.md

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nest-yalc-2/api-strategy",
+  "version": "1.3.3",
+  "type": "module",
+  "description": "",
+  "exports": {
+    ".": "./src/index.js",
+    "./*.js": "./src/*.js",
+    "./*": "./src/*"
+  },
+  "author": "",
+  "license": "MIT",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "tslib": "^2.6.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nek97/nestjs-yalc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nek97/nestjs-yalc/issues"
+  },
+  "homepage": "https://github.com/Nek97/nestjs-yalc#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/call-strategy-wrappers.spec.ts

@@ -0,0 +1,217 @@
+import { jest, describe, expect, it } from "@jest/globals";
+import type { IApiCallStrategy } from "../context-call.interface.js";
+import { ConditionalCallStrategy } from "../strategies/conditional-call.strategy.js";
+import { FallbackCallStrategy } from "../strategies/fallback-call.strategy.js";
+import { ShadowCallStrategy } from "../strategies/shadow-call.strategy.js";
+
+function callStrategy(overrides: Partial<IApiCallStrategy> = {}) {
+  return {
+    call: jest.fn(async () => ({ data: "call" })),
+    get: jest.fn(async () => ({ data: "get" })),
+    post: jest.fn(async () => ({ data: "post" })),
+    ...overrides,
+  } satisfies IApiCallStrategy;
+}
+
+describe("ConditionalCallStrategy", () => {
+  it("delegates calls when enabled", async () => {
+    const target = callStrategy();
+    const strategy = new ConditionalCallStrategy(target, {
+      enabled: () => true,
+    });
+
+    await expect(strategy.call("/items")).resolves.toEqual({ data: "call" });
+    await expect(strategy.get("/items")).resolves.toEqual({ data: "get" });
+    await expect(strategy.post("/items")).resolves.toEqual({ data: "post" });
+  });
+
+  it("delegates calls when no condition is configured", async () => {
+    const strategy = new ConditionalCallStrategy(callStrategy());
+
+    await expect(strategy.call("/items")).resolves.toEqual({ data: "call" });
+  });
+
+  it("returns a disabled response when disabled", async () => {
+    const target = callStrategy();
+    const strategy = new ConditionalCallStrategy(target, {
+      enabled: false,
+      disabledResponse: { data: "disabled" },
+    });
+
+    await expect(strategy.call("/items")).resolves.toEqual({
+      data: "disabled",
+    });
+    expect(target.call).not.toHaveBeenCalled();
+  });
+
+  it("throws the default disabled error", async () => {
+    const strategy = new ConditionalCallStrategy(callStrategy(), {
+      enabled: false,
+    });
+
+    await expect(strategy.get("/items")).rejects.toThrow("disabled");
+  });
+
+  it("throws a custom disabled error", async () => {
+    const strategy = new ConditionalCallStrategy(callStrategy(), {
+      enabled: false,
+      disabledError: () => new Error("custom disabled"),
+    });
+
+    await expect(strategy.post("/items")).rejects.toThrow("custom disabled");
+  });
+
+  it("throws a custom disabled error instance", async () => {
+    const strategy = new ConditionalCallStrategy(callStrategy(), {
+      enabled: false,
+      disabledError: new Error("disabled instance"),
+    });
+
+    await expect(strategy.call("/items")).rejects.toThrow("disabled instance");
+  });
+});
+
+describe("FallbackCallStrategy", () => {
+  it("requires at least one strategy", () => {
+    expect(() => new FallbackCallStrategy([])).toThrow("at least one");
+  });
+
+  it("falls back to the next strategy after a failure", async () => {
+    const first = callStrategy({
+      call: jest.fn(async () => {
+        throw new Error("primary failed");
+      }),
+    });
+    const second = callStrategy();
+    const strategy = new FallbackCallStrategy([first, second]);
+
+    await expect(strategy.call("/items")).resolves.toEqual({ data: "call" });
+    expect(first.call).toHaveBeenCalled();
+    expect(second.call).toHaveBeenCalled();
+  });
+
+  it("stops fallback when the predicate rejects it", async () => {
+    const error = new Error("do not retry");
+    const strategy = new FallbackCallStrategy(
+      [
+        callStrategy({
+          get: jest.fn(async () => {
+            throw error;
+          }),
+        }),
+        callStrategy(),
+      ],
+      {
+        shouldFallback: () => false,
+      }
+    );
+
+    await expect(strategy.get("/items")).rejects.toThrow(error);
+  });
+
+  it("throws the last error after all strategies fail", async () => {
+    const strategy = new FallbackCallStrategy([
+      callStrategy({
+        post: jest.fn(async () => {
+          throw new Error("first failed");
+        }),
+      }),
+      callStrategy({
+        post: jest.fn(async () => {
+          throw new Error("last failed");
+        }),
+      }),
+    ]);
+
+    await expect(strategy.post("/items")).rejects.toThrow("last failed");
+  });
+});
+
+describe("ShadowCallStrategy", () => {
+  it("requires at least one shadow strategy", () => {
+    expect(() => new ShadowCallStrategy(callStrategy(), [])).toThrow(
+      "at least one"
+    );
+  });
+
+  it("returns the primary response and triggers shadows", async () => {
+    const primary = callStrategy();
+    const shadow = callStrategy();
+    const strategy = new ShadowCallStrategy(primary, [shadow]);
+
+    await expect(strategy.call("/items")).resolves.toEqual({ data: "call" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(primary.call).toHaveBeenCalled();
+    expect(shadow.call).toHaveBeenCalled();
+  });
+
+  it("ignores fire-and-forget shadow failures", async () => {
+    const strategy = new ShadowCallStrategy(callStrategy(), [
+      callStrategy({
+        call: jest.fn(async () => {
+          throw new Error("shadow failed");
+        }),
+      }),
+    ]);
+
+    await expect(strategy.call("/items")).resolves.toEqual({ data: "call" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  it("throws shadow failures when configured to await and throw", async () => {
+    const strategy = new ShadowCallStrategy(
+      callStrategy(),
+      [
+        callStrategy({
+          get: jest.fn(async () => {
+            throw new Error("shadow failed");
+          }),
+        }),
+      ],
+      {
+        awaitShadows: true,
+        shadowErrorMode: "throw",
+      }
+    );
+
+    await expect(strategy.get("/items")).rejects.toThrow("shadow failed");
+  });
+
+  it("awaits and ignores shadow failures when configured", async () => {
+    const strategy = new ShadowCallStrategy(
+      callStrategy(),
+      [
+        callStrategy({
+          post: jest.fn(async () => {
+            throw new Error("shadow failed");
+          }),
+        }),
+      ],
+      {
+        awaitShadows: true,
+        shadowErrorMode: "ignore",
+      }
+    );
+
+    await expect(strategy.post("/items")).resolves.toEqual({ data: "post" });
+  });
+
+  it("awaits shadows automatically when throw mode is configured", async () => {
+    const strategy = new ShadowCallStrategy(
+      callStrategy(),
+      [
+        callStrategy({
+          call: jest.fn(async () => {
+            throw new Error("shadow failed");
+          }),
+        }),
+      ],
+      {
+        shadowErrorMode: "throw",
+      }
+    );
+
+    await expect(strategy.call("/items")).rejects.toThrow("shadow failed");
+  });
+});

package/src/__tests__/context-call.service.spec.ts

@@ -0,0 +1,52 @@
+import {
+  expect,
+  jest,
+  describe,
+  it,
+  beforeEach,
+  beforeAll,
+  afterAll,
+  afterEach,
+} from '@jest/globals';
+
+import { createMock } from '@golevelup/ts-jest';
+import { HttpAdapterHost } from '@nestjs/common';
+import { ContextCallServiceFactory } from '../context-call.service.js';
+import { NestLocalCallStrategy } from '../index.js';
+
+describe('ContextCallServiceFactory', () => {
+  let httpAdapterHost: HttpAdapterHost;
+
+  beforeEach(() => {
+    httpAdapterHost = createMock<HttpAdapterHost>();
+  });
+
+  it('should be defined', () => {
+    expect(ContextCallServiceFactory).toBeDefined();
+  });
+
+  it('should return a class', () => {
+    const ContextCallService = ContextCallServiceFactory(
+      new NestLocalCallStrategy(httpAdapterHost),
+    );
+    expect(ContextCallService).toBeDefined();
+  });
+
+  it('should return a class that can be instantiated', () => {
+    const ContextCallService = ContextCallServiceFactory(
+      new NestLocalCallStrategy(httpAdapterHost),
+    );
+    const instance = new ContextCallService();
+    expect(instance).toBeDefined();
+  });
+
+  it('should return a class that can set and get a strategy', () => {
+    const ContextCallService = ContextCallServiceFactory(
+      new NestLocalCallStrategy(httpAdapterHost),
+    );
+    const instance = new ContextCallService();
+    const strategy = new NestLocalCallStrategy(httpAdapterHost);
+    instance.setStrategy(strategy);
+    expect(instance.getStrategy()).toBe(strategy);
+  });
+});

package/src/__tests__/context-event.service.spec.ts

@@ -0,0 +1,52 @@
+import {
+  expect,
+  jest,
+  describe,
+  it,
+  beforeEach,
+  beforeAll,
+  afterAll,
+  afterEach,
+} from '@jest/globals';
+
+import { createMock } from '@golevelup/ts-jest';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { ContextEventServiceFactory } from '../context-event.service.js';
+import { NestLocalEventStrategy } from '../index.js';
+
+describe('ContextEventServiceFactory', () => {
+  let eventEmitter: EventEmitter2;
+
+  beforeEach(() => {
+    eventEmitter = createMock<EventEmitter2>();
+  });
+
+  it('should be defined', () => {
+    expect(ContextEventServiceFactory).toBeDefined();
+  });
+
+  it('should return a class', () => {
+    const ContextCallService = ContextEventServiceFactory(
+      new NestLocalEventStrategy(eventEmitter),
+    );
+    expect(ContextCallService).toBeDefined();
+  });
+
+  it('should return a class that can be instantiated', () => {
+    const ContextCallService = ContextEventServiceFactory(
+      new NestLocalEventStrategy(eventEmitter),
+    );
+    const instance = new ContextCallService();
+    expect(instance).toBeDefined();
+  });
+
+  it('should return a class that can set and get a strategy', () => {
+    const ContextCallService = ContextEventServiceFactory(
+      new NestLocalEventStrategy(eventEmitter),
+    );
+    const instance = new ContextCallService();
+    const strategy = new NestLocalEventStrategy(eventEmitter);
+    instance.setStrategy(strategy);
+    expect(instance.getStrategy()).toBe(strategy);
+  });
+});

package/src/__tests__/event-strategy-composition.spec.ts

@@ -0,0 +1,185 @@
+import { jest, describe, expect, it } from "@jest/globals";
+import type { IEventStrategy } from "../context-event.interface.js";
+import { CompositeEventStrategy } from "../strategies/composite-event.strategy.js";
+import { ConditionalEventStrategy } from "../strategies/conditional-event.strategy.js";
+
+function eventStrategy(
+  overrides: Partial<IEventStrategy<object, boolean>> & {
+    onModuleDestroy?: () => Promise<void>;
+  } = {}
+) {
+  return {
+    emit: jest.fn(() => true),
+    emitAsync: jest.fn(async () => true),
+    ...overrides,
+  } satisfies IEventStrategy<object, boolean> & {
+    onModuleDestroy?: () => Promise<void>;
+  };
+}
+
+describe("CompositeEventStrategy", () => {
+  it("requires at least one strategy", () => {
+    expect(() => new CompositeEventStrategy([])).toThrow("at least one");
+  });
+
+  it("emits to every strategy synchronously", () => {
+    const first = eventStrategy();
+    const second = eventStrategy({ emit: jest.fn(() => false) });
+    const strategy = new CompositeEventStrategy([first, second]);
+
+    const result = strategy.emit("event.name", { ok: true });
+
+    expect(result).toEqual([true, false]);
+    expect(first.emit).toHaveBeenCalledWith(
+      "event.name",
+      { ok: true },
+      undefined
+    );
+    expect(second.emit).toHaveBeenCalledWith(
+      "event.name",
+      { ok: true },
+      undefined
+    );
+  });
+
+  it("throws sync errors by default", () => {
+    const error = new Error("sync failure");
+    const strategy = new CompositeEventStrategy([
+      eventStrategy({
+        emit: jest.fn(() => {
+          throw error;
+        }),
+      }),
+    ]);
+
+    expect(() => strategy.emit("event.name", {})).toThrow(error);
+  });
+
+  it("ignores sync errors when configured", () => {
+    const strategy = new CompositeEventStrategy(
+      [
+        eventStrategy({
+          emit: jest.fn(() => {
+            throw new Error("sync failure");
+          }),
+        }),
+        eventStrategy(),
+      ],
+      { errorMode: "ignore" }
+    );
+
+    expect(strategy.emit("event.name", {})).toEqual([true]);
+  });
+
+  it("emits to every strategy asynchronously", async () => {
+    const first = eventStrategy();
+    const second = eventStrategy({ emitAsync: jest.fn(async () => false) });
+    const strategy = new CompositeEventStrategy([first, second]);
+
+    await expect(
+      strategy.emitAsync("event.name", { ok: true })
+    ).resolves.toEqual([true, false]);
+  });
+
+  it("throws async errors by default", async () => {
+    const error = new Error("async failure");
+    const strategy = new CompositeEventStrategy([
+      eventStrategy({
+        emitAsync: jest.fn(async () => {
+          throw error;
+        }),
+      }),
+    ]);
+
+    await expect(strategy.emitAsync("event.name", {})).rejects.toThrow(error);
+  });
+
+  it("ignores async errors when configured", async () => {
+    const strategy = new CompositeEventStrategy(
+      [
+        eventStrategy({
+          emitAsync: jest.fn(async () => {
+            throw new Error("async failure");
+          }),
+        }),
+        eventStrategy(),
+      ],
+      { errorMode: "ignore" }
+    );
+
+    await expect(strategy.emitAsync("event.name", {})).resolves.toEqual([true]);
+  });
+
+  it("destroys nested strategies that implement module destroy", async () => {
+    const onModuleDestroy = jest.fn(async () => undefined);
+    const strategy = new CompositeEventStrategy([
+      eventStrategy({ onModuleDestroy }),
+      eventStrategy(),
+    ]);
+
+    await strategy.onModuleDestroy();
+
+    expect(onModuleDestroy).toHaveBeenCalled();
+  });
+});
+
+describe("ConditionalEventStrategy", () => {
+  it("emits when enabled", () => {
+    const target = eventStrategy();
+    const strategy = new ConditionalEventStrategy(target, {
+      enabled: () => true,
+    });
+
+    expect(strategy.emit("event.name", {})).toBe(true);
+    expect(target.emit).toHaveBeenCalled();
+  });
+
+  it("returns the disabled result when disabled", () => {
+    const target = eventStrategy();
+    const strategy = new ConditionalEventStrategy(target, {
+      enabled: false,
+      disabledResult: false,
+    });
+
+    expect(strategy.emit("event.name", {})).toBe(false);
+    expect(target.emit).not.toHaveBeenCalled();
+  });
+
+  it("skips events rejected by the predicate", async () => {
+    const target = eventStrategy();
+    const strategy = new ConditionalEventStrategy(target, {
+      shouldEmit: () => false,
+      disabledResult: false,
+    });
+
+    await expect(strategy.emitAsync("event.name", {})).resolves.toBe(false);
+    expect(target.emitAsync).not.toHaveBeenCalled();
+  });
+
+  it("delegates async events when enabled and accepted", async () => {
+    const target = eventStrategy();
+    const strategy = new ConditionalEventStrategy(target, {
+      shouldEmit: () => true,
+    });
+
+    await expect(strategy.emitAsync("event.name", {})).resolves.toBe(true);
+    expect(target.emitAsync).toHaveBeenCalled();
+  });
+
+  it("destroys the wrapped strategy when supported", async () => {
+    const onModuleDestroy = jest.fn(async () => undefined);
+    const strategy = new ConditionalEventStrategy(
+      eventStrategy({ onModuleDestroy })
+    );
+
+    await strategy.onModuleDestroy();
+
+    expect(onModuleDestroy).toHaveBeenCalled();
+  });
+
+  it("ignores destroy when the wrapped strategy has no lifecycle hook", async () => {
+    const strategy = new ConditionalEventStrategy(eventStrategy());
+
+    await expect(strategy.onModuleDestroy()).resolves.toBeUndefined();
+  });
+});

package/src/__tests__/header-whitelist.helper.spec.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from '@jest/globals';
+
+import { filterHeaders } from '../header-whitelist.helper.js';
+
+describe('whitelistHeaders', () => {
+  it('should be defined', () => {
+    expect(filterHeaders).toBeDefined();
+  });
+
+  it('should filter headers', () => {
+    const headers = {
+      'x-header': 'x-header',
+      'x-header-2': 'x-header-2',
+      'x-header-3': 'x-header-3',
+    };
+    const whitelist = ['x-header', 'x-header-2'];
+    const filteredHeaders = filterHeaders(headers, whitelist);
+    expect(filteredHeaders).toEqual({
+      'x-header': 'x-header',
+      'x-header-2': 'x-header-2',
+    });
+  });
+
+  it('should return undefined if headers are undefined', () => {
+    const headers = undefined;
+    const whitelist = ['x-header', 'x-header-2'];
+    const filteredHeaders = filterHeaders(headers, whitelist);
+    expect(filteredHeaders).toBeUndefined();
+  });
+});

package/src/__tests__/http-abstract-call.strategy.spec.ts

@@ -0,0 +1,17 @@
+import {
+  expect,
+  jest,
+  describe,
+  it,
+  beforeEach,
+  beforeAll,
+  afterAll,
+  afterEach,
+} from '@jest/globals';
+import { HttpAbstractStrategy } from '../strategies/http-abstract-call.strategy.js';
+
+describe('HttpAbstractStrategy', () => {
+  it('should be defined', () => {
+    expect(HttpAbstractStrategy).toBeDefined();
+  });
+});