{"id":30196483,"url":"https://github.com/arsh342/filesops","last_synced_at":"2025-08-13T05:23:14.077Z","repository":{"id":306458410,"uuid":"1026262665","full_name":"arsh342/filesops","owner":"arsh342","description":"A comprehensive Node.js library for advanced file operations including search, type detection, size calculation, and permission utilities.","archived":false,"fork":false,"pushed_at":"2025-07-25T15:54:13.000Z","size":63,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-25T22:39:38.257Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arsh342.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-25T15:24:22.000Z","updated_at":"2025-07-25T18:39:32.000Z","dependencies_parsed_at":"2025-07-25T22:39:41.083Z","dependency_job_id":"be6f4c8d-76f0-4e1c-a655-3a28b5aff306","html_url":"https://github.com/arsh342/filesops","commit_stats":null,"previous_names":["arsh342/filesops"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/arsh342/filesops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsh342%2Ffilesops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsh342%2Ffilesops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsh342%2Ffilesops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsh342%2Ffilesops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arsh342","download_url":"https://codeload.github.com/arsh342/filesops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsh342%2Ffilesops/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270183894,"owners_count":24541416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-13T05:23:08.495Z","updated_at":"2025-08-13T05:23:14.034Z","avatar_url":"https://github.com/arsh342.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# filesops\n\nA comprehensive Node.js library for advanced file operations including search, type detection, size calculation, and permission utilities.\n\n## Features\n\n- **Advanced File Search**: Powerful search functionality with pattern matching, filtering, and recursive directory traversal\n- **File Type Detection**: Intelligent file type detection using both file extensions and magic numbers\n- **Size Calculation**: Comprehensive file and directory size utilities with human-readable formatting\n- **Permission Checking**: Cross-platform file permission analysis and validation\n\n## Installation\n\n```bash\nnpm install filesops\n```\n\n## Quick Start\n\n```typescript\nimport { FileSearch, FileTypeDetector, SizeCalculator, PermissionChecker } from 'filesops';\n\n// Search for JavaScript files larger than 1MB\nconst result = await FileSearch.search('./src', {\n  extensions: ['.js', '.ts'],\n  minSize: 1024 * 1024, // 1MB\n  pattern: '*.component.*'\n});\n\n// Detect file type\nconst fileType = await FileTypeDetector.detectFromContent('./image.png');\nconsole.log(fileType.mimeType); // 'image/png'\n\n// Calculate directory size\nconst size = await SizeCalculator.getDirectorySize('./dist');\nconsole.log(size.formatted); // '15.2 MB'\n\n// Check file permissions\nconst permissions = await PermissionChecker.getPermissions('./script.sh');\nconsole.log(permissions.executable); // true/false\n```\n\n## API Reference\n\n### FileSearch\n\nAdvanced file searching with multiple filtering options.\n\n#### Methods\n\n- `search(path, options)` - Search for files with advanced filtering\n- `findByName(path, pattern, caseSensitive)` - Find files by name pattern\n- `findByExtension(path, extensions)` - Find files by extension\n- `findLargeFiles(path, minSize)` - Find files larger than specified size\n- `findRecentFiles(path, since)` - Find recently modified files\n- `exists(path)` - Check if file/directory exists\n\n#### Search Options\n\n```typescript\ninterface SearchOptions {\n  pattern?: string | RegExp;        // Name pattern to match\n  extensions?: string[];            // File extensions to include\n  maxDepth?: number;               // Maximum recursion depth\n  includeHidden?: boolean;         // Include hidden files\n  caseSensitive?: boolean;         // Case sensitive pattern matching\n  followSymlinks?: boolean;        // Follow symbolic links\n  maxSize?: number;               // Maximum file size in bytes\n  minSize?: number;               // Minimum file size in bytes\n  modifiedSince?: Date;           // Files modified after this date\n  modifiedBefore?: Date;          // Files modified before this date\n}\n```\n\n### FileTypeDetector\n\nIntelligent file type detection and classification.\n\n#### Methods\n\n- `detectFromPath(filePath)` - Detect type from file extension\n- `detectFromContent(filePath)` - Detect type from file content (magic numbers)\n- `isTextFile(filePath)` - Check if file is text-based\n- `getSupportedExtensions()` - Get all supported file extensions\n- `getExtensionsByCategory(category)` - Get extensions for a specific category\n\n#### File Type Information\n\n```typescript\ninterface FileTypeInfo {\n  extension: string;      // File extension\n  mimeType: string;      // MIME type\n  category: string;      // File category (Code, Image, Document, etc.)\n  description: string;   // Human-readable description\n  isBinary: boolean;     // Is binary file\n  isText: boolean;       // Is text file\n  isImage: boolean;      // Is image file\n  isVideo: boolean;      // Is video file\n  isAudio: boolean;      // Is audio file\n  isArchive: boolean;    // Is archive file\n  isExecutable: boolean; // Is executable file\n}\n```\n\n### SizeCalculator\n\nFile and directory size calculation utilities.\n\n#### Methods\n\n- `getFileSize(filePath)` - Get file size information\n- `getDirectorySize(dirPath, includeHidden)` - Calculate total directory size\n- `getDirectoryStats(dirPath, includeHidden)` - Get comprehensive directory statistics\n- `findLargestFiles(dirPath, limit, includeHidden)` - Find largest files in directory\n- `compareItems(paths)` - Compare sizes of multiple files/directories\n- `getSizeByPattern(dirPath, pattern, includeHidden)` - Calculate size of files matching pattern\n- `formatBytes(bytes, decimals)` - Format bytes as human-readable string\n- `parseSize(sizeString)` - Parse human-readable size to bytes\n\n#### Size Information\n\n```typescript\ninterface SizeInfo {\n  bytes: number;         // Size in bytes\n  kilobytes: number;     // Size in KB\n  megabytes: number;     // Size in MB\n  gigabytes: number;     // Size in GB\n  terabytes: number;     // Size in TB\n  formatted: string;     // Human-readable format\n}\n```\n\n### PermissionChecker\n\nFile and directory permission utilities.\n\n#### Methods\n\n- `canAccess(filePath)` - Check if file is accessible\n- `canRead(filePath)` - Check if file is readable\n- `canWrite(filePath)` - Check if file is writable\n- `canExecute(filePath)` - Check if file is executable\n- `getPermissions(filePath)` - Get detailed permission information\n- `checkPermissions(filePath, permissions)` - Check multiple permissions at once\n- `formatPermissions(permissions)` - Format permissions as Unix-style string\n- `isOwner(filePath)` - Check if current user owns the file\n- `getDetailedInfo(filePath)` - Get comprehensive file information\n- `isDirectoryWritable(dirPath)` - Check if directory allows file creation\n\n#### Permission Information\n\n```typescript\ninterface PermissionInfo {\n  readable: boolean;     // Can current user read\n  writable: boolean;     // Can current user write\n  executable: boolean;   // Can current user execute\n  owner: {              // Owner permissions\n    read: boolean;\n    write: boolean;\n    execute: boolean;\n  };\n  group: {              // Group permissions\n    read: boolean;\n    write: boolean;\n    execute: boolean;\n  };\n  others: {             // Others permissions\n    read: boolean;\n    write: boolean;\n    execute: boolean;\n  };\n  mode: number;         // Numeric mode\n  octal: string;        // Octal representation\n}\n```\n\n## Utility Functions\n\nThe package also provides convenient utility functions for common operations:\n\n```typescript\nimport * as filesops from 'filesops/filesops';\n\n// Get comprehensive file information\nconst info = await filesops.getFileInfo('./file.txt');\n\n// Find files by type and size\nconst largeImages = await filesops.findByTypeAndSize('./photos', 'Image', 1024 * 1024);\n\n// Get disk usage summary\nconst usage = await filesops.getDiskUsage('./project');\n```\n\nAlternatively, you can import utility functions directly:\n\n```typescript\nimport { getFileInfo, getDiskUsage, findByTypeAndSize } from 'filesops/filesops';\n\n// Use functions directly\nconst info = await getFileInfo('./file.txt');\nconst usage = await getDiskUsage('./project');\n```\n\n## Examples\n\n### Finding Large Files\n\n```typescript\nimport { FileSearch, SizeCalculator } from 'filesops';\n\n// Find files larger than 100MB\nconst largeFiles = await FileSearch.findLargeFiles('./downloads', 100 * 1024 * 1024);\n\n// Get the top 10 largest files in a directory\nconst largest = await SizeCalculator.findLargestFiles('./videos', 10);\nlargest.forEach(file =\u003e {\n  console.log(`${file.path}: ${file.size.formatted}`);\n});\n```\n\n### Analyzing Directory Structure\n\n```typescript\nimport { SizeCalculator, FileTypeDetector } from 'filesops';\n\nconst stats = await SizeCalculator.getDirectoryStats('./project');\nconsole.log(`Total size: ${stats.totalSize.formatted}`);\nconsole.log(`Files: ${stats.fileCount}, Directories: ${stats.directoryCount}`);\n\n// Group files by type\nconst searchResult = await FileSearch.search('./project');\nconst filesByType = new Map();\n\nfor (const file of searchResult.files) {\n  const type = FileTypeDetector.detectFromPath(file.path);\n  if (!filesByType.has(type.category)) {\n    filesByType.set(type.category, []);\n  }\n  filesByType.get(type.category).push(file);\n}\n```\n\n### Permission Auditing\n\n```typescript\nimport { PermissionChecker } from 'filesops';\n\nconst files = ['./script.sh', './config.json', './data.db'];\nconst summary = await PermissionChecker.getPermissionSummary(files);\n\nsummary.forEach(({ path, permissions, accessible }) =\u003e {\n  if (accessible \u0026\u0026 permissions) {\n    console.log(`${path}: ${PermissionChecker.formatPermissions(permissions)}`);\n  } else {\n    console.log(`${path}: Not accessible`);\n  }\n});\n```\n\n## Requirements\n\n- Node.js 14.0.0 or higher\n- TypeScript 5.0.0 or higher (for TypeScript projects)\n\n## Development\n\n### Setup\n```bash\n# Clone the repository\ngit clone https://github.com/arsh342/filesops.git\ncd filesops\n\n# Install dependencies (use npm ci for exact versions)\nnpm ci\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n\n# Run development mode (watch for changes)\nnpm run dev\n```\n\n### CI/CD\nThe project includes GitHub Actions workflows for automated testing and publishing. The CI process:\n1. Runs `npm ci` for exact dependency installation\n2. Builds the TypeScript project\n3. Runs the full test suite\n4. Publishes to NPM on successful builds to main branch\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farsh342%2Ffilesops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farsh342%2Ffilesops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farsh342%2Ffilesops/lists"}