alepha 0.18.2 → 0.18.3

package/dist/server/core/index.js

@@ -1594,6 +1594,378 @@ var RoutePrimitive = class extends PipelinePrimitive {
 };
 $route[KIND] = RoutePrimitive;
 
+//#endregion
+//#region ../../src/server/core/primitives/$sse.ts
+/**
+* Async iterable stream of SSE events.
+*
+* Supports push-based event delivery via `push()`, error propagation
+* via `fail()`, and clean termination via `end()`.
+*/
+var SseStream = class {
+	queue = [];
+	error = null;
+	done = false;
+	resolve = null;
+	listeners = [];
+	/**
+	* Push a new event into the stream.
+	*/
+	push(data) {
+		if (this.done) return;
+		this.queue.push(data);
+		for (const listener of this.listeners) listener(data);
+		if (this.resolve) {
+			this.resolve();
+			this.resolve = null;
+		}
+	}
+	/**
+	* Signal an error on the stream.
+	*/
+	fail(error) {
+		this.error = error;
+		this.done = true;
+		if (this.resolve) {
+			this.resolve();
+			this.resolve = null;
+		}
+	}
+	/**
+	* End the stream gracefully.
+	*/
+	end() {
+		this.done = true;
+		if (this.resolve) {
+			this.resolve();
+			this.resolve = null;
+		}
+	}
+	/**
+	* Subscribe to new events as they arrive.
+	*/
+	subscribe(listener) {
+		this.listeners.push(listener);
+		return () => {
+			const idx = this.listeners.indexOf(listener);
+			if (idx >= 0) this.listeners.splice(idx, 1);
+		};
+	}
+	async *[Symbol.asyncIterator]() {
+		while (true) {
+			while (this.queue.length > 0) yield this.queue.shift();
+			if (this.error) throw this.error;
+			if (this.done) return;
+			await new Promise((r) => {
+				this.resolve = r;
+			});
+		}
+	}
+};
+/**
+* Response wrapper for SSE fetch requests.
+*
+* Wraps a standard `Response` and parses the `text/event-stream` body
+* into an async iterable of typed events.
+*/
+var SseFetchResponse = class {
+	response;
+	constructor(response) {
+		this.response = response;
+	}
+	/**
+	* HTTP status code of the response.
+	*/
+	get status() {
+		return this.response.status;
+	}
+	/**
+	* HTTP status text of the response.
+	*/
+	get statusText() {
+		return this.response.statusText;
+	}
+	/**
+	* Response headers.
+	*/
+	get headers() {
+		return this.response.headers;
+	}
+	async *[Symbol.asyncIterator]() {
+		const reader = this.response.body?.getReader();
+		if (!reader) return;
+		const decoder = new TextDecoder();
+		let buffer = "";
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				buffer += decoder.decode(value, { stream: true });
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) if (line.startsWith("data: ")) {
+					const data = line.slice(6);
+					try {
+						yield JSON.parse(data);
+					} catch {}
+				}
+			}
+			if (buffer.startsWith("data: ")) {
+				const data = buffer.slice(6);
+				try {
+					yield JSON.parse(data);
+				} catch {}
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+};
+/**
+* Creates a Server-Sent Events (SSE) primitive for streaming typed events to clients.
+*
+* SSE endpoints provide a unidirectional stream from server to client over HTTP,
+* with full type safety for event data. The handler receives `emit()` and `close()`
+* functions to control the stream.
+*
+* **Key Features**
+* - Full TypeScript inference for event data types
+* - Automatic schema validation using TypeBox
+* - Convention-based URL generation with customizable paths
+* - Direct invocation (`run()`) returns an `SseStream` async iterable
+* - HTTP requests (`fetch()`) returns an `SseFetchResponse` async iterable
+* - Built-in `text/event-stream` content-type handling
+*
+* **URL Generation**
+*
+* All `$sse` paths are automatically prefixed with `/api`.
+*
+* ```ts
+* $sse({ path: "/events" })     // POST /api/events
+* $sse({ path: "/feed/:id" })   // POST /api/feed/:id
+* ```
+*
+* The HTTP method is always POST.
+*
+* @example
+* ```ts
+* class NotificationController {
+*   events = $sse({
+*     schema: {
+*       data: t.object({
+*         type: t.text(),
+*         message: t.text(),
+*       }),
+*     },
+*     handler: async ({ emit, close }) => {
+*       emit({ type: "welcome", message: "Connected!" });
+*       // ... stream events ...
+*       close();
+*     },
+*   });
+* }
+* ```
+*/
+const $sse = (options) => {
+	const instance = createPrimitive(SsePrimitive, options);
+	const fn = (config) => {
+		return instance.run(config);
+	};
+	Object.defineProperty(fn, "name", { get() {
+		return instance.options.name || instance.config.propertyKey;
+	} });
+	return Object.setPrototypeOf(fn, instance);
+};
+/**
+* The SSE primitive class extending PipelinePrimitive.
+*
+* Registers a POST route that streams `text/event-stream` responses.
+* Supports direct invocation via `run()` and HTTP via `fetch()`.
+*/
+var SsePrimitive = class extends PipelinePrimitive {
+	log = $logger();
+	settings = $use(serverApiOptions);
+	serverProvider = $inject(ServerProvider);
+	serverRouterProvider = $inject(ServerRouterProvider);
+	onInit() {
+		if (this.options.disabled) {
+			this.log.debug(`SSE endpoint '${this.name}' is disabled. It won't be available in the API.`);
+			return;
+		}
+		this.serverRouterProvider.createRoute({
+			method: this.method,
+			path: `${this.prefix}${this.path}`,
+			schema: this.requestConfigSchema,
+			handler: (request) => this.httpHandler(request)
+		});
+	}
+	/**
+	* Returns the /api prefix.
+	*/
+	get prefix() {
+		return this.settings.prefix;
+	}
+	/**
+	* Returns the name of the SSE endpoint.
+	*/
+	get name() {
+		return this.options.name || this.config.propertyKey;
+	}
+	/**
+	* Returns the group of the SSE endpoint.
+	*/
+	get group() {
+		return this.options.group || this.config.service.name;
+	}
+	/**
+	* Returns the HTTP method. SSE always uses POST.
+	*/
+	get method() {
+		return "POST";
+	}
+	/**
+	* Returns the path of the SSE endpoint.
+	*/
+	get path() {
+		if (this.options.path) return this.options.path;
+		let path = `/${this.name}`;
+		if (this.options.schema?.params) for (const [key] of Object.entries(this.options.schema.params.properties)) path += `/:${key}`;
+		return path;
+	}
+	/**
+	* Returns the schema configuration.
+	*/
+	get schema() {
+		return this.options.schema;
+	}
+	/**
+	* Constructs a RequestConfigSchema from the SSE config for route registration.
+	*/
+	get requestConfigSchema() {
+		if (!this.options.schema) return void 0;
+		return {
+			body: this.options.schema.body,
+			params: this.options.schema.params,
+			query: this.options.schema.query,
+			headers: this.options.schema.headers
+		};
+	}
+	/**
+	* Call the SSE handler directly and return a typed async iterable stream.
+	* There is no HTTP layer involved.
+	*/
+	run(config) {
+		if (this.options.disabled) throw new AlephaError(`SSE endpoint '${this.name}' is disabled.`);
+		const stream = new SseStream();
+		const { body, params = {}, query = {}, headers = {} } = config ?? {};
+		const url = new URL(`http://localhost${this.path ?? ""}`);
+		const reply = new ServerReply();
+		const context = {
+			body,
+			params,
+			query,
+			headers,
+			request: {
+				method: this.method,
+				url,
+				body,
+				params,
+				query,
+				headers,
+				reply,
+				metadata: {
+					routePath: `${this.prefix}${this.path}`,
+					routeMethod: this.method
+				}
+			},
+			emit: (data) => stream.push(data),
+			close: () => stream.end()
+		};
+		const handlerFn = this.handler.run.bind(this.handler);
+		Promise.resolve().then(() => handlerFn(context)).then(() => {
+			stream.end();
+		}).catch((error) => {
+			stream.fail(error);
+		});
+		return stream;
+	}
+	/**
+	* Works like `run`, but always fetches (http request) the route.
+	* Returns an `SseFetchResponse` that can be async-iterated for typed events.
+	*/
+	async fetch(config) {
+		const host = this.serverProvider.hostname;
+		const url = this.buildFetchUrl(host, config);
+		const { body, headers: configHeaders = {} } = config ?? {};
+		const requestInit = {
+			method: "POST",
+			headers: {
+				accept: "text/event-stream",
+				"content-type": "application/json",
+				...configHeaders
+			}
+		};
+		if (body !== void 0) requestInit.body = JSON.stringify(body);
+		return new SseFetchResponse(await fetch(url, requestInit));
+	}
+	/**
+	* HTTP handler for the registered route.
+	* Returns a ReadableStream with SSE-formatted events.
+	*/
+	httpHandler(request) {
+		const reply = request.reply;
+		reply.setHeader("content-type", "text/event-stream");
+		reply.setHeader("cache-control", "no-cache");
+		reply.setHeader("connection", "keep-alive");
+		const handlerFn = this.handler.run.bind(this.handler);
+		return new ReadableStream({ start: (controller) => {
+			const encoder = new TextEncoder();
+			const context = {
+				body: request.body,
+				params: request.params,
+				query: request.query,
+				headers: request.headers,
+				request,
+				emit: (data) => {
+					try {
+						controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
+					} catch {}
+				},
+				close: () => {
+					try {
+						controller.close();
+					} catch {}
+				}
+			};
+			Promise.resolve().then(() => handlerFn(context)).then(() => {
+				try {
+					controller.close();
+				} catch {}
+			}).catch((error) => {
+				try {
+					controller.error(error);
+				} catch {}
+			});
+		} });
+	}
+	/**
+	* Build the fetch URL with path variables and query params.
+	*/
+	buildFetchUrl(host, config) {
+		let url = `${host}${this.prefix}${this.path}`;
+		const { params, query } = config ?? {};
+		if (params && typeof params === "object") for (const [key, value] of Object.entries(params)) url = url.replace(`:${key}`, String(value));
+		if (query && typeof query === "object") {
+			const searchParams = new URLSearchParams();
+			for (const [key, value] of Object.entries(query)) if (value !== void 0) searchParams.set(key, String(value));
+			const qs = searchParams.toString();
+			if (qs) url += `?${qs}`;
+		}
+		return url;
+	}
+};
+$sse[KIND] = SsePrimitive;
+
 //#endregion
 //#region ../../src/server/core/providers/BunHttpServerProvider.ts
 const envSchema$1 = t.object({
@@ -2606,7 +2978,8 @@ const AlephaServer = $module({
 	primitives: [
 		$route,
 		$action,
-		$middleware
+		$middleware,
+		$sse
 	],
 	services: [
 		ServerProvider,
@@ -2649,5 +3022,5 @@ const AlephaServer = $module({
 });
 
 //#endregion
-export { $action, $circuit, $middleware, $route, ActionPrimitive, AlephaServer, BadRequestError, BunHttpServerProvider, ConflictError, ForbiddenError, HttpClient, HttpError, NodeHttpServerProvider, NotFoundError, RoutePrimitive, ServerCompressProvider, ServerHelmetProvider, ServerLoggerProvider, ServerMiddlewarePrimitive, ServerMultipartProvider, ServerNotReadyProvider, ServerProvider, ServerReply, ServerRouterProvider, ServerTimingProvider, UnauthorizedError, UserAgentParser, ValidationError, compressOptions, errorNameByStatus, errorSchema, helmetOptions, isHttpError, isMultipart, multipartOptions, okSchema, routeMethods, serverApiOptions };
+export { $action, $circuit, $middleware, $route, $sse, ActionPrimitive, AlephaServer, BadRequestError, BunHttpServerProvider, ConflictError, ForbiddenError, HttpClient, HttpError, NodeHttpServerProvider, NotFoundError, RoutePrimitive, ServerCompressProvider, ServerHelmetProvider, ServerLoggerProvider, ServerMiddlewarePrimitive, ServerMultipartProvider, ServerNotReadyProvider, ServerProvider, ServerReply, ServerRouterProvider, ServerTimingProvider, SseFetchResponse, SsePrimitive, SseStream, UnauthorizedError, UserAgentParser, ValidationError, compressOptions, errorNameByStatus, errorSchema, helmetOptions, isHttpError, isMultipart, multipartOptions, okSchema, routeMethods, serverApiOptions };
 //# sourceMappingURL=index.js.map