{"id":31364393,"url":"https://github.com/reedchan7/ls-json","last_synced_at":"2026-01-20T17:34:53.706Z","repository":{"id":315560221,"uuid":"1059995832","full_name":"reedchan7/ls-json","owner":"reedchan7","description":"parse ls output to json format.","archived":false,"fork":false,"pushed_at":"2025-09-19T10:06:58.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-19T10:37:27.026Z","etag":null,"topics":["command-line","file-listing","jc","json","ls","parser"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reedchan7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T08:36:25.000Z","updated_at":"2025-09-19T10:06:28.000Z","dependencies_parsed_at":"2025-09-19T22:23:23.145Z","dependency_job_id":null,"html_url":"https://github.com/reedchan7/ls-json","commit_stats":null,"previous_names":["reedchan7/ls-json"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/reedchan7/ls-json","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reedchan7%2Fls-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reedchan7%2Fls-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reedchan7%2Fls-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reedchan7%2Fls-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reedchan7","download_url":"https://codeload.github.com/reedchan7/ls-json/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reedchan7%2Fls-json/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276187485,"owners_count":25599804,"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-09-21T02:00:07.055Z","response_time":72,"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":["command-line","file-listing","jc","json","ls","parser"],"created_at":"2025-09-27T07:05:34.843Z","updated_at":"2025-09-27T07:05:35.994Z","avatar_url":"https://github.com/reedchan7.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ls-json\n\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](https://www.npmjs.com/package/ls-json)\n\nA powerful TypeScript library to parse `ls` and `ls -R` output into structured JSON format with advanced querying capabilities.\n\n## ✨ Features\n\n- **🚀 Zero Dependencies** - Pure TypeScript implementation with no external dependencies for maximum compatibility and minimal bundle size\n- **📁 Standard ls parsing** - Parse regular `ls -l` output into structured data\n- **🔄 Recursive ls parsing** - Parse `ls -R` output with powerful traversal methods\n- **⚡ Streaming support** - Process large ls outputs efficiently\n- **🎯 Advanced querying** - Find, filter, and traverse directory structures\n- **🔍 Depth control** - Limit recursive parsing depth for performance\n- **🛡️ Error handling** - Graceful handling of permission denied and malformed entries\n\n## Installation\n\n```bash\nnpm install ls-json\n```\n\nOr using pnpm:\n\n```bash\npnpm add ls-json\n```\n\n## Quick Start\n\n### Basic Usage\n\n```typescript\nimport { parse } from \"ls-json\";\n\nconst lsOutput = `total 160\ndrwxr-xr-x  12 user  staff    384 Sep 19 14:51 .\ndrwxr-xr-x   9 user  staff    288 Sep 19 14:16 ..\ndrwxr-xr-x   7 user  staff    224 Sep 19 14:35 dist\n-rw-r--r--   1 user  staff   2640 Sep 19 14:51 index.spec.ts`;\n\nconst result = parse(lsOutput);\nconsole.log(JSON.stringify(result, null, 2));\n```\n\nOutput:\n\n```json\n[\n  {\n    \"filename\": \"dist\",\n    \"flags\": \"drwxr-xr-x\",\n    \"mode\": \"755\",\n    \"type\": \"directory\",\n    \"owner\": \"user\",\n    \"group\": \"staff\",\n    \"size\": 224,\n    \"date\": \"Sep 19 14:35\",\n    \"links\": 7\n  },\n  {\n    \"filename\": \"index.spec.ts\",\n    \"flags\": \"-rw-r--r--\",\n    \"mode\": \"644\",\n    \"type\": \"file\",\n    \"owner\": \"user\",\n    \"group\": \"staff\",\n    \"size\": 2640,\n    \"date\": \"Sep 19 14:51\",\n    \"links\": 1\n  }\n]\n```\n\n### Recursive Directory Parsing\n\n```typescript\nimport { parse } from \"ls-json\";\n\nconst recursiveOutput = `./src:\ntotal 12\n-rw-r--r-- 1 user user 256 Sep 19 14:51 index.ts\ndrwxr-xr-x 2 user user 4096 Sep 19 14:52 utils\n\n./src/utils:\ntotal 8\n-rw-r--r-- 1 user user 128 Sep 19 14:53 helper.ts`;\n\nconst result = parse(recursiveOutput, { recursive: true });\n\n// Get all files across all directories\nconst allFiles = result.getAllEntries();\nconsole.log(allFiles.length); // 3 entries\n\n// Find specific files\nconst indexFile = result.findEntry((entry) =\u003e entry.filename === \"index.ts\");\nconsole.log(indexFile?.parent); // \"./src\"\n\n// Filter by file type\nconst jsFiles = result.filterEntries(\n  (entry) =\u003e entry.filename.endsWith(\".ts\") \u0026\u0026 entry.type === \"file\"\n);\nconsole.log(jsFiles.length); // 2 TypeScript files\n```\n\n## API Reference\n\n### Core Functions\n\n#### `parse(data: string, options?: ParseOptions)`\n\nThe main parsing function that handles both standard and recursive ls output.\n\n**Parameters:**\n\n- `data` - The ls command output string\n- `options` - Optional configuration object\n\n**Returns:**\n\n- `LsEntry[]` for standard parsing\n- `LsRecursiveOutput` for recursive parsing (when `options.recursive = true`)\n\n#### `parseStreaming(lines: Iterable\u003cstring\u003e, options?: ParseOptions)`\n\nProcess ls output line by line using a generator for memory efficiency.\n\n### Parse Options\n\n```typescript\ninterface ParseOptions {\n  // Parse as recursive ls output (ls -R)\n  recursive?: boolean;\n\n  // Maximum directory depth (0 = root only, undefined = no limit)\n  depth?: number;\n\n  // Include . and .. entries (default: false)\n  showDotsDir?: boolean;\n\n  // Return raw data without processing (default: false)\n  raw?: boolean;\n\n  // Continue on errors (default: false)\n  ignoreExceptions?: boolean;\n}\n```\n\n### Recursive Output Methods\n\nWhen using `recursive: true`, the result object provides powerful traversal methods:\n\n```typescript\n// Get all entries from all directories\nconst allEntries = result.getAllEntries();\n\n// Find first entry matching criteria\nconst configFile = result.findEntry(\n  (entry) =\u003e entry.filename === \"config.json\"\n);\n\n// Get all entries matching criteria\nconst largeFiles = result.filterEntries((entry) =\u003e entry.size \u003e 1000000);\n\n// Get entries from specific directory\nconst homeEntries = result.getEntriesByPath(\"/home/user\");\n\n// Get directory tree structure\nconst tree = result.getDirectoryTree(); // { '/path': [entries...] }\n\n// Process all entries with callback\nresult.traverse((entry, directory) =\u003e {\n  console.log(`${directory.path}/${entry.filename}`);\n});\n```\n\n## Advanced Examples\n\n### Depth-Limited Parsing\n\n```typescript\n// Only parse root level + 1 level deep\nconst result = parse(recursiveOutput, {\n  recursive: true,\n  depth: 1,\n});\n\n// Process shallow structure for better performance\nconst topLevelDirs = result.filterEntries(\n  (entry) =\u003e entry.type === \"directory\"\n);\n```\n\n### File Analysis\n\n```typescript\nconst result = parse(lsRecursiveOutput, { recursive: true });\n\n// Find the largest file\nconst largestFile = result\n  .getAllEntries()\n  .filter((entry) =\u003e entry.type === \"file\" \u0026\u0026 typeof entry.size === \"number\")\n  .reduce((largest, current) =\u003e\n    current.size \u003e largest.size ? current : largest\n  );\n\n// Count files by extension\nconst extensionCounts = {};\nresult.traverse((entry) =\u003e {\n  if (entry.type === \"file\") {\n    const ext = entry.filename.split(\".\").pop() || \"no-extension\";\n    extensionCounts[ext] = (extensionCounts[ext] || 0) + 1;\n  }\n});\n\n// Find executable files\nconst executables = result.filterEntries(\n  (entry) =\u003e entry.flags \u0026\u0026 entry.flags.includes(\"x\") \u0026\u0026 entry.type === \"file\"\n);\n```\n\n### Error Handling\n\n```typescript\nconst result = parse(lsOutput, {\n  recursive: true,\n  ignoreExceptions: true,\n});\n\n// Check for parsing errors\nif (result.errors) {\n  console.log(\"Global errors:\", result.errors);\n}\n\n// Check directory-specific errors\nresult.directories.forEach((dir) =\u003e {\n  if (dir.errors) {\n    console.log(`Errors in ${dir.path}:`, dir.errors);\n  }\n});\n```\n\n## Data Structures\n\n### LsEntry\n\n```typescript\ninterface LsEntry {\n  filename: string; // File or directory name\n  flags: string; // Permission string (e.g., \"-rwxr-xr-x\")\n  mode: string; // Octal permissions (e.g., \"755\")\n  type:\n    | \"file\"\n    | \"directory\"\n    | \"symlink\"\n    | \"block\"\n    | \"character\"\n    | \"pipe\"\n    | \"socket\";\n  owner: string; // Owner username\n  group: string; // Group name\n  size: number | string; // Size in bytes or human-readable\n  date: string; // Modification date\n  links?: number; // Hard link count\n  parent?: string; // Parent directory (recursive mode only)\n  link_to?: string; // Symlink target\n  epoch?: number; // Unix timestamp (when available)\n}\n```\n\n## Performance Tips\n\n- Use `depth` parameter to limit recursive parsing depth\n- Use `parseStreaming` for very large outputs\n- Set `ignoreExceptions: true` for malformed input\n- Use specific query methods instead of `getAllEntries()` when possible\n\n## License\n\n[Apache-2.0](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freedchan7%2Fls-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freedchan7%2Fls-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freedchan7%2Fls-json/lists"}