Hierarchy (View Summary)

Constructors

Properties

sourceID: string

A short lower-case string, e.g., 'wikidata'

sourceURL: string

The most canonical URL for the source

supportedFields: string[]

Array of 'thing' properties this adapter supports (e.g., 'label', 'description')

supportedPattern: RegExp

Regular expression which determines whether this adapter supports a given URL

throttleMs: number = 0

Minimum milliseconds to wait between requests to this adapter's API. Set to 0 to disable throttling.

Methods

  • Internal lookup implementation to be provided by each adapter. Do not call directly - use lookup() which handles throttling.

    All text strings returned in AdapterMultilingualString objects MUST be in "HTML-safe text" format:

    • HTML entities are escaped (e.g., &&amp;, <&lt;)
    • HTML tags are stripped/rejected
    • Safe to render directly in HTML templates without additional escaping

    For text from external APIs, use this three-step sanitization:

    import { decodeHTML } from 'entities';
    import escapeHTML from 'escape-html';
    import stripTags from 'striptags';

    const safeText = escapeHTML(stripTags(decodeHTML(externalValue)));

    This pattern:

    1. Decodes any existing entities to plain text
    2. Strips HTML tags
    3. Escapes entities for safe HTML storage

    Not all adapters need all three steps - adjust based on the format your external API returns. If it already returns plain text with no entities or tags, only escapeHTML() may be needed.

    Parameters

    • url: string

    Returns Promise<AdapterLookupResult>

  • Perform a lookup for a given URL with automatic throttling. Waits if necessary to respect the adapter's throttleMs setting. Ensures requests are serialized per adapter instance, even with concurrent callers. Implementations should override _lookup() instead of this method.

    Parameters

    • url: string

    Returns Promise<AdapterLookupResult>