@hichchi/utils 0.0.1-alpha.1 → 0.0.1-beta.1

package/types/is-primitive.type.d.ts

@@ -0,0 +1,27 @@
+export type Primitive = string | number | boolean | symbol | bigint | null | undefined;
+export type NonNullPrimitive = string | number | boolean | symbol | bigint;
+/**
+ * Type predicate that determines if a type is a primitive JavaScript value.
+ *
+ * The `IsPrimitive` type evaluates to `true` if the provided type T is a primitive
+ * JavaScript value (string, number, boolean, symbol, bigint, null, or undefined),
+ * and `false` otherwise (objects, arrays, functions, etc.).
+ *
+ * This utility type is useful for creating conditional types that need to
+ * behave differently for primitive vs. non-primitive values.
+ *
+ * @template T The type to check
+ *
+ * @example
+ * ```typescript
+ * // Example with conditional types
+ * type SerializeValue<T> = IsPrimitive<T> extends true
+ *   ? T  // For primitives, keep as-is
+ *   : string;  // For non-primitives, convert to string
+ *
+ * // Usage
+ * type SerializedNumber = SerializeValue<number>;  // number
+ * type SerializedObject = SerializeValue<{foo: string}>;  // string
+ * ```
+ */
+export type IsPrimitive<T> = T extends Primitive ? true : false;

package/types/is-primitive.type.js

@@ -0,0 +1,4 @@
+"use strict";
+// noinspection JSUnusedGlobalSymbols
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=is-primitive.type.js.map

package/types/is-primitive.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-primitive.type.js","sourceRoot":"","sources":["../../../../libs/utils/src/types/is-primitive.type.ts"],"names":[],"mappings":";AAAA,qCAAqC"}

package/types/literal-object.type.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Generic interface for objects with string keys and values of a specified type.
+ *
+ * `LiteralObject` represents a simple key-value dictionary where all keys are strings
+ * and all values are of the same type T. It provides a type-safe way to work with
+ * dynamic objects that have arbitrary string keys.
+ *
+ * Key features:
+ * - Allows any string as a key using an index signature
+ * - Generic type parameter for values with `any` as the default
+ * - Useful for representing dynamic objects with unknown structure
+ * - Commonly used in object transformation and manipulation utilities
+ *
+ * Common use cases:
+ * - Working with JSON data
+ * - Creating dictionaries or maps with string keys
+ * - Representing configuration objects
+ * - Handling data with dynamic property names
+ *
+ * @template T The type of values in the object (defaults to `any`)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default any type
+ * const config: LiteralObject = {
+ *   apiUrl: 'https://api.example.com',
+ *   timeout: 5000,
+ *   retryCount: 3
+ * };
+ *
+ * // With a specific value type
+ * const stringMap: LiteralObject<string> = {
+ *   en: 'Hello',
+ *   fr: 'Bonjour',
+ *   es: 'Hola'
+ * };
+ *
+ * // Accessing properties dynamically
+ * function getValue(obj: LiteralObject, key: string): any {
+ *   return obj[key];
+ * }
+ * ```
+ *
+ * @see {@link objectToPathValueSet} Utility that uses LiteralObject for object flattening
+ * @see {@link PathValueSet} Related interface for flattened object representation
+ */
+export interface LiteralObject<T = any> {
+    [key: string]: T;
+}

package/types/literal-object.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=literal-object.type.js.map

package/types/literal-object.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"literal-object.type.js","sourceRoot":"","sources":["../../../../libs/utils/src/types/literal-object.type.ts"],"names":[],"mappings":""}

package/{src/lib/types.d.ts → types/loose-autocomplete.type.d.ts}

@@ -1,9 +1,3 @@
-export type LiteralObject<T = any> = {
-    [key: string]: T;
-};
-export type PartialWithNull<T> = {
-    [p in keyof T]?: T[p] | null;
-};
 /**
  * Represents a type for autocompleting string values.
  *
@@ -15,6 +9,24 @@ export type PartialWithNull<T> = {
  *
  * @template T Extends string - The set of predefined literal string options for autocompletion.
  *
+ * @example
+ * ```typescript
+ * // Define a set of color options
+ * type ColorOption = 'red' | 'green' | 'blue';
+ *
+ * // Function that accepts predefined colors but also allows custom colors
+ * function setColor(color: LooseAutocomplete<ColorOption>): void {
+ *   console.log(`Setting color to: ${color}`);
+ * }
+ *
+ * // Usage with predefined options (gets autocomplete)
+ * setColor('red');     // Works, with autocomplete
+ * setColor('green');   // Works, with autocomplete
+ *
+ * // Usage with custom string (allowed, but no autocomplete)
+ * setColor('purple');  // Also works, even though not in predefined options
+ * ```
+ *
  * @author Matt Pocock (https://www.totaltypescript.com/tips/create-autocomplete-helper-which-allows-for-arbitrary-values)
  */
 export type LooseAutocomplete<T extends string> = T | Omit<string, T>;

package/types/loose-autocomplete.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=loose-autocomplete.type.js.map

package/types/loose-autocomplete.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loose-autocomplete.type.js","sourceRoot":"","sources":["../../../../libs/utils/src/types/loose-autocomplete.type.ts"],"names":[],"mappings":""}

package/types/partial-with-null.type.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Makes all properties of type T optional and allows them to be null.
+ *
+ * This type is similar to TypeScript's built-in `Partial<T>` type, but it also
+ * allows properties to be null in addition to being undefined or their original type.
+ *
+ * @template T The type to make partial with null.
+ *
+ * @example
+ * ```TypeScript
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // All properties are optional and can be null
+ * const partialUser: PartialWithNull<User> = {
+ *   id: 1,
+ *   name: null,
+ *   // email is omitted (undefined)
+ * };
+ * ```
+ */
+export type PartialWithNull<T> = {
+    [p in keyof T]?: T[p] | null;
+};

package/types/partial-with-null.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=partial-with-null.type.js.map

package/types/partial-with-null.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-with-null.type.js","sourceRoot":"","sources":["../../../../libs/utils/src/types/partial-with-null.type.ts"],"names":[],"mappings":""}

package/types/prettify.type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility type for creating a clean object type from a complex type.
+ *
+ * The `Prettify` type takes a potentially complex type (with intersections, unions,
+ * mapped types, etc.) and converts it into a simple object type with all properties
+ * explicitly defined. This makes the resulting type easier to read in IDE tooltips
+ * and type errors.
+ *
+ * @template T The complex type to simplify
+ *
+ * @author Matt Pocock (https://www.totaltypescript.com/tips/create-autocomplete-helper-which-allows-for-arbitrary-values)
+ *
+ * @example
+ * ```typescript
+ * // Instead of seeing: { a: number } & { b: string }
+ * // You'll see: { a: number, b: string }
+ * type ComplexType = { a: number } & { b: string };
+ * type SimpleType = Prettify<ComplexType>;
+ * ```
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/types/prettify.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=prettify.type.js.map

package/types/prettify.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prettify.type.js","sourceRoot":"","sources":["../../../../libs/utils/src/types/prettify.type.ts"],"names":[],"mappings":""}

package/types/type.type.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generic constructor type for creating class instances.
+ *
+ * The `Type` type represents a constructor function that can create instances of a class.
+ * It's particularly useful when working with dependency injection systems, factories,
+ * or any code that needs to work with class constructors in a generic way.
+ *
+ * @template T The type of object that will be instantiated (defaults to unknown)
+ *
+ * @example
+ * ```typescript
+ * function createInstance<T>(ctor: Type<T>): T {
+ *   return new ctor();
+ * }
+ *
+ * // Usage
+ * class MyService {}
+ * const instance = createInstance(MyService);
+ * ```
+ */
+export type Type<T = unknown> = new (...args: unknown[]) => T;

package/{src/lib/interfaces.js → types/type.type.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=interfaces.js.map
+//# sourceMappingURL=type.type.js.map

package/types/type.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.type.js","sourceRoot":"","sources":["../../../../libs/utils/src/types/type.type.ts"],"names":[],"mappings":""}

package/utils/assertions.utils.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Type-safe utility to check if a value is an array of a specific type.
+ *
+ * This function acts as a type guard that not only checks if the provided value
+ * is an array (using the native Array.isArray method), but also narrows the TypeScript
+ * type to an array of the generic type T. This enables safer handling of potentially
+ * array-typed values with full type inference in the conditional branches.
+ *
+ * @template T The expected element type of the array
+ * @param {T | T[] | undefined} value The value to check, which could be a single item,
+ *                                     an array of items, or undefined
+ * @returns {value is T[]} Type predicate that narrows the type to T[] when true
+ *
+ * @remarks
+ * While this function essentially wraps Array.isArray, its value comes from the
+ * TypeScript type narrowing it provides, making it especially useful in code that
+ * needs to handle both single items and collections of items with type safety.
+ *
+ * The function properly handles undefined values by returning false, making it safe
+ * to use with optional parameters or potentially undefined values.
+ *
+ * @example
+ * ```typescript
+ * // Function that can accept either a single user or multiple users
+ * async function createUser(userOrUsers: UserDto | UserDto[] | undefined): Promise<User | User[]> {
+ *     // TypeScript knows userOrUsers is UserDto[] in this branch
+ *     if (isArray<UserDto>(userOrUsers)) {
+ *         return Promise.all(userOrUsers.map(user => userService.createUser(user)));
+ *     }
+ *     // TypeScript knows userOrUsers is UserDto or undefined in this branch
+ *     else if (userOrUsers) {
+ *         return userService.createUser(userOrUsers);
+ *     }
+ *     else {
+ *         throw new BadRequestException('User data is required');
+ *     }
+ * }
+ * ```
+ */
+export declare function isArray<T>(value: T | T[] | undefined): value is T[];
+/**
+ * Type-safe utility to check if a value is a non-array object of a specific type.
+ *
+ * This function serves as a type guard that checks if the provided value is an object
+ * (but not an array) and narrows the TypeScript type to the generic type T. It properly
+ * excludes null, arrays, and primitive values, focusing only on object instances.
+ *
+ * @template T The expected object type to narrow to when the check passes
+ * @param {T | T[] | undefined} [value] The value to check, which could be a single object,
+ *                                       an array of objects, or undefined
+ * @returns {value is T} Type predicate that narrows the type to T when true
+ *
+ * @remarks
+ * This function performs three checks to ensure the value is a proper object:
+ * 1. It's not an array (using Array.isArray)
+ * 2. It's of type "object" according to JavaScript's typeof operator
+ * 3. It's not null (which would pass the typeof check but isn't a valid object)
+ *
+ * This is particularly useful when handling parameters that could be either an object
+ * or a simpler identifier (like an ID), allowing for type-safe conditional logic.
+ *
+ * @example
+ * ```typescript
+ * // Function that can accept either a user ID or a user object
+ * async function getUserInfo(userIdOrUser: number | User | undefined): Promise<UserInfo> {
+ *     // TypeScript knows userIdOrUser is User in this branch
+ *     if (isObject<User>(userIdOrUser)) {
+ *         // Can safely access object properties
+ *         return await userService.getUserInfo(userIdOrUser.id);
+ *     }
+ *     // TypeScript knows userIdOrUser is number or undefined in this branch
+ *     else {
+ *         return await userService.getUserInfo(userIdOrUser);
+ *     }
+ * }
+ *
+ * // Works with optional parameters too
+ * function formatUserName(user?: User | string): string {
+ *     if (isObject<User>(user)) {
+ *         return `${user.firstName} ${user.lastName}`;
+ *     }
+ *     return user || 'Guest';
+ * }
+ * ```
+ */
+export declare function isObject<T>(value?: T | T[] | undefined): value is T;
+/**
+ * Type-safe utility to check if a value is an object with a specific property.
+ *
+ * This function acts as a type guard that determines if an unknown value is an object
+ * that contains a specified property, and narrows the TypeScript type to the generic
+ * type T when true. This provides a robust way to implement duck typing in TypeScript,
+ * allowing for safe property access in the conditional branches.
+ *
+ * @template T The expected object type that should contain the property
+ * @param {unknown} value Any value to check, with no type constraints
+ * @param {keyof T} propertyName The name of the property that should exist on the object
+ * @returns {value is T} Type predicate that narrows the type to T when true
+ *
+ * @remarks
+ * This function uses Object.prototype.hasOwnProperty.call to safely check for property
+ * existence, even if the object has a custom implementation of hasOwnProperty or if the
+ * property is named 'hasOwnProperty'.
+ *
+ * Unlike the simpler isObject utility, this function can distinguish between different
+ * object types based on their properties, making it ideal for discriminating between
+ * different interface implementations or handling union types.
+ *
+ * @example
+ * ```typescript
+ * // Check if an object has the properties of a User interface
+ * interface User {
+ *   id: number;
+ *   name: string;
+ * }
+ *
+ * interface Order {
+ *   orderNumber: string;
+ *   items: string[];
+ * }
+ *
+ * // Function that can handle different object types
+ * function processEntity(entity: unknown): void {
+ *   // Check if entity has 'id' property, indicating it's a User
+ *   if (isObjectWith<User>(entity, 'id')) {
+ *     // TypeScript knows entity is User in this branch
+ *     console.log(`Processing user: ${entity.name}`);
+ *   }
+ *   // Check if entity has 'orderNumber' property, indicating it's an Order
+ *   else if (isObjectWith<Order>(entity, 'orderNumber')) {
+ *     // TypeScript knows entity is Order in this branch
+ *     console.log(`Processing order: ${entity.orderNumber} with ${entity.items.length} items`);
+ *   }
+ *   else {
+ *     console.log('Unknown entity type');
+ *   }
+ * }
+ *
+ * // Useful for API responses where types may vary
+ * async function handleResponse(response: unknown): Promise<void> {
+ *   if (isObjectWith<ErrorResponse>(response, 'errorCode')) {
+ *     throw new ApiException(response.errorCode, response.message);
+ *   }
+ *   else if (isObjectWith<SuccessResponse>(response, 'data')) {
+ *     await processData(response.data);
+ *   }
+ * }
+ * ```
+ */
+export declare function isObjectWith<T extends object>(value: unknown, propertyName: keyof T): value is T;

package/utils/assertions.utils.js

@@ -0,0 +1,163 @@
+"use strict";
+// noinspection JSUnusedGlobalSymbols
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isArray = isArray;
+exports.isObject = isObject;
+exports.isObjectWith = isObjectWith;
+/**
+ * Type-safe utility to check if a value is an array of a specific type.
+ *
+ * This function acts as a type guard that not only checks if the provided value
+ * is an array (using the native Array.isArray method), but also narrows the TypeScript
+ * type to an array of the generic type T. This enables safer handling of potentially
+ * array-typed values with full type inference in the conditional branches.
+ *
+ * @template T The expected element type of the array
+ * @param {T | T[] | undefined} value The value to check, which could be a single item,
+ *                                     an array of items, or undefined
+ * @returns {value is T[]} Type predicate that narrows the type to T[] when true
+ *
+ * @remarks
+ * While this function essentially wraps Array.isArray, its value comes from the
+ * TypeScript type narrowing it provides, making it especially useful in code that
+ * needs to handle both single items and collections of items with type safety.
+ *
+ * The function properly handles undefined values by returning false, making it safe
+ * to use with optional parameters or potentially undefined values.
+ *
+ * @example
+ * ```typescript
+ * // Function that can accept either a single user or multiple users
+ * async function createUser(userOrUsers: UserDto | UserDto[] | undefined): Promise<User | User[]> {
+ *     // TypeScript knows userOrUsers is UserDto[] in this branch
+ *     if (isArray<UserDto>(userOrUsers)) {
+ *         return Promise.all(userOrUsers.map(user => userService.createUser(user)));
+ *     }
+ *     // TypeScript knows userOrUsers is UserDto or undefined in this branch
+ *     else if (userOrUsers) {
+ *         return userService.createUser(userOrUsers);
+ *     }
+ *     else {
+ *         throw new BadRequestException('User data is required');
+ *     }
+ * }
+ * ```
+ */
+function isArray(value) {
+    return Array.isArray(value);
+}
+/**
+ * Type-safe utility to check if a value is a non-array object of a specific type.
+ *
+ * This function serves as a type guard that checks if the provided value is an object
+ * (but not an array) and narrows the TypeScript type to the generic type T. It properly
+ * excludes null, arrays, and primitive values, focusing only on object instances.
+ *
+ * @template T The expected object type to narrow to when the check passes
+ * @param {T | T[] | undefined} [value] The value to check, which could be a single object,
+ *                                       an array of objects, or undefined
+ * @returns {value is T} Type predicate that narrows the type to T when true
+ *
+ * @remarks
+ * This function performs three checks to ensure the value is a proper object:
+ * 1. It's not an array (using Array.isArray)
+ * 2. It's of type "object" according to JavaScript's typeof operator
+ * 3. It's not null (which would pass the typeof check but isn't a valid object)
+ *
+ * This is particularly useful when handling parameters that could be either an object
+ * or a simpler identifier (like an ID), allowing for type-safe conditional logic.
+ *
+ * @example
+ * ```typescript
+ * // Function that can accept either a user ID or a user object
+ * async function getUserInfo(userIdOrUser: number | User | undefined): Promise<UserInfo> {
+ *     // TypeScript knows userIdOrUser is User in this branch
+ *     if (isObject<User>(userIdOrUser)) {
+ *         // Can safely access object properties
+ *         return await userService.getUserInfo(userIdOrUser.id);
+ *     }
+ *     // TypeScript knows userIdOrUser is number or undefined in this branch
+ *     else {
+ *         return await userService.getUserInfo(userIdOrUser);
+ *     }
+ * }
+ *
+ * // Works with optional parameters too
+ * function formatUserName(user?: User | string): string {
+ *     if (isObject<User>(user)) {
+ *         return `${user.firstName} ${user.lastName}`;
+ *     }
+ *     return user || 'Guest';
+ * }
+ * ```
+ */
+function isObject(value) {
+    return !Array.isArray(value) && typeof value === "object" && value !== null;
+}
+/**
+ * Type-safe utility to check if a value is an object with a specific property.
+ *
+ * This function acts as a type guard that determines if an unknown value is an object
+ * that contains a specified property, and narrows the TypeScript type to the generic
+ * type T when true. This provides a robust way to implement duck typing in TypeScript,
+ * allowing for safe property access in the conditional branches.
+ *
+ * @template T The expected object type that should contain the property
+ * @param {unknown} value Any value to check, with no type constraints
+ * @param {keyof T} propertyName The name of the property that should exist on the object
+ * @returns {value is T} Type predicate that narrows the type to T when true
+ *
+ * @remarks
+ * This function uses Object.prototype.hasOwnProperty.call to safely check for property
+ * existence, even if the object has a custom implementation of hasOwnProperty or if the
+ * property is named 'hasOwnProperty'.
+ *
+ * Unlike the simpler isObject utility, this function can distinguish between different
+ * object types based on their properties, making it ideal for discriminating between
+ * different interface implementations or handling union types.
+ *
+ * @example
+ * ```typescript
+ * // Check if an object has the properties of a User interface
+ * interface User {
+ *   id: number;
+ *   name: string;
+ * }
+ *
+ * interface Order {
+ *   orderNumber: string;
+ *   items: string[];
+ * }
+ *
+ * // Function that can handle different object types
+ * function processEntity(entity: unknown): void {
+ *   // Check if entity has 'id' property, indicating it's a User
+ *   if (isObjectWith<User>(entity, 'id')) {
+ *     // TypeScript knows entity is User in this branch
+ *     console.log(`Processing user: ${entity.name}`);
+ *   }
+ *   // Check if entity has 'orderNumber' property, indicating it's an Order
+ *   else if (isObjectWith<Order>(entity, 'orderNumber')) {
+ *     // TypeScript knows entity is Order in this branch
+ *     console.log(`Processing order: ${entity.orderNumber} with ${entity.items.length} items`);
+ *   }
+ *   else {
+ *     console.log('Unknown entity type');
+ *   }
+ * }
+ *
+ * // Useful for API responses where types may vary
+ * async function handleResponse(response: unknown): Promise<void> {
+ *   if (isObjectWith<ErrorResponse>(response, 'errorCode')) {
+ *     throw new ApiException(response.errorCode, response.message);
+ *   }
+ *   else if (isObjectWith<SuccessResponse>(response, 'data')) {
+ *     await processData(response.data);
+ *   }
+ * }
+ * ```
+ */
+function isObjectWith(value, propertyName) {
+    return Object.prototype.hasOwnProperty.call(value, propertyName);
+}
+//# sourceMappingURL=assertions.utils.js.map

package/utils/assertions.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.utils.js","sourceRoot":"","sources":["../../../../libs/utils/src/utils/assertions.utils.ts"],"names":[],"mappings":";AAAA,qCAAqC;;AAyCrC,0BAEC;AA+CD,4BAEC;AAiED,oCAEC;AA7JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,OAAO,CAAI,KAA0B;IACjD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,SAAgB,QAAQ,CAAI,KAA2B;IACnD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,SAAgB,YAAY,CAAmB,KAAc,EAAE,YAAqB;IAChF,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;AACrE,CAAC"}

package/utils/file.utils.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Comprehensive mapping of file extensions to their corresponding MIME types.
+ *
+ * This map provides a bidirectional mapping between file extensions and MIME types,
+ * enabling applications to determine the appropriate content type for files or
+ * to identify the likely file extension for a given MIME type.
+ *
+ * The map includes entries for common file formats across various categories:
+ * - Documents (PDF, DOC, DOCX, XLS, XLSX, etc.)
+ * - Images (JPG, PNG, GIF, SVG, WebP, etc.)
+ * - Audio (MP3, WAV, OGG, etc.)
+ * - Video (MP4, WebM, AVI, etc.)
+ * - Archives (ZIP, RAR, 7Z, etc.)
+ * - Web resources (HTML, CSS, JS, etc.)
+ * - And many more specialized formats
+ *
+ * @remarks
+ * The map is indexed by file extension (without the dot prefix) and contains
+ * the corresponding MIME type as the value. Use utility functions like
+ * getMimeTypeFromExtension and getExtensionFromMimeType to perform lookups
+ * rather than accessing this map directly.
+ *
+ * Extensions are stored in lowercase to ensure case-insensitive matching.
+ *
+ * @example
+ * ```typescript
+ * // Get MIME type for a file extension
+ * const mimeType = getMimeTypeFromExtension('pdf'); // 'application/pdf'
+ *
+ * // Get file extension for a MIME type
+ * const extension = getExtensionFromMimeType('image/jpeg'); // 'jpg'
+ * ```
+ */
+export declare const mimeTypes: Map<string, string>;
+/**
+ * Get the file extension of the given mime type.
+ * @param {string} mimeType - Mime type.
+ * @param {Map<string, string>} [allowedMimeTypes] - Allowed mime types. If not provided, the default mime types map will be used.
+ * @returns {string | undefined} File extension or undefined if the mime type is not found.
+ *
+ * @example
+ * ```TypeScript
+ * // Using the default mime types map
+ * const extension = getFileExt('application/pdf');
+ * // Output: 'pdf'
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * // Using a custom mime types map
+ * const customMimeTypes = new Map([
+ *   ['jpg', 'image/jpeg'],
+ *   ['png', 'image/png']
+ * ]);
+ * const extension = getFileExt('image/jpeg', customMimeTypes);
+ * // Output: 'jpg'
+ * ```
+ */
+export declare const getFileExt: (mimeType: string, allowedMimeTypes?: Map<string, string>) => string | undefined;
+/**
+ * Get file size in human-readable format.
+ * @param {number} size - File size in bytes.
+ * @param {boolean} [round] - Whether to round the size to whole numbers. If true, decimals will be removed.
+ * @returns {string} File size in human-readable format (B, KB, MB, or GB).
+ *
+ * @example
+ * ```TypeScript
+ * // Get file size with decimals
+ * const readableSize = getFileSize(1536);
+ * // Output: '1.50 KB'
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * // Get rounded file size
+ * const roundedSize = getFileSize(1536, true);
+ * // Output: '2 KB'
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * // Get size for larger files
+ * const largeFileSize = getFileSize(1073741824);
+ * // Output: '1.00 GB'
+ * ```
+ */
+export declare const getFileSize: (size: number, round?: boolean) => string;