npm - @cyberskill/shared - Versions diffs - 3.9.0 → 3.11.0 - Mend

@cyberskill/shared 3.9.0 → 3.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

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

	@@ -1 +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 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 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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"}
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 * @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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

	@@ -1 +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~~"}
1	+ {"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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,114 +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 = { baseDir: "" };
-function d(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 f(e) {
-	return decodeURIComponent(e.slice(0, -a.length));
+function l(e) {
+	return decodeURIComponent(e.slice(0, -r.length));
 }
-function p(e, t) {
-	return c.join(t, d(e));
+function u(e, t) {
+	return i.join(t, c(e));
 }
-var m = {
-	_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 ? u.baseDir = n : u.baseDir = e().CYBERSKILL_STORAGE_DIRECTORY, await l.mkdir(u.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 } = u;
-		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 } = u, n = p(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 m.keys(), n = 1;
-		for (let r of t) {
-			let t = e(await m.getItem(r), r, n);
-			if (t !== void 0) return t;
-			n += 1;
-		}
-	},
-	async key(e) {
-		return (await m.keys())[e] ?? null;
-	},
 	async keys() {
-		let { baseDir: e } = u;
+		let { baseDir: e } = s;
 		try {
-			return (await l.readdir(e)).filter((e) => e.endsWith(a)).map(f);
+			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 m.keys()).length;
-	},
 	async removeItem(e) {
-		let { baseDir: t } = u, n = p(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 } = u, r = p(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;
 	}
-}, h = null, g = null;
-async function _() {
-	return h ? (await h, g) : (h = (async () => {
-		await s.defineDriver(m), u.baseDir = e().CYBERSKILL_STORAGE_DIRECTORY;
-		let t = await s.getDriver(r);
-		await t._initStorage({
-			baseDir: u.baseDir,
-			name: i,
-			storeName: o
-		}), g = t;
-	})().catch((e) => {
-		throw h = null, e;
-	}), await h, g);
+}, f = null;
+async function p() {
+	return f ? (await f, d) : (f = d.init().catch((e) => {
+		throw f = null, e;
+	}), await f, d);
 }
-var v = {
+var m = {
 	async get(e) {
 		try {
-			return await (await _()).getItem(e) ?? null;
+			return await (await p()).getItem(e) ?? null;
 		} catch (e) {
 			return t(e, { returnValue: null });
 		}
 	},
-	async set(e, t) {
-		await (await _()).setItem(e, t);
+	async set(e, n) {
+		try {
+			await (await p()).setItem(e, n);
+		} catch (e) {
+			throw t(e), e;
+		}
 	},
 	async remove(e) {
 		try {
-			await (await _()).removeItem(e);
+			await (await p()).removeItem(e);
 		} catch (e) {
 			t(e);
 		}
 	},
 	async keys() {
 		try {
-			let e = await (await _()).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: [] });
@@ -116,16 +114,16 @@ var v = {
 	},
 	async getLogLink(n) {
 		try {
-			return `${c.join(e().CYBERSKILL_STORAGE_DIRECTORY, d(n))} (key: ${n})`;
+			return `${i.join(e().CYBERSKILL_STORAGE_DIRECTORY, c(n))} (key: ${n})`;
 		} catch (e) {
 			return t(e, { returnValue: null });
 		}
 	}
 };
-function y() {
-	h = null, g = null, u.baseDir = "";
+function h() {
+	f = null, s.baseDir = "";
 }
 //#endregion
-export { y as resetStorageForTesting, v as storage };
+export { h as resetStorageForTesting, m as storage };
 //# sourceMappingURL=storage.util.js.map

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

	@@ -1 +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 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 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 const driver = await ensureLocalForageReady();\n\n await driver.setItem(key, value);\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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"}
1	+ {"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":"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"}

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

@@ -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 CHANGED Viewed

	@@ -1 +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"}
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 /** 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 CHANGED Viewed

@@ -4,10 +4,11 @@ import { BYTES_PER_MB as n, DEFAULT_UPLOAD_CONFIG as r } from "./upload.constant
 import { createWriteStream as i, mkdirSync as a, pathExistsSync as o } from "../fs/fs.util.js";
 import { dirname as s } from "../path/path.util.js";
 import { Buffer as c } from "node:buffer";
-import { Transform as l } from "node:stream";
-import { ReadableStream as u } from "node:stream/web";
+import l from "node:path";
+import { Transform as u } from "node:stream";
+import { ReadableStream as d } from "node:stream/web";
 //#region src/node/upload/upload.util.ts
-async function d(e) {
+async function f(e) {
 	return new Promise((t, n) => {
 		let r = 0;
 		e.on("data", (e) => {
@@ -15,8 +16,8 @@ async function d(e) {
 		}), e.on("end", () => t(r)), e.on("error", n);
 	});
 }
-async function f(t, n, r) {
-	let i = await (await n).file, a = await d(i.createReadStream()), o = r ?? g(), s = h({
+async function p(t, n, r) {
+	let i = await (await n).file, a = await f(i.createReadStream()), o = r ?? _(), s = g({
 		filename: i.filename,
 		fileSize: a
 	}, o, t);
@@ -30,30 +31,30 @@ async function f(t, n, r) {
 		code: e.BAD_REQUEST.CODE
 	};
 }
-async function p(e, t, r) {
-	let i = (r ?? g())[e], a = await f(e, t, r);
+async function m(e, t, r) {
+	let i = (r ?? _())[e], a = await p(e, t, r);
 	if (!a.success) return a;
-	let { createReadStream: o } = a.result, s = i.sizeLimit, d = new l({ transform(e, t, r) {
+	let { createReadStream: o } = a.result, s = i.sizeLimit, l = new u({ transform(e, t, r) {
 		s -= e.length, s < 0 ? r(/* @__PURE__ */ Error(`File size exceeds limit of ${i.sizeLimit / n}MB`)) : r(null, e);
-	} }), p = o().pipe(d);
+	} }), f = o().pipe(l);
 	return {
 		success: !0,
-		result: new u({ start(e) {
-			p.on("data", (t) => {
+		result: new d({ start(e) {
+			f.on("data", (t) => {
 				e.enqueue(typeof t == "string" ? c.from(t) : t);
-			}), p.on("end", () => e.close()), p.on("error", (t) => e.error(t));
+			}), f.on("end", () => e.close()), f.on("error", (t) => e.error(t));
 		} })
 	};
 }
-function m(e, t) {
+function h(e, t) {
 	let n = e.lastIndexOf(".");
 	if (n === -1) return !1;
 	let r = e.substring(n + 1).toLowerCase();
 	return t.includes(r);
 }
-function h(e, t, n) {
+function g(e, t, n) {
 	let { filename: r, fileSize: i } = e, { allowedExtensions: a, sizeLimit: o } = t[n];
-	if (!m(r, a)) return {
+	if (!h(r, a)) return {
 		isValid: !1,
 		error: `File extension not allowed for ${n.toLowerCase()} files. Allowed extensions: ${a.join(", ")}`
 	};
@@ -66,25 +67,38 @@ function h(e, t, n) {
 	}
 	return { isValid: !0 };
 }
-function g(e) {
+function _(e) {
 	return {
 		...r,
 		...e
 	};
 }
-async function _(n) {
-	let { path: r, file: c, config: l, type: u } = n;
+async function v(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
 	};
+	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
+	};
 	if (!c || typeof c != "object") return {
 		success: !1,
 		message: "Invalid file provided",
 		code: e.BAD_REQUEST.CODE
 	};
-	if (l) {
+	if (u) {
 		let n = [
 			t.IMAGE,
 			t.VIDEO,
@@ -92,12 +106,12 @@ async function _(n) {
 			t.OTHER
 		];
 		for (let t of n) {
-			if (!l[t] || !Array.isArray(l[t].allowedExtensions) || l[t].allowedExtensions.length === 0) return {
+			if (!u[t] || !Array.isArray(u[t].allowedExtensions) || u[t].allowedExtensions.length === 0) return {
 				success: !1,
 				message: `Invalid config for ${t.toLowerCase()} files`,
 				code: e.BAD_REQUEST.CODE
 			};
-			if (typeof l[t].sizeLimit != "number" || l[t].sizeLimit <= 0) return {
+			if (typeof u[t].sizeLimit != "number" || u[t].sizeLimit <= 0) return {
 				success: !1,
 				message: `Invalid size limit for ${t.toLowerCase()} files`,
 				code: e.BAD_REQUEST.CODE
@@ -105,13 +119,13 @@ async function _(n) {
 		}
 	}
 	try {
-		let t = await f(u, await c, l);
+		let t = await p(d, await c, u);
 		if (!t.success) return t;
-		let { createReadStream: n } = t.result, d = s(r);
-		o(d) || a(d, { recursive: !0 });
-		let p = n(), m = i(r);
-		return p.pipe(m), await new Promise((e, t) => {
-			m.on("finish", () => e()), m.on("error", t), p.on("error", t);
+		let { createReadStream: n } = t.result, l = s(r);
+		o(l) || a(l, { recursive: !0 });
+		let f = n(), m = i(r);
+		return f.pipe(m), await new Promise((e, t) => {
+			m.on("finish", () => e()), m.on("error", t), f.on("error", t);
 		}), {
 			success: !0,
 			result: r,
@@ -127,6 +141,6 @@ async function _(n) {
 	}
 }
 //#endregion
-export { g as createUploadConfig, f as getAndValidateFile, d as getFileSizeFromStream, p as getFileWebStream, _ as upload, m as validateFileExtension, h as validateUpload };
+export { _ as createUploadConfig, p as getAndValidateFile, f as getFileSizeFromStream, m as getFileWebStream, v as upload, h as validateFileExtension, g as validateUpload };
 //# sourceMappingURL=upload.util.js.map