@figliolia/chalk-animation 1.0.1 → 1.0.3

package/dist/mjs/__tests__/ChalkAnimation.test.js

@@ -0,0 +1,93 @@
+import { ChalkAnimation } from "../ChalkAnimation.js";
+import { Effects } from "../Effects.js";
+import { InstanceTracker } from "../InstanceTracker.js";
+const animations = [
+    "rainbow",
+    "pulse",
+    "glitch",
+    "radar",
+    "neon",
+    "karaoke",
+];
+describe("Chalk Animation", () => {
+    afterAll(() => {
+        jest.restoreAllMocks();
+    });
+    describe("Spawn", () => {
+        beforeAll(() => {
+            jest.spyOn(InstanceTracker, "LOG").mockImplementation(() => { });
+        });
+        afterEach(() => {
+            InstanceTracker.clearAll();
+            InstanceTracker.IDs.reset();
+        });
+        animations.forEach(name => {
+            it(`ChalkAnimation.${name} - returns an initialized animation instance`, () => {
+                const animation = ChalkAnimation[name]("hello");
+                expect(animation.effect).toEqual(Effects[name]);
+                expect(typeof animation.ID).toEqual("string");
+                expect(animation.text).toEqual(["hello"]);
+                expect(animation.lines).toEqual(1);
+                expect(animation.speed).toEqual(1);
+                expect(animation.current).toEqual(1);
+                expect(animation.initialized).toEqual(true);
+                expect(animation.stopped).toEqual(false);
+                expect(animation.controller).not.toEqual(null);
+                expect(InstanceTracker.bucket.size).toEqual(1);
+                animation.stop();
+                expect(animation.stopped).toEqual(true);
+                expect(animation.controller).toEqual(null);
+            });
+            InstanceTracker.loggers.forEach(method => {
+                it(`ChalkAnimation.${name} - subsequent console.${method} stop the animation`, () => {
+                    const animation = ChalkAnimation[name]("hello");
+                    expect(animation.stopped).toEqual(false);
+                    console[method]("");
+                    expect(animation.stopped).toEqual(true);
+                });
+            });
+            it(`ChalkAnimation.${name} - can be stopped and restarted`, () => {
+                const animation = ChalkAnimation[name]("hello");
+                animation.stop();
+                expect(animation.stopped).toEqual(true);
+                animation.start();
+                expect(animation.current).toEqual(2);
+            });
+            it(`ChalkAnimation.${name} - can be manually rendered at a desired frame rate`, () => {
+                const animation = ChalkAnimation[name]("hello").stop();
+                expect(animation.current).toEqual(1);
+                animation.render();
+                expect(animation.current).toEqual(2);
+                animation.render();
+                expect(animation.current).toEqual(3);
+            });
+            it(`ChalkAnimation.${name} - text can be replaced`, () => {
+                if (name === "radar") {
+                    return;
+                }
+                const animation = ChalkAnimation[name]("Y Y Y").stop();
+                const f1 = animation.nextFrame();
+                animation.replace("Z Z Z");
+                const f2 = animation.nextFrame();
+                expect(f1.includes("Y")).toEqual(true);
+                expect(f1.includes("Z")).toEqual(false);
+                expect(f2.includes("Y")).toEqual(false);
+                expect(f2.includes("Z")).toEqual(true);
+            });
+            it(`ChalkAnimation.${name} - supports multiline strings`, () => {
+                const animation = ChalkAnimation[name]("Lorem\nipsum\ndolor\nsit\namet").stop();
+                const frame = animation.nextFrame();
+                expect(animation.lines).toEqual(5);
+                expect(frame.split("\n")).toHaveLength(5);
+            });
+            it(`ChalkAnimation.${name} - supports 5K+ frames`, () => {
+                const animation = ChalkAnimation[name]("Lorem\nipsum\ndolor\nsit\namet").stop();
+                for (let i = 0; i < 5000; i++) {
+                    expect(() => {
+                        animation.nextFrame();
+                    }).not.toThrow();
+                }
+            });
+        });
+    });
+});

package/dist/mjs/index.js

@@ -1,2 +1,2 @@
-export { ChalkAnimation } from "./ChalkAnimation";
-export * from "./types";
+export { ChalkAnimation } from "./ChalkAnimation.js";
+export * from "./types.js";

package/dist/mjs/package.json

@@ -1,3 +1,4 @@
 {
-    "type": "module"
-}
+  "type": "module",
+  "exports": "./index.js"
+}

package/dist/types/Animation.d.ts

@@ -0,0 +1,16 @@
+import type { AnimationFN } from "./types";
+import { FrameRate } from "./FrameRate";
+export declare class Animation extends FrameRate {
+    lines: number;
+    text: string[];
+    stopped: boolean;
+    initialized: boolean;
+    effect: AnimationFN;
+    static readonly LINE_BREAKS: RegExp;
+    constructor(effect: AnimationFN, str: string, delay?: number, speed?: number);
+    render(): void;
+    nextFrame(): string;
+    readonly replace: (str: string) => this;
+    readonly stop: () => this;
+    readonly start: () => this;
+}

package/dist/types/ChalkAnimation.d.ts

@@ -0,0 +1,21 @@
+import { Animation } from "./Animation";
+/**
+ * Chalk Animation
+ *
+ * Console animations for your CLI tools
+ *
+ * ```typescript
+ * const animation = ChalkAnimation.rainbow("hello!");
+ * animation.stop();
+ * animation.start();
+ * ```
+ */
+export declare class ChalkAnimation {
+    static readonly neon: (str: string, speed?: number) => Animation;
+    static readonly radar: (str: string, speed?: number) => Animation;
+    static readonly pulse: (str: string, speed?: number) => Animation;
+    static readonly glitch: (str: string, speed?: number) => Animation;
+    static readonly rainbow: (str: string, speed?: number) => Animation;
+    static readonly karaoke: (str: string, speed?: number) => Animation;
+    private static configure;
+}

package/dist/types/Decor.d.ts

@@ -0,0 +1,5 @@
+import type { MethodKeys, MethodLike } from "./types";
+export declare class Decor {
+    static bound<T, K extends MethodKeys<T>>(target: T, _propertyKey: K, descriptor: TypedPropertyDescriptor<MethodLike>): void;
+    static chainable<I, F extends (...args: any[]) => any>(instance: I, func: F): (...params: Parameters<F>) => I;
+}

package/dist/{mjs → types}/Effects.d.ts

@@ -1,9 +1,9 @@
 export declare class Effects {
-    static longHsv: {
+    static readonly longHsv: {
         interpolation: string;
         hsvSpin: string;
     };
-    static glitchChars: string;
+    static readonly glitchChars = "x*0987654321[]0-~@#(____!!!!\\|?????....0000\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t";
     static rainbow(str: string, frame: number): string;
     static pulse(str: string, frame: number): string;
     static glitch(str: string, frame: number): string;

package/dist/types/FrameRate.d.ts

@@ -0,0 +1,11 @@
+import { InstanceTracker } from "./InstanceTracker";
+export declare class FrameRate extends InstanceTracker {
+    current: number;
+    speed: number;
+    delay: number;
+    controller: ReturnType<typeof setTimeout> | null;
+    constructor(delay: number, speed: number);
+    schedule<F extends () => any>(func: F): void;
+    increment(): void;
+    clearFrames(): void;
+}

package/dist/{mjs → types}/InstanceTracker.d.ts

@@ -8,6 +8,7 @@ export declare class InstanceTracker {
     };
     static IDs: AutoIncrementingID;
     static bucket: Map<string, Animation>;
+    static loggers: readonly ["log", "warn", "info", "error"];
     constructor();
     get instance(): Animation;
     static clearAll(): void;

package/dist/types/__tests__/ChalkAnimation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/{cjs → types}/index.d.ts

@@ -1,4 +1,5 @@
 export { ChalkAnimation } from "./ChalkAnimation";
+export type { Effects } from "./Effects";
 export type { Animation } from "./Animation";
 export type { InstanceTracker } from "./InstanceTracker";
 export * from "./types";

package/dist/types/types.d.ts

@@ -0,0 +1,6 @@
+export type AnimationFN = (str: string, frame: number) => string;
+export type AnimationName = "rainbow" | "pulse" | "glitch" | "radar" | "neon" | "karaoke";
+export type MethodLike<T = any> = (...args: any[]) => T;
+export type MethodKeys<T, R = any> = keyof {
+    [K in keyof T as Required<T>[K] extends MethodLike<R> ? K : never]: T[K];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figliolia/chalk-animation",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "An ESM/Common.js compatible typescript port of the popular 'chalk-animation' library",
   "keywords": [
     "animation",
@@ -30,23 +30,21 @@
   "exports": {
     ".": {
       "import": "./dist/mjs/index.js",
-      "require": "./dist/cjs/index.js"
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
     }
   },
   "main": "dist/cjs/index.js",
   "module": "dist/mjs/index.js",
-  "types": "dist/mjs/index.d.ts",
+  "types": "dist/types/index.d.ts",
   "bin": "./cli.js",
   "files": [
     "dist",
     "src/*"
   ],
   "scripts": {
-    "build": "rm -rf dist && yarn build-esm && yarn build-cjs && yarn package-targets",
-    "build-cjs": "tsc -p cd/tsconfig.cjs.json",
-    "build-esm": "tsc -p cd/tsconfig.mjs.json",
+    "build": "npx ts-packager -e src",
     "lint": "tsc --noemit && eslint ./ --fix",
-    "package-targets": "cd/package.sh",
     "test": "jest"
   },
   "dependencies": {
@@ -55,6 +53,7 @@
     "gradient-string": "^2.0.2"
   },
   "devDependencies": {
+    "@figliolia/ts-packager": "^1.0.3",
     "@swc/core": "^1.3.99",
     "@types/gradient-string": "^1.1.5",
     "@types/jest": "^29.5.10",
@@ -81,4 +80,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/Animation.ts

@@ -1,22 +1,18 @@
 import type { AnimationFN } from "./types";
-import { InstanceTracker } from "./InstanceTracker";
+import { FrameRate } from "./FrameRate";
+import { Decor } from "./Decor";
 
-export class Animation extends InstanceTracker {
-  effect: any;
+export class Animation extends FrameRate {
   lines: number;
-  speed: number;
-  delay: number;
   text: string[];
   stopped = false;
-  currentFrame = 0;
   initialized = false;
-  controller: ReturnType<typeof setTimeout> | null = null;
+  effect: AnimationFN;
+  static readonly LINE_BREAKS = /\r\n|\r|\n/;
   constructor(effect: AnimationFN, str: string, delay = 0, speed = 0) {
-    super();
+    super(delay, speed);
     this.effect = effect;
-    this.speed = speed;
-    this.delay = delay;
-    this.text = str.split(/\r\n|\r|\n/);
+    this.text = str.split(Animation.LINE_BREAKS);
     this.lines = this.text.length;
   }
 
@@ -25,47 +21,37 @@ export class Animation extends InstanceTracker {
       Animation.LOG("\n".repeat(this.lines - 1));
       this.initialized = true;
     }
-    Animation.LOG(this.frame());
-    this.controller = setTimeout(() => {
+    Animation.LOG(this.nextFrame());
+    this.schedule(() => {
       if (!this.stopped) {
         this.render();
       }
-    }, this.delay / this.speed);
+    });
   }
 
-  public frame() {
-    this.currentFrame++;
+  public nextFrame() {
+    this.increment();
     return (
       "\u001B[" +
       `${this.lines}` +
       "F\u001B[G\u001B[2K" +
-      this.text.map((str) => this.effect(str, this.currentFrame)).join("\n")
+      this.text.map(str => this.effect(str, this.current)).join("\n")
     );
   }
 
-  public replace(str: string) {
-    this.text = str.split(/\r\n|\r|\n/);
+  public readonly replace = Decor.chainable(this, (str: string) => {
+    this.text = str.split(Animation.LINE_BREAKS);
     this.lines = this.text.length;
-    return this;
-  }
+  });
 
-  public stop() {
+  public readonly stop = Decor.chainable(this, () => {
     this.clearFrames();
     this.stopped = true;
-    return this;
-  }
+  });
 
-  public start() {
+  public readonly start = Decor.chainable(this, () => {
     this.clearFrames();
     this.stopped = false;
     this.render();
-    return this;
-  }
-
-  private clearFrames() {
-    if (this.controller) {
-      clearTimeout(this.controller);
-      this.controller = null;
-    }
-  }
+  });
 }

package/src/ChalkAnimation.ts

@@ -1,33 +1,32 @@
 import { Effects } from "./Effects";
 import { Animation } from "./Animation";
-import { animateString } from "./animateString";
+import type { AnimationName } from "./types";
 
+/**
+ * Chalk Animation
+ *
+ * Console animations for your CLI tools
+ *
+ * ```typescript
+ * const animation = ChalkAnimation.rainbow("hello!");
+ * animation.stop();
+ * animation.start();
+ * ```
+ */
 export class ChalkAnimation {
-  public static rainbow(str: string, speed = 1) {
-    return animateString(Effects.rainbow, str, 15, speed);
-  }
-
-  public static pulse(str: string, speed = 1) {
-    return animateString(Effects.pulse, str, 16, speed);
-  }
-
-  public static glitch(str: string, speed = 1) {
-    return animateString(Effects.glitch, str, 55, speed);
-  }
-
-  public static radar(str: string, speed = 1) {
-    return animateString(Effects.radar, str, 50, speed);
-  }
-
-  public static neon(str: string, speed = 1) {
-    return animateString(Effects.neon, str, 500, speed);
-  }
-
-  public static karaoke(str: string, speed = 1) {
-    return animateString(Effects.karaoke, str, 50, speed);
-  }
+  public static readonly neon = this.configure("neon", 500);
+  public static readonly radar = this.configure("radar", 50);
+  public static readonly pulse = this.configure("pulse", 16);
+  public static readonly glitch = this.configure("glitch", 55);
+  public static readonly rainbow = this.configure("rainbow", 15);
+  public static readonly karaoke = this.configure("karaoke", 50);
 
-  public static clearAllAnimations() {
-    return Animation.clearAll();
+  private static configure(effect: AnimationName, delay: number) {
+    return (str: string, speed = 1) => {
+      if (!speed || speed <= 0) {
+        throw new Error("Expected `speed` to be an number greater than 0");
+      }
+      return new Animation(Effects[effect], str, delay, speed).start();
+    };
   }
 }

package/src/Decor.ts

@@ -0,0 +1,24 @@
+import type { MethodKeys, MethodLike } from "./types";
+
+export class Decor {
+  public static bound<T, K extends MethodKeys<T>>(
+    target: T,
+    _propertyKey: K,
+    descriptor: TypedPropertyDescriptor<MethodLike>,
+  ) {
+    const operation = descriptor.value;
+    if (operation) {
+      descriptor.value = operation.bind(target);
+    }
+  }
+
+  public static chainable<I, F extends (...args: any[]) => any>(
+    instance: I,
+    func: F,
+  ) {
+    return (...params: Parameters<F>): I => {
+      func(...params);
+      return instance;
+    };
+  }
+}

package/src/Effects.ts

@@ -1,17 +1,21 @@
 import chalk from "chalk";
 import gradient from "gradient-string";
+import { Decor } from "./Decor";
 
 export class Effects {
-  public static longHsv = { interpolation: "hsv", hsvSpin: "long" };
-  public static glitchChars =
+  public static readonly longHsv = { interpolation: "hsv", hsvSpin: "long" };
+  public static readonly glitchChars =
     "x*0987654321[]0-~@#(____!!!!\\|?????....0000\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t";
+
+  @Decor.bound
   public static rainbow(str: string, frame: number) {
     const hue = 5 * frame;
     const leftColor = { h: hue % 360, s: 1, v: 1 };
     const rightColor = { h: (hue + 1) % 360, s: 1, v: 1 };
-    return gradient(leftColor, rightColor)(str, Effects.longHsv);
+    return gradient(leftColor, rightColor)(str, this.longHsv);
   }
 
+  @Decor.bound
   public static pulse(str: string, frame: number) {
     frame = (frame % 120) + 1;
     const transition = 6;
@@ -48,6 +52,7 @@ export class Effects {
     return g(str);
   }
 
+  @Decor.bound
   public static glitch(str: string, frame: number) {
     if (
       (frame % 2) + (frame % 3) + (frame % 11) + (frame % 29) + (frame % 37) >
@@ -66,9 +71,9 @@ export class Effects {
       if (str[i]) {
         if (str[i] !== "\n" && str[i] !== "\r" && Math.random() > 0.995) {
           chunks.push(
-            Effects.glitchChars[
-              Math.floor(Math.random() * Effects.glitchChars.length)
-            ]
+            this.glitchChars[
+              Math.floor(Math.random() * this.glitchChars.length)
+            ],
           );
         } else if (Math.random() > 0.005) {
           chunks.push(str[i]);
@@ -86,6 +91,7 @@ export class Effects {
     return result;
   }
 
+  @Decor.bound
   public static radar(str: string, frame: number) {
     const depth = Math.floor(Math.min(str.length, str.length * 0.2));
     const step = Math.floor(255 / depth);
@@ -106,6 +112,7 @@ export class Effects {
     return chars.join("");
   }
 
+  @Decor.bound
   public static neon(str: string, frame: number) {
     const color =
       frame % 2 === 0
@@ -114,6 +121,7 @@ export class Effects {
     return color(str);
   }
 
+  @Decor.bound
   public static karaoke(str: string, frame: number) {
     const chars = (frame % (str.length + 20)) - 10;
     if (chars < 0) {

package/src/FrameRate.ts

@@ -0,0 +1,28 @@
+import { InstanceTracker } from "./InstanceTracker";
+
+export class FrameRate extends InstanceTracker {
+  current = 0;
+  speed: number;
+  delay: number;
+  controller: ReturnType<typeof setTimeout> | null = null;
+  constructor(delay: number, speed: number) {
+    super();
+    this.delay = delay;
+    this.speed = speed;
+  }
+
+  public schedule<F extends () => any>(func: F) {
+    this.controller = setTimeout(func, this.delay / this.speed);
+  }
+
+  public increment() {
+    this.current++;
+  }
+
+  public clearFrames() {
+    if (this.controller) {
+      clearTimeout(this.controller);
+      this.controller = null;
+    }
+  }
+}

package/src/InstanceTracker.ts

@@ -6,6 +6,7 @@ export class InstanceTracker {
   static readonly LOG = console.log;
   static IDs = new AutoIncrementingID();
   static bucket = new Map<string, Animation>();
+  static loggers = ["log", "warn", "info", "error"] as const;
   constructor() {
     InstanceTracker.clearAll();
     this.ID = InstanceTracker.IDs.get();
@@ -13,10 +14,11 @@ export class InstanceTracker {
   }
 
   static {
-    const methods = ["log", "warn", "info", "error"] as const;
-    methods.forEach((method) => {
+    this.loggers.forEach(method => {
       const original = console[method];
-      console[method] = function (...args: Parameters<typeof console.log>) {
+      console[method] = function (
+        ...args: Parameters<(typeof console)[typeof method]>
+      ) {
         InstanceTracker.clearAll();
         return original.apply(console, args);
       };

package/src/__tests__/ChalkAnimation.test.ts

@@ -0,0 +1,108 @@
+import { ChalkAnimation } from "../ChalkAnimation";
+import { Effects } from "../Effects";
+import { InstanceTracker } from "../InstanceTracker";
+
+const animations = [
+  "rainbow",
+  "pulse",
+  "glitch",
+  "radar",
+  "neon",
+  "karaoke",
+] as const;
+
+describe("Chalk Animation", () => {
+  afterAll(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe("Spawn", () => {
+    beforeAll(() => {
+      jest.spyOn(InstanceTracker, "LOG").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      InstanceTracker.clearAll();
+      InstanceTracker.IDs.reset();
+    });
+
+    animations.forEach(name => {
+      it(`ChalkAnimation.${name} - returns an initialized animation instance`, () => {
+        const animation = ChalkAnimation[name]("hello");
+        expect(animation.effect).toEqual(Effects[name]);
+        expect(typeof animation.ID).toEqual("string");
+        expect(animation.text).toEqual(["hello"]);
+        expect(animation.lines).toEqual(1);
+        expect(animation.speed).toEqual(1);
+        expect(animation.current).toEqual(1);
+        expect(animation.initialized).toEqual(true);
+        expect(animation.stopped).toEqual(false);
+        expect(animation.controller).not.toEqual(null);
+        expect(InstanceTracker.bucket.size).toEqual(1);
+        animation.stop();
+        expect(animation.stopped).toEqual(true);
+        expect(animation.controller).toEqual(null);
+      });
+
+      InstanceTracker.loggers.forEach(method => {
+        it(`ChalkAnimation.${name} - subsequent console.${method} stop the animation`, () => {
+          const animation = ChalkAnimation[name]("hello");
+          expect(animation.stopped).toEqual(false);
+          console[method]("");
+          expect(animation.stopped).toEqual(true);
+        });
+      });
+
+      it(`ChalkAnimation.${name} - can be stopped and restarted`, () => {
+        const animation = ChalkAnimation[name]("hello");
+        animation.stop();
+        expect(animation.stopped).toEqual(true);
+        animation.start();
+        expect(animation.current).toEqual(2);
+      });
+
+      it(`ChalkAnimation.${name} - can be manually rendered at a desired frame rate`, () => {
+        const animation = ChalkAnimation[name]("hello").stop();
+        expect(animation.current).toEqual(1);
+        animation.render();
+        expect(animation.current).toEqual(2);
+        animation.render();
+        expect(animation.current).toEqual(3);
+      });
+
+      it(`ChalkAnimation.${name} - text can be replaced`, () => {
+        if (name === "radar") {
+          return;
+        }
+        const animation = ChalkAnimation[name]("Y Y Y").stop();
+        const f1 = animation.nextFrame();
+        animation.replace("Z Z Z");
+        const f2 = animation.nextFrame();
+        expect(f1.includes("Y")).toEqual(true);
+        expect(f1.includes("Z")).toEqual(false);
+        expect(f2.includes("Y")).toEqual(false);
+        expect(f2.includes("Z")).toEqual(true);
+      });
+
+      it(`ChalkAnimation.${name} - supports multiline strings`, () => {
+        const animation = ChalkAnimation[name](
+          "Lorem\nipsum\ndolor\nsit\namet",
+        ).stop();
+        const frame = animation.nextFrame();
+        expect(animation.lines).toEqual(5);
+        expect(frame.split("\n")).toHaveLength(5);
+      });
+
+      it(`ChalkAnimation.${name} - supports 5K+ frames`, () => {
+        const animation = ChalkAnimation[name](
+          "Lorem\nipsum\ndolor\nsit\namet",
+        ).stop();
+        for (let i = 0; i < 5000; i++) {
+          expect(() => {
+            animation.nextFrame();
+          }).not.toThrow();
+        }
+      });
+    });
+  });
+});

package/src/index.ts

@@ -1,4 +1,5 @@
 export { ChalkAnimation } from "./ChalkAnimation";
+export type { Effects } from "./Effects";
 export type { Animation } from "./Animation";
 export type { InstanceTracker } from "./InstanceTracker";
 export * from "./types";