@firtoz/worker-helper 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @firtoz/worker-helper
 
+## 1.2.0
+
+### Minor Changes
+
+- [`2725815`](https://github.com/firtoz/fullstack-toolkit/commit/27258158dd318b34b44ed77b88b2ac9b2b4b6a3d) Thanks [@firtoz](https://github.com/firtoz)! - Improved workspace-wide type generation and environment setup
+
+  - Refactored `cf-typegen.ts` to automatically discover all wrangler configs using `git ls-files`
+  - Uses git for workspace discovery - fast, respects .gitignore, and finds all tracked configs
+  - Added `prepareEnvFiles` utility to handle .env file creation from .env.example templates
+  - Type generation now includes bindings from all workspace projects for better DX
+
+## 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.2.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.6"
 	},
 	"devDependencies": {
-		"@types/node": "^24.10.1",
-		"@firtoz/maybe-error": "^1.5.1",
-		"bun-types": "^1.3.2"
+		"@types/node": "^25.0.10",
+		"@firtoz/maybe-error": "^1.5.2",
+		"bun-types": "^1.3.6"
 	}
 }

package/src/cf-typegen.ts

@@ -0,0 +1,126 @@
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { prepareEnvFiles } from "./utils/prepare-env";
+
+// 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}`);
+
+/**
+ * Find the git root directory using git command
+ */
+function findGitRoot(startPath: string): string | null {
+	try {
+		const output = execSync("git rev-parse --show-toplevel", {
+			cwd: startPath,
+			encoding: "utf8",
+		});
+		return output.trim();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Find all wrangler config files using git ls-files
+ * This is more efficient and respects .gitignore
+ */
+function findAllWranglerConfigs(gitRoot: string): string[] {
+	try {
+		// Use git ls-files to find all tracked wrangler configs
+		const output = execSync('git ls-files "**/wrangler.json*"', {
+			cwd: gitRoot,
+			encoding: "utf8",
+		});
+
+		return output
+			.trim()
+			.split("\n")
+			.filter((line) => line.length > 0)
+			.map((relativePath) => path.join(gitRoot, relativePath));
+	} catch (err) {
+		console.warn("⚠ Failed to run git ls-files:", err);
+		return [];
+	}
+}
+
+function runWranglerTypes() {
+	const envFiles = prepareEnvFiles(cwd);
+
+	console.log("Running wrangler types...");
+
+	// Find git root to discover all wrangler configs
+	const gitRoot = findGitRoot(cwd);
+	if (!gitRoot) {
+		console.warn(
+			"⚠ Could not find git root, skipping workspace config discovery",
+		);
+		console.log("  Generating types for current directory only");
+	}
+
+	// Find all wrangler configs in the workspace
+	const allConfigs = gitRoot ? findAllWranglerConfigs(gitRoot) : [];
+
+	if (allConfigs.length > 0) {
+		console.log(`  Found ${allConfigs.length} wrangler config(s) in workspace`);
+	}
+
+	// Build the command with multiple -c flags
+	// The first config should be the current directory's wrangler.jsonc
+	const configFlags = ["-c wrangler.jsonc"];
+
+	// Add other configs (relative to cwd for better readability)
+	const currentWranglerJsonc = path.join(cwd, "wrangler.jsonc");
+	const currentWranglerJson = path.join(cwd, "wrangler.json");
+
+	for (const configPath of allConfigs) {
+		const resolvedPath = path.resolve(configPath);
+		// Skip if it's the current directory's config
+		if (
+			resolvedPath === currentWranglerJsonc ||
+			resolvedPath === currentWranglerJson
+		) {
+			continue;
+		}
+		// Make path relative to cwd
+		const relativePath = path.relative(cwd, configPath);
+		configFlags.push(`-c ${relativePath}`);
+	}
+
+	for (const envFile of envFiles) {
+		configFlags.push(`--env-file ${envFile}`);
+	}
+
+	const command = `wrangler types ${configFlags.join(" ")}`;
+
+	console.log(`  Command: ${command}`);
+
+	try {
+		execSync(command, {
+			cwd,
+			stdio: "inherit",
+		});
+		console.log("✓ Wrangler types generated with all workspace bindings");
+	} catch {
+		console.error("Failed to run wrangler types");
+		process.exit(1);
+	}
+}
+
+// Run all steps
+try {
+	runWranglerTypes();
+	console.log("\n✓ CF typegen completed successfully");
+} catch (error: unknown) {
+	console.error("\n✗ CF typegen failed:", error);
+	process.exit(1);
+}

package/src/utils/prepare-env.ts

@@ -0,0 +1,58 @@
+import * as fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Ensures a .env and .env.local file exists in the target directory.
+ * If it doesn't exist, copies from .env.example and .env.local.example.
+ *
+ * @param targetDir - The directory where the .env and .env.local files should exist
+ * @returns An array of the files that were created or already existed
+ */
+export function prepareEnvFiles(targetDir: string): string[] {
+	const exampleEnvPath = path.join(targetDir, ".env.example");
+	const exampleEnvLocalPath = path.join(targetDir, ".env.local.example");
+
+	const exampleEnvExists = fs.existsSync(exampleEnvPath);
+	const exampleLocalEnvExists = fs.existsSync(exampleEnvLocalPath);
+
+	const envPath = path.join(targetDir, ".env");
+	const envLocalPath = path.join(targetDir, ".env.local");
+
+	let envExists = fs.existsSync(envPath);
+	let envLocalExists = fs.existsSync(envLocalPath);
+
+	if (exampleEnvExists) {
+		if (!envExists) {
+			fs.cpSync(exampleEnvPath, envPath);
+
+			console.log("✓ Created .env from .env.example");
+			envExists = true;
+		}
+	}
+
+	if (exampleLocalEnvExists) {
+		if (!envLocalExists) {
+			fs.cpSync(exampleEnvLocalPath, envLocalPath);
+
+			console.log("✓ Created .env.local from .env.local.example");
+			envLocalExists = true;
+		}
+	}
+
+	const result: string[] = [];
+	// The order matters, because latter files' values will override former files' values
+	if (exampleEnvExists) {
+		result.push(".env.example");
+	}
+	if (exampleLocalEnvExists) {
+		result.push(".env.local.example");
+	}
+	if (envExists) {
+		result.push(".env");
+	}
+	if (envLocalExists) {
+		result.push(".env.local");
+	}
+
+	return result;
+}