@adonix.org/cloud-spark 0.0.158 → 0.0.159

package/README.md

@@ -29,8 +29,8 @@ npm install @adonix.org/cloud-spark
 import { BasicWorker, TextResponse } from "@adonix.org/cloud-spark";
 
 export class HelloWorld extends BasicWorker {
-    protected override async get(): Promise<Response> {
-        return this.getResponse(TextResponse, "Hi from Cloud Spark!");
+    async get(): Promise<Response> {
+        return this.response(TextResponse, "Hi from Cloud Spark!");
     }
 }
 ```
@@ -61,6 +61,10 @@ And it's ready on http://localhost:8787
 
 <br>
 
+## :left_right_arrow: Web Sockets
+
+<br>
+
 ## :gear: Middleware
 
 <br>

package/dist/index.d.ts

@@ -47,6 +47,9 @@ declare namespace HttpHeader {
     const ACCESS_CONTROL_EXPOSE_HEADERS = "Access-Control-Expose-Headers";
     const ACCESS_CONTROL_MAX_AGE = "Access-Control-Max-Age";
     const ACCESS_CONTROL_REQUEST_HEADERS = "Access-Control-Request-Headers";
+    const SEC_WEBSOCKET_VERSION = "Sec-WebSocket-Version";
+    const CONNECTION = "Connection";
+    const UPGRADE = "Upgrade";
 }
 /**
  * Standard HTTP request methods.
@@ -136,6 +139,34 @@ declare const Time: {
     readonly Year: 31536000;
 };
 
+/** WebSocket upgrade header value */
+declare const WS_UPGRADE = "upgrade";
+/** WebSocket protocol header value */
+declare const WS_WEBSOCKET = "websocket";
+/** WebSocket protocol version */
+declare const WS_VERSION = "13";
+/** Max close code a user can send */
+declare const WS_MAX_CLOSE_CODE = 4999;
+/** Max number of reason chars a user can send */
+declare const WS_MAX_REASON_CHARS = 123;
+/** WebSocket close codes */
+declare const CloseCode: {
+    readonly NORMAL: 1000;
+    readonly GOING_AWAY: 1001;
+    readonly PROTOCOL_ERROR: 1002;
+    readonly UNSUPPORTED_DATA: 1003;
+    readonly NO_STATUS: 1005;
+    readonly ABNORMAL: 1006;
+    readonly INVALID_PAYLOAD: 1007;
+    readonly POLICY_VIOLATION: 1008;
+    readonly MESSAGE_TOO_BIG: 1009;
+    readonly MISSING_EXTENSION: 1010;
+    readonly INTERNAL_ERROR: 1011;
+    readonly TLS_HANDSHAKE: 1015;
+};
+/** WebSocket RESERVED close codes */
+declare const WS_RESERVED_CODES: Set<number>;
+
 /**
  * Type guard that checks if a string is a valid HTTP method.
  *
@@ -469,6 +500,8 @@ declare function cache(cacheName?: string, getKey?: (request: Request) => URL):
  */
 declare function cors(init?: CorsInit): Middleware;
 
+declare function websocket(path?: string): Middleware;
+
 /**
  * Lexicographically compares two strings.
  *
@@ -564,6 +597,48 @@ declare function stripSearchParams(request: Request): URL;
  */
 declare function getContentType(type: MediaType): string;
 
+type WarnEvent = {
+    type: "warn";
+    message: string;
+};
+type CustomEventMap = {
+    warn: WarnEvent;
+    open: Event;
+};
+type EventOptions = {
+    once?: boolean;
+};
+type ExtendedEventMap = WebSocketEventMap & CustomEventMap;
+type ExtendedEventType = keyof ExtendedEventMap;
+type ExtendedEventListener<K extends ExtendedEventType> = (ev: ExtendedEventMap[K]) => void;
+type WSAttachment = object;
+interface WebSocketConnection<A extends WSAttachment> {
+    get readyState(): number;
+    isState(...states: number[]): boolean;
+    accept(): WebSocket;
+    acceptWebSocket(ctx: DurableObjectState, tags?: string[]): WebSocket;
+    get attachment(): A;
+    attach(attachment: A): void;
+    send(message: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener<K extends ExtendedEventType>(type: K, listener: ExtendedEventListener<K>, options?: EventOptions): void;
+    removeEventListener<K extends ExtendedEventType>(type: K, listener: ExtendedEventListener<K>): void;
+}
+
+declare class WebSocketSessions<A extends WSAttachment = WSAttachment> {
+    private readonly map;
+    create(attachment?: A): WebSocketConnection<A>;
+    restore(ws: WebSocket): WebSocketConnection<A>;
+    restoreAll(all: WebSocket[]): ReadonlyArray<WebSocketConnection<A>>;
+    get(ws: WebSocket): WebSocketConnection<A> | undefined;
+    values(): IterableIterator<WebSocketConnection<A>>;
+    keys(): IterableIterator<WebSocket>;
+    close(ws: WebSocket, code?: number, reason?: string): boolean;
+    [Symbol.iterator](): IterableIterator<WebSocketConnection<A>>;
+    private register;
+    private unregister;
+}
+
 /**
  * A type-safe Cloudflare Worker handler with a guaranteed `fetch` method.
  *
@@ -616,6 +691,12 @@ declare abstract class BaseWorker implements Worker {
      * @returns A Promise that resolves to the `Response` for the request.
      */
     protected abstract dispatch(): Promise<Response>;
+    /**
+     * Checks if the given HTTP method is allowed for this worker.
+     * @param method HTTP method string
+     * @returns true if the method is allowed
+     */
+    isAllowed(method: string): boolean;
     abstract getAllowedMethods(): Method[];
     /**
      * Creates a new instance of the current Worker subclass.
@@ -630,6 +711,23 @@ declare abstract class BaseWorker implements Worker {
      * @returns A {@link Response} promise for the {@link Request}.
      */
     abstract fetch(): Promise<Response>;
+    /**
+     * Simplify and standardize {@link Response} creation by extending {@link WorkerResponse}
+     * or any of its subclasses and passing to this method.
+     *
+     * Or directly use any of the built-in classes.
+     *
+     * ```ts
+     * this.response(TextResponse, "Hello World!")
+     * ```
+     *
+     * @param ResponseClass The response class to instantiate
+     * @param args Additional constructor arguments
+     * @returns A Promise resolving to the {@link Response} object
+     */
+    protected response<Ctor extends new (...args: any[]) => {
+        create(): Promise<Response>;
+    }>(ResponseClass: Ctor, ...args: ConstructorParameters<Ctor>): Promise<Response>;
     /**
      * **Ignite** your `Worker` implementation into a Cloudflare handler.
      *
@@ -646,6 +744,10 @@ declare abstract class BaseWorker implements Worker {
 declare abstract class MiddlewareWorker extends BaseWorker {
     /** Middleware handlers registered for this worker. */
     protected readonly middlewares: Middleware[];
+    /**
+     * Hook for subclasses to perform any initialization.
+     */
+    protected init(): void | Promise<void>;
     /**
      * Add a middleware instance to this worker.
      *
@@ -676,16 +778,6 @@ declare abstract class BasicWorker extends MiddlewareWorker {
      * Dispatches the request to the method-specific handler.
      */
     protected dispatch(): Promise<Response>;
-    /**
-     * Hook for subclasses to perform any initialization.
-     */
-    protected init(): void | Promise<void>;
-    /**
-     * Checks if the given HTTP method is allowed for this worker.
-     * @param method HTTP method string
-     * @returns true if the method is allowed
-     */
-    isAllowed(method: string): boolean;
     /** Override and implement this method for GET requests. */
     protected get(): Promise<Response>;
     /** Override and implement this method for PUT requests. */
@@ -713,23 +805,6 @@ declare abstract class BasicWorker extends MiddlewareWorker {
      * overridden for each specific worker.
      */
     getAllowedMethods(): Method[];
-    /**
-     * Simplify and standardize {@link Response} creation by extending {@link WorkerResponse}
-     * or any of its subclasses and passing to this method.
-     *
-     * Or directly use any of the built-in classes.
-     *
-     * ```ts
-     * this.getResponse(TextResponse, "Hello World!")
-     * ```
-     *
-     * @param ResponseClass The response class to instantiate
-     * @param args Additional constructor arguments
-     * @returns A Promise resolving to the {@link Response} object
-     */
-    protected getResponse<Ctor extends new (...args: any[]) => {
-        getResponse(): Promise<Response>;
-    }>(ResponseClass: Ctor, ...args: ConstructorParameters<Ctor>): Promise<Response>;
 }
 
 /**
@@ -808,6 +883,8 @@ declare abstract class BaseResponse {
     status: StatusCodes;
     /** Optional status text. Defaults to standard reason phrase. */
     statusText?: string;
+    /** Enable websocket responses. */
+    webSocket: WebSocket | null;
     /** Default media type of the response body. */
     mediaType: MediaType;
     /** Converts current state to ResponseInit for constructing a Response. */
@@ -834,8 +911,8 @@ declare abstract class CacheResponse extends BaseResponse {
 declare abstract class WorkerResponse extends CacheResponse {
     private readonly body;
     constructor(body?: BodyInit | null, cache?: CacheControl);
-    /** Builds the Response object with body, headers, and status. */
-    getResponse(): Promise<Response>;
+    /** Builds the Response with body, headers, and status. */
+    create(): Promise<Response>;
 }
 /**
  * Wraps an existing Response and clones its body, headers, and status.
@@ -867,6 +944,13 @@ declare class HtmlResponse extends SuccessResponse {
 declare class TextResponse extends SuccessResponse {
     constructor(content: string, cache?: CacheControl, status?: StatusCodes);
 }
+/**
+ * Response for WebSocket upgrade requests.
+ * Automatically sets status to 101 and attaches the client socket.
+ */
+declare class WebSocketResponse extends WorkerResponse {
+    constructor(client: WebSocket);
+}
 /**
  * Response for HEAD requests. Copy headers and status from a GET response
  * without the body.
@@ -914,6 +998,10 @@ declare class NotFound extends HttpError {
 declare class MethodNotAllowed extends HttpError {
     constructor(worker: Worker);
 }
+/** 426 Upgrade Required error response. */
+declare class UpgradeRequired extends HttpError {
+    constructor();
+}
 /** 500 Internal Server Error response. */
 declare class InternalServerError extends HttpError {
     constructor(details?: string);
@@ -931,4 +1019,4 @@ declare class ServiceUnavailable extends HttpError {
     constructor(details?: string);
 }
 
-export { BadRequest, BasicWorker, CacheControl, ClonedResponse, type CorsConfig, type CorsInit, DELETE, type ErrorJson, Forbidden, GET, HEAD, Head, HtmlResponse, HttpError, HttpHeader, InternalServerError, JsonResponse, type MatchedRoute, MediaType, Method, MethodNotAllowed, MethodNotImplemented, Middleware, 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, type Worker, type WorkerClass, WorkerResponse, assertMethods, cache, cors, getContentType, getHeaderValues, getOrigin, isMethod, isMethodArray, lexCompare, mergeHeader, setHeader, sortSearchParams, stripSearchParams };
+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, WebSocketResponse, WebSocketSessions, type Worker, type WorkerClass, WorkerResponse, assertMethods, cache, cors, getContentType, getHeaderValues, getOrigin, isMethod, isMethodArray, lexCompare, mergeHeader, setHeader, sortSearchParams, stripSearchParams, websocket };