@ultimat3/seo 1.0.0

package/src/images.ts

@@ -0,0 +1,235 @@
+// The responsive image contract: what the markup promises. Two non-negotiables — modern
+// formats are offered before the fallback, and the intrinsic width/height are always inlined
+// so the browser reserves the box before the bytes arrive, keeping CLS at 0. Producing those
+// bytes is `image-driver.ts`; nothing here decodes a pixel.
+
+import { imageQueryInvalid } from './errors';
+import { attributes, escapeAttribute } from './xml';
+
+/** Ordered widest-first is wrong for `srcset`; browsers want ascending. */
+export const DEFAULT_WIDTHS: readonly number[] = [320, 480, 640, 768, 1024, 1280, 1536, 1920];
+
+/** Most-preferred first. The original format is always appended last. */
+export const FORMAT_ORDER = ['avif', 'webp'] as const;
+
+export type ModernFormat = (typeof FORMAT_ORDER)[number];
+
+export const MIME_TYPES: Readonly<Record<string, string>> = {
+  avif: 'image/avif',
+  webp: 'image/webp',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+};
+
+export interface ImageInput {
+  src: string;
+  /** Intrinsic pixel dimensions. Required — this is what prevents layout shift. */
+  width: number;
+  height: number;
+  /** Empty string only for decorative images. */
+  alt: string;
+  /** `sizes` attribute. Defaults to `100vw`, which is honest but conservative. */
+  sizes?: string;
+  /** LCP candidate: eager + high fetch priority + no lazy attribute. */
+  priority?: boolean;
+  /** Base64 data URI rendered behind the image while it loads. */
+  blurDataUrl?: string;
+}
+
+export interface ImageSourceSet {
+  readonly type: string;
+  readonly srcset: string;
+  readonly sizes: string;
+}
+
+export interface ResponsiveImage {
+  readonly sources: readonly ImageSourceSet[];
+  readonly img: {
+    readonly src: string;
+    readonly srcset: string;
+    readonly sizes: string;
+    readonly alt: string;
+    readonly width: number;
+    readonly height: number;
+    readonly loading: 'lazy' | 'eager';
+    readonly decoding: 'async' | 'sync';
+    readonly fetchpriority: 'high' | 'auto';
+    /** `aspect-ratio` plus the blur placeholder, when one was generated. */
+    readonly style: string;
+  };
+}
+
+export interface ResponsiveImageOptions {
+  widths?: readonly number[];
+  formats?: readonly ModernFormat[];
+  /** Builds the URL for one variant. Defaults to `IMAGE_QUERY_KEYS` query parameters (`?w=&f=`). */
+  urlFor?: (src: string, width: number, format?: string) => string;
+}
+
+export function extensionOf(src: string): string {
+  return (src.split('?')[0]?.split('.').pop() ?? '').toLowerCase();
+}
+
+/**
+ * The one spelling of the transform query keys. `defaultUrlFor` writes them and
+ * `parseImageQuery` reads them back — a literal `'w'` in one place and a literal `'w'` in the
+ * other is how a rename of one silently stops answering the other's URLs.
+ */
+export const IMAGE_QUERY_KEYS = { width: 'w', format: 'f', quality: 'q' } as const;
+
+function defaultUrlFor(src: string, width: number, format?: string): string {
+  const separator = src.includes('?') ? '&' : '?';
+  // Both keys read from IMAGE_QUERY_KEYS, never a literal 'w'/'f' — see the constant above.
+  const widthParam = `${IMAGE_QUERY_KEYS.width}=${width}`;
+  const formatParam = format === undefined ? '' : `&${IMAGE_QUERY_KEYS.format}=${format}`;
+  return `${src}${separator}${widthParam}${formatParam}`;
+}
+
+export interface ImageQuery {
+  readonly width?: number | undefined;
+  readonly format?: string | undefined;
+  readonly quality?: number | undefined;
+}
+
+/**
+ * `w` and `q` share one shape: digits only, so `/^[1-9]\d*$/` rejects an empty string, `"0"`, a
+ * negative sign and a fractional point in a single test instead of four checks that could each
+ * drift out of sync with the others.
+ *
+ * Digits alone are still not a number, which is why the range gate is here and not only in
+ * `parseQuality`: 400 of them parse to `Infinity`, and `Infinity > 0` passes every positive-integer
+ * test there is, so `?w=999…9` used to reach the driver as a width nothing can allocate.
+ */
+function parsePositiveInt(param: string, raw: string): number {
+  if (!/^[1-9]\d*$/.test(raw)) throw imageQueryInvalid(param, raw, 'must be a positive integer');
+  const value = Number.parseInt(raw, 10);
+  if (!Number.isSafeInteger(value)) {
+    throw imageQueryInvalid(param, raw, 'is past the largest integer a pixel count can hold');
+  }
+  return value;
+}
+
+function parseQuality(raw: string): number {
+  const quality = parsePositiveInt(IMAGE_QUERY_KEYS.quality, raw);
+  if (quality > 100) throw imageQueryInvalid(IMAGE_QUERY_KEYS.quality, raw, 'must be 100 or less');
+  return quality;
+}
+
+/**
+ * Naming no *real* format is deliberately not refused here: `image-driver.ts`'s
+ * `requestedFormat` already owns "is this an encodable format", and throwing in two places
+ * would give one bad URL two different error codes depending on which module ran first. This
+ * only refuses the one thing that is unambiguously this module's fact — the key was present and
+ * empty.
+ */
+function parseFormat(raw: string): string {
+  if (raw === '')
+    throw imageQueryInvalid(IMAGE_QUERY_KEYS.format, raw, 'must be a non-empty string');
+  return raw;
+}
+
+/**
+ * `null` means no transform was asked for — a plain asset read, not a bad request. An
+ * asked-for-but-unusable value throws instead, because silently serving the full-size
+ * original against a `?w=320` URL is the layout shift this contract exists to prevent.
+ */
+export function parseImageQuery(params: URLSearchParams): ImageQuery | null {
+  const rawWidth = params.get(IMAGE_QUERY_KEYS.width);
+  const rawFormat = params.get(IMAGE_QUERY_KEYS.format);
+  const rawQuality = params.get(IMAGE_QUERY_KEYS.quality);
+  if (rawWidth === null && rawFormat === null && rawQuality === null) return null;
+
+  return {
+    ...(rawWidth === null ? {} : { width: parsePositiveInt(IMAGE_QUERY_KEYS.width, rawWidth) }),
+    ...(rawFormat === null ? {} : { format: parseFormat(rawFormat) }),
+    ...(rawQuality === null ? {} : { quality: parseQuality(rawQuality) }),
+  };
+}
+
+/** Never upscale: drop candidate widths above the intrinsic width. */
+export function usableWidths(intrinsic: number, widths: readonly number[]): readonly number[] {
+  const usable = widths.filter((width) => width <= intrinsic);
+  if (usable.length === 0) return [intrinsic];
+  return usable.includes(intrinsic) ? usable : [...usable, intrinsic];
+}
+
+export function srcsetFor(
+  input: ImageInput,
+  widths: readonly number[],
+  format: string | undefined,
+  urlFor: NonNullable<ResponsiveImageOptions['urlFor']>,
+): string {
+  return widths.map((width) => `${urlFor(input.src, width, format)} ${width}w`).join(', ');
+}
+
+export function responsiveImage(
+  input: ImageInput,
+  options: ResponsiveImageOptions = {},
+): ResponsiveImage {
+  const urlFor = options.urlFor ?? defaultUrlFor;
+  const widths = usableWidths(input.width, options.widths ?? DEFAULT_WIDTHS);
+  const sizes = input.sizes ?? '100vw';
+  const formats = options.formats ?? FORMAT_ORDER;
+
+  const sources: ImageSourceSet[] = formats.map((format) => ({
+    type: MIME_TYPES[format] ?? `image/${format}`,
+    srcset: srcsetFor(input, widths, format, urlFor),
+    sizes,
+  }));
+
+  const style = [
+    `aspect-ratio:${input.width}/${input.height}`,
+    input.blurDataUrl === undefined
+      ? ''
+      : `background-image:url(${input.blurDataUrl});background-size:cover`,
+  ]
+    .filter((part) => part !== '')
+    .join(';');
+
+  return {
+    sources,
+    img: {
+      src: urlFor(input.src, widths[widths.length - 1] ?? input.width, undefined),
+      srcset: srcsetFor(input, widths, undefined, urlFor),
+      sizes,
+      alt: input.alt,
+      width: input.width,
+      height: input.height,
+      loading: input.priority === true ? 'eager' : 'lazy',
+      decoding: input.priority === true ? 'sync' : 'async',
+      fetchpriority: input.priority === true ? 'high' : 'auto',
+      style,
+    },
+  };
+}
+
+/** `<picture>` with AVIF, then WebP, then the original. */
+export function renderPicture(image: ResponsiveImage): string {
+  const sources = image.sources
+    .map(
+      (source) =>
+        `<source${attributes({ type: source.type, srcset: source.srcset, sizes: source.sizes })}>`,
+    )
+    .join('');
+  const img = image.img;
+  return `<picture>${sources}<img${attributes({
+    src: img.src,
+    srcset: img.srcset,
+    sizes: img.sizes,
+    alt: img.alt,
+    width: String(img.width),
+    height: String(img.height),
+    loading: img.loading,
+    decoding: img.decoding,
+    fetchpriority: img.fetchpriority,
+    style: img.style,
+  })}></picture>`;
+}
+
+/** Escapes a data URI for inline `style`, for callers assembling their own tags. */
+export function inlineBlur(dataUrl: string): string {
+  return escapeAttribute(`background-image:url(${dataUrl});background-size:cover`);
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+// The public surface of @ultimat3/seo. Explicit named exports only.
+
+export type { BudgetMeasurement, BudgetMetric, BudgetReport, BudgetViolation } from './budgets';
+export { assertBudgets, BUDGET_UNITS, checkBudgets, DEFAULT_BUDGET, parseBytes } from './budgets';
+export type { SeoErrorCode, SeoErrorInit } from './errors';
+export {
+  budgetExceeded,
+  canonicalMismatch,
+  duplicateMeta,
+  imageQueryInvalid,
+  ldInvalid,
+  metaMissing,
+  metaTooLong,
+  notImplementedDriver,
+  SEO_ERROR_CODES,
+  SeoError,
+  sitemapTooLarge,
+} from './errors';
+export type {
+  BuiltinImageDriverOptions,
+  ImageTransformDriver,
+  TransformedImage,
+  TransformRequest,
+} from './image-driver';
+export { builtinImageDriver } from './image-driver';
+export type {
+  ImageInput,
+  ImageQuery,
+  ImageSourceSet,
+  ModernFormat,
+  ResponsiveImage,
+  ResponsiveImageOptions,
+} from './images';
+export {
+  DEFAULT_WIDTHS,
+  extensionOf,
+  FORMAT_ORDER,
+  IMAGE_QUERY_KEYS,
+  inlineBlur,
+  MIME_TYPES,
+  parseImageQuery,
+  renderPicture,
+  responsiveImage,
+  srcsetFor,
+  usableWidths,
+} from './images';
+export type {
+  ArticleAuthor,
+  ArticleAuthorOrganization,
+  ArticleAuthorPerson,
+  ArticleInput,
+  BreadcrumbInput,
+  EventInput,
+  FaqInput,
+  JsonLd,
+  OfferInput,
+  OrganizationInput,
+  PersonInput,
+  ProductInput,
+  SoftwareApplicationInput,
+  WebSiteInput,
+} from './ld';
+export {
+  Article,
+  BreadcrumbList,
+  Event,
+  FAQPage,
+  LD_CONTEXT,
+  ld,
+  Organization,
+  Person,
+  Product,
+  renderLd,
+  SoftwareApplication,
+  WebSite,
+} from './ld';
+export type {
+  AlternateLocale,
+  HeadTag,
+  OpenGraph,
+  OpenGraphImage,
+  RenderMetaOptions,
+  RobotsDirectives,
+  RouteMeta,
+  ThemeColor,
+  TwitterCard,
+} from './meta';
+export {
+  applyTitleTemplate,
+  DESCRIPTION_MAX_LENGTH,
+  DESCRIPTION_MIN_LENGTH,
+  hreflangSet,
+  renderHeadTags,
+  renderMeta,
+  robotsContent,
+  TITLE_MAX_LENGTH,
+} from './meta';
+export type { RobotsConfig, RobotsGroup, SeoEnvironment } from './robots';
+export { buildRobots, isIndexable, resolveEnvironment } from './robots';
+export type { ChangeFreq, RenderMode, RouteBudget, RouteRecord, Surface } from './routes';
+export { expandRoute, indexableRoutes, isDynamic } from './routes';
+export type { Feed, FeedAuthor, FeedChannel, FeedItem } from './rss';
+export { buildFeed } from './rss';
+export type {
+  BuildSitemapOptions,
+  SitemapAlternate,
+  SitemapFile,
+  SitemapResult,
+  SitemapUrl,
+} from './sitemap';
+export {
+  buildSitemap,
+  chunk,
+  SITEMAP_INDEX_MAX_FILES,
+  SITEMAP_MAX_URLS,
+  sitemapUrls,
+} from './sitemap';
+export type { MetaIssue, MetaValidationReport, ValidateMetaOptions } from './validate';
+export { assertMeta, validateMeta } from './validate';
+
+export { absoluteUrl, escapeAttribute, escapeXml } from './xml';

package/src/ld.ts

@@ -0,0 +1,325 @@
+// Typed JSON-LD builders. Required schema.org fields are required in the input
+// type, so a missing `datePublished` is a compile error rather than a Search
+// Console warning three weeks later. Runtime checks catch empty strings that the
+// type system cannot (a value read from a CMS).
+
+import { ldInvalid } from './errors';
+import type { HeadTag } from './meta';
+
+export type JsonLd = Readonly<Record<string, unknown>>;
+
+export const LD_CONTEXT = 'https://schema.org';
+
+function required(type: string, field: string, value: string, hint: string): string {
+  if (value.trim() === '') throw ldInvalid(type, field, hint);
+  return value;
+}
+
+function node(type: string, body: Readonly<Record<string, unknown>>): JsonLd {
+  const out: Record<string, unknown> = { '@context': LD_CONTEXT, '@type': type };
+  for (const [key, value] of Object.entries(body)) {
+    if (value !== undefined && value !== null) out[key] = value;
+  }
+  return out;
+}
+
+// --- inputs ------------------------------------------------------------------
+
+export interface PersonInput {
+  name: string;
+  url?: string;
+  image?: string;
+  jobTitle?: string;
+  sameAs?: readonly string[];
+}
+
+export interface OrganizationInput {
+  name: string;
+  url: string;
+  logo?: string;
+  sameAs?: readonly string[];
+  description?: string;
+}
+
+/** Discriminated so an Organization author is never mis-rendered as a Person. */
+export interface ArticleAuthorPerson extends PersonInput {
+  type?: 'Person';
+}
+
+export interface ArticleAuthorOrganization extends OrganizationInput {
+  type: 'Organization';
+}
+
+export type ArticleAuthor = ArticleAuthorPerson | ArticleAuthorOrganization;
+
+export interface ArticleInput {
+  headline: string;
+  /** ISO 8601. Required by schema.org for Article rich results. */
+  datePublished: string;
+  author: ArticleAuthor;
+  dateModified?: string;
+  description?: string;
+  image?: string | readonly string[];
+  url?: string;
+  publisher?: OrganizationInput;
+  articleSection?: string;
+  keywords?: readonly string[];
+}
+
+export interface OfferInput {
+  /** Decimal string, never a float, e.g. `'19.99'`. */
+  price: string;
+  priceCurrency: string;
+  availability?: 'InStock' | 'OutOfStock' | 'PreOrder' | 'BackOrder';
+  url?: string;
+  priceValidUntil?: string;
+}
+
+export interface ProductInput {
+  name: string;
+  offers: OfferInput;
+  image?: string | readonly string[];
+  description?: string;
+  sku?: string;
+  brand?: string;
+  aggregateRating?: { ratingValue: string; reviewCount: number };
+}
+
+export interface WebSiteInput {
+  name: string;
+  url: string;
+  /** Enables the sitelinks search box. `{search_term_string}` is substituted. */
+  searchUrlTemplate?: string;
+  inLanguage?: string;
+  publisher?: OrganizationInput;
+}
+
+export interface BreadcrumbInput {
+  items: ReadonlyArray<{ name: string; url: string }>;
+}
+
+export interface FaqInput {
+  questions: ReadonlyArray<{ question: string; answer: string }>;
+}
+
+export interface EventInput {
+  name: string;
+  /** ISO 8601. Required. */
+  startDate: string;
+  /** A venue name or a URL for an online event. Required. */
+  location: string;
+  endDate?: string;
+  description?: string;
+  url?: string;
+  eventAttendanceMode?: 'Offline' | 'Online' | 'Mixed';
+  offers?: OfferInput;
+}
+
+export interface SoftwareApplicationInput {
+  name: string;
+  /** e.g. `DeveloperApplication`. Required for the app rich result. */
+  applicationCategory: string;
+  operatingSystem: string;
+  offers?: OfferInput;
+  aggregateRating?: { ratingValue: string; reviewCount: number };
+  url?: string;
+}
+
+// --- builders ----------------------------------------------------------------
+
+function personOrOrg(input: ArticleAuthor): JsonLd {
+  return input.type === 'Organization' ? Organization(input) : Person(input);
+}
+
+function offer(input: OfferInput): JsonLd {
+  required('Offer', 'price', input.price, 'a decimal string such as "19.99"');
+  required('Offer', 'priceCurrency', input.priceCurrency, 'an ISO-4217 code such as "USD"');
+  return node('Offer', {
+    price: input.price,
+    priceCurrency: input.priceCurrency,
+    availability:
+      input.availability === undefined ? undefined : `https://schema.org/${input.availability}`,
+    url: input.url,
+    priceValidUntil: input.priceValidUntil,
+  });
+}
+
+export function Person(input: PersonInput): JsonLd {
+  required('Person', 'name', input.name, 'the person as they should be credited');
+  return node('Person', {
+    name: input.name,
+    url: input.url,
+    image: input.image,
+    jobTitle: input.jobTitle,
+    sameAs: input.sameAs,
+  });
+}
+
+export function Organization(input: OrganizationInput): JsonLd {
+  required('Organization', 'name', input.name, 'the legal or trading name');
+  required('Organization', 'url', input.url, 'the canonical homepage URL');
+  return node('Organization', {
+    name: input.name,
+    url: input.url,
+    logo: input.logo,
+    sameAs: input.sameAs,
+    description: input.description,
+  });
+}
+
+export function Article(input: ArticleInput): JsonLd {
+  required('Article', 'headline', input.headline, 'the visible article headline');
+  required('Article', 'datePublished', input.datePublished, 'an ISO 8601 date');
+  return node('Article', {
+    headline: input.headline,
+    datePublished: input.datePublished,
+    dateModified: input.dateModified ?? input.datePublished,
+    author: personOrOrg(input.author),
+    description: input.description,
+    image: input.image,
+    url: input.url,
+    publisher: input.publisher === undefined ? undefined : Organization(input.publisher),
+    articleSection: input.articleSection,
+    keywords: input.keywords,
+  });
+}
+
+export function Product(input: ProductInput): JsonLd {
+  required('Product', 'name', input.name, 'the product name shown on the page');
+  return node('Product', {
+    name: input.name,
+    offers: offer(input.offers),
+    image: input.image,
+    description: input.description,
+    sku: input.sku,
+    brand: input.brand === undefined ? undefined : { '@type': 'Brand', name: input.brand },
+    aggregateRating:
+      input.aggregateRating === undefined
+        ? undefined
+        : { '@type': 'AggregateRating', ...input.aggregateRating },
+  });
+}
+
+export function WebSite(input: WebSiteInput): JsonLd {
+  required('WebSite', 'name', input.name, 'the site name');
+  required('WebSite', 'url', input.url, 'the canonical homepage URL');
+  return node('WebSite', {
+    name: input.name,
+    url: input.url,
+    inLanguage: input.inLanguage,
+    publisher: input.publisher === undefined ? undefined : Organization(input.publisher),
+    potentialAction:
+      input.searchUrlTemplate === undefined
+        ? undefined
+        : {
+            '@type': 'SearchAction',
+            target: {
+              '@type': 'EntryPoint',
+              urlTemplate: input.searchUrlTemplate,
+            },
+            'query-input': 'required name=search_term_string',
+          },
+  });
+}
+
+export function BreadcrumbList(input: BreadcrumbInput): JsonLd {
+  if (input.items.length === 0) {
+    throw ldInvalid('BreadcrumbList', 'items', 'at least one crumb');
+  }
+  return node('BreadcrumbList', {
+    itemListElement: input.items.map((item, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: required('BreadcrumbList', 'items[].name', item.name, 'the crumb label'),
+      item: required('BreadcrumbList', 'items[].url', item.url, 'an absolute URL'),
+    })),
+  });
+}
+
+export function FAQPage(input: FaqInput): JsonLd {
+  if (input.questions.length === 0) {
+    throw ldInvalid('FAQPage', 'questions', 'at least one question/answer pair');
+  }
+  return node('FAQPage', {
+    mainEntity: input.questions.map((entry) => ({
+      '@type': 'Question',
+      name: required('FAQPage', 'questions[].question', entry.question, 'the question text'),
+      acceptedAnswer: {
+        '@type': 'Answer',
+        text: required('FAQPage', 'questions[].answer', entry.answer, 'the answer text'),
+      },
+    })),
+  });
+}
+
+export function Event(input: EventInput): JsonLd {
+  required('Event', 'name', input.name, 'the event name');
+  required('Event', 'startDate', input.startDate, 'an ISO 8601 date-time');
+  required('Event', 'location', input.location, 'a venue name or an online URL');
+  const online = /^https?:\/\//.test(input.location);
+  return node('Event', {
+    name: input.name,
+    startDate: input.startDate,
+    endDate: input.endDate,
+    description: input.description,
+    url: input.url,
+    eventAttendanceMode: `https://schema.org/${input.eventAttendanceMode ?? (online ? 'Online' : 'Offline')}EventAttendanceMode`,
+    location: online
+      ? { '@type': 'VirtualLocation', url: input.location }
+      : { '@type': 'Place', name: input.location },
+    offers: input.offers === undefined ? undefined : offer(input.offers),
+  });
+}
+
+export function SoftwareApplication(input: SoftwareApplicationInput): JsonLd {
+  required('SoftwareApplication', 'name', input.name, 'the application name');
+  required(
+    'SoftwareApplication',
+    'applicationCategory',
+    input.applicationCategory,
+    'a schema.org application category',
+  );
+  required(
+    'SoftwareApplication',
+    'operatingSystem',
+    input.operatingSystem,
+    'the supported OS list, e.g. "Linux, macOS"',
+  );
+  return node('SoftwareApplication', {
+    name: input.name,
+    applicationCategory: input.applicationCategory,
+    operatingSystem: input.operatingSystem,
+    url: input.url,
+    offers: input.offers === undefined ? undefined : offer(input.offers),
+    aggregateRating:
+      input.aggregateRating === undefined
+        ? undefined
+        : { '@type': 'AggregateRating', ...input.aggregateRating },
+  });
+}
+
+/** The namespace routes use: `meta: () => ({ ld: [ld.Article(post)] })`. */
+export const ld = {
+  Article,
+  BreadcrumbList,
+  Event,
+  FAQPage,
+  Organization,
+  Person,
+  Product,
+  SoftwareApplication,
+  WebSite,
+} as const;
+
+/** One `<script type="application/ld+json">` holding a @graph of every node. */
+export function renderLd(nodes: readonly JsonLd[]): HeadTag {
+  const payload =
+    nodes.length === 1
+      ? nodes[0]
+      : { '@context': LD_CONTEXT, '@graph': nodes.map(({ '@context': _drop, ...rest }) => rest) };
+  return {
+    tag: 'script',
+    attrs: { type: 'application/ld+json' },
+    text: JSON.stringify(payload),
+  };
+}