@socketsecurity/lib 6.0.9 → 6.0.10

package/dist/node/timers-promises.js

@@ -5,6 +5,9 @@ const require_constants_runtime = require('../constants/runtime.js');
 
 //#region src/node/timers-promises.ts
 let timersPromises;
+/**
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
 function getNodeTimersPromises() {
 	if (!require_constants_runtime.IS_NODE) return;
 	return timersPromises ??= /*@__PURE__*/ require("timers/promises");

package/dist/node/url.d.ts

@@ -3,4 +3,7 @@
  *   shared across all `node/*.ts` lazy-loaders.
  */
 import type * as NodeUrl from 'node:url';
+/**
+ * @unused No internal or Socket consumers (exercised only by its unit tests).
+ */
 export declare function getNodeUrl(): typeof NodeUrl;

package/dist/node/url.js

@@ -5,6 +5,9 @@ const require_constants_runtime = require('../constants/runtime.js');
 
 //#region src/node/url.ts
 let cachedUrl;
+/**
+* @unused No internal or Socket consumers (exercised only by its unit tests).
+*/
 function getNodeUrl() {
 	if (!require_constants_runtime.IS_NODE) return;
 	return cachedUrl ??= /*@__PURE__*/ require("url");

package/dist/npm/meta-cache.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @file Cached packument fetch — `getPackumentSlim` wires the pure slicer
+ *   (`./meta-slice`) to an injectable HTTP adapter and the repo's
+ *   `createTtlCache` (memo + cacache persistence + in-flight dedupe via
+ *   `getOrFetch`). Every `getPackumentSlim`-backed cache is actually three
+ *   `TtlCache` instances sharing one cacache directory (`getCachePeers`): the
+ *   primary cache (the object callers hold), a persisted long-TTL last
+ *   known-good store (`-stale` prefix, `STALE_TTL_MS`), and a short-TTL
+ *   storm-control marker (`-storm` prefix, `STALE_SERVE_TTL_MS`). Three
+ *   failure-handling policies layer on top:
+ *
+ *   - **`force`** bypasses a cached entry EXCEPT when it was written within the
+ *     last 30 seconds, so a burst of forced refreshes coalesces into one
+ *     upstream fetch instead of hammering the registry. A forced refresh NEVER
+ *     removes the existing entry before fetching — on failure, whatever was
+ *     cached before the call is untouched, and serve-stale-on-error (below)
+ *     still has the persisted last-known-good value to fall back on.
+ *   - **Negative caching** is narrow and short: only a definitive HTTP 404
+ *     (package/version genuinely absent) is cached, for `NEGATIVE_TTL_MS`, and
+ *     only when the persisted stale store holds no known-good data for that
+ *     key. A transient error (network failure, 5xx) is NEVER negative-cached,
+ *     and a still-fresh negative entry is discarded rather than trusted the
+ *     moment known-good data exists in the persisted stale store — a retry
+ *     always outranks a cached "not found" over real data.
+ *   - **Serve-stale-on-error**: every successful fetch also persists the
+ *     `PackumentMetaSlim` to the stale store, independent of the primary
+ *     entry's own TTL — `STALE_TTL_MS` (7 days) comfortably outlives it, so the
+ *     value survives both the primary entry's expiry and a process restart. If
+ *     a later refresh fails for ANY reason — including a fresh 404 — the
+ *     persisted value is served instead of propagating the error, and the
+ *     storm-control marker is (re)written so a burst of callers within
+ *     `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+ *     failed. ETag revalidation requires a header-capable HTTP adapter; the
+ *     current `NpmMetaHttpAdapter` is header-less by design so test doubles and
+ *     `httpJson` stay interchangeable with the rest of the npm client surface —
+ *     see `NpmMetaHttpAdapter`.
+ */
+import type { GetPackumentSlimOptions, NpmMetaHttpAdapter, PackumentMetaSlim, PackumentVariant } from './meta-types';
+import type { TtlCache, TtlCacheOptions } from '../cache/ttl/types';
+/**
+ * A cached, successfully-fetched packument.
+ */
+export interface CachedPackumentHit {
+    cachedAt: number;
+    kind: 'hit';
+    meta: PackumentMetaSlim;
+}
+/**
+ * A cached definitive-404 result — narrow and short-lived (`NEGATIVE_TTL_MS`);
+ * see the file-level doc for when this is written.
+ */
+export interface CachedPackumentMiss {
+    cachedAt: number;
+    kind: 'miss';
+    status: number;
+}
+/**
+ * The value shape stored per cache key — either a successful fetch or a
+ * short-lived negative (404) result.
+ */
+export type CachedPackumentEntry = CachedPackumentHit | CachedPackumentMiss;
+/**
+ * Thrown by `getPackumentSlim` (and the `getVersions` / `getLatestVersion`
+ * exact-version / dist-tag lookups) when a specific package, version, or tag
+ * is definitively absent. Carries `status` so `extractHttpStatus` reports it
+ * the same way as a real `HttpResponseError`.
+ */
+export declare class PackumentNotFoundError extends Error {
+    packageName: string;
+    status: number;
+    constructor(packageName: string, status: number, message?: string | undefined);
+}
+/**
+ * Build the cache key for one (registry, name, variant) tuple. Normalizes
+ * `registry` first (`normalizeRegistryUrl`) so two spellings of the same
+ * registry collapse to one key.
+ */
+export declare function buildMetaCacheKey(registry: string, name: string, variant: PackumentVariant): string;
+/**
+ * Deep-clone a `PackumentMetaSlim` via a JSON round-trip — plain
+ * JSON-roundtrippable data (strings, numbers, booleans, records), so this is
+ * 3-5x faster than `structuredClone` and avoids the HTML structured-clone
+ * algorithm entirely. Used at every public read boundary so no two callers
+ * ever hold a reference to the same cached object.
+ */
+export declare function cloneMeta(meta: PackumentMetaSlim): PackumentMetaSlim;
+/**
+ * Companion long-TTL (persisted stale) and short-TTL (storm-control) caches
+ * that back one primary `TtlCache` instance — see the file-level doc.
+ */
+export interface NpmMetaCachePeers {
+    stale: TtlCache;
+    storm: TtlCache;
+}
+/**
+ * Create a dedicated npm-meta cache instance — same `prefix` /
+ * default-`ttl` as the module singleton, overridable per-call. Use this (vs.
+ * the default singleton) for test isolation or a non-default TTL. Also
+ * creates and registers this instance's persisted-stale + storm-control
+ * companions (`registerCachePeers`).
+ */
+export declare function createNpmMetaCache(options?: TtlCacheOptions | undefined): TtlCache;
+/**
+ * The uncached fetch attempt for one packument, run through the negative-cache
+ * decision: on success, persists the result to `staleCache` and returns a
+ * `hit`; on a definitive 404 with no persisted stale data, returns a `miss`
+ * (a normal, non-throwing outcome the caller decides how to cache); any other
+ * failure (transient error, or a 404 when stale data DOES exist) rethrows so
+ * the caller's serve-stale-on-error path can take over.
+ */
+export declare function fetchAndCacheEntry(name: string, key: string, fetchOptions: ResolvedPackumentFetchOptions, staleCache: TtlCache): Promise<CachedPackumentEntry>;
+/**
+ * `GetPackumentSlimOptions` with every field the fetch path needs resolved to
+ * a concrete value (defaults applied) — the shape `fetchPackumentSlim` and
+ * `getPackumentSlim`'s cache-key logic operate on internally.
+ */
+export interface ResolvedPackumentFetchOptions {
+    http: NpmMetaHttpAdapter;
+    registry: string;
+    retries: number;
+    timeout?: number | undefined;
+    variant: PackumentVariant;
+}
+/**
+ * The uncached fetch — GET the packument with the variant's `Accept` header
+ * and slice it. Split out so `getPackumentSlim`'s cache-key / force logic
+ * stays readable. Throws (never negative-caches itself — that decision is
+ * `getPackumentSlim`'s, which has the context to know whether stale data
+ * already exists for this key).
+ */
+export declare function fetchPackumentSlim(name: string, resolved: ResolvedPackumentFetchOptions): Promise<PackumentMetaSlim>;
+/**
+ * Resolve the persisted-stale + storm-control companions for a primary cache
+ * instance, creating them lazily (under the default prefix) for a `TtlCache`
+ * that wasn't created via `createNpmMetaCache`.
+ */
+export declare function getCachePeers(cache: TtlCache): NpmMetaCachePeers;
+/**
+ * The module-level default cache instance, created lazily on first use.
+ */
+export declare function getDefaultMetaCache(): TtlCache;
+/**
+ * Fetch a package's packument, slice it down to `PackumentMetaSlim`, and
+ * cache the result. Concurrent calls for the same (registry, name, variant)
+ * dedupe to a single upstream request via the cache's `getOrFetch`. See the
+ * file-level doc for the `force` / negative-cache / serve-stale-on-error
+ * policies.
+ *
+ * @throws {PackumentNotFoundError} When the registry returns a definitive 404
+ *   and no previously-good data exists for this key to serve instead.
+ */
+export declare function getPackumentSlim(name: string, options?: GetPackumentSlimOptions | undefined): Promise<PackumentMetaSlim>;
+/**
+ * Look up the persisted last known-good value for `key`, if any — backed by
+ * `STALE_TTL_MS` (7 days), independent of the primary cache's own TTL, and
+ * readable from a fresh process. Returns a fresh clone so no two callers ever
+ * share a reference to the same cached object.
+ */
+export declare function getStaleMeta(cache: TtlCache, key: string): Promise<PackumentMetaSlim | undefined>;
+/**
+ * Normalize a registry base URL so two spellings of the same registry
+ * collapse to one cache key and one request URL: lowercase the scheme+host,
+ * and ensure exactly one trailing slash. Falls back to the input unchanged
+ * when it isn't a parseable absolute URL.
+ */
+export declare function normalizeRegistryUrl(registry: string): string;
+/**
+ * Create and register the persisted-stale + storm-control companion caches
+ * for `cache` under `prefix`.
+ */
+export declare function registerCachePeers(cache: TtlCache, prefix: string): NpmMetaCachePeers;
+/**
+ * Persist `meta` as the last known-good value for `key`, independent of the
+ * primary entry's own TTL/expiry.
+ */
+export declare function rememberStaleMeta(cache: TtlCache, key: string, meta: PackumentMetaSlim): Promise<void>;
+/**
+ * Serve-stale-on-error: look up the persisted last known-good value and, when
+ * found, (re)write the storm-control marker so a burst of callers within
+ * `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+ * failed.
+ */
+export declare function serveStaleOnFailure(staleCache: TtlCache, stormCache: TtlCache, key: string): Promise<PackumentMetaSlim | undefined>;

package/dist/npm/meta-cache.js

@@ -0,0 +1,318 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_json = require('../primordials/json.js');
+const require_primordials_url = require('../primordials/url.js');
+const require_http_request_response_types = require('../http-request/response-types.js');
+const require_http_request_node = require('../http-request/node.js');
+const require_cache_ttl_store = require('../cache/ttl/store.js');
+const require_npm_meta_slice = require('./meta-slice.js');
+const require_npm_registry = require('./registry.js');
+
+//#region src/npm/meta-cache.ts
+/**
+* @file Cached packument fetch — `getPackumentSlim` wires the pure slicer
+*   (`./meta-slice`) to an injectable HTTP adapter and the repo's
+*   `createTtlCache` (memo + cacache persistence + in-flight dedupe via
+*   `getOrFetch`). Every `getPackumentSlim`-backed cache is actually three
+*   `TtlCache` instances sharing one cacache directory (`getCachePeers`): the
+*   primary cache (the object callers hold), a persisted long-TTL last
+*   known-good store (`-stale` prefix, `STALE_TTL_MS`), and a short-TTL
+*   storm-control marker (`-storm` prefix, `STALE_SERVE_TTL_MS`). Three
+*   failure-handling policies layer on top:
+*
+*   - **`force`** bypasses a cached entry EXCEPT when it was written within the
+*     last 30 seconds, so a burst of forced refreshes coalesces into one
+*     upstream fetch instead of hammering the registry. A forced refresh NEVER
+*     removes the existing entry before fetching — on failure, whatever was
+*     cached before the call is untouched, and serve-stale-on-error (below)
+*     still has the persisted last-known-good value to fall back on.
+*   - **Negative caching** is narrow and short: only a definitive HTTP 404
+*     (package/version genuinely absent) is cached, for `NEGATIVE_TTL_MS`, and
+*     only when the persisted stale store holds no known-good data for that
+*     key. A transient error (network failure, 5xx) is NEVER negative-cached,
+*     and a still-fresh negative entry is discarded rather than trusted the
+*     moment known-good data exists in the persisted stale store — a retry
+*     always outranks a cached "not found" over real data.
+*   - **Serve-stale-on-error**: every successful fetch also persists the
+*     `PackumentMetaSlim` to the stale store, independent of the primary
+*     entry's own TTL — `STALE_TTL_MS` (7 days) comfortably outlives it, so the
+*     value survives both the primary entry's expiry and a process restart. If
+*     a later refresh fails for ANY reason — including a fresh 404 — the
+*     persisted value is served instead of propagating the error, and the
+*     storm-control marker is (re)written so a burst of callers within
+*     `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+*     failed. ETag revalidation requires a header-capable HTTP adapter; the
+*     current `NpmMetaHttpAdapter` is header-less by design so test doubles and
+*     `httpJson` stay interchangeable with the rest of the npm client surface —
+*     see `NpmMetaHttpAdapter`.
+*/
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const ACCEPT_ABBREVIATED = "application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*";
+const ACCEPT_FULL = "application/json";
+const CACHE_PREFIX = "npm-meta";
+const DEFAULT_TTL_MS = 900 * 1e3;
+const FORCE_MIN_AGE_MS = 3e4;
+const NEGATIVE_TTL_MS = 45e3;
+const STALE_TTL_MS = 10080 * 60 * 1e3;
+const STALE_SERVE_TTL_MS = 6e4;
+const DEFAULT_RETRIES = 2;
+const MAX_RETRIES = 5;
+/**
+* Thrown by `getPackumentSlim` (and the `getVersions` / `getLatestVersion`
+* exact-version / dist-tag lookups) when a specific package, version, or tag
+* is definitively absent. Carries `status` so `extractHttpStatus` reports it
+* the same way as a real `HttpResponseError`.
+*/
+var PackumentNotFoundError = class extends Error {
+	packageName;
+	status;
+	constructor(packageName, status, message) {
+		super(message ?? `getPackumentSlim: "${packageName}" not found (registry returned ${status}).`);
+		this.name = "PackumentNotFoundError";
+		this.packageName = packageName;
+		this.status = status;
+	}
+};
+/**
+* Build the cache key for one (registry, name, variant) tuple. Normalizes
+* `registry` first (`normalizeRegistryUrl`) so two spellings of the same
+* registry collapse to one key.
+*/
+function buildMetaCacheKey(registry, name, variant) {
+	return `${normalizeRegistryUrl(registry)}:${name}:${variant}`;
+}
+/**
+* Deep-clone a `PackumentMetaSlim` via a JSON round-trip — plain
+* JSON-roundtrippable data (strings, numbers, booleans, records), so this is
+* 3-5x faster than `structuredClone` and avoids the HTML structured-clone
+* algorithm entirely. Used at every public read boundary so no two callers
+* ever hold a reference to the same cached object.
+*/
+function cloneMeta(meta) {
+	return require_primordials_json.JSONParse(require_primordials_json.JSONStringify(meta));
+}
+/**
+* Maps a primary cache instance to its persisted-stale + storm-control
+* companions. Keyed by the `TtlCache` instance (not a plain module
+* singleton) so distinct cache instances — e.g. one per test — never see
+* each other's stale/storm data.
+*/
+const cachePeers = /* @__PURE__ */ new WeakMap();
+/**
+* Create a dedicated npm-meta cache instance — same `prefix` /
+* default-`ttl` as the module singleton, overridable per-call. Use this (vs.
+* the default singleton) for test isolation or a non-default TTL. Also
+* creates and registers this instance's persisted-stale + storm-control
+* companions (`registerCachePeers`).
+*/
+function createNpmMetaCache(options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const prefix = opts.prefix ?? CACHE_PREFIX;
+	const cache = require_cache_ttl_store.createTtlCache({
+		prefix,
+		ttl: DEFAULT_TTL_MS,
+		...opts
+	});
+	registerCachePeers(cache, prefix);
+	return cache;
+}
+/**
+* The uncached fetch attempt for one packument, run through the negative-cache
+* decision: on success, persists the result to `staleCache` and returns a
+* `hit`; on a definitive 404 with no persisted stale data, returns a `miss`
+* (a normal, non-throwing outcome the caller decides how to cache); any other
+* failure (transient error, or a 404 when stale data DOES exist) rethrows so
+* the caller's serve-stale-on-error path can take over.
+*/
+async function fetchAndCacheEntry(name, key, fetchOptions, staleCache) {
+	try {
+		const meta = await fetchPackumentSlim(name, fetchOptions);
+		await staleCache.set(key, meta);
+		return {
+			cachedAt: Date.now(),
+			kind: "hit",
+			meta
+		};
+	} catch (e) {
+		if (e instanceof require_http_request_response_types.HttpResponseError && e.response.status === 404 && await staleCache.get(key) === void 0) return {
+			cachedAt: Date.now(),
+			kind: "miss",
+			status: 404
+		};
+		throw e;
+	}
+}
+/**
+* The uncached fetch — GET the packument with the variant's `Accept` header
+* and slice it. Split out so `getPackumentSlim`'s cache-key / force logic
+* stays readable. Throws (never negative-caches itself — that decision is
+* `getPackumentSlim`'s, which has the context to know whether stale data
+* already exists for this key).
+*/
+async function fetchPackumentSlim(name, resolved) {
+	const accept = resolved.variant === "full" ? ACCEPT_FULL : ACCEPT_ABBREVIATED;
+	const url = `${normalizeRegistryUrl(resolved.registry)}${require_npm_registry.encodeRegistryName(name)}`;
+	return require_npm_meta_slice.slicePackument(await resolved.http.json(url, {
+		headers: { Accept: accept },
+		retries: resolved.retries,
+		timeout: resolved.timeout
+	}));
+}
+/**
+* Resolve the persisted-stale + storm-control companions for a primary cache
+* instance, creating them lazily (under the default prefix) for a `TtlCache`
+* that wasn't created via `createNpmMetaCache`.
+*/
+function getCachePeers(cache) {
+	return cachePeers.get(cache) ?? registerCachePeers(cache, CACHE_PREFIX);
+}
+let defaultMetaCache;
+/**
+* The module-level default cache instance, created lazily on first use.
+*/
+function getDefaultMetaCache() {
+	if (defaultMetaCache === void 0) defaultMetaCache = createNpmMetaCache();
+	return defaultMetaCache;
+}
+/**
+* Fetch a package's packument, slice it down to `PackumentMetaSlim`, and
+* cache the result. Concurrent calls for the same (registry, name, variant)
+* dedupe to a single upstream request via the cache's `getOrFetch`. See the
+* file-level doc for the `force` / negative-cache / serve-stale-on-error
+* policies.
+*
+* @throws {PackumentNotFoundError} When the registry returns a definitive 404
+*   and no previously-good data exists for this key to serve instead.
+*/
+async function getPackumentSlim(name, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const cache = opts.cache ?? getDefaultMetaCache();
+	const registry = normalizeRegistryUrl(opts.registry ?? NPM_REGISTRY);
+	const variant = opts.variant ?? "abbreviated";
+	const retries = Math.min(opts.retries ?? DEFAULT_RETRIES, MAX_RETRIES);
+	const key = buildMetaCacheKey(registry, name, variant);
+	const { stale: staleCache, storm: stormCache } = getCachePeers(cache);
+	const fetchOptions = {
+		http: opts.http ?? { json: require_http_request_node.httpJson },
+		registry,
+		retries,
+		timeout: opts.timeout,
+		variant
+	};
+	if (opts.force) {
+		const cached = await cache.get(key);
+		if (cached?.kind === "hit" && Date.now() - cached.cachedAt <= FORCE_MIN_AGE_MS) return cloneMeta(cached.meta);
+		let result;
+		try {
+			result = await fetchAndCacheEntry(name, key, fetchOptions, staleCache);
+		} catch (e) {
+			const stale = await serveStaleOnFailure(staleCache, stormCache, key);
+			if (stale !== void 0) return cloneMeta(stale);
+			throw e;
+		}
+		await cache.set(key, result);
+		if (result.kind === "miss") throw new PackumentNotFoundError(name, result.status);
+		return cloneMeta(result.meta);
+	}
+	const storming = await stormCache.get(key);
+	if (storming !== void 0) return cloneMeta(storming);
+	const existing = await cache.get(key);
+	if (existing?.kind === "miss") {
+		if (Date.now() - existing.cachedAt <= NEGATIVE_TTL_MS && await staleCache.get(key) === void 0) throw new PackumentNotFoundError(name, existing.status);
+		await cache.delete(key);
+	}
+	let entry;
+	try {
+		entry = await cache.getOrFetch(key, () => fetchAndCacheEntry(name, key, fetchOptions, staleCache));
+	} catch (e) {
+		const stale = await serveStaleOnFailure(staleCache, stormCache, key);
+		if (stale !== void 0) return cloneMeta(stale);
+		throw e;
+	}
+	if (entry.kind === "miss") throw new PackumentNotFoundError(name, entry.status);
+	return cloneMeta(entry.meta);
+}
+/**
+* Look up the persisted last known-good value for `key`, if any — backed by
+* `STALE_TTL_MS` (7 days), independent of the primary cache's own TTL, and
+* readable from a fresh process. Returns a fresh clone so no two callers ever
+* share a reference to the same cached object.
+*/
+async function getStaleMeta(cache, key) {
+	const found = await getCachePeers(cache).stale.get(key);
+	return found === void 0 ? void 0 : cloneMeta(found);
+}
+/**
+* Normalize a registry base URL so two spellings of the same registry
+* collapse to one cache key and one request URL: lowercase the scheme+host,
+* and ensure exactly one trailing slash. Falls back to the input unchanged
+* when it isn't a parseable absolute URL.
+*/
+function normalizeRegistryUrl(registry) {
+	try {
+		const url = new require_primordials_url.URLCtor(registry);
+		return `${`${url.protocol}//${url.host}`.toLowerCase()}${url.pathname.endsWith("/") ? url.pathname : `${url.pathname}/`}${url.search}`;
+	} catch {
+		return registry;
+	}
+}
+/**
+* Create and register the persisted-stale + storm-control companion caches
+* for `cache` under `prefix`.
+*/
+function registerCachePeers(cache, prefix) {
+	const peers = {
+		stale: require_cache_ttl_store.createTtlCache({
+			prefix: `${prefix}-stale`,
+			ttl: STALE_TTL_MS
+		}),
+		storm: require_cache_ttl_store.createTtlCache({
+			prefix: `${prefix}-storm`,
+			ttl: STALE_SERVE_TTL_MS
+		})
+	};
+	cachePeers.set(cache, peers);
+	return peers;
+}
+/**
+* Persist `meta` as the last known-good value for `key`, independent of the
+* primary entry's own TTL/expiry.
+*/
+async function rememberStaleMeta(cache, key, meta) {
+	await getCachePeers(cache).stale.set(key, cloneMeta(meta));
+}
+/**
+* Serve-stale-on-error: look up the persisted last known-good value and, when
+* found, (re)write the storm-control marker so a burst of callers within
+* `STALE_SERVE_TTL_MS` is served without re-hitting a registry that just
+* failed.
+*/
+async function serveStaleOnFailure(staleCache, stormCache, key) {
+	const priorGood = await staleCache.get(key);
+	if (priorGood === void 0) return;
+	await stormCache.set(key, priorGood);
+	return priorGood;
+}
+
+//#endregion
+exports.PackumentNotFoundError = PackumentNotFoundError;
+exports.buildMetaCacheKey = buildMetaCacheKey;
+exports.cloneMeta = cloneMeta;
+exports.createNpmMetaCache = createNpmMetaCache;
+exports.fetchAndCacheEntry = fetchAndCacheEntry;
+exports.fetchPackumentSlim = fetchPackumentSlim;
+exports.getCachePeers = getCachePeers;
+exports.getDefaultMetaCache = getDefaultMetaCache;
+exports.getPackumentSlim = getPackumentSlim;
+exports.getStaleMeta = getStaleMeta;
+exports.normalizeRegistryUrl = normalizeRegistryUrl;
+exports.registerCachePeers = registerCachePeers;
+exports.rememberStaleMeta = rememberStaleMeta;
+exports.serveStaleOnFailure = serveStaleOnFailure;

package/dist/npm/meta-slice.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Pure slicing of a raw npm packument into the client's slim shapes — no
+ *   network, no cache. `sliceVersionMeta` handles one version's `dist` /
+ *   `_npmUser` fields; `slicePackument` wraps it with the top-level packument
+ *   fields (`name`, `distTags`, `time.created` / `time.modified`).
+ */
+import type { PackumentMetaSlim, PackumentVersionMetaSlim, RawPackument, RawPackumentVersion } from './meta-types';
+/**
+ * Slice one raw version entry into its `PackumentVersionMetaSlim` shape.
+ *
+ * `trustedPublisher` / `staged` are only set when `_npmUser` is present on the
+ * entry (i.e. the packument was fetched with `variant: 'full'`) — on the
+ * abbreviated variant, trust signals are unknown rather than `false`.
+ */
+export declare function sliceOneVersion(entry: RawPackumentVersion, publishedAt: string | undefined): PackumentVersionMetaSlim;
+/**
+ * Slice a raw packument into `PackumentMetaSlim` — the top-level fields the
+ * client keeps (`name`, `distTags` with a guaranteed `latest` key,
+ * `timeCreated` / `timeModified`, `lastSynced`) plus the per-version map from
+ * `sliceVersionMeta`.
+ */
+export declare function slicePackument(packument: RawPackument): PackumentMetaSlim;
+/**
+ * Slice every version entry in a raw packument into `PackumentVersionMetaSlim`
+ * records, keyed by version string.
+ */
+export declare function sliceVersionMeta(packument: RawPackument): Record<string, PackumentVersionMetaSlim>;

package/dist/npm/meta-slice.js

@@ -0,0 +1,68 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/npm/meta-slice.ts
+/**
+* Slice one raw version entry into its `PackumentVersionMetaSlim` shape.
+*
+* `trustedPublisher` / `staged` are only set when `_npmUser` is present on the
+* entry (i.e. the packument was fetched with `variant: 'full'`) — on the
+* abbreviated variant, trust signals are unknown rather than `false`.
+*/
+function sliceOneVersion(entry, publishedAt) {
+	const dist = entry.dist;
+	const npmUser = entry._npmUser;
+	const slim = { time: publishedAt ?? "" };
+	if (entry.deprecated !== void 0) slim.deprecated = entry.deprecated;
+	if (entry.engines !== void 0) slim.engines = entry.engines;
+	if (dist?.integrity !== void 0) slim.integrity = dist.integrity;
+	if (dist?.shasum !== void 0) slim.shasum = dist.shasum;
+	if (dist?.tarball !== void 0) slim.tarball = dist.tarball;
+	if (dist?.attestations !== void 0) slim.attestations = dist.attestations;
+	if (npmUser !== void 0) {
+		slim.trustedPublisher = !!npmUser.trustedPublisher;
+		slim.staged = !!npmUser.approver;
+	}
+	return slim;
+}
+/**
+* Slice a raw packument into `PackumentMetaSlim` — the top-level fields the
+* client keeps (`name`, `distTags` with a guaranteed `latest` key,
+* `timeCreated` / `timeModified`, `lastSynced`) plus the per-version map from
+* `sliceVersionMeta`.
+*/
+function slicePackument(packument) {
+	const rawDistTags = packument["dist-tags"] ?? {};
+	return {
+		distTags: {
+			latest: rawDistTags["latest"] ?? "",
+			...rawDistTags
+		},
+		lastSynced: Date.now(),
+		name: packument.name ?? "",
+		timeCreated: packument.time?.["created"],
+		timeModified: packument.time?.["modified"],
+		versions: sliceVersionMeta(packument)
+	};
+}
+/**
+* Slice every version entry in a raw packument into `PackumentVersionMetaSlim`
+* records, keyed by version string.
+*/
+function sliceVersionMeta(packument) {
+	const rawVersions = packument.versions ?? {};
+	const time = packument.time ?? {};
+	const result = {};
+	const versions = Object.keys(rawVersions);
+	for (let i = 0, { length } = versions; i < length; i += 1) {
+		const version = versions[i];
+		result[version] = sliceOneVersion(rawVersions[version], time[version]);
+	}
+	return result;
+}
+
+//#endregion
+exports.sliceOneVersion = sliceOneVersion;
+exports.slicePackument = slicePackument;
+exports.sliceVersionMeta = sliceVersionMeta;