fluxor-cloud-db 1.0.0

package/jest.config.ts

@@ -0,0 +1,12 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  moduleFileExtensions: ['ts', 'js'],
+  testMatch: ['<rootDir>/tests/**/*.test.ts'],
+  verbose: true
+};
+
+export default config;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "fluxor-cloud-db",
+  "version": "1.0.0",
+  "description": "Cloud-agnostic event framework",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "cross-env": "^10.1.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:watch": "jest --watch",
+    "build": "tsup src/index.ts --format cjs,esm --dts --out-dir dist --clean"
+  },
+  "bin": {
+    "new": "bin/create-app/create-app.js"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.1012.0",
+    "@aws-sdk/lib-dynamodb": "^3.1012.0",
+    "@types/mongodb": "^4.0.6",
+    "fluxor-cloud": "^1.0.61",
+    "mongodb": "^7.1.0",
+    "reflect-metadata": "^0.2.2"
+  }
+}

package/src/contracts/database-adapter.ts

@@ -0,0 +1,161 @@
+import { WhereClause, QueryOptions, PaginatedResult, BatchResult, UpdateClause } from "../types/query";
+
+/**
+ * Unified database adapter interface
+ * Supports DynamoDB, MongoDB, SQL databases, and other data stores
+ */
+export 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;
+ 
+    // ============ SELECT Operations ============
+ 
+    /**
+     * 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>>;
+ 
+    // ============ CREATE Operations ============
+ 
+    /**
+     * 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 Operations ============
+ 
+    /**
+     * 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 Operations ============
+ 
+    /**
+     * 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 }>;
+ 
+    // ============ Advanced Operations ============
+ 
+    /**
+     * 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>;
+}