@gzl10/ts-helpers 4.2.1

package/dist/types/index.d.ts

@@ -0,0 +1,211 @@
+export { b as generateAlphaNumericString, a as generateAlphaString, c as generateComplexString, l as generateEmail, n as generateHexColor, m as generatePassword, g as generateRandomInteger, i as generateSpanishCIF, k as generateSpanishIBAN, h as generateSpanishNIE, f as generateSpanishNIF, j as generateSpanishPostalCode, e as generateUsername, d as generateUsernameFromEmail, r as isValidCIF, u as isValidEmail, x as isValidJSON, q as isValidNIE, o as isValidNIF, y as isValidSpanishIBAN, t as isValidSpanishPhone, s as isValidSpanishPostalCode, w as isValidURL, p as validateNIF, v as validation } from './validation-core-DfHF8rCG.js';
+export { j as capitalizeEachWord, i as capitalizeFirst, c as cleanJsonChars, o as contains, C as countOccurrences, q as endsWith, e as ensureEndsWith, d as ensureStartsWith, K as envKeyToPath, H as escapeHtmlChars, E as isEmail, D as isEmpty, J as matchPathPattern, v as padEnd, r as padStart, L as pathToEnvKey, G as removeAccents, A as repeatString, B as replaceAllOccurrences, z as reverseString, a as sanitizeString, p as startsWith, s as strings, b as stripFromEnd, f as stripFromStart, k as toCamelCase, m as toKebabCase, g as toLowerCase, n as toPascalCase, l as toSnakeCase, h as toUpperCase, F as toUrlSlug, w as trim, y as trimEnd, x as trimStart, t as truncateString, I as unescapeHtmlChars, u as unescapeUnicode } from './strings-CiqRPYLL.js';
+export { a as calculateDifferences, c as comparator, d as deepEqual, i as deleteArrayElementsBy, f as formatToReadableString, b as generateCrcHash, j as getDeepValue, g as getShallowProperties, h as hasSameType, o as objects, s as setDeepValue, e as updateArrayElementById, u as updateArrayElementsBy } from './objects-BohS8GCS.js';
+export { p as addDays, v as addMonths, s as addNowDays, x as addNowMonths, u as addNowSeconds, z as addNowYears, q as addSeconds, y as addYears, r as areDatesEqualWithTolerance, d as dates, g as dayOfWeek, j as diffBusinessDays, h as diffDays, o as diffMilliSeconds, k as diffMonths, m as diffYears, A as excelToDate, a as format, E as formatForMysql, f as formatNow, e as fromNow, I as getFirstDayOfYear, H as getFirstWorkdayAfterMonths, F as getFirstWorkdayOfMonth, J as getLastDayOfYear, G as getLastWorkdayOfMonth, B as isDateTime, C as isEqualsDateTimeByDay, D as isExpired, i as isNew, K as isWeekday, l as longString, n as now, t as toDate, b as toDateFromString, c as toISO, w as weekOfYear } from './dates-hTiE0Z11.js';
+import { I as IMathOp } from './math-BQ9Lwdp7.js';
+export { c as calculateAggregations, q as calculateAnnuityPayment, k as calculateCorrelation, u as calculateEuclideanDistance, o as calculateFutureValue, t as calculateHistogram, i as calculateIQR, n as calculateIRR, v as calculateManhattanDistance, b as calculateMedian, d as calculateMode, l as calculateNPV, g as calculatePercentile, p as calculatePresentValue, h as calculateQuartiles, e as calculateStandardDeviation, a as calculateTrendSlope, f as calculateVariance, j as detectOutliers, m as math, r as normalizeToRange, s as scaleToRange, w as simpleKMeans } from './math-BQ9Lwdp7.js';
+export { a as async, h as handleOperation, r as runBatch, s as sleep, w as wait } from './async-C8gvbSG-.js';
+import { i as isBrowserEnvironment, a as isNodeEnvironment, E as EnvironmentInfo } from './environment-B8eLS7KT.js';
+export { b as EnvironmentCriteria, j as detectHostname, h as detectProtocol, e as environment, m as getEnvironmentInfo, o as isBrowser, c as isDevelopment, k as isLocalhost, n as isNode, g as isNonProduction, l as isPrivateIP, d as isProduction, f as isTest, p as parseEnvValue } from './environment-B8eLS7KT.js';
+export { i as isNumericValue, n as number, r as roundToDecimals } from './number-CYnQfLWj.js';
+export { getCryptoCapabilities, getEnvironmentType, isBrowserEnv, isNodeCryptoAvailable, isNodeEnv, isWebCryptoAvailable, isWorkerEnvironment } from './environment-detection.js';
+
+/**
+ * Universal exports - Safe for all environments
+ * No crypto dependencies - browser and Node.js compatible
+ */
+
+declare const g: {
+    isBrowserEnv: typeof isBrowserEnvironment;
+    isNodeEnv: typeof isNodeEnvironment;
+    isWorkerEnvironment: () => boolean;
+    isWebCryptoAvailable: () => boolean;
+    isNodeCryptoAvailable: () => boolean;
+    getEnvironmentType: () => "node" | "browser" | "worker" | "unknown";
+    getCryptoCapabilities: () => {
+        webCrypto: boolean;
+        nodeCrypto: boolean;
+        fallbackOnly: boolean;
+        environment: "node" | "browser" | "worker" | "unknown";
+    };
+    isNodeEnvironment(): boolean;
+    isBrowserEnvironment(): boolean;
+    isDevelopment(req?: any): boolean;
+    isProduction(): boolean;
+    isTest(): boolean;
+    isNonProduction(): boolean;
+    detectProtocol(req?: any): "http" | "https";
+    detectHostname(req?: any): string;
+    isLocalhost(hostname: string): boolean;
+    isPrivateIP(hostname: string): boolean;
+    getEnvironmentInfo(req?: any): EnvironmentInfo;
+    parseEnvValue(value: string | undefined): any;
+    isNode: typeof isNodeEnvironment;
+    isBrowser: typeof isBrowserEnvironment;
+    isNumericValue(value: any): boolean;
+    roundToDecimals(num: number, decimals?: number): number;
+    runBatch<T>(jobs: Promise<T>[], batchSize?: number): Promise<T[]>;
+    handleOperation<T>(target: Record<string, any>, operation: string, ...args: any[]): Promise<T>;
+    sleep: (ms: number) => Promise<void>;
+    wait: (ms: number) => Promise<void>;
+    calculateTrendSlope(y: number[], x: number[]): number;
+    calculateAggregations: (operations: IMathOp, pgroupBy: string[], inData: any[], appendOperationToField?: boolean) => any;
+    calculateMedian: (values: number[]) => number;
+    calculateMode: (values: number[]) => number | null;
+    calculateStandardDeviation: (values: number[], sample?: boolean) => number;
+    calculateVariance: (values: number[], sample?: boolean) => number;
+    calculatePercentile: (values: number[], percentile: number) => number;
+    calculateQuartiles: (values: number[]) => {
+        Q1: number;
+        Q2: number;
+        Q3: number;
+    };
+    calculateIQR: (values: number[]) => number;
+    detectOutliers: (values: number[], multiplier?: number) => number[];
+    calculateCorrelation: (x: number[], y: number[]) => number;
+    calculateNPV: (cashFlows: number[], discountRate: number) => number;
+    calculateIRR: (cashFlows: number[], initialGuess?: number, maxIterations?: number, tolerance?: number) => number;
+    calculateFutureValue: (presentValue: number, interestRate: number, periods: number) => number;
+    calculatePresentValue: (futureValue: number, interestRate: number, periods: number) => number;
+    calculateAnnuityPayment: (presentValue: number, interestRate: number, periods: number) => number;
+    normalizeToRange: (values: number[]) => number[];
+    scaleToRange: (values: number[], minRange: number, maxRange: number) => number[];
+    calculateHistogram: (values: number[], bins: number) => Array<{
+        range: [number, number];
+        count: number;
+    }>;
+    calculateEuclideanDistance: (point1: number[], point2: number[]) => number;
+    calculateManhattanDistance: (point1: number[], point2: number[]) => number;
+    simpleKMeans: (points: number[][], k: number, maxIterations?: number) => {
+        centroids: number[][];
+        clusters: number[];
+    };
+    formatNow: (formatStr?: string) => string;
+    format: (value: any, formatStr?: string) => string;
+    longString: (value?: any) => string;
+    toDate: (value: any, isUtc?: boolean) => Date;
+    toDateFromString: (dateString: string, format: "DD/MM/YYYY" | "YYYY-MM-DD" | "MM/DD/YYYY" | "YYYY/MM/DD" | "DD-MM-YYYY" | "MM-DD-YYYY" | "YYYYMMDD" | "DDMMYYYY" | "MMDDYYYY" | "YYYY.MM.DD" | "DD.MM.YYYY" | "MM.DD.YYYY") => Date | null;
+    now: () => Date;
+    isNew: (value: any, daysnew?: number) => boolean;
+    toISO: (value?: any, isUtc?: boolean) => string;
+    fromNow: (value: any) => string;
+    dayOfWeek: (value?: any) => string;
+    weekOfYear: (value?: any) => string;
+    diffDays: (start: any, end?: any, precise?: boolean) => number;
+    diffBusinessDays: (start: any, end?: any, precise?: boolean) => number;
+    diffMonths: (value: any, valueRefOrNow?: any, precise?: boolean) => number;
+    diffYears: (value: any, valueRefOrNow?: any, precise?: boolean) => number;
+    diffMilliSeconds: (value: any, valueRefOrNow?: any) => number;
+    addDays: (value: any, nDays?: number) => Date;
+    addSeconds: (value: any, nSeconds?: number) => Date;
+    areDatesEqualWithTolerance: (date1: Date, date2: Date) => boolean;
+    addNowDays: (nDays?: number) => Date;
+    addNowSeconds: (nSeconds?: number) => Date;
+    addMonths: (value: any, nMonths?: number) => Date;
+    addNowMonths: (nMonths?: number) => Date;
+    addYears: (value: any, nYears?: number) => Date;
+    addNowYears: (nYears?: number) => Date;
+    excelToDate: (value: any) => Date | null;
+    isDateTime: (value: any) => boolean;
+    isEqualsDateTimeByDay: (value1: any, value2: any) => boolean;
+    isExpired: (value: any, valueRefOrNow?: any) => boolean;
+    formatForMysql: (fecha: Date | null) => string | null;
+    getFirstWorkdayOfMonth: (month?: number) => Date;
+    getLastWorkdayOfMonth: (month?: number) => Date;
+    getFirstWorkdayAfterMonths: (initialDate: Date, n: number) => Date;
+    getFirstDayOfYear: () => Date;
+    getLastDayOfYear: () => Date;
+    isWeekday: (date: any) => boolean;
+    setDeepValue<T = any>(obj: T, path: string, value: any): T;
+    getDeepValue<T = any>(obj: any, path: string, defaultValue?: T): T | undefined;
+    comparator: (data1: any, data2: any) => boolean;
+    deepEqual: (data1: any, data2: any) => boolean;
+    formatToReadableString: (data: {
+        [key: string]: any;
+    }) => string;
+    getShallowProperties: (obj: any) => any;
+    calculateDifferences: (oldObj: any, newObj: any) => any;
+    generateCrcHash: (str: string | Buffer | Uint8Array | any) => string;
+    hasSameType: (sourceTarget: any, destinationTarget: any) => boolean;
+    updateArrayElementsBy: (data: any[], objUpd: any, objSearch: any) => any[];
+    updateArrayElementById: (data: any[], objUpd: any, idField: string) => void;
+    deleteArrayElementsBy: (data: any[], objSearch: any) => any[];
+    matchPathPattern(path: string, pattern: string): boolean;
+    envKeyToPath(envKey: string, prefix?: string): string;
+    pathToEnvKey(path: string, prefix?: string): string;
+    sanitizeString: (instr: string | null) => string;
+    cleanJsonChars: (texto: string | null) => string;
+    truncateString: (str: string, maxlength?: number, suffix?: string) => string;
+    unescapeUnicode: (input: string) => string;
+    ensureEndsWith: (str: string, trailing: string) => string;
+    stripFromEnd: (str: string, trailing: string) => string;
+    ensureStartsWith: (str: string, leading: string) => string;
+    stripFromStart: (str: string, leading: string) => string;
+    toLowerCase: (str: string) => string;
+    toUpperCase: (str: string) => string;
+    capitalizeFirst: (str: string) => string;
+    capitalizeEachWord: (str: string) => string;
+    toCamelCase: (str: string) => string;
+    toSnakeCase: (str: string) => string;
+    toKebabCase: (str: string) => string;
+    toPascalCase: (str: string) => string;
+    contains: (str: string, searchStr: string, caseSensitive?: boolean) => boolean;
+    startsWith: (str: string, searchStr: string, caseSensitive?: boolean) => boolean;
+    endsWith: (str: string, searchStr: string, caseSensitive?: boolean) => boolean;
+    padStart: (str: string, length: number, padChar?: string) => string;
+    padEnd: (str: string, length: number, padChar?: string) => string;
+    trim: (str: string) => string;
+    trimStart: (str: string) => string;
+    trimEnd: (str: string) => string;
+    reverseString: (str: string) => string;
+    repeatString: (str: string, times: number) => string;
+    replaceAllOccurrences: (str: string, searchStr: string, replaceStr: string) => string;
+    countOccurrences: (str: string, searchStr: string) => number;
+    isEmpty: (str: string | null | undefined) => boolean;
+    isEmail: (str: string) => boolean;
+    toUrlSlug: (str: string) => string;
+    removeAccents: (str: string) => string;
+    escapeHtmlChars: (str: string) => string;
+    unescapeHtmlChars: (str: string) => string;
+    generateRandomInteger: (min?: number, max?: number) => number;
+    generateAlphaString: (options?: {
+        length?: number;
+        casing?: "upper" | "lower" | undefined;
+    }) => string;
+    generateAlphaNumericString: (options?: {
+        length?: number;
+        casing?: "upper" | "lower" | undefined;
+    }) => string;
+    generateComplexString: (options?: {
+        length?: number;
+        casing?: "upper" | "lower" | undefined;
+    }) => string;
+    generateUsernameFromEmail: (email: string, randomDigits?: number) => string;
+    generateUsername: (separator?: string, randomDigits?: number, length?: number) => string;
+    generateSpanishNIF: () => string;
+    generateSpanishNIE: () => string;
+    generateSpanishCIF: () => string;
+    generateSpanishPostalCode: () => string;
+    generateSpanishIBAN: () => string;
+    generateEmail: (domain?: string) => string;
+    generatePassword: (options?: {
+        length?: number;
+        includeUppercase?: boolean;
+        includeLowercase?: boolean;
+        includeNumbers?: boolean;
+        includeSymbols?: boolean;
+    }) => string;
+    generateHexColor: (shortFormat?: boolean) => string;
+    isValidNIF: (nif: string) => boolean;
+    validateNIF: (nif: string) => boolean;
+    isValidNIE: (nie: string) => boolean;
+    isValidCIF: (cif: string) => boolean;
+    isValidSpanishPostalCode: (postalCode: string) => boolean;
+    isValidSpanishPhone: (phone: string) => boolean;
+    isValidEmail: (email: string) => boolean;
+    isValidURL: (url: string) => boolean;
+    isValidJSON: (str: string) => boolean;
+    isValidSpanishIBAN: (iban: string) => boolean;
+};
+
+export { EnvironmentInfo, IMathOp, g as default, isBrowserEnvironment, isNodeEnvironment };

package/dist/types/json.d.ts

@@ -0,0 +1,284 @@
+/**
+ * JSON Import/Export utilities
+ *
+ * Provides reliable JSON file operations for both Node.js and Browser environments.
+ * Features:
+ * - UTF-8 encoding for international character support
+ * - Pretty-printing with configurable indentation
+ * - Dual-mode: filesystem (Node.js) vs download trigger (Browser)
+ * - Native JSON.stringify/parse for maximum compatibility
+ *
+ * @module json
+ */
+/**
+ * Exports data as JSON file with UTF-8 encoding
+ *
+ * Works in both Node.js (writes to filesystem) and Browser (triggers download).
+ * Uses native JSON.stringify for serialization with optional pretty-printing.
+ *
+ * Features:
+ * - UTF-8 encoding for international characters
+ * - Configurable indentation (default: 2 spaces)
+ * - Automatic filename extraction in browser
+ * - Pretty-printed by default for readability
+ *
+ * Environment behavior:
+ * - **Node.js**: Writes file to filesystem at specified path
+ * - **Browser**: Triggers automatic download with filename extracted from path
+ *
+ * ⚠️ WARNING: Cannot serialize:
+ * - Functions (removed silently)
+ * - Symbols (removed silently)
+ * - Circular references (throws TypeError)
+ * - undefined values (removed from objects, converted to null in arrays)
+ * - BigInt values (throws TypeError unless custom replacer provided)
+ *
+ * @param data - Any serializable JavaScript value (object, array, primitive)
+ * @param filePath - File path (Node.js) or download filename (Browser)
+ * @param options - Export options (optional)
+ * @param options.indent - Number of spaces for indentation (default: 2, use 0 for compact)
+ * @returns Promise that resolves when export completes
+ *
+ * @example
+ * ```typescript
+ * // Basic export - Object
+ * const config = {
+ *   database: { host: 'localhost', port: 5432 },
+ *   features: { auth: true, payments: false }
+ * }
+ *
+ * // Node.js - Write to file
+ * await exportJSON(config, './config/app.json')
+ * // Creates: ./config/app.json with 2-space indentation
+ *
+ * // Browser - Trigger download
+ * await exportJSON(config, 'app-config.json')
+ * // Downloads: app-config.json to browser's download folder
+ *
+ * // Compact output (no pretty-printing)
+ * await exportJSON(config, 'config.json', { indent: 0 })
+ * // Single-line JSON: {"database":{"host":"localhost","port":5432}}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Array export
+ * const users = [
+ *   { id: 1, name: 'Alice', email: 'alice@example.com' },
+ *   { id: 2, name: 'Bob', email: 'bob@example.com' }
+ * ]
+ * await exportJSON(users, 'users.json')
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Configuration backup system
+ * async function backupConfiguration(config: AppConfig) {
+ *   const timestamp = new Date().toISOString().split('T')[0]
+ *   const filename = `config-backup-${timestamp}.json`
+ *
+ *   try {
+ *     await exportJSON(config, `./backups/${filename}`, { indent: 2 })
+ *     console.log(`✅ Configuration backed up to ${filename}`)
+ *   } catch (error) {
+ *     console.error('❌ Backup failed:', error)
+ *     throw error
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Export API response for debugging
+ * async function debugApiResponse(endpoint: string, data: any) {
+ *   const filename = `api-${endpoint.replace(/\//g, '-')}.json`
+ *   await exportJSON({
+ *     endpoint,
+ *     timestamp: new Date().toISOString(),
+ *     data
+ *   }, filename)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle circular references
+ * const obj = { name: 'test' }
+ * obj.self = obj  // Circular reference
+ *
+ * try {
+ *   await exportJSON(obj, 'circular.json')
+ * } catch (error) {
+ *   console.error('Cannot serialize circular structure')
+ *   // Use custom replacer to handle circular refs
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Different indentation levels
+ * await exportJSON(data, 'compact.json', { indent: 0 })     // Single line
+ * await exportJSON(data, 'readable.json', { indent: 2 })    // 2 spaces (default)
+ * await exportJSON(data, 'spacious.json', { indent: 4 })    // 4 spaces
+ * ```
+ *
+ * @throws {TypeError} If data contains circular references or BigInt values
+ * @throws {Error} If file write fails in Node.js (permissions, disk space, etc.)
+ * @see {@link importJSON} for importing JSON files
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify JSON.stringify Documentation}
+ */
+declare function exportJSON(data: any, filePath: string, options?: {
+    indent?: number;
+}): Promise<void>;
+/**
+ * Imports JSON file and parses it to JavaScript value
+ *
+ * Reads JSON file from filesystem (Node.js only) and parses using native JSON.parse.
+ * Returns the parsed JavaScript value (object, array, primitive).
+ *
+ * Features:
+ * - UTF-8 encoding support for international characters
+ * - Native JSON.parse for standard-compliant parsing
+ * - Automatic type inference
+ * - Whitespace and comment tolerance (standard JSON only)
+ *
+ * ⚠️ BROWSER LIMITATION: File reading from filesystem is not supported in browsers
+ * for security reasons. For browser file uploads, use `readFileAsText()` with a File object
+ * obtained from an input[type="file"] element.
+ *
+ * @param filePath - Path to JSON file (Node.js only)
+ * @param _options - Reserved for future options (currently unused)
+ * @returns Promise<any> Parsed JavaScript value (object, array, primitive, null)
+ *
+ * @example
+ * ```typescript
+ * // Basic import - Node.js only
+ * const config = await importJSON('./config/app.json')
+ * // Returns: { database: { host: 'localhost', port: 5432 }, ... }
+ *
+ * console.log(config.database.host)  // 'localhost'
+ *
+ * // Array import
+ * const users = await importJSON('./data/users.json')
+ * // Returns: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ *
+ * // Primitive values (valid JSON)
+ * const version = await importJSON('./version.json')  // "1.2.3"
+ * const enabled = await importJSON('./feature.json')   // true
+ * const count = await importJSON('./count.json')       // 42
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Load configuration with fallback
+ * async function loadConfiguration(configPath: string): Promise<AppConfig> {
+ *   try {
+ *     const config = await importJSON(configPath)
+ *
+ *     // Validate loaded config
+ *     if (!config.database || !config.database.host) {
+ *       throw new Error('Invalid configuration: missing database.host')
+ *     }
+ *
+ *     return config
+ *   } catch (error) {
+ *     console.warn(`Failed to load config from ${configPath}:`, error)
+ *     console.log('Using default configuration')
+ *     return getDefaultConfig()
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-world: Restore configuration backup
+ * async function restoreBackup(backupFile: string) {
+ *   console.log(`Restoring configuration from ${backupFile}...`)
+ *
+ *   const backup = await importJSON(`./backups/${backupFile}`)
+ *
+ *   // Verify backup integrity
+ *   if (!backup.timestamp || !backup.config) {
+ *     throw new Error('Invalid backup file format')
+ *   }
+ *
+ *   // Restore configuration
+ *   await saveConfiguration(backup.config)
+ *
+ *   console.log(`✅ Configuration restored from ${backup.timestamp}`)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Browser alternative using File API
+ * // HTML: <input type="file" id="jsonFile" accept=".json">
+ *
+ * document.getElementById('jsonFile').addEventListener('change', async (e) => {
+ *   const file = e.target.files[0]
+ *
+ *   // Read file content
+ *   const content = await readFileAsText(file)
+ *
+ *   // Parse JSON
+ *   try {
+ *     const data = JSON.parse(content)
+ *     console.log('Imported JSON:', data)
+ *   } catch (error) {
+ *     console.error('Invalid JSON file:', error)
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle parsing errors
+ * async function safeImportJSON(filePath: string): Promise<any | null> {
+ *   try {
+ *     return await importJSON(filePath)
+ *   } catch (error) {
+ *     if (error.message.includes('not supported in browser')) {
+ *       console.error('Use File API for browser uploads')
+ *     } else if (error.code === 'ENOENT') {
+ *       console.error(`File not found: ${filePath}`)
+ *     } else if (error instanceof SyntaxError) {
+ *       console.error(`Invalid JSON syntax in ${filePath}:`, error.message)
+ *     } else {
+ *       console.error('JSON import failed:', error)
+ *     }
+ *     return null
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Type-safe import with validation
+ * interface DatabaseConfig {
+ *   host: string
+ *   port: number
+ *   database: string
+ * }
+ *
+ * async function loadDatabaseConfig(path: string): Promise<DatabaseConfig> {
+ *   const raw = await importJSON(path)
+ *
+ *   // Runtime validation
+ *   if (typeof raw.host !== 'string' || typeof raw.port !== 'number') {
+ *     throw new Error('Invalid database configuration structure')
+ *   }
+ *
+ *   return raw as DatabaseConfig
+ * }
+ * ```
+ *
+ * @throws {Error} 'JSON import not supported in browser' when called in browser environment
+ * @throws {SyntaxError} If file contains invalid JSON syntax
+ * @throws {Error} File system errors (ENOENT, EACCES, etc.) in Node.js
+ * @see {@link exportJSON} for exporting JSON files
+ * @see {@link readFileAsText} for browser file reading
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse JSON.parse Documentation}
+ */
+declare function importJSON(filePath: string, _options?: any): Promise<any>;
+
+export { exportJSON, importJSON };