@websolutespa/bom-next 3.0.2 → 4.0.0-next.1

package/src/server/metadata.ts

@@ -1,22 +1,30 @@
 import type { ResolvingMetadata } from 'next';
 import type { CollectionSlug, SanitizedConfig } from 'payload';
-import type { PageParams } from '../types';
+import type { LayoutOption, PageContextOptions, PageParams, PageSelect } from '../types';
 import { createPageContext } from './context';
 
 /**
  * Returns a generateMetadata function for a given page collection slug.
- * Uses bowl's createPageContext (Payload local API) instead of the store abstraction.
+ *
+ * It uses the same defaults as `createPageContext`, so the page read is
+ * memoized and shared with the page component within the same request.
+ * Pass the same options used by the page (depth, select, headers…) to hit that cache.
  */
-export function getMetadata<TSlug extends CollectionSlug>(slug: TSlug, config: Promise<SanitizedConfig>) {
+export function getMetadata<TSlug extends CollectionSlug, TSelect extends PageSelect<TSlug> = undefined>(
+    slug: TSlug,
+    config: Promise<SanitizedConfig>,
+    options?: Omit<PageContextOptions<TSlug, TSelect, LayoutOption>, 'config'>
+) {
     return async function generateMetadata(
         props: Readonly<{ params: Promise<PageParams>; }>,
-        parent: ResolvingMetadata
+        _parent: ResolvingMetadata
     ) {
         const { market, locale, id } = await props.params;
-        const { page } = await createPageContext(market, locale, slug, id, config);
+        const { page } = await createPageContext<TSlug, TSelect, LayoutOption>(market, locale, slug, id, { ...options, config });
+        const doc = page as { title?: string; abstract?: string; meta?: { title?: string; description?: string } } | undefined;
         return {
-            title: page!.meta?.title || page!.title,
-            description: page!.meta?.description || page!.abstract,
+            title: doc?.meta?.title || doc?.title,
+            description: doc?.meta?.description || doc?.abstract,
         };
     };
 }

package/src/server/mixer.ts

@@ -1,11 +1,12 @@
 import { collectRoutes, defaultLocale, defaultMarket, ICategory, ILocale, IMarket, IMedia, IRoute, isDevelopment, isObject } from '@websolutespa/bom-core';
 import type { Config, User } from '@websolutespa/payload-plugin-bowl';
 import { InMemoryCache } from '@websolutespa/payload-plugin-bowl';
+import { draftMode, headers as getHeaders } from 'next/headers';
 import { NextRequest } from 'next/server';
 import { BasePayload, getPayload as getPayload_, SanitizedConfig, TypedFallbackLocale, TypedLocale } from 'payload';
 import { cache } from 'react';
 import { guest } from '../lib/const';
-import type { BaseOptions, IContext, MixerContext, ReadonlyHeaders } from '../types';
+import type { BaseOptions, DraftOption, IContext, MixerContext, ReadOptions, ReadonlyHeaders } from '../types';
 import type { MixerPayload } from './mixer-payload';
 
 // !!! todo check when to use in memory cache
@@ -269,11 +270,28 @@ export async function getMixerContext({
   return context;
 }
 
+/**
+ * Resolves a draft option to a boolean.
+ * `'auto'` reads Next's `draftMode()`; outside a request scope (build, scripts) it resolves to false.
+ */
+export async function resolveDraft(draft: DraftOption = 'auto'): Promise<boolean> {
+  if (typeof draft === 'boolean') {
+    return draft;
+  }
+  try {
+    return (await draftMode()).isEnabled;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Runtime (request-time) payload accessor.
  *
  * By default, operates as the guest user for static generation. For auth:
  * call getHeaders() directly in your page/route/layout, then pass it here.
+ * In draft mode the request headers are read automatically, so drafts are
+ * read as the authenticated user rather than the guest.
  *
  * Example:
  *   const headers = await getHeaders();
@@ -282,13 +300,23 @@ export async function getMixerContext({
 export async function getPayload({
   config,
   headers,
+  draft = false,
 }: {
   config: Promise<SanitizedConfig>;
   headers?: ReadonlyHeaders;
+  draft?: boolean;
 }) {
   const payload = await getPayload_({ config });
   await setContext({ payload: payload as MixerPayload });
 
+  if (!headers && draft) {
+    try {
+      headers = await getHeaders() as ReadonlyHeaders;
+    } catch {
+      // outside a request scope: keep the guest user
+    }
+  }
+
   let user: User & Config['user'] = guest;
   if (headers) {
     try {
@@ -296,17 +324,15 @@ export async function getPayload({
       if (auth.user) {
         user = auth.user as typeof user;
       }
-      // console.log('getPayload', user, token);
     } catch (error) {
       console.log('getPayload.error', error);
     }
   }
 
-  const draft = false;
-
   return {
     payload: payload as MixerPayload,
     user,
+    draft,
     getContext: (market: string, locale: string) => getMixerContext({ payload, market, locale, user, draft }),
   };
 }
@@ -326,21 +352,43 @@ export function getAuthHeaders(token: { value: string } | undefined): Headers {
 }
 
 /**
- * Produces the common option block shared across all payload.find / payload.findGlobal calls.
+ * Produces the read options shared across payload.find / findByID / findGlobal calls.
  * For payload.find, add pagination: false and limit: 10000 at the call site.
- * For payload.findByID, spread directly — extra find-only fields are ignored.
+ * `select`, `populate` and `joins` are only included when provided.
  */
-export function buildBaseOptions(user: any, locale: string, draft?: boolean) {
+export function buildReadOptions({
+  user,
+  locale,
+  draft = false,
+  depth,
+  select,
+  populate,
+  joins,
+}: ReadOptions & {
+  user: any;
+  locale: string;
+}) {
   return {
     locale: locale as TypedLocale,
     fallbackLocale: defaultLocale as TypedFallbackLocale,
-    draft: draft ?? false,
-    depth: 0,
+    draft,
+    depth,
     user,
     overrideAccess: false,
+    ...(select !== undefined ? { select } : {}),
+    ...(populate !== undefined ? { populate } : {}),
+    // joins are collection specific: typed by the caller's options, untyped here
+    ...(joins !== undefined ? { joins } as {} : {}),
   };
 }
 
+/**
+ * @deprecated Use `buildReadOptions({ user, locale, draft, depth })`.
+ * Kept for backward compatibility: reads at depth 0.
+ */
+export function buildBaseOptions(user: any, locale: string, draft?: boolean) {
+  return buildReadOptions({ user, locale, draft, depth: 0 });
+}
 
 /**
  * Payload proxy example

package/src/server/page.ts

@@ -1,13 +1,50 @@
-'use server';
+import 'server-only';
 
 import { getCategorySegments, ICategorized, ICategory, IRoute, IRouteLink } from '@websolutespa/bom-core';
 import type { User } from '@websolutespa/payload-plugin-bowl';
-import type { CollectionSlug } from 'payload';
+import type { CollectionSlug, SelectType } from 'payload';
 import { buildBreadcrumb } from '../lib/breadcrumb';
-import type { MixerContext, TypedPage } from '../types';
-import { buildBaseOptions } from './mixer';
+import type { MixerContext, PageEnvelopeField, PageSelect, ReadOptions, TypedPage } from '../types';
+import { buildReadOptions } from './mixer';
 import type { MixerPayload } from './mixer-payload';
 
+/**
+ * Fields `getPage` needs to build the envelope (href, alternates, breadcrumb,
+ * segments) and that templates rely on (meta, template). They are always
+ * kept, whatever `select` the caller passes.
+ */
+export const PAGE_ENVELOPE_FIELDS = ['id', 'slug', 'title', 'category', 'markets', 'meta', 'template'] as const satisfies readonly PageEnvelopeField[];
+
+function isExcludeSelect(select: SelectType): boolean {
+  return Object.values(select).some(value =>
+    value === false || (typeof value === 'object' && value !== null && isExcludeSelect(value as SelectType))
+  );
+}
+
+/**
+ * Merges the envelope fields into a Payload select.
+ * - include mode (`true` values): envelope keys are added.
+ * - exclude mode (`false` values): envelope keys are removed from the exclusion list.
+ */
+export function withEnvelopeSelect<T extends SelectType | undefined>(select: T): T {
+  if (!select || Object.keys(select).length === 0) {
+    return select;
+  }
+  const merged: Record<string, unknown> = { ...select };
+  if (isExcludeSelect(select)) {
+    for (const key of PAGE_ENVELOPE_FIELDS) {
+      delete merged[key];
+    }
+  } else {
+    for (const key of PAGE_ENVELOPE_FIELDS) {
+      if (merged[key] === undefined) {
+        merged[key] = true;
+      }
+    }
+  }
+  return merged as T;
+}
+
 /**
  * Fetches a single page document by ID using Payload local API and assembles
  * the IPage envelope (routes, alternates, breadcrumb, parentRoute).
@@ -16,8 +53,12 @@ import type { MixerPayload } from './mixer-payload';
  *   - routes/alternates : mixerContext.routes filtered by schema+id
  *   - segments          : getCategorySegments() from bom-core (pure)
  *   - breadcrumb        : findRouteOfCategory() from bom-core + mixerContext.currentRoutes
+ *
+ * Returns undefined when the document is not found; any other error is logged and rethrown.
+ * The last argument accepts read options (depth, draft, select, populate, joins);
+ * a boolean is still accepted as the legacy `draftMode` flag (depth 0).
  */
-export async function getPage<TSlug extends CollectionSlug>(
+export async function getPage<TSlug extends CollectionSlug, TSelect extends PageSelect<TSlug> = undefined>(
   slug: TSlug,
   id: string,
   market: string,
@@ -25,19 +66,22 @@ export async function getPage<TSlug extends CollectionSlug>(
   payload: MixerPayload,
   user: User,
   mixerContext: MixerContext,
-  draftMode?: boolean
-): Promise<TypedPage<TSlug> | undefined> {
+  readOptions?: ReadOptions | boolean
+): Promise<TypedPage<TSlug, TSelect> | undefined> {
+  const options: ReadOptions = typeof readOptions === 'object'
+    ? readOptions
+    : { draft: readOptions, depth: 0 };
+  const read = buildReadOptions({
+    ...options,
+    select: withEnvelopeSelect(options.select),
+    user,
+    locale,
+  });
   try {
-    const base = buildBaseOptions(user, locale, draftMode);
     const page = await payload.findByID({
+      ...read,
       collection: slug,
       id,
-      locale: base.locale,
-      fallbackLocale: base.fallbackLocale,
-      draft: base.draft,
-      depth: base.depth,
-      user: base.user,
-      overrideAccess: base.overrideAccess,
       disableErrors: true,
       context: mixerContext,
     });
@@ -69,13 +113,14 @@ export async function getPage<TSlug extends CollectionSlug>(
         alternates,
         breadcrumb,
         parentRoute,
-      } as unknown as TypedPage<TSlug>;
+      } as unknown as TypedPage<TSlug, TSelect>;
     } else {
       console.log('PageService.getPage.notfound', slug, id, locale);
       return undefined;
     }
-  } catch {
-    return undefined;
+  } catch (error) {
+    console.error('PageService.getPage.error', slug, id, locale, error);
+    throw error;
   }
 }
 

package/src/types.ts

@@ -1,7 +1,7 @@
 import type { ICategorized, IComponent, ILayout, ILocale, IMarket, IPage, IPrettify, IRoute, PageProps } from '@websolutespa/bom-core';
 import type { Category, EndUser, User } from '@websolutespa/payload-plugin-bowl';
 import type { DynamicOptions, Loader } from 'next/dynamic';
-import type { BasePayload, CollectionSlug, DataFromCollectionSlug, SanitizedConfig, TypedFallbackLocale, TypedLocale } from 'payload';
+import type { BasePayload, CollectionSlug, DataFromCollectionSlug, JoinQuery, PopulateType, SanitizedConfig, SelectType, TransformCollectionWithSelect, TypedCollectionSelect, TypedFallbackLocale, TypedLocale } from 'payload';
 import type { ComponentType, ReactNode } from 'react';
 import type { BowlDecorator, MixerPayload } from './server/mixer-payload';
 
@@ -114,14 +114,116 @@ export type IContext = {
   context: MixerContext;
 }
 
-export type PageDocument<TSlug extends CollectionSlug> = DataFromCollectionSlug<TSlug>;
+/** `true` / `false` forces draft mode, `'auto'` reads Next's `draftMode()`. */
+export type DraftOption = boolean | 'auto';
+
+/** Select accepted for a page collection, or `undefined` for the full document. */
+export type PageSelect<TSlug extends CollectionSlug> = TypedCollectionSelect[TSlug] | undefined;
+
+/**
+ * A generated page collection document, narrowed by `select` when one is given.
+ * Without a select the full generated document type is returned.
+ */
+export type PageDocument<
+  TSlug extends CollectionSlug,
+  TSelect = undefined,
+> = TSelect extends SelectType ? TransformCollectionWithSelect<TSlug, TSelect> : DataFromCollectionSlug<TSlug>;
+
+/** Fields always read by `createPageContext`, whatever `select` is passed (see PAGE_ENVELOPE_FIELDS). */
+export type PageEnvelopeField = 'id' | 'slug' | 'title' | 'category' | 'markets' | 'meta' | 'template';
+
+type SelectInclude = { [key: string]: SelectInclude | true };
+
+/** Type counterpart of `withEnvelopeSelect`: the envelope fields are always part of the result. */
+export type WithEnvelopeSelect<TSelect> = TSelect extends SelectInclude
+  ? TSelect & { [K in PageEnvelopeField]: true }
+  : Omit<TSelect, PageEnvelopeField>;
+
+/** Envelope added by `getPage` to every page document. */
+export type PageEnvelope = Pick<IPage, 'schema' | 'alternates' | 'breadcrumb' | 'href' | 'parentRoute'>;
+
+/**
+ * A generated page collection document enriched with Bowl's page envelope.
+ * With a `select`, only the selected fields (plus the envelope fields) are typed.
+ */
+export type TypedPage<
+  TSlug extends CollectionSlug,
+  TSelect extends PageSelect<TSlug> = undefined,
+> = [TSelect] extends [SelectType]
+  ? BowlDecorator<PageDocument<TSlug, WithEnvelopeSelect<TSelect>>> & PageEnvelope
+  : BowlDecorator<PageDocument<TSlug>> & IPage<ICategorized>;
+
+/**
+ * Narrows relationship / upload fields that are known to be populated
+ * (depth >= 1) from `string | T` (or `number | T`) to `T`.
+ *
+ * @example
+ * const media = page.media as Populated<typeof page.media>;
+ */
+export type Populated<T> = T extends readonly (infer TItem)[]
+  ? Populated<TItem>[]
+  : Exclude<T, string | number>;
+
+/** Options for the layout fetch (`createLayoutContext`, or `layout` in `createPageContext`). */
+export type LayoutOptions = {
+  /** Population depth for app, menus, labels, markets. Default `DEFAULT_LAYOUT_DEPTH` (1: app logo, menu media). */
+  depth?: number;
+  /** Default: the page draft option, or `'auto'` for `createLayoutContext`. */
+  draft?: DraftOption;
+};
+
+/** The `layout` option of `createPageContext`: layout options, or `false` to skip the layout. */
+export type LayoutOption = LayoutOptions | false;
+
+/** `ILayout`, or `undefined` when the layout option is `false`. */
+export type LayoutFor<TLayout extends LayoutOption> = TLayout extends false ? undefined : ILayout;
+
+export type LayoutContextOptions = LayoutOptions & {
+  config: Promise<SanitizedConfig>;
+  headers?: ReadonlyHeaders;
+};
 
-/** A generated page collection document enriched with Bowl's page envelope. */
-export type TypedPage<TSlug extends CollectionSlug> = BowlDecorator<PageDocument<TSlug>> & IPage<ICategorized>;
+export type PageContextOptions<
+  TSlug extends CollectionSlug = CollectionSlug,
+  TSelect extends PageSelect<TSlug> = undefined,
+  TLayout extends LayoutOption = LayoutOption,
+> = {
+  config: Promise<SanitizedConfig>;
+  headers?: ReadonlyHeaders;
+  /**
+   * Population depth. Default `DEFAULT_PAGE_DEPTH` (2).
+   * 0 = ids only, 1 = direct relations/uploads (including those inside blocks),
+   * 2 = relations of relations (e.g. card covers).
+   */
+  depth?: number;
+  /** Payload select for the page document. Envelope fields are always merged in. */
+  select?: TSelect;
+  /** Per-collection select applied to populated documents, e.g. `{ media: { url: true } }`. */
+  populate?: PopulateType;
+  joins?: JoinQuery<TSlug> | false;
+  /** `true` / `false`, or `'auto'` to read Next `draftMode()`. Default `'auto'`. */
+  draft?: DraftOption;
+  /** Options for the layout fetch, or `false` to skip loading the layout (`layout` is then `undefined`). */
+  layout?: TLayout;
+};
+
+/** Read options shared by every local API call made for a page or layout. */
+export type ReadOptions = {
+  depth?: number;
+  draft?: boolean;
+  select?: SelectType;
+  populate?: PopulateType;
+  joins?: JoinQuery<any> | false;
+};
 
-export type TypedPageContext<TSlug extends CollectionSlug = CollectionSlug> = {
-  layout: ILayout;
-  page: TypedPage<TSlug> | undefined;
+export type TypedPageContext<
+  TSlug extends CollectionSlug = CollectionSlug,
+  TSelect extends PageSelect<TSlug> = undefined,
+  TLayout extends LayoutOption = LayoutOptions,
+> = {
+  /** `undefined` when the page context was created with `layout: false`. */
+  layout: LayoutFor<TLayout>;
+  page: TypedPage<TSlug, TSelect> | undefined;
   user: IUser | IEndUser | null;
   label: (key: string, params?: Record<string, any>) => string;
   link: (category: string) => string | undefined;