@frogfish/k2db 1.0.1

package/db.d.ts

@@ -0,0 +1,181 @@
+import { ObjectId } from "mongodb";
+export interface HostConfig {
+    host: string;
+    port?: number;
+}
+export interface DatabaseConfig {
+    name: string;
+    user?: string;
+    password?: string;
+    hosts?: HostConfig[];
+    replicaset?: string;
+}
+export interface BaseDocument {
+    _id?: ObjectId;
+    _uuid: string;
+    _created: number;
+    _updated: number;
+    _owner: string;
+    _deleted?: boolean;
+    [key: string]: any;
+}
+export declare class DB {
+    private conf;
+    private db;
+    private connection;
+    constructor(conf: DatabaseConfig);
+    /**
+     * Initializes the MongoDB connection.
+     */
+    init(): Promise<void>;
+    /**
+     * Retrieves a collection from the database.
+     * @param collectionName - Name of the collection.
+     */
+    private getCollection;
+    get(collectionName: string, uuid: string): Promise<BaseDocument>;
+    /**
+     * Retrieves a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param uuid - UUID of the document.
+     * @param objectTypeName - Optional object type name.
+     * @param fields - Optional array of fields to include.
+     */
+    findOne(collectionName: string, criteria: any, fields?: Array<string>): Promise<BaseDocument | null>;
+    /**
+     * Finds documents based on parameters with pagination support.
+     * @param collectionName - Name of the collection.
+     * @param filter - Criteria to filter the documents.
+     * @param params - Optional search parameters (for sorting, including/excluding fields).
+     * @param skip - Number of documents to skip (for pagination).
+     * @param limit - Maximum number of documents to return.
+     */
+    find(collectionName: string, filter: any, params?: any, skip?: number, limit?: number): Promise<BaseDocument[]>;
+    /**
+     * Aggregates documents based on criteria with pagination support.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Aggregation pipeline criteria.
+     * @param skip - Number of documents to skip (for pagination).
+     * @param limit - Maximum number of documents to return.
+     */
+    aggregate(collectionName: string, criteria: any[], skip?: number, limit?: number): Promise<BaseDocument[]>;
+    /**
+     * Creates a new document in the collection.
+     * @param collectionName - Name of the collection.
+     * @param owner - Owner of the document.
+     * @param data - Data to insert.
+     */
+    create(collectionName: string, owner: string, data: Partial<BaseDocument>): Promise<{
+        id: string;
+    }>;
+    /**
+     * Updates multiple documents based on criteria.
+     * Can either replace the documents or patch them.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Update criteria.
+     * @param values - Values to update or replace with.
+     * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
+     */
+    updateAll(collectionName: string, criteria: any, values: Partial<BaseDocument>, replace?: boolean): Promise<any>;
+    /**
+     * Updates a single document by UUID.
+     * Can either replace the document or patch it.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID string to identify the document.
+     * @param data - Data to update or replace with.
+     * @param replace - If true, replaces the entire document (PUT), otherwise patches (PATCH).
+     * @param objectTypeName - Optional object type name.
+     */
+    update(collectionName: string, id: string, data: Partial<BaseDocument>, replace?: boolean, objectTypeName?: string): Promise<any>;
+    /**
+     * Removes (soft deletes) multiple documents based on criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Removal criteria.
+     */
+    deleteAll(collectionName: string, criteria: any): Promise<any>;
+    /**
+     * Removes (soft deletes) a single document by UUID.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID of the document.
+     */
+    delete(collectionName: string, id: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Permanently deletes a document that has been soft-deleted.
+     * @param collectionName - Name of the collection.
+     * @param id - UUID of the document.
+     */
+    purge(collectionName: string, id: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Restores a soft-deleted document.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Criteria to identify the document.
+     */
+    restore(collectionName: string, criteria: any): Promise<{
+        status: string;
+        modified: number;
+    }>;
+    /**
+     * Counts documents based on criteria.
+     * @param collectionName - Name of the collection.
+     * @param criteria - Counting criteria.
+     */
+    count(collectionName: string, criteria: any): Promise<{
+        count: number;
+    }>;
+    /**
+     * Drops an entire collection.
+     * @param collectionName - Name of the collection.
+     */
+    drop(collectionName: string): Promise<{
+        status: string;
+    }>;
+    /**
+     * Sanitizes aggregation criteria.
+     * @param criteria - Aggregation stage criteria.
+     */
+    private static sanitiseCriteria;
+    /**
+     * Optional: Executes a transaction with the provided operations.
+     * @param operations - A function that performs operations within a transaction session.
+     */
+    executeTransaction(operations: (session: any) => Promise<void>): Promise<void>;
+    /**
+     * Optional: Creates an index on the specified collection.
+     * @param collectionName - Name of the collection.
+     * @param indexSpec - Specification of the index.
+     * @param options - Optional index options.
+     */
+    createIndex(collectionName: string, indexSpec: any, options?: any): Promise<void>;
+    /**
+     * Releases the MongoDB connection.
+     */
+    release(): Promise<void>;
+    /**
+     * Closes the MongoDB connection.
+     */
+    close(): void;
+    /**
+     * Drops the entire database.
+     */
+    dropDatabase(): Promise<void>;
+    /**
+     * Validates the MongoDB collection name.
+     * @param collectionName - The name of the collection to validate.
+     * @throws {K2Error} - If the collection name is invalid.
+     */
+    private validateCollectionName;
+    /**
+     * Optional: Checks the health of the database connection.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Utility to normalize the error type.
+     * @param err - The caught error of type `unknown`.
+     * @returns A normalized error of type `Error`.
+     */
+    private normalizeError;
+}