@tomphttp/bare-client - npm Package Compare versions

Comparing version 2.0.0-beta to 2.0.0-beta.1

dist/BareClient.d.ts

@@ -1,4 +0,40 @@
-import type { BareHeaders, BareManifest, BareResponseFetch, BareWebSocket, urlLike } from './BareTypes';
+import type { BareHeaders, BareManifest, BareResponseFetch, urlLike } from './BareTypes';
 import type { WebSocketImpl } from './Client';
 export declare function fetchManifest(server: string | URL, signal?: AbortSignal): Promise<BareManifest>;
+export declare namespace BareWebSocket {
+    type GetReadyStateCallback = () => number;
+    type GetSendErrorCallback = () => Error | undefined;
+    type GetProtocolCallback = () => string;
+    type HeadersType = BareHeaders | Headers | undefined;
+    type HeadersProvider = BareHeaders | (() => BareHeaders | Promise<BareHeaders>);
+    interface Options {
+        /**
+         * A provider of request headers to pass to the remote.
+         * Usually one of `User-Agent`, `Origin`, and `Cookie`
+         * Can be just the headers object or an synchronous/asynchronous function that returns the headers object
+         */
+        headers: BareWebSocket.HeadersProvider;
+        /**
+         * A hook executed by this function with helper arguments for hooking the readyState property. If a hook isn't provided, bare-client will hook the property on the instance. Hooking it on an instance basis is good for small projects, but ideally the class should be hooked by the user of bare-client.
+         */
+        readyStateHook?: ((socket: WebSocket, getReadyState: BareWebSocket.GetReadyStateCallback) => void) | undefined;
+        /**
+         * A hook executed by this function with helper arguments for determining if the send function should throw an error. If a hook isn't provided, bare-client will hook the function on the instance.
+         */
+        sendErrorHook?: ((socket: WebSocket, getSendError: BareWebSocket.GetSendErrorCallback) => void) | undefined;
+        /**
+         * A hook executed by this function with the URL. If a hook isn't provided, bare-client will hook the URL.
+         */
+        urlHook?: ((socket: WebSocket, url: URL) => void) | undefined;
+        /**
+         * A hook executed by this function with a helper for getting the current fake protocol. If a hook isn't provided, bare-client will hook the protocol.
+         */
+        protocolHook?: ((socket: WebSocket, getProtocol: BareWebSocket.GetProtocolCallback) => void) | undefined;
+        /**
+         * A callback executed by this function with an array of cookies. This is called once the metadata from the server is received.
+         */
+        setCookiesCallback?: ((setCookies: string[]) => void) | undefined;
+        webSocketImpl: WebSocketImpl;
+    }
+}
 export declare class BareClient {
@@ -26,9 +62,4 @@ manfiest?: BareManifest;
     private getClient;
-    /**
-     *
-     * @param readyStateHook A callback executed by this function with helper arguments for hooking the readyState property. If a hook isn't provided, bare-client will hook the property on the instance. Hooking it on an instance basis is good for small projects, but ideally the class should be hooked by the user of bare-client.
-     * @param sendHook A callback executed by this function with helper arguments for hooking the send function. If a hook isn't provided, bare-client will hook the function on the instance.
-     */
-    createWebSocket(remote: urlLike, protocols?: string | string[] | undefined, headers?: BareHeaders | Headers | undefined, readyStateHook?: ((socket: WebSocket, getReadyState: () => number) => void) | undefined, sendHook?: ((socket: WebSocket, getSendError: () => Error | undefined) => void) | undefined, webSocketImpl?: WebSocketImpl): BareWebSocket;
+    createWebSocket(remote: urlLike, protocols: string | string[] | undefined, options: BareWebSocket.Options): WebSocket;
     fetch(url: urlLike | Request, init?: RequestInit): Promise<BareResponseFetch>;
 }

dist/BareTypes.d.ts

@@ -13,31 +13,2 @@ export declare type BareMethod = 'GET' | 'POST' | 'DELETE' | 'OPTIONS' | 'PUT' | 'PATCH' | 'UPDATE' | string;
 /**
- * metadata with the URL for convenience
- */
-export interface BareWebSocketMetaFull extends BareWebSocketMeta {
-    url: string;
-}
-/**
- * A MetaEvent is sent to clients using WebSockets when the metadata is received and before the open event is dispatched.
- * By default, the Bare client will define the protocol and url on the WebSocket.
- * Clients can cancel replace behavior with their own by calling event.preventDefault().
- * */
-export interface MetaEvent extends Event {
-    /** Returns the metadata received from the server. */
-    readonly meta: BareWebSocketMetaFull;
-}
-export interface BareWebSocketEventMap {
-    meta: MetaEvent;
-}
-/**
- * WebSocket with an additional property.
- */
-export interface BareWebSocket extends WebSocket {
-    addEventListener: {
-        <K extends keyof BareWebSocketEventMap>(type: K, listener: (this: WebSocket, ev: BareWebSocketEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
-    } & WebSocket['addEventListener'];
-    removeEventListener: {
-        <K extends keyof BareWebSocketEventMap>(type: K, listener: (this: WebSocket, ev: BareWebSocketEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
-    } & WebSocket['addEventListener'];
-}
-/**
  * A Response with additional properties.
@@ -44,0 +15,0 @@ */

dist/Client.d.ts

@@ -20,4 +20,5 @@ import type { BareBodyInit, BareCache, BareHeaders, BareMethod, BareResponse, BareWebSocketMeta } from './BareTypes.js';
 };
+export declare type GetRequestHeadersCallback = () => Promise<BareHeaders>;
 export declare abstract class Client {
-    abstract connect(remote: URL, protocols: string[], requestHeaders: BareHeaders, onMeta: MetaCallback, onReadyState: ReadyStateCallback, webSocketImpl: WebSocketImpl): WebSocket;
+    abstract connect(remote: URL, protocols: string[], getRequestHeaders: GetRequestHeadersCallback, onMeta: MetaCallback, onReadyState: ReadyStateCallback, webSocketImpl: WebSocketImpl): WebSocket;
     abstract request(method: BareMethod, requestHeaders: BareHeaders, body: BareBodyInit, remote: URL, cache: BareCache | undefined, signal: AbortSignal | undefined): Promise<BareResponse>;
@@ -24,0 +25,0 @@ protected base: URL;

dist/index.d.ts

 import { BareClient } from './BareClient';
-export { BareClient };
 export * from './Client';
 export * from './BareTypes';
+export * from './BareClient';
 /**
@@ -6,0 +6,0 @@ *

dist/index.js

@@ -464,3 +464,3 @@ // The user likely has overwritten all networking functions after importing bare-client
     }
-    connect(remote, protocols, requestHeaders, onMeta, onReadyState) {
+    connect(remote, protocols, getRequestHeaders, onMeta, onReadyState) {
         const ws = new WebSocket(this.ws);
@@ -489,3 +489,3 @@ const cleanup = () => {
             // now we want the client to see the websocket is open and ready to communicate with the remote
-            onReadyState(WebSocket.OPEN);
+            onReadyState(WebSocketFields.OPEN);
             ws.dispatchEvent(new Event('open'));
@@ -503,10 +503,10 @@ };
             // but we need to fake this from the client so it thinks it's still connecting
-            onReadyState(WebSocket.CONNECTING);
-            WebSocketFields.prototype.send.call(ws, JSON.stringify({
+            onReadyState(WebSocketFields.CONNECTING);
+            getRequestHeaders().then((headers) => WebSocketFields.prototype.send.call(ws, JSON.stringify({
                 type: 'connect',
                 remote: remote.toString(),
                 protocols,
-                headers: requestHeaders,
+                headers,
                 forwardHeaders: [],
-            }));
+            })));
         }, 
@@ -663,10 +663,5 @@ // only block the open event once
                 return new ctor(this.server);
-        throw new Error(`Unable to find compatible client version.`);
+        throw new Error('Unable to find compatible client version. Starting from v2.0.0, @tomphttp/bare-client only supports Bare servers v3+. For more information, see https://github.com/tomphttp/bare-client/');
     }
-    /**
-     *
-     * @param readyStateHook A callback executed by this function with helper arguments for hooking the readyState property. If a hook isn't provided, bare-client will hook the property on the instance. Hooking it on an instance basis is good for small projects, but ideally the class should be hooked by the user of bare-client.
-     * @param sendHook A callback executed by this function with helper arguments for hooking the send function. If a hook isn't provided, bare-client will hook the function on the instance.
-     */
-    createWebSocket(remote, protocols = [], headers = {}, readyStateHook, sendHook, webSocketImpl = WebSocket) {
+    createWebSocket(remote, protocols = [], options) {
         if (!this.client)
@@ -688,41 +683,30 @@ throw new TypeError('You need to wait for the client to finish fetching the manifest before creating any WebSockets. Try caching the manifest data before making this request.');
                 throw new DOMException(`Failed to construct 'WebSocket': The subprotocol '${proto}' is invalid.`);
-        const requestHeaders = headers instanceof Headers ? Object.fromEntries(headers) : headers;
-        // user is expected to specify user-agent and origin
-        // both are in spec
-        requestHeaders['Host'] = remote.host;
-        // requestHeaders['Origin'] = origin;
-        requestHeaders['Pragma'] = 'no-cache';
-        requestHeaders['Cache-Control'] = 'no-cache';
-        requestHeaders['Upgrade'] = 'websocket';
-        // requestHeaders['User-Agent'] = navigator.userAgent;
-        requestHeaders['Connection'] = 'Upgrade';
-        const socket = this.client.connect(remote, protocols, requestHeaders, (meta) => {
-            const metaEvent = new Event('meta');
-            // prepare the event
-            const metaFull = Object.freeze({
-                url: remote.toString(),
-                ...meta,
-            });
-            Object.defineProperty(metaEvent, 'meta', {
-                value: metaFull,
-                writable: false,
-                configurable: false,
-            });
-            // define the properties ourselves by default if dispatchEvent returns true
-            // true is returned when nothing is done to cancel the event (preventDefault, cancellable)
-            if (!socket.dispatchEvent(metaEvent)) {
-                Object.defineProperty(socket, 'protocol', {
-                    get: () => metaFull.protocol,
-                    configurable: true,
-                    enumerable: true,
-                });
-                Object.defineProperty(socket, 'url', {
-                    get: () => metaFull.url,
-                    configurable: true,
-                    enumerable: true,
-                });
-            }
+        const socket = this.client.connect(remote, protocols, async () => {
+            const resolvedHeaders = typeof options.headers === 'function'
+                ? await options.headers()
+                : options.headers || {};
+            const requestHeaders = resolvedHeaders instanceof Headers
+                ? Object.fromEntries(resolvedHeaders)
+                : resolvedHeaders;
+            // user is expected to specify user-agent and origin
+            // both are in spec
+            requestHeaders['Host'] = remote.host;
+            // requestHeaders['Origin'] = origin;
+            requestHeaders['Pragma'] = 'no-cache';
+            requestHeaders['Cache-Control'] = 'no-cache';
+            requestHeaders['Upgrade'] = 'websocket';
+            // requestHeaders['User-Agent'] = navigator.userAgent;
+            requestHeaders['Connection'] = 'Upgrade';
+            return requestHeaders;
+        }, (meta) => {
+            fakeProtocol = meta.protocol;
+            if (options.setCookiesCallback)
+                options.setCookiesCallback(meta.setCookies);
         }, (readyState) => {
             fakeReadyState = readyState;
-        }, webSocketImpl);
+        }, options.webSocketImpl || WebSocket);
+        // protocol is always an empty before connecting
+        // updated when we receive the metadata
+        // this value doesn't change when it's CLOSING or CLOSED etc
+        let fakeProtocol = '';
         let fakeReadyState = WebSocketFields.CONNECTING;
@@ -736,4 +720,4 @@ const getReadyState = () => {
         };
-        if (readyStateHook)
-            readyStateHook(socket, getReadyState);
+        if (options.readyStateHook)
+            options.readyStateHook(socket, getReadyState);
         else {
@@ -755,4 +739,4 @@ // we have to hook .readyState ourselves
         };
-        if (sendHook)
-            sendHook(socket, getSendError);
+        if (options.sendErrorHook)
+            options.sendErrorHook(socket, getSendError);
         else {
@@ -768,2 +752,19 @@ // we have to hook .send ourselves
         }
+        if (options.urlHook)
+            options.urlHook(socket, remote);
+        else
+            Object.defineProperty(socket, 'url', {
+                get: () => remote.toString(),
+                configurable: true,
+                enumerable: true,
+            });
+        const getProtocol = () => fakeProtocol;
+        if (options.protocolHook)
+            options.protocolHook(socket, getProtocol);
+        else
+            Object.defineProperty(socket, 'protocol', {
+                get: getProtocol,
+                configurable: true,
+                enumerable: true,
+            });
         return socket;
@@ -828,3 +829,3 @@ }
 
-export { BareClient, BareError, Client, createBareClient, maxRedirects, statusEmpty, statusRedirect };
+export { BareClient, BareError, Client, createBareClient, fetchManifest, maxRedirects, statusEmpty, statusRedirect };
 //# sourceMappingURL=index.js.map

dist/V3.d.ts

@@ -1,4 +0,4 @@
-import type { BareBodyInit, BareCache, BareHeaders, BareMethod, BareResponse, BareWebSocket } from './BareTypes.js';
+import type { BareBodyInit, BareCache, BareHeaders, BareMethod, BareResponse } from './BareTypes.js';
 import { Client } from './Client.js';
-import type { ReadyStateCallback, MetaCallback } from './Client.js';
+import type { ReadyStateCallback, MetaCallback, GetRequestHeadersCallback } from './Client.js';
 export default class ClientV3 extends Client {
@@ -8,3 +8,3 @@ ws: URL;
     constructor(server: URL);
-    connect(remote: URL, protocols: string[], requestHeaders: BareHeaders, onMeta: MetaCallback, onReadyState: ReadyStateCallback): BareWebSocket;
+    connect(remote: URL, protocols: string[], getRequestHeaders: GetRequestHeadersCallback, onMeta: MetaCallback, onReadyState: ReadyStateCallback): WebSocket;
     request(method: BareMethod, requestHeaders: BareHeaders, body: BareBodyInit, remote: URL, cache: BareCache | undefined, signal: AbortSignal | undefined): Promise<BareResponse>;
@@ -11,0 +11,0 @@ private readBareResponse;

package.json

 {
 	"name": "@tomphttp/bare-client",
-	"version": "2.0.0-beta",
+	"version": "2.0.0-beta.1",
 	"homepage": "https://github.com/tomphttp",
@@ -5,0 +5,0 @@ "bugs": {

README.md

@@ -5,4 +5,22 @@ # Bare Client
 
+See the [V2 API documentation](./docs/V2.md).
+
 See the [changelog](./CHANGELOG.md).
 
+## Upgrading
+
+A guide for updating from v1 to v2 can be found [here](./docs/V2-UPGRADE-GUIDE.md).
+
+## Older Bare servers
+
+Starting from v2, @tomphttp/bare-client only supports Bare servers v3+.
+
+If you operate an outdated Bare server, we encourage you to update. If you're using an outdated Bare server, we encourage you to find an updated Bare server or host your own.
+
+If you're too lazy to do either of the above, you can install an outdated and unsupported version of the Bare client.
+
+```sh
+npm install @tomphttp/bare-client@1
+```
+
 ## Quickstart
@@ -9,0 +27,0 @@

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

73

increased by32.73%

Number of medium supply chain risk alerts

6

decreased by-66.67%

Worsened metrics

Total package byte prevSize

214666

decreased by-37.69%

Number of package files

17

decreased by-19.05%

Lines of code

1883

decreased by-38.1%

No dependency changes