@plyaz/db 0.0.0

package/dist/adapters/sql/SQLAdapter.d.ts

@@ -0,0 +1,282 @@
+import type { SQLAdapterConfig, Transaction, DatabaseResult, PaginatedResult, QueryOptions, DatabaseHealthStatus, Filter, DatabaseAdapterType } from "@plyaz/types/db";
+/**
+ * @class SQLAdapter
+ * @implements {DatabaseAdapterType}
+ * @classdesc
+ * Plain SQL adapter implementation for raw SQL queries.
+ *
+ * This adapter provides an interface to interact with SQL databases using raw SQL queries,
+ * supporting CRUD operations, transactions, and health checks. It uses PostgreSQL's node-pg
+ * driver for database connectivity and provides a simple, direct SQL interface without
+ * ORM abstractions. This adapter is ideal for applications that require direct control
+ * over SQL queries or need to leverage database-specific features.
+ */
+export declare class SQLAdapter implements DatabaseAdapterType {
+    private pool;
+    private config;
+    private tableMap;
+    private idColumnMap;
+    /**
+     * Creates a new SQLAdapter instance.
+     * @param {SQLAdapterConfig} config - Configuration for the SQL adapter.
+     * @description
+     * Initializes the adapter with the provided configuration, setting up the connection pool
+     * for PostgreSQL database connections. The configuration should include a connection string
+     * and optional pool settings such as min/max connections and idle timeout. The adapter
+     * maintains internal maps for table names and ID columns to provide a level of abstraction
+     * over the raw database schema.
+     */
+    constructor(config: SQLAdapterConfig);
+    /**
+     * Initialize the adapter.
+     * @returns {Promise<DatabaseResult<void>>} Promise resolving to DatabaseResult indicating success or failure.
+     * @description
+     * Tests the database connection by attempting to establish a connection to the database.
+     * This method is typically called during application startup to verify that the adapter
+     * can communicate with the database before performing any operations. Returns a success
+     * result if the connection is established, or a failure result with an error if the
+     * connection cannot be established.
+     */
+    initialize(): Promise<DatabaseResult<void>>;
+    /**
+     * Connect to the database.
+     * @returns {Promise<void>} Promise that resolves when connected.
+     * @description
+     * Establishes a connection to the PostgreSQL database using the connection pool.
+     * This method is called to ensure that a connection is available before performing database operations.
+     * The connection pool manages the connections efficiently, reusing them when possible.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the database.
+     * @returns {Promise<void>} Promise that resolves when disconnected.
+     * @description
+     * Gracefully shuts down the connection pool, closing all active connections.
+     * This method should be called when the adapter is no longer needed, typically during
+     * application shutdown, to free up database resources and prevent connection leaks.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Gets the underlying PostgreSQL client instance.
+     * @template TClient - The type of the database client to return.
+     * @returns {TClient} The PostgreSQL pool instance cast to the specified client type.
+     * @description
+     * This method provides access to the underlying PostgreSQL connection pool.
+     * While direct access is technically possible, it is generally discouraged to
+     * preserve abstraction and ensure all database operations go through the adapter’s
+     * interface for consistent error handling, logging, and event management.
+     */
+    getClient<TClient extends object = object>(): TClient;
+    /**
+     * Execute a raw SQL query.
+     * @template T - The expected type of the query result rows.
+     * @param {string} sql - SQL query string.
+     * @param {T[]} [params] - Query parameters.
+     * @returns {Promise<T[]>} Promise resolving to query results.
+     * @description
+     * Executes a raw SQL query against the database, with optional parameterization.
+     * This method is useful for complex queries that cannot be easily expressed using the adapter's
+     * built-in methods or for database-specific operations. The method uses parameterized queries
+     * to prevent SQL injection attacks. If the query execution fails, a DatabaseError is thrown.
+     */
+    query<T>(sql: string, params?: T[]): Promise<T[]>;
+    /**
+     * Register a table with the adapter.
+     * @template TTable - Type representing the table structure.
+     * @template TIdColumn - Type representing the ID column.
+     * @param {string} name - Logical name for the table.
+     * @param {TTable} [table] - Table name or object.
+     * @param {TIdColumn} [idColumn] - Optional ID column name.
+     * @description
+     * Registers a table with the adapter, allowing it to be referenced by a logical name
+     * in subsequent operations. This is necessary for the adapter to perform operations
+     * on the table. The ID column can also be specified if it differs from the default 'id'.
+     * This registration enables the adapter to map logical table names to actual table names
+     * and ID columns, providing a layer of abstraction between the application and the database schema.
+     */
+    registerTable<TTable, TIdColumn>(name: string, table?: TTable, idColumn?: TIdColumn): void;
+    /**
+     * Find a single record by ID.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<T | null>>} Promise resolving to DatabaseResult containing the record or null.
+     * @description
+     * Retrieves a single record from the specified table using its primary ID.
+     * The method constructs a SELECT query with a WHERE clause for the ID column.
+     * If the record is found, it is returned in a success result. If no record is found,
+     * null is returned in a success result. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    /**
+     * Find multiple records with filtering and pagination.
+     * @template T - The expected type of the records.
+     * @param {string} table - Table name.
+     * @param {QueryOptions} [options] - Query options including filters, sorting, and pagination.
+     * @returns {Promise<DatabaseResult<PaginatedResult<object>>>} Promise resolving to DatabaseResult containing paginated data.
+     * @description
+     * Retrieves multiple records from the specified table with support for filtering,
+     * sorting, and pagination. The method constructs a SELECT query with optional WHERE,
+     * ORDER BY, LIMIT, and OFFSET clauses. It first executes a COUNT query to get the
+     * total number of matching records, then executes the main query with the applied filters,
+     * sorting, and pagination. The result includes the data array, total count of matching records,
+     * and pagination metadata such as current page, total pages, and offset.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    /**
+     * Finds multiple records from the specified table with optional filtering, sorting, and pagination.
+     * @template TRecord - Type representing the shape of records returned.
+     * @template TOptions - Query options type.
+     * @template TParam - Type of query parameters (primitives).
+     * @param {string} table - Name of the table to query.
+     * @param {TOptions} [options] - Optional query options for filtering, sorting, and pagination.
+     * @returns {Promise<DatabaseResult<PaginatedResult<TRecord>>>} - A promise resolving to a paginated result.
+     * @throws {DatabaseError} - When query execution or initialization fails.
+     */
+    /**
+     * Finds multiple records from the specified table with optional filtering, sorting, and pagination.
+     * @template T - Type representing the shape of records returned.
+     * @param {string} table - Name of the table to query.
+     * @param {QueryOptions<object>} [options] - Optional query options for filtering, sorting, and pagination.
+     * @returns {Promise<DatabaseResult<PaginatedResult<T>>>} - A promise resolving to a paginated result.
+     * @throws {DatabaseError} - When query execution or initialization fails.
+     */
+    findMany<T>(table: string, options?: QueryOptions<object>): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Create a new record.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {T} data - Record data to create.
+     * @returns {Promise<DatabaseResult<T>>} Promise resolving to DatabaseResult containing the created record.
+     * @description
+     * Inserts a new record into the specified table using the provided data.
+     * The method constructs an INSERT query with column names and parameter placeholders
+     * for the values. After insertion, it returns the inserted record with any auto-generated
+     * fields (like IDs) populated using the RETURNING clause. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    create<T>(table: string, data: T): Promise<DatabaseResult<T>>;
+    /**
+     * Update an existing record.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @param {Partial<T>} data - Partial record data to update.
+     * @returns {Promise<DatabaseResult<T>>} Promise resolving to DatabaseResult containing the updated record.
+     * @description
+     * Updates an existing record in the specified table using its primary ID.
+     * Only the fields provided in the data object are updated, allowing for partial updates.
+     * The method constructs an UPDATE query with a SET clause for the fields to update
+     * and a WHERE clause for the ID. After updating, it returns the updated record using
+     * the RETURNING clause. If an error occurs during the operation, a failure result with
+     * an error message is returned.
+     */
+    update<T>(table: string, id: string, data: Partial<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Delete a record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<void>>} Promise resolving to DatabaseResult indicating success or failure.
+     * @description
+     * Deletes a record from the specified table using its primary ID.
+     * The method constructs a DELETE query with a WHERE clause for the ID column.
+     * If the operation is successful, it returns a success result with no value.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    delete(table: string, id: string): Promise<DatabaseResult<void>>;
+    /**
+     * Execute a transaction.
+     * @template T - The expected type of the transaction result.
+     * @param {(trx: Transaction) => Promise<T>} callback - Function containing transaction operations.
+     * @returns {Promise<DatabaseResult<T>>} Promise resolving to DatabaseResult containing the transaction result.
+     * @description
+     * Executes a callback function within a database transaction, providing atomicity.
+     * If the callback function executes successfully, the transaction is committed.
+     * If an error occurs during the execution of the callback function, the transaction
+     * is rolled back, ensuring that no partial changes are applied to the database.
+     * The method returns the result of the callback function if successful,
+     * or a failure result with an error message if an error occurs.
+     * The transaction object passed to the callback provides methods for performing
+     * database operations within the transaction.
+     */
+    transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Check if a record exists.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<boolean>>} Promise resolving to DatabaseResult containing boolean indicating existence.
+     * @description
+     * Checks if a record with the specified ID exists in the table.
+     * The method constructs a SELECT query with a WHERE clause for the ID column
+     * and a LIMIT of 1. It returns a success result with a boolean value indicating
+     * whether the record exists. If an error occurs during the operation, a failure result
+     * with an error message is returned.
+     */
+    exists(table: string, id: string): Promise<DatabaseResult<boolean>>;
+    /**
+     * Count records matching a filter.
+     * @param {string} table - Table name.
+     * @param {Filter} [filter] - Filter conditions.
+     * @returns {Promise<DatabaseResult<number>>} Promise resolving to DatabaseResult containing the count.
+     * @description
+     * Counts the number of records in the specified table that match the optional filter.
+     * The method constructs a COUNT query with an optional WHERE clause based on the filter.
+     * It returns a success result with the count of matching records.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    count(table: string, filter?: Filter): Promise<DatabaseResult<number>>;
+    /**
+     * Perform health check.
+     * @returns {Promise<DatabaseResult<DatabaseHealthStatus>>} Promise resolving to DatabaseResult containing health status.
+     * @description
+     * Checks the health of the database connection by executing a simple query.
+     * The method measures the response time of the query to determine the health status.
+     * It returns a success result with a HealthStatus object indicating whether the database is healthy,
+     * the response time of the health check, and any additional details.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    healthCheck(): Promise<DatabaseResult<DatabaseHealthStatus>>;
+    /**
+     * Get the actual table name from the mapped table name.
+     * @private
+     * @param {string} name - Logical table name.
+     * @returns {string} Actual table name.
+     * @throws {DatabaseError} If table is not registered.
+     * @description
+     * Retrieves the actual table name that has been previously registered with the adapter.
+     * This method is used internally by other methods to ensure that operations are performed
+     * on valid, registered tables. If the table is not found, it throws a DatabaseError.
+     */
+    private getTableName;
+    private validateBasicParams;
+    private validateCreateParams;
+    private validateUpdateParams;
+    /**
+     * Builds a SQL WHERE clause string from a provided filter definition.
+     *
+     * @private
+     * @template TParams - Tuple type representing the parameter array.
+     * @param {Filter} filter - The filter condition containing the field, operator, and value.
+     * @param {TParams} params - Mutable array to collect SQL parameter values.
+     * @param {number} startIndex - The starting index for SQL parameter placeholders (e.g., $1, $2, ...).
+     * @returns {string} The constructed SQL WHERE clause string.
+     * @throws {DatabaseError} If an unsupported operator is encountered or if the filter value type is invalid.
+     *
+     * @description
+     * This method dynamically builds a SQL WHERE clause based on the provided `filter` object.
+     * It supports operators such as:
+     * - `eq`, `ne` (equality and inequality)
+     * - `gt`, `gte`, `lt`, `lte` (comparison)
+     * - `in` (membership in a list)
+     * - `like` (pattern matching)
+     * - `between` (range)
+     * - `isNull`, `isNotNull` (null checks)
+     *
+     * The function safely constructs parameterized queries by adding each value
+     * into the `params` array and referencing it via `$<index>` placeholders,
+     * helping to prevent SQL injection attacks.
+     */
+    private buildWhereClause;
+}
+//# sourceMappingURL=SQLAdapter.d.ts.map

package/dist/adapters/sql/SQLAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SQLAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/sql/SQLAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/supabase/SupabaseAdapter.d.ts

@@ -0,0 +1,305 @@
+import type { DatabaseAdapterType, DatabaseResult, PaginatedResult, QueryOptions, Filter, DatabaseHealthStatus, Transaction, SupabaseAdapterConfig } from "@plyaz/types/db";
+/**
+ * @class SupabaseAdapter
+ * @implements {DatabaseAdapterType}
+ * @classdesc
+ * Supabase adapter implementation for database operations.
+ *
+ * This adapter provides an interface to interact with Supabase databases,
+ * supporting CRUD operations, transactions, and health checks. It leverages
+ * the Supabase JavaScript client to communicate with PostgreSQL databases through
+ * Supabase's API. The adapter provides a consistent interface while abstracting
+ * away the specifics of Supabase's API calls.
+ */
+export declare class SupabaseAdapter implements DatabaseAdapterType {
+    private client;
+    private config;
+    private tableMap;
+    private idColumnMap;
+    /**
+     * Creates a new SupabaseAdapter instance.
+     * @param {SupabaseAdapterConfig} config - Configuration for the Supabase adapter.
+     * @description
+     * Initializes the adapter with the provided configuration, setting up the Supabase client.
+     * The configuration must include a Supabase URL and either a service key or an anonymous key.
+     * The adapter maintains internal maps for table names and ID columns to provide a level of
+     * abstraction over the database schema. If required configuration values are missing,
+     * the constructor throws a DatabaseError.
+     * @throws {DatabaseError} If Supabase URL or key is not provided in the configuration.
+     */
+    constructor(config: SupabaseAdapterConfig);
+    /**
+     * Initializes the Supabase database adapter.
+     * @returns {Promise<DatabaseResult<void>>} A promise resolving to a DatabaseResult indicating
+     * whether the initialization was successful or failed.
+     * @description
+     * Validates the Supabase database connection by invoking a simple predefined RPC function (`version`).
+     * This method is typically executed during application startup to ensure the adapter can
+     * successfully communicate with the database before performing any operations.
+     *
+     * The method calls the `version` RPC to confirm connectivity. If the RPC function is not defined,
+     * it is treated as a non-critical error and the connection is still considered valid. Any other
+     * errors are reported as initialization failures.
+     */
+    initialize(): Promise<DatabaseResult<void>>;
+    /**
+     * Connect to the database.
+     * @returns {Promise<void>} Promise that resolves when connected.
+     * @description
+     * Supabase handles connections automatically, so this method is a no-op.
+     * The Supabase client manages connections internally, establishing them as needed
+     * and handling connection pooling. This method is included for interface compatibility
+     * but does not perform any connection operations.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the database.
+     * @returns {Promise<void>} Promise that resolves when disconnected.
+     * @description
+     * Supabase handles disconnections automatically, so this method is a no-op.
+     * The Supabase client manages connections internally, closing them when appropriate.
+     * This method is included for interface compatibility but does not perform any
+     * disconnection operations.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Gets the underlying Supabase client instance.
+     * @template TClient - The type of the Supabase client to return.
+     * @returns {TClient} The Supabase client instance cast to the specified client type.
+     * @description
+     * This method provides access to the underlying Supabase client.
+     * Although direct access is technically possible, it is discouraged to maintain
+     * abstraction and ensure that all database operations go through the adapter’s
+     * interface for consistent error handling, logging, and event management.
+     */
+    getClient<TClient extends object = object>(): TClient;
+    /**
+     * Execute a raw SQL query.
+     * @template T - The expected type of the query result rows.
+     * @param {string} sql - SQL query string.
+     * @param {T[]} [params] - Query parameters.
+     * @returns {Promise<T[]>} Promise resolving to query results.
+     * @description
+     * Executes a raw SQL query against the database using Supabase's RPC function.
+     * This method is useful for complex queries that cannot be easily expressed using the adapter's
+     * built-in methods or for database-specific operations. The method uses parameterized queries
+     * to prevent SQL injection attacks. If the query execution fails, a DatabaseError is thrown.
+     * Note that this requires a custom RPC function named 'exec_sql' to be set up in your Supabase project.
+     */
+    query<T>(sql: string, params?: T[]): Promise<T[]>;
+    /**
+     * Register a table with the adapter.
+     * @template TTable - Type representing the table structure.
+     * @template TIdColumn - Type representing the ID column.
+     * @param {string} name - Logical name for the table.
+     * @param {TTable} [table] - Actual table name (defaults to logical name if not provided).
+     * @param {TIdColumn} [idColumn] - Optional ID column name.
+     * @description
+     * Registers a table with the adapter, allowing it to be referenced by a logical name
+     * in subsequent operations. This is necessary for the adapter to perform operations
+     * on the table. The ID column can also be specified if it differs from the default 'id'.
+     * This registration enables the adapter to map logical table names to actual table names
+     * and ID columns, providing a layer of abstraction between the application and the database schema.
+     * If no table name is provided, the logical name is used as the actual table name.
+     */
+    registerTable<TTable, TIdColumn>(name: string, table?: TTable, idColumn?: TIdColumn): void;
+    /**
+     * Find a single record by ID.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<T | null>>} Promise resolving to DatabaseResult containing the record or null.
+     * @description
+     * Retrieves a single record from the specified table using its primary ID.
+     * The method uses Supabase's select method with a filter for the ID column and
+     * the single() method to retrieve exactly one record. If the record is found,
+     * it is returned in a success result. If no record is found (indicated by error code PGRST116),
+     * null is returned in a success result. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    findById<T>(table: string, id: string): Promise<DatabaseResult<T | null>>;
+    /**
+     * Find multiple records with filtering and pagination.
+     * @template T - The expected type of the records.
+     * @param {string} table - Table name.
+     * @param {QueryOptions} [options] - Query options including filters, sorting, and pagination.
+     * @returns {Promise<DatabaseResult<PaginatedResult<T>>>} Promise resolving to DatabaseResult containing paginated data.
+     * @description
+     * Retrieves multiple records from the specified table with support for filtering,
+     * sorting, and pagination. The method first executes a count query to get the
+     * total number of matching records, then executes the main query with the applied filters,
+     * sorting, and pagination. The result includes the data array, total count of matching records,
+     * and pagination metadata such as current page, total pages, and limit.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    findMany<T>(table: string, options?: QueryOptions): Promise<DatabaseResult<PaginatedResult<T>>>;
+    /**
+     * Create a new record.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {T} data - Record data to create.
+     * @returns {Promise<DatabaseResult<T>>} Promise resolving to DatabaseResult containing the created record.
+     * @description
+     * Inserts a new record into the specified table using the provided data.
+     * The method uses Supabase's insert method with the data and then chains a select()
+     * and single() call to retrieve the inserted record with any auto-generated fields
+     * (like IDs) populated. If the operation is successful, it returns the created record.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    create<T>(table: string, data: T): Promise<DatabaseResult<T>>;
+    /**
+     * Update an existing record.
+     * @template T - The expected type of the record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @param {Partial<T>} data - Partial record data to update.
+     * @returns {Promise<DatabaseResult<T>>} Promise resolving to DatabaseResult containing the updated record.
+     * @description
+     * Updates an existing record in the specified table using its primary ID.
+     * Only the fields provided in the data object are updated, allowing for partial updates.
+     * The method uses Supabase's update method with the data and a filter for the ID column,
+     * then chains a select() and single() call to retrieve the updated record. If the operation
+     * is successful, it returns the updated record. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    update<T>(table: string, id: string, data: Partial<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Delete a record.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<void>>} Promise resolving to DatabaseResult indicating success or failure.
+     * @description
+     * Deletes a record from the specified table using its primary ID.
+     * The method uses Supabase's delete method with a filter for the ID column.
+     * If the operation is successful, it returns a success result with no value.
+     * If an error occurs during the operation, a failure result with an error message is returned.
+     */
+    delete(table: string, id: string): Promise<DatabaseResult<void>>;
+    /**
+     * Execute a transaction.
+     * @template T - The expected type of the transaction result.
+     * @param {(trx: Transaction) => Promise<T>} callback - Function containing transaction operations.
+     * @returns {Promise<DatabaseResult<T>>} Promise resolving to DatabaseResult containing the transaction result.
+     * @description
+     * Executes a callback function within a database transaction, providing atomicity.
+     * Note that Supabase doesn't support traditional multi-statement transactions in the same way
+     * as direct database connections. This adapter simulates transactional behavior by executing
+     * all operations through the same client, but does not provide true rollback capabilities.
+     * If the callback function executes successfully, the transaction is considered committed.
+     * If an error occurs during the execution of the callback function, a failure result with
+     * an error message is returned, but any successful operations within the callback will not
+     * be rolled back.
+     */
+    transaction<T>(callback: (trx: Transaction) => Promise<T>): Promise<DatabaseResult<T>>;
+    /**
+     * Check if a record exists.
+     * @param {string} table - Table name.
+     * @param {string} id - Record ID.
+     * @returns {Promise<DatabaseResult<boolean>>} Promise resolving to DatabaseResult containing boolean indicating existence.
+     * @description
+     * Checks if a record with the specified ID exists in the table.
+     * The method constructs a SELECT query with a WHERE clause for the ID column
+     * and a LIMIT of 1. It returns a success result with a boolean value indicating
+     * whether the record exists. If an error occurs during the operation, a failure result
+     * with an error message is returned.
+     */
+    exists(table: string, id: string): Promise<DatabaseResult<boolean>>;
+    /**
+     * Count records matching a filter.
+     * @param {string} table - Table name.
+     * @param {Filter} [filter] - Filter conditions.
+     * @returns {Promise<DatabaseResult<number>>} Promise resolving to DatabaseResult containing the count.
+     * @description
+     * Counts the number of records in the specified table that match the optional filter.
+     * The method uses Supabase's select method with the count option set to 'exact'
+     * and head set to true to return only the count. If a filter is provided,
+     * it is applied to narrow down the count to matching records. It returns a success
+     * result with the count of matching records. If an error occurs during the operation,
+     * a failure result with an error message is returned.
+     */
+    count(table: string, filter?: Filter): Promise<DatabaseResult<number>>;
+    /**
+     * Perform health check.
+     * @returns {Promise<DatabaseResult<DatabaseHealthStatus>>} Promise resolving to DatabaseResult containing health status.
+     * @description
+     * Checks the health of the database connection by executing a simple RPC call.
+     * The method measures the response time of the query to determine the health status.
+     * It attempts to call a 'version' RPC function, ignoring errors related to the function
+     * not existing but reporting other errors. It returns a success result with a DatabaseHealthStatus
+     * object indicating whether the database is healthy, the response time of the health check,
+     * and any additional details. If an error occurs during the operation, a failure result
+     * with an error message is returned.
+     */
+    healthCheck(): Promise<DatabaseResult<DatabaseHealthStatus>>;
+    /**
+     * Get the actual table name from the mapped table name.
+     * @private
+     * @param {string} name - Logical table name.
+     * @returns {string} Actual table name.
+     * @throws {DatabaseError} If table is not registered.
+     * @description
+     * Retrieves the actual table name that has been previously registered with the adapter.
+     * This method is used internally by other methods to ensure that operations are performed
+     * on valid, registered tables. If the table is not found, it throws a DatabaseError.
+     */
+    private getTableName;
+    /**
+     * Applies filter conditions to a Supabase query with comprehensive operator support
+     *
+     * Transforms generic Filter objects into Supabase-specific query methods while maintaining
+     * type safety and preventing SQL injection through operator validation.
+     *
+     * **Supported Operators:**
+     * - Equality: eq, ne (not equal)
+     * - Comparison: gt, gte, lt, lte
+     * - Pattern: like (with % wildcards)
+     * - Membership: in, notIn (array values)
+     * - Range: between (two-element array)
+     * - Null checks: isNull, isNotNull
+     *
+     * **Security Features:**
+     * - Validates field names against regex: /^[a-zA-Z_][a-zA-Z0-9_]*$/
+     * - Validates operator against whitelist
+     * - Type-checks array values for 'in', 'notIn', 'between' operators
+     *
+     * @private
+     * @template Q - Type of the Supabase query builder
+     * @param {Q} query - Supabase query builder instance to apply filters to
+     * @param {Filter} filter - Filter conditions with field, operator, and value
+     * @returns {Q} Modified query builder with filter conditions applied
+     *
+     * @throws {BaseError} SUPABASE_INVALID_FILTER - If 'in'/'notIn' value is not an array
+     * @throws {BaseError} SUPABASE_INVALID_FILTER - If 'between' value is not a 2-element array
+     * @throws {BaseError} SUPABASE_UNSUPPORTED_OPERATOR - If operator is not in whitelist
+     *
+     * @example
+     * ```typescript
+     * // Equality filter
+     * const query1 = this.applyFilter(baseQuery, {
+     *   field: 'status',
+     *   operator: 'eq',
+     *   value: 'active'
+     * });
+     * // Generates: query.eq('status', 'active')
+     *
+     * // Range filter
+     * const query2 = this.applyFilter(baseQuery, {
+     *   field: 'age',
+     *   operator: 'between',
+     *   value: [18, 65]
+     * });
+     * // Generates: query.gte('age', 18).lte('age', 65)
+     *
+     * // Array membership filter
+     * const query3 = this.applyFilter(baseQuery, {
+     *   field: 'category',
+     *   operator: 'in',
+     *   value: ['tech', 'science', 'business']
+     * });
+     * // Generates: query.in('category', ['tech', 'science', 'business'])
+     * ```
+     *
+     */
+    private applyFilter;
+}
+//# sourceMappingURL=SupabaseAdapter.d.ts.map

package/dist/adapters/supabase/SupabaseAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupabaseAdapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/supabase/SupabaseAdapter.ts"],"names":[],"mappings":"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"}