arkos 2.0.0-next.3 → 2.0.0-next.30

package/dist/esm/utils/arkos-router/utils/helpers/upload-manager.js

@@ -7,10 +7,12 @@ import { removeBothSlashes } from "../../../helpers/text.helpers.js";
 import { promisify } from "util";
 import sheu from "../../../sheu.js";
 import AppError from "../../../../modules/error-handler/utils/app-error.js";
-import { extractRequestInfo, generateRelativePath, } from "../../../../modules/file-upload/utils/helpers/file-upload.helpers.js";
+import { extractRequestInfo, optimizeImage, } from "../../../../modules/file-upload/utils/helpers/file-upload.helpers.js";
 import deepmerge from "../../../helpers/deepmerge.helper.js";
 import { catchAsync } from "../../../../exports/error-handler/index.js";
-import { pascalCase } from "../../../helpers/change-case.helpers.js";
+import { isSafeUploadParam, normalizeUploadDir, normalizeUploadUrlPath, resolveUploadPath, } from "../../../../modules/file-upload/utils/helpers/upload-path.helper.js";
+import { uploadServingRegistry } from "../../../../modules/file-upload/utils/helpers/upload-serving.registry.js";
+import { ConflictError } from "../../../../modules/error-handler/utils/errors.js";
 function determineUploadDir(file) {
     if (file.mimetype.includes?.("image"))
         return "/images";
@@ -24,38 +26,396 @@ function determineUploadDir(file) {
         return "/documents";
     return "/files";
 }
+function getTemplateParams(template) {
+    return template
+        .split("/")
+        .filter((segment) => segment.startsWith(":"))
+        .map((segment) => segment.slice(1).replace(/\(.*\)$/, ""));
+}
+function substituteUploadTemplate(template, values, label) {
+    const missing = [];
+    const result = template
+        .split("/")
+        .map((segment) => {
+        if (!segment.startsWith(":"))
+            return segment;
+        const name = segment.slice(1).replace(/\(.*\)$/, "");
+        const value = values[name];
+        if (value === undefined) {
+            missing.push(name);
+            return segment;
+        }
+        if (!isSafeUploadParam(value))
+            throw new Error(`Invalid upload param ":${name}" for ${label}`);
+        return value;
+    })
+        .join("/");
+    if (missing.length > 0)
+        throw new Error(`Missing required upload param(s) ${missing
+            .map((name) => `":${name}"`)
+            .join(", ")} for ${label}.`);
+    return result;
+}
+function stripExtension(filename) {
+    const ext = path.extname(filename);
+    return ext ? filename.slice(0, -ext.length) : filename;
+}
+const RESERVED_FILE_NAMES = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;
+function isSafeFileName(filename) {
+    return (typeof filename === "string" &&
+        filename.length > 0 &&
+        filename.length <= 255 &&
+        !filename.includes("/") &&
+        !filename.includes("\\") &&
+        !filename.includes("\0") &&
+        filename !== "." &&
+        filename !== ".." &&
+        !/[. ]$/.test(filename) &&
+        !RESERVED_FILE_NAMES.test(filename));
+}
+function isInside(base, target) {
+    const relative = path.relative(base, target);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+function safeOriginalBaseName(file) {
+    const ext = path.extname(file.originalname);
+    const base = path
+        .basename(file.originalname, ext)
+        .replace(/[^A-Za-z0-9._ -]/g, "-")
+        .replace(/^[. ]+/, "");
+    return base || "file";
+}
 const storage = multer.diskStorage({
     destination: (req, file, cb) => {
-        const arkosConfig = getArkosConfig();
-        const baseUploadDir = arkosConfig.fileUpload?.baseUploadDir || "/uploads";
-        let uploadDir = req.headers["x-upload-dir"] || determineUploadDir(file);
-        req.headers["x-upload-dir"] = uploadDir;
-        const fullUploadDir = path.resolve(path.join(process.cwd(), baseUploadDir.replaceAll("//", "/"), uploadDir.replaceAll("//", "/")));
-        if (!fs.existsSync(fullUploadDir))
-            fs.mkdirSync(fullUploadDir, { recursive: true });
-        cb(null, fullUploadDir);
+        void (async () => {
+            try {
+                const arkosReq = req;
+                const arkosConfig = getArkosConfig();
+                const baseUploadDir = arkosConfig.fileUpload?.baseUploadDir || "/uploads";
+                const settings = uploadManager.getUploadSettingsForFile(arkosReq.__arkos?.uploadConfig, file);
+                const resolved = await uploadManager.resolveUploadSettings(arkosReq, file, settings);
+                const basePath = path.resolve(process.cwd(), baseUploadDir.replaceAll("//", "/"));
+                const fullUploadDir = resolveUploadPath(basePath, resolved.uploadDir, { strictSegments: true });
+                if (!fullUploadDir)
+                    throw new Error(`Invalid upload directory "${resolved.uploadDir}"`);
+                file.__arkos = {
+                    uploadDir: resolved.uploadDir,
+                    urlPath: resolved.urlPath,
+                    urlPathExact: resolved.urlPathExact,
+                    dirParams: resolved.dirParams,
+                    uploadPath: fullUploadDir,
+                };
+                if (!fs.existsSync(fullUploadDir))
+                    fs.mkdirSync(fullUploadDir, { recursive: true });
+                cb(null, fullUploadDir);
+            }
+            catch (error) {
+                cb(error, "");
+            }
+        })();
     },
-    filename: (_, file, cb) => {
-        const uniqueSuffix = Date.now() + "-" + Math.round(Math.random() * 1e9);
-        const ext = path.extname(file.originalname);
-        cb(null, `${file.originalname.replace(ext, "")}-${uniqueSuffix}${ext}`);
+    filename: (req, file, cb) => {
+        void (async () => {
+            try {
+                const arkosReq = req;
+                const settings = uploadManager.getUploadSettingsForFile(arkosReq.__arkos?.uploadConfig, file);
+                const meta = file.__arkos;
+                const index = uploadManager.nextFileIndex(arkosReq, file);
+                let preparedBase;
+                if (settings.prepareFile) {
+                    const result = await settings.prepareFile({
+                        file: file,
+                        dirParams: meta?.dirParams || {},
+                        index,
+                    }, arkosReq, arkosReq.res?.locals || {});
+                    if (result?.filename !== undefined) {
+                        if (typeof result.filename !== "string")
+                            throw new Error("prepareFile must return a string filename");
+                        preparedBase = stripExtension(result.filename);
+                        if (!isSafeFileName(preparedBase))
+                            throw new Error(`Invalid file name "${result.filename}" returned by prepareFile`);
+                    }
+                }
+                const ext = path.extname(file.originalname);
+                const uniqueSuffix = Date.now() + "-" + Math.round(Math.random() * 1e9);
+                const finalName = preparedBase
+                    ? `${preparedBase}${ext}`
+                    : `${safeOriginalBaseName(file)}-${uniqueSuffix}${ext}`;
+                const uploadPath = meta?.uploadPath || "";
+                if (!uploadPath)
+                    throw new Error(`Unable to resolve the upload directory for file "${file.originalname}"`);
+                const targetPath = path.resolve(uploadPath, finalName);
+                if (!isInside(uploadPath, targetPath))
+                    throw new Error(`Invalid file name "${finalName}"`);
+                const targets = (arkosReq.__arkos.uploadTargetPaths ??= new Set());
+                if (targets.has(targetPath))
+                    throw new ConflictError(`Duplicate upload target "${finalName}" in the same request`, "UploadConflict", { filename: finalName });
+                if (settings.overwrite === false && fs.existsSync(targetPath))
+                    throw new ConflictError(`File "${finalName}" already exists and overwrite is disabled`, "UploadConflict", { filename: finalName });
+                targets.add(targetPath);
+                (arkosReq.__arkos.uploadWrittenPaths ??= []).push(targetPath);
+                file.__arkos = {
+                    ...meta,
+                    targetPath,
+                };
+                cb(null, finalName);
+            }
+            catch (error) {
+                cb(error, "");
+            }
+        })();
     },
 });
+function isNestedArrayPath(fieldPath) {
+    return fieldPath.includes("[]");
+}
+function buildPathMatcher(pattern) {
+    const escaped = pattern
+        .replace(/\[]/g, "\x00")
+        .replace(/[\[\]]/g, "\\$&")
+        .replace(/\x00/g, "\\[\\d+\\]");
+    return new RegExp(`^${escaped}$`);
+}
+function extractIndex(segment) {
+    return parseInt(segment.replace(/\[|\]/g, ""), 10);
+}
+function extractIndices(key, pattern) {
+    const patternParts = pattern.match(/\[[^\]]*\]/g) || [];
+    const keyParts = key.match(/\[[^\]]*\]/g) || [];
+    const indices = [];
+    for (let i = 0; i < patternParts.length; i++) {
+        if (patternParts[i] === "[]") {
+            indices.push(extractIndex(keyParts[i]));
+        }
+    }
+    return indices;
+}
+function groupFilesByPattern(files, pattern) {
+    const matcher = buildPathMatcher(pattern);
+    const groups = new Map();
+    for (const key of Object.keys(files)) {
+        if (!matcher.test(key))
+            continue;
+        const indices = extractIndices(key, pattern);
+        const groupKey = indices.join(",");
+        if (!groups.has(groupKey))
+            groups.set(groupKey, []);
+        groups.get(groupKey).push(...files[key]);
+    }
+    return groups;
+}
+function validateFileConstraints(file, allowedFileTypes, maxSize) {
+    if (maxSize && file.size > maxSize) {
+        return `File '${file.originalname}' exceeds the maximum allowed size of ${maxSize} bytes`;
+    }
+    if (allowedFileTypes) {
+        const ext = path.extname(file.originalname).toLowerCase();
+        const allowed = Array.isArray(allowedFileTypes)
+            ? allowedFileTypes.includes(ext)
+            : allowedFileTypes.test(ext);
+        if (!allowed) {
+            return `File type '${ext}' is not allowed for '${file.originalname}'`;
+        }
+    }
+    return null;
+}
+function flattenFieldsForMulter(fields) {
+    return fields.map((field) => ({
+        name: field.name,
+        maxCount: "type" in field && field.type === "single" ? 1 : (field.maxCount ?? 5),
+    }));
+}
+function configHasNestedArrayPaths(config) {
+    if (config.type === "single" || config.type === "array") {
+        return isNestedArrayPath(config.field);
+    }
+    if (config.type === "fields") {
+        return config.fields.some((f) => isNestedArrayPath(f.name));
+    }
+    return false;
+}
+const isImageFile = (file) => !!file?.mimetype?.includes?.("image");
+const collectUploadedFiles = (req) => {
+    if (req.file)
+        return [req.file];
+    if (Array.isArray(req.files))
+        return req.files;
+    if (req.files && typeof req.files === "object")
+        return Object.values(req.files).flat();
+    return [];
+};
+const getImageOptionsForFile = (config, file) => {
+    const baseOptions = config.image;
+    if (config.type !== "fields")
+        return baseOptions;
+    const field = config.fields.find((entry) => {
+        if (entry.name === file.fieldname)
+            return true;
+        try {
+            return buildPathMatcher(entry.name).test(file.fieldname);
+        }
+        catch {
+            return false;
+        }
+    });
+    return field?.image ?? baseOptions;
+};
+const optimizeUploadedImages = async (config, files) => {
+    for (const file of files) {
+        try {
+            const optimizedPath = await optimizeImage(file.path, getImageOptionsForFile(config, file));
+            file.path = optimizedPath;
+            file.filename = path.basename(optimizedPath);
+            try {
+                file.size = (await promisify(fs.stat)(optimizedPath)).size;
+            }
+            catch { }
+        }
+        catch (error) {
+            if (error?.message === "Input file contains unsupported image format")
+                continue;
+            throw new Error(`Cannot process uploaded image: ${error.message}`);
+        }
+    }
+};
+function resolveFieldEntry(field, config = {}) {
+    const isLegacy = !("type" in field) || field.type === undefined;
+    if (isLegacy) {
+        return {
+            ...config,
+            name: field.name,
+            type: "array",
+            required: !!config.required,
+            minCount: field.minCount,
+            maxCount: field.maxCount,
+            allowedFileTypes: config.allowedFileTypes,
+            maxSize: config.maxSize,
+            attachToBody: config.attachToBody,
+        };
+    }
+    if (field.type === "single") {
+        return {
+            name: field.name,
+            type: "single",
+            required: field.required !== false,
+            minCount: undefined,
+            maxCount: undefined,
+            allowedFileTypes: field.allowedFileTypes,
+            maxSize: field.maxSize,
+            attachToBody: field.attachToBody,
+        };
+    }
+    return {
+        name: field.name,
+        type: "array",
+        required: field.required !== false,
+        minCount: field.minCount,
+        maxCount: field.maxCount,
+        allowedFileTypes: field.allowedFileTypes,
+        maxSize: field.maxSize,
+        attachToBody: field.attachToBody,
+    };
+}
 class UploadManager {
-    constructor() {
-        this.fileFilter = (_, file, cb, allowedFileTypes) => {
-            const ext = path.extname(file.originalname).toLowerCase();
-            let isAllowed = false;
-            if (Array.isArray(allowedFileTypes))
-                isAllowed = allowedFileTypes.includes(ext);
-            else
-                isAllowed = allowedFileTypes.test(ext);
-            if (isAllowed)
-                cb(null, true);
-            else
-                cb(new AppError(`File type not allowed, allowed files are ${String(allowedFileTypes).replaceAll("/", "").split("|").join(", ")}`, 400, "FileTypeNotAllowed", { filename: file.originalname }));
+    getUploadSettingsForFile(config, file) {
+        if (!config)
+            return { key: "config" };
+        if (config.type === "fields") {
+            const field = config.fields.find((entry) => {
+                if (entry.name === file.fieldname)
+                    return true;
+                try {
+                    return buildPathMatcher(entry.name).test(file.fieldname);
+                }
+                catch {
+                    return false;
+                }
+            });
+            const typedField = field && "type" in field && field.type !== undefined ? field : undefined;
+            return {
+                uploadDir: typedField?.uploadDir ?? config.uploadDir,
+                urlPath: typedField?.urlPath ?? config.urlPath,
+                prepare: typedField?.prepare ?? config.prepare,
+                prepareFile: typedField?.prepareFile ?? config.prepareFile,
+                overwrite: typedField?.overwrite ?? config.overwrite,
+                key: `field:${field?.name ?? file.fieldname}`,
+            };
+        }
+        return {
+            uploadDir: config.uploadDir,
+            urlPath: config.urlPath,
+            prepare: config.prepare,
+            prepareFile: config.prepareFile,
+            overwrite: config.overwrite,
+            key: `config:${config.type}`,
         };
     }
+    async resolveUploadSettings(req, file, settings) {
+        req.__arkos ??= {};
+        const cached = req.__arkos.preparedUploads?.get(settings.key);
+        if (cached)
+            return cached;
+        const prepared = settings.prepare
+            ? await settings.prepare(req, req.res?.locals || {})
+            : undefined;
+        const dirParams = {};
+        for (const [key, value] of Object.entries(prepared?.dirParams || {})) {
+            if (typeof value !== "string")
+                throw new Error(`prepare returned a non-string value for ":${key}"`);
+            dirParams[key] = value;
+        }
+        const values = {};
+        for (const [key, value] of Object.entries(req.params || {}))
+            if (typeof value === "string")
+                values[key] = value;
+        Object.assign(values, dirParams);
+        const uploadDir = normalizeUploadDir(substituteUploadTemplate(settings.uploadDir || determineUploadDir(file), values, "upload directory"));
+        let urlPath;
+        let urlPathExact = false;
+        if (settings.urlPath && typeof settings.urlPath === "object") {
+            urlPath = normalizeUploadUrlPath(settings.urlPath.exact);
+            urlPathExact = true;
+        }
+        else {
+            urlPath = normalizeUploadUrlPath(substituteUploadTemplate(settings.urlPath || `/${uploadDir}`, values, "upload URL path"));
+        }
+        const resolved = {
+            dirParams,
+            uploadDir,
+            urlPath,
+            urlPathExact,
+        };
+        (req.__arkos.preparedUploads ??= new Map()).set(settings.key, resolved);
+        return resolved;
+    }
+    nextFileIndex(req, file) {
+        req.__arkos ??= {};
+        const indexes = (req.__arkos.uploadFileIndexes ??= {});
+        const index = indexes[file.fieldname] ?? 0;
+        indexes[file.fieldname] = index + 1;
+        return index;
+    }
+    async cleanupRequestFiles(req) {
+        const paths = req.__arkos?.uploadWrittenPaths || [];
+        for (const filePath of paths) {
+            try {
+                await fs.promises.unlink(filePath);
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT")
+                    sheu.warn(`Failed to delete file: ${filePath} because ${error.message}`, { timestamp: true });
+            }
+        }
+        if (req.__arkos) {
+            req.__arkos.uploadWrittenPaths = [];
+            req.__arkos.uploadTargetPaths = new Set();
+        }
+        delete req.file;
+        delete req.files;
+    }
     getUpload({ maxSize = 1024 * 1024 * 5, allowedFileTypes = /.*/, }) {
         return multer({
             storage,
@@ -64,22 +424,67 @@ class UploadManager {
         });
     }
     getMiddleware(config) {
-        let upload;
-        if (config.type === "single")
-            upload = this.getUpload(config)[config.type](config.field);
-        else if (config.type === "array")
-            upload = this.getUpload(config)[config.type](config.field, config.maxCount || 5);
-        else
-            upload = this.getUpload(config)[config.type](config.fields);
-        return upload;
+        if (configHasNestedArrayPaths(config)) {
+            return multer({ storage }).any();
+        }
+        if (config.type === "single") {
+            return this.getUpload(config).single(config.field);
+        }
+        else if (config.type === "array") {
+            return this.getUpload(config).array(config.field, config.maxCount ?? 5);
+        }
+        else {
+            const multerOptions = "maxSize" in config || "allowedFileTypes" in config
+                ? {
+                    maxSize: config.maxSize,
+                    allowedFileTypes: config.allowedFileTypes,
+                }
+                : {};
+            return this.getUpload(multerOptions).fields(flattenFieldsForMulter(config.fields));
+        }
+    }
+    registerUploadConfig(config, route) {
+        const register = (dir, urlPath, serve, hasPrepare, type) => uploadServingRegistry.registerWrite({
+            dir,
+            urlPath,
+            serve,
+            route,
+            hasPrepare,
+            type,
+        });
+        if (config.type === "single" || config.type === "array") {
+            register(config.uploadDir, config.urlPath, config.serve, !!config.prepare, config.type);
+            return;
+        }
+        for (const field of config.fields) {
+            const isLegacy = !("type" in field) || field.type === undefined;
+            if (isLegacy) {
+                register(config.uploadDir, config.urlPath, config.serve, !!config.prepare, "array");
+                continue;
+            }
+            register(field.uploadDir ?? config.uploadDir, field.urlPath ?? config.urlPath, field.serve ?? config.serve, !!(field.prepare ?? config.prepare), field.type ?? "array");
+        }
     }
     handleUpload(config, oldFilePath) {
         return catchAsync((req, res, next) => {
             const middleware = this.getMiddleware(config);
-            req.headers["x-upload-dir"] = config.uploadDir;
+            req.__arkos = { ...req.__arkos, uploadConfig: config };
             middleware(req, res, async (err) => {
-                if (err)
+                if (err) {
+                    if (err instanceof ConflictError ||
+                        err?.code === "UploadConflict")
+                        await this.cleanupRequestFiles(req);
                     return next(err);
+                }
+                if (configHasNestedArrayPaths(config) && Array.isArray(req.files)) {
+                    const normalized = {};
+                    for (const file of req.files) {
+                        if (!normalized[file.fieldname])
+                            normalized[file.fieldname] = [];
+                        normalized[file.fieldname].push(file);
+                    }
+                    req.files = normalized;
+                }
                 if (oldFilePath) {
                     const { fileUpload: configs } = getArkosConfig();
                     const filePath = path.resolve(process.cwd(), removeBothSlashes(configs?.baseUploadDir), removeBothSlashes(oldFilePath));
@@ -100,43 +505,98 @@ class UploadManager {
         return catchAsync((req, _, next) => {
             const errors = [];
             const errorCodes = [];
-            if (uploadConfig.required === false)
-                return next();
-            if (uploadConfig.type === "single") {
-                if (!req.file) {
-                    errors.push(`Required upload field '${uploadConfig.field}' is missing`);
-                    errorCodes.push(uploadConfig.field);
+            const addError = (msg, code) => {
+                errors.push(msg);
+                errorCodes.push(code);
+            };
+            const validateField = (field, type, required, minCount, maxCount, allowedFileTypes, maxSize) => {
+                const isNested = isNestedArrayPath(field);
+                if (isNested) {
+                    const filesObj = req.files;
+                    if (!filesObj || Array.isArray(filesObj)) {
+                        if (required)
+                            addError(`Required field '${field}' is missing`, field);
+                        return;
+                    }
+                    const groups = groupFilesByPattern(filesObj, field);
+                    if (groups.size === 0) {
+                        if (required)
+                            addError(`Required field '${field}' is missing`, field);
+                        return;
+                    }
+                    for (const [groupKey, groupFiles] of groups) {
+                        const label = `'${field}' (group ${groupKey})`;
+                        if (type === "single" && groupFiles.length !== 1) {
+                            addError(`Field ${label} must have exactly 1 file`, field);
+                        }
+                        if (type === "array") {
+                            if (minCount && groupFiles.length < minCount) {
+                                addError(`Field ${label} requires at least ${minCount} files, got ${groupFiles.length}`, field);
+                            }
+                            if (maxCount && groupFiles.length > maxCount) {
+                                addError(`Field ${label} allows at most ${maxCount} files, got ${groupFiles.length}`, field);
+                            }
+                        }
+                        for (const file of groupFiles) {
+                            const err = validateFileConstraints(file, allowedFileTypes, maxSize);
+                            if (err)
+                                addError(err, field);
+                        }
+                    }
                 }
+                else {
+                    if (type === "single") {
+                        if (required && !req.file) {
+                            addError(`Required upload field '${field}' is missing`, field);
+                        }
+                    }
+                    else {
+                        const filesObj = req.files;
+                        const files = Array.isArray(req.files)
+                            ? req.files
+                            : filesObj?.[field];
+                        if (!files || files.length === 0) {
+                            if (required)
+                                addError(`Required upload field '${field}' is missing or empty`, field);
+                        }
+                        else if (!Array.isArray(files)) {
+                            if (required)
+                                addError(`Malformed upload field '${field}'`, field);
+                        }
+                        else {
+                            if (minCount && files.length < minCount) {
+                                addError(`Field '${field}' requires at least ${minCount} files, got ${files.length}`, field);
+                            }
+                        }
+                    }
+                }
+            };
+            if (uploadConfig.type === "single") {
+                validateField(uploadConfig.field, "single", uploadConfig.required !== false, undefined, undefined, isNestedArrayPath(uploadConfig.field)
+                    ? uploadConfig.allowedFileTypes
+                    : undefined, isNestedArrayPath(uploadConfig.field)
+                    ? uploadConfig.maxSize
+                    : undefined);
             }
             else if (uploadConfig.type === "array") {
-                if (!req.files || !Array.isArray(req.files) || req.files.length === 0) {
-                    errors.push(`Required upload field '${uploadConfig.field}' is missing or empty`);
-                    errorCodes.push(uploadConfig.field);
-                }
+                validateField(uploadConfig.field, "array", uploadConfig.required !== false, uploadConfig.minCount, uploadConfig.maxCount, isNestedArrayPath(uploadConfig.field)
+                    ? uploadConfig.allowedFileTypes
+                    : undefined, isNestedArrayPath(uploadConfig.field)
+                    ? uploadConfig.maxSize
+                    : undefined);
             }
             else if (uploadConfig.type === "fields") {
-                if (!req.files ||
-                    typeof req.files !== "object" ||
-                    Array.isArray(req.files)) {
-                    errors.push(`Required upload fields are missing. Expected an object with fields: ${uploadConfig.fields.map((f) => f.name).join(", ")}`);
-                    errorCodes.push(...uploadConfig.fields.map((f) => f.name));
-                }
-                else {
-                    for (const field of uploadConfig.fields) {
-                        const filesForField = req.files[field.name];
-                        if (!filesForField ||
-                            !Array.isArray(filesForField) ||
-                            filesForField.length === 0) {
-                            errors.push(`Required upload field '${field.name}' is missing or empty`);
-                            errorCodes.push(field.name);
-                        }
-                    }
+                for (const fieldEntry of uploadConfig.fields) {
+                    const resolved = resolveFieldEntry(fieldEntry, uploadConfig);
+                    validateField(resolved.name, resolved.type, resolved.required, resolved.minCount, resolved.maxCount, isNestedArrayPath(resolved.name)
+                        ? resolved.allowedFileTypes
+                        : undefined, isNestedArrayPath(resolved.name) ? resolved.maxSize : undefined);
                 }
             }
             if (errors.length > 0) {
-                throw new AppError(errors[0], 400, `Missing${pascalCase(errorCodes[0]).replaceAll("_", "")}FileField`, {
-                    errors,
-                });
+                throw new AppError(errors[0], 400, uploadConfig.type !== "single"
+                    ? `MissingUploadFields`
+                    : `MissingUploadField`, { errors });
             }
             next();
         });
@@ -156,7 +616,8 @@ class UploadManager {
                     await deleteFile(req.file);
                     delete req.file;
                 }
-                else if (config.type === "array" && Array.isArray(req.files)) {
+                else if ((config.type === "array" || configHasNestedArrayPaths(config)) &&
+                    Array.isArray(req.files)) {
                     for (const file of req.files) {
                         await deleteFile(file);
                     }
@@ -180,39 +641,33 @@ class UploadManager {
         };
     }
     handlePostUpload(config) {
-        return catchAsync((req, _, next) => {
+        return catchAsync(async (req, _, next) => {
             const { baseURL, baseRoute } = extractRequestInfo(req);
-            const arkosConfig = getArkosConfig();
-            const normalizePath = (filePath) => {
-                let fullBaseUploadDir = path.resolve(path.join(process.cwd(), arkosConfig.fileUpload?.baseUploadDir));
-                fullBaseUploadDir = fullBaseUploadDir.replace(process.cwd(), "");
-                return filePath
-                    .replaceAll(process.cwd(), "")
-                    .replace(`/${fullBaseUploadDir}`, "")
-                    .replace(fullBaseUploadDir, "")
-                    .replace(/\\/g, "/");
+            const baseRoutePath = baseRoute === "/" ? "" : normalizeUploadUrlPath(baseRoute);
+            const getPublicRelativePath = (file) => {
+                if (file.__arkos?.urlPathExact)
+                    return normalizeUploadUrlPath(file.__arkos.urlPath || "/");
+                const publicDir = file.__arkos?.urlPath ||
+                    `/${normalizeUploadDir(file.__arkos?.uploadDir || "")}`;
+                return `${normalizeUploadUrlPath(publicDir)}/${file.filename || path.basename(file.path)}`.replace(/\/+/g, "/");
             };
-            const buildFileURL = (file) => {
-                const relativePath = generateRelativePath(file.path, req.headers["x-upload-dir"]);
-                return `${baseURL}${baseRoute === "/" ? "" : baseRoute}${relativePath.startsWith("/") ? relativePath : `/${relativePath}`}`;
-            };
-            const getAttachValue = (file) => {
+            const buildFileURL = (file) => `${baseURL}${baseRoutePath}${getPublicRelativePath(file)}`;
+            const getAttachValue = (file, attachToBody) => {
                 const url = buildFileURL(file);
                 file.url = url;
-                file.pathname = normalizePath(file.path);
-                if (config.attachToBody === false)
+                file.pathname = `${baseRoutePath}${getPublicRelativePath(file)}`;
+                if (attachToBody === false)
                     return undefined;
-                if (config.attachToBody === "pathname" || !config.attachToBody)
-                    return ((baseRoute === "/"
-                        ? ""
-                        : baseRoute.startsWith("/")
-                            ? baseRoute
-                            : `/${baseRoute}`) + normalizePath(file.path));
-                if (config.attachToBody === "url")
+                if (attachToBody === "url")
                     return url;
-                if (config.attachToBody === "file")
+                if (attachToBody === "file")
                     return file;
-                return undefined;
+                if (typeof attachToBody === "function") {
+                    const result = attachToBody(file);
+                    if (result)
+                        return result;
+                }
+                return file.pathname;
             };
             const setNestedValue = (obj, path, value) => {
                 const keys = path.match(/[^\[\]]+/g) || [];
@@ -228,50 +683,159 @@ class UploadManager {
                 const lastKey = keys[keys.length - 1];
                 current[lastKey] = value;
             };
-            try {
-                if (config.type === "single" && req.file) {
-                    const value = getAttachValue(req.file);
-                    if (value !== undefined && config.field) {
-                        const bodyUpdate = {};
-                        setNestedValue(bodyUpdate, config.field, value);
-                        req.body = deepmerge(req.body || {}, bodyUpdate);
+            const reconstructNestedArrayPath = (pattern, filesObj, attachToBody, type, sharedBodyUpdate) => {
+                const groups = groupFilesByPattern(filesObj, pattern);
+                if (groups.size === 0)
+                    return;
+                const segments = pattern.match(/[^\[\]]+|\[\]/g) || [];
+                const sortedGroups = [...groups.entries()].sort((a, b) => {
+                    const ai = a[0].split(",").map(Number);
+                    const bi = b[0].split(",").map(Number);
+                    for (let i = 0; i < Math.min(ai.length, bi.length); i++) {
+                        if (ai[i] !== bi[i])
+                            return ai[i] - bi[i];
                     }
-                }
-                else if (config.type === "array" && Array.isArray(req.files)) {
-                    const values = req.files
-                        .map((file) => getAttachValue(file))
+                    return 0;
+                });
+                const bodyUpdate = sharedBodyUpdate ?? {};
+                for (const [groupKey, groupFiles] of sortedGroups) {
+                    const indices = groupKey.split(",").map(Number);
+                    let indexCounter = 0;
+                    const concretePath = segments
+                        .map((seg) => {
+                        if (seg === "[]")
+                            return `[${indices[indexCounter++]}]`;
+                        return seg;
+                    })
+                        .reduce((acc, seg, i) => {
+                        if (i === 0)
+                            return seg;
+                        if (seg.startsWith("["))
+                            return acc + seg;
+                        return acc + `[${seg}]`;
+                    }, "");
+                    const values = groupFiles
+                        .map((f) => getAttachValue(f, attachToBody))
                         .filter((v) => v !== undefined);
-                    if (values.length > 0 && config.field) {
-                        const bodyUpdate = {};
-                        setNestedValue(bodyUpdate, config.field, values);
-                        req.body = deepmerge(req.body || {}, bodyUpdate);
+                    if (values.length === 0)
+                        continue;
+                    const valueToSet = type === "single" ? values[0] : values;
+                    setNestedValue(bodyUpdate, concretePath, valueToSet);
+                }
+                if (!sharedBodyUpdate) {
+                    req.body = deepmerge(req.body || {}, bodyUpdate);
+                }
+            };
+            try {
+                const imageFiles = collectUploadedFiles(req).filter(isImageFile);
+                if (imageFiles.length > 0)
+                    await optimizeUploadedImages(config, imageFiles);
+                if (config.type === "single") {
+                    if (isNestedArrayPath(config.field)) {
+                        const filesObj = req.files;
+                        if (filesObj && !Array.isArray(filesObj)) {
+                            reconstructNestedArrayPath(config.field, filesObj, config.attachToBody, "single");
+                        }
+                    }
+                    else if (req.file) {
+                        const value = getAttachValue(req.file, config.attachToBody);
+                        if (value !== undefined) {
+                            const bodyUpdate = {};
+                            setNestedValue(bodyUpdate, config.field, value);
+                            req.body = deepmerge(req.body || {}, bodyUpdate);
+                        }
                     }
                 }
-                else if (config.type === "fields" &&
-                    req.files &&
-                    !Array.isArray(req.files)) {
-                    const bodyUpdate = {};
-                    for (const fieldName in req.files) {
-                        const files = req.files[fieldName];
-                        const values = files
-                            .map((file) => getAttachValue(file))
+                else if (config.type === "array") {
+                    if (isNestedArrayPath(config.field)) {
+                        const filesObj = req.files;
+                        if (filesObj && !Array.isArray(filesObj)) {
+                            reconstructNestedArrayPath(config.field, filesObj, config.attachToBody, "array");
+                        }
+                    }
+                    else if (Array.isArray(req.files)) {
+                        const values = req.files
+                            .map((file) => getAttachValue(file, config.attachToBody))
                             .filter((v) => v !== undefined);
                         if (values.length > 0) {
-                            const valueToAttach = values.length === 1 ? values[0] : values;
-                            setNestedValue(bodyUpdate, fieldName, valueToAttach);
+                            const bodyUpdate = {};
+                            setNestedValue(bodyUpdate, config.field, values);
+                            req.body = deepmerge(req.body || {}, bodyUpdate);
+                        }
+                    }
+                }
+                else if (config.type === "fields") {
+                    const filesObj = req.files;
+                    if (!filesObj || Array.isArray(filesObj))
+                        return next();
+                    const bodyUpdate = {};
+                    const configAttachToBody = "attachToBody" in config ? config.attachToBody : undefined;
+                    for (const fieldEntry of config.fields) {
+                        const resolved = resolveFieldEntry(fieldEntry);
+                        if (isNestedArrayPath(resolved.name)) {
+                            reconstructNestedArrayPath(resolved.name, filesObj, resolved.attachToBody ?? configAttachToBody, resolved.type, bodyUpdate);
+                        }
+                        else {
+                            const files = filesObj[resolved.name];
+                            if (!files || files.length === 0)
+                                continue;
+                            const attachTo = resolved.attachToBody ?? configAttachToBody;
+                            const values = files
+                                .map((f) => getAttachValue(f, attachTo))
+                                .filter((v) => v !== undefined);
+                            if (values.length === 0)
+                                continue;
+                            const valueToAttach = resolved.type === "single" ? values[0] : values;
+                            setNestedValue(bodyUpdate, resolved.name, valueToAttach);
                         }
                     }
                     if (Object.keys(bodyUpdate).length > 0) {
-                        req.body = deepmerge(req.body || {}, bodyUpdate);
+                        req.body = deepmerge(req.body || {}, bodyUpdate, {
+                            arrayMerge: (target, source) => {
+                                const result = [...target];
+                                source.forEach((item, i) => {
+                                    result[i] = result[i] ? deepmerge(result[i], item) : item;
+                                });
+                                return result;
+                            },
+                        });
                     }
                 }
             }
             catch (err) {
-                throw new AppError(`File uploads post processing failed ${err.message}`, 500, "FileUploadPostProcessError");
+                if (err instanceof AppError)
+                    throw err;
+                throw new Error(`File uploads post processing failed: ${err.message}`);
             }
             next();
         });
     }
+    fileFilter = (_, file, cb, allowedFileTypes) => {
+        const ext = path.extname(file.originalname).toLowerCase();
+        let isAllowed = false;
+        if (Array.isArray(allowedFileTypes))
+            isAllowed = allowedFileTypes.includes(ext);
+        else
+            isAllowed = allowedFileTypes.test(ext);
+        if (isAllowed)
+            cb(null, true);
+        else
+            cb(new AppError(`File type not allowed, allowed files are ${String(allowedFileTypes).replaceAll("/", "").split("|").join(", ")}`, 400, "FileTypeNotAllowed", { filename: file.originalname }));
+    };
+    isAllFieldRequired(uploadConfig) {
+        let isRequired = false;
+        if (!uploadConfig)
+            return false;
+        if (uploadConfig.type !== "fields")
+            isRequired = uploadConfig.required !== false;
+        else {
+            isRequired =
+                uploadConfig.required !== undefined
+                    ? uploadConfig.required
+                    : uploadConfig.fields.every((field) => field.required || field.required === undefined);
+        }
+        return isRequired;
+    }
 }
 const uploadManager = new UploadManager();
 export default uploadManager;