@cisstech/nestjs-expand/src/lib/expand.utils.d.ts

A NestJS module to build Dynamic Resource Expansion for APIs

import { ExpansionError } from './expand';
/**
 * A recursive object representing the properties to expand.
 * Each property is either a boolean or another ExpandTree.
 */
export type ExpansionThree = {
    [key: string]: ExpansionThree | boolean;
};
/**
 * Creates an ExpansionThree from a string or array of strings.
 *
 * @remarks
 * This function assumes that the object is already an ExpansionThree if it's an object.
 * @returns An ExpansionThree.
 */
export declare const createExpansionThree: (object?: string | string[] | ExpansionThree) => ExpansionThree;
/**
 * Masks an object with a given selection three.
 * @remarks
 * - Empty selection tree will return the target object as is.
 * - Array values are also supported. The selection tree at the array level will be applied to each item in the array.
 * - If a key is not present in the selection tree, it will be excluded from the result.
 * - `null` or `undefined` values will be returned as is.
 * @example
 * ```ts
 *
 * const targetObject = {
 *  a: 1,
 *  b: {
 *    c: 2,
 *    d: {
 *      e: 3,
 *      f: 4,
 *    },
 *    g: 5,
 *  },
 *  h: 6,
 * }
 *
 * const selectionTree = {
 *  '*': true,
 *   b: {
 *    d: {
 *      e: true,
 *    },
 *    g: true,
 *   },
 *   h: false
 * }
 *
 * const result = maskObjectWithThree(targetObject, selectionTree)
 *
 * // result = {
 * //   a: 1,
 * //   b: {
 * //     d: {
 * //       e: 3,
 * //     },
 * //     g: 5,
 * //   }
 * // }
 * ```
 *
 * @param target - The object to be masked.
 * @param selection - The selection criteria for masking.
 * @returns The masked object.
 */
export declare const maskObjectWithThree: (target: any, selection: ExpansionThree) => any;
/**
 * Handle expansion errors by attaching them to the response object.
 * For arrays, errors will be attached to individual items.
 * For objects, errors will be attached to the object directly.
 *
 * @param expansionErrors - Map of errors with their paths
 * @param result - Result object to attach errors to
 * @param includeErrors - Whether to include errors in the response
 */
export declare const handleExpansionErrors: (expansionErrors: Map<string, ExpansionError>, result: any, includeErrors?: boolean) => void;