fluxor-cloud-db 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,347 @@
+type DynamoConfig = {
+    region: string;
+    endpoint: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+};
+
+type QueryOperator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "IN" | "NOT_IN" | "BETWEEN" | "LIKE" | "EXISTS" | "BEGINS_WITH";
+/**
+ * Represents a single condition in a WHERE clause
+ */
+interface QueryCondition {
+    operator: QueryOperator;
+    value: any;
+}
+/**
+ * Represents a single field condition or nested conditions
+ */
+interface WhereClause {
+    [key: string]: QueryCondition | QueryCondition[] | WhereClause;
+}
+/**
+ * Represents update operations on specific fields
+ */
+interface UpdateClause {
+    [key: string]: any;
+}
+/**
+ * Configuration for query operations
+ */
+interface QueryOptions {
+    limit?: number;
+    offset?: number;
+    orderBy?: {
+        field: string;
+        direction: "ASC" | "DESC";
+    }[];
+    projection?: string[];
+    consistent?: boolean;
+}
+/**
+ * Result wrapper for paginated responses
+ */
+type PaginatedResult<T> = {
+    items: T[];
+    total: number;
+    hasMore: boolean;
+    nextOffset?: number;
+};
+/**
+ * Result wrapper for batch operations
+ */
+interface BatchResult {
+    successful: number;
+    failed: number;
+    errors?: {
+        index: number;
+        error: string;
+    }[];
+}
+
+/**
+ * Unified database adapter interface
+ * Supports DynamoDB, MongoDB, SQL databases, and other data stores
+ */
+interface DatabaseAdapter {
+    /**
+     * Establish connection to the database
+     * Implementation varies by backend (DynamoDB, MongoDB, etc.)
+     */
+    connect(): Promise<void>;
+    /**
+     * Close connection to the database
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if adapter is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Fetch a single record matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions
+     * @param options - Query options (projection, consistency, etc.)
+     * @returns Single record or null if not found
+     */
+    selectOne<T = Record<string, any>>(tableName: string, where: WhereClause, options?: QueryOptions): Promise<T | null>;
+    /**
+     * Fetch multiple records matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions
+     * @param options - Query options (limit, offset, orderBy, projection, etc.)
+     * @returns Array of matching records with pagination info
+     */
+    selectMany<T = Record<string, any>>(tableName: string, where?: WhereClause, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    /**
+     * Insert a single record
+     * @param tableName - Table/collection name
+     * @param data - Record to insert
+     * @returns Created record with any server-generated fields
+     */
+    createOne<T = Record<string, any>>(tableName: string, data: Record<string, any>): Promise<T>;
+    /**
+     * Insert multiple records in a batch operation
+     * @param tableName - Table/collection name
+     * @param data - Array of records to insert
+     * @param options - Batch options (e.g., stopOnError)
+     * @returns Batch operation result with success/failure counts
+     */
+    createMany<T = Record<string, any>>(tableName: string, data: Record<string, any>[], options?: {
+        stopOnError?: boolean;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    /**
+     * Update a single record matching the where conditions
+     * @param tableName - Table/collection name
+     * @param update - Fields to update
+     * @param where - Query conditions to identify record
+     * @returns Updated record
+     */
+    updateOne<T = Record<string, any>>(tableName: string, update: UpdateClause, where: WhereClause): Promise<T>;
+    /**
+     * Update multiple records matching the where conditions
+     * @param tableName - Table/collection name
+     * @param update - Fields to update
+     * @param where - Query conditions to identify records
+     * @param options - Update options (e.g., limit)
+     * @returns Batch operation result with updated count
+     */
+    updateMany<T = Record<string, any>>(tableName: string, update: UpdateClause, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    /**
+     * Delete a single record matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions to identify record
+     * @returns Deleted record or confirmation
+     */
+    deleteOne(tableName: string, where: WhereClause): Promise<{
+        success: boolean;
+        deletedCount: number;
+    }>;
+    /**
+     * Delete multiple records matching the where conditions
+     * @param tableName - Table/collection name
+     * @param where - Query conditions to identify records
+     * @param options - Delete options (e.g., limit)
+     * @returns Batch operation result with deleted count
+     */
+    deleteMany(tableName: string, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        result: BatchResult;
+    }>;
+    /**
+     * Execute a raw query specific to the database backend
+     * Use sparingly for complex queries not supported by the adapter
+     */
+    executeRaw<T = any>(query: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * Start a transaction (if supported by the backend)
+     */
+    beginTransaction?(): Promise<void>;
+    /**
+     * Commit an active transaction
+     */
+    commitTransaction?(): Promise<void>;
+    /**
+     * Rollback an active transaction
+     */
+    rollbackTransaction?(): Promise<void>;
+    /**
+     * Check the health/status of the database connection
+     */
+    healthCheck(): Promise<boolean>;
+}
+
+declare class DynamoService implements DatabaseAdapter {
+    private client;
+    private dynamoDBClient;
+    private isConnectedFlag;
+    private config;
+    setConfig(config: DynamoConfig): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    healthCheck(): Promise<boolean>;
+    selectOne<T = Record<string, any>>(tableName: string, where: WhereClause, options?: QueryOptions): Promise<T | null>;
+    selectMany<T = Record<string, any>>(tableName: string, where?: WhereClause, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    createOne<T = Record<string, any>>(tableName: string, data: Record<string, any>): Promise<T>;
+    createMany<T = Record<string, any>>(tableName: string, data: Record<string, any>[], options?: {
+        stopOnError?: boolean;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    updateOne<T = Record<string, any>>(tableName: string, update: UpdateClause, where: WhereClause): Promise<T>;
+    updateMany<T = Record<string, any>>(tableName: string, update: UpdateClause, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    deleteOne(tableName: string, where: WhereClause): Promise<{
+        success: boolean;
+        deletedCount: number;
+    }>;
+    deleteMany(tableName: string, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        result: BatchResult;
+    }>;
+    executeRaw<T = any>(query: string, params?: Record<string, any>): Promise<T>;
+    private validateConfig;
+    private getClient;
+    private buildKey;
+    private extractKey;
+    private isKeyQuery;
+    private buildProjection;
+    private buildKeyConditionExpression;
+    private buildFilterExpression;
+    private buildUpdateExpression;
+    private handleError;
+}
+
+/**
+ * MongoDB implementation of DatabaseAdapter interface
+ * This is a template implementation showing how to adapt another database backend
+ */
+
+interface MongoConfig {
+    uri: string;
+    dbName: string;
+    authSource?: string;
+    retryWrites?: boolean;
+    w?: "majority" | number;
+}
+declare class MongoService implements DatabaseAdapter {
+    private client;
+    private db;
+    private isConnectedFlag;
+    private config;
+    setConfig(config: MongoConfig): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    healthCheck(): Promise<boolean>;
+    selectOne<T = Record<string, any>>(tableName: string, where: WhereClause, options?: QueryOptions): Promise<T | null>;
+    selectMany<T = Record<string, any>>(tableName: string, where?: WhereClause, options?: QueryOptions): Promise<PaginatedResult<T>>;
+    createOne<T = Record<string, any>>(tableName: string, data: Record<string, any>): Promise<T>;
+    createMany<T = Record<string, any>>(tableName: string, data: Record<string, any>[], options?: {
+        stopOnError?: boolean;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    updateOne<T = Record<string, any>>(tableName: string, update: UpdateClause, where: WhereClause): Promise<T>;
+    updateMany<T = Record<string, any>>(tableName: string, update: UpdateClause, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        result: BatchResult;
+    }>;
+    deleteOne(tableName: string, where: WhereClause): Promise<{
+        success: boolean;
+        deletedCount: number;
+    }>;
+    deleteMany(tableName: string, where?: WhereClause, options?: {
+        limit?: number;
+    }): Promise<{
+        success: boolean;
+        deletedCount: number;
+        result: BatchResult;
+    }>;
+    executeRaw<T = any>(query: string, params?: Record<string, any>): Promise<T>;
+    private validateConfig;
+    private getDb;
+    private getCollection;
+    private buildMongoFilter;
+    private isValidOperator;
+    private buildMongoUpdate;
+    private handleError;
+}
+
+interface Condition {
+    operator: string;
+    value: unknown;
+}
+declare const eq: (value: unknown) => Condition;
+declare const neq: (value: unknown) => Condition;
+declare const gt: (value: number | string) => Condition;
+declare const gte: (value: number | string) => Condition;
+declare const lt: (value: number | string) => Condition;
+declare const lte: (value: number | string) => Condition;
+/** Inclusive range. MongoDB only. */
+declare const between: (min: number | string, max: number | string) => Condition;
+declare const anyOf: (values: unknown[]) => Condition;
+declare const noneOf: (values: unknown[]) => Condition;
+declare const startsWith: (value: string) => Condition;
+/** Case-insensitive substring match. MongoDB only. */
+declare const like: (value: string) => Condition;
+/** Field presence check. MongoDB only. */
+declare const exists: (value?: boolean) => Condition;
+/** Alias for eq */
+declare const equals: (value: unknown) => Condition;
+/** Alias for neq */
+declare const notEquals: (value: unknown) => Condition;
+/** Alias for anyOf */
+declare const inList: (values: unknown[]) => Condition;
+/** Alias for noneOf */
+declare const notInList: (values: unknown[]) => Condition;
+
+/**
+ * Resolves the {@link DynamoService} instance from the service container.
+ *
+ * @example
+ * ```typescript
+ * const dynamo = useDynamo();
+ * const user = await dynamo.selectOne("users", { id: { operator: "=", value: 1 } });
+ * ```
+ *
+ * @returns The registered {@link DynamoService} instance.
+ */
+declare const useDynamo: () => DynamoService;
+/**
+ * Resolves the {@link MongoService} instance from the service container.
+ *
+ * @example
+ * ```typescript
+ * const mongo = useMongo();
+ * const users = await mongo.selectMany("users", { status: { operator: "=", value: "active" } });
+ * ```
+ *
+ * @returns The registered {@link MongoService} instance.
+ */
+declare const useMongo: () => MongoService;
+
+export { type DynamoConfig, DynamoService, type MongoConfig, MongoService, anyOf, between, eq, equals, exists, gt, gte, inList, like, lt, lte, neq, noneOf, notEquals, notInList, startsWith, useDynamo, useMongo };