@electric-sql/client 1.1.4 → 1.2.0

package/dist/index.d.ts

@@ -118,6 +118,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 +435,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.
      *
@@ -368,16 +579,14 @@ interface ShapeStreamInterface<T extends Row<unknown> = Row> {
     error?: unknown;
     mode: LogMode;
     forceDisconnectAndRefresh(): Promise<void>;
-    requestSnapshot(params: {
-        where?: string;
-        params?: Record<string, string>;
-        limit: number;
-        offset?: number;
-        orderBy: string;
-    }): Promise<{
+    requestSnapshot(params: SubsetParams): Promise<{
         metadata: SnapshotMetadata;
         data: Array<Message<T>>;
     }>;
+    fetchSnapshot(opts: SubsetParams): Promise<{
+        metadata: SnapshotMetadata;
+        data: Array<ChangeMessage<T>>;
+    }>;
 }
 /**
  * Reads updates to a shape from Electric using HTTP requests and long polling or
@@ -451,7 +660,7 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
      */
     forceDisconnectAndRefresh(): Promise<void>;
     /**
-     * Request a snapshot for subset of data.
+     * Request a snapshot for subset of data and inject it into the subscribed data stream.
      *
      * Only available when mode is `changes_only`.
      * Returns the insertion point & the data, but more importantly injects the data
@@ -468,6 +677,17 @@ declare class ShapeStream<T extends Row<unknown> = Row> implements ShapeStreamIn
         metadata: SnapshotMetadata;
         data: Array<ChangeMessage<T>>;
     }>;
+    /**
+     * Fetch a snapshot for subset of data.
+     * Returns the metadata and the data, but does not inject it into the subscribed data stream.
+     *
+     * @param opts - The options for the snapshot request.
+     * @returns The metadata and the data for the snapshot.
+     */
+    fetchSnapshot(opts: SubsetParams): Promise<{
+        metadata: SnapshotMetadata;
+        data: Array<ChangeMessage<T>>;
+    }>;
 }
 
 type ShapeData<T extends Row<unknown> = Row> = Map<string, T>;
@@ -588,4 +808,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 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, camelToSnake, createColumnMapper, isChangeMessage, isControlMessage, isVisibleInSnapshot, resolveValue, snakeCamelMapper, snakeToCamel };