{"id":15551281,"url":"https://github.com/orcunsaltik/njshell","last_synced_at":"2026-04-09T20:46:07.576Z","repository":{"id":135804368,"uuid":"275408130","full_name":"orcunsaltik/njshell","owner":"orcunsaltik","description":"Run shell, bash command or file asynchronously from Node.js scripts.","archived":false,"fork":false,"pushed_at":"2020-10-17T19:02:50.000Z","size":15,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-06T04:13:54.043Z","etag":null,"topics":["bash","cmd","es6","javascript","js","node","node-js","node-module","nodejs","shell"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/njshell","language":"JavaScript","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/orcunsaltik.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}},"created_at":"2020-06-27T16:13:10.000Z","updated_at":"2024-07-09T06:33:49.000Z","dependencies_parsed_at":"2023-05-22T19:00:19.781Z","dependency_job_id":null,"html_url":"https://github.com/orcunsaltik/njshell","commit_stats":{"total_commits":17,"total_committers":2,"mean_commits":8.5,"dds":0.05882352941176472,"last_synced_commit":"3d7827c24512b7701ac24c5f04ddc8f4cb189c99"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orcunsaltik%2Fnjshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orcunsaltik%2Fnjshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orcunsaltik%2Fnjshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orcunsaltik%2Fnjshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orcunsaltik","download_url":"https://codeload.github.com/orcunsaltik/njshell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246126669,"owners_count":20727594,"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","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":["bash","cmd","es6","javascript","js","node","node-js","node-module","nodejs","shell"],"created_at":"2024-10-02T14:03:53.916Z","updated_at":"2026-04-09T20:46:07.561Z","avatar_url":"https://github.com/orcunsaltik.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# njshell\n\n[![CI](https://github.com/orcunsaltik/njshell/actions/workflows/ci.yml/badge.svg)](https://github.com/orcunsaltik/njshell/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/njshell.svg)](https://www.npmjs.com/package/njshell)\n[![npm downloads](https://img.shields.io/npm/dt/njshell.svg)](https://www.npmjs.com/package/njshell)\n[![license](https://img.shields.io/npm/l/njshell.svg)](https://github.com/orcunsaltik/njshell/blob/master/LICENSE)\n\n\u003e Lightweight shell command executor for Node.js - Support for multiple output formats (string, buffer, stream, vinyl), local npm binaries, timeout controls, and Gulp integration.\n\nLightweight utility for running shell commands from Node.js with support for multiple output types: string, buffer, stream, and vinyl (for Gulp pipelines).\n\n## Features\n\n- ✅ Multiple output formats (string, buffer, stream, vinyl)\n- ✅ Async/Promise-based API\n- ✅ Local npm binary execution\n- ✅ Timeout and signal support\n- ✅ Gulp/Vinyl integration\n- ✅ Windows support\n- ✅ TypeScript-friendly JSDoc\n- ✅ Zero configuration\n\n## Installation\n\n```bash\nnpm install njshell\n```\n\n## Quick Start\n\n```javascript\nconst { exec, execLocal } = require('njshell');\n\n// Execute command and get output as string\nconst version = await exec('node --version');\nconsole.log(version); // \"v20.10.0\"\n\n// Run local npm binary\nconst lintResult = await execLocal('eslint src/**/*.js');\nconsole.log(lintResult);\n```\n\n## API\n\n### `exec(command, type, filename, options)`\n\nExecute a shell command with flexible output format.\n\n**Parameters:**\n\n- `command` (string) - Command to execute\n- `type` (string) - Output format: `'string'` (default), `'buffer'`, `'stream'`, or `'vinyl'`\n- `filename` (string) - Required when type is `'vinyl'`\n- `options` (object) - Execution options\n\n**Options:**\n\n- `cwd` (string) - Current working directory\n- `encoding` (string) - Output encoding (default: `'utf8'`)\n- `timeout` (number) - Timeout in milliseconds (default: `0` = no timeout)\n- `maxBuffer` (number) - Maximum stdout/stderr size (default: 10MB)\n- `signal` (AbortSignal) - AbortSignal for cancellation\n\n**Returns:** `Promise\u003cstring|Buffer|Readable|Stream\u003e`\n\n---\n\n### `execLocal(binary, type, filename, options)`\n\nExecute a local npm binary from `node_modules/.bin/`.\n\n**Parameters:**\n\n- `binary` (string) - Binary name (e.g., `'eslint'`, `'webpack'`)\n- `type` (string) - Output format (same as `exec`)\n- `filename` (string) - Required when type is `'vinyl'`\n- `options` (object) - Execution options (same as `exec`)\n\n**Returns:** `Promise\u003cstring|Buffer|Readable|Stream\u003e`\n\n---\n\n## Usage Examples\n\n### String Output (Default)\n\nGet command output as a trimmed string:\n\n```javascript\nconst { exec } = require('njshell');\n\n// Get Node.js version\nconst version = await exec('node --version');\nconsole.log(version); // \"v20.10.0\"\n\n// Get directory listing\nconst files = await exec('ls -la');\nconsole.log(files);\n\n// Get package version from npm\nconst pkgVersion = await exec('npm view njshell version');\nconsole.log(`Current version: ${pkgVersion}`);\n```\n\n---\n\n### Buffer Output\n\nGet raw binary output:\n\n```javascript\nconst { exec } = require('njshell');\n\n// Get file contents as buffer\nconst buffer = await exec('cat image.png', 'buffer');\nconsole.log(buffer); // \u003cBuffer 89 50 4e 47...\u003e\n\n// Process binary data\nconst compressed = zlib.gzipSync(buffer);\n```\n\n---\n\n### Stream Output\n\nGet output as a readable stream:\n\n```javascript\nconst { exec } = require('njshell');\nconst fs = require('fs');\n\n// Stream large file\nconst stream = await exec('cat large-file.txt', 'stream');\nstream.pipe(fs.createWriteStream('output.txt'));\n\n// Process stream data\nstream.on('data', (chunk) =\u003e {\n  console.log(`Received ${chunk.length} bytes`);\n});\n\nstream.on('end', () =\u003e {\n  console.log('Stream completed');\n});\n```\n\n---\n\n### Vinyl Output (Gulp Integration)\n\nCreate vinyl files for Gulp pipelines:\n\n```javascript\nconst { exec } = require('njshell');\nconst gulp = require('gulp');\n\nasync function buildStats() {\n  // Run webpack and get stats as vinyl file\n  const vinylStream = await exec('webpack --json', 'vinyl', 'webpack-stats.json');\n\n  return vinylStream.pipe(gulp.dest('dist'));\n}\n\nexports.stats = buildStats;\n```\n\n---\n\n### Local Binaries\n\nExecute npm binaries from `node_modules/.bin/`:\n\n```javascript\nconst { execLocal } = require('njshell');\n\n// Run ESLint\nconst lintResult = await execLocal('eslint src/**/*.js');\nconsole.log(lintResult);\n\n// Run Webpack\nconst buildOutput = await execLocal('webpack --mode production');\nconsole.log(buildOutput);\n\n// Run TypeScript compiler\nconst tscOutput = await execLocal('tsc --noEmit');\nconsole.log(tscOutput);\n```\n\n---\n\n### Advanced Options\n\nUse execution options for better control:\n\n```javascript\nconst { exec } = require('njshell');\n\n// Set working directory\nconst result = await exec('npm install', 'string', null, {\n  cwd: '/path/to/project',\n});\n\n// Set timeout (5 seconds)\ntry {\n  await exec('long-running-command', 'string', null, {\n    timeout: 5000,\n  });\n} catch (err) {\n  console.error('Command timed out');\n}\n\n// Use AbortController for cancellation\nconst controller = new AbortController();\n\nsetTimeout(() =\u003e controller.abort(), 3000);\n\ntry {\n  await exec('sleep 10', 'string', null, {\n    signal: controller.signal,\n  });\n} catch (err) {\n  console.error('Command aborted');\n}\n\n// Increase buffer size for large output\nconst largeOutput = await exec('cat huge-file.txt', 'string', null, {\n  maxBuffer: 50 * 1024 * 1024, // 50MB\n});\n```\n\n---\n\n### Error Handling\n\nHandle command execution errors:\n\n```javascript\nconst { exec } = require('njshell');\n\ntry {\n  const result = await exec('invalid-command');\n} catch (err) {\n  console.error('Command failed:', err.message);\n  console.error('stderr:', err.stderr);\n  console.error('stdout:', err.stdout);\n}\n```\n\n---\n\n### Gulp Build Pipeline\n\nComplete Gulp integration example:\n\n```javascript\nconst { src, dest, series } = require('gulp');\nconst { exec, execLocal } = require('njshell');\n\nasync function lint() {\n  const result = await execLocal('eslint src/**/*.js');\n  console.log(result);\n}\n\nasync function build() {\n  const output = await execLocal('webpack --mode production');\n  console.log(output);\n}\n\nasync function generateDocs() {\n  const docStream = await exec('jsdoc src -r -d docs', 'vinyl', 'docs/index.html');\n  return docStream.pipe(dest('dist'));\n}\n\nexports.default = series(lint, build, generateDocs);\n```\n\n---\n\n## Output Types\n\n### `'string'` (Default)\n\nReturns trimmed UTF-8 string. Best for text output.\n\n```javascript\nconst text = await exec('echo \"Hello World\"');\n// Returns: \"Hello World\"\n```\n\n### `'buffer'`\n\nReturns Buffer object. Best for binary data.\n\n```javascript\nconst buffer = await exec('cat image.png', 'buffer');\n// Returns: \u003cBuffer 89 50 4e 47...\u003e\n```\n\n### `'stream'`\n\nReturns Readable stream. Best for large outputs.\n\n```javascript\nconst stream = await exec('cat large.log', 'stream');\n// Returns: Readable stream\n```\n\n### `'vinyl'`\n\nReturns vinyl file stream. Best for Gulp pipelines.\n\n```javascript\nconst vinylStream = await exec('build-output', 'vinyl', 'output.json');\n// Returns: Vinyl stream for Gulp\n```\n\n---\n\n## Requirements\n\n- Node.js \u003e= 18.0.0\n\n## Changelog\n\n### v2.0.1 (2025)\n\n- 🚀 Updated config files to latest standards\n- 🚀 Improved development workflow\n- 🚀 Better code quality tools\n- 🚀 Updated SEO-friendly package description\n\n### v2.0.0 (2024)\n\n- 🚀 **BREAKING:** Requires Node.js 18+\n- 🚀 **BREAKING:** Main file renamed from `main.js` to `index.js`\n- ✨ Added execution options (cwd, timeout, maxBuffer, signal)\n- ✨ Better error handling with stderr/stdout attachment\n- ✨ Windows support for execLocal (.cmd extension)\n- ✨ Improved vinyl file path handling\n- 🐛 Fixed console.log noise (now uses console.warn for stderr)\n- 🐛 Fixed vinyl path resolution\n- 📚 Comprehensive JSDoc documentation\n- 🔧 Updated dependencies (njfs 2.0, vinyl 3.0)\n\n### v1.1.2 (2020)\n\n- Previous stable release\n\n## Migration from v1.x\n\n```javascript\n// v1.x - Basic usage (still works)\nconst result = await exec('npm --version');\n\n// v2.x - With options\nconst result = await exec('npm --version', 'string', null, {\n  cwd: '/path/to/project',\n  timeout: 5000,\n});\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Troubleshooting\n\nWhen you encounter a problem, please [open an issue](https://github.com/orcunsaltik/njshell/issues).\n\n## Author\n\n**Orçun Saltık**\n\n- GitHub: [@orcunsaltik](https://github.com/orcunsaltik)\n- Email: saltikorcun@gmail.com\n\n## License\n\n[MIT](LICENSE) © Orçun Saltık\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forcunsaltik%2Fnjshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forcunsaltik%2Fnjshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forcunsaltik%2Fnjshell/lists"}