Websocket provider and sse/ws injectables

Author: Anatoly Ostrovsky

@types/core/di/ng-module/ng-module.d.ts

@@ -199,4 +199,28 @@ export class NgModule {
     entityClass: ng.EntityClass<T>,
     options?: any | undefined,
   ): NgModule;
+  /**
+   * Register a pre-configured SSE connection during module configuration.
+   *
+   * @param {string} name - Injectable name
+   * @param {string} url - SSE endpoint
+   * @param {ng.SseConfig} [options] - Optional SSE config
+   * @returns {NgModule}
+   */
+  sse(name: string, url: string, options?: ng.SseConfig): NgModule;
+  /**
+   * Register a pre-configured WebSocket connection during module configuration.
+   *
+   * @param {string} name - Injectable name
+   * @param {string} url - WebSocket endpoint
+   * @param {string[]} [protocols] - Optional subprotocols
+   * @param {ng.WebSocketConfig} [options] - Optional WebSocket configuration
+   * @returns {NgModule}
+   */
+  websocket(
+    name: string,
+    url: string,
+    protocols?: string[],
+    options?: ng.WebSocketConfig,
+  ): NgModule;
 }

@types/namespace.d.ts

@@ -121,6 +121,10 @@ import {
   SCEService as TSCEService,
   SCEDelegateService as TSCEDelegateService,
 } from "./services/sce/interface.ts";
+import {
+  WebSocketConfig as TWebSocketConfig,
+  WebSocketService as TWebSocketService,
+} from "./services/websocket/interface.ts";
 declare global {
   interface Function {
     $inject?: readonly string[] | undefined;
@@ -229,5 +233,7 @@ declare global {
     type RequestShortcutConfig = TRequestShortcutConfig;
     type HttpProviderDefaults = THttpProviderDefaults;
     type ProviderCache = TProviderCache;
+    type WebSocketConfig = TWebSocketConfig;
+    type WebSocketService = TWebSocketService;
   }
 }

@types/services/sse/interface.d.ts

@@ -1,29 +1,14 @@
+import { StreamConnectionConfig } from "../stream/interface.ts";
 /**
- * Configuration object for SSE
+ * SSE-specific configuration
  */
-export interface SseConfig {
+export interface SseConfig extends StreamConnectionConfig {
   /** Include cookies/credentials when connecting */
   withCredentials?: boolean;
-  /** Custom headers (Note: EventSource doesn't natively support headers; handled at app level if needed) */
-  headers?: Record<string, string>;
-  /** Called when the connection is successfully opened */
-  onOpen?: (event: Event) => void;
-  /** Called when a message event is received */
-  onMessage?: (data: any, event: MessageEvent) => void;
-  /** Called on connection error */
-  onError?: (err: Event) => void;
-  /** Transform raw SSE message data (default: JSON.parse if possible) */
-  transformMessage?: (data: string) => any;
   /** Optional query parameters appended to the URL */
   params?: Record<string, any>;
-  /** Called when the connection is being re-established */
-  onReconnect?: (attempt: number) => void;
-  /** Delay in milliseconds before attempting to reconnect (default: 1000ms) */
-  retryDelay?: number;
-  /** Maximum number of reconnect attempts (default: Infinity) */
-  maxRetries?: number;
-  /** Heartbeat timeout in milliseconds; reconnect if no message within this time */
-  heartbeatTimeout?: number;
+  /** Custom headers (EventSource doesn't natively support headers) */
+  headers?: Record<string, string>;
 }
 /**
  * Managed SSE connection object returned by $sse.

@types/services/stream/interface.d.ts

@@ -15,4 +15,5 @@ export interface StreamConnectionConfig {
   heartbeatTimeout?: number;
   /** Function to transform incoming messages */
   transformMessage?: (data: any) => any;
+  [key: string]: any;
 }

@types/services/stream/stream.d.ts

@@ -23,7 +23,7 @@ export class StreamConnection {
     retryDelay: number;
     maxRetries: number;
     heartbeatTimeout: number;
-    transformMessage: (data: string) => any;
+    transformMessage: (data: any) => any;
   };
   _log: import("../log/interface.ts").LogService;
   _retryCount: number;

@types/services/websocket/interface.d.ts

@@ -0,0 +1,23 @@
+import { StreamConnectionConfig } from "../stream/interface.ts";
+import { StreamConnection } from "../stream/stream.js";
+/**
+ * WebSocket-specific configuration
+ */
+export interface WebSocketConfig extends StreamConnectionConfig {
+  /** Optional WebSocket subprotocols */
+  protocols?: string[];
+  /** Called when the WebSocket connection closes */
+  onClose?: (event: CloseEvent) => void;
+}
+/**
+ * Type of the injectable WebSocket service returned by the provider.
+ * Acts as a factory for pre-configured WebSocket connections.
+ */
+export type WebSocketService = (
+  /** The WebSocket URL (already pre-configured if passed at module registration) */
+  url?: string,
+  /** Optional WebSocket subprotocols */
+  protocols?: string[],
+  /** Optional configuration (merges with defaults) */
+  config?: WebSocketConfig,
+) => StreamConnection;

@types/services/websocket/websocket.d.ts

@@ -0,0 +1,20 @@
+/**
+ * WebSocketProvider
+ * Provides a pre-configured WebSocket connection as an injectable.
+ */
+export class WebSocketProvider {
+  /** @type {ng.WebSocketConfig} */
+  defaults: ng.WebSocketConfig;
+  $get: (
+    | string
+    | ((
+        log: ng.LogService,
+      ) => (
+        url: string,
+        protocols?: string[],
+        config?: import("./interface.ts").WebSocketConfig,
+      ) => StreamConnection)
+  )[];
+  _$log: import("../log/interface.ts").LogService;
+}
+import { StreamConnection } from "../stream/stream.js";

README.md

@@ -17,7 +17,7 @@ AngularTS builds on that foundation and adds:
 - built-in enterprise-level router (`ui-router` ported as `ng-router`)
 - built-in animations (`animate`)
 - new directives, inspired by `HTMX`
-- new injectables for REST resources, persistent stores, Web Workers and WASM modules
+- new injectables for REST resources, persistent stores, Web Workers, EventSources, WebSockets and WASM modules
 
 The result is a high-performance, buildless, multi-paradigm and battle-tested JS framework that stays as close to Web standards as possible.
 

src/core/di/ng-module/ng-module.js

@@ -372,4 +372,60 @@ export class NgModule {
 
     return this;
   }
+
+  /**
+   * Register a pre-configured SSE connection during module configuration.
+   *
+   * @param {string} name - Injectable name
+   * @param {string} url - SSE endpoint
+   * @param {ng.SseConfig} [options] - Optional SSE config
+   * @returns {NgModule}
+   */
+  sse(name, url, options = {}) {
+    validate(isString, name, "name");
+    validate(isString, url, "url");
+
+    this._invokeQueue.push([
+      $t._provide,
+      "factory",
+      [
+        name,
+        [
+          $t._sse,
+          /** @param {ng.SseService} $sse */ ($sse) => $sse(url, options),
+        ],
+      ],
+    ]);
+
+    return this;
+  }
+
+  /**
+   * Register a pre-configured WebSocket connection during module configuration.
+   *
+   * @param {string} name - Injectable name
+   * @param {string} url - WebSocket endpoint
+   * @param {string[]} [protocols] - Optional subprotocols
+   * @param {ng.WebSocketConfig} [options] - Optional WebSocket configuration
+   * @returns {NgModule}
+   */
+  websocket(name, url, protocols = [], options = {}) {
+    validate(isString, name, "name");
+    validate(isString, url, "url");
+
+    this._invokeQueue.push([
+      $t._provide,
+      "factory",
+      [
+        name,
+        [
+          $t._websocket,
+          /** @param {ng.WebSocketService} $ws */ ($ws) =>
+            $ws(url, protocols, options),
+        ],
+      ],
+    ]);
+
+    return this;
+  }
 }

src/injection-tokens.js

@@ -66,6 +66,8 @@ export const $injectTokens = {
   _url: "$url",
   _view: "$view",
   _window: "$window",
+  _ws: "$ws",
+
   // provide literals
   _provide: "$provide",
   _injector: "$injector",