TSUrlFilter
This is a TypeScript library that implements AdGuard's content blocking rules.
- Idea
- Installation
- API description
- Documentation
Idea
The idea is to have a single library that we can reuse for the following tasks:
- Doing content blocking in our Chrome and Firefox extensions (obviously)
- Using this library for parsing rules and converting to Safari-compatible content blocking lists (see AdGuard for Safari, AdGuard for iOS)
- Using this library for validating and linting filter lists (see FiltersRegistry, AdguardFilters)
Installation
You can install the package via:
- Yarn:
yarn add @adguard/tsurlfilter - NPM:
npm install @adguard/tsurlfilter - PNPM:
pnpm install @adguard/tsurlfilter
API description
Public properties
TSURLFILTER_VERSION
type: string
Version of the library.
Public classes
Engine
Engine is a main class of this library. It represents the filtering functionality for loaded rules
Factory
You can create engine via factories. There are two modes: sync and async.
Important: The content field in EngineFactoryOptions accepts either
a raw string or a FilterList instance.
If you provide a string, it will be automatically wrapped
in a FilterList and converted.
If you provide a FilterList instance, you have full control
over the conversion process by optionally providing conversion data
to the FilterList constructor.
Note: tsurlfilter only supports AdGuard filter syntax.
If you need to convert rules from other syntaxes
(e.g., uBlock Origin, Adblock Plus), use the FilterList class
which automatically converts rules to AdGuard format
via RawRuleConverter.convertToAdg().
This conversion should be done at the filter list level
before the engine processes the rules.
Sync mode
Create engine synchronously.
/**
* Creates an instance of the network engine in sync mode.
*
* @param options Engine factory options.
*
* @returns An instance of the network engine.
*/
public static createSync(options: EngineFactoryOptions): Engine;
Async mode
Create engine asynchronously. We use this approach in AdGuard browser extension to avoid UI lags.
/**
* Creates an instance of the network engine in async mode.
*
* @param options Engine factory options.
*
* @returns An instance of the network engine.
*/
public static createAsync(options: EngineFactoryOptions): Promise<Engine>;
Example
const engine = await Engine.createAsync({
filters: [
{
id: 1,
content: '||example.com^',
},
],
});
matchRequest
/**
* Matches the specified request against the filtering engine and returns the matching result.
* In case frameRules parameter is not specified, frame rules will be selected matching request.sourceUrl.
*
* @param request - request to check
* @param frameRules - source rules or undefined
* @returns matching result
*/
matchRequest(request: Request, frameRule: NetworkRule | null = null): MatchingResult;
matchFrame
/**
* Matches current frame and returns document-level allowlist rule if found.
*
* @param frameUrl
*/
matchFrame(frameUrl: string): NetworkRule | null;
Starting engine
import { Engine, setConfiguration } from '@adguard/tsurlfilter';
const rawFilter = [
'[AdGuard]',
'! Title: Example filter',
'! Description: This is just an example filter.',
'example.com##h1',
].join('\n');
const config = {
engine: 'extension',
version: '1.0.0',
verbose: true,
};
setConfiguration(config);
// Create engine using the factory method
const engine = Engine.createSync({
filters: [
{
id: 0,
content: rawFilter,
},
],
});
console.log(`Engine loaded with ${engine.getRulesCount()} rule(s)`);
Matching requests
const request = new Request(url, sourceUrl, RequestType.Document);
const result = engine.matchRequest(request);
Retrieving cosmetic data
const cosmeticResult = engine.getCosmeticResult(request, CosmeticOption.CosmeticOptionAll);
MatchingResult
MatchingResult contains all the rules matching a web request, and provides methods that define how a web request should be processed
getBasicResult
/**
* GetBasicResult returns a rule that should be applied to the web request.
* Possible outcomes are:
* returns null -- bypass the request.
* returns a allowlist rule -- bypass the request.
* returns a blocking rule -- block the request.
*
* @returns basic result rule
*/
getBasicResult(): NetworkRule | null;
getDocumentBlockingResult
/**
* Returns a rule that should block a document request.
*
* @returns Document blocking rule if any, null otherwise.
*/
getDocumentBlockingResult(): NetworkRule | null;
getCosmeticOption
This flag should be used for getCosmeticResult(request: Request, option: CosmeticOption)
/**
* Returns a bit-flag with the list of cosmetic options
*
* @returns {CosmeticOption} mask
*/
getCosmeticOption(): CosmeticOption;
Other rules
/**
* Return an array of replace rules
*/
getReplaceRules(): NetworkRule[]
/**
* Returns an array of csp rules
*/
getCspRules(): NetworkRule[]
/**
* Returns an array of cookie rules
*/
getCookieRules(): NetworkRule[]
CosmeticResult
Cosmetic result is the representation of matching cosmetic rules. It contains the following properties:
/**
* Storage of element hiding rules
*/
public elementHiding: CosmeticStylesResult;
/**
* Storage of CSS rules
*/
public CSS: CosmeticStylesResult;
/**
* Storage of JS rules
*/
public JS: CosmeticScriptsResult;
/**
* Storage of Html filtering rules
*/
public Html: CosmeticHtmlResult;
/**
* Script rules
*/
public getScriptRules(): CosmeticRule[];
Applying cosmetic result - CSS
const css = [...cosmeticResult.elementHiding.generic, ...cosmeticResult.elementHiding.specific]
.map((rule) => `${rule.getContent()} { display: none!important; }`);
const styleText = css.join('\n');
const injectDetails = {
code: styleText,
runAt: 'document_start',
};
chrome.tabs.insertCSS(tabId, injectDetails);
Applying cosmetic result - scripts
const cosmeticRules = cosmeticResult.getScriptRules();
const scriptsCode = cosmeticRules.map((x) => x.getScript()).join('\r\n');
const toExecute = buildScriptText(scriptsCode);
chrome.tabs.executeScript(tabId, {
code: toExecute,
});
DnsEngine
DNSEngine combines host rules and network rules and is supposed to quickly find matching rules for hostnames.
Constructor
/**
* Builds an instance of dns engine
*
* @param storage
*/
constructor(storage: RuleStorage);
match
/**
* Match searches over all filtering and host rules loaded to the engine
*
* @param hostname to check
* @returns dns result object
*/
public match(hostname: string): DnsResult;
Matching hostname
const dnsResult = dnsEngine.match(hostname);
if (dnsResult.basicRule && !dnsResult.basicRule.isAllowlist()) {
// blocking rule found
...
}
if (dnsResult.hostRules.length > 0) {
// hosts rules found
...
}
RuleSyntaxUtils
This module is not used in the engine directly, but it can be used in other libraries
Public methods
/**
* Checks if rule can be matched by domain
*
* @param ruleText Rule text
* @param domain Domain to check
*/
public static isRuleForDomain(ruleText: string, domain: string): boolean
/**
* Checks if rule can be matched by URL
*
* @param ruleText Rule text
* @param url URL to check
*/
public static isRuleForUrl(ruleText: string, url: string): boolean;
FilterList
FilterList is a class that represents a converted filter list
with efficient access to both converted and original rule content.
Key Features
- Automatic Rule Conversion: Converts filter rules to AdGuard format using
RawRuleConverter.convertToAdg() - O(1) Access: Provides constant-time access to original filtering rules via conversion data
- Bidirectional Mapping: Maintains mappings between converted and original rules
- Content Restoration: Can restore the original filter list from converted content
Constructor
/**
* Creates a new FilterList instance.
*
* @param content Filter list content.
* @param data Optional conversion data. If not provided, the filter list will be prepared.
*/
constructor(content: string, data?: ConversionData)
Conversion Data Structure
The ConversionData interface tracks the relationship between converted and original rules:
interface ConversionData {
/**
* Original filter list rules that were converted.
*/
originals: string[];
/**
* Conversion map.
* Maps line start offsets in the converted content to indexes in the originals array.
* Keys are 0-based line start offsets, values are 0-based indexes in originals array.
*/
conversions: Record<number, number>;
}
Main Methods
Getting Converted Content
/**
* Returns the converted content.
*/
public getContent(): string;
Getting Rule Text
/**
* Returns the rule text for a given offset in the converted content.
* This may be a converted rule.
*
* @param offset Line start offset in the converted content.
* @returns Rule as string, or null if not found.
*/
public getRuleText(offset: number): string | null;
Getting Original Rule Text
/**
* Returns the original rule text for a given offset.
* If the rule was converted, returns the original from conversion data.
* If not converted, returns the rule text (which is already the original).
*
* @param offset Line start offset in the converted content.
* @returns Original rule text, or null if offset is invalid.
*/
public getOriginalRuleText(offset: number): string | null;
Getting Converted Rule Original (Strict)
/**
* Returns the original rule text only if the rule was actually converted.
* Unlike getOriginalRuleText(), this returns null for unconverted rules.
*
* @param offset Line start offset in the converted content.
* @returns Original rule text if converted, or null if not converted or invalid offset.
*/
public getConvertedRuleOriginal(offset: number): string | null;
Restoring Original Content
/**
* Restores the original filter list content from the converted content.
*
* @returns Original filter list content.
*/
public getOriginalContent(): string;
Static Methods
/**
* Creates an empty converted filter list.
*/
public static createEmpty(): FilterList;
/**
* Creates an empty conversion data.
*/
public static createEmptyConversionData(): ConversionData;
Usage Example
import { FilterList } from '@adguard/tsurlfilter';
// Create a filter list (automatically converts rules)
const filterList = new FilterList('||example.com^$third-party');
// Get converted content
const converted = filterList.getContent();
// Get rule at specific offset
const rule = filterList.getRuleText(0);
// Get original rule if it was converted
const original = filterList.getOriginalRuleText(0);
// Restore full original content
const originalContent = filterList.getOriginalContent();
// Create from existing conversion data (no re-conversion)
const data = filterList.getConversionData();
const filterList2 = new FilterList(converted, data);