@decaf-ts/integrations 0.10.8 → 0.11.0

package/lib/types/redis/RedisStatement.d.cts

@@ -0,0 +1,175 @@
+import { Adapter, AdapterFlags, Condition, Statement } from "@decaf-ts/core";
+import { RedisContext, RawRedisQuery } from "./types.d.cts";
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * @description Redis-specific query statement builder
+ * @summary Extends the base Statement class to provide query building functionality for the Redis adapter.
+ * This class translates high-level query operations into predicates that can filter and sort
+ * in-memory data structures (records reverted from the table hash).
+ * @template M - The model type being queried
+ * @template R - The result type returned by the query
+ * @class RedisStatement
+ * @category Redis
+ * @example
+ * ```typescript
+ * // Create a statement for querying User models
+ * const statement = redisAdapter.Statement<User>();
+ *
+ * // Build a query to find active users with age > 18
+ * const results = await statement
+ *   .from(User)
+ *   .where(Condition.and(
+ *     Condition.eq('active', true),
+ *     Condition.gt('age', 18)
+ *   ))
+ *   .orderBy('lastName', 'asc')
+ *   .limit(10)
+ *   .execute();
+ * ```
+ */
+export declare class RedisStatement<M extends Model, R, A extends Adapter<M, any, RawRedisQuery<any>, RedisContext>> extends Statement<M, A, R, RawRedisQuery<any>> {
+    /**
+     * @description Creates a statement bound to the Redis adapter
+     * @param {A} adapter - The Redis adapter instance to use for executing queries
+     * @param {Partial<AdapterFlags>} [overrides] - Optional adapter flag overrides
+     */
+    constructor(adapter: A, overrides?: Partial<AdapterFlags>);
+    /**
+     * @description Creates a sort comparator function
+     * @summary Generates a function that compares two model instances based on the orderBy criteria.
+     * This method handles different data types (string, number, date) and sort directions (asc, desc).
+     * @return {function(Model, Model): number} A comparator function for sorting model instances
+     */
+    private getSort;
+    /**
+     * @description Compares two models by a single attribute
+     * @summary Resolves the attribute's design type and delegates to the matching
+     * type-specific comparator.
+     * @param {Model} el1 - The first model instance
+     * @param {Model} el2 - The second model instance
+     * @param {keyof Model} key - The attribute to compare
+     * @return {number} A negative number, zero or a positive number as per the comparison
+     */
+    private compareByKey;
+    /**
+     * @description Compares two boolean values
+     * @return {number} 0 when equal, 1 when `a` is true, -1 otherwise
+     */
+    private compareBooleans;
+    /**
+     * @description Compares two numeric values
+     * @return {number} The numeric difference between the values
+     */
+    private compareNumbers;
+    /**
+     * @description Compares two bigint values
+     * @return {number} 0 when equal, 1 when `a` is greater, -1 otherwise
+     */
+    private compareBigInts;
+    /**
+     * @description Compares two strings using locale-aware ordering
+     * @return {number} The locale compare result between the values
+     */
+    private compareStrings;
+    /**
+     * @description Compares two dates by their epoch timestamps
+     * @return {number} The difference between the timestamps
+     */
+    private compareDates;
+    /**
+     * @description Builds a Redis query from the statement
+     * @summary Converts the statement's selectors and conditions into a RawRedisQuery object
+     * that can be executed by the Redis adapter. This method assembles all query components
+     * (select, from, where, limit, offset, sort) into the final query structure.
+     * @return {RawRedisQuery<M>} The constructed Redis query object
+     */
+    protected build(): RawRedisQuery<any>;
+    /**
+     * @description Parses a condition into a Redis query predicate
+     * @summary Converts a Condition object into a predicate function that can be used
+     * to filter model instances in memory. This method handles both simple conditions
+     * (equals, greater than, etc.) and complex conditions with logical operators (AND, OR).
+     * @template M - The model type for the condition
+     * @param {Condition<M>} condition - The condition to parse
+     * @return {RawRedisQuery<M>} A Redis query object with a where predicate function
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant RedisStatement
+     *   participant SimpleCondition
+     *   participant ComplexCondition
+     *
+     *   Caller->>RedisStatement: parseCondition(condition)
+     *   alt Simple condition (eq, gt, lt, etc.)
+     *     RedisStatement->>SimpleCondition: Extract attr1, operator, comparison
+     *     SimpleCondition-->>RedisStatement: Return predicate function
+     *   else Logical operator (AND, OR)
+     *     RedisStatement->>ComplexCondition: Extract nested conditions
+     *     RedisStatement->>RedisStatement: parseCondition(leftCondition)
+     *     RedisStatement->>RedisStatement: parseCondition(rightCondition)
+     *     ComplexCondition-->>RedisStatement: Combine predicates with logical operator
+     *   end
+     *   RedisStatement-->>Caller: Return query with where predicate
+     */
+    protected parseCondition(condition: Condition<M>): RawRedisQuery<any>;
+    /**
+     * @description Validates that an aggregation selector targets a numeric attribute
+     * @param {SelectSelector<M>} selector - The attribute selector to validate
+     * @param {string} context - The aggregation context used in error messages
+     * @return {void}
+     */
+    private ensureNumericSelector;
+    /**
+     * @description Validates that an aggregation selector targets a numeric or date attribute
+     * @param {SelectSelector<M>} selector - The attribute selector to validate
+     * @param {string} context - The aggregation context used in error messages
+     * @return {void}
+     */
+    private ensureNumberOrDateSelector;
+    /**
+     * @description Validates that a selector's attribute type satisfies a predicate
+     * @summary Resolves the attribute type from the model metadata and raises a
+     * `QueryError` when the type does not match the expected kind.
+     * @param {SelectSelector<M>} selector - The attribute selector to validate
+     * @param {string} context - The aggregation context used in error messages
+     * @param {function(string): boolean} predicate - Type acceptance predicate
+     * @param {string} description - Human readable description of the accepted types
+     * @return {void}
+     */
+    private ensureSelectorType;
+    /**
+     * @description Resolves the attribute type from the model metadata
+     * @summary Reads the metadata or design type of the attribute and normalizes it
+     * to a lowercase type name.
+     * @param {Constructor<Model>} clazz - The model constructor
+     * @param {string} attr - The attribute name
+     * @param {string} context - The context used in error messages
+     * @return {string} The normalized attribute type
+     */
+    private determineAttributeType;
+    /**
+     * @description Normalizes a raw metadata type to a lowercase type name
+     * @param {any} metaType - The raw metadata type value
+     * @return {string | undefined} The normalized type name, when resolvable
+     */
+    private normalizeMetaType;
+    /**
+     * @description Whether the given type name is a numeric type
+     * @param {string} [type] - The normalized type name
+     * @return {boolean} True for "number" and "bigint"
+     */
+    private isNumericType;
+    /**
+     * @description Converts a value to a numeric comparable value
+     * @summary Maps date, number and bigint values to numbers for comparison and
+     * raises a `QueryError` for missing or incompatible values.
+     * @param {any} value - The value to convert
+     * @param {string} attrType - The normalized attribute type
+     * @param {string} attrName - The attribute name used in error messages
+     * @param {string} context - The context used in error messages
+     * @param {object} [options] - Conversion options
+     * @param {boolean} [options.allowNull] - Whether null/undefined values return null instead of raising
+     * @return {number | null} The numeric comparable value
+     */
+    private toComparableValue;
+}

package/lib/types/redis/RedisStatement.d.mts

@@ -0,0 +1,175 @@
+import { Adapter, AdapterFlags, Condition, Statement } from "@decaf-ts/core";
+import { RedisContext, RawRedisQuery } from "./types.d.mts";
+import { Model } from "@decaf-ts/decorator-validation";
+/**
+ * @description Redis-specific query statement builder
+ * @summary Extends the base Statement class to provide query building functionality for the Redis adapter.
+ * This class translates high-level query operations into predicates that can filter and sort
+ * in-memory data structures (records reverted from the table hash).
+ * @template M - The model type being queried
+ * @template R - The result type returned by the query
+ * @class RedisStatement
+ * @category Redis
+ * @example
+ * ```typescript
+ * // Create a statement for querying User models
+ * const statement = redisAdapter.Statement<User>();
+ *
+ * // Build a query to find active users with age > 18
+ * const results = await statement
+ *   .from(User)
+ *   .where(Condition.and(
+ *     Condition.eq('active', true),
+ *     Condition.gt('age', 18)
+ *   ))
+ *   .orderBy('lastName', 'asc')
+ *   .limit(10)
+ *   .execute();
+ * ```
+ */
+export declare class RedisStatement<M extends Model, R, A extends Adapter<M, any, RawRedisQuery<any>, RedisContext>> extends Statement<M, A, R, RawRedisQuery<any>> {
+    /**
+     * @description Creates a statement bound to the Redis adapter
+     * @param {A} adapter - The Redis adapter instance to use for executing queries
+     * @param {Partial<AdapterFlags>} [overrides] - Optional adapter flag overrides
+     */
+    constructor(adapter: A, overrides?: Partial<AdapterFlags>);
+    /**
+     * @description Creates a sort comparator function
+     * @summary Generates a function that compares two model instances based on the orderBy criteria.
+     * This method handles different data types (string, number, date) and sort directions (asc, desc).
+     * @return {function(Model, Model): number} A comparator function for sorting model instances
+     */
+    private getSort;
+    /**
+     * @description Compares two models by a single attribute
+     * @summary Resolves the attribute's design type and delegates to the matching
+     * type-specific comparator.
+     * @param {Model} el1 - The first model instance
+     * @param {Model} el2 - The second model instance
+     * @param {keyof Model} key - The attribute to compare
+     * @return {number} A negative number, zero or a positive number as per the comparison
+     */
+    private compareByKey;
+    /**
+     * @description Compares two boolean values
+     * @return {number} 0 when equal, 1 when `a` is true, -1 otherwise
+     */
+    private compareBooleans;
+    /**
+     * @description Compares two numeric values
+     * @return {number} The numeric difference between the values
+     */
+    private compareNumbers;
+    /**
+     * @description Compares two bigint values
+     * @return {number} 0 when equal, 1 when `a` is greater, -1 otherwise
+     */
+    private compareBigInts;
+    /**
+     * @description Compares two strings using locale-aware ordering
+     * @return {number} The locale compare result between the values
+     */
+    private compareStrings;
+    /**
+     * @description Compares two dates by their epoch timestamps
+     * @return {number} The difference between the timestamps
+     */
+    private compareDates;
+    /**
+     * @description Builds a Redis query from the statement
+     * @summary Converts the statement's selectors and conditions into a RawRedisQuery object
+     * that can be executed by the Redis adapter. This method assembles all query components
+     * (select, from, where, limit, offset, sort) into the final query structure.
+     * @return {RawRedisQuery<M>} The constructed Redis query object
+     */
+    protected build(): RawRedisQuery<any>;
+    /**
+     * @description Parses a condition into a Redis query predicate
+     * @summary Converts a Condition object into a predicate function that can be used
+     * to filter model instances in memory. This method handles both simple conditions
+     * (equals, greater than, etc.) and complex conditions with logical operators (AND, OR).
+     * @template M - The model type for the condition
+     * @param {Condition<M>} condition - The condition to parse
+     * @return {RawRedisQuery<M>} A Redis query object with a where predicate function
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant RedisStatement
+     *   participant SimpleCondition
+     *   participant ComplexCondition
+     *
+     *   Caller->>RedisStatement: parseCondition(condition)
+     *   alt Simple condition (eq, gt, lt, etc.)
+     *     RedisStatement->>SimpleCondition: Extract attr1, operator, comparison
+     *     SimpleCondition-->>RedisStatement: Return predicate function
+     *   else Logical operator (AND, OR)
+     *     RedisStatement->>ComplexCondition: Extract nested conditions
+     *     RedisStatement->>RedisStatement: parseCondition(leftCondition)
+     *     RedisStatement->>RedisStatement: parseCondition(rightCondition)
+     *     ComplexCondition-->>RedisStatement: Combine predicates with logical operator
+     *   end
+     *   RedisStatement-->>Caller: Return query with where predicate
+     */
+    protected parseCondition(condition: Condition<M>): RawRedisQuery<any>;
+    /**
+     * @description Validates that an aggregation selector targets a numeric attribute
+     * @param {SelectSelector<M>} selector - The attribute selector to validate
+     * @param {string} context - The aggregation context used in error messages
+     * @return {void}
+     */
+    private ensureNumericSelector;
+    /**
+     * @description Validates that an aggregation selector targets a numeric or date attribute
+     * @param {SelectSelector<M>} selector - The attribute selector to validate
+     * @param {string} context - The aggregation context used in error messages
+     * @return {void}
+     */
+    private ensureNumberOrDateSelector;
+    /**
+     * @description Validates that a selector's attribute type satisfies a predicate
+     * @summary Resolves the attribute type from the model metadata and raises a
+     * `QueryError` when the type does not match the expected kind.
+     * @param {SelectSelector<M>} selector - The attribute selector to validate
+     * @param {string} context - The aggregation context used in error messages
+     * @param {function(string): boolean} predicate - Type acceptance predicate
+     * @param {string} description - Human readable description of the accepted types
+     * @return {void}
+     */
+    private ensureSelectorType;
+    /**
+     * @description Resolves the attribute type from the model metadata
+     * @summary Reads the metadata or design type of the attribute and normalizes it
+     * to a lowercase type name.
+     * @param {Constructor<Model>} clazz - The model constructor
+     * @param {string} attr - The attribute name
+     * @param {string} context - The context used in error messages
+     * @return {string} The normalized attribute type
+     */
+    private determineAttributeType;
+    /**
+     * @description Normalizes a raw metadata type to a lowercase type name
+     * @param {any} metaType - The raw metadata type value
+     * @return {string | undefined} The normalized type name, when resolvable
+     */
+    private normalizeMetaType;
+    /**
+     * @description Whether the given type name is a numeric type
+     * @param {string} [type] - The normalized type name
+     * @return {boolean} True for "number" and "bigint"
+     */
+    private isNumericType;
+    /**
+     * @description Converts a value to a numeric comparable value
+     * @summary Maps date, number and bigint values to numbers for comparison and
+     * raises a `QueryError` for missing or incompatible values.
+     * @param {any} value - The value to convert
+     * @param {string} attrType - The normalized attribute type
+     * @param {string} attrName - The attribute name used in error messages
+     * @param {string} context - The context used in error messages
+     * @param {object} [options] - Conversion options
+     * @param {boolean} [options.allowNull] - Whether null/undefined values return null instead of raising
+     * @return {number | null} The numeric comparable value
+     */
+    private toComparableValue;
+}

package/lib/types/redis/adapter.d.cts

@@ -0,0 +1,288 @@
+import "reflect-metadata";
+import { Adapter, AdapterFlags, ContextualArgs, MaybeContextualArg, RawResult } from "@decaf-ts/core";
+import { type RedisClientType } from "redis";
+import { BaseError, OperationKeys, PrimaryKeyType } from "@decaf-ts/db-decorators";
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+import { RawRedisQuery, RedisConfig, RedisContext, RedisFlags } from "./types.d.cts";
+import { RedisStatement } from "./RedisStatement.d.cts";
+import { RedisPaginator } from "./RedisPaginator.d.cts";
+import { RedisDispatch } from "./RedisDispatch.d.cts";
+import { RedisContextLock } from "./RedisContextLock.d.cts";
+/**
+ * @description Redis adapter for data persistence
+ * @summary The RedisAdapter implements the persistence layer on top of Redis
+ * (or any Redis-compatible server such as DragonflyDB). Each model table is
+ * stored as a single Redis hash whose fields are record ids and whose values are
+ * serialized records. The adapter is modelled on the core RAM adapter: raw queries
+ * load the matching table, revert every record to a model and then apply the same
+ * filtering, sorting, aggregation and pagination logic in JavaScript.
+ * `@transactional()` is backed by {@link RedisContextLock}, which buffers writes
+ * on a dedicated connection and flushes them atomically with `MULTI`/`EXEC`.
+ * @class RedisAdapter
+ * @category Redis
+ * @example
+ * ```typescript
+ * const adapter = new RedisAdapter({ url: "redis://localhost:6379" });
+ * await adapter.initialize();
+ * const repo = new (adapter.repository<User>())(User, adapter);
+ * await repo.create(new User({ name: "John" }));
+ * ```
+ */
+export declare class RedisAdapter extends Adapter<RedisConfig, RedisClientType, RawRedisQuery, RedisContext> {
+    private _redisClient?;
+    constructor(conf?: RedisConfig, alias?: string);
+    /**
+     * @description Creates operation flags with a user identity
+     * @summary Extends the base flags with a `UUID` used by the `createdBy` and
+     * `updatedBy` handlers. Defaults to the configured `user` or the current time.
+     * @template M - The model type for the operation
+     * @param {OperationKeys} operation - The operation being performed
+     * @param {Constructor<M>} model - The model constructor
+     * @param {Partial<RedisFlags>} flags - Partial flags to extend
+     * @return {Promise<RedisFlags>} The complete flags with a UUID
+     */
+    flags<M extends Model<boolean>>(operation: OperationKeys, model: Constructor<M>, flags: Partial<RedisFlags>): Promise<RedisFlags>;
+    /**
+     * @description Creates the Redis event dispatcher
+     * @return {RedisDispatch} A Redis-aware dispatch instance
+     */
+    protected Dispatch(): RedisDispatch;
+    /**
+     * @description Provides the Redis transaction lock implementation
+     * @summary Returns a fresh {@link RedisContextLock} per top-level transaction
+     * so `@transactional()` can buffer writes on a dedicated connection.
+     * @param {...any[]} args - Optional arguments forwarded to the lock
+     * @return {RedisContextLock} A fresh Redis transaction lock
+     */
+    transactionLock(...args: any[]): RedisContextLock<this>;
+    /**
+     * @description Initializes the adapter and opens the Redis connection
+     * @param {...MaybeContextualArg} args - Initialization arguments
+     * @return {Promise<void>} A promise that resolves once initialization is complete
+     */
+    initialize(...args: MaybeContextualArg<RedisContext>): Promise<void>;
+    /**
+     * @description Shuts down the adapter and closes the Redis connection
+     * @param {...MaybeContextualArg} args - Shutdown arguments
+     * @return {Promise<void>} A promise that resolves once shutdown is complete
+     */
+    shutdown(...args: MaybeContextualArg<RedisContext>): Promise<void>;
+    /**
+     * @description Builds the namespaced Redis key for a table
+     * @param {string} table - The table (model) name
+     * @return {string} The namespaced Redis hash key
+     */
+    recordKey(table: string): string;
+    /**
+     * @description Resolves the active transaction lock from a context, when present
+     * @summary Returns the {@link RedisContextLock} only while a transaction is
+     * actually open, so CRUD operations buffer their writes during a transaction and
+     * go straight to Redis otherwise.
+     * @param {RedisContext} [ctx] - The operation context
+     * @return {RedisContextLock | undefined} The active lock, when one exists
+     */
+    protected activeLock(ctx?: RedisContext): RedisContextLock | undefined;
+    /**
+     * @description Prepares a model for storage
+     * @summary Delegates to the base implementation, which extracts the primary
+     * key from the record before it is handed to {@link create}.
+     * @template M - The model type being prepared
+     * @param {M} model - The model instance to prepare
+     * @return Object containing the record, id and transient data
+     */
+    prepare<M extends Model>(model: M, ...args: [...any[], RedisContext]): {
+        record: Record<string, any>;
+        id: string;
+        transient?: Record<string, any>;
+    };
+    /**
+     * @description Converts a stored record back to a model instance
+     * @summary Delegates to the base implementation, reattaching the primary key
+     * extracted from the record's Redis hash field.
+     * @template M - The model type to revert to
+     * @param {Record<string, any>} obj - The stored record
+     * @param {Constructor<M>} clazz - The model constructor
+     * @param {PrimaryKeyType} id - The primary key value
+     * @return {M} The reconstructed model instance
+     */
+    revert<M extends Model>(obj: Record<string, any>, clazz: Constructor<M>, id: PrimaryKeyType, transient?: Record<string, any>, ...args: [...any[], RedisContext]): M;
+    /**
+     * @description Creates a new record in Redis
+     * @summary Writes the serialized record to the table hash. Inside a
+     * transaction the write is buffered (read-your-writes) instead of hitting
+     * Redis; otherwise `HSETNX` guarantees the record does not already exist.
+     * @template M - The model type
+     * @param {Constructor<M>} clazz - The model constructor
+     * @param {PrimaryKeyType} id - The unique record identifier
+     * @param {Record<string, any>} model - The record to store
+     * @return {Promise<Record<string, any>>} The stored record
+     */
+    create<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: ContextualArgs<RedisContext>): Promise<Record<string, any>>;
+    /**
+     * @description Reads a record from Redis
+     * @summary Reads the record from the table hash. Inside a transaction the
+     * buffered value wins (read-your-writes); a buffered delete is treated as a
+     * missing record.
+     * @template M - The model type
+     * @param {Constructor<M>} clazz - The model constructor
+     * @param {PrimaryKeyType} id - The unique record identifier
+     * @return {Promise<Record<string, any>>} The stored record
+     */
+    read<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<RedisContext>): Promise<Record<string, any>>;
+    /**
+     * @description Updates an existing record in Redis
+     * @summary Inside a transaction the write is buffered; otherwise the record
+     * is overwritten in place. A missing record raises a `NotFoundError`.
+     * @template M - The model type
+     * @param {Constructor<M>} clazz - The model constructor
+     * @param {PrimaryKeyType} id - The unique record identifier
+     * @param {Record<string, any>} model - The new record data
+     * @return {Promise<Record<string, any>>} The updated record
+     */
+    update<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: ContextualArgs<RedisContext>): Promise<Record<string, any>>;
+    /**
+     * @description Deletes a record from Redis
+     * @summary Inside a transaction the delete is buffered; otherwise the field
+     * is removed from the table hash immediately. A missing record raises a
+     * `NotFoundError`.
+     * @template M - The model type
+     * @param {Constructor<M>} clazz - The model constructor
+     * @param {PrimaryKeyType} id - The unique record identifier
+     * @return {Promise<Record<string, any>>} The deleted record
+     */
+    delete<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<RedisContext>): Promise<Record<string, any>>;
+    /**
+     * @description Loads every record of a table, applying buffered writes
+     * @summary Reads the table hash and merges the transaction buffer on top so a
+     * query inside a transaction observes the transaction's own writes.
+     * @param {string} table - The table (model) name
+     * @param {RedisContext} [ctx] - The operation context
+     * @return {Promise<[string, string][]>} The record id/serialized pairs
+     */
+    protected loadTable(table: string, ctx?: RedisContext): Promise<[string, string][]>;
+    /**
+     * @description Executes a raw query against Redis
+     * @summary Loads the matching table, reverts every record to a model and
+     * applies the in-memory filtering, sorting, aggregation and pagination logic.
+     * This mirrors the core RAM adapter, since Redis hashes are not queryable.
+     * @template R - The query return type
+     * @template D - Whether only documents are returned
+     * @param {RawRedisQuery<any>} rawInput - The query specification
+     * @param {D} docsOnly - Whether to return only documents (default true)
+     * @return {Promise<RawResult<R, D>>} The query result
+     */
+    raw<R, D extends boolean>(rawInput: RawRedisQuery<any>, docsOnly?: D, ...args: ContextualArgs<RedisContext>): Promise<RawResult<R, D>>;
+    /**
+     * @description Groups records by one or more attributes
+     * @summary Recursively nests groups when multiple selectors are provided; the
+     * top-level result maps each group key to the matching records (or nested groups).
+     * @param {any[]} records - The records to group
+     * @param {(keyof Model)[]} selectors - The attributes to group by
+     * @return {Record<string, any>} The grouped records keyed by normalized group keys
+     */
+    private groupRecords;
+    /**
+     * @description Normalizes a group key to a string
+     * @summary Produces a stable string key for `undefined`, `null`, symbols,
+     * objects (via JSON) and primitives.
+     * @param {any} value - The raw group key value
+     * @return {string} The normalized key
+     */
+    private normalizeGroupKey;
+    /**
+     * @description Applies skip/limit pagination over grouped results
+     * @summary Pages the group keys while preserving their associated records.
+     * @param {Record<string, any>} grouped - The grouped records
+     * @param {number} [skip] - The number of groups to skip
+     * @param {number} [limit] - The maximum number of groups to return
+     * @return {Record<string, any>} The paged groups
+     */
+    private applyGroupPagination;
+    /**
+     * @description Parses and converts errors to appropriate types
+     * @summary Returns `BaseError` instances unchanged, maps connection
+     * failures to `ConnectionError` and wraps everything else in an
+     * `InternalError`.
+     * @template V - The expected error type
+     * @param {Error} err - The error to parse
+     * @return {V} The parsed error
+     */
+    parseError<V extends BaseError>(err: Error): V;
+    /**
+     * @description Creates a new statement builder for queries
+     * @template M - The model type for the statement
+     * @param {Partial<AdapterFlags>} [overrides] - Optional adapter flag overrides
+     * @return {RedisStatement<M, any, Adapter<...>>} A new statement builder
+     */
+    Statement<M extends Model<boolean>>(overrides?: Partial<AdapterFlags>): RedisStatement<M, any, Adapter<any, any, RawRedisQuery<M>, RedisContext>>;
+    /**
+     * @description Creates a new paginator for queries
+     * @template M - The model type for the paginator
+     * @param {RawRedisQuery} query - The query to paginate
+     * @param {number} size - The page size
+     * @param {Constructor<M>} clazz - The model constructor
+     * @return {RedisPaginator<M>} A new paginator
+     */
+    Paginator<M extends Model<boolean>>(query: RawRedisQuery, size: number, clazz: Constructor<M>): RedisPaginator<M>;
+    /**
+     * @description Validates that an aggregation targets an attribute of the expected kind
+     * @summary Resolves the attribute type from the model metadata and raises a
+     * `QueryError` when the type does not satisfy the given predicate.
+     * @param {Constructor<Model>} clazz - The model constructor
+     * @param {string} field - The attribute name to validate
+     * @param {string} context - The aggregation context used in error messages
+     * @param {function(string): boolean} predicate - Type acceptance predicate
+     * @param {string} description - Human readable description of the accepted types
+     * @return {void}
+     */
+    private ensureFieldType;
+    /**
+     * @description Resolves the attribute type from the model metadata
+     * @summary Reads the metadata or design type of the attribute and normalizes it
+     * to a lowercase type name.
+     * @param {Constructor<Model>} clazz - The model constructor
+     * @param {string} field - The attribute name
+     * @return {string | undefined} The normalized attribute type, when resolvable
+     */
+    private resolveFieldType;
+    /**
+     * @description Normalizes a raw metadata type to a lowercase type name
+     * @param {any} metaType - The raw metadata type value
+     * @return {string | undefined} The normalized type name, when resolvable
+     */
+    private normalizeMetaType;
+    /**
+     * @description Whether the given type name is a numeric type
+     * @param {string} [type] - The normalized type name
+     * @return {boolean} True for "number" and "bigint"
+     */
+    private isNumericType;
+    /**
+     * @description Converts a value to a numeric value for aggregation
+     * @summary Accepts numbers and bigints (converted to `Number`) and raises a
+     * `QueryError` for any other value kind.
+     * @param {any} value - The value to convert
+     * @param {string} field - The attribute name used in error messages
+     * @param {string} context - The aggregation context used in error messages
+     * @return {number} The numeric value
+     */
+    private toNumericValue;
+    /**
+     * @description Creates the underlying Redis client
+     * @summary Returns the already connected client when one exists (including
+     * through a `for()` configuration-scoped proxy, whose own `_client` slot would
+     * otherwise be empty and build a fresh unconnected client). Otherwise builds a
+     * node-redis client from the configured URL or discrete host/port/credentials.
+     * The client is created lazily and connected by {@link initialize}.
+     * @return {RedisClientType} The Redis client
+     */
+    protected getClient(): RedisClientType;
+    /**
+     * @description Registers Redis-specific decorations for model properties
+     * @summary Configures `createdBy` and `updatedBy` handlers for the Redis
+     * flavour so those fields are populated from the context UUID.
+     * @return {void}
+     */
+    static decoration(): void;
+}