{"_id":"@backendkit-labs/console-animations","_rev":"2-2bd071a6ecf17ce9e8ad1f6c0126e414","name":"@backendkit-labs/console-animations","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.2":{"name":"@backendkit-labs/console-animations","version":"0.1.2","keywords":["terminal","animation","cli","loader","spinner","progress","console"],"author":{"name":"Mairon José Cuello Martínez","email":"[backendkit.dev@gmail.com - mmairon@gmail.com]"},"license":"MIT","_id":"@backendkit-labs/console-animations@0.1.2","maintainers":[{"name":"backendkit.dev","email":"backendkit.dev@gmail.com"}],"homepage":"https://github.com/backendkit-dev/backendkit-monorepo/tree/master/packages/console-animations#readme","bugs":{"url":"https://github.com/backendkit-dev/backendkit-monorepo/issues"},"bin":{"console-animations":"dist/bin/demo.js"},"dist":{"shasum":"2eb324ce5f020e1c29e31642f29ed2e4048b5411","tarball":"https://registry.npmjs.org/@backendkit-labs/console-animations/-/console-animations-0.1.2.tgz","fileCount":9,"integrity":"sha512-P4WdizL6aQwYS20tqQCbBkxpdNuT01zCyVmSbFfsjLmImLGpX8P7C4zukDXUdKptREyh9a9q9+xJs+QLBPt6PA==","signatures":[{"sig":"MEUCIEjIN3UkO+KKifT/9V0JeA10qtbbb/6PCN+Xnrchm0bOAiEAw6jULqSWpm05jUnkbyPrI1vIzNoS+dhUNz75S7Kiibs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":236475},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"1d35632d677d1c5435701f2c29d00e1813aca84b","scripts":{"dev":"tsup --watch","lint":"eslint src/","test":"vitest run","build":"tsup","format":"prettier --write src/","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build && npm run test && npm run lint"},"_npmUser":{"name":"backendkit.dev","email":"backendkit.dev@gmail.com"},"repository":{"url":"git+https://github.com/backendkit-dev/backendkit-monorepo.git","type":"git","directory":"packages/console-animations"},"_npmVersion":"11.8.0","description":"Enterprise-grade terminal animations library for Node.js CLI applications","directories":{},"sideEffects":false,"_nodeVersion":"22.16.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.0.0","vitest":"^2.0.0","prettier":"^3.0.0","@eslint/js":"^9.39.4","typescript":"^5.5.0","@types/node":"^22.19.19","typescript-eslint":"^8.59.3"},"_npmOperationalInternal":{"tmp":"tmp/console-animations_0.1.2_1778619859783_0.9017728740356372","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@backendkit-labs/console-animations","version":"0.1.3","license":"Apache-2.0","author":{"name":"BackendKit Labs","email":"backendkit.dev@gmail.com"},"description":"Enterprise-grade terminal animations library for Node.js CLI applications","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"bin":{"console-animations":"dist/bin/demo.js"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","lint":"eslint src/","format":"prettier --write src/","prepublishOnly":"npm run build && npm run test && npm run lint"},"keywords":["terminal","animation","cli","loader","spinner","progress","console"],"homepage":"https://github.com/backendkit-dev/backendkit-monorepo/tree/master/packages/console-animations#readme","repository":{"type":"git","url":"git+https://github.com/backendkit-dev/backendkit-monorepo.git","directory":"packages/console-animations"},"bugs":{"url":"https://github.com/backendkit-dev/backendkit-monorepo/issues"},"publishConfig":{"access":"public"},"sideEffects":false,"engines":{"node":">=18"},"devDependencies":{"@eslint/js":"^9.39.4","@types/node":"^22.19.19","eslint":"^9.0.0","prettier":"^3.0.0","tsup":"^8.0.0","typescript":"^5.5.0","typescript-eslint":"^8.59.3","vitest":"^2.0.0"},"gitHead":"f6769720db5a99cfb74b9d2c46a99b3b648b86aa","_id":"@backendkit-labs/console-animations@0.1.3","_nodeVersion":"22.16.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-IAC5ctrH3xabcONJL+JBgfVxflVt1vIW+n/pEPczr/g/QsipHJUAA/qU86o4El1VdZID/SG20XqEr0okwwgpUg==","shasum":"2e72b388fd3e962cb32c1bd1e2db2c5a78e3312f","tarball":"https://registry.npmjs.org/@backendkit-labs/console-animations/-/console-animations-0.1.3.tgz","fileCount":10,"unpackedSize":247226,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD8gVT7r5Xyq1IDVS41oUuKqKiEqMVfFFLYSnQhwxWaFQIgYjkw1dxMn1rCf0/J/Rq69qTKmgoy3Jg5DeyVJy12g6o="}]},"_npmUser":{"name":"backendkit.dev","email":"backendkit.dev@gmail.com"},"directories":{},"maintainers":[{"name":"backendkit.dev","email":"backendkit.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/console-animations_0.1.3_1778797132980_0.8744784839910722"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-12T21:04:19.646Z","modified":"2026-05-14T22:18:53.270Z","0.1.2":"2026-05-12T21:04:19.925Z","0.1.3":"2026-05-14T22:18:53.128Z"},"bugs":{"url":"https://github.com/backendkit-dev/backendkit-monorepo/issues"},"author":{"name":"BackendKit Labs","email":"backendkit.dev@gmail.com"},"license":"Apache-2.0","homepage":"https://github.com/backendkit-dev/backendkit-monorepo/tree/master/packages/console-animations#readme","keywords":["terminal","animation","cli","loader","spinner","progress","console"],"repository":{"type":"git","url":"git+https://github.com/backendkit-dev/backendkit-monorepo.git","directory":"packages/console-animations"},"description":"Enterprise-grade terminal animations library for Node.js CLI applications","maintainers":[{"name":"backendkit.dev","email":"backendkit.dev@gmail.com"}],"readme":"# @backendkit-labs/console-animations\r\n\r\n[![npm version](https://img.shields.io/npm/v/@backendkit-labs/console-animations?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@backendkit-labs/console-animations)\r\n[![CI](https://img.shields.io/github/actions/workflow/status/backendkit-dev/backendkit-monorepo/ci.yml?style=flat-square&label=CI)](https://github.com/backendkit-dev/backendkit-monorepo/actions/workflows/ci.yml)\r\n[![License](https://img.shields.io/npm/l/@backendkit-labs/console-animations?style=flat-square)](LICENSE)\r\n[![Node](https://img.shields.io/node/v/@backendkit-labs/console-animations?style=flat-square)](package.json)\r\n[![Downloads](https://img.shields.io/npm/dm/@backendkit-labs/console-animations?style=flat-square)](https://www.npmjs.com/package/@backendkit-labs/console-animations)\r\n\r\n> Enterprise-grade terminal animations for Node.js CLI applications and backend processes.\r\n\r\n**17 built-in animations** — spinners, progress bars, loaders and visual effects — with terminal states (`succeed` / `fail` / `warn`), dynamic text updates, CI detection, and zero runtime dependencies.\r\n\r\n```bash\r\n# Try it instantly\r\nnpx @backendkit-labs/console-animations\r\n```\r\n\r\n---\r\n\r\n## Animations Preview\r\n\r\n### Spinners & Loaders\r\n\r\n| Animation | Type | Frames | Use case |\r\n|-----------|------|--------|----------|\r\n| **Spinner** | `SPINNER` | `⠋` `⠙` `⠹` `⠸` `⠼` `⠴` `⠦` `⠧` `⠇` `⠏` | Tasks, installs, fetching |\r\n| **Dots** | `DOTS` | `⣾` `⣽` `⣻` `⢿` `⡿` `⣟` `⣯` `⣷` | Waiting, processing |\r\n| **Pulse** | `PULSE` | `·` `◌` `○` `◎` `●` `◎` `○` `◌` | Heartbeat, status check |\r\n| **Worm** | `WORM` | `[●─────────]` `[────●─────]` `[─────────●]` | Indeterminate progress |\r\n| **Snake** | `SNAKE` | `●·········` `·····●····` `·········●` | Scanning, searching |\r\n| **Bouncing Ball** | `BOUNCING_BALL` | `[◉           ]` `[      ◉     ]` `[           ◉]` | Loading, buffering |\r\n\r\n### Progress & Fill\r\n\r\n| Animation | Type | Frames | Use case |\r\n|-----------|------|--------|----------|\r\n| **Progress Bar** | `PROGRESS_BAR` | `[████████░░░░] 67% \\| ETA: 4s` | File download, build steps |\r\n| **Cyberpunk** | `CYBERPUNK` | `▰▱▱▱▱▱▱▱▱▱` `▰▰▰▰▰▱▱▱▱▱` `▰▰▰▰▰▰▰▰▰▰` | Deploy, upload, sync |\r\n\r\n### Text & Typing\r\n\r\n| Animation | Type | Frames | Use case |\r\n|-----------|------|--------|----------|\r\n| **Typing** | `TYPING` | `D█` `De█` `Dep█` `Deploy█` | Command output, logs |\r\n\r\n### Visual Effects\r\n\r\n| Animation | Type | Frames | Use case |\r\n|-----------|------|--------|----------|\r\n| **Waves** | `WAVES` | `▁▂▃▄▅▆▇█▇▆▅▄▃▂` `▂▃▄▅▆▇█▇▆▅▄▃▂▁` | Audio, processing |\r\n| **Matrix** | `MATRIX` | `ｦｱｶｺｻｼｽｾｿ` `ｲｳｴｵﾀﾁﾂﾃﾄ` | Data stream, encryption |\r\n| **Hacker** | `HACKER` | `[FF] A3  2B  7C` `[A3] 7C  FF  2B` | Hex scan, network |\r\n| **Rain** | `RAIN` | `╷│╵` pattern | Ambient, idle state |\r\n| **Fire** | `FIRE` | `   ▲   ` `  ▲▲▲  ` `▲▲▲█▲▲▲` | Alerts, hot paths |\r\n| **Stars** | `STARS` | `✦  ✧  ✦  ✧` `✧  ✦  ✧  ✦` | Success, decorative |\r\n| **Particles** | `PARTICLES` | `·   ·   ·` `  · · ·  ` `   ···   ` | Ambient |\r\n| **Futurista** | `FUTURISTA` | `◆  ◇  ◆` `◇  ◆  ◇` `◈  ◇  ◈` | Sci-fi, startup |\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @backendkit-labs/console-animations\r\n```\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport { AnimationManager, AnimationType } from '@backendkit-labs/console-animations';\r\n\r\nconst manager = new AnimationManager();\r\n\r\nconst spinner = manager.start({\r\n  type: AnimationType.SPINNER,\r\n  color: 'cyan',\r\n  prefix: '  Installing packages ',\r\n});\r\n\r\nsetTimeout(() => {\r\n  manager.succeed(spinner.id, 'Packages installed');\r\n}, 3000);\r\n```\r\n\r\n---\r\n\r\n## Terminal States\r\n\r\nStop animations with a visible result — the most important feature for professional CLIs:\r\n\r\n```typescript\r\nmanager.succeed(id, 'Build complete')   // ✔ Build complete   (green)\r\nmanager.fail(id, 'Build failed')        // ✖ Build failed     (red)\r\nmanager.warn(id, 'Skipped 3 files')     // ⚠ Skipped 3 files  (yellow)\r\nmanager.info(id, 'Cache hit')           // ℹ Cache hit        (cyan)\r\n```\r\n\r\nWorks in CI too — animations are silent in non-TTY environments, only the final state is printed.\r\n\r\n---\r\n\r\n## Presets\r\n\r\nReady-to-use configurations for the most common backend and CLI scenarios:\r\n\r\n```typescript\r\nimport { AnimationManager, Presets } from '@backendkit-labs/console-animations';\r\n\r\nconst manager = new AnimationManager();\r\n\r\n// One-liner for common tasks\r\nconst s = manager.start(Presets.install('Installing dependencies'));\r\nconst b = manager.start(Presets.build('Compiling TypeScript'));\r\nconst d = manager.start(Presets.deploy('Deploying to production'));\r\nconst c = manager.start(Presets.connect('Connecting to database'));\r\n\r\n// With auto succeed/fail via run()\r\nconst result = await manager.run(\r\n  Presets.build('Building'),\r\n  () => runWebpack(),\r\n);\r\n```\r\n\r\n| Preset | Animation | Color | Use case |\r\n|--------|-----------|-------|----------|\r\n| `Presets.install(text?)` | `SPINNER` | cyan | npm/package installs |\r\n| `Presets.build(text?)` | `DOTS` | yellow | Compilation, bundling |\r\n| `Presets.deploy(text?)` | `WORM` | magenta | Deployments |\r\n| `Presets.connect(text?)` | `PULSE` | blue | DB / network connections |\r\n| `Presets.migrate(text?)` | `SNAKE` | yellow | DB migrations |\r\n| `Presets.download(text?, total?)` | `PROGRESS_BAR` | cyan | Downloads with ETA |\r\n| `Presets.upload(text?, total?)` | `CYBERPUNK` | green | Uploads |\r\n| `Presets.encrypt(text?)` | `HACKER` | greenBright | Encryption / hashing |\r\n| `Presets.scan(text?)` | `MATRIX` | green | Security scans |\r\n| `Presets.stream(text?)` | `WAVES` | cyan | Data streaming |\r\n\r\n---\r\n\r\n## Progress Bar with ETA\r\n\r\n```typescript\r\nconst bar = manager.start(Presets.download('Downloading package', 100));\r\n\r\n// Drive progress externally — ETA is calculated automatically\r\nbar.setProgress(30);  // [████████░░░░░░░░░░░░░░░░░░░░░░]  30% | ETA: 7s\r\nbar.setProgress(60);  // [████████████████░░░░░░░░░░░░░░]  60% | ETA: 3s\r\nbar.setProgress(100); // [██████████████████████████████] 100% | 1.2s\r\n\r\nmanager.succeed(bar.id, 'Download complete');\r\n```\r\n\r\n---\r\n\r\n## Dynamic Updates\r\n\r\nChange text or config while an animation is running:\r\n\r\n```typescript\r\nconst s = manager.start(Presets.install('Resolving packages'));\r\n\r\n// Update prefix mid-flight\r\nmanager.update(s.id, { prefix: '  Downloading packages ' });\r\nmanager.update(s.id, { prefix: '  Linking dependencies ' });\r\n\r\nmanager.succeed(s.id, 'Installation complete');\r\n```\r\n\r\n---\r\n\r\n## Async Workflow with Auto-stop\r\n\r\n```typescript\r\n// run() automatically calls succeed() on resolve, fail() on reject\r\nconst result = await manager.run(\r\n  Presets.deploy('Deploying to production'),\r\n  () => deployToProduction(),\r\n  {\r\n    successText: 'Deployed successfully',\r\n    failText: 'Deployment failed',\r\n  },\r\n);\r\n```\r\n\r\n---\r\n\r\n## CI / Non-TTY Detection\r\n\r\nAnimations are automatically disabled in non-interactive environments (CI, piped output). Only terminal states are printed:\r\n\r\n```\r\n# In a terminal (interactive)\r\n⠙ Building TypeScript...   ← animated\r\n\r\n# In GitHub Actions / CI\r\n✔ Building TypeScript       ← only final state, no animation noise\r\n```\r\n\r\nNo configuration needed — detection is automatic via `process.stdout.isTTY` and `process.env.CI`.\r\n\r\n---\r\n\r\n## API Reference\r\n\r\n### AnimationManager\r\n\r\n| Method | Signature | Description |\r\n|--------|-----------|-------------|\r\n| `start` | `(config) → IAnimation` | Creates and starts an animation |\r\n| `stop` | `(id) → void` | Stops silently |\r\n| `succeed` | `(id, text?) → void` | Stops with ✔ (green) |\r\n| `fail` | `(id, text?) → void` | Stops with ✖ (red) |\r\n| `warn` | `(id, text?) → void` | Stops with ⚠ (yellow) |\r\n| `info` | `(id, text?) → void` | Stops with ℹ (cyan) |\r\n| `update` | `(id, partial) → void` | Updates config while running |\r\n| `pause` | `(id) → void` | Freezes current frame |\r\n| `resume` | `(id) → void` | Resumes a paused animation |\r\n| `destroy` | `(id) → void` | Stops and releases resources |\r\n| `destroyAll` | `() → void` | Destroys all active animations |\r\n| `get` | `(id) → IAnimation \\| undefined` | Gets animation by ID |\r\n| `getAll` | `() → IAnimation[]` | Returns all active animations |\r\n| `getByType` | `(type) → IAnimation[]` | Filters by type |\r\n| `run<T>` | `(config, task, opts?) → Promise<T>` | Wraps async task with auto-stop |\r\n\r\n### AnimationBuilder\r\n\r\nFluent API for composing configs:\r\n\r\n```typescript\r\nimport { AnimationBuilder, AnimationType } from '@backendkit-labs/console-animations';\r\n\r\nconst config = new AnimationBuilder()\r\n  .setType(AnimationType.WORM)\r\n  .setColor('magenta')\r\n  .setSpeed(60)\r\n  .setPrefix('  Migrating database ')\r\n  .build();\r\n\r\nconst anim = manager.start(config);\r\n```\r\n\r\n### AnimationConfig\r\n\r\n| Property | Type | Default | Description |\r\n|----------|------|---------|-------------|\r\n| `type` | `AnimationType` | required | Animation type |\r\n| `id` | `string` | auto | Unique animation ID |\r\n| `text` | `string` | `''` | Text for typing animation |\r\n| `color` | `Color` | `undefined` | ANSI color |\r\n| `speed` | `number` | `80` | ms between frames |\r\n| `prefix` | `string` | `''` | Text before the animation |\r\n| `suffix` | `string` | `''` | Text after the animation |\r\n| `overwrite` | `boolean` | `true` | Overwrite current line |\r\n| `multiline` | `boolean` | `false` | Multi-line frame |\r\n| `frames` | `string[]` | `undefined` | Custom frame array |\r\n| `width` | `number` | `20` | Progress bar width |\r\n| `total` | `number` | `100` | Progress bar total steps |\r\n| `showEta` | `boolean` | `false` | Show ETA on progress bar |\r\n| `custom` | `Record<string, unknown>` | `undefined` | Extra data for custom animations |\r\n\r\n### Colors\r\n\r\n`black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray` `grey`\r\n`redBright` `greenBright` `yellowBright` `blueBright` `magentaBright` `cyanBright` `whiteBright`\r\n\r\n### Events\r\n\r\n```typescript\r\nmanager.on(AnimationEvent.START,        (data) => { /* animation started */ });\r\nmanager.on(AnimationEvent.STOP,         (data) => { /* animation stopped */ });\r\nmanager.on(AnimationEvent.STATE_CHANGE, (data) => { /* state transition  */ });\r\nmanager.on(AnimationEvent.FRAME,        (data) => { /* new frame rendered */ });\r\nmanager.on(AnimationEvent.ERROR,        (data) => { /* error occurred     */ });\r\n```\r\n\r\n---\r\n\r\n## Custom Animations\r\n\r\n```typescript\r\nimport { AbstractAnimation, AnimationConfig } from '@backendkit-labs/console-animations';\r\n\r\nclass MyAnimation extends AbstractAnimation {\r\n  constructor(config: AnimationConfig) {\r\n    super(config);\r\n  }\r\n\r\n  protected buildFrames(): string[] {\r\n    return ['◐', '◓', '◑', '◒'];\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n```\r\nAnimationManager (Facade)\r\n  ├── AnimationFactory    — creates animations by type\r\n  ├── AnimationRegistry   — ID → IAnimation map\r\n  ├── FrameScheduler      — adaptive loop, min 16 ms\r\n  ├── RenderEngine        — stdout writer + ANSI + CI detection\r\n  └── EventEmitter        — observer pattern\r\n\r\nAbstractAnimation (Template Method)\r\n  └── 17 concrete animations\r\n\r\nAnimationBuilder   — fluent config builder\r\nPresets            — ready-to-use configs for common tasks\r\nterminal / symbols — environment detection utilities\r\n```\r\n\r\n---\r\n\r\n## Running Examples\r\n\r\n```bash\r\ngit clone https://github.com/backendkit-dev/backendkit-monorepo.git\r\ncd backendkit-monorepo/packages/console-animations\r\nnpm install && npm run build\r\n\r\nnpx tsx examples/basic-usage.ts\r\nnpx tsx examples/multi-animation.ts\r\nnpx tsx examples/custom-animation.ts\r\nnpx tsx examples/async-workflow.ts\r\n```\r\n\r\n---\r\n\r\n## License\r\n\r\nApache-2.0 — [BackendKit Labs](https://github.com/backendkit-dev)\r\n","readmeFilename":"README.md"}