@friggframework/core 2.0.0-next.12 → 2.0.0-next.120

package/integrations/options.js

@@ -1,5 +1,5 @@
 const { RequiredPropertyError } = require('../errors');
-const { get, getAndVerifyType } = require('../assertions');
+const { get } = require('../assertions');
 
 class Options {
     constructor(params) {

package/integrations/repositories/config-patch-shared.js

@@ -0,0 +1,43 @@
+/**
+ * Shared validation for IntegrationRepository.patchIntegrationConfig().
+ *
+ * A patch is an atomic shallow merge into Integration.config: every key in
+ * the patch is written, every other existing key is left untouched. This
+ * contract is enforced here, before any adapter emits a query, so a bug fix
+ * (or a tighter rule) fixes all three backends in one place.
+ *
+ * Keys may not contain '.' or start with '$' — both are reserved by the
+ * MongoDB/DocumentDB update-command syntax the mongo and documentdb adapters
+ * use to address `config.<key>` paths. A value of `null` is allowed and sets
+ * the key to null — the only way to clear a config field over the PATCH HTTP
+ * endpoint (it sets the value, it does not remove the key). `undefined` is
+ * rejected: it can't arrive over JSON and signals a programming error, not an
+ * intent. Removing a key entirely still requires a full replace via updateConfig.
+ */
+function validateConfigPatch(patch) {
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+        throw new Error('patchIntegrationConfig: patch must be a non-null object');
+    }
+
+    const keys = Object.keys(patch);
+    if (keys.length === 0) {
+        throw new Error(
+            'patchIntegrationConfig: patch must contain at least one key'
+        );
+    }
+
+    for (const key of keys) {
+        if (key.includes('.') || key.startsWith('$')) {
+            throw new Error(
+                `patchIntegrationConfig: patch key '${key}' cannot contain '.' or start with '$'`
+            );
+        }
+        if (patch[key] === undefined) {
+            throw new Error(
+                `patchIntegrationConfig: patch['${key}'] cannot be undefined`
+            );
+        }
+    }
+}
+
+module.exports = { validateConfigPatch };

package/integrations/repositories/integration-mapping-query-pipeline.js

@@ -0,0 +1,152 @@
+const SORT_KEY = '__sortKey';
+const MONGO_DIRECTIONS = { asc: 1, desc: -1 };
+const SORT_TYPE_RANKS = [
+    ['string'],
+    ['int', 'long', 'double', 'decimal'],
+    ['bool'],
+    ['array'],
+    ['object'],
+];
+const SCALAR_TYPES = SORT_TYPE_RANKS.slice(0, 3).flat();
+
+const isType = (expression, type) => ({ $eq: [{ $type: expression }, type] });
+const isAbsent = (expression) => ({
+    $eq: [{ $ifNull: [expression, null] }, null],
+});
+const mappingField = (segments) => `$mapping.${segments.join('.')}`;
+
+const CONDITION_EXPRESSIONS = {
+    exists: (operand) => ({ $ne: [{ $ifNull: [operand, null] }, null] }),
+    notExists: (operand) => isAbsent(operand),
+    in: (operand, values) => ({
+        $and: [
+            isType(operand, 'string'),
+            { $in: [operand, { $literal: values }] },
+        ],
+    }),
+    notStartsWith: (operand, prefix) => ({
+        $cond: [
+            isType(operand, 'string'),
+            {
+                $ne: [
+                    { $substrCP: [operand, 0, [...prefix].length] },
+                    { $literal: prefix },
+                ],
+            },
+            true,
+        ],
+    }),
+};
+
+/**
+ * Aggregation stages that answer a validated queryMappings query on the
+ * MongoDB wire protocol.
+ *
+ * @param {*} integrationId - The value IntegrationMapping.integrationId is stored as
+ * @param {ReturnType<import('./integration-mapping-query').validateMappingQuery>} query
+ * @returns {{match: Object, page: Object[], sort: Object}} `match` selects
+ *   the matching documents; `page` sorts, skips and limits them; `sort` is
+ *   the $sort stage inside `page`
+ */
+function buildMappingQueryStages(
+    integrationId,
+    { where, orderBy, skip, take, omit }
+) {
+    const match = {
+        $match: {
+            integrationId,
+            $expr: {
+                $and: [
+                    isType('$mapping', 'object'),
+                    ...where.map(entryExpression),
+                ],
+            },
+        },
+    };
+    const sort = { $sort: sortSpec(orderBy) };
+    const page = [
+        ...(orderBy
+            ? [{ $addFields: { [SORT_KEY]: sortKey(orderBy.path) } }]
+            : []),
+        ...(omit.length > 0 ? [{ $project: omitProjection(omit) }] : []),
+        sort,
+        ...(skip > 0 ? [{ $skip: skip }] : []),
+        { $limit: take },
+    ];
+    return { match, page, sort };
+}
+
+function entryExpression(entry) {
+    if (!entry.anyOf) return conditionExpression(entry);
+    return { $or: entry.anyOf.map(conditionExpression) };
+}
+
+function conditionExpression({ field, path, op, value }) {
+    const operand = field === 'sourceId' ? '$sourceId' : resolvePath(path);
+    return CONDITION_EXPRESSIONS[op](operand, value);
+}
+
+/**
+ * The value at a mapping path; null when an enclosing value is not an object.
+ */
+function resolvePath(segments) {
+    const enclosing = segments
+        .slice(0, -1)
+        .map((_, i) =>
+            isType(mappingField(segments.slice(0, i + 1)), 'object')
+        );
+    if (enclosing.length === 0) return mappingField(segments);
+    return {
+        $cond: [
+            enclosing.length === 1 ? enclosing[0] : { $and: enclosing },
+            mappingField(segments),
+            null,
+        ],
+    };
+}
+
+/**
+ * Orders values like jsonb: strings < numbers < booleans < arrays < objects,
+ * scalars by value within their type. Null and absent values sort last in
+ * both directions.
+ */
+function sortKey(path) {
+    const type = { $type: '$$value' };
+    return {
+        $let: {
+            vars: { value: resolvePath(path) },
+            in: {
+                missing: isAbsent('$$value'),
+                rank: {
+                    $switch: {
+                        branches: SORT_TYPE_RANKS.map((types, i) => ({
+                            case: { $in: [type, types] },
+                            then: i + 1,
+                        })),
+                        default: 0,
+                    },
+                },
+                value: {
+                    $cond: [{ $in: [type, SCALAR_TYPES] }, '$$value', null],
+                },
+            },
+        },
+    };
+}
+
+function sortSpec(orderBy) {
+    if (!orderBy) return { _id: 1 };
+    const direction = MONGO_DIRECTIONS[orderBy.direction];
+    return {
+        [`${SORT_KEY}.missing`]: 1,
+        [`${SORT_KEY}.rank`]: direction,
+        [`${SORT_KEY}.value`]: direction,
+        _id: direction,
+    };
+}
+
+function omitProjection(omit) {
+    return Object.fromEntries(omit.map((key) => [`mapping.${key}`, 0]));
+}
+
+module.exports = { buildMappingQueryStages };

package/integrations/repositories/integration-mapping-query.js

@@ -0,0 +1,193 @@
+const SEGMENT_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_TAKE = 500;
+const MAX_IN_VALUES = 500;
+const MAX_CONDITIONS = 20;
+const DIRECTIONS = ['asc', 'desc'];
+
+const OPERATORS = {
+    exists: { fields: ['mapping'] },
+    notExists: { fields: ['mapping'] },
+    in: { fields: ['mapping'], value: toStringList },
+    notStartsWith: { fields: ['sourceId'], value: toPrefix },
+};
+
+/**
+ * Checks a queryMappings query and normalizes it for an adapter.
+ *
+ * @param {Object} query - See IntegrationMappingRepositoryInterface.queryMappings
+ * @returns {{where: Array<Object>, orderBy: ({path: string[], direction: 'asc'|'desc'}|null), skip: number, take: number, omit: string[]}}
+ * @throws {Error} When the query does not fit that shape
+ */
+function validateMappingQuery(query) {
+    if (!isPlainObject(query)) {
+        throw new Error('queryMappings: query must be an object');
+    }
+    const { where = [], orderBy, skip = 0, take, omit = [] } = query;
+    if (!Array.isArray(where)) {
+        throw new Error('queryMappings: where must be an array');
+    }
+    if (!Number.isInteger(take) || take < 1 || take > MAX_TAKE) {
+        throw new Error(
+            `queryMappings: take must be an integer between 1 and ${MAX_TAKE}`
+        );
+    }
+    if (!Number.isSafeInteger(skip) || skip < 0) {
+        throw new Error('queryMappings: skip must be a non-negative integer');
+    }
+    if (
+        !Array.isArray(omit) ||
+        !omit.every((key) => typeof key === 'string' && SEGMENT_REGEX.test(key))
+    ) {
+        throw new Error(
+            `queryMappings: omit must be an array of top-level mapping keys matching ${SEGMENT_REGEX}`
+        );
+    }
+
+    const whereEntries = where.map(toWhereEntry);
+    const conditionCount = whereEntries.reduce(
+        (count, entry) => count + (entry.anyOf ? entry.anyOf.length : 1),
+        0
+    );
+    if (conditionCount > MAX_CONDITIONS) {
+        throw new Error(
+            `queryMappings: where must have at most ${MAX_CONDITIONS} conditions, anyOf members included`
+        );
+    }
+
+    return {
+        where: whereEntries,
+        orderBy: orderBy === undefined ? null : toOrderBy(orderBy),
+        skip,
+        take,
+        omit,
+    };
+}
+
+function toOrderBy(orderBy) {
+    if (!isPlainObject(orderBy)) {
+        throw new Error('queryMappings: orderBy must be an object');
+    }
+    const { field, segments } = parsePath(orderBy.path);
+    if (field !== 'mapping') {
+        throw new Error(
+            "queryMappings: orderBy.path must be a mapping path ('mapping.<segment>...')"
+        );
+    }
+    if (!DIRECTIONS.includes(orderBy.direction)) {
+        throw new Error(
+            "queryMappings: orderBy.direction must be 'asc' or 'desc'"
+        );
+    }
+    return { path: segments, direction: orderBy.direction };
+}
+
+function toWhereEntry(entry) {
+    assertWhereEntryShape(entry);
+    if (!('anyOf' in entry)) return toCondition(entry);
+
+    const { anyOf } = entry;
+    if (!Array.isArray(anyOf) || anyOf.length === 0) {
+        throw new Error('queryMappings: anyOf must be a non-empty array');
+    }
+    return {
+        anyOf: anyOf.map((condition) => {
+            assertWhereEntryShape(condition);
+            if ('anyOf' in condition) {
+                throw new Error('queryMappings: nested anyOf is not supported');
+            }
+            return toCondition(condition);
+        }),
+    };
+}
+
+function assertWhereEntryShape(entry) {
+    if (!isPlainObject(entry)) {
+        throw new Error('queryMappings: each where entry must be an object');
+    }
+}
+
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * `{ path: 'mapping.outbound.status', op: 'in', value: ['failed'] }` →
+ * `{ field: 'mapping', path: ['outbound', 'status'], op: 'in', value: ['failed'] }`.
+ * A `sourceId` condition has no `path`; an op without a value has no `value`.
+ */
+function toCondition({ path, op, value }) {
+    const { field, segments } = parsePath(path);
+    const operator = Object.hasOwn(OPERATORS, op) ? OPERATORS[op] : null;
+    if (!operator?.fields.includes(field)) {
+        throw new Error(
+            `queryMappings: op ${JSON.stringify(
+                op
+            )} is not allowed on '${path}' (allowed: ${operatorsOn(field).join(
+                ', '
+            )})`
+        );
+    }
+    return {
+        field,
+        ...(segments.length > 0 && { path: segments }),
+        op,
+        ...(operator.value && { value: operator.value(value, path) }),
+    };
+}
+
+function operatorsOn(field) {
+    return Object.keys(OPERATORS).filter((op) =>
+        OPERATORS[op].fields.includes(field)
+    );
+}
+
+function toStringList(value, path) {
+    if (
+        !Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((v) => typeof v === 'string')
+    ) {
+        throw new Error(
+            `queryMappings: 'in' value must be a non-empty array of strings on '${path}'`
+        );
+    }
+    if (value.length > MAX_IN_VALUES) {
+        throw new Error(
+            `queryMappings: 'in' value must have at most ${MAX_IN_VALUES} strings on '${path}'`
+        );
+    }
+    return value;
+}
+
+function toPrefix(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(
+            `queryMappings: 'notStartsWith' value must be a non-empty string on '${path}'`
+        );
+    }
+    return value;
+}
+
+/**
+ * `'mapping.outbound.status'` → `{ field: 'mapping', segments: ['outbound', 'status'] }`,
+ * `'sourceId'` → `{ field: 'sourceId', segments: [] }`.
+ */
+function parsePath(path) {
+    const [field, ...segments] =
+        typeof path === 'string' ? path.split('.') : [];
+    const valid =
+        (field === 'sourceId' && segments.length === 0) ||
+        (field === 'mapping' &&
+            segments.length > 0 &&
+            segments.every((segment) => SEGMENT_REGEX.test(segment)));
+    if (!valid) {
+        throw new Error(
+            `queryMappings: invalid path ${JSON.stringify(
+                path
+            )} (must be 'sourceId' or 'mapping.<segment>...' with segments matching ${SEGMENT_REGEX})`
+        );
+    }
+    return { field, segments };
+}
+
+module.exports = { validateMappingQuery };