@travetto/model-query 8.0.0 → 8.0.2

package/README.md

@@ -127,12 +127,38 @@ 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.
+
+**Code: Query Aggregate**
+```typescript
+export interface ModelQueryAggregateSupport extends ModelQuerySupport {
+  /**
+   * Run an aggregation on a field
+   * @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>)
+  >(
+    modelClass: Class<T>,
+    operation: Op,
+    field: F,
+    query?: ModelQuery<T>
+  ): Promise<AggregateResultType<T, F>>;
+}
+```
+
 ## Implementations
-|Service|Query|QueryCrud|QueryFacet|
-|-------|-----|---------|----------|
-|[Elasticsearch Model Source](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch#readme "Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.")|X|X|X|
-|[MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.")|X'|X'|X'|
-|[SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.")|X'|X'|X'|
+|Service|Query|QueryCrud|QueryFacet|QueryAggregate|
+|-------|-----|---------|----------|--------------|
+|[Elasticsearch Model Source](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch#readme "Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.")|X|X|X|X|
+|[MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.")|X'|X'|X'|X'|
+|[SQL Model Service](https://github.com/travetto/travetto/tree/main/module/model-sql#readme "SQL backing for the travetto model module, with real-time modeling support for SQL schemas.")|X'|X'|X'|X'|
 
 ## Querying
 One of the complexities of abstracting multiple storage mechanisms, is providing a consistent query language. The query language the module uses is a derivation of [mongodb](https://mongodb.com)'s query language, with some restrictions, additions, and caveats. Additionally, given the nature of typescript, all queries are statically typed, and will catch type errors at compile time.
@@ -227,9 +253,15 @@ In addition to the provided contracts, the module also provides common utilities
 ```typescript
 import { Config } from '@travetto/config';
 import { Injectable } from '@travetto/di';
-import type { ModelQueryCrudSupport, ModelQueryFacetSupport, ModelQuerySuggestSupport } from '@travetto/model-query';
+import type {
+  ModelQueryAggregateSupport,
+  ModelQueryCrudSupport,
+  ModelQueryFacetSupport,
+  ModelQuerySuggestSupport
+} from '@travetto/model-query';
 import { Suite } from '@travetto/test';
 
+import { ModelQueryAggregateSuite } from '@travetto/model-query/support/test/aggregate.ts';
 import { ModelQueryCrudSuite } from '@travetto/model-query/support/test/crud.ts';
 import { ModelQueryFacetSuite } from '@travetto/model-query/support/test/facet.ts';
 import { ModelQueryPolymorphismSuite } from '@travetto/model-query/support/test/polymorphism.ts';
@@ -242,7 +274,9 @@ import { QueryModelService } from './query-service.ts';
 class CustomModelConfig {}
 
 @Injectable()
-class CustomModelService extends QueryModelService implements ModelQueryCrudSupport, ModelQueryFacetSupport, ModelQuerySuggestSupport {}
+class CustomModelService
+  extends QueryModelService
+  implements ModelQueryAggregateSupport, ModelQueryCrudSupport, ModelQueryFacetSupport, ModelQuerySuggestSupport {}
 
 @Suite()
 class CustomQuerySuite extends ModelQuerySuite {
@@ -250,6 +284,12 @@ class CustomQuerySuite extends ModelQuerySuite {
   configClass = CustomModelConfig;
 }
 
+@Suite()
+class CustomQueryAggregateSuite extends ModelQueryAggregateSuite {
+  serviceClass = CustomModelService;
+  configClass = CustomModelConfig;
+}
+
 @Suite()
 class CustomQueryCrudSuite extends ModelQueryCrudSuite {
   serviceClass = CustomModelService;

package/__index__.ts

@@ -1,10 +1,12 @@
 export * from './src/model/indexes.ts';
 export * from './src/model/query.ts';
 export * from './src/model/where-clause.ts';
+export * from './src/types/aggregate.ts';
 export * from './src/types/crud.ts';
 export * from './src/types/facet.ts';
 export * from './src/types/query.ts';
 export * from './src/types/suggest.ts';
+export * from './src/util/aggregate.ts';
 export * from './src/util/crud.ts';
 export * from './src/util/facet.ts';
 export * from './src/util/query.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/model-query",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "description": "Datastore abstraction for advanced query support.",
   "keywords": [
     "datastore",
@@ -30,12 +30,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@travetto/di": "^8.0.0",
-    "@travetto/model": "^8.0.0",
-    "@travetto/schema": "^8.0.0"
+    "@travetto/di": "^8.0.1",
+    "@travetto/model": "^8.0.2",
+    "@travetto/schema": "^8.0.2"
   },
   "peerDependencies": {
-    "@travetto/test": "^8.0.0"
+    "@travetto/test": "^8.0.1"
   },
   "peerDependenciesMeta": {
     "@travetto/test": {

package/src/model/where-clause.ts

@@ -6,6 +6,8 @@ export type QueryPrimitiveArray = QueryPrimitive[];
 export type DistanceUnit = 'mi' | 'm' | 'km' | 'ft' | 'rad';
 export type RetainQueryPrimitiveFields<T> = Pick<T, ValidFields<T, QueryPrimitive>>;
 export type ValidStringFields<T> = KeyPaths<T, String | string | string[] | String[] | undefined>;
+export type ValidNumericFields<T> = KeyPaths<T, number | bigint | Number | undefined>;
+export type ValidComparableFields<T> = KeyPaths<T, number | bigint | Number | Date | undefined>;
 
 type General<T> = {
   $eq?: T;

package/src/types/aggregate.ts

@@ -0,0 +1,48 @@
+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 { 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>
+    : never
+  : Path extends keyof T
+    ? NonNullable<T[Path]> extends (infer Element)[]
+      ? Element
+      : NonNullable<T[Path]>
+    : never;
+
+export type AggregateResultType<T, F extends string> = [PathType<T, F>] extends [never]
+  ? number | Date | bigint | undefined
+  : PathType<T, F> | undefined;
+
+/**
+ * The contract for a model service with aggregate support
+ * @concrete
+ */
+export interface ModelQueryAggregateSupport extends ModelQuerySupport {
+  /**
+   * Run an aggregation on a field
+   * @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>)
+  >(
+    modelClass: Class<T>,
+    operation: Op,
+    field: F,
+    query?: ModelQuery<T>
+  ): Promise<AggregateResultType<T, F>>;
+}

package/src/util/aggregate.ts

@@ -0,0 +1,29 @@
+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';
+
+export class ModelQueryAggregateUtil {
+  /**
+   * Type guard for determining if service supports query aggregate operations
+   */
+  static isSupported = hasFunction<ModelQueryAggregateSupport>('aggregateFieldByQuery');
+
+  /**
+   * Resolve and coerce the aggregate query result using DataUtil.coerceType
+   * @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
+   */
+  static resolveResult<T extends ModelType, Op extends AggregateOperation, F extends string>(
+    modelClass: Class<T>,
+    operation: Op,
+    field: F,
+    rawValue: unknown
+  ): AggregateResultType<T, F> {
+    const leafFieldType = SchemaRegistryIndex.getNestedFieldConfig(modelClass, field)!.type;
+    return castTo(DataUtil.coerceType(rawValue, leafFieldType, false) ?? undefined);
+  }
+}

package/support/doc.support.tsx

@@ -2,6 +2,7 @@
 import { DocFileUtil, type DocJSXElement, type DocJSXElementByFn, d } from '@travetto/doc';
 import { castKey, Runtime, toConcrete } from '@travetto/runtime';
 
+import type { ModelQueryAggregateSupport } from '../src/types/aggregate.ts';
 import type { ModelQueryCrudSupport } from '../src/types/crud.ts';
 import type { ModelQueryFacetSupport } from '../src/types/facet.ts';
 import type { ModelQuerySupport } from '../src/types/query.ts';
@@ -11,6 +12,7 @@ const toLink = (title: string, target: Function): DocJSXElementByFn<'CodeLink'>
   d.codeLink(title, Runtime.getSourceFile(target), new RegExp(`\\binterface\\s+${target.name}`));
 
 export const Links = {
+  QueryAggregate: toLink('Aggregate', toConcrete<ModelQueryAggregateSupport>()),
   QueryCrud: toLink('Query Crud', toConcrete<ModelQueryCrudSupport>()),
   QueryFacet: toLink('Facet', toConcrete<ModelQueryFacetSupport>()),
   QuerySuggest: toLink('Suggest', toConcrete<ModelQuerySuggestSupport>()),
@@ -21,7 +23,7 @@ export const ModelQueryTypes = (fn: Function): DocJSXElement[] => {
   const { content } = DocFileUtil.readSource(fn);
   const found: DocJSXElementByFn<'CodeLink'>[] = [];
   const seen = new Set<string>();
-  for (const [, key] of content.matchAll(/Model(Query(Suggest|Facet|Crud)?)Support/g)) {
+  for (const [, key] of content.matchAll(/Model(Query(Aggregate|Suggest|Facet|Crud)?)Support/g)) {
     if (!seen.has(key) && key in Links) {
       seen.add(key);
       const link = Links[castKey(key)];

package/support/test/aggregate.ts

@@ -0,0 +1,107 @@
+import assert from 'node:assert';
+
+import type { ModelCrudSupport } from '@travetto/model';
+import { Suite, Test } from '@travetto/test';
+
+import { BaseModelSuite } from '@travetto/model/support/test/base.ts';
+
+import type { ModelQueryAggregateSupport } from '../../src/types/aggregate.ts';
+import { Aged, BigIntModel, Person } from './model.ts';
+
+@Suite()
+export abstract class ModelQueryAggregateSuite extends BaseModelSuite<ModelQueryAggregateSupport & ModelCrudSupport> {
+  @Test('verify basic aggregations')
+  async testAggregate() {
+    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' } }),
+      Person.from({ name: 'Charlie', age: 40, gender: 'm', address: { street1: '3rd St' } }),
+      Person.from({ name: 'Dana', age: 50, gender: 'f', address: { street1: '4th St' } })
+    ];
+
+    const service = await this.service;
+    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 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', {
+      where: {
+        age: { $gte: 30 }
+      }
+    });
+    assert(filteredSumResult === 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', {
+      where: {
+        age: { $gt: 1000 }
+      }
+    });
+    assert(noMatchResult === 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() {
+    const service = await this.service;
+
+    await this.saveAll(BigIntModel, [
+      BigIntModel.from({ largeNumber: 100n }),
+      BigIntModel.from({ largeNumber: 200n }),
+      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);
+  }
+}

package/support/test/polymorphism.ts

@@ -7,10 +7,12 @@ import { Suite, Test } from '@travetto/test';
 import { BaseModelSuite } from '@travetto/model/support/test/base.ts';
 import { Doctor, Engineer, Firefighter, Worker } from '@travetto/model/support/test/polymorphism.ts';
 
+import type { ModelQueryAggregateSupport } from '../../src/types/aggregate.ts';
 import type { ModelQueryCrudSupport } from '../../src/types/crud.ts';
 import type { ModelQueryFacetSupport } from '../../src/types/facet.ts';
 import type { ModelQuerySupport } from '../../src/types/query.ts';
 import type { ModelQuerySuggestSupport } from '../../src/types/suggest.ts';
+import { ModelQueryAggregateUtil } from '../../src/util/aggregate.ts';
 import { ModelQueryCrudUtil } from '../../src/util/crud.ts';
 import { ModelQueryFacetUtil } from '../../src/util/facet.ts';
 import { ModelQuerySuggestUtil } from '../../src/util/suggest.ts';
@@ -109,4 +111,24 @@ export abstract class ModelQueryPolymorphismSuite extends BaseModelSuite<ModelQu
     const docFacet = await svc.facetByQuery(Doctor, 'specialty');
     assert.deepStrictEqual(docFacet, [{ count: 2, key: 'eyes' }]);
   }
+
+  @Test({ skip: ModelQueryPolymorphismSuite.ifNot(ModelQueryAggregateUtil.isSupported) })
+  async testAggregateQuery() {
+    const service: ModelQueryAggregateSupport & ModelQuerySupport = castTo(await this.service);
+    const [doctorOne, doctorTwo, firefighterOne, firefighterTwo] = [
+      Doctor.from({ name: 'bob', specialty: 'eyes' }),
+      Doctor.from({ name: 'nob', specialty: 'eyes' }),
+      Firefighter.from({ name: 'rob', firehouse: 20 }),
+      Firefighter.from({ name: 'fob', firehouse: 30 })
+    ];
+
+    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);
+  }
 }