feat: generics

Author: coodos

infrastructure/evault-core/src/db/db.service.spec.ts

@@ -16,15 +16,15 @@ describe("DbService (integration)", () => {
     let driver: Driver;
 
     beforeAll(async () => {
-        container = await new Neo4jContainer("neo4j:4.4.12").start();
+        container = await new Neo4jContainer("neo4j:5.15").start();
 
         const username = container.getUsername();
         const password = container.getPassword();
         const boltPort = container.getMappedPort(7687);
         const uri = `bolt://localhost:${boltPort}`;
 
         driver = neo4j.driver(uri, neo4j.auth.basic(username, password));
-        service = new DbService(uri, username, password);
+        service = new DbService(driver);
     });
 
     afterAll(async () => {

infrastructure/evault-core/src/db/db.service.ts

@@ -1,27 +1,33 @@
 import neo4j, { Driver } from "neo4j-driver";
 import { W3IDBuilder } from "w3id";
 import { serializeValue, deserializeValue } from "./schema";
-
-type MetaEnvelope = {
-    ontology: string;
-    payload: Record<string, any>;
-    acl: string[];
-};
-
-type Envelope = {
-    id: string;
-    value: any;
-    ontology: string;
-    valueType: string;
-};
-
+import {
+    MetaEnvelope,
+    Envelope,
+    MetaEnvelopeResult,
+    StoreMetaEnvelopeResult,
+    SearchMetaEnvelopesResult,
+    GetAllEnvelopesResult,
+} from "./types";
+
+/**
+ * Service for managing meta-envelopes and their associated envelopes in Neo4j.
+ * Provides functionality for storing, retrieving, searching, and updating data
+ * with proper type handling and access control.
+ */
 export class DbService {
-    private driver: Driver;
-
-    constructor(uri: string, user: string, password: string) {
-        this.driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
-    }
-
+    /**
+     * Creates a new instance of the DbService.
+     * @param driver - The Neo4j driver instance
+     */
+    constructor(private driver: Driver) {}
+
+    /**
+     * Executes a Cypher query with the given parameters.
+     * @param query - The Cypher query to execute
+     * @param params - The parameters for the query
+     * @returns The result of the query execution
+     */
     private async runQuery(query: string, params: Record<string, any>) {
         const session = this.driver.session();
         try {
@@ -31,7 +37,18 @@ export class DbService {
         }
     }
 
-    async storeMetaEnvelope(meta: Omit<MetaEnvelope, "id">, acl: string[]) {
+    /**
+     * Stores a new meta-envelope and its associated envelopes.
+     * @param meta - The meta-envelope data (without ID)
+     * @param acl - The access control list for the meta-envelope
+     * @returns The created meta-envelope and its envelopes
+     */
+    async storeMetaEnvelope<
+        T extends Record<string, any> = Record<string, any>,
+    >(
+        meta: Omit<MetaEnvelope<T>, "id">,
+        acl: string[],
+    ): Promise<StoreMetaEnvelopeResult<T>> {
         const w3id = await new W3IDBuilder().build();
 
         const cypher: string[] = [
@@ -44,7 +61,7 @@ export class DbService {
             acl: acl,
         };
 
-        const createdEnvelopes: Envelope[] = [];
+        const createdEnvelopes: Envelope<T[keyof T]>[] = [];
         let counter = 0;
 
         for (const [key, value] of Object.entries(meta.payload)) {
@@ -74,7 +91,7 @@ export class DbService {
             createdEnvelopes.push({
                 id: envelopeId,
                 ontology: key,
-                value: value,
+                value: value as T[keyof T],
                 valueType,
             });
 
@@ -93,12 +110,19 @@ export class DbService {
         };
     }
 
-    async findMetaEnvelopesBySearchTerm(
+    /**
+     * Finds meta-envelopes containing the search term in any of their envelopes.
+     * Returns all envelopes from the matched meta-envelopes.
+     * @param ontology - The ontology to search within
+     * @param searchTerm - The term to search for
+     * @returns Array of matched meta-envelopes with their complete envelope sets
+     */
+    async findMetaEnvelopesBySearchTerm<
+        T extends Record<string, any> = Record<string, any>,
+    >(
         ontology: string,
         searchTerm: string,
-    ): Promise<
-        { id: string; envelopes: any[]; parsed: Record<string, any> }[]
-    > {
+    ): Promise<SearchMetaEnvelopesResult<T>> {
         const result = await this.runQuery(
             `
     MATCH (m:MetaEnvelope { ontology: $ontology })-[:LINKS_TO]->(e:Envelope)
@@ -111,43 +135,53 @@ export class DbService {
       END
     WITH m
     MATCH (m)-[:LINKS_TO]->(allEnvelopes:Envelope)
-    RETURN m.id AS id, collect(allEnvelopes) AS envelopes
+    RETURN m.id AS id, m.ontology AS ontology, m.acl AS acl, collect(allEnvelopes) AS envelopes
     `,
             { ontology, term: searchTerm },
         );
 
-        return result.records.map((record) => {
-            const envelopes = record.get("envelopes").map((node: any) => {
-                const properties = node.properties;
-                return {
-                    id: properties.id,
-                    ontology: properties.ontology,
-                    value: deserializeValue(
-                        properties.value,
-                        properties.valueType,
-                    ),
-                    valueType: properties.valueType,
-                };
-            });
+        return result.records.map((record): MetaEnvelopeResult<T> => {
+            const envelopes = record
+                .get("envelopes")
+                .map((node: any): Envelope<T[keyof T]> => {
+                    const properties = node.properties;
+                    return {
+                        id: properties.id,
+                        ontology: properties.ontology,
+                        value: deserializeValue(
+                            properties.value,
+                            properties.valueType,
+                        ) as T[keyof T],
+                        valueType: properties.valueType,
+                    };
+                });
 
-            // Reconstruct the original payload structure
             const parsed = envelopes.reduce(
-                (acc: Record<string, any>, envelope: Envelope) => {
-                    acc[envelope.ontology] = envelope.value;
+                (acc: T, envelope: Envelope<T[keyof T]>) => {
+                    (acc as any)[envelope.ontology] = envelope.value;
                     return acc;
                 },
-                {},
+                {} as T,
             );
 
             return {
                 id: record.get("id"),
+                ontology: record.get("ontology"),
+                acl: record.get("acl"),
                 envelopes,
                 parsed,
             };
         });
     }
 
-    async findMetaEnvelopeById(id: string): Promise<any> {
+    /**
+     * Finds a meta-envelope by its ID.
+     * @param id - The ID of the meta-envelope to find
+     * @returns The meta-envelope with all its envelopes and parsed payload, or null if not found
+     */
+    async findMetaEnvelopeById<
+        T extends Record<string, any> = Record<string, any>,
+    >(id: string): Promise<MetaEnvelopeResult<T> | null> {
         const result = await this.runQuery(
             `
       MATCH (m:MetaEnvelope { id: $id })-[:LINKS_TO]->(e:Envelope)
@@ -159,23 +193,27 @@ export class DbService {
         if (!result.records[0]) return null;
 
         const record = result.records[0];
-        const envelopes = record.get("envelopes").map((node: any) => {
-            const properties = node.properties;
-            return {
-                id: properties.id,
-                ontology: properties.ontology,
-                value: deserializeValue(properties.value, properties.valueType),
-                valueType: properties.valueType,
-            };
-        });
+        const envelopes = record
+            .get("envelopes")
+            .map((node: any): Envelope<T[keyof T]> => {
+                const properties = node.properties;
+                return {
+                    id: properties.id,
+                    ontology: properties.ontology,
+                    value: deserializeValue(
+                        properties.value,
+                        properties.valueType,
+                    ) as T[keyof T],
+                    valueType: properties.valueType,
+                };
+            });
 
-        // Reconstruct the original payload structure
         const parsed = envelopes.reduce(
-            (acc: Record<string, any>, envelope: Envelope) => {
-                acc[envelope.ontology] = envelope.value;
+            (acc: T, envelope: Envelope<T[keyof T]>) => {
+                (acc as any)[envelope.ontology] = envelope.value;
                 return acc;
             },
-            {},
+            {} as T,
         );
 
         return {
@@ -187,6 +225,11 @@ export class DbService {
         };
     }
 
+    /**
+     * Finds all meta-envelope IDs for a given ontology.
+     * @param ontology - The ontology to search for
+     * @returns Array of meta-envelope IDs
+     */
     async findMetaEnvelopesByOntology(ontology: string): Promise<string[]> {
         const result = await this.runQuery(
             `
@@ -199,6 +242,10 @@ export class DbService {
         return result.records.map((r) => r.get("id"));
     }
 
+    /**
+     * Deletes a meta-envelope and all its associated envelopes.
+     * @param id - The ID of the meta-envelope to delete
+     */
     async deleteMetaEnvelope(id: string): Promise<void> {
         await this.runQuery(
             `
@@ -209,9 +256,14 @@ export class DbService {
         );
     }
 
-    async updateEnvelopeValue(
+    /**
+     * Updates the value of an envelope.
+     * @param envelopeId - The ID of the envelope to update
+     * @param newValue - The new value to set
+     */
+    async updateEnvelopeValue<T = any>(
         envelopeId: string,
-        newValue: any,
+        newValue: T,
     ): Promise<void> {
         const { value: storedValue, type: valueType } =
             serializeValue(newValue);
@@ -225,20 +277,30 @@ export class DbService {
         );
     }
 
-    async getAllEnvelopes(): Promise<Envelope[]> {
+    /**
+     * Retrieves all envelopes in the system.
+     * @returns Array of all envelopes
+     */
+    async getAllEnvelopes<T = any>(): Promise<GetAllEnvelopesResult<T>> {
         const result = await this.runQuery(`MATCH (e:Envelope) RETURN e`, {});
-        return result.records.map((r) => {
+        return result.records.map((r): Envelope<T> => {
             const node = r.get("e");
             const properties = node.properties;
             return {
                 id: properties.id,
                 ontology: properties.ontology,
-                value: deserializeValue(properties.value, properties.valueType),
+                value: deserializeValue(
+                    properties.value,
+                    properties.valueType,
+                ) as T,
                 valueType: properties.valueType,
             };
         });
     }
 
+    /**
+     * Closes the database connection.
+     */
     async close(): Promise<void> {
         await this.driver.close();
     }

infrastructure/evault-core/src/db/types.ts

@@ -0,0 +1,59 @@
+/**
+ * Represents a meta-envelope that contains multiple envelopes of data.
+ */
+export type MetaEnvelope<T extends Record<string, any> = Record<string, any>> =
+  {
+    ontology: string;
+    payload: T;
+    acl: string[];
+  };
+
+/**
+ * Represents an individual envelope containing a single piece of data.
+ */
+export type Envelope<T = any> = {
+  id: string;
+  value: T;
+  ontology: string;
+  valueType: string;
+};
+
+/**
+ * Base result type for all database operations that return a meta-envelope.
+ * Includes the parsed payload structure reconstructed from the envelopes.
+ */
+export type MetaEnvelopeResult<
+  T extends Record<string, any> = Record<string, any>,
+> = {
+  id: string;
+  ontology: string;
+  acl: string[];
+  envelopes: Envelope<T[keyof T]>[];
+  parsed: T;
+};
+
+/**
+ * Result type for storing a new meta-envelope.
+ */
+export type StoreMetaEnvelopeResult<
+  T extends Record<string, any> = Record<string, any>,
+> = {
+  metaEnvelope: {
+    id: string;
+    ontology: string;
+    acl: string[];
+  };
+  envelopes: Envelope<T[keyof T]>[];
+};
+
+/**
+ * Result type for searching meta-envelopes.
+ */
+export type SearchMetaEnvelopesResult<
+  T extends Record<string, any> = Record<string, any>,
+> = MetaEnvelopeResult<T>[];
+
+/**
+ * Result type for retrieving all envelopes.
+ */
+export type GetAllEnvelopesResult<T = any> = Envelope<T>[];