@node-cli/bundlecheck 1.3.0 → 1.4.1

package/dist/index.d.ts

@@ -1,11 +1,321 @@
 /**
- * @file Automatically generated by barrelsby.
- */
-
-export * from "./bundlecheck";
-export * from "./bundler";
-export * from "./cache";
-export * from "./defaults";
-export * from "./parse";
-export * from "./trend";
-export * from "./versions";
+ * @node-cli/bundlecheck - Library API
+ *
+ * Programmatic interface for analyzing npm package bundle sizes.
+ *
+ */
+/**
+ * =============================================================================
+ * Types
+ * =============================================================================
+ */
+/**
+ * Options for getting bundle stats of a single package.
+ */
+export type GetBundleStatsOptions = {
+    /**
+     * Package name with optional version (e.g., "@mantine/core" or
+     * "@mantine/core@7.0.0").
+     */
+    package: string;
+    /**
+     * Specific exports to measure (e.g., ["Button", "Input"]).
+     */
+    exports?: string[];
+    /**
+     * Additional packages to mark as external (not bundled).
+     */
+    external?: string[];
+    /**
+     * Bundle everything including default externals (react, react-dom).
+     */
+    noExternal?: boolean;
+    /**
+     * Gzip compression level (1-9, default 5).
+     */
+    gzipLevel?: number;
+    /**
+     * Custom npm registry URL.
+     */
+    registry?: string;
+    /**
+     * Target platform: "browser", "node", or "auto" (default: "auto" - auto-detect
+     * from package.json).
+     */
+    platform?: "browser" | "node" | "auto";
+    /**
+     * Bypass cache and force re-analysis.
+     */
+    force?: boolean;
+};
+/**
+ * Result from getBundleStats.
+ */
+export type BundleStats = {
+    /**
+     * Display name of the package (may include subpath).
+     */
+    packageName: string;
+    /**
+     * Resolved package version.
+     */
+    packageVersion: string;
+    /**
+     * Exports that were analyzed.
+     */
+    exports: string[];
+    /**
+     * Raw (minified) bundle size in bytes.
+     */
+    rawSize: number;
+    /**
+     * Gzipped bundle size in bytes (null for node platform).
+     */
+    gzipSize: number | null;
+    /**
+     * Gzip compression level used.
+     */
+    gzipLevel: number;
+    /**
+     * Packages marked as external (not included in bundle).
+     */
+    externals: string[];
+    /**
+     * Package dependencies.
+     */
+    dependencies: string[];
+    /**
+     * Target platform used for bundling.
+     */
+    platform: "browser" | "node";
+    /**
+     * Human-readable raw size (e.g., "45.2 kB").
+     */
+    rawSizeFormatted: string;
+    /**
+     * Human-readable gzip size (e.g., "12.3 kB") or null.
+     */
+    gzipSizeFormatted: string | null;
+    /**
+     * Whether the result was retrieved from cache.
+     */
+    fromCache: boolean;
+};
+/**
+ * Options for getting bundle size trend across versions.
+ */
+export type GetBundleTrendOptions = {
+    /**
+     * Package name (e.g., "@mantine/core") - version is ignored if provided.
+     */
+    package: string;
+    /**
+     * Number of versions to analyze (default 5).
+     */
+    versionCount?: number;
+    /**
+     * Specific exports to measure (e.g., ["Button", "Input"]).
+     */
+    exports?: string[];
+    /**
+     * Additional packages to mark as external (not bundled).
+     */
+    external?: string[];
+    /**
+     * Bundle everything including default externals (react, react-dom).
+     */
+    noExternal?: boolean;
+    /**
+     * Gzip compression level (1-9, default 5).
+     */
+    gzipLevel?: number;
+    /**
+     * Custom npm registry URL.
+     */
+    registry?: string;
+    /**
+     * Target platform: "browser", "node", or "auto" (default: "auto" - auto-detect
+     * from package.json).
+     */
+    platform?: "browser" | "node" | "auto";
+    /**
+     * Bypass cache and force re-analysis.
+     */
+    force?: boolean;
+};
+/**
+ * Single version result in trend analysis.
+ */
+export type TrendVersionResult = {
+    /**
+     * Package version.
+     */
+    version: string;
+    /**
+     * Raw (minified) bundle size in bytes.
+     */
+    rawSize: number;
+    /**
+     * Gzipped bundle size in bytes (null for node platform).
+     */
+    gzipSize: number | null;
+    /**
+     * Human-readable raw size (e.g., "45.2 kB").
+     */
+    rawSizeFormatted: string;
+    /**
+     * Human-readable gzip size (e.g., "12.3 kB") or null.
+     */
+    gzipSizeFormatted: string | null;
+};
+/**
+ * Size change information between oldest and newest versions.
+ */
+export type TrendChange = {
+    /**
+     * Oldest version analyzed.
+     */
+    fromVersion: string;
+    /**
+     * Newest version analyzed.
+     */
+    toVersion: string;
+    /**
+     * Raw size difference in bytes (positive = increase, negative = decrease).
+     */
+    rawDiff: number;
+    /**
+     * Raw size percentage change (null if oldest size was 0).
+     */
+    rawPercent: number | null;
+    /**
+     * Human-readable raw size change (e.g., "+5.2 kB" or "-1.3 kB").
+     */
+    rawDiffFormatted: string;
+    /**
+     * Gzip size difference in bytes (null if not applicable).
+     */
+    gzipDiff: number | null;
+    /**
+     * Gzip size percentage change (null if not applicable or oldest size was 0).
+     */
+    gzipPercent: number | null;
+    /**
+     * Human-readable gzip size change (e.g., "+1.5 kB" or "-0.8 kB") or null.
+     */
+    gzipDiffFormatted: string | null;
+};
+/**
+ * Result from getBundleTrend.
+ */
+export type BundleTrend = {
+    /**
+     * Package name.
+     */
+    packageName: string;
+    /**
+     * Results for each version analyzed (newest first).
+     */
+    versions: TrendVersionResult[];
+    /**
+     * Size change between oldest and newest versions (null if only one version).
+     */
+    change: TrendChange | null;
+};
+/**
+ * Options for fetching package versions.
+ */
+export type GetPackageVersionsOptions = {
+    /**
+     * Package name (e.g., "@mantine/core").
+     */
+    package: string;
+    /**
+     * Custom npm registry URL.
+     */
+    registry?: string;
+};
+/**
+ * Result from getPackageVersions.
+ */
+export type PackageVersions = {
+    /**
+     * All available versions (sorted newest first).
+     */
+    versions: string[];
+    /**
+     * Distribution tags (e.g., { latest: "7.0.0", next: "8.0.0-beta.1" }).
+     */
+    tags: Record<string, string>;
+};
+/**
+ * =============================================================================
+ * 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 declare function getBundleStats(options: GetBundleStatsOptions): Promise<BundleStats>;
+/**
+ * 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 declare function getBundleTrend(options: GetBundleTrendOptions): Promise<BundleTrend>;
+/**
+ * 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 declare function getPackageVersions(options: GetPackageVersionsOptions): Promise<PackageVersions>;
+/**
+ * =============================================================================
+ * 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";

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/trend.d.ts

@@ -1,7 +1,9 @@
 export type TrendResult = {
     version: string;
     rawSize: number;
-    /** Gzip size in bytes, or null for node platform */
+    /**
+     * Gzip size in bytes, or null for node platform.
+     */
     gzipSize: number | null;
 };
 export type TrendOptions = {
@@ -13,22 +15,26 @@ export type TrendOptions = {
     gzipLevel?: number;
     boring?: boolean;
     registry?: string;
-    /** Target platform. If undefined, auto-detects from package.json engines */
+    /**
+     * Target platform. If undefined, auto-detects from package.json engines.
+     */
     platform?: "browser" | "node";
-    /** Bypass cache and force re-fetch/re-calculation */
+    /**
+     * 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[];