@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/themes/types.d.ts

@@ -1,67 +1,109 @@
 /**
- * @fileoverview Elegant theme type system.
- * Type-safe theming for spinners, loggers, prompts, and links.
+ * @file Elegant theme type system. Type-safe theming for spinners, loggers,
+ *   prompts, and links.
  */
-import type { ColorValue } from '../colors';
+import type { ColorValue } from '../colors/types';
 import type { ShimmerDirection } from '../effects/shimmer';
-import type { SpinnerStyle } from '../spinner';
+import type { SpinnerStyle } from '../spinner/types';
 /**
- * Color reference — direct value or semantic keyword.
- * Keywords: 'primary', 'secondary', 'inherit', 'rainbow'
+ * Color reference — direct value or semantic keyword. Keywords: 'primary',
+ * 'secondary', 'inherit', 'rainbow'
  */
 export type ColorReference = ColorValue | 'primary' | 'secondary' | 'inherit' | 'rainbow';
 /**
  * Theme color palette — semantic colors for visual harmony.
  */
 export type ThemeColors = {
-    /** Primary brand identity */
+    /**
+     * Primary brand identity.
+     */
     primary: ColorValue;
-    /** Secondary accent (optional) */
+    /**
+     * Secondary accent (optional)
+     */
     secondary?: ColorValue | undefined;
-    /** Success indicator ✓ */
+    /**
+     * Success indicator ✓
+     */
     success: ColorValue;
-    /** Error indicator ✗ */
+    /**
+     * Error indicator ✗
+     */
     error: ColorValue;
-    /** Warning indicator ⚠ */
+    /**
+     * Warning indicator ⚠
+     */
     warning: ColorValue;
-    /** Information indicator ℹ */
+    /**
+     * Information indicator ℹ.
+     */
     info: ColorValue;
-    /** Progress indicator → */
+    /**
+     * Progress indicator →
+     */
     step: ColorValue;
-    /** Primary text */
+    /**
+     * Primary text.
+     */
     text: ColorValue;
-    /** Dimmed text */
+    /**
+     * Dimmed text.
+     */
     textDim: ColorValue;
-    /** Hyperlinks */
+    /**
+     * Hyperlinks.
+     */
     link: ColorReference;
-    /** Interactive prompts */
+    /**
+     * Interactive prompts.
+     */
     prompt: ColorReference;
 };
 /**
  * Theme effects — animations and visual enhancements.
  */
 export type ThemeEffects = {
-    /** Spinner configuration */
+    /**
+     * Spinner configuration.
+     */
     spinner?: {
-        /** Color (supports theme references) */
+        /**
+         * Color (supports theme references)
+         */
         color?: ColorReference | undefined;
-        /** Animation style */
+        /**
+         * Animation style.
+         */
         style?: SpinnerStyle | string | undefined;
     };
-    /** Shimmer configuration */
+    /**
+     * Shimmer configuration.
+     */
     shimmer?: {
-        /** Enable shimmer */
+        /**
+         * Enable shimmer.
+         */
         enabled?: boolean | undefined;
-        /** Color (single, gradient, or keyword) */
+        /**
+         * Color (single, gradient, or keyword)
+         */
         color?: ColorReference | ColorValue[] | undefined;
-        /** Direction */
+        /**
+         * Direction.
+         */
         direction?: ShimmerDirection | undefined;
-        /** Speed (steps per frame) */
+        /**
+         * Speed (steps per frame)
+         */
         speed?: number | undefined;
     };
-    /** Pulse configuration */
+    /**
+     * Pulse configuration.
+     */
     pulse?: {
-        /** Speed (milliseconds) */
+        /**
+         * Speed (milliseconds)
+         */
         speed?: number | undefined;
     };
 };
@@ -69,25 +111,41 @@ export type ThemeEffects = {
  * Theme metadata — descriptive information.
  */
 export type ThemeMeta = {
-    /** Description */
+    /**
+     * Description.
+     */
     description?: string | undefined;
-    /** Author */
+    /**
+     * Author.
+     */
     author?: string | undefined;
-    /** Version */
+    /**
+     * Version.
+     */
     version?: string | undefined;
 };
 /**
  * Theme definition — complete visual identity.
  */
 export type Theme = {
-    /** Unique identifier (kebab-case) */
+    /**
+     * Unique identifier (kebab-case)
+     */
     name: string;
-    /** Display name */
+    /**
+     * Display name.
+     */
     displayName: string;
-    /** Color palette */
+    /**
+     * Color palette.
+     */
     colors: ThemeColors;
-    /** Visual effects (optional) */
+    /**
+     * Visual effects (optional)
+     */
     effects?: ThemeEffects | undefined;
-    /** Metadata (optional) */
+    /**
+     * Metadata (optional)
+     */
     meta?: ThemeMeta | undefined;
 };

package/dist/ttl-cache/cache.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file `createTtlCache` — generic TTL-based cache built on top of cacache
+ *   (persistent) plus an in-memory LRU memo layer. Two-tier caching: hot data
+ *   lives in `memoCache` (Map<string, TtlCacheEntry>) capped at `memoMaxSize`
+ *   entries with LRU eviction via Map insertion-order semantics. Persistent
+ *   storage uses cacache so cached values survive process restarts. Key
+ *   features:
+ *
+ *   - Per-key namespacing via `prefix` so multiple caches share one cacache
+ *     directory without conflicting.
+ *   - `getOrFetch` deduplicates concurrent requests for the same key
+ *     (thundering-herd protection via `inflightRequests` map).
+ *   - Wildcard support for `getAll` / `deleteAll` (single-key methods throw on
+ *     `*`).
+ *   - Clock-skew detection: entries with suspiciously-far-future `expiresAt` are
+ *     treated as expired.
+ */
+import type { TtlCache, TtlCacheOptions } from './types';
+/**
+ * Create a TTL-based cache instance.
+ *
+ * @example
+ *   ;```typescript
+ *   const cache = createTtlCache({ ttl: 60_000, prefix: 'my-app' })
+ *   await cache.set('key', { value: 42 })
+ *   const data = await cache.get('key') // { value: 42 }
+ *   ```
+ */
+export declare function createTtlCache(options?: TtlCacheOptions): TtlCache;

package/dist/{cache-with-ttl.js → ttl-cache/cache.js}

@@ -28,13 +28,21 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var cache_with_ttl_exports = {};
-__export(cache_with_ttl_exports, {
+var cache_exports = {};
+__export(cache_exports, {
   createTtlCache: () => createTtlCache
 });
-module.exports = __toCommonJS(cache_with_ttl_exports);
-var cacache = __toESM(require("./cacache"));
-var import_primordials = require("./primordials");
+module.exports = __toCommonJS(cache_exports);
+var import_clear = require("../cacache/clear");
+var import_read = require("../cacache/read");
+var import_write = require("../cacache/write");
+var import_date = require("../primordials/date");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_map_set = require("../primordials/map-set");
+var import_math = require("../primordials/math");
+var import_regexp = require("../primordials/regexp");
+var import_string = require("../primordials/string");
 const DEFAULT_TTL_MS = 5 * 60 * 1e3;
 const DEFAULT_PREFIX = "ttl-cache";
 const DEFAULT_MEMO_MAX_SIZE = 1e3;
@@ -48,12 +56,12 @@ function createTtlCache(options) {
     ...options
   };
   if (opts.prefix?.includes("*")) {
-    throw new import_primordials.TypeErrorCtor(
+    throw new import_error.TypeErrorCtor(
       'Cache prefix cannot contain wildcards (*). Use clear({ prefix: "pattern*" }) for wildcard matching.'
     );
   }
-  const memoCache = new import_primordials.MapCtor();
-  const memoMaxSize = (0, import_primordials.MathMax)(1, opts.memoMaxSize ?? DEFAULT_MEMO_MAX_SIZE);
+  const memoCache = new import_map_set.MapCtor();
+  const memoMaxSize = (0, import_math.MathMax)(1, opts.memoMaxSize ?? DEFAULT_MEMO_MAX_SIZE);
   function memoSet(fullKey, entry) {
     if (memoCache.has(fullKey)) {
       memoCache.delete(fullKey);
@@ -70,7 +78,7 @@ function createTtlCache(options) {
     return `${opts.prefix}:${key}`;
   }
   function isExpired(entry) {
-    const now = (0, import_primordials.DateNow)();
+    const now = (0, import_date.DateNow)();
     const maxFutureMs = 1e4;
     if (entry.expiresAt > now + ttl + maxFutureMs) {
       return true;
@@ -81,20 +89,20 @@ function createTtlCache(options) {
     const fullPattern = buildKey(pattern);
     const hasWildcard = pattern.includes("*");
     if (!hasWildcard) {
-      return (key) => (0, import_primordials.StringPrototypeStartsWith)(key, fullPattern);
+      return (key) => (0, import_string.StringPrototypeStartsWith)(key, fullPattern);
     }
-    const escaped = (0, import_primordials.StringPrototypeReplaceAll)(
+    const escaped = (0, import_string.StringPrototypeReplaceAll)(
       fullPattern,
       /[.+?^${}()|[\]\\]/g,
       "\\$&"
     );
-    const regexPattern = (0, import_primordials.StringPrototypeReplaceAll)(escaped, "*", ".*");
-    const regex = new import_primordials.RegExpCtor(`^${regexPattern}$`);
-    return (key) => (0, import_primordials.RegExpPrototypeTest)(regex, key);
+    const regexPattern = (0, import_string.StringPrototypeReplaceAll)(escaped, "*", ".*");
+    const regex = new import_regexp.RegExpCtor(`^${regexPattern}$`);
+    return (key) => (0, import_regexp.RegExpPrototypeTest)(regex, key);
   }
   async function get(key) {
-    if ((0, import_primordials.StringPrototypeIncludes)(key, "*")) {
-      throw new import_primordials.TypeErrorCtor(
+    if ((0, import_string.StringPrototypeIncludes)(key, "*")) {
+      throw new import_error.TypeErrorCtor(
         "Cache key cannot contain wildcards (*). Use getAll(pattern) to retrieve multiple entries."
       );
     }
@@ -109,14 +117,14 @@ function createTtlCache(options) {
         memoCache.delete(fullKey);
       }
     }
-    const cacheEntry = await cacache.safeGet(fullKey);
+    const cacheEntry = await (0, import_read.safeGet)(fullKey);
     if (cacheEntry) {
       let entry;
       try {
-        entry = (0, import_primordials.JSONParse)(cacheEntry.data.toString("utf8"));
+        entry = (0, import_json.JSONParse)(cacheEntry.data.toString("utf8"));
       } catch {
         try {
-          await cacache.remove(fullKey);
+          await (0, import_write.remove)(fullKey);
         } catch {
         }
         return void 0;
@@ -128,14 +136,14 @@ function createTtlCache(options) {
         return entry.data;
       }
       try {
-        await cacache.remove(fullKey);
+        await (0, import_write.remove)(fullKey);
       } catch {
       }
     }
     return void 0;
   }
   async function getAll(pattern) {
-    const results = new import_primordials.MapCtor();
+    const results = new import_map_set.MapCtor();
     const matches = createMatcher(pattern);
     if (opts.memoize) {
       for (const [key, entry] of memoCache.entries()) {
@@ -146,12 +154,12 @@ function createTtlCache(options) {
           memoCache.delete(key);
           continue;
         }
-        const originalKey = opts.prefix ? (0, import_primordials.StringPrototypeSlice)(key, opts.prefix.length + 1) : key;
+        const originalKey = opts.prefix ? (0, import_string.StringPrototypeSlice)(key, opts.prefix.length + 1) : key;
         results.set(originalKey, entry.data);
       }
     }
-    const cacheDir = (await import("./paths/socket")).getSocketCacacheDir();
-    const cacacheModule = await import("./cacache");
+    const cacheDir = (await import("../paths/socket")).getSocketCacacheDir();
+    const cacacheModule = await import("../cacache/_internal");
     const stream = cacacheModule.getCacache().ls.stream(cacheDir);
     for await (const cacheEntry of stream) {
       if (!cacheEntry.key.startsWith(`${opts.prefix}:`)) {
@@ -165,15 +173,15 @@ function createTtlCache(options) {
         continue;
       }
       try {
-        const entry = await cacache.safeGet(cacheEntry.key);
+        const entry = await (0, import_read.safeGet)(cacheEntry.key);
         if (!entry) {
           continue;
         }
-        const parsed = (0, import_primordials.JSONParse)(
+        const parsed = (0, import_json.JSONParse)(
           entry.data.toString("utf8")
         );
         if (isExpired(parsed)) {
-          await cacache.remove(cacheEntry.key);
+          await (0, import_write.remove)(cacheEntry.key);
           continue;
         }
         results.set(originalKey, parsed.data);
@@ -186,27 +194,27 @@ function createTtlCache(options) {
     return results;
   }
   async function set(key, data) {
-    if ((0, import_primordials.StringPrototypeIncludes)(key, "*")) {
-      throw new import_primordials.TypeErrorCtor(
+    if ((0, import_string.StringPrototypeIncludes)(key, "*")) {
+      throw new import_error.TypeErrorCtor(
         'Cache key cannot contain wildcards (*). Wildcards are only supported in clear({ prefix: "pattern*" }).'
       );
     }
     const fullKey = buildKey(key);
     const entry = {
       data,
-      expiresAt: (0, import_primordials.DateNow)() + ttl
+      expiresAt: (0, import_date.DateNow)() + ttl
     };
     if (opts.memoize) {
       memoSet(fullKey, entry);
     }
     try {
-      await cacache.put(fullKey, JSON.stringify(entry), {
+      await (0, import_write.put)(fullKey, (0, import_json.JSONStringify)(entry), {
         metadata: { expiresAt: entry.expiresAt }
       });
     } catch {
     }
   }
-  const inflightRequests = new import_primordials.MapCtor();
+  const inflightRequests = new import_map_set.MapCtor();
   async function getOrFetch(key, fetcher) {
     const fullKey = buildKey(key);
     const preexisting = inflightRequests.get(fullKey);
@@ -234,20 +242,20 @@ function createTtlCache(options) {
     return await promise;
   }
   async function deleteEntry(key) {
-    if ((0, import_primordials.StringPrototypeIncludes)(key, "*")) {
-      throw new import_primordials.TypeErrorCtor(
+    if ((0, import_string.StringPrototypeIncludes)(key, "*")) {
+      throw new import_error.TypeErrorCtor(
         "Cache key cannot contain wildcards (*). Use deleteAll(pattern) to remove multiple entries."
       );
     }
     const fullKey = buildKey(key);
     memoCache.delete(fullKey);
     try {
-      await cacache.remove(fullKey);
+      await (0, import_write.remove)(fullKey);
     } catch {
     }
   }
   async function deleteAll(pattern) {
-    const fullPrefix = pattern ? `${opts.prefix}:${pattern}` : opts.prefix;
+    const fullPrefix = pattern ? `${opts.prefix}:${pattern}` : `${opts.prefix}:`;
     if (!pattern) {
       memoCache.clear();
     } else {
@@ -258,7 +266,7 @@ function createTtlCache(options) {
         }
       }
     }
-    const removed = await cacache.clear({ prefix: fullPrefix });
+    const removed = await (0, import_clear.clear)({ prefix: fullPrefix });
     return removed ?? 0;
   }
   async function clear(options2) {

package/dist/ttl-cache/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @file Public type surface for `ttl-cache/*` modules — the `TtlCache`
+ *   interface (the seven-method API returned by `createTtlCache`), the
+ *   `TtlCacheEntry` storage shape, and the `TtlCacheOptions` / `ClearOptions`
+ *   configuration records. Pure types, no runtime side effects.
+ */
+export interface ClearOptions {
+    /**
+     * Only clear in-memory memoization cache, not persistent cache. Useful for
+     * forcing a refresh of cached data without removing it from disk.
+     *
+     * @default false
+     */
+    memoOnly?: boolean | undefined;
+}
+export interface TtlCache {
+    /**
+     * Get cached data without fetching. Returns undefined if not found or
+     * expired.
+     *
+     * @param key - Cache key (must not contain wildcards)
+     *
+     * @throws {TypeError} If key contains wildcards (*)
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Get all cached entries matching a pattern. Supports wildcards (*) for
+     * flexible matching.
+     *
+     * @param pattern - Key pattern (supports * wildcards, or use '*' for all
+     *   entries)
+     *
+     * @returns Map of matching entries (key -> value)
+     */
+    getAll<T>(pattern: string): Promise<Map<string, T>>;
+    /**
+     * Get cached data or fetch and cache if missing/expired.
+     *
+     * @param key - Cache key (must not contain wildcards)
+     */
+    getOrFetch<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
+    /**
+     * Set cached data with TTL.
+     *
+     * @param key - Cache key (must not contain wildcards)
+     *
+     * @throws {TypeError} If key contains wildcards (*)
+     */
+    set<T>(key: string, data: T): Promise<void>;
+    /**
+     * Delete a specific cache entry.
+     *
+     * @param key - Cache key (must not contain wildcards)
+     *
+     * @throws {TypeError} If key contains wildcards (*)
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Delete all cache entries matching a pattern. Supports wildcards (*) for
+     * flexible matching.
+     *
+     * @param pattern - Key pattern (supports * wildcards, or omit to delete all)
+     *
+     * @returns Number of entries deleted
+     */
+    deleteAll(pattern?: string | undefined): Promise<number>;
+    /**
+     * Clear all cache entries (like Map.clear()). Optionally clear only in-memory
+     * cache.
+     *
+     * @param options - Optional configuration.
+     */
+    clear(options?: ClearOptions | undefined): Promise<void>;
+}
+export interface TtlCacheEntry<T> {
+    data: T;
+    expiresAt: number;
+}
+export interface TtlCacheOptions {
+    /**
+     * Time-to-live in milliseconds.
+     *
+     * @default 5 * 60 * 1000 (5 minutes)
+     */
+    ttl?: number | undefined;
+    /**
+     * Enable in-memory memoization for hot data.
+     *
+     * @default true
+     */
+    memoize?: boolean | undefined;
+    /**
+     * Maximum number of entries to keep in the in-memory memo cache. When
+     * exceeded, the least-recently-used entry is evicted. The persistent
+     * (cacache) layer is unaffected.
+     *
+     * @default 1000
+     */
+    memoMaxSize?: number | undefined;
+    /**
+     * Custom cache key prefix. Must not contain wildcards (_). Use clear({
+     * prefix: "pattern_" }) for wildcard matching instead.
+     *
+     * @default 'ttl-cache'
+     *
+     * @throws {TypeError} If prefix contains wildcards
+     */
+    prefix?: string | undefined;
+}

package/dist/ttl-cache/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/url/parse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file URL parsing helpers — `parseUrl` (safe `new URL(...)` wrapper that
+ *   returns `undefined` instead of throwing) and `createRelativeUrl` (compose a
+ *   relative path against an optional base).
+ */
+import type { CreateRelativeUrlOptions } from './types';
+/**
+ * Create a relative URL for testing.
+ *
+ * @example
+ *   ;```typescript
+ *   createRelativeUrl('/api/test') // 'api/test'
+ *   createRelativeUrl('/api/test', { base: 'https://example.com' }) // 'https://example.com/api/test'
+ *   ```
+ */
+export declare function createRelativeUrl(path: string, options?: CreateRelativeUrlOptions | undefined): string;
+/**
+ * Parse a value as a URL.
+ *
+ * @example
+ *   ;```typescript
+ *   parseUrl('https://example.com') // URL { href: 'https://example.com/' }
+ *   parseUrl('invalid') // undefined
+ *   ```
+ */
+export declare function parseUrl(value: string | URL): URL | undefined;

package/dist/url/parse.js

@@ -0,0 +1,57 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var parse_exports = {};
+__export(parse_exports, {
+  createRelativeUrl: () => createRelativeUrl,
+  parseUrl: () => parseUrl
+});
+module.exports = __toCommonJS(parse_exports);
+var import_string = require("../primordials/string");
+const UrlCtor = URL;
+// @__NO_SIDE_EFFECTS__
+function createRelativeUrl(path, options) {
+  const { base = "" } = {
+    __proto__: null,
+    ...options
+  };
+  const relativePath = (0, import_string.StringPrototypeReplace)(path, /^\//, "");
+  if (base) {
+    let baseUrl = base;
+    if (!(0, import_string.StringPrototypeEndsWith)(baseUrl, "/")) {
+      baseUrl += "/";
+    }
+    return baseUrl + relativePath;
+  }
+  return relativePath;
+}
+// @__NO_SIDE_EFFECTS__
+function parseUrl(value) {
+  try {
+    return new UrlCtor(value);
+  } catch {
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRelativeUrl,
+  parseUrl
+});

package/dist/url/predicates.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file URL type-guard predicates — `isUrl` answers whether a value parses as a
+ *   valid URL via `parseUrl`.
+ */
+/**
+ * Check if a value is a valid URL.
+ *
+ * @example
+ *   ;```typescript
+ *   isUrl('https://example.com') // true
+ *   isUrl('not a url') // false
+ *   isUrl(null) // false
+ *   ```
+ */
+export declare function isUrl(value: string | URL | null | undefined): boolean;