@adonix.org/cloud-spark 0.0.161 → 0.0.163

package/README.md

@@ -1,4 +1,4 @@
-# ⚡️ Cloud Spark
+# ⚡️Cloud Spark
 
 [![npm version](https://img.shields.io/npm/v/@adonix.org/cloud-spark.svg?color=blue)](https://www.npmjs.com/package/@adonix.org/cloud-spark)
 [![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/adonix-org/cloud-spark/blob/main/LICENSE)
@@ -21,7 +21,7 @@ npm install @adonix.org/cloud-spark
 
 <br>
 
-## :stopwatch: Quickstart
+## :rocket: Quickstart
 
 :page_facing_up: hello-world.ts
 
@@ -29,7 +29,7 @@ npm install @adonix.org/cloud-spark
 import { BasicWorker, TextResponse } from "@adonix.org/cloud-spark";
 
 export class HelloWorld extends BasicWorker {
-    async get(): Promise<Response> {
+    get() {
         return this.response(TextResponse, "Hi from Cloud Spark!");
     }
 }

package/dist/index.d.ts

@@ -27,11 +27,14 @@ declare const CacheControl: {
  * Standard HTTP header names and common values.
  */
 declare namespace HttpHeader {
-    const ALLOW = "Allow";
     const ACCEPT_ENCODING = "Accept-Encoding";
-    const ORIGIN = "Origin";
+    const ACCEPT_RANGES = "Accept-Ranges";
+    const ALLOW = "Allow";
+    const CONTENT_LENGTH = "Content-Length";
+    const CONTENT_RANGE = "Content-Range";
     const CONTENT_TYPE = "Content-Type";
     const CACHE_CONTROL = "Cache-Control";
+    const ORIGIN = "Origin";
     const USER_AGENT = "User-Agent";
     const VARY = "Vary";
     const CONTENT_SECURITY_POLICY = "Content-Security-Policy";
@@ -197,7 +200,7 @@ declare function isMethodArray(value: unknown): value is Method[];
 declare function assertMethods(value: unknown): asserts value is Method[];
 
 /**
- * User-supplied options for configuring CORS behavior.
+ * User-supplied options for configuring`CORS`behavior.
  *
  * This is a partial form of {@link CorsConfig}, meaning you only need
  * to provide the options you want to override. Any missing values will
@@ -213,9 +216,9 @@ declare function assertMethods(value: unknown): asserts value is Method[];
  */
 type CorsInit = Partial<CorsConfig>;
 /**
- * Configuration options for Cross-Origin Resource Sharing (CORS).
+ * Configuration options for Cross-Origin Resource Sharing `CORS`.
  *
- * Implementations of CORS middleware use this interface to determine
+ * Implementations of `CORS` middleware use this interface to determine
  * how cross-origin requests are validated and which headers are sent
  * in the response.
  *
@@ -232,7 +235,7 @@ type CorsInit = Partial<CorsConfig>;
  */
 interface CorsConfig {
     /**
-     * Origins allowed for CORS requests.
+     * Origins allowed for `CORS` requests.
      *
      * Use `["*"]` to allow all origins, or provide a list of specific origins.
      * Example: `["https://example.com", "https://api.example.com"]`
@@ -241,9 +244,9 @@ interface CorsConfig {
      */
     allowedOrigins: string[];
     /**
-     * HTTP headers allowed in CORS requests.
+     * HTTP headers allowed in `CORS` requests.
      *
-     * Browsers always allow *CORS-safelisted request headers* without preflight:
+     * Browsers always allow `CORS`-safelisted request headers* without preflight:
      * - `Accept`
      * - `Accept-Language`
      * - `Content-Language`
@@ -280,7 +283,7 @@ interface CorsConfig {
      * can be cached by the client.
      *
      * Increase for production use to reduce preflights, or lower for development
-     * if you frequently adjust CORS rules.
+     * if you frequently adjust `CORS` rules.
      *
      * @default 300 (5 minutes)
      */
@@ -317,6 +320,19 @@ interface ErrorJson {
     details: string;
 }
 
+/**
+ * Initialization options for an OctetStream response.
+ *
+ * @property size - Total size of the data (required).
+ * @property offset - Start of the byte range (optional, defaults to 0).
+ * @property length - Length of the byte range (optional, defaults to size).
+ */
+interface OctetStreamInit {
+    size: number;
+    offset?: number;
+    length?: number;
+}
+
 /**
  * Represents the constructor of a Worker subclass.
  *
@@ -402,7 +418,7 @@ type RouteHandler = RouteCallback | WorkerClass;
  * pass to the registered handler.
  */
 interface Route {
-    /** HTTP method for the route (e.g., GET, POST, etc.) */
+    /** HTTP method for the route (e.g., `GET`, `POST`, etc.) */
     method: Method;
     /** Path-to-regexp matcher function for this route */
     matcher: MatchFunction<PathParams>;
@@ -423,7 +439,7 @@ interface MatchedRoute {
 /**
  * A route tuple. Each tuple consists of:
  *
- * 1. HTTP method (e.g., "GET", "POST")
+ * 1. HTTP method (e.g., `GET`, `POST`)
  * 2. Path string (supports parameters, e.g., "/users/:id")
  * 3. Callback function or Worker class to handle matched requests
  * */
@@ -475,7 +491,7 @@ declare abstract class Middleware {
  * Creates a Vary-aware caching middleware for Workers.
  *
  * This middleware:
- * - Caches **GET requests** only.
+ * - Caches `GET` requests **only**.
  * - Respects the `Vary` header of responses, ensuring that requests
  *   with different headers (e.g., `Origin`) receive the correct cached response.
  * - Skips caching for non-cacheable responses (e.g., error responses or
@@ -489,13 +505,13 @@ declare abstract class Middleware {
 declare function cache(cacheName?: string, getKey?: (request: Request) => URL): Middleware;
 
 /**
- * Creates a CORS middleware instance.
+ * Creates a`CORS`middleware instance.
  *
  * This middleware automatically handles Cross-Origin Resource Sharing (CORS)
- * for incoming requests, including preflight OPTIONS requests, and adds
+ * for incoming requests, including preflight `OPTIONS` requests, and adds
  * appropriate headers to responses.
  *
- * @param init - Optional configuration for CORS behavior. See {@link CorsConfig}.
+ * @param init - Optional configuration for `CORS` behavior. See {@link CorsConfig}.
  * @returns A {@link Middleware} instance that can be used in your middleware chain.
  */
 declare function cors(init?: CorsInit): Middleware;
@@ -595,7 +611,7 @@ declare function stripSearchParams(request: Request): URL;
  * @param type - The media type.
  * @returns A string suitable for the `Content-Type` header.
  */
-declare function getContentType(type: MediaType): string;
+declare function getContentType(type: MediaType | string): string;
 
 type WarnEvent = {
     type: "warn";
@@ -627,7 +643,7 @@ interface WebSocketConnection<A extends WSAttachment> {
 
 declare class WebSocketSessions<A extends WSAttachment = WSAttachment> {
     private readonly map;
-    create(attachment?: A): WebSocketConnection<A>;
+    create(attachment?: Partial<A>): WebSocketConnection<A>;
     restore(ws: WebSocket): WebSocketConnection<A>;
     restoreAll(all: WebSocket[]): ReadonlyArray<WebSocketConnection<A>>;
     get(ws: WebSocket): WebSocketConnection<A> | undefined;
@@ -641,20 +657,13 @@ declare class WebSocketSessions<A extends WSAttachment = WSAttachment> {
 
 /**
  * A type-safe Cloudflare Worker handler with a guaranteed `fetch` method.
- *
- * Extends `ExportedHandler` but ensures that `fetch` exists and has the
- * correct signature for Cloudflare Worker invocation.
- *
- * `Env` is a placeholder type for the environment bindings provided by
- * the user (e.g., KV namespaces, secrets, Durable Objects). This interface
- * does not constrain the actual type; it only ensures `fetch` is present.
  */
-interface FetchHandler extends ExportedHandler<Env> {
+interface FetchHandler {
     /**
      * Handles an incoming request and produces a response.
      *
      * @param request - The incoming `Request` object.
-     * @param env - User-provided environment bindings (placeholder type).
+     * @param env - User-provided environment bindings.
      * @param ctx - Execution context for background tasks (`waitUntil`).
      * @returns A `Promise` that resolves to a `Response`.
      */
@@ -778,31 +787,31 @@ declare abstract class BasicWorker extends MiddlewareWorker {
      * Dispatches the request to the method-specific handler.
      */
     protected dispatch(): Promise<Response>;
-    /** Override and implement this method for GET requests. */
+    /** Override and implement this method for `GET` requests. */
     protected get(): Promise<Response>;
-    /** Override and implement this method for PUT requests. */
+    /** Override and implement this method for `PUT` requests. */
     protected put(): Promise<Response>;
-    /** Override and implement this method for POST requests. */
+    /** Override and implement this method for `POST` requests. */
     protected post(): Promise<Response>;
-    /** Override and implement this method for PATCH requests. */
+    /** Override and implement this method for `PATCH` requests. */
     protected patch(): Promise<Response>;
-    /** Override and implement this method for DELETE requests. */
+    /** Override and implement this method for `DELETE` requests. */
     protected delete(): Promise<Response>;
-    /** Returns a default empty OPTIONS response. */
+    /** Returns a default empty `OPTIONS` response. */
     protected options(): Promise<Response>;
     /**
-     * Default handler for HEAD requests.
-     * Performs a GET request and removes the body for HEAD semantics.
+     * Default handler for `HEAD` requests.
+     * Performs a `GET` request and removes the body for `HEAD` semantics.
      *
      * Usually does not need to be overridden as this behavior covers
-     * standard HEAD requirements.
+     * standard `HEAD` requirements.
      */
     protected head(): Promise<Response>;
     /**
-     * DEFAULT allowed HTTP methods for subclasses.
+     * The DEFAULT allowed HTTP methods for subclasses are `GET`, `HEAD`, `OPTIONS`.
      *
-     * These defaults were selected for getting started quickly and should be
-     * overridden for each specific worker.
+     * These defaults were selected for getting started quickly and can be
+     * overridden for each worker subclass.
      */
     getAllowedMethods(): Method[];
 }
@@ -825,7 +834,7 @@ declare abstract class RouteWorker extends BasicWorker {
      * - A function that receives URL parameters, or
      * - A Worker subclass that will handle the request.
      *
-     * @param method  - HTTP method for the route (GET, POST, etc.).
+     * @param method  - HTTP method for the route (`GET`, `POST`, etc.).
      * @param path    - URL path pattern (Express-style, 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.
@@ -835,7 +844,7 @@ declare abstract class RouteWorker extends BasicWorker {
      * Registers multiple routes at once in the worker.
      *
      * Each route should be a tuple `[method, path, handler]` where:
-     * - `method`  - HTTP method for the route (GET, POST, etc.).
+     * - `method`  - HTTP method for the route (`GET`, `POST`, etc.).
      * - `path`    - URL path pattern (Express-style, e.g., "/users/:id").
      * - `handler` - A function that receives URL parameters or a Worker subclass
      *               that will handle the request.
@@ -886,7 +895,7 @@ declare abstract class BaseResponse {
     /** Enable websocket responses. */
     webSocket: WebSocket | null;
     /** Default media type of the response body. */
-    mediaType: MediaType;
+    mediaType: MediaType | string;
     /** Converts current state to ResponseInit for constructing a Response. */
     protected get responseInit(): ResponseInit;
     /** Sets a header, overwriting any existing value. */
@@ -944,6 +953,55 @@ declare class HtmlResponse extends SuccessResponse {
 declare class TextResponse extends SuccessResponse {
     constructor(content: string, cache?: CacheControl, status?: StatusCodes);
 }
+/**
+ * A response class for streaming binary data.
+ *
+ * Automatically sets headers for:
+ * - Accept-Ranges: bytes
+ * - Content-Length
+ * - Content-Range (for partial content)
+ *
+ * The status code is handled internally:
+ * - 200 OK for full content
+ * - 206 Partial Content for range responses
+ *
+ * @param stream - The ReadableStream containing the data to send.
+ * @param init - Options for the response:
+ *   - size: Total size of the data (required)
+ *   - offset: Start of the byte range (defaults to 0)
+ *   - length: Length of the byte range (defaults to size)
+ * @param cache: Optional caching information
+ */
+declare class OctetStream extends WorkerResponse {
+    constructor(stream: ReadableStream, init: OctetStreamInit, cache?: CacheControl);
+}
+/**
+ * A streaming response for Cloudflare R2 objects.
+ *
+ * @param object - The R2 object to stream.
+ * @param cache - Optional caching information.
+ */
+declare class R2ObjectStream extends OctetStream {
+    constructor(object: R2ObjectBody, cache?: CacheControl);
+    /**
+     * Computes the byte range for an R2 object, returning all values needed
+     * to construct a proper streaming response.
+     *
+     * Handles three cases:
+     * 1. **No range specified** — returns the full object.
+     * 2. **Suffix range** (e.g., last N bytes) — calculates offset and length
+     *    so that only the requested suffix is returned.
+     * 3. **Standard offset/length range** — returns the requested range,
+     *    applying defaults if offset or length are missing.
+     *
+     * @param object - The R2 object containing optional range information.
+     * @returns An object containing:
+     *   - `size` — total size of the object in bytes
+     *   - `offset` — starting byte of the range
+     *   - `length` — number of bytes in the range
+     */
+    private static computeRange;
+}
 /**
  * Response for WebSocket upgrade requests.
  * Automatically sets status to 101 and attaches the client socket.
@@ -952,16 +1010,16 @@ declare class WebSocketUpgrade extends WorkerResponse {
     constructor(client: WebSocket);
 }
 /**
- * Response for HEAD requests. Copy headers and status from a GET response
+ * Response for `HEAD` requests. Copy headers and status from a `GET` response
  * without the body.
  */
 declare class Head extends WorkerResponse {
     constructor(get: Response);
 }
 /**
- * Response for OPTIONS preflight requests.
+ * Response for `OPTIONS` preflight requests.
  */
-declare class Options extends SuccessResponse {
+declare class Options extends WorkerResponse {
     constructor();
 }
 
@@ -1019,4 +1077,4 @@ declare class ServiceUnavailable extends HttpError {
     constructor(details?: string);
 }
 
-export { BadRequest, BasicWorker, CacheControl, ClonedResponse, CloseCode, type CorsConfig, type CorsInit, DELETE, type ErrorJson, Forbidden, GET, HEAD, Head, HtmlResponse, HttpError, HttpHeader, InternalServerError, JsonResponse, type MatchedRoute, MediaType, Method, MethodNotAllowed, MethodNotImplemented, NotFound, NotImplemented, OPTIONS, Options, PATCH, POST, PUT, type PathParams, type Route, type RouteCallback, type RouteHandler, type RouteTable, type RouteTuple, RouteWorker, ServiceUnavailable, SuccessResponse, TextResponse, Time, Unauthorized, UpgradeRequired, WS_MAX_CLOSE_CODE, WS_MAX_REASON_CHARS, WS_RESERVED_CODES, WS_UPGRADE, WS_VERSION, WS_WEBSOCKET, WebSocketSessions, WebSocketUpgrade, type Worker, type WorkerClass, WorkerResponse, assertMethods, cache, cors, getContentType, getHeaderValues, getOrigin, isMethod, isMethodArray, lexCompare, mergeHeader, setHeader, sortSearchParams, stripSearchParams, websocket };
+export { BadRequest, BasicWorker, CacheControl, ClonedResponse, CloseCode, type CorsConfig, type CorsInit, DELETE, type ErrorJson, Forbidden, GET, HEAD, Head, HtmlResponse, HttpError, HttpHeader, InternalServerError, JsonResponse, type MatchedRoute, MediaType, Method, MethodNotAllowed, MethodNotImplemented, NotFound, NotImplemented, OPTIONS, OctetStream, type OctetStreamInit, Options, PATCH, POST, PUT, type PathParams, R2ObjectStream, type Route, type RouteCallback, type RouteHandler, type RouteTable, type RouteTuple, RouteWorker, ServiceUnavailable, SuccessResponse, TextResponse, Time, Unauthorized, UpgradeRequired, WS_MAX_CLOSE_CODE, WS_MAX_REASON_CHARS, WS_RESERVED_CODES, WS_UPGRADE, WS_VERSION, WS_WEBSOCKET, WebSocketSessions, WebSocketUpgrade, type Worker, type WorkerClass, WorkerResponse, assertMethods, cache, cors, getContentType, getHeaderValues, getOrigin, isMethod, isMethodArray, lexCompare, mergeHeader, setHeader, sortSearchParams, stripSearchParams, websocket };