{"_id":"osc-progress","_rev":"3-366f95b1cc2e0d570532a9b207a2a63d","name":"osc-progress","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"osc-progress","version":"0.1.0","keywords":["osc","terminal","progress","cli","ghostty","wezterm","windows-terminal"],"author":{"name":"Peter Steinberger"},"license":"MIT","_id":"osc-progress@0.1.0","maintainers":[{"name":"steipete","email":"steipete@gmail.com"}],"homepage":"https://github.com/steipete/osc-progress#readme","bugs":{"url":"https://github.com/steipete/osc-progress/issues"},"dist":{"shasum":"1eb358e00381a7a07bcbf2aa4edd2b147fb5e69d","tarball":"https://registry.npmjs.org/osc-progress/-/osc-progress-0.1.0.tgz","fileCount":10,"integrity":"sha512-9HrEuN+6C/ZsbLI58ZVIOMMfk3K9y1wEf7v1KA9eiChfWoe/HCOVJrRdPhP815tY/CB4wt5snJMfFMEBPZDhng==","signatures":[{"sig":"MEQCIE8j5OGoa81b2tn7/Ki7FnFGowgabVF2/fRoWK91YsrHAiBOa5mTzU2hRloFVSKWWjNWKMKKxWBiEz5xe56kMyCELA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23926},"main":"./dist/esm/index.js","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js"}},"gitHead":"b4589770622a3a037c99c0ef58792808593a28b6","scripts":{"lint":"biome check .","test":"pnpm build && vitest run","build":"tsc -p tsconfig.build.json","check":"pnpm lint && pnpm test:coverage","format":"biome format --write .","prepack":"pnpm build","prepare":"pnpm build","lint:fix":"biome check --write .","typecheck":"tsc -p tsconfig.build.json --noEmit","test:coverage":"pnpm build && vitest run --coverage","prepublishOnly":"pnpm check"},"_npmUser":{"name":"steipete","email":"steipete@gmail.com"},"repository":{"url":"git+https://github.com/steipete/osc-progress.git","type":"git"},"_npmVersion":"11.6.2","description":"Tiny TypeScript helper for OSC 9;4 terminal progress sequences.","directories":{},"sideEffects":false,"_nodeVersion":"25.2.1","_hasShrinkwrap":false,"packageManager":"pnpm@10.25.0","devDependencies":{"vitest":"^4.0.16","typescript":"^5.9.3","@types/node":"^25.0.3","@biomejs/biome":"^2.3.10","@vitest/coverage-v8":"^4.0.16"},"_npmOperationalInternal":{"tmp":"tmp/osc-progress_0.1.0_1766149227919_0.5070711198522255","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"osc-progress","version":"0.2.0","keywords":["osc","terminal","progress","cli","ghostty","wezterm","windows-terminal"],"author":{"name":"Peter Steinberger"},"license":"MIT","_id":"osc-progress@0.2.0","maintainers":[{"name":"steipete","email":"steipete@gmail.com"}],"homepage":"https://github.com/steipete/osc-progress#readme","bugs":{"url":"https://github.com/steipete/osc-progress/issues"},"dist":{"shasum":"e66dd094fc44e782a0f15aa269eda2fc7d98fb30","tarball":"https://registry.npmjs.org/osc-progress/-/osc-progress-0.2.0.tgz","fileCount":10,"integrity":"sha512-GJR9XnS8dQ+sAdbhX90RA4WbmEyrso7X9aHMws4MaQ2GRpfEjnOUSZIdOXJQfnIfBoy9oCc7US/MNFCyuJQzjg==","signatures":[{"sig":"MEUCIQC7J9D6gzkggFsTbOWzUSIJ3naIKsF8JJ8/pceRr9L89wIgDsmTeZbdIezOa89E2X51/sjj7a6/iKhzBi+UnZlfBWc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29965},"main":"./dist/esm/index.js","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js"}},"gitHead":"44bd742691cda9a11c08bcd27ec69aaf4576e850","scripts":{"lint":"biome check .","test":"pnpm build && vitest run","build":"tsc -p tsconfig.build.json","check":"pnpm lint && pnpm test:coverage","format":"biome format --write .","prepack":"pnpm build","prepare":"pnpm build","lint:fix":"biome check --write .","typecheck":"tsc -p tsconfig.build.json --noEmit","test:coverage":"pnpm build && vitest run --coverage","prepublishOnly":"pnpm check"},"_npmUser":{"name":"steipete","email":"steipete@gmail.com"},"repository":{"url":"git+https://github.com/steipete/osc-progress.git","type":"git"},"_npmVersion":"11.6.2","description":"Tiny TypeScript helper for OSC 9;4 terminal progress sequences.","directories":{},"sideEffects":false,"_nodeVersion":"25.2.1","_hasShrinkwrap":false,"packageManager":"pnpm@10.25.0","devDependencies":{"vitest":"^4.0.16","typescript":"^5.9.3","@types/node":"^25.0.3","@biomejs/biome":"^2.3.10","@vitest/coverage-v8":"^4.0.16"},"_npmOperationalInternal":{"tmp":"tmp/osc-progress_0.2.0_1766626571659_0.028077726545152393","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"osc-progress","version":"0.3.0","description":"Tiny TypeScript helper for OSC 9;4 terminal progress sequences.","license":"MIT","author":{"name":"Peter Steinberger"},"repository":{"type":"git","url":"git+https://github.com/steipete/osc-progress.git"},"homepage":"https://github.com/steipete/osc-progress#readme","bugs":{"url":"https://github.com/steipete/osc-progress/issues"},"keywords":["osc","terminal","progress","cli","ghostty","wezterm","windows-terminal"],"type":"module","main":"./dist/esm/index.js","module":"./dist/esm/index.js","types":"./dist/types/index.d.ts","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js"}},"engines":{"node":">=20"},"sideEffects":false,"devDependencies":{"@biomejs/biome":"^2.3.10","@types/node":"^25.0.3","@vitest/coverage-v8":"^4.0.16","typescript":"^5.9.3","vitest":"^4.0.16"},"scripts":{"build":"tsc -p tsconfig.build.json","typecheck":"tsc -p tsconfig.build.json --noEmit","format":"biome format --write .","lint":"biome check .","lint:fix":"biome check --write .","test":"pnpm build && vitest run","test:coverage":"pnpm build && vitest run --coverage","check":"pnpm lint && pnpm test:coverage"},"_id":"osc-progress@0.3.0","_integrity":"sha512-4/8JfsetakdeEa4vAYV45FW20aY+B/+K8NEXp5Eiar3wR8726whgHrbSg5Ar/ZY1FLJ/AGtUqV7W2IVF+Gvp9A==","_resolved":"/private/var/folders/qp/t4t5pw1n1279_1qckf4gqhyc0000gn/T/1b412a2beff4d4708debd83453ff4eed/osc-progress-0.3.0.tgz","_from":"file:osc-progress-0.3.0.tgz","_nodeVersion":"25.3.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-4/8JfsetakdeEa4vAYV45FW20aY+B/+K8NEXp5Eiar3wR8726whgHrbSg5Ar/ZY1FLJ/AGtUqV7W2IVF+Gvp9A==","shasum":"449d9d7b346c8ea2a7838841103b98d23f5c6a06","tarball":"https://registry.npmjs.org/osc-progress/-/osc-progress-0.3.0.tgz","fileCount":10,"unpackedSize":41163,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB/39CZwdRiw4TTHYVGGq7h3gcPE+0qGG53/l0f00GnFAiEA/sTjwfzGKZpzDFTSSU/jA4icveE5m9QTxzBQqcNlNlg="}]},"_npmUser":{"name":"steipete","email":"steipete@gmail.com"},"directories":{},"maintainers":[{"name":"steipete","email":"steipete@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/osc-progress_0.3.0_1768891732017_0.1679489791530162"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-19T13:00:27.918Z","modified":"2026-01-20T06:48:52.355Z","0.1.0":"2025-12-19T13:00:28.055Z","0.2.0":"2025-12-25T01:36:11.810Z","0.3.0":"2026-01-20T06:48:52.227Z"},"bugs":{"url":"https://github.com/steipete/osc-progress/issues"},"author":{"name":"Peter Steinberger"},"license":"MIT","homepage":"https://github.com/steipete/osc-progress#readme","keywords":["osc","terminal","progress","cli","ghostty","wezterm","windows-terminal"],"repository":{"type":"git","url":"git+https://github.com/steipete/osc-progress.git"},"description":"Tiny TypeScript helper for OSC 9;4 terminal progress sequences.","maintainers":[{"name":"steipete","email":"steipete@gmail.com"}],"readme":"# ⏳ osc-progress — Tiny lib for OSC 9;4 terminal progress.\n\nTiny TypeScript helper for **OSC 9;4** terminal progress (Ghostty / WezTerm / Windows Terminal).\n\n## Install\n\n```bash\npnpm add osc-progress\n```\n\n## Usage\n\n```ts\nimport process from 'node:process'\nimport { startOscProgress } from 'osc-progress'\n\nconst stop = startOscProgress({\n  label: 'Fetching',\n  write: (chunk) => process.stderr.write(chunk),\n  env: process.env,\n  isTty: process.stderr.isTTY,\n})\n\n// ...do work...\n\nstop()\n```\n\nIndeterminate (spinner-like) mode:\n\n```ts\nimport { startOscProgress } from 'osc-progress'\n\nconst stop = startOscProgress({ label: 'Waiting', indeterminate: true })\n// ...\nstop()\n```\n\nStrip OSC progress from stored logs:\n\n```ts\nimport { sanitizeOscProgress } from 'osc-progress'\n\nconst clean = sanitizeOscProgress(text, /*keepOsc*/ process.stdout.isTTY)\n```\n\n## API\n\n### `supportsOscProgress(env?, isTty?, options?)`\n\nReturns `true` when emitting OSC 9;4 progress makes sense.\n\nHeuristics:\n- requires a TTY\n- enables for `TERM_PROGRAM=ghostty*`, `TERM_PROGRAM=wezterm*`, or `WT_SESSION` (Windows Terminal)\n\nOptional overrides:\n- `options.disabled` / `options.force`\n- `options.disableEnvVar` / `options.forceEnvVar` (expects `= \"1\"`)\n\n### `startOscProgress(options?)`\n\nStarts a best-effort progress indicator and returns `stop(): void`.\n\nNotes:\n- `label` is appended as extra payload; **not part of the canonical OSC 9;4 spec** (many terminals ignore it, some show it).\n- default is a timer-driven `0% → 99%` progression (never completes by itself).\n- `terminator` defaults to `st` (`ESC \\\\`); `bel` is also supported.\n\n### `createOscProgressController(options?)`\n\nReturns a small stateful controller:\n- `setIndeterminate(label)`\n- `setPercent(label, percent)`\n- `setPaused(label)` (state `4`)\n- `done(label?)` (emit 100% then clear)\n- `fail(label?)` (emit error state then clear)\n- `clear()`\n- `dispose()` (cleanup timers/listeners)\n\nUse this when you already have real progress (bytes/total, seconds/total) and want determinate terminal progress instead of the timer-based ramp.\n\nNotes:\n- returns no-op methods when `supportsOscProgress(...)` is false\n- `percent` is rounded and clamped to `0..100`\n- `clear()` uses the last label (or the initial `options.label` if nothing was set yet)\n- progress updates are throttled by default (deduped + max ~1 update/150ms)\n- `stallAfterMs` emits a paused/stalled state when updates stop\n- `clearDelayMs` controls how long `done()` / `fail()` wait before clearing\n- `autoClearOnExit` clears on process exit\n\n```ts\nimport process from 'node:process'\nimport { createOscProgressController } from 'osc-progress'\n\nconst osc = createOscProgressController({\n  env: process.env,\n  isTty: process.stderr.isTTY,\n  write: (chunk) => process.stderr.write(chunk),\n  stallAfterMs: 10_000,\n  clearDelayMs: 200,\n  autoClearOnExit: true,\n})\n\nosc.setIndeterminate('Connecting')\nosc.setPercent('Downloading', 12)\nosc.setPercent('Downloading', 67)\nosc.done()\n```\n\n#### Controller options\n\n- `stallAfterMs`: emit state=4 when no updates are seen within this window.\n- `stalledLabel`: override stalled label (string or formatter).\n- `clearDelayMs`: delay before `done()`/`fail()` clears.\n- `autoClearOnExit`: clear progress on process exit.\n\n### `sanitizeOscProgress(text, keepOsc)`\n\nRemoves OSC 9;4 progress sequences (terminated by `BEL`, `ST` (`ESC \\\\`), or `0x9c`).\n\n## Semantics / portability\n\nOSC 9;4 is widely implemented, but state `4` is ambiguous across terminals (some treat it as `paused`, some as `warning`).\nThis library exposes the raw numeric state and does not try to reinterpret it.\n","readmeFilename":"README.md"}