@studiometa/js-toolkit 3.6.2 → 3.7.0

package/decorators/withGroup.d.ts

@@ -8,9 +8,32 @@ export interface WithGroupProps extends BaseProps {
 export interface WithGroupInterface extends BaseInterface {
     get $group(): Set<Base>;
 }
+/**
+ * Options for the `withGroup` decorator.
+ */
+export interface WithGroupOptions<T extends Base = Base, Scope extends object = object> {
+    /**
+     * Resolve the scope an instance belongs to. Return `undefined` to fall back
+     * to the global (unscoped) registry.
+     */
+    getScope?: (instance: T) => Scope | undefined;
+    /**
+     * Resolve the group name of an instance, optionally using its resolved scope.
+     * Defaults to `instance.$options.group`.
+     */
+    getGroup?: (instance: T, scope: Scope | undefined) => string;
+}
+/**
+ * Enumerate the scoped groups registered for a given scope.
+ *
+ * Returns the live `Map` of `${namespace}${group}` keys to their members set
+ * for the given scope, or an empty `Map` for unknown scopes. Unknown scopes are
+ * NOT registered as a side effect of reading.
+ */
+export declare function getScopedGroups(scope: object): Map<string, Set<Base>>;
 /**
  * Add group features to easily bind multiple components together.
  *
  * @link https://js-toolkit.studiometa.dev/api/decorators/withGroup.html
  */
-export declare function withGroup<S extends Base = Base>(BaseClass: typeof Base, namespace?: string): BaseDecorator<WithGroupInterface, S, WithGroupProps>;
+export declare function withGroup<S extends Base = Base, Scope extends object = object>(BaseClass: typeof Base, namespace?: string, options?: WithGroupOptions<S, Scope>): BaseDecorator<WithGroupInterface, S, WithGroupProps>;

package/decorators/withGroup.js

@@ -1,7 +1,30 @@
 function groups() {
   return globalThis.__JS_TOOLKIT_GROUPS__ ??= /* @__PURE__ */ new Map();
 }
-function withGroup(BaseClass, namespace = "") {
+const scopedGroups = /* @__PURE__ */ new WeakMap();
+function getScopedGroups(scope) {
+  return scopedGroups.get(scope) ?? /* @__PURE__ */ new Map();
+}
+function resolveGroupSet(scope, key) {
+  if (scope) {
+    let map = scopedGroups.get(scope);
+    if (!map) {
+      map = /* @__PURE__ */ new Map();
+      scopedGroups.set(scope, map);
+    }
+    let set = map.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      map.set(key, set);
+    }
+    return set;
+  }
+  const registry = groups();
+  return registry.get(key) ?? registry.set(key, /* @__PURE__ */ new Set()).get(key);
+}
+function withGroup(BaseClass, namespace = "", options = {}) {
+  const getScope = options.getScope;
+  const getGroup = options.getGroup ?? ((instance) => instance.$options.group);
   return class WithGroup extends BaseClass {
     static config = {
       ...BaseClass.config,
@@ -9,12 +32,27 @@ function withGroup(BaseClass, namespace = "") {
         group: String
       }
     };
+    /**
+     * The members set remembered at mount time, if any.
+     *
+     * @private
+     */
+    __groupSnapshot = void 0;
+    /**
+     * Resolve the members set for the current scope and group.
+     *
+     * @private
+     */
+    __resolveGroup() {
+      const scope = getScope?.(this);
+      const group = `${namespace}${getGroup(this, scope)}`;
+      return resolveGroupSet(scope, group);
+    }
     /**
      * Get the group set.
      */
     get $group() {
-      const group = `${namespace}${this.$options.group}`;
-      const instances = groups().get(group) ?? groups().set(group, /* @__PURE__ */ new Set()).get(group);
+      const instances = this.__groupSnapshot ?? this.__resolveGroup();
       for (const instance of instances) {
         if (!instance.$el.isConnected) {
           instances.delete(instance);
@@ -25,15 +63,19 @@ function withGroup(BaseClass, namespace = "") {
     constructor(element) {
       super(element);
       this.$on("mounted", () => {
-        this.$group.add(this);
+        const instances = this.$group;
+        instances.add(this);
+        this.__groupSnapshot = instances;
       });
       this.$on("destroyed", () => {
-        this.$group.delete(this);
+        this.__groupSnapshot?.delete(this);
+        this.__groupSnapshot = void 0;
       });
     }
   };
 }
 export {
+  getScopedGroups,
   withGroup
 };
 //# sourceMappingURL=withGroup.js.map

package/decorators/withGroup.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../packages/js-toolkit/decorators/withGroup.ts"],
-  "sourcesContent": ["import type { BaseDecorator, BaseInterface } from '../Base/types.js';\nimport type { Base, BaseProps, BaseConfig } from '../Base/index.js';\n\nexport interface WithGroupProps extends BaseProps {\n  $options: {\n    group: string;\n  };\n}\n\nexport interface WithGroupInterface extends BaseInterface {\n  get $group(): Set<Base>;\n}\n\n/**\n * Get global groups map.\n */\nfunction groups<T extends Base = Base>(): Map<string, Set<T>> {\n  return (globalThis.__JS_TOOLKIT_GROUPS__ ??= new Map<string, Set<T>>());\n}\n\n/**\n * Add group features to easily bind multiple components together.\n *\n * @link https://js-toolkit.studiometa.dev/api/decorators/withGroup.html\n */\nexport function withGroup<S extends Base = Base>(\n  BaseClass: typeof Base,\n  namespace = '',\n): BaseDecorator<WithGroupInterface, S, WithGroupProps> {\n  // @ts-expect-error Decorators can not be typed.\n  return class WithGroup<T extends BaseProps = BaseProps> extends BaseClass<T & WithGroupProps> {\n    static config: BaseConfig = {\n      ...BaseClass.config,\n      options: {\n        group: String,\n      },\n    };\n\n    /**\n     * Get the group set.\n     */\n    get $group() {\n      const group = `${namespace}${this.$options.group}`;\n      const instances =\n        groups<this>().get(group) ?? groups<this>().set(group, new Set()).get(group);\n\n      for (const instance of instances) {\n        if (!instance.$el.isConnected) {\n          instances.delete(instance);\n        }\n      }\n\n      return instances;\n    }\n\n    constructor(element: HTMLElement) {\n      super(element);\n\n      this.$on('mounted', () => {\n        this.$group.add(this);\n      });\n      this.$on('destroyed', () => {\n        this.$group.delete(this);\n      });\n    }\n  };\n}\n"],
-  "mappings": "AAgBA,SAAS,SAAqD;AAC5D,SAAQ,WAAW,0BAA0B,oBAAI,IAAoB;AACvE;AAOO,SAAS,UACd,WACA,YAAY,IAC0C;AAEtD,SAAO,MAAM,kBAAmD,UAA8B;AAAA,IAC5F,OAAO,SAAqB;AAAA,MAC1B,GAAG,UAAU;AAAA,MACb,SAAS;AAAA,QACP,OAAO;AAAA,MACT;AAAA,IACF;AAAA;AAAA;AAAA;AAAA,IAKA,IAAI,SAAS;AACX,YAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,SAAS,KAAK;AAChD,YAAM,YACJ,OAAa,EAAE,IAAI,KAAK,KAAK,OAAa,EAAE,IAAI,OAAO,oBAAI,IAAI,CAAC,EAAE,IAAI,KAAK;AAE7E,iBAAW,YAAY,WAAW;AAChC,YAAI,CAAC,SAAS,IAAI,aAAa;AAC7B,oBAAU,OAAO,QAAQ;AAAA,QAC3B;AAAA,MACF;AAEA,aAAO;AAAA,IACT;AAAA,IAEA,YAAY,SAAsB;AAChC,YAAM,OAAO;AAEb,WAAK,IAAI,WAAW,MAAM;AACxB,aAAK,OAAO,IAAI,IAAI;AAAA,MACtB,CAAC;AACD,WAAK,IAAI,aAAa,MAAM;AAC1B,aAAK,OAAO,OAAO,IAAI;AAAA,MACzB,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
+  "sourcesContent": ["import type { BaseDecorator, BaseInterface } from '../Base/types.js';\nimport type { Base, BaseProps, BaseConfig } from '../Base/index.js';\n\nexport interface WithGroupProps extends BaseProps {\n  $options: {\n    group: string;\n  };\n}\n\nexport interface WithGroupInterface extends BaseInterface {\n  get $group(): Set<Base>;\n}\n\n/**\n * Options for the `withGroup` decorator.\n */\nexport interface WithGroupOptions<T extends Base = Base, Scope extends object = object> {\n  /**\n   * Resolve the scope an instance belongs to. Return `undefined` to fall back\n   * to the global (unscoped) registry.\n   */\n  getScope?: (instance: T) => Scope | undefined;\n  /**\n   * Resolve the group name of an instance, optionally using its resolved scope.\n   * Defaults to `instance.$options.group`.\n   */\n  getGroup?: (instance: T, scope: Scope | undefined) => string;\n}\n\n/**\n * Get global groups map.\n */\nfunction groups<T extends Base = Base>(): Map<string, Set<T>> {\n  return (globalThis.__JS_TOOLKIT_GROUPS__ ??= new Map<string, Set<T>>());\n}\n\n/**\n * Scoped groups registry, keyed by scope identity. Scopes are stored in a\n * `WeakMap` so they can be garbage-collected once no longer referenced.\n */\nconst scopedGroups = new WeakMap<object, Map<string, Set<Base>>>();\n\n/**\n * Enumerate the scoped groups registered for a given scope.\n *\n * Returns the live `Map` of `${namespace}${group}` keys to their members set\n * for the given scope, or an empty `Map` for unknown scopes. Unknown scopes are\n * NOT registered as a side effect of reading.\n */\nexport function getScopedGroups(scope: object): Map<string, Set<Base>> {\n  return scopedGroups.get(scope) ?? new Map<string, Set<Base>>();\n}\n\n/**\n * Get the members set for a given `(scope, key)` pair, creating it if needed.\n * When `scope` is `undefined`, the global (unscoped) registry is used.\n */\nfunction resolveGroupSet(scope: object | undefined, key: string): Set<Base> {\n  if (scope) {\n    let map = scopedGroups.get(scope);\n    if (!map) {\n      map = new Map<string, Set<Base>>();\n      scopedGroups.set(scope, map);\n    }\n    let set = map.get(key);\n    if (!set) {\n      set = new Set<Base>();\n      map.set(key, set);\n    }\n    return set;\n  }\n\n  const registry = groups();\n  return registry.get(key) ?? registry.set(key, new Set()).get(key)!;\n}\n\n/**\n * Add group features to easily bind multiple components together.\n *\n * @link https://js-toolkit.studiometa.dev/api/decorators/withGroup.html\n */\nexport function withGroup<S extends Base = Base, Scope extends object = object>(\n  BaseClass: typeof Base,\n  namespace = '',\n  options: WithGroupOptions<S, Scope> = {},\n): BaseDecorator<WithGroupInterface, S, WithGroupProps> {\n  const getScope = options.getScope;\n  const getGroup = options.getGroup ?? ((instance: S) => instance.$options.group);\n\n  // @ts-expect-error Decorators can not be typed.\n  return class WithGroup<T extends BaseProps = BaseProps> extends BaseClass<T & WithGroupProps> {\n    static config: BaseConfig = {\n      ...BaseClass.config,\n      options: {\n        group: String,\n      },\n    };\n\n    /**\n     * The members set remembered at mount time, if any.\n     *\n     * @private\n     */\n    __groupSnapshot: Set<Base> | undefined = undefined;\n\n    /**\n     * Resolve the members set for the current scope and group.\n     *\n     * @private\n     */\n    __resolveGroup() {\n      const scope = getScope?.(this as unknown as S);\n      const group = `${namespace}${getGroup(this as unknown as S, scope)}`;\n      return resolveGroupSet(scope, group);\n    }\n\n    /**\n     * Get the group set.\n     */\n    get $group() {\n      const instances = this.__groupSnapshot ?? this.__resolveGroup();\n\n      for (const instance of instances) {\n        if (!instance.$el.isConnected) {\n          instances.delete(instance);\n        }\n      }\n\n      return instances;\n    }\n\n    constructor(element: HTMLElement) {\n      super(element);\n\n      this.$on('mounted', () => {\n        // Resolve the members set through the public `$group` getter so that\n        // subclasses overriding it keep receiving the membership writes. At this\n        // point `__groupSnapshot` is still `undefined`, so the base getter\n        // resolves fresh (identical behaviour for non-overriding classes).\n        // Remember the exact set the instance was added to so that on destroy a\n        // member is always removed from the set it joined, even if the scope or\n        // group would now resolve differently.\n        const instances = this.$group;\n        instances.add(this);\n        this.__groupSnapshot = instances;\n      });\n      this.$on('destroyed', () => {\n        this.__groupSnapshot?.delete(this);\n        this.__groupSnapshot = undefined;\n      });\n    }\n  };\n}\n"],
+  "mappings": "AAgCA,SAAS,SAAqD;AAC5D,SAAQ,WAAW,0BAA0B,oBAAI,IAAoB;AACvE;AAMA,MAAM,eAAe,oBAAI,QAAwC;AAS1D,SAAS,gBAAgB,OAAuC;AACrE,SAAO,aAAa,IAAI,KAAK,KAAK,oBAAI,IAAuB;AAC/D;AAMA,SAAS,gBAAgB,OAA2B,KAAwB;AAC1E,MAAI,OAAO;AACT,QAAI,MAAM,aAAa,IAAI,KAAK;AAChC,QAAI,CAAC,KAAK;AACR,YAAM,oBAAI,IAAuB;AACjC,mBAAa,IAAI,OAAO,GAAG;AAAA,IAC7B;AACA,QAAI,MAAM,IAAI,IAAI,GAAG;AACrB,QAAI,CAAC,KAAK;AACR,YAAM,oBAAI,IAAU;AACpB,UAAI,IAAI,KAAK,GAAG;AAAA,IAClB;AACA,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,OAAO;AACxB,SAAO,SAAS,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,oBAAI,IAAI,CAAC,EAAE,IAAI,GAAG;AAClE;AAOO,SAAS,UACd,WACA,YAAY,IACZ,UAAsC,CAAC,GACe;AACtD,QAAM,WAAW,QAAQ;AACzB,QAAM,WAAW,QAAQ,aAAa,CAAC,aAAgB,SAAS,SAAS;AAGzE,SAAO,MAAM,kBAAmD,UAA8B;AAAA,IAC5F,OAAO,SAAqB;AAAA,MAC1B,GAAG,UAAU;AAAA,MACb,SAAS;AAAA,QACP,OAAO;AAAA,MACT;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,kBAAyC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOzC,iBAAiB;AACf,YAAM,QAAQ,WAAW,IAAoB;AAC7C,YAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,MAAsB,KAAK,CAAC;AAClE,aAAO,gBAAgB,OAAO,KAAK;AAAA,IACrC;AAAA;AAAA;AAAA;AAAA,IAKA,IAAI,SAAS;AACX,YAAM,YAAY,KAAK,mBAAmB,KAAK,eAAe;AAE9D,iBAAW,YAAY,WAAW;AAChC,YAAI,CAAC,SAAS,IAAI,aAAa;AAC7B,oBAAU,OAAO,QAAQ;AAAA,QAC3B;AAAA,MACF;AAEA,aAAO;AAAA,IACT;AAAA,IAEA,YAAY,SAAsB;AAChC,YAAM,OAAO;AAEb,WAAK,IAAI,WAAW,MAAM;AAQxB,cAAM,YAAY,KAAK;AACvB,kBAAU,IAAI,IAAI;AAClB,aAAK,kBAAkB;AAAA,MACzB,CAAC;AACD,WAAK,IAAI,aAAa,MAAM;AAC1B,aAAK,iBAAiB,OAAO,IAAI;AACjC,aAAK,kBAAkB;AAAA,MACzB,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "A set of useful little bits of JavaScript to boost your project! 🚀",
   "publishConfig": {
     "access": "public"

package/utils/math/fold.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Fold a value back and forth in the min and max range.
+ * @link https://js-toolkit.studiometa.dev/utils/math/fold.html
+ */
+export declare function fold(value: number, min: number, max: number): number;

package/utils/math/fold.js

@@ -0,0 +1,14 @@
+import { wrap } from "./wrap.js";
+function fold(value, min, max) {
+  const range = max - min;
+  if (!Number.isFinite(range) || range <= 0) {
+    return min;
+  }
+  const cycle = range * 2;
+  const wrapped = wrap(value, min, min + cycle);
+  return wrapped > max ? 2 * max - wrapped : wrapped;
+}
+export {
+  fold
+};
+//# sourceMappingURL=fold.js.map

package/utils/math/fold.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/utils/math/fold.ts"],
+  "sourcesContent": ["import { wrap } from './wrap.js';\n\n/**\n * Fold a value back and forth in the min and max range.\n * @link https://js-toolkit.studiometa.dev/utils/math/fold.html\n */\nexport function fold(value: number, min: number, max: number): number {\n  const range = max - min;\n\n  if (!Number.isFinite(range) || range <= 0) {\n    return min;\n  }\n\n  const cycle = range * 2;\n  const wrapped = wrap(value, min, min + cycle);\n\n  return wrapped > max ? 2 * max - wrapped : wrapped;\n}\n"],
+  "mappings": "AAAA,SAAS,YAAY;AAMd,SAAS,KAAK,OAAe,KAAa,KAAqB;AACpE,QAAM,QAAQ,MAAM;AAEpB,MAAI,CAAC,OAAO,SAAS,KAAK,KAAK,SAAS,GAAG;AACzC,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,QAAQ;AACtB,QAAM,UAAU,KAAK,OAAO,KAAK,MAAM,KAAK;AAE5C,SAAO,UAAU,MAAM,IAAI,MAAM,UAAU;AAC7C;",
+  "names": []
+}

package/utils/math/index.d.ts

@@ -5,6 +5,7 @@ export { createRange } from './createRange.js';
 export { clamp } from './clamp.js';
 export { clamp01 } from './clamp01.js';
 export { damp } from './damp.js';
+export { fold } from './fold.js';
 export { spring } from './spring.js';
 export { inertiaFinalValue } from './inertiaFinalValue.js';
 export { lerp } from './lerp.js';

package/utils/math/index.js

@@ -5,6 +5,7 @@ import { createRange } from "./createRange.js";
 import { clamp } from "./clamp.js";
 import { clamp01 } from "./clamp01.js";
 import { damp } from "./damp.js";
+import { fold } from "./fold.js";
 import { spring } from "./spring.js";
 import { inertiaFinalValue } from "./inertiaFinalValue.js";
 import { lerp } from "./lerp.js";
@@ -19,6 +20,7 @@ export {
   createRange,
   damp,
   ease,
+  fold,
   inertiaFinalValue,
   lerp,
   map,

package/utils/math/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../packages/js-toolkit/utils/math/index.ts"],
-  "sourcesContent": ["export * as ease from './ease.js';\nexport * from './createEases.js';\nexport * from './ease.js';\nexport { createRange } from './createRange.js';\nexport { clamp } from './clamp.js';\nexport { clamp01 } from './clamp01.js';\nexport { damp } from './damp.js';\nexport { spring } from './spring.js';\nexport { inertiaFinalValue } from './inertiaFinalValue.js';\nexport { lerp } from './lerp.js';\nexport { map } from './map.js';\nexport { round } from './round.js';\nexport { mean } from './mean.js';\nexport { smoothTo } from './smoothTo.js';\nexport { wrap } from './wrap.js';\n"],
-  "mappings": "AAAA,YAAY,UAAU;AACtB,cAAc;AACd,cAAc;AACd,SAAS,mBAAmB;AAC5B,SAAS,aAAa;AACtB,SAAS,eAAe;AACxB,SAAS,YAAY;AACrB,SAAS,cAAc;AACvB,SAAS,yBAAyB;AAClC,SAAS,YAAY;AACrB,SAAS,WAAW;AACpB,SAAS,aAAa;AACtB,SAAS,YAAY;AACrB,SAAS,gBAAgB;AACzB,SAAS,YAAY;",
+  "sourcesContent": ["export * as ease from './ease.js';\nexport * from './createEases.js';\nexport * from './ease.js';\nexport { createRange } from './createRange.js';\nexport { clamp } from './clamp.js';\nexport { clamp01 } from './clamp01.js';\nexport { damp } from './damp.js';\nexport { fold } from './fold.js';\nexport { spring } from './spring.js';\nexport { inertiaFinalValue } from './inertiaFinalValue.js';\nexport { lerp } from './lerp.js';\nexport { map } from './map.js';\nexport { round } from './round.js';\nexport { mean } from './mean.js';\nexport { smoothTo } from './smoothTo.js';\nexport { wrap } from './wrap.js';\n"],
+  "mappings": "AAAA,YAAY,UAAU;AACtB,cAAc;AACd,cAAc;AACd,SAAS,mBAAmB;AAC5B,SAAS,aAAa;AACtB,SAAS,eAAe;AACxB,SAAS,YAAY;AACrB,SAAS,YAAY;AACrB,SAAS,cAAc;AACvB,SAAS,yBAAyB;AAClC,SAAS,YAAY;AACrB,SAAS,WAAW;AACpB,SAAS,aAAa;AACtB,SAAS,YAAY;AACrB,SAAS,gBAAgB;AACzB,SAAS,YAAY;",
   "names": []
 }

package/utils/math/wrap.js

@@ -1,5 +1,8 @@
 function wrap(value, min, max) {
   const range = max - min;
+  if (!Number.isFinite(range)) {
+    return value;
+  }
   return min === max ? min : (range + (value - min) % range) % range + min;
 }
 export {

package/utils/math/wrap.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../packages/js-toolkit/utils/math/wrap.ts"],
-  "sourcesContent": ["/**\n * Wrap a value in the min and max range.\n * @link https://js-toolkit.studiometa.dev/utils/math/wrap.html\n */\nexport function wrap(value: number, min: number, max: number): number {\n  const range = max - min;\n  return min === max ? min : ((range + ((value - min) % range)) % range) + min;\n}\n"],
-  "mappings": "AAIO,SAAS,KAAK,OAAe,KAAa,KAAqB;AACpE,QAAM,QAAQ,MAAM;AACpB,SAAO,QAAQ,MAAM,OAAQ,SAAU,QAAQ,OAAO,SAAU,QAAS;AAC3E;",
+  "sourcesContent": ["/**\n * Wrap a value in the min and max range.\n * @link https://js-toolkit.studiometa.dev/utils/math/wrap.html\n */\nexport function wrap(value: number, min: number, max: number): number {\n  const range = max - min;\n\n  if (!Number.isFinite(range)) {\n    return value;\n  }\n\n  return min === max ? min : ((range + ((value - min) % range)) % range) + min;\n}\n"],
+  "mappings": "AAIO,SAAS,KAAK,OAAe,KAAa,KAAqB;AACpE,QAAM,QAAQ,MAAM;AAEpB,MAAI,CAAC,OAAO,SAAS,KAAK,GAAG;AAC3B,WAAO;AAAA,EACT;AAEA,SAAO,QAAQ,MAAM,OAAQ,SAAU,QAAQ,OAAO,SAAU,QAAS;AAC3E;",
   "names": []
 }