@justanarthur/payload-www 2.2.8 → 2.3.0

package/README.md

@@ -20,7 +20,7 @@ The composition root is `createWWWConfig()` — see [Quick start](#quick-start)
 | Fields | [`/fields`](#fields) | `link`, `linkGroup` (with `disableLabel` / `appearances` / `localized` / `relationTo` / `extraFields`), `slugField`, `appearanceOptions`. |
 | Access | [`/access`](#access) | `anyone`, `authenticated`, `authenticatedOrPublished`. |
 | Caching | [`Caching`](#caching) | Cached query getters wrap `@pro-laico/payload-revalidate` finders; tag-based invalidation via `revalidatePlugin()`; `seedPayloadCache` singleton seed. |
-| Metadata | [`/metadata`](#metadata) | `buildArticleLd`, `buildBreadcrumbsLd`, `buildOrganizationLd`, `buildWebSiteLd`, `buildProductLd`, `buildRootJsonLd`; slug transforms; `queryDocBySlug`, `queryDocByID`, `queryGlobal`, `queryAllDocs`, `queryAllLocaleSlugs`; `seedPayloadCache`, `tagsFor`. |
+| Metadata | [`/metadata`](#metadata) | `buildArticleLd`, `buildBreadcrumbsLd`, `buildOrganizationLd`, `buildWebSiteLd`, `buildProductLd`, `buildRootJsonLd`; slug transforms; `queryDocBySlug`, `queryDocByID`, `queryGlobal`, `queryDocs`, `queryAllDocs`, `queryAllLocaleSlugs`; `seedPayloadCache`, `tagsFor`. |
 | Next.js page renderers | [`/render-pages`](#render-pages) | `createCollectionPageExports`, `createRootLayoutExports`; default render components `PagesPage`, `PostsPage`, `HeaderPage`, `FooterPage`, `RootJsonLd`. |
 | Sitemap | [`/sitemap`](#sitemap) | `createSitemapFromCollections` (Next.js file-convention helper). |
 | Plugin re-exports | [`/imagehash`](#plugin-re-exports), [`/translator`](#plugin-re-exports) | Drop-in for hosts that don't want to import the sibling packages directly. |
@@ -144,6 +144,7 @@ const { default: PostPage, generateMetadata, generateStaticParams } = createColl
 | `routing` | `RoutingConfig` | required | `{ locales, defaultLocale, localePrefix, labels? }` from `next-intl/routing`'s `defineRouting` |
 | `slug` | `string` | `'pages'` | collection slug to query |
 | `slugShape` | `'single' \| 'catch-all'` | `'single'` | drives `generateStaticParams` + slug segmentation |
+| `depth` | `number` | `2` | relationship / upload hops populated on the rendered document. `0` hands every media and relationship field to the render component as a bare id. Enumeration (`generateStaticParams`, `generateSitemap`) stays at `0` regardless. |
 
 ### `createCollectionPageExports(args, deps)` — deps
 
@@ -171,6 +172,7 @@ const { default: PostPage, generateMetadata, generateStaticParams } = createColl
 | `config` | `Promise<SanitizedConfig>` | required |
 | `importMap` | `ImportMap` | required |
 | `routing` | `RoutingConfig` | required |
+| `depth` | `number` | relationship / upload hops populated on the `header` + `footer` globals. Defaults to `2`. |
 
 | dep | type | notes |
 |---|---|---|
@@ -253,8 +255,8 @@ in the host's `revalidatePlugin()` registration (see [Caching](#caching) below).
 
 ### Caching
 
-The lib's cached query layer (`queryDocBySlug`, `queryGlobal`, `queryAllDocs`, `queryAllLocaleSlugs`,
-`queryDocByID`) wraps `@pro-laico/payload-revalidate`'s finders in `'use cache'` + `cacheLife('weeks')`
+The lib's cached query layer (`queryDocBySlug`, `queryGlobal`, `queryDocs`, `queryAllDocs`,
+`queryAllLocaleSlugs`, `queryDocByID`) wraps `@pro-laico/payload-revalidate`'s finders in `'use cache'` + `cacheLife('weeks')`
 scopes. Setup:
 
 1. **Install the peer deps at the workspace root** (not in the lib's `dependencies` — `file:` links
@@ -301,6 +303,34 @@ scopes. Setup:
    seedPayloadCache({ config })
    ```
 
+6. **List with `queryDocs`, never a raw `payload.find`** — a read inside `'use cache'` that
+   doesn't go through the finders carries no tags, so nothing the admin does can bust it.
+   `queryDocs` tags list membership plus every returned doc and what is populated into it:
+
+   ```ts
+   import { queryDocs } from '@justanarthur/payload-www/metadata'
+
+   const { docs, totalPages } = await queryDocs({
+     collectionSlug: 'posts',
+     locale,
+     sort: '-publishedAt',
+     limit: 10,
+     depth: 1,
+     list: 'archive'
+   })
+   ```
+
+   `list` names a scope whose sort and filter fields are declared on the plugin, so moving a
+   post's date or category reorders the archive even when that post wasn't on the page:
+
+   ```ts
+   createWWWConfig().withWWWConfig({
+     defaultPluginsConfigs: {
+       revalidate: { collections: { posts: { lists: { archive: ['publishedAt', 'categories'] } } } }
+     }
+   })
+   ```
+
 The cached profile is `cacheLife('weeks')` — Next 16's built-in long-tail profile (5 m stale,
 1 w revalidate, 30 d expire). No custom `cacheLife` config entry needed. Invalidations are
 purely tag-based: `revalidatePlugin()` fires the same tags the finders emit, so every save /
@@ -344,6 +374,7 @@ import {
   queryDocBySlug,           // cached collection fetch
   queryDocByID,             // cached collection fetch by id
   queryGlobal,              // cached global fetch
+  queryDocs,                // cached, tagged listing (where / sort / limit / page)
   queryAllDocs,             // for generateStaticParams
   queryAllLocaleSlugs,      // for hreflang alternates
   seedPayloadCache,         // one-time seed for the pro-laico cache helpers
@@ -396,7 +427,7 @@ The package's `package.json#exports` map:
 | `@justanarthur/payload-www/collections` | `createWWWCollectionGlobal`, `queryDoc` |
 | `@justanarthur/payload-www/fields` | `link`, `linkGroup`, `appearanceOptions`, `slugField`, `LinkAppearances`, `LinkOptions` |
 | `@justanarthur/payload-www/access` | `anyone`, `authenticated`, `authenticatedOrPublished` |
-| `@justanarthur/payload-www/metadata` | `buildArticleLd`, `buildBreadcrumbsLd`, `buildOrganizationLd`, `buildWebSiteLd`, `buildProductLd`, `buildRootJsonLd`, `queryDocBySlug`, `queryDocByID`, `queryGlobal`, `queryAllDocs`, `queryAllLocaleSlugs`, `seedPayloadCache`, `tagsFor`, `paramsSlugToSlug`, `slugToParamsSlug` + types |
+| `@justanarthur/payload-www/metadata` | `buildArticleLd`, `buildBreadcrumbsLd`, `buildOrganizationLd`, `buildWebSiteLd`, `buildProductLd`, `buildRootJsonLd`, `queryDocBySlug`, `queryDocByID`, `queryGlobal`, `queryDocs`, `queryAllDocs`, `queryAllLocaleSlugs`, `seedPayloadCache`, `tagsFor`, `paramsSlugToSlug`, `slugToParamsSlug` + types |
 | `@justanarthur/payload-www/utils` | `generateImportName`, `getFromImportMap` |
 | `@justanarthur/payload-www/imagehash` | `imageHashPlugin`, `BlurhashPluginOptions` (re-export of `@justanarthur/payload-imagehash-plugin`) |
 | `@justanarthur/payload-www/translator` | `translator` (re-export of `@justanarthur/payload-plugin-translator`) |

package/dist/collections.d.ts

@@ -20,6 +20,7 @@ type QueryDocArgs = ({
 	globalSlug: string;
 	locale: string;
 	draft?: boolean;
+	depth?: number;
 }) | ({
 	collectionSlug: string;
 	slug: string;

package/dist/collections.js

@@ -119,7 +119,7 @@ function seedPayloadCache({ config }) {
     return;
   _seedPromise = (async () => {
     const payload = await getPayload({ config: await config });
-    _helpers = createCacheHelpers(payload);
+    _helpers = { ...createCacheHelpers(payload), payload };
   })();
 }
 async function requireCacheHelpers() {
@@ -132,6 +132,7 @@ async function requireCacheHelpers() {
   }
   throw new Error("[payload-www] seedPayloadCache({ config }) must be called before any query getter. " + "Call it from createCollectionPageExports / createRootLayoutExports factory, or in your root layout.");
 }
+var RENDER_DEPTH = 2;
 async function queryDocBySlug(args) {
   "use cache";
   cacheLife("weeks");
@@ -142,7 +143,7 @@ async function queryDocBySlug(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
   const result = await find(args.slug);
   const doc = result ?? (isIndexSlug(args.slug) ? await find(null) : null);
@@ -156,7 +157,7 @@ async function queryGlobal(args) {
     const result = await findGlobal(args.globalSlug, {
       locale: args.locale,
       draft: args.draft ?? false,
-      depth: args.depth
+      depth: args.depth ?? RENDER_DEPTH
     });
     return result ?? null;
   } catch (error) {
@@ -172,9 +173,31 @@ async function queryAllDocs(args) {
   const { ids } = await findIds(collection, { locale: args.locale, pagination: false, overrideAccess: false });
   if (ids.length === 0)
     return [];
-  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false })));
+  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false, depth: 0 })));
   return docs.filter((d) => d !== null);
 }
+async function queryDocs({
+  collectionSlug,
+  list,
+  draft = false,
+  depth = RENDER_DEPTH,
+  ...find
+}) {
+  "use cache";
+  cacheLife("weeks");
+  const { payload, cacheIds, cacheDoc } = await requireCacheHelpers();
+  const collection = collectionSlug;
+  const result = await payload.find({ ...find, collection, draft, depth, overrideAccess: draft });
+  await cacheIds(result, collection, { list, draft });
+  for (const doc of result.docs)
+    await cacheDoc(doc, collection, { draft });
+  return {
+    docs: result.docs,
+    totalDocs: result.totalDocs,
+    totalPages: result.totalPages,
+    page: result.page ?? 1
+  };
+}
 async function queryDoc(args) {
   if ("globalSlug" in args)
     return queryGlobal(args);
@@ -199,7 +222,7 @@ async function queryDocByID(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
 }
 

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import { CollectionConfig, Config, GlobalConfig, Plugin } from "payload";
 import { MCPPluginConfig } from "@payloadcms/plugin-mcp";
+import { RevalidatePluginOptions } from "@pro-laico/payload-revalidate";
 import { SEOPluginConfig } from "@justanarthur/payload-plugin-seo/types";
 import { BlurhashPluginOptions } from "@justanarthur/payload-imagehash-plugin/types";
 import { TranslatorConfig } from "@justanarthur/payload-plugin-translator/types";
@@ -15,7 +16,7 @@ type WWWInputConfig = Omit<Config, "collections" | "globals" | "plugins"> & {
 		imageHash?: MergeOrOverride<BlurhashPluginOptions>;
 		translator?: MergeOrOverride<TranslatorConfig>;
 		mcp?: MergeOrOverride<MCPPluginConfig>;
-		revalidate?: false | (<D>(d: D) => D);
+		revalidate?: false | MergeOrOverride<RevalidatePluginOptions>;
 	};
 };
 declare function createWWWConfig(): WWWConfigApi;

package/dist/config.js

@@ -317,6 +317,7 @@ import { revalidatePlugin } from "@pro-laico/payload-revalidate";
 function createWWWConfig() {
   function withWWWConfig(input) {
     const { defaultPluginsConfigs, ...config } = input;
+    const revalidate = defaultPluginsConfigs?.revalidate;
     const blocks = config.blocks || [];
     const collections = mergeOrOverride([
       createPagesCollection(blocks),
@@ -362,7 +363,7 @@ function createWWWConfig() {
     ];
     const plugins = [
       ...mergeOrOverride(defaultPlugins, config.plugins),
-      revalidatePlugin()
+      revalidatePlugin(revalidate === false ? { enabled: false } : mergeOrOverride({}, revalidate))
     ];
     return {
       ...config,

package/dist/metadata.d.ts

@@ -22,7 +22,7 @@ declare function paramsSlugToSlug(slug: string | string[] | undefined, _shape: S
 declare function slugToParamsSlug(slug: string, shape: SlugShape): string | string[];
 declare function isIndexSlug(slug: string | null | undefined): boolean;
 declare function shapeHasIndexPath(shape: SlugShape): boolean;
-import { DataFromCollectionSlug, DataFromGlobalSlug, SanitizedConfig } from "payload";
+import { DataFromCollectionSlug, DataFromGlobalSlug, SanitizedConfig, SelectType, Sort, Where } from "payload";
 import { tagsFor } from "@pro-laico/payload-revalidate";
 type SeedPayloadCacheArgs = {
 	config: SanitizedConfig | Promise<SanitizedConfig>;
@@ -47,9 +47,28 @@ type QueryListArgs<S extends string> = {
 	slugField?: string;
 	locale: string;
 };
+type QueryDocsArgs<S extends string> = {
+	collectionSlug: S;
+	locale: string;
+	where?: Where;
+	sort?: Sort;
+	limit?: number;
+	page?: number;
+	depth?: number;
+	select?: SelectType;
+	draft?: boolean;
+	list?: string;
+};
+type QueryDocsResult<S extends string> = {
+	docs: DataFromCollectionSlug<S>[];
+	totalDocs: number;
+	totalPages: number;
+	page: number;
+};
 declare function queryDocBySlug<S extends string>(args: QueryCollectionArgs<S>): Promise<DataFromCollectionSlug<S> | null>;
 declare function queryGlobal<G extends string>(args: QueryGlobalArgs<G>): Promise<DataFromGlobalSlug<G> | null>;
 declare function queryAllDocs<S extends string = string>(args: QueryListArgs<S>): Promise<DataFromCollectionSlug<S>[]>;
+declare function queryDocs<S extends string>({ collectionSlug, list, draft, depth,...find }: QueryDocsArgs<S>): Promise<QueryDocsResult<S>>;
 declare function queryAllLocaleSlugs(args: {
 	collectionSlug: string;
 	id: number | string;
@@ -74,6 +93,7 @@ declare const metadata: {
 	queryDocBySlug: typeof queryDocBySlug;
 	queryDocByID: typeof queryDocByID;
 	queryGlobal: typeof queryGlobal;
+	queryDocs: typeof queryDocs;
 	queryAllDocs: typeof queryAllDocs;
 	queryAllLocaleSlugs: typeof queryAllLocaleSlugs;
 	paramsSlugToSlug: typeof paramsSlugToSlug;
@@ -83,4 +103,4 @@ declare const metadata: {
 	seedPayloadCache: typeof seedPayloadCache;
 	tagsFor: (payload: Payload_eipjla) => Tags_1jpdl;
 };
-export { ArticleLdOptions, BreadcrumbItem, BuildOrganizationLdOptions, BuildProductLdOptions, BuildRootJsonLdOptions, BuildWebSiteLdOptions, SeedPayloadCacheArgs, SlugShape, buildArticleLd, buildBreadcrumbsLd, buildOrganizationLd, buildProductLd, buildRootJsonLd, buildWebSiteLd, metadata as default, isIndexSlug, paramsSlugToSlug, queryAllDocs, queryAllLocaleSlugs, queryDocByID, queryDocBySlug, queryGlobal, seedPayloadCache, shapeHasIndexPath, slugToParamsSlug, tagsFor };
+export { ArticleLdOptions, BreadcrumbItem, BuildOrganizationLdOptions, BuildProductLdOptions, BuildRootJsonLdOptions, BuildWebSiteLdOptions, QueryDocsArgs, QueryDocsResult, SeedPayloadCacheArgs, SlugShape, buildArticleLd, buildBreadcrumbsLd, buildOrganizationLd, buildProductLd, buildRootJsonLd, buildWebSiteLd, metadata as default, isIndexSlug, paramsSlugToSlug, queryAllDocs, queryAllLocaleSlugs, queryDocByID, queryDocBySlug, queryDocs, queryGlobal, seedPayloadCache, shapeHasIndexPath, slugToParamsSlug, tagsFor };

package/dist/metadata.js

@@ -127,7 +127,7 @@ function seedPayloadCache({ config }) {
     return;
   _seedPromise = (async () => {
     const payload = await getPayload({ config: await config });
-    _helpers = createCacheHelpers(payload);
+    _helpers = { ...createCacheHelpers(payload), payload };
   })();
 }
 async function requireCacheHelpers() {
@@ -140,6 +140,7 @@ async function requireCacheHelpers() {
   }
   throw new Error("[payload-www] seedPayloadCache({ config }) must be called before any query getter. " + "Call it from createCollectionPageExports / createRootLayoutExports factory, or in your root layout.");
 }
+var RENDER_DEPTH = 2;
 async function queryDocBySlug(args) {
   "use cache";
   cacheLife("weeks");
@@ -150,7 +151,7 @@ async function queryDocBySlug(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
   const result = await find(args.slug);
   const doc = result ?? (isIndexSlug(args.slug) ? await find(null) : null);
@@ -164,7 +165,7 @@ async function queryGlobal(args) {
     const result = await findGlobal(args.globalSlug, {
       locale: args.locale,
       draft: args.draft ?? false,
-      depth: args.depth
+      depth: args.depth ?? RENDER_DEPTH
     });
     return result ?? null;
   } catch (error) {
@@ -180,9 +181,31 @@ async function queryAllDocs(args) {
   const { ids } = await findIds(collection, { locale: args.locale, pagination: false, overrideAccess: false });
   if (ids.length === 0)
     return [];
-  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false })));
+  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false, depth: 0 })));
   return docs.filter((d) => d !== null);
 }
+async function queryDocs({
+  collectionSlug,
+  list,
+  draft = false,
+  depth = RENDER_DEPTH,
+  ...find
+}) {
+  "use cache";
+  cacheLife("weeks");
+  const { payload, cacheIds, cacheDoc } = await requireCacheHelpers();
+  const collection = collectionSlug;
+  const result = await payload.find({ ...find, collection, draft, depth, overrideAccess: draft });
+  await cacheIds(result, collection, { list, draft });
+  for (const doc of result.docs)
+    await cacheDoc(doc, collection, { draft });
+  return {
+    docs: result.docs,
+    totalDocs: result.totalDocs,
+    totalPages: result.totalPages,
+    page: result.page ?? 1
+  };
+}
 async function queryDoc(args) {
   if ("globalSlug" in args)
     return queryGlobal(args);
@@ -207,7 +230,7 @@ async function queryDocByID(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
 }
 
@@ -222,6 +245,7 @@ var metadata = {
   queryDocBySlug,
   queryDocByID,
   queryGlobal,
+  queryDocs,
   queryAllDocs,
   queryAllLocaleSlugs,
   paramsSlugToSlug,
@@ -246,6 +270,7 @@ export {
   queryAllLocaleSlugs,
   queryDocByID,
   queryDocBySlug,
+  queryDocs,
   queryGlobal,
   seedPayloadCache,
   shapeHasIndexPath,

package/dist/pages.d.ts

@@ -39,6 +39,8 @@ type CreateCollectionPageExportsArgs<S extends string = "pages"> = {
 	importMap: ImportMap3;
 	routing: RoutingConfig;
 	slugShape?: SlugShape;
+	/** Relationship / upload hops populated on the rendered document. `0` renders them as bare ids. */
+	depth?: number;
 };
 type CreateCollectionPageExportsDeps<S extends string> = {
 	getServerSideURL: () => string;
@@ -46,7 +48,7 @@ type CreateCollectionPageExportsDeps<S extends string> = {
 	/** Rendered while the document streams. Defaults to nothing. */
 	fallback?: ReactNode2;
 };
-declare function createCollectionPageExports<S extends string = "pages">({ slug: collectionSlug, _payloadConfig, importMap, routing, slugShape }: CreateCollectionPageExportsArgs<S>, { getServerSideURL, pagePathPrefix, fallback }: CreateCollectionPageExportsDeps<S>): {
+declare function createCollectionPageExports<S extends string = "pages">({ slug: collectionSlug, _payloadConfig, importMap, routing, slugShape, depth }: CreateCollectionPageExportsArgs<S>, { getServerSideURL, pagePathPrefix, fallback }: CreateCollectionPageExportsDeps<S>): {
 	default: (props: NextPageProps) => Promise<ReactNode2>;
 	generateMetadata: (props: NextPageProps) => Promise<Metadata>;
 	generateStaticParams: (props: GenerateStaticParamsProps) => Promise<{

package/dist/pages.js

@@ -212,7 +212,7 @@ function seedPayloadCache({ config }) {
     return;
   _seedPromise = (async () => {
     const payload = await getPayload({ config: await config });
-    _helpers = createCacheHelpers(payload);
+    _helpers = { ...createCacheHelpers(payload), payload };
   })();
 }
 async function requireCacheHelpers() {
@@ -225,6 +225,7 @@ async function requireCacheHelpers() {
   }
   throw new Error("[payload-www] seedPayloadCache({ config }) must be called before any query getter. " + "Call it from createCollectionPageExports / createRootLayoutExports factory, or in your root layout.");
 }
+var RENDER_DEPTH = 2;
 async function queryDocBySlug(args) {
   "use cache";
   cacheLife("weeks");
@@ -235,7 +236,7 @@ async function queryDocBySlug(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
   const result = await find(args.slug);
   const doc = result ?? (isIndexSlug(args.slug) ? await find(null) : null);
@@ -249,7 +250,7 @@ async function queryGlobal(args) {
     const result = await findGlobal(args.globalSlug, {
       locale: args.locale,
       draft: args.draft ?? false,
-      depth: args.depth
+      depth: args.depth ?? RENDER_DEPTH
     });
     return result ?? null;
   } catch (error) {
@@ -265,9 +266,31 @@ async function queryAllDocs(args) {
   const { ids } = await findIds(collection, { locale: args.locale, pagination: false, overrideAccess: false });
   if (ids.length === 0)
     return [];
-  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false })));
+  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false, depth: 0 })));
   return docs.filter((d) => d !== null);
 }
+async function queryDocs({
+  collectionSlug,
+  list,
+  draft = false,
+  depth = RENDER_DEPTH,
+  ...find
+}) {
+  "use cache";
+  cacheLife("weeks");
+  const { payload, cacheIds, cacheDoc } = await requireCacheHelpers();
+  const collection = collectionSlug;
+  const result = await payload.find({ ...find, collection, draft, depth, overrideAccess: draft });
+  await cacheIds(result, collection, { list, draft });
+  for (const doc of result.docs)
+    await cacheDoc(doc, collection, { draft });
+  return {
+    docs: result.docs,
+    totalDocs: result.totalDocs,
+    totalPages: result.totalPages,
+    page: result.page ?? 1
+  };
+}
 async function queryDoc(args) {
   if ("globalSlug" in args)
     return queryGlobal(args);
@@ -292,7 +315,7 @@ async function queryDocByID(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
 }
 
@@ -368,7 +391,8 @@ function createCollectionPageExports({
   _payloadConfig,
   importMap,
   routing,
-  slugShape = "single"
+  slugShape = "single",
+  depth = RENDER_DEPTH
 }, {
   getServerSideURL,
   pagePathPrefix,
@@ -380,6 +404,7 @@ function createCollectionPageExports({
     return queryDoc({
       slug,
       locale,
+      depth,
       collectionSlug
     });
   }

package/dist/render-pages.d.ts

@@ -48,6 +48,8 @@ type CreateCollectionPageExportsArgs<S extends string = "pages"> = {
 	importMap: ImportMap3;
 	routing: RoutingConfig;
 	slugShape?: SlugShape;
+	/** Relationship / upload hops populated on the rendered document. `0` renders them as bare ids. */
+	depth?: number;
 };
 type CreateCollectionPageExportsDeps<S extends string> = {
 	getServerSideURL: () => string;
@@ -55,7 +57,7 @@ type CreateCollectionPageExportsDeps<S extends string> = {
 	/** Rendered while the document streams. Defaults to nothing. */
 	fallback?: ReactNode2;
 };
-declare function createCollectionPageExports<S extends string = "pages">({ slug: collectionSlug, _payloadConfig, importMap, routing, slugShape }: CreateCollectionPageExportsArgs<S>, { getServerSideURL, pagePathPrefix, fallback }: CreateCollectionPageExportsDeps<S>): {
+declare function createCollectionPageExports<S extends string = "pages">({ slug: collectionSlug, _payloadConfig, importMap, routing, slugShape, depth }: CreateCollectionPageExportsArgs<S>, { getServerSideURL, pagePathPrefix, fallback }: CreateCollectionPageExportsDeps<S>): {
 	default: (props: NextPageProps) => Promise<ReactNode2>;
 	generateMetadata: (props: NextPageProps) => Promise<Metadata>;
 	generateStaticParams: (props: GenerateStaticParamsProps) => Promise<{
@@ -75,6 +77,8 @@ type CreateRootLayoutExportsArgs = {
 	_payloadConfig: Promise<SanitizedConfig3>;
 	importMap: ImportMap4;
 	routing: RoutingConfig;
+	/** Relationship / upload hops populated on the header and footer globals. `0` renders them as bare ids. */
+	depth?: number;
 };
 type CreateRootLayoutProvidersArgs = {
 	children: ReactNode3;
@@ -86,7 +90,7 @@ type CreateRootLayoutExportsDeps = {
 	getServerSideURL?: () => string;
 };
 type Element_12xgc2 = JSX_1kxb2["Element"];
-declare function createRootLayoutExports({ _payloadConfig, importMap, routing }: CreateRootLayoutExportsArgs, { providers, htmlAttrs, getServerSideURL }?: CreateRootLayoutExportsDeps): {
+declare function createRootLayoutExports({ _payloadConfig, importMap, routing, depth }: CreateRootLayoutExportsArgs, { providers, htmlAttrs, getServerSideURL }?: CreateRootLayoutExportsDeps): {
 	default: (props: NextLayoutProps) => Promise<Element_12xgc2>;
 	generateStaticParams: () => {
 		locale: string;

package/dist/render-pages.js

@@ -242,7 +242,7 @@ function seedPayloadCache({ config }) {
     return;
   _seedPromise = (async () => {
     const payload = await getPayload({ config: await config });
-    _helpers = createCacheHelpers(payload);
+    _helpers = { ...createCacheHelpers(payload), payload };
   })();
 }
 async function requireCacheHelpers() {
@@ -255,6 +255,7 @@ async function requireCacheHelpers() {
   }
   throw new Error("[payload-www] seedPayloadCache({ config }) must be called before any query getter. " + "Call it from createCollectionPageExports / createRootLayoutExports factory, or in your root layout.");
 }
+var RENDER_DEPTH = 2;
 async function queryDocBySlug(args) {
   "use cache";
   cacheLife("weeks");
@@ -265,7 +266,7 @@ async function queryDocBySlug(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
   const result = await find(args.slug);
   const doc = result ?? (isIndexSlug(args.slug) ? await find(null) : null);
@@ -279,7 +280,7 @@ async function queryGlobal(args) {
     const result = await findGlobal(args.globalSlug, {
       locale: args.locale,
       draft: args.draft ?? false,
-      depth: args.depth
+      depth: args.depth ?? RENDER_DEPTH
     });
     return result ?? null;
   } catch (error) {
@@ -295,9 +296,31 @@ async function queryAllDocs(args) {
   const { ids } = await findIds(collection, { locale: args.locale, pagination: false, overrideAccess: false });
   if (ids.length === 0)
     return [];
-  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false })));
+  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false, depth: 0 })));
   return docs.filter((d) => d !== null);
 }
+async function queryDocs({
+  collectionSlug,
+  list,
+  draft = false,
+  depth = RENDER_DEPTH,
+  ...find
+}) {
+  "use cache";
+  cacheLife("weeks");
+  const { payload, cacheIds, cacheDoc } = await requireCacheHelpers();
+  const collection = collectionSlug;
+  const result = await payload.find({ ...find, collection, draft, depth, overrideAccess: draft });
+  await cacheIds(result, collection, { list, draft });
+  for (const doc of result.docs)
+    await cacheDoc(doc, collection, { draft });
+  return {
+    docs: result.docs,
+    totalDocs: result.totalDocs,
+    totalPages: result.totalPages,
+    page: result.page ?? 1
+  };
+}
 async function queryDoc(args) {
   if ("globalSlug" in args)
     return queryGlobal(args);
@@ -322,7 +345,7 @@ async function queryDocByID(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
 }
 
@@ -398,7 +421,8 @@ function createCollectionPageExports({
   _payloadConfig,
   importMap,
   routing,
-  slugShape = "single"
+  slugShape = "single",
+  depth = RENDER_DEPTH
 }, {
   getServerSideURL,
   pagePathPrefix,
@@ -410,6 +434,7 @@ function createCollectionPageExports({
     return queryDoc({
       slug,
       locale,
+      depth,
       collectionSlug
     });
   }
@@ -535,7 +560,8 @@ async function resolveLocale(props) {
 function createRootLayoutExports({
   _payloadConfig,
   importMap,
-  routing
+  routing,
+  depth = RENDER_DEPTH
 }, {
   providers,
   htmlAttrs,
@@ -553,8 +579,8 @@ function createRootLayoutExports({
       header,
       footer
     ] = await Promise.all([
-      queryDoc({ globalSlug: "header", locale }),
-      queryDoc({ globalSlug: "footer", locale })
+      queryDoc({ globalSlug: "header", locale, depth }),
+      queryDoc({ globalSlug: "footer", locale, depth })
     ]);
     const renderedHeader = renderWWWDataModule(header, { collectionSlug: "header", configPath: "globals", config: _payloadConfig, importMap }, { ...props, locale }), renderedFooter = renderWWWDataModule(footer, { collectionSlug: "footer", configPath: "globals", config: _payloadConfig, importMap }, { ...props, locale });
     const mergedHtmlAttrs = {

package/dist/sitemap.js

@@ -37,7 +37,7 @@ function seedPayloadCache({ config }) {
     return;
   _seedPromise = (async () => {
     const payload = await getPayload({ config: await config });
-    _helpers = createCacheHelpers(payload);
+    _helpers = { ...createCacheHelpers(payload), payload };
   })();
 }
 async function requireCacheHelpers() {
@@ -50,6 +50,7 @@ async function requireCacheHelpers() {
   }
   throw new Error("[payload-www] seedPayloadCache({ config }) must be called before any query getter. " + "Call it from createCollectionPageExports / createRootLayoutExports factory, or in your root layout.");
 }
+var RENDER_DEPTH = 2;
 async function queryDocBySlug(args) {
   "use cache";
   cacheLife("weeks");
@@ -60,7 +61,7 @@ async function queryDocBySlug(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
   const result = await find(args.slug);
   const doc = result ?? (isIndexSlug(args.slug) ? await find(null) : null);
@@ -74,7 +75,7 @@ async function queryGlobal(args) {
     const result = await findGlobal(args.globalSlug, {
       locale: args.locale,
       draft: args.draft ?? false,
-      depth: args.depth
+      depth: args.depth ?? RENDER_DEPTH
     });
     return result ?? null;
   } catch (error) {
@@ -90,9 +91,31 @@ async function queryAllDocs(args) {
   const { ids } = await findIds(collection, { locale: args.locale, pagination: false, overrideAccess: false });
   if (ids.length === 0)
     return [];
-  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false })));
+  const docs = await Promise.all(ids.map((id) => findDocByID(collection, id, { locale: args.locale, overrideAccess: false, depth: 0 })));
   return docs.filter((d) => d !== null);
 }
+async function queryDocs({
+  collectionSlug,
+  list,
+  draft = false,
+  depth = RENDER_DEPTH,
+  ...find
+}) {
+  "use cache";
+  cacheLife("weeks");
+  const { payload, cacheIds, cacheDoc } = await requireCacheHelpers();
+  const collection = collectionSlug;
+  const result = await payload.find({ ...find, collection, draft, depth, overrideAccess: draft });
+  await cacheIds(result, collection, { list, draft });
+  for (const doc of result.docs)
+    await cacheDoc(doc, collection, { draft });
+  return {
+    docs: result.docs,
+    totalDocs: result.totalDocs,
+    totalPages: result.totalPages,
+    page: result.page ?? 1
+  };
+}
 async function queryDoc(args) {
   if ("globalSlug" in args)
     return queryGlobal(args);
@@ -117,7 +140,7 @@ async function queryDocByID(args) {
     locale: args.locale,
     draft: args.draft ?? false,
     overrideAccess: args.draft ?? false,
-    depth: args.depth
+    depth: args.depth ?? RENDER_DEPTH
   });
 }
 
@@ -214,7 +237,8 @@ function createCollectionPageExports({
   _payloadConfig,
   importMap,
   routing,
-  slugShape = "single"
+  slugShape = "single",
+  depth = RENDER_DEPTH
 }, {
   getServerSideURL,
   pagePathPrefix,
@@ -226,6 +250,7 @@ function createCollectionPageExports({
     return queryDoc({
       slug,
       locale,
+      depth,
       collectionSlug
     });
   }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@justanarthur/payload-www",
   "description": "Reusable Payload CMS website template — config builder, collections, globals, blocks, fields, access, hooks, metadata (JSON-LD, hreflang), page renderers, and test helpers.",
-  "version": "2.2.8",
+  "version": "2.3.0",
+  "license": "MIT",
   "type": "module",
   "private": false,
   "files": [