backfarm 1.0.4 → 1.0.6

package/dist/utility/libs/index.d.ts

@@ -0,0 +1,1772 @@
+import * as node_http from 'node:http';
+import * as mysql2_promise from 'mysql2/promise';
+import * as pg from 'pg';
+import * as qs from 'qs';
+import * as express_serve_static_core from 'express-serve-static-core';
+import * as express from 'express';
+import { URLOptions, DeleteFile, DeleteFiles, DownloadFileParams, DownloadedFile, DownloadFilesParams, QueryItems, GenerateIdOptions, DownloadablePath, CustomErrorTemplate, BulkWriteInterface, DeleteDocuments, InsertOneInterface, InsertManyInterface, UpdateDocument, UploadFileInput, UploadFilesInput, FilesUploadedResponseData } from './interface.js';
+import { S3Client } from '@aws-sdk/client-s3';
+import { PathOptions, DatabaseType, CustomBulkWriteResult, CustomDeleteResult, CustomInsertOneResult, CustomInsertManyResult, CustomUpdateResult, ResponseInterface, FileUploadedResponseData } from './types.js';
+import 'mongodb';
+import './env.js';
+
+/**
+ * Deletes a file from either remote object storage or the local filesystem.
+ *
+ * The function determines whether the provided file reference is a URL or
+ * a local filesystem path using `url_or_path()`.
+ *
+ * For remote URLs, the corresponding object key is extracted from the URL
+ * and the object is deleted from the configured bucket using the S3-compatible
+ * storage client.
+ *
+ * For local paths, the function first checks whether the file exists and
+ * removes it using the asynchronous filesystem API. If the local file does
+ * not exist, the operation is still considered successful.
+ *
+ * Errors encountered during either remote or local deletion are caught and
+ * returned as part of the result instead of being thrown.
+ *
+ * @param item_file - Full URL of the remote file or local filesystem path
+ * of the file to delete.
+ *
+ * @returns A promise resolving to a `DeleteFile` result containing the
+ * original file URL/path, the deletion status, and the error when the
+ * operation fails.
+ *
+ * @example
+ * // Delete a file stored in the remote bucket.
+ * const result = await deleteFile(
+ *     'https://storage.example.com/my-bucket/uploads/profile.jpg'
+ * );
+ *
+ * // Returns:
+ * // {
+ * //     status: true,
+ * //     url_or_path:
+ * //         'https://storage.example.com/my-bucket/uploads/profile.jpg'
+ * // }
+ *
+ * @example
+ * // Delete a locally stored file.
+ * const result = await deleteFile(
+ *     './uploads/profile.jpg'
+ * );
+ *
+ * // Returns:
+ * // {
+ * //     status: true,
+ * //     url_or_path: './uploads/profile.jpg'
+ * // }
+ *
+ * @example
+ * // A local file that does not exist is treated as successfully deleted.
+ * const result = await deleteFile(
+ *     './uploads/missing-file.jpg'
+ * );
+ *
+ * // Returns:
+ * // {
+ * //     status: true,
+ *     // url_or_path: './uploads/missing-file.jpg'
+ * // }
+ *
+ * @example
+ * // Handle the deletion result.
+ * const result = await deleteFile(filePath);
+ *
+ * if (result.status) {
+ *     console.log('File deleted successfully:', result.url_or_path);
+ * } else {
+ *     console.error('Failed to delete file:', result.error);
+ * }
+ */
+declare const deleteFile: (item_file: string) => Promise<DeleteFile>;
+/**
+ * Deletes multiple files from either remote object storage or the local
+ * filesystem.
+ *
+ * Each file is automatically classified as either a remote URL or a local
+ * filesystem path using `url_or_path()`. Remote files are deleted from the
+ * configured S3-compatible bucket, while local files are removed from the
+ * filesystem.
+ *
+ * The function is designed to be idempotent for local files: if a local
+ * file does not exist, that file is still reported as successfully deleted.
+ *
+ * Duplicate file references are removed before processing to prevent the
+ * same file from being deleted more than once.
+ *
+ * Files are processed in batches of up to 50 items at a time to limit
+ * concurrent filesystem and object-storage operations. Each batch is
+ * processed concurrently, while subsequent batches wait for the previous
+ * batch to complete.
+ *
+ * Individual deletion failures do not stop the remaining files from being
+ * processed. Every file receives its own result describing whether the
+ * deletion succeeded or failed.
+ *
+ * @param item_files - Array of remote file URLs or local filesystem paths
+ * to delete.
+ *
+ * @returns A promise resolving to a `DeleteFiles` object containing the
+ * deletion result for each unique file.
+ *
+ * @example
+ * // Delete multiple remote files.
+ * const result = await deleteFiles([
+ *     'https://storage.example.com/my-bucket/uploads/image1.jpg',
+ *     'https://storage.example.com/my-bucket/uploads/image2.jpg',
+ *     'https://storage.example.com/my-bucket/uploads/document.pdf',
+ * ]);
+ *
+ * // Returns:
+ * // {
+ * //     items: [
+ * //         {
+ * //             url_or_path: 'https://storage.example.com/my-bucket/uploads/image1.jpg',
+ * //             status: true
+ * //         },
+ * //         {
+ * //             url_or_path: 'https://storage.example.com/my-bucket/uploads/image2.jpg',
+ * //             status: true
+ * //         },
+ *         {
+ *             url_or_path: 'https://storage.example.com/my-bucket/uploads/document.pdf',
+ *             status: true
+ *         }
+ *     ]
+ * // }
+ *
+ * @example
+ * // Delete multiple local files.
+ * const result = await deleteFiles([
+ *     './uploads/image1.jpg',
+ *     './uploads/image2.jpg',
+ *     './uploads/document.pdf',
+ * ]);
+ *
+ * @example
+ * // Remote URLs and local paths can be mixed in the same request.
+ * const result = await deleteFiles([
+ *     'https://storage.example.com/my-bucket/uploads/avatar.jpg',
+ *     './uploads/temp-file.pdf',
+ * ]);
+ *
+ * @example
+ * // Duplicate file references are automatically removed.
+ * const result = await deleteFiles([
+ *     './uploads/image.jpg',
+ *     './uploads/image.jpg',
+ *     './uploads/document.pdf',
+ * ]);
+ *
+ * // The image is processed only once.
+ *
+ * @example
+ * // Individual failures are returned without stopping other deletions.
+ * const result = await deleteFiles([
+ *     './uploads/existing.jpg',
+ *     './uploads/missing.jpg',
+ *     'invalid-file-reference',
+ * ]);
+ *
+ * // Example result:
+ * // {
+ * //     items: [
+ * //         {
+ * //             url_or_path: './uploads/existing.jpg',
+ *             status: true
+ *         },
+ *         {
+ *             url_or_path: './uploads/missing.jpg',
+ *             status: true
+ *         },
+ *         {
+ *             url_or_path: 'invalid-file-reference',
+ *             status: false
+ *         }
+ *     ]
+ * // }
+ *
+ * @example
+ * // An empty array returns immediately without performing any operations.
+ * const result = await deleteFiles([]);
+ *
+ * // Returns:
+ * // {
+ * //     items: []
+ * // }
+ */
+declare const deleteFiles: (item_files: string[]) => Promise<DeleteFiles>;
+/**
+ * Downloads a file from the configured S3-compatible object storage and
+ * saves it to the application's local in-app bucket.
+ *
+ * The object key is extracted from the provided file URL using
+ * `getKeyFromUrl()`. The file is then retrieved from the configured bucket
+ * using `GetObjectCommand`.
+ *
+ * A unique file name is generated while preserving the original file
+ * extension. The resulting file is stored under the path specified by
+ * `outputPath`, with `ENV.IN_APP_BUCKET` automatically used as the root
+ * directory.
+ *
+ * The required directory structure is created automatically if it does not
+ * already exist. The downloaded object is streamed directly to the local
+ * filesystem rather than loading the entire file into memory.
+ *
+ * @param params - Parameters required to download the file.
+ * @param params.url - Full URL of the file stored in the S3-compatible
+ * object storage.
+ * @param params.outputPath - Optional array of directory segments where
+ * the downloaded file should be stored inside the in-app bucket.
+ *
+ * @returns A promise resolving to a `DownloadedFile` containing the original
+ * URL, the local file path when successful, and an error when the operation
+ * fails.
+ *
+ * @example
+ * // Download a file into the default in-app bucket directory.
+ * const result = await downloadFile({
+ *     url: 'https://storage.example.com/my-bucket/uploads/profile.jpg',
+ * });
+ *
+ * // Example result:
+ * // {
+ * //     status: true,
+ * //     url: 'https://storage.example.com/my-bucket/uploads/profile.jpg',
+ *     path: 'in_app_bucket/a8f91c2e4b7d91f2.jpg'
+ * // }
+ *
+ * @example
+ * // Download a file into a specific directory.
+ * const result = await downloadFile({
+ *     url: 'https://storage.example.com/my-bucket/documents/report.pdf',
+ *     outputPath: ['temporary_files', 'documents'],
+ * });
+ *
+ * // Example result:
+ * // {
+ * //     status: true,
+ * //     url: 'https://storage.example.com/my-bucket/documents/report.pdf',
+ *     path: 'in_app_bucket/temporary_files/documents/b71d92ac31f04e21.pdf'
+ * // }
+ *
+ * @example
+ * // Handle a failed download.
+ * const result = await downloadFile({
+ *     url: 'https://storage.example.com/my-bucket/missing.jpg',
+ *     outputPath: ['temporary_files'],
+ * });
+ *
+ * if (!result.status) {
+ *     console.error('Download failed:', result.error);
+ * }
+ *
+ * @example
+ * // The downloaded file keeps the original extension while receiving
+ * // a newly generated unique file name.
+ * const result = await downloadFile({
+ *     url: 'https://storage.example.com/my-bucket/images/avatar.png',
+ *     outputPath: ['images'],
+ * });
+ *
+ * // The resulting file will have a structure similar to:
+ * // in_app_bucket/images/<unique-id>.png
+ */
+declare const downloadFile: ({ url, outputPath }: DownloadFileParams) => Promise<DownloadedFile>;
+/**
+ * Downloads multiple files from the configured S3-compatible object storage
+ * and saves them to the local in-app bucket.
+ *
+ * Each file is downloaded independently and processed concurrently. The
+ * object key for each file is extracted from its URL using `getKeyFromUrl()`,
+ * and the file is streamed directly to the local filesystem.
+ *
+ * A unique file name is generated for every downloaded file while preserving
+ * its original file extension. The target directory is created automatically
+ * when it does not already exist.
+ *
+ * A global output path can be provided for all files, or each file can define
+ * its own output path. These two options cannot be used together.
+ *
+ * Unlike a batch operation that stops when one file fails, each download is
+ * handled independently. A failure for one file does not prevent the
+ * remaining files from being downloaded.
+ *
+ * @param params - Parameters containing the files to download and an
+ * optional common output path.
+ * @param params.files - Array of file download configurations. Each file
+ * contains its remote URL and may optionally specify its own output path.
+ * @param params.globalPath - Optional common output path used for every file.
+ * Cannot be used when any individual file specifies `outputPath`.
+ *
+ * @returns A promise resolving to an array of `DownloadedFile` results.
+ * Each result represents the success or failure of its corresponding
+ * download.
+ *
+ * @example
+ * // Download multiple files into the default in-app bucket directory.
+ * const results = await downloadFiles({
+ *     files: [
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/images/profile.jpg',
+ *         },
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/documents/report.pdf',
+ *         },
+ *     ],
+ * });
+ *
+ * @example
+ * // Download multiple files into the same directory.
+ * const results = await downloadFiles({
+ *     files: [
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/images/profile.jpg',
+ *         },
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/images/banner.png',
+ *         },
+ *     ],
+ *     globalPath: 'temporary_files',
+ * });
+ *
+ * // Resulting paths will be similar to:
+ * // in_app_bucket/temporary_files/<unique-id>.jpg
+ * // in_app_bucket/temporary_files/<unique-id>.png
+ *
+ * @example
+ * // Each file can have its own output directory.
+ * const results = await downloadFiles({
+ *     files: [
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/images/profile.jpg',
+ *             outputPath: ['users', 'images'],
+ *         },
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/documents/report.pdf',
+ *             outputPath: ['users', 'documents'],
+ *         },
+ *     ],
+ * });
+ *
+ * @example
+ * // Check the result of each download independently.
+ * const results = await downloadFiles({
+ *     files: [
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/image1.jpg',
+ *         },
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/image2.jpg',
+ *         },
+ *     ],
+ *     globalPath: 'downloads',
+ * });
+ *
+ * results.forEach((result) => {
+ *     if (result.status) {
+ *         console.log('Downloaded:', result.path);
+ *     } else {
+ *         console.error('Download failed:', result.url, result.error);
+ *     }
+ * });
+ *
+ * @example
+ * // Invalid: globalPath and individual outputPath cannot be used together.
+ * const results = await downloadFiles({
+ *     files: [
+ *         {
+ *             url: 'https://storage.example.com/my-bucket/image.jpg',
+ *             outputPath: ['images'],
+ *         },
+ *     ],
+ *     globalPath: 'downloads',
+ * });
+ *
+ * // Throws:
+ * // Error: Conflict: Cannot specify both 'globalPath' and
+ * // 'individual outputPath' on files.
+ */
+declare const downloadFiles: ({ files, globalPath, }: DownloadFilesParams) => Promise<DownloadedFile[]>;
+declare const upload_file: ({ file, path }: UploadFileInput) => Promise<FileUploadedResponseData>;
+/**
+ * Uploads multiple files to the configured S3-compatible storage bucket
+ * concurrently with a configurable concurrency limit.
+ *
+ * Each file is uploaded using the `upload_file` function. A global path can
+ * be applied to all files, or each file can specify its own individual path,
+ * but both options cannot be used at the same time.
+ *
+ * Failed uploads are collected separately from successful uploads, allowing
+ * the caller to inspect the result of every individual file without stopping
+ * the entire batch operation.
+ *
+ * @param params - Configuration options for the batch upload.
+ * @param params.files - The files to upload along with their optional paths.
+ * @param params.globalPath - An optional path applied to all files that do
+ * not specify an individual path.
+ * @param params.concurrency - The maximum number of files uploaded
+ * concurrently. Defaults to `5`.
+ * @returns A promise resolving to a `FilesUploadedResponseData` containing
+ * separate arrays of successfully uploaded and failed files.
+ * @throws {Error} If both `globalPath` and an individual file `path` are
+ * provided.
+ *
+ * @example
+ * const result = await upload_files({
+ *     files: [
+ *         { file: file1 },
+ *         { file: file2 },
+ *         { file: file3 },
+ *     ],
+ *     globalPath: ['temporary_files'],
+ *     concurrency: 5,
+ * });
+ *
+ * console.log('Successful uploads:', result.successFiles);
+ * console.log('Failed uploads:', result.failedFiles);
+ *
+ * @example
+ * const result = await upload_files({
+ *     files: [
+ *         {
+ *             file: file1,
+ *             path: ['documents', 'reports'],
+ *         },
+ *         {
+ *             file: file2,
+ *             path: ['documents', 'images'],
+ *         },
+ *     ],
+ *     concurrency: 10,
+ * });
+ *
+ * @example
+ * // This throws because globalPath and an individual path cannot be used together.
+ * const result = await upload_files({
+ *     files: [
+ *         {
+ *             file: file1,
+ *             path: ['documents'],
+ *         },
+ *     ],
+ *     globalPath: ['temporary_files'],
+ * });
+ */
+declare const upload_files: ({ files, globalPath, concurrency }: UploadFilesInput) => Promise<FilesUploadedResponseData>;
+/**
+ * Returns the configured S3-compatible storage client.
+ *
+ * This function provides access to the shared `S3Client` instance configured
+ * by the application's cloud storage engine. The client can be used for
+ * operations such as uploading, downloading, deleting, and managing objects
+ * in an S3-compatible storage service.
+ *
+ * The function returns the existing client instance rather than creating a
+ * new client, allowing the application to reuse the same connection
+ * configuration across storage operations.
+ *
+ * @returns A promise resolving to the configured `S3Client` instance.
+ *
+ * @example
+ * // Get the configured S3 client.
+ * const s3Client = await getS3Client();
+ *
+ * // Use the client for an S3 operation.
+ * const result = await s3Client.send(
+ *     new GetObjectCommand({
+ *         Bucket: ENV.BUCKET_NAME,
+ *         Key: 'temporary_files/example.jpg',
+ *     })
+ * );
+ *
+ * @example
+ * // The same configured client can be reused for multiple operations.
+ * const s3Client = await getS3Client();
+ *
+ * await s3Client.send(uploadCommand);
+ * await s3Client.send(downloadCommand);
+ * await s3Client.send(deleteCommand);
+ */
+declare const getS3Client: () => Promise<S3Client>;
+/**
+ * Normalizes and logs an error with optional contextual information.
+ *
+ * Formats the error for both terminal and browser environments, displaying
+ * its type, message, timestamp, context, stack trace, and raw error object.
+ * The normalized error is returned after being logged.
+ *
+ * @param err - The unknown error value to normalize and handle.
+ * @param context - Optional context describing where the error occurred.
+ * @returns The normalized error as a `CustomErrorTemplate`.
+ *
+ * @example
+ * const error = handleError(error, 'File Upload');
+ * // Logs the normalized error and returns a CustomErrorTemplate.
+ *
+ * @example
+ * try {
+ *     await upload_file(file);
+ * } catch (error) {
+ *     handleError(error, 'MinIO Upload');
+ * }
+ */
+declare function handleError(err: unknown, context?: string): CustomErrorTemplate;
+/**
+ * Asynchronously checks whether a file or path exists and is accessible.
+ *
+ * The function uses the filesystem access check to determine whether the
+ * specified path can be accessed. It resolves to `true` when the path is
+ * accessible and `false` when the access check fails.
+ *
+ * Any filesystem error is handled internally, so the function does not
+ * throw when the file or directory does not exist.
+ *
+ * @param filePath - The filesystem path to check.
+ *
+ * @returns A promise resolving to `true` if the path exists and is
+ * accessible, otherwise `false`.
+ *
+ * @example
+ * // Check whether a file exists.
+ * const exists = await fileExistsAsync('./uploads/profile.jpg');
+ *
+ * if (exists) {
+ *     console.log('File exists.');
+ * }
+ *
+ * @example
+ * // Use the result before reading a file.
+ * const filePath = './uploads/document.pdf';
+ *
+ * if (await fileExistsAsync(filePath)) {
+ *     const file = await fs.readFile(filePath);
+ *     console.log('File loaded successfully.');
+ * }
+ *
+ * @example
+ * // A missing file returns false instead of throwing an error.
+ * const exists = await fileExistsAsync('./uploads/missing.jpg');
+ *
+ * // Returns:
+ * // false
+ */
+declare function fileExistsAsync(filePath: string): Promise<boolean>;
+/**
+ * Synchronously checks whether a file or filesystem path exists and is
+ * accessible.
+ *
+ * The function uses Node.js's synchronous filesystem access check to
+ * determine whether the specified path can be accessed. It returns `true`
+ * when the path is accessible and `false` when the access check fails.
+ *
+ * Any filesystem error is handled internally, so the function does not
+ * throw when the file or directory does not exist.
+ *
+ * @param filePath - The filesystem path to check.
+ *
+ * @returns `true` if the path exists and is accessible; otherwise `false`.
+ *
+ * @example
+ * // Check whether a file exists.
+ * const exists = fileExistsSync('./uploads/profile.jpg');
+ *
+ * if (exists) {
+ *     console.log('File exists.');
+ * }
+ *
+ * @example
+ * // Check before performing a synchronous file operation.
+ * const filePath = './uploads/document.pdf';
+ *
+ * if (fileExistsSync(filePath)) {
+ *     const file = fsSync.readFileSync(filePath);
+ *     console.log('File loaded successfully.');
+ * }
+ *
+ * @example
+ * // A missing file returns false instead of throwing an error.
+ * const exists = fileExistsSync('./uploads/missing.jpg');
+ *
+ * // Returns:
+ * // false
+ */
+declare function fileExistsSync(filePath: string): boolean;
+/**
+ * Extracts the file extension from a supported file input.
+ *
+ * Supports Express Multer files, Web API `File` objects, raw `Buffer` values,
+ * and file paths or URLs. For URLs and paths, query parameters and hash
+ * fragments are ignored when determining the extension.
+ *
+ * @param input - The file, buffer, path, or URL from which to extract the extension.
+ * @returns The file extension without the leading dot, converted to lowercase.
+ * Returns an empty string if no extension can be determined.
+ *
+ * @example
+ * const extension = getFileExtension('https://example.com/files/image.PNG');
+ * // Returns: "png"
+ *
+ * @example
+ * const extension = getFileExtension(req.file);
+ * // Returns: "pdf"
+ *
+ * @example
+ * const extension = getFileExtension('documents/report.pdf?download=true');
+ * // Returns: "pdf"
+ *
+ * @example
+ * const extension = getFileExtension(buffer);
+ * // Returns: ""
+ */
+declare function getFileExtension(input: Express.Multer.File | File | Buffer | string): string;
+/**
+ * Determines whether the provided value is a URL or a local/server based file path.
+ *
+ * If the value is a valid HTTP/HTTPS URL, the configured URL environment
+ * value is returned. Otherwise, the configured local path environment value
+ * is returned.
+ *
+ * @param val - The URL or local file path to evaluate.
+ * @returns The configured URL or local path based on the input type.
+ *
+ * @example
+ * const basePath = url_or_path('https://example.com/file.png');
+ * // Returns ENV.URL
+ *
+ * @example
+ * const basePath = url_or_path('/uploads/file.png');
+ * // Returns ENV.PATH
+ */
+declare const url_or_path: (val: string) => "url" | "path";
+/**
+ * Safely normalizes Buffer, Express.Multer.File, Web File, or File Path into Uint8Array
+ */
+declare function toUint8Array(file: Express.Multer.File | File | Buffer | string): Promise<Uint8Array>;
+/**
+ * Builds a normalized file path from the provided path components.
+ *
+ * Combines the path prefix, path segments, path postfix, and file name,
+ * while removing empty values and normalizing redundant slashes.
+ *
+ * If `fileName` is a Web API `File` object, its `name` property is used.
+ *
+ * @param options - The path components used to construct the final path.
+ * @param options.path_prefix - An optional prefix to prepend to the path.
+ * @param options.path - An array of path segments.
+ * @param options.path_postfix - An optional postfix to append before the file name.
+ * @param options.fileName - The file name or a Web API `File` object.
+ * @returns A normalized path with components separated by a single slash.
+ *
+ * @example
+ * const filePath = buildPath({
+ *     path_prefix: 'uploads',
+ *     path: ['documents', 'reports'],
+ *     fileName: 'report.pdf',
+ * });
+ * // Returns: "uploads/documents/reports/report.pdf"
+ *
+ * @example
+ * const filePath = buildPath({
+ *     path: ['documents//', '/reports/'],
+ *     fileName: 'report.pdf',
+ * });
+ * // Returns: "documents/reports/report.pdf"
+ */
+declare function buildPath(options: PathOptions): string;
+/**
+ * Determines the MIME content type of a file from its available metadata
+ * or, when given a file path or URL, from its file extension.
+ *
+ * Supports Express Multer files, Web API `File` objects, raw `Buffer` values,
+ * and file paths or URLs.
+ *
+ * @param file - The file, buffer, path, or URL whose content type should be determined.
+ * @returns A promise resolving to the detected MIME content type.
+ *
+ * @example
+ * const contentType = await getFileContentType(req.file);
+ * // Returns something like: "image/jpeg"
+ *
+ * @example
+ * const contentType = await getFileContentType('/uploads/document.pdf');
+ * // Returns: "application/pdf"
+ *
+ * @example
+ * const contentType = await getFileContentType(buffer);
+ * // Returns: "application/octet-stream"
+ */
+declare const getFileContentType: (file: Express.Multer.File | File | Buffer | string) => Promise<string>;
+/**
+ * Builds the download path for a file stored in the application's
+ * in-app bucket.
+ *
+ * The configured `ENV.IN_APP_BUCKET` value is automatically used as the
+ * path prefix. If the bucket name is already present in the supplied
+ * segments, it is removed first to prevent the bucket name from being
+ * duplicated in the resulting path.
+ *
+ * The function supports an optional file name or file-like input. When a
+ * `File` or `Express.Multer.File` is provided, the underlying file name is
+ * resolved by `buildPath()`.
+ *
+ * @param options - Options used to construct the in-app bucket path.
+ * @param options.segments - Optional path segments representing directories
+ * within the in-app bucket.
+ * @param options.fileName - Optional file to append to the generated path.
+ * Supports `Express.Multer.File`, Web API `File`, `Buffer`, or a string
+ * path/file name.
+ *
+ * @returns A normalized path beginning with `ENV.IN_APP_BUCKET`.
+ *
+ * @example
+ * // Build a path for a file inside the in-app bucket.
+ * const path = getInAppBucketDownloadPath({
+ *     segments: ['temporary_files', 'images'],
+ *     fileName: 'profile.jpg',
+ * });
+ *
+ * // Returns:
+ * // <IN_APP_BUCKET>/temporary_files/images/profile.jpg
+ *
+ * @example
+ * // The bucket name is automatically removed if it is already
+ * // included in the provided segments.
+ * const path = getInAppBucketDownloadPath({
+ *     segments: [
+ *         ENV.IN_APP_BUCKET,
+ *         'temporary_files',
+ *         'images',
+ *     ],
+ *     fileName: 'profile.jpg',
+ * });
+ *
+ * // Returns:
+ * // <IN_APP_BUCKET>/temporary_files/images/profile.jpg
+ *
+ * @example
+ * // A Multer file can be supplied directly.
+ * const path = getInAppBucketDownloadPath({
+ *     segments: ['temporary_files'],
+ *     fileName: req.file,
+ * });
+ *
+ * @example
+ * // A path can be generated without a file name.
+ * const path = getInAppBucketDownloadPath({
+ *     segments: ['temporary_files', 'images'],
+ * });
+ *
+ * // Returns:
+ * // <IN_APP_BUCKET>/temporary_files/images
+ */
+declare function getInAppBucketDownloadPath({ segments, fileName }?: DownloadablePath): string;
+/**
+ * Detects the SQL database type from a database connection URL.
+ *
+ * The function supports MySQL and PostgreSQL connection URL schemes,
+ * including common driver-specific variants such as `mysql2`,
+ * `mysql+pymysql`, `postgresql+psycopg2`, and `postgresql+asyncpg`.
+ *
+ * If the connection string does not contain a recognized protocol, the
+ * function attempts to identify the database using keywords in the
+ * connection string or the default database ports:
+ *
+ * - MySQL: `3306`
+ * - PostgreSQL: `5432`
+ *
+ * Invalid URLs are also checked as raw connection strings before an error
+ * is thrown. This allows common connection strings without a protocol to
+ * still be detected.
+ *
+ * @param url - The SQL database connection URL or connection string.
+ * @returns `ENV.MY_SQL` for MySQL connections or `ENV.POSTGRES_SQL` for
+ * PostgreSQL connections.
+ * @throws {Error} If the URL is invalid or the database type cannot be
+ * identified as MySQL or PostgreSQL.
+ *
+ * @example
+ * // Detect PostgreSQL from a standard connection URL.
+ * const database = detectSQLDatabase(
+ *     'postgresql://user:password@localhost:5432/my_database'
+ * );
+ *
+ * // Returns: ENV.POSTGRES_SQL
+ *
+ * @example
+ * // Detect MySQL from a standard connection URL.
+ * const database = detectSQLDatabase(
+ *     'mysql://user:password@localhost:3306/my_database'
+ * );
+ *
+ * // Returns: ENV.MY_SQL
+ *
+ * @example
+ * // Driver-specific PostgreSQL URLs are also supported.
+ * const database = detectSQLDatabase(
+ *     'postgresql+psycopg2://user:password@localhost:5432/my_database'
+ * );
+ *
+ * // Returns: ENV.POSTGRES_SQL
+ *
+ * @example
+ * // A connection string without a recognized protocol can be detected
+ * // using the default PostgreSQL port.
+ * const database = detectSQLDatabase(
+ *     'localhost:5432/my_database'
+ * );
+ *
+ * // Returns: ENV.POSTGRES_SQL
+ *
+ * @example
+ * // Throws when the database type cannot be determined.
+ * const database = detectSQLDatabase(
+ *     'mongodb://localhost:27017/my_database'
+ * );
+ *
+ * // Error: Unsupported or unrecognized database type.
+ */
+declare function detectSQLDatabase(url: string): DatabaseType;
+/**
+ * Determines whether a database connection URL represents a MySQL database.
+ *
+ * This function delegates database detection to `detectSQLDatabase()` and
+ * compares the detected database type with the configured MySQL database
+ * identifier.
+ *
+ * Any error encountered while parsing or detecting the database type is
+ * handled internally, and the function returns `false` instead of throwing.
+ * This makes the function safe to use when validating or conditionally
+ * selecting a database implementation.
+ *
+ * @param url - The SQL database connection URL or connection string.
+ * @returns `true` if the URL represents a MySQL database; otherwise `false`.
+ *
+ * @example
+ * // Standard MySQL connection URL.
+ * const result = isMySQL(
+ *     'mysql://user:password@localhost:3306/my_database'
+ * );
+ *
+ * // Returns: true
+ *
+ * @example
+ * // PostgreSQL URL.
+ * const result = isMySQL(
+ *     'postgresql://user:password@localhost:5432/my_database'
+ * );
+ *
+ * // Returns: false
+ *
+ * @example
+ * // Invalid or unsupported connection URL.
+ * const result = isMySQL('invalid-database-url');
+ *
+ * // Returns: false instead of throwing an error.
+ */
+declare function isMySQL(url: string): boolean;
+/**
+ * Determines whether a database connection URL represents a PostgreSQL
+ * database.
+ *
+ * This function delegates database detection to `detectSQLDatabase()` and
+ * compares the detected database type with the configured PostgreSQL
+ * identifier.
+ *
+ * Any error encountered while parsing or detecting the database type is
+ * handled internally, causing the function to return `false` instead of
+ * throwing. This makes the function safe to use when conditionally selecting
+ * PostgreSQL-specific database logic.
+ *
+ * @param url - The SQL database connection URL or connection string.
+ * @returns `true` if the URL represents a PostgreSQL database; otherwise
+ * `false`.
+ *
+ * @example
+ * // Standard PostgreSQL connection URL.
+ * const result = isPostgreSQL(
+ *     'postgresql://user:password@localhost:5432/my_database'
+ * );
+ *
+ * // Returns: true
+ *
+ * @example
+ * // MySQL connection URL.
+ * const result = isPostgreSQL(
+ *     'mysql://user:password@localhost:3306/my_database'
+ * );
+ *
+ * // Returns: false
+ *
+ * @example
+ * // Invalid or unsupported connection URL.
+ * const result = isPostgreSQL('invalid-database-url');
+ *
+ * // Returns: false instead of throwing an error.
+ */
+declare function isPostgreSQL(url: string): boolean;
+/**
+ * Generates one or more cryptographically secure unique values.
+ *
+ * Values can be generated using hexadecimal characters or a custom
+ * alphanumeric character set. Optional timestamps and prefixes can be
+ * included in the generated values.
+ *
+ * When `count` is provided, multiple unique values are returned as an array.
+ * Otherwise, a single string is returned.
+ *
+ * @param length - The length of the randomly generated portion of each value.
+ * @param options - Optional configuration for generating the value(s).
+ * @param options.useHex - Whether to generate the random portion using hexadecimal characters.
+ * @param options.includeTimestamp - Whether to prepend a hexadecimal timestamp.
+ * @param options.prefix - An optional prefix to prepend to the generated value.
+ * @param options.count - The number of values to generate. If omitted, one value is returned.
+ * @returns A single unique string when `count` is not provided, or an array of unique strings when `count` is specified.
+ * @throws {Error} If `length` or `count` is less than or equal to zero.
+ *
+ * @example
+ * const id = generateUniqueValue(16);
+ * // Returns: "aZ7_kP2mQ9xL3nBc"
+ *
+ * @example
+ * const id = generateUniqueValue(16, {
+ *     useHex: true,
+ *     prefix: 'file',
+ * });
+ * // Returns: "file-7f3a9c12d84e..."
+ *
+ * @example
+ * const id = generateUniqueValue(12, {
+ *     includeTimestamp: true,
+ * });
+ * // Returns: "198a7f3c12a-7Kx9mP..."
+ *
+ * @example
+ * const ids = generateUniqueValue(10, {
+ *     count: 5,
+ *     prefix: 'file',
+ * });
+ * // Returns: ["file-...", "file-...", "file-...", "file-...", "file-..."]
+ */
+declare function generateUniqueValue(length: number, options?: GenerateIdOptions): string;
+declare function generateUniqueValue(length: number, options: GenerateIdOptions & {
+    count: number;
+}): string[];
+/**
+ * Builds a normalized URL or path from an optional endpoint, path segments,
+ * and file name.
+ *
+ * The function safely combines all provided segments while removing empty
+ * values and normalizing slashes between segments. If the endpoint contains
+ * an HTTP or HTTPS protocol, the protocol is preserved separately so that
+ * slash normalization does not alter it.
+ *
+ * A `File` object can also be provided as `fileName`; in that case, its
+ * original file name is extracted automatically.
+ *
+ * @param options - Options used to construct the URL.
+ * @param options.end_point - Optional base URL or endpoint. Supports
+ * `http://` and `https://` protocols.
+ * @param options.path - Optional array of path segments to append to the
+ * endpoint.
+ * @param options.fileName - Optional file name or Web API `File` object.
+ *
+ * @returns A normalized URL/path containing the provided endpoint, path
+ * segments, and file name. Returns an empty string when no valid segments
+ * are provided.
+ *
+ * @example
+ * // Build a URL from an endpoint, path, and file name.
+ * const url = buildURL({
+ *     end_point: 'https://storage.example.com',
+ *     path: ['uploads', 'images'],
+ *     fileName: 'profile.jpg',
+ * });
+ *
+ * // Returns:
+ * // https://storage.example.com/uploads/images/profile.jpg
+ *
+ * @example
+ * // Extra slashes are automatically normalized.
+ * const url = buildURL({
+ *     end_point: 'https://storage.example.com/',
+ *     path: ['/uploads/', '/images//'],
+ *     fileName: '/profile.jpg',
+ * });
+ *
+ * // Returns:
+ * // https://storage.example.com/uploads/images/profile.jpg
+ *
+ * @example
+ * // A File object can be used as the file name.
+ * const url = buildURL({
+ *     end_point: 'https://storage.example.com',
+ *     path: ['uploads'],
+ *     fileName: file,
+ * });
+ *
+ * // If file.name is "document.pdf":
+ * // https://storage.example.com/uploads/document.pdf
+ *
+ * @example
+ * // The function can also build a path without a URL endpoint.
+ * const path = buildURL({
+ *     path: ['uploads', 'documents'],
+ *     fileName: 'report.pdf',
+ * });
+ *
+ * // Returns:
+ * // uploads/documents/report.pdf
+ *
+ * @example
+ * // Empty or undefined segments are ignored.
+ * const url = buildURL({
+ *     end_point: 'https://storage.example.com/',
+ *     path: ['', 'uploads', '', 'documents'],
+ *     fileName: 'report.pdf',
+ * });
+ *
+ * // Returns:
+ * // https://storage.example.com/uploads/documents/report.pdf
+ *
+ * @example
+ * // Returns an empty string when no usable values are provided.
+ * const url = buildURL({});
+ *
+ * // Returns:
+ * // ''
+ */
+declare function buildURL({ end_point, path, fileName }: URLOptions): string;
+/**
+ * Extracts the object key/path from a full public file URL.
+ *
+ * This function is intended for files stored in the configured bucket.
+ * It parses the URL, extracts the pathname, removes the configured bucket
+ * name when it appears as the first path segment, and decodes any
+ * URL-encoded characters in the resulting object key.
+ *
+ * For example, a URL such as:
+ *
+ * `https://storage.example.com/my-bucket/uploads/images/profile%20photo.jpg`
+ *
+ * will produce:
+ *
+ * `uploads/images/profile photo.jpg`
+ *
+ * @param url - The full public URL of the stored file.
+ * @returns The decoded object key/path without the bucket name.
+ *
+ * @throws {TypeError} If the provided value is not a valid URL.
+ *
+ * @example
+ * // Extract the object key from a bucket URL.
+ * const key = getKeyFromUrl(
+ *     'https://storage.example.com/my-bucket/uploads/profile.jpg'
+ * );
+ *
+ * // Returns:
+ * // 'uploads/profile.jpg'
+ *
+ * @example
+ * // URL-encoded characters are decoded automatically.
+ * const key = getKeyFromUrl(
+ *     'https://storage.example.com/my-bucket/uploads/profile%20photo.jpg'
+ * );
+ *
+ * // Returns:
+ * // 'uploads/profile photo.jpg'
+ *
+ * @example
+ * // Nested directories are preserved.
+ * const key = getKeyFromUrl(
+ *     'https://storage.example.com/my-bucket/users/123/avatar/image.png'
+ * );
+ *
+ * // Returns:
+ * // 'users/123/avatar/image.png'
+ */
+declare const getKeyFromUrl: (url: string) => string;
+/**
+ * Sends a standardized API response to the client.
+ *
+ * This function provides a consistent response structure for both successful
+ * and failed requests. The `success` property acts as the discriminator
+ * between the two response types.
+ *
+ * For successful responses, the function returns the supplied status,
+ * message, data, and metadata. For failed responses, it returns the supplied
+ * status, message, error information, and metadata.
+ *
+ * A response timestamp is automatically generated when one is not already
+ * provided through `meta.timestamp`.
+ *
+ * @param response - Express `Response` object used to send the HTTP response.
+ * @param success - Indicates whether the request was successful.
+ * @param status - HTTP status code returned to the client.
+ * @param message - Optional human-readable response message.
+ * @param data - Optional data returned by a successful operation.
+ * @param error - Error information returned when the operation fails.
+ * @param meta - Optional response metadata such as request ID, timestamp,
+ * pagination information, or other request-related information.
+ *
+ * @returns The Express response containing the standardized API payload.
+ *
+ * @example
+ * // Successful response.
+ * return response_to_client({
+ *     response: res,
+ *     success: true,
+ *     status: 200,
+ *     message: 'User fetched successfully.',
+ *     data: user,
+ * });
+ *
+ * @example
+ * // Successful response with pagination metadata.
+ * return response_to_client({
+ *     response: res,
+ *     success: true,
+ *     status: 200,
+ *     message: 'Users fetched successfully.',
+ *     data: users,
+ *     meta: {
+ *         timestamp: new Date().toISOString(),
+ *         requestId: 'req_123456',
+ *         page: 1,
+ *         limit: 20,
+ *         totalItems: 100,
+ *         totalPages: 5,
+ *     },
+ * });
+ *
+ * @example
+ * // Error response.
+ * return response_to_client({
+ *     response: res,
+ *     success: false,
+ *     status: 404,
+ *     message: 'File not found.',
+ *     error: {
+ *         code: 'FILE_NOT_FOUND',
+ *         path: '/files/profile.jpg',
+ *     },
+ * });
+ *
+ * @example
+ * // Validation error with structured details.
+ * return response_to_client({
+ *     response: res,
+ *     success: false,
+ *     status: 400,
+ *     message: 'Validation failed.',
+ *     error: {
+ *         code: 'VALIDATION_ERROR',
+ *         details: [
+ *             {
+ *                 field: 'email',
+ *                 message: 'Invalid email address.',
+ *             },
+ *             {
+ *                 field: 'password',
+ *                 message: 'Password is required.',
+ *             },
+ *         ],
+ *     },
+ * });
+ *
+ * @example
+ * // Error response with a request ID for tracing.
+ * return response_to_client({
+ *     response: res,
+ *     success: false,
+ *     status: 500,
+ *     message: 'Internal server error.',
+ *     error: {
+ *         code: 'INTERNAL_SERVER_ERROR',
+ *     },
+ *     meta: {
+ *         timestamp: new Date().toISOString(),
+ *         requestId: 'req_abc123',
+ *     },
+ * });
+ */
+declare const responseToClient: ({ response, ...payload }: ResponseInterface) => express.Response<any, Record<string, any>>;
+/**
+ * Executes multiple write operations against a MongoDB collection in a single
+ * bulk operation.
+ *
+ * The function connects to the specified database and collection, executes
+ * the provided bulk write operations, and returns a standardized result
+ * indicating whether the operation succeeded or failed.
+ *
+ * @param params - Configuration and operations required for the bulk write.
+ * @param params.dbName - The name of the MongoDB database.
+ * @param params.collectionName - The name of the collection to modify.
+ * @param params.writable - An array of MongoDB bulk write operations to execute.
+ * @param params.options - Optional MongoDB bulk write configuration.
+ * @returns A promise resolving to a `CustomBulkWriteResult` containing either
+ * the `BulkWriteResult` on success or an `Error` on failure.
+ *
+ * @example
+ * const result = await bulkWrite({
+ *     dbName: 'my_database',
+ *     collectionName: 'users',
+ *     writable: [
+ *         {
+ *             insertOne: {
+ *                 document: {
+ *                     name: 'John',
+ *                     email: 'john@example.com',
+ *                 },
+ *             },
+ *         },
+ *         {
+ *             updateOne: {
+ *                 filter: { name: 'Jane' },
+ *                 update: { $set: { active: true } },
+ *             },
+ *         },
+ *     ],
+ * });
+ *
+ * if (result.status) {
+ *     console.log(result.result);
+ * } else {
+ *     console.error(result.error);
+ * }
+ */
+declare const mongoBulkWrite: (params: BulkWriteInterface) => Promise<CustomBulkWriteResult>;
+/**
+ * Deletes one or more documents from a MongoDB collection.
+ *
+ * By default, the function deletes a single document matching the provided
+ * query. When `deleteMany` is set to `true`, all documents matching the query
+ * are deleted.
+ *
+ * @param params - Configuration options for the delete operation.
+ * @param params.dbName - The name of the MongoDB database.
+ * @param params.collection - The name of the collection to delete from.
+ * @param params.query - The MongoDB filter used to identify the documents.
+ * @param params.deleteMany - Whether to delete all matching documents instead
+ * of only the first matching document. Defaults to `false`.
+ * @param params.options - Optional MongoDB delete operation options.
+ * @returns A promise resolving to a `CustomDeleteResult` containing the
+ * `DeleteResult` and number of deleted documents on success, or an `Error`
+ * on failure.
+ *
+ * @example
+ * const result = await deleteDocument({
+ *     dbName: 'my_database',
+ *     collection: 'users',
+ *     query: {
+ *         email: 'john@example.com',
+ *     },
+ * });
+ *
+ * if (result.status) {
+ *     console.log(`Deleted ${result.deletedCount} document(s)`);
+ * } else {
+ *     console.error(result.error);
+ * }
+ *
+ * @example
+ * const result = await deleteDocument({
+ *     dbName: 'my_database',
+ *     collection: 'users',
+ *     query: {
+ *         active: false,
+ *     },
+ *     deleteMany: true,
+ * });
+ *
+ * // Deletes all inactive users matching the query.
+ */
+declare const mongoDeleteDocument: (params: DeleteDocuments) => Promise<CustomDeleteResult>;
+/**
+ * Inserts a single document into a MongoDB collection.
+ *
+ * The document is inserted into the specified database and collection using
+ * the provided MongoDB insertion options. The generic type `T` allows the
+ * inserted document and resulting operation to remain type-safe.
+ *
+ * @param params - Configuration options for the insert operation.
+ * @param params.dbName - The name of the MongoDB database.
+ * @param params.collectionName - The name of the collection to insert into.
+ * @param params.field - The document to insert.
+ * @param params.options - Optional MongoDB insert operation options.
+ * @returns A promise resolving to a `CustomInsertOneResult<T>` containing the
+ * `InsertOneResult` on success or an `Error` on failure.
+ *
+ * @example
+ * const result = await insertOneField({
+ *     dbName: 'my_database',
+ *     collectionName: 'users',
+ *     field: {
+ *         name: 'John Doe',
+ *         email: 'john@example.com',
+ *     },
+ * });
+ *
+ * if (result.status) {
+ *     console.log('Inserted ID:', result.result.insertedId);
+ * } else {
+ *     console.error(result.error);
+ * }
+ */
+declare const mongoInsertField: <T>(params: InsertOneInterface<T>) => Promise<CustomInsertOneResult<T>>;
+/**
+ * Inserts multiple documents into a MongoDB collection.
+ *
+ * The documents are inserted into the specified database and collection
+ * using the provided MongoDB insertion options. The generic type `T`
+ * ensures that the inserted documents and resulting operation remain
+ * type-safe.
+ *
+ * @param params - Configuration options for the bulk insert operation.
+ * @param params.dbName - The name of the MongoDB database.
+ * @param params.collectionName - The name of the collection to insert into.
+ * @param params.fields - An array of documents to insert.
+ * @param params.options - Optional MongoDB bulk write options.
+ * @returns A promise resolving to a `CustomInsertManyResult<T>` containing
+ * the `InsertManyResult` and number of inserted documents on success, or
+ * an `Error` on failure.
+ *
+ * @example
+ * const result = await insertManyFields({
+ *     dbName: 'my_database',
+ *     collectionName: 'users',
+ *     fields: [
+ *         {
+ *             name: 'John Doe',
+ *             email: 'john@example.com',
+ *         },
+ *         {
+ *             name: 'Jane Doe',
+ *             email: 'jane@example.com',
+ *         },
+ *     ],
+ * });
+ *
+ * if (result.status) {
+ *     console.log(`Inserted ${result.insertedCount} documents`);
+ * } else {
+ *     console.error(result.error);
+ * }
+ */
+declare const mongoInsertFields: <T>(params: InsertManyInterface<T>) => Promise<CustomInsertManyResult<T>>;
+/**
+ * Updates one or more documents in a MongoDB collection.
+ *
+ * By default, the function updates a single document matching the provided
+ * query. When `updateMany` is set to `true`, all documents matching the query
+ * are updated.
+ *
+ * @param params - Configuration options for the update operation.
+ * @param params.dbName - The name of the MongoDB database.
+ * @param params.collectionName - The name of the collection to update.
+ * @param params.query - The MongoDB filter used to identify the documents.
+ * @param params.updatable - The update operations or update pipeline to apply
+ * to the matching documents.
+ * @param params.updateMany - Whether to update all matching documents instead
+ * of only the first matching document. Defaults to `false`.
+ * @param params.options - Optional MongoDB update operation options.
+ * @returns A promise resolving to a `CustomUpdateResult` containing the
+ * `UpdateResult` on success or an `Error` on failure.
+ *
+ * @example
+ * const result = await updateField({
+ *     dbName: 'my_database',
+ *     collectionName: 'users',
+ *     query: {
+ *         email: 'john@example.com',
+ *     },
+ *     updatable: {
+ *         $set: {
+ *             active: true,
+ *         },
+ *     },
+ * });
+ *
+ * if (result.status) {
+ *     console.log('User updated successfully');
+ * } else {
+ *     console.error(result.error);
+ * }
+ *
+ * @example
+ * const result = await updateField({
+ *     dbName: 'my_database',
+ *     collectionName: 'users',
+ *     query: {
+ *         active: false,
+ *     },
+ *     updatable: {
+ *         $set: {
+ *             status: 'inactive',
+ *         },
+ *     },
+ *     updateMany: true,
+ * });
+ *
+ * // Updates all users matching the query.
+ */
+declare const mongoUpdateField: (params: UpdateDocument) => Promise<CustomUpdateResult>;
+/**
+ * Creates Multer middleware for handling multiple file uploads from a
+ * single form field.
+ *
+ * The middleware accepts multiple files using the specified field name and
+ * limits the maximum number of uploaded files to the provided count.
+ *
+ * If no field name is supplied, `ENV.FILES` is used as the default field
+ * name. Likewise, `MAX_BATCH_FILES` is used as the default maximum number
+ * of files.
+ *
+ * @param fieldName - Name of the multipart/form-data field containing the
+ * uploaded files.
+ * @param maxCount - Maximum number of files that can be uploaded in a
+ * single request.
+ *
+ * @returns Multer middleware configured to process an array of uploaded
+ * files.
+ *
+ * @example
+ * // Use the default field name and maximum file count.
+ * router.post('/upload', upload_batch(), uploadBatchFilesApi);
+ *
+ * @example
+ * // Accept up to 10 files from the "files" field.
+ * router.post(
+ *     '/upload',
+ *     upload_batch('files', 10),
+ *     uploadBatchFilesApi
+ * );
+ *
+ * @example
+ * // Use a custom field name with the configured maximum file count.
+ * router.post(
+ *     '/images',
+ *     upload_batch('images'),
+ *     uploadBatchFilesApi
+ * );
+ */
+declare const upload_batch: (fieldName?: string, maxCount?: number) => express.RequestHandler<express_serve_static_core.ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>;
+/**
+ * Creates Multer middleware for handling a single file upload.
+ *
+ * The middleware expects one uploaded file from the specified
+ * `multipart/form-data` field and makes the uploaded file available through
+ * `req.file`.
+ *
+ * If no field name is provided, `ENV.FILE` is used as the default field name.
+ *
+ * @param fieldName - Name of the multipart/form-data field containing the
+ * uploaded file.
+ *
+ * @returns Multer middleware configured to process a single uploaded file.
+ *
+ * @example
+ * // Use the default field name.
+ * router.post(
+ *     '/upload',
+ *     upload_single(),
+ *     uploadSingleFileApi
+ * );
+ *
+ * @example
+ * // Accept a single file from the "file" field.
+ * router.post(
+ *     '/upload',
+ *     upload_single('file'),
+ *     uploadSingleFileApi
+ * );
+ *
+ * @example
+ * // Use a custom field name.
+ * router.post(
+ *     '/profile-picture',
+ *     upload_single('profilePicture'),
+ *     uploadSingleFileApi
+ * );
+ *
+ * // The uploaded file will be available as:
+ * // req.file
+ */
+declare const upload_single: (fieldName?: string) => express.RequestHandler<express_serve_static_core.ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>;
+/**
+ * Executes one or more SQL queries using the database configured through
+ * the `SQL_DB_URL` environment variable.
+ *
+ * The function automatically detects whether the configured database is
+ * PostgreSQL or MySQL and delegates execution to the appropriate database
+ * implementation.
+ *
+ * Supports structured CRUD operations (`insert_one`, `insert_many`, `select`,
+ * `update`, and `delete`) as well as custom raw SQL queries.
+ *
+ * Parameterized conditions and raw queries are supported. The placeholder
+ * syntax must match the configured database engine:
+ *
+ * - MySQL uses `?` placeholders.
+ * - PostgreSQL uses `$1`, `$2`, `$3`, etc.
+ *
+ * The corresponding values are supplied through `conditionalParams` for
+ * structured CRUD operations or `params` for raw SQL queries.
+ *
+ * @param query - The SQL operations to execute.
+ * @param query.crud - Optional array of structured CRUD operations.
+ * @param query.custom - Optional raw SQL query or array of raw SQL queries.
+ *
+ * @returns A promise resolving to the result returned by the PostgreSQL or
+ * MySQL query executor. If the configured `SQL_DB_URL` does not represent a
+ * supported database, an `Error` is returned.
+ *
+ * @example
+ * // Insert a user.
+ * //
+ * // This operation is database-independent because the values are passed
+ * // as an object and the underlying executor generates the appropriate SQL.
+ * await executeQuery({
+ *     crud: [
+ *         {
+ *             insert_one: {
+ *                 table: CONSTANTS.USER_INFOS,
+ *                 item: {
+ *                     [CONSTANTS.USER_PRIMARY_ID]: generateUniqueValue(32),
+ *                     [CONSTANTS.USER_NAME]: 'Divyanshu',
+ *                     [CONSTANTS.USER_EMAIL]: 'div@example.com',
+ *                     [CONSTANTS.USER_GENDER]: CONSTANTS.GENDER_TYPE.MALE,
+ *                 },
+ *             },
+ *         },
+ *     ],
+ * });
+ *
+ * @example
+ * // Select a user by email.
+ * //
+ * // MySQL:
+ * // condition: 'user_email = ?'
+ * //
+ * // PostgreSQL:
+ * // condition: 'user_email = $1'
+ * //
+ * // The value is supplied separately through conditionalParams.
+ * await executeQuery({
+ *     crud: [
+ *         {
+ *             select: {
+ *                 table: CONSTANTS.USER_INFOS,
+ *                 columns: [
+ *                     CONSTANTS.USER_PRIMARY_ID,
+ *                     CONSTANTS.USER_NAME,
+ *                     CONSTANTS.USER_EMAIL,
+ *                 ],
+ *                 condition: 'user_email = ?',
+ *                 conditionalParams: ['div@example.com'],
+ *             },
+ *         },
+ *     ],
+ * });
+ *
+ * @example
+ * // Update a user's information.
+ * //
+ * // MySQL:
+ * // condition: 'user_primary_id = ?'
+ * //
+ * // PostgreSQL:
+ * // condition: 'user_primary_id = $1'
+ * await executeQuery({
+ *     crud: [
+ *         {
+ *             update: {
+ *                 table: CONSTANTS.USER_INFOS,
+ *                 item: {
+ *                     [CONSTANTS.USER_NAME]: 'Div',
+ *                     [CONSTANTS.USER_PHONE_NUMBER]: '+1234567890',
+ *                 },
+ *                 condition: 'user_primary_id = ?',
+ *                 conditionalParams: [
+ *                     '550e8400-e29b-41d4-a716-446655440000',
+ *                 ],
+ *             },
+ *         },
+ *     ],
+ * });
+ *
+ * @example
+ * // Delete a user.
+ * //
+ * // Replace `?` with `$1` when using PostgreSQL.
+ * await executeQuery({
+ *     crud: [
+ *         {
+ *             delete: {
+ *                 table: CONSTANTS.USER_INFOS,
+ *                 condition: 'user_primary_id = ?',
+ *                 conditionalParams: [
+ *                     '550e8400-e29b-41d4-a716-446655440000',
+ *                 ],
+ *             },
+ *         },
+ *     ],
+ * });
+ *
+ * @example
+ * // Execute a raw SQL query.
+ * //
+ * // MySQL:
+ * // query: 'SELECT * FROM user_infos WHERE user_email = ?'
+ * //
+ * // PostgreSQL:
+ * // query: 'SELECT * FROM user_infos WHERE user_email = $1'
+ * await executeQuery({
+ *     custom: {
+ *         query: 'SELECT * FROM user_infos WHERE user_email = ?',
+ *         params: ['div@example.com'],
+ *     },
+ * });
+ *
+ * @example
+ * // Execute multiple operations in one call.
+ * //
+ * // The underlying executor handles the operations according to the
+ * // configured database engine.
+ * await executeQuery({
+ *     crud: [
+ *         {
+ *             insert_one: {
+ *                 table: CONSTANTS.USER_INFOS,
+ *                 item: {
+ *                     [CONSTANTS.USER_PRIMARY_ID]: generateUniqueValue(32),
+ *                     [CONSTANTS.USER_NAME]: 'Alice',
+ *                     [CONSTANTS.USER_EMAIL]: 'alice@example.com',
+ *                 },
+ *             },
+ *         },
+ *         {
+ *             update: {
+ *                 table: CONSTANTS.USER_INFOS,
+ *                 item: {
+ *                     status: 'active',
+ *                 },
+ *                 condition: 'user_email = ?',
+ *                 conditionalParams: ['alice@example.com'],
+ *             },
+ *         },
+ *     ],
+ * });
+ */
+declare const executeQuery: (query: QueryItems) => Promise<any[] | Error>;
+/**
+ * Returns the connection pool for the SQL database configured through
+ * the `SQL_DB_URL` environment variable.
+ *
+ * The database type is detected automatically from the connection URL.
+ * If the URL represents a PostgreSQL database, the PostgreSQL connection
+ * pool is returned. If it represents a MySQL database, the MySQL connection
+ * pool is returned.
+ *
+ * This function acts as the database-agnostic entry point for obtaining
+ * the application's SQL connection pool. Callers do not need to know
+ * whether the application is currently using PostgreSQL or MySQL.
+ *
+ * The underlying pool is created lazily and reused across subsequent
+ * calls through `getPgSqlPool()` or `getMySqlPool()`.
+ *
+ * @returns A promise resolving to the PostgreSQL or MySQL connection pool,
+ * depending on the configured `SQL_DB_URL`. Returns `undefined` if the
+ * configured database URL does not match a supported SQL database.
+ *
+ * @example
+ * // Get the configured SQL connection pool.
+ * const pool = await getPool();
+ *
+ * if (!pool) {
+ *     throw new Error('Unsupported SQL database configuration.');
+ * }
+ *
+ * @example
+ * // The same function works regardless of whether the application
+ * // is configured to use PostgreSQL or MySQL.
+ * const pool = await getPool();
+ *
+ * if (pool) {
+ *     // Use the returned pool with the appropriate database layer.
+ *     console.log('Database pool is ready.');
+ * }
+ */
+declare const getPool: () => Promise<pg.Pool | mysql2_promise.Pool | undefined>;
+/**
+ * Returns the application's configured Express instance.
+ *
+ * This function provides access to the shared Express application created
+ * by the application entry point. It returns the existing instance rather
+ * than creating a new Express application.
+ *
+ * The returned instance can be used to configure middleware, routes,
+ * error handlers, and other Express application settings.
+ *
+ * @returns The shared Express `Application` instance.
+ *
+ * @example
+ * // Get the Express application instance.
+ * const app = getApp();
+ *
+ * // Register a route.
+ * app.get('/health', (req, res) => {
+ *     res.json({ status: 'ok' });
+ * });
+ *
+ * @example
+ * // Use the shared application when configuring middleware.
+ * const app = getApp();
+ *
+ * app.use(express.json());
+ *
+ * @example
+ * // Export the configured application for use by a server entry point.
+ * const app = getApp();
+ *
+ * app.listen(PORT, () => {
+ *     console.log(`Server running on port ${PORT}`);
+ * });
+ */
+declare const getApp: () => express.Application;
+/**
+ * Returns the application's underlying HTTP server.
+ *
+ * This function provides access to the shared Node.js HTTP server created
+ * using the configured Express application. The same server instance is
+ * returned each time instead of creating a new server.
+ *
+ * The HTTP server can be used for operations that require access to the
+ * underlying Node.js server, such as attaching WebSocket servers or
+ * handling
+ * low-level HTTP server events.
+ *
+ * @returns The shared Node.js `http.Server` instance.
+ *
+ * @example
+ * // Attach a WebSocket server to the HTTP server.
+ * const server = getServer();
+ *
+ * const wsServer = new WebSocket.Server({
+ *     server,
+ * });
+ *
+ * @example
+ * // Listen for server-level errors.
+ * const server = getServer();
+ *
+ * server.on('error', (error) => {
+ *     console.error('HTTP server error:', error);
+ * });
+ */
+declare const getServer: () => node_http.Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>;
+
+export { buildPath, buildURL, deleteFile, deleteFiles, detectSQLDatabase, downloadFile, downloadFiles, executeQuery, fileExistsAsync, fileExistsSync, generateUniqueValue, getApp, getFileContentType, getFileExtension, getInAppBucketDownloadPath, getKeyFromUrl, getPool, getS3Client, getServer, handleError, isMySQL, isPostgreSQL, mongoBulkWrite, mongoDeleteDocument, mongoInsertField, mongoInsertFields, mongoUpdateField, responseToClient, toUint8Array, upload_batch, upload_file, upload_files, upload_single, url_or_path };