head-metadata 0.0.12 → 0.1.0

package/MIGRATION.md

@@ -0,0 +1,124 @@
+# Migration Guide
+
+## 0.0.x to 0.1.0
+
+`head-metadata` now uses extractor config keys as output field names. Collection
+extractors preserve every result in document order instead of writing values into
+a record, and extractor callbacks can return typed values of any shape.
+
+### Move Element Names Into Extractors
+
+Previously, the config key selected the HTML element. The extractor's `key` or
+`parent` selected the output field:
+
+```ts
+// old
+const metadata = extractHeadMetadata(html, {
+  title: titleExtractor,
+  meta: metaExtractor,
+  link: linkExtractor
+});
+```
+
+Extractors now declare their element with `tag`. Config keys name the output fields:
+
+```ts
+// new
+const metadata = extractHeadMetadata(html, {
+  pageTitle: titleExtractor,
+  meta: metaExtractor,
+  links: linkExtractor
+});
+```
+
+This allows multiple extractors to read the same element while producing different
+fields.
+
+### Replace Collection Records With Arrays
+
+Collection callbacks previously returned `{ key, value }`. Later values replaced
+earlier values with the same key:
+
+```ts
+// old
+const imageExtractor = {
+  type: 'collection',
+  parent: 'images',
+  callback: (node) => ({ key: 'og:image', value: '/image.png' })
+};
+```
+
+Collection callbacks now return the item to append. The config key selects the
+result array:
+
+```ts
+// new
+import type { TCollectionExtractor } from 'head-metadata';
+
+const imageExtractor = {
+  tag: 'meta',
+  type: 'collection',
+  callback: () => ({ property: 'og:image', content: '/image.png' })
+} satisfies TCollectionExtractor<{ property: string; content: string }>;
+
+const metadata = extractHeadMetadata(html, { images: imageExtractor });
+// metadata.images: Array<{ property: string; content: string }>
+```
+
+Collections are always present, even when no element produces a value. Repeated
+metadata is retained in document order.
+
+### Update Single Extractors
+
+Move the selected element from the config key into `tag` and remove `key`:
+
+```ts
+// old
+const descriptionExtractor = {
+  type: 'single',
+  key: 'description',
+  callback: extractDescription
+};
+
+const metadata = extractHeadMetadata(html, { meta: descriptionExtractor });
+```
+
+```ts
+// new
+import type { TSingleExtractor } from 'head-metadata';
+
+const descriptionExtractor = {
+  tag: 'meta',
+  type: 'single',
+  callback: extractDescription
+} satisfies TSingleExtractor<string>;
+
+const metadata = extractHeadMetadata(html, { description: descriptionExtractor });
+```
+
+Single extractors keep the first non-null result. Their output field is optional
+because no matching element may produce a value.
+
+### Update Built-In Extractor Results
+
+`metaExtractor` and `linkExtractor` now return structured arrays:
+
+| Old result                       | New result                                                        |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `metadata.meta.description`      | Search `metadata.meta` for `{ name: 'description' }`              |
+| `metadata.meta['og:image']`      | Filter `metadata.meta` for `{ property: 'og:image' }`             |
+| `metadata.link.icon`             | Filter `metadata.links` for entries whose `rel` includes `'icon'` |
+| Repeated keys kept only the last | Repeated entries are all retained in document order               |
+
+Use any config key you prefer. This guide uses `meta` and `links` to match the
+built-in result shapes.
+
+The new `baseExtractor` reads the first non-null `<base href>` value.
+
+### Account for Decoded Character References
+
+Extractor callbacks now receive decoded attribute values and ordinary text. For
+example, `Cats &amp; Dogs` becomes `Cats & Dogs`. Script, style, and CDATA content
+remain literal.
+
+Tokenizer and extractor errors continue to propagate to the caller.

package/README.md

@@ -10,70 +10,257 @@
         <img src="https://img.shields.io/bundlephobia/minzip/head-metadata.svg?label=minzipped%20size&style=flat&colorA=293140&colorB=FDE200" alt="NPM bundle minzipped size"/>
     </a>
     <a href="https://www.npmjs.com/package/head-metadata">
-        <img src="https://img.shields.io/npm/dt/featuer-state.svg?label=downloads&style=flat&colorA=293140&colorB=FDE200" alt="NPM total downloads"/>
+        <img src="https://img.shields.io/npm/dt/head-metadata.svg?label=downloads&style=flat&colorA=293140&colorB=FDE200" alt="NPM total downloads"/>
     </a>
     <a href="https://discord.gg/w4xE3bSjhQ">
         <img src="https://img.shields.io/discord/795291052897992724.svg?label=&logo=discord&logoColor=000000&color=293140&labelColor=FDE200" alt="Join Discord"/>
     </a>
 </p>
 
-> Status: Experimental
+`head-metadata` extracts typed values from the first `<head>` element in an HTML
+document. Choose an output field and extractor for each value you need. Single
+extractors keep one value, while collection extractors preserve repeated values in
+document order.
 
-`head-metadata` is a typesafe and straightforward utility for extracting structured metadata (like `<meta>`, `<title>`, and `<link>`) from the `<head>` of an HTML document.
+- Extract titles, base URLs, meta tags, and links without building a full-page DOM
+- Preserve repeated Open Graph images, icons, alternates, and other metadata
+- Infer result fields and value types from the extractor config
+- Decode character references in attributes and ordinary text
+- Add custom extractors for project-specific head elements
 
-## 📖 Usage
+```ts
+import { extractHeadMetadata, linkExtractor, metaExtractor, titleExtractor } from 'head-metadata';
+
+const metadata = extractHeadMetadata(
+  `<head>
+    <title>Example</title>
+    <meta property="og:image" content="/first.png">
+    <meta property="og:image" content="/second.png">
+    <link rel="icon" sizes="48x48" href="/favicon.png">
+  </head>`,
+  {
+    title: titleExtractor,
+    meta: metaExtractor,
+    links: linkExtractor
+  }
+);
+
+metadata.title; // 'Example' | undefined
+metadata.meta; // both og:image entries, in document order
+metadata.links; // [{ rel: ['icon'], sizes: ['48x48'], href: '/favicon.png' }]
+```
+
+Migrating from `0.0.x`? See [MIGRATION.md](./MIGRATION.md).
+
+## Install
+
+```bash
+npm install head-metadata
+```
 
-### Extract Metadata from `<head>`
+## Usage
+
+Pass the HTML string and an extractor config to `extractHeadMetadata()`:
 
 ```ts
-import { extractHeadMetadata, linkExtractor, metaExtractor, titleExtractor } from 'head-metadata';
+import {
+  baseExtractor,
+  extractHeadMetadata,
+  linkExtractor,
+  metaExtractor,
+  titleExtractor
+} from 'head-metadata';
+
+const metadata = extractHeadMetadata(html, {
+  title: titleExtractor,
+  baseHref: baseExtractor,
+  meta: metaExtractor,
+  links: linkExtractor
+});
+```
+
+Config keys name the output fields. Each extractor's `tag` selects the HTML element
+it receives. Multiple extractors can select the same tag and produce different
+fields.
+
+The extractor kind determines whether an output field is optional or always present:
+
+| Extractor kind | Result                                                                 |
+| -------------- | ---------------------------------------------------------------------- |
+| `single`       | First non-null result. The field is omitted when nothing produces one. |
+| `collection`   | All non-null results in document order. An empty array when unmatched. |
+
+## API
 
-const html = `
-  <html>
-    <head>
-      <title>Example</title>
-      <meta name="description" content="An example page" />
-      <link rel="canonical" href="https://example.com" />
-    </head>
-  </html>
-`;
+### `extractHeadMetadata(html, extractors)`
 
+Extracts configured values from the first `<head>` element.
+
+```ts
 const metadata = extractHeadMetadata(html, {
-	meta: metaExtractor,
-	title: titleExtractor,
-	link: linkExtractor
+  pageTitle: titleExtractor,
+  meta: metaExtractor
 });
 
-console.log(metadata);
-/*
-{
-  title: 'Example',
-  meta: {
-    description: 'An example page'
-  },
-  link: {
-    canonical: 'https://example.com'
-  }
-}
-*/
+metadata.pageTitle; // string | undefined
+metadata.meta; // TMetaMetadata[]
+```
+
+The function stops parsing after the first selected head. Tokenizer errors and
+extractor callback errors propagate to the caller.
+
+Extractor callbacks receive a `TXmlNode`:
+
+| Field        | Description                                 |
+| ------------ | ------------------------------------------- |
+| `local`      | Lowercase local element name                |
+| `prefix`     | Lowercase namespace prefix, when present    |
+| `attributes` | Attributes with decoded values              |
+| `content`    | Child nodes and non-whitespace text content |
+
+Character references are decoded in ordinary text and attribute values. Script,
+style, and CDATA content remain literal. URLs are not resolved or otherwise changed.
+
+## Built-In Extractors
+
+### `titleExtractor`
+
+Selects `<title>` and returns its trimmed text. Configure it as a single field:
+
+```ts
+const metadata = extractHeadMetadata(html, {
+  title: titleExtractor
+});
+```
+
+The first title that produces text wins. `metadata.title` is `undefined` when no
+title produces text.
+
+### `baseExtractor`
+
+Selects `<base>` and returns its `href` without resolving it:
+
+```ts
+const metadata = extractHeadMetadata(html, {
+  baseHref: baseExtractor
+});
+```
+
+The first base element with an `href` wins.
+
+### `metaExtractor`
+
+Selects `<meta>` elements and returns `TMetaMetadata[]`. Each entry preserves the
+supported attributes that are present:
+
+```ts
+const metadata = extractHeadMetadata(
+  `<head>
+    <meta name="description" content="An example page">
+    <meta property="og:image" content="/first.png">
+    <meta property="og:image" content="/second.png">
+  </head>`,
+  { meta: metaExtractor }
+);
+
+metadata.meta;
+// [
+//   { name: 'description', content: 'An example page' },
+//   { property: 'og:image', content: '/first.png' },
+//   { property: 'og:image', content: '/second.png' }
+// ]
 ```
 
-### Create Custom Extractors
+Supported fields are `charset`, `name`, `property`, `httpEquiv`, and `content`.
+An element without any supported attribute is skipped.
+
+### `linkExtractor`
+
+Selects `<link>` elements that contain both `rel` and `href`, and returns
+`TLinkMetadata[]`:
+
+```ts
+const metadata = extractHeadMetadata(
+  `<head>
+    <link rel="icon" type="image/png" sizes="32x32 48x48" href="/favicon.png">
+  </head>`,
+  { links: linkExtractor }
+);
+
+metadata.links;
+// [{
+//   rel: ['icon'],
+//   href: '/favicon.png',
+//   type: 'image/png',
+//   sizes: ['32x32', '48x48']
+// }]
+```
+
+`rel` and `sizes` are split on ASCII whitespace. Relation tokens are lowercase.
+The extractor also preserves `media` and `hreflang` when present.
+
+## Custom Extractors
+
+Use `TSingleExtractor<GValue>` for the first matching value and
+`TCollectionExtractor<GValue>` for every matching value. Return `null` to skip an
+element.
+
+```ts
+import { extractHeadMetadata, type TSingleExtractor } from 'head-metadata';
+
+const descriptionExtractor = {
+  tag: 'meta',
+  type: 'single',
+  callback: (node) => {
+    const name = node.attributes.find((attribute) => attribute.local === 'name')?.value;
+    const content = node.attributes.find((attribute) => attribute.local === 'content')?.value;
+    return name === 'description' ? (content ?? null) : null;
+  }
+} satisfies TSingleExtractor<string>;
+
+const metadata = extractHeadMetadata(html, {
+  description: descriptionExtractor
+});
+
+metadata.description; // string | undefined
+```
 
-You can write your own extractors to handle any `<head>` child element:
+Set `tag` to the lowercase HTML tag name. Config keys remain independent from tag
+names, so several extractors can read the same element:
 
 ```ts
-export const customLinkExtractor = {
-	type: 'collection' as const,
-	parent: 'link' as const,
-	callback: (node) => {
-		const rel = node.attributes.find((a) => a.local === 'rel');
-		const href = node.attributes.find((a) => a.local === 'href');
-		if (rel != null && href != null) {
-			return { key: rel.value, value: href.value };
-		}
-
-		return null;
-	}
-} satisfies TCollectionExtractor;
+const metadata = extractHeadMetadata(html, {
+  meta: metaExtractor,
+  description: descriptionExtractor
+});
 ```
+
+## Scope
+
+`head-metadata` parses HTML you already have. The calling application remains
+responsible for:
+
+- Fetching pages and following redirects
+- Limiting response size and request duration
+- Resolving relative URLs against the page URL and `<base href>`
+- Selecting preferred Open Graph, Twitter, and fallback values
+- Validating or downloading referenced resources
+
+## FAQ
+
+### Why use extractors instead of returning every head element?
+
+Extractors keep parsing separate from application policy. They also keep the result
+small and typed: callers choose the elements and output fields they need.
+
+### Are repeated metadata values preserved?
+
+Yes. Collection extractors append every non-null result in document order. This
+allows callers to choose among repeated Open Graph images, icons, and alternate
+links.
+
+### Does it parse the entire document?
+
+No. It processes only the first `<head>` selected by `xml-tokenizer`, then advances
+the tokenizer to the end of its input. The HTML string is still supplied by the
+caller; network streaming and response limits are outside this package.

package/dist/cjs/extract-head-metadata.js

@@ -1 +1 @@
-"use strict";var o=require("xml-tokenizer");function u(i,n){const r=Object.keys(n).reduce((e,s)=>(e[s]={},e),{}),t=[];return o.select(i,[[{axis:"self-or-descendant",local:"head"}]],(e,s)=>{switch(e.type){case"SelectionEnd":{s.goToEnd();break}case"ElementStart":{if(e.local in n){const l={local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,attributes:[],content:[]},a=t[t.length-1];a!=null&&a.content.push(l),t.push(l)}break}case"ElementEnd":{if(e.end.type==="Close"||e.end.type==="Empty"){const l=t[t.length-1];if(l==null)break;const a=n[l.local];if(a!=null)switch(a.type){case"collection":{const c=a.callback(l);c!=null&&(r[a.parent][c.key]=c.value);break}case"single":{const c=a.callback(l);c!=null&&(r[a.key]=c);break}}t.pop()}break}case"Attribute":{const l=t[t.length-1];l!=null&&l.attributes.push({local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,value:e.value});break}case"Text":case"Cdata":{const l=t[t.length-1];l!=null&&e.text.trim().length>0&&l.content.push(e.text);break}}},o.htmlConfig),r}exports.extractHeadMetadata=u;
+"use strict";var u=require("entities"),p=require("xml-tokenizer");function h(f,d){var r;const o=new Map,s=new Map;for(const[e,l]of Object.entries(d)){const t=(r=s.get(l.tag))!=null?r:[];t.push([e,l]),s.set(l.tag,t),l.type==="collection"&&o.set(e,[])}const n=[];p.select(f,[[{axis:"self-or-descendant",local:"head"}]],(e,l)=>{switch(e.type){case"SelectionEnd":{l.goToEnd();break}case"ElementStart":{const t=n[n.length-1];if(t==null&&!s.has(e.local)){n.push(null);break}const a={local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,attributes:[],content:[]};t==null||t.content.push(a),n.push(a);break}case"ElementEnd":{if(e.end.type==="Open")break;const t=n.pop();if(t==null)break;n[n.length-1]==null&&i(t);break}case"Attribute":{const t=n[n.length-1];t==null||t.attributes.push({local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,value:u.decodeHTMLAttribute(e.value)});break}case"Text":case"Cdata":{const t=n[n.length-1];if(t==null)break;const a=t.local==="script"||t.local==="style",c=e.type==="Cdata"||a?e.text:u.decodeHTML(e.text);c.trim().length>0&&t.content.push(c);break}}},p.htmlConfig);function i(e){var l;for(const[t,a]of(l=s.get(e.local))!=null?l:[]){if(a.type==="single"&&o.has(t))continue;const c=a.callback(e);c!=null&&(a.type==="collection"?o.get(t).push(c):o.set(t,c))}for(const t of e.content)typeof t!="string"&&i(t)}return Object.fromEntries(o)}exports.extractHeadMetadata=h;

package/dist/cjs/extractors/base-extractor.js

@@ -0,0 +1 @@
+"use strict";const r={type:"single",tag:"base",callback:l=>{var t,a;return(a=(t=l.attributes.find(({local:e})=>e==="href"))==null?void 0:t.value)!=null?a:null}};exports.baseExtractor=r;

package/dist/cjs/extractors/link-extractor.js

@@ -1 +1 @@
-"use strict";const r={type:"collection",parent:"link",callback:t=>{const e=t.attributes.find(l=>l.local==="rel"),n=t.attributes.find(l=>l.local==="href");return e!=null&&n!=null?{key:e.value,value:n.value}:null}};exports.linkExtractor=r;
+"use strict";var b=Object.defineProperty,c=Object.getOwnPropertySymbols,p=Object.prototype.hasOwnProperty,v=Object.prototype.propertyIsEnumerable,f=(r,e,t)=>e in r?b(r,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):r[e]=t,a=(r,e)=>{for(var t in e||(e={}))p.call(e,t)&&f(r,t,e[t]);if(c)for(var t of c(e))v.call(e,t)&&f(r,t,e[t]);return r};const y={type:"collection",tag:"link",callback:r=>{const e=r.attributes.find(l=>l.local==="rel"),t=r.attributes.find(l=>l.local==="href");if(e==null||t==null)return null;const n=r.attributes.find(l=>l.local==="type"),u=r.attributes.find(l=>l.local==="sizes"),i=r.attributes.find(l=>l.local==="media"),o=r.attributes.find(l=>l.local==="hreflang");return a(a(a(a({rel:s(e.value,!0),href:t.value},n!=null?{type:n.value}:{}),u!=null?{sizes:s(u.value)}:{}),i!=null?{media:i.value}:{}),o!=null?{hreflang:o.value}:{})}};function s(r,e=!1){return r.split(/[\t\n\f\r ]+/).filter(t=>t.length>0).map(t=>e?t.toLowerCase():t)}exports.linkExtractor=y;

package/dist/cjs/extractors/meta-extractor.js

@@ -1 +1 @@
-"use strict";const n={type:"collection",parent:"meta",callback:e=>{const a=e.attributes.find(t=>t.local==="charset");if(a!=null)return{key:"charset",value:a.value};const l=e.attributes.find(t=>t.local==="name"||t.local==="property"),c=e.attributes.find(t=>t.local==="content");return l!=null&&c!=null?{key:l.value,value:c.value}:null}};exports.metaExtractor=n;
+"use strict";const l={type:"collection",tag:"meta",callback:a=>{const t={};for(const{local:e,value:c}of a.attributes)switch(e){case"charset":case"name":case"property":case"content":t[e]!=null||(t[e]=c);break;case"http-equiv":t.httpEquiv!=null||(t.httpEquiv=c);break}return Object.keys(t).length>0?t:null}};exports.metaExtractor=l;

package/dist/cjs/extractors/title-extractor.js

@@ -1 +1 @@
-"use strict";const r={type:"single",key:"title",callback:e=>{const t=e.content[0];return typeof t=="string"?t.trim():null}};exports.titleExtractor=r;
+"use strict";const r={type:"single",tag:"title",callback:e=>{const t=e.content[0];return typeof t=="string"?t.trim():null}};exports.titleExtractor=r;

package/dist/cjs/index.js

@@ -1 +1 @@
-"use strict";var t=require("./extract-head-metadata.js"),r=require("./extractors/link-extractor.js"),a=require("./extractors/meta-extractor.js"),e=require("./extractors/title-extractor.js");exports.extractHeadMetadata=t.extractHeadMetadata,exports.linkExtractor=r.linkExtractor,exports.metaExtractor=a.metaExtractor,exports.titleExtractor=e.titleExtractor;
+"use strict";var t=require("./extract-head-metadata.js"),r=require("./extractors/base-extractor.js"),a=require("./extractors/link-extractor.js"),e=require("./extractors/meta-extractor.js"),c=require("./extractors/title-extractor.js");exports.extractHeadMetadata=t.extractHeadMetadata,exports.baseExtractor=r.baseExtractor,exports.linkExtractor=a.linkExtractor,exports.metaExtractor=e.metaExtractor,exports.titleExtractor=c.titleExtractor;

package/dist/esm/extract-head-metadata.js

@@ -1 +1 @@
-import{select as i,htmlConfig as p}from"xml-tokenizer";function u(r,c){const o=Object.keys(c).reduce((e,s)=>(e[s]={},e),{}),t=[];return i(r,[[{axis:"self-or-descendant",local:"head"}]],(e,s)=>{switch(e.type){case"SelectionEnd":{s.goToEnd();break}case"ElementStart":{if(e.local in c){const l={local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,attributes:[],content:[]},a=t[t.length-1];a!=null&&a.content.push(l),t.push(l)}break}case"ElementEnd":{if(e.end.type==="Close"||e.end.type==="Empty"){const l=t[t.length-1];if(l==null)break;const a=c[l.local];if(a!=null)switch(a.type){case"collection":{const n=a.callback(l);n!=null&&(o[a.parent][n.key]=n.value);break}case"single":{const n=a.callback(l);n!=null&&(o[a.key]=n);break}}t.pop()}break}case"Attribute":{const l=t[t.length-1];l!=null&&l.attributes.push({local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,value:e.value});break}case"Text":case"Cdata":{const l=t[t.length-1];l!=null&&e.text.trim().length>0&&l.content.push(e.text);break}}},p),o}export{u as extractHeadMetadata};
+import{decodeHTML as f,decodeHTMLAttribute as h}from"entities";import{select as d,htmlConfig as b}from"xml-tokenizer";function g(p,u){var r;const a=new Map,s=new Map;for(const[e,l]of Object.entries(u)){const t=(r=s.get(l.tag))!=null?r:[];t.push([e,l]),s.set(l.tag,t),l.type==="collection"&&a.set(e,[])}const n=[];d(p,[[{axis:"self-or-descendant",local:"head"}]],(e,l)=>{switch(e.type){case"SelectionEnd":{l.goToEnd();break}case"ElementStart":{const t=n[n.length-1];if(t==null&&!s.has(e.local)){n.push(null);break}const o={local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,attributes:[],content:[]};t==null||t.content.push(o),n.push(o);break}case"ElementEnd":{if(e.end.type==="Open")break;const t=n.pop();if(t==null)break;n[n.length-1]==null&&i(t);break}case"Attribute":{const t=n[n.length-1];t==null||t.attributes.push({local:e.local,prefix:e.prefix.length>0?e.prefix:void 0,value:h(e.value)});break}case"Text":case"Cdata":{const t=n[n.length-1];if(t==null)break;const o=t.local==="script"||t.local==="style",c=e.type==="Cdata"||o?e.text:f(e.text);c.trim().length>0&&t.content.push(c);break}}},b);function i(e){var l;for(const[t,o]of(l=s.get(e.local))!=null?l:[]){if(o.type==="single"&&a.has(t))continue;const c=o.callback(e);c!=null&&(o.type==="collection"?a.get(t).push(c):a.set(t,c))}for(const t of e.content)typeof t!="string"&&i(t)}return Object.fromEntries(a)}export{g as extractHeadMetadata};

package/dist/esm/extractors/base-extractor.js

@@ -0,0 +1 @@
+const r={type:"single",tag:"base",callback:a=>{var l,t;return(t=(l=a.attributes.find(({local:e})=>e==="href"))==null?void 0:l.value)!=null?t:null}};export{r as baseExtractor};

package/dist/esm/extractors/link-extractor.js

@@ -1 +1 @@
-const a={type:"collection",parent:"link",callback:t=>{const e=t.attributes.find(l=>l.local==="rel"),n=t.attributes.find(l=>l.local==="href");return e!=null&&n!=null?{key:e.value,value:n.value}:null}};export{a as linkExtractor};
+var b=Object.defineProperty,c=Object.getOwnPropertySymbols,p=Object.prototype.hasOwnProperty,v=Object.prototype.propertyIsEnumerable,f=(e,r,t)=>r in e?b(e,r,{enumerable:!0,configurable:!0,writable:!0,value:t}):e[r]=t,a=(e,r)=>{for(var t in r||(r={}))p.call(r,t)&&f(e,t,r[t]);if(c)for(var t of c(r))v.call(r,t)&&f(e,t,r[t]);return e};const y={type:"collection",tag:"link",callback:e=>{const r=e.attributes.find(l=>l.local==="rel"),t=e.attributes.find(l=>l.local==="href");if(r==null||t==null)return null;const n=e.attributes.find(l=>l.local==="type"),u=e.attributes.find(l=>l.local==="sizes"),i=e.attributes.find(l=>l.local==="media"),o=e.attributes.find(l=>l.local==="hreflang");return a(a(a(a({rel:s(r.value,!0),href:t.value},n!=null?{type:n.value}:{}),u!=null?{sizes:s(u.value)}:{}),i!=null?{media:i.value}:{}),o!=null?{hreflang:o.value}:{})}};function s(e,r=!1){return e.split(/[\t\n\f\r ]+/).filter(t=>t.length>0).map(t=>r?t.toLowerCase():t)}export{y as linkExtractor};

package/dist/esm/extractors/meta-extractor.js

@@ -1 +1 @@
-const c={type:"collection",parent:"meta",callback:e=>{const l=e.attributes.find(t=>t.local==="charset");if(l!=null)return{key:"charset",value:l.value};const a=e.attributes.find(t=>t.local==="name"||t.local==="property"),n=e.attributes.find(t=>t.local==="content");return a!=null&&n!=null?{key:a.value,value:n.value}:null}};export{c as metaExtractor};
+const l={type:"collection",tag:"meta",callback:a=>{const t={};for(const{local:e,value:c}of a.attributes)switch(e){case"charset":case"name":case"property":case"content":t[e]!=null||(t[e]=c);break;case"http-equiv":t.httpEquiv!=null||(t.httpEquiv=c);break}return Object.keys(t).length>0?t:null}};export{l as metaExtractor};

package/dist/esm/extractors/title-extractor.js

@@ -1 +1 @@
-const n={type:"single",key:"title",callback:e=>{const t=e.content[0];return typeof t=="string"?t.trim():null}};export{n as titleExtractor};
+const n={type:"single",tag:"title",callback:e=>{const t=e.content[0];return typeof t=="string"?t.trim():null}};export{n as titleExtractor};

package/dist/esm/index.js

@@ -1 +1 @@
-import{extractHeadMetadata as o}from"./extract-head-metadata.js";import{linkExtractor as e}from"./extractors/link-extractor.js";import{metaExtractor as m}from"./extractors/meta-extractor.js";import{titleExtractor as f}from"./extractors/title-extractor.js";export{o as extractHeadMetadata,e as linkExtractor,m as metaExtractor,f as titleExtractor};
+import{extractHeadMetadata as o}from"./extract-head-metadata.js";import{baseExtractor as e}from"./extractors/base-extractor.js";import{linkExtractor as m}from"./extractors/link-extractor.js";import{metaExtractor as f}from"./extractors/meta-extractor.js";import{titleExtractor as E}from"./extractors/title-extractor.js";export{e as baseExtractor,o as extractHeadMetadata,m as linkExtractor,f as metaExtractor,E as titleExtractor};

package/dist/types/extract-head-metadata.d.ts

@@ -1,7 +1,19 @@
-import { TExtractCollectionKeys, TExtractors, TExtractSingleKeys } from './types';
+import { type TCollectionExtractor, type TExtractor, type TExtractors } from './types';
+/**
+ * Extracts configured metadata from the first `<head>` element.
+ *
+ * Config keys name output fields, while each extractor's `tag` selects an HTML
+ * element. Collections contain every non-null result in document order. Singles
+ * keep the first non-null result and are omitted when no value is found.
+ *
+ * Attribute values and ordinary text are decoded before callbacks run. Script,
+ * style, and CDATA content remain literal. Tokenizer and callback errors propagate.
+ */
 export declare function extractHeadMetadata<GExtractors extends TExtractors>(html: string, extractors: GExtractors): TExtractMetadata<GExtractors>;
 export type TExtractMetadata<GExtractors extends TExtractors> = {
-    [K in TExtractSingleKeys<GExtractors>]: string;
+    [K in keyof GExtractors as GExtractors[K]['type'] extends 'collection' ? never : K]?: TExtractorResult<GExtractors[K]>;
 } & {
-    [K in TExtractCollectionKeys<GExtractors>]: Record<string, string>;
+    [K in keyof GExtractors as GExtractors[K]['type'] extends 'collection' ? K : never]: TExtractorResult<GExtractors[K]>;
 };
+type TExtractorResult<GExtractor extends TExtractor> = GExtractor extends TCollectionExtractor ? NonNullable<ReturnType<GExtractor['callback']>>[] : NonNullable<ReturnType<GExtractor['callback']>>;
+export {};

package/dist/types/extractors/base-extractor.d.ts

@@ -0,0 +1,6 @@
+/** Extracts the unresolved `href` from a `<base>` element. */
+export declare const baseExtractor: {
+    type: "single";
+    tag: string;
+    callback: (node: import("xml-tokenizer").TXmlNode) => string | null;
+};

package/dist/types/extractors/index.d.ts

@@ -1,3 +1,4 @@
+export * from './base-extractor';
 export * from './link-extractor';
 export * from './meta-extractor';
 export * from './title-extractor';

package/dist/types/extractors/link-extractor.d.ts

@@ -1,8 +1,21 @@
+/** Extracts link relationships and resource details from each `<link>` element. */
 export declare const linkExtractor: {
     type: "collection";
-    parent: "link";
-    callback: (node: import("..").TXmlNode) => {
-        key: string;
-        value: string;
-    } | null;
+    tag: string;
+    callback: (node: import("xml-tokenizer").TXmlNode) => TLinkMetadata | null;
 };
+/** Link relationship and resource attributes extracted from a `<link>` element. */
+export interface TLinkMetadata {
+    /** Lowercase relationship tokens from `rel`. */
+    rel: string[];
+    /** Unresolved resource URL from `href`. */
+    href: string;
+    /** Resource media type. */
+    type?: string;
+    /** Resource size tokens from `sizes`. */
+    sizes?: string[];
+    /** Media query that controls when the link applies. */
+    media?: string;
+    /** Language of the linked resource. */
+    hreflang?: string;
+}

package/dist/types/extractors/meta-extractor.d.ts

@@ -1,8 +1,19 @@
+/** Extracts supported attributes from each `<meta>` element. */
 export declare const metaExtractor: {
     type: "collection";
-    parent: "meta";
-    callback: (node: import("..").TXmlNode) => {
-        key: string;
-        value: string;
-    } | null;
+    tag: string;
+    callback: (node: import("xml-tokenizer").TXmlNode) => TMetaMetadata | null;
 };
+/** Supported attributes extracted from a `<meta>` element. */
+export interface TMetaMetadata {
+    /** Declared document character encoding. */
+    charset?: string;
+    /** Metadata name, such as `description` or `twitter:card`. */
+    name?: string;
+    /** Metadata property, such as `og:title` or `og:image`. */
+    property?: string;
+    /** HTTP header name supplied through `http-equiv`. */
+    httpEquiv?: string;
+    /** Metadata value. */
+    content?: string;
+}

package/dist/types/extractors/title-extractor.d.ts

@@ -1,5 +1,6 @@
+/** Extracts trimmed text from a `<title>` element. */
 export declare const titleExtractor: {
     type: "single";
-    key: "title";
-    callback: (node: import("..").TXmlNode) => string | null;
+    tag: string;
+    callback: (node: import("xml-tokenizer").TXmlNode) => string | null;
 };

package/dist/types/types.d.ts

@@ -1,33 +1,20 @@
-export interface TXmlNode {
-    local: string;
-    prefix?: string;
-    attributes: {
-        local: string;
-        prefix?: string;
-        value: string;
-    }[];
-    content: (TXmlNode | string)[];
-}
-export type TCollectionExtractor = {
+import { type TXmlNode } from 'xml-tokenizer';
+export type { TXmlNode } from 'xml-tokenizer';
+/** Extractor that collects every non-null callback result in document order. */
+export interface TCollectionExtractor<GValue = unknown> {
     type: 'collection';
-    parent: string;
-    callback: (node: TXmlNode) => {
-        key: string;
-        value: string;
-    } | null;
-};
-export type TSingleExtractor = {
+    /** Selects an HTML element by its lowercase tag name. */
+    tag: string;
+    /** Returns the value to append, or `null` to skip this element. */
+    callback: (node: TXmlNode) => GValue | null;
+}
+/** Extractor that keeps the first non-null callback result and skips later matches. */
+export interface TSingleExtractor<GValue = unknown> {
     type: 'single';
-    key: string;
-    callback: (node: TXmlNode) => string | null;
-};
+    /** Selects an HTML element by its lowercase tag name. */
+    tag: string;
+    /** Returns the field value, or `null` to continue searching. */
+    callback: (node: TXmlNode) => GValue | null;
+}
 export type TExtractor = TCollectionExtractor | TSingleExtractor;
-export type TExtractors = {
-    [K: string]: TExtractor;
-};
-export type TExtractCollectionKeys<GExtractors extends TExtractors> = {
-    [K in keyof GExtractors]: GExtractors[K] extends TCollectionExtractor ? GExtractors[K]['parent'] : never;
-}[keyof GExtractors];
-export type TExtractSingleKeys<GExtractors extends TExtractors> = {
-    [K in keyof GExtractors]: GExtractors[K] extends TSingleExtractor ? GExtractors[K]['key'] : never;
-}[keyof GExtractors];
+export type TExtractors = Record<string, TExtractor>;

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "head-metadata",
-  "version": "0.0.12",
+  "version": "0.1.0",
   "private": false,
-  "description": "Typesafe and straightforward utility for extracting structured metadata (like `<meta>`, `<title>`, and `<link>`) from the `<head>` of an HTML document",
-  "keywords": [],
+  "description": "Typed HTML head metadata extraction with configurable single and collection extractors",
+  "keywords": [
+    "html",
+    "metadata",
+    "head-metadata",
+    "head",
+    "meta-tags",
+    "open-graph",
+    "twitter-card",
+    "seo",
+    "title",
+    "link-tags",
+    "typescript",
+    "extractor",
+    "xml-tokenizer"
+  ],
   "homepage": "https://builder.group/?utm_source=package-json",
   "bugs": {
     "url": "https://github.com/builder-group/community/issues"
@@ -20,14 +34,16 @@
   "types": "./dist/types/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "MIGRATION.md"
   ],
   "dependencies": {
-    "xml-tokenizer": "0.0.45"
+    "entities": "^8.1.0",
+    "xml-tokenizer": "0.0.47"
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
-    "rollup-presets": "0.0.27"
+    "@types/node": "^26.5.1",
+    "rollup-presets": "0.0.30"
   },
   "size-limit": [
     {
@@ -39,8 +55,8 @@
     "build:prod": "export NODE_ENV=production && pnpm build",
     "clean": "shx rm -rf dist && shx rm -rf .turbo && shx rm -rf node_modules",
     "install:clean": "pnpm run clean && pnpm install",
-    "lint": "eslint . --fix",
-    "publish:patch": "pnpm build:prod && pnpm version patch && pnpm publish --no-git-checks --access=public",
+    "lint": "eslint .",
+    "publish:patch": "pnpm build:prod && pnpm version patch --no-git-tag-version && pnpm publish --no-git-checks --access=public",
     "size": "size-limit --why",
     "start:dev": "tsc -w",
     "test": "vitest run",