snapreq 0.0.1

package/README.md

@@ -0,0 +1,144 @@
+# snapreq
+
+A cross-platform HTTP and WebSocket client with **one API** across Node, the web, Expo and React Native.
+
+The same code runs everywhere. Where a platform cannot provide a feature (Unix sockets in a browser, request-body compression over `fetch`, …) snapreq raises a clear `SnapReqUnsupportedFeatureError` instead of silently changing behaviour — so the API is identical and the gaps are explicit.
+
+- Zero runtime dependencies.
+- Picks the right transport at runtime: Node `http`/`https`, `fetch`, or `XMLHttpRequest`.
+- `node:*` modules are loaded with a dynamic `import()` from the Node transport only, so web/Expo bundlers (Metro, webpack, …) never try to bundle them.
+- ESM + JSDoc types, checked with `tsc`.
+
+## Install
+
+```sh
+npm install snapreq
+```
+
+## HTTP
+
+```js
+import SnapReq from "snapreq"
+
+const client = new SnapReq({baseUrl: "https://api.example.com"})
+
+const response = await client.get("/users", {query: {page: 1}})
+const users = await response.json()
+
+await client.post("/users", {name: "Ada"})
+```
+
+Every call returns a `SnapReqResponse`:
+
+```js
+response.status          // 200
+response.ok              // status in 200..299
+response.headers.get("content-type")
+await response.json()    // parsed JSON (null for an empty body)
+await response.text()    // UTF-8 string
+await response.bytes()   // Uint8Array
+await response.buffer()  // Node Buffer (Node only)
+```
+
+`request()` does **not** throw on a non-2xx status by default (like `fetch`). Pass `throwOnError: true` (per request or on the client) to get a `SnapReqHttpError` carrying `status`, `responseText` and the `response`.
+
+### Client options
+
+```js
+new SnapReq({
+  baseUrl,        // origin (and optional base path) prefixed onto relative paths
+  headers,        // default headers — object or a factory `() => ({...})` for dynamic auth
+  retry,          // default retry policy (see below)
+  throwOnError,   // throw SnapReqHttpError on non-2xx (default false)
+  credentials,    // fetch credentials mode: "omit" | "same-origin" | "include"
+  transport,      // "auto" (default) | "node" | "fetch" | "xhr" | a transport instance
+
+  // Node transport only:
+  socketPath,     // connect over a Unix domain socket
+  tls,            // {ca, cert, key, rejectUnauthorized}
+  keepAlive       // reuse connections (default true)
+})
+```
+
+### Retry
+
+Retries transient network errors and retryable HTTP statuses (502/503/504 by default). Only applies to buffered requests — never to streamed bodies.
+
+```js
+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"
+
+await client.get("/x", {retry: {shouldRetry: (error) => defaultRetryableError(error) || isMyCase(error)}})
+```
+
+### Streaming
+
+```js
+const response = await client.requestStream({method: "GET", path: "/logs"})
+
+for await (const chunk of response.stream()) {
+  process.stdout.write(chunk) // chunk is a Uint8Array
+}
+```
+
+`requestStream()` requires a transport that supports response streaming and never retries. On Node the raw stream is also available as `response.nodeStream`.
+
+### Request-body compression (Node)
+
+```js
+await client.post("/upload", largePayload, {bodyCompression: "gzip"}) // gzip | deflate | br | zstd
+```
+
+Over `fetch`/`xhr` this raises `SnapReqUnsupportedFeatureError`.
+
+### Capabilities
+
+Each transport advertises what it can do. Inspect them when you need to branch on platform support:
+
+```js
+const caps = await client.capabilities()
+// {unixSocket, tlsClientCert, requestCompression, responseStreaming, requestStreaming, keepAlive, abort}
+```
+
+| Capability          | Node | fetch | xhr |
+| ------------------- | :--: | :---: | :-: |
+| unixSocket          |  ✅  |  —    |  —  |
+| tlsClientCert       |  ✅  |  —    |  —  |
+| requestCompression  |  ✅  |  —    |  —  |
+| responseStreaming   |  ✅  |  ✅   |  —  |
+| requestStreaming    |  ✅  |  —    |  —  |
+| keepAlive           |  ✅  |  —    |  —  |
+| abort               |  ✅  |  ✅   |  ✅ |
+
+## WebSocket
+
+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"
+
+const client = new SnapReqWebSocketClient({url: "wss://example.com/websocket"})
+
+await client.connect()
+
+// Request/response over the socket
+const response = await client.post("/things", {name: "thing"})
+response.json()
+
+// Channel subscription
+const unsubscribe = await client.subscribeAndWait("updates", {}, (payload) => console.log(payload))
+
+// 1:1 connection
+const connection = client.openConnection("ChatConnection", {onMessage: (body) => console.log(body)})
+await connection.ready
+connection.sendMessage({text: "hi"})
+```
+
+Optional adapters: `networkMonitor` (gate reconnects on online state) and `sessionStore` (persist the session id across reloads).
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "snapreq",
+  "version": "0.0.1",
+  "description": "Cross-platform HTTP and WebSocket client with one API across Node, web, Expo and React Native",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/**"
+  ],
+  "scripts": {
+    "lint": "eslint src spec",
+    "test": "node --test \"spec/**/*-spec.js\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "http",
+    "fetch",
+    "websocket",
+    "client",
+    "expo",
+    "react-native",
+    "cross-platform"
+  ],
+  "author": "kasper@diestoeckels.de",
+  "license": "ISC",
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "eslint": "^10.3.0",
+    "eslint-plugin-jsdoc": "^62.9.0",
+    "globals": "^16.0.0",
+    "typescript": "^6.0.3",
+    "ws": "^8.21.0"
+  }
+}

package/src/capabilities.js

@@ -0,0 +1,31 @@
+// @ts-check
+
+/**
+ * @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) {
+  return {
+    unixSocket: false,
+    tlsClientCert: false,
+    requestCompression: false,
+    responseStreaming: false,
+    requestStreaming: false,
+    keepAlive: false,
+    abort: false,
+    ...overrides
+  }
+}

package/src/errors.js

@@ -0,0 +1,69 @@
+// @ts-check
+
+/** Base class for every error thrown by snapreq. */
+export class SnapReqError extends Error {
+  /** @param {string} message - Human readable description. */
+  constructor(message) {
+    super(message)
+    this.name = "SnapReqError"
+  }
+}
+
+/**
+ * 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}) {
+    super(message)
+    this.name = "SnapReqHttpError"
+    this.method = method
+    this.url = url
+    this.status = status
+    this.statusText = statusText
+    this.responseText = responseText
+    this.response = response
+  }
+}
+
+/**
+ * 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}) {
+    super(`The "${transport}" transport does not support ${feature}${detail ? `: ${detail}` : ""}.`)
+    this.name = "SnapReqUnsupportedFeatureError"
+    this.feature = feature
+    this.transport = transport
+  }
+}
+
+/** Thrown when a request is aborted via an `AbortSignal`. */
+export class SnapReqAbortError extends SnapReqError {
+  /** @param {string} [message] - Human readable description. */
+  constructor(message = "Request aborted.") {
+    super(message)
+    this.name = "SnapReqAbortError"
+  }
+}

package/src/headers.js

@@ -0,0 +1,92 @@
+// @ts-check
+
+/**
+ * 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) {
+    /** @type {Map<string, {name: string, value: string}>} - Keyed by lower-cased name. */
+    this._map = new Map()
+
+    if (!init) return
+
+    if (init instanceof SnapReqHeaders) {
+      for (const [name, value] of init.entries()) this.set(name, value)
+    } else if (typeof (/** @type {any} */ (init)[Symbol.iterator]) === "function") {
+      for (const [name, value] of /** @type {Iterable<[string, string]>} */ (init)) this.set(name, value)
+    } else {
+      for (const [name, value] of Object.entries(init)) {
+        if (Array.isArray(value)) {
+          this.set(name, value.join(", "))
+        } else if (value !== undefined && value !== null) {
+          this.set(name, String(value))
+        }
+      }
+    }
+  }
+
+  /**
+   * @param {string} name - Header name (case-insensitive).
+   * @param {string | number} value - Header value.
+   * @returns {void}
+   */
+  set(name, value) {
+    this._map.set(name.toLowerCase(), {name, value: String(value)})
+  }
+
+  /**
+   * @param {string} name - Header name (case-insensitive).
+   * @returns {string | null} - The header value or null when absent.
+   */
+  get(name) {
+    return this._map.get(name.toLowerCase())?.value ?? null
+  }
+
+  /**
+   * @param {string} name - Header name (case-insensitive).
+   * @returns {boolean} - Whether the header is present.
+   */
+  has(name) {
+    return this._map.has(name.toLowerCase())
+  }
+
+  /**
+   * @param {string} name - Header name (case-insensitive).
+   * @returns {void}
+   */
+  delete(name) {
+    this._map.delete(name.toLowerCase())
+  }
+
+  /**
+   * @yields {[string, string]} - Name/value pair preserving original casing.
+   * @returns {IterableIterator<[string, string]>} - Name/value pairs preserving original casing.
+   */
+  *entries() {
+    for (const {name, value} of this._map.values()) yield [name, value]
+  }
+
+  /** @returns {[string, string][]} - Name/value pairs preserving original casing. */
+  toArray() {
+    return [...this.entries()]
+  }
+
+  /**
+   * 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() {
+    /** @type {Record<string, string>} */
+    const object = {}
+
+    for (const {name, value} of this._map.values()) object[name] = value
+
+    return object
+  }
+}

package/src/index.js

@@ -0,0 +1,22 @@
+// @ts-check
+
+import SnapReq from "./snap-req.js"
+
+export default SnapReq
+export {default as SnapReq} from "./snap-req.js"
+export {default as SnapReqResponse} from "./response.js"
+export {default as SnapReqHeaders} from "./headers.js"
+export {
+  SnapReqError,
+  SnapReqHttpError,
+  SnapReqUnsupportedFeatureError,
+  SnapReqAbortError
+} from "./errors.js"
+export {defaultRetryableError} from "./retry.js"
+export {detectRuntime, selectTransport} from "./transports/select.js"
+export {default as FetchTransport} from "./transports/fetch-transport.js"
+export {default as XhrTransport} from "./transports/xhr-transport.js"
+
+// The WebSocket client is exported from its own module so importing the HTTP
+// client never pulls WebSocket code into a bundle that does not need it.
+export {default as SnapReqWebSocketClient} from "./websocket/websocket-client.js"

package/src/request.js

@@ -0,0 +1,104 @@
+// @ts-check
+
+import SnapReqHeaders from "./headers.js"
+
+/**
+ * @typedef {"identity" | "gzip" | "deflate" | "br" | "zstd"} CompressionEncoding
+ */
+
+/**
+ * @typedef {object} NormalizedBody
+ * @property {"none" | "text" | "bytes" | "stream"} kind - Shape of the body payload.
+ * @property {string | Uint8Array | AsyncIterable<Uint8Array> | null} value - The payload itself.
+ */
+
+const ABSOLUTE_URL_REGEX = /^[a-z][a-z0-9+.-]*:\/\//i
+
+/**
+ * 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, path, query) {
+  /** @type {string} */
+  let resolved
+
+  if (ABSOLUTE_URL_REGEX.test(path)) {
+    resolved = path
+  } else if (baseUrl) {
+    resolved = `${baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`
+  } else {
+    resolved = path
+  }
+
+  if (!query) return resolved
+
+  const params = new URLSearchParams()
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null) params.append(key, String(value))
+  }
+
+  const queryString = params.toString()
+
+  if (!queryString) return resolved
+
+  return resolved.includes("?") ? `${resolved}&${queryString}` : `${resolved}?${queryString}`
+}
+
+/**
+ * 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) {
+  return Boolean(
+    body &&
+    typeof body === "object" &&
+    !(body instanceof Uint8Array) &&
+    !(body instanceof ArrayBuffer) &&
+    (typeof (/** @type {any} */ (body).pipe) === "function" || typeof (/** @type {any} */ (body)[Symbol.asyncIterator]) === "function")
+  )
+}
+
+/**
+ * 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, headers) {
+  if (body === undefined || body === null) {
+    return {kind: "none", value: null}
+  }
+
+  if (body instanceof Uint8Array) {
+    if (!headers.has("content-type")) headers.set("Content-Type", "application/octet-stream")
+
+    return {kind: "bytes", value: body}
+  }
+
+  if (body instanceof ArrayBuffer) {
+    if (!headers.has("content-type")) headers.set("Content-Type", "application/octet-stream")
+
+    return {kind: "bytes", value: new Uint8Array(body)}
+  }
+
+  if (isStreamBody(body)) {
+    if (!headers.has("content-type")) headers.set("Content-Type", "application/octet-stream")
+
+    return {kind: "stream", value: /** @type {AsyncIterable<Uint8Array>} */ (body)}
+  }
+
+  if (typeof body === "string") {
+    return {kind: "text", value: body}
+  }
+
+  if (!headers.has("content-type")) headers.set("Content-Type", "application/json")
+
+  return {kind: "text", value: JSON.stringify(body)}
+}

package/src/response.js

@@ -0,0 +1,156 @@
+// @ts-check
+
+import SnapReqHeaders from "./headers.js"
+
+/**
+ * Concatenates a list of byte chunks into a single `Uint8Array`.
+ * @param {Uint8Array[]} chunks - Byte chunks in order.
+ * @returns {Uint8Array} - The concatenated bytes.
+ */
+function concatChunks(chunks) {
+  let total = 0
+
+  for (const chunk of chunks) total += chunk.byteLength
+
+  const result = new Uint8Array(total)
+  let offset = 0
+
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+
+  return result
+}
+
+/**
+ * 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}) {
+    this.url = url
+    this.method = method
+    this.status = status
+    this.statusText = statusText
+    this.headers = headers || new SnapReqHeaders()
+    /** @type {Uint8Array | null} */
+    this._bytes = bytes ?? null
+    /** @type {AsyncIterable<Uint8Array> | null} */
+    this._stream = stream ?? null
+    /** @type {import("node:stream").Readable | undefined} */
+    this.nodeStream = nodeStream
+    this._streamConsumed = false
+  }
+
+  /** @returns {boolean} - Whether the status is in the 2xx range. */
+  get ok() {
+    return this.status >= 200 && this.status < 300
+  }
+
+  /**
+   * 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() {
+    if (!this._stream) {
+      throw new Error("This response has no readable stream (the body was already buffered by the transport).")
+    }
+
+    if (this._streamConsumed) {
+      throw new Error("This response stream has already been consumed.")
+    }
+
+    this._streamConsumed = true
+
+    return this._stream
+  }
+
+  /** @returns {boolean} - Whether the body is available as a stream that has not been read yet. */
+  get streamable() {
+    return Boolean(this._stream) && !this._streamConsumed
+  }
+
+  /**
+   * Reads the whole body into a `Uint8Array`, buffering the stream if needed.
+   * @returns {Promise<Uint8Array>} - The full response body.
+   */
+  async bytes() {
+    if (this._bytes) return this._bytes
+
+    if (!this._stream) {
+      this._bytes = new Uint8Array(0)
+
+      return this._bytes
+    }
+
+    if (this._streamConsumed) {
+      throw new Error("Cannot buffer this response: its stream was already consumed via stream().")
+    }
+
+    this._streamConsumed = true
+
+    /** @type {Uint8Array[]} */
+    const chunks = []
+
+    for await (const chunk of this._stream) {
+      chunks.push(chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk))
+    }
+
+    this._bytes = concatChunks(chunks)
+
+    return this._bytes
+  }
+
+  /**
+   * 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.
+   */
+  async buffer() {
+    if (typeof Buffer === "undefined") {
+      throw new Error("Buffer is not available on this platform; use bytes() instead.")
+    }
+
+    const bytes = await this.bytes()
+
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  }
+
+  /**
+   * Reads the whole body and decodes it as a UTF-8 string.
+   * @returns {Promise<string>} - The decoded response body.
+   */
+  async text() {
+    const bytes = await this.bytes()
+
+    return new TextDecoder("utf-8").decode(bytes)
+  }
+
+  /**
+   * Reads the whole body and parses it as JSON. Returns `null` for an empty
+   * body.
+   * @returns {Promise<any>} - The parsed JSON body.
+   */
+  async json() {
+    const text = await this.text()
+
+    if (!text) return null
+
+    return JSON.parse(text)
+  }
+}