@ztimson/utils 0.27.9 → 0.27.11

package/dist/index.mjs

@@ -182,6 +182,9 @@ function clean(obj, undefinedOnly = false) {
   return obj;
 }
 function deepCopy(value) {
+  if (value == null) return value;
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean" || t === "function") return value;
   try {
     return structuredClone(value);
   } catch {
@@ -463,10 +466,7 @@ class Cache {
     __publicField(this, "complete", false);
     /** Await initial loading */
     __publicField(this, "loading", new Promise((r) => this._loading = r));
-    /**
-     * Get all cached items
-     * @return {T[]} Array of items
-     */
+    /** Get all cached items */
     __publicField(this, "values", this.all);
     var _a, _b, _c, _d;
     this.key = key;
@@ -514,6 +514,7 @@ class Cache {
     if (value[this.key] === void 0) throw new Error(`${this.key.toString()} Doesn't exist on ${JSON.stringify(value, null, 2)}`);
     return value[this.key];
   }
+  /** Save item to storage */
   save(key) {
     var _a, _b;
     const persists = this.options.persistentStorage;
@@ -567,9 +568,6 @@ class Cache {
   }
   /**
    * Add a new item to the cache. Like set, but finds key automatically
-   * @param {T} value Item to add to cache
-   * @param {number | undefined} ttl Override default expiry
-   * @return {this}
    */
   add(value, ttl = this.ttl) {
     const key = this.getKey(value);
@@ -578,9 +576,6 @@ class Cache {
   }
   /**
    * Add several rows to the cache
-   * @param {T[]} rows Several items that will be cached using the default key
-   * @param complete Mark cache as complete & reliable, defaults to true
-   * @return {this}
    */
   addAll(rows, complete = true) {
     this.clear();
@@ -588,9 +583,7 @@ class Cache {
     this.complete = complete;
     return this;
   }
-  /**
-   * Remove all keys from cache
-   */
+  /** Remove all keys */
   clear() {
     this.complete = false;
     for (const [k, t] of this.timers) clearTimeout(t);
@@ -600,10 +593,7 @@ class Cache {
     this.save();
     return this;
   }
-  /**
-   * Delete an item from the cache
-   * @param {K} key Item's primary key
-   */
+  /** Delete a cached item */
   delete(key) {
     this.clearTimer(key);
     const idx = this.lruOrder.indexOf(key);
@@ -612,10 +602,7 @@ class Cache {
     this.save(key);
     return this;
   }
-  /**
-   * Return cache as an array of key-value pairs
-   * @return {[K, T][]} Key-value pairs array
-   */
+  /** Return entries as array */
   entries(expired) {
     const out = [];
     for (const [k, v] of this.store.entries()) {
@@ -624,10 +611,7 @@ class Cache {
     }
     return out;
   }
-  /**
-   * Manually expire a cached item
-   * @param {K} key Key to expire
-   */
+  /** Manually expire a cached item */
   expire(key) {
     this.complete = false;
     if (this.options.expiryPolicy == "keep") {
@@ -640,12 +624,7 @@ class Cache {
     } else this.delete(key);
     return this;
   }
-  /**
-   * Find the first cached item to match a filter
-   * @param {Partial<T>} filter Partial item to match
-   * @param {Boolean} expired Include expired items, defaults to false
-   * @returns {T | undefined} Cached item or undefined if nothing matched
-   */
+  /** Find first matching item */
   find(filter, expired) {
     for (const v of this.store.values()) {
       const row = v;
@@ -653,24 +632,16 @@ class Cache {
     }
     return void 0;
   }
-  /**
-   * Get item from the cache
-   * @param {K} key Key to lookup
-   * @param expired Include expired items
-   * @return {T} Cached item
-   */
+  /** Get cached item by key */
   get(key, expired) {
     const raw = this.store.get(key);
     if (raw == null) return null;
-    const cached = deepCopy(raw);
     this.touchLRU(key);
-    if (expired || !(cached == null ? void 0 : cached._expired)) return cached;
+    const isExpired = raw == null ? void 0 : raw._expired;
+    if (expired || !isExpired) return deepCopy(raw);
     return null;
   }
-  /**
-   * Get a list of cached keys
-   * @return {K[]} Array of keys
-   */
+  /** Return list of keys */
   keys(expired) {
     const out = [];
     for (const [k, v] of this.store.entries()) {
@@ -679,10 +650,7 @@ class Cache {
     }
     return out;
   }
-  /**
-   * Get map of cached items
-   * @return {Record<K, T>}
-   */
+  /** Return map of key → item */
   map(expired) {
     const copy = {};
     for (const [k, v] of this.store.entries()) {
@@ -691,13 +659,7 @@ class Cache {
     }
     return copy;
   }
-  /**
-   * Add an item to the cache manually specifying the key
-   * @param {K} key Key item will be cached under
-   * @param {T} value Item to cache
-   * @param {number | undefined} ttl Override default expiry in seconds
-   * @return {this}
-   */
+  /** Add item manually specifying the key */
   set(key, value, ttl = this.options.ttl) {
     if (this.options.expiryPolicy == "keep") delete value._expired;
     this.clearTimer(key);
@@ -708,7 +670,7 @@ class Cache {
       const t = setTimeout(() => {
         this.expire(key);
         this.save(key);
-      }, (ttl || 0) * 1e3);
+      }, ttl * 1e3);
       this.timers.set(key, t);
     }
     return this;
@@ -1953,10 +1915,12 @@ const _PathEvent = class _PathEvent {
     __publicField(this, "fullPath");
     /** Path including the name, excluding the module */
     __publicField(this, "path");
-    /** Last sagment of path */
+    /** Last segment of path */
     __publicField(this, "name");
     /** List of methods */
     __publicField(this, "methods");
+    /** Whether this path contains glob patterns */
+    __publicField(this, "hasGlob");
     if (typeof e == "object") {
       Object.assign(this, e);
       return;
@@ -1965,17 +1929,34 @@ const _PathEvent = class _PathEvent {
       Object.assign(this, _PathEvent.pathEventCache.get(e));
       return;
     }
-    let [p, scope, method] = e.replaceAll(/\/{2,}/g, "/").split(":");
-    if (!method) method = scope || "*";
-    if (p == "*" || !p && method == "*") {
-      p = "";
-      method = "*";
+    let [p, method] = e.replaceAll(/\/{2,}/g, "/").split(":");
+    if (!method) method = "*";
+    if (p === "" || p === void 0) {
+      this.module = "";
+      this.path = "";
+      this.fullPath = "";
+      this.name = "";
+      this.methods = new ASet(["n"]);
+      this.hasGlob = false;
+      _PathEvent.pathEventCache.set(e, this);
+      return;
+    }
+    if (p === "*") {
+      this.module = "";
+      this.path = "";
+      this.fullPath = "**";
+      this.name = "";
+      this.methods = new ASet(["*"]);
+      this.hasGlob = true;
+      _PathEvent.pathEventCache.set(e, this);
+      return;
     }
     let temp = p.split("/").filter((p2) => !!p2);
     this.module = temp.splice(0, 1)[0] || "";
     this.path = temp.join("/");
     this.fullPath = `${this.module}${this.module && this.path ? "/" : ""}${this.path}`;
     this.name = temp.pop() || "";
+    this.hasGlob = this.fullPath.includes("*");
     this.methods = new ASet(method.split(""));
     _PathEvent.pathEventCache.set(e, this);
   }
@@ -2000,6 +1981,13 @@ const _PathEvent = class _PathEvent {
   set create(v) {
     v ? this.methods.delete("n").delete("*").add("c") : this.methods.delete("c");
   }
+  /** Execute method specified */
+  get execute() {
+    return !this.methods.has("n") && (this.methods.has("*") || this.methods.has("x"));
+  }
+  set execute(v) {
+    v ? this.methods.delete("n").delete("*").add("x") : this.methods.delete("x");
+  }
   /** Read method specified */
   get read() {
     return !this.methods.has("n") && (this.methods.has("*") || this.methods.has("r"));
@@ -2025,6 +2013,64 @@ const _PathEvent = class _PathEvent {
   static clearCache() {
     _PathEvent.pathEventCache.clear();
   }
+  /** Clear the permission cache */
+  static clearPermissionCache() {
+    _PathEvent.permissionCache.clear();
+  }
+  /**
+   * Score a path for specificity ranking (lower = more specific = higher priority)
+   * @private
+   */
+  static scoreSpecificity(path) {
+    if (path === "**" || path === "") return Number.MAX_SAFE_INTEGER;
+    const segments = path.split("/").filter((p) => !!p);
+    let score = -segments.length;
+    segments.forEach((seg) => {
+      if (seg === "**") score += 0.5;
+      else if (seg === "*") score += 0.25;
+    });
+    return score;
+  }
+  /**
+   * Check if a path matches a glob pattern
+   * @private
+   */
+  static pathMatchesGlob(path, pattern) {
+    if (pattern === path) return true;
+    const pathParts = path.split("/").filter((p) => !!p);
+    const patternParts = pattern.split("/").filter((p) => !!p);
+    let pathIdx = 0;
+    let patternIdx = 0;
+    while (patternIdx < patternParts.length && pathIdx < pathParts.length) {
+      const patternPart = patternParts[patternIdx];
+      if (patternPart === "**") {
+        if (patternIdx === patternParts.length - 1) {
+          return true;
+        }
+        patternParts[patternIdx + 1];
+        while (pathIdx < pathParts.length) {
+          if (_PathEvent.pathMatchesGlob(pathParts.slice(pathIdx).join("/"), patternParts.slice(patternIdx + 1).join("/"))) {
+            return true;
+          }
+          pathIdx++;
+        }
+        return false;
+      } else if (patternPart === "*") {
+        pathIdx++;
+        patternIdx++;
+      } else {
+        if (patternPart !== pathParts[pathIdx]) {
+          return false;
+        }
+        pathIdx++;
+        patternIdx++;
+      }
+    }
+    if (patternIdx < patternParts.length) {
+      return patternParts.slice(patternIdx).every((p) => p === "**");
+    }
+    return pathIdx === pathParts.length;
+  }
   /**
    * Combine multiple events into one parsed object. Longest path takes precedent, but all subsequent methods are
    * combined until a "none" is reached
@@ -2033,38 +2079,58 @@ const _PathEvent = class _PathEvent {
    * @return {PathEvent} Final combined permission
    */
   static combine(...paths) {
-    let hitNone = false;
-    const combined = paths.map((p) => p instanceof _PathEvent ? p : new _PathEvent(p)).toSorted((p1, p2) => {
-      const l1 = p1.fullPath.length, l2 = p2.fullPath.length;
-      return l1 < l2 ? 1 : l1 > l2 ? -1 : 0;
-    }).reduce((acc, p) => {
-      if (acc && !acc.fullPath.startsWith(p.fullPath)) return acc;
-      if (p.none) hitNone = true;
-      if (!acc) return p;
-      if (hitNone) return acc;
-      acc.methods = new ASet([...acc.methods, ...p.methods]);
-      return acc;
-    }, null);
-    return combined;
+    const parsed = paths.map((p) => p instanceof _PathEvent ? p : new _PathEvent(p));
+    const sorted = parsed.toSorted((p1, p2) => {
+      const score1 = _PathEvent.scoreSpecificity(p1.fullPath);
+      const score2 = _PathEvent.scoreSpecificity(p2.fullPath);
+      return score1 - score2;
+    });
+    let result = null;
+    for (const p of sorted) {
+      if (!result) {
+        result = p;
+      } else {
+        if (result.fullPath.startsWith(p.fullPath)) {
+          if (p.none) {
+            break;
+          }
+          result.methods = new ASet([...result.methods, ...p.methods]);
+        }
+      }
+    }
+    return result || new _PathEvent("");
   }
   /**
    * Filter a set of paths based on the target
    *
    * @param {string | PathEvent | (string | PathEvent)[]} target Array of events that will filtered
-   * @param filter {...PathEvent} Must container one of
-   * @return {boolean} Whether there is any overlap
+   * @param filter {...PathEvent} Must contain one of
+   * @return {PathEvent[]} Filtered results
    */
   static filter(target, ...filter) {
     const parsedTarget = makeArray(target).map((pe) => pe instanceof _PathEvent ? pe : new _PathEvent(pe));
     const parsedFilter = makeArray(filter).map((pe) => pe instanceof _PathEvent ? pe : new _PathEvent(pe));
-    return parsedTarget.filter((t) => !!parsedFilter.find((r) => {
-      const wildcard = r.fullPath == "*" || t.fullPath == "*";
-      const p1 = r.fullPath.includes("*") ? r.fullPath.slice(0, r.fullPath.indexOf("*")) : r.fullPath;
-      const p2 = t.fullPath.includes("*") ? t.fullPath.slice(0, t.fullPath.indexOf("*")) : t.fullPath;
-      const scope = p1.startsWith(p2) || p2.startsWith(p1);
-      const methods = r.all || t.all || r.methods.intersection(t.methods).length;
-      return (wildcard || scope) && methods;
-    }));
+    return parsedTarget.filter((t) => {
+      const combined = _PathEvent.combine(t);
+      return !!parsedFilter.find((r) => _PathEvent.matches(r, combined));
+    });
+  }
+  /**
+   * Check if a filter pattern matches a target path
+   * @private
+   */
+  static matches(pattern, target) {
+    if (pattern.fullPath === "" || target.fullPath === "") return false;
+    if (pattern.fullPath === "*" || target.fullPath === "*") return pattern.methods.has("*") || target.methods.has("*") || pattern.methods.intersection(target.methods).length > 0;
+    const methodsMatch = pattern.all || target.all || pattern.methods.intersection(target.methods).length > 0;
+    if (!methodsMatch) return false;
+    if (!pattern.hasGlob && !target.hasGlob) {
+      return pattern.fullPath === target.fullPath;
+    }
+    if (pattern.hasGlob) {
+      return this.pathMatchesGlob(target.fullPath, pattern.fullPath);
+    }
+    return this.pathMatchesGlob(pattern.fullPath, target.fullPath);
   }
   /**
    * Squash 2 sets of paths & return true if any overlap is found
@@ -2076,21 +2142,15 @@ const _PathEvent = class _PathEvent {
   static has(target, ...has) {
     const parsedTarget = makeArray(target).map((pe) => pe instanceof _PathEvent ? pe : new _PathEvent(pe));
     const parsedRequired = makeArray(has).map((pe) => pe instanceof _PathEvent ? pe : new _PathEvent(pe));
-    return !!parsedRequired.find((r) => !!parsedTarget.find((t) => {
-      const wildcard = r.fullPath == "*" || t.fullPath == "*";
-      const p1 = r.fullPath.includes("*") ? r.fullPath.slice(0, r.fullPath.indexOf("*")) : r.fullPath;
-      const p2 = t.fullPath.includes("*") ? t.fullPath.slice(0, t.fullPath.indexOf("*")) : t.fullPath;
-      const scope = p1.startsWith(p2);
-      const methods = r.all || t.all || r.methods.intersection(t.methods).length;
-      return (wildcard || scope) && methods;
-    }));
+    const effectiveTarget = parsedTarget.length === 1 ? parsedTarget[0] : _PathEvent.combine(...parsedTarget);
+    return !!parsedRequired.find((r) => _PathEvent.matches(r, effectiveTarget));
   }
   /**
    * Squash 2 sets of paths & return true if the target has all paths
    *
    * @param {string | PathEvent | (string | PathEvent)[]} target Array of Events as strings or pre-parsed
    * @param has Target must have all these paths
-   * @return {boolean} Whether there is any overlap
+   * @return {boolean} Whether all are present
    */
   static hasAll(target, ...has) {
     return has.filter((h) => _PathEvent.has(target, h)).length == has.length;
@@ -2098,7 +2158,7 @@ const _PathEvent = class _PathEvent {
   /**
    * Same as `has` but raises an error if there is no overlap
    *
-   * @param {string | string[]} target Array of Events as strings or pre-parsed
+   * @param {string | PathEvent | (string | PathEvent)[]} target Array of Events as strings or pre-parsed
    * @param has Target must have at least one of these path
    */
   static hasFatal(target, ...has) {
@@ -2107,7 +2167,7 @@ const _PathEvent = class _PathEvent {
   /**
    * Same as `hasAll` but raises an error if the target is missing any paths
    *
-   * @param {string | string[]} target Array of Events as strings or pre-parsed
+   * @param {string | PathEvent | (string | PathEvent)[]} target Array of Events as strings or pre-parsed
    * @param has Target must have all these paths
    */
   static hasAllFatal(target, ...has) {
@@ -2139,7 +2199,7 @@ const _PathEvent = class _PathEvent {
    * Squash 2 sets of paths & return true if the target has all paths
    *
    * @param has Target must have all these paths
-   * @return {boolean} Whether there is any overlap
+   * @return {boolean} Whether all are present
    */
   hasAll(...has) {
     return _PathEvent.hasAll(this, ...has);
@@ -2164,7 +2224,7 @@ const _PathEvent = class _PathEvent {
    * Filter a set of paths based on this event
    *
    * @param {string | PathEvent | (string | PathEvent)[]} target Array of events that will filtered
-   * @return {boolean} Whether there is any overlap
+   * @return {PathEvent[]} Filtered results
    */
   filter(target) {
     return _PathEvent.filter(target, this);
@@ -2180,6 +2240,10 @@ const _PathEvent = class _PathEvent {
 };
 /** Internal cache for PathEvent instances to avoid redundant parsing */
 __publicField(_PathEvent, "pathEventCache", /* @__PURE__ */ new Map());
+/** Cache for compiled permissions (path + required permissions → result) */
+__publicField(_PathEvent, "permissionCache", /* @__PURE__ */ new Map());
+/** Max size for permission cache before LRU eviction */
+__publicField(_PathEvent, "MAX_PERMISSION_CACHE_SIZE", 1e3);
 let PathEvent = _PathEvent;
 class PathEventEmitter {
   constructor(prefix = "") {
@@ -2188,16 +2252,27 @@ class PathEventEmitter {
   }
   emit(event, ...args) {
     const parsed = event instanceof PathEvent ? event : new PathEvent(`${this.prefix}/${event}`);
-    this.listeners.filter((l) => PathEvent.has(l[0], parsed)).forEach(async (l) => l[1](parsed, ...args));
+    this.listeners.filter((l) => PathEvent.has(l[0], parsed)).forEach((l) => l[1](parsed, ...args));
   }
   off(listener) {
     this.listeners = this.listeners.filter((l) => l[1] != listener);
   }
   on(event, listener) {
     makeArray(event).forEach((e) => {
-      if (typeof e == "string" && e[0] == "*" && this.prefix) e = e.slice(1);
+      let fullEvent;
+      if (typeof e === "string") {
+        if (e[0] === ":" && this.prefix) {
+          fullEvent = `${this.prefix}${e}`;
+        } else if (this.prefix) {
+          fullEvent = `${this.prefix}/${e}`;
+        } else {
+          fullEvent = e;
+        }
+      } else {
+        fullEvent = e instanceof PathEvent ? PathEvent.toString(e.fullPath, e.methods) : e;
+      }
       this.listeners.push([
-        e instanceof PathEvent ? e : new PathEvent(`${this.prefix}/${e}`),
+        new PathEvent(fullEvent),
         listener
       ]);
     });
@@ -2213,7 +2288,7 @@ class PathEventEmitter {
     });
   }
   relayEvents(emitter) {
-    emitter.on("*", (event, ...args) => this.emit(event, ...args));
+    emitter.on("**", (event, ...args) => this.emit(event, ...args));
   }
 }
 function search(rows, search2, regex, transform = (r) => r) {
@@ -2422,7 +2497,7 @@ class MemoryStorage {
   }
 }
 memoryStorage.MemoryStorage = MemoryStorage;
-(function(exports) {
+(function(exports$1) {
   var __createBinding = commonjsGlobal && commonjsGlobal.__createBinding || (Object.create ? function(o, m, k, k2) {
     if (k2 === void 0) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -2436,12 +2511,12 @@ memoryStorage.MemoryStorage = MemoryStorage;
     if (k2 === void 0) k2 = k;
     o[k2] = m[k];
   });
-  var __exportStar = commonjsGlobal && commonjsGlobal.__exportStar || function(m, exports2) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports2, p)) __createBinding(exports2, m, p);
+  var __exportStar = commonjsGlobal && commonjsGlobal.__exportStar || function(m, exports$12) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports$12, p)) __createBinding(exports$12, m, p);
   };
-  Object.defineProperty(exports, "__esModule", { value: true });
-  __exportStar(persist$1, exports);
-  __exportStar(memoryStorage, exports);
+  Object.defineProperty(exports$1, "__esModule", { value: true });
+  __exportStar(persist$1, exports$1);
+  __exportStar(memoryStorage, exports$1);
 })(dist);
 export {
   ASet,