Project · head — a CLI as an npm package

Hints

• Use stdlib only — no commander/yargs/minimist. process.argv + a 10-line loop is enough for -n. Fewer deps = faster install.
• For stdin detection: process.stdin.isTTY returns true when interactive, undefined when piped. Iterate via for await (const line of readline.createInterface({ input: process.stdin })).
• Read files as streams via readline.createInterface({ input: createReadStream(path) }). Don't readFile — head -n 5 of a 10 GB file should be near-instant.
• Add a shebang #!/usr/bin/env node to your bin script and chmod +x src/cli.js. Without it the bin entry won't work on Linux.

Expected output

$ pnpm exec head-js -n 3 README.md
# head-js

A simple head clone in Node.js.

$ pnpm exec head-js README.md src/cli.js
==> README.md <==
# head-js

[... 10 lines ...]

==> src/cli.js <==
#!/usr/bin/env node
import { createReadStream } from "node:fs";
[... 10 lines ...]

$ printf "a\nb\nc\nd\ne\n" | pnpm exec head-js -n 2
a
b

Stretch goals

• Add a -c <BYTES> flag for bytes mode (UTF-8 boundary safe — read bytes, then decode the prefix and trim to last valid char).
• Add a --quiet flag that suppresses headers in multi-file mode. Match BSD head semantics.
• Publish to npm under your username scope: npm publish --access public. Verify a teammate can pnpm install -g @you/head-js and run it.
• Add benchmark mode: read a 1 GB file, time head -n 100. Compare to system head. Should be within 2× — if not, you're not streaming.