@hyperfrontend/project-scope 0.2.1 → 0.2.2

package/core/fs/index.d.ts

@@ -1,6 +1,479 @@
-export * from './read';
-export * from './write';
-export * from './stat';
-export * from './directory';
-export * from './traversal';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Entry metadata for a directory listing.
+ */
+interface DirectoryEntry {
+    /** Entry basename */
+    name: string;
+    /** Full path */
+    path: string;
+    /** Is a file */
+    isFile: boolean;
+    /** Is a directory */
+    isDirectory: boolean;
+    /** Is a symbolic link */
+    isSymlink: boolean;
+    /** Directory depth (for recursive listings) */
+    depth?: number;
+}
+/**
+ * Options for recursive directory listing.
+ */
+interface RecursiveOptions {
+    /** Maximum depth (-1 or Infinity for unlimited) */
+    maxDepth?: number;
+    /** Include hidden files (dotfiles) */
+    includeHidden?: boolean;
+    /** Follow symbolic links into directories */
+    followSymlinks?: boolean;
+}
+/**
+ * List immediate contents of a directory.
+ *
+ * @param dirPath - Absolute or relative path to the directory
+ * @returns Array of entries with metadata for each file/directory
+ * @throws {Error} If directory doesn't exist or isn't a directory
+ *
+ * @example Listing directory contents
+ * ```typescript
+ * import { readDirectory } from '@hyperfrontend/project-scope'
+ *
+ * const entries = readDirectory('./src')
+ * for (const entry of entries) {
+ *   console.log(entry.name, entry.isFile ? 'file' : 'directory')
+ * }
+ * ```
+ */
+declare function readDirectory(dirPath: string): DirectoryEntry[];
+/**
+ * List directory contents recursively with depth tracking.
+ *
+ * @param dirPath - Root directory path to start traversal
+ * @param options - Configuration for depth limit, hidden files, and symlinks
+ * @returns Flat array of all entries found during traversal
+ *
+ * @example Recursive directory listing with options
+ * ```typescript
+ * import { readDirectoryRecursive } from '@hyperfrontend/project-scope'
+ *
+ * // List all files up to 3 levels deep
+ * const entries = readDirectoryRecursive('./src', { maxDepth: 3 })
+ *
+ * // Include hidden files
+ * const allEntries = readDirectoryRecursive('./project', { includeHidden: true })
+ * ```
+ */
+declare function readDirectoryRecursive(dirPath: string, options?: RecursiveOptions): DirectoryEntry[];
+/**
+ * Options for {@link createDirectory}.
+ */
+interface CreateDirectoryOptions {
+    /** Create parent directories if missing (default: true) */
+    recursive?: boolean;
+}
+/**
+ * Create a directory, optionally creating parent directories.
+ *
+ * @param dirPath - Path where the directory should be created
+ * @param options - Creation options
+ * @param options.recursive - Create parent directories if missing (default: true)
+ *
+ * @example Creating directories
+ * ```typescript
+ * // Create nested directories
+ * createDirectory('./output/reports/2024')
+ *
+ * // Create single directory without parents
+ * createDirectory('./logs', { recursive: false })
+ * ```
+ */
+declare function createDirectory(dirPath: string, options?: CreateDirectoryOptions): void;
+/**
+ * Options for {@link removeDirectory}.
+ */
+interface RemoveDirectoryOptions {
+    /** Delete directory contents recursively */
+    recursive?: boolean;
+    /** Ignore errors if directory doesn't exist */
+    force?: boolean;
+}
+/**
+ * Delete a directory from the filesystem.
+ *
+ * @param dirPath - Path to the directory to remove
+ * @param options - Removal configuration
+ * @param options.recursive - Delete directory contents recursively
+ * @param options.force - Ignore errors if directory doesn't exist
+ *
+ * @example Removing directories
+ * ```typescript
+ * // Remove directory and all contents
+ * removeDirectory('./temp', { recursive: true })
+ *
+ * // Safe removal (no error if missing)
+ * removeDirectory('./cache', { recursive: true, force: true })
+ * ```
+ */
+declare function removeDirectory(dirPath: string, options?: RemoveDirectoryOptions): void;
+
+/**
+ * Error codes for file system operations.
+ */
+type FileSystemErrorCode = 'FS_NOT_FOUND' | 'FS_READ_ERROR' | 'FS_WRITE_ERROR' | 'FS_PARSE_ERROR' | 'FS_NOT_A_DIRECTORY';
+/**
+ * File system error with code and context.
+ */
+interface FileSystemErrorContext {
+    /** Absolute or relative path where the error occurred */
+    path: string;
+    /** The filesystem operation that failed */
+    operation: 'read' | 'write' | 'stat' | 'readdir';
+    /** Original error that caused the failure */
+    cause?: unknown;
+}
+/**
+ * Create a file system error with code and context.
+ *
+ * @param message - The error message describing what went wrong
+ * @param code - The category code for this type of filesystem failure
+ * @param context - Additional context including path, operation, and cause
+ * @returns A configured Error object with code and context properties
+ *
+ * @example Creating a file system error
+ * ```typescript
+ * throw createFileSystemError(
+ *   'Cannot read file',
+ *   'FS_READ_ERROR',
+ *   { path: './missing.txt', operation: 'read' }
+ * )
+ * ```
+ */
+declare function createFileSystemError(message: string, code: FileSystemErrorCode, context: FileSystemErrorContext): Error;
+/**
+ * Read file contents as string.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents as string
+ * @throws {Error} If file doesn't exist or can't be read
+ *
+ * @example Reading file contents
+ * ```typescript
+ * import { readFileContent } from '@hyperfrontend/project-scope'
+ *
+ * const content = readFileContent('./package.json')
+ * console.log(content) // JSON string
+ * ```
+ */
+declare function readFileContent(filePath: string, encoding?: BufferEncoding): string;
+/**
+ * Read file contents as Buffer.
+ *
+ * @param filePath - Path to file
+ * @returns File contents as Buffer
+ * @throws {Error} If file doesn't exist or can't be read
+ *
+ * @example Reading file as buffer
+ * ```typescript
+ * const buffer = readFileBuffer('./image.png')
+ * console.log(buffer.length) // File size in bytes
+ * ```
+ */
+declare function readFileBuffer(filePath: string): Buffer;
+/**
+ * Read file if exists, return null otherwise.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents or null if file doesn't exist
+ *
+ * @example Reading file if it exists
+ * ```typescript
+ * const content = readFileIfExists('./optional-config.json')
+ * if (content) {
+ *   // File existed, use content
+ * }
+ * ```
+ */
+declare function readFileIfExists(filePath: string, encoding?: BufferEncoding): string | null;
+/**
+ * Options for reading a JSON file.
+ */
+interface ReadJsonFileOptions<T> {
+    /** Default value to return if the file is not found */
+    default?: T;
+}
+/**
+ * Read and parse JSON file.
+ *
+ * @param filePath - Path to JSON file
+ * @param options - Parse options
+ * @param options.default - Default value if file not found (if not provided, throws on missing file)
+ * @returns Parsed JSON object
+ * @throws {Error} If file doesn't exist (when no default provided) or contains invalid JSON
+ *
+ * @example Reading JSON file
+ * ```typescript
+ * import { readJsonFile } from '@hyperfrontend/project-scope'
+ *
+ * // Read with type inference
+ * interface Config { port: number }
+ * const config = readJsonFile<Config>('./config.json')
+ *
+ * // Read with default fallback
+ * const settings = readJsonFile('./settings.json', { default: {} })
+ * ```
+ */
+declare function readJsonFile<T>(filePath: string, options?: ReadJsonFileOptions<T>): T;
+/**
+ * Read and parse JSON file if exists, return null otherwise.
+ *
+ * @param filePath - Path to JSON file
+ * @returns Parsed JSON object or null if file doesn't exist or is invalid
+ *
+ * @example Reading JSON file if it exists
+ * ```typescript
+ * interface UserSettings { theme: string }
+ * const settings = readJsonFileIfExists<UserSettings>('./user-settings.json')
+ * const theme = settings?.theme ?? 'default'
+ * ```
+ */
+declare function readJsonFileIfExists<T>(filePath: string): T | null;
+
+/**
+ * File statistics.
+ */
+interface FileStats {
+    /** Is a file */
+    isFile: boolean;
+    /** Is a directory */
+    isDirectory: boolean;
+    /** Is a symbolic link */
+    isSymlink: boolean;
+    /** File size in bytes */
+    size: number;
+    /** Creation time */
+    created: Date;
+    /** Modification time */
+    modified: Date;
+    /** Last access time */
+    accessed: Date;
+    /** File mode/permissions */
+    mode: number;
+}
+/**
+ * Get file stats with error handling.
+ *
+ * @param filePath - Path to file
+ * @param followSymlinks - Whether to follow symlinks (default: true)
+ * @returns File stats or null if path doesn't exist
+ *
+ * @example Getting file statistics
+ * ```typescript
+ * const stats = getFileStat('./package.json')
+ * if (stats) {
+ *   console.log(`Size: ${stats.size} bytes`)
+ *   console.log(`Modified: ${stats.modified}`)
+ * }
+ * ```
+ */
+declare function getFileStat(filePath: string, followSymlinks?: boolean): FileStats | null;
+/**
+ * Check if path is a file.
+ *
+ * @param filePath - Path to check
+ * @returns True if path is a file
+ *
+ * @example Checking if path is a file
+ * ```typescript
+ * if (isFile('./package.json')) {
+ *   // Path exists and is a regular file
+ * }
+ * ```
+ */
+declare function isFile(filePath: string): boolean;
+/**
+ * Check if path is a directory.
+ *
+ * @param dirPath - Path to check
+ * @returns True if path is a directory
+ *
+ * @example Checking if path is a directory
+ * ```typescript
+ * if (isDirectory('./src')) {
+ *   // Path exists and is a directory
+ * }
+ * ```
+ */
+declare function isDirectory(dirPath: string): boolean;
+/**
+ * Check if path is a symbolic link.
+ *
+ * @param linkPath - Path to check
+ * @returns True if path is a symlink
+ *
+ * @example Checking if path is a symlink
+ * ```typescript
+ * if (isSymlink('./node_modules/.bin/tsc')) {
+ *   // Path is a symbolic link
+ * }
+ * ```
+ */
+declare function isSymlink(linkPath: string): boolean;
+/**
+ * Check if path exists.
+ *
+ * @param filePath - Path to check
+ * @returns True if path exists
+ *
+ * @example Checking if path exists
+ * ```typescript
+ * if (exists('./config.json')) {
+ *   const config = readJsonFile('./config.json')
+ * }
+ * ```
+ */
+declare function exists(filePath: string): boolean;
+
+/**
+ * Options for write operations.
+ */
+interface WriteFileOptions {
+    /** File encoding */
+    encoding?: BufferEncoding;
+    /** File mode/permissions */
+    mode?: number;
+}
+/**
+ * Options for JSON write operations.
+ */
+interface WriteJsonOptions extends WriteFileOptions {
+    /** Indentation spaces (default: 2) */
+    indent?: number;
+}
+/**
+ * Ensure directory exists, create recursively if not.
+ *
+ * @param dirPath - Directory path to ensure exists
+ *
+ * @example Ensuring directory exists
+ * ```typescript
+ * ensureDir('./output/reports')
+ * // Directory now exists (created if missing)
+ * ```
+ */
+declare function ensureDir(dirPath: string): void;
+/**
+ * Write string content to file.
+ * Creates parent directories if needed.
+ *
+ * @param filePath - Absolute or relative path to the target file
+ * @param content - String content to write to the file
+ * @param options - Optional write configuration (encoding, mode)
+ * @throws {Error} If write fails
+ *
+ * @example Writing text content to file
+ * ```typescript
+ * import { writeFileContent } from '@hyperfrontend/project-scope'
+ *
+ * // Write a simple text file
+ * writeFileContent('./output/data.txt', 'Hello, World!')
+ *
+ * // Write with custom encoding
+ * writeFileContent('./output/data.txt', 'Content', { encoding: 'utf-8' })
+ * ```
+ */
+declare function writeFileContent(filePath: string, content: string, options?: WriteFileOptions): void;
+/**
+ * Write Buffer to file.
+ * Creates parent directories if needed.
+ *
+ * @param filePath - Absolute or relative path to the target file
+ * @param content - Buffer containing binary data to write
+ * @param options - Optional write configuration (mode)
+ * @throws {Error} If write fails
+ *
+ * @example Writing binary buffer to file
+ * ```typescript
+ * const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47])
+ * writeFileBuffer('./output/image.png', imageBuffer)
+ * ```
+ */
+declare function writeFileBuffer(filePath: string, content: Buffer, options?: WriteFileOptions): void;
+/**
+ * Write JSON data to file with formatting.
+ * Creates parent directories if needed.
+ *
+ * @param filePath - Absolute or relative path to the target JSON file
+ * @param data - Object or value to serialize as JSON
+ * @param options - Optional write configuration (indent, encoding, mode)
+ * @throws {Error} If write fails
+ *
+ * @example Writing JSON data to file
+ * ```typescript
+ * import { writeJsonFile } from '@hyperfrontend/project-scope'
+ *
+ * // Write object to JSON file
+ * writeJsonFile('./config.json', { port: 3000, debug: true })
+ *
+ * // Write with custom indentation
+ * writeJsonFile('./config.json', data, { indent: 4 })
+ * ```
+ */
+declare function writeJsonFile<T>(filePath: string, data: T, options?: WriteJsonOptions): void;
+
+/**
+ * Generic upward directory traversal.
+ * Name avoids similarity to fs.readdir/fs.readdirSync.
+ *
+ * @param startPath - Starting directory
+ * @param predicate - Function to test each directory
+ * @returns First matching directory or null
+ *
+ * @example Finding directory containing README
+ * ```typescript
+ * // Find first directory containing a README
+ * const readmeDir = traverseUpward('./src/utils', (dir) =>
+ *   existsSync(join(dir, 'README.md'))
+ * )
+ * // => '/project' or null
+ * ```
+ */
+declare function traverseUpward(startPath: string, predicate: (dirPath: string) => boolean): string | null;
+/**
+ * Find directory containing any of the specified marker files.
+ *
+ * @param startPath - Starting directory
+ * @param markers - Array of marker file names to search for
+ * @returns First directory containing any marker, or null
+ *
+ * @example Finding project root by marker files
+ * ```typescript
+ * // Find project root by looking for common marker files
+ * const projectRoot = locateByMarkers('./src/components', [
+ *   'package.json',
+ *   'nx.json',
+ *   'tsconfig.base.json'
+ * ])
+ * // => '/workspace/my-project'
+ * ```
+ */
+declare function locateByMarkers(startPath: string, markers: readonly string[]): string | null;
+/**
+ * Find directory where predicate returns true, starting from given path.
+ *
+ * @param startPath - Starting directory
+ * @param test - Function to test if directory matches criteria
+ * @returns Matching directory path or null
+ *
+ * @example Finding directory with specific config
+ * ```typescript
+ * // Find directory with a specific config
+ * const configDir = findUpwardWhere('./deep/nested/path', (dir) =>
+ *   existsSync(join(dir, '.eslintrc.js'))
+ * )
+ * ```
+ */
+declare function findUpwardWhere(startPath: string, test: (dirPath: string) => boolean): string | null;
+
+export { createDirectory, createFileSystemError, ensureDir, exists, findUpwardWhere, getFileStat, isDirectory, isFile, isSymlink, locateByMarkers, readDirectory, readDirectoryRecursive, readFileBuffer, readFileContent, readFileIfExists, readJsonFile, readJsonFileIfExists, removeDirectory, traverseUpward, writeFileBuffer, writeFileContent, writeJsonFile };
+export type { DirectoryEntry, FileStats, FileSystemErrorCode, FileSystemErrorContext, ReadJsonFileOptions, RecursiveOptions, WriteFileOptions, WriteJsonOptions };

package/core/fs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/core/fs/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/core/fs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnE,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AAC9F,YAAY,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACvC,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACrG,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAA;AACrI,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAC5E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC9E,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA"}