@donkeylabs/server 1.1.19 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "1.1.19",
+  "version": "2.0.0",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/core/events.ts

@@ -1,6 +1,8 @@
 // Core Events Service
 // Pub/sub async event queue
 
+import type { EventRegistry } from "../core";
+
 export interface EventHandler<T = any> {
   (data: T): void | Promise<void>;
 }
@@ -25,10 +27,44 @@ export interface EventsConfig {
   maxHistorySize?: number;
 }
 
+/**
+ * Check if EventRegistry has any keys (is augmented)
+ */
+type HasEvents = keyof EventRegistry extends never ? false : true;
+
+/**
+ * Events service interface.
+ * When EventRegistry is augmented (via generated types), emit/on become fully typed.
+ * Otherwise, falls back to generic string event names.
+ */
 export interface Events {
+  /**
+   * Emit a typed event (when EventRegistry is augmented)
+   */
+  emit<K extends keyof EventRegistry>(event: K, data: EventRegistry[K]): Promise<void>;
+  /**
+   * Emit an untyped event (fallback for dynamic event names)
+   */
   emit<T = any>(event: string, data: T): Promise<void>;
+
+  /**
+   * Subscribe to a typed event (when EventRegistry is augmented)
+   */
+  on<K extends keyof EventRegistry>(event: K, handler: EventHandler<EventRegistry[K]>): Subscription;
+  /**
+   * Subscribe to an untyped event (fallback for patterns like "user.*")
+   */
   on<T = any>(event: string, handler: EventHandler<T>): Subscription;
+
+  /**
+   * Subscribe to a typed event once (when EventRegistry is augmented)
+   */
+  once<K extends keyof EventRegistry>(event: K, handler: EventHandler<EventRegistry[K]>): Subscription;
+  /**
+   * Subscribe to an untyped event once
+   */
   once<T = any>(event: string, handler: EventHandler<T>): Subscription;
+
   off(event: string, handler?: EventHandler): void;
   getHistory(event: string, limit?: number): Promise<EventRecord[]>;
 }

package/src/core.ts

@@ -24,6 +24,52 @@ export interface ClientConfig {
 
 export type EventSchemas = Record<string, z.ZodType<any>>;
 
+/**
+ * Registry for server-level events.
+ * Augment this interface to add typed events:
+ *
+ * @example
+ * ```ts
+ * // In generated types or app's types file
+ * declare module "@donkeylabs/server" {
+ *   interface EventRegistry {
+ *     "order.created": { orderId: string; total: number };
+ *     "user.signup": { userId: string; email: string };
+ *   }
+ * }
+ *
+ * // Now ctx.core.events.emit("order.created", {...}) is typed
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface EventRegistry {}
+
+/**
+ * Define server-level events with Zod schemas.
+ * Events defined here will be typed and available across the app.
+ *
+ * @example
+ * ```ts
+ * // src/events.ts
+ * import { z } from "zod";
+ * import { defineEvents } from "@donkeylabs/server";
+ *
+ * export const events = defineEvents({
+ *   "order.created": z.object({
+ *     orderId: z.string(),
+ *     total: z.number(),
+ *   }),
+ *   "user.signup": z.object({
+ *     userId: z.string(),
+ *     email: z.string(),
+ *   }),
+ * });
+ * ```
+ */
+export function defineEvents<T extends EventSchemas>(events: T): T {
+  return events;
+}
+
 export type Register<
   Service = void,
   Schema = {},

package/src/index.ts

@@ -46,6 +46,10 @@ export {
   createPlugin,
   PluginManager,
   PluginContext,
+  // Events
+  defineEvents,
+  type EventRegistry,
+  type EventSchemas,
   type PluginRegistry,
   type PluginHandlerRegistry,
   type PluginMiddlewareRegistry,
@@ -57,7 +61,6 @@ export {
   type InferHandlers,
   type InferMiddleware,
   type InferDependencies,
-  type EventSchemas,
   // Custom services registry
   type ServiceRegistry,
 } from "./core";