@adonix.org/cloud-spark 0.0.184 → 0.0.185

package/README.md

@@ -9,20 +9,11 @@
 
 **_Ignite_** your Cloudflare Workers with a type-safe library for rapid development.
 
-Get instant access to common essentials:
+CloudSpark provides a logical foundation for building Cloudflare Workers. It works well for simple workers or projects that grow in complexity, helping keep code organized and functionality scalable. It is lightweight and designed to let you focus on the logic that powers your worker.
 
-- Method & Route dispatch
-- CORS
-- Caching
-- WebSockets
+:bulb: If you are new to _Cloudflare Workers_, create a free [Cloudflare account](https://dash.cloudflare.com/sign-up) and install their command line interface [Wrangler](#cowboy_hat_face-wrangler).
 
-And then explore:
-
-- Custom Middleware
-- Nested Workers
-- Advanced Routing
-
-:bulb: If you are new to _Cloudflare Workers_, create a free [Cloudflare account](https://dash.cloudflare.com/sign-up) and install their command line interface [Wrangler](#cowboy_hat_face-wrangler). Detailed worker documentation can also be found [here](https://developers.cloudflare.com/workers/).
+Detailed worker documentation can also be found [here](https://developers.cloudflare.com/workers/).
 
 <br>
 
@@ -36,22 +27,16 @@ npm install @adonix.org/cloud-spark
 
 ## :rocket: Quickstart
 
-:page_facing_up: hello-world.ts
+:page_facing_up: index.ts
 
 ```ts
 import { BasicWorker, TextResponse } from "@adonix.org/cloud-spark";
 
-export class HelloWorld extends BasicWorker {
+class HelloWorld extends BasicWorker {
     get() {
         return this.response(TextResponse, "Hi from Cloud Spark!");
     }
 }
-```
-
-:page_facing_up: index.ts
-
-```ts
-import { HelloWorld } from "./hello-world";
 
 export default HelloWorld.ignite();
 ```
@@ -68,76 +53,174 @@ And it's ready on http://localhost:8787
 
 ## :arrow_right: Basic Worker
 
-As shown in the [Quickstart](#rocket-quickstart), BasicWorker is the base class for building Cloudflare Workers with this library. It handles common tasks, including:
+As shown in the [Quickstart](#rocket-quickstart), BasicWorker is the base class for building Cloudflare Workers with CloudSpark. It handles common tasks, including:
 
 - Dispatching incoming HTTP requests to the corresponding handler (GET, POST, PUT, etc.).
-- Catching unhandled errors and returning a structured 500 InternalServerError.
 - Providing defaults for standard HTTP behavior, such as HEAD requests and OPTIONS responses.
 - Ensuring type safety and consistent response formatting.
+- Support for built-in and custom middleware.
+- Catching unhandled errors.
 
-Subclasses only need to implement the HTTP methods that their Worker will handle. Each method can be overridden independently, and additional functionality such as middleware can be added as needed.
-
-## :hammer_and_wrench: Basic Worker API
-
-#### `getAllowedMethods(): Method[]`
+Subclasses only need to implement the HTTP methods that their Worker will handle. Each method can be overridden independently, and additional functionality such as [middleware](#gear-middleware) can be added as needed.
 
-Returns the HTTP methods supported by this Worker.
+Building on the [Quickstart](#rocket-quickstart), what follows is a more complete example:
 
-- **Default:** `[GET, HEAD, OPTIONS]`
-- **Notes:** Subclasses must override to allow additional methods. Any request using a method not listed will automatically return a `405 Method Not Allowed` response.
-
-#### `get(): Promise<Response>`
-
-Override this method to handle `GET` requests.
+:page_facing_up: index.ts
 
-- **Default behavior:** Returns a `404 Not Found`.
-- **Notes:** Typically used to return content or data for read requests.
+```ts
+import { BasicWorker, JsonResponse, Method, POST, TextResponse } from "@adonix.org/cloud-spark";
+
+/**
+ * To access the Cloudflare runtime properties:
+ *   • this.request — the incoming Request
+ *   • this.env — environment bindings (KV, R2, etc.)
+ *   • this.ctx — the execution context for background tasks
+ */
+export class MyWorker extends BasicWorker {
+    /**
+     * Override to allow additional method support for the worker.
+     * GET and HEAD requests are always allowed.
+     *
+     * Default: GET, HEAD, OPTIONS
+     *
+     * For OPTIONS requests, the default response is:
+     *     204 No Content
+     *     "Allow" response header contains all allowed methods.
+     *
+     * If a requested method is not listed, the response is:
+     *     405 Method Not Allowed
+     *
+     * If an allowed method isn’t implemented, the response is:
+     *     GET or HEAD: 404 Not Found
+     *     All other methods: 501 Not Implemented
+     *
+     * This example adds POST method support to the defaults.
+     */
+    public override getAllowedMethods(): Method[] {
+        return [...super.getAllowedMethods(), POST];
+    }
 
-#### `head(): Promise<Response>`
+    /**
+     * Example handler for GET requests that returns a simple
+     * text response.
+     */
+    protected override get(): Promise<Response> {
+        return this.response(TextResponse, "Hello from Cloud Spark!");
+    }
 
-Handles `HEAD` requests.
+    /**
+     * Example handler for POST requests that echoes the
+     * incoming JSON.
+     */
+    protected override async post(): Promise<Response> {
+        const json = await this.request.json();
+        // Do something with the request JSON.
 
-- **Default behavior:** Performs a `GET` request internally and strips the body.
-- **Notes:** Rarely needs to be overridden; ensures compliance with [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.2).
+        return this.response(JsonResponse, json);
+    }
 
-#### `post(): Promise<Response>`
+    /**
+     * Supported BasicWorker request methods:
+     *    protected override get(): Promise<Response>
+     *    protected override put(): Promise<Response>
+     *    protected override post(): Promise<Response>
+     *    protected override patch(): Promise<Response>
+     *    protected override delete(): Promise<Response>
+     *
+     * Implementations are provided but can be overridden for:
+     *    protected override head(): Promise<Response>
+     *    protected override options(): Promise<Response>
+     */
+}
 
-Override to handle `POST` requests.
+/**
+ * Connects this worker to the Cloudflare runtime.
+ */
+export default MyWorker.ignite();
+```
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Ideal for form submissions, JSON payloads, or resource creation.
+<br>
 
-#### `put(): Promise<Response>`
+## :twisted_rightwards_arrows: Route Worker
 
-Override to handle `PUT` requests.
+RouteWorker extends [BasicWorker](#arrow_right-basic-worker) to provide route-based request handling making it easy to define multiple endpoints in a single Worker. It provides:
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Used for full resource creation or replacement.
+- Registering routes individually or in bulk.
+- Matching incoming requests to registered routes by HTTP method and path.
+- Support for URL path patterns using [path-to-regex](https://github.com/pillarjs/path-to-regexp) syntax.
+- Dispatching requests to either a callback function or another Worker.
 
-#### `patch(): Promise<Response>`
+Example:
 
-Override to handle `PATCH` requests.
+:page_facing_up: index.ts
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Used for partial updates to existing resources.
+```ts
+import { BasicWorker, GET, PathParams, RouteWorker, TextResponse } from "@adonix.org/cloud-spark";
+
+/**
+ * An example worker with path routing.
+ */
+class GreetingWorker extends RouteWorker {
+    /**
+     * Called before request processing to enable worker
+     * initialization without overriding the constructor.
+     */
+    protected override init(): void {
+        /**
+         * Example of path-to-regex and local method routing.
+         */
+        this.route(GET, "/hello/:name", this.hello);
+
+        /**
+         * Example of simple path to a nested worker.
+         */
+        this.route(GET, "/goodbye", GoodbyeWorker);
+    }
 
-#### `delete(): Promise<Response>`
+    /**
+     * Path parameters are provided via path-to-regex parsing
+     * of the request path.
+     *
+     * For example, http://localhost:8787/hello/Inigo will yield
+     * the text response "Hello Inigo!"
+     */
+    protected hello(params: PathParams): Promise<Response> {
+        return this.response(TextResponse, `Hello ${params["name"]}!`);
+    }
+}
 
-Override to handle `DELETE` requests.
+/**
+ * An example nested BasicWorker.
+ *
+ * The original request, env, and ctx are passed to the nested
+ * worker via the constructor.
+ *
+ * RouteWorkers may also be nested to access path parameters.
+ */
+class GoodbyeWorker extends BasicWorker {
+    /**
+     * GET handler for the "/goodbye" path.
+     */
+    protected override get(): Promise<Response> {
+        return this.response(TextResponse, "Goodbye!");
+    }
+}
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Used to remove resources.
+/**
+ * Connects GreetingWorker to the Cloudflare runtime.
+ */
+export default GreetingWorker.ignite();
+```
 
-#### `options(): Promise<Response>`
+<br>
 
-Override to handle `OPTIONS` requests.
+## :gear: Middleware
 
-- **Default behavior:** Returns `200 OK` with the `Allow` header listing supported methods.
-- **Notes:** `GET`, `HEAD`, and `OPTIONS` are included by default.
+### CORS
 
-<br>
+### Cache
 
-## :twisted_rightwards_arrows: Route Worker
+### Custom
 
 <br>
 
@@ -145,10 +228,6 @@ Override to handle `OPTIONS` requests.
 
 <br>
 
-## :gear: Middleware
-
-<br>
-
 ## :cowboy_hat_face: Wrangler
 
 First, create a **FREE** [Cloudflare account](https://dash.cloudflare.com/sign-up).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@adonix.org/cloud-spark",
-    "version": "0.0.184",
+    "version": "0.0.185",
     "description": "Ignite your Cloudflare Workers with a type-safe library for rapid development.",
     "license": "Apache-2.0",
     "type": "module",
@@ -51,21 +51,21 @@
         "lint": "eslint ./src"
     },
     "devDependencies": {
-        "@eslint/js": "^9.39.0",
-        "@types/node": "^24.9.2",
+        "@eslint/js": "^9.39.1",
+        "@types/node": "^24.10.0",
         "@typescript-eslint/eslint-plugin": "^8.46.2",
-        "@typescript-eslint/parser": "^8.46.2",
-        "@vitest/coverage-v8": "^4.0.6",
-        "eslint": "^9.39.0",
+        "@typescript-eslint/parser": "^8.46.3",
+        "@vitest/coverage-v8": "^4.0.8",
+        "eslint": "^9.39.1",
         "eslint-plugin-import": "^2.32.0",
         "globals": "^16.5.0",
         "jiti": "^2.6.1",
         "prettier": "^3.6.2",
         "tsup": "^8.5.0",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.46.2",
-        "vitest": "^4.0.6",
-        "wrangler": "^4.45.3"
+        "typescript-eslint": "^8.46.3",
+        "vitest": "^4.0.8",
+        "wrangler": "^4.47.0"
     },
     "dependencies": {
         "cache-control-parser": "^2.0.6",