@bluecopa/core 0.1.58 → 0.1.59

package/dist/input-table-db/aggregateUtils.d.ts

@@ -0,0 +1,78 @@
+import { WhereOp, AggregateSpec, AggregateResult, Row } from './types';
+export type WhereClause = {
+    field: string;
+    op: WhereOp;
+    value: unknown;
+};
+/**
+ * Validates an aggregate spec — function names must be in the allowed set,
+ * column names must pass validateIdentifier (safe for URL params).
+ */
+export declare function validateAggregateSpec<TRow extends Row>(spec: AggregateSpec<TRow>): void;
+/**
+ * Validates groupBy columns — each name must pass validateIdentifier() and must not
+ * overlap with aggregate spec keys (which would create a key collision in the result).
+ */
+export declare function validateGroupBySpec<TRow extends Row>(groupBy: (keyof TRow & string)[], spec: AggregateSpec<TRow>): void;
+/**
+ * Builds the PostgREST `select` query param string from an AggregateSpec.
+ *
+ * For spec `{ amount: ['sum', 'avg'], _count: true }` produces:
+ *   `amount_sum:amount.sum(),amount_avg:amount.avg(),count()`
+ *
+ * When groupBy columns are provided, they are prepended as bare column names,
+ * which causes PostgREST to automatically group by those columns:
+ *   `order_date,status,amount_sum:amount.sum(),count()`
+ *
+ * Aliases prevent collisions when multiple columns use the same function.
+ */
+export declare function buildAggregateSelect<TRow extends Row>(spec: AggregateSpec<TRow>, groupBy?: (keyof TRow & string)[]): string;
+/**
+ * Builds the PostgREST `order` query param string from an array of order clauses.
+ *
+ * For `[{ field: 'order_date', direction: 'asc' }, { field: 'status', direction: 'desc' }]`
+ * produces: `order_date.asc,status.desc`
+ */
+export declare function buildPostgrestOrder(orders: {
+    field: string;
+    direction: 'asc' | 'desc';
+}[]): string;
+/**
+ * Builds PostgREST filter query params from a WhereClause array.
+ *
+ * For `[{ field: 'status', op: '==', value: 'active' }]` produces:
+ *   `{ status: 'eq.active' }`
+ *
+ * The `in`/`not-in` operators wrap array values in parentheses:
+ *   `{ status: 'in.(a,b,c)' }`
+ *
+ * Field names are validated via validateIdentifier and checked against
+ * PostgREST reserved param names to prevent query param injection.
+ *
+ * Values containing PostgREST reserved characters (`,` `.` `:` `(` `)`)
+ * are wrapped in double quotes per PostgREST escaping rules.
+ *
+ * Multiple filters on the same field (e.g., range queries) are preserved as
+ * an array, which Axios serializes as repeated query params:
+ *   `amount=gt.10&amount=lt.100` — PostgREST ANDs them automatically.
+ */
+export declare function buildPostgrestFilters(wheres: WhereClause[]): Record<string, string | string[]>;
+/**
+ * Maps a flat PostgREST aggregate response back to the nested AggregateResult shape.
+ *
+ * Given spec `{ amount: ['sum', 'avg'], _count: true }` and flat row:
+ *   `{ amount_sum: 1234, amount_avg: 123, count: 50 }`
+ * Returns:
+ *   `{ amount: { sum: 1234, avg: 123 }, _count: 50 }`
+ */
+export declare function parseAggregateResponse<TSpec extends AggregateSpec>(spec: TSpec, data: Record<string, number | null>[]): AggregateResult<TSpec>;
+/**
+ * Maps a flat PostgREST grouped aggregate response to an array of nested result objects.
+ *
+ * For each row in data, includes the groupBy column values directly plus nested aggregate values.
+ * Given spec `{ amount: ['sum'] }`, groupBy `['status']`, and data:
+ *   `[{ status: 'active', amount_sum: 500 }, { status: 'draft', amount_sum: 100 }]`
+ * Returns:
+ *   `[{ status: 'active', amount: { sum: 500 } }, { status: 'draft', amount: { sum: 100 } }]`
+ */
+export declare function parseGroupedAggregateResponse<TSpec extends AggregateSpec>(spec: TSpec, groupBy: string[], data: Record<string, unknown>[]): Record<string, unknown>[];

package/dist/input-table-db/collectionRef.d.ts

@@ -1,8 +1,9 @@
 import { RxCollection } from 'rxdb';
 import { RxReplicationState } from 'rxdb/plugins/replication';
 import { IWebsocketProvider } from '../config';
-import { Row, WhereOp, CollectionRef, QueryBuilder, InputTableColumn } from './types';
+import { Row, WhereOp, CollectionRef, QueryBuilder, InputTableColumn, AggregateSpec, AggregateResult, GroupedAggregateResult } from './types';
 import { DocRefImpl } from './docRef';
+import { WhereClause } from './aggregateUtils';
 export declare class CollectionRefImpl<TRow extends Row = Row> implements CollectionRef<TRow> {
     private collection;
     private solutionId;
@@ -12,6 +13,7 @@ export declare class CollectionRefImpl<TRow extends Row = Row> implements Collec
     private replicationState;
     private getWebsocketProvider;
     constructor(collection: RxCollection, solutionId: string, tableName: string, primaryKeyField: string, pkColumn: InputTableColumn | undefined, replicationState: RxReplicationState<any, any>, getWebsocketProvider: () => IWebsocketProvider | undefined);
+    private makeQueryBuilder;
     where(field: keyof TRow & string, op: WhereOp, value: unknown): QueryBuilder<TRow>;
     orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
     limit(count: number): QueryBuilder<TRow>;
@@ -21,4 +23,24 @@ export declare class CollectionRefImpl<TRow extends Row = Row> implements Collec
     subscribe(callback: (rows: TRow[]) => void): () => void;
     get(): Promise<TRow[]>;
     count(callback: (count: number) => void): () => void;
+    /**
+     * Compute server-side aggregates via PostgREST. Bypasses local RxDB cache.
+     *
+     * - No `groupBy` → returns a single summary object.
+     * - `groupBy: ['col']` → returns an array of per-group objects, each containing the
+     *   grouped column values plus nested aggregate results. Requires at least one aggregate
+     *   function or `_count: true` in the spec.
+     * - `groupBy: []` (empty array) → treated as non-grouped; returns the single summary shape.
+     */
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec, options: {
+        groupBy: [];
+    }): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>, TKeys extends (keyof TRow & string)[]>(spec: TSpec, options: {
+        groupBy: TKeys;
+    }): Promise<GroupedAggregateResult<TSpec, TRow, TKeys>>;
+    executeAggregate<TSpec extends AggregateSpec<TRow>>(wheres: WhereClause[], orders: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[], limit: number | undefined, skip: number | undefined, spec: TSpec, groupBy?: (keyof TRow & string)[]): Promise<AggregateResult<TSpec> | GroupedAggregateResult<TSpec, TRow, (keyof TRow & string)[]>>;
 }

package/dist/input-table-db/index.d.ts

@@ -1,4 +1,4 @@
 export { copaInputTableDb } from './inputTableDb';
 export { InputTableColumnType } from './types';
 export { InputTableError } from './utils';
-export type { Row, WhereOp, QueryBuilder, DocRef, CollectionRef, InputTableDB, InputTableDefinition, InputTableColumn } from './types';
+export type { Row, WhereOp, QueryBuilder, DocRef, CollectionRef, InputTableDB, InputTableDefinition, InputTableColumn, AggregateFunction, AggregateSpec, AggregateResult, GroupedAggregateResult } from './types';

package/dist/input-table-db/queryBuilder.d.ts

@@ -1,27 +1,32 @@
 import { RxCollection } from 'rxdb';
-import { Row, WhereOp, QueryBuilder } from './types';
-type WhereClause = {
-    field: string;
-    op: WhereOp;
-    value: unknown;
-};
+import { Row, WhereOp, QueryBuilder, AggregateSpec, AggregateResult, GroupedAggregateResult } from './types';
+import { WhereClause } from './aggregateUtils';
 type OrderClause = {
     field: string;
     direction: 'asc' | 'desc';
 };
+type AggregateExecutor<TRow extends Row> = <TSpec extends AggregateSpec<TRow>>(wheres: WhereClause[], orders: OrderClause[], limit: number | undefined, skip: number | undefined, spec: TSpec, groupBy?: (keyof TRow & string)[]) => Promise<AggregateResult<TSpec> | GroupedAggregateResult<TSpec, TRow, (keyof TRow & string)[]>>;
 export declare class QueryBuilderImpl<TRow extends Row = Row> implements QueryBuilder<TRow> {
     private collection;
+    private aggregateExecutor?;
     private wheres;
     private orders;
     private limitCount;
     private skipCount;
-    constructor(collection: RxCollection, initialWhere?: WhereClause, initialOrder?: OrderClause, initialLimit?: number, initialSkip?: number);
+    constructor(collection: RxCollection, initialWhere?: WhereClause, initialOrder?: OrderClause, initialLimit?: number, initialSkip?: number, aggregateExecutor?: AggregateExecutor<TRow>);
     where(field: keyof TRow & string, op: WhereOp, value: unknown): QueryBuilder<TRow>;
     orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
     limit(count: number): QueryBuilder<TRow>;
     skip(count: number): QueryBuilder<TRow>;
     subscribe(callback: (rows: TRow[]) => void): () => void;
     get(): Promise<TRow[]>;
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec, options: {
+        groupBy: [];
+    }): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>, TKeys extends (keyof TRow & string)[]>(spec: TSpec, options: {
+        groupBy: TKeys;
+    }): Promise<GroupedAggregateResult<TSpec, TRow, TKeys>>;
     private buildQuery;
 }
 export {};

package/dist/input-table-db/types.d.ts

@@ -28,6 +28,26 @@ export type InputTableDefinition = {
 export type Row = Record<string, unknown>;
 /** Where clause operators */
 export type WhereOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in';
+/** Supported PostgREST aggregate functions */
+export type AggregateFunction = 'sum' | 'avg' | 'count' | 'min' | 'max';
+/** Aggregate specification — column-to-functions mapping + optional row count */
+export type AggregateSpec<TRow extends Row = Row> = {
+    [K in keyof TRow & string]?: AggregateFunction[];
+} & {
+    _count?: true;
+};
+/** Result shape — nested column.function values + optional row count */
+export type AggregateResult<TSpec> = {
+    [K in keyof TSpec as K extends '_count' ? never : K]: K extends string ? TSpec[K] extends AggregateFunction[] ? {
+        [F in TSpec[K][number]]: number | null;
+    } : never : never;
+} & (TSpec extends {
+    _count: true;
+} ? {
+    _count: number;
+} : object);
+/** Result type for grouped aggregates — array of group rows */
+export type GroupedAggregateResult<TSpec extends AggregateSpec, TRow extends Row, TKeys extends (keyof TRow & string)[]> = (AggregateResult<TSpec> & Pick<TRow, TKeys[number]>)[];
 export interface QueryBuilder<TRow extends Row = Row> {
     where(field: keyof TRow & string, op: WhereOp, value: unknown): QueryBuilder<TRow>;
     orderBy(field: keyof TRow & string, direction?: 'asc' | 'desc'): QueryBuilder<TRow>;
@@ -35,6 +55,13 @@ export interface QueryBuilder<TRow extends Row = Row> {
     skip(count: number): QueryBuilder<TRow>;
     subscribe(callback: (rows: TRow[]) => void): () => void;
     get(): Promise<TRow[]>;
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec, options: {
+        groupBy: [];
+    }): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>, TKeys extends (keyof TRow & string)[]>(spec: TSpec, options: {
+        groupBy: TKeys;
+    }): Promise<GroupedAggregateResult<TSpec, TRow, TKeys>>;
 }
 export interface DocRef<TRow extends Row = Row> {
     get(): Promise<TRow | null>;
@@ -52,6 +79,13 @@ export interface CollectionRef<TRow extends Row = Row> {
     subscribe(callback: (rows: TRow[]) => void): () => void;
     get(): Promise<TRow[]>;
     count(callback: (count: number) => void): () => void;
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>>(spec: TSpec, options: {
+        groupBy: [];
+    }): Promise<AggregateResult<TSpec>>;
+    aggregate<TSpec extends AggregateSpec<TRow>, TKeys extends (keyof TRow & string)[]>(spec: TSpec, options: {
+        groupBy: TKeys;
+    }): Promise<GroupedAggregateResult<TSpec, TRow, TKeys>>;
 }
 export interface InputTableDB {
     collection<TRow extends Row = Row>(name: string): CollectionRef<TRow>;

package/dist/input-table-db/utils.d.ts

@@ -1,6 +1,11 @@
 /**
  * Shared utilities for the input-table-db SDK.
  */
+/**
+ * Builds request headers for solution branch context.
+ * Reads from SDK config first, falls back to cookies (browser only).
+ */
+export declare function getSolutionBranchHeaders(): Record<string, string>;
 export declare class InputTableError extends Error {
     status: number;
     constructor(message: string, status: number);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluecopa/core",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "type": "module",
   "main": "dist/index.es.js",
   "module": "dist/index.es.js",