@lupinum/ginko-content 0.4.0-rc.2 → 1.0.0-beta.2

package/README.md

@@ -15,7 +15,7 @@
 </p>
 
 > [!WARNING]
-> Version `0.4.0-rc.2` is a release candidate. Install it from npm's `next`
+> Version `1.0.0-beta.2` is a prerelease. Install it from npm's `next`
 > channel. The stable `0.3` line remains on `latest`.
 
 ## Why use this package?
@@ -40,13 +40,13 @@ output.
 Use the Nuxt CLI:
 
 ```bash
-npx nuxi module add @lupinum/ginko-content@0.4.0-rc.2
+npx nuxi module add @lupinum/ginko-content@1.0.0-beta.2
 ```
 
 Or install and register the module by hand:
 
 ```bash
-pnpm add @lupinum/ginko-content@0.4.0-rc.2
+pnpm add @lupinum/ginko-content@1.0.0-beta.2
 ```
 
 ```ts
@@ -93,9 +93,9 @@ import { pages } from '~~/content.config'
 
 definePageMeta({ key: route => route.path })
 
-const { page } = await useContentPage(pages)
+const { page, status } = await useContentPage(pages)
 
-if (!page.value) {
+if (status.value === 'not-found') {
   throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
 }
 </script>
@@ -111,8 +111,10 @@ if (!page.value) {
 - YAML, JSON, and CSV ingestion.
 - Typed collections and frontmatter.
 - Route-aware pages and server-side queries.
+- Exact filtered counts and server-resolved references.
 - Locale-aware routes and fallback rules.
 - Navigation, search, sitemap, and prerender helpers.
+- Agent-readable Markdown and recoverable Markdown 404s.
 - A provider contract for remote or database-backed sources.
 
 Optional features stay explicit. Install `pagefind`, `katex`, or

package/dist/core/provider-errors.d.ts

@@ -7,4 +7,4 @@ export interface ContentProviderError extends Error {
         code: ContentProviderErrorCode;
     };
 }
-export declare const createContentProviderError: (code: ContentProviderErrorCode, message: string, details?: Record<string, unknown>) => ContentProviderError;
+export declare const createCoreProviderError: (code: ContentProviderErrorCode, message: string, details?: Record<string, unknown>) => ContentProviderError;

package/dist/core/provider-errors.js

@@ -19,7 +19,7 @@ export const statusForProviderError = {
   unsupported_provider_prerender: 400,
   unsupported_filesystem_preview: 400
 };
-export const createContentProviderError = (code, message, details = {}) => Object.assign(new Error(message), {
+export const createCoreProviderError = (code, message, details = {}) => Object.assign(new Error(message), {
   statusCode: statusForProviderError[code],
   statusMessage: code,
   data: {

package/dist/core/query/execute.js

@@ -1,8 +1,8 @@
 import { isPlanRegex } from "./plan.js";
 import { resolveLocaleChain, sortLocalesCanonically } from "../content/locale.js";
 import { getGraphCanonicalVariants, resolveGraphCanonicalKey, resolveGraphRouteVariant, resolveGraphVariant, selectGraphDocuments } from "../content/graph.js";
-import { ensureArray, get, sortList, withKeys, withoutKeys } from "./operators.js";
-import { createContentProviderError } from "../provider-errors.js";
+import { ensureArray, get, projectDocumentFields, sortList } from "./operators.js";
+import { createCoreProviderError } from "../provider-errors.js";
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const reviveRegex = (value) => isPlanRegex(value) ? new RegExp(value.source, value.flags) : value;
 const includesEntry = (haystack, entry) => typeof haystack === "string" ? isPlanRegex(entry) ? reviveRegex(entry).test(haystack) : haystack.includes(String(entry)) : haystack.some((value) => compareOperators.eq(value, entry));
@@ -114,10 +114,10 @@ const applyQueryPlanSort = (matched, plan) => {
   }
 };
 export const applyQueryPlanProjection = (items, plan) => {
-  return items.map((item) => {
-    const without = withoutKeys([...plan.projection.without])(item);
-    return withKeys([...plan.projection.only])(without);
-  });
+  return items.map((item) => projectDocumentFields(
+    item,
+    plan.projection
+  ));
 };
 const FILESYSTEM_CURSOR_PREFIX = "o:";
 const encodeFilesystemCursor = (offset) => {
@@ -125,7 +125,7 @@ const encodeFilesystemCursor = (offset) => {
   return typeof Buffer !== "undefined" ? Buffer.from(raw).toString("base64") : btoa(raw);
 };
 const invalidFilesystemCursor = () => {
-  throw createContentProviderError(
+  throw createCoreProviderError(
     "unsupported_query_shape",
     "The filesystem provider received an invalid cursor.",
     { provider: "filesystem", field: "paging.after" }

package/dist/core/query/filter.d.ts

@@ -38,4 +38,5 @@ export declare const compileQueryParams: (input: {
     locale?: string;
     fallback?: LocaleFallback;
     exact?: boolean;
+    count?: boolean;
 }) => ContentProviderQueryInput;

package/dist/core/query/filter.js

@@ -166,6 +166,9 @@ export const compileQueryParams = (input) => {
   if (input.exact !== void 0 && typeof input.exact !== "boolean") {
     throw new TypeError("Invalid content query exact option: expected a boolean.");
   }
+  if (input.count !== void 0 && typeof input.count !== "boolean") {
+    throw new TypeError("Invalid content query count option: expected a boolean.");
+  }
   const selector = compileSelector(input.by);
   const path = selector && "path" in selector ? selector.path : void 0;
   const route = selector && "route" in selector ? selector.route : void 0;
@@ -180,7 +183,8 @@ export const compileQueryParams = (input) => {
     ...sort ? { sort } : {},
     ...input.limit !== void 0 ? { limit: input.limit } : {},
     ...input.skip !== void 0 ? { skip: input.skip } : {},
-    ...select ? { only: select } : {}
+    ...select ? { only: select } : {},
+    ...input.count ? { count: true } : {}
   };
   if (input.locale || path || route || ref || fallback !== void 0) {
     const exact = input.exact ?? (input.locale ? fallback === void 0 || fallback === false : false);

package/dist/core/query/operators.d.ts

@@ -14,6 +14,12 @@ export declare const withoutKeys: (keys?: string[]) => <T extends Record<string,
 export declare const withKeys: (keys?: string[]) => <T extends Record<string, unknown>>(obj: T | undefined) => {
     [k: string]: unknown;
 } | undefined;
+export interface DocumentProjection {
+    only?: readonly string[];
+    without?: readonly string[];
+}
+/** Apply the shared document field-selection rules at every query boundary. */
+export declare const projectDocumentFields: <T extends Record<string, unknown>>(document: T, projection: DocumentProjection, guaranteed?: readonly string[]) => T;
 export declare const sortList: <T extends Record<string, unknown>>(data: T[], params: ContentQuerySortOptions) => T[];
 /**
  * Ensure result is an array

package/dist/core/query/operators.js

@@ -37,6 +37,19 @@ export const withKeys = (keys = []) => (obj) => {
   const { prefixes, properties } = detectProperties(keys);
   return pickObject(obj, (key) => properties.includes(key) || prefixes.includes(key.charAt(0)));
 };
+export const projectDocumentFields = (document, projection, guaranteed = []) => {
+  const selected = projection.only ?? [];
+  const excluded = projection.without ?? [];
+  if (selected.length === 0 && excluded.length === 0) return document;
+  const stripped = excluded.length > 0 ? withoutKeys([...excluded])(document) : document;
+  if (selected.length === 0) return stripped;
+  const projected = withKeys([...selected])(stripped);
+  if (guaranteed.length === 0) return projected;
+  return {
+    ...projected,
+    ...withKeys([...guaranteed])(document)
+  };
+};
 export const sortList = (data, params) => {
   const sortParams = params;
   const comperable = new Intl.Collator(sortParams.$locale, {

package/dist/core/visibility.js

@@ -1,4 +1,4 @@
-import { createContentProviderError } from "./provider-errors.js";
+import { createCoreProviderError } from "./provider-errors.js";
 export const resolveRuntimeEnvironment = () => import.meta.dev ? "development" : "production";
 export const resolveIncludeDrafts = (context) => {
   if (typeof context.includeDrafts === "boolean") {
@@ -9,7 +9,7 @@ export const resolveIncludeDrafts = (context) => {
 export const isPublicationVisible = (facts, context) => !facts.draft || resolveIncludeDrafts(context);
 export const assertFilesystemPreviewSupported = (context) => {
   if (context.environment === "production" && context.previewAuthorized) {
-    throw createContentProviderError(
+    throw createCoreProviderError(
       "unsupported_filesystem_preview",
       "Production preview requires a content provider. The filesystem provider serves an immutable sealed snapshot in production and cannot overlay draft/preview content \u2014 configure a provider-owned preview workflow, or disable preview for filesystem production deployments.",
       { provider: "filesystem" }

package/dist/features/agent/agent-markdown.d.ts

@@ -20,6 +20,7 @@ export interface AgentMarkdown {
     description: string;
     markdown: string;
     sourceFile?: string;
+    order?: number;
     canonicalUrl: string;
     lastModified?: string;
     publicSignals?: AgentMarkdownPublicSignals;

package/dist/features/agent/walker.js

@@ -21,6 +21,12 @@ const renderChildren = (node, ctx) => (node.children || []).map((child) => rende
 const block = (value) => value.trim() ? `${value.trim()}
 
 ` : "";
+const codeFenceInfo = (node) => {
+  const language = typeof node.props?.language === "string" ? node.props.language.replace(/[\r\n]/g, " ").trim() : "";
+  const filename = typeof node.props?.filename === "string" ? node.props.filename.replace(/[\r\n]/g, " ").trim() : "";
+  const escapedFilename = filename.replace(/\\/g, "\\\\").replace(/\]/g, "\\]");
+  return `${language}${escapedFilename ? ` [${escapedFilename}]` : ""}`;
+};
 const renderList = (node, ctx, ordered = false) => block((node.children || []).map((child, index) => {
   const [first, ...rest] = child.children || [];
   let task = "";
@@ -136,7 +142,7 @@ const renderNode = (node, ctx) => {
     case "code":
       return `\`${node.value || textValue(node)}\``;
     case "pre":
-      return block(`\`\`\`
+      return block(`\`\`\`${codeFenceInfo(node)}
 ${textValue(node)}
 \`\`\``);
     case "a": {

package/dist/features/collections/resolve.d.ts

@@ -1,5 +1,4 @@
-import type { ParsedContent } from '../../types/content';
-import { type GenerateSearchSectionsOptions } from '../search/sections';
+import { type GenerateSearchSectionsOptions, type SearchablePage } from '../search/sections';
 import type { RuntimeContentI18nInput } from '../localization/config';
 type CollectionResolveRuntime = RuntimeContentI18nInput;
 export declare const resolveCollectionItemSurroundingsData: (collection: string, path: string, runtime: CollectionResolveRuntime, options: {
@@ -17,7 +16,7 @@ export declare const resolveCollectionSearchSectionsData: (collection: string, r
     locale?: string;
     activeLocale?: string;
 }) & {
-    loadPages: (extraFields: string[]) => Promise<Array<Pick<ParsedContent, "path" | "title" | "description" | "body"> & Record<string, unknown>>>;
+    loadPages: (extraFields: string[]) => Promise<SearchablePage[]>;
 }) => Promise<{
     id: string;
     title: string;

package/dist/features/query/context.d.ts

@@ -1,6 +1,6 @@
 import type { NavItem } from '../../types/content';
 import type { ContentPublicQueryResponse } from '../../types/api';
-import type { ContentProviderQueryInput } from '../../types/query';
+import type { ContentQueryTransportInput } from '../../types/query';
 import type { ResolvedCollectionLocalePolicy } from '../localization/locale-policy';
 export interface RuntimeContentConfig {
     locales?: string[];
@@ -17,6 +17,11 @@ export interface RuntimeContentConfig {
     }>;
 }
 export type ContentQueryEndpoint = 'query' | 'navigation';
+/**
+ * Internal execution context created only by Ginko's client and server
+ * adapters. Query transports must consume orchestration fields such as
+ * `populate` and return the fully resolved public response envelope.
+ */
 export interface ContentQueryContext {
     runtime: RuntimeContentConfig;
     /** Optional direct provider operation used by server-side `surround()`. */
@@ -26,5 +31,6 @@ export interface ContentQueryContext {
         fallback?: boolean | readonly string[];
         select?: readonly string[];
     }) => Promise<Array<NavItem | null>>;
-    transport: <T>(endpoint: ContentQueryEndpoint, params: ContentProviderQueryInput) => Promise<ContentPublicQueryResponse<T> | NavItem[]>;
+    /** Execute the complete public query contract, including population. */
+    transport: <T>(endpoint: ContentQueryEndpoint, params: ContentQueryTransportInput) => Promise<ContentPublicQueryResponse<T> | NavItem[]>;
 }

package/dist/features/query/documents.d.ts

@@ -1,6 +1,7 @@
 import type { ContentCollectionHandle } from '../../types/config';
-import type { DocumentFromHandle, LocalizedDoc, ManyOptions, OneOptions, PopulateFromOptions, PopulateSpec, PopulatedDocument, ResolveOneOptions, ResolveOneResult } from '../../types/query';
+import type { CountOptions, DocumentFromHandle, LocalizedDoc, ManyOptions, OneOptions, PopulateFromOptions, PopulateSpec, PopulatedDocument, ResolveOneOptions, ResolveOneResult } from '../../types/query';
 import type { ContentQueryContext } from './context';
-export declare function resolveDocument<const H extends ContentCollectionHandle | string, O extends ResolveOneOptions<H, PopulateSpec | undefined>>(context: ContentQueryContext, one: typeof resolveDocumentOnly, handle: H, options: O): Promise<ResolveOneResult<PopulatedDocument<DocumentFromHandle<H>, PopulateFromOptions<O>>>>;
+export declare function resolveDocument<const H extends ContentCollectionHandle | string, O extends ResolveOneOptions<H, PopulateSpec | undefined>>(context: ContentQueryContext, handle: H, options: O): Promise<ResolveOneResult<PopulatedDocument<DocumentFromHandle<H>, PopulateFromOptions<O>>>>;
 export declare function resolveDocumentOnly<const H extends ContentCollectionHandle | string, O extends OneOptions<H, PopulateSpec | undefined>>(context: ContentQueryContext, handle: H, options: O): Promise<LocalizedDoc<PopulatedDocument<DocumentFromHandle<H>, PopulateFromOptions<O>>> | null>;
-export declare function resolveManyDocuments<const H extends ContentCollectionHandle | string, O extends ManyOptions<H, PopulateSpec | undefined>>(context: ContentQueryContext, one: typeof resolveDocumentOnly, handle: H, options?: O): Promise<Array<LocalizedDoc<PopulatedDocument<DocumentFromHandle<H>, PopulateFromOptions<O>>>>>;
+export declare function resolveManyDocuments<const H extends ContentCollectionHandle | string, O extends ManyOptions<H, PopulateSpec | undefined>>(context: ContentQueryContext, handle: H, options?: O): Promise<Array<LocalizedDoc<PopulatedDocument<DocumentFromHandle<H>, PopulateFromOptions<O>>>>>;
+export declare function resolveCount<const H extends ContentCollectionHandle | string, O extends CountOptions<H>>(context: ContentQueryContext, handle: H, options?: O): Promise<number>;

package/dist/features/query/documents.js

@@ -1,9 +1,9 @@
 import { compileQueryParams } from "../../core/query/filter.js";
-import { isNotFoundError } from "./errors.js";
+import { withNotFoundFallback } from "./errors.js";
 import { ensureCollectionName } from "./handles.js";
 import { resolveFallback } from "./locale-options.js";
-import { populateDocument, populateDocuments, selectWithPopulate, validatePopulateSpec } from "./populate.js";
-import { unwrapListResponse, unwrapOneResponse } from "./responses.js";
+import { selectWithPopulate, serializePopulateSpec, validatePopulateSpec } from "./populate.js";
+import { unwrapCountResponse, unwrapFindResponse, unwrapOneResponse } from "./responses.js";
 const explainResolution = (collection, requestedBy, normalizedBy, requestedLocale, requestedFallback, doc) => {
   const resolvedLocale = doc?.resolution?.resolved?.locale || doc?.locale;
   return {
@@ -29,65 +29,81 @@ const explainResolution = (collection, requestedBy, normalizedBy, requestedLocal
     }
   };
 };
-export async function resolveDocument(context, one, handle, options) {
+export async function resolveDocument(context, handle, options) {
   const collection = ensureCollectionName(handle);
   const runtime = context.runtime;
   validatePopulateSpec(handle, collection, runtime, options.populate);
   const by = options.by;
   const fallback = resolveFallback(options.fallback, collection, runtime);
-  const params = compileQueryParams({
-    collection,
-    by,
-    locale: options.locale,
-    fallback,
-    select: selectWithPopulate(options.select, options.populate)
-  });
+  const params = {
+    ...compileQueryParams({
+      collection,
+      by,
+      locale: options.locale,
+      fallback,
+      select: selectWithPopulate(options.select, options.populate)
+    }),
+    ...options.populate ? { populate: serializePopulateSpec(options.populate) } : {}
+  };
   params.first = true;
-  let response;
-  try {
-    response = await context.transport("query", params);
-  } catch (error) {
-    if (isNotFoundError(error)) {
-      const explain2 = explainResolution(collection, options.by, by, options.locale, options.fallback, null);
-      return { doc: null, explain: explain2 };
-    }
-    throw error;
-  }
+  const response = await withNotFoundFallback(
+    () => context.transport("query", params),
+    { result: null }
+  );
   const doc = unwrapOneResponse(response);
-  const populated = doc ? await populateDocument(context, one, doc, options.populate, options.locale, options.fallback) : null;
   const explain = explainResolution(collection, options.by, by, options.locale, options.fallback, doc);
   return {
-    doc: populated,
+    doc,
     explain
   };
 }
 export async function resolveDocumentOnly(context, handle, options) {
-  const result = await resolveDocument(context, resolveDocumentOnly, handle, options);
+  const result = await resolveDocument(context, handle, options);
   return result.doc;
 }
-export async function resolveManyDocuments(context, one, handle, options = {}) {
+export async function resolveManyDocuments(context, handle, options = {}) {
   const collection = ensureCollectionName(handle);
   const runtime = context.runtime;
   validatePopulateSpec(handle, collection, runtime, options.populate);
   const fallback = resolveFallback(options.fallback, collection, runtime);
+  const params = {
+    ...compileQueryParams({
+      collection,
+      where: options.where,
+      sort: options.sort,
+      limit: options.limit,
+      skip: options.skip,
+      locale: options.locale,
+      fallback,
+      select: selectWithPopulate(options.select, options.populate)
+    }),
+    ...options.populate ? { populate: serializePopulateSpec(options.populate) } : {}
+  };
+  const response = await withNotFoundFallback(
+    () => context.transport("query", params),
+    { result: [], skip: 0, limit: 0, total: 0 }
+  );
+  const find = unwrapFindResponse(response);
+  const docs = find.result;
+  if (import.meta.dev && options.limit === void 0 && find.total > docs.length) {
+    console.warn(
+      `[ginko-content] many("${collection}") matched ${find.total} documents but returned ${docs.length}. Pass an explicit limit or use paginate() to read the rest.`
+    );
+  }
+  return docs;
+}
+export async function resolveCount(context, handle, options = {}) {
+  const collection = ensureCollectionName(handle);
+  const fallback = resolveFallback(options.fallback, collection, context.runtime);
   const params = compileQueryParams({
     collection,
     where: options.where,
-    sort: options.sort,
-    limit: options.limit,
-    skip: options.skip,
     locale: options.locale,
     fallback,
-    select: selectWithPopulate(options.select, options.populate)
+    count: true
   });
-  let response;
-  try {
-    response = await context.transport("query", params);
-  } catch (error) {
-    if (isNotFoundError(error)) return [];
-    throw error;
-  }
-  const docs = unwrapListResponse(response);
-  const populated = await populateDocuments(context, one, docs, options.populate, options.locale, options.fallback);
-  return populated;
+  return unwrapCountResponse(await withNotFoundFallback(
+    () => context.transport("query", params),
+    { result: 0 }
+  ));
 }

package/dist/features/query/errors.d.ts

@@ -1 +1,3 @@
 export declare const isNotFoundError: (error: unknown) => boolean;
+/** Apply the public query API's one shared rule for missing collections. */
+export declare const withNotFoundFallback: <T>(request: () => Promise<T>, fallback: T) => Promise<T>;

package/dist/features/query/errors.js

@@ -2,3 +2,11 @@ export const isNotFoundError = (error) => {
   const statusCode = error?.statusCode ?? error?.response?.status;
   return statusCode === 404;
 };
+export const withNotFoundFallback = async (request, fallback) => {
+  try {
+    return await request();
+  } catch (error) {
+    if (isNotFoundError(error)) return fallback;
+    throw error;
+  }
+};

package/dist/features/query/navigation.js

@@ -1,6 +1,7 @@
 import { compileQueryParams } from "../../core/query/filter.js";
 import { NAVIGATION_REQUIRED_FIELDS } from "../../types/navigation.js";
 import { ensureCollectionName } from "./handles.js";
+import { withNotFoundFallback } from "./errors.js";
 import { isCollectionRouteRoot, isNavigationRootPath } from "./localized-docs.js";
 import { resolveFallback } from "./locale-options.js";
 export const navigationSelectFields = (fields = []) => [
@@ -19,7 +20,10 @@ export async function resolveNavigation(context, handle, options = {}) {
     select: navigationSelectFields(options.select),
     exact: options.fallback === void 0 ? false : void 0
   });
-  const response = await context.transport("navigation", params);
+  const response = await withNotFoundFallback(
+    () => context.transport("navigation", params),
+    []
+  );
   const list = Array.isArray(response) ? response : Array.isArray(response?.result) ? response.result : [];
   return list;
 }

package/dist/features/query/pagination.d.ts

@@ -1,13 +1,10 @@
-import type { ParsedContent } from '../../types/content';
 import type { ContentCollectionHandle } from '../../types/config';
-import type { DocumentFromHandle, LocalizedDoc, OneOptions, PaginationOptions, PaginationResult, PopulateFromOptions, PopulateSpec, PopulatedDocument } from '../../types/query';
+import type { DocumentFromHandle, PaginationOptions, PaginationResult, PopulateFromOptions, PopulateSpec, PopulatedDocument } from '../../types/query';
 import type { ContentQueryContext } from './context';
-type OneResolver = <H extends ContentCollectionHandle | string>(context: ContentQueryContext, handle: H, options: OneOptions<H>) => Promise<LocalizedDoc<ParsedContent> | null>;
 /**
  * Resolve one honest pagination page. Two discriminated
  * modes: `offset` (exact `total`/`pageCount`) and `cursor` (opaque forward
  * cursor, no synthetic total). Omitting `mode` while supplying `page` means
  * `mode: 'offset'` — the source-compatible default.
  */
-export declare function resolvePagination<const H extends ContentCollectionHandle | string, O extends PaginationOptions<H, PopulateSpec | undefined>>(context: ContentQueryContext, one: OneResolver, handle: H, options: O): Promise<PaginationResult<PopulatedDocument<DocumentFromHandle<H>, PopulateFromOptions<O>>>>;
-export {};
+export declare function resolvePagination<const H extends ContentCollectionHandle | string, O extends PaginationOptions<H, PopulateSpec | undefined>>(context: ContentQueryContext, handle: H, options: O): Promise<PaginationResult<PopulatedDocument<DocumentFromHandle<H>, PopulateFromOptions<O>>>>;

package/dist/features/query/pagination.js

@@ -1,7 +1,7 @@
 import { compileQueryParams } from "../../core/query/filter.js";
 import { ensureCollectionName } from "./handles.js";
 import { resolveFallback } from "./locale-options.js";
-import { populateDocuments, selectWithPopulate, validatePopulateSpec } from "./populate.js";
+import { selectWithPopulate, serializePopulateSpec, validatePopulateSpec } from "./populate.js";
 import {
   assertPublicPagingLimit,
   DEFAULT_PUBLIC_PAGINATION_LIMIT,
@@ -9,7 +9,7 @@ import {
   MAX_PUBLIC_QUERY_SKIP
 } from "../../core/query/limits.js";
 import { unwrapCursorFindResponse, unwrapFindResponse } from "./responses.js";
-import { isNotFoundError } from "./errors.js";
+import { withNotFoundFallback } from "./errors.js";
 const resolvePage = (value) => {
   if (value === void 0) return 1;
   if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
@@ -17,26 +17,7 @@ const resolvePage = (value) => {
   }
   return value;
 };
-const emptyOffsetPage = (page, limit) => ({
-  mode: "offset",
-  data: [],
-  page,
-  limit,
-  total: 0,
-  pageCount: 0,
-  hasNext: false,
-  hasPrevious: page > 1,
-  nextPage: null,
-  previousPage: page > 1 ? page - 1 : null
-});
-const emptyCursorPage = (limit) => ({
-  mode: "cursor",
-  data: [],
-  limit,
-  endCursor: null,
-  hasNext: false
-});
-export async function resolvePagination(context, one, handle, options) {
+export async function resolvePagination(context, handle, options) {
   const collection = ensureCollectionName(handle);
   const runtime = context.runtime;
   validatePopulateSpec(handle, collection, runtime, options.populate);
@@ -54,6 +35,17 @@ export async function resolvePagination(context, one, handle, options) {
   const limit = options.limit ?? DEFAULT_PUBLIC_PAGINATION_LIMIT;
   assertPublicPagingLimit(limit);
   const select = selectWithPopulate(options.select, options.populate);
+  const baseParams = {
+    ...compileQueryParams({
+      collection,
+      where: options.where,
+      sort: options.sort,
+      locale: options.locale,
+      fallback,
+      select
+    }),
+    ...options.populate ? { populate: serializePopulateSpec(options.populate) } : {}
+  };
   if (mode === "cursor") {
     if (options.after !== void 0 && options.after !== null) {
       if (typeof options.after !== "string") {
@@ -63,29 +55,18 @@ export async function resolvePagination(context, one, handle, options) {
         throw new TypeError(`Content pagination cursor exceeds ${MAX_PUBLIC_QUERY_CURSOR_BYTES} bytes.`);
       }
     }
-    const params2 = compileQueryParams({
-      collection,
-      where: options.where,
-      sort: options.sort,
-      locale: options.locale,
-      fallback,
-      select
-    });
-    params2.paging = { mode: "cursor", after: options.after ?? null, limit };
-    let response2;
-    try {
-      response2 = await context.transport("query", params2);
-    } catch (error) {
-      if (isNotFoundError(error)) {
-        return emptyCursorPage(limit);
-      }
-      throw error;
-    }
+    const params2 = {
+      ...baseParams,
+      paging: { mode: "cursor", after: options.after ?? null, limit }
+    };
+    const response2 = await withNotFoundFallback(
+      () => context.transport("query", params2),
+      { mode: "cursor", result: [], limit, pageInfo: { endCursor: null, hasNext: false } }
+    );
     const envelope2 = unwrapCursorFindResponse(response2);
-    const populated2 = await populateDocuments(context, one, envelope2.result, options.populate, options.locale, options.fallback);
     return {
       mode: "cursor",
-      data: populated2,
+      data: envelope2.result,
       limit: envelope2.limit,
       endCursor: envelope2.endCursor,
       hasNext: envelope2.hasNext
@@ -96,30 +77,19 @@ export async function resolvePagination(context, one, handle, options) {
   if (!Number.isSafeInteger(skip) || skip > MAX_PUBLIC_QUERY_SKIP) {
     throw new TypeError(`Content pagination page exceeds the maximum query skip of ${MAX_PUBLIC_QUERY_SKIP}.`);
   }
-  const params = compileQueryParams({
-    collection,
-    where: options.where,
-    sort: options.sort,
-    locale: options.locale,
-    fallback,
-    select
-  });
-  params.paging = { mode: "offset", skip, limit };
-  let response;
-  try {
-    response = await context.transport("query", params);
-  } catch (error) {
-    if (isNotFoundError(error)) {
-      return emptyOffsetPage(page, limit);
-    }
-    throw error;
-  }
+  const params = {
+    ...baseParams,
+    paging: { mode: "offset", skip, limit }
+  };
+  const response = await withNotFoundFallback(
+    () => context.transport("query", params),
+    { result: [], skip, limit, total: 0 }
+  );
   const envelope = unwrapFindResponse(response);
-  const populated = await populateDocuments(context, one, envelope.result, options.populate, options.locale, options.fallback);
   const pageCount = envelope.total > 0 ? Math.ceil(envelope.total / limit) : 0;
   return {
     mode: "offset",
-    data: populated,
+    data: envelope.result,
     page,
     limit,
     total: envelope.total,

package/dist/features/query/populate.d.ts

@@ -1,10 +1,12 @@
 import type { ParsedContent } from '../../types/content';
 import type { ContentCollectionHandle } from '../../types/config';
-import type { LocaleFallback, LocalizedDoc, OneOptions, PopulateSpec, PopulatedDocument } from '../../types/query';
+import type { LocaleFallback, LocalizedDoc, OneOptions, ContentQueryTransportInput, PopulateSpec, PopulatedDocument } from '../../types/query';
 import type { ContentQueryContext, RuntimeContentConfig } from './context';
+export declare const serializePopulateSpec: (populate: PopulateSpec | undefined) => Record<string, string> | undefined;
 export declare const validatePopulateSpec: (source: ContentCollectionHandle | string, sourceCollection: string, runtime: RuntimeContentConfig | undefined, populate: PopulateSpec | undefined) => void;
 type PopulateReferenceResolver = (context: ContentQueryContext, target: ContentCollectionHandle | string, options: OneOptions<ContentCollectionHandle | string>) => Promise<unknown>;
 export declare const populateDocuments: <T extends ParsedContent, P extends PopulateSpec | undefined>(context: ContentQueryContext, resolveReference: PopulateReferenceResolver, docs: ReadonlyArray<LocalizedDoc<T>>, populate: P, locale: string | undefined, fallback: LocaleFallback | undefined) => Promise<Array<LocalizedDoc<PopulatedDocument<T, P>>>>;
 export declare const populateDocument: <T extends ParsedContent, P extends PopulateSpec | undefined>(context: ContentQueryContext, resolveReference: PopulateReferenceResolver, doc: LocalizedDoc<T>, populate: P, locale: string | undefined, fallback: LocaleFallback | undefined) => Promise<LocalizedDoc<PopulatedDocument<T, P>>>;
+export declare const populateQueryResponse: (context: ContentQueryContext, resolveReference: PopulateReferenceResolver, response: unknown, params: ContentQueryTransportInput) => Promise<unknown>;
 export declare const selectWithPopulate: (select: ReadonlyArray<string> | undefined, populate: PopulateSpec | undefined) => string[] | undefined;
 export {};