@cisstech/nestjs-expand/src/lib/expand.js

A NestJS module to build Dynamic Resource Expansion for APIs

"use strict";
/* eslint-disable @typescript-eslint/ban-types */
/* eslint-disable @typescript-eslint/no-explicit-any */
Object.defineProperty(exports, "__esModule", { value: true });
exports.DEFAULT_EXPAND_CONFIG = exports.EXPAND_CONFIG = exports.Selectable = exports.Expandable = exports.UseExpansionMethod = exports.ExpanderMethods = exports.Expander = exports.SELECTABLE_KEY = exports.USE_EXPANSION_METHOD_KEY = exports.EXPANDABLE_KEY = exports.EXPANDER_METHODS_KEY = exports.EXPANDER_KEY = void 0;
const common_1 = require("@nestjs/common");
require("reflect-metadata"); // Import reflect-metadata
/**
 * Symbol key for metadata associated with expanders.
 */
exports.EXPANDER_KEY = Symbol('EXPANDER');
/**
 * Symbol key for metadata associated with classes containing reusable expander methods.
 */
exports.EXPANDER_METHODS_KEY = Symbol('EXPANDER_METHODS'); // Renamed from REUSABLE_EXPANDER_KEY
/**
 * Symbol key for metadata associated with expandable parameters on controller/expander methods.
 */
exports.EXPANDABLE_KEY = Symbol('EXPANDABLE');
/**
 * Symbol key for metadata associated with linking reusable expander methods.
 */
exports.USE_EXPANSION_METHOD_KEY = Symbol('USE_EXPANSION_METHOD');
/**
 * Symbol key for metadata associated with selectable parameters.
 */
exports.SELECTABLE_KEY = Symbol('SELECTABLE');
/**
 * Decorator function to mark a class as a standard expander for a specific DTO.
 *
 * @remarks
 * - The class must be a NestJS provider.
 * - Methods on this class matching requested expansion fields will be called.
 *
 * @param target - The DTO class this expander is responsible for.
 * @returns A metadata decorator.
 */
const Expander = (target) => (0, common_1.SetMetadata)(exports.EXPANDER_KEY, target);
exports.Expander = Expander;
/**
 * Decorator function to mark a class as containing reusable expansion methods.
 *
 * @remarks
 * - The class must be a NestJS provider.
 * - Methods from this class can be linked to specific fields in standard @Expander
 *   classes using @UseExpansionMethod.
 *
 * @param params - Optional parameters.
 * @returns A metadata decorator.
 */
const ExpanderMethods = (params) => (0, common_1.SetMetadata)(exports.EXPANDER_METHODS_KEY, params ?? {}); // Renamed from ReusableExpander
exports.ExpanderMethods = ExpanderMethods;
/**
 * Decorator function to link a field in an @Expander class to a method
 * in a @ExpanderMethods class. Applied at the CLASS level of an @Expander.
 * Can be applied multiple times for different fields.
 *
 * @typeparam TParentResource - The type of the parent DTO (automatically inferred if possible).
 * @typeparam TReusableExpander - The type of the reusable expander class.
 *
 * @param config - Configuration detailing the field name, reusable class, method, and parameter mapping.
 * @returns A ClassDecorator.
 */
const UseExpansionMethod = (config) => {
    // Explicitly return a ClassDecorator
    return (target) => {
        // target is the class constructor
        // Retrieve existing metadata array or initialize a new one
        const existingMetadata = Reflect.getMetadata(exports.USE_EXPANSION_METHOD_KEY, target) || [];
        // Add the new configuration
        existingMetadata.push(config);
        // Store the updated array back onto the class
        Reflect.defineMetadata(exports.USE_EXPANSION_METHOD_KEY, existingMetadata, target);
    };
};
exports.UseExpansionMethod = UseExpansionMethod;
/**
 * Decorator controller/expander method as expandable (for recursive expansion).
 * Also used on controller endpoints to enable expansion for the response.
 *
 * @remarks
 * - When used on an @Expander method, enables recursive expansion if that method's return value is requested for further expansion.
 * - When used on a controller endpoint, enables expansion for the DTO returned by that endpoint.
 *
 * @param target - The DTO class returned by the method/endpoint.
 * @param config - Additional configuration for expandable parameters.
 * @returns A metadata decorator.
 */
const Expandable = (target, config) => (0, common_1.SetMetadata)(exports.EXPANDABLE_KEY, { target, ...config });
exports.Expandable = Expandable;
/**
 * Decorator function to mark a controller endpoint response as selectable.
 *
 * @remarks
 * - You can mark all endpoints of your app as selectable by setting the {@link ExpandConfig.enableGlobalSelection} option of the `NestKitExpandModule.forRoot()`.
 *
 * @returns A metadata decorator.
 */
const Selectable = (config) => (0, common_1.SetMetadata)(exports.SELECTABLE_KEY, config ?? {});
exports.Selectable = Selectable;
/**
 * Injection token for the ExpandConfig.
 */
exports.EXPAND_CONFIG = Symbol('EXPAND_CONFIG');
exports.DEFAULT_EXPAND_CONFIG = {
    enableLogging: true,
    enableGlobalSelection: false,
    selectQueryParamName: 'selects',
    expandQueryParamName: 'expands',
    logLevel: 'warn',
    errorHandling: {
        includeErrorsInResponse: false,
        defaultErrorPolicy: 'ignore',
        errorResponseShape: (error, path) => ({
            message: error.message,
            path,
        }),
    },
};
//# sourceMappingURL=expand.js.map