@arrirpc/server 0.84.1 → 0.85.0

package/README.md

@@ -385,6 +385,74 @@ declare module '@arrirpc/server' {
 }
 ```
 
+### Background Workers & Lifecycle Hooks
+
+You can register background workers and lifecycle hooks on `ArriApp`. Workers and lifecycle hooks do not run when the app is imported during codegen (`arri build`); they only start when the web server begins listening.
+
+```ts
+import { ArriApp, defineWorker } from '@arrirpc/server';
+
+const app = new ArriApp({
+    onStart() {
+        console.log('Server is starting up');
+    },
+    onStop() {
+        console.log('Server is shutting down');
+    },
+    onWorkerError(err, worker) {
+        logger.error({ err, worker: worker.name }, 'Worker error');
+    },
+});
+
+// Registering a worker with a continuous loop and AbortSignal
+app.registerWorker(
+    defineWorker({
+        name: 'queue-consumer',
+        async start(signal) {
+            while (!signal.aborted) {
+                const job = await queue.pop({ signal });
+                if (job) await processJob(job);
+            }
+        },
+        async stop() {
+            // Optional: cleanup or drain
+        },
+    }),
+);
+
+// Registering a third-party worker (e.g. BullMQ)
+app.registerWorker(
+    defineWorker({
+        name: 'bullmq-emails',
+        async start() {
+            worker = new Worker('emails', async (job) => {
+                await sendEmail(job.data);
+            });
+        },
+        async stop() {
+            await worker.close();
+        },
+    }),
+);
+
+// Function shorthand
+app.registerWorker(async (signal) => {
+    while (!signal.aborted) {
+        await heartbeat();
+        await delay(5000, signal);
+    }
+});
+```
+
+Services can also register workers:
+
+```ts
+const authService = new ArriService('auth');
+authService.registerWorker(tokenCleanupWorker);
+
+app.use(authService); // Workers will be registered on the app
+```
+
 ### Adding Client Generators
 
 ```ts

package/dist/index.cjs

@@ -804,6 +804,18 @@ class ArriRouter {
   }
 }
 
+function defineWorker(worker) {
+  if (typeof worker === "function") {
+    return {
+      start: worker
+    };
+  }
+  return worker;
+}
+function isWorker(input) {
+  return typeof input === "object" && input !== null && "start" in input && typeof input.start === "function";
+}
+
 class ArriService {
   name;
   constructor(name) {
@@ -811,10 +823,14 @@ class ArriService {
   }
   procedures = [];
   definitions = {};
+  workers = [];
   rpc(name, procedure) {
     procedure.name = `${this.name}.${name}`;
     this.procedures.push(procedure);
   }
+  registerWorker(worker) {
+    this.workers.push(defineWorker(worker));
+  }
   registerDefinitions(models) {
     for (const key of Object.keys(models)) {
       this.definitions[key] = models[key];
@@ -826,6 +842,9 @@ class ArriService {
   getDefinitions() {
     return this.definitions;
   }
+  getWorkers() {
+    return this.workers;
+  }
 }
 function defineService(name, procedures) {
   const service = new ArriService(name);
@@ -846,6 +865,12 @@ class ArriApp {
   _procedures = {};
   _definitions = {};
   _middlewares = [];
+  _workers = [];
+  _onStartHooks = [];
+  _onStopHooks = [];
+  _workerErrorHooks = [];
+  _abortController = null;
+  _isRunning = false;
   _onRequest;
   _onAfterResponse;
   _onBeforeResponse;
@@ -863,6 +888,15 @@ class ArriApp {
     this._onError = opts.onError;
     this._onAfterResponse = opts.onAfterResponse;
     this._onBeforeResponse = opts.onBeforeResponse;
+    if (opts.onStart) {
+      this.onStart(opts.onStart);
+    }
+    if (opts.onStop) {
+      this.onStop(opts.onStop);
+    }
+    if (opts.onWorkerError) {
+      this.onWorkerError(opts.onWorkerError);
+    }
     this._heartbeatMs = opts.heartbeatMs ?? 2e4;
     this._rpcRoutePrefix = opts?.rpcRoutePrefix ?? "";
     this._rpcDefinitionPath = opts?.rpcDefinitionPath ?? "__definition";
@@ -937,6 +971,9 @@ class ArriApp {
         this.rpc(rpc.name, rpc);
       }
       this.registerDefinitions(input.getDefinitions());
+      for (const worker of input.getWorkers()) {
+        this.registerWorker(worker);
+      }
       return;
     }
     this._middlewares.push(input);
@@ -1012,6 +1049,118 @@ class ArriApp {
     }
     return appDef;
   }
+  registerWorker(worker) {
+    const w = defineWorker(worker);
+    this._workers.push(w);
+    if (this._isRunning && this._abortController) {
+      void (async () => {
+        try {
+          await w.start(this._abortController.signal);
+        } catch (err) {
+          await this._handleWorkerError(w, err);
+        }
+      })();
+    }
+  }
+  onStart(hook) {
+    this._onStartHooks.push(hook);
+  }
+  onStop(hook) {
+    this._onStopHooks.push(hook);
+  }
+  onWorkerError(hook) {
+    this._workerErrorHooks.push(hook);
+  }
+  async _handleWorkerError(worker, error) {
+    let handled = false;
+    if (worker.onError) {
+      try {
+        await worker.onError(error);
+        handled = true;
+      } catch (hookErr) {
+        console.error(
+          `[Arri] Error in worker.onError hook for worker ${worker.name ?? "unnamed"}:`,
+          hookErr
+        );
+      }
+    }
+    for (const hook of this._workerErrorHooks) {
+      try {
+        await hook(error, worker);
+        handled = true;
+      } catch (hookErr) {
+        console.error(
+          `[Arri] Error in onWorkerError hook for worker ${worker.name ?? "unnamed"}:`,
+          hookErr
+        );
+      }
+    }
+    if (!handled) {
+      console.error(
+        `[Arri] Unhandled error in worker ${worker.name ?? "unnamed"}:`,
+        error
+      );
+    }
+  }
+  async start() {
+    if (this._isRunning) {
+      return;
+    }
+    this._isRunning = true;
+    const controller = new AbortController();
+    this._abortController = controller;
+    try {
+      for (const hook of this._onStartHooks) {
+        await hook();
+      }
+    } catch (err) {
+      this._isRunning = false;
+      controller.abort();
+      this._abortController = null;
+      throw err;
+    }
+    for (const worker of this._workers) {
+      void (async () => {
+        try {
+          await worker.start(controller.signal);
+        } catch (err) {
+          await this._handleWorkerError(worker, err);
+        }
+      })();
+    }
+  }
+  async stop() {
+    if (!this._isRunning) {
+      return;
+    }
+    this._isRunning = false;
+    this._abortController?.abort();
+    const stopPromises = this._workers.map(async (worker) => {
+      try {
+        if (worker.stop) {
+          await worker.stop();
+        }
+      } catch (err) {
+        await this._handleWorkerError(worker, err);
+      }
+    });
+    const hookPromises = this._onStopHooks.map(async (hook) => {
+      try {
+        await hook();
+      } catch (err) {
+        if (this._debug) {
+          console.error("Error in onStop hook:", err);
+        }
+      }
+    });
+    await Promise.allSettled([...stopPromises, ...hookPromises]);
+  }
+  get workers() {
+    return [...this._workers];
+  }
+  get isRunning() {
+    return this._isRunning;
+  }
 }
 
 const defineMiddleware = (middleware) => middleware;
@@ -1030,6 +1179,7 @@ exports.defineMiddleware = defineMiddleware;
 exports.defineRoute = defineRoute;
 exports.defineRpc = defineRpc;
 exports.defineService = defineService;
+exports.defineWorker = defineWorker;
 exports.errorResponseFromValidationErrors = errorResponseFromValidationErrors;
 exports.getRpcParamName = getRpcParamName;
 exports.getRpcPath = getRpcPath;
@@ -1041,6 +1191,7 @@ exports.handleRoute = handleRoute;
 exports.isEventStreamRpc = isEventStreamRpc;
 exports.isRpc = isRpc;
 exports.isRpcParamSchema = isRpcParamSchema;
+exports.isWorker = isWorker;
 exports.registerEventStreamRpc = registerEventStreamRpc;
 exports.registerRoute = registerRoute;
 exports.registerRpc = registerRpc;

package/dist/index.d.cts

@@ -186,15 +186,29 @@ type RequestValidator<T = any> = {
 declare function getSchemaValidator<T extends Record<string, any> = any>(rpcName: string, type: 'params' | 'response', schema: RpcParamSchema<T>): RequestValidator<T> | undefined;
 declare function getSchemaName(rpcName: string, type: 'params' | 'response', schema: RpcParamSchema<any>): string;
 
+type WorkerHandler = (signal: AbortSignal) => Promise<void> | void;
+type WorkerErrorHandler = (error: unknown, worker: ArriWorker) => void | Promise<void>;
+interface ArriWorker {
+    name?: string;
+    start: (signal: AbortSignal) => Promise<void> | void;
+    stop?: () => Promise<void> | void;
+    onError?: (error: unknown) => void | Promise<void>;
+}
+declare function defineWorker(worker: ArriWorker | WorkerHandler): ArriWorker;
+declare function isWorker(input: unknown): input is ArriWorker;
+
 declare class ArriService {
     name: string;
     constructor(name: string);
     private readonly procedures;
     private readonly definitions;
+    private readonly workers;
     rpc(name: string, procedure: Rpc<any, any, any>): void;
+    registerWorker(worker: ArriWorker | WorkerHandler): void;
     registerDefinitions(models: DefinitionMap): void;
     getProcedures(): NamedHttpRpc<any, any, any>[];
     getDefinitions(): DefinitionMap;
+    getWorkers(): ArriWorker[];
 }
 declare function defineService(name: string, procedures?: Record<string, HttpRpc<any, any, any>>): ArriService;
 
@@ -207,9 +221,15 @@ declare class ArriApp {
     private readonly _rpcDefinitionPath;
     private readonly _rpcRoutePrefix;
     appInfo: AppDefinition['info'];
-    private _procedures;
+    private readonly _procedures;
     private _definitions;
     private readonly _middlewares;
+    private readonly _workers;
+    private readonly _onStartHooks;
+    private readonly _onStopHooks;
+    private readonly _workerErrorHooks;
+    private _abortController;
+    private _isRunning;
     private readonly _onRequest;
     private readonly _onAfterResponse;
     private readonly _onBeforeResponse;
@@ -225,6 +245,15 @@ declare class ArriApp {
     route<TPath extends string, TQuery extends AObjectSchema<any, any>, TBody extends ASchema<any>, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>): void;
     registerDefinitions(definitions: DefinitionMap): void;
     getAppDefinition(): AppDefinition;
+    registerWorker(worker: ArriWorker | WorkerHandler): void;
+    onStart(hook: () => Promise<void> | void): void;
+    onStop(hook: () => Promise<void> | void): void;
+    onWorkerError(hook: WorkerErrorHandler): void;
+    private _handleWorkerError;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    get workers(): ArriWorker[];
+    get isRunning(): boolean;
 }
 interface ArriOptions {
     debug?: boolean;
@@ -245,10 +274,13 @@ interface ArriOptions {
     onAfterResponse?: (event: RequestHookEvent) => void | Promise<void>;
     onBeforeResponse?: (event: RequestHookEvent) => void | Promise<void>;
     onError?: (error: arriError, event: RequestHookEvent) => void | Promise<void>;
+    onStart?: () => Promise<void> | void;
+    onStop?: () => Promise<void> | void;
+    onWorkerError?: WorkerErrorHandler;
 }
 interface RequestHookEvent extends Omit<H3Event, 'context'> {
     context: RequestHookContext;
 }
 
-export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };
-export type { ArriEventContext, ArriOptions, ArriRoute, DefinitionMap, EventStreamConnectionOptions, EventStreamRpc, EventStreamRpcHandler, EventStreamRpcHandlerContext, ExtractParam, ExtractParams, HttpRpc, Middleware, MiddlewareEvent, MiddlewareEventContext, NamedHttpRpc, PostRouteEvent, RequestHookContext, RequestHookEvent, RequestValidator, RouteEvent, RouteEventContext, RouteOptions, RoutePostEventContext, Rpc, RpcEvent, RpcEventContext, RpcHandler, RpcParamSchema, RpcPostEvent, RpcPostEventContext, RpcPostHandler, SsePushResult };
+export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, defineWorker, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, isWorker, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };
+export type { ArriEventContext, ArriOptions, ArriRoute, ArriWorker, DefinitionMap, EventStreamConnectionOptions, EventStreamRpc, EventStreamRpcHandler, EventStreamRpcHandlerContext, ExtractParam, ExtractParams, HttpRpc, Middleware, MiddlewareEvent, MiddlewareEventContext, NamedHttpRpc, PostRouteEvent, RequestHookContext, RequestHookEvent, RequestValidator, RouteEvent, RouteEventContext, RouteOptions, RoutePostEventContext, Rpc, RpcEvent, RpcEventContext, RpcHandler, RpcParamSchema, RpcPostEvent, RpcPostEventContext, RpcPostHandler, SsePushResult, WorkerErrorHandler, WorkerHandler };

package/dist/index.d.mts

@@ -186,15 +186,29 @@ type RequestValidator<T = any> = {
 declare function getSchemaValidator<T extends Record<string, any> = any>(rpcName: string, type: 'params' | 'response', schema: RpcParamSchema<T>): RequestValidator<T> | undefined;
 declare function getSchemaName(rpcName: string, type: 'params' | 'response', schema: RpcParamSchema<any>): string;
 
+type WorkerHandler = (signal: AbortSignal) => Promise<void> | void;
+type WorkerErrorHandler = (error: unknown, worker: ArriWorker) => void | Promise<void>;
+interface ArriWorker {
+    name?: string;
+    start: (signal: AbortSignal) => Promise<void> | void;
+    stop?: () => Promise<void> | void;
+    onError?: (error: unknown) => void | Promise<void>;
+}
+declare function defineWorker(worker: ArriWorker | WorkerHandler): ArriWorker;
+declare function isWorker(input: unknown): input is ArriWorker;
+
 declare class ArriService {
     name: string;
     constructor(name: string);
     private readonly procedures;
     private readonly definitions;
+    private readonly workers;
     rpc(name: string, procedure: Rpc<any, any, any>): void;
+    registerWorker(worker: ArriWorker | WorkerHandler): void;
     registerDefinitions(models: DefinitionMap): void;
     getProcedures(): NamedHttpRpc<any, any, any>[];
     getDefinitions(): DefinitionMap;
+    getWorkers(): ArriWorker[];
 }
 declare function defineService(name: string, procedures?: Record<string, HttpRpc<any, any, any>>): ArriService;
 
@@ -207,9 +221,15 @@ declare class ArriApp {
     private readonly _rpcDefinitionPath;
     private readonly _rpcRoutePrefix;
     appInfo: AppDefinition['info'];
-    private _procedures;
+    private readonly _procedures;
     private _definitions;
     private readonly _middlewares;
+    private readonly _workers;
+    private readonly _onStartHooks;
+    private readonly _onStopHooks;
+    private readonly _workerErrorHooks;
+    private _abortController;
+    private _isRunning;
     private readonly _onRequest;
     private readonly _onAfterResponse;
     private readonly _onBeforeResponse;
@@ -225,6 +245,15 @@ declare class ArriApp {
     route<TPath extends string, TQuery extends AObjectSchema<any, any>, TBody extends ASchema<any>, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>): void;
     registerDefinitions(definitions: DefinitionMap): void;
     getAppDefinition(): AppDefinition;
+    registerWorker(worker: ArriWorker | WorkerHandler): void;
+    onStart(hook: () => Promise<void> | void): void;
+    onStop(hook: () => Promise<void> | void): void;
+    onWorkerError(hook: WorkerErrorHandler): void;
+    private _handleWorkerError;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    get workers(): ArriWorker[];
+    get isRunning(): boolean;
 }
 interface ArriOptions {
     debug?: boolean;
@@ -245,10 +274,13 @@ interface ArriOptions {
     onAfterResponse?: (event: RequestHookEvent) => void | Promise<void>;
     onBeforeResponse?: (event: RequestHookEvent) => void | Promise<void>;
     onError?: (error: arriError, event: RequestHookEvent) => void | Promise<void>;
+    onStart?: () => Promise<void> | void;
+    onStop?: () => Promise<void> | void;
+    onWorkerError?: WorkerErrorHandler;
 }
 interface RequestHookEvent extends Omit<H3Event, 'context'> {
     context: RequestHookContext;
 }
 
-export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };
-export type { ArriEventContext, ArriOptions, ArriRoute, DefinitionMap, EventStreamConnectionOptions, EventStreamRpc, EventStreamRpcHandler, EventStreamRpcHandlerContext, ExtractParam, ExtractParams, HttpRpc, Middleware, MiddlewareEvent, MiddlewareEventContext, NamedHttpRpc, PostRouteEvent, RequestHookContext, RequestHookEvent, RequestValidator, RouteEvent, RouteEventContext, RouteOptions, RoutePostEventContext, Rpc, RpcEvent, RpcEventContext, RpcHandler, RpcParamSchema, RpcPostEvent, RpcPostEventContext, RpcPostHandler, SsePushResult };
+export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, defineWorker, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, isWorker, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };
+export type { ArriEventContext, ArriOptions, ArriRoute, ArriWorker, DefinitionMap, EventStreamConnectionOptions, EventStreamRpc, EventStreamRpcHandler, EventStreamRpcHandlerContext, ExtractParam, ExtractParams, HttpRpc, Middleware, MiddlewareEvent, MiddlewareEventContext, NamedHttpRpc, PostRouteEvent, RequestHookContext, RequestHookEvent, RequestValidator, RouteEvent, RouteEventContext, RouteOptions, RoutePostEventContext, Rpc, RpcEvent, RpcEventContext, RpcHandler, RpcParamSchema, RpcPostEvent, RpcPostEventContext, RpcPostHandler, SsePushResult, WorkerErrorHandler, WorkerHandler };

package/dist/index.d.ts

@@ -186,15 +186,29 @@ type RequestValidator<T = any> = {
 declare function getSchemaValidator<T extends Record<string, any> = any>(rpcName: string, type: 'params' | 'response', schema: RpcParamSchema<T>): RequestValidator<T> | undefined;
 declare function getSchemaName(rpcName: string, type: 'params' | 'response', schema: RpcParamSchema<any>): string;
 
+type WorkerHandler = (signal: AbortSignal) => Promise<void> | void;
+type WorkerErrorHandler = (error: unknown, worker: ArriWorker) => void | Promise<void>;
+interface ArriWorker {
+    name?: string;
+    start: (signal: AbortSignal) => Promise<void> | void;
+    stop?: () => Promise<void> | void;
+    onError?: (error: unknown) => void | Promise<void>;
+}
+declare function defineWorker(worker: ArriWorker | WorkerHandler): ArriWorker;
+declare function isWorker(input: unknown): input is ArriWorker;
+
 declare class ArriService {
     name: string;
     constructor(name: string);
     private readonly procedures;
     private readonly definitions;
+    private readonly workers;
     rpc(name: string, procedure: Rpc<any, any, any>): void;
+    registerWorker(worker: ArriWorker | WorkerHandler): void;
     registerDefinitions(models: DefinitionMap): void;
     getProcedures(): NamedHttpRpc<any, any, any>[];
     getDefinitions(): DefinitionMap;
+    getWorkers(): ArriWorker[];
 }
 declare function defineService(name: string, procedures?: Record<string, HttpRpc<any, any, any>>): ArriService;
 
@@ -207,9 +221,15 @@ declare class ArriApp {
     private readonly _rpcDefinitionPath;
     private readonly _rpcRoutePrefix;
     appInfo: AppDefinition['info'];
-    private _procedures;
+    private readonly _procedures;
     private _definitions;
     private readonly _middlewares;
+    private readonly _workers;
+    private readonly _onStartHooks;
+    private readonly _onStopHooks;
+    private readonly _workerErrorHooks;
+    private _abortController;
+    private _isRunning;
     private readonly _onRequest;
     private readonly _onAfterResponse;
     private readonly _onBeforeResponse;
@@ -225,6 +245,15 @@ declare class ArriApp {
     route<TPath extends string, TQuery extends AObjectSchema<any, any>, TBody extends ASchema<any>, TResponse = any>(route: ArriRoute<TPath, TQuery, TBody, TResponse>): void;
     registerDefinitions(definitions: DefinitionMap): void;
     getAppDefinition(): AppDefinition;
+    registerWorker(worker: ArriWorker | WorkerHandler): void;
+    onStart(hook: () => Promise<void> | void): void;
+    onStop(hook: () => Promise<void> | void): void;
+    onWorkerError(hook: WorkerErrorHandler): void;
+    private _handleWorkerError;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    get workers(): ArriWorker[];
+    get isRunning(): boolean;
 }
 interface ArriOptions {
     debug?: boolean;
@@ -245,10 +274,13 @@ interface ArriOptions {
     onAfterResponse?: (event: RequestHookEvent) => void | Promise<void>;
     onBeforeResponse?: (event: RequestHookEvent) => void | Promise<void>;
     onError?: (error: arriError, event: RequestHookEvent) => void | Promise<void>;
+    onStart?: () => Promise<void> | void;
+    onStop?: () => Promise<void> | void;
+    onWorkerError?: WorkerErrorHandler;
 }
 interface RequestHookEvent extends Omit<H3Event, 'context'> {
     context: RequestHookContext;
 }
 
-export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };
-export type { ArriEventContext, ArriOptions, ArriRoute, DefinitionMap, EventStreamConnectionOptions, EventStreamRpc, EventStreamRpcHandler, EventStreamRpcHandlerContext, ExtractParam, ExtractParams, HttpRpc, Middleware, MiddlewareEvent, MiddlewareEventContext, NamedHttpRpc, PostRouteEvent, RequestHookContext, RequestHookEvent, RequestValidator, RouteEvent, RouteEventContext, RouteOptions, RoutePostEventContext, Rpc, RpcEvent, RpcEventContext, RpcHandler, RpcParamSchema, RpcPostEvent, RpcPostEventContext, RpcPostHandler, SsePushResult };
+export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, defineWorker, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, isWorker, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };
+export type { ArriEventContext, ArriOptions, ArriRoute, ArriWorker, DefinitionMap, EventStreamConnectionOptions, EventStreamRpc, EventStreamRpcHandler, EventStreamRpcHandlerContext, ExtractParam, ExtractParams, HttpRpc, Middleware, MiddlewareEvent, MiddlewareEventContext, NamedHttpRpc, PostRouteEvent, RequestHookContext, RequestHookEvent, RequestValidator, RouteEvent, RouteEventContext, RouteOptions, RoutePostEventContext, Rpc, RpcEvent, RpcEventContext, RpcHandler, RpcParamSchema, RpcPostEvent, RpcPostEventContext, RpcPostHandler, SsePushResult, WorkerErrorHandler, WorkerHandler };

package/dist/index.mjs

@@ -803,6 +803,18 @@ class ArriRouter {
   }
 }
 
+function defineWorker(worker) {
+  if (typeof worker === "function") {
+    return {
+      start: worker
+    };
+  }
+  return worker;
+}
+function isWorker(input) {
+  return typeof input === "object" && input !== null && "start" in input && typeof input.start === "function";
+}
+
 class ArriService {
   name;
   constructor(name) {
@@ -810,10 +822,14 @@ class ArriService {
   }
   procedures = [];
   definitions = {};
+  workers = [];
   rpc(name, procedure) {
     procedure.name = `${this.name}.${name}`;
     this.procedures.push(procedure);
   }
+  registerWorker(worker) {
+    this.workers.push(defineWorker(worker));
+  }
   registerDefinitions(models) {
     for (const key of Object.keys(models)) {
       this.definitions[key] = models[key];
@@ -825,6 +841,9 @@ class ArriService {
   getDefinitions() {
     return this.definitions;
   }
+  getWorkers() {
+    return this.workers;
+  }
 }
 function defineService(name, procedures) {
   const service = new ArriService(name);
@@ -845,6 +864,12 @@ class ArriApp {
   _procedures = {};
   _definitions = {};
   _middlewares = [];
+  _workers = [];
+  _onStartHooks = [];
+  _onStopHooks = [];
+  _workerErrorHooks = [];
+  _abortController = null;
+  _isRunning = false;
   _onRequest;
   _onAfterResponse;
   _onBeforeResponse;
@@ -862,6 +887,15 @@ class ArriApp {
     this._onError = opts.onError;
     this._onAfterResponse = opts.onAfterResponse;
     this._onBeforeResponse = opts.onBeforeResponse;
+    if (opts.onStart) {
+      this.onStart(opts.onStart);
+    }
+    if (opts.onStop) {
+      this.onStop(opts.onStop);
+    }
+    if (opts.onWorkerError) {
+      this.onWorkerError(opts.onWorkerError);
+    }
     this._heartbeatMs = opts.heartbeatMs ?? 2e4;
     this._rpcRoutePrefix = opts?.rpcRoutePrefix ?? "";
     this._rpcDefinitionPath = opts?.rpcDefinitionPath ?? "__definition";
@@ -936,6 +970,9 @@ class ArriApp {
         this.rpc(rpc.name, rpc);
       }
       this.registerDefinitions(input.getDefinitions());
+      for (const worker of input.getWorkers()) {
+        this.registerWorker(worker);
+      }
       return;
     }
     this._middlewares.push(input);
@@ -1011,8 +1048,120 @@ class ArriApp {
     }
     return appDef;
   }
+  registerWorker(worker) {
+    const w = defineWorker(worker);
+    this._workers.push(w);
+    if (this._isRunning && this._abortController) {
+      void (async () => {
+        try {
+          await w.start(this._abortController.signal);
+        } catch (err) {
+          await this._handleWorkerError(w, err);
+        }
+      })();
+    }
+  }
+  onStart(hook) {
+    this._onStartHooks.push(hook);
+  }
+  onStop(hook) {
+    this._onStopHooks.push(hook);
+  }
+  onWorkerError(hook) {
+    this._workerErrorHooks.push(hook);
+  }
+  async _handleWorkerError(worker, error) {
+    let handled = false;
+    if (worker.onError) {
+      try {
+        await worker.onError(error);
+        handled = true;
+      } catch (hookErr) {
+        console.error(
+          `[Arri] Error in worker.onError hook for worker ${worker.name ?? "unnamed"}:`,
+          hookErr
+        );
+      }
+    }
+    for (const hook of this._workerErrorHooks) {
+      try {
+        await hook(error, worker);
+        handled = true;
+      } catch (hookErr) {
+        console.error(
+          `[Arri] Error in onWorkerError hook for worker ${worker.name ?? "unnamed"}:`,
+          hookErr
+        );
+      }
+    }
+    if (!handled) {
+      console.error(
+        `[Arri] Unhandled error in worker ${worker.name ?? "unnamed"}:`,
+        error
+      );
+    }
+  }
+  async start() {
+    if (this._isRunning) {
+      return;
+    }
+    this._isRunning = true;
+    const controller = new AbortController();
+    this._abortController = controller;
+    try {
+      for (const hook of this._onStartHooks) {
+        await hook();
+      }
+    } catch (err) {
+      this._isRunning = false;
+      controller.abort();
+      this._abortController = null;
+      throw err;
+    }
+    for (const worker of this._workers) {
+      void (async () => {
+        try {
+          await worker.start(controller.signal);
+        } catch (err) {
+          await this._handleWorkerError(worker, err);
+        }
+      })();
+    }
+  }
+  async stop() {
+    if (!this._isRunning) {
+      return;
+    }
+    this._isRunning = false;
+    this._abortController?.abort();
+    const stopPromises = this._workers.map(async (worker) => {
+      try {
+        if (worker.stop) {
+          await worker.stop();
+        }
+      } catch (err) {
+        await this._handleWorkerError(worker, err);
+      }
+    });
+    const hookPromises = this._onStopHooks.map(async (hook) => {
+      try {
+        await hook();
+      } catch (err) {
+        if (this._debug) {
+          console.error("Error in onStop hook:", err);
+        }
+      }
+    });
+    await Promise.allSettled([...stopPromises, ...hookPromises]);
+  }
+  get workers() {
+    return [...this._workers];
+  }
+  get isRunning() {
+    return this._isRunning;
+  }
 }
 
 const defineMiddleware = (middleware) => middleware;
 
-export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };
+export { ArriApp, ArriRouter, ArriService, EventStreamConnection, arriError, arriErrorResponse, createAppDefinition, createHttpRpcDefinition, defineError, defineEventStreamRpc, defineMiddleware, defineRoute, defineRpc, defineService, defineWorker, errorResponseFromValidationErrors, getRpcParamName, getRpcPath, getRpcResponseName, getSchemaName, getSchemaValidator, handleH3Error, handleRoute, isEventStreamRpc, isRpc, isRpcParamSchema, isWorker, registerEventStreamRpc, registerRoute, registerRpc, validateRpcRequestInput };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrirpc/server",
-  "version": "0.84.1",
+  "version": "0.85.0",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -28,9 +28,9 @@
     "scule": "^1.3.0",
     "source-map-support": "^0.5.21",
     "uncrypto": "^0.1.3",
-    "@arrirpc/codegen-utils": "0.84.1",
-    "@arrirpc/schema": "0.84.1",
-    "arri": "0.84.1"
+    "@arrirpc/codegen-utils": "0.85.0",
+    "@arrirpc/schema": "0.85.0",
+    "arri": "0.85.0"
   },
   "devDependencies": {
     "bun-types": "^1.3.8"