Group by support

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@comake/skl-js-engine",
-	"version": "0.21.0",
+	"version": "0.22.0",
 	"description": "Standard Knowledge Language Javascript Engine",
 	"keywords": [
 		"skl",
@@ -83,7 +83,7 @@
 		"eslint-plugin-tsdoc": "^0.2.16",
 		"eslint-plugin-unused-imports": "^2.0.0",
 		"fs": "^0.0.1-security",
-		"husky": "^8.0.0",
+		"husky": "^8.0.3",
 		"jest": "^29.5.0",
 		"jsdom": "^20.0.0",
 		"ts-jest": "^29.1.0",

src/SklEngine.ts

@@ -53,6 +53,7 @@
   ensureArray,
 } from './util/Util';
 import { SKL, SHACL, RDFS, SKL_ENGINE, XSD, RDF } from './util/Vocabularies';
+import { GroupByOptions, GroupByResponse } from './storage/GroupOptionTypes';
 
 export type VerbHandler = <T extends OrArray<NodeObject> = OrArray<NodeObject>>(
   params: JSONObject,
@@ -131,6 +132,10 @@
     return await this.queryAdapter.findAll(options);
   }
 
+  public async groupBy(options: GroupByOptions): Promise<GroupByResponse> {
+    return await this.queryAdapter.groupBy(options);
+  }
+
   public async findAllBy(where: FindOptionsWhere): Promise<Entity[]> {
     return await this.queryAdapter.findAllBy(where);
   }

src/storage/GroupOptionTypes.ts

@@ -0,0 +1,32 @@
+import { FindOptionsWhere } from "./FindOptionsTypes";
+
+// Add these types at the top of the file
+export interface GroupByOptions {
+  where?: FindOptionsWhere;
+  groupBy?: string[];
+  dateRange?: {
+    start: string;
+    end: string;
+  };
+  dateGrouping?: "month" | "day";
+  limit?: number;
+  offset?: number;
+}
+
+export interface GroupResult {
+  group: Record<string, string | number>;
+  count: number;
+  entityIds: string[];
+}
+
+export interface GroupByResponse {
+  results: GroupResult[];
+  meta: {
+    totalCount: number;
+    dateRange?: {
+      start: string;
+      end: string;
+    };
+    groupings: string[];
+  };
+}

src/storage/query-adapter/QueryAdapter.ts

@@ -9,6 +9,7 @@
   FindOneOptions,
   FindOptionsWhere,
 } from '../FindOptionsTypes';
+import { GroupByOptions, GroupByResponse } from '../GroupOptionTypes';
 
 export type RawQueryResult = Record<string, number | boolean | string>;
 
@@ -102,4 +103,8 @@
    * Removes all entities from the database.
    */
   destroyAll(): Promise<void>;
+  /**
+   * Groups entities by a given options.
+   */
+  groupBy(options: GroupByOptions): Promise<GroupByResponse>;
 }

src/storage/query-adapter/sparql/SparqlQueryAdapter.ts

@@ -37,6 +37,7 @@
 import type { SparqlQueryAdapterOptions } from './SparqlQueryAdapterOptions';
 import { SparqlQueryBuilder } from './SparqlQueryBuilder';
 import { SparqlUpdateBuilder } from './SparqlUpdateBuilder';
+import { GroupByOptions, GroupByResponse, GroupResult } from '../../GroupOptionTypes';
 
 /**
  * A {@link QueryAdapter} that stores data in a database through a sparql endpoint.
@@ -213,6 +214,58 @@
     return entityOrEntities;
   }
 
+  public async groupBy(options: GroupByOptions): Promise<GroupByResponse> {
+    const queryBuilder = new SparqlQueryBuilder();
+    const { query: selectQuery, variableMapping } = await queryBuilder.buildGroupByQuery(options);
+    const results = await this.queryExecutor.executeSparqlSelectAndGetData(
+      selectQuery
+    );
+
+    // Create reverse mapping from path to variable name
+    const reverseMapping = Object.entries(variableMapping).reduce((acc, [varName, path]) => {
+      acc[path] = varName;
+      return acc;
+    }, {} as Record<string, string>);
+
+    // Transform results
+    const groupResults: GroupResult[] = results.map((result) => {
+      const group: Record<string, string | number> = {};
+
+      options.groupBy?.forEach((path) => {
+        const varName = reverseMapping[path];
+        if (!varName) {
+          throw new Error(`No variable mapping found for path: ${path}`);
+        }
+        const value = result[varName].value;
+        // Try to convert to number if possible
+        group[path] = isNaN(Number(value)) ? value : Number(value);
+      });
+
+      if (options.dateGrouping) {
+        const dateGroupVarName = reverseMapping['dateGroup'];
+        group.dateGroup = result[dateGroupVarName].value;
+      }
+
+      const countVarName = reverseMapping['count'];
+      const entityIdsVarName = reverseMapping['entityIds'];
+
+      return {
+        group,
+        count: parseInt(result[countVarName].value, 10),
+        entityIds: result[entityIdsVarName].value.split(" "),
+      };
+    });
+
+    return {
+      results: groupResults,
+      meta: {
+        totalCount: groupResults.reduce((sum, curr) => sum + curr.count, 0),
+        dateRange: options.dateRange,
+        groupings: options.groupBy || [],
+      },
+    };
+  }
+
   public async update(id: string, attributes: Partial<Entity>): Promise<void>;
   public async update(ids: string[], attributes: Partial<Entity>): Promise<void>;
   public async update(idOrIds: string | string[], attributes: Partial<Entity>): Promise<void> {