@veloxts/events 0.6.56 → 0.6.58

package/README.md

@@ -1,31 +1,8 @@
 # @veloxts/events
 
-> **Early Preview** - APIs may change before v1.0.
+> **Early Preview (v0.6.x)** - APIs are stabilizing but may still change. Use with caution in production.
 
-Real-time event broadcasting via WebSocket with optional Redis pub/sub for scaling.
-
-## Installation
-
-```bash
-npm install @veloxts/events
-```
-
-## Quick Start
-
-```typescript
-import { eventsPlugin } from '@veloxts/events';
-
-app.use(eventsPlugin({ driver: 'ws', path: '/ws' }));
-
-// Broadcast an event
-await ctx.broadcast({
-  channel: 'orders.123',
-  event: 'order.shipped',
-  data: { trackingNumber: 'TRACK123' },
-});
-```
-
-See [GUIDE.md](./GUIDE.md) for detailed documentation.
+Real-time event broadcasting for VeloxTS Framework - provides WebSocket and SSE drivers with channel authorization and optional Redis pub/sub for horizontal scaling. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
 
 ## License
 

package/dist/index.d.ts

@@ -43,3 +43,22 @@ export { createEventsManager, createManagerFromDriver, type EventsManager, event
 export { _resetStandaloneEvents, eventsPlugin, getEvents, getEventsFromInstance, } from './plugin.js';
 export { ClientMessageSchema, formatValidationErrors, PresenceMemberSchema, SseSubscribeBodySchema, SseUnsubscribeBodySchema, type ValidationResult, validateBody, WsAuthBodySchema, } from './schemas.js';
 export type { BroadcastDriver, BroadcastEvent, Channel, ChannelAuthorizer, ChannelAuthResult, ChannelType, ClientConnection, ClientMessage, EventsBaseOptions, EventsDefaultOptions, EventsManagerOptions, EventsPluginOptions, EventsSseOptions, EventsWsOptions, PresenceMember, ServerMessage, Subscription, } from './types.js';
+/**
+ * DI tokens and providers for @veloxts/events
+ *
+ * Use these to integrate events services with the @veloxts/core DI container.
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerEventsProviders, EVENTS_MANAGER } from '@veloxts/events';
+ *
+ * const container = new Container();
+ * await registerEventsProviders(container, { driver: 'ws' });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders', 'order.created', { id: '123' });
+ * ```
+ */
+export { registerEventsProviders } from './providers.js';
+export { EVENTS_CONFIG, EVENTS_DRIVER, EVENTS_MANAGER } from './tokens.js';

package/dist/index.js

@@ -47,3 +47,27 @@ export { createEventsManager, createManagerFromDriver, events, } from './manager
 export { _resetStandaloneEvents, eventsPlugin, getEvents, getEventsFromInstance, } from './plugin.js';
 // Schemas (for validation)
 export { ClientMessageSchema, formatValidationErrors, PresenceMemberSchema, SseSubscribeBodySchema, SseUnsubscribeBodySchema, validateBody, WsAuthBodySchema, } from './schemas.js';
+// ============================================================================
+// Dependency Injection
+// ============================================================================
+/**
+ * DI tokens and providers for @veloxts/events
+ *
+ * Use these to integrate events services with the @veloxts/core DI container.
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerEventsProviders, EVENTS_MANAGER } from '@veloxts/events';
+ *
+ * const container = new Container();
+ * await registerEventsProviders(container, { driver: 'ws' });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders', 'order.created', { id: '123' });
+ * ```
+ */
+// Provider exports - factory functions for registering services
+export { registerEventsProviders } from './providers.js';
+// Token exports - unique identifiers for DI resolution
+export { EVENTS_CONFIG, EVENTS_DRIVER, EVENTS_MANAGER } from './tokens.js';

package/dist/providers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * DI Providers for @veloxts/events
+ *
+ * Factory provider functions for registering events services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module events/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerEventsProviders, EVENTS_MANAGER } from '@veloxts/events';
+ *
+ * const container = new Container();
+ * await registerEventsProviders(container, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ * });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders', 'order.created', { id: '123' });
+ * ```
+ */
+import type { Container } from '@veloxts/core';
+import type { EventsPluginOptions } from './types.js';
+/**
+ * Registers events providers with a container
+ *
+ * This handles async initialization of the events manager and registers
+ * the resolved instance directly for synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Events plugin options (driver, path, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerEventsProviders, EVENTS_MANAGER } from '@veloxts/events';
+ *
+ * const container = new Container();
+ *
+ * // WebSocket driver (default, recommended for real-time)
+ * await registerEventsProviders(container, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // For horizontal scaling
+ * });
+ *
+ * // SSE driver (fallback for environments without WebSocket)
+ * await registerEventsProviders(container, {
+ *   driver: 'sse',
+ *   path: '/events',
+ * });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders.123', 'order.shipped', { trackingNumber: 'TRACK123' });
+ * ```
+ */
+export declare function registerEventsProviders(container: Container, config?: EventsPluginOptions): Promise<void>;

package/dist/providers.js

@@ -0,0 +1,81 @@
+/**
+ * DI Providers for @veloxts/events
+ *
+ * Factory provider functions for registering events services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module events/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerEventsProviders, EVENTS_MANAGER } from '@veloxts/events';
+ *
+ * const container = new Container();
+ * await registerEventsProviders(container, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ * });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders', 'order.created', { id: '123' });
+ * ```
+ */
+import { createEventsManager } from './manager.js';
+import { EVENTS_CONFIG, EVENTS_DRIVER, EVENTS_MANAGER } from './tokens.js';
+// ============================================================================
+// Bulk Registration Helpers
+// ============================================================================
+/**
+ * Registers events providers with a container
+ *
+ * This handles async initialization of the events manager and registers
+ * the resolved instance directly for synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Events plugin options (driver, path, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerEventsProviders, EVENTS_MANAGER } from '@veloxts/events';
+ *
+ * const container = new Container();
+ *
+ * // WebSocket driver (default, recommended for real-time)
+ * await registerEventsProviders(container, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // For horizontal scaling
+ * });
+ *
+ * // SSE driver (fallback for environments without WebSocket)
+ * await registerEventsProviders(container, {
+ *   driver: 'sse',
+ *   path: '/events',
+ * });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders.123', 'order.shipped', { trackingNumber: 'TRACK123' });
+ * ```
+ */
+export async function registerEventsProviders(container, config = {}) {
+    // Register config
+    container.register({
+        provide: EVENTS_CONFIG,
+        useValue: config,
+    });
+    // Create events manager (async operation)
+    const eventsManager = await createEventsManager(config);
+    // Register the driver for direct access
+    container.register({
+        provide: EVENTS_DRIVER,
+        useValue: eventsManager.driver,
+    });
+    // Register the resolved events manager instance directly
+    // This allows synchronous resolution from the container
+    container.register({
+        provide: EVENTS_MANAGER,
+        useValue: eventsManager,
+    });
+}

package/dist/tokens.d.ts

@@ -0,0 +1,59 @@
+/**
+ * DI Tokens for @veloxts/events
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow events services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module events/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { EVENTS_MANAGER, registerEventsProviders } from '@veloxts/events';
+ *
+ * const container = new Container();
+ * await registerEventsProviders(container, { driver: 'ws' });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders', 'order.created', { id: '123' });
+ * ```
+ */
+import type { BroadcastDriver, EventsManager, EventsPluginOptions } from './types.js';
+/**
+ * Events manager token
+ *
+ * The main events manager instance for broadcasting events.
+ *
+ * @example
+ * ```typescript
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders.123', 'order.shipped', { trackingNumber: 'TRACK123' });
+ * await events.broadcastToMany(['user.1', 'user.2'], 'notification', { message: 'Hello!' });
+ * ```
+ */
+export declare const EVENTS_MANAGER: import("@veloxts/core").SymbolToken<EventsManager>;
+/**
+ * Broadcast driver token
+ *
+ * The underlying broadcast driver (WebSocket or SSE).
+ * Use EVENTS_MANAGER for high-level operations; use this for direct driver access.
+ *
+ * @example
+ * ```typescript
+ * const driver = container.resolve(EVENTS_DRIVER);
+ * await driver.broadcast({ channel: 'orders', event: 'created', data: { id: '123' } });
+ * ```
+ */
+export declare const EVENTS_DRIVER: import("@veloxts/core").SymbolToken<BroadcastDriver>;
+/**
+ * Events configuration token
+ *
+ * Contains events plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(EVENTS_CONFIG);
+ * console.log(config.driver); // 'ws' or 'sse'
+ * ```
+ */
+export declare const EVENTS_CONFIG: import("@veloxts/core").SymbolToken<EventsPluginOptions>;

package/dist/tokens.js

@@ -0,0 +1,65 @@
+/**
+ * DI Tokens for @veloxts/events
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow events services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module events/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { EVENTS_MANAGER, registerEventsProviders } from '@veloxts/events';
+ *
+ * const container = new Container();
+ * await registerEventsProviders(container, { driver: 'ws' });
+ *
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders', 'order.created', { id: '123' });
+ * ```
+ */
+import { token } from '@veloxts/core';
+// ============================================================================
+// Core Events Tokens
+// ============================================================================
+/**
+ * Events manager token
+ *
+ * The main events manager instance for broadcasting events.
+ *
+ * @example
+ * ```typescript
+ * const events = container.resolve(EVENTS_MANAGER);
+ * await events.broadcast('orders.123', 'order.shipped', { trackingNumber: 'TRACK123' });
+ * await events.broadcastToMany(['user.1', 'user.2'], 'notification', { message: 'Hello!' });
+ * ```
+ */
+export const EVENTS_MANAGER = token.symbol('EVENTS_MANAGER');
+/**
+ * Broadcast driver token
+ *
+ * The underlying broadcast driver (WebSocket or SSE).
+ * Use EVENTS_MANAGER for high-level operations; use this for direct driver access.
+ *
+ * @example
+ * ```typescript
+ * const driver = container.resolve(EVENTS_DRIVER);
+ * await driver.broadcast({ channel: 'orders', event: 'created', data: { id: '123' } });
+ * ```
+ */
+export const EVENTS_DRIVER = token.symbol('EVENTS_DRIVER');
+// ============================================================================
+// Configuration Tokens
+// ============================================================================
+/**
+ * Events configuration token
+ *
+ * Contains events plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(EVENTS_CONFIG);
+ * console.log(config.driver); // 'ws' or 'sse'
+ * ```
+ */
+export const EVENTS_CONFIG = token.symbol('EVENTS_CONFIG');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/events",
-  "version": "0.6.56",
+  "version": "0.6.58",
   "description": "Real-time event broadcasting for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,7 @@
     "superjson": "2.2.2",
     "ws": "8.18.2",
     "zod": "3.24.4",
-    "@veloxts/core": "0.6.56"
+    "@veloxts/core": "0.6.58"
   },
   "peerDependencies": {
     "fastify": "^5.0.0",
@@ -49,7 +49,7 @@
     "ioredis": "5.6.1",
     "typescript": "5.8.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.56"
+    "@veloxts/testing": "0.6.58"
   },
   "publishConfig": {
     "access": "public"