snapreq 0.0.1 → 0.0.3

package/README.md

@@ -15,6 +15,19 @@ The same code runs everywhere. Where a platform cannot provide a feature (Unix s
 npm install snapreq
 ```
 
+## Imports
+
+snapreq has **no barrel entry point** — you import each piece from its own subpath so a bundler (Metro/Expo, webpack, …) only pulls in what you use, and the HTTP client never drags the WebSocket client into your bundle:
+
+```js
+import SnapReq from "snapreq"                       // the HTTP client
+import SnapReqWebSocketClient from "snapreq/websocket"
+import {SnapReqHttpError, SnapReqUnsupportedFeatureError} from "snapreq/errors"
+import {defaultRetryableError} from "snapreq/retry"
+import SnapReqResponse from "snapreq/response"
+import SnapReqHeaders from "snapreq/headers"
+```
+
 ## HTTP
 
 ```js
@@ -69,7 +82,7 @@ await client.get("/flaky", {retry: true})
 await client.get("/flaky", {retry: {tries: 5, waitMs: 200, retryableStatuses: [503]}})
 
 // Compose extra rules on top of the default network classifier:
-import {defaultRetryableError} from "snapreq"
+import {defaultRetryableError} from "snapreq/retry"
 
 await client.get("/x", {retry: {shouldRetry: (error) => defaultRetryableError(error) || isMyCase(error)}})
 ```
@@ -118,7 +131,7 @@ const caps = await client.capabilities()
 A WebSocket client over `globalThis.WebSocket` with auto-reconnect, session resumption, request/response calls, channel subscriptions and 1:1 connections.
 
 ```js
-import {SnapReqWebSocketClient} from "snapreq"
+import SnapReqWebSocketClient from "snapreq/websocket"
 
 const client = new SnapReqWebSocketClient({url: "wss://example.com/websocket"})
 
@@ -137,7 +150,7 @@ await connection.ready
 connection.sendMessage({text: "hi"})
 ```
 
-Optional adapters: `networkMonitor` (gate reconnects on online state) and `sessionStore` (persist the session id across reloads).
+Optional adapters: `networkMonitor` (gate reconnects on online state), `sessionStore` (persist the session id across reloads) and `deserialize` (a `(value) => value` transform applied inside `response.json()` so an app can re-hydrate its own wire format).
 
 ## License
 

package/package.json

@@ -1,17 +1,33 @@
 {
   "name": "snapreq",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Cross-platform HTTP and WebSocket client with one API across Node, web, Expo and React Native",
   "type": "module",
-  "main": "src/index.js",
+  "main": "./src/snap-req.js",
+  "types": "./types/snap-req.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {"types": "./types/snap-req.d.ts", "default": "./src/snap-req.js"},
+    "./websocket": {"types": "./types/websocket/websocket-client.d.ts", "default": "./src/websocket/websocket-client.js"},
+    "./errors": {"types": "./types/errors.d.ts", "default": "./src/errors.js"},
+    "./headers": {"types": "./types/headers.d.ts", "default": "./src/headers.js"},
+    "./response": {"types": "./types/response.d.ts", "default": "./src/response.js"},
+    "./retry": {"types": "./types/retry.d.ts", "default": "./src/retry.js"},
+    "./capabilities": {"types": "./types/capabilities.d.ts", "default": "./src/capabilities.js"},
+    "./transports/select": {"types": "./types/transports/select.d.ts", "default": "./src/transports/select.js"},
+    "./transports/fetch": {"types": "./types/transports/fetch-transport.d.ts", "default": "./src/transports/fetch-transport.js"},
+    "./transports/xhr": {"types": "./types/transports/xhr-transport.d.ts", "default": "./src/transports/xhr-transport.js"},
+    "./*": {"types": "./types/*.d.ts", "default": "./src/*.js"}
   },
   "files": [
-    "src/**"
+    "src/**",
+    "types/**"
   ],
   "scripts": {
+    "all-checks": "npm run typecheck && npm run lint && npm run test",
+    "build:types": "tsc -p tsconfig.build.json",
     "lint": "eslint src spec",
+    "prepublishOnly": "npm run build:types",
+    "release:patch": "release-patch",
     "test": "node --test \"spec/**/*-spec.js\"",
     "typecheck": "tsc --noEmit"
   },
@@ -33,6 +49,7 @@
     "eslint": "^10.3.0",
     "eslint-plugin-jsdoc": "^62.9.0",
     "globals": "^16.0.0",
+    "release-patch": "^1.0.0",
     "typescript": "^6.0.3",
     "ws": "^8.21.0"
   }

package/src/websocket/websocket-client.js

@@ -31,11 +31,14 @@ export default class SnapReqWebSocketClient {
    * @param {{getIsOnline?: () => boolean | Promise<boolean>, subscribe?: (callback: (isOnline: boolean) => void) => (() => void) | {remove: () => void}}} [args.networkMonitor] - Optional online-state adapter. When provided, auto-reconnect can wait for the network to report online before reconnecting, and open sockets are closed when the monitor reports offline.
    * @param {number[]} [args.reconnectDelays] - Backoff delays in ms (default: [1000, 2000, 4000, 8000, 15000]).
    * @param {{get: () => string | null | undefined | Promise<string | null | undefined>, set: (sessionId: string) => void | Promise<void>, clear: () => void | Promise<void>}} [args.sessionStore] - Optional sessionId persistence hook surviving reloads (localStorage, a cookie, SQLite, etc.).
+   * @param {(value: any) => any} [args.deserialize] - Optional transform applied to a response body inside `response.json()`. Lets an app re-hydrate its own wire format. Defaults to identity.
    */
-  constructor({autoReconnect = true, debug = false, networkMonitor, reconnectDelays, sessionStore, url} = /** @type {any} */ ({})) {
+  constructor({autoReconnect = true, debug = false, deserialize, networkMonitor, reconnectDelays, sessionStore, url} = /** @type {any} */ ({})) {
     if (!globalThis.WebSocket) throw new Error("WebSocket global is not available")
     if (!url) throw new Error("SnapReqWebSocketClient requires a url")
 
+    /** @type {(value: any) => any} */
+    this._deserialize = deserialize || ((value) => value)
     /** @type {boolean} */
     this.autoReconnect = autoReconnect
     this.debug = debug
@@ -637,7 +640,7 @@ export default class SnapReqWebSocketClient {
 
       if (pending) {
         this.pendingRequests.delete(id)
-        pending.resolve(new SnapReqWebSocketResponse(message))
+        pending.resolve(new SnapReqWebSocketResponse(message, this._deserialize))
       } else {
         this._debug(`No pending request for response id ${id}`)
       }
@@ -1006,8 +1009,9 @@ export default class SnapReqWebSocketClient {
 export class SnapReqWebSocketResponse {
   /**
    * @param {object} message - The response message.
+   * @param {(value: any) => any} [deserialize] - Transform applied to the parsed body in `json()`. Defaults to identity.
    */
-  constructor(message) {
+  constructor(message, deserialize) {
     const responseMessage = /** @type {{body?: any, headers?: Record<string, any>, id?: string | number | null, statusCode?: number, statusMessage?: string, type?: string}} */ (message)
 
     this.body = responseMessage.body
@@ -1016,14 +1020,15 @@ export class SnapReqWebSocketResponse {
     this.statusCode = responseMessage.statusCode || 200
     this.statusMessage = responseMessage.statusMessage || "OK"
     this.type = responseMessage.type
+    this._deserialize = deserialize || ((value) => value)
   }
 
-  /** @returns {any} - The parsed JSON body. */
+  /** @returns {any} - The parsed (and optionally deserialized) JSON body. */
   json() {
     if (typeof this.body !== "string") {
       throw new Error("Response body is not a string")
     }
 
-    return JSON.parse(this.body)
+    return this._deserialize(JSON.parse(this.body))
   }
 }

package/types/capabilities.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @typedef {object} TransportCapabilities
+ * @property {boolean} unixSocket - Connect over a Unix domain socket.
+ * @property {boolean} tlsClientCert - Present a client certificate / custom CA for TLS.
+ * @property {boolean} requestCompression - Compress the request body (gzip/deflate/br/zstd).
+ * @property {boolean} responseStreaming - Expose the response body as a stream before it is fully read.
+ * @property {boolean} requestStreaming - Send a streamed (async-iterable) request body.
+ * @property {boolean} keepAlive - Reuse connections across requests (HTTP keep-alive).
+ * @property {boolean} abort - Cancel an in-flight request via an `AbortSignal`.
+ */
+/**
+ * Builds a fully-populated capability object so callers can read every flag
+ * without undefined checks.
+ * @param {Partial<TransportCapabilities>} overrides - Capabilities the transport supports.
+ * @returns {TransportCapabilities} - Complete capability flags.
+ */
+export function buildCapabilities(overrides: Partial<TransportCapabilities>): TransportCapabilities;
+export type TransportCapabilities = {
+    /**
+     * - Connect over a Unix domain socket.
+     */
+    unixSocket: boolean;
+    /**
+     * - Present a client certificate / custom CA for TLS.
+     */
+    tlsClientCert: boolean;
+    /**
+     * - Compress the request body (gzip/deflate/br/zstd).
+     */
+    requestCompression: boolean;
+    /**
+     * - Expose the response body as a stream before it is fully read.
+     */
+    responseStreaming: boolean;
+    /**
+     * - Send a streamed (async-iterable) request body.
+     */
+    requestStreaming: boolean;
+    /**
+     * - Reuse connections across requests (HTTP keep-alive).
+     */
+    keepAlive: boolean;
+    /**
+     * - Cancel an in-flight request via an `AbortSignal`.
+     */
+    abort: boolean;
+};

package/types/errors.d.ts

@@ -0,0 +1,64 @@
+/** Base class for every error thrown by snapreq. */
+export class SnapReqError extends Error {
+    /** @param {string} message - Human readable description. */
+    constructor(message: string);
+}
+/**
+ * Thrown when a request completes with a non-2xx status and the caller asked
+ * snapreq to treat error statuses as failures (`throwOnError`, the default for
+ * the high-level helpers). Carries enough metadata to build a friendly message
+ * without re-reading the response.
+ */
+export class SnapReqHttpError extends SnapReqError {
+    /**
+     * @param {object} options - Error metadata.
+     * @param {string} options.message - Human readable description.
+     * @param {string} options.method - HTTP method used for the request.
+     * @param {string} options.url - Fully resolved request URL.
+     * @param {number} options.status - HTTP status code returned by the server.
+     * @param {string} [options.statusText] - HTTP status text returned by the server.
+     * @param {string} [options.responseText] - Decoded response body, when available.
+     * @param {import("./response.js").default} [options.response] - The response that failed.
+     */
+    constructor({ message, method, url, status, statusText, responseText, response }: {
+        message: string;
+        method: string;
+        url: string;
+        status: number;
+        statusText?: string;
+        responseText?: string;
+        response?: import("./response.js").default;
+    });
+    method: string;
+    url: string;
+    status: number;
+    statusText: string;
+    responseText: string;
+    response: import("./response.js").default;
+}
+/**
+ * Thrown when a request asks for a capability the active transport cannot
+ * provide on the current platform (for example a Unix socket or request-body
+ * compression in a browser). The API stays identical across platforms; this
+ * error is how snapreq tells you a specific feature had to be left out.
+ */
+export class SnapReqUnsupportedFeatureError extends SnapReqError {
+    /**
+     * @param {object} options - Error metadata.
+     * @param {string} options.feature - The capability that is not supported.
+     * @param {string} options.transport - Name of the active transport.
+     * @param {string} [options.detail] - Optional extra context.
+     */
+    constructor({ feature, transport, detail }: {
+        feature: string;
+        transport: string;
+        detail?: string;
+    });
+    feature: string;
+    transport: string;
+}
+/** Thrown when a request is aborted via an `AbortSignal`. */
+export class SnapReqAbortError extends SnapReqError {
+    /** @param {string} [message] - Human readable description. */
+    constructor(message?: string);
+}

package/types/headers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A tiny case-insensitive header bag. Works the same on every platform and
+ * avoids depending on the DOM `Headers` global (absent in some runtimes) or on
+ * Node's header handling. Header values are always stored as strings.
+ */
+export default class SnapReqHeaders {
+    /**
+     * @param {Record<string, string | number | string[]> | SnapReqHeaders | Iterable<[string, string]>} [init] - Initial headers.
+     */
+    constructor(init?: Record<string, string | number | string[]> | SnapReqHeaders | Iterable<[string, string]>);
+    /** @type {Map<string, {name: string, value: string}>} - Keyed by lower-cased name. */
+    _map: Map<string, {
+        name: string;
+        value: string;
+    }>;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @param {string | number} value - Header value.
+     * @returns {void}
+     */
+    set(name: string, value: string | number): void;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @returns {string | null} - The header value or null when absent.
+     */
+    get(name: string): string | null;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @returns {boolean} - Whether the header is present.
+     */
+    has(name: string): boolean;
+    /**
+     * @param {string} name - Header name (case-insensitive).
+     * @returns {void}
+     */
+    delete(name: string): void;
+    /**
+     * @yields {[string, string]} - Name/value pair preserving original casing.
+     * @returns {IterableIterator<[string, string]>} - Name/value pairs preserving original casing.
+     */
+    entries(): IterableIterator<[string, string]>;
+    /** @returns {[string, string][]} - Name/value pairs preserving original casing. */
+    toArray(): [string, string][];
+    /**
+     * Plain object form keyed by the original header casing. Suitable for
+     * passing straight to `http.request` or `fetch`.
+     * @returns {Record<string, string>} - Header object.
+     */
+    toObject(): Record<string, string>;
+}

package/types/request.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Joins a base URL and a path and appends query parameters. `path` may be a
+ * fully-qualified URL, in which case the base is ignored.
+ * @param {string | undefined} baseUrl - Origin (and optional base path).
+ * @param {string} path - Path or absolute URL.
+ * @param {Record<string, string | number | boolean | null | undefined> | undefined} query - Query parameters.
+ * @returns {string} - Resolved absolute URL.
+ */
+export function buildUrl(baseUrl: string | undefined, path: string, query: Record<string, string | number | boolean | null | undefined> | undefined): string;
+/**
+ * Determines whether a value should be sent as a streamed request body.
+ * @param {unknown} body - Candidate body value.
+ * @returns {boolean} - Whether the body is a stream.
+ */
+export function isStreamBody(body: unknown): boolean;
+/**
+ * Normalizes a user-supplied body into one of a small set of shapes and applies
+ * a default `Content-Type` header when the caller did not set one.
+ * @param {unknown} body - Raw body value.
+ * @param {SnapReqHeaders} headers - Headers to receive a default `Content-Type`.
+ * @returns {NormalizedBody} - Normalized body descriptor.
+ */
+export function normalizeBody(body: unknown, headers: SnapReqHeaders): NormalizedBody;
+export type CompressionEncoding = "identity" | "gzip" | "deflate" | "br" | "zstd";
+export type NormalizedBody = {
+    /**
+     * - Shape of the body payload.
+     */
+    kind: "none" | "text" | "bytes" | "stream";
+    /**
+     * - The payload itself.
+     */
+    value: string | Uint8Array | AsyncIterable<Uint8Array> | null;
+};
+import SnapReqHeaders from "./headers.js";

package/types/response.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A platform-agnostic response. Transports build it with either a fully-read
+ * body (`bytes`) or a `stream` (an async iterable of `Uint8Array`) that the
+ * read helpers buffer on first use. The body can be read exactly once as a
+ * stream; the buffering helpers may be called repeatedly because they cache.
+ */
+export default class SnapReqResponse {
+    /**
+     * @param {object} options - Response data.
+     * @param {string} options.url - Fully resolved request URL.
+     * @param {string} options.method - HTTP method used for the request.
+     * @param {number} options.status - HTTP status code.
+     * @param {string} [options.statusText] - HTTP status text.
+     * @param {SnapReqHeaders} [options.headers] - Response headers.
+     * @param {Uint8Array} [options.bytes] - Fully-read body, when the transport already buffered it.
+     * @param {AsyncIterable<Uint8Array>} [options.stream] - Streamed body, when the transport supports streaming.
+     * @param {import("node:stream").Readable} [options.nodeStream] - Raw Node stream, when available, for advanced consumers.
+     */
+    constructor({ url, method, status, statusText, headers, bytes, stream, nodeStream }: {
+        url: string;
+        method: string;
+        status: number;
+        statusText?: string;
+        headers?: SnapReqHeaders;
+        bytes?: Uint8Array;
+        stream?: AsyncIterable<Uint8Array>;
+        nodeStream?: import("node:stream").Readable;
+    });
+    url: string;
+    method: string;
+    status: number;
+    statusText: string;
+    headers: SnapReqHeaders;
+    /** @type {Uint8Array | null} */
+    _bytes: Uint8Array | null;
+    /** @type {AsyncIterable<Uint8Array> | null} */
+    _stream: AsyncIterable<Uint8Array> | null;
+    /** @type {import("node:stream").Readable | undefined} */
+    nodeStream: import("node:stream").Readable | undefined;
+    _streamConsumed: boolean;
+    /** @returns {boolean} - Whether the status is in the 2xx range. */
+    get ok(): boolean;
+    /**
+     * Returns the response body as an async iterable of byte chunks. Can only be
+     * called once and only when the transport provided a stream.
+     * @returns {AsyncIterable<Uint8Array>} - The streamed body.
+     */
+    stream(): AsyncIterable<Uint8Array>;
+    /** @returns {boolean} - Whether the body is available as a stream that has not been read yet. */
+    get streamable(): boolean;
+    /**
+     * Reads the whole body into a `Uint8Array`, buffering the stream if needed.
+     * @returns {Promise<Uint8Array>} - The full response body.
+     */
+    bytes(): Promise<Uint8Array>;
+    /**
+     * Reads the whole body as a Node `Buffer`. Node-only convenience; throws when
+     * the `Buffer` global is unavailable.
+     * @returns {Promise<Buffer>} - The full response body as a Buffer.
+     */
+    buffer(): Promise<Buffer>;
+    /**
+     * Reads the whole body and decodes it as a UTF-8 string.
+     * @returns {Promise<string>} - The decoded response body.
+     */
+    text(): Promise<string>;
+    /**
+     * Reads the whole body and parses it as JSON. Returns `null` for an empty
+     * body.
+     * @returns {Promise<any>} - The parsed JSON body.
+     */
+    json(): Promise<any>;
+}
+import SnapReqHeaders from "./headers.js";

package/types/retry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @typedef {object} RetryOptions
+ * @property {number} [tries] - Maximum number of attempts. Defaults to 3.
+ * @property {number} [waitMs] - Delay between attempts in milliseconds. Defaults to 500.
+ * @property {number[]} [retryableStatuses] - HTTP status codes that should be retried. Defaults to 502/503/504.
+ * @property {(error: unknown, attempt: number) => boolean} [shouldRetry] - Override the retryable-error classifier.
+ */
+/**
+ * @typedef {object} NormalizedRetryOptions
+ * @property {number} tries - Maximum number of attempts.
+ * @property {number} waitMs - Delay between attempts in milliseconds.
+ * @property {number[]} retryableStatuses - HTTP status codes that should be retried.
+ * @property {(error: unknown, attempt: number) => boolean} shouldRetry - Retryable-error classifier.
+ */
+/**
+ * The default network-error classifier. Exposed so callers can compose extra
+ * rules on top of it (for example matching server-specific 500 messages).
+ * @param {unknown} error - Error thrown by a transport.
+ * @returns {boolean} - Whether the error is a transient network failure.
+ */
+export function defaultRetryableError(error: unknown): boolean;
+/**
+ * Normalizes the `retry` option into a complete set of retry settings, or
+ * `null` when retries are disabled.
+ * @param {boolean | RetryOptions | undefined} retry - Retry configuration.
+ * @returns {NormalizedRetryOptions | null} - Normalized retry settings.
+ */
+export function normalizeRetryOptions(retry: boolean | RetryOptions | undefined): NormalizedRetryOptions | null;
+/**
+ * Runs a request attempt, retrying transient network errors and retryable HTTP
+ * statuses. Retries are only used for buffered requests — the caller must not
+ * apply this to streamed responses.
+ * @param {() => Promise<import("./response.js").default>} attempt - Performs one request attempt.
+ * @param {NormalizedRetryOptions} retry - Normalized retry settings.
+ * @returns {Promise<import("./response.js").default>} - The successful (or final) response.
+ */
+export function runWithRetry(attempt: () => Promise<import("./response.js").default>, retry: NormalizedRetryOptions): Promise<import("./response.js").default>;
+export type RetryOptions = {
+    /**
+     * - Maximum number of attempts. Defaults to 3.
+     */
+    tries?: number;
+    /**
+     * - Delay between attempts in milliseconds. Defaults to 500.
+     */
+    waitMs?: number;
+    /**
+     * - HTTP status codes that should be retried. Defaults to 502/503/504.
+     */
+    retryableStatuses?: number[];
+    /**
+     * - Override the retryable-error classifier.
+     */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+export type NormalizedRetryOptions = {
+    /**
+     * - Maximum number of attempts.
+     */
+    tries: number;
+    /**
+     * - Delay between attempts in milliseconds.
+     */
+    waitMs: number;
+    /**
+     * - HTTP status codes that should be retried.
+     */
+    retryableStatuses: number[];
+    /**
+     * - Retryable-error classifier.
+     */
+    shouldRetry: (error: unknown, attempt: number) => boolean;
+};