cfw-utils 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Lyntor Paul Figueroa (https://github.com/h4ckedneko)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# Cloudflare Workers Utilities
+
+A set of utility functions for Cloudflare Workers.
+
+## Installation
+
+```bash
+npm install cfw-utils
+```
+
+```bash
+pnpm add cfw-utils
+```
+
+```bash
+yarn add cfw-utils
+```
+
+Alternatively, you can also just copy and paste the utilities in [src/utils](src/utils) to your project.
+
+## Usage
+
+### configureStep()
+
+A reusable step runner for Cloudflare Workflows. Simplifies running workflow steps with shared default configuration and centralized error handling.
+
+#### Features
+
+- **Default config** - Apply consistent timeout, retries, or other settings across all steps
+- **Error handling** - Automatically execute cleanup logic when any step fails
+- **Familiar API** - Mirrors Cloudflare's `step.do` signature
+
+#### Example
+
+```typescript
+export class Workflow extends WorkflowEntrypoint<Env, Params> {
+  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+    const { runStep } = configureStep(step, {
+      // Default config applied to all steps (can be overridden per step).
+      defaultConfig: {
+        retries: {
+          limit: 10,
+          delay: 1000,
+          backoff: "exponential",
+        },
+        timeout: "5 minutes",
+      },
+      // Cleanup logic executed when any step fails.
+      onError: async (error) => {
+        await setAsFailed();
+        console.error(error);
+      },
+    });
+
+    // Run a step with default configuration.
+    const result = await runStep("fetch data", async () => {
+      return await fetch("https://example.com").then(r => r.json());
+    });
+
+    // Run a step with overridden timeout (other defaults still apply).
+    await runStep("process data", { timeout: "30 minutes" }, async () => {
+      await saveToDb(result);
+    });
+  }
+}
+```
+
+## License
+
+MIT © [Lyntor Paul Figueroa](https://github.com/h4ckedneko)

package/dist/index.cjs

@@ -0,0 +1,43 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/utils/workflow.ts
+/**
+* Configures a reusable step runner for a Cloudflare Workflow.
+*
+* @param step - The workflow step instance
+* @param options - See {@link ConfigureStepOptions}
+* @returns An object containing the configured `runStep` function
+*
+* @example
+* const { runStep } = configureStep(step, {
+*   defaultConfig: { timeout: "1 minute" },
+*   onError: async () => {
+*     await db.job.update({
+*       where: { id },
+*       data: { status: "FAILED" },
+*     });
+*   },
+* });
+*
+* const result = await runStep("fetch data", async () => {
+*   return await fetch("https://example.com").then(r => r.json());
+* });
+*/
+function configureStep(step, options = {}) {
+	async function runStep(name, configOrCallback, maybeCallback) {
+		const config = typeof configOrCallback === "function" ? {} : configOrCallback;
+		const callback = typeof configOrCallback === "function" ? configOrCallback : maybeCallback;
+		const run = () => step.do(name, {
+			...options.defaultConfig,
+			...config
+		}, callback);
+		if (options.onError) try {
+			return await run();
+		} catch (error) {
+			await step.do(`handle error for: ${name}`, () => options.onError(error));
+		}
+		return await run();
+	}
+	return { runStep };
+}
+//#endregion
+exports.configureStep = configureStep;

package/dist/index.d.cts

@@ -0,0 +1,37 @@
+import { WorkflowStep, WorkflowStepConfig, WorkflowStepContext } from "cloudflare:workers";
+
+//#region src/utils/workflow.d.ts
+type ConfigureStepOptions = {
+  defaultConfig?: WorkflowStepConfig;
+  onError?: (error: unknown) => Promise<void>;
+};
+/**
+ * Configures a reusable step runner for a Cloudflare Workflow.
+ *
+ * @param step - The workflow step instance
+ * @param options - See {@link ConfigureStepOptions}
+ * @returns An object containing the configured `runStep` function
+ *
+ * @example
+ * const { runStep } = configureStep(step, {
+ *   defaultConfig: { timeout: "1 minute" },
+ *   onError: async () => {
+ *     await db.job.update({
+ *       where: { id },
+ *       data: { status: "FAILED" },
+ *     });
+ *   },
+ * });
+ *
+ * const result = await runStep("fetch data", async () => {
+ *   return await fetch("https://example.com").then(r => r.json());
+ * });
+ */
+declare function configureStep(step: WorkflowStep, options?: ConfigureStepOptions): {
+  runStep: {
+    <T extends Rpc.Serializable<T>>(name: string, callback: (ctx: WorkflowStepContext) => Promise<T>): Promise<T>;
+    <T extends Rpc.Serializable<T>>(name: string, config: WorkflowStepConfig, callback: (ctx: WorkflowStepContext) => Promise<T>): Promise<T>;
+  };
+};
+//#endregion
+export { ConfigureStepOptions, configureStep };

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+import { WorkflowStep, WorkflowStepConfig, WorkflowStepContext } from "cloudflare:workers";
+
+//#region src/utils/workflow.d.ts
+type ConfigureStepOptions = {
+  defaultConfig?: WorkflowStepConfig;
+  onError?: (error: unknown) => Promise<void>;
+};
+/**
+ * Configures a reusable step runner for a Cloudflare Workflow.
+ *
+ * @param step - The workflow step instance
+ * @param options - See {@link ConfigureStepOptions}
+ * @returns An object containing the configured `runStep` function
+ *
+ * @example
+ * const { runStep } = configureStep(step, {
+ *   defaultConfig: { timeout: "1 minute" },
+ *   onError: async () => {
+ *     await db.job.update({
+ *       where: { id },
+ *       data: { status: "FAILED" },
+ *     });
+ *   },
+ * });
+ *
+ * const result = await runStep("fetch data", async () => {
+ *   return await fetch("https://example.com").then(r => r.json());
+ * });
+ */
+declare function configureStep(step: WorkflowStep, options?: ConfigureStepOptions): {
+  runStep: {
+    <T extends Rpc.Serializable<T>>(name: string, callback: (ctx: WorkflowStepContext) => Promise<T>): Promise<T>;
+    <T extends Rpc.Serializable<T>>(name: string, config: WorkflowStepConfig, callback: (ctx: WorkflowStepContext) => Promise<T>): Promise<T>;
+  };
+};
+//#endregion
+export { ConfigureStepOptions, configureStep };

package/dist/index.mjs

@@ -0,0 +1,42 @@
+//#region src/utils/workflow.ts
+/**
+* Configures a reusable step runner for a Cloudflare Workflow.
+*
+* @param step - The workflow step instance
+* @param options - See {@link ConfigureStepOptions}
+* @returns An object containing the configured `runStep` function
+*
+* @example
+* const { runStep } = configureStep(step, {
+*   defaultConfig: { timeout: "1 minute" },
+*   onError: async () => {
+*     await db.job.update({
+*       where: { id },
+*       data: { status: "FAILED" },
+*     });
+*   },
+* });
+*
+* const result = await runStep("fetch data", async () => {
+*   return await fetch("https://example.com").then(r => r.json());
+* });
+*/
+function configureStep(step, options = {}) {
+	async function runStep(name, configOrCallback, maybeCallback) {
+		const config = typeof configOrCallback === "function" ? {} : configOrCallback;
+		const callback = typeof configOrCallback === "function" ? configOrCallback : maybeCallback;
+		const run = () => step.do(name, {
+			...options.defaultConfig,
+			...config
+		}, callback);
+		if (options.onError) try {
+			return await run();
+		} catch (error) {
+			await step.do(`handle error for: ${name}`, () => options.onError(error));
+		}
+		return await run();
+	}
+	return { runStep };
+}
+//#endregion
+export { configureStep };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "cfw-utils",
+  "version": "0.0.1",
+  "description": "A set of utility functions for Cloudflare Workers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h4ckedneko/cfwutils.git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc",
+    "format": "dprint fmt",
+    "prepare": "lefthook install",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.2",
+    "@cloudflare/workers-types": "^4.20260317.1",
+    "dprint": "^0.53.1",
+    "lefthook": "^2.1.4",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.6",
+    "typescript": "^6.0.2"
+  }
+}