@warlock.js/core 4.5.0 → 4.6.1

package/esm/repositories/adapters/cascade/cascade-query-builder.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cascade-query-builder.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/core/src/repositories/adapters/cascade/cascade-query-builder.ts"],"sourcesContent":["import type {\n  QueryBuilderContract as CascadeQueryBuilderContract,\n  Model,\n} from \"@warlock.js/cascade\";\nimport type {\n  ChunkCallback,\n  CursorPaginationOptions,\n  CursorPaginationResult,\n  FilterOptions,\n  FilterRules,\n  PaginationResult,\n  QueryBuilderContract,\n  WhereOperator,\n} from \"../../contracts\";\nimport { FilterApplicator } from \"./filter-applicator\";\n\n/**\n * Cascade query builder wrapper\n * Wraps Cascade-Next's ModelAggregate to implement QueryBuilderContract\n *\n * @template T - The model instance type\n */\nexport class CascadeQueryBuilder<T extends Model> implements QueryBuilderContract<T> {\n  /**\n   * Constructor\n   * @param query - Cascade-Next QueryBuilder instance\n   */\n  public constructor(private query: CascadeQueryBuilderContract<T>) {}\n\n  // ============================================================================\n  // WHERE CLAUSES\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.where}\n   */\n  public where(field: string, value: any): this;\n  public where(field: string, operator: WhereOperator, value: any): this;\n  public where(conditions: Record<string, any>): this;\n  public where(callback: (query: this) => void): this;\n  public where(\n    fieldOrConditionsOrCallback: string | Record<string, any> | ((query: this) => void),\n    operatorOrValue?: WhereOperator | any,\n    value?: any,\n  ): this {\n    if (typeof fieldOrConditionsOrCallback === \"function\") {\n      // Callback\n      fieldOrConditionsOrCallback(this);\n    } else if (typeof fieldOrConditionsOrCallback === \"object\") {\n      // Object conditions\n      this.query.where(fieldOrConditionsOrCallback);\n    } else if (value !== undefined) {\n      // Field, operator, value\n      this.query.where(fieldOrConditionsOrCallback, operatorOrValue, value);\n    } else {\n      // Field, value\n      this.query.where(fieldOrConditionsOrCallback, operatorOrValue);\n    }\n\n    return this;\n  }\n\n  /**\n   * Pretty display the query in terminal\n   */\n  public pretty() {\n    return this.query.pretty();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.orWhere}\n   */\n  public orWhere(field: string, value: any): this;\n  public orWhere(field: string, operator: WhereOperator, value: any): this;\n  public orWhere(conditions: Record<string, any>): this;\n  public orWhere(\n    fieldOrConditions: string | Record<string, any>,\n    operatorOrValue?: WhereOperator | any,\n    value?: any,\n  ): this {\n    if (typeof fieldOrConditions === \"object\") {\n      this.query.orWhere(fieldOrConditions);\n    } else if (value !== undefined) {\n      this.query.orWhere(fieldOrConditions, operatorOrValue, value);\n    } else {\n      this.query.orWhere(fieldOrConditions, operatorOrValue);\n    }\n\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereIn}\n   */\n  public whereIn(field: string, values: any[]): this {\n    this.query.whereIn(field, values);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereNotIn}\n   */\n  public whereNotIn(field: string, values: any[]): this {\n    this.query.whereNotIn(field, values);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereNull}\n   */\n  public whereNull(field: string): this {\n    this.query.whereNull(field);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereNotNull}\n   */\n  public whereNotNull(field: string): this {\n    this.query.whereNotNull(field);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereBetween}\n   */\n  public whereBetween(field: string, range: [any, any]): this {\n    this.query.whereBetween(field, range);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereLike}\n   */\n  public whereLike(field: string, pattern: string): this {\n    this.query.whereLike(field, pattern);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.similarTo}\n   */\n  public similarTo(column: string, embedding: number[], alias?: string): this {\n    this.query.similarTo(column, embedding, alias);\n    return this;\n  }\n\n  // ============================================================================\n  // SELECT / PROJECTION\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.select}\n   */\n  public select(fields: string[]): this;\n  public select(...fields: string[]): this;\n  public select(...fields: any[]): this {\n    if (Array.isArray(fields[0])) {\n      this.query.select(fields[0]);\n    } else {\n      this.query.select(fields);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.deselect}\n   */\n  public deselect(fields: string[]): this;\n  public deselect(...fields: string[]): this;\n  public deselect(...fields: any[]): this {\n    if (Array.isArray(fields[0])) {\n      this.query.deselect(fields[0]);\n    } else {\n      this.query.deselect(fields);\n    }\n    return this;\n  }\n\n  // ============================================================================\n  // ORDERING\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.orderBy}\n   */\n  public orderBy(field: string, direction: \"asc\" | \"desc\" = \"asc\"): this {\n    this.query.orderBy(field, direction);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.sortBy}\n   */\n  public sortBy(orderBy: Record<string, \"asc\" | \"desc\">): this {\n    // Apply each order clause individually\n    for (const [field, direction] of Object.entries(orderBy)) {\n      this.query.orderBy(field, direction);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.random}\n   */\n  public random(limit: number): this {\n    this.query.orderByRandom(limit);\n    return this;\n  }\n\n  // ============================================================================\n  // LIMITING\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.limit}\n   */\n  public limit(limit: number): this {\n    this.query.limit(limit);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.offset}\n   */\n  public offset(offset: number): this {\n    this.query.offset(offset);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.skip}\n   */\n  public skip(count: number): this {\n    return this.offset(count);\n  }\n\n  // ============================================================================\n  // FILTERING (Repository-specific)\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.applyFilters}\n   */\n  public applyFilters(filters: FilterRules<this>, data: any, options: FilterOptions): this {\n    const applicator = new FilterApplicator();\n    applicator.apply(this.query as any, filters, data, options);\n    return this;\n  }\n\n  // ============================================================================\n  // EXECUTION\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.get}\n   */\n  public async get(): Promise<T[]> {\n    return this.query.get();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.first}\n   */\n  public async first(): Promise<T | null> {\n    return this.query.first();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.count}\n   */\n  public async count(): Promise<number> {\n    return this.query.count();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.paginate}\n   */\n  public async paginate(page: number, limit: number): Promise<PaginationResult<T>> {\n    const result = await this.query.paginate({ limit, page });\n\n    // Convert Cascade-Next pagination to repository format\n    return {\n      data: result.data,\n      pagination: {\n        ...result.pagination,\n        result: result.data.length,\n      },\n    };\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.cursorPaginate}\n   *\n   * NOTE: This method is a pure executor.\n   * The caller (e.g. RepositoryManager._listImpl) is responsible for applying\n   * the cursor WHERE condition and ORDER BY BEFORE calling this method,\n   * so that the cursor column is always the primary sort key.\n   *\n   * For a forward page (`direction: \"next\"`) the caller sorts ASC and filters\n   * `> cursor`, so the rows already arrive in ascending cursor order.\n   *\n   * For a backward page (`direction: \"prev\"`) the caller sorts DESC and filters\n   * `< cursor`, so rows arrive in DESCENDING order. We re-reverse the trimmed\n   * page back to ascending so callers always receive a page in the same\n   * (ascending) order regardless of direction, and we derive the next/prev\n   * cursors from the page boundaries accordingly.\n   */\n  public async cursorPaginate(\n    options: CursorPaginationOptions,\n  ): Promise<CursorPaginationResult<T>> {\n    const { limit, cursorColumn = \"id\", direction = \"next\" } = options;\n\n    // Fetch limit + 1 to detect whether more pages exist in the scan direction.\n    this.limit(limit + 1);\n\n    const results = await this.get();\n    const hasMore = results.length > limit;\n\n    // Drop the extra record used for the hasMore check. It always sits at the\n    // tail because the caller ordered the scan so the next-to-fetch row is last.\n    const trimmed = hasMore ? results.slice(0, limit) : results;\n\n    const cursorOf = (record: T | undefined): string | number | undefined =>\n      record === undefined ? undefined : ((record as any)[cursorColumn] as string | number);\n\n    if (direction === \"prev\") {\n      // Scan came back DESC; present it ascending.\n      const documents = [...trimmed].reverse();\n      const first = documents[0];\n      const last = documents[documents.length - 1];\n\n      return {\n        data: documents,\n        pagination: {\n          limit,\n          result: documents.length,\n          hasMore,\n          // Going further back is only possible when the backward scan saw more\n          // rows than this page; the boundary is this page's first (smallest) row.\n          prevCursor: hasMore ? cursorOf(first) : undefined,\n          // Going forward always resumes after this page's last (largest) row.\n          nextCursor: cursorOf(last),\n        },\n      };\n    }\n\n    // Forward page — rows already ascending.\n    const documents = trimmed;\n    const first = documents[0];\n    const last = documents[documents.length - 1];\n\n    return {\n      data: documents,\n      pagination: {\n        limit,\n        result: documents.length,\n        hasMore,\n        // Going forward is only possible when the forward scan saw more rows\n        // than this page; the boundary is this page's last (largest) row.\n        nextCursor: hasMore ? cursorOf(last) : undefined,\n        // Going back resumes before this page's first (smallest) row.\n        prevCursor: cursorOf(first),\n      },\n    };\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.chunk}\n   */\n  public async chunk(size: number, callback: ChunkCallback<T>): Promise<void> {\n    return this.query.chunk(size, callback);\n  }\n\n  // ============================================================================\n  // UTILITIES\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.with}\n   */\n  public with(relation: string): this {\n    this.query.with(relation);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.joinWith}\n   */\n  public joinWith(...relations: string[]): this {\n    if (this.query.joinWith) {\n      this.query.joinWith(...relations);\n    } else {\n      console.warn(\n        \"[Repository] joinWith is not supported by the underlying query builder. Falling back to with.\",\n      );\n      for (const relation of relations) {\n        this.query.with(relation);\n      }\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.clone}\n   */\n  public clone(): this {\n    return new CascadeQueryBuilder(this.query.clone()) as this;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"cascade-query-builder.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/core/src/repositories/adapters/cascade/cascade-query-builder.ts"],"sourcesContent":["import type {\n  QueryBuilderContract as CascadeQueryBuilderContract,\n  Model,\n} from \"@warlock.js/cascade\";\nimport type {\n  AggregateExpressions,\n  ChunkCallback,\n  CursorPaginationOptions,\n  CursorPaginationResult,\n  FilterOptions,\n  FilterRules,\n  GroupByFields,\n  PaginationResult,\n  QueryBuilderContract,\n  WhereOperator,\n} from \"../../contracts\";\nimport { FilterApplicator } from \"./filter-applicator\";\n\n/**\n * Cascade query builder wrapper\n * Wraps Cascade-Next's ModelAggregate to implement QueryBuilderContract\n *\n * @template T - The model instance type\n */\nexport class CascadeQueryBuilder<T extends Model> implements QueryBuilderContract<T> {\n  /**\n   * Constructor\n   * @param query - Cascade-Next QueryBuilder instance\n   */\n  public constructor(private query: CascadeQueryBuilderContract<T>) {}\n\n  // ============================================================================\n  // WHERE CLAUSES\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.where}\n   */\n  public where(field: string, value: any): this;\n  public where(field: string, operator: WhereOperator, value: any): this;\n  public where(conditions: Record<string, any>): this;\n  public where(callback: (query: this) => void): this;\n  public where(\n    fieldOrConditionsOrCallback: string | Record<string, any> | ((query: this) => void),\n    operatorOrValue?: WhereOperator | any,\n    value?: any,\n  ): this {\n    if (typeof fieldOrConditionsOrCallback === \"function\") {\n      // Callback\n      fieldOrConditionsOrCallback(this);\n    } else if (typeof fieldOrConditionsOrCallback === \"object\") {\n      // Object conditions\n      this.query.where(fieldOrConditionsOrCallback);\n    } else if (value !== undefined) {\n      // Field, operator, value\n      this.query.where(fieldOrConditionsOrCallback, operatorOrValue, value);\n    } else {\n      // Field, value\n      this.query.where(fieldOrConditionsOrCallback, operatorOrValue);\n    }\n\n    return this;\n  }\n\n  /**\n   * Pretty display the query in terminal\n   */\n  public pretty() {\n    return this.query.pretty();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.orWhere}\n   */\n  public orWhere(field: string, value: any): this;\n  public orWhere(field: string, operator: WhereOperator, value: any): this;\n  public orWhere(conditions: Record<string, any>): this;\n  public orWhere(\n    fieldOrConditions: string | Record<string, any>,\n    operatorOrValue?: WhereOperator | any,\n    value?: any,\n  ): this {\n    if (typeof fieldOrConditions === \"object\") {\n      this.query.orWhere(fieldOrConditions);\n    } else if (value !== undefined) {\n      this.query.orWhere(fieldOrConditions, operatorOrValue, value);\n    } else {\n      this.query.orWhere(fieldOrConditions, operatorOrValue);\n    }\n\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereIn}\n   */\n  public whereIn(field: string, values: any[]): this {\n    this.query.whereIn(field, values);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereNotIn}\n   */\n  public whereNotIn(field: string, values: any[]): this {\n    this.query.whereNotIn(field, values);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereNull}\n   */\n  public whereNull(field: string): this {\n    this.query.whereNull(field);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereNotNull}\n   */\n  public whereNotNull(field: string): this {\n    this.query.whereNotNull(field);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereBetween}\n   */\n  public whereBetween(field: string, range: [any, any]): this {\n    this.query.whereBetween(field, range);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.whereLike}\n   */\n  public whereLike(field: string, pattern: string): this {\n    this.query.whereLike(field, pattern);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.similarTo}\n   */\n  public similarTo(column: string, embedding: number[], alias?: string): this {\n    this.query.similarTo(column, embedding, alias);\n    return this;\n  }\n\n  // ============================================================================\n  // SELECT / PROJECTION\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.select}\n   */\n  public select(fields: string[]): this;\n  public select(...fields: string[]): this;\n  public select(...fields: any[]): this {\n    if (Array.isArray(fields[0])) {\n      this.query.select(fields[0]);\n    } else {\n      this.query.select(fields);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.deselect}\n   */\n  public deselect(fields: string[]): this;\n  public deselect(...fields: string[]): this;\n  public deselect(...fields: any[]): this {\n    if (Array.isArray(fields[0])) {\n      this.query.deselect(fields[0]);\n    } else {\n      this.query.deselect(fields);\n    }\n    return this;\n  }\n\n  // ============================================================================\n  // ORDERING\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.orderBy}\n   */\n  public orderBy(field: string, direction: \"asc\" | \"desc\" = \"asc\"): this {\n    this.query.orderBy(field, direction);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.sortBy}\n   */\n  public sortBy(orderBy: Record<string, \"asc\" | \"desc\">): this {\n    // Apply each order clause individually\n    for (const [field, direction] of Object.entries(orderBy)) {\n      this.query.orderBy(field, direction);\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.random}\n   */\n  public random(limit: number): this {\n    this.query.orderByRandom(limit);\n    return this;\n  }\n\n  // ============================================================================\n  // LIMITING\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.limit}\n   */\n  public limit(limit: number): this {\n    this.query.limit(limit);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.offset}\n   */\n  public offset(offset: number): this {\n    this.query.offset(offset);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.skip}\n   */\n  public skip(count: number): this {\n    return this.offset(count);\n  }\n\n  // ============================================================================\n  // FILTERING (Repository-specific)\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.applyFilters}\n   */\n  public applyFilters(filters: FilterRules<this>, data: any, options: FilterOptions): this {\n    const applicator = new FilterApplicator();\n    applicator.apply(this.query as any, filters, data, options);\n    return this;\n  }\n\n  // ============================================================================\n  // EXECUTION\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.get}\n   */\n  public async get(): Promise<T[]> {\n    return this.query.get();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.first}\n   */\n  public async first(): Promise<T | null> {\n    return this.query.first();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.count}\n   */\n  public async count(): Promise<number> {\n    return this.query.count();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.sum}\n   */\n  public async sum(field: string): Promise<number> {\n    return this.query.sum(field);\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.avg}\n   */\n  public async avg(field: string): Promise<number> {\n    return this.query.avg(field);\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.min}\n   */\n  public async min(field: string): Promise<number> {\n    return this.query.min(field);\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.max}\n   */\n  public async max(field: string): Promise<number> {\n    return this.query.max(field);\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.groupBy}\n   */\n  public async groupBy<R = Record<string, unknown>>(\n    fields: GroupByFields,\n    aggregates: AggregateExpressions,\n  ): Promise<R[]> {\n    return this.query.groupBy(fields, aggregates).get<R>();\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.aggregate}\n   *\n   * Whole-set aggregation: groups with no group key so every matching record\n   * falls into a single group, then returns that one summary row.\n   */\n  public async aggregate<R = Record<string, unknown>>(\n    aggregates: AggregateExpressions,\n  ): Promise<R | null> {\n    const rows = await this.query.groupBy([], aggregates).get<R>();\n    return rows[0] ?? null;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.paginate}\n   */\n  public async paginate(page: number, limit: number): Promise<PaginationResult<T>> {\n    const result = await this.query.paginate({ limit, page });\n\n    // Convert Cascade-Next pagination to repository format\n    return {\n      data: result.data,\n      pagination: {\n        ...result.pagination,\n        result: result.data.length,\n      },\n    };\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.cursorPaginate}\n   *\n   * NOTE: This method is a pure executor.\n   * The caller (e.g. RepositoryManager._listImpl) is responsible for applying\n   * the cursor WHERE condition and ORDER BY BEFORE calling this method,\n   * so that the cursor column is always the primary sort key.\n   *\n   * For a forward page (`direction: \"next\"`) the caller sorts ASC and filters\n   * `> cursor`, so the rows already arrive in ascending cursor order.\n   *\n   * For a backward page (`direction: \"prev\"`) the caller sorts DESC and filters\n   * `< cursor`, so rows arrive in DESCENDING order. We re-reverse the trimmed\n   * page back to ascending so callers always receive a page in the same\n   * (ascending) order regardless of direction, and we derive the next/prev\n   * cursors from the page boundaries accordingly.\n   */\n  public async cursorPaginate(\n    options: CursorPaginationOptions,\n  ): Promise<CursorPaginationResult<T>> {\n    const { limit, cursorColumn = \"id\", direction = \"next\" } = options;\n\n    // Fetch limit + 1 to detect whether more pages exist in the scan direction.\n    this.limit(limit + 1);\n\n    const results = await this.get();\n    const hasMore = results.length > limit;\n\n    // Drop the extra record used for the hasMore check. It always sits at the\n    // tail because the caller ordered the scan so the next-to-fetch row is last.\n    const trimmed = hasMore ? results.slice(0, limit) : results;\n\n    const cursorOf = (record: T | undefined): string | number | undefined =>\n      record === undefined ? undefined : ((record as any)[cursorColumn] as string | number);\n\n    if (direction === \"prev\") {\n      // Scan came back DESC; present it ascending.\n      const documents = [...trimmed].reverse();\n      const first = documents[0];\n      const last = documents[documents.length - 1];\n\n      return {\n        data: documents,\n        pagination: {\n          limit,\n          result: documents.length,\n          hasMore,\n          // Going further back is only possible when the backward scan saw more\n          // rows than this page; the boundary is this page's first (smallest) row.\n          prevCursor: hasMore ? cursorOf(first) : undefined,\n          // Going forward always resumes after this page's last (largest) row.\n          nextCursor: cursorOf(last),\n        },\n      };\n    }\n\n    // Forward page — rows already ascending.\n    const documents = trimmed;\n    const first = documents[0];\n    const last = documents[documents.length - 1];\n\n    return {\n      data: documents,\n      pagination: {\n        limit,\n        result: documents.length,\n        hasMore,\n        // Going forward is only possible when the forward scan saw more rows\n        // than this page; the boundary is this page's last (largest) row.\n        nextCursor: hasMore ? cursorOf(last) : undefined,\n        // Going back resumes before this page's first (smallest) row.\n        prevCursor: cursorOf(first),\n      },\n    };\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.chunk}\n   */\n  public async chunk(size: number, callback: ChunkCallback<T>): Promise<void> {\n    return this.query.chunk(size, callback);\n  }\n\n  // ============================================================================\n  // UTILITIES\n  // ============================================================================\n\n  /**\n   * {@inheritDoc QueryBuilderContract.with}\n   */\n  public with(relation: string): this {\n    this.query.with(relation);\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.joinWith}\n   */\n  public joinWith(...relations: string[]): this {\n    if (this.query.joinWith) {\n      this.query.joinWith(...relations);\n    } else {\n      console.warn(\n        \"[Repository] joinWith is not supported by the underlying query builder. Falling back to with.\",\n      );\n      for (const relation of relations) {\n        this.query.with(relation);\n      }\n    }\n    return this;\n  }\n\n  /**\n   * {@inheritDoc QueryBuilderContract.clone}\n   */\n  public clone(): this {\n    return new CascadeQueryBuilder(this.query.clone()) as this;\n  }\n}\n"],"mappings":"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"}

package/esm/repositories/contracts/index.d.mts

@@ -1,3 +1,3 @@
 import { RepositoryAdapterContract } from "./repository-adapter.contract.mjs";
 import { AllRepositoryOptions, CachedRepositoryOptions, ChunkCallback, CursorPaginationOptions, CursorPaginationResult, FilterFunction, FilterOperator, FilterOptions, FilterRule, FilterRules, PaginationMode, PaginationResult, RepositoryConfigurations, RepositoryEvent, RepositoryOptions, RepositoryOptionsWithCursor, RepositoryOptionsWithPages, SaveMode, TypedAllRepositoryOptions, TypedRepositoryOptions, TypedRepositoryOptionsWithCursor, TypedRepositoryOptionsWithPages, WhereOperator } from "./types.mjs";
-import { QueryBuilderContract } from "./query-builder.contract.mjs";
+import { AggregateExpressionInput, AggregateExpressions, GroupByFields, QueryBuilderContract } from "./query-builder.contract.mjs";

package/esm/repositories/contracts/query-builder.contract.d.mts

@@ -1,6 +1,29 @@
 import { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, FilterOptions, FilterRules, PaginationResult, WhereOperator } from "./types.mjs";
 
 //#region ../@warlock.js/core/src/repositories/contracts/query-builder.contract.d.ts
+/**
+ * Field(s) to group aggregated results by.
+ *
+ * ORM-agnostic mirror of the underlying driver's group-by payload: a single
+ * field name, a list of field names, or a driver-specific object form.
+ */
+type GroupByFields = string | string[] | Record<string, unknown> | Array<Record<string, unknown>>;
+/**
+ * A single aggregate expression in a `groupBy` / `aggregate` projection.
+ *
+ * Either an abstract, cross-driver expression (e.g. produced by Cascade's
+ * `$agg.count()` / `$agg.sum("amount")`) or a raw, driver-specific shape
+ * (e.g. MongoDB `{ $sum: "$amount" }`, SQL `"SUM(amount)"`). The repository
+ * layer is agnostic to which form is used and forwards it verbatim.
+ */
+type AggregateExpressionInput = string | Record<string, unknown> | unknown;
+/**
+ * Map of result aliases to aggregate expressions.
+ *
+ * @example
+ * { count: $agg.count(), total: $agg.sum("total") }
+ */
+type AggregateExpressions = Record<string, AggregateExpressionInput>;
 /**
  * Query builder contract for building database queries
  * This interface is ORM-agnostic and can be implemented by any data source adapter
@@ -244,6 +267,69 @@ interface QueryBuilderContract<T> {
    * @returns Promise resolving to count
    */
   count(): Promise<number>;
+  /**
+   * Sum a numeric field across all matching records.
+   *
+   * @param field - Field name to sum
+   * @returns Promise resolving to the numeric sum (0 when no records match)
+   *
+   * @example
+   * await query.where("status", "paid").sum("total")
+   */
+  sum(field: string): Promise<number>;
+  /**
+   * Average a numeric field across all matching records.
+   *
+   * @param field - Field name to average
+   * @returns Promise resolving to the numeric average (0 when no records match)
+   *
+   * @example
+   * await query.where("status", "paid").avg("total")
+   */
+  avg(field: string): Promise<number>;
+  /**
+   * Minimum value of a field across all matching records.
+   *
+   * @param field - Field name
+   * @returns Promise resolving to the minimum value (0 when no records match)
+   */
+  min(field: string): Promise<number>;
+  /**
+   * Maximum value of a field across all matching records.
+   *
+   * @param field - Field name
+   * @returns Promise resolving to the maximum value (0 when no records match)
+   */
+  max(field: string): Promise<number>;
+  /**
+   * Group matching records by one or more fields and compute aggregates.
+   *
+   * This is a terminal executor: it applies the grouping + aggregate
+   * projection and returns the grouped rows.
+   *
+   * @template R - Shape of each grouped row
+   * @param fields - Field(s) to group by
+   * @param aggregates - Map of result aliases to aggregate expressions
+   * @returns Promise resolving to the array of grouped rows
+   *
+   * @example
+   * await query.groupBy("status", { count: $agg.count(), total: $agg.sum("total") })
+   */
+  groupBy<R = Record<string, unknown>>(fields: GroupByFields, aggregates: AggregateExpressions): Promise<R[]>;
+  /**
+   * Compute aggregates over the whole matching set as a single summary row.
+   *
+   * Equivalent to a `groupBy` with no group key — every matching record falls
+   * into one group and the aggregate projection is returned as one object.
+   *
+   * @template R - Shape of the summary row
+   * @param aggregates - Map of result aliases to aggregate expressions
+   * @returns Promise resolving to the single summary row (or `null` when empty)
+   *
+   * @example
+   * await query.aggregate({ total: $agg.sum("total"), avg: $agg.avg("total") })
+   */
+  aggregate<R = Record<string, unknown>>(aggregates: AggregateExpressions): Promise<R | null>;
   /**
    * Execute query with pagination
    *
@@ -320,5 +406,5 @@ interface QueryBuilderContract<T> {
   similarTo(column: string, embedding: number[], alias?: string): this;
 }
 //#endregion
-export { QueryBuilderContract };
+export { AggregateExpressionInput, AggregateExpressions, GroupByFields, QueryBuilderContract };
 //# sourceMappingURL=query-builder.contract.d.mts.map

package/esm/repositories/contracts/query-builder.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"query-builder.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/core/src/repositories/contracts/query-builder.contract.ts"],"mappings":";;;;;AAgBA;;;;UAAiB,oBAAA;EAqEkB;;;;;;;;;;EAtDjC,KAAA,CAAM,KAAA,UAAe,KAAA;EAyR0B;;;;;;;;;;;EA5Q/C,KAAA,CAAM,KAAA,UAAe,QAAA,EAAU,aAAA,EAAe,KAAA;EAb9C;;;;;;;;;EAwBA,KAAA,CAAM,UAAA,EAAY,MAAA;EAAZ;;;;;;;;;EAWN,KAAA,CAAM,QAAA,GAAW,KAAA;EAmBM;;;;;;;EAVvB,OAAA,CAAQ,KAAA,UAAe,KAAA;EAuCvB;;;;;;;;EA7BA,OAAA,CAAQ,KAAA,UAAe,QAAA,EAAU,aAAA,EAAe,KAAA;EAyDpB;;;;;;EAjD5B,OAAA,CAAQ,UAAA,EAAY,MAAA;EA4FpB;;;;;;;;;;EAhFA,OAAA,CAAQ,KAAA,UAAe,MAAA;EA2HhB;;;;;;;EAlHP,UAAA,CAAW,KAAA,UAAe,MAAA;EAsJrB;;;;;;EA9IL,SAAA,CAAU,KAAA;EAuKV;;;;;;EA/JA,YAAA,CAAa,KAAA;EA6KJ;;;;;;;;;;EAjKT,YAAA,CAAa,KAAA,UAAe,KAAA;EAsL8B;;;;;;;;;;EA1K1D,SAAA,CAAU,KAAA,UAAe,OAAA;EA6MZ;;;EAxMb,MAAA;EAqO0B;;;AAAmC;;;;;;EAtN7D,MAAA,CAAO,MAAA;;;;;;;;;;EAWP,MAAA,IAAU,MAAA;;;;;;;EAQV,QAAA,CAAS,MAAA;;;;;;;EAQT,QAAA,IAAY,MAAA;;;;;;;;;;;EAgBZ,OAAA,CAAQ,KAAA,UAAe,SAAA;;;;;;;;;;EAWvB,MAAA,CAAO,OAAA,EAAS,MAAA;;;;;;;EAQhB,MAAA,CAAO,KAAA;;;;;;;EAYP,KAAA,CAAM,KAAA;;;;;;;EAQN,MAAA,CAAO,MAAA;;;;;;;EAQP,IAAA,CAAK,KAAA;;;;;;;;;EAcL,YAAA,CAAa,OAAA,EAAS,WAAA,QAAmB,IAAA,OAAW,OAAA,EAAS,aAAA;;;;;;EAW7D,GAAA,IAAO,OAAA,CAAQ,CAAA;;;;;;EAOf,KAAA,IAAS,OAAA,CAAQ,CAAA;;;;;;EAOjB,KAAA,IAAS,OAAA;;;;;;;;EAST,QAAA,CAAS,IAAA,UAAc,KAAA,WAAgB,OAAA,CAAQ,gBAAA,CAAiB,CAAA;;;;;;;;;;;EAYhE,cAAA,CAAe,OAAA,EAAS,uBAAA,GAA0B,OAAA,CAAQ,sBAAA,CAAuB,CAAA;;;;;;;;EASjF,KAAA,CAAM,IAAA,UAAc,QAAA,EAAU,aAAA,CAAc,CAAA,IAAK,OAAA;;;;;;;;;;EAejD,IAAA,EAAM,QAAA;;;;;;;;;;EAWN,QAAA,KAAa,SAAA;;;;;;EAOb,KAAA;;;;;;;;;;;;;;;;;;;;;EAsBA,SAAA,CAAU,MAAA,UAAgB,SAAA,YAAqB,KAAA;AAAA"}
+{"version":3,"file":"query-builder.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/core/src/repositories/contracts/query-builder.contract.ts"],"mappings":";;;;;AAgBA;;;;KAAY,aAAA,uBAAoC,MAAA,oBAA0B,KAAA,CAAM,MAAA;;;;;;;;AAAM;KAU1E,wBAAA,YAAoC,MAAM;;;;AAAA;AAQtD;;KAAY,oBAAA,GAAuB,MAAM,SAAS,wBAAA;;AAAwB;AAQ1E;;;;UAAiB,oBAAA;EAqEkB;;;;;;;;;;EAtDjC,KAAA,CAAM,KAAA,UAAe,KAAA;EAsSD;;;;;;;;;;;EAzRpB,KAAA,CAAM,KAAA,UAAe,QAAA,EAAU,aAAA,EAAe,KAAA;EAoVkB;;;;;;;;;EAzUhE,KAAA,CAAM,UAAA,EAAY,MAAA;EA8VsC;;;;;;;;;EAnVxD,KAAA,CAAM,QAAA,GAAW,KAAA;EAtB6B;;;;;;;EA+B9C,OAAA,CAAQ,KAAA,UAAe,KAAA;EAAf;;;;;;;;EAUR,OAAA,CAAQ,KAAA,UAAe,QAAA,EAAU,aAAA,EAAe,KAAA;EAQxC;;;;;;EAAR,OAAA,CAAQ,UAAA,EAAY,MAAA;EA6BpB;;;;;;;;;;EAjBA,OAAA,CAAQ,KAAA,UAAe,MAAA;EAqEvB;;;;;;;EA5DA,UAAA,CAAW,KAAA,UAAe,MAAA;EAuG1B;;;;;;EA/FA,SAAA,CAAU,KAAA;EAkHH;;;;;;EA1GP,YAAA,CAAa,KAAA;EAoJb;;;;;;;;;;EAxIA,YAAA,CAAa,KAAA,UAAe,KAAA;EA0JX;;;;;;;;;;EA9IjB,SAAA,CAAU,KAAA,UAAe,OAAA;EAmLL;;;EA9KpB,MAAA;EAsMA;;;;;;;;;EAvLA,MAAA,CAAO,MAAA;EAyMG;;;;;;;;;EA9LV,MAAA,IAAU,MAAA;EAuMqC;;;;;;EA/L/C,QAAA,CAAS,MAAA;EA2MwE;;;;;;EAnMjF,QAAA,IAAY,MAAA;EA2NZ;;;;;;;;;;EA3MA,OAAA,CAAQ,KAAA,UAAe,SAAA;;;;;;;;;;EAWvB,MAAA,CAAO,OAAA,EAAS,MAAA;;;;;;;EAQhB,MAAA,CAAO,KAAA;;;;;;;EAYP,KAAA,CAAM,KAAA;;;;;;;EAQN,MAAA,CAAO,MAAA;;;;;;;EAQP,IAAA,CAAK,KAAA;;;;;;;;;EAcL,YAAA,CAAa,OAAA,EAAS,WAAA,QAAmB,IAAA,OAAW,OAAA,EAAS,aAAA;;;;;;EAW7D,GAAA,IAAO,OAAA,CAAQ,CAAA;;;;;;EAOf,KAAA,IAAS,OAAA,CAAQ,CAAA;;;;;;EAOjB,KAAA,IAAS,OAAA;;;;;;;;;;EAWT,GAAA,CAAI,KAAA,WAAgB,OAAA;;;;;;;;;;EAWpB,GAAA,CAAI,KAAA,WAAgB,OAAA;;;;;;;EAQpB,GAAA,CAAI,KAAA,WAAgB,OAAA;;;;;;;EAQpB,GAAA,CAAI,KAAA,WAAgB,OAAA;;;;;;;;;;;;;;;EAgBpB,OAAA,KAAY,MAAA,mBACV,MAAA,EAAQ,aAAA,EACR,UAAA,EAAY,oBAAA,GACX,OAAA,CAAQ,CAAA;;;;;;;;;;;;;;EAeX,SAAA,KAAc,MAAA,mBAAyB,UAAA,EAAY,oBAAA,GAAuB,OAAA,CAAQ,CAAA;;;;;;;;EASlF,QAAA,CAAS,IAAA,UAAc,KAAA,WAAgB,OAAA,CAAQ,gBAAA,CAAiB,CAAA;;;;;;;;;;;EAYhE,cAAA,CAAe,OAAA,EAAS,uBAAA,GAA0B,OAAA,CAAQ,sBAAA,CAAuB,CAAA;;;;;;;;EASjF,KAAA,CAAM,IAAA,UAAc,QAAA,EAAU,aAAA,CAAc,CAAA,IAAK,OAAA;;;;;;;;;;EAejD,IAAA,EAAM,QAAA;;;;;;;;;;EAWN,QAAA,KAAa,SAAA;;;;;;EAOb,KAAA;;;;;;;;;;;;;;;;;;;;;EAsBA,SAAA,CAAU,MAAA,UAAgB,SAAA,YAAqB,KAAA;AAAA"}

package/esm/repositories/index.d.mts

@@ -1,6 +1,6 @@
 import { RepositoryManager } from "./repository.manager.mjs";
 import { RepositoryAdapterContract } from "./contracts/repository-adapter.contract.mjs";
 import { AllRepositoryOptions, CachedRepositoryOptions, ChunkCallback, CursorPaginationOptions, CursorPaginationResult, FilterFunction, FilterOperator, FilterOptions, FilterRule, FilterRules, PaginationMode, PaginationResult, RepositoryConfigurations, RepositoryEvent, RepositoryOptions, RepositoryOptionsWithCursor, RepositoryOptionsWithPages, SaveMode, TypedAllRepositoryOptions, TypedRepositoryOptions, TypedRepositoryOptionsWithCursor, TypedRepositoryOptionsWithPages, WhereOperator } from "./contracts/types.mjs";
-import { QueryBuilderContract } from "./contracts/query-builder.contract.mjs";
+import { AggregateExpressionInput, AggregateExpressions, GroupByFields, QueryBuilderContract } from "./contracts/query-builder.contract.mjs";
 import { CascadeAdapter } from "./adapters/cascade/cascade-adapter.mjs";
 import { CascadeQueryBuilder } from "./adapters/cascade/cascade-query-builder.mjs";

package/esm/repositories/repository.manager.d.mts

@@ -1,6 +1,6 @@
 import { RepositoryAdapterContract } from "./contracts/repository-adapter.contract.mjs";
 import { AllRepositoryOptions, ChunkCallback, CursorPaginationResult, FilterRules, PaginationResult, RepositoryOptions, SaveMode, TypedAllRepositoryOptions, TypedRepositoryOptions, TypedRepositoryOptionsWithCursor, TypedRepositoryOptionsWithPages } from "./contracts/types.mjs";
-import { QueryBuilderContract } from "./contracts/query-builder.contract.mjs";
+import { AggregateExpressions, GroupByFields, QueryBuilderContract } from "./contracts/query-builder.contract.mjs";
 import { CacheDriver, CacheKey } from "@warlock.js/cache";
 
 //#region ../@warlock.js/core/src/repositories/repository.manager.d.ts
@@ -555,6 +555,104 @@ declare class RepositoryManager<T = unknown, F = Record<string, any>> {
    * @public
    */
   countActiveCached(options?: TypedRepositoryOptions<F>): Promise<number>;
+  /**
+   * Sum a numeric field across records matching options.
+   *
+   * Applies `filterBy` (and its operator-injection guard), `where`, scopes and
+   * every other repository option to the query FIRST — exactly like `count()` —
+   * THEN runs the aggregate, so the sum is always scoped by the same filters
+   * the rest of the repository honors.
+   *
+   * @param field - Numeric field to sum
+   * @param options - Repository options (filter values, perform, etc.)
+   * @returns Promise resolving to the filtered numeric sum
+   * @public
+   *
+   * @example
+   * await ordersRepository.sum("total", { status: "paid" });
+   */
+  sum(field: string, options?: TypedRepositoryOptions<F>): Promise<number>;
+  /**
+   * Average a numeric field across records matching options.
+   *
+   * Options (including `filterBy`) are applied before the aggregate, mirroring
+   * `count()`.
+   *
+   * @param field - Numeric field to average
+   * @param options - Repository options
+   * @returns Promise resolving to the filtered numeric average
+   * @public
+   */
+  avg(field: string, options?: TypedRepositoryOptions<F>): Promise<number>;
+  /**
+   * Minimum value of a field across records matching options.
+   *
+   * Options (including `filterBy`) are applied before the aggregate, mirroring
+   * `count()`.
+   *
+   * @param field - Field name
+   * @param options - Repository options
+   * @returns Promise resolving to the filtered minimum value
+   * @public
+   */
+  min(field: string, options?: TypedRepositoryOptions<F>): Promise<number>;
+  /**
+   * Maximum value of a field across records matching options.
+   *
+   * Options (including `filterBy`) are applied before the aggregate, mirroring
+   * `count()`.
+   *
+   * @param field - Field name
+   * @param options - Repository options
+   * @returns Promise resolving to the filtered maximum value
+   * @public
+   */
+  max(field: string, options?: TypedRepositoryOptions<F>): Promise<number>;
+  /**
+   * Group records by one or more fields and compute aggregates.
+   *
+   * Repository options (including `filterBy`) are applied before the grouping,
+   * mirroring `count()`, so the grouped rows are always scoped by the same
+   * filters the rest of the repository honors.
+   *
+   * @template R - Shape of each grouped row
+   * @param fields - Field(s) to group by
+   * @param aggregates - Map of result aliases to aggregate expressions (e.g. `$agg.*`)
+   * @param options - Repository options
+   * @returns Promise resolving to the array of grouped rows
+   * @public
+   *
+   * @example
+   * import { $agg } from "@warlock.js/cascade";
+   *
+   * await ordersRepository.groupBy(
+   *   "status",
+   *   { count: $agg.count(), total: $agg.sum("total") },
+   *   { paidAfter: "2026-01-01" },
+   * );
+   */
+  groupBy<R = Record<string, unknown>>(fields: GroupByFields, aggregates: AggregateExpressions, options?: TypedRepositoryOptions<F>): Promise<R[]>;
+  /**
+   * Compute aggregates over the whole matching set as a single summary row.
+   *
+   * Repository options (including `filterBy`) are applied before the aggregate,
+   * mirroring `count()`.
+   *
+   * @template R - Shape of the summary row
+   * @param aggregates - Map of result aliases to aggregate expressions (e.g. `$agg.*`)
+   * @param options - Repository options
+   * @returns Promise resolving to the single summary row (or `null` when empty)
+   * @public
+   *
+   * @example
+   * import { $agg } from "@warlock.js/cascade";
+   *
+   * await ordersRepository.aggregate(
+   *   { total: $agg.sum("total"), avg: $agg.avg("total") },
+   *   { status: "paid" },
+   * );
+   */
+  aggregate<R = Record<string, unknown>>(aggregates: AggregateExpressions, options?: TypedRepositoryOptions<F>): Promise<R | null>;
   /**
    * Set cache driver
    * @param driver - Cache driver instance

package/esm/repositories/repository.manager.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.manager.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/repositories/repository.manager.ts"],"mappings":"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"}
+{"version":3,"file":"repository.manager.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/repositories/repository.manager.ts"],"mappings":"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"}

package/esm/repositories/repository.manager.mjs

@@ -707,6 +707,134 @@ var RepositoryManager = class {
 		}));
 	}
 	/**
+	* Sum a numeric field across records matching options.
+	*
+	* Applies `filterBy` (and its operator-injection guard), `where`, scopes and
+	* every other repository option to the query FIRST — exactly like `count()` —
+	* THEN runs the aggregate, so the sum is always scoped by the same filters
+	* the rest of the repository honors.
+	*
+	* @param field - Numeric field to sum
+	* @param options - Repository options (filter values, perform, etc.)
+	* @returns Promise resolving to the filtered numeric sum
+	* @public
+	*
+	* @example
+	* await ordersRepository.sum("total", { status: "paid" });
+	*/
+	async sum(field, options) {
+		const query = this.newQuery();
+		const opts = this.prepareOptions(options);
+		this.applyOptionsToQuery(query, opts);
+		return await query.sum(field);
+	}
+	/**
+	* Average a numeric field across records matching options.
+	*
+	* Options (including `filterBy`) are applied before the aggregate, mirroring
+	* `count()`.
+	*
+	* @param field - Numeric field to average
+	* @param options - Repository options
+	* @returns Promise resolving to the filtered numeric average
+	* @public
+	*/
+	async avg(field, options) {
+		const query = this.newQuery();
+		const opts = this.prepareOptions(options);
+		this.applyOptionsToQuery(query, opts);
+		return await query.avg(field);
+	}
+	/**
+	* Minimum value of a field across records matching options.
+	*
+	* Options (including `filterBy`) are applied before the aggregate, mirroring
+	* `count()`.
+	*
+	* @param field - Field name
+	* @param options - Repository options
+	* @returns Promise resolving to the filtered minimum value
+	* @public
+	*/
+	async min(field, options) {
+		const query = this.newQuery();
+		const opts = this.prepareOptions(options);
+		this.applyOptionsToQuery(query, opts);
+		return await query.min(field);
+	}
+	/**
+	* Maximum value of a field across records matching options.
+	*
+	* Options (including `filterBy`) are applied before the aggregate, mirroring
+	* `count()`.
+	*
+	* @param field - Field name
+	* @param options - Repository options
+	* @returns Promise resolving to the filtered maximum value
+	* @public
+	*/
+	async max(field, options) {
+		const query = this.newQuery();
+		const opts = this.prepareOptions(options);
+		this.applyOptionsToQuery(query, opts);
+		return await query.max(field);
+	}
+	/**
+	* Group records by one or more fields and compute aggregates.
+	*
+	* Repository options (including `filterBy`) are applied before the grouping,
+	* mirroring `count()`, so the grouped rows are always scoped by the same
+	* filters the rest of the repository honors.
+	*
+	* @template R - Shape of each grouped row
+	* @param fields - Field(s) to group by
+	* @param aggregates - Map of result aliases to aggregate expressions (e.g. `$agg.*`)
+	* @param options - Repository options
+	* @returns Promise resolving to the array of grouped rows
+	* @public
+	*
+	* @example
+	* import { $agg } from "@warlock.js/cascade";
+	*
+	* await ordersRepository.groupBy(
+	*   "status",
+	*   { count: $agg.count(), total: $agg.sum("total") },
+	*   { paidAfter: "2026-01-01" },
+	* );
+	*/
+	async groupBy(fields, aggregates, options) {
+		const query = this.newQuery();
+		const opts = this.prepareOptions(options);
+		this.applyOptionsToQuery(query, opts);
+		return await query.groupBy(fields, aggregates);
+	}
+	/**
+	* Compute aggregates over the whole matching set as a single summary row.
+	*
+	* Repository options (including `filterBy`) are applied before the aggregate,
+	* mirroring `count()`.
+	*
+	* @template R - Shape of the summary row
+	* @param aggregates - Map of result aliases to aggregate expressions (e.g. `$agg.*`)
+	* @param options - Repository options
+	* @returns Promise resolving to the single summary row (or `null` when empty)
+	* @public
+	*
+	* @example
+	* import { $agg } from "@warlock.js/cascade";
+	*
+	* await ordersRepository.aggregate(
+	*   { total: $agg.sum("total"), avg: $agg.avg("total") },
+	*   { status: "paid" },
+	* );
+	*/
+	async aggregate(aggregates, options) {
+		const query = this.newQuery();
+		const opts = this.prepareOptions(options);
+		this.applyOptionsToQuery(query, opts);
+		return await query.aggregate(aggregates);
+	}
+	/**
 	* Set cache driver
 	* @param driver - Cache driver instance
 	* @returns This repository for chaining