@ztimson/utils 0.27.9 → 0.27.11

package/dist/cache.d.ts

@@ -38,6 +38,7 @@ export declare class Cache<K extends string | number | symbol, T> {
      */
     constructor(key?: keyof T | undefined, options?: CacheOptions);
     private getKey;
+    /** Save item to storage */
     private save;
     private clearTimer;
     private touchLRU;
@@ -48,72 +49,30 @@ export declare class Cache<K extends string | number | symbol, T> {
     all(expired?: boolean): CachedValue<T>[];
     /**
      * 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: T, ttl?: any): this;
     /**
      * 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: T[], complete?: boolean): this;
-    /**
-     * Remove all keys from cache
-     */
+    /** Remove all keys */
     clear(): this;
-    /**
-     * Delete an item from the cache
-     * @param {K} key Item's primary key
-     */
+    /** Delete a cached item */
     delete(key: K): this;
-    /**
-     * Return cache as an array of key-value pairs
-     * @return {[K, T][]} Key-value pairs array
-     */
+    /** Return entries as array */
     entries(expired?: boolean): [K, CachedValue<T>][];
-    /**
-     * Manually expire a cached item
-     * @param {K} key Key to expire
-     */
+    /** Manually expire a cached item */
     expire(key: K): 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: Partial<T>, expired?: boolean): T | undefined;
-    /**
-     * 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: K, expired?: boolean): CachedValue<T> | null;
-    /**
-     * Get a list of cached keys
-     * @return {K[]} Array of keys
-     */
+    /** Return list of keys */
     keys(expired?: boolean): K[];
-    /**
-     * Get map of cached items
-     * @return {Record<K, T>}
-     */
+    /** Return map of key → item */
     map(expired?: boolean): Record<K, CachedValue<T>>;
-    /**
-     * 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: K, value: T, ttl?: number | undefined): this;
-    /**
-     * Get all cached items
-     * @return {T[]} Array of items
-     */
+    /** Get all cached items */
     values: (expired?: boolean) => CachedValue<T>[];
 }

package/dist/index.cjs

@@ -186,6 +186,9 @@ ${opts.message || this.desc}`;
     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 {
@@ -467,10 +470,7 @@ ${opts.message || this.desc}`;
       __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;
@@ -518,6 +518,7 @@ ${opts.message || this.desc}`;
       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;
@@ -571,9 +572,6 @@ ${opts.message || this.desc}`;
     }
     /**
      * 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);
@@ -582,9 +580,6 @@ ${opts.message || this.desc}`;
     }
     /**
      * 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();
@@ -592,9 +587,7 @@ ${opts.message || this.desc}`;
       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);
@@ -604,10 +597,7 @@ ${opts.message || this.desc}`;
       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);
@@ -616,10 +606,7 @@ ${opts.message || this.desc}`;
       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()) {
@@ -628,10 +615,7 @@ ${opts.message || this.desc}`;
       }
       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") {
@@ -644,12 +628,7 @@ ${opts.message || this.desc}`;
       } 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;
@@ -657,24 +636,16 @@ ${opts.message || this.desc}`;
       }
       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()) {
@@ -683,10 +654,7 @@ ${opts.message || this.desc}`;
       }
       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()) {
@@ -695,13 +663,7 @@ ${opts.message || this.desc}`;
       }
       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);
@@ -712,7 +674,7 @@ ${opts.message || this.desc}`;
         const t = setTimeout(() => {
           this.expire(key);
           this.save(key);
-        }, (ttl || 0) * 1e3);
+        }, ttl * 1e3);
         this.timers.set(key, t);
       }
       return this;
@@ -1957,10 +1919,12 @@ ${opts.message || this.desc}`;
       __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;
@@ -1969,17 +1933,34 @@ ${opts.message || this.desc}`;
         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);
     }
@@ -2004,6 +1985,13 @@ ${opts.message || this.desc}`;
     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"));
@@ -2029,6 +2017,64 @@ ${opts.message || this.desc}`;
     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
@@ -2037,38 +2083,58 @@ ${opts.message || this.desc}`;
      * @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
@@ -2080,21 +2146,15 @@ ${opts.message || this.desc}`;
     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;
@@ -2102,7 +2162,7 @@ ${opts.message || this.desc}`;
     /**
      * 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) {
@@ -2111,7 +2171,7 @@ ${opts.message || this.desc}`;
     /**
      * 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) {
@@ -2143,7 +2203,7 @@ ${opts.message || this.desc}`;
      * 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);
@@ -2168,7 +2228,7 @@ ${opts.message || this.desc}`;
      * 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);
@@ -2184,6 +2244,10 @@ ${opts.message || this.desc}`;
   };
   /** 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 = "") {
@@ -2192,16 +2256,27 @@ ${opts.message || this.desc}`;
     }
     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
         ]);
       });
@@ -2217,7 +2292,7 @@ ${opts.message || this.desc}`;
       });
     }
     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) {
@@ -2426,7 +2501,7 @@ ${opts.message || this.desc}`;
     }
   }
   memoryStorage.MemoryStorage = MemoryStorage;
-  (function(exports3) {
+  (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);
@@ -2440,12 +2515,12 @@ ${opts.message || this.desc}`;
       if (k2 === void 0) k2 = k;
       o[k2] = m[k];
     });
-    var __exportStar = commonjsGlobal && commonjsGlobal.__exportStar || function(m, exports4) {
-      for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports4, p)) __createBinding(exports4, 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(exports3, "__esModule", { value: true });
-    __exportStar(persist$1, exports3);
-    __exportStar(memoryStorage, exports3);
+    Object.defineProperty(exports$1, "__esModule", { value: true });
+    __exportStar(persist$1, exports$1);
+    __exportStar(memoryStorage, exports$1);
   })(dist);
   exports2.ASet = ASet;
   exports2.ArgParser = ArgParser;