@firtoz/worker-helper 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @firtoz/worker-helper
 
+## 1.1.0
+
+### Minor Changes
+
+- [`b0f7893`](https://github.com/firtoz/fullstack-toolkit/commit/b0f789314c4ee85d8c08466b968baad2977a2581) Thanks [@firtoz](https://github.com/firtoz)! - Added cf-typegen script utility for generating Cloudflare Workers TypeScript types
+
+  - Added cf-typegen script that runs wrangler types command for specified worker directory
+  - Utility used by test packages to generate worker-configuration.d.ts
+  - Simplified type generation workflow for Cloudflare Workers projects
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -6,19 +6,79 @@ Type-safe Web Worker helper with Zod validation for input and output messages. T
 
 ## Features
 
+### Web Workers
+
 - 🔒 **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
 
+### Cloudflare Workers
+
+- 🔧 **cf-typegen**: Automatic `.env.local` creation from `wrangler.jsonc` vars
+- 📝 **Type Generation**: Wrapper around `wrangler types` with env preparation
+
 ## Installation
 
 ```bash
 bun add @firtoz/worker-helper zod
 ```
 
-## Usage
+## cf-typegen (Cloudflare Workers Utility)
+
+Automatic TypeScript type generation and `.env.local` management for Cloudflare Workers projects.
+
+### Setup
+
+Add the script to your Cloudflare Workers package:
+
+```json
+{
+  "scripts": {
+    "cf-typegen": "bun --cwd ../../packages/worker-helper cf-typegen $(pwd)"
+  }
+}
+```
+
+### What It Does
+
+1. **Reads `.env.local.example`** to find required env vars
+2. **Creates/updates `.env.local`** with any missing vars (as empty strings)
+3. **Runs `wrangler types`** to generate TypeScript definitions
+
+### Example
+
+```bash
+cd your-worker-package
+bun run cf-typegen
+```
+
+**Output:**
+```
+Running CF typegen for: /path/to/your-worker
+✓ Added missing env vars: OPENROUTER_API_KEY, DATABASE_URL
+Running wrangler types...
+✓ Wrangler types generated
+✓ CF typegen completed successfully
+```
+
+**Generated `.env.local`:**
+```env
+OPENROUTER_API_KEY=
+DATABASE_URL=
+```
+
+### Why This Matters
+
+- Ensures `wrangler types` always succeeds (needs `.env.local` or `.dev.vars`)
+- Keeps `.env.local` in sync with `.env.local.example`
+- Avoids accidentally binding empty vars at runtime via `wrangler.jsonc` `vars`
+- Developers can fill in actual values without committing them to git
+- CI/CD can generate types without needing actual secrets
+- `.env.local.example` serves as documentation for required env vars
+
+## Web Worker Usage
 
 ### 1. Define Your Schemas
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@firtoz/worker-helper",
-	"version": "1.0.0",
-	"description": "Type-safe Web Worker helper with Zod validation for input and output messages",
+	"version": "1.1.0",
+	"description": "Type-safe Web Worker helper with Zod validation and Cloudflare Workers utilities (cf-typegen)",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
 	"types": "./src/index.ts",
@@ -28,15 +28,20 @@
 		"lint:ci": "biome ci src",
 		"format": "biome format src --write",
 		"test": "bun test",
-		"test:watch": "bun test --watch"
+		"test:watch": "bun test --watch",
+		"cf-typegen": "bun ./src/cf-typegen.ts"
 	},
 	"keywords": [
 		"typescript",
 		"web-worker",
 		"worker",
+		"cloudflare-workers",
+		"cloudflare",
 		"zod",
 		"validation",
-		"type-safe"
+		"type-safe",
+		"wrangler",
+		"typegen"
 	],
 	"author": "Firtina Ozbalikchi <firtoz@github.com>",
 	"license": "MIT",
@@ -56,11 +61,11 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"zod": "^4.1.12"
+		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@types/node": "^24.10.1",
-		"@firtoz/maybe-error": "^1.5.1",
-		"bun-types": "^1.3.2"
+		"@types/node": "^25.0.9",
+		"@firtoz/maybe-error": "^1.5.2",
+		"bun-types": "^1.3.6"
 	}
 }

package/src/cf-typegen.ts

@@ -0,0 +1,138 @@
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+// Use the current working directory
+const cwd = process.argv[2];
+if (!cwd || !fs.existsSync(cwd)) {
+	console.error(
+		"Please specify a directory as the first parameter. Usually $(pwd).",
+	);
+	process.exit(1);
+}
+
+console.log(`Running CF typegen for: ${cwd}`);
+
+/**
+ * Extracts required env vars from .env.local.example
+ */
+function getRequiredEnvVars(examplePath: string): string[] {
+	try {
+		if (!fs.existsSync(examplePath)) {
+			return [];
+		}
+
+		const content = fs.readFileSync(examplePath, "utf8");
+		const vars: string[] = [];
+
+		// Parse .env format: VAR_NAME=value
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			// Skip comments and empty lines
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=/);
+			if (match) {
+				vars.push(match[1]);
+			}
+		}
+
+		return vars;
+	} catch (err) {
+		console.warn(`Failed to read ${examplePath}:`, err);
+		return [];
+	}
+}
+
+/**
+ * Ensures .env.local exists with required env vars from .env.local.example
+ */
+function prepareEnvLocal(): { created: boolean; added: string[] } {
+	const envPath = path.join(cwd, ".env.local");
+	const examplePath = path.join(cwd, ".env.local.example");
+
+	if (!fs.existsSync(examplePath)) {
+		console.log("No .env.local.example found, skipping env preparation");
+		return { created: false, added: [] };
+	}
+
+	const requiredVars = getRequiredEnvVars(examplePath);
+	if (requiredVars.length === 0) {
+		console.log("No vars found in .env.local.example");
+		return { created: false, added: [] };
+	}
+
+	let content = "";
+	let created = false;
+	const added: string[] = [];
+
+	if (fs.existsSync(envPath)) {
+		content = fs.readFileSync(envPath, "utf8");
+	} else {
+		created = true;
+	}
+
+	// Check which vars are missing
+	for (const varName of requiredVars) {
+		const regex = new RegExp(`^${varName}=`, "m");
+		if (!regex.test(content)) {
+			if (content && !content.endsWith("\n")) {
+				content += "\n";
+			}
+			content += `${varName}=\n`;
+			added.push(varName);
+		}
+	}
+
+	// Write if there were any changes
+	if (created || added.length > 0) {
+		fs.writeFileSync(envPath, content);
+	}
+
+	return { created, added };
+}
+
+// Step 1: Prepare .env.local with required vars from wrangler.jsonc
+function prepareEnv() {
+	try {
+		const updates = prepareEnvLocal();
+		if (updates.created) {
+			console.log("✓ Created .env.local");
+		}
+		if (updates.added.length > 0) {
+			console.log(`✓ Added missing env vars: ${updates.added.join(", ")}`);
+		}
+		if (!updates.created && updates.added.length === 0) {
+			console.log("✓ .env.local file already has all required vars");
+		}
+	} catch (error) {
+		console.error(String(error));
+		process.exit(1);
+	}
+}
+
+// Step 2: Run wrangler types
+function runWranglerTypes() {
+	console.log("Running wrangler types...");
+	try {
+		execSync("wrangler types -c wrangler.jsonc --env-file .env.local", {
+			cwd,
+			stdio: "inherit",
+		});
+		console.log("✓ Wrangler types generated");
+	} catch {
+		console.error("Failed to run wrangler types");
+		process.exit(1);
+	}
+}
+
+// Run all steps
+try {
+	prepareEnv();
+	runWranglerTypes();
+	console.log("\n✓ CF typegen completed successfully");
+} catch (error: unknown) {
+	console.error("\n✗ CF typegen failed:", error);
+	process.exit(1);
+}