@adguard/filters-compiler 3.2.11 → 3.2.12

package/dist/main/optimization.d.ts

@@ -0,0 +1,112 @@
+export declare const STATS_JSON = "stats.json";
+export declare const FILTERS_DIR_NAME = "filters";
+interface PercentEntry {
+    filterId: number;
+}
+export interface PercentJson {
+    config: PercentEntry[];
+}
+interface GroupConfig {
+    hits: number;
+}
+interface OptimizationGroup {
+    config: GroupConfig;
+    rules: Record<string, number>;
+}
+export interface OptimizationStats {
+    groups: OptimizationGroup[];
+}
+/**
+ * Thrown by `getOptimizationStatistics` when a filter's stats cannot be
+ * retrieved, from either a local file or the remote server.
+ *
+ * Carries `filterId` and `sourcePath` as structured fields so callers can
+ * build their own actionable message instead of matching on `error.message`.
+ */
+export declare class OptimizationStatsError extends Error {
+    filterId: number;
+    sourcePath: string;
+    code: "OPTIMIZATION_STATS_UNAVAILABLE";
+    constructor(filterId: number, sourcePath: string, options?: ErrorOptions);
+}
+/**
+ * Validates that stats have non-empty groups.
+ *
+ * @param filterId - Numeric filter identifier.
+ * @param stats - Parsed optimization stats object.
+ * @throws {Error} if stats is not an object, or if stats.groups is missing or empty.
+ */
+export declare function assertValidStats(filterId: number, stats: unknown): asserts stats is OptimizationStats;
+/**
+ * Manages a local on-disk cache of optimization stats files.
+ *
+ * Typical usage for generating the cache:
+ * 1. `download(basePath, includedFilterIds, excludedFilterIds)` — save
+ *    `stats.json` for filters listed in the remote `percent.json`.
+ *
+ * Typical usage for using the cache:
+ * 1. `use(basePath)` — tells `getOptimizationStatistics` to read stats
+ *    from local files lazily during compilation instead of fetching remotely.
+ * 2. `reset(basePath)` — remove the cache directory and clear in-memory state.
+ */
+export declare const localOptimizationStatistics: {
+    /**
+     * Downloads `stats.json` files for filters listed in the remote
+     * `percent.json` and saves them to disk.
+     * Existing `stats.json` files will be overwritten.
+     *
+     * `includedFilterIds` and `excludedFilterIds` cannot both be non-empty.
+     *
+     * @param basePath - Directory to save `filters/<filterId>/stats.json` into.
+     * @param includedFilterIds - Filter IDs to process; empty (default) processes all.
+     * @param excludedFilterIds - Filter IDs to exclude; empty (default) excludes none.
+     * @throws {Error} When both `includedFilterIds` and `excludedFilterIds` are non-empty.
+     */
+    download: (basePath: string, includedFilterIds?: number[], excludedFilterIds?: number[]) => Promise<void>;
+    /**
+     * Configures `getOptimizationStatistics` to read stats from local files under
+     * `basePath` instead of fetching from the remote server.
+     * Stats are loaded lazily on demand during compilation. `percent.json` is
+     * still fetched remotely to determine which filters are optimizable.
+     *
+     * @param basePath - Directory containing `filters/<filterId>/stats.json`.
+     */
+    use(basePath: string): void;
+    /**
+     * Removes the cache directory and clears in-memory state.
+     *
+     * @param basePath - Directory to remove.
+     */
+    reset(basePath: string): Promise<void>;
+};
+/**
+ * Returns the optimization stats for the given filter, or `null` when
+ * optimization is disabled or the filter is not listed in `percent.json`.
+ *
+ * When `localOptimizationStatistics.use(path)` has been called, stats
+ * are read lazily from local files. Otherwise stats are fetched from the
+ * remote server.
+ *
+ * @param filterId - Numeric filter identifier.
+ * @returns Parsed stats object, or `null` when the filter has no optimization stats.
+ * @throws {Error} When the stats are missing or malformed.
+ */
+export declare const getOptimizationStatistics: (filterId: number) => Promise<OptimizationStats | null>;
+/**
+ * Checks if rule should be skipped because optimization is enabled for this filter
+ * and the hit count for this rule is below the configured threshold.
+ *
+ * @param ruleText - Rule text to check.
+ * @param optimizationStats - Optimization config for this filter.
+ * @returns `true` if the rule should be skipped, `false` otherwise.
+ */
+export declare const skipRuleWithOptimization: (ruleText: string, optimizationStats: OptimizationStats | null) => boolean;
+/**
+ * Disables optimized filter builds
+ */
+export declare const disableOptimization: () => void;
+/**
+ * Enables optimized filter builds
+ */
+export declare const enableOptimization: () => void;
+export {};

package/dist/types/src/main/optimization.d.ts

@@ -0,0 +1,112 @@
+export declare const STATS_JSON = "stats.json";
+export declare const FILTERS_DIR_NAME = "filters";
+interface PercentEntry {
+    filterId: number;
+}
+export interface PercentJson {
+    config: PercentEntry[];
+}
+interface GroupConfig {
+    hits: number;
+}
+interface OptimizationGroup {
+    config: GroupConfig;
+    rules: Record<string, number>;
+}
+export interface OptimizationStats {
+    groups: OptimizationGroup[];
+}
+/**
+ * Thrown by `getOptimizationStatistics` when a filter's stats cannot be
+ * retrieved, from either a local file or the remote server.
+ *
+ * Carries `filterId` and `sourcePath` as structured fields so callers can
+ * build their own actionable message instead of matching on `error.message`.
+ */
+export declare class OptimizationStatsError extends Error {
+    filterId: number;
+    sourcePath: string;
+    code: "OPTIMIZATION_STATS_UNAVAILABLE";
+    constructor(filterId: number, sourcePath: string, options?: ErrorOptions);
+}
+/**
+ * Validates that stats have non-empty groups.
+ *
+ * @param filterId - Numeric filter identifier.
+ * @param stats - Parsed optimization stats object.
+ * @throws {Error} if stats is not an object, or if stats.groups is missing or empty.
+ */
+export declare function assertValidStats(filterId: number, stats: unknown): asserts stats is OptimizationStats;
+/**
+ * Manages a local on-disk cache of optimization stats files.
+ *
+ * Typical usage for generating the cache:
+ * 1. `download(basePath, includedFilterIds, excludedFilterIds)` — save
+ *    `stats.json` for filters listed in the remote `percent.json`.
+ *
+ * Typical usage for using the cache:
+ * 1. `use(basePath)` — tells `getOptimizationStatistics` to read stats
+ *    from local files lazily during compilation instead of fetching remotely.
+ * 2. `reset(basePath)` — remove the cache directory and clear in-memory state.
+ */
+export declare const localOptimizationStatistics: {
+    /**
+     * Downloads `stats.json` files for filters listed in the remote
+     * `percent.json` and saves them to disk.
+     * Existing `stats.json` files will be overwritten.
+     *
+     * `includedFilterIds` and `excludedFilterIds` cannot both be non-empty.
+     *
+     * @param basePath - Directory to save `filters/<filterId>/stats.json` into.
+     * @param includedFilterIds - Filter IDs to process; empty (default) processes all.
+     * @param excludedFilterIds - Filter IDs to exclude; empty (default) excludes none.
+     * @throws {Error} When both `includedFilterIds` and `excludedFilterIds` are non-empty.
+     */
+    download: (basePath: string, includedFilterIds?: number[], excludedFilterIds?: number[]) => Promise<void>;
+    /**
+     * Configures `getOptimizationStatistics` to read stats from local files under
+     * `basePath` instead of fetching from the remote server.
+     * Stats are loaded lazily on demand during compilation. `percent.json` is
+     * still fetched remotely to determine which filters are optimizable.
+     *
+     * @param basePath - Directory containing `filters/<filterId>/stats.json`.
+     */
+    use(basePath: string): void;
+    /**
+     * Removes the cache directory and clears in-memory state.
+     *
+     * @param basePath - Directory to remove.
+     */
+    reset(basePath: string): Promise<void>;
+};
+/**
+ * Returns the optimization stats for the given filter, or `null` when
+ * optimization is disabled or the filter is not listed in `percent.json`.
+ *
+ * When `localOptimizationStatistics.use(path)` has been called, stats
+ * are read lazily from local files. Otherwise stats are fetched from the
+ * remote server.
+ *
+ * @param filterId - Numeric filter identifier.
+ * @returns Parsed stats object, or `null` when the filter has no optimization stats.
+ * @throws {Error} When the stats are missing or malformed.
+ */
+export declare const getOptimizationStatistics: (filterId: number) => Promise<OptimizationStats | null>;
+/**
+ * Checks if rule should be skipped because optimization is enabled for this filter
+ * and the hit count for this rule is below the configured threshold.
+ *
+ * @param ruleText - Rule text to check.
+ * @param optimizationStats - Optimization config for this filter.
+ * @returns `true` if the rule should be skipped, `false` otherwise.
+ */
+export declare const skipRuleWithOptimization: (ruleText: string, optimizationStats: OptimizationStats | null) => boolean;
+/**
+ * Disables optimized filter builds
+ */
+export declare const disableOptimization: () => void;
+/**
+ * Enables optimized filter builds
+ */
+export declare const enableOptimization: () => void;
+export {};

package/dist/types/src/main/utils/concurrent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs `fn` over `items` with at most `concurrency` calls in flight at once.
+ *
+ * @param items - Items to process.
+ * @param max - Max number of concurrent `fn` calls.
+ * @param fn - Async worker invoked for each item.
+ */
+export declare const mapWithConcurrency: <T>(items: T[], max: number, fn: (item: T) => Promise<void>) => Promise<void>;

package/dist/types/src/main/utils/log.d.ts

@@ -0,0 +1,31 @@
+import { Logger } from '@adguard/logger';
+/**
+ * Extend logger implementation
+ */
+declare class CompilerLogger extends Logger {
+    #private;
+    /**
+     * Log file path, set after successful initialization.
+     */
+    logFile: string | undefined;
+    /** @inheritdoc */
+    info(message: unknown): void;
+    /** @inheritdoc */
+    error(message: unknown): void;
+    /** @inheritdoc */
+    warn(message: unknown): void;
+    /**
+     * Initializes logger
+     *
+     * @param logFilePath - log file path
+     *
+     * The log file is opened with 'w' (truncate/create). Subsequent writes are appended.
+     */
+    initialize(logFilePath: string | undefined): void;
+    /**
+     * Optional: call to close the file descriptor when done (e.g., on shutdown)
+     */
+    close(): void;
+}
+declare const logger: CompilerLogger;
+export { logger };

package/dist/types/src/main/utils/webutils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Number of times to retry downloading after the first failed attempt for `downloadFile` function.
+ */
+export declare const RETRY_NUM = 5;
+/**
+ * Downloads file from url with two attempts
+ *
+ * @param url
+ * @returns raw content of the file
+ */
+export declare const downloadFile: (url: string) => Promise<string>;

package/dist/types/test/optimization.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/webutils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -4,8 +4,10 @@
   "homepage": "http://adguard.com",
   "type": "module",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "types"
   ],
   "exports": {
     ".": {
@@ -45,6 +47,7 @@
     "eslint-config-airbnb-base": "15.0.0",
     "eslint-import-resolver-exports": "1.0.0-beta.5",
     "eslint-plugin-import": "2.31.0",
+    "eslint-plugin-jsdoc": "63.2.0",
     "husky": "8.0.2",
     "markdownlint": "0.40.0",
     "markdownlint-cli": "0.48.0",
@@ -55,7 +58,7 @@
     "typescript": "6.0.3",
     "vitest": "3.0.5"
   },
-  "version": "3.2.11",
+  "version": "3.2.12",
   "scripts": {
     "prebuild": "rimraf dist",
     "build": "rollup --config rollup.config.js --silent",