@firtoz/worker-helper 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# @firtoz/worker-helper
+
+## 1.0.0
+
+### Major Changes
+
+- [#22](https://github.com/firtoz/fullstack-toolkit/pull/22) [`cf12782`](https://github.com/firtoz/fullstack-toolkit/commit/cf1278236e484e6350eb614ce2381e0afcec326e) Thanks [@firtoz](https://github.com/firtoz)! - Initial release of `@firtoz/worker-helper` - Type-safe Web Worker communication with Zod validation for both client and worker sides.
+
+  > **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
+
+  ## Worker-Side (`WorkerHelper`)
+
+  - **Abstract class pattern** for creating type-safe workers
+  - **Zod validation** for both incoming and outgoing messages
+  - **Mandatory error handlers** give complete control over error handling:
+    - `handleMessage` - Process validated messages
+    - `handleInputValidationError` - Handle input validation failures
+    - `handleOutputValidationError` - Handle output validation failures
+    - `handleProcessingError` - Handle runtime errors
+  - **Full async support** - All handlers support both sync and async operations
+  - **Type-safe `send()` method** - Automatically validates before sending
+  - Uses Bun's global `Worker` and `self` patterns
+
+  ## Client-Side (`WorkerClient`)
+
+  - **Type-safe wrapper** for Worker instances
+  - **Validates messages** sent TO the worker (client → worker)
+  - **Validates messages** received FROM the worker (worker → client)
+  - **Optional callbacks**:
+    - `onMessage` - Receive validated messages
+    - `onValidationError` - Handle validation failures
+    - `onError` - Handle worker errors
+  - **Worker lifecycle management** with `terminate()` and `getWorker()`
+  - Accepts existing Worker instances for maximum flexibility
+
+  ## Features
+
+  - Full TypeScript support with automatic type inference
+  - Works with discriminated unions for type-safe message routing
+  - Comprehensive test suite with 33 tests (18 for WorkerHelper, 15 for WorkerClient)
+  - Tests include async operations, validation errors, and error handling
+  - Uses `.worker.ts` extension convention for worker files
+  - Zero dependencies except Zod
+  - Built for Bun's Worker API
+
+  ## Example
+
+  ```typescript
+  // Define schemas
+  const InputSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("add"), a: z.number(), b: z.number() }),
+  ]);
+
+  const OutputSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("result"), value: z.number() }),
+  ]);
+
+  // Worker side (worker.worker.ts)
+  declare var self: Worker;
+
+  class MyWorker extends WorkerHelper<Input, Output> {
+    constructor() {
+      super(self, InputSchema, OutputSchema, {
+        handleMessage: (data) => {
+          if (data.type === "add") {
+            this.send({ type: "result", value: data.a + data.b });
+          }
+        },
+        handleInputValidationError: (error, originalData) => {
+          console.error("Invalid input:", error);
+        },
+        // ... other handlers
+      });
+    }
+  }
+
+  new MyWorker();
+
+  // Client side
+  const worker = new Worker(
+    new URL("./worker.worker.ts", import.meta.url).href
+  );
+
+  const client = new WorkerClient({
+    worker,
+    clientSchema: InputSchema,
+    serverSchema: OutputSchema,
+    onMessage: (msg) => console.log("Result:", msg.value),
+  });
+
+  client.send({ type: "add", a: 5, b: 3 }); // Type-safe!
+  ```

package/README.md

@@ -0,0 +1,337 @@
+# @firtoz/worker-helper
+
+Type-safe Web Worker helper with Zod validation for input and output messages. This package provides a simple way to create type-safe Web Workers with automatic validation of messages sent between the main thread and worker threads.
+
+> **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
+
+## Features
+
+- 🔒 **Type-safe**: Full TypeScript support with automatic type inference
+- ✅ **Zod Validation**: Automatic validation of both input and output messages
+- 🎯 **Custom Error Handlers**: Mandatory error handlers give you complete control over error handling
+- 🔄 **Async Support**: Built-in support for async message handlers
+- 🧩 **Discriminated Unions**: Works great with Zod's discriminated unions for type-safe message routing
+
+## Installation
+
+```bash
+bun add @firtoz/worker-helper zod
+```
+
+## Usage
+
+### 1. Define Your Schemas
+
+First, define Zod schemas for your input and output messages:
+
+```typescript
+import { z } from "zod";
+
+const InputSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("add"),
+    a: z.number(),
+    b: z.number(),
+  }),
+  z.object({
+    type: z.literal("multiply"),
+    a: z.number(),
+    b: z.number(),
+  }),
+]);
+
+const OutputSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("result"),
+    value: z.number(),
+  }),
+  z.object({
+    type: z.literal("error"),
+    message: z.string(),
+  }),
+]);
+
+type Input = z.infer<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+```
+
+### 2. Create Your Worker
+
+Create a worker file (e.g., `worker.ts`):
+
+```typescript
+import { WorkerHelper } from "@firtoz/worker-helper";
+import { InputSchema, OutputSchema, type Input, type Output } from "./schemas";
+
+// Declare self as Worker for TypeScript
+declare var self: Worker;
+
+new WorkerHelper<Input, Output>(self, InputSchema, OutputSchema, {
+  // Handle validated messages
+  handleMessage: (data, send) => {
+    switch (data.type) {
+      case "add":
+        send({
+          type: "result",
+          value: data.a + data.b,
+        });
+        break;
+
+      case "multiply":
+        send({
+          type: "result",
+          value: data.a * data.b,
+        });
+        break;
+    }
+  },
+
+  // Handle input validation errors
+  handleInputValidationError: (error, originalData) => {
+    console.error("Invalid input received:", error);
+    self.postMessage({
+      type: "error",
+      message: `Invalid input: ${error.message}`,
+    });
+  },
+
+  // Handle output validation errors
+  handleOutputValidationError: (error, originalData) => {
+    console.error("Invalid output attempted:", error);
+    self.postMessage({
+      type: "error",
+      message: `Internal error: invalid output`,
+    });
+  },
+
+  // Handle processing errors
+  handleProcessingError: (error, validatedData) => {
+    console.error("Processing error:", error);
+    const message = error instanceof Error ? error.message : String(error);
+    self.postMessage({
+      type: "error",
+      message: `Processing failed: ${message}`,
+    });
+  },
+});
+```
+
+### 3. Use Your Worker
+
+In your main thread:
+
+```typescript
+// Worker is a global in Bun, no need to import
+const worker = new Worker(new URL("./worker.ts", import.meta.url).href);
+
+// Send a message
+worker.postMessage({
+  type: "add",
+  a: 5,
+  b: 3,
+});
+
+// Receive messages
+worker.on("message", (result) => {
+  if (result.type === "result") {
+    console.log("Result:", result.value); // 8
+  } else if (result.type === "error") {
+    console.error("Error:", result.message);
+  }
+});
+
+// Clean up
+worker.on("exit", () => {
+  console.log("Worker exited");
+});
+```
+
+## API
+
+### `WorkerHelper<TInput, TOutput>`
+
+The main class that manages worker message handling with validation.
+
+#### Constructor Parameters
+
+- `self: MessageTarget` - The worker's `self` object (or `parentPort` for Node.js compatibility)
+- `inputSchema: ZodType<TInput>` - Zod schema for validating incoming messages
+- `outputSchema: ZodType<TOutput>` - Zod schema for validating outgoing messages
+- `handlers: WorkerHelperHandlers<TInput, TOutput>` - Object containing all message and error handlers
+
+### `WorkerHelperHandlers<TInput, TOutput>`
+
+Interface defining all required handlers:
+
+```typescript
+type WorkerHelperHandlers<TInput, TOutput> = {
+  // Handle validated messages
+  handleMessage: (
+    data: TInput,
+    send: (response: TOutput) => void,
+  ) => void | Promise<void>;
+
+  // Handle input validation errors
+  handleInputValidationError: (
+    error: ZodError<TInput>,
+    originalData: unknown,
+  ) => void | Promise<void>;
+
+  // Handle output validation errors
+  handleOutputValidationError: (
+    error: ZodError<TOutput>,
+    originalData: TOutput,
+  ) => void | Promise<void>;
+
+  // Handle processing errors (exceptions thrown in handleMessage)
+  handleProcessingError: (
+    error: unknown,
+    validatedData: TInput,
+  ) => void | Promise<void>;
+};
+```
+
+## Advanced Usage
+
+### Async Message Handling
+
+All handlers support both synchronous and asynchronous operations:
+
+```typescript
+new WorkerHelper<Input, Output>(self, InputSchema, OutputSchema, {
+  handleMessage: async (data, send) => {
+    // Perform async operations
+    const result = await someAsyncOperation(data);
+    send(result);
+  },
+
+  handleInputValidationError: async (error, originalData) => {
+    // Log to remote service
+    await logError(error);
+    self.postMessage({ type: "error", message: "Invalid input" });
+  },
+
+  // ... other handlers
+});
+```
+
+### Complex Message Types
+
+Use discriminated unions for type-safe message routing:
+
+```typescript
+const InputSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("compute"),
+    operation: z.enum(["add", "subtract", "multiply", "divide"]),
+    operands: z.array(z.number()),
+  }),
+  z.object({
+    type: z.literal("status"),
+  }),
+  z.object({
+    type: z.literal("config"),
+    settings: z.record(z.string(), z.unknown()),
+  }),
+]);
+
+// TypeScript will narrow the type based on the discriminator
+handleMessage: (data, send) => {
+  switch (data.type) {
+    case "compute":
+      // data is narrowed to { type: "compute", operation: ..., operands: ... }
+      break;
+    case "status":
+      // data is narrowed to { type: "status" }
+      break;
+    case "config":
+      // data is narrowed to { type: "config", settings: ... }
+      break;
+  }
+};
+```
+
+### Custom Error Responses
+
+You have full control over how errors are communicated back to the main thread:
+
+```typescript
+handleInputValidationError: (error, originalData) => {
+  // Send structured error response
+  self.postMessage({
+    type: "error",
+    code: "VALIDATION_ERROR",
+    details: error.issues,
+    timestamp: Date.now(),
+  });
+},
+
+handleProcessingError: (error, validatedData) => {
+  // Send error with context
+  self.postMessage({
+    type: "error",
+    code: "PROCESSING_ERROR",
+    message: error instanceof Error ? error.message : String(error),
+    input: validatedData.type, // Include relevant context
+  });
+},
+```
+
+## Error Handling
+
+The WorkerHelper validates messages at three key points:
+
+1. **Input Validation**: Before your handler receives a message, it's validated against the input schema. If validation fails, `handleInputValidationError` is called.
+
+2. **Output Validation**: Before a message is sent from the worker, it's validated against the output schema. If validation fails, `handleOutputValidationError` is called.
+
+3. **Processing Errors**: If your `handleMessage` handler throws an error, `handleProcessingError` is called.
+
+All error handlers are **mandatory**, ensuring you handle all error cases explicitly.
+
+## Best Practices
+
+1. **Use Discriminated Unions**: They provide type-safe message routing and better error messages.
+
+2. **Keep Schemas Strict**: Use strict schemas to catch errors early.
+
+3. **Log Errors Appropriately**: Use error handlers to log errors to your monitoring system.
+
+4. **Don't Swallow Errors**: Always communicate errors back to the main thread in some form.
+
+5. **Test Error Cases**: Use the error handlers to test how your application handles invalid inputs and processing errors.
+
+## Testing
+
+The package includes comprehensive tests. Run them with:
+
+```bash
+bun test
+```
+
+See the test files for examples of testing workers with different scenarios:
+- Valid message handling
+- Input validation errors
+- Output validation errors
+- Processing errors
+- Async operations
+- Edge cases
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Related Packages
+
+- [@firtoz/maybe-error](../maybe-error) - Type-safe error handling pattern
+- [@firtoz/hono-fetcher](../hono-fetcher) - Type-safe Hono API client
+- [@firtoz/websocket-do](../websocket-do) - Type-safe WebSocket Durable Objects
+
+## Support
+
+For issues and questions, please file an issue on [GitHub](https://github.com/firtoz/fullstack-toolkit/issues).
+

package/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "@firtoz/worker-helper",
+	"version": "1.0.0",
+	"description": "Type-safe Web Worker helper with Zod validation for input and output messages",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"require": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"import": "./src/*.ts",
+			"require": "./src/*.ts"
+		}
+	},
+	"files": [
+		"src/**/*.ts",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"lint": "biome check --write src",
+		"lint:ci": "biome ci src",
+		"format": "biome format src --write",
+		"test": "bun test",
+		"test:watch": "bun test --watch"
+	},
+	"keywords": [
+		"typescript",
+		"web-worker",
+		"worker",
+		"zod",
+		"validation",
+		"type-safe"
+	],
+	"author": "Firtina Ozbalikchi <firtoz@github.com>",
+	"license": "MIT",
+	"homepage": "https://github.com/firtoz/fullstack-toolkit#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/firtoz/fullstack-toolkit.git",
+		"directory": "packages/worker-helper"
+	},
+	"bugs": {
+		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"zod": "^4.1.12"
+	},
+	"devDependencies": {
+		"@types/node": "^24.10.1",
+		"@firtoz/maybe-error": "^1.5.1",
+		"bun-types": "^1.3.2"
+	}
+}

package/src/WorkerClient.ts

@@ -0,0 +1,92 @@
+import type { ZodType } from "zod/v4";
+
+export interface WorkerClientOptions<TClientMessage, TServerMessage> {
+	/**
+	 * Worker instance to wrap
+	 */
+	worker: Worker;
+	/**
+	 * Schema for validating messages sent to the worker
+	 */
+	clientSchema: ZodType<TClientMessage>;
+	/**
+	 * Schema for validating messages received from the worker
+	 */
+	serverSchema: ZodType<TServerMessage>;
+	/**
+	 * Callback for validated messages from the worker
+	 */
+	onMessage?: (message: TServerMessage) => void;
+	/**
+	 * Callback for when validation fails on incoming messages
+	 */
+	onValidationError?: (error: Error, rawMessage: unknown) => void;
+	/**
+	 * Callback for worker errors
+	 */
+	onError?: (event: ErrorEvent) => void;
+}
+
+export class WorkerClient<TClientMessage, TServerMessage> {
+	private worker: Worker;
+	private readonly clientSchema: ZodType<TClientMessage>;
+	private readonly serverSchema: ZodType<TServerMessage>;
+	private readonly onMessageCallback?: (message: TServerMessage) => void;
+	private readonly onValidationErrorCallback?: (
+		error: Error,
+		rawMessage: unknown,
+	) => void;
+
+	constructor(options: WorkerClientOptions<TClientMessage, TServerMessage>) {
+		this.clientSchema = options.clientSchema;
+		this.serverSchema = options.serverSchema;
+		this.onMessageCallback = options.onMessage;
+		this.onValidationErrorCallback = options.onValidationError;
+		this.worker = options.worker;
+
+		// Setup event handlers
+		this.worker.addEventListener("message", (event: MessageEvent) => {
+			this.handleMessage(event);
+		});
+
+		if (options.onError) {
+			this.worker.addEventListener("error", options.onError);
+		}
+	}
+
+	private handleMessage(event: MessageEvent): void {
+		try {
+			// Validate the incoming message
+			const validatedMessage = this.serverSchema.parse(event.data);
+			this.onMessageCallback?.(validatedMessage);
+		} catch (error) {
+			// Validation failed
+			const validationError =
+				error instanceof Error ? error : new Error(String(error));
+			this.onValidationErrorCallback?.(validationError, event.data);
+		}
+	}
+
+	/**
+	 * Send a message to the worker with validation
+	 */
+	public send(message: TClientMessage): void {
+		// Validate the outgoing message
+		const validatedMessage = this.clientSchema.parse(message);
+		this.worker.postMessage(validatedMessage);
+	}
+
+	/**
+	 * Terminate the worker
+	 */
+	public terminate(): void {
+		this.worker.terminate();
+	}
+
+	/**
+	 * Get the underlying Worker instance
+	 */
+	public getWorker(): Worker {
+		return this.worker;
+	}
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {
+	WorkerClient,
+	type WorkerClientOptions,
+} from "./WorkerClient";
+export { WorkerHelper, type WorkerHelperHandlers } from "./worker-helper";

package/src/worker-helper.ts

@@ -0,0 +1,71 @@
+import type { ZodError, ZodType } from "zod/v4";
+
+type MessageTarget = DedicatedWorkerGlobalScope;
+
+export type WorkerHelperHandlers<TInput, TOutput> = {
+	handleMessage: (data: TInput) => void | Promise<void>;
+	handleInputValidationError: (
+		error: ZodError<TInput>,
+		originalData: unknown,
+	) => void | Promise<void>;
+	handleOutputValidationError: (
+		error: ZodError<TOutput>,
+		originalData: TOutput,
+	) => void | Promise<void>;
+	handleProcessingError: (
+		error: unknown,
+		validatedData: TInput,
+	) => void | Promise<void>;
+};
+
+export abstract class WorkerHelper<TInput, TOutput> {
+	constructor(
+		private self: MessageTarget,
+		private inputSchema: ZodType<TInput>,
+		private outputSchema: ZodType<TOutput>,
+		private handlers: WorkerHelperHandlers<TInput, TOutput>,
+	) {
+		this.setupMessageListener();
+	}
+
+	protected send = (response: TOutput) => {
+		// Validate output before sending
+		const outputValidation = this.outputSchema.safeParse(response);
+		if (!outputValidation.success) {
+			this.handlers.handleOutputValidationError(
+				outputValidation.error,
+				response,
+			);
+			return;
+		}
+
+		// Send as success response
+		this.self.postMessage(response);
+	};
+
+	private setupMessageListener(): void {
+		this.self.addEventListener("message", (event: MessageEvent) => {
+			this.handleMessage(event);
+		});
+	}
+
+	private async handleMessage(event: MessageEvent): Promise<void> {
+		// Validate input using safeParse
+		const validationResult = this.inputSchema.safeParse(event.data);
+
+		if (!validationResult.success) {
+			await this.handlers.handleInputValidationError(
+				validationResult.error,
+				event.data,
+			);
+			return;
+		}
+
+		// Handle the validated message
+		try {
+			await this.handlers.handleMessage(validationResult.data);
+		} catch (error) {
+			await this.handlers.handleProcessingError(error, validationResult.data);
+		}
+	}
+}