@adonix.org/cloud-spark 0.0.184 → 0.0.186

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,84 +53,359 @@ 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.
+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.
 
-## :hammer_and_wrench: Basic Worker API
+Building on the [Quickstart](#rocket-quickstart), what follows is a more complete example:
 
-#### `getAllowedMethods(): Method[]`
+:page_facing_up: index.ts
 
-Returns the HTTP methods supported by this Worker.
+```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];
+    }
 
-- **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.
+    /**
+     * Example handler for GET requests that returns a simple
+     * text response.
+     */
+    protected override get(): Promise<Response> {
+        return this.response(TextResponse, "Hello from Cloud Spark!");
+    }
 
-#### `get(): Promise<Response>`
+    /**
+     * 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.
 
-Override this method to handle `GET` requests.
+        return this.response(JsonResponse, json);
+    }
 
-- **Default behavior:** Returns a `404 Not Found`.
-- **Notes:** Typically used to return content or data for read requests.
+    /**
+     * 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>
+     */
+}
 
-#### `head(): Promise<Response>`
+/**
+ * Connects this worker to the Cloudflare runtime.
+ */
+export default MyWorker.ignite();
+```
 
-Handles `HEAD` requests.
+<br>
 
-- **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).
+## :twisted_rightwards_arrows: Route Worker
 
-#### `post(): Promise<Response>`
+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:
 
-Override to handle `POST` requests.
+- 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-regexp](https://github.com/pillarjs/path-to-regexp) syntax.
+- Dispatching requests to either a callback function or another worker.
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Ideal for form submissions, JSON payloads, or resource creation.
+Example:
 
-#### `put(): Promise<Response>`
+:page_facing_up: index.ts
 
-Override to handle `PUT` requests.
+```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-regexp and local method routing.
+         */
+        this.route(GET, "/hello/:name", this.hello);
+
+        /**
+         * Example of simple path to a nested worker.
+         */
+        this.route(GET, "/goodbye", GoodbyeWorker);
+    }
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Used for full resource creation or replacement.
+    /**
+     * Path parameters are provided via path-to-regexp 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"]}!`);
+    }
+}
 
-#### `patch(): Promise<Response>`
+/**
+ * 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!");
+    }
+}
 
-Override to handle `PATCH` requests.
+/**
+ * Connects GreetingWorker to the Cloudflare runtime.
+ */
+export default GreetingWorker.ignite();
+```
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Used for partial updates to existing resources.
+:bulb: Requests with no matching route fall back to the corresponding [BasicWorker](#arrow_right-basic-worker) method.
 
-#### `delete(): Promise<Response>`
+<br>
 
-Override to handle `DELETE` requests.
+## :gear: Middleware
 
-- **Default behavior:** Returns `501 Method Not Implemented`.
-- **Notes:** Used to remove resources.
+Middleware extends your worker’s behavior in a modular way. Each middleware can inspect the incoming request, return a custom response early, or modify the response produced by later handlers. It’s a simple way to add logic such as authentication checks, request logging, or response transformations without touching your core code.
 
-#### `options(): Promise<Response>`
+CloudSpark includes built-in middleware for common functionality like caching and CORS, and you can easily create your own to handle behavior specific to your application.
 
-Override to handle `OPTIONS` requests.
+### CORS
 
-- **Default behavior:** Returns `200 OK` with the `Allow` header listing supported methods.
-- **Notes:** `GET`, `HEAD`, and `OPTIONS` are included by default.
+Register the built-in CORS middleware as follows:
 
-<br>
+:page_facing_up: index.ts
 
-## :twisted_rightwards_arrows: Route Worker
+```ts
+import { BasicWorker, cors } from "@adonix.org/cloud-spark";
+
+class MyWorker extends BasicWorker {
+    /**
+     * Register middleware in the init method.
+     */
+    protected override init(): void {
+        /**
+         * Create and register the built-in CORS middleware
+         * with default options:
+         *
+         * {
+         *   allowedOrigins: ["*"],
+         *   allowedHeaders: ["Content-Type"],
+         *   exposedHeaders: [],
+         *   allowCredentials: false,
+         *   maxAge: 300,
+         * }
+         *
+         */
+        this.use(cors());
+
+        /**
+         * To override specific default CORS options:
+         *
+         * this.use(cors({ allowedOrigins: ["https://www.adonix.org"], maxAge: 604800 }));
+         *
+         */
+    }
+}
+```
 
-<br>
+:bulb: The middleware adds CORS headers to the response **ONLY** if the request includes an `Origin` header.
 
-## :left_right_arrow: Web Sockets
+### Cache
+
+CloudSpark includes built-in caching middleware that stores responses for improving performance. Only responses that are safe to cache are stored, including:
+
+- Responses to GET requests with a 200 OK status.
+- Responses that specify a time-to-live via `Cache-Control` headers (max-age or s-maxage).
+- Responses with `Vary` headers are fully supported, so the cache respects variations based on headers like `Accept-Language`.
+- Responses that **do not** include user-specific data (such as Set-Cookie or requests with Authorization/Cookie headers).
+
+Other types of responses (non-GET, errors, partial content, or requests marked no-store) are never cached. This ensures caching is safe and consistent with HTTP standards.
+
+Register the built-in cache middleware as follows:
+
+:page_facing_up: index.ts
+
+```ts
+import { BasicWorker, cache, CacheControl, JsonResponse, Time } from "@adonix.org/cloud-spark";
+
+class MyWorker extends BasicWorker {
+    /**
+     * Enable middleware in the worker init method.
+     */
+    protected override init(): void {
+        /**
+         * Create and register the built-in cache middleware.
+         */
+        this.use(cache());
+
+        /**
+         * Optionally pass settings to the cache function:
+         *
+         * 	name — the name of the cache storage to use. If omitted,
+         *         the default cache is used.
+         *  getKey — a function that maps the incoming request to a
+         *           cache key.
+         *           Built-in key functions include:
+         *               • sortSearchParams (Default)
+         *               • stripSearchParams
+         *
+         * this.use(cache({
+         *     name: "my-cache",
+         *     getKey: stripSearchParams,
+         * }));
+         *
+         */
+    }
+
+    /**
+     * Create a cacheable response.
+     */
+    protected override get(): Promise<Response> {
+        /**
+         * Example JSON message.
+         */
+        const json = {
+            message: "Hi from Cloud Spark!",
+            timestamp: new Date().toLocaleString(),
+        };
+
+        /**
+         * Cache the response for 10 seconds.
+         */
+        const cc: CacheControl = {
+            "s-maxage": 10 * Time.Second,
+        };
+
+        return this.response(JsonResponse, json, cc);
+    }
+}
+
+/**
+ * Connects MyWorker to the Cloudflare runtime.
+ */
+export default MyWorker.ignite();
+```
+
+:bulb: The `cf-cache-status` response header will contain **HIT** when serving from the cache.
+
+### WebSocket
+
+The WebSocket middleware ensures upgrade requests are valid before they reach your handler. You can provide a path (default: `"/"`) and register multiple instances for multiple paths. Invalid upgrade requests are intercepted, and the correct error response is returned.
+
+A valid WebSocket upgrade request must use the `GET` method and include the following:
+
+| Header                | Value     |
+| --------------------- | --------- |
+| Connection            | Upgrade   |
+| Upgrade               | websocket |
+| Sec-WebSocket-Version | 13        |
+
+Register the built-in websocket middleware as follows:
+
+:page_facing_up: index.ts
+
+```ts
+import { GET, PathParams, RouteWorker, websocket } from "@adonix.org/cloud-spark";
+
+class ChatWorker extends RouteWorker {
+    /**
+     * Register both the upgrade route and middleware.
+     */
+    protected override init(): void {
+        /**
+         * Route for WebSocket upgrades.
+         */
+        this.route(GET, "/chat/:room", this.upgrade);
+
+        /**
+         * Register WebSocket middleware to match the
+         * upgrade route.
+         */
+        this.use(websocket("/chat/:room"));
+    }
+
+    /**
+     * Handles WebSocket upgrade requests.
+     *
+     * Expects a DurableObject binding named CHAT 
+     * in wrangler.jsonc
+     */
+    protected upgrade(params: PathParams): Promise<Response> {
+        const room = params["room"];
+        const chat = this.env.CHAT;
+
+        /**
+         * Request has already been validated by the 
+         * WebSocket middleware.
+         */
+        return chat.get(chat.idFromName(room)).fetch(this.request);
+    }
+}
+
+/**
+ * Connects ChatWorker to the Cloudflare runtime.
+ */
+export default ChatWorker.ignite();
+```
+
+### Custom
 
 <br>
 
-## :gear: Middleware
+## :left_right_arrow: Web Sockets
 
 <br>
 

package/dist/index.d.ts

@@ -419,7 +419,7 @@ declare function cors(init?: CorsInit): Middleware;
  * - Only validates the upgrade request; it does **not** perform the actual WebSocket upgrade.
  * - Ensures the request:
  *   - Uses the `GET` method.
- *   - Matches the specified path, supporting `path-to-regex` style patterns
+ *   - Matches the specified path, supporting `path-to-regexp` style patterns
  *     (e.g., `/chat/:name`).
  *   - Contains required WebSocket headers:
  *     - `Connection: Upgrade`
@@ -429,7 +429,7 @@ declare function cors(init?: CorsInit): Middleware;
  *   the next middleware or origin handler.
  *
  * @param path - The URL path to intercept for WebSocket upgrades. Defaults to `/`.
- *               Supports dynamic segments using `path-to-regex` syntax.
+ *               Supports dynamic segments using `path-to-regexp` syntax.
  * @returns A {@link Middleware} instance that can be used in your middleware chain.
  *
  * @example
@@ -725,7 +725,7 @@ declare abstract class BaseWorker implements Worker {
      * @param args Additional constructor arguments
      * @returns A Promise resolving to the {@link Response} object
      */
-    protected response<Ctor extends new (...args: any[]) => {
+    response<Ctor extends new (...args: any[]) => {
         response(): Promise<Response>;
     }>(ResponseClass: Ctor, ...args: ConstructorParameters<Ctor>): Promise<Response>;
     /**
@@ -828,7 +828,7 @@ declare abstract class RouteWorker extends BasicWorker {
      * - A Worker subclass that will handle the request.
      *
      * @param method  - HTTP method for the route (`GET`, `POST`, etc.).
-     * @param path    - URL path pattern (path-to-regex, e.g., "/users/:id").
+     * @param path    - URL path pattern (path-to-regexp, e.g., "/users/:id").
      * @param handler - The function or Worker class to run when the route matches.
      * @returns The current worker instance, allowing method chaining.
      */
@@ -838,7 +838,7 @@ declare abstract class RouteWorker extends BasicWorker {
      *
      * Each route should be a tuple `[method, path, handler]` where:
      * - `method`  - HTTP method for the route (`GET`, `POST`, etc.).
-     * - `path`    - URL path pattern (path-to-regex e.g., "/users/:id").
+     * - `path`    - URL path pattern (path-to-regexp e.g., "/users/:id").
      * - `handler` - A function that receives URL parameters or a Worker subclass
      *               that will handle the request.
      *