@electric-sql/client 1.1.5 → 1.2.1

package/dist/index.d.ts

@@ -20,9 +20,31 @@ type NormalizedPgSnapshot = {
     xip_list: bigint[];
 };
 interface Header {
-    [key: Exclude<string, `operation` | `control`>]: Value;
+    [key: Exclude<string, `operation` | `control` | `event`>]: Value;
 }
 type Operation = `insert` | `update` | `delete`;
+/**
+ * A tag is a string identifying a reason for this row to be part of the shape.
+ *
+ * Tags can be composite, but they are always sent as a single string. Compound tags
+ * are separated by `|`. It's up to the client to split the tag into its components
+ * in order to react to move-outs correctly. Tag parts are guaranteed to not contain an
+ * unescaped `|` character (escaped as `\\|`) or be a literal `*`.
+ *
+ * Composite tag width is guaranteed to be fixed for a given shape.
+ */
+type MoveTag = string;
+/**
+ * A move-out pattern is a position and a value. The position is the index of the column
+ * that is being moved out. The value is the value of the column that is being moved out.
+ *
+ * Tag width and value order is fixed for a given shape, so the client can determine
+ * which tags match this pattern.
+ */
+type MoveOutPattern = {
+    pos: number;
+    value: string;
+};
 type ControlMessage = {
     headers: (Header & {
         control: `up-to-date` | `must-refetch`;
@@ -31,6 +53,12 @@ type ControlMessage = {
         control: `snapshot-end`;
     } & PostgresSnapshot);
 };
+type EventMessage = {
+    headers: Header & {
+        event: `move-out`;
+        patterns: MoveOutPattern[];
+    };
+};
 type ChangeMessage<T extends Row<unknown> = Row> = {
     key: string;
     value: T;
@@ -38,9 +66,12 @@ type ChangeMessage<T extends Row<unknown> = Row> = {
     headers: Header & {
         operation: Operation;
         txids?: number[];
+        /** Tags will always be present for changes if the shape has a subquery in its where clause, and are omitted otherwise.*/
+        tags?: MoveTag[];
+        removed_tags?: MoveTag[];
     };
 };
-type Message<T extends Row<unknown> = Row> = ControlMessage | ChangeMessage<T>;
+type Message<T extends Row<unknown> = Row> = ControlMessage | EventMessage | ChangeMessage<T>;
 /**
  * Common properties for all columns.
  * `dims` is the number of dimensions of the column. Only provided if the column is an array.
@@ -118,6 +149,140 @@ type Parser<Extensions = never> = {
 };
 type TransformFunction<Extensions = never> = (message: Row<Extensions>) => Row<Extensions>;
 
+type DbColumnName = string;
+type AppColumnName = string;
+/**
+ * A bidirectional column mapper that handles transforming column **names**
+ * between database format (e.g., snake_case) and application format (e.g., camelCase).
+ *
+ * **Important**: ColumnMapper only transforms column names, not column values or types.
+ * For type conversions (e.g., string → Date), use the `parser` option.
+ * For value transformations (e.g., encryption), use the `transformer` option.
+ *
+ * @example
+ * ```typescript
+ * const mapper = snakeCamelMapper()
+ * mapper.decode('user_id') // 'userId'
+ * mapper.encode('userId') // 'user_id'
+ * ```
+ */
+interface ColumnMapper {
+    /**
+     * Transform a column name from database format to application format.
+     * Applied to column names in query results.
+     */
+    decode: (dbColumnName: DbColumnName) => AppColumnName;
+    /**
+     * Transform a column name from application format to database format.
+     * Applied to column names in WHERE clauses and other query parameters.
+     */
+    encode: (appColumnName: AppColumnName) => DbColumnName;
+}
+/**
+ * Converts a snake_case string to camelCase.
+ *
+ * Handles edge cases:
+ * - Preserves leading underscores: `_user_id` → `_userId`
+ * - Preserves trailing underscores: `user_id_` → `userId_`
+ * - Collapses multiple underscores: `user__id` → `userId`
+ * - Normalizes to lowercase first: `user_Column` → `userColumn`
+ *
+ * @example
+ * snakeToCamel('user_id') // 'userId'
+ * snakeToCamel('project_id') // 'projectId'
+ * snakeToCamel('created_at') // 'createdAt'
+ * snakeToCamel('_private') // '_private'
+ * snakeToCamel('user__id') // 'userId'
+ * snakeToCamel('user_id_') // 'userId_'
+ */
+declare function snakeToCamel(str: string): string;
+/**
+ * Converts a camelCase string to snake_case.
+ *
+ * Handles consecutive capitals (acronyms) properly:
+ * - `userID` → `user_id`
+ * - `userHTTPSURL` → `user_https_url`
+ *
+ * @example
+ * camelToSnake('userId') // 'user_id'
+ * camelToSnake('projectId') // 'project_id'
+ * camelToSnake('createdAt') // 'created_at'
+ * camelToSnake('userID') // 'user_id'
+ * camelToSnake('parseHTMLString') // 'parse_html_string'
+ */
+declare function camelToSnake(str: string): string;
+/**
+ * Creates a column mapper from an explicit mapping of database columns to application columns.
+ *
+ * @param mapping - Object mapping database column names (keys) to application column names (values)
+ * @returns A ColumnMapper that can encode and decode column names bidirectionally
+ *
+ * @example
+ * const mapper = createColumnMapper({
+ *   user_id: 'userId',
+ *   project_id: 'projectId',
+ *   created_at: 'createdAt'
+ * })
+ *
+ * // Use with ShapeStream
+ * const stream = new ShapeStream({
+ *   url: 'http://localhost:3000/v1/shape',
+ *   params: { table: 'todos' },
+ *   columnMapper: mapper
+ * })
+ */
+declare function createColumnMapper(mapping: Record<string, string>): ColumnMapper;
+/**
+ * Creates a column mapper that automatically converts between snake_case and camelCase.
+ * This is the most common use case for column mapping.
+ *
+ * When a schema is provided, it will only map columns that exist in the schema.
+ * Otherwise, it will map any column name it encounters.
+ *
+ * **⚠️ Limitations and Edge Cases:**
+ * - **WHERE clause encoding**: Uses regex-based parsing which may not handle all complex
+ *   SQL expressions. Test thoroughly with your queries, especially those with:
+ *   - Complex nested expressions
+ *   - Custom operators or functions
+ *   - Column names that conflict with SQL keywords
+ *   - Quoted identifiers (e.g., `"$price"`, `"user-id"`) - not supported
+ *   - Column names with special characters (non-alphanumeric except underscore)
+ * - **Acronym ambiguity**: `userID` → `user_id` → `userId` (ID becomes Id after roundtrip)
+ *   Use `createColumnMapper()` with explicit mapping if you need exact control
+ * - **Type conversion**: This only renames columns, not values. Use `parser` for type conversion
+ *
+ * **When to use explicit mapping instead:**
+ * - You have column names that don't follow snake_case/camelCase patterns
+ * - You need exact control over mappings (e.g., `id` → `identifier`)
+ * - Your WHERE clauses are complex and automatic encoding fails
+ * - You have quoted identifiers or column names with special characters
+ *
+ * @param schema - Optional database schema to constrain mapping to known columns
+ * @returns A ColumnMapper for snake_case ↔ camelCase conversion
+ *
+ * @example
+ * // Basic usage
+ * const mapper = snakeCamelMapper()
+ *
+ * // With schema - only maps columns in schema (recommended)
+ * const mapper = snakeCamelMapper(schema)
+ *
+ * // Use with ShapeStream
+ * const stream = new ShapeStream({
+ *   url: 'http://localhost:3000/v1/shape',
+ *   params: { table: 'todos' },
+ *   columnMapper: snakeCamelMapper()
+ * })
+ *
+ * @example
+ * // If automatic encoding fails, fall back to manual column names in WHERE clauses:
+ * stream.requestSnapshot({
+ *   where: "user_id = $1", // Use database column names directly if needed
+ *   params: { "1": "123" }
+ * })
+ */
+declare function snakeCamelMapper(schema?: Schema): ColumnMapper;
+
 declare class FetchError extends Error {
     url: string;
     status: number;
@@ -301,7 +466,84 @@ interface ShapeStreamOptions<T = never> {
     fetchClient?: typeof fetch;
     backoffOptions?: BackoffOptions;
     parser?: Parser<T>;
+    /**
+     * Function to transform rows after parsing (e.g., for encryption, type coercion).
+     * Applied to data received from Electric.
+     *
+     * **Note**: If you're using `transformer` solely for column name transformation
+     * (e.g., snake_case → camelCase), consider using `columnMapper` instead, which
+     * provides bidirectional transformation and automatically encodes WHERE clauses.
+     *
+     * **Execution order** when both are provided:
+     * 1. `columnMapper.decode` runs first (renames columns)
+     * 2. `transformer` runs second (transforms values)
+     *
+     * @example
+     * ```typescript
+     * // For column renaming only - use columnMapper
+     * import { snakeCamelMapper } from '@electric-sql/client'
+     * const stream = new ShapeStream({ columnMapper: snakeCamelMapper() })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // For value transformation (encryption, etc.) - use transformer
+     * const stream = new ShapeStream({
+     *   transformer: (row) => ({
+     *     ...row,
+     *     encrypted_field: decrypt(row.encrypted_field)
+     *   })
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use both together
+     * const stream = new ShapeStream({
+     *   columnMapper: snakeCamelMapper(), // Runs first: renames columns
+     *   transformer: (row) => ({         // Runs second: transforms values
+     *     ...row,
+     *     encryptedData: decrypt(row.encryptedData)
+     *   })
+     * })
+     * ```
+     */
     transformer?: TransformFunction<T>;
+    /**
+     * Bidirectional column name mapper for transforming between database column names
+     * (e.g., snake_case) and application column names (e.g., camelCase).
+     *
+     * The mapper handles both:
+     * - **Decoding**: Database → Application (applied to query results)
+     * - **Encoding**: Application → Database (applied to WHERE clauses)
+     *
+     * @example
+     * ```typescript
+     * // Most common case: snake_case ↔ camelCase
+     * import { snakeCamelMapper } from '@electric-sql/client'
+     *
+     * const stream = new ShapeStream({
+     *   url: 'http://localhost:3000/v1/shape',
+     *   params: { table: 'todos' },
+     *   columnMapper: snakeCamelMapper()
+     * })
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom mapping
+     * import { createColumnMapper } from '@electric-sql/client'
+     *
+     * const stream = new ShapeStream({
+     *   columnMapper: createColumnMapper({
+     *     user_id: 'userId',
+     *     project_id: 'projectId',
+     *     created_at: 'createdAt'
+     *   })
+     * })
+     * ```
+     */
+    columnMapper?: ColumnMapper;
     /**
      * A function for handling shapestream errors.
      *
@@ -597,4 +839,4 @@ declare function isControlMessage<T extends Row<unknown> = Row>(message: Message
  */
 declare function isVisibleInSnapshot(txid: number | bigint | `${bigint}`, snapshot: PostgresSnapshot | NormalizedPgSnapshot): boolean;
 
-export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, type NormalizedPgSnapshot, type NumericColumn, type Offset, type Operation, type PostgresParams, type PostgresSnapshot, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type SnapshotMetadata, type SubsetParams, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue };
+export { BackoffDefaults, type BackoffOptions, type BitColumn, type BpcharColumn, type ChangeMessage, type ColumnInfo, type ColumnMapper, type CommonColumnProps, type ControlMessage, ELECTRIC_PROTOCOL_QUERY_PARAMS, type EventMessage, type ExternalHeadersRecord, type ExternalParamsRecord, FetchError, type GetExtensions, type IntervalColumn, type IntervalColumnWithPrecision, type LogMode, type MaybePromise, type Message, type MoveOutPattern, type MoveTag, type NormalizedPgSnapshot, type NumericColumn, type Offset, type Operation, type PostgresParams, type PostgresSnapshot, type RegularColumn, type Row, type Schema, Shape, type ShapeChangedCallback, type ShapeData, ShapeStream, type ShapeStreamInterface, type ShapeStreamOptions, type SnapshotMetadata, type SubsetParams, type TimeColumn, type TypedMessages, type Value, type VarcharColumn, camelToSnake, createColumnMapper, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue, snakeCamelMapper, snakeToCamel };