opinionated-machine 10.0.0 → 10.2.0

package/dist/lib/testing/sseSessionSpyFactory.js

@@ -0,0 +1,100 @@
+import { SSESessionSpy } from "../sse/SSESessionSpy.js";
+const isThenable = (value) => typeof value?.then === 'function';
+/**
+ * Run a route's own lifecycle hook, then notify the spy — even if the hook fails.
+ *
+ * The spy is an observer of the connection, not a participant in it: a hook that
+ * throws is a failure of the app under test, and swallowing the connection event
+ * on top of it would surface as an unrelated `waitForConnection` timeout much
+ * later. The hook's own failure is propagated to the route builder unchanged.
+ *
+ * The spy is notified *after* the hook, mirroring `AbstractSSEController`, so a
+ * hook that enriches the session does so before any waiter observes it.
+ */
+function runHookThenNotify(hook, notify) {
+    let result;
+    try {
+        result = hook();
+    }
+    catch (error) {
+        notify();
+        throw error;
+    }
+    if (isThenable(result)) {
+        return result.then(() => notify(), (error) => {
+            notify();
+            throw error;
+        });
+    }
+    notify();
+}
+/**
+ * Create a standalone connection spy plus the route hooks that drive it.
+ *
+ * `AbstractSSEController` exposes a spy of its own via `connectionSpy` (gated on
+ * `{ enableConnectionSpy: true }`). Routes built with `buildApiRoute` have no
+ * such controller, so this factory drives a spy from the route's `onConnect` /
+ * `onClose` hooks instead. That removes the race between `connect()` returning
+ * (HTTP headers received) and the server-side handler finishing its connection
+ * registration.
+ *
+ * **The hooks have to be passed to the `buildApiRoute()` call that builds the
+ * route.** The route builder captures them when it constructs the handler, so
+ * attaching them to an already-built `RouteOptions` object has no effect. A
+ * route owned by production code therefore has to accept SSE route options (or
+ * the hooks themselves) as a parameter for a test to be able to spy on it.
+ *
+ * **Only useful for sessions that outlive the handler** — `keepAlive` sessions.
+ * An `autoClose` route closes its session as the handler returns, before the
+ * test can claim it, so `awaitServerConnection` on such a route races and
+ * usually times out. Omit `awaitServerConnection` there and assert on the
+ * events the client received instead.
+ *
+ * The spy observes `@lokalise/fastify-api-contracts` sessions by default, which
+ * is what `buildApiRoute` hands to its hooks. Pass this package's `SSESession`
+ * as the type argument when wiring it to `buildFastifyRoute` instead.
+ *
+ * @example
+ * ```typescript
+ * const { spy, routeOptions } = createSSESessionSpy()
+ *
+ * // in the app-under-test's route registration
+ * app.route(buildApiRoute(contract, handler, { ...routeOptions }))
+ *
+ * // in the test
+ * const { client, serverConnection } = await SSEHttpClient.connect(baseUrl, path, {
+ *   awaitServerConnection: { spy },
+ * })
+ * // serverConnection is registered server-side and ready to use
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Route with lifecycle hooks of its own: compose instead of replacing them
+ * const { spy, withSpy } = createSSESessionSpy()
+ *
+ * app.route(buildApiRoute(contract, handler, withSpy(productionRouteOptions)))
+ * ```
+ */
+export function createSSESessionSpy() {
+    const spy = new SSESessionSpy();
+    // `TOptions extends object` rather than `extends SSESessionSpyHooks`: with an
+    // all-optional constraint, TypeScript falls back to the constraint itself for
+    // an argument that declares no hooks, which would drop every other route
+    // option from the result type. Hook compatibility is enforced by the
+    // intersection in the parameter position instead.
+    const withSpy = (options) => {
+        const { onConnect, onClose, ...passThrough } = options ?? {};
+        return {
+            ...passThrough,
+            onConnect: (connection) => runHookThenNotify(() => onConnect?.(connection), () => spy.addConnection(connection)),
+            onClose: (connection, initiator) => runHookThenNotify(() => onClose?.(connection, initiator), () => spy.addDisconnection(connection.id)),
+        };
+    };
+    return {
+        spy,
+        routeOptions: withSpy(),
+        withSpy,
+    };
+}
+//# sourceMappingURL=sseSessionSpyFactory.js.map

package/dist/lib/testing/sseSessionSpyFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseSessionSpyFactory.js","sourceRoot":"","sources":["../../../lib/testing/sseSessionSpyFactory.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwB,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAiE7E,MAAM,UAAU,GAAG,CAAC,KAAc,EAA6B,EAAE,CAC/D,OAAQ,KAAwC,EAAE,IAAI,KAAK,UAAU,CAAA;AAEvE;;;;;;;;;;GAUG;AACH,SAAS,iBAAiB,CACxB,IAAgC,EAChC,MAAkB;IAElB,IAAI,MAA4B,CAAA;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,EAAE,CAAA;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAA;QACR,MAAM,KAAK,CAAA;IACb,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC,IAAI,CAChB,GAAG,EAAE,CAAC,MAAM,EAAE,EACd,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,EAAE,CAAA;YACR,MAAM,KAAK,CAAA;QACb,CAAC,CACF,CAAA;IACH,CAAC;IAED,MAAM,EAAE,CAAA;AACV,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,UAAU,mBAAmB;IAGjC,MAAM,GAAG,GAAG,IAAI,aAAa,EAAY,CAAA;IAEzC,8EAA8E;IAC9E,8EAA8E;IAC9E,yEAAyE;IACzE,qEAAqE;IACrE,kDAAkD;IAClD,MAAM,OAAO,GAAG,CACd,OAAiD,EAC8B,EAAE;QACjF,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,GAC1C,OAAO,IAAK,EAA8C,CAAA;QAE5D,OAAO;YACL,GAAI,WAAuD;YAC3D,SAAS,EAAE,CAAC,UAAU,EAAE,EAAE,CACxB,iBAAiB,CACf,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,EAC7B,GAAG,EAAE,CAAC,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,CACpC;YACH,OAAO,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,CACjC,iBAAiB,CACf,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,SAAS,CAAC,EACtC,GAAG,EAAE,CAAC,GAAG,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC,CAC1C;SACJ,CAAA;IACH,CAAC,CAAA;IAED,OAAO;QACL,GAAG;QACH,YAAY,EAAE,OAAO,EAAE;QACvB,OAAO;KACR,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opinionated-machine",
-  "version": "10.0.0",
+  "version": "10.2.0",
   "description": "Very opinionated DI framework for fastify, built on top of awilix ",
   "type": "module",
   "license": "MIT",