@evolu/common 7.4.1 → 8.0.0-next.1

package/dist/src/Types.d.ts

@@ -1,9 +1,38 @@
 /**
- * TypeScript utility types
+ * TypeScript utility types.
  *
  * @module
  */
 import * as Kysely from "kysely";
+import type { TypeName } from "./Type.js";
+/**
+ * A function that receives a value and returns nothing.
+ *
+ * Use for event handlers, observers, and async completion handlers.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const onComplete: Callback<string> = (value) => console.log(value);
+ * const queue = new Set<Callback<Result<Data, Error>>>();
+ * ```
+ */
+export type Callback<T> = (value: T) => void;
+/**
+ * A function that receives a value and optionally returns a teardown function.
+ *
+ * Use for subscriptions or callbacks that need abort-time teardown.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const subscribe: CallbackWithTeardown<EventSource> = (source) => {
+ *   source.start();
+ *   return () => source.stop();
+ * };
+ * ```
+ */
+export type CallbackWithTeardown<T> = (value: T) => void | (() => void);
 /**
  * Checks a condition on a value and returns a boolean.
  *
@@ -102,11 +131,6 @@ export type NullablePartial<T, NK extends keyof T = {
 }[keyof T], NP = Pick<T, Exclude<keyof T, NK>> & Partial<Pick<T, NK>>> = {
     [K in keyof NP]: NP[K];
 };
-/**
- * A type alias for `never` that is used intentionally when casting is not
- * needed and unit tests exist to ensure correctness.
- */
-export type IntentionalNever = never;
 /**
  * String, number, bigint, boolean, undefined, null
  *
@@ -124,6 +148,15 @@ export type Literal = string | number | bigint | boolean | undefined | null;
  * - True -> boolean
  */
 export type WidenLiteral<T extends Literal> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends bigint ? bigint : T;
+/**
+ * Removes `readonly` modifier from all properties of a type.
+ *
+ * Useful for constructing immutable objects step-by-step (e.g. builder pattern)
+ * before casting them back to the readonly type.
+ */
+export type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
 /**
  * Simplify an intersection type into a single mapped type.
  *
@@ -148,4 +181,125 @@ export type Simplify<T> = Kysely.Simplify<T>;
  * unchanged.
  */
 export type PartialProp<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * A value that can be awaited.
+ *
+ * Use when a function may complete synchronously or asynchronously depending on
+ * runtime conditions (e.g., cache hit vs network fetch).
+ *
+ * ### Example
+ *
+ * ```ts
+ * const getData = (id: string): Awaitable<Data> => {
+ *   const cached = cache.get(id);
+ *   if (cached) return cached; // Sync path
+ *   return fetchData(id); // Async path
+ * };
+ *
+ * // Always works
+ * const data = await getData(id);
+ *
+ * // Or optimize for sync path
+ * const result = getData(id);
+ * const data = isPromiseLike(result) ? await result : result;
+ * ```
+ */
+export type Awaitable<T> = T | PromiseLike<T>;
+/**
+ * Type guard to check if a value is a {@link PromiseLike}.
+ *
+ * Use with {@link Awaitable} to conditionally `await` only when necessary,
+ * avoiding microtask overhead for synchronous values.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const validate = (id: string): Awaitable<boolean> => {
+ *   const cached = cache.get(id);
+ *   if (cached !== undefined) return cached; // Sync path
+ *   return fetchValidation(id); // Async path
+ * };
+ *
+ * const result = validate(id);
+ * const isValid = isPromiseLike(result) ? await result : result;
+ * ```
+ */
+export declare const isPromiseLike: <T>(value: Awaitable<T>) => value is PromiseLike<T>;
+/** Single digit 0-9. Useful for template literal type validation. */
+export type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/** Digit 1-9. Useful for template literal type validation. */
+export type Digit1To9 = Exclude<Digit, "0">;
+/** Numeric string 1-6. Useful for days validation. */
+export type Digit1To6 = "1" | "2" | "3" | "4" | "5" | "6";
+/** Numeric string 1-23. Useful for hours validation. */
+export type Digit1To23 = Digit1To9 | `1${Digit}` | `2${"0" | "1" | "2" | "3"}`;
+/** Numeric string 1-51. Useful for weeks validation. */
+export type Digit1To51 = Digit1To9 | `${"1" | "2" | "3" | "4"}${Digit}` | `5${"0" | "1"}`;
+/** Numeric string 1-99. Useful for years validation. */
+export type Digit1To99 = Digit1To9 | `${Digit1To9}${Digit}`;
+/** Numeric string 1-59. Useful for minutes, seconds validation. */
+export type Digit1To59 = Digit1To9 | `1${Digit}` | `2${Digit}` | `3${Digit}` | `4${Digit}` | `5${Digit}`;
+/** Numeric literal 1-99. */
+export type Int1To99 = NumberFromString<Digit1To99>;
+/** Numeric literal 1-100. */
+export type Int1To100 = Int1To99 | 100;
+/**
+ * Parses a numeric literal type from a string literal.
+ *
+ * Used by {@link Int1To99}.
+ */
+export type NumberFromString<T extends string> = T extends `${infer N extends number}` ? N : never;
+/** Converts a union to an intersection. */
+export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Removes keys from each member of a union.
+ *
+ * Use when {@link Omit} would collapse a discriminated union into a single
+ * shared shape.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type Event =
+ *   | { type: "a"; a: string; shared: number }
+ *   | { type: "b"; b: number; shared: number };
+ *
+ * type Payload = DistributiveOmit<Event, "shared">;
+ * // { type: "a"; a: string } | { type: "b"; b: number }
+ * ```
+ */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * Extracts members of a discriminated union by their `type` literal.
+ *
+ * Constrains `TType` to valid `type` values, so typos fail at the type argument
+ * instead of silently producing `never`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type Message =
+ *   | { readonly type: "Create"; readonly id: string }
+ *   | { readonly type: "Delete"; readonly id: string };
+ *
+ * type CreateMessage = ExtractType<Message, "Create">;
+ * // { readonly type: "Create"; readonly id: string }
+ *
+ * // Type error: "Cretae" is not a valid Message type
+ * type _Typo = ExtractType<Message, "Cretae">;
+ * ```
+ */
+export type ExtractType<TUnion extends {
+    readonly type: TypeName;
+}, TType extends TUnion["type"]> = Extract<TUnion, {
+    readonly type: TType;
+}>;
+/**
+ * Constrains `T` to only contain keys not present in `Existing`.
+ *
+ * Use as a generic constraint to prevent overriding existing properties.
+ */
+export type NewKeys<T, Existing> = {
+    [K in keyof T]: K extends keyof Existing ? never : T[K];
+};
 //# sourceMappingURL=Types.d.ts.map

package/dist/src/Types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../src/Types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAEzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,mBAAmB,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,IAAI,CACvD,CAAC,EAAE,CAAC,EACJ,KAAK,EAAE,MAAM,KACV,CAAC,IAAI,CAAC,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,eAAe,CACzB,CAAC,EACD,EAAE,SAAS,MAAM,CAAC,GAAG;KAClB,CAAC,IAAI,MAAM,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CAC9C,CAAC,MAAM,CAAC,CAAC,EACV,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IACvD;KAAG,CAAC,IAAI,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;CAAE,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAErC;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,IAAI,CAAC,SAAS,MAAM,GAC1D,MAAM,GACN,CAAC,SAAS,MAAM,GACd,MAAM,GACN,CAAC,SAAS,OAAO,GACf,OAAO,GACP,CAAC,SAAS,MAAM,GACd,MAAM,GACN,CAAC,CAAC;AAEZ;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../src/Types.ts"],"names":[],"mappings":"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"}

package/dist/src/Types.js

@@ -1,6 +1,26 @@
 /**
- * TypeScript utility types
+ * TypeScript utility types.
  *
  * @module
  */
-export {};
+import * as Kysely from "kysely";
+/**
+ * Type guard to check if a value is a {@link PromiseLike}.
+ *
+ * Use with {@link Awaitable} to conditionally `await` only when necessary,
+ * avoiding microtask overhead for synchronous values.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const validate = (id: string): Awaitable<boolean> => {
+ *   const cached = cache.get(id);
+ *   if (cached !== undefined) return cached; // Sync path
+ *   return fetchValidation(id); // Async path
+ * };
+ *
+ * const result = validate(id);
+ * const isValid = isPromiseLike(result) ? await result : result;
+ * ```
+ */
+export const isPromiseLike = (value) => typeof value?.then === "function";

package/dist/src/WebSocket.d.ts

@@ -1,12 +1,69 @@
-import { Result } from "./Result.js";
-import { RetryError, RetryOptions } from "./Task.js";
-/** WebSocket with auto-reconnect and offline support. */
-export interface WebSocket extends Disposable {
+/**
+ * WebSocket with auto-reconnect.
+ *
+ * @module
+ */
+import type { Result } from "./Result.js";
+import type { Schedule } from "./Schedule.js";
+import type { RetryError, Task } from "./Task.js";
+import type { Millis } from "./Time.js";
+import { type Typed } from "./Type.js";
+/**
+ * WebSocket with auto-reconnect.
+ *
+ * The API mirrors native
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/WebSocket | WebSocket}
+ * but retries connections indefinitely by default. This design accounts for the
+ * fact that browser and React Native online/offline detection APIs are
+ * unreliable — they may report online status incorrectly, so the only reliable
+ * approach is to keep attempting reconnection.
+ *
+ * Created via {@link createWebSocket} which returns a {@link Task}.
+ *
+ * Disposing starts closing the connection without waiting for the close event
+ * so disposal stays immediate. This wrapper treats disposal as local teardown,
+ * not as waiting for the full WebSocket close handshake to finish.
+ *
+ * ## How Binary Messages Work
+ *
+ * The Server Chooses the Message Type:
+ *
+ * - Text (0x1) → Sent as UTF-8 encoded text (always received as a string in the
+ *   browser).
+ * - Binary (0x2) → Sent as raw binary data (received as a Blob or ArrayBuffer,
+ *   depending on binaryType).
+ *
+ * The Client's binaryType Controls How Binary Data is Processed:
+ *
+ * - If the server sends a text frame (0x1), the browser always delivers
+ *   event.data as a string, regardless of binaryType.
+ * - If the server sends a binary frame (0x2), the browser delivers event.data as:
+ *
+ *   - A Blob (default: "blob")
+ *   - An ArrayBuffer ("arraybuffer")
+ *
+ * ### Example
+ *
+ * ```ts
+ * const ws = await run(
+ *   createWebSocket("wss://example.com", {
+ *     onMessage: (data) => console.log("Received:", data),
+ *     onOpen: () => console.log("Connected"),
+ *     onClose: () => console.log("Disconnected"),
+ *   }),
+ * );
+ * if (ws.ok) {
+ *   ws.value.send("Hello");
+ *   // Later: await ws.value[Symbol.asyncDispose]();
+ * }
+ * ```
+ */
+export interface WebSocket extends AsyncDisposable {
     /**
      * Send data through the WebSocket connection. Returns {@link Result} with an
      * error if the data couldn't be sent.
      */
-    send: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => Result<void, WebSocketSendError>;
+    send: (data: BufferSource | Blob | string | globalThis.Uint8Array) => Result<void, WebSocketSendError>;
     readonly getReadyState: () => WebSocketReadyState;
     /** Returns true if the WebSocket is open and ready to send data. */
     readonly isOpen: () => boolean;
@@ -17,94 +74,109 @@ export interface WebSocket extends Disposable {
  *
  * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
  */
-export interface WebSocketSendError {
-    readonly type: "WebSocketSendError";
+export interface WebSocketSendError extends Typed<"WebSocketSendError"> {
 }
 /** WebSocket connection states. */
 export type WebSocketReadyState = "connecting" | "open" | "closing" | "closed";
-export type CreateWebSocket = (url: string, options?: WebSocketOptions) => WebSocket;
+/** {@link Task} that creates a {@link WebSocket}. */
+export type CreateWebSocket = (url: string, options?: WebSocketOptions) => Task<WebSocket>;
 export interface CreateWebSocketDep {
     readonly createWebSocket: CreateWebSocket;
 }
-/** Options for creating {@link WebSocket} */
+/** Options for creating {@link WebSocket}. */
 export interface WebSocketOptions {
     /** Protocol(s) to use with the WebSocket connection. */
-    protocols?: string | Array<string>;
+    readonly protocols?: string | ReadonlyArray<string>;
     /** Sets the binary type for the data being received. */
-    binaryType?: "blob" | "arraybuffer";
+    readonly binaryType?: "blob" | "arraybuffer";
     /** Callback when the connection is established. */
-    onOpen?: () => void;
+    readonly onOpen?: () => void;
     /** Callback when an error occurs. */
-    onError?: (error: WebSocketError) => void;
+    readonly onError?: (error: WebSocketError) => void;
     /** Callback when the connection is closed. */
-    onClose?: (event: CloseEvent) => void;
+    readonly onClose?: (event: CloseEvent) => void;
+    /**
+     * Determines whether a closed connection should trigger a retry.
+     *
+     * Return false to stop retrying, for example on auth errors or maintenance.
+     */
+    readonly shouldRetryOnClose?: (event: CloseEvent) => boolean;
     /** Callback when message data is received. */
-    onMessage?: (data: string | ArrayBuffer | Blob) => void;
-    /** Options for retry behavior. */
-    retryOptions?: Omit<RetryOptions<WebSocketRetryError>, "signal">;
+    readonly onMessage?: (data: string | ArrayBuffer | Blob) => void;
+    /**
+     * Retry schedule for reconnection. Defaults to:
+     *
+     * ```ts
+     * // A jittered, capped, unlimited exponential backoff.
+     * jitter(1)(maxDelay("30s")(exponential("100ms")));
+     * ```
+     */
+    readonly schedule?: Schedule<Millis, WebSocketRetryError>;
     /**
      * For custom WebSocket implementations.
      *
-     * This suppors blob:
+     * This supports blob:
      *
      * https://github.com/callstackincubator/react-native-fast-io
      */
-    WebSocketConstructor?: typeof globalThis.WebSocket;
+    readonly WebSocketConstructor?: typeof globalThis.WebSocket;
 }
 export type WebSocketError = WebSocketConnectError | WebSocketConnectionError | RetryError<WebSocketRetryError>;
 /**
  * An error that occurs when a connection cannot be established due to a network
- * error.
+ * error. Fires before `onclose`.
  */
-export interface WebSocketConnectError {
-    readonly type: "WebSocketConnectError";
+export interface WebSocketConnectError extends Typed<"WebSocketConnectError"> {
     readonly event: Event;
 }
 /**
- * An error that occurs when a connection is closed due to an issue (e.g.,
- * failure to send some data).
+ * An error that occurs when an established connection encounters an issue
+ * (e.g., failure to send data). Fires before `onclose`.
+ *
+ * Note: Only Node.js and WebKit fire this error on abrupt server termination.
+ * Chromium and Firefox only fire `onclose` without a preceding error event.
  *
  * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/error_event
  */
-export interface WebSocketConnectionError {
-    readonly type: "WebSocketConnectionError";
+export interface WebSocketConnectionError extends Typed<"WebSocketConnectionError"> {
     readonly event: Event;
 }
 export type WebSocketRetryError = WebSocketConnectError | WebSocketConnectionCloseError;
-export interface WebSocketConnectionCloseError {
-    readonly type: "WebSocketConnectionCloseError";
+/** An error that occurs when the connection is closed by the server. */
+export interface WebSocketConnectionCloseError extends Typed<"WebSocketConnectionCloseError"> {
     readonly event: CloseEvent;
 }
+/** Create a new {@link WebSocket}. */
+export declare const createWebSocket: CreateWebSocket;
 /**
- * Create a new {@link WebSocket}.
- *
- * The default behavior is that WebSocket tries to reconnect repeatedly in case
- * the application is offline, because online events (both web and native) are
- * not reliable. Once it connects and the connection is closed, it tries to
- * reconnect again. Retrying the connection can be controlled using the
- * retryOptions retryable predicate.
- *
- * ### How Binary Messages Work in WebSockets
- *
- * The Server Chooses the Message Type:
- *
- * - Text (0x1) → Sent as UTF-8 encoded text (always received as a string in the
- *   browser).
- * - Binary (0x2) → Sent as raw binary data (received as a Blob or ArrayBuffer,
- *   depending on binaryType).
- *
- * The Client's binaryType Controls How Binary Data is Processed:
- *
- * - If the server sends a text frame (0x1), the browser always delivers
- *   event.data as a string, regardless of binaryType.
- * - If the server sends a binary frame (0x2), the browser delivers event.data as:
- *
- *   - A Blob (default: "blob")
- *   - An ArrayBuffer ("arraybuffer")
- *
- * ### Example
- *
- * TODO:
+ * An inspectable in-memory {@link CreateWebSocket} for testing by
+ * {@link testCreateWebSocket}.
  */
-export declare const createWebSocket: CreateWebSocket;
+export interface TestCreateWebSocket extends CreateWebSocket {
+    readonly createdUrls: Array<string>;
+    readonly sentMessages: Array<{
+        readonly url: string;
+        readonly data: BufferSource | Blob | string | globalThis.Uint8Array;
+    }>;
+    readonly message: (url: string, data: string | ArrayBuffer | Blob) => void;
+    readonly open: (url: string) => void;
+}
+/** Creates {@link TestCreateWebSocket}. */
+export declare const testCreateWebSocket: (options?: {
+    /** Throw immediately when a socket is created. */
+    readonly throwOnCreate?: boolean;
+    /** Initial open state of created sockets. Defaults to true. */
+    readonly isOpen?: boolean;
+}) => TestCreateWebSocket;
+/**
+ * A native {@link WebSocket} prepared for integration tests by
+ * {@link testSetupWebSocket}.
+ */
+export interface TestSetupWebSocket extends AsyncDisposable {
+    readonly socket: globalThis.WebSocket;
+    readonly send: (data: BufferSource | Blob | string | globalThis.Uint8Array) => void;
+    readonly waitForMessage: () => Promise<string | globalThis.Uint8Array>;
+}
+/** Opens a native {@link WebSocket} and returns {@link TestSetupWebSocket}. */
+export declare const testSetupWebSocket: (url: string) => Promise<TestSetupWebSocket>;
 //# sourceMappingURL=WebSocket.d.ts.map

package/dist/src/WebSocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebSocket.d.ts","sourceRoot":"","sources":["../../src/WebSocket.ts"],"names":[],"mappings":"AACA,OAAO,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAS,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG5D,yDAAyD;AACzD,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C;;;OAGG;IACH,IAAI,EAAE,CACJ,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,GAAG,eAAe,KACpD,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAEtC,QAAQ,CAAC,aAAa,EAAE,MAAM,mBAAmB,CAAC;IAElD,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC;AAED,mCAAmC;AACnC,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE/E,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,KACvB,SAAS,CAAC;AAEf,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAEnC,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAEpC,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB,qCAAqC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAE1C,8CAA8C;IAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAEtC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAExD,kCAAkC;IAClC,YAAY,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC,CAAC;IAEjE;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,UAAU,CAAC,SAAS,CAAC;CACpD;AAED,MAAM,MAAM,cAAc,GACtB,qBAAqB,GACrB,wBAAwB,GACxB,UAAU,CAAC,mBAAmB,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,GAC3B,qBAAqB,GACrB,6BAA6B,CAAC;AAElC,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,EAAE,eA6H7B,CAAC"}
+{"version":3,"file":"WebSocket.d.ts","sourceRoot":"","sources":["../../src/WebSocket.ts"],"names":[],"mappings":"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"}