@durable-streams/client 0.1.2 → 0.1.3

package/README.md

@@ -1,6 +1,12 @@
 # @durable-streams/client
 
-TypeScript client for the Electric Durable Streams protocol.
+TypeScript client for the Durable Streams protocol.
+
+## Installation
+
+```bash
+npm install @durable-streams/client
+```
 
 ## Overview
 

package/dist/index.cjs

@@ -466,6 +466,7 @@ async function* parseSSEStream(stream$1, signal) {
 			const { done, value } = await reader.read();
 			if (done) break;
 			buffer += decoder.decode(value, { stream: true });
+			buffer = buffer.replace(/\r\n/g, `\n`).replace(/\r/g, `\n`);
 			const lines = buffer.split(`\n`);
 			buffer = lines.pop() ?? ``;
 			for (const line of lines) if (line === ``) {
@@ -1180,6 +1181,78 @@ async function resolveParams(params) {
 	else resolved[key] = value;
 	return resolved;
 }
+const warnedOrigins = new Set();
+/**
+* Safely read NODE_ENV without triggering "process is not defined" errors.
+* Works in both browser and Node.js environments.
+*/
+function getNodeEnvSafely() {
+	if (typeof process === `undefined`) return void 0;
+	return process.env?.NODE_ENV;
+}
+/**
+* Check if we're in a browser environment.
+*/
+function isBrowserEnvironment() {
+	return typeof globalThis.window !== `undefined`;
+}
+/**
+* Get window.location.href safely, returning undefined if not available.
+*/
+function getWindowLocationHref() {
+	if (typeof globalThis.window !== `undefined` && typeof globalThis.window.location !== `undefined`) return globalThis.window.location.href;
+	return void 0;
+}
+/**
+* Resolve a URL string, handling relative URLs in browser environments.
+* Returns undefined if the URL cannot be parsed.
+*/
+function resolveUrlMaybe(urlString) {
+	try {
+		return new URL(urlString);
+	} catch {
+		const base = getWindowLocationHref();
+		if (base) try {
+			return new URL(urlString, base);
+		} catch {
+			return void 0;
+		}
+		return void 0;
+	}
+}
+/**
+* Warn if using HTTP (not HTTPS) URL in a browser environment.
+* HTTP typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1,
+* which can cause slow streams and app freezes with multiple active streams.
+*
+* Features:
+* - Warns only once per origin to prevent log spam
+* - Handles relative URLs by resolving against window.location.href
+* - Safe to call in Node.js environments (no-op)
+* - Skips warning during tests (NODE_ENV=test)
+*/
+function warnIfUsingHttpInBrowser(url, warnOnHttp) {
+	if (warnOnHttp === false) return;
+	const nodeEnv = getNodeEnvSafely();
+	if (nodeEnv === `test`) return;
+	if (!isBrowserEnvironment() || typeof console === `undefined` || typeof console.warn !== `function`) return;
+	const urlStr = url instanceof URL ? url.toString() : url;
+	const parsedUrl = resolveUrlMaybe(urlStr);
+	if (!parsedUrl) return;
+	if (parsedUrl.protocol === `http:`) {
+		if (!warnedOrigins.has(parsedUrl.origin)) {
+			warnedOrigins.add(parsedUrl.origin);
+			console.warn("[DurableStream] Using HTTP (not HTTPS) typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1. This can cause slow streams and app freezes with multiple active streams. Use HTTPS for HTTP/2 support. See https://electric-sql.com/r/electric-http2 for more information.");
+		}
+	}
+}
+/**
+* Reset the HTTP warning state. Only exported for testing purposes.
+* @internal
+*/
+function _resetHttpWarningForTesting() {
+	warnedOrigins.clear();
+}
 
 //#endregion
 //#region src/stream-api.ts
@@ -1787,7 +1860,8 @@ var DurableStream = class DurableStream {
 			offset: options?.offset,
 			live: options?.live,
 			json: options?.json,
-			onError: options?.onError ?? this.#onError
+			onError: options?.onError ?? this.#onError,
+			warnOnHttp: options?.warnOnHttp ?? this.#options.warnOnHttp
 		});
 	}
 	/**
@@ -1848,6 +1922,7 @@ function toReadableStream(source) {
 function validateOptions(options) {
 	if (!options.url) throw new MissingStreamUrlError();
 	if (options.signal && !(options.signal instanceof AbortSignal)) throw new InvalidSignalError();
+	warnIfUsingHttpInBrowser(options.url, options.warnOnHttp);
 }
 
 //#endregion
@@ -1869,7 +1944,9 @@ exports.STREAM_OFFSET_HEADER = STREAM_OFFSET_HEADER
 exports.STREAM_SEQ_HEADER = STREAM_SEQ_HEADER
 exports.STREAM_TTL_HEADER = STREAM_TTL_HEADER
 exports.STREAM_UP_TO_DATE_HEADER = STREAM_UP_TO_DATE_HEADER
+exports._resetHttpWarningForTesting = _resetHttpWarningForTesting
 exports.asAsyncIterableReadableStream = asAsyncIterableReadableStream
 exports.createFetchWithBackoff = createFetchWithBackoff
 exports.createFetchWithConsumedBody = createFetchWithConsumedBody
-exports.stream = stream
+exports.stream = stream
+exports.warnIfUsingHttpInBrowser = warnIfUsingHttpInBrowser

package/dist/index.d.cts

@@ -249,6 +249,14 @@ interface StreamOptions {
   * fall back to long-polling mode.
   */
   sseResilience?: SSEResilienceOptions;
+  /**
+  * Whether to warn when using HTTP (not HTTPS) URLs in browser environments.
+  * HTTP limits browsers to 6 concurrent connections (HTTP/1.1), which can
+  * cause slow streams and app freezes with multiple active streams.
+  *
+  * @default true
+  */
+  warnOnHttp?: boolean;
 }
 /**
 * Options for SSE connection resilience.
@@ -374,6 +382,14 @@ interface StreamHandleOptions {
   * @default true
   */
   batching?: boolean;
+  /**
+  * Whether to warn when using HTTP (not HTTPS) URLs in browser environments.
+  * HTTP limits browsers to 6 concurrent connections (HTTP/1.1), which can
+  * cause slow streams and app freezes with multiple active streams.
+  *
+  * @default true
+  */
+  warnOnHttp?: boolean;
 }
 /**
 * Options for creating a new stream.
@@ -944,6 +960,26 @@ declare class DurableStream {
   stream<TJson = unknown>(options?: Omit<StreamOptions, `url`>): Promise<StreamResponse<TJson>>;
 }
 
+//#endregion
+//#region src/utils.d.ts
+/**
+* Warn if using HTTP (not HTTPS) URL in a browser environment.
+* HTTP typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1,
+* which can cause slow streams and app freezes with multiple active streams.
+*
+* Features:
+* - Warns only once per origin to prevent log spam
+* - Handles relative URLs by resolving against window.location.href
+* - Safe to call in Node.js environments (no-op)
+* - Skips warning during tests (NODE_ENV=test)
+*/
+declare function warnIfUsingHttpInBrowser(url: string | URL, warnOnHttp?: boolean): void;
+/**
+* Reset the HTTP warning state. Only exported for testing purposes.
+* @internal
+*/
+declare function _resetHttpWarningForTesting(): void;
+
 //#endregion
 //#region src/error.d.ts
 /**
@@ -1069,4 +1105,4 @@ declare const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string>;
 declare const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 //#endregion
-export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream };
+export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };

package/dist/index.d.ts

@@ -249,6 +249,14 @@ interface StreamOptions {
   * fall back to long-polling mode.
   */
   sseResilience?: SSEResilienceOptions;
+  /**
+  * Whether to warn when using HTTP (not HTTPS) URLs in browser environments.
+  * HTTP limits browsers to 6 concurrent connections (HTTP/1.1), which can
+  * cause slow streams and app freezes with multiple active streams.
+  *
+  * @default true
+  */
+  warnOnHttp?: boolean;
 }
 /**
 * Options for SSE connection resilience.
@@ -374,6 +382,14 @@ interface StreamHandleOptions {
   * @default true
   */
   batching?: boolean;
+  /**
+  * Whether to warn when using HTTP (not HTTPS) URLs in browser environments.
+  * HTTP limits browsers to 6 concurrent connections (HTTP/1.1), which can
+  * cause slow streams and app freezes with multiple active streams.
+  *
+  * @default true
+  */
+  warnOnHttp?: boolean;
 }
 /**
 * Options for creating a new stream.
@@ -944,6 +960,26 @@ declare class DurableStream {
   stream<TJson = unknown>(options?: Omit<StreamOptions, `url`>): Promise<StreamResponse<TJson>>;
 }
 
+//#endregion
+//#region src/utils.d.ts
+/**
+* Warn if using HTTP (not HTTPS) URL in a browser environment.
+* HTTP typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1,
+* which can cause slow streams and app freezes with multiple active streams.
+*
+* Features:
+* - Warns only once per origin to prevent log spam
+* - Handles relative URLs by resolving against window.location.href
+* - Safe to call in Node.js environments (no-op)
+* - Skips warning during tests (NODE_ENV=test)
+*/
+declare function warnIfUsingHttpInBrowser(url: string | URL, warnOnHttp?: boolean): void;
+/**
+* Reset the HTTP warning state. Only exported for testing purposes.
+* @internal
+*/
+declare function _resetHttpWarningForTesting(): void;
+
 //#endregion
 //#region src/error.d.ts
 /**
@@ -1069,4 +1105,4 @@ declare const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string>;
 declare const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 //#endregion
-export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream };
+export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };

package/dist/index.js

@@ -442,6 +442,7 @@ async function* parseSSEStream(stream$1, signal) {
 			const { done, value } = await reader.read();
 			if (done) break;
 			buffer += decoder.decode(value, { stream: true });
+			buffer = buffer.replace(/\r\n/g, `\n`).replace(/\r/g, `\n`);
 			const lines = buffer.split(`\n`);
 			buffer = lines.pop() ?? ``;
 			for (const line of lines) if (line === ``) {
@@ -1156,6 +1157,78 @@ async function resolveParams(params) {
 	else resolved[key] = value;
 	return resolved;
 }
+const warnedOrigins = new Set();
+/**
+* Safely read NODE_ENV without triggering "process is not defined" errors.
+* Works in both browser and Node.js environments.
+*/
+function getNodeEnvSafely() {
+	if (typeof process === `undefined`) return void 0;
+	return process.env?.NODE_ENV;
+}
+/**
+* Check if we're in a browser environment.
+*/
+function isBrowserEnvironment() {
+	return typeof globalThis.window !== `undefined`;
+}
+/**
+* Get window.location.href safely, returning undefined if not available.
+*/
+function getWindowLocationHref() {
+	if (typeof globalThis.window !== `undefined` && typeof globalThis.window.location !== `undefined`) return globalThis.window.location.href;
+	return void 0;
+}
+/**
+* Resolve a URL string, handling relative URLs in browser environments.
+* Returns undefined if the URL cannot be parsed.
+*/
+function resolveUrlMaybe(urlString) {
+	try {
+		return new URL(urlString);
+	} catch {
+		const base = getWindowLocationHref();
+		if (base) try {
+			return new URL(urlString, base);
+		} catch {
+			return void 0;
+		}
+		return void 0;
+	}
+}
+/**
+* Warn if using HTTP (not HTTPS) URL in a browser environment.
+* HTTP typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1,
+* which can cause slow streams and app freezes with multiple active streams.
+*
+* Features:
+* - Warns only once per origin to prevent log spam
+* - Handles relative URLs by resolving against window.location.href
+* - Safe to call in Node.js environments (no-op)
+* - Skips warning during tests (NODE_ENV=test)
+*/
+function warnIfUsingHttpInBrowser(url, warnOnHttp) {
+	if (warnOnHttp === false) return;
+	const nodeEnv = getNodeEnvSafely();
+	if (nodeEnv === `test`) return;
+	if (!isBrowserEnvironment() || typeof console === `undefined` || typeof console.warn !== `function`) return;
+	const urlStr = url instanceof URL ? url.toString() : url;
+	const parsedUrl = resolveUrlMaybe(urlStr);
+	if (!parsedUrl) return;
+	if (parsedUrl.protocol === `http:`) {
+		if (!warnedOrigins.has(parsedUrl.origin)) {
+			warnedOrigins.add(parsedUrl.origin);
+			console.warn("[DurableStream] Using HTTP (not HTTPS) typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1. This can cause slow streams and app freezes with multiple active streams. Use HTTPS for HTTP/2 support. See https://electric-sql.com/r/electric-http2 for more information.");
+		}
+	}
+}
+/**
+* Reset the HTTP warning state. Only exported for testing purposes.
+* @internal
+*/
+function _resetHttpWarningForTesting() {
+	warnedOrigins.clear();
+}
 
 //#endregion
 //#region src/stream-api.ts
@@ -1763,7 +1836,8 @@ var DurableStream = class DurableStream {
 			offset: options?.offset,
 			live: options?.live,
 			json: options?.json,
-			onError: options?.onError ?? this.#onError
+			onError: options?.onError ?? this.#onError,
+			warnOnHttp: options?.warnOnHttp ?? this.#options.warnOnHttp
 		});
 	}
 	/**
@@ -1824,7 +1898,8 @@ function toReadableStream(source) {
 function validateOptions(options) {
 	if (!options.url) throw new MissingStreamUrlError();
 	if (options.signal && !(options.signal instanceof AbortSignal)) throw new InvalidSignalError();
+	warnIfUsingHttpInBrowser(options.url, options.warnOnHttp);
 }
 
 //#endregion
-export { BackoffDefaults, CURSOR_QUERY_PARAM, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, FetchBackoffAbortError, FetchError, InvalidSignalError, LIVE_QUERY_PARAM, MissingStreamUrlError, OFFSET_QUERY_PARAM, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream };
+export { BackoffDefaults, CURSOR_QUERY_PARAM, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, FetchBackoffAbortError, FetchError, InvalidSignalError, LIVE_QUERY_PARAM, MissingStreamUrlError, OFFSET_QUERY_PARAM, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/client",
   "description": "TypeScript client for the Durable Streams protocol",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,7 @@
   "devDependencies": {
     "fast-check": "^4.4.0",
     "tsdown": "^0.9.0",
-    "@durable-streams/server": "0.1.2"
+    "@durable-streams/server": "0.1.4"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/index.ts

@@ -20,6 +20,9 @@ export { stream } from "./stream-api"
 // DurableStream class for read/write operations
 export { DurableStream, type DurableStreamOptions } from "./stream"
 
+// HTTP warning utility
+export { warnIfUsingHttpInBrowser, _resetHttpWarningForTesting } from "./utils"
+
 // ============================================================================
 // Types
 // ============================================================================

package/src/sse.ts

@@ -50,6 +50,9 @@ export async function* parseSSEStream(
 
       buffer += decoder.decode(value, { stream: true })
 
+      // Normalize line endings: CRLF → LF, lone CR → LF (per SSE spec)
+      buffer = buffer.replace(/\r\n/g, `\n`).replace(/\r/g, `\n`)
+
       // Process complete lines
       const lines = buffer.split(`\n`)
       // Keep the last incomplete line in the buffer

package/src/stream.ts

@@ -24,7 +24,12 @@ import {
   createFetchWithConsumedBody,
 } from "./fetch"
 import { stream as streamFn } from "./stream-api"
-import { handleErrorResponse, resolveHeaders, resolveParams } from "./utils"
+import {
+  handleErrorResponse,
+  resolveHeaders,
+  resolveParams,
+  warnIfUsingHttpInBrowser,
+} from "./utils"
 import type { BackoffOptions } from "./fetch"
 import type { queueAsPromised } from "fastq"
 import type {
@@ -742,6 +747,7 @@ export class DurableStream {
       live: options?.live,
       json: options?.json,
       onError: options?.onError ?? this.#onError,
+      warnOnHttp: options?.warnOnHttp ?? this.#options.warnOnHttp,
     })
   }
 
@@ -864,4 +870,5 @@ function validateOptions(options: Partial<DurableStreamOptions>): void {
   if (options.signal && !(options.signal instanceof AbortSignal)) {
     throw new InvalidSignalError()
   }
+  warnIfUsingHttpInBrowser(options.url, options.warnOnHttp)
 }

package/src/types.ts

@@ -158,6 +158,15 @@ export interface StreamOptions {
    * fall back to long-polling mode.
    */
   sseResilience?: SSEResilienceOptions
+
+  /**
+   * Whether to warn when using HTTP (not HTTPS) URLs in browser environments.
+   * HTTP limits browsers to 6 concurrent connections (HTTP/1.1), which can
+   * cause slow streams and app freezes with multiple active streams.
+   *
+   * @default true
+   */
+  warnOnHttp?: boolean
 }
 
 /**
@@ -310,6 +319,15 @@ export interface StreamHandleOptions {
    * @default true
    */
   batching?: boolean
+
+  /**
+   * Whether to warn when using HTTP (not HTTPS) URLs in browser environments.
+   * HTTP limits browsers to 6 concurrent connections (HTTP/1.1), which can
+   * cause slow streams and app freezes with multiple active streams.
+   *
+   * @default true
+   */
+  warnOnHttp?: boolean
 }
 
 /**

package/src/utils.ts

@@ -102,3 +102,123 @@ export async function resolveValue<T>(
   }
   return value
 }
+
+// Module-level Set to track origins we've already warned about (prevents log spam)
+const warnedOrigins = new Set<string>()
+
+/**
+ * Safely read NODE_ENV without triggering "process is not defined" errors.
+ * Works in both browser and Node.js environments.
+ */
+function getNodeEnvSafely(): string | undefined {
+  if (typeof process === `undefined`) return undefined
+  // Use optional chaining for process.env in case it's undefined (e.g., in some bundler environments)
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return process.env?.NODE_ENV
+}
+
+/**
+ * Check if we're in a browser environment.
+ */
+function isBrowserEnvironment(): boolean {
+  return typeof globalThis.window !== `undefined`
+}
+
+/**
+ * Get window.location.href safely, returning undefined if not available.
+ */
+function getWindowLocationHref(): string | undefined {
+  if (
+    typeof globalThis.window !== `undefined` &&
+    typeof globalThis.window.location !== `undefined`
+  ) {
+    return globalThis.window.location.href
+  }
+  return undefined
+}
+
+/**
+ * Resolve a URL string, handling relative URLs in browser environments.
+ * Returns undefined if the URL cannot be parsed.
+ */
+function resolveUrlMaybe(urlString: string): URL | undefined {
+  try {
+    // First try parsing as an absolute URL
+    return new URL(urlString)
+  } catch {
+    // If that fails and we're in a browser, try resolving as relative URL
+    const base = getWindowLocationHref()
+    if (base) {
+      try {
+        return new URL(urlString, base)
+      } catch {
+        return undefined
+      }
+    }
+    return undefined
+  }
+}
+
+/**
+ * Warn if using HTTP (not HTTPS) URL in a browser environment.
+ * HTTP typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1,
+ * which can cause slow streams and app freezes with multiple active streams.
+ *
+ * Features:
+ * - Warns only once per origin to prevent log spam
+ * - Handles relative URLs by resolving against window.location.href
+ * - Safe to call in Node.js environments (no-op)
+ * - Skips warning during tests (NODE_ENV=test)
+ */
+export function warnIfUsingHttpInBrowser(
+  url: string | URL,
+  warnOnHttp?: boolean
+): void {
+  // Skip warning if explicitly disabled
+  if (warnOnHttp === false) return
+
+  // Skip warning during tests
+  const nodeEnv = getNodeEnvSafely()
+  if (nodeEnv === `test`) {
+    return
+  }
+
+  // Only warn in browser environments
+  if (
+    !isBrowserEnvironment() ||
+    typeof console === `undefined` ||
+    typeof console.warn !== `function`
+  ) {
+    return
+  }
+
+  // Parse the URL (handles both absolute and relative URLs)
+  const urlStr = url instanceof URL ? url.toString() : url
+  const parsedUrl = resolveUrlMaybe(urlStr)
+
+  if (!parsedUrl) {
+    // Could not parse URL - silently skip
+    return
+  }
+
+  // Check if URL uses HTTP protocol
+  if (parsedUrl.protocol === `http:`) {
+    // Only warn once per origin
+    if (!warnedOrigins.has(parsedUrl.origin)) {
+      warnedOrigins.add(parsedUrl.origin)
+      console.warn(
+        `[DurableStream] Using HTTP (not HTTPS) typically limits browsers to ~6 concurrent connections per origin under HTTP/1.1. ` +
+          `This can cause slow streams and app freezes with multiple active streams. ` +
+          `Use HTTPS for HTTP/2 support. See https://electric-sql.com/r/electric-http2 for more information.`
+      )
+    }
+  }
+}
+
+/**
+ * Reset the HTTP warning state. Only exported for testing purposes.
+ * @internal
+ */
+export function _resetHttpWarningForTesting(): void {
+  warnedOrigins.clear()
+}