@abinnovision/payloadcms-wayfinder 1.0.0-beta.2

package/dist/montage/index.d.mts

@@ -0,0 +1,32 @@
+import { PayloadCollectionMappingResolved } from "../pattern/types.mjs";
+import { LoadMappingsArgs } from "../config/load-mappings.mjs";
+import { MontageSlots } from "@abinnovision/payloadcms-montage";
+//#region src/montage/index.d.ts
+/**
+ * The slot the compiled mappings ride in.
+ *
+ * Prefixed with the package name because extension names share one namespace
+ * across every library using montage.
+ */
+declare const wayfinderExtension: import("@abinnovision/payloadcms-montage").ContextExtension<PayloadCollectionMappingResolved[]>;
+/**
+ * Loads the mappings once and parks them on the render context.
+ *
+ * Blocks resolve links individually and there may be dozens on a page, so the
+ * read happens once per request rather than once per link.
+ *
+ * @param ctx The render context.
+ * @param args The Payload instance and mapping-global settings.
+ */
+declare const initWayfinder: (ctx: MontageSlots, args: LoadMappingsArgs) => Promise<void>;
+/**
+ * Reads the mappings off the render context.
+ *
+ * Returns an empty list when {@link initWayfinder} has not run, so a block
+ * rendered outside a request renders without links rather than throwing.
+ *
+ * @param ctx The render context.
+ */
+declare const getMappings: (ctx: MontageSlots) => PayloadCollectionMappingResolved[];
+//#endregion
+export { getMappings, initWayfinder, wayfinderExtension };

package/dist/montage/index.mjs

@@ -0,0 +1,30 @@
+import { loadMappings } from "../config/load-mappings.mjs";
+import { createContextExtension } from "@abinnovision/payloadcms-montage";
+//#region src/montage/index.ts
+/**
+* The slot the compiled mappings ride in.
+*
+* Prefixed with the package name because extension names share one namespace
+* across every library using montage.
+*/ const wayfinderExtension = createContextExtension("wayfinder:mappings");
+/**
+* Loads the mappings once and parks them on the render context.
+*
+* Blocks resolve links individually and there may be dozens on a page, so the
+* read happens once per request rather than once per link.
+*
+* @param ctx The render context.
+* @param args The Payload instance and mapping-global settings.
+*/ const initWayfinder = async (ctx, args) => {
+	wayfinderExtension.set(ctx, await loadMappings(args));
+};
+/**
+* Reads the mappings off the render context.
+*
+* Returns an empty list when {@link initWayfinder} has not run, so a block
+* rendered outside a request renders without links rather than throwing.
+*
+* @param ctx The render context.
+*/ const getMappings = (ctx) => wayfinderExtension.get(ctx) ?? [];
+//#endregion
+export { getMappings, initWayfinder, wayfinderExtension };

package/dist/pattern/define-links.d.mts

@@ -0,0 +1,187 @@
+import { BaseResolvedLink, Contributed, DeclaredLinkVariant, LabelLike, LinkFieldData } from "./types.mjs";
+import { Field } from "payload";
+//#region src/pattern/define-links.d.ts
+/**
+ * Collapses a union of object types into their intersection.
+ *
+ * Indexing a record of variants yields a union, and `Contributed<T>` is
+ * homomorphic, so it distributes over that union and every property becomes
+ * invisible. Intersecting first is what keeps them readable.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (it: U) => void : never) extends ((it: infer I) => void) ? I : never;
+/** The values a `select` field accepts, from either option shape. */
+type OptionValue<O1> = O1 extends readonly (infer I)[] ? I extends string ? I : I extends {
+  value: infer V;
+} ? V : never : never;
+/** What a relationship or upload holds, populated or not. */
+type RelatedValue = string | number | {
+  id: string | number;
+};
+/**
+ * The value one field holds, as Payload emits it.
+ *
+ * Covers the field types a link variant realistically uses to describe a
+ * destination. Anything else resolves to `unknown` rather than a guess: a wrong
+ * type would be worse than an unhelpful one, because it would be believed.
+ *
+ * `hasMany` is checked before each scalar case for that reason — it changes the
+ * value to an array, and typing it as a scalar would be wrong rather than
+ * merely vague.
+ */
+type FieldData<F1> = F1 extends {
+  name: infer N extends string;
+} ? F1 extends {
+  type: "select" | "radio";
+  options: infer O;
+  hasMany: true;
+} ? { [K in N]?: OptionValue<O>[] | null; } : F1 extends {
+  type: "select" | "radio";
+  options: infer O;
+} ? { [K in N]?: OptionValue<O> | null; } : F1 extends {
+  type: "relationship" | "upload";
+  hasMany: true;
+} ? { [K in N]?: RelatedValue[] | null; } : F1 extends {
+  type: "relationship" | "upload";
+} ? { [K in N]?: RelatedValue | null; } : F1 extends {
+  type: "text" | "textarea" | "email" | "code" | "date";
+} ? { [K in N]?: string | null; } : F1 extends {
+  type: "number";
+} ? { [K in N]?: number | null; } : F1 extends {
+  type: "checkbox";
+} ? { [K in N]?: boolean | null; } : { [K in N]?: unknown; } : object;
+/** Everything a variant's own fields contribute, as one object type. */
+type DataOfFields<TFields extends readonly unknown[]> = UnionToIntersection<FieldData<TFields[number]>>;
+/** A variant that has had no resolver attached. */
+interface LinkVariantSpec<TFields extends readonly Field[]> {
+  label: LabelLike;
+  fields?: TFields;
+}
+/**
+ * A declared link type: its admin presentation, the fields it contributes, and
+ * how it turns into an href.
+ */
+interface LinkVariantDefinition<TCtx = unknown, TFields extends readonly Field[] = readonly Field[], TExtra = object, TData = DataOfFields<TFields>> {
+  label: LabelLike;
+  fields?: TFields;
+  resolve?: (args: {
+    link: LinkFieldData<string, TData>;
+    context: TCtx;
+  }) => (BaseResolvedLink & TExtra) | null;
+  /**
+   * The variant's data shape, in a position it can be read back from.
+   *
+   * Declared and never assigned, so no such key exists at runtime. It is
+   * here because `.data<T>()` has to override what a variant contributes,
+   * and re-deriving from `fields` would ignore it.
+   */
+  readonly __data?: TData;
+}
+/**
+ * The loosest shape a variant can take, used wherever a declaration is only
+ * being constrained rather than read.
+ *
+ * `resolve` takes `never` so that any resolver satisfies it: a parameter is
+ * contravariant, and `never` is assignable to every argument type.
+ */
+interface AnyLinkVariantDefinition {
+  label: LabelLike;
+  fields?: readonly Field[];
+  resolve?: (args: never) => unknown;
+}
+/** The link vocabulary an app declares: which types exist and how each resolves. */
+interface LinkDeclaration<TVariants1 extends Record<string, AnyLinkVariantDefinition> = Record<string, AnyLinkVariantDefinition>> {
+  variants: TVariants1;
+}
+/** The stored shape of a link field built from a declaration. */
+/**
+ * What one variant contributes.
+ *
+ * Read off `__data` rather than re-derived from `fields`, so a variant that
+ * named its own shape with `.data<T>()` keeps it.
+ */
+type DataOfVariant<V> = V extends {
+  __data?: infer D;
+} ? unknown extends D ? object : D : V extends {
+  fields?: infer F extends readonly unknown[];
+} ? DataOfFields<F> : object;
+type LinkDataOf<T> = T extends LinkDeclaration<infer TVariants> ? LinkFieldData<Extract<keyof TVariants, string>, UnionToIntersection<{ [K in keyof TVariants]: DataOfVariant<TVariants[K]>; }[keyof TVariants]>> : never;
+/** What resolving a link built from a declaration can produce. */
+type ResolvedLinkOf<T> = T extends LinkDeclaration<infer TVariants> ? BaseResolvedLink & Contributed<UnionToIntersection<{ [K in keyof TVariants]: TVariants[K] extends {
+  resolve?: (args: never) => infer R;
+} ? Extract<R, BaseResolvedLink> extends (infer E) ? Omit<E, keyof BaseResolvedLink> : object : object; }[keyof TVariants]>> : never;
+/**
+ * Builds one variant, inferring what its fields contribute.
+ *
+ * Two calls rather than one object, because TypeScript will not contextually
+ * type a resolver from a sibling property of the same object literal. Passing
+ * the fields through `variant(...)` first is what lets `.resolve()` see them.
+ */
+/** A variant part-way through being built. */
+interface VariantStep<TCtx, TFields extends readonly Field[], TData> {
+  resolve: <TExtra extends object>(fn: (args: {
+    link: LinkFieldData<string, TData>;
+    context: TCtx;
+  }) => (BaseResolvedLink & TExtra) | null) => LinkVariantDefinition<TCtx, TFields, TExtra, TData>;
+  /**
+   * Names the shape for fields that cannot be derived.
+   *
+   * A few field types resolve to `unknown`, because guessing at their shape
+   * would produce something wrong rather than something vague, and a wrong
+   * type gets believed. This replaces the derived shape for one variant,
+   * leaving every other variant alone.
+   */
+  data: <TOverride>() => VariantStep<TCtx, TFields, TOverride>;
+}
+type VariantBuilder<TCtx> = <const TFields extends readonly Field[]>(spec: LinkVariantSpec<TFields>) => LinkVariantDefinition<TCtx, TFields, object, DataOfFields<TFields>> & VariantStep<TCtx, TFields, DataOfFields<TFields>>;
+/**
+ * Declares the link types an app offers.
+ *
+ * One declaration feeds every place a link is handled: the field an editor
+ * fills in, the resolver that turns it into an href, and the rich-text
+ * feature. Passing the same declaration to all of them is what stops a variant
+ * existing in the admin panel but resolving to nothing.
+ *
+ * Curried because TypeScript has no partial type-argument inference: naming the
+ * context type up front would otherwise force every variant's fields to be
+ * named too.
+ *
+ * Returns plain data. It builds no field and resolves no link itself, so it
+ * stays free of the Payload runtime and a frontend can hold the same
+ * declaration the CMS config does.
+ */
+declare const defineLinks: <TCtx = unknown>() => <const TVariants1 extends Record<string, AnyLinkVariantDefinition>>(build: (variant: VariantBuilder<TCtx>) => {
+  variants: TVariants1;
+}) => LinkDeclaration<TVariants1>;
+/**
+ * The context a declaration's resolvers expect, recovered from the declaration
+ * itself so a caller does not have to name it twice.
+ */
+type ContextOfVariant<V> = V extends {
+  resolve?: infer R;
+} ? NonNullable<R> extends ((...args: never[]) => unknown) ? Parameters<NonNullable<R>>[0] extends {
+  context: infer C;
+} ? C : never : never : never;
+type LinkContextOf<T> = T extends LinkDeclaration<infer TVariants> ? UnionToIntersection<{ [K in keyof TVariants]: ContextOfVariant<TVariants[K]>; }[keyof TVariants]> : unknown;
+/**
+ * Carries a declaration to whichever function needs it.
+ *
+ * `TDeclaration` is a type parameter rather than the bare
+ * {@link LinkDeclaration} so that what the declaration's resolvers return, and
+ * the context they expect, both flow to the call site. Without it a caller
+ * would have to annotate the result to see its own variants' properties.
+ */
+interface LinkVariantSource<TDeclaration extends LinkDeclaration = LinkDeclaration> {
+  /** The declaration built by {@link defineLinks}. */
+  links?: TDeclaration;
+}
+/**
+ * Flattens a declaration into a list.
+ *
+ * The keyed form carries each variant's value as its key, so it is put back on
+ * the object here and everything downstream works with one shape.
+ *
+ * @param source The declaration, or nothing.
+ */
+declare const variantsOf: <TCtx, TExtra>(source: LinkVariantSource) => readonly DeclaredLinkVariant<TCtx, TExtra>[];
+//#endregion
+export { AnyLinkVariantDefinition, DataOfFields, LinkContextOf, LinkDataOf, LinkDeclaration, LinkVariantDefinition, LinkVariantSource, LinkVariantSpec, ResolvedLinkOf, VariantBuilder, defineLinks, variantsOf };

package/dist/pattern/define-links.mjs

@@ -0,0 +1,41 @@
+//#region src/pattern/define-links.ts
+const createVariantBuilder = () => {
+	const step = (spec) => ({
+		...spec,
+		resolve: (fn) => ({
+			...spec,
+			resolve: fn
+		}),
+		data: () => step(spec)
+	});
+	return (spec) => step(spec);
+};
+/**
+* Declares the link types an app offers.
+*
+* One declaration feeds every place a link is handled: the field an editor
+* fills in, the resolver that turns it into an href, and the rich-text
+* feature. Passing the same declaration to all of them is what stops a variant
+* existing in the admin panel but resolving to nothing.
+*
+* Curried because TypeScript has no partial type-argument inference: naming the
+* context type up front would otherwise force every variant's fields to be
+* named too.
+*
+* Returns plain data. It builds no field and resolves no link itself, so it
+* stays free of the Payload runtime and a frontend can hold the same
+* declaration the CMS config does.
+*/ const defineLinks = () => (build) => build(createVariantBuilder());
+/**
+* Flattens a declaration into a list.
+*
+* The keyed form carries each variant's value as its key, so it is put back on
+* the object here and everything downstream works with one shape.
+*
+* @param source The declaration, or nothing.
+*/ const variantsOf = (source) => source.links ? Object.entries(source.links.variants).map(([value, definition]) => ({
+	...definition,
+	value
+})) : [];
+//#endregion
+export { defineLinks, variantsOf };

package/dist/pattern/define-mappings.d.mts

@@ -0,0 +1,15 @@
+import { PayloadCollectionMapping, PayloadCollectionMappingResolved } from "./types.mjs";
+//#region src/pattern/define-mappings.d.ts
+/**
+ * Compiles a code-defined collection map.
+ *
+ * Every runtime function takes its mappings as plain data, so the CMS-authored
+ * global is one way to produce them and this is the other. Reach for it when
+ * routing is fixed at build time, when a project has no admin panel, or in
+ * tests — none of which should have to stand up a global first.
+ *
+ * @param mappings The collection-to-pattern map.
+ */
+declare const defineMappings: (mappings: PayloadCollectionMapping[]) => PayloadCollectionMappingResolved[];
+//#endregion
+export { defineMappings };

package/dist/pattern/define-mappings.mjs

@@ -0,0 +1,14 @@
+import { resolveCollectionMapping } from "./resolver.mjs";
+//#region src/pattern/define-mappings.ts
+/**
+* Compiles a code-defined collection map.
+*
+* Every runtime function takes its mappings as plain data, so the CMS-authored
+* global is one way to produce them and this is the other. Reach for it when
+* routing is fixed at build time, when a project has no admin panel, or in
+* tests — none of which should have to stand up a global first.
+*
+* @param mappings The collection-to-pattern map.
+*/ const defineMappings = (mappings) => mappings.map((mapping) => resolveCollectionMapping(mapping));
+//#endregion
+export { defineMappings };

package/dist/pattern/derive-link-label.d.mts

@@ -0,0 +1,23 @@
+import { LinkFieldData } from "./types.mjs";
+import { LinkVariantSource } from "./define-links.mjs";
+//#region src/pattern/derive-link-label.d.ts
+/**
+ * Derives a short destination hint for a link.
+ *
+ * Payload's floating link editor builds its hover preview from a top-level
+ * `label` / `url`, neither of which a nested link group populates on its own,
+ * so without this the preview is blank for every link.
+ *
+ * The hint describes where the link points rather than what it says. Anchor
+ * text would look like a resolved title while telling an editor nothing about
+ * the destination.
+ *
+ * Lives in the pure layer because both the editor feature and the admin
+ * component need it, and neither may import the other.
+ *
+ * @param link The nested link group of a link node.
+ * @param source App-declared link types, which may describe themselves.
+ */
+declare const deriveLinkLabel: <TExtra>(link: LinkFieldData<string, TExtra>, source?: LinkVariantSource) => string | undefined;
+//#endregion
+export { deriveLinkLabel };

package/dist/pattern/derive-link-label.mjs

@@ -0,0 +1,35 @@
+import { variantsOf } from "./define-links.mjs";
+//#region src/pattern/derive-link-label.ts
+/**
+* Derives a short destination hint for a link.
+*
+* Payload's floating link editor builds its hover preview from a top-level
+* `label` / `url`, neither of which a nested link group populates on its own,
+* so without this the preview is blank for every link.
+*
+* The hint describes where the link points rather than what it says. Anchor
+* text would look like a resolved title while telling an editor nothing about
+* the destination.
+*
+* Lives in the pure layer because both the editor feature and the admin
+* component need it, and neither may import the other.
+*
+* @param link The nested link group of a link node.
+* @param source App-declared link types, which may describe themselves.
+*/ const deriveLinkLabel = (link, source = {}) => {
+	switch (link.type) {
+		case "custom": return link.url ?? void 0;
+		case "reference": {
+			if (!link.reference) return;
+			const { relationTo, value } = link.reference;
+			return `${relationTo}/${typeof value === "object" ? value.id : value}`;
+		}
+		case "same-page": return link.samePageIdentifier ? `#${link.samePageIdentifier}` : void 0;
+		case "none":
+		case void 0:
+		case null: return;
+		default: return variantsOf(source).find((it) => it.value === link.type)?.value;
+	}
+};
+//#endregion
+export { deriveLinkLabel };

package/dist/pattern/index.d.mts

@@ -0,0 +1,8 @@
+import { BaseResolvedLink, BuiltinLinkVariant, Contributed, DEFAULT_LOCALE_KEY, DeclaredLinkVariant, FormatHref, LabelLike, LinkFieldData, PayloadCollectionMapping, PayloadCollectionMappingMatch, PayloadCollectionMappingResolved, PayloadCollectionMappingResolvers, PayloadCollectionMappingSpecificity, ResolvedLink } from "./types.mjs";
+import { AnyLinkVariantDefinition, DataOfFields, LinkDataOf, LinkDeclaration, LinkVariantDefinition, LinkVariantSource, LinkVariantSpec, ResolvedLinkOf, VariantBuilder, defineLinks, variantsOf } from "./define-links.mjs";
+import { defineMappings } from "./define-mappings.mjs";
+import { deriveLinkLabel } from "./derive-link-label.mjs";
+import { PayloadCollectionMatch, matchCollectionMappings } from "./matcher.mjs";
+import { DEFAULT_IDENTIFIER_FIELD, RegisteredCollections, ResolveParamQueryPathArgs, resolveParamQueryPath } from "./param-query-path.mjs";
+import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./resolver.mjs";
+export { type AnyLinkVariantDefinition, type BaseResolvedLink, type BuiltinLinkVariant, type Contributed, DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, type DataOfFields, type DeclaredLinkVariant, type FormatHref, type LabelLike, type LinkDataOf, type LinkDeclaration, type LinkFieldData, type LinkVariantDefinition, type LinkVariantSource, type LinkVariantSpec, type PayloadCollectionMapping, type PayloadCollectionMappingMatch, type PayloadCollectionMappingResolved, type PayloadCollectionMappingResolvers, type PayloadCollectionMappingSpecificity, type PayloadCollectionMatch, type RegisteredCollections, type ResolveParamQueryPathArgs, type ResolvedLink, type ResolvedLinkOf, type VariantBuilder, defineLinks, defineMappings, deriveLinkLabel, isRootWildcard, matchCollectionMappings, resolveCollectionMapping, resolveParamQueryPath, resolversFor, variantsOf };

package/dist/pattern/index.mjs

@@ -0,0 +1,8 @@
+import { defineLinks, variantsOf } from "./define-links.mjs";
+import { DEFAULT_LOCALE_KEY } from "./types.mjs";
+import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./resolver.mjs";
+import { defineMappings } from "./define-mappings.mjs";
+import { deriveLinkLabel } from "./derive-link-label.mjs";
+import { matchCollectionMappings } from "./matcher.mjs";
+import { DEFAULT_IDENTIFIER_FIELD, resolveParamQueryPath } from "./param-query-path.mjs";
+export { DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, defineLinks, defineMappings, deriveLinkLabel, isRootWildcard, matchCollectionMappings, resolveCollectionMapping, resolveParamQueryPath, resolversFor, variantsOf };

package/dist/pattern/matcher.d.mts

@@ -0,0 +1,26 @@
+import { PayloadCollectionMappingMatch, PayloadCollectionMappingResolved } from "./types.mjs";
+//#region src/pattern/matcher.d.ts
+interface MatchOpts {
+  path: string;
+  locale: string;
+  mappings: PayloadCollectionMappingResolved[];
+}
+type PayloadCollectionMatch = {
+  mapping: PayloadCollectionMappingResolved;
+} & PayloadCollectionMappingMatch;
+/**
+ * Finds every collection a path could belong to, most specific first.
+ *
+ * More than one pattern can match the same path: `/legal/imprint` fits both
+ * `/:section/:slug` and a wildcard. Returning all of them lets the caller fall
+ * through to the next candidate when the first yields no document, instead of
+ * 404ing on a page that exists.
+ *
+ * Ordering is by specificity rather than by the order rows happen to sit in
+ * the CMS, so resolution stays deterministic.
+ *
+ * @param opts The path, locale and candidate mappings.
+ */
+declare const matchCollectionMappings: (opts: MatchOpts) => PayloadCollectionMatch[];
+//#endregion
+export { PayloadCollectionMatch, matchCollectionMappings };

package/dist/pattern/matcher.mjs

@@ -0,0 +1,74 @@
+import { resolversFor } from "./resolver.mjs";
+//#region src/pattern/matcher.ts
+/**
+* Orders two candidates most-specific first.
+*
+* Literal segments win outright, so `/journal/:slug` beats `/:section/:slug`
+* for `/journal/first-post`. Failing that, a catch-all yields to a fixed-arity
+* pattern. Length breaks the remaining ties, and the collection name breaks
+* the last one: two collections may legally hold the same pattern, and
+* without a final tiebreak the winner would be whichever row an editor
+* happened to drag higher.
+*/ const bySpecificity = (a, b) => {
+	const left = a.resolvers.specificity;
+	const right = b.resolvers.specificity;
+	if (left.literalSegments !== right.literalSegments) return right.literalSegments - left.literalSegments;
+	if (left.hasWildcard !== right.hasWildcard) return left.hasWildcard ? 1 : -1;
+	if (left.totalSegments !== right.totalSegments) return right.totalSegments - left.totalSegments;
+	return a.mapping.collection.localeCompare(b.mapping.collection);
+};
+/**
+* Resolves the site root. A wildcard pattern cannot match `/` — path-to-regexp
+* requires at least one segment — so the collection whose pattern is a bare
+* catch-all owns it, identified by an empty path.
+*
+* @param opts The path, locale and candidate mappings.
+*/ const matchRoot = (opts) => {
+	for (const mapping of opts.mappings) {
+		const resolvers = resolversFor(mapping, opts.locale);
+		if (!resolvers || !resolvers.specificity.hasWildcard || resolvers.specificity.literalSegments > 0 || resolvers.specificity.totalSegments !== 1) continue;
+		const field = resolvers.paramNames[0];
+		if (!field) continue;
+		return {
+			mapping,
+			identifier: {
+				field,
+				value: "/"
+			},
+			scope: {}
+		};
+	}
+};
+/**
+* Finds every collection a path could belong to, most specific first.
+*
+* More than one pattern can match the same path: `/legal/imprint` fits both
+* `/:section/:slug` and a wildcard. Returning all of them lets the caller fall
+* through to the next candidate when the first yields no document, instead of
+* 404ing on a page that exists.
+*
+* Ordering is by specificity rather than by the order rows happen to sit in
+* the CMS, so resolution stays deterministic.
+*
+* @param opts The path, locale and candidate mappings.
+*/ const matchCollectionMappings = (opts) => {
+	if (opts.path === "/") {
+		const root = matchRoot(opts);
+		return root ? [root] : [];
+	}
+	return opts.mappings.flatMap((mapping) => {
+		const resolvers = resolversFor(mapping, opts.locale);
+		return resolvers ? [{
+			mapping,
+			resolvers
+		}] : [];
+	}).sort(bySpecificity).flatMap(({ mapping, resolvers }) => {
+		const matched = resolvers.match(opts.path);
+		return matched ? [{
+			mapping,
+			...matched
+		}] : [];
+	});
+};
+//#endregion
+export { matchCollectionMappings };

package/dist/pattern/param-query-path.d.mts

@@ -0,0 +1,42 @@
+import { PayloadCollectionMappingResolved } from "./types.mjs";
+import { SanitizedCollectionConfig } from "payload";
+//#region src/pattern/param-query-path.d.ts
+/** The default field a relationship parameter matches on. */
+declare const DEFAULT_IDENTIFIER_FIELD = "slug";
+type RegisteredCollections = Record<string, {
+  config: SanitizedCollectionConfig;
+} | undefined>;
+interface ResolveParamQueryPathArgs {
+  /** The collection the mapping belongs to. */
+  config: SanitizedCollectionConfig;
+  /** The parameter name taken from the path pattern. */
+  param: string;
+  /** Every registered collection, for following relationships. */
+  collections: RegisteredCollections;
+  /**
+   * The compiled mappings, when available. Supplying them lets a
+   * relationship's identifier field be derived from the target collection's
+   * own pattern instead of assumed.
+   */
+  mappings?: PayloadCollectionMappingResolved[];
+  /** The locale to derive against; patterns may differ per locale. */
+  locale?: string;
+  /** Fallback when the target's identifier cannot be derived. */
+  identifierField?: string;
+}
+/**
+ * Resolves a path parameter to the query path it filters on.
+ *
+ * A parameter naming a plain field filters that field directly. A parameter
+ * naming a relationship filters the related document's identifier, so
+ * `:section` becomes `section.slug` for a target keyed by `slug`.
+ *
+ * @param args The collection, parameter and resolution context.
+ */
+declare const resolveParamQueryPath: (args: ResolveParamQueryPathArgs) => {
+  queryPath: string;
+} | {
+  error: string;
+};
+//#endregion
+export { DEFAULT_IDENTIFIER_FIELD, RegisteredCollections, ResolveParamQueryPathArgs, resolveParamQueryPath };

package/dist/pattern/param-query-path.mjs

@@ -0,0 +1,53 @@
+import { resolversFor } from "./resolver.mjs";
+//#region src/pattern/param-query-path.ts
+/** The default field a relationship parameter matches on. */ const DEFAULT_IDENTIFIER_FIELD = "slug";
+/**
+* Works out which field of a related collection a parameter matches on.
+*
+* The target's own pattern already names it: the last parameter of the pattern
+* a collection is served at is, by definition, what identifies its documents.
+* Deriving it means a project keyed by `permalink` or `handle` needs no
+* configuration, and cannot drift out of sync with its own routes.
+*
+* A wildcard target is excluded on purpose. Its stored value carries a leading
+* slash, while the value arriving from a match is a bare segment, so a query
+* built from it would never match — and would fail as an empty result rather
+* than as an error.
+*
+* @param target The related collection's slug.
+* @param args The resolution arguments.
+*/ const deriveIdentifierField = (target, args) => {
+	const fallback = args.identifierField ?? "slug";
+	if (!args.mappings || args.locale === void 0) return fallback;
+	const mapping = args.mappings.find((it) => it.collection === target);
+	if (!mapping) return fallback;
+	const resolvers = resolversFor(mapping, args.locale);
+	if (!resolvers || resolvers.specificity.hasWildcard) return fallback;
+	return resolvers.paramNames.at(-1) ?? fallback;
+};
+/**
+* Resolves a path parameter to the query path it filters on.
+*
+* A parameter naming a plain field filters that field directly. A parameter
+* naming a relationship filters the related document's identifier, so
+* `:section` becomes `section.slug` for a target keyed by `slug`.
+*
+* @param args The collection, parameter and resolution context.
+*/ const resolveParamQueryPath = (args) => {
+	const field = args.config.flattenedFields.find((it) => it.name === args.param);
+	if (!field) return { error: `Collection "${args.config.slug}" does not define a field named "${args.param}"` };
+	if (field.type !== "relationship") return { queryPath: args.param };
+	const targets = Array.isArray(field.relationTo) ? field.relationTo : [field.relationTo];
+	const identifiers = /* @__PURE__ */ new Set();
+	let identifier = args.identifierField ?? "slug";
+	for (const target of targets) {
+		const targetConfig = args.collections[target]?.config;
+		identifier = deriveIdentifierField(target, args);
+		if (!targetConfig?.flattenedFields.some((it) => it.name === identifier)) return { error: `Relationship "${args.param}" points at "${target}", which has no "${identifier}" field to match on` };
+		identifiers.add(identifier);
+	}
+	if (identifiers.size > 1) return { error: `Relationship "${args.param}" points at collections identified by different fields (${[...identifiers].sort().join(", ")}), which cannot be matched in one query` };
+	return { queryPath: `${args.param}.${identifier}` };
+};
+//#endregion
+export { DEFAULT_IDENTIFIER_FIELD, resolveParamQueryPath };

package/dist/pattern/resolver.d.mts

@@ -0,0 +1,30 @@
+import { PayloadCollectionMapping, PayloadCollectionMappingResolved, PayloadCollectionMappingResolvers } from "./types.mjs";
+//#region src/pattern/resolver.d.ts
+/**
+ * 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.
+ */
+declare const isRootWildcard: (resolvers: PayloadCollectionMappingResolvers, values: string[]) => boolean;
+/**
+ * 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.
+ */
+declare const resolversFor: (mapping: PayloadCollectionMappingResolved, locale: string) => PayloadCollectionMappingResolvers | undefined;
+/**
+ * Compiles a mapping's patterns into match and build functions.
+ *
+ * @param input The mapping as authored.
+ */
+declare const resolveCollectionMapping: (input: PayloadCollectionMapping) => PayloadCollectionMappingResolved;
+//#endregion
+export { isRootWildcard, resolveCollectionMapping, resolversFor };