@node-cli/bundlecheck 1.2.0 → 1.4.0

package/dist/index.js

@@ -0,0 +1,229 @@
+/**
+ * @node-cli/bundlecheck - Library API
+ *
+ * Programmatic interface for analyzing npm package bundle sizes.
+ *
+ */ import { checkBundleSize, formatBytes, getExternals, parsePackageSpecifier } from "./bundler.js";
+import { getCachedResult, normalizeCacheKey, setCachedResult } from "./cache.js";
+import { normalizePlatform, TREND_VERSION_COUNT } from "./defaults.js";
+import { analyzeTrend, selectTrendVersions } from "./trend.js";
+import { fetchPackageVersions as fetchVersions } from "./versions.js";
+/**
+ * =============================================================================
+ * Library Functions
+ * =============================================================================
+ */ /**
+ * Get bundle size statistics for an npm package.
+ *
+ * @example
+ * ```js
+ * import { getBundleStats } from "@node-cli/bundlecheck";
+ *
+ * const stats = await getBundleStats({
+ *   package: "@mantine/core@7.0.0",
+ *   exports: ["Button", "Input"],
+ * });
+ *
+ * console.log(stats.gzipSizeFormatted); // "12.3 kB"
+ * ```
+ *
+ */ export async function getBundleStats(options) {
+    const { package: packageName, exports: exportsList, external: additionalExternals, noExternal, gzipLevel = 5, registry, platform: platformOption = "auto", force = false } = options;
+    // Normalize platform.
+    const platform = normalizePlatform(platformOption === "auto" ? undefined : platformOption);
+    // Parse package specifier.
+    const { name: baseName, version: requestedVersion } = parsePackageSpecifier(packageName);
+    // Resolve "latest" to actual version for cache key.
+    let resolvedVersion = requestedVersion;
+    if (requestedVersion === "latest") {
+        const { tags } = await fetchVersions({
+            packageName: baseName,
+            registry
+        });
+        resolvedVersion = tags.latest || requestedVersion;
+    }
+    // Compute externals for cache key.
+    const externals = getExternals(baseName, additionalExternals, noExternal);
+    // Build cache key.
+    const cacheKey = normalizeCacheKey({
+        packageName: baseName,
+        version: resolvedVersion,
+        exports: exportsList,
+        platform,
+        gzipLevel,
+        externals,
+        noExternal: noExternal ?? false
+    });
+    // Check cache (unless force is set).
+    if (!force) {
+        const cached = getCachedResult(cacheKey);
+        if (cached) {
+            return formatBundleStats(cached, true);
+        }
+    }
+    // Perform the analysis.
+    const result = await checkBundleSize({
+        packageName,
+        exports: exportsList,
+        additionalExternals,
+        noExternal,
+        gzipLevel,
+        registry,
+        platform
+    });
+    // Store in cache.
+    setCachedResult(cacheKey, result);
+    return formatBundleStats(result, false);
+}
+/**
+ * Get bundle size trend across multiple versions of a package.
+ *
+ * @example
+ * ```js
+ * import { getBundleTrend } from "@node-cli/bundlecheck";
+ *
+ * const trend = await getBundleTrend({
+ *   package: "@mantine/core",
+ *   versionCount: 5,
+ * });
+ *
+ * console.log(trend.change?.rawDiffFormatted); // "+5.2 kB"
+ * ```
+ *
+ */ export async function getBundleTrend(options) {
+    const { package: packageName, versionCount = TREND_VERSION_COUNT, exports: exportsList, external: additionalExternals, noExternal, gzipLevel, registry, platform: platformOption = "auto", force = false } = options;
+    // Normalize platform.
+    const platform = normalizePlatform(platformOption === "auto" ? undefined : platformOption);
+    // Parse package name (ignore version if provided).
+    const { name: baseName, subpath } = parsePackageSpecifier(packageName);
+    const fullPackagePath = subpath ? `${baseName}/${subpath}` : baseName;
+    // Fetch available versions.
+    const { versions } = await fetchVersions({
+        packageName: baseName,
+        registry
+    });
+    if (versions.length === 0) {
+        throw new Error(`No versions found for package: ${baseName}`);
+    }
+    // Select versions for trend.
+    const trendVersions = selectTrendVersions(versions, versionCount);
+    // Analyze all versions (silently - no console output).
+    const results = await analyzeTrend({
+        packageName: fullPackagePath,
+        versions: trendVersions,
+        exports: exportsList,
+        additionalExternals,
+        noExternal,
+        gzipLevel,
+        boring: true,
+        registry,
+        platform,
+        force
+    });
+    if (results.length === 0) {
+        throw new Error(`Failed to analyze any versions for package: ${baseName}`);
+    }
+    // Format results.
+    const formattedVersions = results.map((r)=>({
+            version: r.version,
+            rawSize: r.rawSize,
+            gzipSize: r.gzipSize,
+            rawSizeFormatted: formatBytes(r.rawSize),
+            gzipSizeFormatted: r.gzipSize !== null ? formatBytes(r.gzipSize) : null
+        }));
+    // Calculate change between oldest and newest.
+    let change = null;
+    if (results.length > 1) {
+        const newest = results[0];
+        const oldest = results[results.length - 1];
+        const rawDiff = newest.rawSize - oldest.rawSize;
+        // Handle division by zero: if oldest size is 0, percent is null.
+        const rawPercent = oldest.rawSize === 0 ? null : rawDiff / oldest.rawSize * 100;
+        let gzipDiff = null;
+        let gzipPercent = null;
+        let gzipDiffFormatted = null;
+        if (newest.gzipSize !== null && oldest.gzipSize !== null) {
+            gzipDiff = newest.gzipSize - oldest.gzipSize;
+            // Handle division by zero: if oldest size is 0, percent is null.
+            gzipPercent = oldest.gzipSize === 0 ? null : gzipDiff / oldest.gzipSize * 100;
+            gzipDiffFormatted = gzipDiff >= 0 ? `+${formatBytes(gzipDiff)}` : `-${formatBytes(Math.abs(gzipDiff))}`;
+        }
+        change = {
+            fromVersion: oldest.version,
+            toVersion: newest.version,
+            rawDiff,
+            rawPercent: rawPercent !== null ? Number.parseFloat(rawPercent.toFixed(1)) : null,
+            rawDiffFormatted: rawDiff >= 0 ? `+${formatBytes(rawDiff)}` : `-${formatBytes(Math.abs(rawDiff))}`,
+            gzipDiff,
+            gzipPercent: gzipPercent !== null ? Number.parseFloat(gzipPercent.toFixed(1)) : null,
+            gzipDiffFormatted
+        };
+    }
+    return {
+        packageName: fullPackagePath,
+        versions: formattedVersions,
+        change
+    };
+}
+/**
+ * Get available versions for an npm package.
+ *
+ * @example
+ * ```js
+ * import { getPackageVersions } from "@node-cli/bundlecheck";
+ *
+ * const { versions, tags } = await getPackageVersions({
+ *   package: "@mantine/core",
+ * });
+ *
+ * console.log(tags.latest); // "7.0.0"
+ * ```
+ *
+ */ export async function getPackageVersions(options) {
+    const { package: packageName, registry } = options;
+    const result = await fetchVersions({
+        packageName,
+        registry
+    });
+    return {
+        versions: result.versions,
+        tags: result.tags
+    };
+}
+/**
+ * =============================================================================
+ * Re-exports for advanced usage
+ * =============================================================================
+ */ /**
+ * - Format bytes to human-readable string (e.g., 1024 → "1 kB").
+ * - Parse a package specifier (e.g., "@scope/name@1.0.0" → { name, version,
+ * subpath }).
+ */ export { formatBytes, parsePackageSpecifier } from "./bundler.js";
+/**
+ * - Clear the bundle cache.
+ * - Get the number of cached entries.
+ */ export { clearCache, getCacheCount } from "./cache.js";
+/**
+ * =============================================================================
+ * Internal Helpers
+ * =============================================================================
+ */ /**
+ * Format a BundleResult into a BundleStats object.
+ */ function formatBundleStats(result, fromCache) {
+    return {
+        packageName: result.packageName,
+        packageVersion: result.packageVersion,
+        exports: result.exports,
+        rawSize: result.rawSize,
+        gzipSize: result.gzipSize,
+        gzipLevel: result.gzipLevel,
+        externals: result.externals,
+        dependencies: result.dependencies,
+        platform: result.platform,
+        rawSizeFormatted: formatBytes(result.rawSize),
+        gzipSizeFormatted: result.gzipSize !== null ? formatBytes(result.gzipSize) : null,
+        fromCache
+    };
+}
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @node-cli/bundlecheck - Library API\n *\n * Programmatic interface for analyzing npm package bundle sizes.\n *\n */\n\nimport {\n\ttype BundleResult,\n\tcheckBundleSize,\n\tformatBytes,\n\tgetExternals,\n\tparsePackageSpecifier,\n} from \"./bundler.js\";\nimport {\n\tgetCachedResult,\n\tnormalizeCacheKey,\n\tsetCachedResult,\n} from \"./cache.js\";\nimport { normalizePlatform, TREND_VERSION_COUNT } from \"./defaults.js\";\nimport { analyzeTrend, selectTrendVersions } from \"./trend.js\";\nimport { fetchPackageVersions as fetchVersions } from \"./versions.js\";\n\n/**\n * =============================================================================\n * Types\n * =============================================================================\n */\n\n/**\n * Options for getting bundle stats of a single package.\n */\nexport type GetBundleStatsOptions = {\n\t/**\n\t * Package name with optional version (e.g., \"@mantine/core\" or\n\t * \"@mantine/core@7.0.0\").\n\t */\n\tpackage: string;\n\t/**\n\t * Specific exports to measure (e.g., [\"Button\", \"Input\"]).\n\t */\n\texports?: string[];\n\t/**\n\t * Additional packages to mark as external (not bundled).\n\t */\n\texternal?: string[];\n\t/**\n\t * Bundle everything including default externals (react, react-dom).\n\t */\n\tnoExternal?: boolean;\n\t/**\n\t * Gzip compression level (1-9, default 5).\n\t */\n\tgzipLevel?: number;\n\t/**\n\t * Custom npm registry URL.\n\t */\n\tregistry?: string;\n\t/**\n\t * Target platform: \"browser\", \"node\", or \"auto\" (default: \"auto\" - auto-detect\n\t * from package.json).\n\t */\n\tplatform?: \"browser\" | \"node\" | \"auto\";\n\t/**\n\t * Bypass cache and force re-analysis.\n\t */\n\tforce?: boolean;\n};\n\n/**\n * Result from getBundleStats.\n */\nexport type BundleStats = {\n\t/**\n\t * Display name of the package (may include subpath).\n\t */\n\tpackageName: string;\n\t/**\n\t * Resolved package version.\n\t */\n\tpackageVersion: string;\n\t/**\n\t * Exports that were analyzed.\n\t */\n\texports: string[];\n\t/**\n\t * Raw (minified) bundle size in bytes.\n\t */\n\trawSize: number;\n\t/**\n\t * Gzipped bundle size in bytes (null for node platform).\n\t */\n\tgzipSize: number | null;\n\t/**\n\t * Gzip compression level used.\n\t */\n\tgzipLevel: number;\n\t/**\n\t * Packages marked as external (not included in bundle).\n\t */\n\texternals: string[];\n\t/**\n\t * Package dependencies.\n\t */\n\tdependencies: string[];\n\t/**\n\t * Target platform used for bundling.\n\t */\n\tplatform: \"browser\" | \"node\";\n\t/**\n\t * Human-readable raw size (e.g., \"45.2 kB\").\n\t */\n\trawSizeFormatted: string;\n\t/**\n\t * Human-readable gzip size (e.g., \"12.3 kB\") or null.\n\t */\n\tgzipSizeFormatted: string | null;\n\t/**\n\t * Whether the result was retrieved from cache.\n\t */\n\tfromCache: boolean;\n};\n\n/**\n * Options for getting bundle size trend across versions.\n */\nexport type GetBundleTrendOptions = {\n\t/**\n\t * Package name (e.g., \"@mantine/core\") - version is ignored if provided.\n\t */\n\tpackage: string;\n\t/**\n\t * Number of versions to analyze (default 5).\n\t */\n\tversionCount?: number;\n\t/**\n\t * Specific exports to measure (e.g., [\"Button\", \"Input\"]).\n\t */\n\texports?: string[];\n\t/**\n\t * Additional packages to mark as external (not bundled).\n\t */\n\texternal?: string[];\n\t/**\n\t * Bundle everything including default externals (react, react-dom).\n\t */\n\tnoExternal?: boolean;\n\t/**\n\t * Gzip compression level (1-9, default 5).\n\t */\n\tgzipLevel?: number;\n\t/**\n\t * Custom npm registry URL.\n\t */\n\tregistry?: string;\n\t/**\n\t * Target platform: \"browser\", \"node\", or \"auto\" (default: \"auto\" - auto-detect\n\t * from package.json).\n\t */\n\tplatform?: \"browser\" | \"node\" | \"auto\";\n\t/**\n\t * Bypass cache and force re-analysis.\n\t */\n\tforce?: boolean;\n};\n\n/**\n * Single version result in trend analysis.\n */\nexport type TrendVersionResult = {\n\t/**\n\t * Package version.\n\t */\n\tversion: string;\n\t/**\n\t * Raw (minified) bundle size in bytes.\n\t */\n\trawSize: number;\n\t/**\n\t * Gzipped bundle size in bytes (null for node platform).\n\t */\n\tgzipSize: number | null;\n\t/**\n\t * Human-readable raw size (e.g., \"45.2 kB\").\n\t */\n\trawSizeFormatted: string;\n\t/**\n\t * Human-readable gzip size (e.g., \"12.3 kB\") or null.\n\t */\n\tgzipSizeFormatted: string | null;\n};\n\n/**\n * Size change information between oldest and newest versions.\n */\nexport type TrendChange = {\n\t/**\n\t * Oldest version analyzed.\n\t */\n\tfromVersion: string;\n\t/**\n\t * Newest version analyzed.\n\t */\n\ttoVersion: string;\n\t/**\n\t * Raw size difference in bytes (positive = increase, negative = decrease).\n\t */\n\trawDiff: number;\n\t/**\n\t * Raw size percentage change (null if oldest size was 0).\n\t */\n\trawPercent: number | null;\n\t/**\n\t * Human-readable raw size change (e.g., \"+5.2 kB\" or \"-1.3 kB\").\n\t */\n\trawDiffFormatted: string;\n\t/**\n\t * Gzip size difference in bytes (null if not applicable).\n\t */\n\tgzipDiff: number | null;\n\t/**\n\t * Gzip size percentage change (null if not applicable or oldest size was 0).\n\t */\n\tgzipPercent: number | null;\n\t/**\n\t * Human-readable gzip size change (e.g., \"+1.5 kB\" or \"-0.8 kB\") or null.\n\t */\n\tgzipDiffFormatted: string | null;\n};\n\n/**\n * Result from getBundleTrend.\n */\nexport type BundleTrend = {\n\t/**\n\t * Package name.\n\t */\n\tpackageName: string;\n\t/**\n\t * Results for each version analyzed (newest first).\n\t */\n\tversions: TrendVersionResult[];\n\t/**\n\t * Size change between oldest and newest versions (null if only one version).\n\t */\n\tchange: TrendChange | null;\n};\n\n/**\n * Options for fetching package versions.\n */\nexport type GetPackageVersionsOptions = {\n\t/**\n\t * Package name (e.g., \"@mantine/core\").\n\t */\n\tpackage: string;\n\t/**\n\t * Custom npm registry URL.\n\t */\n\tregistry?: string;\n};\n\n/**\n * Result from getPackageVersions.\n */\nexport type PackageVersions = {\n\t/**\n\t * All available versions (sorted newest first).\n\t */\n\tversions: string[];\n\t/**\n\t * Distribution tags (e.g., { latest: \"7.0.0\", next: \"8.0.0-beta.1\" }).\n\t */\n\ttags: Record<string, string>;\n};\n\n/**\n * =============================================================================\n * Library Functions\n * =============================================================================\n */\n\n/**\n * Get bundle size statistics for an npm package.\n *\n * @example\n * ```js\n * import { getBundleStats } from \"@node-cli/bundlecheck\";\n *\n * const stats = await getBundleStats({\n *   package: \"@mantine/core@7.0.0\",\n *   exports: [\"Button\", \"Input\"],\n * });\n *\n * console.log(stats.gzipSizeFormatted); // \"12.3 kB\"\n * ```\n *\n */\nexport async function getBundleStats(\n\toptions: GetBundleStatsOptions,\n): Promise<BundleStats> {\n\tconst {\n\t\tpackage: packageName,\n\t\texports: exportsList,\n\t\texternal: additionalExternals,\n\t\tnoExternal,\n\t\tgzipLevel = 5,\n\t\tregistry,\n\t\tplatform: platformOption = \"auto\",\n\t\tforce = false,\n\t} = options;\n\n\t// Normalize platform.\n\tconst platform = normalizePlatform(\n\t\tplatformOption === \"auto\" ? undefined : platformOption,\n\t);\n\n\t// Parse package specifier.\n\tconst { name: baseName, version: requestedVersion } =\n\t\tparsePackageSpecifier(packageName);\n\n\t// Resolve \"latest\" to actual version for cache key.\n\tlet resolvedVersion = requestedVersion;\n\tif (requestedVersion === \"latest\") {\n\t\tconst { tags } = await fetchVersions({\n\t\t\tpackageName: baseName,\n\t\t\tregistry,\n\t\t});\n\t\tresolvedVersion = tags.latest || requestedVersion;\n\t}\n\n\t// Compute externals for cache key.\n\tconst externals = getExternals(baseName, additionalExternals, noExternal);\n\n\t// Build cache key.\n\tconst cacheKey = normalizeCacheKey({\n\t\tpackageName: baseName,\n\t\tversion: resolvedVersion,\n\t\texports: exportsList,\n\t\tplatform,\n\t\tgzipLevel,\n\t\texternals,\n\t\tnoExternal: noExternal ?? false,\n\t});\n\n\t// Check cache (unless force is set).\n\tif (!force) {\n\t\tconst cached = getCachedResult(cacheKey);\n\t\tif (cached) {\n\t\t\treturn formatBundleStats(cached, true);\n\t\t}\n\t}\n\n\t// Perform the analysis.\n\tconst result = await checkBundleSize({\n\t\tpackageName,\n\t\texports: exportsList,\n\t\tadditionalExternals,\n\t\tnoExternal,\n\t\tgzipLevel,\n\t\tregistry,\n\t\tplatform,\n\t});\n\n\t// Store in cache.\n\tsetCachedResult(cacheKey, result);\n\n\treturn formatBundleStats(result, false);\n}\n\n/**\n * Get bundle size trend across multiple versions of a package.\n *\n * @example\n * ```js\n * import { getBundleTrend } from \"@node-cli/bundlecheck\";\n *\n * const trend = await getBundleTrend({\n *   package: \"@mantine/core\",\n *   versionCount: 5,\n * });\n *\n * console.log(trend.change?.rawDiffFormatted); // \"+5.2 kB\"\n * ```\n *\n */\nexport async function getBundleTrend(\n\toptions: GetBundleTrendOptions,\n): Promise<BundleTrend> {\n\tconst {\n\t\tpackage: packageName,\n\t\tversionCount = TREND_VERSION_COUNT,\n\t\texports: exportsList,\n\t\texternal: additionalExternals,\n\t\tnoExternal,\n\t\tgzipLevel,\n\t\tregistry,\n\t\tplatform: platformOption = \"auto\",\n\t\tforce = false,\n\t} = options;\n\n\t// Normalize platform.\n\tconst platform = normalizePlatform(\n\t\tplatformOption === \"auto\" ? undefined : platformOption,\n\t);\n\n\t// Parse package name (ignore version if provided).\n\tconst { name: baseName, subpath } = parsePackageSpecifier(packageName);\n\tconst fullPackagePath = subpath ? `${baseName}/${subpath}` : baseName;\n\n\t// Fetch available versions.\n\tconst { versions } = await fetchVersions({\n\t\tpackageName: baseName,\n\t\tregistry,\n\t});\n\n\tif (versions.length === 0) {\n\t\tthrow new Error(`No versions found for package: ${baseName}`);\n\t}\n\n\t// Select versions for trend.\n\tconst trendVersions = selectTrendVersions(versions, versionCount);\n\n\t// Analyze all versions (silently - no console output).\n\tconst results = await analyzeTrend({\n\t\tpackageName: fullPackagePath,\n\t\tversions: trendVersions,\n\t\texports: exportsList,\n\t\tadditionalExternals,\n\t\tnoExternal,\n\t\tgzipLevel,\n\t\tboring: true, // Suppress logging\n\t\tregistry,\n\t\tplatform,\n\t\tforce,\n\t});\n\n\tif (results.length === 0) {\n\t\tthrow new Error(`Failed to analyze any versions for package: ${baseName}`);\n\t}\n\n\t// Format results.\n\tconst formattedVersions: TrendVersionResult[] = results.map((r) => ({\n\t\tversion: r.version,\n\t\trawSize: r.rawSize,\n\t\tgzipSize: r.gzipSize,\n\t\trawSizeFormatted: formatBytes(r.rawSize),\n\t\tgzipSizeFormatted: r.gzipSize !== null ? formatBytes(r.gzipSize) : null,\n\t}));\n\n\t// Calculate change between oldest and newest.\n\tlet change: TrendChange | null = null;\n\tif (results.length > 1) {\n\t\tconst newest = results[0];\n\t\tconst oldest = results[results.length - 1];\n\n\t\tconst rawDiff = newest.rawSize - oldest.rawSize;\n\t\t// Handle division by zero: if oldest size is 0, percent is null.\n\t\tconst rawPercent =\n\t\t\toldest.rawSize === 0 ? null : (rawDiff / oldest.rawSize) * 100;\n\n\t\tlet gzipDiff: number | null = null;\n\t\tlet gzipPercent: number | null = null;\n\t\tlet gzipDiffFormatted: string | null = null;\n\n\t\tif (newest.gzipSize !== null && oldest.gzipSize !== null) {\n\t\t\tgzipDiff = newest.gzipSize - oldest.gzipSize;\n\t\t\t// Handle division by zero: if oldest size is 0, percent is null.\n\t\t\tgzipPercent =\n\t\t\t\toldest.gzipSize === 0 ? null : (gzipDiff / oldest.gzipSize) * 100;\n\t\t\tgzipDiffFormatted =\n\t\t\t\tgzipDiff >= 0\n\t\t\t\t\t? `+${formatBytes(gzipDiff)}`\n\t\t\t\t\t: `-${formatBytes(Math.abs(gzipDiff))}`;\n\t\t}\n\n\t\tchange = {\n\t\t\tfromVersion: oldest.version,\n\t\t\ttoVersion: newest.version,\n\t\t\trawDiff,\n\t\t\trawPercent:\n\t\t\t\trawPercent !== null ? Number.parseFloat(rawPercent.toFixed(1)) : null,\n\t\t\trawDiffFormatted:\n\t\t\t\trawDiff >= 0\n\t\t\t\t\t? `+${formatBytes(rawDiff)}`\n\t\t\t\t\t: `-${formatBytes(Math.abs(rawDiff))}`,\n\t\t\tgzipDiff,\n\t\t\tgzipPercent:\n\t\t\t\tgzipPercent !== null ? Number.parseFloat(gzipPercent.toFixed(1)) : null,\n\t\t\tgzipDiffFormatted,\n\t\t};\n\t}\n\n\treturn {\n\t\tpackageName: fullPackagePath,\n\t\tversions: formattedVersions,\n\t\tchange,\n\t};\n}\n\n/**\n * Get available versions for an npm package.\n *\n * @example\n * ```js\n * import { getPackageVersions } from \"@node-cli/bundlecheck\";\n *\n * const { versions, tags } = await getPackageVersions({\n *   package: \"@mantine/core\",\n * });\n *\n * console.log(tags.latest); // \"7.0.0\"\n * ```\n *\n */\nexport async function getPackageVersions(\n\toptions: GetPackageVersionsOptions,\n): Promise<PackageVersions> {\n\tconst { package: packageName, registry } = options;\n\n\tconst result = await fetchVersions({\n\t\tpackageName,\n\t\tregistry,\n\t});\n\n\treturn {\n\t\tversions: result.versions,\n\t\ttags: result.tags,\n\t};\n}\n\n/**\n * =============================================================================\n * Re-exports for advanced usage\n * =============================================================================\n */\n\n/**\n * - Format bytes to human-readable string (e.g., 1024 → \"1 kB\").\n * - Parse a package specifier (e.g., \"@scope/name@1.0.0\" → { name, version,\n * subpath }).\n */\nexport { formatBytes, parsePackageSpecifier } from \"./bundler.js\";\n/**\n * - Clear the bundle cache.\n * - Get the number of cached entries.\n */\nexport { clearCache, getCacheCount } from \"./cache.js\";\n\n/**\n * =============================================================================\n * Internal Helpers\n * =============================================================================\n */\n\n/**\n * Format a BundleResult into a BundleStats object.\n */\nfunction formatBundleStats(\n\tresult: BundleResult,\n\tfromCache: boolean,\n): BundleStats {\n\treturn {\n\t\tpackageName: result.packageName,\n\t\tpackageVersion: result.packageVersion,\n\t\texports: result.exports,\n\t\trawSize: result.rawSize,\n\t\tgzipSize: result.gzipSize,\n\t\tgzipLevel: result.gzipLevel,\n\t\texternals: result.externals,\n\t\tdependencies: result.dependencies,\n\t\tplatform: result.platform,\n\t\trawSizeFormatted: formatBytes(result.rawSize),\n\t\tgzipSizeFormatted:\n\t\t\tresult.gzipSize !== null ? formatBytes(result.gzipSize) : null,\n\t\tfromCache,\n\t};\n}\n"],"names":["checkBundleSize","formatBytes","getExternals","parsePackageSpecifier","getCachedResult","normalizeCacheKey","setCachedResult","normalizePlatform","TREND_VERSION_COUNT","analyzeTrend","selectTrendVersions","fetchPackageVersions","fetchVersions","getBundleStats","options","package","packageName","exports","exportsList","external","additionalExternals","noExternal","gzipLevel","registry","platform","platformOption","force","undefined","name","baseName","version","requestedVersion","resolvedVersion","tags","latest","externals","cacheKey","cached","formatBundleStats","result","getBundleTrend","versionCount","subpath","fullPackagePath","versions","length","Error","trendVersions","results","boring","formattedVersions","map","r","rawSize","gzipSize","rawSizeFormatted","gzipSizeFormatted","change","newest","oldest","rawDiff","rawPercent","gzipDiff","gzipPercent","gzipDiffFormatted","Math","abs","fromVersion","toVersion","Number","parseFloat","toFixed","rawDiffFormatted","getPackageVersions","clearCache","getCacheCount","fromCache","packageVersion","dependencies"],"mappings":"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"}

package/dist/parse.d.ts

@@ -8,6 +8,8 @@ export type Flags = {
     external?: string;
     noExternal?: boolean;
     registry?: string;
+    platform?: string;
+    force?: boolean;
 };
 export type Parameters = {
     ["0"]?: string;

package/dist/parse.js

@@ -1,5 +1,5 @@
 /* istanbul ignore file */ import { parser } from "@node-cli/parser";
-import { DEFAULT_EXTERNALS, defaultFlags } from "./defaults.js";
+import { DEFAULT_EXTERNALS, defaultFlags, isValidPlatform } from "./defaults.js";
 export const config = parser({
     meta: import.meta,
     examples: [
@@ -46,6 +46,14 @@ export const config = parser({
         {
             command: "bundlecheck lodash --registry https://registry.example.com",
             comment: "## Use a custom npm registry"
+        },
+        {
+            command: "bundlecheck express --platform node",
+            comment: "## Check bundle size for Node.js platform (aliases: server, nodejs, backend)"
+        },
+        {
+            command: "bundlecheck lodash --force",
+            comment: "## Bypass cache and force re-fetch/re-calculation"
         }
     ],
     flags: {
@@ -99,6 +107,18 @@ export const config = parser({
             default: defaultFlags.registry,
             description: "Custom npm registry URL (default: https://registry.npmjs.org)",
             type: "string"
+        },
+        platform: {
+            shortFlag: "p",
+            default: defaultFlags.platform,
+            description: 'Target platform: "auto" (default, detects from engines), "browser" or "node"',
+            type: "string"
+        },
+        force: {
+            shortFlag: "f",
+            default: defaultFlags.force,
+            description: "Bypass cache and force re-fetch/re-calculation",
+            type: "boolean"
         }
     },
     parameters: {
@@ -119,6 +139,11 @@ export const config = parser({
             exit: 1,
             message: ()=>"Error: Gzip level must be between 1 and 9",
             test: (flags)=>flags.gzipLevel !== undefined && (flags.gzipLevel < 1 || flags.gzipLevel > 9)
+        },
+        {
+            exit: 1,
+            message: ()=>'Error: Invalid platform. Use "browser" (or web, desktop, client) or "node" (or server, nodejs, backend)',
+            test: (flags)=>!isValidPlatform(flags.platform)
         }
     ],
     usage: true,

package/dist/parse.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/parse.ts"],"sourcesContent":["/* istanbul ignore file */\nimport { parser } from \"@node-cli/parser\";\nimport { DEFAULT_EXTERNALS, defaultFlags } from \"./defaults.js\";\n\nexport type Flags = {\n\tboring?: boolean;\n\thelp?: boolean;\n\tversion?: boolean;\n\tversions?: boolean;\n\ttrend?: string;\n\tgzipLevel?: number;\n\texternal?: string;\n\tnoExternal?: boolean;\n\tregistry?: string;\n};\n\nexport type Parameters = {\n\t[\"0\"]?: string; // package name\n\t[\"1\"]?: string; // exports (comma-separated)\n};\n\nexport type Configuration = {\n\tflags?: Flags;\n\tparameters?: Parameters;\n\tusage?: boolean;\n\tshowHelp?: () => void;\n};\n\nexport const config: Configuration = parser({\n\tmeta: import.meta,\n\texamples: [\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash\",\n\t\t\tcomment: \"## Check the bundle size of the entire lodash package\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash@4.17.0\",\n\t\t\tcomment: \"## Check a specific version of a package\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck @mantine/core\",\n\t\t\tcomment: \"## Check the bundle size of the entire @mantine/core package\",\n\t\t},\n\t\t{\n\t\t\tcommand: 'bundlecheck @mantine/core \"ScrollArea,Button\"',\n\t\t\tcomment:\n\t\t\t\t\"## Check the bundle size of specific exports from @mantine/core\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck react --no-external\",\n\t\t\tcomment:\n\t\t\t\t\"## Check the bundle size of react itself (not marked as external)\",\n\t\t},\n\t\t{\n\t\t\tcommand: 'bundlecheck some-pkg --external \"vue,svelte\"',\n\t\t\tcomment: \"## Add vue and svelte as additional external dependencies\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --gzip-level 6\",\n\t\t\tcomment: \"## Use a different gzip compression level (1-9)\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --versions\",\n\t\t\tcomment: \"## Choose from available versions interactively\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --trend\",\n\t\t\tcomment: \"## Show bundle size trend (default: 5 versions)\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --trend 3\",\n\t\t\tcomment: \"## Show bundle size trend for 3 versions\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --registry https://registry.example.com\",\n\t\t\tcomment: \"## Use a custom npm registry\",\n\t\t},\n\t],\n\tflags: {\n\t\tgzipLevel: {\n\t\t\tshortFlag: \"g\",\n\t\t\tdefault: defaultFlags.gzipLevel,\n\t\t\tdescription: \"Gzip compression level (1-9, default: 5)\",\n\t\t\ttype: \"number\",\n\t\t},\n\t\texternal: {\n\t\t\tshortFlag: \"e\",\n\t\t\tdefault: defaultFlags.external,\n\t\t\tdescription: `Comma-separated additional externals (default externals: ${DEFAULT_EXTERNALS.join(\", \")})`,\n\t\t\ttype: \"string\",\n\t\t},\n\t\tnoExternal: {\n\t\t\tshortFlag: \"n\",\n\t\t\tdefault: defaultFlags.noExternal,\n\t\t\tdescription:\n\t\t\t\t\"Do not mark any packages as external (useful for checking react/react-dom themselves)\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\tboring: {\n\t\t\tshortFlag: \"b\",\n\t\t\tdefault: defaultFlags.boring,\n\t\t\tdescription: \"Do not use color output\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\thelp: {\n\t\t\tshortFlag: \"h\",\n\t\t\tdescription: \"Display help instructions\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\tversion: {\n\t\t\tshortFlag: \"v\",\n\t\t\tdescription: \"Output the current version\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\tversions: {\n\t\t\tshortFlag: \"V\",\n\t\t\tdefault: defaultFlags.versions,\n\t\t\tdescription: \"Choose from available package versions interactively\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\ttrend: {\n\t\t\tshortFlag: \"t\",\n\t\t\tdescription: \"Show bundle size trend for N recent versions (default: 5)\",\n\t\t\ttype: \"string\",\n\t\t},\n\t\tregistry: {\n\t\t\tshortFlag: \"r\",\n\t\t\tdefault: defaultFlags.registry,\n\t\t\tdescription:\n\t\t\t\t\"Custom npm registry URL (default: https://registry.npmjs.org)\",\n\t\t\ttype: \"string\",\n\t\t},\n\t},\n\tparameters: {\n\t\tpackage: {\n\t\t\tdescription: \"The npm package to check (e.g., lodash, @mantine/core)\",\n\t\t},\n\t\texports: {\n\t\t\tdescription:\n\t\t\t\t'Comma-separated list of exports to check (e.g., \"ScrollArea,Button\")',\n\t\t},\n\t},\n\trestrictions: [\n\t\t{\n\t\t\texit: 1,\n\t\t\tmessage: () => \"Error: Package name is required\",\n\t\t\ttest: (flags, parameters) => !parameters?.[\"0\"],\n\t\t},\n\t\t{\n\t\t\texit: 1,\n\t\t\tmessage: () => \"Error: Gzip level must be between 1 and 9\",\n\t\t\ttest: (flags) =>\n\t\t\t\tflags.gzipLevel !== undefined &&\n\t\t\t\t(flags.gzipLevel < 1 || flags.gzipLevel > 9),\n\t\t},\n\t],\n\tusage: true,\n\tdefaultFlags,\n});\n"],"names":["parser","DEFAULT_EXTERNALS","defaultFlags","config","meta","examples","command","comment","flags","gzipLevel","shortFlag","default","description","type","external","join","noExternal","boring","help","version","versions","trend","registry","parameters","package","exports","restrictions","exit","message","test","undefined","usage"],"mappings":"AAAA,wBAAwB,GACxB,SAASA,MAAM,QAAQ,mBAAmB;AAC1C,SAASC,iBAAiB,EAAEC,YAAY,QAAQ,gBAAgB;AA0BhE,OAAO,MAAMC,SAAwBH,OAAO;IAC3CI,MAAM;IACNC,UAAU;QACT;YACCC,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SACC;QACF;QACA;YACCD,SAAS;YACTC,SACC;QACF;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;KACA;IACDC,OAAO;QACNC,WAAW;YACVC,WAAW;YACXC,SAAST,aAAaO,SAAS;YAC/BG,aAAa;YACbC,MAAM;QACP;QACAC,UAAU;YACTJ,WAAW;YACXC,SAAST,aAAaY,QAAQ;YAC9BF,aAAa,CAAC,yDAAyD,EAAEX,kBAAkBc,IAAI,CAAC,MAAM,CAAC,CAAC;YACxGF,MAAM;QACP;QACAG,YAAY;YACXN,WAAW;YACXC,SAAST,aAAac,UAAU;YAChCJ,aACC;YACDC,MAAM;QACP;QACAI,QAAQ;YACPP,WAAW;YACXC,SAAST,aAAae,MAAM;YAC5BL,aAAa;YACbC,MAAM;QACP;QACAK,MAAM;YACLR,WAAW;YACXE,aAAa;YACbC,MAAM;QACP;QACAM,SAAS;YACRT,WAAW;YACXE,aAAa;YACbC,MAAM;QACP;QACAO,UAAU;YACTV,WAAW;YACXC,SAAST,aAAakB,QAAQ;YAC9BR,aAAa;YACbC,MAAM;QACP;QACAQ,OAAO;YACNX,WAAW;YACXE,aAAa;YACbC,MAAM;QACP;QACAS,UAAU;YACTZ,WAAW;YACXC,SAAST,aAAaoB,QAAQ;YAC9BV,aACC;YACDC,MAAM;QACP;IACD;IACAU,YAAY;QACXC,SAAS;YACRZ,aAAa;QACd;QACAa,SAAS;YACRb,aACC;QACF;IACD;IACAc,cAAc;QACb;YACCC,MAAM;YACNC,SAAS,IAAM;YACfC,MAAM,CAACrB,OAAOe,aAAe,CAACA,YAAY,CAAC,IAAI;QAChD;QACA;YACCI,MAAM;YACNC,SAAS,IAAM;YACfC,MAAM,CAACrB,QACNA,MAAMC,SAAS,KAAKqB,aACnBtB,CAAAA,MAAMC,SAAS,GAAG,KAAKD,MAAMC,SAAS,GAAG,CAAA;QAC5C;KACA;IACDsB,OAAO;IACP7B;AACD,GAAG"}
+{"version":3,"sources":["../src/parse.ts"],"sourcesContent":["/* istanbul ignore file */\nimport { parser } from \"@node-cli/parser\";\nimport {\n\tDEFAULT_EXTERNALS,\n\tdefaultFlags,\n\tisValidPlatform,\n} from \"./defaults.js\";\n\nexport type Flags = {\n\tboring?: boolean;\n\thelp?: boolean;\n\tversion?: boolean;\n\tversions?: boolean;\n\ttrend?: string;\n\tgzipLevel?: number;\n\texternal?: string;\n\tnoExternal?: boolean;\n\tregistry?: string;\n\tplatform?: string;\n\tforce?: boolean;\n};\n\nexport type Parameters = {\n\t[\"0\"]?: string; // package name\n\t[\"1\"]?: string; // exports (comma-separated)\n};\n\nexport type Configuration = {\n\tflags?: Flags;\n\tparameters?: Parameters;\n\tusage?: boolean;\n\tshowHelp?: () => void;\n};\n\nexport const config: Configuration = parser({\n\tmeta: import.meta,\n\texamples: [\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash\",\n\t\t\tcomment: \"## Check the bundle size of the entire lodash package\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash@4.17.0\",\n\t\t\tcomment: \"## Check a specific version of a package\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck @mantine/core\",\n\t\t\tcomment: \"## Check the bundle size of the entire @mantine/core package\",\n\t\t},\n\t\t{\n\t\t\tcommand: 'bundlecheck @mantine/core \"ScrollArea,Button\"',\n\t\t\tcomment:\n\t\t\t\t\"## Check the bundle size of specific exports from @mantine/core\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck react --no-external\",\n\t\t\tcomment:\n\t\t\t\t\"## Check the bundle size of react itself (not marked as external)\",\n\t\t},\n\t\t{\n\t\t\tcommand: 'bundlecheck some-pkg --external \"vue,svelte\"',\n\t\t\tcomment: \"## Add vue and svelte as additional external dependencies\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --gzip-level 6\",\n\t\t\tcomment: \"## Use a different gzip compression level (1-9)\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --versions\",\n\t\t\tcomment: \"## Choose from available versions interactively\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --trend\",\n\t\t\tcomment: \"## Show bundle size trend (default: 5 versions)\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --trend 3\",\n\t\t\tcomment: \"## Show bundle size trend for 3 versions\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --registry https://registry.example.com\",\n\t\t\tcomment: \"## Use a custom npm registry\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck express --platform node\",\n\t\t\tcomment:\n\t\t\t\t\"## Check bundle size for Node.js platform (aliases: server, nodejs, backend)\",\n\t\t},\n\t\t{\n\t\t\tcommand: \"bundlecheck lodash --force\",\n\t\t\tcomment: \"## Bypass cache and force re-fetch/re-calculation\",\n\t\t},\n\t],\n\tflags: {\n\t\tgzipLevel: {\n\t\t\tshortFlag: \"g\",\n\t\t\tdefault: defaultFlags.gzipLevel,\n\t\t\tdescription: \"Gzip compression level (1-9, default: 5)\",\n\t\t\ttype: \"number\",\n\t\t},\n\t\texternal: {\n\t\t\tshortFlag: \"e\",\n\t\t\tdefault: defaultFlags.external,\n\t\t\tdescription: `Comma-separated additional externals (default externals: ${DEFAULT_EXTERNALS.join(\", \")})`,\n\t\t\ttype: \"string\",\n\t\t},\n\t\tnoExternal: {\n\t\t\tshortFlag: \"n\",\n\t\t\tdefault: defaultFlags.noExternal,\n\t\t\tdescription:\n\t\t\t\t\"Do not mark any packages as external (useful for checking react/react-dom themselves)\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\tboring: {\n\t\t\tshortFlag: \"b\",\n\t\t\tdefault: defaultFlags.boring,\n\t\t\tdescription: \"Do not use color output\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\thelp: {\n\t\t\tshortFlag: \"h\",\n\t\t\tdescription: \"Display help instructions\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\tversion: {\n\t\t\tshortFlag: \"v\",\n\t\t\tdescription: \"Output the current version\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\tversions: {\n\t\t\tshortFlag: \"V\",\n\t\t\tdefault: defaultFlags.versions,\n\t\t\tdescription: \"Choose from available package versions interactively\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t\ttrend: {\n\t\t\tshortFlag: \"t\",\n\t\t\tdescription: \"Show bundle size trend for N recent versions (default: 5)\",\n\t\t\ttype: \"string\",\n\t\t},\n\t\tregistry: {\n\t\t\tshortFlag: \"r\",\n\t\t\tdefault: defaultFlags.registry,\n\t\t\tdescription:\n\t\t\t\t\"Custom npm registry URL (default: https://registry.npmjs.org)\",\n\t\t\ttype: \"string\",\n\t\t},\n\t\tplatform: {\n\t\t\tshortFlag: \"p\",\n\t\t\tdefault: defaultFlags.platform,\n\t\t\tdescription:\n\t\t\t\t'Target platform: \"auto\" (default, detects from engines), \"browser\" or \"node\"',\n\t\t\ttype: \"string\",\n\t\t},\n\t\tforce: {\n\t\t\tshortFlag: \"f\",\n\t\t\tdefault: defaultFlags.force,\n\t\t\tdescription: \"Bypass cache and force re-fetch/re-calculation\",\n\t\t\ttype: \"boolean\",\n\t\t},\n\t},\n\tparameters: {\n\t\tpackage: {\n\t\t\tdescription: \"The npm package to check (e.g., lodash, @mantine/core)\",\n\t\t},\n\t\texports: {\n\t\t\tdescription:\n\t\t\t\t'Comma-separated list of exports to check (e.g., \"ScrollArea,Button\")',\n\t\t},\n\t},\n\trestrictions: [\n\t\t{\n\t\t\texit: 1,\n\t\t\tmessage: () => \"Error: Package name is required\",\n\t\t\ttest: (flags, parameters) => !parameters?.[\"0\"],\n\t\t},\n\t\t{\n\t\t\texit: 1,\n\t\t\tmessage: () => \"Error: Gzip level must be between 1 and 9\",\n\t\t\ttest: (flags) =>\n\t\t\t\tflags.gzipLevel !== undefined &&\n\t\t\t\t(flags.gzipLevel < 1 || flags.gzipLevel > 9),\n\t\t},\n\t\t{\n\t\t\texit: 1,\n\t\t\tmessage: () =>\n\t\t\t\t'Error: Invalid platform. Use \"browser\" (or web, desktop, client) or \"node\" (or server, nodejs, backend)',\n\t\t\ttest: (flags) => !isValidPlatform(flags.platform),\n\t\t},\n\t],\n\tusage: true,\n\tdefaultFlags,\n});\n"],"names":["parser","DEFAULT_EXTERNALS","defaultFlags","isValidPlatform","config","meta","examples","command","comment","flags","gzipLevel","shortFlag","default","description","type","external","join","noExternal","boring","help","version","versions","trend","registry","platform","force","parameters","package","exports","restrictions","exit","message","test","undefined","usage"],"mappings":"AAAA,wBAAwB,GACxB,SAASA,MAAM,QAAQ,mBAAmB;AAC1C,SACCC,iBAAiB,EACjBC,YAAY,EACZC,eAAe,QACT,gBAAgB;AA4BvB,OAAO,MAAMC,SAAwBJ,OAAO;IAC3CK,MAAM;IACNC,UAAU;QACT;YACCC,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SACC;QACF;QACA;YACCD,SAAS;YACTC,SACC;QACF;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SAAS;QACV;QACA;YACCD,SAAS;YACTC,SACC;QACF;QACA;YACCD,SAAS;YACTC,SAAS;QACV;KACA;IACDC,OAAO;QACNC,WAAW;YACVC,WAAW;YACXC,SAASV,aAAaQ,SAAS;YAC/BG,aAAa;YACbC,MAAM;QACP;QACAC,UAAU;YACTJ,WAAW;YACXC,SAASV,aAAaa,QAAQ;YAC9BF,aAAa,CAAC,yDAAyD,EAAEZ,kBAAkBe,IAAI,CAAC,MAAM,CAAC,CAAC;YACxGF,MAAM;QACP;QACAG,YAAY;YACXN,WAAW;YACXC,SAASV,aAAae,UAAU;YAChCJ,aACC;YACDC,MAAM;QACP;QACAI,QAAQ;YACPP,WAAW;YACXC,SAASV,aAAagB,MAAM;YAC5BL,aAAa;YACbC,MAAM;QACP;QACAK,MAAM;YACLR,WAAW;YACXE,aAAa;YACbC,MAAM;QACP;QACAM,SAAS;YACRT,WAAW;YACXE,aAAa;YACbC,MAAM;QACP;QACAO,UAAU;YACTV,WAAW;YACXC,SAASV,aAAamB,QAAQ;YAC9BR,aAAa;YACbC,MAAM;QACP;QACAQ,OAAO;YACNX,WAAW;YACXE,aAAa;YACbC,MAAM;QACP;QACAS,UAAU;YACTZ,WAAW;YACXC,SAASV,aAAaqB,QAAQ;YAC9BV,aACC;YACDC,MAAM;QACP;QACAU,UAAU;YACTb,WAAW;YACXC,SAASV,aAAasB,QAAQ;YAC9BX,aACC;YACDC,MAAM;QACP;QACAW,OAAO;YACNd,WAAW;YACXC,SAASV,aAAauB,KAAK;YAC3BZ,aAAa;YACbC,MAAM;QACP;IACD;IACAY,YAAY;QACXC,SAAS;YACRd,aAAa;QACd;QACAe,SAAS;YACRf,aACC;QACF;IACD;IACAgB,cAAc;QACb;YACCC,MAAM;YACNC,SAAS,IAAM;YACfC,MAAM,CAACvB,OAAOiB,aAAe,CAACA,YAAY,CAAC,IAAI;QAChD;QACA;YACCI,MAAM;YACNC,SAAS,IAAM;YACfC,MAAM,CAACvB,QACNA,MAAMC,SAAS,KAAKuB,aACnBxB,CAAAA,MAAMC,SAAS,GAAG,KAAKD,MAAMC,SAAS,GAAG,CAAA;QAC5C;QACA;YACCoB,MAAM;YACNC,SAAS,IACR;YACDC,MAAM,CAACvB,QAAU,CAACN,gBAAgBM,MAAMe,QAAQ;QACjD;KACA;IACDU,OAAO;IACPhC;AACD,GAAG"}

package/dist/trend.d.ts

@@ -1,7 +1,10 @@
 export type TrendResult = {
     version: string;
     rawSize: number;
-    gzipSize: number;
+    /**
+     * Gzip size in bytes, or null for node platform.
+     */
+    gzipSize: number | null;
 };
 export type TrendOptions = {
     packageName: string;
@@ -12,18 +15,26 @@ export type TrendOptions = {
     gzipLevel?: number;
     boring?: boolean;
     registry?: string;
+    /**
+     * Target platform. If undefined, auto-detects from package.json engines.
+     */
+    platform?: "browser" | "node";
+    /**
+     * Bypass cache and force re-fetch/re-calculation.
+     */
+    force?: boolean;
 };
 /**
- * Select versions for trend analysis
- * Returns the most recent stable versions (newest first)
- * Filters out prerelease versions (canary, alpha, beta, rc, etc.)
+ * Select versions for trend analysis Returns the most recent stable versions
+ * (newest first) Filters out prerelease versions (canary, alpha, beta, rc,
+ * etc.)
  */
 export declare function selectTrendVersions(allVersions: string[], count?: number): string[];
 /**
- * Analyze bundle size trend across multiple versions
+ * Analyze bundle size trend across multiple versions.
  */
 export declare function analyzeTrend(options: TrendOptions): Promise<TrendResult[]>;
 /**
- * Render a bar graph showing bundle size trend
+ * Render a bar graph showing bundle size trend.
  */
 export declare function renderTrendGraph(packageName: string, results: TrendResult[], boring?: boolean): string[];