@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.
- package/README.md +476 -0
- package/dist/cli.cjs +58912 -0
- package/dist/constants.js +23 -0
- package/dist/declarative-rule/declarative-rule.js +15 -0
- package/dist/declarative-rule/header-info.js +12 -0
- package/dist/declarative-rule/modify-header-info.js +31 -0
- package/dist/declarative-rule/query-key-value.js +12 -0
- package/dist/declarative-rule/query-transform.js +12 -0
- package/dist/declarative-rule/redirect.js +14 -0
- package/dist/declarative-rule/rule-action.js +44 -0
- package/dist/declarative-rule/rule-condition.js +77 -0
- package/dist/declarative-rule/url-transform.js +30 -0
- package/dist/errors/conversion-errors/empty-domains-error.js +24 -0
- package/dist/errors/conversion-errors/empty-resources-error.js +24 -0
- package/dist/errors/conversion-errors/index.js +17 -0
- package/dist/errors/conversion-errors/invalid-declarative-rule-error.js +22 -0
- package/dist/errors/conversion-errors/unsupported-modifier-error.js +20 -0
- package/dist/errors/conversion-errors/unsupported-regexp-error.js +27 -0
- package/dist/errors/converter-options-errors/empty-or-negative-number-of-rules-error.js +18 -0
- package/dist/errors/converter-options-errors/index.js +15 -0
- package/dist/errors/converter-options-errors/negative-number-of-rules-error.js +18 -0
- package/dist/errors/converter-options-errors/resources-path-error.js +18 -0
- package/dist/errors/limitation-errors/index.js +17 -0
- package/dist/errors/limitation-errors/max-scanned-rules-error.js +20 -0
- package/dist/errors/limitation-errors/too-many-error.js +28 -0
- package/dist/errors/limitation-errors/too-many-regexp-rules-error.js +25 -0
- package/dist/errors/limitation-errors/too-many-rules-error.js +25 -0
- package/dist/errors/limitation-errors/too-many-unsafe-rules-error.js +25 -0
- package/dist/errors/unavailable-sources-errors/unavailable-filter-source-error.js +21 -0
- package/dist/errors/unavailable-sources-errors/unavailable-ruleset-source-error.js +21 -0
- package/dist/filter/filter.js +92 -0
- package/dist/filter-converter/filter-converter.js +385 -0
- package/dist/grouped-rules-converters/url-transform-converter.js +340 -0
- package/dist/index.js +30 -0
- package/dist/package.json.js +3 -0
- package/dist/re2-regexp/re2-validator.js +37 -0
- package/dist/re2-regexp/regex-validator-extension.js +30 -0
- package/dist/re2.wasm +0 -0
- package/dist/rule/option-names.js +65 -0
- package/dist/rule/rule-badfilter.js +81 -0
- package/dist/rule/rule-priority.js +88 -0
- package/dist/rule/rule-validator.js +455 -0
- package/dist/rule/rule.js +853 -0
- package/dist/rule/string-utils.js +49 -0
- package/dist/rule-converters/csp-converter.js +105 -0
- package/dist/rule-converters/regular-rule-converter.js +789 -0
- package/dist/rule-converters/remove-header-converter.js +97 -0
- package/dist/rule-converters/rules-converter.js +365 -0
- package/dist/rule-converters/rules-grouper.js +75 -0
- package/dist/rules-scanner/rules-scanner.js +136 -0
- package/dist/ruleset/metadata-rule.js +35 -0
- package/dist/ruleset/metadata-ruleset.js +162 -0
- package/dist/ruleset/rules-hash-map.js +71 -0
- package/dist/ruleset/ruleset-with-source-map.js +406 -0
- package/dist/ruleset/ruleset.js +54 -0
- package/dist/ruleset/source-map.js +283 -0
- package/dist/types/cli/convert-filters.d.ts +32 -0
- package/dist/types/cli/index.d.ts +7 -0
- package/dist/types/cli/utils.d.ts +19 -0
- package/dist/types/src/declarative-rule/declarative-rule.d.ts +32 -0
- package/dist/types/src/declarative-rule/header-info.d.ts +31 -0
- package/dist/types/src/declarative-rule/modify-header-info.d.ts +46 -0
- package/dist/types/src/declarative-rule/query-key-value.d.ts +24 -0
- package/dist/types/src/declarative-rule/query-transform.d.ts +21 -0
- package/dist/types/src/declarative-rule/redirect.d.ts +32 -0
- package/dist/types/src/declarative-rule/rule-action.d.ts +68 -0
- package/dist/types/src/declarative-rule/rule-condition.d.ts +262 -0
- package/dist/types/src/declarative-rule/url-transform.d.ts +69 -0
- package/dist/types/src/errors/conversion-errors/empty-domains-error.d.ts +21 -0
- package/dist/types/src/errors/conversion-errors/empty-resources-error.d.ts +21 -0
- package/dist/types/src/errors/conversion-errors/index.d.ts +27 -0
- package/dist/types/src/errors/conversion-errors/invalid-declarative-rule-error.d.ts +30 -0
- package/dist/types/src/errors/conversion-errors/unsupported-modifier-error.d.ts +20 -0
- package/dist/types/src/errors/conversion-errors/unsupported-regexp-error.d.ts +23 -0
- package/dist/types/src/errors/converter-options-errors/empty-or-negative-number-of-rules-error.d.ts +13 -0
- package/dist/types/src/errors/converter-options-errors/index.d.ts +23 -0
- package/dist/types/src/errors/converter-options-errors/negative-number-of-rules-error.d.ts +13 -0
- package/dist/types/src/errors/converter-options-errors/resources-path-error.d.ts +13 -0
- package/dist/types/src/errors/limitation-errors/index.d.ts +27 -0
- package/dist/types/src/errors/limitation-errors/max-scanned-rules-error.d.ts +18 -0
- package/dist/types/src/errors/limitation-errors/too-many-error.d.ts +33 -0
- package/dist/types/src/errors/limitation-errors/too-many-regexp-rules-error.d.ts +21 -0
- package/dist/types/src/errors/limitation-errors/too-many-rules-error.d.ts +21 -0
- package/dist/types/src/errors/limitation-errors/too-many-unsafe-rules-error.d.ts +21 -0
- package/dist/types/src/errors/unavailable-sources-errors/unavailable-filter-source-error.d.ts +19 -0
- package/dist/types/src/errors/unavailable-sources-errors/unavailable-ruleset-source-error.d.ts +19 -0
- package/dist/types/src/filter/filter.d.ts +74 -0
- package/dist/types/src/filter/types.d.ts +45 -0
- package/dist/types/src/filter-converter/conversion-result.d.ts +35 -0
- package/dist/types/src/filter-converter/filter-converter-options.d.ts +81 -0
- package/dist/types/src/filter-converter/filter-converter.d.ts +197 -0
- package/dist/types/src/index.d.ts +37 -0
- package/dist/types/src/rule/rule-types.d.ts +33 -0
- package/dist/types/src/rule/rule-validator.d.ts +185 -0
- package/dist/types/src/rule/rule.d.ts +269 -0
- package/dist/types/src/ruleset/metadata-ruleset.d.ts +128 -0
- package/dist/types/src/ruleset/rules-hash-map.d.ts +70 -0
- package/dist/types/src/ruleset/ruleset-with-source-map.d.ts +318 -0
- package/dist/types/src/ruleset/ruleset.d.ts +86 -0
- package/dist/types/src/ruleset/source-map.d.ts +45 -0
- package/dist/types/src/ruleset/types.d.ts +68 -0
- package/dist/types/src/utils/is-safe-rule.d.ts +20 -0
- package/dist/types/src/utils/ruleset-utils.d.ts +45 -0
- package/dist/types/src/version.d.ts +6 -0
- package/dist/url-transform-converter.js +338 -0
- package/dist/utils/error.js +22 -0
- package/dist/utils/is-safe-rule.js +25 -0
- package/dist/utils/lazy-loader.js +116 -0
- package/dist/utils/lazy.js +50 -0
- package/dist/utils/ruleset-utils.js +76 -0
- package/dist/utils/string.js +180 -0
- package/dist/utils/valibot.js +74 -0
- package/dist/version.js +7 -0
- 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)
|