@cyberskill/shared 3.10.0 → 3.11.0

package/dist/node/mongo/mongo.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"mongo.util.js","names":[],"sources":["../../../src/node/mongo/mongo.util.ts"],"sourcesContent":["import type migrate from 'migrate-mongo';\nimport type mongooseRaw from 'mongoose';\n\nimport aggregatePaginate from 'mongoose-aggregate-paginate-v2';\nimport mongoosePaginate from 'mongoose-paginate-v2';\nimport { randomUUID } from 'node:crypto';\n\nimport { getNestedValue, regexSearchMapper, setNestedValue } from '#util/index.js';\nimport { validate } from '#util/validate/index.js';\n\nimport type { MongoController } from './mongo.controller.js';\nimport type { C_Document, I_CreateModelOptions, I_CreateSchemaOptions, I_DynamicVirtualConfig, I_DynamicVirtualOptions, I_ExtendedModel, I_GenericDocument, I_MongooseModelMiddleware, T_Filter, T_MongoosePlugin, T_MongooseSchema, T_QueryFilter, T_VirtualOptions, T_WithId } from './mongo.type.js';\n\nimport { addGitIgnoreEntry, writeFileSync } from '../fs/index.js';\nimport { MIGRATE_MONGO_CONFIG, PATH } from '../path/index.js';\n\n/**\n * Converts enum values to proper model names.\n * Handles common naming conventions like converting 'USER' to 'User'.\n *\n * @param enumValue - The enum value to convert\n * @returns The converted model name\n */\nexport function convertEnumToModelName(enumValue: string): string {\n    if (enumValue === enumValue.toUpperCase()) {\n        return enumValue.charAt(0).toUpperCase() + enumValue.slice(1).toLowerCase();\n    }\n\n    return enumValue;\n}\n\n/**\n * Interface for the MongoDB utility object to enable explicit type annotation.\n * Required to avoid TS7056 (inferred type exceeds maximum serialization length).\n */\ninterface I_MongoUtils {\n    createGenericFields: () => I_GenericDocument;\n    applyPlugins: <T>(schema: T_MongooseSchema<T>, plugins: Array<T_MongoosePlugin | false>) => void;\n    applyMiddlewares: <T extends Partial<C_Document>>(schema: T_MongooseSchema<T>, middlewares: I_MongooseModelMiddleware<T>[]) => void;\n    createGenericSchema: (mongoose: typeof mongooseRaw) => T_MongooseSchema<I_GenericDocument>;\n    createSchema: <T, R extends string = string>(options: I_CreateSchemaOptions<T, R>) => T_MongooseSchema<T>;\n    createModel: <T extends Partial<C_Document>, R extends string = string>(options: I_CreateModelOptions<T, R>) => I_ExtendedModel<T>;\n    validator: {\n        isRequired: <T>() => (this: T, value: unknown) => Promise<boolean>;\n        isUnique: <T extends { constructor: { exists: (query: { [key: string]: unknown }) => Promise<unknown> } }>(fields: string[]) => (this: T, value: unknown) => Promise<boolean>;\n        matchesRegex: (regexArray: RegExp[]) => (value: string) => Promise<boolean>;\n    };\n    migrate: {\n        getModule: () => Promise<typeof migrate>;\n        setConfig: (options: Partial<migrate.config.Config> & { moduleSystem?: 'commonjs' | 'esm' }) => void;\n    };\n    regexify: <T>(filter?: T_QueryFilter<T>, fields?: (keyof T | string)[]) => T_QueryFilter<T>;\n    isDynamicVirtual: <T, R extends string>(options?: T_VirtualOptions<T, R>) => options is I_DynamicVirtualOptions<T, R>;\n    getNewRecords: <T extends I_GenericDocument>(controller: MongoController<T>, recordsToCheck: T[], filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean, filter?: T_Filter<T>) => Promise<T[]>;\n    getExistingRecords: <T extends I_GenericDocument>(controller: MongoController<T>, recordsToCheck: T[], filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean, filter?: T_Filter<T>) => Promise<T_WithId<T>[]>;\n}\n\n/**\n * MongoDB utility object providing comprehensive database operations and utilities.\n * This object contains methods for creating generic fields, applying plugins and middlewares,\n * creating schemas and models, validation functions, migration utilities, and regex filtering.\n */\nexport const mongo: I_MongoUtils = {\n    /**\n     * Creates generic fields that are commonly used across MongoDB documents.\n     * This function generates standard fields including a UUID, deletion flag, and timestamps\n     * that can be applied to any document schema.\n     *\n     * @returns An object containing generic document fields (id, isDel, createdAt, updatedAt).\n     */\n    createGenericFields(): I_GenericDocument {\n        return {\n            id: randomUUID(),\n            isDel: false,\n            createdAt: new Date(),\n            updatedAt: new Date(),\n        };\n    },\n    /**\n     * Applies plugins to a Mongoose schema.\n     * This function filters out falsy plugins and applies the remaining valid plugins\n     * to the provided schema.\n     *\n     * @param schema - The Mongoose schema to apply plugins to.\n     * @param plugins - An array of plugin functions or false values to filter and apply.\n     */\n    applyPlugins<T>(schema: T_MongooseSchema<T>, plugins: Array<T_MongoosePlugin | false>) {\n        plugins\n            .filter((plugin): plugin is T_MongoosePlugin => typeof plugin === 'function')\n            .forEach(plugin => schema.plugin(plugin));\n    },\n    /**\n     * Applies middleware functions to a Mongoose schema.\n     * This function configures pre and post middleware for specified methods on the schema.\n     *\n     * @param schema - The Mongoose schema to apply middleware to.\n     * @param middlewares - An array of middleware configurations with method, pre, and post functions.\n     */\n    applyMiddlewares<T extends Partial<C_Document>>(\n        schema: T_MongooseSchema<T>,\n        middlewares: I_MongooseModelMiddleware<T>[],\n    ) {\n        middlewares.forEach(({ method, pre, post }) => {\n            if (method && pre) {\n                schema.pre(method as RegExp, pre);\n            }\n\n            if (method && post) {\n                schema.post(method as RegExp, post);\n            }\n        });\n    },\n    /**\n     * Creates a generic Mongoose schema with common fields.\n     * This function creates a base schema with UUID field and deletion flag,\n     * configured with automatic timestamps.\n     *\n     * @param mongoose - The Mongoose instance to create the schema with.\n     * @returns A Mongoose schema with generic document fields.\n     */\n    createGenericSchema(mongoose: typeof mongooseRaw) {\n        return new mongoose.Schema<I_GenericDocument>(\n            {\n                id: { type: String, default: () => randomUUID(), unique: true },\n                isDel: { type: Boolean, default: false },\n            },\n            { timestamps: true },\n        );\n    },\n    /**\n     * Creates a Mongoose schema with optional virtual fields and generic fields.\n     * This function creates a new Mongoose schema from the provided schema definition,\n     * optionally adds virtual fields, and includes generic fields (unless standalone is true).\n     *\n     * @param options - Configuration options including mongoose instance, schema definition, virtuals, and standalone flag.\n     * @param options.mongoose - The Mongoose instance to use for schema creation.\n     * @param options.schema - The schema definition object.\n     * @param options.virtuals - Optional array of virtual field configurations.\n     * @param options.standalone - Whether to exclude generic fields (default: false).\n     * @returns A configured Mongoose schema.\n     */\n    createSchema<T, R extends string = string>({\n        mongoose,\n        schema,\n        virtuals = [],\n        standalone = false,\n    }: I_CreateSchemaOptions<T, R>): T_MongooseSchema<T> {\n        const createdSchema = new mongoose.Schema<T>(schema, {\n            toJSON: { virtuals: true }, // So `res.json()` and other `JSON.stringify()` functions include virtuals\n            toObject: { virtuals: true }, // So `console.log()` and other functions that use `toObject()` include virtuals\n        });\n\n        virtuals.forEach(({ name, options, get }) => {\n            if (mongo.isDynamicVirtual<T, R>(options)) {\n                const schemaStatics = createdSchema.statics as Record<string, unknown>;\n\n                if (!schemaStatics['_dynamicVirtuals']) {\n                    schemaStatics['_dynamicVirtuals'] = [];\n                }\n\n                (schemaStatics['_dynamicVirtuals'] as I_DynamicVirtualConfig<T>[]).push({\n                    name: name as string,\n                    options,\n                });\n\n                const virtualInstance = createdSchema.virtual(name as string);\n\n                if (get) {\n                    virtualInstance.get(get);\n                }\n                else {\n                    virtualInstance.get(function (this: T & { _populated?: { [key: string]: unknown } }) {\n                        return this._populated?.[name as string] || (options?.count ? 0 : (options?.justOne ? null : []));\n                    });\n                }\n            }\n            else {\n                const virtualInstance = createdSchema.virtual(name as string, options);\n\n                if (get) {\n                    virtualInstance.get(get);\n                }\n            }\n        });\n\n        if (!standalone) {\n            createdSchema.add(mongo.createGenericSchema(mongoose));\n        }\n\n        return createdSchema;\n    },\n    /**\n     * Creates a Mongoose model with plugins, middleware, and pagination support.\n     * This function creates a model from a schema with optional pagination and aggregation plugins,\n     * and applies any specified middleware. If a model with the same name already exists, it returns the existing model.\n     *\n     * @param options - Configuration options including mongoose instance, model name, schema, and feature flags.\n     * @param options.mongoose - The Mongoose instance to use for model creation.\n     * @param options.name - The name of the model to create.\n     * @param options.schema - The schema definition for the model.\n     * @param options.pagination - Whether to enable pagination plugin (default: false).\n     * @param options.aggregate - Whether to enable aggregation pagination plugin (default: false).\n     * @param options.virtuals - Optional array of virtual field configurations.\n     * @param options.middlewares - Optional array of middleware configurations.\n     * @returns A configured Mongoose model with extended functionality.\n     * @throws {Error} When the model name is not provided.\n     */\n    createModel<T extends Partial<C_Document>, R extends string = string>({\n        mongoose: currentMongooseInstance,\n        name,\n        schema,\n        virtuals = [],\n        pagination = true,\n        aggregate = true,\n        middlewares = [],\n    }: I_CreateModelOptions<T, R>): I_ExtendedModel<T> {\n        if (!name) {\n            throw new Error('Model name is required.');\n        }\n\n        if (currentMongooseInstance.models[name]) {\n            return currentMongooseInstance.models[name] as I_ExtendedModel<T>;\n        }\n\n        const createdSchema = mongo.createSchema({ mongoose: currentMongooseInstance, schema, virtuals });\n\n        if (pagination || aggregate) {\n            mongo.applyPlugins<T>(createdSchema, [\n                pagination && mongoosePaginate,\n                aggregate && aggregatePaginate,\n            ]);\n        }\n\n        mongo.applyMiddlewares<T>(createdSchema, middlewares);\n\n        const model = currentMongooseInstance.model<T>(name, createdSchema) as I_ExtendedModel<T>;\n\n        if (virtuals.length > 0) {\n            // Mongoose Model has no typed _virtualConfigs; used by MongooseController.getDynamicVirtuals()\n            (model as any)._virtualConfigs = virtuals;\n        }\n\n        return model;\n    },\n    /**\n     * Validation utilities for Mongoose schemas.\n     * This object provides common validation functions that can be used in Mongoose schema definitions.\n     */\n    validator: {\n        /**\n         * Creates a required field validator.\n         * This function returns a validator that checks if a field value is not empty\n         * using the validate.isEmpty utility.\n         *\n         * @returns A validation function that returns true if the field is not empty.\n         */\n        isRequired<T>(): (this: T, value: unknown) => Promise<boolean> {\n            return async function (this: T, value: unknown): Promise<boolean> {\n                return !validate.isEmpty(value);\n            };\n        },\n        /**\n         * Creates a unique field validator.\n         * This function returns a validator that checks if a field value is unique\n         * across the specified fields in the collection.\n         *\n         * @param fields - An array of field names to check for uniqueness.\n         * @returns A validation function that returns true if the value is unique across the specified fields.\n         * @throws {Error} When fields is not a non-empty array of strings.\n         */\n        isUnique<T extends { constructor: { exists: (query: { [key: string]: unknown }) => Promise<unknown> } }>(fields: string[]) {\n            return async function (this: T, value: unknown): Promise<boolean> {\n                if (!Array.isArray(fields) || fields.length === 0) {\n                    throw new Error('Fields must be a non-empty array of strings.');\n                }\n\n                const query = { $or: fields.map(field => ({ [field]: value })) };\n                const existingDocument = await this.constructor.exists(query);\n\n                return !existingDocument;\n            };\n        },\n        /**\n         * Creates a regex pattern validator.\n         * This function returns a validator that checks if a string value matches\n         * all provided regular expressions.\n         *\n         * @param regexArray - An array of regular expressions to test against the value.\n         * @returns A validation function that returns true if the value matches all regex patterns.\n         * @throws {Error} When regexArray is not an array of valid RegExp objects.\n         */\n        matchesRegex(regexArray: RegExp[]): (value: string) => Promise<boolean> {\n            return async (value: string): Promise<boolean> => {\n                if (!Array.isArray(regexArray) || regexArray.some(r => !(r instanceof RegExp))) {\n                    throw new Error('regexArray must be an array of valid RegExp objects.');\n                }\n\n                return regexArray.every(regex => regex.test(value));\n            };\n        },\n    },\n    /**\n     * Migration utilities for MongoDB.\n     * This object extends the migrate-mongo library with additional configuration utilities.\n     */\n    migrate: {\n        /**\n         * Lazily loads the migrate-mongo module to avoid eager import overhead.\n         * Use this to access migrate-mongo methods (up, down, status, create) programmatically.\n         *\n         * @returns A promise resolving to the migrate-mongo module.\n         */\n        async getModule(): Promise<typeof migrate> {\n            return (await import('migrate-mongo')).default;\n        },\n        /**\n         * Sets the migration configuration and updates .gitignore.\n         * This function creates a migration configuration file and ensures it's properly\n         * excluded from version control.\n         *\n         * @param options - Migration configuration options to write to the config file.\n         */\n        setConfig: (options: Partial<migrate.config.Config> & { moduleSystem?: 'commonjs' | 'esm' }) => {\n            const optionsJS = `// This file is automatically generated by the Cyberskill CLI.\\nmodule.exports = ${JSON.stringify(options, null, 4)}`;\n\n            writeFileSync(PATH.MIGRATE_MONGO_CONFIG, optionsJS);\n\n            addGitIgnoreEntry(PATH.GIT_IGNORE, MIGRATE_MONGO_CONFIG);\n        },\n    },\n    /**\n     * Converts string values in a filter to regex patterns for case-insensitive search.\n     * This function recursively processes a filter object and converts string values in specified fields\n     * to MongoDB regex patterns that support accented character matching.\n     *\n     * @remarks\n     * **Performance guard:** Input strings are capped at 200 characters to mitigate ReDoS risk.\n     * The generated regex patterns include accented character alternation groups (e.g., `(a|à|á|...)`)\n     * which can be polynomially complex for very long inputs. For production search on large collections,\n     * consider using MongoDB `$text` search indexes instead of `$regex` for better performance.\n     *\n     * @param filter - The filter object to process.\n     * @param fields - An array of field names to convert to regex patterns.\n     * @returns A new filter object with string values converted to regex patterns.\n     */\n    regexify<T>(filter?: T_QueryFilter<T>, fields?: (keyof T | string)[]): T_QueryFilter<T> {\n        if (!filter) {\n            return {} as T_QueryFilter<T>;\n        }\n\n        let newFilter = { ...filter };\n\n        if (!fields || fields.length === 0) {\n            return newFilter;\n        }\n\n        const MAX_REGEX_INPUT_LENGTH = 200;\n\n        for (const field of fields) {\n            const path = field.toString().split('.');\n            const value = getNestedValue(newFilter, path);\n\n            if (typeof value === 'string' && value.length > 0 && value.length <= MAX_REGEX_INPUT_LENGTH) {\n                const regexValue = {\n                    $regex: `.*${regexSearchMapper(value)}.*`,\n                    $options: 'i',\n                };\n\n                newFilter = setNestedValue(newFilter, path, regexValue);\n            }\n        }\n\n        return newFilter;\n    },\n    /**\n     * Checks if a virtual options object has a dynamic ref function.\n     *\n     * @param options - The virtual options to check.\n     * @returns True if the options contain a dynamic ref function.\n     */\n    isDynamicVirtual<T, R extends string = string>(options?: T_VirtualOptions<T, R>): options is I_DynamicVirtualOptions<T, R> {\n        return Boolean(options && typeof options.ref === 'function');\n    },\n\n    /**\n     * Generic utility function to get new records from the database\n     * @param controller - MongoController instance\n     * @param recordsToCheck - Array of records to check\n     * @param filterFn - Function to determine if a record already exists\n     * @returns Array of records that don't exist in the database\n     */\n    async getNewRecords<T extends I_GenericDocument>(\n        controller: MongoController<T>,\n        recordsToCheck: T[],\n        filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean,\n        filter: T_Filter<T> = {} as T_Filter<T>,\n    ): Promise<T[]> {\n        const existingRecords = await controller.findAll(filter);\n\n        if (!existingRecords.success) {\n            throw new Error(`Failed to query existing records: ${existingRecords.message}`);\n        }\n\n        if ('truncated' in existingRecords && existingRecords.truncated) {\n            throw new Error('getNewRecords: Results were truncated by the default limit. Use pagination or set an explicit limit to ensure complete data.');\n        }\n\n        const filteredRecords = recordsToCheck.filter(newRecord =>\n            !existingRecords.result.some((existingRecord: T_WithId<T>) =>\n                filterFn(existingRecord, newRecord),\n            ),\n        );\n\n        return filteredRecords;\n    },\n\n    /**\n     * Generic utility function to get existing records that match the filter criteria\n     * @param controller - MongoController instance\n     * @param recordsToCheck - Array of records to check\n     * @param filterFn - Function to determine if a record exists\n     * @returns Array of existing records that match the filter criteria\n     * @throws {Error} When the database query fails — prevents silent data inconsistency.\n     */\n    async getExistingRecords<T extends I_GenericDocument>(\n        controller: MongoController<T>,\n        recordsToCheck: T[],\n        filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean,\n        filter: T_Filter<T> = {} as T_Filter<T>,\n    ): Promise<T_WithId<T>[]> {\n        const existingRecords = await controller.findAll(filter);\n\n        if (!existingRecords.success) {\n            throw new Error(`Failed to query existing records: ${existingRecords.message}`);\n        }\n\n        if ('truncated' in existingRecords && existingRecords.truncated) {\n            throw new Error('getExistingRecords: Results were truncated by the default limit. Use pagination or set an explicit limit to ensure complete data.');\n        }\n\n        const foundRecords = existingRecords.result.filter((existingRecord: T_WithId<T>) =>\n            recordsToCheck.some((newRecord: T) =>\n                filterFn(existingRecord, newRecord),\n            ),\n        );\n\n        return foundRecords;\n    },\n};\n\nexport { applyNestedPopulate } from './mongo.populate.js';\n"],"mappings":"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"}
+{"version":3,"file":"mongo.util.js","names":[],"sources":["../../../src/node/mongo/mongo.util.ts"],"sourcesContent":["import type migrate from 'migrate-mongo';\nimport type mongooseRaw from 'mongoose';\n\nimport aggregatePaginate from 'mongoose-aggregate-paginate-v2';\nimport mongoosePaginate from 'mongoose-paginate-v2';\nimport { randomUUID } from 'node:crypto';\n\nimport { getNestedValue, regexSearchMapper, setNestedValue } from '#util/index.js';\nimport { validate } from '#util/validate/index.js';\n\nimport type { MongoController } from './mongo.controller.js';\nimport type { C_Document, I_CreateModelOptions, I_CreateSchemaOptions, I_DynamicVirtualConfig, I_DynamicVirtualOptions, I_ExtendedModel, I_GenericDocument, I_MongooseModelMiddleware, T_Filter, T_MongoosePlugin, T_MongooseSchema, T_QueryFilter, T_VirtualOptions, T_WithId } from './mongo.type.js';\n\nimport { addGitIgnoreEntry, writeFileSync } from '../fs/index.js';\nimport { MIGRATE_MONGO_CONFIG, PATH } from '../path/index.js';\n\n/**\n * Converts enum values to proper model names.\n * Handles common naming conventions like converting 'USER' to 'User'.\n *\n * @param enumValue - The enum value to convert\n * @returns The converted model name\n */\nexport function convertEnumToModelName(enumValue: string): string {\n    if (enumValue === enumValue.toUpperCase()) {\n        return enumValue.charAt(0).toUpperCase() + enumValue.slice(1).toLowerCase();\n    }\n\n    return enumValue;\n}\n\n/**\n * Interface for the MongoDB utility object to enable explicit type annotation.\n * Required to avoid TS7056 (inferred type exceeds maximum serialization length).\n */\ninterface I_MongoUtils {\n    createGenericFields: () => I_GenericDocument;\n    applyPlugins: <T>(schema: T_MongooseSchema<T>, plugins: Array<T_MongoosePlugin | false>) => void;\n    applyMiddlewares: <T extends Partial<C_Document>>(schema: T_MongooseSchema<T>, middlewares: I_MongooseModelMiddleware<T>[]) => void;\n    createGenericSchema: (mongoose: typeof mongooseRaw) => T_MongooseSchema<I_GenericDocument>;\n    createSchema: <T, R extends string = string>(options: I_CreateSchemaOptions<T, R>) => T_MongooseSchema<T>;\n    createModel: <T extends Partial<C_Document>, R extends string = string>(options: I_CreateModelOptions<T, R>) => I_ExtendedModel<T>;\n    validator: {\n        isRequired: <T>() => (this: T, value: unknown) => Promise<boolean>;\n        isUnique: <T extends { constructor: { exists: (query: { [key: string]: unknown }) => Promise<unknown> } }>(fields: string[]) => (this: T, value: unknown) => Promise<boolean>;\n        matchesRegex: (regexArray: RegExp[]) => (value: string) => Promise<boolean>;\n    };\n    migrate: {\n        getModule: () => Promise<typeof migrate>;\n        setConfig: (options: Partial<migrate.config.Config> & { moduleSystem?: 'commonjs' | 'esm' }) => void;\n    };\n    regexify: <T>(filter?: T_QueryFilter<T>, fields?: (keyof T | string)[]) => T_QueryFilter<T>;\n    isDynamicVirtual: <T, R extends string>(options?: T_VirtualOptions<T, R>) => options is I_DynamicVirtualOptions<T, R>;\n    getNewRecords: <T extends I_GenericDocument>(controller: MongoController<T>, recordsToCheck: T[], filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean, filter?: T_Filter<T>) => Promise<T[]>;\n    getExistingRecords: <T extends I_GenericDocument>(controller: MongoController<T>, recordsToCheck: T[], filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean, filter?: T_Filter<T>) => Promise<T_WithId<T>[]>;\n}\n\n/**\n * MongoDB utility object providing comprehensive database operations and utilities.\n * This object contains methods for creating generic fields, applying plugins and middlewares,\n * creating schemas and models, validation functions, migration utilities, and regex filtering.\n */\nexport const mongo: I_MongoUtils = {\n    /**\n     * Creates generic fields that are commonly used across MongoDB documents.\n     * This function generates standard fields including a UUID, deletion flag, and timestamps\n     * that can be applied to any document schema.\n     *\n     * @returns An object containing generic document fields (id, isDel, createdAt, updatedAt).\n     */\n    createGenericFields(): I_GenericDocument {\n        return {\n            id: randomUUID(),\n            isDel: false,\n            createdAt: new Date(),\n            updatedAt: new Date(),\n        };\n    },\n    /**\n     * Applies plugins to a Mongoose schema.\n     * This function filters out falsy plugins and applies the remaining valid plugins\n     * to the provided schema.\n     *\n     * @param schema - The Mongoose schema to apply plugins to.\n     * @param plugins - An array of plugin functions or false values to filter and apply.\n     */\n    applyPlugins<T>(schema: T_MongooseSchema<T>, plugins: Array<T_MongoosePlugin | false>) {\n        plugins\n            .filter((plugin): plugin is T_MongoosePlugin => typeof plugin === 'function')\n            .forEach(plugin => schema.plugin(plugin));\n    },\n    /**\n     * Applies middleware functions to a Mongoose schema.\n     * This function configures pre and post middleware for specified methods on the schema.\n     *\n     * @param schema - The Mongoose schema to apply middleware to.\n     * @param middlewares - An array of middleware configurations with method, pre, and post functions.\n     */\n    applyMiddlewares<T extends Partial<C_Document>>(\n        schema: T_MongooseSchema<T>,\n        middlewares: I_MongooseModelMiddleware<T>[],\n    ) {\n        middlewares.forEach(({ method, pre, post }) => {\n            if (method && pre) {\n                schema.pre(method as RegExp, pre);\n            }\n\n            if (method && post) {\n                schema.post(method as RegExp, post);\n            }\n        });\n    },\n    /**\n     * Creates a generic Mongoose schema with common fields.\n     * This function creates a base schema with UUID field and deletion flag,\n     * configured with automatic timestamps.\n     *\n     * @param mongoose - The Mongoose instance to create the schema with.\n     * @returns A Mongoose schema with generic document fields.\n     */\n    createGenericSchema(mongoose: typeof mongooseRaw) {\n        return new mongoose.Schema<I_GenericDocument>(\n            {\n                id: { type: String, default: () => randomUUID(), unique: true },\n                isDel: { type: Boolean, default: false },\n            },\n            { timestamps: true },\n        );\n    },\n    /**\n     * Creates a Mongoose schema with optional virtual fields and generic fields.\n     * This function creates a new Mongoose schema from the provided schema definition,\n     * optionally adds virtual fields, and includes generic fields (unless standalone is true).\n     *\n     * @param options - Configuration options including mongoose instance, schema definition, virtuals, and standalone flag.\n     * @param options.mongoose - The Mongoose instance to use for schema creation.\n     * @param options.schema - The schema definition object.\n     * @param options.virtuals - Optional array of virtual field configurations.\n     * @param options.standalone - Whether to exclude generic fields (default: false).\n     * @returns A configured Mongoose schema.\n     */\n    createSchema<T, R extends string = string>({\n        mongoose,\n        schema,\n        virtuals = [],\n        standalone = false,\n    }: I_CreateSchemaOptions<T, R>): T_MongooseSchema<T> {\n        const createdSchema = new mongoose.Schema<T>(schema, {\n            toJSON: { virtuals: true }, // So `res.json()` and other `JSON.stringify()` functions include virtuals\n            toObject: { virtuals: true }, // So `console.log()` and other functions that use `toObject()` include virtuals\n        });\n\n        virtuals.forEach(({ name, options, get }) => {\n            if (mongo.isDynamicVirtual<T, R>(options)) {\n                const schemaStatics = createdSchema.statics as Record<string, unknown>;\n\n                if (!schemaStatics['_dynamicVirtuals']) {\n                    schemaStatics['_dynamicVirtuals'] = [];\n                }\n\n                (schemaStatics['_dynamicVirtuals'] as I_DynamicVirtualConfig<T>[]).push({\n                    name: name as string,\n                    options,\n                });\n\n                const virtualInstance = createdSchema.virtual(name as string);\n\n                if (get) {\n                    virtualInstance.get(get);\n                }\n                else {\n                    virtualInstance.get(function (this: T & { _populated?: { [key: string]: unknown } }) {\n                        return this._populated?.[name as string] || (options?.count ? 0 : (options?.justOne ? null : []));\n                    });\n                }\n            }\n            else {\n                const virtualInstance = createdSchema.virtual(name as string, options);\n\n                if (get) {\n                    virtualInstance.get(get);\n                }\n            }\n        });\n\n        if (!standalone) {\n            createdSchema.add(mongo.createGenericSchema(mongoose));\n        }\n\n        return createdSchema;\n    },\n    /**\n     * Creates a Mongoose model with plugins, middleware, and pagination support.\n     * This function creates a model from a schema with optional pagination and aggregation plugins,\n     * and applies any specified middleware. If a model with the same name already exists, it returns the existing model.\n     *\n     * @param options - Configuration options including mongoose instance, model name, schema, and feature flags.\n     * @param options.mongoose - The Mongoose instance to use for model creation.\n     * @param options.name - The name of the model to create.\n     * @param options.schema - The schema definition for the model.\n     * @param options.pagination - Whether to enable pagination plugin (default: false).\n     * @param options.aggregate - Whether to enable aggregation pagination plugin (default: false).\n     * @param options.virtuals - Optional array of virtual field configurations.\n     * @param options.middlewares - Optional array of middleware configurations.\n     * @returns A configured Mongoose model with extended functionality.\n     * @throws {Error} When the model name is not provided.\n     */\n    createModel<T extends Partial<C_Document>, R extends string = string>({\n        mongoose: currentMongooseInstance,\n        name,\n        schema,\n        virtuals = [],\n        pagination = true,\n        aggregate = true,\n        middlewares = [],\n    }: I_CreateModelOptions<T, R>): I_ExtendedModel<T> {\n        if (!name) {\n            throw new Error('Model name is required.');\n        }\n\n        if (currentMongooseInstance.models[name]) {\n            return currentMongooseInstance.models[name] as I_ExtendedModel<T>;\n        }\n\n        const createdSchema = mongo.createSchema({ mongoose: currentMongooseInstance, schema, virtuals });\n\n        if (pagination || aggregate) {\n            mongo.applyPlugins<T>(createdSchema, [\n                pagination && mongoosePaginate,\n                aggregate && aggregatePaginate,\n            ]);\n        }\n\n        mongo.applyMiddlewares<T>(createdSchema, middlewares);\n\n        const model = currentMongooseInstance.model<T>(name, createdSchema) as I_ExtendedModel<T>;\n\n        if (virtuals.length > 0) {\n            // Mongoose Model has no typed _virtualConfigs; used by MongooseController.getDynamicVirtuals()\n            (model as any)._virtualConfigs = virtuals;\n        }\n\n        return model;\n    },\n    /**\n     * Validation utilities for Mongoose schemas.\n     * This object provides common validation functions that can be used in Mongoose schema definitions.\n     */\n    validator: {\n        /**\n         * Creates a required field validator.\n         * This function returns a validator that checks if a field value is not empty\n         * using the validate.isEmpty utility.\n         *\n         * @returns A validation function that returns true if the field is not empty.\n         */\n        isRequired<T>(): (this: T, value: unknown) => Promise<boolean> {\n            return async function (this: T, value: unknown): Promise<boolean> {\n                return !validate.isEmpty(value);\n            };\n        },\n        /**\n         * Creates a unique field validator.\n         * This function returns a validator that checks if a field value is unique\n         * across the specified fields in the collection.\n         *\n         * @param fields - An array of field names to check for uniqueness.\n         * @returns A validation function that returns true if the value is unique across the specified fields.\n         * @throws {Error} When fields is not a non-empty array of strings.\n         */\n        isUnique<T extends { constructor: { exists: (query: { [key: string]: unknown }) => Promise<unknown> } }>(fields: string[]) {\n            return async function (this: T, value: unknown): Promise<boolean> {\n                if (!Array.isArray(fields) || fields.length === 0) {\n                    throw new Error('Fields must be a non-empty array of strings.');\n                }\n\n                const query = { $or: fields.map(field => ({ [field]: value })) };\n                const existingDocument = await this.constructor.exists(query);\n\n                return !existingDocument;\n            };\n        },\n        /**\n         * Creates a regex pattern validator.\n         * This function returns a validator that checks if a string value matches\n         * all provided regular expressions.\n         *\n         * @param regexArray - An array of regular expressions to test against the value.\n         * @returns A validation function that returns true if the value matches all regex patterns.\n         * @throws {Error} When regexArray is not an array of valid RegExp objects.\n         */\n        matchesRegex(regexArray: RegExp[]): (value: string) => Promise<boolean> {\n            return async (value: string): Promise<boolean> => {\n                if (!Array.isArray(regexArray) || regexArray.some(r => !(r instanceof RegExp))) {\n                    throw new Error('regexArray must be an array of valid RegExp objects.');\n                }\n\n                return regexArray.every(regex => regex.test(value));\n            };\n        },\n    },\n    /**\n     * Migration utilities for MongoDB.\n     * This object extends the migrate-mongo library with additional configuration utilities.\n     */\n    migrate: {\n        /**\n         * Lazily loads the migrate-mongo module to avoid eager import overhead.\n         * Use this to access migrate-mongo methods (up, down, status, create) programmatically.\n         *\n         * @returns A promise resolving to the migrate-mongo module.\n         */\n        async getModule(): Promise<typeof migrate> {\n            return (await import('migrate-mongo')).default;\n        },\n        /**\n         * Sets the migration configuration and updates .gitignore.\n         * This function creates a migration configuration file and ensures it's properly\n         * excluded from version control.\n         *\n         * @param options - Migration configuration options to write to the config file.\n         */\n        setConfig: (options: Partial<migrate.config.Config> & { moduleSystem?: 'commonjs' | 'esm' }) => {\n            const optionsJS = `// This file is automatically generated by the Cyberskill CLI.\\nmodule.exports = ${JSON.stringify(options, null, 4)}`;\n\n            writeFileSync(PATH.MIGRATE_MONGO_CONFIG, optionsJS);\n\n            addGitIgnoreEntry(PATH.GIT_IGNORE, MIGRATE_MONGO_CONFIG);\n        },\n    },\n    /**\n     * Converts string values in a filter to regex patterns for case-insensitive search.\n     * This function recursively processes a filter object and converts string values in specified fields\n     * to MongoDB regex patterns that support accented character matching.\n     *\n     * @remarks\n     * **Performance guard:** Input strings are capped at 200 characters to mitigate ReDoS risk.\n     * The generated regex patterns include accented character alternation groups (e.g., `(a|à|á|...)`)\n     * which can be polynomially complex for very long inputs. For production search on large collections,\n     * consider using MongoDB `$text` search indexes instead of `$regex` for better performance.\n     *\n     * @param filter - The filter object to process.\n     * @param fields - An array of field names to convert to regex patterns.\n     * @returns A new filter object with string values converted to regex patterns.\n     */\n    regexify<T>(filter?: T_QueryFilter<T>, fields?: (keyof T | string)[]): T_QueryFilter<T> {\n        if (!filter) {\n            return {} as T_QueryFilter<T>;\n        }\n\n        let newFilter = { ...filter };\n\n        if (!fields || fields.length === 0) {\n            return newFilter;\n        }\n\n        const MAX_REGEX_INPUT_LENGTH = 200;\n\n        for (const field of fields) {\n            const path = field.toString().split('.');\n            const value = getNestedValue(newFilter, path);\n\n            if (typeof value === 'string' && value.length > 0 && value.length <= MAX_REGEX_INPUT_LENGTH) {\n                const regexValue = {\n                    $regex: `.*${regexSearchMapper(value)}.*`,\n                    $options: 'i',\n                };\n\n                newFilter = setNestedValue(newFilter, path, regexValue);\n            }\n        }\n\n        return newFilter;\n    },\n    /**\n     * Checks if a virtual options object has a dynamic ref function.\n     *\n     * @param options - The virtual options to check.\n     * @returns True if the options contain a dynamic ref function.\n     */\n    isDynamicVirtual<T, R extends string = string>(options?: T_VirtualOptions<T, R>): options is I_DynamicVirtualOptions<T, R> {\n        return Boolean(options && typeof options.ref === 'function');\n    },\n\n    /**\n     * Generic utility function to get new records from the database\n     * @param controller - MongoController instance\n     * @param recordsToCheck - Array of records to check\n     * @param filterFn - Function to determine if a record already exists\n     * @param filter - Optional filter to narrow the query\n     * @returns Array of records that don't exist in the database\n     */\n    async getNewRecords<T extends I_GenericDocument>(\n        controller: MongoController<T>,\n        recordsToCheck: T[],\n        filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean,\n        filter: T_Filter<T> = {} as T_Filter<T>,\n    ): Promise<T[]> {\n        const existingRecords = await controller.findAll(filter);\n\n        if (!existingRecords.success) {\n            throw new Error(`Failed to query existing records: ${existingRecords.message}`);\n        }\n\n        if ('truncated' in existingRecords && existingRecords.truncated) {\n            throw new Error('getNewRecords: Results were truncated by the default limit. Use pagination or set an explicit limit to ensure complete data.');\n        }\n\n        const filteredRecords = recordsToCheck.filter(newRecord =>\n            !existingRecords.result.some((existingRecord: T_WithId<T>) =>\n                filterFn(existingRecord, newRecord),\n            ),\n        );\n\n        return filteredRecords;\n    },\n\n    /**\n     * Generic utility function to get existing records that match the filter criteria\n     * @param controller - MongoController instance\n     * @param recordsToCheck - Array of records to check\n     * @param filterFn - Function to determine if a record exists\n     * @param filter - Optional filter to narrow the query\n     * @returns Array of existing records that match the filter criteria\n     * @throws {Error} When the database query fails — prevents silent data inconsistency.\n     */\n    async getExistingRecords<T extends I_GenericDocument>(\n        controller: MongoController<T>,\n        recordsToCheck: T[],\n        filterFn: (existingRecord: T_WithId<T>, newRecord: T) => boolean,\n        filter: T_Filter<T> = {} as T_Filter<T>,\n    ): Promise<T_WithId<T>[]> {\n        const existingRecords = await controller.findAll(filter);\n\n        if (!existingRecords.success) {\n            throw new Error(`Failed to query existing records: ${existingRecords.message}`);\n        }\n\n        if ('truncated' in existingRecords && existingRecords.truncated) {\n            throw new Error('getExistingRecords: Results were truncated by the default limit. Use pagination or set an explicit limit to ensure complete data.');\n        }\n\n        const foundRecords = existingRecords.result.filter((existingRecord: T_WithId<T>) =>\n            recordsToCheck.some((newRecord: T) =>\n                filterFn(existingRecord, newRecord),\n            ),\n        );\n\n        return foundRecords;\n    },\n};\n\nexport { applyNestedPopulate } from './mongo.populate.js';\n"],"mappings":"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"}

package/dist/node/storage/index.js

@@ -1,3 +1,3 @@
-import { NODE_FS_DRIVER_NAME as e, STORAGE_INSTANCE_NAME as t, STORAGE_KEY_EXTENSION as n, STORAGE_STORE_NAME as r } from "./storage.constant.js";
-import { resetStorageForTesting as i, storage as a } from "./storage.util.js";
-export { e as NODE_FS_DRIVER_NAME, t as STORAGE_INSTANCE_NAME, n as STORAGE_KEY_EXTENSION, r as STORAGE_STORE_NAME, i as resetStorageForTesting, a as storage };
+import { STORAGE_KEY_EXTENSION as e } from "./storage.constant.js";
+import { resetStorageForTesting as t, storage as n } from "./storage.util.js";
+export { e as STORAGE_KEY_EXTENSION, t as resetStorageForTesting, n as storage };

package/dist/node/storage/storage.constant.d.ts

@@ -1,4 +1 @@
-export declare const NODE_FS_DRIVER_NAME = "localforage-node-fs";
 export declare const STORAGE_KEY_EXTENSION = ".json";
-export declare const STORAGE_INSTANCE_NAME = "cyberskill";
-export declare const STORAGE_STORE_NAME = "node-storage";

package/dist/node/storage/storage.constant.js

@@ -1,6 +1,6 @@
 //#region src/node/storage/storage.constant.ts
-var e = "localforage-node-fs", t = ".json", n = "cyberskill", r = "node-storage";
+var e = ".json";
 //#endregion
-export { e as NODE_FS_DRIVER_NAME, n as STORAGE_INSTANCE_NAME, t as STORAGE_KEY_EXTENSION, r as STORAGE_STORE_NAME };
+export { e as STORAGE_KEY_EXTENSION };
 
 //# sourceMappingURL=storage.constant.js.map

package/dist/node/storage/storage.constant.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.constant.js","names":[],"sources":["../../../src/node/storage/storage.constant.ts"],"sourcesContent":["export const NODE_FS_DRIVER_NAME = 'localforage-node-fs';\nexport const STORAGE_KEY_EXTENSION = '.json';\nexport const STORAGE_INSTANCE_NAME = 'cyberskill';\nexport const STORAGE_STORE_NAME = 'node-storage';\n"],"mappings":";AAAA,IAAa,IAAsB,uBACtB,IAAwB,SACxB,IAAwB,cACxB,IAAqB"}
+{"version":3,"file":"storage.constant.js","names":[],"sources":["../../../src/node/storage/storage.constant.ts"],"sourcesContent":["export const STORAGE_KEY_EXTENSION = '.json';\n"],"mappings":";AAAA,IAAa,IAAwB"}

package/dist/node/storage/storage.type.d.ts

@@ -1,14 +1,3 @@
-import { default as localForage } from 'localforage';
-export type LocalForageDriver = Parameters<typeof localForage.defineDriver>[0];
-export interface NodeLocalForageOptions {
-    driver?: string | string[];
-    size?: number;
-    version?: number;
-    description?: string;
-    name?: string;
-    storeName?: string;
-    baseDir?: string;
-}
 export interface NodeFsDriverState {
     baseDir: string;
 }

package/dist/node/storage/storage.util.d.ts

@@ -1,6 +1,6 @@
 /**
  * Persistent storage utility object for data persistence across application sessions.
- * This object provides methods for storing, retrieving, and managing data using localForage,
+ * Uses a filesystem-backed driver that stores JSON-encoded values on disk,
  * with automatic initialization and error handling.
  */
 export declare const storage: {

package/dist/node/storage/storage.util.js

@@ -1,120 +1,112 @@
 import { getEnv as e } from "../../config/env/env.util.js";
 import { catchError as t, log as n } from "../log/log.util.js";
-import { NODE_FS_DRIVER_NAME as r, STORAGE_INSTANCE_NAME as i, STORAGE_KEY_EXTENSION as a, STORAGE_STORE_NAME as o } from "./storage.constant.js";
-import s from "localforage";
-import c from "node:path";
-import l from "node:fs/promises";
+import { STORAGE_KEY_EXTENSION as r } from "./storage.constant.js";
+import i from "node:path";
+import a from "node:fs/promises";
 //#region src/node/storage/storage.util.ts
-var u = 200, d = { baseDir: "" };
-function f(e) {
-	return `${encodeURIComponent(e)}${a}`;
+var o = 200, s = { baseDir: "" };
+function c(e) {
+	if (e.length > o) throw RangeError(`Storage key exceeds maximum length of ${o} characters`);
+	return `${encodeURIComponent(e)}${r}`;
 }
-function p(e) {
-	return decodeURIComponent(e.slice(0, -a.length));
+function l(e) {
+	return decodeURIComponent(e.slice(0, -r.length));
 }
-function m(e, t) {
-	return c.join(t, f(e));
+function u(e, t) {
+	return i.join(t, c(e));
 }
-var h = {
-	_driver: r,
-	_support: !0,
-	async _initStorage(t) {
+var d = {
+	async init(t) {
 		try {
-			let n = typeof t == "object" && t && "baseDir" in t ? t.baseDir : void 0;
-			typeof n == "string" && n.length > 0 ? d.baseDir = n : d.baseDir = e().CYBERSKILL_STORAGE_DIRECTORY, await l.mkdir(d.baseDir, { recursive: !0 });
+			typeof t == "string" && t.length > 0 ? s.baseDir = t : s.baseDir = e().CYBERSKILL_STORAGE_DIRECTORY, await a.mkdir(s.baseDir, { recursive: !0 });
 		} catch (e) {
 			throw n.error("[Storage:init]", e), e;
 		}
 	},
 	async clear() {
-		let { baseDir: e } = d;
-		e && (await l.rm(e, {
-			recursive: !0,
-			force: !0
-		}), await l.mkdir(e, { recursive: !0 }));
+		let { baseDir: e } = s;
+		if (!e) return;
+		let t = `${e}.trash.${Date.now()}`, n = `${e}.fresh.${Date.now()}`;
+		try {
+			await a.mkdir(n, { recursive: !0 });
+			try {
+				await a.rename(e, t);
+			} catch {}
+			await a.rename(n, e), a.rm(t, {
+				recursive: !0,
+				force: !0
+			}).catch(() => {});
+		} catch {
+			await a.rm(e, {
+				recursive: !0,
+				force: !0
+			}), await a.mkdir(e, { recursive: !0 }), a.rm(n, {
+				recursive: !0,
+				force: !0
+			}).catch(() => {}), a.rm(t, {
+				recursive: !0,
+				force: !0
+			}).catch(() => {});
+		}
 	},
 	async getItem(e) {
-		let { baseDir: t } = d, n = m(e, t);
+		let { baseDir: t } = s, n = u(e, t);
 		try {
-			let e = await l.readFile(n, "utf8");
+			let e = await a.readFile(n, "utf8");
 			return JSON.parse(e);
 		} catch (e) {
 			if (e.code === "ENOENT") return null;
 			throw e;
 		}
 	},
-	async iterate(e) {
-		let t = await h.keys(), n = 1;
-		for (let r of t) {
-			let t = e(await h.getItem(r), r, n);
-			if (t !== void 0) return t;
-			n += 1;
-		}
-	},
-	async key(e) {
-		return (await h.keys())[e] ?? null;
-	},
 	async keys() {
-		let { baseDir: e } = d;
+		let { baseDir: e } = s;
 		try {
-			return (await l.readdir(e)).filter((e) => e.endsWith(a)).map(p);
+			return (await a.readdir(e)).filter((e) => e.endsWith(r)).map(l);
 		} catch (e) {
 			if (e.code === "ENOENT") return [];
 			throw e;
 		}
 	},
-	async length() {
-		return (await h.keys()).length;
-	},
 	async removeItem(e) {
-		let { baseDir: t } = d, n = m(e, t);
-		await l.rm(n, { force: !0 });
+		let { baseDir: t } = s, n = u(e, t);
+		await a.rm(n, { force: !0 });
 	},
 	async setItem(e, t) {
-		let { baseDir: n } = d, r = m(e, n);
-		return await l.mkdir(n, { recursive: !0 }), await l.writeFile(r, JSON.stringify(t), "utf8"), t;
+		let { baseDir: n } = s, r = u(e, n);
+		return await a.mkdir(n, { recursive: !0 }), await a.writeFile(r, JSON.stringify(t), "utf8"), t;
 	}
-}, g = null, _ = null;
-async function v() {
-	return g ? (await g, _) : (g = (async () => {
-		await s.defineDriver(h), d.baseDir = e().CYBERSKILL_STORAGE_DIRECTORY;
-		let t = await s.getDriver(r);
-		await t._initStorage({
-			baseDir: d.baseDir,
-			name: i,
-			storeName: o
-		}), _ = t;
-	})().catch((e) => {
-		throw g = null, e;
-	}), await g, _);
+}, f = null;
+async function p() {
+	return f ? (await f, d) : (f = d.init().catch((e) => {
+		throw f = null, e;
+	}), await f, d);
 }
-var y = {
+var m = {
 	async get(e) {
-		if (e.length > u) return n.warn(`[Storage:get] Key exceeds maximum length of ${u} characters`), null;
 		try {
-			return await (await v()).getItem(e) ?? null;
+			return await (await p()).getItem(e) ?? null;
 		} catch (e) {
 			return t(e, { returnValue: null });
 		}
 	},
 	async set(e, n) {
-		if (e.length > u) throw RangeError(`Storage key exceeds maximum length of ${u} characters`);
 		try {
-			await (await v()).setItem(e, n);
+			await (await p()).setItem(e, n);
 		} catch (e) {
 			throw t(e), e;
 		}
 	},
 	async remove(e) {
 		try {
-			await (await v()).removeItem(e);
+			await (await p()).removeItem(e);
 		} catch (e) {
 			t(e);
 		}
 	},
 	async keys() {
 		try {
-			let e = await (await v()).keys();
+			let e = await (await p()).keys();
 			return Array.isArray(e) ? e : (n.warn("[Storage:keys] Invalid keys response:", e), []);
 		} catch (e) {
 			return t(e, { returnValue: [] });
@@ -122,16 +114,16 @@ var y = {
 	},
 	async getLogLink(n) {
 		try {
-			return `${c.join(e().CYBERSKILL_STORAGE_DIRECTORY, f(n))} (key: ${n})`;
+			return `${i.join(e().CYBERSKILL_STORAGE_DIRECTORY, c(n))} (key: ${n})`;
 		} catch (e) {
 			return t(e, { returnValue: null });
 		}
 	}
 };
-function b() {
-	g = null, _ = null, d.baseDir = "";
+function h() {
+	f = null, s.baseDir = "";
 }
 //#endregion
-export { b as resetStorageForTesting, y as storage };
+export { h as resetStorageForTesting, m as storage };
 
 //# sourceMappingURL=storage.util.js.map

package/dist/node/storage/storage.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/node/storage/storage.util.ts"],"sourcesContent":["import localForage from 'localforage';\nimport fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport type { LocalForageDriver, NodeFsDriverState, NodeLocalForageOptions } from './storage.type.js';\n\nimport { catchError, log } from '../log/index.js';\nimport { NODE_FS_DRIVER_NAME, STORAGE_INSTANCE_NAME, STORAGE_KEY_EXTENSION, STORAGE_STORE_NAME } from './storage.constant.js';\n\nconst MAX_KEY_LENGTH = 200;\n\nconst nodeFsDriverState: NodeFsDriverState = {\n    baseDir: '',\n};\n\n/**\n * Encodes a storage key into a filename-safe string.\n */\nfunction encodeKey(key: string): string {\n    return `${encodeURIComponent(key)}${STORAGE_KEY_EXTENSION}`;\n}\n\n/**\n * Decodes a filename-safe key back to the original storage key.\n */\nfunction decodeKey(fileName: string): string {\n    return decodeURIComponent(fileName.slice(0, -STORAGE_KEY_EXTENSION.length));\n}\n\n/**\n * Maps a storage key to an absolute file path inside the storage directory.\n */\nfunction getFilePath(key: string, baseDir: string): string {\n    return path.join(baseDir, encodeKey(key));\n}\n\n/**\n * Custom localForage driver that stores JSON-encoded values on the filesystem.\n */\nconst nodeFsDriver: LocalForageDriver = {\n    _driver: NODE_FS_DRIVER_NAME,\n    _support: true,\n    /** Ensures the storage directory exists and respects custom baseDir overrides. */\n    async _initStorage(options: unknown) {\n        try {\n            const baseDirFromOptions = typeof options === 'object' && options !== null && 'baseDir' in options\n                ? (options as { baseDir?: unknown }).baseDir\n                : undefined;\n\n            if (typeof baseDirFromOptions === 'string' && baseDirFromOptions.length > 0) {\n                nodeFsDriverState.baseDir = baseDirFromOptions;\n            }\n            else {\n                nodeFsDriverState.baseDir = getEnv().CYBERSKILL_STORAGE_DIRECTORY;\n            }\n\n            await fs.mkdir(nodeFsDriverState.baseDir, { recursive: true });\n        }\n        catch (error) {\n            log.error('[Storage:init]', error);\n            throw error;\n        }\n    },\n    /** Deletes all stored entries by recreating the directory. Callers must ensure no concurrent operations. */\n    async clear() {\n        const { baseDir } = nodeFsDriverState;\n\n        if (!baseDir) {\n            return;\n        }\n\n        await fs.rm(baseDir, { recursive: true, force: true });\n        await fs.mkdir(baseDir, { recursive: true });\n    },\n    /** Reads and parses a stored value; returns null when the file is missing. */\n    async getItem<T>(key: string): Promise<T | null> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        try {\n            const content = await fs.readFile(filePath, 'utf8');\n\n            return JSON.parse(content) as T;\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return null;\n            }\n            throw error;\n        }\n    },\n    /** Iterates through all keys, invoking the iterator until it returns a value. */\n    async iterate<T, U>(iterator: (value: T, key: string, iterationNumber: number) => U): Promise<U> {\n        const keys = await nodeFsDriver.keys();\n        let iterationNumber = 1;\n\n        for (const key of keys) {\n            const value = await nodeFsDriver.getItem<T>(key);\n\n            const result = iterator(value as T, key, iterationNumber);\n\n            if (result !== undefined) {\n                return result;\n            }\n            iterationNumber += 1;\n        }\n\n        return undefined as unknown as U;\n    },\n    /** Returns the key name at the given index or null when out of bounds. */\n    async key(keyIndex: number): Promise<string> {\n        const keys = await nodeFsDriver.keys();\n\n        return keys[keyIndex] ?? null as unknown as string;\n    },\n    /** Lists all stored keys. */\n    async keys(): Promise<string[]> {\n        const { baseDir } = nodeFsDriverState;\n\n        try {\n            const files = await fs.readdir(baseDir);\n\n            return files\n                .filter(file => file.endsWith(STORAGE_KEY_EXTENSION))\n                .map(decodeKey);\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return [];\n            }\n            throw error;\n        }\n    },\n    /** Returns the count of stored keys. */\n    async length(): Promise<number> {\n        const keys = await nodeFsDriver.keys();\n\n        return keys.length;\n    },\n    /** Removes a stored value for the given key. */\n    async removeItem(key: string): Promise<void> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.rm(filePath, { force: true });\n    },\n    /** Stores a value as JSON on disk. */\n    async setItem<T>(key: string, value: T): Promise<T> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.mkdir(baseDir, { recursive: true });\n        await fs.writeFile(filePath, JSON.stringify(value), 'utf8');\n\n        return value;\n    },\n};\n\nlet initPromise: Promise<void> | null = null;\nlet driverInstance: LocalForageDriver | null = null;\n\n/**\n * Prepares and returns the filesystem-backed localForage driver.\n * We bypass localForage's default driver selection and explicitly initialize\n * our custom driver to ensure Node compatibility.\n */\nasync function ensureLocalForageReady(): Promise<LocalForageDriver> {\n    if (initPromise) {\n        await initPromise;\n        return driverInstance as LocalForageDriver;\n    }\n\n    initPromise = (async () => {\n        await localForage.defineDriver(nodeFsDriver);\n        nodeFsDriverState.baseDir = getEnv().CYBERSKILL_STORAGE_DIRECTORY;\n        const driver = await localForage.getDriver(NODE_FS_DRIVER_NAME);\n\n        const initOptions = {\n            baseDir: nodeFsDriverState.baseDir,\n            name: STORAGE_INSTANCE_NAME,\n            storeName: STORAGE_STORE_NAME,\n        } satisfies NodeLocalForageOptions;\n\n        await driver._initStorage(initOptions as unknown as Parameters<typeof driver._initStorage>[0]);\n        driverInstance = driver;\n    })().catch((error) => {\n        initPromise = null;\n        throw error;\n    });\n\n    await initPromise;\n\n    return driverInstance as LocalForageDriver;\n}\n\n/**\n * Persistent storage utility object for data persistence across application sessions.\n * This object provides methods for storing, retrieving, and managing data using localForage,\n * with automatic initialization and error handling.\n */\nexport const storage = {\n    /**\n     * Retrieves a value from persistent storage by key.\n     * This method fetches data that was previously stored using the set method.\n     * Returns null if the key doesn't exist or if an error occurs.\n     *\n     * @param key - The unique identifier for the stored value.\n     * @returns A promise that resolves to the stored value or null if not found.\n     */\n    async get<T = unknown>(key: string): Promise<T | null> {\n        if (key.length > MAX_KEY_LENGTH) {\n            log.warn(`[Storage:get] Key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);\n            return null;\n        }\n\n        try {\n            const driver = await ensureLocalForageReady();\n            const result = await driver.getItem<T>(key);\n\n            return result ?? null;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n    /**\n     * Stores a value in persistent storage with a unique key.\n     * This method saves data that can be retrieved later using the get method.\n     * The data is automatically serialized and stored in the configured storage directory.\n     *\n     * @param key - The unique identifier for the value to store.\n     * @param value - The data to store (will be automatically serialized).\n     * @returns A promise that resolves when the storage operation is complete.\n     */\n    async set<T = unknown>(key: string, value: T): Promise<void> {\n        if (key.length > MAX_KEY_LENGTH) {\n            throw new RangeError(`Storage key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);\n        }\n\n        try {\n            const driver = await ensureLocalForageReady();\n\n            await driver.setItem(key, value);\n        }\n        catch (error) {\n            catchError(error);\n            throw error;\n        }\n    },\n    /**\n     * Removes a value from persistent storage by key.\n     * This method permanently deletes the stored data associated with the specified key.\n     *\n     * @param key - The unique identifier of the value to remove.\n     * @returns A promise that resolves when the removal operation is complete.\n     */\n    async remove(key: string): Promise<void> {\n        try {\n            const driver = await ensureLocalForageReady();\n\n            await driver.removeItem(key);\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Retrieves all storage keys.\n     * This method returns an array of all keys that currently have stored values.\n     * Returns an empty array if no keys exist or if an error occurs.\n     *\n     * @returns A promise that resolves to an array of storage keys.\n     */\n    async keys(): Promise<string[]> {\n        try {\n            const driver = await ensureLocalForageReady();\n            const keys = await driver.keys();\n\n            if (!Array.isArray(keys)) {\n                log.warn(`[Storage:keys] Invalid keys response:`, keys);\n                return [];\n            }\n\n            return keys;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: [] });\n        }\n    },\n    /**\n     * Gets a human-readable log link for a storage key.\n     * This method provides a formatted string that shows the storage directory path\n     * and the key name for debugging and manual inspection purposes.\n     *\n     * @param key - The storage key to generate a log link for.\n     * @returns A promise that resolves to a formatted log link string or null if an error occurs.\n     */\n    async getLogLink(key: string): Promise<string | null> {\n        try {\n            const storagePath = path.join(getEnv().CYBERSKILL_STORAGE_DIRECTORY, encodeKey(key));\n\n            return `${storagePath} (key: ${key})`;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n\n};\n\n/**\n * Resets all module-level singleton state used by the storage module.\n * Intended for use in tests to ensure isolation between test cases.\n * Do NOT call this in production code.\n */\nexport function resetStorageForTesting(): void {\n    initPromise = null;\n    driverInstance = null;\n    nodeFsDriverState.baseDir = '';\n}\n"],"mappings":"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"}
+{"version":3,"file":"storage.util.js","names":[],"sources":["../../../src/node/storage/storage.util.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { getEnv } from '#config/env/index.js';\n\nimport { catchError, log } from '../log/index.js';\nimport { STORAGE_KEY_EXTENSION } from './storage.constant.js';\n\nconst MAX_KEY_LENGTH = 200;\n\ninterface NodeFsDriverState {\n    baseDir: string;\n}\n\nconst nodeFsDriverState: NodeFsDriverState = {\n    baseDir: '',\n};\n\n/**\n * Encodes a storage key into a filename-safe string.\n * Validates key length before encoding to prevent OS filename limits.\n *\n * @throws {RangeError} When key exceeds maximum length.\n */\nfunction encodeKey(key: string): string {\n    if (key.length > MAX_KEY_LENGTH) {\n        throw new RangeError(`Storage key exceeds maximum length of ${MAX_KEY_LENGTH} characters`);\n    }\n    return `${encodeURIComponent(key)}${STORAGE_KEY_EXTENSION}`;\n}\n\n/**\n * Decodes a filename-safe key back to the original storage key.\n */\nfunction decodeKey(fileName: string): string {\n    return decodeURIComponent(fileName.slice(0, -STORAGE_KEY_EXTENSION.length));\n}\n\n/**\n * Maps a storage key to an absolute file path inside the storage directory.\n */\nfunction getFilePath(key: string, baseDir: string): string {\n    return path.join(baseDir, encodeKey(key));\n}\n\n/**\n * Filesystem-backed storage driver that stores JSON-encoded values on disk.\n * Directly implements all storage operations without any external dependencies.\n * storage operations without the unnecessary browser-oriented dependency.\n */\nconst fsDriver = {\n    /** Ensures the storage directory exists. */\n    async init(baseDir?: string) {\n        try {\n            if (typeof baseDir === 'string' && baseDir.length > 0) {\n                nodeFsDriverState.baseDir = baseDir;\n            }\n            else {\n                nodeFsDriverState.baseDir = getEnv().CYBERSKILL_STORAGE_DIRECTORY;\n            }\n\n            await fs.mkdir(nodeFsDriverState.baseDir, { recursive: true });\n        }\n        catch (error) {\n            log.error('[Storage:init]', error);\n            throw error;\n        }\n    },\n    /** Deletes all stored entries atomically by swapping to a fresh directory. */\n    async clear() {\n        const { baseDir } = nodeFsDriverState;\n\n        if (!baseDir) {\n            return;\n        }\n\n        // Atomic swap: create a fresh temp dir, rename old→trash, rename fresh→baseDir, remove trash\n        const trashDir = `${baseDir}.trash.${Date.now()}`;\n        const freshDir = `${baseDir}.fresh.${Date.now()}`;\n\n        try {\n            await fs.mkdir(freshDir, { recursive: true });\n            // Try atomic rename swap\n            try {\n                await fs.rename(baseDir, trashDir);\n            }\n            catch {\n                // baseDir might not exist yet; no-op\n            }\n            await fs.rename(freshDir, baseDir);\n            // Clean up trash in the background (non-blocking)\n            fs.rm(trashDir, { recursive: true, force: true }).catch(() => {});\n        }\n        catch {\n            // Fallback: non-atomic clear (e.g., cross-device rename)\n            await fs.rm(baseDir, { recursive: true, force: true });\n            await fs.mkdir(baseDir, { recursive: true });\n            // Clean up any leftover temp dirs\n            fs.rm(freshDir, { recursive: true, force: true }).catch(() => {});\n            fs.rm(trashDir, { recursive: true, force: true }).catch(() => {});\n        }\n    },\n    /** Reads and parses a stored value; returns null when the file is missing. */\n    async getItem<T>(key: string): Promise<T | null> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        try {\n            const content = await fs.readFile(filePath, 'utf8');\n\n            return JSON.parse(content) as T;\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return null;\n            }\n            throw error;\n        }\n    },\n    /** Lists all stored keys. */\n    async keys(): Promise<string[]> {\n        const { baseDir } = nodeFsDriverState;\n\n        try {\n            const files = await fs.readdir(baseDir);\n\n            return files\n                .filter(file => file.endsWith(STORAGE_KEY_EXTENSION))\n                .map(decodeKey);\n        }\n        catch (error) {\n            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n                return [];\n            }\n            throw error;\n        }\n    },\n    /** Removes a stored value for the given key. */\n    async removeItem(key: string): Promise<void> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.rm(filePath, { force: true });\n    },\n    /** Stores a value as JSON on disk. */\n    async setItem<T>(key: string, value: T): Promise<T> {\n        const { baseDir } = nodeFsDriverState;\n        const filePath = getFilePath(key, baseDir);\n\n        await fs.mkdir(baseDir, { recursive: true });\n        await fs.writeFile(filePath, JSON.stringify(value), 'utf8');\n\n        return value;\n    },\n};\n\nlet initPromise: Promise<void> | null = null;\n\n/**\n * Initializes the filesystem storage driver (singleton, idempotent).\n * Ensures the storage directory exists before any read/write operations.\n */\nasync function ensureDriverReady(): Promise<typeof fsDriver> {\n    if (initPromise) {\n        await initPromise;\n        return fsDriver;\n    }\n\n    initPromise = fsDriver.init().catch((error) => {\n        initPromise = null;\n        throw error;\n    });\n\n    await initPromise;\n\n    return fsDriver;\n}\n\n/**\n * Persistent storage utility object for data persistence across application sessions.\n * Uses a filesystem-backed driver that stores JSON-encoded values on disk,\n * with automatic initialization and error handling.\n */\nexport const storage = {\n    /**\n     * Retrieves a value from persistent storage by key.\n     * This method fetches data that was previously stored using the set method.\n     * Returns null if the key doesn't exist or if an error occurs.\n     *\n     * @param key - The unique identifier for the stored value.\n     * @returns A promise that resolves to the stored value or null if not found.\n     */\n    async get<T = unknown>(key: string): Promise<T | null> {\n        try {\n            const driver = await ensureDriverReady();\n            const result = await driver.getItem<T>(key);\n\n            return result ?? null;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n    /**\n     * Stores a value in persistent storage with a unique key.\n     * This method saves data that can be retrieved later using the get method.\n     * The data is automatically serialized and stored in the configured storage directory.\n     *\n     * @param key - The unique identifier for the value to store.\n     * @param value - The data to store (will be automatically serialized).\n     * @returns A promise that resolves when the storage operation is complete.\n     */\n    async set<T = unknown>(key: string, value: T): Promise<void> {\n        try {\n            const driver = await ensureDriverReady();\n\n            await driver.setItem(key, value);\n        }\n        catch (error) {\n            catchError(error);\n            throw error;\n        }\n    },\n    /**\n     * Removes a value from persistent storage by key.\n     * This method permanently deletes the stored data associated with the specified key.\n     *\n     * @param key - The unique identifier of the value to remove.\n     * @returns A promise that resolves when the removal operation is complete.\n     */\n    async remove(key: string): Promise<void> {\n        try {\n            const driver = await ensureDriverReady();\n\n            await driver.removeItem(key);\n        }\n        catch (error) {\n            catchError(error);\n        }\n    },\n    /**\n     * Retrieves all storage keys.\n     * This method returns an array of all keys that currently have stored values.\n     * Returns an empty array if no keys exist or if an error occurs.\n     *\n     * @returns A promise that resolves to an array of storage keys.\n     */\n    async keys(): Promise<string[]> {\n        try {\n            const driver = await ensureDriverReady();\n            const keys = await driver.keys();\n\n            if (!Array.isArray(keys)) {\n                log.warn(`[Storage:keys] Invalid keys response:`, keys);\n                return [];\n            }\n\n            return keys;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: [] });\n        }\n    },\n    /**\n     * Gets a human-readable log link for a storage key.\n     * This method provides a formatted string that shows the storage directory path\n     * and the key name for debugging and manual inspection purposes.\n     *\n     * @param key - The storage key to generate a log link for.\n     * @returns A promise that resolves to a formatted log link string or null if an error occurs.\n     */\n    async getLogLink(key: string): Promise<string | null> {\n        try {\n            const storagePath = path.join(getEnv().CYBERSKILL_STORAGE_DIRECTORY, encodeKey(key));\n\n            return `${storagePath} (key: ${key})`;\n        }\n        catch (error) {\n            return catchError(error, { returnValue: null });\n        }\n    },\n\n};\n\n/**\n * Resets all module-level singleton state used by the storage module.\n * Intended for use in tests to ensure isolation between test cases.\n * Do NOT call this in production code.\n */\nexport function resetStorageForTesting(): void {\n    initPromise = null;\n    nodeFsDriverState.baseDir = '';\n}\n"],"mappings":";;;;;;AAQA,IAAM,IAAiB,KAMjB,IAAuC,EACzC,SAAS,IACZ;AAQD,SAAS,EAAU,GAAqB;AACpC,KAAI,EAAI,SAAS,EACb,OAAU,WAAW,yCAAyC,EAAe,aAAa;AAE9F,QAAO,GAAG,mBAAmB,EAAI,GAAG;;AAMxC,SAAS,EAAU,GAA0B;AACzC,QAAO,mBAAmB,EAAS,MAAM,GAAG,CAAC,EAAsB,OAAO,CAAC;;AAM/E,SAAS,EAAY,GAAa,GAAyB;AACvD,QAAO,EAAK,KAAK,GAAS,EAAU,EAAI,CAAC;;AAQ7C,IAAM,IAAW;CAEb,MAAM,KAAK,GAAkB;AACzB,MAAI;AAQA,GAPI,OAAO,KAAY,YAAY,EAAQ,SAAS,IAChD,EAAkB,UAAU,IAG5B,EAAkB,UAAU,GAAQ,CAAC,8BAGzC,MAAM,EAAG,MAAM,EAAkB,SAAS,EAAE,WAAW,IAAM,CAAC;WAE3D,GAAO;AAEV,SADA,EAAI,MAAM,kBAAkB,EAAM,EAC5B;;;CAId,MAAM,QAAQ;EACV,IAAM,EAAE,eAAY;AAEpB,MAAI,CAAC,EACD;EAIJ,IAAM,IAAW,GAAG,EAAQ,SAAS,KAAK,KAAK,IACzC,IAAW,GAAG,EAAQ,SAAS,KAAK,KAAK;AAE/C,MAAI;AACA,SAAM,EAAG,MAAM,GAAU,EAAE,WAAW,IAAM,CAAC;AAE7C,OAAI;AACA,UAAM,EAAG,OAAO,GAAS,EAAS;WAEhC;AAKN,GAFA,MAAM,EAAG,OAAO,GAAU,EAAQ,EAElC,EAAG,GAAG,GAAU;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAAC,YAAY,GAAG;UAE/D;AAMF,GAJA,MAAM,EAAG,GAAG,GAAS;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,EACtD,MAAM,EAAG,MAAM,GAAS,EAAE,WAAW,IAAM,CAAC,EAE5C,EAAG,GAAG,GAAU;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAAC,YAAY,GAAG,EACjE,EAAG,GAAG,GAAU;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAAC,YAAY,GAAG;;;CAIzE,MAAM,QAAW,GAAgC;EAC7C,IAAM,EAAE,eAAY,GACd,IAAW,EAAY,GAAK,EAAQ;AAE1C,MAAI;GACA,IAAM,IAAU,MAAM,EAAG,SAAS,GAAU,OAAO;AAEnD,UAAO,KAAK,MAAM,EAAQ;WAEvB,GAAO;AACV,OAAK,EAAgC,SAAS,SAC1C,QAAO;AAEX,SAAM;;;CAId,MAAM,OAA0B;EAC5B,IAAM,EAAE,eAAY;AAEpB,MAAI;AAGA,WAFc,MAAM,EAAG,QAAQ,EAAQ,EAGlC,QAAO,MAAQ,EAAK,SAAS,EAAsB,CAAC,CACpD,IAAI,EAAU;WAEhB,GAAO;AACV,OAAK,EAAgC,SAAS,SAC1C,QAAO,EAAE;AAEb,SAAM;;;CAId,MAAM,WAAW,GAA4B;EACzC,IAAM,EAAE,eAAY,GACd,IAAW,EAAY,GAAK,EAAQ;AAE1C,QAAM,EAAG,GAAG,GAAU,EAAE,OAAO,IAAM,CAAC;;CAG1C,MAAM,QAAW,GAAa,GAAsB;EAChD,IAAM,EAAE,eAAY,GACd,IAAW,EAAY,GAAK,EAAQ;AAK1C,SAHA,MAAM,EAAG,MAAM,GAAS,EAAE,WAAW,IAAM,CAAC,EAC5C,MAAM,EAAG,UAAU,GAAU,KAAK,UAAU,EAAM,EAAE,OAAO,EAEpD;;CAEd,EAEG,IAAoC;AAMxC,eAAe,IAA8C;AAazD,QAZI,KACA,MAAM,GACC,MAGX,IAAc,EAAS,MAAM,CAAC,OAAO,MAAU;AAE3C,QADA,IAAc,MACR;GACR,EAEF,MAAM,GAEC;;AAQX,IAAa,IAAU;CASnB,MAAM,IAAiB,GAAgC;AACnD,MAAI;AAIA,UAFe,OADA,MAAM,GAAmB,EACZ,QAAW,EAAI,IAE1B;WAEd,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,MAAM,CAAC;;;CAYvD,MAAM,IAAiB,GAAa,GAAyB;AACzD,MAAI;AAGA,UAFe,MAAM,GAAmB,EAE3B,QAAQ,GAAK,EAAM;WAE7B,GAAO;AAEV,SADA,EAAW,EAAM,EACX;;;CAUd,MAAM,OAAO,GAA4B;AACrC,MAAI;AAGA,UAFe,MAAM,GAAmB,EAE3B,WAAW,EAAI;WAEzB,GAAO;AACV,KAAW,EAAM;;;CAUzB,MAAM,OAA0B;AAC5B,MAAI;GAEA,IAAM,IAAO,OADE,MAAM,GAAmB,EACd,MAAM;AAOhC,UALK,MAAM,QAAQ,EAAK,GAKjB,KAJH,EAAI,KAAK,yCAAyC,EAAK,EAChD,EAAE;WAKV,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,EAAE,EAAE,CAAC;;;CAWrD,MAAM,WAAW,GAAqC;AAClD,MAAI;AAGA,UAAO,GAFa,EAAK,KAAK,GAAQ,CAAC,8BAA8B,EAAU,EAAI,CAAC,CAE9D,SAAS,EAAI;WAEhC,GAAO;AACV,UAAO,EAAW,GAAO,EAAE,aAAa,MAAM,CAAC;;;CAI1D;AAOD,SAAgB,IAA+B;AAE3C,CADA,IAAc,MACd,EAAkB,UAAU"}

package/dist/node/upload/upload.type.d.ts

@@ -32,4 +32,6 @@ export interface I_UploadOptions {
     path: string;
     type: E_UploadType;
     config?: I_UploadConfig;
+    /** Base directory for path containment validation. When set, the resolved `path` must reside within this directory. */
+    baseDir?: string;
 }

package/dist/node/upload/upload.type.js.map

@@ -1 +1 @@
-{"version":3,"file":"upload.type.js","names":[],"sources":["../../../src/node/upload/upload.type.ts"],"sourcesContent":["export enum E_UploadType {\n    IMAGE = 'IMAGE',\n    VIDEO = 'VIDEO',\n    AUDIO = 'AUDIO',\n    DOCUMENT = 'DOCUMENT',\n    OTHER = 'OTHER',\n}\n\nexport interface I_UploadValidationConfig {\n    filename: string;\n    fileSize?: number;\n}\n\nexport interface I_UploadTypeConfig {\n    allowedExtensions: string[];\n    sizeLimit: number;\n}\n\nexport interface I_UploadConfig {\n    [E_UploadType.IMAGE]: I_UploadTypeConfig;\n    [E_UploadType.VIDEO]: I_UploadTypeConfig;\n    [E_UploadType.AUDIO]: I_UploadTypeConfig;\n    [E_UploadType.DOCUMENT]: I_UploadTypeConfig;\n    [E_UploadType.OTHER]: I_UploadTypeConfig;\n}\n\nexport interface I_UploadFileData {\n    createReadStream: () => NodeJS.ReadableStream;\n    filename: string;\n}\n\nexport interface I_UploadFile {\n    file: I_UploadFileData;\n}\n\nexport interface I_UploadOptions {\n    file: Promise<I_UploadFile>;\n    path: string;\n    type: E_UploadType;\n    config?: I_UploadConfig;\n}\n"],"mappings":";AAAA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,WAAA,YACA,EAAA,QAAA;KACH"}
+{"version":3,"file":"upload.type.js","names":[],"sources":["../../../src/node/upload/upload.type.ts"],"sourcesContent":["export enum E_UploadType {\n    IMAGE = 'IMAGE',\n    VIDEO = 'VIDEO',\n    AUDIO = 'AUDIO',\n    DOCUMENT = 'DOCUMENT',\n    OTHER = 'OTHER',\n}\n\nexport interface I_UploadValidationConfig {\n    filename: string;\n    fileSize?: number;\n}\n\nexport interface I_UploadTypeConfig {\n    allowedExtensions: string[];\n    sizeLimit: number;\n}\n\nexport interface I_UploadConfig {\n    [E_UploadType.IMAGE]: I_UploadTypeConfig;\n    [E_UploadType.VIDEO]: I_UploadTypeConfig;\n    [E_UploadType.AUDIO]: I_UploadTypeConfig;\n    [E_UploadType.DOCUMENT]: I_UploadTypeConfig;\n    [E_UploadType.OTHER]: I_UploadTypeConfig;\n}\n\nexport interface I_UploadFileData {\n    createReadStream: () => NodeJS.ReadableStream;\n    filename: string;\n}\n\nexport interface I_UploadFile {\n    file: I_UploadFileData;\n}\n\nexport interface I_UploadOptions {\n    file: Promise<I_UploadFile>;\n    path: string;\n    type: E_UploadType;\n    config?: I_UploadConfig;\n    /** Base directory for path containment validation. When set, the resolved `path` must reside within this directory. */\n    baseDir?: string;\n}\n"],"mappings":";AAAA,IAAY,IAAL,yBAAA,GAAA;QACH,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,QAAA,SACA,EAAA,WAAA,YACA,EAAA,QAAA;KACH"}

package/dist/node/upload/upload.util.js

@@ -74,13 +74,21 @@ function _(e) {
 	};
 }
 async function v(n) {
-	let { path: r, file: c, config: u, type: d } = n;
+	let { path: r, file: c, config: u, type: d, baseDir: f } = n;
 	if (!r || typeof r != "string") return {
 		success: !1,
 		message: "Invalid path provided",
 		code: e.BAD_REQUEST.CODE
 	};
-	if (l.resolve(r) !== l.normalize(r) && r.includes("..")) return {
+	let m = l.resolve(r);
+	if (f) {
+		let t = l.resolve(f) + l.sep;
+		if (!m.startsWith(t) && m !== l.resolve(f)) return {
+			success: !1,
+			message: "Path traversal detected: path resolves outside the allowed base directory",
+			code: e.BAD_REQUEST.CODE
+		};
+	} else if (r.includes("..")) return {
 		success: !1,
 		message: "Path traversal detected: \"..\" segments are not allowed",
 		code: e.BAD_REQUEST.CODE

package/dist/node/upload/upload.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"upload.util.js","names":[],"sources":["../../../src/node/upload/upload.util.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\nimport nodePath from 'node:path';\nimport { Transform } from 'node:stream';\nimport { ReadableStream } from 'node:stream/web';\n\nimport type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\n\nimport type { I_UploadConfig, I_UploadFile, I_UploadFileData, I_UploadOptions, I_UploadTypeConfig, I_UploadValidationConfig } from './upload.type.js';\n\nimport { createWriteStream, mkdirSync, pathExistsSync } from '../fs/index.js';\nimport { dirname } from '../path/index.js';\nimport { BYTES_PER_MB, DEFAULT_UPLOAD_CONFIG } from './upload.constant.js';\nimport { E_UploadType } from './upload.type.js';\n\n/**\n * Calculates the size of a file from a readable stream.\n * This function reads through the entire stream to determine the total byte size\n * by accumulating the length of each data chunk.\n *\n * @param stream - The readable stream to calculate the size for.\n * @returns A promise that resolves to the total size of the stream in bytes.\n */\nexport async function getFileSizeFromStream(stream: NodeJS.ReadableStream): Promise<number> {\n    return new Promise((resolve, reject) => {\n        let size = 0;\n        stream.on('data', (chunk) => {\n            size += chunk.length;\n        });\n        stream.on('end', () => resolve(size));\n        stream.on('error', reject);\n    });\n}\n\n/**\n * Extracts and validates file data from an upload file.\n * This function processes upload files by:\n * - Extracting file metadata and creating a readable stream\n * - Calculating the file size from the stream\n * - Validating file size and extension against upload configuration\n * - Returning a standardized response with success status and error codes\n * - Providing validated file data for further processing\n *\n * @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing validated file data or error information.\n */\nexport async function getAndValidateFile(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<I_UploadFileData>> {\n    const fileData = await (await file).file;\n    const stream = fileData.createReadStream();\n    // Stream is consumed here for validation; callers use createReadStream() again for the actual write.\n    // This is intentional — createReadStream() is a factory that yields a new stream per call.\n    const fileSize = await getFileSizeFromStream(stream);\n    const uploadConfig = config ?? createUploadConfig();\n\n    const validationResult = validateUpload(\n        { filename: fileData.filename, fileSize },\n        uploadConfig,\n        type,\n    );\n\n    if (!validationResult.isValid) {\n        return {\n            success: false,\n            message: validationResult.error || 'File validation failed',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    return {\n        success: true,\n        result: fileData,\n        message: 'File validated successfully',\n    };\n}\n\n/**\n * Creates a validated web-readable stream from an upload file with size validation.\n * This function processes file uploads for web environments by:\n * - Validating file data using getAndValidateFile function\n * - Creating a size validation transform stream to monitor upload progress\n * - Returning a web-compatible ReadableStream with real-time validation\n * - Providing standardized error responses for validation failures\n * - Wrapping the stream in a standardized response format\n *\n * @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing either a web ReadableStream or error information.\n */\nexport async function getFileWebStream(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<ReadableStream<Uint8Array>>> {\n    const uploadConfig = config ?? createUploadConfig();\n    const typeConfig = uploadConfig[type];\n\n    const fileData = await getAndValidateFile(type, file, config);\n\n    if (!fileData.success) {\n        return fileData;\n    }\n\n    const { createReadStream } = fileData.result;\n\n    let remainingBytes = typeConfig.sizeLimit;\n\n    const sizeValidationStream = new Transform({\n        transform(chunk: Buffer, _enc: BufferEncoding, cb) {\n            remainingBytes -= chunk.length;\n\n            if (remainingBytes < 0) {\n                cb(new Error(`File size exceeds limit of ${typeConfig.sizeLimit / BYTES_PER_MB}MB`));\n            }\n            else {\n                cb(null, chunk);\n            }\n        },\n    });\n    const originalStream = createReadStream();\n    const validatedStream = originalStream.pipe(sizeValidationStream);\n\n    return {\n        success: true,\n        result: new ReadableStream<Uint8Array>({\n            start(controller) {\n                validatedStream.on('data', (chunk: Buffer | string) => {\n                    controller.enqueue(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);\n                });\n                validatedStream.on('end', () => controller.close());\n                validatedStream.on('error', (err: unknown) => controller.error(err));\n            },\n        }),\n    };\n}\n\n/**\n * Validates if a file has an allowed extension.\n * This function extracts the file extension from the filename and checks if it's\n * included in the list of allowed extensions (case-insensitive comparison).\n *\n * @param filename - The filename to check for valid extension.\n * @param allowedExtensions - An array of allowed file extensions (without dots).\n * @returns True if the file extension is allowed, false otherwise.\n */\nexport function validateFileExtension(filename: string, allowedExtensions: string[]): boolean {\n    const lastDotIndex = filename.lastIndexOf('.');\n\n    if (lastDotIndex === -1) {\n        return false;\n    }\n\n    const extension = filename.substring(lastDotIndex + 1).toLowerCase();\n\n    return allowedExtensions.includes(extension);\n}\n\n/**\n * Validates an upload against the specified configuration.\n * This function performs comprehensive validation including:\n * - File extension validation against allowed extensions\n * - File size validation against size limits\n * - Returns detailed error messages for validation failures\n *\n * @param config - The validation configuration including filename and optional file size.\n * @param uploadConfig - The upload configuration containing allowed extensions and size limits.\n * @param uploadType - The type of upload being validated.\n * @returns An object indicating validation success and optional error message.\n */\nexport function validateUpload(\n    config: I_UploadValidationConfig,\n    uploadConfig: I_UploadConfig,\n    uploadType: E_UploadType,\n): { isValid: boolean; error?: string } {\n    const { filename, fileSize } = config;\n    const typeConfig: I_UploadTypeConfig = uploadConfig[uploadType];\n\n    const { allowedExtensions, sizeLimit } = typeConfig;\n\n    if (!validateFileExtension(filename, allowedExtensions)) {\n        return {\n            isValid: false,\n            error: `File extension not allowed for ${uploadType.toLowerCase()} files. Allowed extensions: ${allowedExtensions.join(', ')}`,\n        };\n    }\n\n    if (fileSize !== undefined && fileSize > sizeLimit) {\n        const maxSizeMB = Math.round(sizeLimit / (1024 * 1024));\n\n        return {\n            isValid: false,\n            error: `File size exceeds limit for ${uploadType.toLowerCase()} files. Maximum size: ${maxSizeMB}MB`,\n        };\n    }\n\n    return { isValid: true };\n}\n\n/**\n * Creates a default upload configuration with predefined settings for different file types.\n * This function provides sensible defaults for image, video, document, and other file types,\n * including allowed extensions and size limits. The configuration can be customized with overrides.\n *\n * @param overrides - Optional configuration overrides to merge with the default configuration.\n * @returns A complete upload configuration object with defaults and any provided overrides.\n */\nexport function createUploadConfig(overrides?: Partial<I_UploadConfig>): I_UploadConfig {\n    return { ...DEFAULT_UPLOAD_CONFIG, ...overrides };\n}\n\n/**\n * Uploads a file with comprehensive validation and error handling.\n * This function processes file uploads with the following features:\n * - Input validation for path and file parameters\n * - Configuration validation for all upload types\n * - File validation using getAndValidateFile function\n * - Automatic directory creation\n * - Stream-based file writing\n * - Comprehensive error handling with standardized response codes\n *\n * @param options - Upload configuration including file, path, type, and optional validation config.\n * @returns A promise that resolves to a standardized response with success status, message, file path, and response codes.\n */\nexport async function upload(options: I_UploadOptions): Promise<I_Return<string>> {\n    const { path, file, config, type } = options;\n\n    if (!path || typeof path !== 'string') {\n        return {\n            success: false,\n            message: 'Invalid path provided',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    // Security: Prevent directory traversal attacks by checking the resolved path\n    const resolvedPath = nodePath.resolve(path);\n\n    if (resolvedPath !== nodePath.normalize(path) && path.includes('..')) {\n        return {\n            success: false,\n            message: 'Path traversal detected: \"..\" segments are not allowed',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    if (!file || typeof file !== 'object') {\n        return {\n            success: false,\n            message: 'Invalid file provided',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    if (config) {\n        const requiredTypes = [E_UploadType.IMAGE, E_UploadType.VIDEO, E_UploadType.DOCUMENT, E_UploadType.OTHER];\n\n        for (const requiredType of requiredTypes) {\n            if (!config[requiredType] || !Array.isArray(config[requiredType].allowedExtensions) || config[requiredType].allowedExtensions.length === 0) {\n                return {\n                    success: false,\n                    message: `Invalid config for ${requiredType.toLowerCase()} files`,\n                    code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n                };\n            }\n            if (typeof config[requiredType].sizeLimit !== 'number' || config[requiredType].sizeLimit <= 0) {\n                return {\n                    success: false,\n                    message: `Invalid size limit for ${requiredType.toLowerCase()} files`,\n                    code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n                };\n            }\n        }\n    }\n\n    try {\n        const fileData = await getAndValidateFile(type, await file, config);\n\n        if (!fileData.success) {\n            return fileData;\n        }\n\n        const { createReadStream } = fileData.result;\n\n        const dir = dirname(path);\n\n        if (!pathExistsSync(dir)) {\n            mkdirSync(dir, { recursive: true });\n        }\n\n        const writeStream = createReadStream();\n        const out = createWriteStream(path);\n        writeStream.pipe(out);\n\n        await new Promise<void>((resolve, reject) => {\n            out.on('finish', () => resolve());\n            out.on('error', reject);\n            writeStream.on('error', reject);\n        });\n\n        return {\n            success: true,\n            result: path,\n            message: 'File uploaded successfully',\n            code: RESPONSE_STATUS.OK.CODE,\n        };\n    }\n    catch (error) {\n        return {\n            success: false,\n            message: error instanceof Error ? error.message : 'File upload failed',\n            code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n        };\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"upload.util.js","names":[],"sources":["../../../src/node/upload/upload.util.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\nimport nodePath from 'node:path';\nimport { Transform } from 'node:stream';\nimport { ReadableStream } from 'node:stream/web';\n\nimport type { I_Return } from '#typescript/index.js';\n\nimport { RESPONSE_STATUS } from '#constant/index.js';\n\nimport type { I_UploadConfig, I_UploadFile, I_UploadFileData, I_UploadOptions, I_UploadTypeConfig, I_UploadValidationConfig } from './upload.type.js';\n\nimport { createWriteStream, mkdirSync, pathExistsSync } from '../fs/index.js';\nimport { dirname } from '../path/index.js';\nimport { BYTES_PER_MB, DEFAULT_UPLOAD_CONFIG } from './upload.constant.js';\nimport { E_UploadType } from './upload.type.js';\n\n/**\n * Calculates the size of a file from a readable stream.\n * This function reads through the entire stream to determine the total byte size\n * by accumulating the length of each data chunk.\n *\n * @param stream - The readable stream to calculate the size for.\n * @returns A promise that resolves to the total size of the stream in bytes.\n */\nexport async function getFileSizeFromStream(stream: NodeJS.ReadableStream): Promise<number> {\n    return new Promise((resolve, reject) => {\n        let size = 0;\n        stream.on('data', (chunk) => {\n            size += chunk.length;\n        });\n        stream.on('end', () => resolve(size));\n        stream.on('error', reject);\n    });\n}\n\n/**\n * Extracts and validates file data from an upload file.\n * This function processes upload files by:\n * - Extracting file metadata and creating a readable stream\n * - Calculating the file size from the stream\n * - Validating file size and extension against upload configuration\n * - Returning a standardized response with success status and error codes\n * - Providing validated file data for further processing\n *\n * @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing validated file data or error information.\n */\nexport async function getAndValidateFile(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<I_UploadFileData>> {\n    const fileData = await (await file).file;\n    const stream = fileData.createReadStream();\n    // Stream is consumed here for validation; callers use createReadStream() again for the actual write.\n    // This is intentional — createReadStream() is a factory that yields a new stream per call.\n    const fileSize = await getFileSizeFromStream(stream);\n    const uploadConfig = config ?? createUploadConfig();\n\n    const validationResult = validateUpload(\n        { filename: fileData.filename, fileSize },\n        uploadConfig,\n        type,\n    );\n\n    if (!validationResult.isValid) {\n        return {\n            success: false,\n            message: validationResult.error || 'File validation failed',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    return {\n        success: true,\n        result: fileData,\n        message: 'File validated successfully',\n    };\n}\n\n/**\n * Creates a validated web-readable stream from an upload file with size validation.\n * This function processes file uploads for web environments by:\n * - Validating file data using getAndValidateFile function\n * - Creating a size validation transform stream to monitor upload progress\n * - Returning a web-compatible ReadableStream with real-time validation\n * - Providing standardized error responses for validation failures\n * - Wrapping the stream in a standardized response format\n *\n * @param type - The type of upload being processed (IMAGE, VIDEO, DOCUMENT, OTHER).\n * @param file - The upload file object containing file metadata and stream creation method.\n * @param config - Optional upload configuration. If not provided, uses default configuration.\n * @returns A promise that resolves to a standardized response containing either a web ReadableStream or error information.\n */\nexport async function getFileWebStream(type: E_UploadType, file: I_UploadFile, config?: I_UploadConfig): Promise<I_Return<ReadableStream<Uint8Array>>> {\n    const uploadConfig = config ?? createUploadConfig();\n    const typeConfig = uploadConfig[type];\n\n    const fileData = await getAndValidateFile(type, file, config);\n\n    if (!fileData.success) {\n        return fileData;\n    }\n\n    const { createReadStream } = fileData.result;\n\n    let remainingBytes = typeConfig.sizeLimit;\n\n    const sizeValidationStream = new Transform({\n        transform(chunk: Buffer, _enc: BufferEncoding, cb) {\n            remainingBytes -= chunk.length;\n\n            if (remainingBytes < 0) {\n                cb(new Error(`File size exceeds limit of ${typeConfig.sizeLimit / BYTES_PER_MB}MB`));\n            }\n            else {\n                cb(null, chunk);\n            }\n        },\n    });\n    const originalStream = createReadStream();\n    const validatedStream = originalStream.pipe(sizeValidationStream);\n\n    return {\n        success: true,\n        result: new ReadableStream<Uint8Array>({\n            start(controller) {\n                validatedStream.on('data', (chunk: Buffer | string) => {\n                    controller.enqueue(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);\n                });\n                validatedStream.on('end', () => controller.close());\n                validatedStream.on('error', (err: unknown) => controller.error(err));\n            },\n        }),\n    };\n}\n\n/**\n * Validates if a file has an allowed extension.\n * This function extracts the file extension from the filename and checks if it's\n * included in the list of allowed extensions (case-insensitive comparison).\n *\n * @param filename - The filename to check for valid extension.\n * @param allowedExtensions - An array of allowed file extensions (without dots).\n * @returns True if the file extension is allowed, false otherwise.\n */\nexport function validateFileExtension(filename: string, allowedExtensions: string[]): boolean {\n    const lastDotIndex = filename.lastIndexOf('.');\n\n    if (lastDotIndex === -1) {\n        return false;\n    }\n\n    const extension = filename.substring(lastDotIndex + 1).toLowerCase();\n\n    return allowedExtensions.includes(extension);\n}\n\n/**\n * Validates an upload against the specified configuration.\n * This function performs comprehensive validation including:\n * - File extension validation against allowed extensions\n * - File size validation against size limits\n * - Returns detailed error messages for validation failures\n *\n * @param config - The validation configuration including filename and optional file size.\n * @param uploadConfig - The upload configuration containing allowed extensions and size limits.\n * @param uploadType - The type of upload being validated.\n * @returns An object indicating validation success and optional error message.\n */\nexport function validateUpload(\n    config: I_UploadValidationConfig,\n    uploadConfig: I_UploadConfig,\n    uploadType: E_UploadType,\n): { isValid: boolean; error?: string } {\n    const { filename, fileSize } = config;\n    const typeConfig: I_UploadTypeConfig = uploadConfig[uploadType];\n\n    const { allowedExtensions, sizeLimit } = typeConfig;\n\n    if (!validateFileExtension(filename, allowedExtensions)) {\n        return {\n            isValid: false,\n            error: `File extension not allowed for ${uploadType.toLowerCase()} files. Allowed extensions: ${allowedExtensions.join(', ')}`,\n        };\n    }\n\n    if (fileSize !== undefined && fileSize > sizeLimit) {\n        const maxSizeMB = Math.round(sizeLimit / (1024 * 1024));\n\n        return {\n            isValid: false,\n            error: `File size exceeds limit for ${uploadType.toLowerCase()} files. Maximum size: ${maxSizeMB}MB`,\n        };\n    }\n\n    return { isValid: true };\n}\n\n/**\n * Creates a default upload configuration with predefined settings for different file types.\n * This function provides sensible defaults for image, video, document, and other file types,\n * including allowed extensions and size limits. The configuration can be customized with overrides.\n *\n * @param overrides - Optional configuration overrides to merge with the default configuration.\n * @returns A complete upload configuration object with defaults and any provided overrides.\n */\nexport function createUploadConfig(overrides?: Partial<I_UploadConfig>): I_UploadConfig {\n    return { ...DEFAULT_UPLOAD_CONFIG, ...overrides };\n}\n\n/**\n * Uploads a file with comprehensive validation and error handling.\n * This function processes file uploads with the following features:\n * - Input validation for path and file parameters\n * - Configuration validation for all upload types\n * - File validation using getAndValidateFile function\n * - Automatic directory creation\n * - Stream-based file writing\n * - Comprehensive error handling with standardized response codes\n *\n * @param options - Upload configuration including file, path, type, and optional validation config.\n * @returns A promise that resolves to a standardized response with success status, message, file path, and response codes.\n */\nexport async function upload(options: I_UploadOptions): Promise<I_Return<string>> {\n    const { path, file, config, type, baseDir } = options;\n\n    if (!path || typeof path !== 'string') {\n        return {\n            success: false,\n            message: 'Invalid path provided',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    // Security: Validate path is within allowed base directory to prevent path traversal.\n    // When baseDir is provided, the resolved path must start with it.\n    // When baseDir is not provided, reject any path containing \"..\" segments.\n    const resolvedPath = nodePath.resolve(path);\n\n    if (baseDir) {\n        const resolvedBase = nodePath.resolve(baseDir) + nodePath.sep;\n        if (!resolvedPath.startsWith(resolvedBase) && resolvedPath !== nodePath.resolve(baseDir)) {\n            return {\n                success: false,\n                message: 'Path traversal detected: path resolves outside the allowed base directory',\n                code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n            };\n        }\n    }\n    else if (path.includes('..')) {\n        return {\n            success: false,\n            message: 'Path traversal detected: \"..\" segments are not allowed',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    if (!file || typeof file !== 'object') {\n        return {\n            success: false,\n            message: 'Invalid file provided',\n            code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n        };\n    }\n\n    if (config) {\n        const requiredTypes = [E_UploadType.IMAGE, E_UploadType.VIDEO, E_UploadType.DOCUMENT, E_UploadType.OTHER];\n\n        for (const requiredType of requiredTypes) {\n            if (!config[requiredType] || !Array.isArray(config[requiredType].allowedExtensions) || config[requiredType].allowedExtensions.length === 0) {\n                return {\n                    success: false,\n                    message: `Invalid config for ${requiredType.toLowerCase()} files`,\n                    code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n                };\n            }\n            if (typeof config[requiredType].sizeLimit !== 'number' || config[requiredType].sizeLimit <= 0) {\n                return {\n                    success: false,\n                    message: `Invalid size limit for ${requiredType.toLowerCase()} files`,\n                    code: RESPONSE_STATUS.BAD_REQUEST.CODE,\n                };\n            }\n        }\n    }\n\n    try {\n        const fileData = await getAndValidateFile(type, await file, config);\n\n        if (!fileData.success) {\n            return fileData;\n        }\n\n        const { createReadStream } = fileData.result;\n\n        const dir = dirname(path);\n\n        if (!pathExistsSync(dir)) {\n            mkdirSync(dir, { recursive: true });\n        }\n\n        const writeStream = createReadStream();\n        const out = createWriteStream(path);\n        writeStream.pipe(out);\n\n        await new Promise<void>((resolve, reject) => {\n            out.on('finish', () => resolve());\n            out.on('error', reject);\n            writeStream.on('error', reject);\n        });\n\n        return {\n            success: true,\n            result: path,\n            message: 'File uploaded successfully',\n            code: RESPONSE_STATUS.OK.CODE,\n        };\n    }\n    catch (error) {\n        return {\n            success: false,\n            message: error instanceof Error ? error.message : 'File upload failed',\n            code: RESPONSE_STATUS.INTERNAL_SERVER_ERROR.CODE,\n        };\n    }\n}\n"],"mappings":"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"}

package/dist/node_modules/.pnpm/vitest@4.1.0_@types_node@25.5.0_jsdom@29.0.1_@noble_hashes@1.8.0__vite@8.0.1_@types_nod_5f6c16f4d4385f16c87b17afc93c851f/node_modules/vitest/dist/config.js

@@ -0,0 +1,8 @@
+//#region node_modules/.pnpm/vitest@4.1.0_@types+node@25.5.0_jsdom@29.0.1_@noble+hashes@1.8.0__vite@8.0.1_@types+nod_5f6c16f4d4385f16c87b17afc93c851f/node_modules/vitest/dist/config.js
+function e(e) {
+	return e;
+}
+//#endregion
+export { e as defineConfig };
+
+//# sourceMappingURL=config.js.map

package/dist/node_modules/.pnpm/{vitest@4.1.0_@types_node@25.5.0_jsdom@29.0.0_@noble_hashes@1.8.0__vite@8.0.1_@types_nod_36acd00c2670b611b011192023dc5bd9 → vitest@4.1.0_@types_node@25.5.0_jsdom@29.0.1_@noble_hashes@1.8.0__vite@8.0.1_@types_nod_5f6c16f4d4385f16c87b17afc93c851f}/node_modules/vitest/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","names":[],"sources":["../../../../../../../node_modules/.pnpm/vitest@4.1.0_@types+node@25.5.0_jsdom@29.0.0_@noble+hashes@1.8.0__vite@8.0.1_@types+nod_36acd00c2670b611b011192023dc5bd9/node_modules/vitest/dist/config.js"],"sourcesContent":["export { c as configDefaults, a as coverageConfigDefaults, d as defaultExclude, b as defaultInclude } from './chunks/defaults.CdU2lD-q.js';\nexport { mergeConfig } from 'vite';\nexport { d as defaultBrowserPort } from './chunks/constants.CPYnjOGj.js';\nimport 'node:os';\nimport './chunks/env.D4Lgay0q.js';\nimport 'std-env';\n\nfunction defineConfig(config) {\n\treturn config;\n}\nfunction defineProject(config) {\n\treturn config;\n}\n\nexport { defineConfig, defineProject };\n"],"x_google_ignoreList":[0],"mappings":";AAOA,SAAS,EAAa,GAAQ;AAC7B,QAAO"}
+{"version":3,"file":"config.js","names":[],"sources":["../../../../../../../node_modules/.pnpm/vitest@4.1.0_@types+node@25.5.0_jsdom@29.0.1_@noble+hashes@1.8.0__vite@8.0.1_@types+nod_5f6c16f4d4385f16c87b17afc93c851f/node_modules/vitest/dist/config.js"],"sourcesContent":["export { c as configDefaults, a as coverageConfigDefaults, d as defaultExclude, b as defaultInclude } from './chunks/defaults.CdU2lD-q.js';\nexport { mergeConfig } from 'vite';\nexport { d as defaultBrowserPort } from './chunks/constants.CPYnjOGj.js';\nimport 'node:os';\nimport './chunks/env.D4Lgay0q.js';\nimport 'std-env';\n\nfunction defineConfig(config) {\n\treturn config;\n}\nfunction defineProject(config) {\n\treturn config;\n}\n\nexport { defineConfig, defineProject };\n"],"x_google_ignoreList":[0],"mappings":";AAOA,SAAS,EAAa,GAAQ;AAC7B,QAAO"}

package/dist/react/storage/storage.hook.d.ts

@@ -1,7 +1,7 @@
 import { I_Serializer } from '../../util/serializer/index.js';
 /**
  * React hook that provides persistent storage functionality with automatic serialization.
- * This hook manages state that persists across browser sessions using localForage,
+ * This hook manages state that persists across browser sessions using localStorage,
  * with automatic serialization/deserialization of complex data types. It provides
  * a React-friendly interface for storage operations with proper error handling.
  *