@caperjs/core 0.1.0

package/src/utils/map.ts

@@ -0,0 +1,59 @@
+/**
+ * Returns the map entry that comes before the entry with the provided key.
+ * If the provided key is the first entry in the map or doesn't exist in the map, the function returns undefined.
+ * @param {Map<K, V>} map The map to search in.
+ * @param {any} currentKey The key of the map entry that comes after the desired entry.
+ * @returns {[K, V] | undefined} The map entry that comes before the entry with the provided key, or undefined if such an entry doesn't exist.
+ */
+export function getPreviousMapEntry<K = any, V = any>(map: Map<K, V>, currentKey: any): [K, V] | undefined {
+  let previous: [any, any] | undefined;
+
+  for (const entry of map) {
+    if (entry[0] === currentKey) {
+      return previous;
+    }
+    previous = entry;
+  }
+  return undefined;
+}
+
+/**
+ * Returns the map entry that comes after the entry with the provided key.
+ * If the provided key is the first entry in the map or doesn't exist in the map, the function returns undefined.
+ * @param {Map<K, V>} map The map to search in.
+ * @param {any} currentKey The key of the map entry that comes after the desired entry.
+ * @returns {[K, V] | undefined} The map entry that comes before the entry with the provided key, or undefined if such an entry doesn't exist.
+ */
+export function getNextMapEntry<K = any, V = any>(map: Map<K, V>, currentKey: any): [K, V] | undefined {
+  let next: [any, any] | undefined;
+  // go in reverse
+  const entries = Array.from(map.entries());
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry[0] === currentKey) {
+      return next;
+    }
+    next = entry;
+  }
+  return undefined;
+}
+
+/**
+ * Returns the last entry in the provided map.
+ * If the map is empty, the function returns undefined.
+ * @param {Map<K, V>} map The map to get the last entry from.
+ * @returns {[K, V] | undefined} The last entry in the map, or undefined if the map is empty.
+ */
+export function getLastMapEntry<K = any, V = any>(map: Map<K, V>): [K, V] | undefined {
+  return Array.from(map.entries()).pop() as [K, V];
+}
+
+/**
+ * Returns the first entry in the provided map.
+ * If the map is empty, the function returns undefined.
+ * @param {Map<K, V>} map The map to get the last entry from.
+ * @returns {[K, V] | undefined} The last entry in the map, or undefined if the map is empty.
+ */
+export function getFirstMapEntry<K = any, V = any>(map: Map<K, V>): [K, V] | undefined {
+  return Array.from(map.entries()).shift() as [K, V];
+}

package/src/utils/math.ts

@@ -0,0 +1,19 @@
+/**
+ * Clamp a number
+ * @param pValue
+ * @param pMin
+ * @param pMax
+ */
+export function clamp(pValue: number, pMin: number, pMax: number): number {
+  return Math.max(pMin, Math.min(pMax, pValue));
+}
+
+/**
+ * lerp
+ * @param pMin
+ * @param pMax
+ * @param pPerc
+ */
+export function lerp(pMin: number, pMax: number, pPerc: number): number {
+  return pMin + (pMax - pMin) * pPerc;
+}

package/src/utils/misc.ts

@@ -0,0 +1,45 @@
+import { Point } from 'pixi.js';
+import type { Size, SizeLike } from './types';
+
+export function resolveSizeLike(size?: SizeLike): Size {
+  if (size === undefined) {
+    return { width: 0, height: 0 };
+  }
+  if (Array.isArray(size)) {
+    return { width: size[0], height: size[1] === undefined ? size[0] : size[1] };
+  } else if (size instanceof Point) {
+    return { width: size.x, height: size.y };
+  } else if (typeof size === 'object') {
+    // cast as an object
+    const obj = size as { width: number; height: number };
+    return { width: obj.width || 0, height: obj.height || 0 };
+  } else {
+    return { width: size ?? 0, height: size ?? 0 };
+  }
+}
+
+type DebouncedFunction<T extends (...args: any[]) => any> = (...args: Parameters<T>) => void;
+
+/**
+ * Debounce a function
+ * @param func - function to debounce
+ * @param wait - time in milliseconds
+ * @example const debounced = debounce(() => console.log('debounced'), 1000);
+ * @example window.addEventListener('resize', debounced);
+ */
+export function debounce<T extends (...args: any[]) => any>(func: T, wait: number): DebouncedFunction<T> {
+  let timeoutId: NodeJS.Timeout | null = null;
+
+  return function (this: any, ...args: Parameters<T>) {
+    // Clear existing timeout if any
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    // Set new timeout
+    timeoutId = setTimeout(() => {
+      func.apply(this, args);
+      timeoutId = null;
+    }, wait);
+  };
+}

package/src/utils/number.ts

@@ -0,0 +1,3 @@
+export function getZeroPaddedNumber(num: number, zeroPad: number = 0): string {
+  return num.toString().padStart(zeroPad, '0');
+}

package/src/utils/object.ts

@@ -0,0 +1,43 @@
+import { DeepPartial } from './types';
+
+/**
+ * Plucks the specified keys from an object and returns a new object with only those keys.
+ * @template T The type of the original object.
+ * @template K The keys to pluck from the original object.
+ * @param {T} obj The original object.
+ * @param {K[]} keys The keys to pluck from the original object.
+ * @returns {Pick<T, K>} A new object with only the plucked keys.
+ */
+export function pluck<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
+  return keys.reduce((acc, key) => (key in obj ? { ...acc, [key]: obj[key] } : acc), {} as Pick<T, K>);
+}
+
+/**
+ * Omits the specified keys from an object and returns a new object without those keys.
+ * @template T The type of the original object.
+ * @template K The keys to omit from the original object.
+ * @param {K[]} keysToOmit The keys to omit from the original object.
+ * @param {Partial<T>} obj The original object.
+ * @returns {Omit<T, K>} A new object without the omitted keys.
+ */
+export function omitKeys<T extends object, K extends keyof T>(keysToOmit: K[], obj: Partial<T>): Omit<T, K> {
+  return Object.entries(obj)
+    .filter(([key]) => !keysToOmit.includes(key as K))
+    .reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {} as Omit<T, K>);
+}
+
+export function deepMerge<T extends Record<string, any>>(target: T, source: DeepPartial<T>): T {
+  for (const key in source) {
+    if (
+      source[key] !== undefined &&
+      Object.prototype.toString.call(source[key]) === '[object Object]' &&
+      key in target &&
+      typeof target[key] === 'object'
+    ) {
+      target[key] = deepMerge(target[key], source[key] as T[Extract<keyof T, string>]);
+    } else if (source[key] !== undefined) {
+      target[key] = source[key] as T[Extract<keyof T, string>];
+    }
+  }
+  return target;
+}

package/src/utils/padding.ts

@@ -0,0 +1,43 @@
+import type { Padding, PointLike } from './types';
+
+export function resolvePadding(paddingNum: number, size: number) {
+  // check of the paddingNum is a decimal between 0 and 1
+  // if it is, return a number that is the percentage of the size
+  if (paddingNum >= 0 && paddingNum <= 1) {
+    return paddingNum * size;
+  }
+  return paddingNum;
+}
+
+export function ensurePadding(padding: Partial<Padding> | PointLike): Padding {
+  if (Array.isArray(padding)) {
+    return {
+      top: padding[0],
+      right: padding?.[1] ?? padding[0],
+      bottom: padding?.[2] ?? padding[0],
+      left: padding?.[3] ?? padding?.[1] ?? padding[0] ?? 0,
+    };
+  }
+  if (typeof padding === 'number') {
+    return { top: padding, right: padding, bottom: padding, left: padding };
+  } else if (typeof padding === 'object') {
+    const paddingAsPointLike = padding as { x?: number; y?: number };
+    if (paddingAsPointLike.x !== undefined && paddingAsPointLike.y !== undefined) {
+      return {
+        top: paddingAsPointLike.y,
+        right: paddingAsPointLike.x,
+        bottom: paddingAsPointLike.y,
+        left: paddingAsPointLike.x,
+      };
+    } else {
+      return {
+        top: (padding as Padding).top ?? 0,
+        right: (padding as Padding).right ?? 0,
+        bottom: (padding as Padding).bottom ?? 0,
+        left: (padding as Padding).left ?? 0,
+      };
+    }
+  } else {
+    return { top: 0, right: 0, bottom: 0, left: 0 };
+  }
+}

package/src/utils/pixi.ts

@@ -0,0 +1,116 @@
+import { Circle, Container, ContainerChild, Ellipse, Point, Polygon, Rectangle, RoundedRectangle } from 'pixi.js';
+import { PointLike, Size } from './types';
+import { resolvePointLike } from './point';
+
+export type PixiSimpleShape = Rectangle | Circle | Ellipse | RoundedRectangle;
+export type PixiShape = PixiSimpleShape | Polygon;
+
+/**
+ * Reassigns the displays object parent while maintaing it's world position
+ * @param pChild
+ * @param pParent
+ */
+export function reParent(pChild: ContainerChild, pParent: Container): void {
+  if (pChild.parent) {
+    pChild.parent.worldTransform.apply(pChild.position as Point, pChild.position as Point);
+  }
+  pParent.worldTransform.applyInverse(pChild.position as Point, pChild.position as Point);
+  pChild.parent?.removeChild(pChild);
+  pParent.addChild(pChild);
+}
+
+/**
+ *
+ * @param pObject
+ */
+export function objectDiagonal(pObject: Container): number {
+  return Math.sqrt(pObject.width * pObject.width + pObject.height * pObject.height);
+}
+
+/**
+ * Removes provided object from its parent and re-adds it.
+ * @param pObject The object to send to the back.
+ */
+export function sendToFront(pObject: Container): void {
+  const parent = pObject.parent;
+  if (!parent) return;
+  parent.removeChild(pObject);
+  parent.addChild(pObject);
+}
+
+/**
+ * Removes provided object from its parent and re-adds it at index 0.
+ * @param pObject The object to send to the back.
+ */
+export function sendToBack(pObject: Container): void {
+  const parent = pObject.parent;
+  if (!parent) return;
+  parent.removeChild(pObject);
+  parent.addChildAt(pObject, 0);
+}
+
+/**
+ *
+ * @param pShape
+ * @param pDelta
+ */
+export function offsetShape(pShape: PixiShape, pDelta: Point): PixiShape {
+  if (pShape instanceof Polygon) {
+    for (let i = 0; i < pShape.points.length; i += 2) {
+      pShape.points[i] += pDelta.x;
+      pShape.points[i + 1] += pDelta.y;
+    }
+    return pShape;
+  } else {
+    pShape.x += pDelta.x;
+    pShape.y += pDelta.y;
+    return pShape;
+  }
+}
+
+/**
+ *
+ * @param pShape
+ * @param pDelta
+ */
+export function offsetSimpleShape(pShape: PixiSimpleShape, pDelta: Point): PixiSimpleShape {
+  pShape.x += pDelta.x;
+  pShape.y += pDelta.y;
+  return pShape;
+}
+
+export function scaleUniform(obj: any, scaleNum: number, scaleProp: 'width' | 'height' = 'width') {
+  const scaleVal: 'x' | 'y' = scaleProp === 'width' ? 'y' : 'x';
+  const otherScaleVal: 'x' | 'y' = scaleProp === 'width' ? 'x' : 'y';
+  obj[scaleProp] = scaleNum;
+  obj.scale[scaleVal] = obj.scale[otherScaleVal];
+}
+
+export function scaleToWidth(obj: Container, width: number) {
+  scaleUniform(obj, width, 'width');
+}
+
+export function scaleToHeight(obj: Container, height: number) {
+  scaleUniform(obj, height, 'height');
+}
+
+export function scaleToSize(obj: Container, size: PointLike | Size, firstProp: 'width' | 'height' = 'width') {
+  let resolvedSize;
+  if ((size as Size)?.width && (size as Size)?.height) {
+    resolvedSize = { x: (size as Size).width, y: (size as Size).height };
+  } else {
+    resolvedSize = resolvePointLike(size as PointLike);
+  }
+
+  if (firstProp === 'width') {
+    scaleToWidth(obj, resolvedSize.x);
+    if (obj.height < resolvedSize.y) {
+      scaleToHeight(obj, resolvedSize.y);
+    }
+  } else {
+    scaleToHeight(obj, resolvedSize.y);
+    if (obj.width < resolvedSize.x) {
+      scaleToWidth(obj, resolvedSize.x);
+    }
+  }
+}

package/src/utils/platform.ts

@@ -0,0 +1,33 @@
+import { isMobile as PIXIUtilsIsMobile } from 'pixi.js';
+
+/**
+ * Checks if the device has a retina display.
+ * A device is considered to have a retina display if its device pixel ratio is greater than 1,
+ * or if it matches the media query for high resolution displays.
+ * @type {boolean}
+ */
+export const isRetina =
+  typeof window !== 'undefined'
+    ? window.devicePixelRatio > 1 ||
+      (window.matchMedia &&
+        window.matchMedia(
+          '(-webkit-min-device-pixel-ratio: 1.5), (min--moz-device-pixel-ratio: 1.5), (-o-min-device-pixel-ratio: 3/2), (min-resolution: 1.5dppx)',
+        ).matches)
+    : false;
+
+/**
+ * Check if we're on a touch device
+ */
+export const isTouch: boolean =
+  typeof window !== 'undefined'
+    ? 'ontouchstart' in window || navigator.maxTouchPoints > 0 || navigator?.maxTouchPoints > 0
+    : false;
+
+/**
+ * Checks if the device is a mobile device.
+ * This uses the `isMobile` function from the `@pixi/utils` package.
+ * @type {boolean}
+ */
+export const isMobile = PIXIUtilsIsMobile.any;
+export const isAndroid = PIXIUtilsIsMobile.android.device;
+export const isIos = PIXIUtilsIsMobile.apple.device;

package/src/utils/point.ts

@@ -0,0 +1,123 @@
+import { Point, PointLike } from 'pixi.js';
+import { lerp } from './math';
+import { PointLike as CaperPointLike } from './types';
+
+/**
+ * Add the x and the y values of two Points together and return a new point.
+ * @returns Point
+ * @param a
+ * @param b
+ */
+export function add(a: PointLike, b: PointLike): Point {
+  return new Point(a.x + b.x, a.y + b.y);
+}
+
+/**
+ * Increase the x,y of point A by the x,y of point B.
+ * @param a
+ * @param b
+ */
+export function addToPoint(a: PointLike, b: PointLike): void {
+  a.x += b.x;
+  a.y += b.y;
+}
+
+/**
+ * Subtract the x and the y values of point B from Point A and return a new point.
+ * @param a
+ * @param b
+ */
+export function subtract(a: PointLike, b: PointLike): Point {
+  return new Point(a.x - b.x, a.y - b.y);
+}
+
+/**
+ * Decrease the x,y of point A by the x,y of point B.
+ * @param a
+ * @param b
+ */
+export function subtractFromPoint(a: PointLike, b: PointLike): void {
+  a.x -= b.x;
+  a.y -= b.y;
+}
+
+/**
+ * Multply the x,y values of a point by the provided value.
+ * @param a
+ * @param pMult
+ */
+export function multiply(a: PointLike, pMult: number): Point {
+  const point: Point = new Point(a.x, a.y);
+  point.x *= pMult;
+  point.y *= pMult;
+  return point;
+}
+
+/**
+ *
+ * @param pt
+ * @param percent
+ */
+export function lerpPoint(pt: PointLike, percent: number): number {
+  return lerp(pt.x, pt.y, percent);
+}
+
+/**
+ * Get the distance between two points.
+ * @param a
+ * @param b
+ */
+export function distance(a: PointLike, b: Point): number {
+  return Math.sqrt(distanceSq(a, b));
+}
+
+/**
+ * Get the squared distance between two points.
+ * @param a
+ * @param b
+ */
+export function distanceSq(a: PointLike, b: Point): number {
+  return (b.x - a.x) * (b.x - a.x) + (b.y - a.y) * (b.y - a.y);
+}
+
+/**
+ * Gets the magnitude of a point.
+ * @param pt
+ */
+export function magnitude(pt: PointLike): number {
+  return Math.sqrt(pt.x * pt.x + pt.y * pt.y);
+}
+
+export type PointLikeResult = { x: number; y: number } | Point;
+
+export function resolvePointLike(
+  position?: CaperPointLike,
+  asPoint?: false,
+  x?: number,
+  y?: number,
+): { x: number; y: number };
+export function resolvePointLike(position?: CaperPointLike, asPoint?: true, x?: number, y?: number): Point;
+export function resolvePointLike(
+  position?: CaperPointLike,
+  asPoint: boolean = false,
+  x: number = 0,
+  y: number = 0,
+): PointLikeResult {
+  if (position instanceof Point) {
+    x = position.x;
+    y = position.y;
+  } else if (Array.isArray(position)) {
+    x = position[0];
+    y = position[1] === undefined ? position[0] : position[1];
+  } else if (typeof position === 'object') {
+    // cast as an object
+    const obj = position as { x: number; y: number };
+    x = obj.x || 0;
+    y = obj.y || 0;
+  } else {
+    x = position ?? x;
+    y = position ?? y;
+  }
+
+  return asPoint ? new Point(x, y) : { x, y };
+}

package/src/utils/promise/Queue.ts

@@ -0,0 +1,125 @@
+import { triggerViteError } from '../vite';
+
+/**
+ * Creates a new Queue with the given promises.
+ * @param {...(Promise<any> | (() => Promise<any | void>))[]} promises The promises to add to the queue.
+ * @returns {Queue} The created Queue.
+ */
+export function createQueue(...promises: (Promise<any> | (() => Promise<any | void>))[]): Queue {
+  return new Queue(promises);
+}
+
+/**
+ * A class representing a queue of promises.
+ * @template T The type of the values that the promises in the queue resolve to.
+ */
+export class Queue<T = any | void> {
+  private _promises: (Promise<any> | (() => Promise<T>))[];
+  private _currentIndex: number = 0;
+  private _isPaused: boolean = false;
+  private _isCanceled: boolean = false;
+
+  /**
+   * Creates a new Queue.
+   * @param {(Promise<any> | (() => Promise<T>))[]} promises The promises to add to the queue.
+   */
+  constructor(promises: (Promise<any> | (() => Promise<T>))[] = []) {
+    this._promises = promises;
+  }
+
+  private _results: T[];
+
+  /**
+   * Gets the results of the promises that have been resolved so far.
+   * @returns {T[]} The results.
+   */
+  public get results(): T[] {
+    return this._results;
+  }
+
+  /**
+   * Gets the progress of the queue.
+   * @returns {number} The progress (0-1)
+   */
+  public get progress(): number {
+    return this._currentIndex / this._promises.length;
+  }
+
+  /**
+   * Adds promises to the queue.
+   * @param {...(Promise<any> | (() => Promise<T>))[]} args The promises to add.
+   */
+  public add(...args: (Promise<any> | (() => Promise<T>))[]) {
+    this._promises.push(...args);
+  }
+
+  /**
+   * Starts the execution of the promises in the queue.
+   */
+  public start(): void {
+    if (this._currentIndex === 0) {
+      // don't start if already started
+      this._results = [];
+      void this._next();
+    }
+  }
+
+  /**
+   * Pauses the execution of the promises in the queue.
+   */
+  public pause(): void {
+    this._isPaused = true;
+  }
+
+  /**
+   * Resumes the execution of the promises in the queue.
+   */
+  public resume(): void {
+    if (this._isPaused) {
+      this._isPaused = false;
+      void this._next();
+    }
+  }
+
+  /**
+   * Cancels the execution of the promises in the queue.
+   */
+  public cancel(): void {
+    this._isCanceled = true;
+    this._promises = [];
+  }
+
+  /**
+   * Executes the next promise in the queue.
+   * @private
+   * @returns {Promise<void>} A promise that resolves when the next promise in the queue has been executed.
+   */
+  private async _next(): Promise<void> {
+    if (this._isPaused || this._isCanceled || this._currentIndex >= this._promises.length) {
+      return;
+    }
+
+    const currentFunction = this._promises[this._currentIndex];
+
+    try {
+      const result = typeof currentFunction === 'function' ? await currentFunction() : await currentFunction;
+      this._results.push(result);
+      this._currentIndex++;
+      void this._next();
+    } catch (error: any) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      // Log the original error object directly (outside Logger's collapsed
+      // groups) so DevTools renders a source-mapped, clickable stack.
+      console.error("Queue didn't complete due to an error:", error);
+      triggerViteError({
+        message: `Queue didn't complete due to an error: ${err.message}`,
+        stack: err.stack,
+        id: error?.id,
+      });
+      // this._isCanceled = true;
+      // remove the current promise from the queue
+      this._promises.splice(this._currentIndex, 1);
+      void this._next();
+    }
+  }
+}

package/src/utils/promise/functions.ts

@@ -0,0 +1,16 @@
+/**
+ * Delays the execution of the subsequent code.
+ * @param {number} seconds The delay time in seconds. Default is 0.
+ * @returns {Promise<void>} A promise that resolves after the specified delay.
+ */
+export const delay = (seconds: number = 0): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+
+export const wait = (seconds: number = 0): Promise<void> => delay(seconds);
+
+/**
+ * Checks if the given value is a promise.
+ * @param {any} value The value to check.
+ * @returns {boolean} True if the value is a promise, false otherwise.
+ */
+export const isPromise = (value: any): value is Promise<any> => value && typeof value.then === 'function';

package/src/utils/promise/index.ts

@@ -0,0 +1,2 @@
+export * from './functions';
+export * from './Queue';