perf(memoization,cacache): O(n) → O(1) LRU / regex compile in hot loops

Two independent hot-path wins:

**memoization.ts** — `memoize()` and `memoizeAsync()` previously
maintained a parallel `accessOrder: string[]` alongside the primary
`cache: Map`, and bumped recency on every cache hit via
`indexOf()` (O(n)) + `splice()` (O(n)). For a fully-populated cache
of size 1000, every hit walked up to 1000 entries and shifted the
tail. LRU eviction also did `accessOrder.shift()` which is O(n).

Replace with a Map-insertion-order idiom: `cache.delete(key)` +
`cache.set(key, entry)` moves an entry to the tail in O(1), and
`cache.keys().next().value` returns the oldest in O(1). The parallel
array is gone; every `cache` Map operation stays O(1). Same pattern
already used in `dlx/detect.ts` and `dlx/package.ts`.

memoizeAsync gains a small `bumpRecency()` helper to centralize the
delete-then-set idiom across the hit and stale-dedup branches.

**cacache.ts** — `clear()`'s wildcard branch streamed every cache
entry through `matchesPattern(key, pattern)`, which re-compiled the
regex on every key. For a wildcard clear across N entries that's N
redundant regex compiles. Refactor to `createPatternMatcher(pattern)`
which compiles once and closes over the regex; call sites hoist the
matcher out of the stream loop, dropping regex allocations from
O(N) to O(1). Non-wildcard patterns stay on the fast prefix path.

All 41 memoization tests + 29 cacache tests pass unchanged; full
suite 6327/6327 passing. No API surface changes.

Author: jdalton

CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added — schema (new module, replaces `validation/validate-schema`)
+
+- `@socketsecurity/lib/schema/validate` — non-throwing validator accepting any Zod-shaped schema (duck-typed on `.safeParse`). Returns a tagged `{ ok: true, value } | { ok: false, errors }` with normalized `{ path, message }` issues. socket-lib additionally recognizes TypeBox for its own internal use (e.g. `src/ipc.ts` stub validation); external callers should pass Zod schemas. No runtime dependency on `zod` — consumers bring their own
+- `@socketsecurity/lib/schema/parse` — throwing twin for fail-fast trust boundaries (app startup, config files). Summarizes all issues into a single `Error` message
+- `@socketsecurity/lib/schema/types` — shared types: `Schema<T>`, `ParseResult<T>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema`, and `Infer<S>` (which unwraps Zod v3/v4 and TypeBox output shapes)
+
+### Added — native feature-detect helpers
+
+- `@socketsecurity/lib/promises` `withResolvers()` — exposes the TC39 [`Promise.withResolvers`](https://tc39.es/ecma262/#sec-promise.withResolvers) API as a first-class export. Bound to the native method when available (Node 20.12+ / 21+ / 22+; V8 ≥ 12.0); otherwise falls back to a spec-equivalent `new Promise(executor)` implementation. Returns `{ promise, resolve, reject }` with `Object.prototype`-prototyped own enumerable properties per §27.2.4.9. Retires the `let resolve; const p = new Promise(r => { resolve = r })` dance for deferred-resolution patterns. Public `PromiseWithResolvers<T>` interface exported alongside
+
+### Changed
+
+- `@socketsecurity/lib/regexps` `escapeRegExp()` — bound to native [`RegExp.escape`](https://tc39.es/ecma262/#sec-regexp.escape) when available (Node 24+ / V8 13.7); otherwise uses a spec-compliant fallback. Previous implementation escaped only the SyntaxCharacter set, leaving output unsafe against leading-identifier merging (e.g. a trailing `\0..\9` in a surrounding pattern could absorb a leading digit) and unsafe inside `/.../` literals (no `/` escape). New implementation encodes leading `[0-9A-Za-z]` as `\xHH`, backslash-prefixes `SyntaxCharacter + /`, emits `ControlEscape` letter forms, and `\xHH`-escapes the `otherPunctuators` / whitespace / line-terminator / lone-surrogate set per §22.2.5.1. Fallback output byte-equivalent to native across ASCII 0-127 plus non-ASCII NBSP / ZWNBSP / LS / PS / surrogates (zero diffs). **Caller-visible shape change**: escaped output now uses `\xHH` for many characters that previously passed through literally (e.g. `escapeRegExp('a')` is now `'\\x61'`, not `'a'`); callers that string-match on the escape output rather than compiling it into a `RegExp` may need updates. Functional equivalence (round-trip match against the original input) is preserved
+
+### Removed
+
+- `@socketsecurity/lib/validation/*` subpath retired entirely — its two exports are re-homed under modules that match their purpose. Migrate:
+  - `import { validateSchema } from '@socketsecurity/lib/validation/validate-schema'` → `import { validateSchema } from '@socketsecurity/lib/schema/validate'`
+  - `import { parseSchema } from '@socketsecurity/lib/validation/validate-schema'` → `import { parseSchema } from '@socketsecurity/lib/schema/parse'`
+  - `import { safeJsonParse } from '@socketsecurity/lib/validation/json-parser'` → `import { safeJsonParse } from '@socketsecurity/lib/json/parse'`
+  - Types (`Infer`, `ValidateResult`, `ValidationIssue`, `AnySchema`, `Schema`, `ParseResult`) → `@socketsecurity/lib/schema/types`
+  - Types (`SafeJsonParseOptions`) → `@socketsecurity/lib/json/types`
+- `memoizeDebounced` export from `@socketsecurity/lib/memoization` — the helper was misnamed (the "debounce" callback only invoked the already-memoized fn for cache-population side effects, never deferred the caller's return value) and had no internal consumers. Use `memoize` or `memoizeAsync` with a `ttl` instead
+
+### Fixed — caching
+
+- `src/dlx/detect.ts` — bound `packageJsonPathCache` with an LRU cap (200) and give negative entries a 10s TTL so a directory that later gains a `package.json` (e.g. `npm install` in a sibling workspace) is re-probed instead of permanently stuck on the cached "not found"
+- `src/dlx/package.ts` — bound `binaryPathCache` with an LRU cap (200) so a long-running process that resolves many distinct binary paths no longer accumulates entries forever after `cleanDlxCache` reclaims the files on disk
+- `src/cacache.ts` / `src/cache-with-ttl.ts` — wildcard deletion (`deleteAll('foo*bar')`) now anchors both ends of the pattern. The missing `$` anchor silently over-deleted keys like `foo123bar-extra`
+- `src/globs.ts` — cache key for array-valued options (e.g. `ignore`) is now order-insensitive, so the same logical set doesn't produce multiple cache entries depending on call-site ordering
+
+### Fixed — promises & concurrency
+
+- `src/promise-queue.ts` — when a bounded queue hits its limit, reject the **newest** submission (current call) rather than the oldest already-enqueued task. Prior behavior let a flood of new submissions cancel in-flight work the caller had already committed to awaiting
+- `src/suppress-warnings.ts` `withSuppressedWarnings()` — do not reassign `process.emitWarning` in `finally`. The snapshot-and-restore pattern at the top of the function either captured the native function after a wrapper was already installed (then restoring native on exit wiped every other active suppression) or captured the wrapper itself (making the restore a no-op). Suppression is driven by the `suppressedWarnings` set; membership changes are enough
+- `src/process-lock.ts` — drop the `existsSync(lockPath)` pre-check before `mkdirSync(lockPath)`. `mkdirSync` without `recursive` is already atomic and throws `EEXIST` when another process owns the directory; the pre-check only opened a TOCTOU window without adding safety. Stale-lock detection now compares full-precision milliseconds (`Date.now() - mtime.getTime() > staleMs`) instead of second-level truncation — sub-second `staleMs` values (e.g. 500) were previously being rounded up to a 1s minimum
+
+### Fixed — URL / version / spec parsing
+
+- `src/packages/specs.ts` `getRepoUrlDetails()` — tighten the GitHub URL matcher to anchor on `github.com` specifically (escaped `.`, full-label match) and accept npm's canonical `git+https://` / `git+ssh://` repository URL forms. Previously `/^.+github.com\//` matched lookalike hosts like `githubXcom` or `fake-github.com.attacker.tld`, and returned garbage (e.g. `user: 'git@github.com:npm'`) for scp-style URLs. scp-style `git@github.com:…` (no `://`) is now rejected and returns `{ user: '', project: '' }` — callers must normalize to https/ssh upstream
+- `src/url.ts` `urlSearchParamAsBoolean()` — accept the same truthy vocabulary as `envAsBoolean` (`1` / `true` / `yes` / `on`, case-insensitive). Empty-string input now falls through to `defaultValue` instead of silently returning `false`
+- `src/versions.ts` `maxVersion()` / `minVersion()` — pass `includePrerelease: true` to semver so an all-prerelease input like `['1.0.0-alpha', '1.0.0-beta']` resolves to the latest prerelease instead of returning `undefined` under semver's default behavior against `'*'`
+- `src/external/semver.d.ts` — add `RangeOptions` and type the `options` parameter on `maxSatisfying` / `minSatisfying`
+
+### Fixed — misc
+
+- `src/fs.ts` `findUp()` / `findUpSync()` — traverse up to and **including** the filesystem root (and `stopAt`). The old `while (dir && dir !== root)` loop exited before visiting `root` itself, so a match at `/.foo` was never found
+- `src/words.ts` `capitalize()` — iterate by code point so non-BMP characters (emoji, astral-plane scripts) aren't split between their UTF-16 surrogate pair halves. Previously `'𐐀foo'` produced a broken leading surrogate
+- `src/words.ts` `determineArticle()` — match leading vowels case-insensitively (`Apple` → `an Apple`, not `a Apple`). Silent-h / y-sound exceptions (hour, user) remain a documented limitation rather than a built-in exception list
+
 ## [5.20.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.1) - 2026-04-19
 
 ### Fixed

src/cacache.ts

@@ -40,29 +40,23 @@ export interface RemoveOptions {
 }
 
 /**
- * Check if a key matches a pattern (with wildcard support).
+ * Build a key→boolean matcher for `pattern`. For non-wildcard patterns
+ * this returns a prefix-startsWith predicate (no regex allocation); for
+ * wildcard patterns it compiles the regex *once* and closes over it so
+ * the caller can apply the same matcher across N keys in O(1)-per-key.
+ *
+ * Anchors both ends — `foo*bar` matches exactly `foo<anything>bar`,
+ * not `foo<anything>bar<more>`.
  */
-function matchesPattern(key: string, pattern: string): boolean {
-  // If no wildcards, use simple prefix matching (faster)
+function createPatternMatcher(pattern: string): (key: string) => boolean {
   if (!pattern.includes('*')) {
-    return key.startsWith(pattern)
+    return (key: string) => key.startsWith(pattern)
   }
-  // Use regex for wildcard patterns
-  const regex = patternToRegex(pattern)
-  return regex.test(key)
-}
-
-/**
- * Convert wildcard pattern to regex for matching.
- * Supports * as wildcard (matches any characters). Anchors both ends —
- * `foo*bar` matches exactly `foo<anything>bar`, not `foo<anything>bar<more>`.
- */
-function patternToRegex(pattern: string): RegExp {
-  // Escape regex special characters except *
+  // Escape regex special characters except `*`, then convert `*` to `.*`.
   const escaped = pattern.replaceAll(/[.+?^${}()|[\]\\]/g, '\\$&')
-  // Convert * to .* (match any characters)
   const regexPattern = escaped.replaceAll('*', '.*')
-  return new RegExp(`^${regexPattern}$`)
+  const regex = new RegExp(`^${regexPattern}$`)
+  return (key: string) => regex.test(key)
 }
 
 /**
@@ -136,13 +130,16 @@ export async function clear(
     return removed
   }
 
-  // For wildcard patterns, need to match each entry.
+  // For wildcard patterns, need to match each entry. Compile the
+  // matcher once outside the stream loop so wildcard scans are
+  // O(1)-per-key instead of re-compiling the regex on every entry.
   let removed = 0
+  const matches = createPatternMatcher(opts.prefix)
   /* c8 ignore next - External cacache call */
   const stream = cacache.ls.stream(cacheDir)
 
   for await (const entry of stream) {
-    if (matchesPattern(entry.key, opts.prefix)) {
+    if (matches(entry.key)) {
       try {
         /* c8 ignore next - External cacache call */
         await cacache.rm.entry(cacheDir, entry.key)

src/memoization.ts

@@ -150,19 +150,21 @@ export function memoize<Args extends unknown[], Result>(
     throw new TypeError('TTL must be non-negative')
   }
 
+  // LRU via Map insertion-order: delete+re-insert moves a key to the
+  // end in O(1). The oldest key is `cache.keys().next().value`. This
+  // replaces the prior parallel `accessOrder: string[]` which cost
+  // O(n) per hit (indexOf + splice) and scaled poorly for large caches.
   const cache = new Map<string, CacheEntry<Result>>()
-  const accessOrder: string[] = []
 
   // Register for global clearing.
   cacheRegistry.push(() => {
     cache.clear()
-    accessOrder.length = 0
   })
 
   function evictLRU(): void {
-    if (cache.size >= maxSize && accessOrder.length > 0) {
-      const oldest = accessOrder.shift()
-      if (oldest) {
+    if (cache.size >= maxSize) {
+      const oldest = cache.keys().next().value
+      if (oldest !== undefined) {
         cache.delete(oldest)
         debugLog(`[memoize:${name}] clear`, {
           key: oldest,
@@ -182,41 +184,31 @@ export function memoize<Args extends unknown[], Result>(
   return function memoized(...args: Args): Result {
     const key = keyGen(...args)
 
-    // Check cache
     const cached = cache.get(key)
     if (cached) {
       if (!isExpired(cached)) {
         cached.hits++
-        // Move to end of access order (LRU)
-        const index = accessOrder.indexOf(key)
-        if (index !== -1) {
-          accessOrder.splice(index, 1)
-        }
-        accessOrder.push(key)
+        // Bump recency: delete + re-insert moves the entry to Map's
+        // insertion-order tail in O(1).
+        cache.delete(key)
+        cache.set(key, cached)
 
         debugLog(`[memoize:${name}] hit`, { key, hits: cached.hits })
         return cached.value
       }
-      // Clean up expired entry before re-caching.
+      // Expired — drop it before recomputing.
       cache.delete(key)
-      const index = accessOrder.indexOf(key)
-      if (index !== -1) {
-        accessOrder.splice(index, 1)
-      }
     }
 
-    // Cache miss - compute value
     debugLog(`[memoize:${name}] miss`, { key })
     const value = fn(...args)
 
-    // Store in cache
     evictLRU()
     cache.set(key, {
       value,
       timestamp: Date.now(),
       hits: 0,
     })
-    accessOrder.push(key)
 
     debugLog(`[memoize:${name}] set`, { key, cacheSize: cache.size })
     return value
@@ -253,19 +245,20 @@ export function memoizeAsync<Args extends unknown[], Result>(
     ttl = Number.POSITIVE_INFINITY,
   } = options
 
+  // LRU via Map insertion-order: see `memoize()` above for the full
+  // rationale. Key lifecycle on bump: `cache.delete(key)` +
+  // `cache.set(key, entry)` moves the entry to the tail in O(1).
   const cache = new Map<string, CacheEntry<Promise<Result>>>()
-  const accessOrder: string[] = []
 
   // Register for global clearing.
   cacheRegistry.push(() => {
     cache.clear()
-    accessOrder.length = 0
   })
 
   function evictLRU(): void {
-    if (cache.size >= maxSize && accessOrder.length > 0) {
-      const oldest = accessOrder.shift()
-      if (oldest) {
+    if (cache.size >= maxSize) {
+      const oldest = cache.keys().next().value
+      if (oldest !== undefined) {
         cache.delete(oldest)
         debugLog(`[memoizeAsync:${name}] clear`, {
           key: oldest,
@@ -282,24 +275,24 @@ export function memoizeAsync<Args extends unknown[], Result>(
     return Date.now() - entry.timestamp > ttl
   }
 
+  // Bump an existing cache entry to the tail (most-recently-used) in
+  // O(1). Caller must have already verified `cache.has(key)`.
+  function bumpRecency(key: string, entry: CacheEntry<Promise<Result>>): void {
+    cache.delete(key)
+    cache.set(key, entry)
+  }
+
   // Track in-flight refreshes to prevent thundering herd on TTL expiry.
   const refreshing = new Map<string, Promise<Result>>()
 
   return async function memoized(...args: Args): Promise<Result> {
     const key = keyGen(...args)
 
-    // Check cache
     const cached = cache.get(key)
     if (cached) {
       if (!isExpired(cached)) {
         cached.hits++
-        // Move to end of access order (LRU)
-        const index = accessOrder.indexOf(key)
-        if (index !== -1) {
-          accessOrder.splice(index, 1)
-        }
-        accessOrder.push(key)
-
+        bumpRecency(key, cached)
         debugLog(`[memoizeAsync:${name}] hit`, { key, hits: cached.hits })
         return await cached.value
       }
@@ -310,35 +303,26 @@ export function memoizeAsync<Args extends unknown[], Result>(
         debugLog(`[memoizeAsync:${name}] stale-dedup`, { key })
         // Bump recency so the entry we're refreshing isn't evicted
         // under LRU pressure while a peer is computing on our behalf.
-        const inflightIndex = accessOrder.indexOf(key)
-        if (inflightIndex !== -1) {
-          accessOrder.splice(inflightIndex, 1)
-        }
-        accessOrder.push(key)
+        bumpRecency(key, cached)
         return await inflight
       }
-      // Clean up expired entry before re-caching.
+      // Expired and no in-flight refresh — drop it before recomputing.
       cache.delete(key)
-      const index = accessOrder.indexOf(key)
-      if (index !== -1) {
-        accessOrder.splice(index, 1)
-      }
     }
 
-    // Cache miss - compute value
     debugLog(`[memoizeAsync:${name}] miss`, { key })
 
-    // Create promise and cache it immediately (for deduplication)
+    // Create promise and cache it immediately (for deduplication).
     const promise = fn(...args).then(
       result => {
         refreshing.delete(key)
-        // Success — update cache entry with resolved promise AND refresh
-        // the timestamp so the freshly-computed value isn't immediately
-        // classified as expired. The timestamp was previously set when
-        // the fetch *started*; under a slow fn this meant `isExpired`
-        // could fire right as the value landed, and every subsequent
-        // call past TTL recomputed because the stale-dedup branch had
-        // nothing to join (`refreshing` was emptied here first).
+        // Success — refresh the timestamp so the freshly-computed value
+        // isn't immediately classified as expired. The timestamp was
+        // previously set when the fetch *started*; under a slow fn this
+        // meant `isExpired` could fire right as the value landed, and
+        // every subsequent call past TTL recomputed because the
+        // stale-dedup branch had nothing to join (`refreshing` was
+        // emptied here first).
         const entry = cache.get(key)
         if (entry) {
           entry.value = Promise.resolve(result)
@@ -348,26 +332,20 @@ export function memoizeAsync<Args extends unknown[], Result>(
       },
       error => {
         refreshing.delete(key)
-        // Failure - remove from cache to allow retry
+        // Failure — remove from cache to allow retry.
         cache.delete(key)
-        const index = accessOrder.indexOf(key)
-        if (index !== -1) {
-          accessOrder.splice(index, 1)
-        }
         debugLog(`[memoizeAsync:${name}] error`, { key, error })
         throw error
       },
     )
     refreshing.set(key, promise)
 
-    // Store promise in cache
     evictLRU()
     cache.set(key, {
       value: promise,
       timestamp: Date.now(),
       hits: 0,
     })
-    accessOrder.push(key)
 
     debugLog(`[memoizeAsync:${name}] set`, { key, cacheSize: cache.size })
     return await promise