@supabase/realtime-js 2.108.3-canary.2 → 2.110.0-canary.0

package/src/RealtimePostgresFilterBuilder.ts

@@ -0,0 +1,253 @@
+/**
+ * Comparison operators accepted in a Postgres Changes `filter` string.
+ *
+ * These mirror the PostgREST operator surface and are evaluated server-side.
+ * Any operator can be negated via {@link RealtimePostgresFilterBuilder.not}
+ * (the `not.` prefix).
+ *
+ * This is the subset of PostgREST's `FilterOperator` (see `postgrest-js`) that
+ * Realtime Postgres Changes supports. Containment, range and full-text search
+ * operators (`cs`, `cd`, `ov`, range ops, `fts`, …) are intentionally not
+ * included because the Realtime server does not evaluate them.
+ *
+ * - `eq`, `neq`, `lt`, `lte`, `gt`, `gte` — comparison
+ * - `in` — membership: `status=in.(active,pending)`
+ * - `like`, `ilike` — pattern match (case-sensitive / insensitive): `title=like.%foo%`
+ * - `is` — `IS` check against `null` / `true` / `false` / `unknown`: `deleted_at=is.null`
+ * - `match`, `imatch` — POSIX regex match (`~` / `~*`)
+ * - `isdistinct` — NULL-safe inequality (`IS DISTINCT FROM`)
+ */
+export type RealtimePostgresChangesFilterOperator =
+  | 'eq'
+  | 'neq'
+  | 'lt'
+  | 'lte'
+  | 'gt'
+  | 'gte'
+  | 'in'
+  | 'like'
+  | 'ilike'
+  | 'is'
+  | 'match'
+  | 'imatch'
+  | 'isdistinct'
+
+/** Scalar value accepted by a single filter operator. */
+export type RealtimeFilterValue = string | number | boolean | null
+
+/** Value accepted by the `is` operator. */
+export type RealtimeIsFilterValue = null | boolean | 'null' | 'true' | 'false' | 'unknown'
+
+// Reserved characters that force PostgREST-style quoting: `[,()]` (which the
+// server reads as condition/list delimiters) plus `"`/`\` (escaped inside quotes).
+const PostgrestReservedCharsRegexp = /[,()"\\]/
+
+const needsQuoting = (value: string): boolean =>
+  PostgrestReservedCharsRegexp.test(value) || value !== value.trim()
+
+const quote = (value: string): string => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+
+const serializeScalar = (value: RealtimeFilterValue): string => {
+  const serialized = value === null ? 'null' : String(value)
+  return needsQuoting(serialized) ? quote(serialized) : serialized
+}
+
+const serializeIsValue = (value: RealtimeIsFilterValue): string =>
+  value === null ? 'null' : String(value)
+
+// Builds the `operator.value` portion of a filter (everything after `column=`).
+const serialize = (operator: RealtimePostgresChangesFilterOperator, value: unknown): string => {
+  if (operator === 'in') {
+    const values = Array.isArray(value) ? value : [value]
+    if (values.length === 0) {
+      throw new Error('Realtime `in` filter requires at least one value.')
+    }
+    const items = Array.from(new Set(values))
+      .map((v) => serializeScalar(v as RealtimeFilterValue))
+      .join(',')
+    return `in.(${items})`
+  }
+
+  if (operator === 'is') {
+    return `is.${serializeIsValue(value as RealtimeIsFilterValue)}`
+  }
+
+  return `${operator}.${serializeScalar(value as RealtimeFilterValue)}`
+}
+
+/**
+ * Fluent builder for Postgres Changes `filter` strings.
+ *
+ * Each method appends a single `column=operator.value` condition. Multiple
+ * conditions are combined with commas, which the Realtime server applies as an
+ * `AND`. Pass an instance straight to `channel.on('postgres_changes', …)` — the
+ * SDK serializes it to a string automatically — or call {@link build} to obtain
+ * the string yourself.
+ *
+ * The builder mirrors the `postgrest-js` filter API (`eq`, `neq`, `in`, `like`,
+ * `not`, …) for the operators that Realtime supports. Values containing reserved
+ * characters (`,`, `(`, `)`, `"`, `\`) — or surrounding whitespace — are
+ * automatically double-quoted and escaped the same way PostgREST does, so they
+ * survive the server's filter parser; all other values are sent verbatim.
+ *
+ * The filter is snapshotted when passed to `channel.on(...)`; mutating the
+ * builder afterwards does not affect an existing subscription. An empty builder
+ * serializes to `''`, which the server treats as "no filter".
+ *
+ * @example
+ * channel.on('postgres_changes', {
+ *   event: '*',
+ *   schema: 'public',
+ *   table: 'users',
+ *   filter: postgresChangesFilter().eq('id', 1).lt('age', 30), // → 'id=eq.1,age=lt.30'
+ * }, (payload) => { ... })
+ */
+export class RealtimePostgresFilterBuilder {
+  private readonly filters: string[] = []
+
+  private add(
+    column: string,
+    operator: RealtimePostgresChangesFilterOperator,
+    value: unknown,
+    negate = false
+  ): this {
+    const prefix = negate ? 'not.' : ''
+    this.filters.push(`${column}=${prefix}${serialize(operator, value)}`)
+    return this
+  }
+
+  /** Match rows where `column` equals `value` (`column=eq.value`). */
+  eq(column: string, value: RealtimeFilterValue): this {
+    return this.add(column, 'eq', value)
+  }
+
+  /** Match rows where `column` does not equal `value` (`column=neq.value`). */
+  neq(column: string, value: RealtimeFilterValue): this {
+    return this.add(column, 'neq', value)
+  }
+
+  /** Match rows where `column` is greater than `value` (`column=gt.value`). */
+  gt(column: string, value: RealtimeFilterValue): this {
+    return this.add(column, 'gt', value)
+  }
+
+  /** Match rows where `column` is greater than or equal to `value` (`column=gte.value`). */
+  gte(column: string, value: RealtimeFilterValue): this {
+    return this.add(column, 'gte', value)
+  }
+
+  /** Match rows where `column` is less than `value` (`column=lt.value`). */
+  lt(column: string, value: RealtimeFilterValue): this {
+    return this.add(column, 'lt', value)
+  }
+
+  /** Match rows where `column` is less than or equal to `value` (`column=lte.value`). */
+  lte(column: string, value: RealtimeFilterValue): this {
+    return this.add(column, 'lte', value)
+  }
+
+  /**
+   * Match rows where `column` is one of `values` (`column=in.(a,b,c)`).
+   * Requires at least one value; duplicates are removed. An element containing a
+   * reserved character is double-quoted (`in.("a,b",c)`), so commas inside an
+   * element are preserved. `null` is intentionally not accepted (`IN (null)`
+   * never matches in SQL) — use `is`/`not('col','is',null)` for null checks.
+   */
+  in(column: string, values: ReadonlyArray<string | number | boolean>): this {
+    return this.add(column, 'in', values)
+  }
+
+  /** Match rows where `column` matches the case-sensitive `pattern` (`column=like.pattern`). */
+  like(column: string, pattern: string): this {
+    return this.add(column, 'like', pattern)
+  }
+
+  /** Match rows where `column` matches the case-insensitive `pattern` (`column=ilike.pattern`). */
+  ilike(column: string, pattern: string): this {
+    return this.add(column, 'ilike', pattern)
+  }
+
+  /** Match rows where `column` matches the POSIX regex `pattern` (`column=match.pattern`). */
+  match(column: string, pattern: string): this {
+    return this.add(column, 'match', pattern)
+  }
+
+  /** Match rows where `column` matches the case-insensitive POSIX regex `pattern` (`column=imatch.pattern`). */
+  imatch(column: string, pattern: string): this {
+    return this.add(column, 'imatch', pattern)
+  }
+
+  /**
+   * Match rows where `column` `IS` the given value (`column=is.null`).
+   * Accepts `null`, a boolean, or the keywords `'null' | 'true' | 'false' | 'unknown'`.
+   */
+  is(column: string, value: RealtimeIsFilterValue): this {
+    return this.add(column, 'is', value)
+  }
+
+  /** Match rows where `column` is distinct from `value` (`column=isdistinct.value`). NULL-safe inequality. */
+  isDistinct(column: string, value: RealtimeFilterValue): this {
+    return this.add(column, 'isdistinct', value)
+  }
+
+  /**
+   * Negate any operator with the `not.` prefix (`column=not.operator.value`).
+   * `in` takes an array, `is` takes an `IS` keyword/boolean/null, and every
+   * other operator takes a scalar value.
+   *
+   * @example
+   * postgresChangesFilter().not('status', 'in', ['draft', 'archived'])
+   * // → status=not.in.(draft,archived)
+   * postgresChangesFilter().not('deleted_at', 'is', null)
+   * // → deleted_at=not.is.null
+   */
+  not(column: string, operator: 'in', value: ReadonlyArray<string | number | boolean>): this
+  not(column: string, operator: 'is', value: RealtimeIsFilterValue): this
+  not(
+    column: string,
+    operator: Exclude<RealtimePostgresChangesFilterOperator, 'in' | 'is'>,
+    value: RealtimeFilterValue
+  ): this
+  not(
+    column: string,
+    operator: RealtimePostgresChangesFilterOperator,
+    value: RealtimeFilterValue | ReadonlyArray<string | number | boolean>
+  ): this {
+    return this.add(column, operator, value, true)
+  }
+
+  /**
+   * Serialize all conditions into the comma-separated (AND) filter string.
+   *
+   * Conditions are joined by commas, which the server applies as `AND`. A scalar
+   * value (or single `in` element) that contains a reserved character — `,`,
+   * `(`, `)`, `"`, `\` — or surrounding whitespace is double-quoted and escaped
+   * the way PostgREST does, so commas inside a value are preserved rather than
+   * read as a condition boundary.
+   */
+  build(): string {
+    return this.filters.join(',')
+  }
+
+  /** Alias for {@link build}; lets the builder be used wherever a string is expected. */
+  toString(): string {
+    return this.build()
+  }
+}
+
+/**
+ * Create a {@link RealtimePostgresFilterBuilder} for composing a Postgres
+ * Changes `filter`. Conditions are combined with `AND`.
+ *
+ * @example
+ * import { postgresChangesFilter } from '@supabase/realtime-js'
+ *
+ * channel.on('postgres_changes', {
+ *   event: 'UPDATE',
+ *   schema: 'public',
+ *   table: 'orders',
+ *   filter: postgresChangesFilter().gt('amount', 100).eq('status', 'open'),
+ * }, (payload) => { ... })
+ */
+export const postgresChangesFilter = (): RealtimePostgresFilterBuilder =>
+  new RealtimePostgresFilterBuilder()

package/src/index.ts

@@ -8,10 +8,14 @@ import RealtimeChannel, {
   RealtimeChannelOptions,
   RealtimeChannelSendResponse,
   RealtimePostgresChangesFilter,
+  RealtimePostgresChangesFilterOperator,
+  RealtimePostgresFilterBuilder,
+  postgresChangesFilter,
   RealtimePostgresChangesPayload,
   RealtimePostgresInsertPayload,
   RealtimePostgresUpdatePayload,
   RealtimePostgresDeletePayload,
+  RealtimeSystemPayload,
   REALTIME_LISTEN_TYPES,
   REALTIME_POSTGRES_CHANGES_LISTEN_EVENT,
   REALTIME_SUBSCRIBE_STATES,
@@ -34,10 +38,14 @@ export {
   RealtimeClientOptions,
   RealtimeMessage,
   RealtimePostgresChangesFilter,
+  RealtimePostgresChangesFilterOperator,
+  RealtimePostgresFilterBuilder,
+  postgresChangesFilter,
   RealtimePostgresChangesPayload,
   RealtimePostgresInsertPayload,
   RealtimePostgresUpdatePayload,
   RealtimePostgresDeletePayload,
+  RealtimeSystemPayload,
   RealtimePresenceJoinPayload,
   RealtimePresenceLeavePayload,
   RealtimePresenceState,

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.108.3-canary.2'
+export const version = '2.110.0-canary.0'

package/src/lib/websocket-factory.ts

@@ -38,7 +38,7 @@ export interface WebSocketLike {
 }
 
 export interface WebSocketEnvironment {
-  type: 'native' | 'ws' | 'cloudflare' | 'unsupported'
+  type: 'native' | 'cloudflare' | 'unsupported'
   /** WebSocket constructor for this environment, if available. */
   wsConstructor?: typeof WebSocket
   error?: string
@@ -113,32 +113,13 @@ export class WebSocketFactory {
     if (_process) {
       const processVersions = _process['versions']
       if (processVersions && processVersions['node']) {
-        // Remove 'v' prefix if present and parse the major version
-        const versionString = processVersions['node']
-        const nodeVersion = parseInt(versionString.replace(/^v/, '').split('.')[0])
-
-        // Node.js 22+ should have native WebSocket
-        if (nodeVersion >= 22) {
-          // Check if native WebSocket is available (should be in Node.js 22+)
-          if (typeof globalThis.WebSocket !== 'undefined') {
-            return { type: 'native', wsConstructor: globalThis.WebSocket }
-          }
-          // If not available, user needs to provide it
-          return {
-            type: 'unsupported',
-            error: `Node.js ${nodeVersion} detected but native WebSocket not found.`,
-            workaround: 'Provide a WebSocket implementation via the transport option.',
-          }
-        }
-
-        // Node.js < 22 doesn't have native WebSocket
+        // Reaching here means an earlier check did not find a native WebSocket,
+        // so this Node.js process is missing the global WebSocket (Node.js 22+).
         return {
           type: 'unsupported',
-          error: `Node.js ${nodeVersion} detected without native WebSocket support.`,
+          error: 'Node.js detected but native WebSocket not found.',
           workaround:
-            'For Node.js < 22, install "ws" package and provide it via the transport option:\n' +
-            'import ws from "ws"\n' +
-            'new RealtimeClient(url, { transport: ws })',
+            'Ensure you are running Node.js 22+ or provide a WebSocket implementation via the transport option.',
         }
       }
     }
@@ -194,7 +175,7 @@ export class WebSocketFactory {
   public static isWebSocketSupported(): boolean {
     try {
       const env = this.detectEnvironment()
-      return env.type === 'native' || env.type === 'ws'
+      return env.type === 'native'
     } catch {
       return false
     }