To avoid hammering remote servers (and to keep your build times reasonable),
results are persisted to a cache. The cache is **pluggable**: a default
[lowdb][]-backed JSON file is provided out of the box, and you can swap in
your own backend (Redis, KV, in-memory, etc.) by implementing a tiny
two-method interface.

## When should I use this?

Use this plugin if you publish content with many external references — blog
posts, link round-ups, documentation — and you want hover tooltips to display
the actual page title rather than the raw URL.

You probably **shouldn't** use it if:

- Your build runs in a sandbox without outbound network access.
- You don't trust the remote pages and don't want to render their titles
(consider [`rehype-sanitize`][rehype-sanitize] downstream regardless — see
[Security](#security)).
- Build performance is more important than hover-over UX (the first build
fetches every link; subsequent builds are cache hits).

## Install

This package is [ESM only][esm]. In Node.js (version 18+):

```sh
npm install rehype-external-link-title
```

```sh
pnpm add rehype-external-link-title
```

## Use

Say we have the following input HTML:

```html

###### Parameters

- `options` ([`Options`](#options), optional) — configuration

###### Returns

Async transform.

### `Options`

Configuration (TypeScript type).

### `Cache`

The plugin treats the cache as a dumb async key/value store. TTL/staleness
handling is performed by the plugin itself, so cache implementations stay
trivial:

```ts
export interface CacheEntry {
title: string | null // `null` = "we tried and got nothing"
updatedAt: string // ISO-8601
}

export interface Cache {
get(url: string): Promise | CacheEntry | undefined
set(url: string, entry: CacheEntry): Promise | void
delete?(url: string): Promise | void // optional
}
```

Both sync and async return values are supported, so a `Map`-backed cache or a
Redis-backed cache are equally easy to write.

### Built-in caches

```ts
import {lowdbCache, memoryCache} from 'rehype-external-link-title/cache'

const persistent = lowdbCache({path: '.cache/titles.json'})
const ephemeral = memoryCache()
```

- **`lowdbCache(options?: {path?: string})`** — JSON file backed by [lowdb][].
The file is opened lazily on first use (no top-level I/O).
- **`memoryCache()`** — `Map`-backed; useful for tests or short-lived processes.

## Examples

### Custom cache path

```ts
unified().use(rehypeExternalLinkTitle, {cache: '.cache/external-link-titles.json'})
```

### Refetch every entry older than a week

```ts
unified().use(rehypeExternalLinkTitle, {ttl: 7 * 24 * 60 * 60 * 1000})
```

### Bring your own cache (Redis-style)

```ts
import type {Cache, CacheEntry} from 'rehype-external-link-title'

const redisCache: Cache = {
async get(url) {
const raw = await redis.get(`title:${url}`)
return raw ? (JSON.parse(raw) as CacheEntry) : undefined
},
async set(url, entry) {
await redis.set(`title:${url}`, JSON.stringify(entry))
},
async delete(url) {
await redis.del(`title:${url}`)
},
}

unified().use(rehypeExternalLinkTitle, {cache: redisCache})
```

### Custom User-Agent

```ts
unified().use(rehypeExternalLinkTitle, {
fetch: {userAgent: 'MyCoolBlog/1.0 (+https://example.com/about)'},
})
```

### Process only a subset of links

```ts
unified().use(rehypeExternalLinkTitle, {
test: (href) => href.startsWith('https://en.wikipedia.org/'),
})
```

## Types

This package is fully typed with [TypeScript][]. It exports the additional
types `Options`, `Cache`, `CacheEntry`, `FetchOptions`, and `LinkPredicate`.

## Compatibility

Compatible with maintained versions of Node.js (>=18). Works with `unified`
version 11+.

## Security

```ts
import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'

unified()
.use(rehypeExternalLinkTitle)
.use(rehypeSanitize, {
...defaultSchema,
attributes: {
...defaultSchema.attributes,
a: [...(defaultSchema.attributes?.a ?? []), 'title'],
},
})
```

The HTML returned by remote servers is sanitized internally with [DOMPurify][]
(stripped down to ``/``/`` only) before the title is
extracted, so malicious script tags in the source page are discarded before
parsing.

## License

[MIT][license] © [Ari Palo][author]