@travetto/model-query 8.0.3 → 8.0.4

package/README.md

@@ -35,7 +35,13 @@ export interface ModelQuerySupport {
    * @param query The query to search for
    * @param failOnMany Should the query fail on more than one result found, defaults to true
    */
-  queryOne<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>, failOnMany?: boolean): Promise<T>;
+  getByQuery<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>, failOnMany?: boolean): Promise<T>;
+  /**
+   * Find the count of matching documents by query.
+   * @param cls The model class
+   * @param query The query to count for
+   */
+  countByQuery<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>): Promise<number>;
 }
 ```
 
@@ -122,35 +128,24 @@ export interface ModelQuerySuggestSupport extends ModelQuerySupport {
 ```
 
 ### Aggregate
-This contract provides the ability to run strongly-typed field-level aggregations (such as sum, avg, min, and max) on models with optional query filtering.
+This contract provides the ability to run strongly-typed field-level statistics (such as min, max, count, avg, and sum) on models with optional query filtering.
 
 **Code: Query Aggregate**
 ```typescript
 export interface ModelQueryAggregateSupport extends ModelQuerySupport {
   /**
-   * Run an aggregation on a field
+   * Run an aggregation on a comparable field.
+   * For numeric fields (number/bigint), returns count, min, max, avg, and sum.
+   * For date fields, returns count, min, and max.
    * @param modelClass The model class to aggregate
-   * @param operation The operation to perform ('sum', 'avg', 'min', 'max')
    * @param field The field to aggregate on
    * @param query Additional query filtering
    */
-  aggregateFieldByQuery<
-    T extends ModelType,
-    Op extends AggregateOperation,
-    F extends (Op extends AggregateNumericOperation ? ValidNumericFields<T> : ValidComparableFields<T>)
-  >(
+  aggregateFieldByQuery<T extends ModelType, F extends ValidComparableFields<T>>(
     modelClass: Class<T>,
-    operation: Op,
     field: F,
     query?: ModelQuery<T>
-  ): Promise<AggregateResultType<T, F>>;
-
-  /**
-   * Find the count of matching documents by query.
-   * @param cls The model class
-   * @param query The query to count for
-   */
-  countByQuery<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>): Promise<number>;
+  ): Promise<FieldAggregateResult<T, F>>;
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/model-query",
-  "version": "8.0.3",
+  "version": "8.0.4",
   "description": "Datastore abstraction for advanced query support.",
   "keywords": [
     "datastore",

package/src/types/aggregate.ts

@@ -2,13 +2,9 @@ import type { ModelType } from '@travetto/model';
 import type { Class } from '@travetto/runtime';
 
 import type { ModelQuery } from '../model/query.ts';
-import type { ValidComparableFields, ValidNumericFields } from '../model/where-clause.ts';
+import type { ValidComparableFields } from '../model/where-clause.ts';
 import type { ModelQuerySupport } from './query.ts';
 
-export type AggregateNumericOperation = 'sum' | 'avg';
-export type AggregateComparableOperation = 'min' | 'max';
-export type AggregateOperation = AggregateNumericOperation | AggregateComparableOperation;
-
 export type PathType<T, Path extends string> = Path extends `${infer Head}.${infer Tail}`
   ? Head extends keyof T
     ? PathType<NonNullable<T[Head]> extends (infer Element)[] ? Element : NonNullable<T[Head]>, Tail>
@@ -23,33 +19,39 @@ export type AggregateResultType<T, F extends string> = [PathType<T, F>] extends
   ? number | Date | bigint | undefined
   : PathType<T, F> | undefined;
 
+export type DateFieldAggregateResult = {
+  count: number;
+  min?: Date;
+  max?: Date;
+};
+
+export type NumericFieldAggregateResult<T, F extends string> = {
+  count: number;
+  min?: AggregateResultType<T, F>;
+  max?: AggregateResultType<T, F>;
+  avg?: AggregateResultType<T, F>;
+  sum?: AggregateResultType<T, F>;
+};
+
+export type FieldAggregateResult<T, F extends string> =
+  NonNullable<PathType<T, F>> extends Date ? DateFieldAggregateResult : NumericFieldAggregateResult<T, F>;
+
 /**
  * The contract for a model service with aggregate support
  * @concrete
  */
 export interface ModelQueryAggregateSupport extends ModelQuerySupport {
   /**
-   * Run an aggregation on a field
+   * Run an aggregation on a comparable field.
+   * For numeric fields (number/bigint), returns count, min, max, avg, and sum.
+   * For date fields, returns count, min, and max.
    * @param modelClass The model class to aggregate
-   * @param operation The operation to perform ('sum', 'avg', 'min', 'max')
    * @param field The field to aggregate on
    * @param query Additional query filtering
    */
-  aggregateFieldByQuery<
-    T extends ModelType,
-    Op extends AggregateOperation,
-    F extends (Op extends AggregateNumericOperation ? ValidNumericFields<T> : ValidComparableFields<T>)
-  >(
+  aggregateFieldByQuery<T extends ModelType, F extends ValidComparableFields<T>>(
     modelClass: Class<T>,
-    operation: Op,
     field: F,
     query?: ModelQuery<T>
-  ): Promise<AggregateResultType<T, F>>;
-
-  /**
-   * Find the count of matching documents by query.
-   * @param cls The model class
-   * @param query The query to count for
-   */
-  countByQuery<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>): Promise<number>;
+  ): Promise<FieldAggregateResult<T, F>>;
 }

package/src/types/query.ts

@@ -20,5 +20,11 @@ export interface ModelQuerySupport {
    * @param query The query to search for
    * @param failOnMany Should the query fail on more than one result found, defaults to true
    */
-  queryOne<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>, failOnMany?: boolean): Promise<T>;
+  getByQuery<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>, failOnMany?: boolean): Promise<T>;
+  /**
+   * Find the count of matching documents by query.
+   * @param cls The model class
+   * @param query The query to count for
+   */
+  countByQuery<T extends ModelType>(cls: Class<T>, query: ModelQuery<T>): Promise<number>;
 }

package/src/util/aggregate.ts

@@ -2,7 +2,8 @@ import type { ModelType } from '@travetto/model';
 import { castTo, type Class, hasFunction } from '@travetto/runtime';
 import { DataUtil, SchemaRegistryIndex } from '@travetto/schema';
 
-import type { AggregateOperation, AggregateResultType, ModelQueryAggregateSupport } from '../types/aggregate.ts';
+import type { ValidComparableFields } from '../model/where-clause.ts';
+import type { AggregateResultType, FieldAggregateResult, ModelQueryAggregateSupport } from '../types/aggregate.ts';
 
 export class ModelQueryAggregateUtil {
   /**
@@ -11,19 +12,37 @@ export class ModelQueryAggregateUtil {
   static isSupported = hasFunction<ModelQueryAggregateSupport>('aggregateFieldByQuery');
 
   /**
-   * Resolve and coerce the aggregate query result using DataUtil.coerceType
+   * Resolve and coerce aggregate query results
    * @param modelClass The model class being queried
-   * @param operation The aggregate operation
    * @param field The field being aggregated
-   * @param rawValue The raw result value from the datastore
+   * @param rawValues The raw result values from the datastore
    */
-  static resolveResult<T extends ModelType, Op extends AggregateOperation, F extends string>(
+  static resolveAggregate<T extends ModelType, F extends ValidComparableFields<T>>(
     modelClass: Class<T>,
-    operation: Op,
     field: F,
-    rawValue: unknown
-  ): AggregateResultType<T, F> {
+    rawValues: { count?: unknown; min?: unknown; max?: unknown; avg?: unknown; sum?: unknown }
+  ): FieldAggregateResult<T, F> {
+    const count = Number(rawValues.count ?? 0);
+    if (count === 0) {
+      return castTo({ count: 0 });
+    }
     const leafFieldType = SchemaRegistryIndex.getNestedFieldConfig(modelClass, field)!.type;
-    return castTo(DataUtil.coerceType(rawValue, leafFieldType, false) ?? undefined);
+    const coerce = (value: unknown): AggregateResultType<T, F> => castTo(DataUtil.coerceType(value, leafFieldType, false) ?? undefined);
+
+    if (leafFieldType === Date) {
+      return castTo({
+        count,
+        min: coerce(rawValues.min),
+        max: coerce(rawValues.max)
+      });
+    }
+
+    return castTo({
+      count,
+      min: coerce(rawValues.min),
+      max: coerce(rawValues.max),
+      avg: coerce(rawValues.avg),
+      sum: coerce(rawValues.sum)
+    });
   }
 }

package/support/test/aggregate.ts

@@ -10,8 +10,30 @@ import { Aged, BigIntModel, Person } from './model.ts';
 
 @Suite()
 export abstract class ModelQueryAggregateSuite extends BaseModelSuite<ModelQueryAggregateSupport & ModelCrudSupport> {
-  @Test('verify basic aggregations')
-  async testAggregate() {
+  @Test('verify date field aggregate')
+  async testDateFieldAggregate() {
+    const service = await this.service;
+
+    const firstDate = new Date(2020, 0, 1);
+    const secondDate = new Date(2021, 0, 1);
+    const thirdDate = new Date(2022, 0, 1);
+
+    await this.saveAll(Aged, [
+      Aged.from({ createdAt: firstDate }),
+      Aged.from({ createdAt: secondDate }),
+      Aged.from({ createdAt: thirdDate })
+    ]);
+
+    const aggregate = await service.aggregateFieldByQuery(Aged, 'createdAt');
+    assert(aggregate.count === 3);
+    assert(aggregate.min instanceof Date);
+    assert(aggregate.min.getTime() === firstDate.getTime());
+    assert(aggregate.max instanceof Date);
+    assert(aggregate.max.getTime() === thirdDate.getTime());
+  }
+
+  @Test('verify field aggregate')
+  async testFieldAggregate() {
     const people = [
       Person.from({ name: 'Bob', age: 20, gender: 'm', address: { street1: '1st St' } }),
       Person.from({ name: 'Alice', age: 30, gender: 'f', address: { street1: '2nd St' } }),
@@ -23,67 +45,38 @@ export abstract class ModelQueryAggregateSuite extends BaseModelSuite<ModelQuery
     const saved = await this.saveAll(Person, people);
     assert(saved === 4);
 
-    const sumResult = await service.aggregateFieldByQuery(Person, 'sum', 'age');
-    assert(sumResult === 140);
-
-    const averageResult = await service.aggregateFieldByQuery(Person, 'avg', 'age');
-    assert(averageResult === 35);
+    const aggregate = await service.aggregateFieldByQuery(Person, 'age');
+    assert(aggregate.count === 4);
+    assert(aggregate.min === 20);
+    assert(aggregate.max === 50);
+    assert(aggregate.avg === 35);
+    assert(aggregate.sum === 140);
 
-    const minimumResult = await service.aggregateFieldByQuery(Person, 'min', 'age');
-    assert(minimumResult === 20);
-
-    const maximumResult = await service.aggregateFieldByQuery(Person, 'max', 'age');
-    assert(maximumResult === 50);
-
-    // Filtered aggregations
-    const filteredSumResult = await service.aggregateFieldByQuery(Person, 'sum', 'age', {
+    const filteredAggregate = await service.aggregateFieldByQuery(Person, 'age', {
       where: {
         age: { $gte: 30 }
       }
     });
-    assert(filteredSumResult === 120);
+    assert(filteredAggregate.count === 3);
+    assert(filteredAggregate.min === 30);
+    assert(filteredAggregate.max === 50);
+    assert(filteredAggregate.avg === 40);
+    assert(filteredAggregate.sum === 120);
 
-    const filteredAverageResult = await service.aggregateFieldByQuery(Person, 'avg', 'age', {
-      where: {
-        gender: 'f'
-      }
-    });
-    assert(filteredAverageResult === 40);
-
-    // No matches
-    const noMatchResult = await service.aggregateFieldByQuery(Person, 'sum', 'age', {
+    const emptyAggregate = await service.aggregateFieldByQuery(Person, 'age', {
       where: {
         age: { $gt: 1000 }
       }
     });
-    assert(noMatchResult === undefined);
+    assert(emptyAggregate.count === 0);
+    assert(emptyAggregate.min === undefined);
+    assert(emptyAggregate.max === undefined);
+    assert(emptyAggregate.avg === undefined);
+    assert(emptyAggregate.sum === undefined);
   }
 
-  @Test('verify date aggregations')
-  async testDateAggregate() {
-    const service = await this.service;
-
-    const firstDate = new Date(2020, 0, 1);
-    const secondDate = new Date(2021, 0, 1);
-    const thirdDate = new Date(2022, 0, 1);
-
-    await this.saveAll(Aged, [
-      Aged.from({ createdAt: firstDate }),
-      Aged.from({ createdAt: secondDate }),
-      Aged.from({ createdAt: thirdDate })
-    ]);
-
-    const minimumDateResult = await service.aggregateFieldByQuery(Aged, 'min', 'createdAt');
-    assert(minimumDateResult instanceof Date);
-    assert(minimumDateResult.getTime() === firstDate.getTime());
-
-    const maximumDateResult = await service.aggregateFieldByQuery(Aged, 'max', 'createdAt');
-    assert(maximumDateResult instanceof Date);
-    assert(maximumDateResult.getTime() === thirdDate.getTime());
-  }
-
-  @Test('verify bigint aggregations')
-  async testBigIntAggregate() {
+  @Test('verify bigint field aggregate')
+  async testBigIntFieldAggregate() {
     const service = await this.service;
 
     await this.saveAll(BigIntModel, [
@@ -92,16 +85,11 @@ export abstract class ModelQueryAggregateSuite extends BaseModelSuite<ModelQuery
       BigIntModel.from({ largeNumber: 300n })
     ]);
 
-    const sumResult = await service.aggregateFieldByQuery(BigIntModel, 'sum', 'largeNumber');
-    assert(sumResult === 600n);
-
-    const minimumResult = await service.aggregateFieldByQuery(BigIntModel, 'min', 'largeNumber');
-    assert(minimumResult === 100n);
-
-    const maximumResult = await service.aggregateFieldByQuery(BigIntModel, 'max', 'largeNumber');
-    assert(maximumResult === 300n);
-
-    const averageResult = await service.aggregateFieldByQuery(BigIntModel, 'avg', 'largeNumber');
-    assert(averageResult === 200n);
+    const aggregate = await service.aggregateFieldByQuery(BigIntModel, 'largeNumber');
+    assert(aggregate.count === 3);
+    assert(aggregate.min === 100n);
+    assert(aggregate.max === 300n);
+    assert(aggregate.avg === 200n);
+    assert(aggregate.sum === 600n);
   }
 }

package/support/test/polymorphism.ts

@@ -18,9 +18,7 @@ import { ModelQueryFacetUtil } from '../../src/util/facet.ts';
 import { ModelQuerySuggestUtil } from '../../src/util/suggest.ts';
 
 @Suite()
-export abstract class ModelQueryPolymorphismSuite extends BaseModelSuite<
-  ModelQuerySupport & ModelQueryAggregateSupport & ModelCrudSupport
-> {
+export abstract class ModelQueryPolymorphismSuite extends BaseModelSuite<ModelQuerySupport & ModelCrudSupport> {
   @Test()
   async testQuery() {
     const svc = await this.service;
@@ -42,13 +40,13 @@ export abstract class ModelQueryPolymorphismSuite extends BaseModelSuite<
     assert((await svc.countByQuery(Doctor, { where: { name: 'bob' } })) === 1);
     assert((await svc.countByQuery(Engineer, { where: { name: 'bob' } })) === 0);
 
-    assert((await svc.queryOne(Worker, { where: { name: 'bob' } })) instanceof Doctor);
-    await assert.rejects(() => svc.queryOne(Firefighter, { where: { name: 'bob' } }), NotFoundError);
+    assert((await svc.getByQuery(Worker, { where: { name: 'bob' } })) instanceof Doctor);
+    await assert.rejects(() => svc.getByQuery(Firefighter, { where: { name: 'bob' } }), NotFoundError);
   }
 
   @Test({ skip: ModelQueryPolymorphismSuite.ifNot(ModelQueryCrudUtil.isSupported) })
   async testCrudQuery() {
-    const svc: ModelQueryCrudSupport & ModelQueryAggregateSupport & ModelQuerySupport = castTo(await this.service);
+    const svc: ModelQueryCrudSupport & ModelQuerySupport = castTo(await this.service);
     const [doc, doc2, fire, eng] = [
       Doctor.from({ name: 'bob', specialty: 'feet' }),
       Doctor.from({ name: 'nob', specialty: 'eyes' }),
@@ -127,10 +125,11 @@ export abstract class ModelQueryPolymorphismSuite extends BaseModelSuite<
     await this.saveAll(Worker, [doctorOne, doctorTwo, firefighterOne, firefighterTwo]);
     assert((await this.getSize(Worker)) === 4);
 
-    const sumFirehouse = await service.aggregateFieldByQuery(Firefighter, 'sum', 'firehouse');
-    assert(sumFirehouse === 50);
-
-    const averageFirehouse = await service.aggregateFieldByQuery(Firefighter, 'avg', 'firehouse');
-    assert(averageFirehouse === 25);
+    const aggregate = await service.aggregateFieldByQuery(Firefighter, 'firehouse');
+    assert(aggregate.count === 2);
+    assert(aggregate.min === 20);
+    assert(aggregate.max === 30);
+    assert(aggregate.avg === 25);
+    assert(aggregate.sum === 50);
   }
 }

package/support/test/query.ts

@@ -6,12 +6,11 @@ import { Suite, Test } from '@travetto/test';
 
 import { BaseModelSuite } from '@travetto/model/support/test/base.ts';
 
-import type { ModelQueryAggregateSupport } from '../../__index__.ts';
 import type { ModelQuerySupport } from '../../src/types/query.ts';
 import { Aged, Location, Names, Note, Person, PersonFamily, Recipe, SimpleList, WithNestedLists, WithNestedNestedLists } from './model.ts';
 
 @Suite()
-export abstract class ModelQuerySuite extends BaseModelSuite<ModelQuerySupport & ModelQueryAggregateSupport & ModelCrudSupport> {
+export abstract class ModelQuerySuite extends BaseModelSuite<ModelQuerySupport & ModelCrudSupport> {
   supportsGeo = true;
 
   @Test()
@@ -33,10 +32,10 @@ export abstract class ModelQuerySuite extends BaseModelSuite<ModelQuerySupport &
 
     await this.saveAll(Person, people);
 
-    const one = await svc.queryOne(Person, { where: { id: people[0].id } });
+    const one = await svc.getByQuery(Person, { where: { id: people[0].id } });
     assert(one.id === people[0].id);
 
-    const one2 = await svc.queryOne(Person, { where: { id: { $eq: people[0].id } } });
+    const one2 = await svc.getByQuery(Person, { where: { id: { $eq: people[0].id } } });
     assert(one2.id === people[0].id);
 
     const none = await svc.countByQuery(Person, { where: { id: { $ne: people[0].id } } });
@@ -92,11 +91,11 @@ export abstract class ModelQuerySuite extends BaseModelSuite<ModelQuerySupport &
       )
     );
 
-    await assert.rejects(() => service.queryOne(Person, { where: { gender: 'm' } }), /Invalid number of results/);
-    await assert.rejects(() => service.queryOne(Person, { where: { gender: 'z' } }), NotFoundError);
-    await assert.rejects(() => service.queryOne(Person, { where: { gender: 'z' } }), /No results found for query/);
-    await assert.rejects(() => service.queryOne(Person, { where: { id: 'orange' } }), NotFoundError);
-    await assert.rejects(() => service.queryOne(Person, { where: { id: 'orange' } }), /orange/);
+    await assert.rejects(() => service.getByQuery(Person, { where: { gender: 'm' } }), /Invalid number of results/);
+    await assert.rejects(() => service.getByQuery(Person, { where: { gender: 'z' } }), NotFoundError);
+    await assert.rejects(() => service.getByQuery(Person, { where: { gender: 'z' } }), /No results found for query/);
+    await assert.rejects(() => service.getByQuery(Person, { where: { id: 'orange' } }), NotFoundError);
+    await assert.rejects(() => service.getByQuery(Person, { where: { id: 'orange' } }), /orange/);
   }
 
   @Test('Verify array $in queries work properly')