@supabase/realtime-js 2.108.3-canary.1 → 2.109.0

package/src/RealtimeChannel.ts

@@ -13,6 +13,14 @@ import { normalizeChannelError } from './lib/normalizeChannelError'
 import ChannelAdapter from './phoenix/channelAdapter'
 import { ChannelBindingCallback, ChannelOnErrorCallback } from './phoenix/types'
 import type { Timer } from './phoenix/types'
+import { RealtimePostgresFilterBuilder } from './RealtimePostgresFilterBuilder'
+import type { RealtimePostgresChangesFilterOperator } from './RealtimePostgresFilterBuilder'
+
+export type { RealtimePostgresChangesFilterOperator } from './RealtimePostgresFilterBuilder'
+export {
+  RealtimePostgresFilterBuilder,
+  postgresChangesFilter,
+} from './RealtimePostgresFilterBuilder'
 
 type ReplayOption = {
   since: number
@@ -25,8 +33,18 @@ export type RealtimeChannelOptions = {
      * self option enables client to receive message it broadcast
      * ack option instructs server to acknowledge that broadcast message was received
      * replay option instructs server to replay broadcast messages
+     * replication_ready option instructs the server to emit a `system` event once the
+     * Postgres replication connection backing this channel is established and ready to
+     * stream changes. Listen for it with `channel.on('system', {}, (payload) => ...)`;
+     * the payload's `status` is `'ok'` (`message: 'Replication connection established'`)
+     * on success or `'error'` if the connection is not ready in time.
      */
-    broadcast?: { self?: boolean; ack?: boolean; replay?: ReplayOption }
+    broadcast?: {
+      self?: boolean
+      ack?: boolean
+      replay?: ReplayOption
+      replication_ready?: boolean
+    }
     /**
      * key option is used to track presence payload across clients
      */
@@ -120,13 +138,67 @@ export type RealtimePostgresChangesFilter<T extends `${REALTIME_POSTGRES_CHANGES
    */
   table?: string
   /**
-   * Receive database changes when filter is matched.
+   * Receive database changes only when the filter is matched.
+   *
+   * A filter is a `column=operator.value` expression, e.g. `id=eq.1` or
+   * `title=like.%foo%`. See {@link RealtimePostgresChangesFilterOperator} for
+   * the available operators.
+   *
+   * Multiple filters can be combined with commas; they are applied as an `AND`
+   * condition: `filter: 'id=gt.0,id=lt.100'`.
+   *
+   * Any operator can be negated with the `not.` prefix: `filter: 'status=not.in.(draft,archived)'`.
+   *
+   * The server splits conditions on commas outside quotes/parentheses. To
+   * include a reserved character (`,`, `(`, `)`) in a value, wrap it in double
+   * quotes PostgREST-style: `name=eq."a,b"`. The {@link RealtimePostgresFilterBuilder}
+   * does this quoting for you.
+   *
+   * Instead of a raw string you can pass a {@link RealtimePostgresFilterBuilder}
+   * (via `postgresChangesFilter()`) for a type-checked, ergonomic way to compose filters; the
+   * SDK serializes it to a string automatically.
+   */
+  filter?: string | RealtimePostgresFilterBuilder
+  /**
+   * Restrict the change payload to a subset of columns instead of receiving the
+   * full row. Reduces payload size (helpful for large `bytea`/`jsonb` columns)
+   * and the data transferred per event.
+   *
+   * The listed columns must be selectable by the subscribing role.
+   *
+   * @example
+   * channel.on('postgres_changes', {
+   *   event: '*',
+   *   schema: 'public',
+   *   table: 'users',
+   *   select: ['id', 'first_name'],
+   * }, (payload) => {
+   *   // payload.new only contains { id, first_name }
+   * })
    */
-  filter?: string
+  select?: string[]
 }
 
 export type RealtimeChannelSendResponse = 'ok' | 'timed out' | 'error' | (string & {})
 
+/**
+ * Payload of a `system` event emitted by the server.
+ *
+ * Most notably, when a channel is created with `config.broadcast.replication_ready: true`,
+ * the server sends one of these once the Postgres replication connection is ready
+ * (`status: 'ok'`) or fails to become ready in time (`status: 'error'`).
+ */
+export type RealtimeSystemPayload = {
+  /** The extension that produced the message, e.g. `'system'` or `'postgres_changes'`. */
+  extension: 'system' | 'postgres_changes' | (string & {})
+  /** `'ok'` on success, `'error'` on failure. */
+  status: 'ok' | 'error' | (string & {})
+  /** Human-readable description, e.g. `'Replication connection established'`. */
+  message: string
+  /** The channel (sub)topic the message refers to. */
+  channel: string
+}
+
 export enum REALTIME_POSTGRES_CHANGES_LISTEN_EVENT {
   ALL = '*',
   INSERT = 'INSERT',
@@ -157,6 +229,7 @@ type PostgresChangesFilters = {
     schema?: string
     table?: string
     filter?: string
+    select?: string[]
   }[]
 }
 
@@ -569,6 +642,31 @@ export default class RealtimeChannel {
       payload: RealtimeBroadcastDeletePayload<T>
     }) => void
   ): RealtimeChannel
+  /**
+   * Listen for `system` events on this channel.
+   *
+   * The payload follows the {@link RealtimeSystemPayload} shape. Opt in to the replication-ready
+   * notification with `config.broadcast.replication_ready: true` when creating the channel, then
+   * watch for `payload.status === 'ok'` to know the Postgres replication connection is ready.
+   *
+   * @example Know when the replication connection is ready
+   * ```js
+   * const channel = supabase.channel('room1', {
+   *   config: { broadcast: { replication_ready: true } },
+   * })
+   *
+   * channel
+   *   .on('postgres_changes', { event: '*', schema: 'public', table: 'messages' }, (payload) => {
+   *     console.log('Change received!', payload)
+   *   })
+   *   .on('system', {}, (payload) => {
+   *     if (payload.extension === 'system' && payload.status === 'ok') {
+   *       console.log('Replication connection is ready:', payload.message)
+   *     }
+   *   })
+   *   .subscribe()
+   * ```
+   */
   on<T extends { [key: string]: any }>(
     type: `${REALTIME_LISTEN_TYPES.SYSTEM}`,
     filter: {},
@@ -735,7 +833,7 @@ export default class RealtimeChannel {
    */
   on(
     type: `${REALTIME_LISTEN_TYPES}`,
-    filter: { event: string; [key: string]: string },
+    filter: { event: string; [key: string]: any },
     callback: (payload: any) => void
   ): RealtimeChannel {
     const stateCheck = this.channelAdapter.isJoined() || this.channelAdapter.isJoining()
@@ -1007,6 +1105,20 @@ export default class RealtimeChannel {
   _on(type: string, filter: { [key: string]: any }, callback: ChannelBindingCallback) {
     const typeLower = type.toLocaleLowerCase()
 
+    // Serialize a postgres_changes filter builder into its string form so the
+    // rest of the pipeline (join payload, server binding match) sees a string.
+    // Duck-type `build()` in addition to `instanceof` so a builder constructed
+    // against a duplicate copy of the package (separate module realm) still works.
+    const filterValue = filter?.filter
+    if (
+      filterValue instanceof RealtimePostgresFilterBuilder ||
+      (typeof filterValue === 'object' &&
+        filterValue !== null &&
+        typeof (filterValue as { build?: unknown }).build === 'function')
+    ) {
+      filter = { ...filter, filter: (filterValue as RealtimePostgresFilterBuilder).build() }
+    }
+
     const ref = this.channelAdapter.on(type, callback)
 
     const binding: Binding = {

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.1'
+export const version = '2.109.0'