backfarm 1.0.0

package/dist/utility/utilis/general/file-operations.d.ts

@@ -0,0 +1,140 @@
+import { PathOptions } from '../../libs/interface.js';
+import 'mongodb';
+import '../../libs/types.js';
+import 'express';
+import '../../libs/env.js';
+
+/**
+ * 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;
+/**
+ * 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({ path_prefix, path, path_postfix, fileName, }: PathOptions): string;
+/**
+ * Builds the local file path for a downloaded file.
+ *
+ * Removes any occurrence of the configured in-app bucket from the provided
+ * path to prevent duplicating the bucket name, then constructs the final
+ * path using the configured in-app bucket as the path prefix.
+ *
+ * @param options - The path and file name options used to build the downloaded file path.
+ * @param options.path - The path segments leading to the file.
+ * @param options.fileName - The name of the file or a Web API `File` object.
+ * @returns The complete local path for the downloaded file.
+ *
+ * @example
+ * const filePath = downloadedFilePath({
+ *     path: ['documents', 'reports'],
+ *     fileName: 'report.pdf',
+ * });
+ * // Returns a path prefixed with ENV.IN_APP_BUCKET.
+ *
+ * @example
+ * const filePath = downloadedFilePath({
+ *     path: [ENV.IN_APP_BUCKET, 'documents'],
+ *     fileName: file,
+ * });
+ * // The duplicate bucket segment is removed before building the path.
+ */
+declare function downloadedFilePath({ path, fileName }: 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>;
+/**
+ * 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) => string;
+/**
+ * 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>;
+
+export { buildPath, downloadedFilePath, getFileContentType, getFileExtension, toUint8Array, url_or_path };

package/dist/utility/utilis/general/file-operations.js

@@ -0,0 +1,19 @@
+import {
+  buildPath,
+  downloadedFilePath,
+  getFileContentType,
+  getFileExtension,
+  toUint8Array,
+  url_or_path
+} from "../../../chunk-FMCW72HO.js";
+import "../../../chunk-EWQYVPOL.js";
+import "../../../chunk-7QVYU63E.js";
+export {
+  buildPath,
+  downloadedFilePath,
+  getFileContentType,
+  getFileExtension,
+  toUint8Array,
+  url_or_path
+};
+//# sourceMappingURL=file-operations.js.map

package/dist/utility/utilis/general/file-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/utility/utilis/general/sqlDb.js.d.ts

@@ -0,0 +1,151 @@
+import { DatabaseType } from '../../libs/types.js';
+import 'mongodb';
+import 'express';
+import '../../libs/env.js';
+
+/**
+ * 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;
+
+export { detectSQLDatabase, isMySQL, isPostgreSQL };

package/dist/utility/utilis/general/sqlDb.js.js

@@ -0,0 +1,13 @@
+import {
+  detectSQLDatabase,
+  isMySQL,
+  isPostgreSQL
+} from "../../../chunk-MNSQSU7T.js";
+import "../../../chunk-EWQYVPOL.js";
+import "../../../chunk-7QVYU63E.js";
+export {
+  detectSQLDatabase,
+  isMySQL,
+  isPostgreSQL
+};
+//# sourceMappingURL=sqlDb.js.js.map

package/dist/utility/utilis/general/sqlDb.js.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/utility/utilis/general/uuids.d.ts

@@ -0,0 +1,55 @@
+import { GenerateIdOptions } from '../../libs/interface.js';
+import 'mongodb';
+import '../../libs/types.js';
+import 'express';
+import '../../libs/env.js';
+
+/**
+ * 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[];
+
+export { generateUniqueValue };

package/dist/utility/utilis/general/uuids.js

@@ -0,0 +1,8 @@
+import {
+  generateUniqueValue
+} from "../../../chunk-X3R3RLXY.js";
+import "../../../chunk-7QVYU63E.js";
+export {
+  generateUniqueValue
+};
+//# sourceMappingURL=uuids.js.map

package/dist/utility/utilis/general/uuids.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/utility/utilis/general/web.d.ts

@@ -0,0 +1,247 @@
+import * as express from 'express';
+import { URLOptions } from '../../libs/interface.js';
+import { ResponseInterface } from '../../libs/types.js';
+import 'mongodb';
+import '../../libs/env.js';
+
+/**
+ * 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 response_to_client: ({ response, ...payload }: ResponseInterface) => express.Response<any, Record<string, any>>;
+
+export { buildURL, getKeyFromUrl, response_to_client };

package/dist/utility/utilis/general/web.js

@@ -0,0 +1,13 @@
+import {
+  buildURL,
+  getKeyFromUrl,
+  response_to_client
+} from "../../../chunk-SSFPGDA3.js";
+import "../../../chunk-EWQYVPOL.js";
+import "../../../chunk-7QVYU63E.js";
+export {
+  buildURL,
+  getKeyFromUrl,
+  response_to_client
+};
+//# sourceMappingURL=web.js.map

package/dist/utility/utilis/general/web.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}