@j0hanz/superfetch 2.0.0 → 2.0.1

package/dist/resources/cached-content-params.js

@@ -0,0 +1,36 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { isRecord } from '../utils/guards.js';
+export const CACHE_NAMESPACE = 'markdown';
+const HASH_PATTERN = /^[a-f0-9.]+$/i;
+export function resolveCacheParams(params) {
+    const parsed = requireRecordParams(params);
+    const namespace = requireParamString(parsed, 'namespace');
+    const urlHash = requireParamString(parsed, 'urlHash');
+    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return { namespace, urlHash };
+}
+function requireRecordParams(value) {
+    if (!isRecord(value)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return value;
+}
+function requireParamString(params, key) {
+    const raw = params[key];
+    const resolved = resolveStringParam(raw);
+    if (!resolved) {
+        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
+    }
+    return resolved;
+}
+function isValidNamespace(namespace) {
+    return namespace === CACHE_NAMESPACE;
+}
+function isValidHash(hash) {
+    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
+}
+function resolveStringParam(value) {
+    return typeof value === 'string' ? value : null;
+}

package/dist/resources/cached-content.js

@@ -4,10 +4,42 @@ import * as cache from '../services/cache.js';
 import { parseCacheKey, toResourceUri } from '../services/cache-keys.js';
 import { logWarn } from '../services/logger.js';
 import { parseCachedPayload, resolveCachedPayloadContent, } from '../utils/cached-payload.js';
-import { getErrorMessage } from '../utils/error-utils.js';
+import { getErrorMessage } from '../utils/error-details.js';
 import { isRecord } from '../utils/guards.js';
 const CACHE_NAMESPACE = 'markdown';
 const HASH_PATTERN = /^[a-f0-9.]+$/i;
+function resolveCacheParams(params) {
+    const parsed = requireRecordParams(params);
+    const namespace = requireParamString(parsed, 'namespace');
+    const urlHash = requireParamString(parsed, 'urlHash');
+    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return { namespace, urlHash };
+}
+function requireRecordParams(value) {
+    if (!isRecord(value)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return value;
+}
+function requireParamString(params, key) {
+    const raw = params[key];
+    const resolved = resolveStringParam(raw);
+    if (!resolved) {
+        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
+    }
+    return resolved;
+}
+function isValidNamespace(namespace) {
+    return namespace === CACHE_NAMESPACE;
+}
+function isValidHash(hash) {
+    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
+}
+function resolveStringParam(value) {
+    return typeof value === 'string' ? value : null;
+}
 function buildResourceEntry(namespace, urlHash) {
     return {
         name: `${namespace}:${urlHash}`,
@@ -42,29 +74,6 @@ export function registerCachedContentResource(server) {
     registerCacheContentResource(server);
     registerCacheUpdateSubscription(server);
 }
-function resolveCacheParams(params) {
-    const parsed = requireRecordParams(params);
-    const namespace = requireParamString(parsed, 'namespace');
-    const urlHash = requireParamString(parsed, 'urlHash');
-    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
-    }
-    return { namespace, urlHash };
-}
-function requireRecordParams(value) {
-    if (!isRecord(value)) {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
-    }
-    return value;
-}
-function requireParamString(params, key) {
-    const raw = params[key];
-    const resolved = resolveStringParam(raw);
-    if (!resolved) {
-        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
-    }
-    return resolved;
-}
 function buildCachedContentResponse(uri, cacheKey) {
     const cached = requireCacheEntry(cacheKey);
     return buildMarkdownContentResponse(uri, cached.content);
@@ -98,15 +107,6 @@ function registerCacheUpdateSubscription(server) {
         unsubscribe();
     };
 }
-function isValidNamespace(namespace) {
-    return namespace === CACHE_NAMESPACE;
-}
-function isValidHash(hash) {
-    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
-}
-function resolveStringParam(value) {
-    return typeof value === 'string' ? value : null;
-}
 function requireCacheEntry(cacheKey) {
     const cached = cache.get(cacheKey);
     if (!cached) {

package/dist/server.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { config } from './config/index.js';
-import { destroyAgents } from './services/fetcher/agents.js';
+import { destroyAgents } from './services/fetcher.js';
 import { logError, logInfo } from './services/logger.js';
 import { registerTools } from './tools/index.js';
 import { registerCachedContentResource } from './resources/cached-content.js';

package/dist/services/cache-events.d.ts

@@ -0,0 +1,8 @@
+import type { CacheKeyParts } from './cache-keys.js';
+export interface CacheUpdateEvent extends CacheKeyParts {
+    cacheKey: string;
+}
+type CacheUpdateListener = (event: CacheUpdateEvent) => void;
+export declare function onCacheUpdate(listener: CacheUpdateListener): () => void;
+export declare function notifyCacheUpdate(cacheKey: string): void;
+export {};

package/dist/services/cache-events.js

@@ -0,0 +1,19 @@
+import { parseCacheKey } from './cache-keys.js';
+const updateListeners = new Set();
+export function onCacheUpdate(listener) {
+    updateListeners.add(listener);
+    return () => {
+        updateListeners.delete(listener);
+    };
+}
+export function notifyCacheUpdate(cacheKey) {
+    if (updateListeners.size === 0)
+        return;
+    const parts = parseCacheKey(cacheKey);
+    if (!parts)
+        return;
+    const event = { cacheKey, ...parts };
+    for (const listener of updateListeners) {
+        listener(event);
+    }
+}

package/dist/services/cache.d.ts

@@ -1,14 +1,15 @@
 import type { CacheEntry } from '../config/types/content.js';
-import type { CacheKeyParts } from './cache-keys.js';
-interface CacheUpdateEvent extends CacheKeyParts {
+export interface CacheUpdateEvent {
     cacheKey: string;
+    namespace: string;
+    urlHash: string;
 }
+type CacheUpdateListener = (event: CacheUpdateEvent) => void;
+export declare function onCacheUpdate(listener: CacheUpdateListener): () => void;
 interface CacheEntryMetadata {
     url: string;
     title?: string;
 }
-type CacheUpdateListener = (event: CacheUpdateEvent) => void;
-export declare function onCacheUpdate(listener: CacheUpdateListener): () => void;
 export declare function get(cacheKey: string | null): CacheEntry | undefined;
 export declare function set(cacheKey: string | null, content: string, metadata: CacheEntryMetadata): void;
 export declare function keys(): readonly string[];

package/dist/services/cache.js

@@ -1,10 +1,28 @@
 import { setInterval as setIntervalPromise } from 'node:timers/promises';
 import { config } from '../config/index.js';
-import { getErrorMessage } from '../utils/error-utils.js';
+import { getErrorMessage } from '../utils/error-details.js';
 import { parseCacheKey } from './cache-keys.js';
 import { logWarn } from './logger.js';
 const contentCache = new Map();
 let cleanupController = null;
+const updateListeners = new Set();
+export function onCacheUpdate(listener) {
+    updateListeners.add(listener);
+    return () => {
+        updateListeners.delete(listener);
+    };
+}
+function notifyCacheUpdate(cacheKey) {
+    if (updateListeners.size === 0)
+        return;
+    const parts = parseCacheKey(cacheKey);
+    if (!parts)
+        return;
+    const event = { cacheKey, ...parts };
+    for (const listener of updateListeners) {
+        listener(event);
+    }
+}
 function startCleanupLoop() {
     if (cleanupController)
         return;
@@ -17,15 +35,14 @@ function startCleanupLoop() {
 }
 async function runCleanupLoop(signal) {
     const intervalMs = Math.floor(config.cache.ttl * 1000);
-    for await (const _ of setIntervalPromise(intervalMs, undefined, {
+    for await (const getNow of setIntervalPromise(intervalMs, Date.now, {
         signal,
         ref: false,
     })) {
-        enforceCacheLimits();
+        enforceCacheLimits(getNow());
     }
 }
-function enforceCacheLimits() {
-    const now = Date.now();
+function enforceCacheLimits(now) {
     for (const [key, item] of contentCache.entries()) {
         if (now > item.expiresAt) {
             contentCache.delete(key);
@@ -33,21 +50,6 @@ function enforceCacheLimits() {
     }
     trimCacheToMaxKeys();
 }
-const updateListeners = new Set();
-export function onCacheUpdate(listener) {
-    updateListeners.add(listener);
-    return () => {
-        updateListeners.delete(listener);
-    };
-}
-function emitCacheUpdate(cacheKey) {
-    const parts = parseCacheKey(cacheKey);
-    if (!parts)
-        return;
-    for (const listener of updateListeners) {
-        listener({ cacheKey, ...parts });
-    }
-}
 export function get(cacheKey) {
     if (!isCacheReadable(cacheKey))
         return undefined;
@@ -69,16 +71,17 @@ function runCacheOperation(cacheKey, message, operation) {
     }
 }
 function readCacheEntry(cacheKey) {
-    return readCacheItem(cacheKey)?.entry;
+    const now = Date.now();
+    return readCacheItem(cacheKey, now)?.entry;
 }
-function isExpired(item) {
-    return Date.now() > item.expiresAt;
+function isExpired(item, now) {
+    return now > item.expiresAt;
 }
-function readCacheItem(cacheKey) {
+function readCacheItem(cacheKey, now) {
     const item = contentCache.get(cacheKey);
     if (!item)
         return undefined;
-    if (isExpired(item)) {
+    if (isExpired(item, now)) {
         contentCache.delete(cacheKey);
         return undefined;
     }
@@ -89,8 +92,15 @@ export function set(cacheKey, content, metadata) {
         return;
     runCacheOperation(cacheKey, 'Cache set error', () => {
         startCleanupLoop();
-        const entry = buildCacheEntry(content, metadata);
-        persistCacheEntry(cacheKey, entry);
+        const now = Date.now();
+        const expiresAtMs = now + config.cache.ttl * 1000;
+        const entry = buildCacheEntry({
+            content,
+            metadata,
+            fetchedAtMs: now,
+            expiresAtMs,
+        });
+        persistCacheEntry(cacheKey, entry, expiresAtMs);
     });
 }
 export function keys() {
@@ -99,20 +109,19 @@ export function keys() {
 export function isEnabled() {
     return config.cache.enabled;
 }
-function buildCacheEntry(content, metadata) {
+function buildCacheEntry({ content, metadata, fetchedAtMs, expiresAtMs, }) {
     return {
         url: metadata.url,
         content,
-        fetchedAt: new Date().toISOString(),
-        expiresAt: new Date(resolveExpiryTimestamp()).toISOString(),
+        fetchedAt: new Date(fetchedAtMs).toISOString(),
+        expiresAt: new Date(expiresAtMs).toISOString(),
         ...(metadata.title === undefined ? {} : { title: metadata.title }),
     };
 }
-function persistCacheEntry(cacheKey, entry) {
-    const expiresAt = resolveExpiryTimestamp();
-    contentCache.set(cacheKey, { entry, expiresAt });
+function persistCacheEntry(cacheKey, entry, expiresAtMs) {
+    contentCache.set(cacheKey, { entry, expiresAt: expiresAtMs });
     trimCacheToMaxKeys();
-    emitCacheUpdate(cacheKey);
+    notifyCacheUpdate(cacheKey);
 }
 function trimCacheToMaxKeys() {
     if (contentCache.size <= config.cache.maxKeys)
@@ -120,19 +129,14 @@ function trimCacheToMaxKeys() {
     removeOldestEntries(contentCache.size - config.cache.maxKeys);
 }
 function removeOldestEntries(count) {
-    if (count <= 0)
-        return;
-    let removed = 0;
-    for (const key of contentCache.keys()) {
-        contentCache.delete(key);
-        removed += 1;
-        if (removed >= count)
-            return;
+    const iterator = contentCache.keys();
+    for (let removed = 0; removed < count; removed += 1) {
+        const next = iterator.next();
+        if (next.done)
+            break;
+        contentCache.delete(next.value);
     }
 }
-function resolveExpiryTimestamp() {
-    return Date.now() + config.cache.ttl * 1000;
-}
 function logCacheError(message, cacheKey, error) {
     logWarn(message, {
         key: cacheKey.length > 100 ? cacheKey.slice(0, 100) : cacheKey,

package/dist/services/extractor.js

@@ -1,6 +1,6 @@
 import { parseHTML } from 'linkedom';
 import { Readability } from '@mozilla/readability';
-import { getErrorMessage } from '../utils/error-utils.js';
+import { getErrorMessage } from '../utils/error-details.js';
 import { isRecord } from '../utils/guards.js';
 import { truncateHtml } from '../utils/html-truncator.js';
 import { logError, logInfo, logWarn } from './logger.js';
@@ -8,21 +8,21 @@ import { extractMetadata } from './metadata-collector.js';
 function isReadabilityCompatible(doc) {
     if (!isRecord(doc))
         return false;
-    if (!('documentElement' in doc))
-        return false;
-    if (typeof doc.querySelectorAll !== 'function')
-        return false;
-    if (typeof doc.querySelector !== 'function')
-        return false;
-    return true;
+    return hasDocumentElement(doc) && hasQuerySelectors(doc);
+}
+function hasDocumentElement(record) {
+    return 'documentElement' in record;
+}
+function hasQuerySelectors(record) {
+    return (typeof record.querySelectorAll === 'function' &&
+        typeof record.querySelector === 'function');
 }
 function extractArticle(document) {
     if (!isReadabilityCompatible(document)) {
         logWarn('Document not compatible with Readability');
         return null;
     }
-    const parsed = parseReadabilityArticle(document);
-    return parsed ? mapReadabilityResult(parsed) : null;
+    return mapParsedArticle(parseReadabilityArticle(document));
 }
 function parseReadabilityArticle(document) {
     try {
@@ -31,31 +31,38 @@ function parseReadabilityArticle(document) {
         return reader.parse();
     }
     catch (error) {
-        logError('Failed to extract article with Readability', error instanceof Error ? error : undefined);
+        logError('Failed to extract article with Readability', asError(error));
         return null;
     }
 }
+function asError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return undefined;
+}
+function mapParsedArticle(parsed) {
+    return parsed ? mapReadabilityResult(parsed) : null;
+}
 function mapReadabilityResult(parsed) {
-    const article = {
+    return {
         content: parsed.content ?? '',
         textContent: parsed.textContent ?? '',
+        ...buildOptionalArticleFields(parsed),
     };
-    const title = toOptional(parsed.title);
-    if (title !== undefined)
-        article.title = title;
-    const byline = toOptional(parsed.byline);
-    if (byline !== undefined)
-        article.byline = byline;
-    const excerpt = toOptional(parsed.excerpt);
-    if (excerpt !== undefined)
-        article.excerpt = excerpt;
-    const siteName = toOptional(parsed.siteName);
-    if (siteName !== undefined)
-        article.siteName = siteName;
-    return article;
-}
-function toOptional(value) {
-    return value ?? undefined;
+}
+function buildOptionalArticleFields(parsed) {
+    const optional = {};
+    addOptionalField(optional, 'title', parsed.title);
+    addOptionalField(optional, 'byline', parsed.byline);
+    addOptionalField(optional, 'excerpt', parsed.excerpt);
+    addOptionalField(optional, 'siteName', parsed.siteName);
+    return optional;
+}
+function addOptionalField(target, key, value) {
+    if (value == null)
+        return;
+    target[key] = value;
 }
 export function extractContent(html, url, options = { extractArticle: true }) {
     if (!isValidInput(html, url)) {
@@ -69,7 +76,7 @@ function tryExtractContent(html, url, options) {
         applyBaseUri(document, url);
         const metadata = extractMetadata(document);
         return {
-            article: options.extractArticle ? extractArticle(document) : null,
+            article: resolveArticleExtraction(document, options.extractArticle),
             metadata,
         };
     }
@@ -79,15 +86,19 @@ function tryExtractContent(html, url, options) {
     }
 }
 function isValidInput(html, url) {
-    if (!html || typeof html !== 'string') {
-        logWarn('extractContent called with invalid HTML input');
-        return false;
-    }
-    if (!url || typeof url !== 'string') {
-        logWarn('extractContent called with invalid URL');
-        return false;
-    }
-    return true;
+    return (validateRequiredString(html, 'extractContent called with invalid HTML input') && validateRequiredString(url, 'extractContent called with invalid URL'));
+}
+function validateRequiredString(value, message) {
+    if (isNonEmptyString(value))
+        return true;
+    logWarn(message);
+    return false;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function resolveArticleExtraction(document, shouldExtract) {
+    return shouldExtract ? extractArticle(document) : null;
 }
 function applyBaseUri(document, url) {
     try {

package/dist/services/fetcher/agents.js

@@ -1,7 +1,7 @@
 import dns from 'node:dns';
 import os from 'node:os';
 import { Agent } from 'undici';
-import { createErrorWithCode } from '../../utils/error-utils.js';
+import { createErrorWithCode } from '../../utils/error-details.js';
 import { isRecord } from '../../utils/guards.js';
 import { handleLookupResult } from './dns-selection.js';
 const DNS_LOOKUP_TIMEOUT_MS = 5000;

package/dist/services/fetcher/dns-selection.js

@@ -1,4 +1,4 @@
-import { createErrorWithCode } from '../../utils/error-utils.js';
+import { createErrorWithCode } from '../../utils/error-details.js';
 import { isBlockedIp } from '../../utils/url-validator.js';
 function normalizeLookupResults(addresses, family) {
     if (Array.isArray(addresses)) {

package/dist/services/fetcher/interceptors.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import diagnosticsChannel from 'node:diagnostics_channel';
 import { performance } from 'node:perf_hooks';
-import { isSystemError } from '../../utils/error-utils.js';
+import { isSystemError } from '../../utils/error-details.js';
 import { logDebug, logError, logWarn } from '../logger.js';
 const fetchChannel = diagnosticsChannel.channel('superfetch.fetch');
 function redactUrl(rawUrl) {
@@ -27,7 +27,14 @@ function publishFetchEvent(event) {
         // Avoid crashing the publisher if a subscriber throws.
     }
 }
-function publishAndLogFetchStart(context) {
+export function startFetchTelemetry(url, method) {
+    const safeUrl = redactUrl(url);
+    const context = {
+        requestId: randomUUID(),
+        startTime: performance.now(),
+        url: safeUrl,
+        method: method.toUpperCase(),
+    };
     publishFetchEvent({
         v: 1,
         type: 'start',
@@ -40,65 +47,40 @@ function publishAndLogFetchStart(context) {
         method: context.method,
         url: context.url,
     });
-}
-export function startFetchTelemetry(url, method) {
-    const safeUrl = redactUrl(url);
-    const context = {
-        requestId: randomUUID(),
-        startTime: performance.now(),
-        url: safeUrl,
-        method: method.toUpperCase(),
-    };
-    publishAndLogFetchStart(context);
     return context;
 }
 export function recordFetchResponse(context, response, contentSize) {
     const duration = performance.now() - context.startTime;
-    publishFetchEnd(context, response.status, duration);
-    logDebug('HTTP Response', {
-        requestId: context.requestId,
-        status: response.status,
-        url: context.url,
-        ...buildResponseMeta(response, contentSize, duration),
-    });
-    logSlowRequestIfNeeded(context, duration);
-}
-function publishFetchEnd(context, status, duration) {
+    const durationLabel = `${Math.round(duration)}ms`;
     publishFetchEvent({
         v: 1,
         type: 'end',
         requestId: context.requestId,
-        status,
+        status: response.status,
         duration,
     });
-}
-function buildResponseMeta(response, contentSize, duration) {
-    const contentLength = response.headers.get('content-length') ?? contentSize?.toString();
-    const meta = {
-        duration: `${Math.round(duration)}ms`,
-    };
     const contentType = response.headers.get('content-type');
-    if (contentType !== null) {
-        meta.contentType = contentType;
-    }
-    if (contentLength !== undefined) {
-        meta.size = contentLength;
-    }
-    return meta;
-}
-function logSlowRequestIfNeeded(context, duration) {
-    if (duration <= 5000)
-        return;
-    logWarn('Slow HTTP request detected', {
+    const contentLength = response.headers.get('content-length') ??
+        (contentSize === undefined ? undefined : String(contentSize));
+    logDebug('HTTP Response', {
         requestId: context.requestId,
+        status: response.status,
         url: context.url,
-        duration: `${Math.round(duration)}ms`,
+        duration: durationLabel,
+        ...(contentType ? { contentType } : {}),
+        ...(contentLength ? { size: contentLength } : {}),
     });
+    if (duration > 5000) {
+        logWarn('Slow HTTP request detected', {
+            requestId: context.requestId,
+            url: context.url,
+            duration: durationLabel,
+        });
+    }
 }
-function normalizeError(error) {
-    return error instanceof Error ? error : new Error(String(error));
-}
-function buildFetchErrorEvent(context, err, duration, status) {
+export function recordFetchError(context, error, status) {
+    const duration = performance.now() - context.startTime;
+    const err = error instanceof Error ? error : new Error(String(error));
     const event = {
         v: 1,
         type: 'error',
@@ -107,10 +89,6 @@ function buildFetchErrorEvent(context, err, duration, status) {
         error: err.message,
         duration,
     };
-    addOptionalErrorFields(event, err, status);
-    return event;
-}
-function addOptionalErrorFields(event, err, status) {
     const code = isSystemError(err) ? err.code : undefined;
     if (code !== undefined) {
         event.code = code;
@@ -118,17 +96,8 @@ function addOptionalErrorFields(event, err, status) {
     if (status !== undefined) {
         event.status = status;
     }
-}
-function selectErrorLogger(status) {
-    return status === 429 ? logWarn : logError;
-}
-export function recordFetchError(context, error, status) {
-    const duration = performance.now() - context.startTime;
-    const err = normalizeError(error);
-    const event = buildFetchErrorEvent(context, err, duration, status);
     publishFetchEvent(event);
-    const log = selectErrorLogger(status);
-    const code = isSystemError(err) ? err.code : undefined;
+    const log = status === 429 ? logWarn : logError;
     log('HTTP Request Error', {
         requestId: context.requestId,
         url: context.url,