opinionated-machine 8.0.0 → 10.0.0

package/dist/lib/routes/sseResponseSchema.js

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+/**
+ * Shape of the error bodies Fastify and the SSE route builders emit themselves, rather than
+ * the handler: `FST_ERR_VALIDATION` when a request fails schema validation, whatever an
+ * application-level `setErrorHandler` returns, and the `{ statusCode, error, message }`
+ * envelope the builders send when a handler throws before streaming starts.
+ *
+ * A declared status schema is unioned with this so those bodies stay serializable. Without it
+ * Fastify serializes them against the handler's schema, fails, and turns a declared 400 or 404
+ * into a 500 `FST_ERR_FAILED_ERROR_SERIALIZATION`. Loose so a custom error handler's extra
+ * fields survive; `statusCode` and `message` are what keeps it from matching handler bodies.
+ * `error` and `code` are listed even though loose mode would carry them anyway, because
+ * Fastify defines them as non-enumerable properties that key enumeration would skip.
+ */
+const frameworkErrorSchema = z.looseObject({
+    statusCode: z.number(),
+    message: z.string(),
+    error: z.string().optional(),
+    code: z.string().optional(),
+});
+/**
+ * Combine alternative body schemas for one status.
+ *
+ * A single schema is returned as-is rather than wrapped, so a status with only one possible
+ * body does not pick up a pointless `anyOf` in the generated spec.
+ *
+ * @returns The combined schema, or `undefined` when there is nothing to describe
+ */
+function unionOf(schemas) {
+    const [first, ...rest] = schemas;
+    if (!first) {
+        return undefined;
+    }
+    return rest.length === 0 ? first : z.union(schemas);
+}
+/**
+ * Describe an SSE stream as the union of its event envelopes, following the OpenAPI 3.x
+ * convention for `text/event-stream`: one object schema per event type (`{ id?, event, data,
+ * retry? }`), discriminated on the `event` name so the contract's event payloads show up in
+ * the generated spec as a `oneOf` of envelopes with a `const` event name.
+ *
+ * Mirrors what `@lokalise/fastify-api-contracts` produces for an `sseBody()` response, so
+ * legacy SSE / dual-mode contracts and `ApiContract` ones document the same way.
+ *
+ * @returns The event envelope schema, or `undefined` when the contract declares no events
+ */
+export function buildSseEventSchema(serverSentEventSchemas) {
+    const eventSchemas = Object.entries(serverSentEventSchemas).map(([eventName, dataSchema]) => z.object({
+        id: z.string().optional(),
+        event: z.literal(eventName),
+        data: dataSchema,
+        retry: z.int().optional(),
+    }));
+    const [firstEventSchema, ...restEventSchemas] = eventSchemas;
+    if (!firstEventSchema) {
+        return undefined;
+    }
+    return restEventSchemas.length === 0
+        ? firstEventSchema
+        : z.discriminatedUnion('event', [firstEventSchema, ...restEventSchemas]);
+}
+/**
+ * Build the JSON schema for one declared status code.
+ *
+ * A status's schema has to accept every body the runtime can put out at that status,
+ * because Fastify serializes against it and rejects anything that does not match:
+ *
+ * - 2xx on a dual-mode contract: `handleSyncMode` validates the sync body against
+ *   `successResponseBodySchema` while `processSSEHandlerResult` validates `sse.respond()`
+ *   against the contract's schema for that status, so both shapes are possible.
+ * - Non-2xx: the handler's declared body, or a framework error envelope.
+ */
+function buildStatusSchema(statusCode, declaredSchema, syncSuccessSchema) {
+    const isSuccessStatus = statusCode >= 200 && statusCode < 300;
+    if (isSuccessStatus) {
+        return unionOf([syncSuccessSchema, declaredSchema].filter((schema) => schema !== undefined));
+    }
+    return declaredSchema && z.union([declaredSchema, frameworkErrorSchema]);
+}
+/**
+ * Build the `schema.response` map for an SSE or dual-mode route from its contract.
+ *
+ * The 200 entry uses Fastify's per-media-type form so a single status can describe both the
+ * event stream and the JSON body: `text/event-stream` carries the event envelopes, and
+ * `application/json` carries the sync body (dual-mode), the body the contract declares for
+ * 200 (an SSE route that answers `sse.respond(200, ...)` before streaming starts), or both.
+ *
+ * Populating this drives both the OpenAPI spec and Fastify's serializer, so a status code the
+ * contract declares is now serialized against its schema instead of plain `JSON.stringify`.
+ *
+ * @param serverSentEventSchemas - Contract's event name to payload schema map
+ * @param responseBodySchemasByStatusCode - Contract's per-status response schemas, if any
+ * @param syncSuccessSchema - Dual-mode sync 2xx body schema; omit for SSE-only contracts
+ */
+export function buildSseResponseSchemas(serverSentEventSchemas, responseBodySchemasByStatusCode, syncSuccessSchema) {
+    const { 200: declaredOkSchema, ...otherStatusSchemas } = responseBodySchemasByStatusCode ?? {};
+    const jsonOkSchema = buildStatusSchema(200, declaredOkSchema, syncSuccessSchema);
+    const eventSchema = buildSseEventSchema(serverSentEventSchemas);
+    const okContent = {
+        ...(eventSchema && { 'text/event-stream': { schema: eventSchema } }),
+        ...(jsonOkSchema && { 'application/json': { schema: jsonOkSchema } }),
+    };
+    const responseSchemas = {};
+    if (Object.keys(okContent).length > 0) {
+        responseSchemas[200] = { content: okContent };
+    }
+    for (const [statusCode, declaredSchema] of Object.entries(otherStatusSchemas)) {
+        const schema = buildStatusSchema(Number(statusCode), declaredSchema, syncSuccessSchema);
+        if (schema) {
+            responseSchemas[statusCode] = schema;
+        }
+    }
+    return responseSchemas;
+}
+//# sourceMappingURL=sseResponseSchema.js.map

package/dist/lib/routes/sseResponseSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseResponseSchema.js","sourceRoot":"","sources":["../../../lib/routes/sseResponseSchema.ts"],"names":[],"mappings":"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"}

package/dist/lib/sse/AbstractSSEController.d.ts

@@ -23,7 +23,7 @@ export type { AllContractEventNames, AllContractEvents, ExtractEventSchema, SSEC
  * ```typescript
  * class NotificationsSSEController extends AbstractSSEController<typeof contracts> {
  *   public static contracts = {
- *     notifications: buildSseContract({ ... }),
+ *     notifications: buildSseContract({ visibility: 'public', ... }),
  *   } as const
  *
  *   public buildSSERoutes() {

package/dist/lib/sse/AbstractSSEController.js

@@ -15,7 +15,7 @@ export { SSESessionSpy } from "./SSESessionSpy.js";
  * ```typescript
  * class NotificationsSSEController extends AbstractSSEController<typeof contracts> {
  *   public static contracts = {
- *     notifications: buildSseContract({ ... }),
+ *     notifications: buildSseContract({ visibility: 'public', ... }),
  *   } as const
  *
  *   public buildSSERoutes() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opinionated-machine",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "description": "Very opinionated DI framework for fastify, built on top of awilix ",
   "type": "module",
   "license": "MIT",
@@ -27,8 +27,8 @@
     "ts-deepmerge": "^8.0.0"
   },
   "peerDependencies": {
-    "@lokalise/api-contracts": ">=7.0.0",
-    "@lokalise/fastify-api-contracts": ">=6.0.0",
+    "@lokalise/api-contracts": ">=8.0.0",
+    "@lokalise/fastify-api-contracts": ">=7.0.0",
     "@lokalise/node-core": ">=14.7.4",
     "awilix": ">=13.0.0",
     "awilix-manager": ">=6.0.0",
@@ -39,9 +39,9 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
     "@changesets/cli": "^3.0.0",
-    "@lokalise/api-contracts": "^7.0.0",
+    "@lokalise/api-contracts": "^8.0.0",
     "@lokalise/biome-config": "^3.1.1",
-    "@lokalise/fastify-api-contracts": "^6.0.0",
+    "@lokalise/fastify-api-contracts": "^7.0.0",
     "@lokalise/node-core": "^14.7.4",
     "@lokalise/tsconfig": "^3.1.0",
     "@types/node": "^22.19.7",