uws-react-native 0.0.11 → 0.1.0-beta.1

package/src/types/HttpResponse.ts

@@ -2,9 +2,13 @@ import type {
 	RecognizedString,
 } from "./RecognizedString"
 
-// import type {
-// 	us_socket_context_t,
-// } from "./us_socket_context_t"
+import type {
+	WebSocketUserData,
+} from "./WebSocketUserData"
+
+import type {
+	us_socket_context_t,
+} from "./us_socket_context_t"
 
 /**
  * An HttpResponse is valid until either onAborted callback or any of the .end/.tryEnd calls succeed. You may attach user data to this object.
@@ -247,23 +251,45 @@ export interface HttpResponse {
 		totalSize: number,
 	) : [boolean, boolean],
 
-	// TODO
-	// Implement this method later.
-	// /**
-	//  * Upgrades a HttpResponse to a WebSocket. See UpgradeAsync, UpgradeSync example files.
-	//  * 
-	//  * Currently, this library is only supported string for the user data.
-	//  * As an object alternative, you can use `JSON.stringify` to this method,
-	//  * and retrieve the user data back from ws.getUserData() with `JSON.parse`.
-	//  */
-	// upgrade/* <UserData extends object> */(
-	// 	// userData: UserData,
-	// 	userData: string,
-	// 	secWebSocketKey: RecognizedString,
-	// 	secWebSocketProtocol: RecognizedString,
-	// 	secWebSocketExtensions: RecognizedString,
-	// 	context: us_socket_context_t,
-	// ) : void,
+	/**
+	 * Upgrades a HttpResponse to a WebSocket.
+	 * 
+	 * Important! There is one difference compared to the uWebSockets.js.
+	 * Instead of passing a user data object to the first argument,
+	 * modify the user data object from the handler parameter at the first argument of this method.
+	 * 
+	 * @example
+	 * ```ts
+	 * uWS.App()
+	 *   .ws("/*", {
+	 *     upgrade: (res, req, context) => {
+	 *       // you can do an async task here
+	 *       // and then, call upgrade method from res
+	 *       res.upgrade(
+	 *         userData => { // do not do an async task in this
+	 *           userData.setString("your_love_letter", "hello world")
+	 *           userData.setBoolean("is_flat_earth", true)
+	 *           userData.setNumber("worth", 67)
+	 *         },
+	 *         req.getHeader("sec-websocket-key"),
+	 *         req.getHeader("sec-websocket-protocol"),
+	 *         req.getHeader("sec-websocket-extensions"),
+	 *         context,
+	 *       )
+	 *     },
+	 *     open: ws => {
+	 *       const isFlatEarth = ws.getUserData().getBoolean("is_flat_earth")
+	 *     },
+	 * })
+	 * ```
+	 */
+	upgrade(
+		userDataFn: (userData: WebSocketUserData) => void,
+		secWebSocketKey: RecognizedString,
+		secWebSocketProtocol: RecognizedString,
+		secWebSocketExtensions: RecognizedString,
+		context: us_socket_context_t,
+	) : void,
 
 	/**
 	 * Enters or continues chunked encoding mode. Writes part of the response. End with zero length write. Returns true if no backpressure was added.
@@ -299,13 +325,4 @@ export interface HttpResponse {
 	writeStatus(
 		status: RecognizedString,
 	) : HttpResponse,
-
-	// TODO
-	// the `upgrade` method needs to be implemented first,
-	// but I also don't know how to attach arbitrary UserData to the HttpRequest object JSI C++.
-	// Probably, I would tell user to get the data explicitly from the ws.getUserData() method
-	// /**
-	//  * Arbitrary user data may be attached to this object 
-	//  */
-	// [key: string]: unknown,
 }

package/src/types/HttpRouterOptions.ts

@@ -5,7 +5,7 @@ export interface HttpRouterOptions {
 	 * if the body read is disabled.
 	 * 
 	 * This is an actual optimization, because uws-react-native has to predefined the body read
-	 * (the res->onDataV2) internally from C++ side by default. So if you disable body reading
+	 * (the res->onDataV2) internally from C++ side by default. So, if you disable body reading
 	 * in a specific route handler, uws-react-native will not do the predefined res->onDataV2 from C++ side at all.
 	 * 
 	 * The reason why uws-react-native has to predefined the res->onDataV2 from C++ side, it is because we cannot do a sync call from uWebSockets C++ which run in arbitrary thread to JS, and late onDataV2 assignment will losing the body data. It is also by design that we run uWebSockets in another thread to prevent Main/UI thread blocking.

package/src/types/TemplatedApp.ts

@@ -26,9 +26,9 @@ import type {
 	RecognizedString,
 } from "./RecognizedString"
 
-// import type {
-// 	WebSocketBehavior,
-// } from "./WebSocketBehavior"
+import type {
+	WebSocketBehavior,
+} from "./WebSocketBehavior"
 
 // import type {
 // 	us_listen_socket,
@@ -172,13 +172,13 @@ export interface TemplatedApp {
 	// 	hostname: string,
 	// ) : TemplatedApp,
 
-	// /**
-	//  * Registers a handler matching specified URL pattern where WebSocket upgrade requests are caught.
-	//  */
-	// ws<UserData>(
-	// 	pattern: RecognizedString,
-	// 	behavior: WebSocketBehavior<UserData>,
-	// ) : TemplatedApp,
+	/**
+	 * Registers a handler matching specified URL pattern where WebSocket upgrade requests are caught.
+	 */
+	ws(
+		pattern: RecognizedString,
+		behavior: WebSocketBehavior,
+	) : TemplatedApp,
 
 	// we can't provide this in Reaact Native
 	/**

package/src/types/WebSocket.ts

@@ -1,12 +1,20 @@
+import {
+	WebSocketSendStatus,
+} from "../modules/WebSocketSendStatus"
+
 import type {
 	RecognizedString,
 } from "./RecognizedString"
 
+import type {
+	WebSocketUserData,
+} from "./WebSocketUserData"
+
 /**
  * A WebSocket connection that is valid from open to close event.
  * Read more about this in the user manual.
  */
-export interface WebSocket<UserData> {
+export interface WebSocket {
 	/**
 	 * Forcefully closes this WebSocket. Immediately calls the close handler.
      * No WebSocket close message is sent.
@@ -19,7 +27,7 @@ export interface WebSocket<UserData> {
 	 */
 	cork(
 		cb: () => void,
-	) : WebSocket<UserData>,
+	) : WebSocket,
 
 	/**
 	 * Gracefully closes this WebSocket. Immediately calls the close handler.
@@ -62,9 +70,9 @@ export interface WebSocket<UserData> {
 	getTopics() : string[],
 
 	/**
-	 * Returns the UserData object.
+	 * Returns the user data object.
 	 */
-	getUserData() : UserData,
+	getUserData() : WebSocketUserData,
 
 	/**
 	 * Returns whether this websocket is subscribed to topic.
@@ -95,40 +103,48 @@ export interface WebSocket<UserData> {
 	 * Sends a message. Returns 1 for success, 2 for dropped due to backpressure limit, and 0 for built up backpressure that will drain over time. You can check backpressure before or after sending by calling getBufferedAmount().
      *
      * Make sure you properly understand the concept of backpressure. Check the backpressure example file.
+	 * 
+	 * This method will returns void due to the message is not a recognized string.
      */
 	send(
 		message: RecognizedString,
 		isBinary?: boolean,
 		compress?: boolean,
-	) : number,
+	) : WebSocketSendStatus | void,
 
 	/**
 	 * Sends the first fragment of a fragmented message. Use for sending large messages in chunks.
      * Returns 1 for success, 2 for dropped due to backpressure limit, and 0 for built up backpressure.
+	 * 
+	 * This method will returns void due to the message is not a recognized string.
      */
 	sendFirstFragment(
 		message: RecognizedString,
 		isBinary?: boolean,
 		compress?: boolean,
-	) : number,
+	) : WebSocketSendStatus | void,
 
 	/**
 	 * Sends a middle fragment of a fragmented message.
      * Returns 1 for success, 2 for dropped due to backpressure limit, and 0 for built up backpressure.
+	 * 
+	 * This method will returns void due to the message is not a recognized string.
      */
 	sendFragment(
 		message: RecognizedString,
 		compress?: boolean,
-	) : number,
+	) : WebSocketSendStatus | void,
 
 	/**
 	 * Sends the last fragment of a fragmented message.
      * Returns 1 for success, 2 for dropped due to backpressure limit, and 0 for built up backpressure.
+	 * 
+	 * This method will returns void due to the message is not a recognized string.
      */
 	sendLastFragment(
 		message: RecognizedString,
 		compress?: boolean,
-	) : number,
+	) : WebSocketSendStatus | void,
 
 	/**
 	 * Subscribe to a topic.

package/src/types/WebSocketBehavior.ts

@@ -21,14 +21,14 @@ import type {
 /**
  * A structure holding settings and handlers for a WebSocket URL route handler.
  */
-export interface WebSocketBehavior<UserData> {
+export interface WebSocketBehavior/* <UserData extends object> */ {
 	/**
 	 * Handler for close event, no matter if error, timeout or graceful close.
 	 * You may not use WebSocket after this event.
 	 * Do not send on this WebSocket from within here, it is closed.
 	 */
 	close?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 		code: number,
 		message: ArrayBuffer,
 	) => void,
@@ -51,7 +51,7 @@ export interface WebSocketBehavior<UserData> {
 	 * Use this to guide / drive your backpressure throttling.
 	 */
 	drain?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 	) => void,
 
 	/**
@@ -62,7 +62,7 @@ export interface WebSocketBehavior<UserData> {
 	 * (until first await or return) and will be neutered.
 	 */
 	dropped?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 		message: ArrayBuffer,
 		isBinary: boolean,
 	) => void | Promise<void>,
@@ -105,7 +105,7 @@ export interface WebSocketBehavior<UserData> {
 	 * Given ArrayBuffer is valid during the lifetime of this callback (until first await or return) and will be neutered.
 	 */
 	message?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 		message: ArrayBuffer,
 		isBinary: boolean,
 	) => void | Promise<void>,
@@ -115,7 +115,7 @@ export interface WebSocketBehavior<UserData> {
 	 * WebSocket is valid from open to close, no errors.
 	 */
 	open?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 	) => void | Promise<void>,
 
 	/**
@@ -123,7 +123,7 @@ export interface WebSocketBehavior<UserData> {
 	 * You do not need to handle this, pong messages are automatically sent as per the standard.
 	 */
 	ping?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 		message: ArrayBuffer,
 	) => void,
 
@@ -131,7 +131,7 @@ export interface WebSocketBehavior<UserData> {
 	 * Handler for received pong control message.
 	 */
 	pong?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 		message: ArrayBuffer,
 	) => void,
 
@@ -144,7 +144,7 @@ export interface WebSocketBehavior<UserData> {
 	 * Handler for subscription changes.
 	 */
 	subscription?: (
-		ws: WebSocket<UserData>,
+		ws: WebSocket,
 		topic: ArrayBuffer,
 		newCount: number,
 		oldCount: number,

package/src/types/WebSocketUserData.ts

@@ -0,0 +1,28 @@
+export interface WebSocketUserData {
+	getBoolean(
+		key: string,
+	): boolean | undefined,
+
+	setBoolean(
+		key: string,
+		value: boolean,
+	): void,
+
+	getNumber(
+		key: string,
+	): number | undefined,
+
+	setNumber(
+		key: string,
+		value: number,
+	): void,
+
+	getString(
+		key: string,
+	): string | undefined,
+
+	setString(
+		key: string,
+		value: number,
+	): void,
+}

package/src/types/index.ts

@@ -5,8 +5,9 @@ export type * from "./HttpResponse"
 export type * from "./MultipartField"
 export type * from "./RecognizedString"
 export type * from "./TemplatedApp"
-// export type * from "./WebSocket"
-// export type * from "./WebSocketBehavior"
+export type * from "./WebSocket"
+export type * from "./WebSocketBehavior"
+export type * from "./WebSocketUserData"
 // export type * from "./us_listen_socket"
 // export type * from "./us_socket"
 // export type * from "./us_socket_context_t"

package/src/types/us_socket_context_t.ts

@@ -1,6 +1,5 @@
 /**
  * Native type representing a raw uSockets struct us_socket_context_t.
- * Used while upgrading a WebSocket manually.
+ * This is not intended to be modified from JavaScript.
  */
-export interface us_socket_context_t {
-}
+export type us_socket_context_t = unknown