feat: Subscription class for SSE

eslint.config.js

@@ -106,6 +106,15 @@ const tsFactoryConcerns = [
       "CallExpression[callee.property.name='createTypeReferenceNode'][arguments.length=1]",
     message: "use ensureTypeNode() helper",
   },
+  {
+    selector: "Literal[value='Extract']",
+    message: "use makeExtract() helper",
+  },
+  {
+    selector:
+      "CallExpression[callee.property.name='createTypeLiteralNode'] > ArrayExpression[elements.length=1]",
+    message: "use makeOnePropObjType() helper",
+  },
 ];
 
 export default tsPlugin.config(

example/example.client.ts

@@ -445,6 +445,32 @@ export class ExpressZodAPIClient {
   }
 }
 
+export const subscribe = <
+  K extends Extract<Request, `get ${string}`>,
+  R extends Extract<PositiveResponse[K], { event: string }>,
+>(
+  request: K,
+  params: Input[K],
+) => {
+  const [path, rest] = substitute(parseRequest(request)[1], params);
+  const source = new EventSource(
+    new URL(`${path}?${new URLSearchParams(rest)}`, "https://example.com"),
+  );
+  const connection = {
+    source,
+    on: <E extends R["event"]>(
+      event: E,
+      handler: (data: Extract<R, { event: E }>["data"]) => void | Promise<void>,
+    ) => {
+      source.addEventListener(event, (msg) =>
+        handler(JSON.parse((msg as MessageEvent).data)),
+      );
+      return connection;
+    },
+  };
+  return connection;
+};
+
 // Usage example:
 /*
 export const exampleImplementation: Implementation = async (
@@ -469,4 +495,5 @@ export const exampleImplementation: Implementation = async (
 };
 const client = new ExpressZodAPIClient(exampleImplementation);
 client.provide("get /v1/user/retrieve", { id: "10" });
+client.subscribe("get /v1/events/time", {}).on("time", (time) => {});
 */

src/integration-base.ts

@@ -2,17 +2,20 @@ import ts from "typescript";
 import { ResponseVariant } from "./api-response";
 import { contentTypes } from "./content-type";
 import { Method, methods } from "./method";
+import type { makeEventSchema } from "./sse";
 import {
   accessModifiers,
   ensureTypeNode,
   f,
   makeArrowFn,
   makeConst,
   makeDeconstruction,
+  makeExtract,
   makeInterface,
   makeInterfaceProp,
   makeKeyOf,
   makeNew,
+  makeOnePropObjType,
   makeParam,
   makeParams,
   makePromise,
@@ -30,6 +33,7 @@ import {
 } from "./typescript-api";
 
 type IOKind = "input" | "response" | ResponseVariant | "encoded";
+type SSEShape = ReturnType<typeof makeEventSchema>["shape"];
 
 export abstract class IntegrationBase {
   protected paths = new Set<string>();
@@ -45,9 +49,15 @@ export abstract class IntegrationBase {
     paramsArgument: f.createIdentifier("params"),
     methodParameter: f.createIdentifier("method"),
     requestParameter: f.createIdentifier("request"),
+    eventParameter: f.createIdentifier("event"),
+    dataParameter: f.createIdentifier("data"),
+    handlerParameter: f.createIdentifier("handler"),
+    msgParameter: f.createIdentifier("msg"),
     parseRequestFn: f.createIdentifier("parseRequest"),
     substituteFn: f.createIdentifier("substitute"),
     provideMethod: f.createIdentifier("provide"),
+    subscribeFn: f.createIdentifier("subscribe"),
+    onMethod: f.createIdentifier("on"),
     implementationArgument: f.createIdentifier("implementation"),
     hasBodyConst: f.createIdentifier("hasBody"),
     undefinedValue: f.createIdentifier("undefined"),
@@ -58,6 +68,8 @@ export abstract class IntegrationBase {
     clientConst: f.createIdentifier("client"),
     contentTypeConst: f.createIdentifier("contentType"),
     isJsonConst: f.createIdentifier("isJSON"),
+    sourceConst: f.createIdentifier("source"),
+    connectionConst: f.createIdentifier("connection"),
   } satisfies Record<string, ts.Identifier>;
 
   protected interfaces: Record<IOKind, ts.Identifier> = {
@@ -294,6 +306,163 @@ export abstract class IntegrationBase {
       [this.makeProvider()],
     );
 
+  protected makeSubscribeFn = () =>
+    makeConst(
+      this.ids.subscribeFn,
+      makeArrowFn(
+        {
+          request: ensureTypeNode("K"),
+          params: f.createIndexedAccessTypeNode(
+            ensureTypeNode(this.interfaces.input),
+            ensureTypeNode("K"),
+          ),
+        },
+        f.createBlock([
+          makeConst(
+            makeDeconstruction(this.ids.pathParameter, this.ids.restConst),
+            f.createCallExpression(this.ids.substituteFn, undefined, [
+              f.createElementAccessExpression(
+                f.createCallExpression(this.ids.parseRequestFn, undefined, [
+                  this.ids.requestParameter,
+                ]),
+                f.createNumericLiteral(1),
+              ),
+              this.ids.paramsArgument,
+            ]),
+          ),
+          makeConst(
+            this.ids.sourceConst,
+            makeNew(
+              f.createIdentifier("EventSource"),
+              makeNew(
+                f.createIdentifier(URL.name),
+                makeTemplate(
+                  "",
+                  [this.ids.pathParameter, "?"],
+                  [
+                    makeNew(
+                      f.createIdentifier(URLSearchParams.name),
+                      this.ids.restConst,
+                    ),
+                  ],
+                ),
+                f.createStringLiteral(this.serverUrl),
+              ),
+            ),
+          ),
+          makeConst(
+            this.ids.connectionConst,
+            f.createObjectLiteralExpression([
+              f.createShorthandPropertyAssignment(this.ids.sourceConst),
+              f.createPropertyAssignment(
+                this.ids.onMethod,
+                makeArrowFn(
+                  {
+                    [this.ids.eventParameter.text]: ensureTypeNode("E"),
+                    [this.ids.handlerParameter.text]: f.createFunctionTypeNode(
+                      undefined,
+                      makeParams({
+                        [this.ids.dataParameter.text]:
+                          f.createIndexedAccessTypeNode(
+                            makeExtract(
+                              "R",
+                              makeOnePropObjType(
+                                propOf<SSEShape>("event"),
+                                "E",
+                              ),
+                            ),
+                            f.createLiteralTypeNode(
+                              f.createStringLiteral(propOf<SSEShape>("data")),
+                            ),
+                          ),
+                      }),
+                      f.createUnionTypeNode([
+                        f.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword),
+                        makePromise(
+                          f.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword),
+                        ),
+                      ]),
+                    ),
+                  },
+                  f.createBlock([
+                    f.createExpressionStatement(
+                      makePropCall(
+                        this.ids.sourceConst,
+                        propOf<EventSource>("addEventListener"),
+                        [
+                          this.ids.eventParameter,
+                          makeArrowFn(
+                            [this.ids.msgParameter],
+                            f.createCallExpression(
+                              this.ids.handlerParameter,
+                              undefined,
+                              [
+                                makePropCall(
+                                  f.createIdentifier(JSON[Symbol.toStringTag]),
+                                  propOf<JSON>("parse"),
+                                  [
+                                    f.createPropertyAccessExpression(
+                                      f.createParenthesizedExpression(
+                                        f.createAsExpression(
+                                          this.ids.msgParameter,
+                                          ensureTypeNode(MessageEvent.name),
+                                        ),
+                                      ),
+                                      propOf<SSEShape>("data"),
+                                    ),
+                                  ],
+                                ),
+                              ],
+                            ),
+                          ),
+                        ],
+                      ),
+                    ),
+                    f.createReturnStatement(this.ids.connectionConst),
+                  ]),
+                  {
+                    typeParams: {
+                      E: f.createIndexedAccessTypeNode(
+                        ensureTypeNode("R"),
+                        f.createLiteralTypeNode(
+                          f.createStringLiteral(propOf<SSEShape>("event")),
+                        ),
+                      ),
+                    },
+                  },
+                ),
+              ),
+            ]),
+          ),
+          f.createReturnStatement(this.ids.connectionConst),
+        ]),
+        {
+          typeParams: {
+            K: makeExtract(
+              this.requestType.name,
+              f.createTemplateLiteralType(f.createTemplateHead("get "), [
+                f.createTemplateLiteralTypeSpan(
+                  f.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+                  f.createTemplateTail(""),
+                ),
+              ]),
+            ),
+            R: makeExtract(
+              f.createIndexedAccessTypeNode(
+                ensureTypeNode(this.interfaces.positive),
+                ensureTypeNode("K"),
+              ),
+              makeOnePropObjType(
+                propOf<SSEShape>("event"),
+                f.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+              ),
+            ),
+          },
+        },
+      ),
+      { expose: true },
+    );
+
   // export const exampleImplementation: Implementation = async (method,path,params) => { ___ };
   protected makeExampleImplementation = () => {
     // method: method.toUpperCase()
@@ -465,5 +634,19 @@ export abstract class IntegrationBase {
         ]),
       ]),
     ),
+    // client.subscribe("get /v1/events/time", {}).on("time", (time) => {});
+    f.createExpressionStatement(
+      makePropCall(
+        makePropCall(this.ids.clientConst, this.ids.subscribeFn, [
+          f.createStringLiteral(`${"get" satisfies Method} /v1/events/time`),
+          f.createObjectLiteralExpression(),
+        ]),
+        this.ids.onMethod,
+        [
+          f.createStringLiteral("time"),
+          makeArrowFn({ time: undefined }, f.createBlock([])),
+        ],
+      ),
+    ),
   ];
 }

src/integration.ts

@@ -180,6 +180,7 @@ export class Integration extends IntegrationBase {
       this.makeSubstituteFn(),
       this.makeImplementationType(),
       this.makeClientClass(),
+      this.makeSubscribeFn(),
     );
 
     this.usage.push(

src/typescript-api.ts

@@ -114,6 +114,14 @@ export const makeInterfaceProp = (
     ensureTypeNode(value),
   );
 
+export const makeOnePropObjType = (
+  ...params: Parameters<typeof makeInterfaceProp>
+) =>
+  ts.setEmitFlags(
+    f.createTypeLiteralNode([makeInterfaceProp(...params)]),
+    ts.EmitFlags.SingleLine,
+  );
+
 export const makeDeconstruction = (
   ...names: ts.Identifier[]
 ): ts.ArrayBindingPattern =>
@@ -293,6 +301,11 @@ export const makePropCall = (
 export const makeNew = (cls: ts.Identifier, ...args: ts.Expression[]) =>
   f.createNewExpression(cls, undefined, args);
 
+export const makeExtract = (
+  base: Parameters<typeof ensureTypeNode>[0],
+  narrow: ts.TypeNode,
+) => f.createTypeReferenceNode("Extract", [ensureTypeNode(base), narrow]);
+
 const primitives: ts.KeywordTypeSyntaxKind[] = [
   ts.SyntaxKind.AnyKeyword,
   ts.SyntaxKind.BigIntKeyword,