@proventuslabs/nestjs-multipart-form/dist/fields/decorator.js

A lightweight and efficient NestJS package for handling multipart form data and file uploads with RxJS streaming support and type safety.

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.MultipartFields = void 0;
exports.multipartFieldsFactory = multipartFieldsFactory;
const common_1 = require("@nestjs/common");
const rxjs_1 = require("rxjs");
const utils_1 = require("../core/utils");
const operators_1 = require("./operators");
function multipartFieldsFactory(options, ctx) {
    if (ctx.getType() !== "http")
        return rxjs_1.EMPTY;
    const request = ctx.switchToHttp().getRequest();
    const fields$ = request._fields$;
    if (!fields$)
        return rxjs_1.EMPTY;
    // 'undefined' - return all fields without validation
    if (options === undefined)
        return fields$;
    const { required: requiredPatterns, all: allPatterns } = (0, utils_1.parseDecoratorOptions)(options);
    return fields$.pipe((0, operators_1.filterFieldsByPatterns)(allPatterns), (0, operators_1.validateRequiredFields)(requiredPatterns));
}
/**
 * Extract and validate multipart form fields from the request.
 *
 * The decorator returns an Observable that emits MultipartField objects.
 * It automatically handles field validation and will throw a MissingFieldsError if required fields are missing.
 *
 * @param options - Optional configuration for field validation. Can be:
 *   - A string: treated as a single required field name or pattern
 *   - An array of field specifications: each element can be either a string (required field/pattern)
 *     or a tuple [fieldname: string, required?: boolean] where required defaults to true
 *   - undefined: returns all fields without validation
 *
 *   Field patterns support a "starts with" syntax by prefixing with "^":
 *   - "fieldname": matches exactly "fieldname"
 *   - "^prefix_": matches any field that starts with "prefix_"
 *
 * @returns A parameter decorator that can be applied to controller method parameters
 * @throws {MissingFieldsError} When required fields are missing from the multipart form
 *
 * @example
 * ‍@Post('upload')
 * async uploadFile(
 *   ‍@MultipartFields(['file', ['description', false]]) fields: Observable<MultipartField>
 * ) {
 *   // Fields will emit each valid field as it's processed.
 *   // 'file' is required, 'description' is optional.
 *   return fields.pipe(
 *     map(field => field.name),
 *     toArray()
 *   );
 * }
 *
 * // Single required field:
 * ‍@Post('upload')
 * async uploadFile(
 *   ‍@MultipartFields('file') fields: Observable<MultipartField>
 * ) {
 *   // Only 'file' field will be emitted.
 * }
 *
 * // All fields without validation:
 * ‍@Post('upload')
 * async uploadFile(
 *   ‍@MultipartFields() fields: Observable<MultipartField>
 * ) {
 *   // All multipart fields will be emitted.
 * }
 *
 * // Using "starts with" pattern matching:
 * ‍@Post('upload')
 * async uploadFile(
 *   ‍@MultipartFields('^user_') fields: Observable<MultipartField>
 * ) {
 *   // Will emit fields like: user_name, user_email, user_avatar, etc.
 * }
 *
 * // Mixed exact and pattern matching:
 * ‍@Post('upload')
 * async uploadFile(
 *   ‍@MultipartFields(['avatar', '^user_', ['metadata', false]]) fields: Observable<MultipartField>
 * ) {
 *   // 'avatar' is required (exact match).
 *   // Any field starting with 'user_' is required.
 *   // 'metadata' is optional (exact match).
 * }
 */
exports.MultipartFields = (0, common_1.createParamDecorator)(multipartFieldsFactory);
//# sourceMappingURL=decorator.js.map