@zintrust/core 0.4.17 → 0.4.19

package/src/common/index.ts

@@ -1,390 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import * as fs from '@node-singletons/fs';
-import * as path from '@node-singletons/path';
-import { fileURLToPath } from '@node-singletons/url';
-
-export { AwsSigV4 } from '@common/AwsSigV4';
-
-// Mutable FileChecker used to abstract FS checks for easier testing/mocking
-export const FileChecker = {
-  exists(filePath: string): boolean {
-    try {
-      return fs.existsSync(filePath);
-    } catch {
-      return false;
-    }
-  },
-};
-
-/**
- * Common utilities - Sealed namespace for immutability
- */
-export const CommonUtils = Object.freeze({
-  /**
-   * Resolve npm executable path from Node.js installation
-   */
-  resolveNpmPath(): string {
-    const nodeBinDir = path.dirname(process.execPath);
-    const candidates =
-      process.platform === 'win32'
-        ? [path.join(nodeBinDir, 'npm.cmd'), path.join(nodeBinDir, 'npm.exe')]
-        : [path.join(nodeBinDir, 'npm')];
-
-    for (const candidate of candidates) {
-      if (fs.existsSync(candidate)) return candidate;
-    }
-
-    throw ErrorFactory.createGeneralError(
-      'Unable to locate npm executable. Ensure Node.js (with npm) is installed in the standard location.'
-    );
-  },
-
-  /**
-   * RUNTIME UTILITIES
-   */
-
-  /**
-   * Async delay helper. No-ops when timers are unavailable.
-   */
-  async delay(ms: number): Promise<void> {
-    if (ms <= 0) return;
-    await new Promise<void>((resolve) => {
-      if (typeof globalThis.setTimeout !== 'function') {
-        resolve();
-        return;
-      }
-      globalThis.setTimeout(() => resolve(), ms);
-    });
-  },
-
-  /**
-   * Resolve an ESM `import.meta.url` to a filesystem path.
-   */
-  esmFilePath(metaUrl: string | URL): string {
-    if (metaUrl === undefined || metaUrl === null) return '';
-    if (typeof metaUrl !== 'string' && !(metaUrl instanceof URL)) return '';
-    if (typeof metaUrl === 'string' && metaUrl.trim() === '') return '';
-    return fileURLToPath(metaUrl);
-  },
-
-  /**
-   * Resolve an ESM `import.meta.url` to a filesystem directory.
-   */
-  esmDirname(metaUrl: string | URL): string {
-    const resolved = this.esmFilePath(metaUrl);
-    return resolved === '' ? '' : path.dirname(resolved);
-  },
-
-  /**
-   * STRING UTILITIES
-   */
-
-  /**
-   * Convert string to camelCase
-   */
-  camelCase(str: string): string {
-    return (
-      str
-        // First convert PascalCase/camelCase to snake_case format for splitting
-        .replaceAll(/([a-z])([A-Z])/g, '$1_$2')
-        .split(/[\s_-]+/)
-        .map((word, index) => {
-          if (index === 0) {
-            return word.charAt(0).toLowerCase() + word.slice(1).toLowerCase();
-          }
-          return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-        })
-        .join('')
-    );
-  },
-
-  /**
-   * Convert string to snake_case
-   */
-  toSnakeCase(str: string): string {
-    return str
-      .replaceAll(/([a-z])([A-Z])/g, '$1_$2')
-      .replaceAll(/([A-Z])/g, '_$1')
-      .replaceAll(/(\d)([A-Z])/g, '$1_$2')
-      .toLowerCase()
-      .replace(/^_/, '')
-      .replaceAll(/__+/g, '_');
-  },
-
-  /**
-   * Convert string to PascalCase
-   */
-  toPascalCase(str: string): string {
-    return str
-      .replaceAll(/([a-z])([A-Z])/g, '$1_$2') // Add underscore before capital letters in camelCase
-      .split(/[\s_-]+/)
-      .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
-      .join('');
-  },
-
-  /**
-   * FILE SYSTEM UTILITIES
-   */
-
-  /**
-   * Check if file exists
-   */
-  fileExists(filePath: string): boolean {
-    return FileChecker.exists(filePath);
-  },
-
-  /**
-   * Ensure directory exists, create if missing
-   */
-  ensureDir(dirPath: string): void {
-    if (!fs.existsSync(dirPath)) {
-      fs.mkdirSync(dirPath, { recursive: true });
-    }
-  },
-
-  /**
-   * Best-effort variant of ensureDir() that never throws.
-   */
-  ensureDirSafe(dirPath: string): void {
-    try {
-      this.ensureDir(dirPath);
-    } catch {
-      // best-effort
-    }
-  },
-
-  /**
-   * Read file contents as string
-   */
-  readFile(filePath: string): string {
-    try {
-      return fs.readFileSync(filePath, 'utf-8');
-    } catch (error) {
-      throw ErrorFactory.createGeneralError(
-        `Failed to read file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
-      );
-    }
-  },
-
-  /**
-   * Read file contents as string (async)
-   */
-  async readFileAsync(filePath: string): Promise<string> {
-    try {
-      const fsPromises = await import('@node-singletons/fs').then((m) => m.fsPromises);
-      return await fsPromises.readFile(filePath, 'utf-8');
-    } catch (error) {
-      throw ErrorFactory.createGeneralError(
-        `Failed to read file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
-      );
-    }
-  },
-
-  /**
-   * Write file with optional directory creation
-   */
-  writeFile(filePath: string, content: string, createDir = true): void {
-    try {
-      if (createDir) {
-        const dir = path.dirname(filePath);
-        this.ensureDir(dir);
-      }
-      fs.writeFileSync(filePath, content, 'utf-8');
-    } catch (error) {
-      throw ErrorFactory.createGeneralError(
-        `Failed to write file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
-      );
-    }
-  },
-
-  /**
-   * Write file with optional directory creation (async)
-   */
-  async writeFileAsync(filePath: string, content: string, createDir = true): Promise<void> {
-    try {
-      const fsPromises = await import('@node-singletons/fs').then((m) => m.fsPromises);
-      if (createDir) {
-        const dir = path.dirname(filePath);
-        await fsPromises.mkdir(dir, { recursive: true });
-      }
-      await fsPromises.writeFile(filePath, content, 'utf-8');
-    } catch (error) {
-      throw ErrorFactory.createGeneralError(
-        `Failed to write file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
-      );
-    }
-  },
-
-  /**
-   * Delete file if it exists
-   */
-  deleteFile(filePath: string): void {
-    try {
-      if (fs.existsSync(filePath)) {
-        fs.unlinkSync(filePath);
-      }
-    } catch (error) {
-      throw ErrorFactory.createGeneralError(
-        `Failed to delete file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
-      );
-    }
-  },
-
-  /**
-   * TIMESTAMP UTILITIES
-   */
-
-  /**
-   * Get current timestamp in ISO format
-   */
-  getCurrentTimestamp(): string {
-    return new Date().toISOString();
-  },
-
-  /**
-   * Format timestamp for filenames (YYYY-MM-DDTHH-MM-SS-SSSZ)
-   */
-  formatTimestamp(date: Date = new Date()): string {
-    return date.toISOString().replaceAll(/[:.]/g, '-');
-  },
-
-  /**
-   * Parse ISO timestamp string to Date
-   */
-  parseTimestamp(timestamp: string): Date {
-    try {
-      const date = new Date(timestamp);
-      if (date.toString() === 'Invalid Date') {
-        throw ErrorFactory.createGeneralError('Invalid date');
-      }
-      return date;
-    } catch (error) {
-      throw ErrorFactory.createGeneralError(`Failed to parse timestamp: ${timestamp}`, error);
-    }
-  },
-
-  /**
-   * VALIDATION UTILITIES
-   */
-
-  /**
-   * Extract error message from unknown error type
-   */
-  extractErrorMessage(error: unknown): string {
-    if (error instanceof Error) {
-      return error.message;
-    }
-    if (typeof error === 'string') {
-      return error;
-    }
-    if (error !== undefined && error !== null && typeof error === 'object' && 'message' in error) {
-      return String((error as { message: unknown }).message);
-    }
-    return 'Unknown error occurred';
-  },
-
-  /**
-   * Validate options object and throw if invalid
-   */
-  validateOptions(
-    options: Record<string, unknown>,
-    requiredFields: string[],
-    context: string
-  ): void {
-    const missingFields = requiredFields.filter(
-      (field) => options[field] === undefined || options[field] === null
-    );
-    if (missingFields.length > 0) {
-      throw ErrorFactory.createGeneralError(
-        `${context}: Missing required options: ${missingFields.join(', ')}`
-      );
-    }
-  },
-
-  /**
-   * Check if value is valid (not null, undefined, or empty string)
-   */
-  isValid(value: unknown): boolean {
-    return value !== null && value !== undefined && value !== '';
-  },
-
-  /**
-   * Ensure value is string, throw otherwise
-   */
-  ensureString(value: unknown, fieldName: string): string {
-    if (typeof value !== 'string') {
-      throw ErrorFactory.createGeneralError(`${fieldName} must be a string, got ${typeof value}`);
-    }
-    return value;
-  },
-
-  /**
-   * Ensure value is object, throw otherwise
-   */
-  ensureObject(value: unknown, fieldName: string): Record<string, unknown> {
-    if (typeof value !== 'object' || value === null) {
-      throw ErrorFactory.createGeneralError(`${fieldName} must be an object, got ${typeof value}`);
-    }
-    return value as Record<string, unknown>;
-  },
-
-  /**
-   * Resolve preferred package manager.
-   * If `preferred` is provided, the first value is returned. Otherwise we detect by lock files.
-   */
-  resolvePackageManager(preferred?: string[]): string {
-    if (Array.isArray(preferred) && preferred.length > 0) {
-      return preferred[0];
-    }
-
-    try {
-      if (this.fileExists('pnpm-lock.yaml')) return 'pnpm';
-      if (this.fileExists('yarn.lock')) return 'yarn';
-      if (this.fileExists('package-lock.json')) return 'npm';
-    } catch {
-      // ignore FS errors and fall through to default
-    }
-
-    // Default to npm
-    return 'npm';
-  },
-});
-
-// Re-export for backward compatibility
-export const resolveNpmPath = (): string => CommonUtils.resolveNpmPath();
-
-export const delay = async (ms: number): Promise<void> => CommonUtils.delay(ms);
-
-export const esmFilePath = (metaUrl: string | URL): string => CommonUtils.esmFilePath(metaUrl);
-export const esmDirname = (metaUrl: string | URL): string => CommonUtils.esmDirname(metaUrl);
-
-export const resolvePackageManager = (preferred?: string[]): string => {
-  return CommonUtils.resolvePackageManager(preferred);
-};
-
-export const extractErrorMessage = (error: unknown): string =>
-  CommonUtils.extractErrorMessage(error);
-
-// Some call sites historically treated non-Error throws (e.g. string) as unknown.
-// Keep that behavior available as a shared helper.
-export const extractErrorMessageStrict = (error: unknown): string => {
-  if (error instanceof Error) return error.message;
-  if (error !== undefined && error !== null && typeof error === 'object' && 'message' in error) {
-    return String((error as { message: unknown }).message);
-  }
-  return 'Unknown error';
-};
-
-// Convenience named exports to make specific helpers testable and import-friendly
-export const fileExists = (filePath: string): boolean => CommonUtils.fileExists(filePath);
-export const ensureDir = (dirPath: string): void => CommonUtils.ensureDir(dirPath);
-export const ensureDirSafe = (dirPath: string): void => CommonUtils.ensureDirSafe(dirPath);
-export const readFile = (filePath: string): string => CommonUtils.readFile(filePath);
-export const writeFile = (filePath: string, content: string, createDir = true): void =>
-  CommonUtils.writeFile(filePath, content, createDir);
-
-export const runFromSource = (): boolean => {
-  const runFromSourceEnv = process.env['ZINTRUST_RUN_FROM_SOURCE'] ?? '';
-
-  return runFromSourceEnv === '1' || runFromSourceEnv.toLowerCase() === 'true';
-};

package/src/common/utility.ts

@@ -1,134 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { isEmpty as isEmptyHelper } from '@helper/index';
-import { randomBytes } from '@node-singletons/crypto';
-
-export const generateUuid = (): string => {
-  if (typeof globalThis?.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
-  return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`; // NOSONAR
-};
-
-export function generateSecureJobId(
-  errMsg: string = 'Secure crypto API not available to generate a job id.'
-): string {
-  if (typeof globalThis.crypto?.randomUUID === 'function') {
-    return globalThis.crypto.randomUUID();
-  }
-
-  if (typeof globalThis.crypto?.getRandomValues === 'function') {
-    const bytes = new Uint8Array(16);
-    globalThis.crypto.getRandomValues(bytes);
-    return bytesToHex(bytes);
-  }
-
-  // Node fallback for environments without Web Crypto
-  try {
-    return randomBytes(16).toString('hex');
-  } catch (error) {
-    throw ErrorFactory.createTryCatchError(
-      errMsg || 'Secure crypto API not available to generate a job id.',
-      error
-    );
-  }
-}
-
-export const getString = (value: unknown): string => (typeof value === 'string' ? value : '');
-
-function bytesToHex(bytes: Uint8Array): string {
-  let out = '';
-  for (const b of bytes) out += b.toString(16).padStart(2, '0');
-  return out;
-}
-
-export function isEmpty(value: unknown): boolean {
-  return isEmptyHelper(value);
-}
-
-export function toStr(value: unknown): string {
-  return String(value ?? '');
-}
-
-export function stripSpaces(value: unknown): string {
-  return toStr(value).replaceAll(' ', '');
-}
-
-export function sanitize(value: unknown, pattern: RegExp, stripSpace = false): string {
-  const input = stripSpace ? stripSpaces(value) : toStr(value);
-  return input.replace(pattern, '');
-}
-
-export function isNumericString(value: string): boolean {
-  const trimmed = value.trim();
-  if (trimmed.length === 0) return false;
-  const n = Number(trimmed);
-  return Number.isFinite(n);
-}
-
-export function toPlusDecimal(num: unknown, dec = 8): number {
-  if (isEmpty(num)) return 0;
-
-  const numStr = toStr(num);
-  const hasDot = numStr.includes('.');
-  const hasExponent = /e/i.test(numStr);
-
-  const normalized = hasExponent ? Number(numStr).toFixed(dec + 1) : numStr;
-
-  const valueNew = hasDot
-    ? (() => {
-        const [whole, frac = ''] = normalized.split('.');
-        return Number.parseFloat(`${whole}.${frac.slice(0, dec)}`);
-      })()
-    : Number.parseFloat(normalized);
-
-  if (valueNew < 0 && String(valueNew).startsWith('-')) {
-    return 0;
-  }
-
-  return valueNew;
-}
-
-export function toMinusDecimal(num: unknown, dec = 8): number {
-  if (isEmpty(num)) return 0;
-
-  const numStr = toStr(num);
-  const hasDot = numStr.includes('.');
-  const hasExponent = /e/i.test(numStr);
-
-  const normalized = hasExponent ? Number(numStr).toFixed(dec + 1) : numStr;
-
-  if (hasDot) {
-    const [whole, frac = ''] = normalized.split('.');
-    return Number.parseFloat(`${whole}.${frac.slice(0, dec)}`);
-  }
-
-  return Number.parseFloat(normalized);
-}
-
-export const nowIso = (): string => new Date().toISOString();
-
-export interface UtilitiesType {
-  generateUuid: () => string;
-  getString: (value: unknown) => string;
-  generateSecureJobId: (errMsg?: string) => string;
-  isEmpty: (value: unknown) => boolean;
-  toStr: (value: unknown) => string;
-  stripSpaces: (value: unknown) => string;
-  sanitize: (value: unknown, pattern: RegExp, stripSpace?: boolean) => string;
-  isNumericString: (value: string) => boolean;
-  toPlusDecimal: (num: unknown, dec?: number) => number;
-  toMinusDecimal: (num: unknown, dec?: number) => number;
-  nowIso: () => string;
-}
-
-export const Utilities = Object.freeze({
-  generateUuid,
-  getString,
-  generateSecureJobId,
-  isEmpty,
-  toStr,
-  stripSpaces,
-  sanitize,
-  isNumericString,
-  toPlusDecimal,
-  toMinusDecimal,
-  nowIso,
-});