@figliolia/chalk-animation 1.0.0 → 1.0.2

package/dist/mjs/ChalkAnimation.js

@@ -1,26 +1,29 @@
 import { Effects } from "./Effects";
 import { Animation } from "./Animation";
-import { animateString } from "./animateString";
+/**
+ * Chalk Animation
+ *
+ * Console animations for your CLI tools
+ *
+ * ```typescript
+ * const animation = ChalkAnimation.rainbow("hello!");
+ * animation.stop();
+ * animation.start();
+ * ```
+ */
 export class ChalkAnimation {
-    static rainbow(str, speed = 1) {
-        return animateString(Effects.rainbow, str, 15, speed);
-    }
-    static pulse(str, speed = 1) {
-        return animateString(Effects.pulse, str, 16, speed);
-    }
-    static glitch(str, speed = 1) {
-        return animateString(Effects.glitch, str, 55, speed);
-    }
-    static radar(str, speed = 1) {
-        return animateString(Effects.radar, str, 50, speed);
-    }
-    static neon(str, speed = 1) {
-        return animateString(Effects.neon, str, 500, speed);
-    }
-    static karaoke(str, speed = 1) {
-        return animateString(Effects.karaoke, str, 50, speed);
-    }
-    static clearAllAnimations() {
-        return Animation.clearAll();
+    static neon = this.configure("neon", 500);
+    static radar = this.configure("radar", 50);
+    static pulse = this.configure("pulse", 16);
+    static glitch = this.configure("glitch", 55);
+    static rainbow = this.configure("rainbow", 15);
+    static karaoke = this.configure("karaoke", 50);
+    static configure(effect, delay) {
+        return (str, 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/dist/mjs/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/Decor.js

@@ -0,0 +1,14 @@
+export class Decor {
+    static bound(target, _propertyKey, descriptor) {
+        const operation = descriptor.value;
+        if (operation) {
+            descriptor.value = operation.bind(target);
+        }
+    }
+    static chainable(instance, func) {
+        return (...params) => {
+            func(...params);
+            return instance;
+        };
+    }
+}

package/dist/mjs/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/mjs/Effects.js

@@ -1,5 +1,12 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
 import chalk from "chalk";
 import gradient from "gradient-string";
+import { Decor } from "./Decor";
 export class Effects {
     static longHsv = { interpolation: "hsv", hsvSpin: "long" };
     static glitchChars = "x*0987654321[]0-~@#(____!!!!\\|?????....0000\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t";
@@ -7,7 +14,7 @@ export class Effects {
         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);
     }
     static pulse(str, frame) {
         frame = (frame % 120) + 1;
@@ -52,7 +59,7 @@ export class Effects {
             i += skip;
             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)]);
+                    chunks.push(this.glitchChars[Math.floor(Math.random() * this.glitchChars.length)]);
                 }
                 else if (Math.random() > 0.005) {
                     chunks.push(str[i]);
@@ -100,3 +107,21 @@ export class Effects {
             chalk.white(str.substr(chars)));
     }
 }
+__decorate([
+    Decor.bound
+], Effects, "rainbow", null);
+__decorate([
+    Decor.bound
+], Effects, "pulse", null);
+__decorate([
+    Decor.bound
+], Effects, "glitch", null);
+__decorate([
+    Decor.bound
+], Effects, "radar", null);
+__decorate([
+    Decor.bound
+], Effects, "neon", null);
+__decorate([
+    Decor.bound
+], Effects, "karaoke", null);

package/dist/mjs/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/FrameRate.js

@@ -0,0 +1,24 @@
+import { InstanceTracker } from "./InstanceTracker";
+export class FrameRate extends InstanceTracker {
+    current = 0;
+    speed;
+    delay;
+    controller = null;
+    constructor(delay, speed) {
+        super();
+        this.delay = delay;
+        this.speed = speed;
+    }
+    schedule(func) {
+        this.controller = setTimeout(func, this.delay / this.speed);
+    }
+    increment() {
+        this.current++;
+    }
+    clearFrames() {
+        if (this.controller) {
+            clearTimeout(this.controller);
+            this.controller = null;
+        }
+    }
+}

package/dist/mjs/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/mjs/InstanceTracker.js

@@ -4,14 +4,14 @@ export class InstanceTracker {
     static LOG = console.log;
     static IDs = new AutoIncrementingID();
     static bucket = new Map();
+    static loggers = ["log", "warn", "info", "error"];
     constructor() {
         InstanceTracker.clearAll();
         this.ID = InstanceTracker.IDs.get();
         InstanceTracker.bucket.set(this.ID, this.instance);
     }
     static {
-        const methods = ["log", "warn", "info", "error"];
-        methods.forEach((method) => {
+        this.loggers.forEach(method => {
             const original = console[method];
             console[method] = function (...args) {
                 InstanceTracker.clearAll();

package/dist/mjs/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/mjs/types.d.ts

@@ -1 +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.0",
+  "version": "1.0.2",
   "description": "An ESM/Common.js compatible typescript port of the popular 'chalk-animation' library",
   "keywords": [
     "animation",

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";

package/src/types.ts

@@ -1 +1,15 @@
 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/dist/cjs/animateString.d.ts

@@ -1,2 +0,0 @@
-import { Animation } from "./Animation";
-export declare function animateString(effect: any, str: string, delay?: number, speed?: number): Animation;