feat: centralize application framework primitives

packages/queue/src/worker.ts

@@ -0,0 +1,36 @@
+import type { JobHandler } from "./index.ts";
+import type { DurableQueue } from "./durable.ts";
+
+export interface WorkerDefinition<T> {
+  name: string;
+  handler: JobHandler<T>;
+  onStart?: () => void | Promise<void>;
+  onStop?: () => void | Promise<void>;
+}
+
+export function defineWorker<T>(definition: WorkerDefinition<T>): WorkerDefinition<T> {
+  if (!definition.name.trim()) throw new TypeError("worker name cannot be empty");
+  return Object.freeze({ ...definition });
+}
+
+/** Explicit process lifecycle for queue workers; safe to start and stop repeatedly. */
+export function runWorker<T>(queue: DurableQueue, definition: WorkerDefinition<T>) {
+  let started = false;
+  return {
+    async start() {
+      if (started) return;
+      started = true;
+      queue.process(definition.name, definition.handler);
+      await definition.onStart?.();
+    },
+    async stop(options?: { force?: boolean }) {
+      if (!started) return;
+      started = false;
+      await queue.shutdown(options);
+      await definition.onStop?.();
+    },
+    get running() {
+      return started;
+    },
+  };
+}