@abinnovision/payloadcms-wayfinder 1.0.0-beta.2

package/dist/pattern/resolver.mjs

@@ -0,0 +1,104 @@
+import { DEFAULT_LOCALE_KEY } from "./types.mjs";
+import * as ptr from "path-to-regexp";
+//#region src/pattern/resolver.ts
+/**
+* A wildcard stands for a whole path, so its value carries a leading slash to
+* match how full paths are stored — a wildcard-mapped collection's identifier
+* is `/about/team`, not `about/team`.
+*
+* @param value Raw parameter value from path-to-regexp.
+* @param isWildcard Whether the parameter was declared as a wildcard.
+*/ const normaliseValue = (value, isWildcard) => {
+	let joined = "";
+	if (Array.isArray(value)) joined = value.filter((it) => typeof it === "string").join("/");
+	else if (typeof value === "string") joined = value;
+	if (!isWildcard) return joined;
+	return joined.startsWith("/") ? joined : `/${joined}`;
+};
+/**
+* Reverses {@link normaliseValue} so a stored full path can be fed back into
+* `compile`, which requires a non-empty array for a wildcard.
+*
+* @param value The parameter value to convert.
+*/ const denormaliseWildcard = (value) => (typeof value === "string" ? value : "").split("/").filter(Boolean);
+const measureSpecificity = (pattern, keys) => {
+	const segments = pattern.split("/").filter(Boolean);
+	return {
+		literalSegments: segments.filter((segment) => !segment.startsWith(":") && !segment.startsWith("*")).length,
+		hasWildcard: keys.some((key) => key.type === "wildcard"),
+		totalSegments: segments.length
+	};
+};
+const createResolvers = (pattern) => {
+	const { keys } = ptr.pathToRegexp(pattern);
+	const matchFn = ptr.match(pattern);
+	const buildFn = ptr.compile(pattern);
+	const wildcardNames = new Set(keys.filter((key) => key.type === "wildcard").map((key) => key.name));
+	return {
+		specificity: measureSpecificity(pattern, keys),
+		paramNames: keys.map((key) => key.name),
+		match: (path) => {
+			const matched = matchFn(path);
+			if (!matched) return false;
+			const ordered = keys.map((key) => {
+				const name = key.name;
+				return {
+					name,
+					value: normaliseValue(matched.params[name], wildcardNames.has(name))
+				};
+			});
+			const identifying = ordered.at(-1);
+			if (!identifying || !identifying.value) return false;
+			return {
+				identifier: {
+					field: identifying.name,
+					value: identifying.value
+				},
+				scope: Object.fromEntries(ordered.slice(0, -1).map((it) => [it.name, it.value]))
+			};
+		},
+		build: (params) => buildFn(Object.fromEntries(Object.entries(params).map(([name, value]) => [name, wildcardNames.has(name) ? denormaliseWildcard(value) : value])))
+	};
+};
+/**
+* Normalises the two shapes a mapping's `path` can take.
+*
+* A localized project yields one pattern per locale. A project with no
+* `localization` block yields a plain string, which would otherwise be walked
+* character by character by `Object.entries` and compile into one nonsense
+* resolver per character.
+*
+* @param path The pattern, or per-locale patterns.
+*/ const normalisePath = (path) => typeof path === "string" ? { [DEFAULT_LOCALE_KEY]: path } : path;
+/**
+* Whether a wildcard pattern was handed the site root. `compile` rejects an
+* empty wildcard, so the home page — a document whose identifier is just `/` —
+* has to be built as the bare root instead.
+*
+* @param resolvers The pattern's compiled resolvers.
+* @param values The parameter values, in pattern order.
+*/ const isRootWildcard = (resolvers, values) => resolvers.specificity.hasWildcard && values.every((value) => value === "" || value === "/");
+/**
+* Picks the resolvers for a locale, falling back to the unlocalized bucket.
+*
+* A project without localization has exactly one bucket under
+* {@link DEFAULT_LOCALE_KEY}, so callers pass whatever locale they have and
+* still get the right pattern.
+*
+* @param mapping The compiled mapping.
+* @param locale The locale to resolve for.
+*/ const resolversFor = (mapping, locale) => mapping.resolvers[locale] ?? mapping.resolvers["__default"];
+/**
+* Compiles a mapping's patterns into match and build functions.
+*
+* @param input The mapping as authored.
+*/ const resolveCollectionMapping = (input) => {
+	const path = normalisePath(input.path);
+	return {
+		collection: input.collection,
+		path,
+		resolvers: Object.fromEntries(Object.entries(path).map(([locale, pattern]) => [locale, createResolvers(pattern)]))
+	};
+};
+//#endregion
+export { isRootWildcard, resolveCollectionMapping, resolversFor };

package/dist/pattern/types.d.mts

@@ -0,0 +1,169 @@
+import { ParamData } from "path-to-regexp";
+import { Field } from "payload";
+//#region src/pattern/types.d.ts
+/**
+ * Locale bucket used when a project has no localization configured.
+ *
+ * Payload only returns a per-locale record for a localized field, and only
+ * when the config declares locales at all. Without them the mapping's `path`
+ * arrives as a plain string, which normalises into this single bucket so the
+ * rest of the package has one shape to work with.
+ */
+declare const DEFAULT_LOCALE_KEY = "__default";
+/**
+ * Maps one collection onto the URL patterns its documents live at.
+ *
+ * A localized project supplies one pattern per locale; a project without
+ * localization supplies a single pattern. Authored in the mapping global, so
+ * adding a page type never means touching routing code.
+ */
+interface PayloadCollectionMapping {
+  collection: string;
+  /**
+   * Either one pattern per locale (`{ de: "/:format/:slug" }`) or a single
+   * pattern for a project with no locales.
+   */
+  path: string | Record<string, string>;
+}
+/**
+ * Result of matching a path against one mapping.
+ */
+interface PayloadCollectionMappingMatch {
+  /**
+   * The pattern's last parameter, which identifies the document within its
+   * collection.
+   */
+  identifier: {
+    field: string;
+    value: string;
+  };
+  /**
+   * Any earlier parameters, keyed by their raw parameter name. These narrow
+   * the lookup without identifying the document — `format` in
+   * `/:format/:slug` is one.
+   */
+  scope: Record<string, string>;
+}
+/**
+ * How specific a pattern is, used to order candidates so that the most
+ * precise pattern wins regardless of the order rows sit in the admin UI.
+ */
+interface PayloadCollectionMappingSpecificity {
+  /** Segments that are literal text rather than a parameter. */
+  literalSegments: number;
+  /** Whether the pattern ends in a catch-all. */
+  hasWildcard: boolean;
+  totalSegments: number;
+}
+interface PayloadCollectionMappingResolvers {
+  match: (path: string) => false | PayloadCollectionMappingMatch;
+  build: (params: ParamData) => string;
+  /**
+   * Parameter names in pattern order, so callers can collect the values a
+   * `build` needs without re-parsing the pattern. The last entry identifies
+   * the document.
+   */
+  paramNames: string[];
+  specificity: PayloadCollectionMappingSpecificity;
+}
+interface PayloadCollectionMappingResolved {
+  collection: string;
+  /** Always a record after normalisation, keyed by locale or by {@link DEFAULT_LOCALE_KEY}. */
+  path: Record<string, string>;
+  resolvers: Record<string, PayloadCollectionMappingResolvers>;
+}
+/**
+ * Rewrites a built path before it is returned.
+ *
+ * Locale prefixing and preview prefixing are the same transform applied at the
+ * same point, so they share one hook rather than competing for two options:
+ *
+ * ```ts
+ * formatHref: ({ path, locale }) => `/${locale}${path}`
+ * formatHref: ({ path, locale }) => `/${locale}${isPreview ? "/-preview" : ""}${path}`
+ * ```
+ *
+ * Defaults to returning the path untouched, so a project serving unprefixed
+ * URLs needs no configuration.
+ */
+type FormatHref = (args: {
+  path: string;
+  locale: string;
+}) => string;
+/** Label accepted wherever the admin panel shows one. */
+type LabelLike = string | Record<string, string>;
+/**
+ * Optional-everything, including an explicit `undefined`.
+ *
+ * `Partial<T>` is not enough under `exactOptionalPropertyTypes`: it marks a
+ * property optional without letting it hold `undefined`, so a variant that
+ * reads one of its own optional fields and passes it straight back would not
+ * typecheck against its own declared shape.
+ */
+type Contributed<T> = { [K in keyof T]?: T[K] | undefined; };
+/** The link types the package understands without configuration. */
+type BuiltinLinkVariant = "none" | "reference" | "custom" | "same-page";
+/**
+ * Structural shape of the `link` field group.
+ *
+ * Declared here rather than imported from a project's generated types so the
+ * field definition that produces it does not depend on its own output.
+ * Nullable throughout because that is how Payload emits optional fields — a
+ * mismatch here shows up at every call site.
+ *
+ * `TVariant` carries any app-declared variant names, and `TExtra` the fields
+ * those variants contribute, so a variant's own resolver can read the data its
+ * own fields produced without a cast.
+ */
+type LinkFieldData<TVariant extends string = never, TExtra = object> = {
+  type?: BuiltinLinkVariant | TVariant | null;
+  label?: string | null;
+  reference?: {
+    relationTo: string;
+    value: string | {
+      id: string;
+      [field: string]: unknown;
+    };
+  } | null;
+  url?: string | null;
+  samePageIdentifier?: string | null;
+  newTab?: boolean | null;
+} & Contributed<TExtra>;
+/** What every link resolves to, before any variant adds to it. */
+interface BaseResolvedLink {
+  href: string;
+  target?: string;
+  rel?: string;
+}
+/**
+ * A resolved link, widened by whatever an app-declared variant returns.
+ *
+ * `E` defaults to an empty object rather than `unknown`: an intersection with
+ * an uninstantiated type parameter stays deferred, which would force a cast at
+ * every built-in branch.
+ *
+ * Every contributed property is optional, for the same reason it is on
+ * {@link LinkFieldData}: `E` is the union of what *every* variant contributes,
+ * so requiring all of it would mean each variant had to return the other
+ * variants' properties alongside its own.
+ */
+type ResolvedLink<E = object> = BaseResolvedLink & Contributed<E>;
+/**
+ * One variant, flattened out of a declaration with its key put back on it.
+ *
+ * The shape everything downstream of {@link defineLinks} works with. Not an
+ * authoring form: variants are written through the builder, which is what
+ * derives their field types.
+ */
+interface DeclaredLinkVariant<TCtx = unknown, TExtra = object> {
+  value: string;
+  label: LabelLike;
+  /** Readonly, because a `const` type parameter infers a readonly tuple. */
+  fields?: readonly Field[];
+  resolve?: (args: {
+    link: LinkFieldData<string, TExtra>;
+    context: TCtx;
+  }) => ResolvedLink<TExtra> | null;
+}
+//#endregion
+export { BaseResolvedLink, BuiltinLinkVariant, Contributed, DEFAULT_LOCALE_KEY, DeclaredLinkVariant, FormatHref, LabelLike, LinkFieldData, PayloadCollectionMapping, PayloadCollectionMappingMatch, PayloadCollectionMappingResolved, PayloadCollectionMappingResolvers, PayloadCollectionMappingSpecificity, ResolvedLink };

package/dist/pattern/types.mjs

@@ -0,0 +1,11 @@
+//#region src/pattern/types.ts
+/**
+* Locale bucket used when a project has no localization configured.
+*
+* Payload only returns a per-locale record for a localized field, and only
+* when the config declares locales at all. Without them the mapping's `path`
+* arrives as a plain string, which normalises into this single bucket so the
+* rest of the package has one shape to work with.
+*/ const DEFAULT_LOCALE_KEY = "__default";
+//#endregion
+export { DEFAULT_LOCALE_KEY };

package/dist/runtime/build-href.d.mts

@@ -0,0 +1,39 @@
+import { FormatHref, PayloadCollectionMappingResolved } from "../pattern/types.mjs";
+import { BuildDiagnosticReason, OnDiagnostic } from "./diagnostics.mjs";
+//#region src/runtime/build-href.d.ts
+/**
+ * A document as it arrives on a populated relationship.
+ *
+ * Typed as a plain object rather than an indexed record so generated
+ * collection interfaces assign to it; the fields the path pattern names are
+ * read dynamically below.
+ */
+type LinkableDocument = object;
+/** Applied when no {@link FormatHref} is supplied: the path, untouched. */
+declare const identityFormatHref: FormatHref;
+interface BuildHrefArgs {
+  mappings: PayloadCollectionMappingResolved[];
+  collection: string;
+  document: LinkableDocument;
+  locale: string;
+  formatHref?: FormatHref;
+  /**
+   * The field a populated relationship is identified by, when it cannot be
+   * derived from the target's own pattern. Must match what
+   * `resolveParamQueryPath` filters on, or build and match disagree.
+   */
+  identifierField?: string;
+  onDiagnostic?: OnDiagnostic<BuildDiagnosticReason>;
+}
+/**
+ * Builds the href a document is served at, using its collection's pattern.
+ *
+ * Returns null when the collection has no mapping or the document is missing a
+ * value the pattern needs — a relationship left unpopulated is the usual
+ * cause, so check `defaultPopulate` before assuming the mapping is wrong.
+ *
+ * @param args The mappings, target collection, document and locale.
+ */
+declare const buildHref: (args: BuildHrefArgs) => string | null;
+//#endregion
+export { BuildHrefArgs, LinkableDocument, buildHref, identityFormatHref };

package/dist/runtime/build-href.mjs

@@ -0,0 +1,73 @@
+import { resolversFor } from "../pattern/resolver.mjs";
+//#region src/runtime/build-href.ts
+/** Applied when no {@link FormatHref} is supplied: the path, untouched. */ const identityFormatHref = ({ path }) => path;
+/**
+* Reads the value a path parameter needs off a document.
+*
+* A plain field yields its own value; a populated relationship yields the
+* related document's identifier, which is what the query matches on.
+*
+* @param document The document being linked to.
+* @param param The path parameter name.
+* @param identifierField The related document's identifying field.
+*/ const readParam = (document, param, identifierField) => {
+	const value = document[param];
+	if (typeof value === "string") return value;
+	if (value && typeof value === "object" && identifierField in value) {
+		const identifier = value[identifierField];
+		return typeof identifier === "string" ? identifier : void 0;
+	}
+};
+/**
+* Builds the href a document is served at, using its collection's pattern.
+*
+* Returns null when the collection has no mapping or the document is missing a
+* value the pattern needs — a relationship left unpopulated is the usual
+* cause, so check `defaultPopulate` before assuming the mapping is wrong.
+*
+* @param args The mappings, target collection, document and locale.
+*/ const buildHref = (args) => {
+	const format = args.formatHref ?? identityFormatHref;
+	const identifierField = args.identifierField ?? "slug";
+	const mapping = args.mappings.find((it) => it.collection === args.collection);
+	if (!mapping) {
+		args.onDiagnostic?.({
+			reason: "no-mapping",
+			collection: args.collection
+		});
+		return null;
+	}
+	const resolvers = resolversFor(mapping, args.locale);
+	if (!resolvers) {
+		args.onDiagnostic?.({
+			reason: "no-locale-pattern",
+			collection: args.collection,
+			locale: args.locale
+		});
+		return null;
+	}
+	const params = {};
+	for (const name of resolvers.paramNames) {
+		const value = readParam(args.document, name, identifierField);
+		if (value === void 0) {
+			args.onDiagnostic?.({
+				reason: "missing-param",
+				collection: args.collection,
+				param: name
+			});
+			return null;
+		}
+		params[name] = value;
+	}
+	const identifying = resolvers.paramNames.at(-1);
+	if (identifying && params[identifying] === "/") return format({
+		path: "/",
+		locale: args.locale
+	});
+	return format({
+		path: resolvers.build(params),
+		locale: args.locale
+	});
+};
+//#endregion
+export { buildHref, identityFormatHref };

package/dist/runtime/build-path.d.mts

@@ -0,0 +1,32 @@
+import { FormatHref, PayloadCollectionMappingResolved } from "../pattern/types.mjs";
+import { BuildDiagnosticReason, OnDiagnostic } from "./diagnostics.mjs";
+//#region src/runtime/build-path.d.ts
+interface BuildPathArgs {
+  mappings: PayloadCollectionMappingResolved[];
+  collection: string;
+  locale: string;
+  /**
+   * Parameter values, either in pattern order or keyed by parameter name.
+   * Positional values let a caller fill a pattern without knowing what its
+   * parameters are called, so renaming one in the CMS needs no code change.
+   */
+  values: string[] | Record<string, string>;
+  formatHref?: FormatHref;
+  onDiagnostic?: OnDiagnostic<BuildDiagnosticReason>;
+}
+/**
+ * Builds a path from parameter values alone, with no document.
+ *
+ * Sitemaps and feeds run outside a request's rendering context and select only
+ * the fields they need, so they never hold a document shaped the way
+ * `buildHref` expects. They do hold the values, which is all a pattern needs.
+ *
+ * An unmapped collection falls back to the site root rather than returning
+ * nothing: emitting a bare root into a feed is recoverable, emitting an empty
+ * href is not.
+ *
+ * @param args The mappings, collection, locale and parameter values.
+ */
+declare const buildPath: (args: BuildPathArgs) => string;
+//#endregion
+export { BuildPathArgs, buildPath };

package/dist/runtime/build-path.mjs

@@ -0,0 +1,49 @@
+import { isRootWildcard, resolversFor } from "../pattern/resolver.mjs";
+import { identityFormatHref } from "./build-href.mjs";
+//#region src/runtime/build-path.ts
+/**
+* Builds a path from parameter values alone, with no document.
+*
+* Sitemaps and feeds run outside a request's rendering context and select only
+* the fields they need, so they never hold a document shaped the way
+* `buildHref` expects. They do hold the values, which is all a pattern needs.
+*
+* An unmapped collection falls back to the site root rather than returning
+* nothing: emitting a bare root into a feed is recoverable, emitting an empty
+* href is not.
+*
+* @param args The mappings, collection, locale and parameter values.
+*/ const buildPath = (args) => {
+	const format = args.formatHref ?? identityFormatHref;
+	const root = () => format({
+		path: "/",
+		locale: args.locale
+	});
+	const mapping = args.mappings.find((it) => it.collection === args.collection);
+	if (!mapping) {
+		args.onDiagnostic?.({
+			reason: "no-mapping",
+			collection: args.collection
+		});
+		return root();
+	}
+	const resolvers = resolversFor(mapping, args.locale);
+	if (!resolvers) {
+		args.onDiagnostic?.({
+			reason: "no-locale-pattern",
+			collection: args.collection,
+			locale: args.locale
+		});
+		return root();
+	}
+	const values = args.values;
+	const ordered = Array.isArray(values) ? resolvers.paramNames.map((_, index) => values[index] ?? "") : resolvers.paramNames.map((name) => values[name] ?? "");
+	if (isRootWildcard(resolvers, ordered)) return root();
+	const params = Object.fromEntries(resolvers.paramNames.map((name, index) => [name, ordered[index] ?? ""]));
+	return format({
+		path: resolvers.build(params),
+		locale: args.locale
+	});
+};
+//#endregion
+export { buildPath };

package/dist/runtime/diagnostics.d.mts

@@ -0,0 +1,35 @@
+//#region src/runtime/diagnostics.d.ts
+/**
+ * Why a routing call produced nothing.
+ *
+ * Every failure here returns `null` so the happy path stays a plain value
+ * rather than a wrapper type. That leaves no way to tell "this collection has
+ * no mapping" from "this relationship was never populated", which is exactly
+ * the distinction someone staring at a missing link needs. These reasons carry
+ * it out of band.
+ */
+type DiagnosticReason = "no-mapping" | "no-locale-pattern" | "unpopulated-reference" | "missing-param" | "no-document" | "unknown-variant";
+interface Diagnostic<TReason extends DiagnosticReason> {
+  reason: TReason;
+  collection?: string;
+  locale?: string;
+  path?: string;
+  param?: string;
+  variant?: string;
+}
+/**
+ * Reports why a call returned nothing.
+ *
+ * Fires once per failed call, so a page whose footer holds forty links to a
+ * misconfigured collection reports forty times. Deduplicating is the caller's
+ * job — the package cannot know which of them are worth surfacing.
+ */
+type OnDiagnostic<TReason extends DiagnosticReason> = (diagnostic: Diagnostic<TReason>) => void;
+/** Reasons {@link buildHref} and {@link buildPath} can report. */
+type BuildDiagnosticReason = "no-mapping" | "no-locale-pattern" | "missing-param";
+/** Reasons link resolution can report. */
+type ResolveLinkDiagnosticReason = BuildDiagnosticReason | "unpopulated-reference" | "unknown-variant";
+/** Reasons path resolution can report. */
+type ResolvePathDiagnosticReason = "no-mapping" | "no-document";
+//#endregion
+export { BuildDiagnosticReason, Diagnostic, DiagnosticReason, OnDiagnostic, ResolveLinkDiagnosticReason, ResolvePathDiagnosticReason };

package/dist/runtime/index.d.mts

@@ -0,0 +1,7 @@
+import { BuildDiagnosticReason, Diagnostic, DiagnosticReason, OnDiagnostic, ResolveLinkDiagnosticReason, ResolvePathDiagnosticReason } from "./diagnostics.mjs";
+import { BuildHrefArgs, LinkableDocument, buildHref, identityFormatHref } from "./build-href.mjs";
+import { BuildPathArgs, buildPath } from "./build-path.mjs";
+import { ResolveLinkArgs, ResolveReference, isAvailableLink, resolveLink } from "./resolve-link.mjs";
+import { PayloadDocument, ResolvePathToDocumentArgs, ResolvePathWhere, ResolvedPath, resolvePathToDocument } from "./resolve-path.mjs";
+import { ResolveRelationshipSlugArgs, resolveRelationshipSlug } from "./resolve-relationship-slug.mjs";
+export { type BuildDiagnosticReason, type BuildHrefArgs, type BuildPathArgs, type Diagnostic, type DiagnosticReason, type LinkableDocument, type OnDiagnostic, type PayloadDocument, type ResolveLinkArgs, type ResolveLinkDiagnosticReason, type ResolvePathDiagnosticReason, type ResolvePathToDocumentArgs, type ResolvePathWhere, type ResolveReference, type ResolveRelationshipSlugArgs, type ResolvedPath, buildHref, buildPath, identityFormatHref, isAvailableLink, resolveLink, resolvePathToDocument, resolveRelationshipSlug };

package/dist/runtime/index.mjs

@@ -0,0 +1,6 @@
+import { buildHref, identityFormatHref } from "./build-href.mjs";
+import { buildPath } from "./build-path.mjs";
+import { isAvailableLink, resolveLink } from "./resolve-link.mjs";
+import { resolvePathToDocument } from "./resolve-path.mjs";
+import { resolveRelationshipSlug } from "./resolve-relationship-slug.mjs";
+export { buildHref, buildPath, identityFormatHref, isAvailableLink, resolveLink, resolvePathToDocument, resolveRelationshipSlug };

package/dist/runtime/resolve-link.d.mts

@@ -0,0 +1,63 @@
+import { BaseResolvedLink, FormatHref, LinkFieldData, PayloadCollectionMappingResolved, ResolvedLink } from "../pattern/types.mjs";
+import { LinkContextOf, LinkDeclaration, LinkVariantSource, ResolvedLinkOf } from "../pattern/define-links.mjs";
+import { OnDiagnostic, ResolveLinkDiagnosticReason } from "./diagnostics.mjs";
+//#region src/runtime/resolve-link.d.ts
+/**
+ * Turns a reference into an href by some means other than the populated
+ * document — an id-to-identifier index, typically.
+ *
+ * Supplied only by projects that cap relationship depth, where a reference
+ * arrives as a bare id. One injected function rather than a second built-in
+ * strategy: the package resolves from the populated document, and this is the
+ * documented way out for setups that cannot.
+ */
+type ResolveReference = (args: {
+  relationTo: string;
+  value: string | {
+    id: string;
+  };
+  locale: string;
+}) => string | null;
+interface ResolveLinkArgs<TExtra = object, TDeclaration extends LinkDeclaration = LinkDeclaration> extends LinkVariantSource<TDeclaration> {
+  link: LinkFieldData<string, TExtra> | undefined;
+  mappings: PayloadCollectionMappingResolved[];
+  locale: string;
+  /** Passed through to a variant's resolver untouched. */
+  /**
+   * Passed through to a variant's resolver untouched.
+   *
+   * When a declaration is supplied its resolvers already say what they
+   * expect, so that shape wins over the array form's own parameter: without
+   * this, any context at all would satisfy a declaration-based call.
+   */
+  context?: LinkContextOf<TDeclaration>;
+  formatHref?: FormatHref;
+  identifierField?: string;
+  resolveReference?: ResolveReference;
+  onDiagnostic?: OnDiagnostic<ResolveLinkDiagnosticReason>;
+}
+/**
+ * Turns a link field's value into an href.
+ *
+ * Internal references route through the collection mapping rather than any
+ * hardcoded prefix, so changing a collection's URL pattern in the CMS updates
+ * every link to it.
+ *
+ * Returns null rather than degrading to the site root. A link that silently
+ * points somewhere plausible is harder to find than one that renders nothing.
+ *
+ * @param args The link value, mappings, locale and any app-declared variants.
+ */
+declare const resolveLink: <TExtra = object, TDeclaration extends LinkDeclaration = LinkDeclaration>(args: ResolveLinkArgs<TExtra, TDeclaration>) => BaseResolvedLink | ResolvedLink<TExtra> | ResolvedLinkOf<TDeclaration> | null;
+/**
+ * Whether a link would resolve to something navigable. Use it to decide
+ * whether to render a link at all, rather than emitting a dead anchor.
+ *
+ * @param args The same arguments as {@link resolveLink}, plus whether a label
+ *   is required for the link to be worth rendering.
+ */
+declare const isAvailableLink: <TExtra = object, TDeclaration extends LinkDeclaration = LinkDeclaration>(args: ResolveLinkArgs<TExtra, TDeclaration> & {
+  withLabel?: boolean;
+}) => boolean;
+//#endregion
+export { ResolveLinkArgs, ResolveReference, isAvailableLink, resolveLink };