@friggframework/core 2.0.0-next.1 → 2.0.0-next.100

package/integrations/repositories/process-repository-documentdb.js

@@ -0,0 +1,311 @@
+const { prisma } = require('../../database/prisma');
+const {
+    toObjectId,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    updateOne,
+    deleteOne,
+} = require('../../database/documentdb-utils');
+const {
+    ProcessRepositoryInterface,
+} = require('./process-repository-interface');
+const {
+    DocumentDBEncryptionService,
+} = require('../../database/documentdb-encryption-service');
+const { validateOps } = require('./process-update-ops-shared');
+
+class ProcessRepositoryDocumentDB extends ProcessRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    async create(processData) {
+        const now = new Date();
+        const plainDocument = {
+            userId: toObjectId(processData.userId),
+            integrationId: toObjectId(processData.integrationId),
+            name: processData.name,
+            type: processData.type,
+            state: processData.state || 'INITIALIZING',
+            context: processData.context || {},
+            results: processData.results || {},
+            childProcesses: (processData.childProcesses || [])
+                .map((id) => toObjectId(id))
+                .filter(Boolean),
+            parentProcessId: processData.parentProcessId
+                ? toObjectId(processData.parentProcessId)
+                : null,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'Process',
+            plainDocument
+        );
+
+        const insertedId = await insertOne(
+            this.prisma,
+            'Process',
+            encryptedDocument
+        );
+
+        const created = await findOne(this.prisma, 'Process', {
+            _id: insertedId,
+        });
+        if (!created) {
+            console.error(
+                '[ProcessRepositoryDocumentDB] Process not found after insert',
+                {
+                    insertedId: fromObjectId(insertedId),
+                    processData: {
+                        userId: processData.userId,
+                        integrationId: processData.integrationId,
+                        name: processData.name,
+                        type: processData.type,
+                    },
+                }
+            );
+            throw new Error(
+                'Failed to create process: Document not found after insert. ' +
+                    'This indicates a database consistency issue.'
+            );
+        }
+        const decryptedProcess = await this.encryptionService.decryptFields(
+            'Process',
+            created
+        );
+        return this._mapProcess(decryptedProcess);
+    }
+
+    async findById(processId) {
+        const objectId = toObjectId(processId);
+        if (!objectId) return null;
+        const doc = await findOne(this.prisma, 'Process', { _id: objectId });
+        if (!doc) return null;
+
+        const decryptedProcess = await this.encryptionService.decryptFields(
+            'Process',
+            doc
+        );
+        return this._mapProcess(decryptedProcess);
+    }
+
+    async update(processId, updates) {
+        const objectId = toObjectId(processId);
+        if (!objectId) return null;
+
+        const existing = await findOne(this.prisma, 'Process', {
+            _id: objectId,
+        });
+        if (!existing) return null;
+
+        const updatePayload = {};
+        if (updates.state !== undefined) updatePayload.state = updates.state;
+        if (updates.context !== undefined)
+            updatePayload.context = updates.context;
+        if (updates.results !== undefined)
+            updatePayload.results = updates.results;
+        if (updates.childProcesses !== undefined) {
+            updatePayload.childProcesses = (updates.childProcesses || [])
+                .map((id) => toObjectId(id))
+                .filter(Boolean);
+        }
+        if (updates.parentProcessId !== undefined) {
+            updatePayload.parentProcessId = updates.parentProcessId
+                ? toObjectId(updates.parentProcessId)
+                : null;
+        }
+        updatePayload.updatedAt = new Date();
+
+        const encryptedUpdate = await this.encryptionService.encryptFields(
+            'Process',
+            updatePayload
+        );
+
+        await updateOne(
+            this.prisma,
+            'Process',
+            { _id: objectId },
+            { $set: encryptedUpdate }
+        );
+
+        const updated = await findOne(this.prisma, 'Process', {
+            _id: objectId,
+        });
+        if (!updated) {
+            console.error(
+                '[ProcessRepositoryDocumentDB] Process not found after update',
+                {
+                    processId: fromObjectId(objectId),
+                }
+            );
+            throw new Error(
+                'Failed to update process: Document not found after update. ' +
+                    'This indicates a database consistency issue.'
+            );
+        }
+        const decryptedProcess = await this.encryptionService.decryptFields(
+            'Process',
+            updated
+        );
+        return this._mapProcess(decryptedProcess);
+    }
+
+    /**
+     * Atomic process update — race-safe counterpart to `update()`.
+     *
+     * Uses DocumentDB's native $inc / $set / $push operators (Mongo-wire
+     * compatible) via findAndModify so increments, sets, and pushes land
+     * in one server-side write. Contention on the same document
+     * serializes at the DB level.
+     *
+     * DocumentDB compatibility notes:
+     *  - $inc: supported since v3.6.
+     *  - $set with dot-path: supported.
+     *  - $push with $each + negative $slice: supported since v4.0.
+     *    Clusters still on v3.6 must upgrade before using pushSlice.
+     *
+     * Process documents have no encrypted fields today; if that changes,
+     * the set-by-path payload here MUST route through
+     * `encryptionService.encryptFields` for any affected paths.
+     *
+     * @param {string} processId
+     * @param {import('./process-repository-interface').ProcessUpdateOps} ops
+     * @returns {Promise<Object|null>}
+     */
+    async applyProcessUpdate(processId, ops) {
+        const normalized = validateOps(ops);
+        const objectId = toObjectId(processId);
+
+        const update = {};
+        const $set = {};
+
+        if (Object.keys(normalized.increment).length > 0) {
+            update.$inc = { ...normalized.increment };
+        }
+        for (const [path, value] of Object.entries(normalized.set)) {
+            $set[path] = value;
+        }
+        if (normalized.newState !== null) {
+            $set.state = normalized.newState;
+        }
+        $set.updatedAt = new Date();
+        update.$set = $set;
+
+        if (Object.keys(normalized.pushSlice).length > 0) {
+            update.$push = {};
+            for (const [path, spec] of Object.entries(normalized.pushSlice)) {
+                update.$push[path] = {
+                    $each: spec.values,
+                    $slice: -spec.keepLast,
+                };
+            }
+        }
+
+        const result = await this.prisma.$runCommandRaw({
+            findAndModify: 'Process',
+            query: { _id: objectId },
+            update,
+            new: true,
+        });
+
+        const doc = result && result.value;
+        if (!doc) return null;
+        const decrypted = await this.encryptionService.decryptFields(
+            'Process',
+            doc
+        );
+        return this._mapProcess(decrypted);
+    }
+
+    async findByIntegrationAndType(integrationId, type) {
+        const integrationObjectId = toObjectId(integrationId);
+        const filter = {
+            integrationId: integrationObjectId,
+            type,
+        };
+        const docs = await findMany(this.prisma, 'Process', filter, {
+            sort: { createdAt: -1 },
+        });
+
+        const decryptedDocs = await Promise.all(
+            docs.map((doc) =>
+                this.encryptionService.decryptFields('Process', doc)
+            )
+        );
+
+        return decryptedDocs.map((doc) => this._mapProcess(doc));
+    }
+
+    async findActiveProcesses(
+        integrationId,
+        excludeStates = ['COMPLETED', 'ERROR']
+    ) {
+        const integrationObjectId = toObjectId(integrationId);
+        const filter = {
+            integrationId: integrationObjectId,
+            state: { $nin: excludeStates },
+        };
+        const docs = await findMany(this.prisma, 'Process', filter, {
+            sort: { createdAt: -1 },
+        });
+
+        const decryptedDocs = await Promise.all(
+            docs.map((doc) =>
+                this.encryptionService.decryptFields('Process', doc)
+            )
+        );
+
+        return decryptedDocs.map((doc) => this._mapProcess(doc));
+    }
+
+    async findByName(name) {
+        const doc = await findOne(
+            this.prisma,
+            'Process',
+            { name },
+            { sort: { createdAt: -1 } }
+        );
+        if (!doc) return null;
+
+        const decryptedProcess = await this.encryptionService.decryptFields(
+            'Process',
+            doc
+        );
+        return this._mapProcess(decryptedProcess);
+    }
+
+    async deleteById(processId) {
+        const objectId = toObjectId(processId);
+        if (!objectId) return;
+        await deleteOne(this.prisma, 'Process', { _id: objectId });
+    }
+
+    _mapProcess(doc) {
+        return {
+            id: fromObjectId(doc?._id),
+            userId: fromObjectId(doc?.userId),
+            integrationId: fromObjectId(doc?.integrationId),
+            name: doc?.name ?? null,
+            type: doc?.type ?? null,
+            state: doc?.state ?? null,
+            context: doc?.context ?? {},
+            results: doc?.results ?? {},
+            childProcesses: (doc?.childProcesses || []).map((id) =>
+                fromObjectId(id)
+            ),
+            parentProcessId: doc?.parentProcessId
+                ? fromObjectId(doc.parentProcessId)
+                : null,
+            createdAt: doc?.createdAt ? new Date(doc.createdAt) : null,
+            updatedAt: doc?.updatedAt ? new Date(doc.updatedAt) : null,
+        };
+    }
+}
+
+module.exports = { ProcessRepositoryDocumentDB };

package/integrations/repositories/process-repository-factory.js

@@ -0,0 +1,53 @@
+const { ProcessRepositoryMongo } = require('./process-repository-mongo');
+const { ProcessRepositoryPostgres } = require('./process-repository-postgres');
+const {
+    ProcessRepositoryDocumentDB,
+} = require('./process-repository-documentdb');
+const config = require('../../database/config');
+
+/**
+ * Process Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * This implements the Factory pattern for Hexagonal Architecture:
+ * - Reads database type from app definition (backend/index.js)
+ * - Returns correct adapter (MongoDB or PostgreSQL)
+ * - Provides clear error for unsupported databases
+ *
+ * Usage:
+ * ```javascript
+ * const repository = createProcessRepository();
+ * await repository.create({ userId, integrationId, name, type, state });
+ * ```
+ *
+ * @returns {ProcessRepositoryInterface} Configured repository adapter
+ * @throws {Error} If database type is not supported
+ */
+function createProcessRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new ProcessRepositoryMongo();
+
+        case 'postgresql':
+            return new ProcessRepositoryPostgres();
+
+        case 'documentdb':
+            return new ProcessRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createProcessRepository,
+    // Export adapters for direct testing
+    ProcessRepositoryMongo,
+    ProcessRepositoryPostgres,
+    ProcessRepositoryDocumentDB,
+};
+

package/integrations/repositories/process-repository-interface.js

@@ -0,0 +1,136 @@
+/**
+ * ProcessRepository Interface
+ * 
+ * Defines the contract for Process data access operations.
+ * Implementations must provide concrete methods for all operations.
+ * 
+ * This interface supports the Hexagonal Architecture pattern by:
+ * - Defining clear boundaries between domain logic and data access
+ * - Allowing multiple implementations (MongoDB, PostgreSQL, in-memory)
+ * - Enabling dependency injection and testability
+ */
+class ProcessRepositoryInterface {
+    /**
+     * Create a new process record
+     * @param {Object} processData - Process data to create
+     * @param {string} processData.userId - User ID
+     * @param {string} processData.integrationId - Integration ID
+     * @param {string} processData.name - Process name
+     * @param {string} processData.type - Process type
+     * @param {string} processData.state - Initial state
+     * @param {Object} [processData.context] - Process context
+     * @param {Object} [processData.results] - Process results
+     * @param {string[]} [processData.childProcesses] - Child process IDs
+     * @param {string} [processData.parentProcessId] - Parent process ID
+     * @returns {Promise<Object>} Created process record
+     */
+    async create(processData) {
+        throw new Error('Method create() must be implemented');
+    }
+
+    /**
+     * Find a process by ID
+     * @param {string} processId - Process ID to find
+     * @returns {Promise<Object|null>} Process record or null if not found
+     */
+    async findById(processId) {
+        throw new Error('Method findById() must be implemented');
+    }
+
+    /**
+     * Update a process record
+     * @param {string} processId - Process ID to update
+     * @param {Object} updates - Fields to update
+     * @returns {Promise<Object>} Updated process record
+     */
+    async update(processId, updates) {
+        throw new Error('Method update() must be implemented');
+    }
+
+    /**
+     * Apply atomic mutations to a process record.
+     *
+     * Race-safe counterpart to `update()`. Where `update()` takes full
+     * JSON blobs and does read-modify-write at the ORM layer (clobber-
+     * prone under concurrent writers), `applyProcessUpdate()` describes
+     * the intent declaratively and each backend uses its native atomic
+     * primitive:
+     *   - PostgreSQL: `jsonb_set` chain inside a single UPDATE ... RETURNING
+     *   - MongoDB: `$inc` / `$set` / `$push` via findAndModify
+     *   - DocumentDB: same operator set as MongoDB (with version caveats)
+     *
+     * All paths are dot-delimited and rooted in `context` or `results`
+     * (e.g. `context.processedRecords`,
+     * `results.aggregateData.totalSynced`). Paths MUST match
+     * `^(context|results)(\\.[a-zA-Z_][a-zA-Z0-9_]*)+$` — validated by
+     * each adapter before any SQL/command generation.
+     *
+     * Intended primary callers: UpdateProcessMetrics and
+     * UpdateProcessState. Other callers can use this directly when they
+     * need race-free cumulative updates.
+     *
+     * @typedef {Object} ProcessUpdateOps
+     * @property {Object.<string, number>} [increment] - Atomic numeric
+     *   increments keyed by dot-path. e.g.
+     *   `{ 'context.processedRecords': 1, 'results.aggregateData.totalSynced': 1 }`
+     * @property {Object.<string, *>} [set] - Atomic whole-subtree set
+     *   keyed by dot-path. Replaces the value at the path (NOT deep
+     *   merge). e.g. `{ 'context.fetchDone': true }`
+     * @property {Object.<string, {values: Array, keepLast: number}>} [pushSlice]
+     *   Atomic array push with bounded retention (sliding window of the
+     *   last `keepLast` items). Keys are dot-paths pointing to arrays.
+     *   e.g. `{ 'results.aggregateData.errors': { values: [err], keepLast: 100 } }`
+     * @property {string} [newState] - Top-level `state` column update.
+     *   Written alongside the JSON mutations in the same UPDATE so state
+     *   + counters move together.
+     *
+     * @param {string} processId - Process ID to update
+     * @param {ProcessUpdateOps} ops - Atomic operations to apply
+     * @returns {Promise<Object|null>} Updated process record (post-
+     *   mutation) or null if the process does not exist.
+     */
+    async applyProcessUpdate(processId, ops) {
+        throw new Error('Method applyProcessUpdate() must be implemented');
+    }
+
+    /**
+     * Find processes by integration and type
+     * @param {string} integrationId - Integration ID
+     * @param {string} type - Process type
+     * @returns {Promise<Array>} Array of process records
+     */
+    async findByIntegrationAndType(integrationId, type) {
+        throw new Error('Method findByIntegrationAndType() must be implemented');
+    }
+
+    /**
+     * Find active processes (not in excluded states)
+     * @param {string} integrationId - Integration ID
+     * @param {string[]} [excludeStates=['COMPLETED', 'ERROR']] - States to exclude
+     * @returns {Promise<Array>} Array of active process records
+     */
+    async findActiveProcesses(integrationId, excludeStates = ['COMPLETED', 'ERROR']) {
+        throw new Error('Method findActiveProcesses() must be implemented');
+    }
+
+    /**
+     * Find a process by name (most recent)
+     * @param {string} name - Process name
+     * @returns {Promise<Object|null>} Most recent process with given name, or null
+     */
+    async findByName(name) {
+        throw new Error('Method findByName() must be implemented');
+    }
+
+    /**
+     * Delete a process by ID
+     * @param {string} processId - Process ID to delete
+     * @returns {Promise<void>}
+     */
+    async deleteById(processId) {
+        throw new Error('Method deleteById() must be implemented');
+    }
+}
+
+module.exports = { ProcessRepositoryInterface };
+