@durable-streams/client 0.1.2 → 0.1.4

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 {
@@ -158,6 +163,11 @@ export class DurableStream {
     this.#options = { ...opts, url: urlStr }
     this.#onError = opts.onError
 
+    // Set contentType from options if provided (for IdempotentProducer and other use cases)
+    if (opts.contentType) {
+      this.contentType = opts.contentType
+    }
+
     // Batching is enabled by default
     this.#batchingEnabled = opts.batching !== false
 
@@ -742,6 +752,7 @@ export class DurableStream {
       live: options?.live,
       json: options?.json,
       onError: options?.onError ?? this.#onError,
+      warnOnHttp: options?.warnOnHttp ?? this.#options.warnOnHttp,
     })
   }
 
@@ -864,4 +875,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
 }
 
 /**
@@ -363,6 +381,26 @@ export interface AppendOptions {
    * AbortSignal for this operation.
    */
   signal?: AbortSignal
+
+  /**
+   * Producer ID for idempotent writes.
+   * Client-supplied stable identifier (e.g., "order-service-1").
+   * Must be provided together with producerEpoch and producerSeq.
+   */
+  producerId?: string
+
+  /**
+   * Producer epoch for idempotent writes.
+   * Client-declared, server-validated monotonically increasing.
+   * Increment on producer restart.
+   */
+  producerEpoch?: number
+
+  /**
+   * Producer sequence for idempotent writes.
+   * Monotonically increasing per epoch, per-batch.
+   */
+  producerSeq?: number
 }
 
 /**
@@ -735,3 +773,76 @@ export interface StreamResponse<TJson = unknown> {
    */
   readonly closed: Promise<void>
 }
+
+// ============================================================================
+// Idempotent Producer Types
+// ============================================================================
+
+/**
+ * Options for creating an IdempotentProducer.
+ */
+export interface IdempotentProducerOptions {
+  /**
+   * Starting epoch (default: 0).
+   * Increment this on producer restart.
+   */
+  epoch?: number
+
+  /**
+   * On 403 Forbidden (stale epoch), automatically retry with epoch+1.
+   * Useful for serverless/ephemeral producers.
+   * @default false
+   */
+  autoClaim?: boolean
+
+  /**
+   * Maximum bytes before sending a batch.
+   * @default 1048576 (1MB)
+   */
+  maxBatchBytes?: number
+
+  /**
+   * Maximum time to wait for more messages before sending batch (ms).
+   * @default 5
+   */
+  lingerMs?: number
+
+  /**
+   * Maximum number of concurrent batches in flight.
+   * Higher values improve throughput at the cost of more memory.
+   * @default 5
+   */
+  maxInFlight?: number
+
+  /**
+   * Custom fetch implementation.
+   */
+  fetch?: typeof globalThis.fetch
+
+  /**
+   * AbortSignal for the producer lifecycle.
+   */
+  signal?: AbortSignal
+
+  /**
+   * Callback for batch errors in fire-and-forget mode.
+   * Since append() returns immediately, errors are reported via this callback.
+   * @param error - The error that occurred
+   */
+  onError?: (error: Error) => void
+}
+
+/**
+ * Result of an append operation from IdempotentProducer.
+ */
+export interface IdempotentAppendResult {
+  /**
+   * The offset after this message was appended.
+   */
+  offset: Offset
+
+  /**
+   * Whether this was a duplicate (idempotent success).
+   */
+  duplicate: 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()
+}