findCanonical

The main function to find the canonical URL for a feed.

findCanonical()

Finds the canonical URL for a given feed URL by fetching, parsing, and testing URL candidates.

Parameters

Parameter	Type	Description
inputUrl	string	The feed URL to canonicalize
options	object	Optional configuration

Options

Option	Type	Default	Description
parser	ParserAdapter	defaultParser	Custom feed parser. See Feed Parsing
fetchFn	FetchFn	defaultFetch	Custom fetch function. See Data Fetching
cleanUrlFn	(url: string) => string	—	Clean URLs before candidate generation (e.g. urlpurify). Query edits are trusted, a changed host or path is verified first. See URL Tiers
existsFn	ExistsFn	—	Database lookup function. See Using Callbacks
tiers	Tier[]	defaultTiers	URL normalization tiers. See URL Tiers
rewrites	Rewrite[]	—	URL rewrites. See URL Rewrites
probes	Probe[]	—	URL probes for testing alternate URL forms. See URL Probes
maxHops	number	20	After this many redirects in one call, the search stops moving to further redirect targets. Every redirect counts, temporary ones and those of failed requests included. With 0 the search never moves to a redirect target. The search also stops moving after twice as many targets, which only a cleanUrlFn that returns a new URL on every call reaches. A value that is not a finite number counts as the default. See How It Works
onFetch	OnFetchFn	—	Callback after each fetch. See Using Callbacks
onMatch	OnMatchFn	—	Callback when URL matches. See Using Callbacks
onExists	OnExistsFn	—	Callback when URL exists. See Using Callbacks
onCanonical	OnCanonicalFn	—	Callback with the returned URL and the response that served it, the place to read the canonical response. See Using Callbacks

Returns

Promise<string | undefined>: The canonical URL, or undefined if the feed is invalid or unreachable. The promise never rejects: an error thrown by any option you pass in, such as existsFn or onMatch, resolves to undefined as well. A few errors only skip one step and the lookup carries on: a rewrite or probe that throws, and a parser that throws on a candidate's body.

Example

import { findCanonical } from 'feedcanon'

const url = await findCanonical('https://www.example.com/feed/?utm_source=rss')

// 'https://example.com/feed'