@docupace/ihub-config 1.1.23 → 1.1.24-admin.1

package/dist/config-service.js

@@ -11,8 +11,194 @@ import { builtInProviders } from './providers/index.js';
 import { deepMergeResolvers, } from './resolvers/index.js';
 import { dump, load } from 'js-yaml';
 import { buildQuery } from '@docupace/ihub-core/query';
+import jp from 'jsonpath';
 const FULL_OBJECT_EXPRESSION_PATTERN = /^\${(.*?)}$/;
 const INLINE_OBJECT_EXPRESSION_PATTERN = /\${(.*?)}/g;
+function isNamedObjectArray(value) {
+    return (Array.isArray(value) &&
+        value.every((item) => item !== null &&
+            typeof item === 'object' &&
+            typeof item.name === 'string'));
+}
+// An override element counts as "self-contained" when it carries enough of
+// its own definition to render on its own — a real attribute path (or paths)
+// or a computed expression — as opposed to a thin `{ name, visible }`-style
+// reference that only makes sense resolved against a base/predefined
+// counterpart of the same name. `paths` (plural) is `Column`'s shape;
+// `path` (singular) is `TableCriteria`'s — both must count, or a resolved
+// filter-criterion `$ref` (which only ever has a singular `path`) is wrongly
+// treated as a dangling reference and silently dropped, even though it just
+// resolved successfully.
+function isSelfContainedOverrideElement(item) {
+    const paths = item.paths;
+    return ((Array.isArray(paths) && paths.length > 0) ||
+        (typeof item.path === 'string' && item.path.length > 0) ||
+        (typeof item.expression === 'string' && item.expression.length > 0));
+}
+/**
+ * Merge semantics for a config sub-path override against the value already
+ * at that JSONPath. Generic — used for any typename/sub-path the
+ * configPath/subPath mechanism resolves, not just `Table.columns`.
+ *
+ * When both the current value and the override value are arrays of objects
+ * each carrying a string `name`, override elements are merged onto their
+ * base counterpart by name (override wins per-attribute, everything else
+ * inherited) instead of the override replacing the array wholesale. This is
+ * what makes a saved override non-destructive:
+ * - Reordering falls out of the override array's own element order.
+ * - "Hiding" an element is an attribute override (e.g. `visible: false`) on
+ *   an element that's still present, not a deletion.
+ * - A base element the override never mentions is appended unchanged, so a
+ *   base element added later still surfaces for someone with an existing
+ *   override, instead of being permanently absent from their frozen array.
+ * - An override element naming something not found in the base is kept
+ *   as-is when it's self-contained (has its own path(s)/expression — e.g. a
+ *   hand-authored column), or silently dropped when it's a thin reference
+ *   whose target (e.g. a predefined column) no longer exists — this never
+ *   throws; the stale reference just doesn't round-trip into the next save.
+ *
+ * Any other shape (scalars, plain objects, arrays without a `name` key) is
+ * returned untouched, so the caller's plain whole-value replace applies
+ * exactly as it did before this merge existed.
+ */
+function mergeSubPathOverrideValue(base, override) {
+    if (!isNamedObjectArray(override) || !isNamedObjectArray(base)) {
+        return override;
+    }
+    const baseByName = new Map(base.map((item) => [item.name, item]));
+    const merged = [];
+    const seenNames = new Set();
+    for (const overrideItem of override) {
+        // Guard against a corrupted/hand-edited override array carrying two
+        // elements with the same name — only the first is kept, so the merged
+        // result never has duplicate names.
+        if (seenNames.has(overrideItem.name)) {
+            continue;
+        }
+        seenNames.add(overrideItem.name);
+        const baseItem = baseByName.get(overrideItem.name);
+        if (baseItem) {
+            merged.push({ ...baseItem, ...overrideItem });
+        }
+        else if (isSelfContainedOverrideElement(overrideItem)) {
+            merged.push(overrideItem);
+        }
+        // else: a thin reference to a name that no longer resolves — drop it.
+    }
+    const mergedNames = new Set(merged.map((item) => item.name));
+    const untouchedBaseItems = base.filter((item) => !mergedNames.has(item.name));
+    return [...merged, ...untouchedBaseItems];
+}
+// Marks each element of a fully-folded named-object array with whether it
+// would still be present (by name) without the narrowest override layer —
+// i.e. whether hiding it (rather than deleting it outright) is required to
+// suppress it, since deleting it would just have the next resolution fold
+// bring it back from a broader layer. `withoutInnermost` is the same
+// broadest-to-narrowest fold as `mergedValue`, minus its last (narrowest)
+// layer — see `applyConfigPathOverride`, where both folds are computed.
+// Only stamps when both values are named-object arrays; any other shape
+// (scalar, plain object, unnamed array) is returned unchanged, mirroring
+// `mergeSubPathOverrideValue`'s own shape guard.
+function stampInherited(mergedValue, withoutInnermost) {
+    if (!isNamedObjectArray(mergedValue) ||
+        !isNamedObjectArray(withoutInnermost)) {
+        return mergedValue;
+    }
+    const inheritedNames = new Set(withoutInnermost.map((item) => item.name));
+    return mergedValue.map((item) => ({
+        ...item,
+        inherited: inheritedNames.has(item.name),
+    }));
+}
+function isRefElement(item) {
+    return (item !== null &&
+        typeof item === 'object' &&
+        typeof item.$ref === 'string');
+}
+// Resolves a config-path override array element's fragment-only `$ref`
+// (e.g. `"#$.predefinedColumns[?(@.name=='email')]"`) against `refRoot` —
+// the config-path's own sibling fields, not another file. This is
+// deliberately narrower than `template`'s YAML `$ref` (processed by
+// `processReferencedObject`/`getRefConfig`, which loads another config
+// file): an override-array `$ref` only ever supports the `#<jsonpath>`
+// self-reference form, resolved with the already-vendored `jsonpath`
+// package (the same one `applyConfigPathOverride` uses for `subPath`
+// strings). A ref that doesn't start with `#`, resolves to nothing, or
+// resolves to a non-object is treated the same as any other unresolved
+// override reference elsewhere in this module — silently dropped rather
+// than thrown, so a stale reference just doesn't round-trip into the next
+// save. Multiple matches take the first, in JSONPath document order.
+//
+// The resolved object keeps the original fragment string under `ref` (not
+// `$ref` — GraphQL field names can't start with `$`) rather than dropping
+// it once resolved. Without this, a client re-saving the array unchanged
+// (e.g. reordering a different column) would have no way to tell this
+// element apart from a plain inline column and would flatten it back into
+// a frozen copy on that save — exactly the staleness problem `$ref` exists
+// to avoid. `Column.ref` (the GraphQL field) surfaces it back to the client
+// so `docupace-ui-main` can keep re-emitting the same `$ref` indefinitely.
+function resolveOverrideElementRef(item, refRoot) {
+    const ref = item.$ref;
+    if (!ref.startsWith('#')) {
+        return undefined;
+    }
+    const [match] = jp.query(refRoot, ref.slice(1));
+    if (match === null || typeof match !== 'object') {
+        return undefined;
+    }
+    const { $ref: _unusedRef, ...localOverrides } = item;
+    return {
+        ...match,
+        ...localOverrides,
+        ref,
+    };
+}
+// Expands any `$ref` elements of a config-path override array into the
+// full object they point at (merged with whatever local attributes the
+// element carries alongside `$ref`, e.g. `visible`) before the array is
+// handed to `mergeSubPathOverrideValue`. Runs first so that a `{ $ref,
+// visible }` stub — which has no `name` of its own — always arrives at the
+// name-keyed merge as a proper named object; `mergeSubPathOverrideValue`
+// itself needs no `$ref` awareness.
+function expandRefOverrideElements(value, refRoot) {
+    if (!Array.isArray(value)) {
+        return value;
+    }
+    return value
+        .map((item) => isRefElement(item) ? resolveOverrideElementRef(item, refRoot) : item)
+        .filter((item) => item !== undefined);
+}
+// Builds the object a config-path override's `$ref` fragments resolve
+// against: the config being overridden, overlaid with the *raw* (not yet
+// merged) override value of every other simple top-level subPath in this
+// same patch (e.g. `$.predefinedColumns`). Using the raw override value
+// rather than depending on loop order elsewhere in
+// `applyConfigPathOverride` means a `$.columns` override's `$ref` into
+// `$.predefinedColumns` resolves correctly regardless of which subPath
+// happens to be processed first. Only single-segment paths (`$.foo`) are
+// overlaid — nested subPaths (`$.filter.criteria`) fall back to whatever
+// value is already on `config`, which is fine since nothing currently
+// needs to `$ref` into a nested subPath.
+//
+// `subPathPatch` now carries an *ordered* array of layers per jsonPath
+// (broadest to narrowest — see `ConfigurationOverrideResult.subPaths`), not
+// a single already-resolved value. The overlay uses only the narrowest
+// (last) layer, same approximation as before cascading existed: a catalog
+// like `$.predefinedColumns`/`$.predefinedFilters` is always saved as a full
+// replacement at a single scope in practice (never a partial patch spread
+// across tiers), so the narrowest present layer already *is* effectively
+// the whole value — exactly what this overlay used before this function
+// took an array at all.
+function buildRefResolutionRoot(config, subPathPatch) {
+    const overlay = {};
+    for (const [jsonPath, layers] of Object.entries(subPathPatch)) {
+        const topLevelMatch = /^\$\.([^.[]+)$/.exec(jsonPath);
+        if (topLevelMatch && layers.length) {
+            overlay[topLevelMatch[1]] = layers[layers.length - 1];
+        }
+    }
+    return { ...config, ...overlay };
+}
 export class ConfigFileStore {
     localPath;
     remotePath;
@@ -155,6 +341,7 @@ class ConfigService {
     configInjectorResolvers;
     providers;
     resolvers;
+    configurationOverrideProvider;
     constructor(model, configStores, extensionOptions = {}) {
         this.configStores = configStores;
         this.model = model;
@@ -167,6 +354,8 @@ class ConfigService {
         this.resolvers = extensionOptions.resolvers
             ? { ...extensionOptions.resolvers }
             : {};
+        this.configurationOverrideProvider =
+            extensionOptions.configurationOverrideProvider;
         if (this.model) {
             this.generateResolvers();
         }
@@ -232,12 +421,34 @@ class ConfigService {
         }
         return processedData;
     }
+    applyReferenceExtensions(processedData, referenceConfig) {
+        if (typeof referenceConfig?.extend !== 'object') {
+            return processedData;
+        }
+        const { extend } = referenceConfig;
+        for (const key in extend) {
+            const extensionValue = extend[key];
+            if (!Array.isArray(extensionValue)) {
+                throw new GraphQLError(`$ref.extend.${key} must be an array; received ${typeof extensionValue}`);
+            }
+            const baseValue = processedData[key];
+            if (baseValue === undefined) {
+                processedData[key] = extensionValue;
+                continue;
+            }
+            if (!Array.isArray(baseValue)) {
+                throw new GraphQLError(`$ref.extend.${key} can only extend an array property; "${key}" resolved to ${typeof baseValue}`);
+            }
+            processedData[key] = [...baseValue, ...extensionValue];
+        }
+        return processedData;
+    }
     async processReferencedObject(configPath, obj, context, values) {
         const referenceConfig = obj.$ref;
         const refConfigPath = typeof referenceConfig === 'object' && referenceConfig.refPath
             ? referenceConfig.refPath
             : referenceConfig;
-        const imageData = await this.processImageReference(refConfigPath);
+        const imageData = await this.processImageReference(refConfigPath, context);
         if (imageData) {
             return imageData;
         }
@@ -246,6 +457,7 @@ class ConfigService {
             ? this.updatePathValues(referencedData, referenceConfig.path)
             : referencedData;
         processedData = this.applyReferenceOverrides(processedData, referenceConfig);
+        processedData = this.applyReferenceExtensions(processedData, referenceConfig);
         processedData = await this.processObjectExpressions(processedData, values, context);
         return this.processObject(configPath, processedData, context, values);
     }
@@ -262,7 +474,16 @@ class ConfigService {
             const builtInQueryResolvers = {
                 pages: () => ({
                     getPageConfig: async (obj, context) => {
-                        const pageConfig = await this.getPageConfig(obj.path, context, true, obj.context);
+                        // `impersonateRoleId`/`impersonateGeneral` are a plain
+                        // pass-through onto context here — this engine never inspects
+                        // identity itself; the host's resolveCurrentIdentity is what
+                        // interprets them and enforces the admin-only restriction.
+                        const impersonation = obj.impersonateRoleId
+                            ? { impersonateRoleId: obj.impersonateRoleId }
+                            : obj.impersonateGeneral
+                                ? { impersonateGeneral: true }
+                                : null;
+                        const pageConfig = await this.getPageConfig(obj.path, impersonation ? { ...context, ...impersonation } : context, true, obj.context);
                         return pageConfig;
                     },
                     getAIConfig: async (obj, context) => {
@@ -346,29 +567,37 @@ class ConfigService {
             return deepMergeResolvers(builtInMutationResolvers, hostMutationResolvers);
         };
     }
-    async processConfig(config, context, processProviders) {
+    // Applies any stored config-path sub-path overrides across the whole
+    // config tree before processConfig's own recursive walk runs, so that
+    // overridden values (which may introduce new sub-config) still go
+    // through provider injection/__typename dispatch below.
+    //
+    // rootSubPathOverrides lets a caller that already resolved overrides for
+    // the root config (e.g. getConfigFromStore, which fetches the whole-object
+    // and sub-path overrides together in one round trip) hand them in directly
+    // instead of having the root node re-resolved a second time below; nested
+    // nodes discovered deeper in the tree are still resolved individually,
+    // since their configPaths aren't known until the tree has been loaded.
+    async processConfig(config, context, processProviders, rootSubPathOverrides) {
+        const overriddenConfig = await this.applyConfigPathOverride(config, context, processProviders, rootSubPathOverrides);
+        return this.processConfigTree(overriddenConfig, context, processProviders);
+    }
+    async processConfigTree(config, context, processProviders) {
         if (!config) {
             return config;
         }
         // Handle arrays
         if (Array.isArray(config)) {
-            return Promise.all(config.map((item) => this.processConfig(item, context, processProviders)));
+            return Promise.all(config.map((item) => this.processConfigTree(item, context, processProviders)));
         }
         // Handle objects
         if (typeof config === 'object') {
             // Recursively process all properties of config
             let processedConfig = { ...config };
             for (const key in processedConfig) {
-                processedConfig[key] = await this.processConfig(processedConfig[key], context, processProviders);
-            }
-            // First process the current object if it has __typename
-            if (processedConfig?.__typename && processProviders) {
-                const providerClass = this.providers[processedConfig.__typename];
-                if (providerClass) {
-                    const provider = new providerClass();
-                    processedConfig = await provider.processConfig(processedConfig, this, context);
-                }
+                processedConfig[key] = await this.processConfigTree(processedConfig[key], context, processProviders);
             }
+            processedConfig = await this.applyTypenameProvider(processedConfig, context, processProviders);
             return processedConfig;
         }
         if (processProviders) {
@@ -376,6 +605,97 @@ class ConfigService {
         }
         return config;
     }
+    // Walks the whole config tree up front (pre-order) and, for every object
+    // that declares a configPath, deep-sets any stored sub-path overrides
+    // (JSONPath-addressed, e.g. "$.columns" or "$.filter.criteria").
+    //
+    // preFetchedSubPaths is only honored for the root node of the walk (the
+    // one being called with a defined third argument); nested calls always
+    // omit it so their own configPath gets resolved fresh.
+    async applyConfigPathOverride(config, context, processProviders, preFetchedSubPaths) {
+        if (!config) {
+            return config;
+        }
+        if (Array.isArray(config)) {
+            return Promise.all(config.map((item) => this.applyConfigPathOverride(item, context, processProviders)));
+        }
+        if (typeof config !== 'object') {
+            return config;
+        }
+        let result = config;
+        if (processProviders) {
+            const subPathPatch = preFetchedSubPaths !== undefined
+                ? preFetchedSubPaths
+                : result.configPath && this.configurationOverrideProvider
+                    ? (await this.configurationOverrideProvider.resolve(result.configPath, context)).subPaths
+                    : null;
+            if (subPathPatch) {
+                const refRoot = buildRefResolutionRoot(result, subPathPatch);
+                // Deep-clone once, up front — `jp.value` mutates its target in
+                // place, and a shallow `{ ...result }` per jsonPath only protects
+                // the top level. A nested subPath (e.g. `$.filter.criteria`) would
+                // otherwise still mutate `result.filter`, which is the *same*
+                // object reference as the original, potentially-shared config
+                // (e.g. reused across tables via `extend`/fragment composition).
+                // Config values are always plain JSON (from YAML/domain storage),
+                // so a JSON round-trip clone is sufficient and avoids
+                // `structuredClone`'s cross-realm `instanceof` pitfalls (its output
+                // fails `instanceof Object` checks — e.g. inside the `jsonpath`
+                // package — when the calling code runs in a different VM
+                // realm/context, as test sandboxes commonly do).
+                result = JSON.parse(JSON.stringify(result));
+                for (const [jsonPath, layers] of Object.entries(subPathPatch)) {
+                    // A single malformed override (an unparseable `$ref` JSONPath, or
+                    // a jsonPath that doesn't resolve to a settable location) must not
+                    // abort resolution of the rest of this config tree — that would
+                    // take down the page for every user over one bad admin-authored
+                    // row. Log and skip just this jsonPath instead.
+                    try {
+                        const currentValue = jp.value(result, jsonPath);
+                        const expandedLayers = layers.map((layer) => expandRefOverrideElements(layer, refRoot));
+                        // `layers` is ordered broadest to narrowest (general, tenant,
+                        // role, user — see `ConfigurationOverrideResult.subPaths`), so
+                        // folding them in order onto `currentValue` cascades correctly:
+                        // each layer only patches what it mentions, inheriting
+                        // everything else from the fold so far. Folding every layer
+                        // except the last gives "what this identity would see without
+                        // its own narrowest override" — the last layer is guaranteed to
+                        // be whichever tier actually has a row for this identity (the
+                        // same tier `pickWinner` would have picked pre-cascading), so
+                        // this is exactly the reference `inherited` needs.
+                        const mergedValue = expandedLayers.reduce(mergeSubPathOverrideValue, currentValue);
+                        const withoutInnermost = expandedLayers
+                            .slice(0, -1)
+                            .reduce(mergeSubPathOverrideValue, currentValue);
+                        const finalValue = stampInherited(mergedValue, withoutInnermost);
+                        const applied = jp.value(result, jsonPath, finalValue);
+                        if (applied === undefined) {
+                            throw new Error(`does not resolve to a settable location: "${jsonPath}"`);
+                        }
+                    }
+                    catch (error) {
+                        log.warn(`Skipping configuration override for "${result.configPath}" at "${jsonPath}": ${error.message}`);
+                    }
+                }
+            }
+        }
+        const overriddenEntries = await Promise.all(Object.entries(result).map(async ([key, value]) => [
+            key,
+            await this.applyConfigPathOverride(value, context, processProviders),
+        ]));
+        return Object.fromEntries(overriddenEntries);
+    }
+    async applyTypenameProvider(processedConfig, context, processProviders) {
+        if (!processedConfig?.__typename || !processProviders) {
+            return processedConfig;
+        }
+        const providerClass = this.providers[processedConfig.__typename];
+        if (!providerClass) {
+            return processedConfig;
+        }
+        const provider = new providerClass();
+        return await provider.processConfig(processedConfig, this, context);
+    }
     async getRefConfig(configPath, refConfigPath, context, values) {
         let fullPath;
         if (refConfigPath.startsWith('.')) {
@@ -462,13 +782,21 @@ class ConfigService {
         };
         return await processValue(object);
     }
-    async processImageReference(refConfigPath) {
+    async processImageReference(refConfigPath, context) {
         const SUPPORTED_IMAGE_FORMATS = ['.jpg', '.jpeg', '.png', '.svg'];
         // Check if the reference is an image file
         const ext = path.extname(refConfigPath).toLowerCase();
         if (!SUPPORTED_IMAGE_FORMATS.includes(ext)) {
             return null;
         }
+        const override = await this.configurationOverrideProvider?.resolve(refConfigPath, context);
+        if (override?.whole?.contentType) {
+            return {
+                data: override.whole.value,
+                mimeType: override.whole.contentType,
+                hash: createHash('sha256').update(override.whole.value).digest('hex'),
+            };
+        }
         let standardStore;
         for (const store of this.configStores) {
             if (store instanceof ConfigFileStore) {
@@ -520,19 +848,31 @@ class ConfigService {
                 return 'application/octet-stream';
         }
     }
-    async getConfigFromStore(path) {
+    // Resolves the whole-object override and any sub-path overrides for
+    // configPath together, in one provider round trip, instead of fetching
+    // them separately at different points of the processing pipeline. The
+    // sub-path overrides are handed back alongside the config so callers can
+    // thread them into processConfig rather than re-resolving them later.
+    async getConfigFromStore(configPath, context) {
+        const override = await this.configurationOverrideProvider?.resolve(configPath, context);
+        const subPathOverrides = override?.subPaths ?? null;
+        if (override?.whole && !override.whole.contentType) {
+            return { config: load(override.whole.value), subPathOverrides };
+        }
         const exceptions = [];
         for (const [index, configStore] of this.configStores.entries()) {
             try {
-                return await configStore.getConfig(path);
+                const config = await configStore.getConfig(configPath);
+                return { config, subPathOverrides };
             }
             catch (e) {
                 exceptions.push(e);
                 if (index == this.configStores.length - 1) {
-                    throw new GraphQLError(`Config not found in path in any store: ${path}`, { originalError: exceptions });
+                    throw new GraphQLError(`Config not found in path in any store: ${configPath}`, { originalError: exceptions });
                 }
             }
         }
+        return { config: undefined, subPathOverrides };
     }
     async hasConfig(configPath) {
         return (await Promise.all(this.configStores.map((configStore) => configStore.hasConfig(configPath)))).some(Boolean);
@@ -542,9 +882,9 @@ class ConfigService {
         return this.getDirectConfig(globalPath, context, values, processProviders);
     }
     async getDirectConfig(configPath, context, values, processProviders) {
-        const obj = await this.getConfigFromStore(configPath);
+        const { config: obj, subPathOverrides } = await this.getConfigFromStore(configPath, context);
         const fullObj = await this.processObject(configPath, obj, context, values);
-        const processedObj = await this.processConfig(fullObj, context, processProviders);
+        const processedObj = await this.processConfig(fullObj, context, processProviders, subPathOverrides);
         return processedObj;
     }
     async listDirectConfigs(configPath) {
@@ -895,21 +1235,22 @@ class ConfigService {
     }
     async getPageConfig(pagePath, context, processConfig, rulesContext) {
         const globalPath = path.join('global', 'pages', pagePath);
-        const obj = await this.getConfigFromStore(globalPath);
+        const { config: obj, subPathOverrides } = await this.getConfigFromStore(globalPath, context);
         const fullObj = await this.processObject(globalPath, obj, context, null);
         const matchingRuleGroups = await this.getRuleGroups(rulesContext, context);
         const configToProcess = this.applyFieldRuleOverrides(fullObj, matchingRuleGroups);
-        return await this.processConfig(configToProcess, context, processConfig);
+        return await this.processConfig(configToProcess, context, processConfig, subPathOverrides);
     }
     async init() {
         return Promise.all(this.configStores.map((configStore) => configStore.init()));
     }
 }
-export const defaultConfigService = ({ model, configStores, configInjectorResolvers, providers, resolvers, }) => {
+export const defaultConfigService = ({ model, configStores, configInjectorResolvers, providers, resolvers, configurationOverrideProvider, }) => {
     const extensionOptions = {
         configInjectorResolvers,
         providers,
         resolvers,
+        configurationOverrideProvider,
     };
     return new ConfigService(model, configStores.map((configStore) => new ConfigFileStore(configStore)), extensionOptions);
 };