@adguard/dnr-converter 1.0.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/README.md +476 -0
  2. package/dist/cli.cjs +58912 -0
  3. package/dist/constants.js +23 -0
  4. package/dist/declarative-rule/declarative-rule.js +15 -0
  5. package/dist/declarative-rule/header-info.js +12 -0
  6. package/dist/declarative-rule/modify-header-info.js +31 -0
  7. package/dist/declarative-rule/query-key-value.js +12 -0
  8. package/dist/declarative-rule/query-transform.js +12 -0
  9. package/dist/declarative-rule/redirect.js +14 -0
  10. package/dist/declarative-rule/rule-action.js +44 -0
  11. package/dist/declarative-rule/rule-condition.js +77 -0
  12. package/dist/declarative-rule/url-transform.js +30 -0
  13. package/dist/errors/conversion-errors/empty-domains-error.js +24 -0
  14. package/dist/errors/conversion-errors/empty-resources-error.js +24 -0
  15. package/dist/errors/conversion-errors/index.js +17 -0
  16. package/dist/errors/conversion-errors/invalid-declarative-rule-error.js +22 -0
  17. package/dist/errors/conversion-errors/unsupported-modifier-error.js +20 -0
  18. package/dist/errors/conversion-errors/unsupported-regexp-error.js +27 -0
  19. package/dist/errors/converter-options-errors/empty-or-negative-number-of-rules-error.js +18 -0
  20. package/dist/errors/converter-options-errors/index.js +15 -0
  21. package/dist/errors/converter-options-errors/negative-number-of-rules-error.js +18 -0
  22. package/dist/errors/converter-options-errors/resources-path-error.js +18 -0
  23. package/dist/errors/limitation-errors/index.js +17 -0
  24. package/dist/errors/limitation-errors/max-scanned-rules-error.js +20 -0
  25. package/dist/errors/limitation-errors/too-many-error.js +28 -0
  26. package/dist/errors/limitation-errors/too-many-regexp-rules-error.js +25 -0
  27. package/dist/errors/limitation-errors/too-many-rules-error.js +25 -0
  28. package/dist/errors/limitation-errors/too-many-unsafe-rules-error.js +25 -0
  29. package/dist/errors/unavailable-sources-errors/unavailable-filter-source-error.js +21 -0
  30. package/dist/errors/unavailable-sources-errors/unavailable-ruleset-source-error.js +21 -0
  31. package/dist/filter/filter.js +92 -0
  32. package/dist/filter-converter/filter-converter.js +385 -0
  33. package/dist/grouped-rules-converters/url-transform-converter.js +340 -0
  34. package/dist/index.js +30 -0
  35. package/dist/package.json.js +3 -0
  36. package/dist/re2-regexp/re2-validator.js +37 -0
  37. package/dist/re2-regexp/regex-validator-extension.js +30 -0
  38. package/dist/re2.wasm +0 -0
  39. package/dist/rule/option-names.js +65 -0
  40. package/dist/rule/rule-badfilter.js +81 -0
  41. package/dist/rule/rule-priority.js +88 -0
  42. package/dist/rule/rule-validator.js +455 -0
  43. package/dist/rule/rule.js +853 -0
  44. package/dist/rule/string-utils.js +49 -0
  45. package/dist/rule-converters/csp-converter.js +105 -0
  46. package/dist/rule-converters/regular-rule-converter.js +789 -0
  47. package/dist/rule-converters/remove-header-converter.js +97 -0
  48. package/dist/rule-converters/rules-converter.js +365 -0
  49. package/dist/rule-converters/rules-grouper.js +75 -0
  50. package/dist/rules-scanner/rules-scanner.js +136 -0
  51. package/dist/ruleset/metadata-rule.js +35 -0
  52. package/dist/ruleset/metadata-ruleset.js +162 -0
  53. package/dist/ruleset/rules-hash-map.js +71 -0
  54. package/dist/ruleset/ruleset-with-source-map.js +406 -0
  55. package/dist/ruleset/ruleset.js +54 -0
  56. package/dist/ruleset/source-map.js +283 -0
  57. package/dist/types/cli/convert-filters.d.ts +32 -0
  58. package/dist/types/cli/index.d.ts +7 -0
  59. package/dist/types/cli/utils.d.ts +19 -0
  60. package/dist/types/src/declarative-rule/declarative-rule.d.ts +32 -0
  61. package/dist/types/src/declarative-rule/header-info.d.ts +31 -0
  62. package/dist/types/src/declarative-rule/modify-header-info.d.ts +46 -0
  63. package/dist/types/src/declarative-rule/query-key-value.d.ts +24 -0
  64. package/dist/types/src/declarative-rule/query-transform.d.ts +21 -0
  65. package/dist/types/src/declarative-rule/redirect.d.ts +32 -0
  66. package/dist/types/src/declarative-rule/rule-action.d.ts +68 -0
  67. package/dist/types/src/declarative-rule/rule-condition.d.ts +262 -0
  68. package/dist/types/src/declarative-rule/url-transform.d.ts +69 -0
  69. package/dist/types/src/errors/conversion-errors/empty-domains-error.d.ts +21 -0
  70. package/dist/types/src/errors/conversion-errors/empty-resources-error.d.ts +21 -0
  71. package/dist/types/src/errors/conversion-errors/index.d.ts +27 -0
  72. package/dist/types/src/errors/conversion-errors/invalid-declarative-rule-error.d.ts +30 -0
  73. package/dist/types/src/errors/conversion-errors/unsupported-modifier-error.d.ts +20 -0
  74. package/dist/types/src/errors/conversion-errors/unsupported-regexp-error.d.ts +23 -0
  75. package/dist/types/src/errors/converter-options-errors/empty-or-negative-number-of-rules-error.d.ts +13 -0
  76. package/dist/types/src/errors/converter-options-errors/index.d.ts +23 -0
  77. package/dist/types/src/errors/converter-options-errors/negative-number-of-rules-error.d.ts +13 -0
  78. package/dist/types/src/errors/converter-options-errors/resources-path-error.d.ts +13 -0
  79. package/dist/types/src/errors/limitation-errors/index.d.ts +27 -0
  80. package/dist/types/src/errors/limitation-errors/max-scanned-rules-error.d.ts +18 -0
  81. package/dist/types/src/errors/limitation-errors/too-many-error.d.ts +33 -0
  82. package/dist/types/src/errors/limitation-errors/too-many-regexp-rules-error.d.ts +21 -0
  83. package/dist/types/src/errors/limitation-errors/too-many-rules-error.d.ts +21 -0
  84. package/dist/types/src/errors/limitation-errors/too-many-unsafe-rules-error.d.ts +21 -0
  85. package/dist/types/src/errors/unavailable-sources-errors/unavailable-filter-source-error.d.ts +19 -0
  86. package/dist/types/src/errors/unavailable-sources-errors/unavailable-ruleset-source-error.d.ts +19 -0
  87. package/dist/types/src/filter/filter.d.ts +74 -0
  88. package/dist/types/src/filter/types.d.ts +45 -0
  89. package/dist/types/src/filter-converter/conversion-result.d.ts +35 -0
  90. package/dist/types/src/filter-converter/filter-converter-options.d.ts +81 -0
  91. package/dist/types/src/filter-converter/filter-converter.d.ts +197 -0
  92. package/dist/types/src/index.d.ts +37 -0
  93. package/dist/types/src/rule/rule-types.d.ts +33 -0
  94. package/dist/types/src/rule/rule-validator.d.ts +185 -0
  95. package/dist/types/src/rule/rule.d.ts +269 -0
  96. package/dist/types/src/ruleset/metadata-ruleset.d.ts +128 -0
  97. package/dist/types/src/ruleset/rules-hash-map.d.ts +70 -0
  98. package/dist/types/src/ruleset/ruleset-with-source-map.d.ts +318 -0
  99. package/dist/types/src/ruleset/ruleset.d.ts +86 -0
  100. package/dist/types/src/ruleset/source-map.d.ts +45 -0
  101. package/dist/types/src/ruleset/types.d.ts +68 -0
  102. package/dist/types/src/utils/is-safe-rule.d.ts +20 -0
  103. package/dist/types/src/utils/ruleset-utils.d.ts +45 -0
  104. package/dist/types/src/version.d.ts +6 -0
  105. package/dist/url-transform-converter.js +338 -0
  106. package/dist/utils/error.js +22 -0
  107. package/dist/utils/is-safe-rule.js +25 -0
  108. package/dist/utils/lazy-loader.js +116 -0
  109. package/dist/utils/lazy.js +50 -0
  110. package/dist/utils/ruleset-utils.js +76 -0
  111. package/dist/utils/string.js +180 -0
  112. package/dist/utils/valibot.js +74 -0
  113. package/dist/version.js +7 -0
  114. package/package.json +122 -0
package/README.md ADDED
@@ -0,0 +1,476 @@
1
+ <!-- omit in toc -->
2
+ # DNR Converter
3
+
4
+ [![npm-badge]][npm-url] [![license-badge]][license-url]
5
+
6
+ [npm-badge]: https://img.shields.io/npm/v/@adguard/dnr-converter
7
+ [npm-url]: https://www.npmjs.com/package/@adguard/dnr-converter
8
+ [license-badge]: https://img.shields.io/npm/l/@adguard/dnr-converter
9
+ [license-url]: https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/dnr-converter/LICENSE
10
+
11
+ A TypeScript library that converts adblock-style filtering rules into rules
12
+ compatible with Chrome's
13
+ [Declarative Net Request (DNR)][dnr-api-url] API. It is designed for developers
14
+ building Manifest V3 browser extensions that need to translate existing AdGuard
15
+ or other adblock filter lists into the DNR format required by modern Chrome
16
+ extensions.
17
+
18
+ [dnr-api-url]: https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest
19
+
20
+ - [Key concepts](#key-concepts)
21
+ - [Supported rule types](#supported-rule-types)
22
+ - [Installation](#installation)
23
+ - [Peer dependencies](#peer-dependencies)
24
+ - [API overview](#api-overview)
25
+ - [`IFilter`](#ifilter)
26
+ - [`Filter`](#filter)
27
+ - [`ConverterOptions`](#converteroptions)
28
+ - [Simple flow: `FilterConverter` + `Ruleset`](#simple-flow-filterconverter--ruleset)
29
+ - [Advanced flow: `FilterConverter` with `withSourceMap: true` + `RulesetWithSourceMap`](#advanced-flow-filterconverter-with-withsourcemap-true--rulesetwithsourcemap)
30
+ - [`MetadataRuleset`](#metadataruleset)
31
+ - [`isSafeRule(rule)`](#issaferulerule)
32
+ - [`DNR_CONVERTER_VERSION`](#dnr_converter_version)
33
+ - [Network rule types](#network-rule-types)
34
+ - [CLI](#cli)
35
+ - [Commands](#commands)
36
+ - [Programmatic API](#programmatic-api)
37
+ - [Documentation](#documentation)
38
+
39
+ ## Key concepts
40
+
41
+ - **Filter** — an adblock filter list represented as an object with an `id` and
42
+ text `content`. Each filter list (e.g. AdGuard Base, EasyList) becomes one
43
+ `Filter` input.
44
+ - **Declarative rule** — a
45
+ [`chrome.declarativeNetRequest.Rule`][dnr-rule-url] object that the browser
46
+ evaluates natively. The converter produces these from filter text.
47
+ - **Source map** — a mapping from each generated declarative rule back to its
48
+ originating filter and rule index, enabling reverse lookup when a declarative
49
+ rule fires.
50
+ - **Rule safety** — Chrome
51
+ [classifies DNR rules][dnr-safe-rules-url] as *safe* (block, allow,
52
+ allowAllRequests, upgradeScheme) or *unsafe* (redirect, modifyHeaders). The
53
+ library exposes a helper to check safety.
54
+ - **Converter options** — limits and paths that control conversion output
55
+ (maximum rule counts, resource paths for redirects).
56
+
57
+ [dnr-rule-url]: https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#type-Rule
58
+ [dnr-safe-rules-url]: https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#safe_rules
59
+
60
+ ### Supported rule types
61
+
62
+ The converter supports virtually all adblock network rule modifiers. The known
63
+ MV3 limitations (inherent to the Declarative Net Request API) are:
64
+
65
+ **Supported modifiers** (with MV3 notes):
66
+
67
+ - Basic blocking/allowing rules, `$third-party`, `$domain` (no regexps / `.*`
68
+ TLDs), all content types (`$script`, `$image`, `$stylesheet`, etc.)
69
+ - `$important`, `$match-case`, `$method`, `$to`, `$denyallow`, `$header`
70
+ (no regex values), `$all`
71
+ - `$redirect` — allowlist rules not supported
72
+ - `$csp`, `$removeparam`, `$removeheader`, `$permissions` — allowlist rules
73
+ not supported; rules with identical conditions are combined only within the
74
+ same filter, not across filters
75
+ - `$urltransform` — limited; complex transforms produce multiple declarative
76
+ rules via pipeline stages
77
+ - `$cookie` — limited; only supported without parameters (bare `$cookie`)
78
+ - `$badfilter` — partial: does not handle `$domain` intersections correctly
79
+
80
+ **Not yet supported / not convertible to DNR**:
81
+
82
+ - `$popup`, `$redirect-rule`, `$referrerpolicy` — not yet implemented
83
+ - `$replace`, `$jsonprune`, `$hls`, `$network`, DNS modifiers (`$client`,
84
+ `$dnsrewrite`, `$dnstype`, `$ctag`) — not expressible in DNR; produce
85
+ conversion errors and are skipped
86
+ - Exception modifiers `$jsinject`, `$stealth`, `$urlblock`, `$genericblock` —
87
+ not yet implemented
88
+ - `$webrtc` — deprecated and not supported
89
+
90
+ For detailed conversion examples with output, see
91
+ [Conversion Examples](src/examples/README.md).
92
+
93
+ ## Installation
94
+
95
+ ```bash
96
+ # pnpm
97
+ pnpm install @adguard/dnr-converter
98
+
99
+ # yarn
100
+ yarn add @adguard/dnr-converter
101
+
102
+ # npm
103
+ npm install @adguard/dnr-converter
104
+ ```
105
+
106
+ ### Peer dependencies
107
+
108
+ The package requires [`@adguard/re2-wasm`](https://www.npmjs.com/package/@adguard/re2-wasm)
109
+ (`1.2.0`) as a peer dependency for regex validation.
110
+
111
+ ## API overview
112
+
113
+ The library uses a single `FilterConverter` class with **two conversion modes**
114
+ selected by the `withSourceMap` option:
115
+
116
+ | | Simple mode (default) | Advanced mode (`withSourceMap: true`) |
117
+ | --- | --- | --- |
118
+ | **Converter** | `FilterConverter` | `FilterConverter` |
119
+ | **Ruleset** | `Ruleset` (sync, in-memory) | `RulesetWithSourceMap` (lazy-load, source map) |
120
+ | **Input filter** | `IFilter` | `IFilter` |
121
+ | **Use case** | When you only need `DeclarativeRule[]` output from plain filter text | When you need source maps, `$badfilter` cross-filter application, and serialization |
122
+
123
+ ### `IFilter`
124
+
125
+ ```ts
126
+ import type { IFilter } from '@adguard/dnr-converter';
127
+ ```
128
+
129
+ Single interface used by both conversion flows:
130
+
131
+ | Method | Type | Description |
132
+ | --- | --- | --- |
133
+ | `getId()` | `number` | Unique filter identifier |
134
+ | `getContent()` | `Promise<string>` | Returns the full text of the filter list |
135
+ | `getRuleByIndex(index)` | `Promise<string>` | Returns original rule text by character offset |
136
+ | `unloadContent()` | `void` | Releases loaded content from memory |
137
+
138
+ ### `Filter`
139
+
140
+ The single concrete `IFilter` implementation shipped by the library supports two
141
+ construction modes:
142
+
143
+ - **Pre-loaded** (`new Filter(id, content: string)`) — accepts the filter text
144
+ directly as a string. `getContent()` resolves immediately; `unloadContent()`
145
+ is a no-op. Use for simple conversion or when content is already in memory.
146
+
147
+ - **Lazy-loaded** (`new Filter(id, source: () => Promise<string>)`) —
148
+ accepts an async callback that fetches the content on demand. Supports promise
149
+ deduplication across concurrent callers, and `unloadContent()` releases the
150
+ cached content. Use with `withSourceMap: true` (advanced mode).
151
+
152
+ ```ts
153
+ import { Filter } from '@adguard/dnr-converter';
154
+
155
+ // Pre-loaded (simple mode)
156
+ const filter = new Filter(1, '||example.com^');
157
+
158
+ // Lazy-loaded (advanced mode with withSourceMap: true)
159
+ const lazyFilter = new Filter(1, async () => fetchFilterText());
160
+ ```
161
+
162
+ ### `ConverterOptions`
163
+
164
+ ```ts
165
+ import type { ConverterOptions } from '@adguard/dnr-converter';
166
+ ```
167
+
168
+ Configuration for the conversion process:
169
+
170
+ | Property | Type | Description |
171
+ | --- | --- | --- |
172
+ | `resourcesPath` | `string?` | Path to web-accessible resources relative to the extension root (starts with `/`, no trailing `/`). Required for `$redirect` rules. |
173
+ | `maxNumberOfRules` | `number?` | Maximum total declarative rules to produce. Excess rules are trimmed. |
174
+ | `maxNumberOfUnsafeRules` | `number?` | Maximum unsafe (dynamic) rules allowed. |
175
+ | `maxNumberOfRegexpRules` | `number?` | Maximum rules using `regexFilter`. |
176
+ | `combine` | `boolean?` | Merge all input filters into a single combined rule set. |
177
+ | `withSourceMap` | `boolean?` | When `true`, returns `RulesetWithSourceMap` instead of `Ruleset`. Enables source maps, `$badfilter` cross-filter support, and lazy loading. |
178
+ | `badFilterRules` | `Rule[]?` | Static `$badfilter` rules to apply at scan time (`withSourceMap: true` only). |
179
+
180
+ ### Simple flow: `FilterConverter` + `Ruleset`
181
+
182
+ Use this flow when you only need `DeclarativeRule[]` output from plain filter
183
+ text, without source maps or lazy loading.
184
+
185
+ ```ts
186
+ import { FilterConverter, Filter } from '@adguard/dnr-converter';
187
+
188
+ const filter = new Filter(1, '||example.com^\n@@||example.com/path^');
189
+
190
+ const converter = new FilterConverter();
191
+ const [{ ruleset, errors, limitations }] = await converter.convert([filter]);
192
+
193
+ console.log(ruleset.getDeclarativeRules()); // DeclarativeRule[]
194
+ console.log(ruleset.getSafeRulesCount()); // 2
195
+ console.log(errors.length); // 0
196
+ ```
197
+
198
+ **Combine multiple filters into one ruleset:**
199
+
200
+ ```ts
201
+ const [{ ruleset }] = await converter.convert(
202
+ [filter1, filter2],
203
+ { combine: true },
204
+ );
205
+ // ruleset.getId() === FilterConverter.COMBINED_RULESET_ID
206
+ ```
207
+
208
+ **Serialize and restore:**
209
+
210
+ ```ts
211
+ const json = ruleset.serialize(); // JSON string of DeclarativeRule[]
212
+
213
+ const { Ruleset } = await import('@adguard/dnr-converter');
214
+ const restored = Ruleset.deserialize(ruleset.getId(), json);
215
+ ```
216
+
217
+ `Ruleset` (returned by default, without `withSourceMap`) implements `IRuleset`:
218
+
219
+ | Method | Returns | Description |
220
+ | --- | --- | --- |
221
+ | `getId()` | `string` | Rule set identifier (e.g. `"ruleset_1"`) |
222
+ | `getSafeRulesCount()` | `number` | Count of safe declarative rules (excludes unsafe) |
223
+ | `getUnsafeRulesCount()` | `number` | Count of unsafe rules |
224
+ | `getRegexpRulesCount()` | `number` | Count of regexp-based rules |
225
+ | `getDeclarativeRules()` | `DeclarativeRule[]` | All converted DNR rules (synchronous) |
226
+ | `serialize()` | `string` | JSON serialization of declarative rules |
227
+ | `Ruleset.deserialize(id, json)` | `Ruleset` | Static: reconstruct from serialized JSON |
228
+
229
+ ### Advanced flow: `FilterConverter` with `withSourceMap: true` + `RulesetWithSourceMap`
230
+
231
+ Use this mode in browser extension internals when you need source maps,
232
+ `$badfilter` cross-filter application, serialization with hash maps, and lazy
233
+ content loading. Pass `withSourceMap: true` in the options to get
234
+ `RulesetWithSourceMap` results.
235
+
236
+ ```ts
237
+ import { Filter, FilterConverter } from '@adguard/dnr-converter';
238
+
239
+ const filter = new Filter(1, async () => '||example.com^\n@@||example.com/path^');
240
+
241
+ const converter = new FilterConverter();
242
+ const [{ ruleset, errors }] = await converter.convert([filter], { withSourceMap: true });
243
+
244
+ const declarativeRules = await ruleset.getDeclarativeRules(); // Promise<DeclarativeRule[]>
245
+ const sources = await ruleset.getRulesById(declarativeRules[0].id);
246
+ console.log(sources[0].sourceRule); // '||example.com^'
247
+ ```
248
+
249
+ **Apply `$badfilter` from dynamic filters against static rule sets:**
250
+
251
+ ```ts
252
+ const [{ ruleset: dynamicRuleset }] = await converter.convert(
253
+ [dynamicFilter],
254
+ { withSourceMap: true },
255
+ );
256
+ const rulesToDisable = await converter.computeRulesToDisable(
257
+ [dynamicRuleset],
258
+ [staticRuleset],
259
+ );
260
+ // rulesToDisable: UpdateStaticRulesOptions[]
261
+ ```
262
+
263
+ `RulesetWithSourceMap` (returned when `withSourceMap: true`) implements
264
+ `IRulesetWithSourceMap`:
265
+
266
+ | Method | Returns | Description |
267
+ | --- | --- | --- |
268
+ | `getId()` | `string` | Rule set identifier |
269
+ | `getSafeRulesCount()` | `number` | Count of safe declarative rules (excludes unsafe) |
270
+ | `getUnsafeRulesCount()` | `number` | Count of unsafe rules |
271
+ | `getRegexpRulesCount()` | `number` | Count of regexp-based rules |
272
+ | `getDeclarativeRules()` | `Promise<DeclarativeRule[]>` | All converted DNR rules (lazy) |
273
+ | `getUnsafeRules()` | `Promise<DeclarativeRule[]>` | Unsafe rules subset (lazy) |
274
+ | `getRulesById(id)` | `Promise<SourceRuleAndFilterId[]>` | Source rules for a DNR rule |
275
+ | `getBadFilterRules()` | `NetworkRule[]` | `$badfilter` rules in this set |
276
+ | `getRulesHashMap()` | `IRulesHashMap` | Hash map for fast `$badfilter` matching |
277
+ | `serializeCompact(unsafeRules, prettyPrint?)` | `Promise<string>` | Compact JSON serialization |
278
+ | `unloadContent()` | `void` | Release lazy-loaded content |
279
+
280
+ ```ts
281
+ import type { ConversionResult } from '@adguard/dnr-converter';
282
+ ```
283
+
284
+ Result returned by converter methods:
285
+
286
+ | Property | Type | Description |
287
+ | --- | --- | --- |
288
+ | `ruleset` | `IRuleset` / `IRulesetWithSourceMap` | The converted rule set |
289
+ | `errors` | `(ConversionError \| Error)[]` | Rules that could not be converted |
290
+ | `limitations` | `LimitationError[]` | Warnings about exceeded limits |
291
+ | `declarativeRulesToCancel` | `UpdateStaticRulesOptions[]?` | Static rule IDs to disable (from `computeRulesToDisable`) |
292
+
293
+ ### `MetadataRuleset`
294
+
295
+ ```ts
296
+ import { MetadataRuleset, METADATA_RULESET_ID } from '@adguard/dnr-converter';
297
+ ```
298
+
299
+ A specialized ruleset that stores checksums and additional properties for a
300
+ collection of DNR rule sets. It serializes as a single-element JSON array
301
+ containing a declarative rule with a `metadata` field, acting as a data
302
+ carrier within serialized ruleset files (never matches real requests).
303
+
304
+ `METADATA_RULESET_ID` is the constant `0`; the ruleset's string ID is always
305
+ `"ruleset_0"`.
306
+
307
+ **Checksum methods:**
308
+
309
+ | Method | Returns | Description |
310
+ | --- | --- | --- |
311
+ | `getId()` | `string` | Always `"ruleset_0"` |
312
+ | `setChecksum(rulesetId, checksum)` | `void` | Store checksum for a rule set |
313
+ | `getChecksum(rulesetId)` | `string \| undefined` | Retrieve checksum, or `undefined` if not set |
314
+ | `getRulesetIds()` | `string[]` | All rule set IDs that have checksums |
315
+
316
+ **Additional-property methods:**
317
+
318
+ | Method | Returns | Description |
319
+ | --- | --- | --- |
320
+ | `setAdditionalProperty(key, value)` | `void` | Store an arbitrary JSON-serializable property |
321
+ | `getAdditionalProperty(key)` | `unknown \| undefined` | Retrieve a property value |
322
+ | `hasAdditionalProperty(key)` | `boolean` | Check whether a property exists |
323
+ | `removeAdditionalProperty(key)` | `void` | Remove a property (no-op if missing) |
324
+
325
+ **Serialization:**
326
+
327
+ | Method | Returns | Description |
328
+ | --- | --- | --- |
329
+ | `serialize(pretty?)` | `string` | JSON string; `pretty=true` for human-readable output |
330
+ | `MetadataRuleset.deserialize(json)` | `MetadataRuleset` | Reconstruct from a serialized string; throws on invalid input |
331
+
332
+ ```ts
333
+ const meta = new MetadataRuleset();
334
+ meta.setChecksum('ruleset_1', 'abc123');
335
+ meta.setAdditionalProperty('version', '2.0');
336
+
337
+ const json = meta.serialize();
338
+ const restored = MetadataRuleset.deserialize(json);
339
+
340
+ console.log(restored.getChecksum('ruleset_1')); // "abc123"
341
+ console.log(restored.getAdditionalProperty('version')); // "2.0"
342
+ ```
343
+
344
+ ### `isSafeRule(rule)`
345
+
346
+ ```ts
347
+ import { isSafeRule } from '@adguard/dnr-converter';
348
+
349
+ // DeclarativeRule from the DNR API
350
+ const rule = {
351
+ id: 2,
352
+ priority: 1,
353
+ action: { type: 'block' },
354
+ condition: { urlFilter: 'example.com' },
355
+ };
356
+
357
+ isSafeRule(rule); // true — "block" is a safe action
358
+ ```
359
+
360
+ Returns `true` if the declarative rule's action is one of the
361
+ [safe rule actions][dnr-safe-rules-url] (`block`, `allow`,
362
+ `allowAllRequests`, `upgradeScheme`). Useful for separating safe static rules
363
+ from unsafe dynamic rules that require additional review.
364
+
365
+ ### `DNR_CONVERTER_VERSION`
366
+
367
+ ```ts
368
+ import { DNR_CONVERTER_VERSION } from '@adguard/dnr-converter';
369
+
370
+ console.log(DNR_CONVERTER_VERSION); // e.g. "0.0.1"
371
+ ```
372
+
373
+ A string constant with the current library version.
374
+
375
+ ### Network rule types
376
+
377
+ The package exports types related to network rule parsing and validation:
378
+
379
+ ```ts
380
+ import {
381
+ Rule,
382
+ HttpHeaderMatcher,
383
+ RuleDeclarativeValidator,
384
+ } from '@adguard/dnr-converter';
385
+ ```
386
+
387
+ - **`Rule`** — parsed network rule with accessors for domains, resource
388
+ types, methods, advanced modifier values, priority, and option flags.
389
+ Create instances via `Rule.createFromText(filterListId, index, text)`.
390
+ - **`HttpHeaderMatcher`** — type describing the parsed `$header` modifier
391
+ value.
392
+ - **`RuleDeclarativeValidator`** — static helper that checks whether a
393
+ `Rule` can be converted to a DNR rule. Call
394
+ `RuleDeclarativeValidator.shouldConvertRule(rule)` — returns
395
+ `true` if the rule is convertible, `false` if it should be silently skipped,
396
+ or throws `UnsupportedModifierError` if the rule uses an unsupported
397
+ modifier.
398
+
399
+ ## CLI
400
+
401
+ The package ships a `dnr-converter` command-line tool for converting filter
402
+ lists to DNR rulesets and extracting filter content back from compiled rulesets.
403
+
404
+ ### Commands
405
+
406
+ #### `convert`
407
+
408
+ Converts AdGuard filter lists from a metadata directory into DNR rulesets.
409
+
410
+ ```bash
411
+ dnr-converter convert \
412
+ ./filters \
413
+ ./resources \
414
+ ./dist/rulesets
415
+ ```
416
+
417
+ **Arguments:**
418
+
419
+ | Argument | Description | Default |
420
+ | --- | --- | --- |
421
+ | `<filters_and_metadata_dir>` | Directory containing `filters.json` and filter list files | *(required)* |
422
+ | `<resources_dir>` | Directory with redirect resources | *(required)* |
423
+ | `[dest_rule_sets_dir]` | Output directory for generated rulesets | `./build/rulesets` |
424
+
425
+ **Options:**
426
+
427
+ | Option | Description | Default |
428
+ | --- | --- | --- |
429
+ | `--debug` | Enable debug logging | `false` |
430
+ | `--prettify-json <bool>` | Pretty-print JSON output files | `true` |
431
+ | `--additional-properties <json>` | Additional properties to include in the metadata ruleset as JSON string | `{}` |
432
+
433
+ The `filters.json` metadata file must be an array of filter metadata objects
434
+ each with at minimum `filterId` and `name` fields.
435
+
436
+ #### `extract-filters`
437
+
438
+ Extracts original filter list content that was embedded in compiled DNR rulesets
439
+ by the `convert` command.
440
+
441
+ ```bash
442
+ dnr-converter extract-filters \
443
+ ./dist/rulesets \
444
+ ./extracted-filters
445
+ ```
446
+
447
+ **Arguments:**
448
+
449
+ | Argument | Description |
450
+ | --- | --- |
451
+ | `<path-to-rulesets>` | Directory containing compiled ruleset files |
452
+ | `<path-to-output>` | Directory to write extracted filter files |
453
+
454
+ ### Programmatic API
455
+
456
+ The CLI logic is also available as a programmatic API via the
457
+ `@adguard/dnr-converter/cli` subpath export:
458
+
459
+ ```ts
460
+ import { convertFilters, generateMD5Hash, type ConvertFiltersOptions } from '@adguard/dnr-converter/cli';
461
+
462
+ await convertFilters(
463
+ './filters',
464
+ './resources',
465
+ './dist/rulesets',
466
+ { debug: true, prettifyJson: true },
467
+ );
468
+ ```
469
+
470
+ ## Documentation
471
+
472
+ - [Changelog](CHANGELOG.md)
473
+ - [Development](DEVELOPMENT.md)
474
+ - [Migration from tsurlfilter](MIGRATION.md)
475
+ - [Conversion Examples](src/examples/README.md)
476
+ - [LLM agent rules](AGENTS.md)