@abinnovision/payloadcms-wayfinder 1.0.0-beta.2 → 1.0.0-beta.4

package/README.md

@@ -6,10 +6,11 @@ Editor-authored URL routing for [Payload CMS](https://payloadcms.com/).
 
 Wayfinder owns one thing: the map from collections to the URL patterns their documents are served
 at. That map is authored in the CMS, so adding a page type is an editorial act rather than a code
-change. Everything else in the package falls out of it. `buildHref` turns a document into an href,
-`buildPath` builds a path from parameter values alone for sitemaps and feeds,
-`resolvePathToDocument` turns a request path back into a document for a catch-all route, and
-`resolveLink` plus `linkField` give editors a link that follows its target when that collection's
+change. Everything else in the package falls out of it. `createRouter` binds the mapping, the
+locale and the href formatter once per request and hands back a router: `router.href` turns a
+document into an href, `router.path` builds a path from parameter values alone for sitemaps and
+feeds, `router.resolve` turns a request path back into a document for a catch-all route, and
+`router.link` plus `linkField` give editors a link that follows its target when that collection's
 pattern changes. [`docs/concepts.md`](./docs/concepts.md) describes the model;
 [`docs/limitations.md`](./docs/limitations.md) states what is out of scope and why.
 
@@ -42,7 +43,7 @@ import { buildConfig } from "payload";
 
 export default buildConfig({
   // ...
-  plugins: [wayfinderPlugin({ linkableCollections: ["pages", "articles"] })],
+  plugins: [wayfinderPlugin({ checkDefaultPopulateOn: ["pages", "articles"] })],
 });
 ```
 
@@ -63,7 +64,7 @@ Read the mapping and hand it to a catch-all route:
 
 ```tsx
 // app/[[...path]]/page.tsx
-import { resolvePathToDocument } from "@abinnovision/payloadcms-wayfinder";
+import { createRouter } from "@abinnovision/payloadcms-wayfinder";
 import { loadMappings } from "@abinnovision/payloadcms-wayfinder/config";
 import { notFound } from "next/navigation";
 import { getPayload } from "payload";
@@ -75,11 +76,10 @@ const Page = async ({ params }: { params: Promise<{ path?: string[] }> }) => {
   const mappings = await loadMappings({ payload });
   const { path } = await params;
 
-  const resolved = await resolvePathToDocument({
+  const wayfinder = createRouter({ mappings, locale: "en" });
+
+  const resolved = await wayfinder.resolve(`/${(path ?? []).join("/")}`, {
     payload,
-    mappings,
-    path: `/${(path ?? []).join("/")}`,
-    locale: "en",
   });
 
   if (!resolved) {
@@ -98,17 +98,20 @@ export default Page;
 ## Entrypoints
 
 ```
-"."         buildHref, buildPath, resolvePathToDocument, resolveLink, defineMappings, defineLinks, types
-"./config"  wayfinderPlugin, createMappingGlobal, loadMappings, linkField
-"./lexical" wayfinderLinkFeature, linkLabelFeature, resolveLinkNode
-"./admin"   LinkLabelFeatureClient, mounted by linkLabelFeature through the import map
-"./montage" initWayfinder, getMappings, wayfinderExtension
+"."          createRouter, defineMappings, defineLinks, resolveRelationshipSlug, deriveLinkLabel, types
+"./internal" the unbound functions the router is built out of, plus the pattern internals
+"./config"   wayfinderPlugin, createMappingGlobal, loadMappings, linkField
+"./lexical"  wayfinderLinkFeature, linkLabelFeature, resolveLinkNode
+"./admin"    LinkLabelFeatureClient, mounted by linkLabelFeature through the import map
+"./montage"  initWayfinder, wayfinderFrom, wayfinderExtension
 ```
 
 `.` is the runtime half. It takes mappings as plain data and never reads the CMS, so it runs in a
-route handler, a sitemap, a script or a test alike. `./config` is loaded by the CLI, by migrations
-and by `payload generate:types`, so it must stay React-free. `./lexical`, `./admin` and
-`./montage` each pull in an optional peer and are separate for that reason.
+route handler, a sitemap, a script or a test alike. `./internal` is the escape hatch behind it,
+for a caller that holds no request or wants a different set of arguments per call; nothing there
+carries a compatibility guarantee. `./config` is loaded by the CLI, by migrations and by
+`payload generate:types`, so it must stay React-free. `./lexical`, `./admin` and `./montage` each
+pull in an optional peer and are separate for that reason.
 [`docs/layers.md`](./docs/layers.md) explains the split.
 
 ## Documentation
@@ -119,7 +122,7 @@ and by `payload generate:types`, so it must stay React-free. `./lexical`, `./adm
   works without.
 - [`docs/integration.md`](./docs/integration.md): plugin setup, caching, catch-all routes,
   sitemaps and `defaultPopulate`.
-- [`docs/linking.md`](./docs/linking.md): `linkField`, `defineLinks`, `resolveLink` and the Lexical
+- [`docs/linking.md`](./docs/linking.md): `linkField`, `defineLinks`, `router.link` and the Lexical
   feature.
 - [`docs/code-defined-mappings.md`](./docs/code-defined-mappings.md): `defineMappings`, with no CMS
   global at all.

package/dist/admin/LinkLabelFeature.client.d.mts

@@ -1,5 +1,4 @@
 //#region src/admin/LinkLabelFeature.client.d.ts
 /** Client feature registering {@link LinkLabelPlugin} on the editor. */
-declare const LinkLabelFeatureClient: import("@payloadcms/richtext-lexical").FeatureProviderProviderClient<undefined, undefined>;
-//#endregion
-export { LinkLabelFeatureClient };
+export declare const LinkLabelFeatureClient: import("@payloadcms/richtext-lexical").FeatureProviderProviderClient<undefined, undefined>;
+//#endregion

package/dist/config/collection-string-field.d.mts

@@ -1,6 +1,6 @@
 import { Field, TextField } from "payload";
 //#region src/config/collection-string-field.d.ts
-interface CreateCollectionStringFieldArgs {
+export interface CreateCollectionStringFieldArgs {
   name: string;
   required?: boolean;
   label?: TextField["label"];
@@ -15,6 +15,5 @@ interface CreateCollectionStringFieldArgs {
  *
  * @param args Field name and presentation overrides.
  */
-declare const createCollectionStringField: (args: CreateCollectionStringFieldArgs) => Field;
-//#endregion
-export { CreateCollectionStringFieldArgs, createCollectionStringField };
+export declare const createCollectionStringField: (args: CreateCollectionStringFieldArgs) => Field;
+//#endregion

package/dist/config/has-duplicates.d.mts

@@ -10,6 +10,5 @@
  *
  * @param keys The authored keys, in row order.
  */
-declare const hasDuplicates: (keys: (string | undefined)[]) => boolean;
-//#endregion
-export { hasDuplicates };
+export declare const hasDuplicates: (keys: (string | undefined)[]) => boolean;
+//#endregion

package/dist/config/link-field.d.mts

@@ -3,7 +3,7 @@ import { LinkDeclaration, LinkVariantSource } from "../pattern/define-links.mjs"
 import { Field } from "payload";
 //#region src/config/link-field.d.ts
 /** Admin labels for the built-in link types. */
-interface LinkFieldLabels {
+export interface LinkFieldLabels {
   label?: LabelLike;
   none?: LabelLike;
   reference?: LabelLike;
@@ -14,7 +14,7 @@ interface LinkFieldLabels {
   urlField?: LabelLike;
   samePageField?: LabelLike;
 }
-interface LinkFieldArgs<TDeclaration extends LinkDeclaration = LinkDeclaration> extends LinkVariantSource<TDeclaration> {
+export interface LinkFieldArgs<TDeclaration extends LinkDeclaration = LinkDeclaration> extends LinkVariantSource<TDeclaration> {
   /**
    * Every collection that has a URL. A target missing here cannot be linked
    * to from the admin panel even if its mapping exists.
@@ -30,6 +30,5 @@ interface LinkFieldArgs<TDeclaration extends LinkDeclaration = LinkDeclaration>
    */
   interfaceName?: string;
 }
-declare const linkField: <TDeclaration extends LinkDeclaration = LinkDeclaration>(args: LinkFieldArgs<TDeclaration>) => Field;
-//#endregion
-export { LinkFieldArgs, LinkFieldLabels, linkField };
+export declare const linkField: <TDeclaration extends LinkDeclaration = LinkDeclaration>(args: LinkFieldArgs<TDeclaration>) => Field;
+//#endregion

package/dist/config/load-mappings.d.mts

@@ -10,15 +10,31 @@ import { Payload } from "payload";
  * `loadMappings` call in your own framework cache and invalidate it from
  * `createMappingGlobal({ onChange })`.
  */
-interface MappingCache {
+export interface MappingCache {
   get: (key: string) => PayloadCollectionMappingResolved[] | undefined;
   set: (key: string, value: PayloadCollectionMappingResolved[]) => void;
 }
-interface LoadMappingsArgs {
+export interface LoadMappingsArgs {
   payload: Payload;
   globalSlug?: string;
-  /** Must match what {@link createMappingGlobal} was given. */
+  /**
+   * Whether patterns are per-locale.
+   *
+   * Derived from the instance's own `localization` config, which is the same
+   * authority `wayfinderPlugin` derives it from, so the two sides cannot
+   * disagree. Set it only to override that, and then on both sides.
+   */
   localized?: boolean;
+  /**
+   * The field a relationship parameter falls back to when the target
+   * collection's own pattern cannot name one.
+   *
+   * Read off the mapping global's own config when the plugin was given it,
+   * so a project states it once, where the global is declared, and both the
+   * save-time validation and the compiled mappings get the same answer. Set
+   * it here only to override that.
+   */
+  fallbackIdentifierField?: string;
   /** Reuses compiled patterns across reads. @see MappingCache */
   cache?: MappingCache;
 }
@@ -33,6 +49,5 @@ interface LoadMappingsArgs {
  *
  * @param args The Payload instance and mapping-global settings.
  */
-declare const loadMappings: (args: LoadMappingsArgs) => Promise<PayloadCollectionMappingResolved[]>;
-//#endregion
-export { LoadMappingsArgs, MappingCache, loadMappings };
+export declare const loadMappings: (args: LoadMappingsArgs) => Promise<PayloadCollectionMappingResolved[]>;
+//#endregion

package/dist/config/load-mappings.mjs

@@ -10,6 +10,16 @@ import "./mapping-global.mjs";
 };
 const defaultCache = createMemoryCache();
 /**
+* Reads what {@link createMappingGlobal} was told, off the global's own config.
+*
+* The write side validates patterns against this and the read side compiles
+* mappings with it, so the two have to agree. Carrying it on the config means
+* a project states it where it declares the global and nowhere else.
+*/ const declaredIdentifierField = (payload, slug) => {
+	const declared = (payload.config.globals.find((it) => it.slug === slug)?.custom)?.wayfinder?.fallbackIdentifierField;
+	return typeof declared === "string" ? declared : void 0;
+};
+/**
 * Reads the mapping global and compiles it.
 *
 * Returns an empty list rather than throwing when the global has never been
@@ -20,10 +30,12 @@ const defaultCache = createMemoryCache();
 *
 * @param args The Payload instance and mapping-global settings.
 */ const loadMappings = async (args) => {
-	const localized = args.localized ?? true;
+	const slug = args.globalSlug ?? "collections-mapping";
+	const localized = args.localized ?? Boolean(args.payload.config.localization);
 	const cache = args.cache ?? defaultCache;
+	const fallbackIdentifierField = args.fallbackIdentifierField ?? declaredIdentifierField(args.payload, slug);
 	const global = await args.payload.findGlobal({
-		slug: args.globalSlug ?? "collections-mapping",
+		slug,
 		depth: 0,
 		overrideAccess: true,
 		...localized ? { locale: "all" } : {}
@@ -43,12 +55,12 @@ const defaultCache = createMemoryCache();
 			path: patterns
 		}] : [];
 	});
-	const key = JSON.stringify(usable);
+	const key = JSON.stringify([usable, fallbackIdentifierField]);
 	const cached = cache.get(key);
 	if (cached) return cached;
 	const compiled = usable.flatMap((mapping) => {
 		try {
-			return [resolveCollectionMapping(mapping)];
+			return [resolveCollectionMapping(mapping, fallbackIdentifierField)];
 		} catch {
 			return [];
 		}

package/dist/config/mapping-global.d.mts

@@ -1,18 +1,27 @@
 import { GlobalConfig } from "payload";
 //#region src/config/mapping-global.d.ts
 /** The global the mapping is authored in, unless overridden. */
-declare const DEFAULT_MAPPING_GLOBAL_SLUG = "collections-mapping";
-interface CreateMappingGlobalArgs {
+export declare const DEFAULT_MAPPING_GLOBAL_SLUG = "collections-mapping";
+export interface CreateMappingGlobalArgs {
   /** Defaults to {@link DEFAULT_MAPPING_GLOBAL_SLUG}. */
   globalSlug?: string;
   /**
-   * Whether path patterns differ per locale. Turn it off for a project with
-   * no `localization` block — Payload would otherwise return a scalar where
-   * a per-locale record is expected.
+   * Whether path patterns differ per locale.
+   *
+   * Derived from the config's `localization` block by `wayfinderPlugin`, and
+   * from the running instance by `loadMappings`, so a project normally never
+   * sets it. Pass it only to override that — and then to both sides, because
+   * Payload returns a scalar for an unlocalized field and a per-locale record
+   * for a localized one, and the read has to expect the shape the write
+   * produced.
    */
   localized?: boolean;
-  /** Fallback identifier field for relationship parameters. */
-  identifierField?: string;
+  /**
+   * The field a relationship parameter falls back to when the target
+   * collection's pattern cannot name one. Used here to validate a pattern at
+   * save time, before any mapping has been compiled to carry it.
+   */
+  fallbackIdentifierField?: string;
   label?: GlobalConfig["label"];
   adminGroup?: string;
   access?: GlobalConfig["access"];
@@ -29,6 +38,5 @@ interface CreateMappingGlobalArgs {
  *
  * @param args Slug, localization and presentation overrides.
  */
-declare const createMappingGlobal: (args?: CreateMappingGlobalArgs) => GlobalConfig;
-//#endregion
-export { CreateMappingGlobalArgs, DEFAULT_MAPPING_GLOBAL_SLUG, createMappingGlobal };
+export declare const createMappingGlobal: (args?: CreateMappingGlobalArgs) => GlobalConfig;
+//#endregion

package/dist/config/mapping-global.mjs

@@ -41,7 +41,7 @@ import { text } from "payload/shared";
 					config: collection.config,
 					param: key.name,
 					collections: opts.req.payload.collections,
-					...args.identifierField ? { identifierField: args.identifierField } : {}
+					...args.fallbackIdentifierField ? { fallbackIdentifierField: args.fallbackIdentifierField } : {}
 				});
 				if ("error" in resolved) return resolved.error;
 			}
@@ -51,6 +51,7 @@ import { text } from "payload/shared";
 	return {
 		slug: args.globalSlug ?? "collections-mapping",
 		label: args.label ?? "Collections Mapping",
+		...args.fallbackIdentifierField ? { custom: { wayfinder: { fallbackIdentifierField: args.fallbackIdentifierField } } } : {},
 		...args.access ? { access: args.access } : {},
 		admin: {
 			group: args.adminGroup ?? "Settings",

package/dist/config/plugin.d.mts

@@ -1,12 +1,15 @@
 import { CreateMappingGlobalArgs } from "./mapping-global.mjs";
 import { Plugin } from "payload";
 //#region src/config/plugin.d.ts
-interface WayfinderPluginArgs extends CreateMappingGlobalArgs {
+export interface WayfinderPluginArgs extends CreateMappingGlobalArgs {
   /**
-   * Collections that can be linked to. Only used to warn about missing
-   * `defaultPopulate`; linking itself is governed by the link field.
+   * Collections to check for `defaultPopulate` at boot.
+   *
+   * Named for what it does. It grants nothing: which collections can be
+   * linked to is decided by the link field's own `relationTo`, and an
+   * earlier name implied this list governed that.
    */
-  linkableCollections?: string[];
+  checkDefaultPopulateOn?: string[];
   /**
    * Set when the project resolves references through its own index rather
    * than a populated document. Suppresses the `defaultPopulate` warning,
@@ -26,6 +29,5 @@ interface WayfinderPluginArgs extends CreateMappingGlobalArgs {
  *
  * @param args Mapping-global settings and startup-check inputs.
  */
-declare const wayfinderPlugin: (args?: WayfinderPluginArgs) => Plugin;
-//#endregion
-export { WayfinderPluginArgs, wayfinderPlugin };
+export declare const wayfinderPlugin: (args?: WayfinderPluginArgs) => Plugin;
+//#endregion

package/dist/config/plugin.mjs

@@ -13,7 +13,10 @@ import { createMappingGlobal } from "./mapping-global.mjs";
 */ const wayfinderPlugin = (args = {}) => (incoming) => {
 	const config = {
 		...incoming,
-		globals: [...incoming.globals ?? [], createMappingGlobal(args)],
+		globals: [...incoming.globals ?? [], createMappingGlobal({
+			localized: Boolean(incoming.localization),
+			...args
+		})],
 		i18n: {
 			...incoming.i18n,
 			translations: {
@@ -24,7 +27,7 @@ import { createMappingGlobal } from "./mapping-global.mjs";
 	};
 	if (args.quiet) return config;
 	if (!args.resolvesReferencesExternally) {
-		const missing = (args.linkableCollections ?? []).filter((slug) => {
+		const missing = (args.checkDefaultPopulateOn ?? []).filter((slug) => {
 			const collection = config.collections?.find((it) => it.slug === slug);
 			return collection && !collection.defaultPopulate;
 		});

package/dist/config/translations.d.mts

@@ -6,7 +6,7 @@
  * without the plugin still works — `req.t` returns the key's fallback — but
  * sees these in English regardless of the admin locale.
  */
-declare const wayfinderTranslations: {
+export declare const wayfinderTranslations: {
   readonly en: {
     readonly wayfinder: {
       readonly duplicateCollection: "Each collection may only be mapped once";
@@ -30,5 +30,4 @@ declare const wayfinderTranslations: {
     };
   };
 };
-//#endregion
-export { wayfinderTranslations };
+//#endregion

package/dist/index.d.mts

@@ -1,16 +1,12 @@
-import { BaseResolvedLink, BuiltinLinkVariant, Contributed, DEFAULT_LOCALE_KEY, DeclaredLinkVariant, FormatHref, LabelLike, LinkFieldData, PayloadCollectionMapping, PayloadCollectionMappingMatch, PayloadCollectionMappingResolved, PayloadCollectionMappingResolvers, PayloadCollectionMappingSpecificity, ResolvedLink } from "./pattern/types.mjs";
-import { AnyLinkVariantDefinition, DataOfFields, LinkDataOf, LinkDeclaration, LinkVariantDefinition, LinkVariantSource, LinkVariantSpec, ResolvedLinkOf, VariantBuilder, defineLinks, variantsOf } from "./pattern/define-links.mjs";
-import { defineMappings } from "./pattern/define-mappings.mjs";
-import { deriveLinkLabel } from "./pattern/derive-link-label.mjs";
-import { PayloadCollectionMatch, matchCollectionMappings } from "./pattern/matcher.mjs";
-import { DEFAULT_IDENTIFIER_FIELD, RegisteredCollections, ResolveParamQueryPathArgs, resolveParamQueryPath } from "./pattern/param-query-path.mjs";
-import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
-import "./pattern/index.mjs";
+import { BaseResolvedLink, BuiltinLinkVariant, DocumentId, FormatHref, LabelLike, LinkFieldData, PayloadCollectionMapping, PayloadCollectionMappingResolved } from "./pattern/types.mjs";
+import { LinkContextOf, LinkDataOf, LinkDeclaration, ResolvedLinkOf, defineLinks } from "./pattern/define-links.mjs";
 import { BuildDiagnosticReason, Diagnostic, DiagnosticReason, OnDiagnostic, ResolveLinkDiagnosticReason, ResolvePathDiagnosticReason } from "./runtime/diagnostics.mjs";
-import { BuildHrefArgs, LinkableDocument, buildHref, identityFormatHref } from "./runtime/build-href.mjs";
-import { BuildPathArgs, buildPath } from "./runtime/build-path.mjs";
-import { ResolveLinkArgs, ResolveReference, isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
-import { PayloadDocument, ResolvePathToDocumentArgs, ResolvePathWhere, ResolvedPath, resolvePathToDocument } from "./runtime/resolve-path.mjs";
+import { LinkableDocument } from "./runtime/build-href.mjs";
+import { ResolveReference } from "./runtime/resolve-link.mjs";
+import { PayloadCollectionMatch } from "./pattern/matcher.mjs";
+import { PayloadDocument, ResolvePathWhere, ResolvedPath } from "./runtime/resolve-path.mjs";
+import { CreateRouterArgs, Router, createRouter } from "./runtime/create-router.mjs";
 import { ResolveRelationshipSlugArgs, resolveRelationshipSlug } from "./runtime/resolve-relationship-slug.mjs";
-import "./runtime/index.mjs";
-export { type AnyLinkVariantDefinition, type BaseResolvedLink, type BuildDiagnosticReason, type BuildHrefArgs, type BuildPathArgs, type BuiltinLinkVariant, type Contributed, DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, type DataOfFields, type DeclaredLinkVariant, type Diagnostic, type DiagnosticReason, type FormatHref, type LabelLike, type LinkDataOf, type LinkDeclaration, type LinkFieldData, type LinkVariantDefinition, type LinkVariantSource, type LinkVariantSpec, type LinkableDocument, type OnDiagnostic, type PayloadCollectionMapping, type PayloadCollectionMappingMatch, type PayloadCollectionMappingResolved, type PayloadCollectionMappingResolvers, type PayloadCollectionMappingSpecificity, type PayloadCollectionMatch, type PayloadDocument, type RegisteredCollections, type ResolveLinkArgs, type ResolveLinkDiagnosticReason, type ResolveParamQueryPathArgs, type ResolvePathDiagnosticReason, type ResolvePathToDocumentArgs, type ResolvePathWhere, type ResolveReference, type ResolveRelationshipSlugArgs, type ResolvedLink, type ResolvedLinkOf, type ResolvedPath, type VariantBuilder, buildHref, buildPath, defineLinks, defineMappings, deriveLinkLabel, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolveRelationshipSlug, resolversFor, variantsOf };
+import { defineMappings } from "./pattern/define-mappings.mjs";
+import { deriveLinkLabel } from "./pattern/derive-link-label.mjs";
+export { type BaseResolvedLink, type BuildDiagnosticReason, type BuiltinLinkVariant, type CreateRouterArgs, type Diagnostic, type DiagnosticReason, type DocumentId, type FormatHref, type LabelLike, type LinkContextOf, type LinkDataOf, type LinkDeclaration, type LinkFieldData, type LinkableDocument, type OnDiagnostic, type PayloadCollectionMapping, type PayloadCollectionMappingResolved, type PayloadCollectionMatch, type PayloadDocument, type ResolveLinkDiagnosticReason, type ResolvePathDiagnosticReason, type ResolvePathWhere, type ResolveReference, type ResolveRelationshipSlugArgs, type ResolvedLinkOf, type ResolvedPath, type Router, createRouter, defineLinks, defineMappings, deriveLinkLabel, resolveRelationshipSlug };

package/dist/index.mjs

@@ -1,15 +1,6 @@
-import { defineLinks, variantsOf } from "./pattern/define-links.mjs";
-import { DEFAULT_LOCALE_KEY } from "./pattern/types.mjs";
-import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
+import { defineLinks } from "./pattern/define-links.mjs";
+import { createRouter } from "./runtime/create-router.mjs";
+import { resolveRelationshipSlug } from "./runtime/resolve-relationship-slug.mjs";
 import { defineMappings } from "./pattern/define-mappings.mjs";
 import { deriveLinkLabel } from "./pattern/derive-link-label.mjs";
-import { matchCollectionMappings } from "./pattern/matcher.mjs";
-import { DEFAULT_IDENTIFIER_FIELD, resolveParamQueryPath } from "./pattern/param-query-path.mjs";
-import "./pattern/index.mjs";
-import { buildHref, identityFormatHref } from "./runtime/build-href.mjs";
-import { buildPath } from "./runtime/build-path.mjs";
-import { isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
-import { resolvePathToDocument } from "./runtime/resolve-path.mjs";
-import { resolveRelationshipSlug } from "./runtime/resolve-relationship-slug.mjs";
-import "./runtime/index.mjs";
-export { DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, buildHref, buildPath, defineLinks, defineMappings, deriveLinkLabel, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolveRelationshipSlug, resolversFor, variantsOf };
+export { createRouter, defineLinks, defineMappings, deriveLinkLabel, resolveRelationshipSlug };

package/dist/internal.d.mts

@@ -0,0 +1,11 @@
+import { Contributed, DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, DeclaredLinkVariant, PayloadCollectionMappingMatch, PayloadCollectionMappingResolvers, PayloadCollectionMappingSpecificity, ResolvedLink } from "./pattern/types.mjs";
+import { AnyLinkVariantDefinition, DataOfFields, LinkVariantDefinition, LinkVariantSource, LinkVariantSpec, VariantBuilder, variantsOf } from "./pattern/define-links.mjs";
+import { BuildHrefArgs, buildHref, identityFormatHref } from "./runtime/build-href.mjs";
+import { ResolveLinkArgs, isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
+import { matchCollectionMappings } from "./pattern/matcher.mjs";
+import { ResolvePathToDocumentArgs, resolvePathToDocument } from "./runtime/resolve-path.mjs";
+import { BuildPathArgs, buildPath } from "./runtime/build-path.mjs";
+import { normaliseLinkNodeFields } from "./pattern/link-node.mjs";
+import { RegisteredCollections, ResolveParamQueryPathArgs, resolveParamQueryPath } from "./pattern/param-query-path.mjs";
+import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
+export { type AnyLinkVariantDefinition, type BuildHrefArgs, type BuildPathArgs, type Contributed, DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, type DataOfFields, type DeclaredLinkVariant, type LinkVariantDefinition, type LinkVariantSource, type LinkVariantSpec, type PayloadCollectionMappingMatch, type PayloadCollectionMappingResolvers, type PayloadCollectionMappingSpecificity, type RegisteredCollections, type ResolveLinkArgs, type ResolveParamQueryPathArgs, type ResolvePathToDocumentArgs, type ResolvedLink, type VariantBuilder, buildHref, buildPath, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, normaliseLinkNodeFields, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolversFor, variantsOf };

package/dist/internal.mjs

@@ -0,0 +1,11 @@
+import { DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY } from "./pattern/types.mjs";
+import { isRootWildcard, resolveCollectionMapping, resolversFor } from "./pattern/resolver.mjs";
+import { buildHref, identityFormatHref } from "./runtime/build-href.mjs";
+import { buildPath } from "./runtime/build-path.mjs";
+import { variantsOf } from "./pattern/define-links.mjs";
+import { isAvailableLink, resolveLink } from "./runtime/resolve-link.mjs";
+import { matchCollectionMappings } from "./pattern/matcher.mjs";
+import { resolveParamQueryPath } from "./pattern/param-query-path.mjs";
+import { resolvePathToDocument } from "./runtime/resolve-path.mjs";
+import { normaliseLinkNodeFields } from "./pattern/link-node.mjs";
+export { DEFAULT_IDENTIFIER_FIELD, DEFAULT_LOCALE_KEY, buildHref, buildPath, identityFormatHref, isAvailableLink, isRootWildcard, matchCollectionMappings, normaliseLinkNodeFields, resolveCollectionMapping, resolveLink, resolveParamQueryPath, resolvePathToDocument, resolversFor, variantsOf };

package/dist/lexical/index.d.mts

@@ -1,4 +1,3 @@
-import { BaseResolvedLink, LinkFieldData, ResolvedLink } from "../pattern/types.mjs";
 import { LinkDeclaration, ResolvedLinkOf } from "../pattern/define-links.mjs";
 import { LinkFieldArgs } from "../config/link-field.mjs";
 import { ResolveLinkArgs } from "../runtime/resolve-link.mjs";
@@ -9,7 +8,7 @@ import { LinkFeature } from "@payloadcms/richtext-lexical";
  * destination, so the floating link editor shows a useful hover preview
  * instead of a blank one.
  */
-declare const linkLabelFeature: import("@payloadcms/richtext-lexical").FeatureProviderProviderServer<undefined, undefined, undefined>;
+export declare const linkLabelFeature: import("@payloadcms/richtext-lexical").FeatureProviderProviderServer<undefined, undefined, undefined>;
 /**
  * Replaces Lexical's link fields with the wayfinder link field, so links
  * written in rich text route through the collection mapping exactly like links
@@ -17,36 +16,22 @@ declare const linkLabelFeature: import("@payloadcms/richtext-lexical").FeaturePr
  *
  * @param args The same arguments as the standalone link field.
  */
-declare const wayfinderLinkFeature: <TDeclaration extends LinkDeclaration = LinkDeclaration>(args: LinkFieldArgs<TDeclaration>) => ReturnType<typeof LinkFeature>;
-/**
- * The two shapes a link node's fields arrive in.
- *
- * A node written by {@link wayfinderLinkFeature} nests the group under `link`.
- * A node written by Lexical's stock link feature stores `linkType` and `doc`
- * at the top level, which existing content will still hold.
- */
-interface SerializedLinkFields {
-  link?: LinkFieldData;
-  linkType?: "custom" | "internal";
-  url?: string | null;
-  newTab?: boolean | null;
-  doc?: {
-    relationTo: string;
-    value: string | {
-      id: string;
-    };
-  } | null;
-}
+export declare const wayfinderLinkFeature: <TDeclaration extends LinkDeclaration = LinkDeclaration>(args: LinkFieldArgs<TDeclaration>) => ReturnType<typeof LinkFeature>;
 /**
  * Resolves a rich-text link node to an href.
  *
+ * Takes the node's `fields` as `unknown`, because Lexical types them as an
+ * open record and a narrower parameter would make every converter cast. The
+ * two shapes a node can hold are unwrapped by
+ * {@link normaliseLinkNodeFields}, so a link written in rich text and a link
+ * authored in a block resolve through exactly the same call.
+ *
  * Returns null when the node points nowhere resolvable, so a converter can
  * render the text without an anchor rather than emitting a dead one.
  *
  * @param args The node's fields plus the usual link-resolution arguments.
  */
-declare const resolveLinkNode: <TExtra = object, TDeclaration extends LinkDeclaration = LinkDeclaration>(args: Omit<ResolveLinkArgs<TExtra, TDeclaration>, "link"> & {
-  fields: SerializedLinkFields | undefined;
-}) => BaseResolvedLink | ResolvedLink<object> | ResolvedLinkOf<TDeclaration> | null;
-//#endregion
-export { linkLabelFeature, resolveLinkNode, wayfinderLinkFeature };
+export declare const resolveLinkNode: <TDeclaration extends LinkDeclaration = LinkDeclaration>(args: Omit<ResolveLinkArgs<TDeclaration>, "link"> & {
+  fields: unknown;
+}) => ResolvedLinkOf<TDeclaration> | null;
+//#endregion

package/dist/lexical/index.mjs

@@ -1,4 +1,5 @@
 import { resolveLink } from "../runtime/resolve-link.mjs";
+import { normaliseLinkNodeFields } from "../pattern/link-node.mjs";
 import { linkField } from "../config/link-field.mjs";
 import { LinkFeature, createServerFeature } from "@payloadcms/richtext-lexical";
 //#region src/lexical/index.ts
@@ -22,36 +23,21 @@ import { LinkFeature, createServerFeature } from "@payloadcms/richtext-lexical";
 * @param args The same arguments as the standalone link field.
 */ const wayfinderLinkFeature = (args) => LinkFeature({ fields: () => [linkField(args)] });
 /**
-* Normalises a link node's fields into the link field's own shape.
-*
-* @param fields The node's `fields` object.
-*/ const normaliseNodeFields = (fields) => {
-	if (!fields) return;
-	if (fields.link) return fields.link;
-	if (fields.linkType === "internal" && fields.doc) return {
-		type: "reference",
-		reference: fields.doc,
-		newTab: fields.newTab ?? null
-	};
-	if (fields.url) return {
-		type: "custom",
-		url: fields.url,
-		newTab: fields.newTab ?? null
-	};
-};
-/**
 * Resolves a rich-text link node to an href.
 *
+* Takes the node's `fields` as `unknown`, because Lexical types them as an
+* open record and a narrower parameter would make every converter cast. The
+* two shapes a node can hold are unwrapped by
+* {@link normaliseLinkNodeFields}, so a link written in rich text and a link
+* authored in a block resolve through exactly the same call.
+*
 * Returns null when the node points nowhere resolvable, so a converter can
 * render the text without an anchor rather than emitting a dead one.
 *
 * @param args The node's fields plus the usual link-resolution arguments.
-*/ const resolveLinkNode = (args) => {
-	const link = normaliseNodeFields(args.fields);
-	return resolveLink({
-		...args,
-		link
-	});
-};
+*/ const resolveLinkNode = (args) => resolveLink({
+	...args,
+	link: normaliseLinkNodeFields(args.fields)
+});
 //#endregion
 export { linkLabelFeature, resolveLinkNode, wayfinderLinkFeature };