@lupinum/ginko-content 0.3.0 → 0.3.2

package/dist/core/content/graph.d.ts

@@ -18,10 +18,9 @@
  *    page resolver when the request arrives as a localized URL.
  *  - **`byRef`**: normalized ref string → canonical key. This is how
  *    markdown links such as `[Ada]($authors.ada)` find their target without a scan.
- *  - **`referenceTargets`**: the `buildReferenceTargets` map — every shape
- *    the user might plausibly write to point at a document (canonical
- *    name, locale-prefixed path, short slug) pre-resolved to a canonical
- *    key.
+ *  - **`referenceTargets`**: every unambiguous shape the user might write
+ *    (canonical name, locale-prefixed path, short slug) pre-resolved to its
+ *    canonical key and owning collection.
  *
  * The graph is rebuilt from scratch on every request in dev; in production
  * it is memoized per-request via `memoizeRuntimeValue(event, 'graph', ...)`.
@@ -32,6 +31,10 @@ import type { ContentVariantIdentity, ResolvedVariant } from '../../types/runtim
 export interface ContentGraphVariant extends ContentVariantIdentity {
     document: ParsedContent;
 }
+export interface ContentGraphReferenceTarget {
+    readonly canonicalKey: string;
+    readonly collection: string;
+}
 export interface ContentGraph {
     documents: ParsedContent[];
     /** id → document. Keys include the locale suffix; one entry per source file. */
@@ -52,8 +55,8 @@ export interface ContentGraph {
     byRef: Record<string, string>;
     /** navigation path → `{ [locale]: document }`. Drives `.navigation.yml` merging. */
     byNavigationPath: Record<string, Record<string, ParsedContent>>;
-    /** Every user-writable reference shape pre-resolved to a canonical key. */
-    referenceTargets: Map<string, string>;
+    /** Every unambiguous user-writable reference shape with its collection scope intact. */
+    referenceTargets: Map<string, ContentGraphReferenceTarget>;
     /** Exact collection-scoped user-writable reference targets. */
     referenceTargetsByCollection: Record<string, Map<string, string>>;
 }
@@ -134,6 +137,12 @@ export declare const resolveGraphRouteVariant: (graph: ContentGraph, routePath:
  * leak through.
  */
 export declare const resolveGraphCanonicalKey: (graph: ContentGraph, identity: string, collection?: string) => string | null;
+/**
+ * Resolve a user-authored reference without discarding the collection that
+ * made the identity unambiguous. Canonical keys are collection-scoped, so
+ * callers that subsequently resolve a locale variant must carry both values.
+ */
+export declare const resolveGraphReferenceTarget: (graph: ContentGraph, identity: string, collection?: string) => ContentGraphReferenceTarget | null;
 export declare const resolveGraphCollectionLocales: (graph: ContentGraph, identity: string, collection?: string) => ContentLocaleEntry[];
 export declare const selectGraphDocuments: (graph: ContentGraph, options?: {
     collection?: string;

package/dist/core/content/graph.js

@@ -100,7 +100,10 @@ export const buildContentGraph = (documents, options = {}) => {
   }
   const referenceTargets = /* @__PURE__ */ new Map();
   for (const [identity, collections] of referenceTargetCollections) {
-    if (collections.length === 1) referenceTargets.set(identity, referenceTargetsByCollection[collections[0]].get(identity));
+    if (collections.length !== 1) continue;
+    const collection = collections[0];
+    const canonicalKey = referenceTargetsByCollection[collection].get(identity);
+    if (canonicalKey) referenceTargets.set(identity, { canonicalKey, collection });
   }
   return {
     documents,
@@ -180,9 +183,24 @@ export const resolveGraphCanonicalKey = (graph, identity, collection) => {
   if (collection && !(graph.byCollection[collection] || []).length) {
     return null;
   }
-  const targetCanonicalKey = collection ? graph.referenceTargetsByCollection[collection]?.get(normalizedIdentity) : graph.referenceTargets.get(normalizedIdentity);
+  const targetCanonicalKey = collection ? graph.referenceTargetsByCollection[collection]?.get(normalizedIdentity) : graph.referenceTargets.get(normalizedIdentity)?.canonicalKey;
   return targetCanonicalKey && hasCollectionVariant(targetCanonicalKey) ? targetCanonicalKey : null;
 };
+export const resolveGraphReferenceTarget = (graph, identity, collection) => {
+  const normalizedIdentity = normalizeReferenceValue(identity);
+  if (!normalizedIdentity) return null;
+  if (collection) {
+    const canonicalKey = resolveGraphCanonicalKey(graph, normalizedIdentity, collection);
+    return canonicalKey ? { canonicalKey, collection } : null;
+  }
+  const canonicalVariants = graph.byCanonical[normalizedIdentity];
+  if (canonicalVariants) {
+    const targetCollection = Object.values(canonicalVariants)[0]?.document.collection || "content";
+    return { canonicalKey: normalizedIdentity, collection: targetCollection };
+  }
+  const target = graph.referenceTargets.get(normalizedIdentity);
+  return target && getGraphCanonicalVariants(graph, target.canonicalKey, target.collection) ? target : null;
+};
 export const resolveGraphCollectionLocales = (graph, identity, collection) => {
   const canonicalKey = resolveGraphCanonicalKey(graph, identity, collection);
   if (!canonicalKey) {

package/dist/features/validation/links.js

@@ -1,4 +1,4 @@
-import { resolveGraphCanonicalKey } from "../../core/content/graph.js";
+import { getGraphCanonicalVariants, resolveGraphReferenceTarget } from "../../core/content/graph.js";
 import { parseRefLink } from "../../core/references/resolve.js";
 const normalizePath = (path) => {
   const normalized = path.replace(/\/{2,}/g, "/").replace(/\/$/, "");
@@ -98,11 +98,11 @@ export const validateContentLinks = async (documents, options) => {
           }
           continue;
         }
-        const canonicalKey = resolveGraphCanonicalKey(options.graph, parsedRef.ref);
-        const variants = canonicalKey ? options.graph.byCanonical[canonicalKey] : void 0;
+        const target = resolveGraphReferenceTarget(options.graph, parsedRef.ref);
+        const variants = target ? getGraphCanonicalVariants(options.graph, target.canonicalKey, target.collection) : void 0;
         const variant = variants?.[document.locale || ""] || variants?.[options.defaultLocale || ""] || Object.values(variants || {})[0];
         const targetDocument2 = variant ? options.graph.byId[variant.contentId] : void 0;
-        const targetRoute = targetDocument2 ? routeByIdentity.get(identityKey(targetDocument2.collection, canonicalKey || "", variant?.locale)) : void 0;
+        const targetRoute = target && targetDocument2 ? routeByIdentity.get(identityKey(target.collection, target.canonicalKey, variant?.locale)) : void 0;
         if (!targetRoute) {
           addBroken(sourceFile, authoredValue);
           continue;

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "configKey": "content",
   "compatibility": {
     "nuxt": ">=4.4.7 <5"

package/dist/module.mjs

@@ -29,7 +29,7 @@ import { createRouterMatcher } from 'vue-router';
 import { globby } from 'globby';
 
 const name = "@lupinum/ginko-content";
-const version = "0.3.0";
+const version = "0.3.2";
 const peerDependencies = {
 	nuxt: ">=4.4.7 <5"};
 

package/dist/runtime/app/composables/query-api.js

@@ -1,4 +1,9 @@
-import { fetchContentApi, getContentApiFetcher, getPreviewToken } from "./utils.js";
+import {
+  createPrerenderPathAdder,
+  fetchContentApi,
+  getContentApiFetcher,
+  getPreviewToken
+} from "./utils.js";
 import { getContentRuntime } from "./runtime.js";
 import {
   backlinks as backlinksWithContext,
@@ -13,13 +18,14 @@ export const createClientContentQueryContext = () => {
   const runtime = getContentRuntime();
   const fetcher = getContentApiFetcher();
   const previewToken = getPreviewToken() ?? null;
+  const addPrerenderPath = createPrerenderPathAdder();
   return {
     runtime,
     transport: async (endpoint, params) => {
       return await fetchContentApi(
         endpoint,
         params,
-        { fetcher, runtime, previewToken }
+        { fetcher, runtime, previewToken, addPrerenderPath }
       );
     }
   };

package/dist/runtime/app/composables/utils.d.ts

@@ -7,17 +7,17 @@ interface ContentRuntimeShape {
 }
 export declare const withContentBase: (url: string) => string;
 export declare const navigationDisabled: () => never;
-export declare const addPrerenderPath: (path: string) => void;
+export declare const createPrerenderPathAdder: () => ((path: string) => void) | undefined;
 export type ContentApiEndpoint = 'query' | 'navigation';
 export type ContentApiFetcher = (request: string, init?: Record<string, unknown>) => Promise<unknown>;
 export declare const getPreviewToken: () => any;
 export declare const getContentApiFetcher: (fetcher?: ContentApiFetcher) => ContentApiFetcher;
-export declare const buildContentApiPath: (endpoint: ContentApiEndpoint, params: ContentProviderQueryInput, runtime?: ContentRuntimeShape) => string;
+export declare const buildContentApiPath: (endpoint: ContentApiEndpoint, params: ContentProviderQueryInput, runtime: ContentRuntimeShape) => string;
 export declare const isHtmlFallbackResponse: (data: unknown) => data is string;
-export declare function fetchContentApi<T>(endpoint: ContentApiEndpoint, params: ContentProviderQueryInput, options?: {
-    fetcher?: ContentApiFetcher;
-    runtime?: ContentRuntimeShape;
-    notFoundMessage?: string;
-    previewToken?: string | null;
+export declare function fetchContentApi<T>(endpoint: ContentApiEndpoint, params: ContentProviderQueryInput, options: {
+    fetcher: ContentApiFetcher;
+    runtime: ContentRuntimeShape;
+    previewToken: string | null;
+    addPrerenderPath?: (path: string) => void;
 }): Promise<T>;
 export {};

package/dist/runtime/app/composables/utils.js

@@ -1,6 +1,6 @@
 import { withBase } from "ufo";
 import { hash } from "ohash";
-import { useRequestEvent, useRequestFetch } from "#imports";
+import { tryUseNuxtApp, useRequestEvent, useRequestFetch } from "#imports";
 import { encodeQueryParams } from "../../utils/query.js";
 import { useContentPreview } from "./preview.js";
 import { getContentRuntime } from "./runtime.js";
@@ -11,13 +11,6 @@ export const navigationDisabled = () => {
   console.warn("Learn more in the Ginko navigation documentation.");
   throw new Error("Navigation is only accessible when you enable it in module options.");
 };
-const lookupRequestEvent = () => {
-  try {
-    return useRequestEvent();
-  } catch {
-    return void 0;
-  }
-};
 const addPathToEvent = (event, path) => {
   event.node.res.setHeader(
     "x-nitro-prerender",
@@ -27,16 +20,12 @@ const addPathToEvent = (event, path) => {
     ].filter(Boolean).join(",")
   );
 };
-const createPrerenderPathAdder = () => {
-  const event = lookupRequestEvent();
+export const createPrerenderPathAdder = () => {
+  if (import.meta.dev || !import.meta.server) return void 0;
+  const nuxtApp = tryUseNuxtApp();
+  const event = nuxtApp ? useRequestEvent(nuxtApp) : void 0;
   return event ? (path) => addPathToEvent(event, path) : void 0;
 };
-export const addPrerenderPath = (path) => {
-  const event = lookupRequestEvent();
-  if (event) {
-    addPathToEvent(event, path);
-  }
-};
 export const getPreviewToken = () => useContentPreview().getPreviewToken();
 export const getContentApiFetcher = (fetcher) => {
   if (fetcher) {
@@ -48,32 +37,26 @@ export const getContentApiFetcher = (fetcher) => {
   return $fetch;
 };
 export const buildContentApiPath = (endpoint, params, runtime) => {
-  const content = runtime || readContentRuntime();
   const encodedParams = encodeQueryParams(params);
-  const requestKey = import.meta.dev ? "_" : `${hash(params)}.${content.integrity}`;
-  return withBase(`/${endpoint}/${requestKey}/${encodedParams}.json`, content.api.baseURL);
+  const requestKey = import.meta.dev ? "_" : `${hash(params)}.${runtime.integrity}`;
+  return withBase(`/${endpoint}/${requestKey}/${encodedParams}.json`, runtime.api.baseURL);
 };
 export const isHtmlFallbackResponse = (data) => {
   return typeof data === "string" && data.startsWith("<!DOCTYPE html>");
 };
-export async function fetchContentApi(endpoint, params, options = {}) {
+export async function fetchContentApi(endpoint, params, options) {
   const apiPath = buildContentApiPath(endpoint, params, options.runtime);
-  const previewToken = options.previewToken === void 0 ? getPreviewToken() : options.previewToken;
-  const addPrerenderPathOnSuccess = !import.meta.dev && import.meta.server ? createPrerenderPathAdder() : void 0;
-  const fetcher = getContentApiFetcher(options.fetcher);
-  const data = await fetcher(apiPath, {
+  const data = await options.fetcher(apiPath, {
     method: "GET",
     responseType: "json",
-    ...previewToken ? { headers: { "x-nuxt-content-preview": previewToken } } : {}
+    ...options.previewToken ? { headers: { "x-nuxt-content-preview": options.previewToken } } : {}
   });
   if (isHtmlFallbackResponse(data)) {
-    throw new Error(options.notFoundMessage || "Not found");
+    throw new Error("Not found");
   }
   if (data === void 0 || data === null) {
     throw new TypeError("Invalid content API response: expected a non-empty JSON body.");
   }
-  if (!import.meta.dev && import.meta.server) {
-    addPrerenderPathOnSuccess?.(apiPath);
-  }
+  options.addPrerenderPath?.(apiPath);
   return data;
 }

package/dist/storage/graph.d.ts

@@ -19,6 +19,7 @@ export declare const getContentGraph: (event: H3Event) => Promise<ContentGraph>;
 export declare function resolveVariant(event: H3Event, canonicalKey: string, requestedLocale?: string, options?: {
     fallback?: string[];
     exact?: boolean;
+    collection?: string;
 }): Promise<import("../types/runtime").ResolvedVariant | null>;
 export declare function resolveRouteVariant(event: H3Event, routePath: string, requestedLocale?: string, options?: {
     fallback?: string[];

package/dist/storage/graph.js

@@ -40,6 +40,7 @@ export async function resolveVariant(event, canonicalKey, requestedLocale, optio
     locales: config.locales,
     fallback: options.fallback,
     exact: options.exact,
+    collection: options.collection,
     localeFallback: config.localeFallback
   });
 }

package/dist/storage/references.js

@@ -1,8 +1,9 @@
+import { resolveGraphReferenceTarget } from "../core/content/graph.js";
 import { collectMarkdownRefLinks, parseRefLink } from "../core/references/resolve.js";
 import { projectContentRoute } from "../features/localization/route-projector.js";
 import { resolveRuntimeCollectionLocalePolicy } from "../features/localization/config.js";
 import { contentConfig } from "./driver.js";
-import { getContentGraph, resolveCanonicalKey, resolveVariant } from "./graph.js";
+import { getContentGraph, resolveVariant } from "./graph.js";
 const isConfiguredQuickLink = (href) => {
   const parsed = parseRefLink(href);
   if (!parsed) {
@@ -33,8 +34,8 @@ const resolveDocumentRefLinks = async (event, content, requestedLocale) => {
       if (!parsed) {
         return null;
       }
-      const canonicalKey = await resolveCanonicalKey(event, parsed.ref);
-      if (!canonicalKey) {
+      const target = resolveGraphReferenceTarget(graph, parsed.ref);
+      if (!target) {
         if (isConfiguredQuickLink(href)) {
           return [href, href];
         }
@@ -45,7 +46,9 @@ const resolveDocumentRefLinks = async (event, content, requestedLocale) => {
         }
         return [href, href];
       }
-      const variant = await resolveVariant(event, canonicalKey, requestedLocale);
+      const variant = await resolveVariant(event, target.canonicalKey, requestedLocale, {
+        collection: target.collection
+      });
       if (!variant?.path) {
         if (import.meta.dev) {
           console.warn(
@@ -60,10 +63,9 @@ const resolveDocumentRefLinks = async (event, content, requestedLocale) => {
         );
       }
       const routeLocale = variant.fallback && requestedLocale ? requestedLocale : variant.resolvedLocale;
-      const targetCollection = graph.byId[variant.contentId]?.collection;
-      const targetPolicy = targetCollection ? resolveRuntimeCollectionLocalePolicy(targetCollection, config) : void 0;
+      const targetPolicy = resolveRuntimeCollectionLocalePolicy(target.collection, config);
       if (!targetPolicy) {
-        throw new Error(`Missing resolved locale policy for content collection "${targetCollection || ""}".`);
+        throw new Error(`Missing resolved locale policy for content collection "${target.collection}".`);
       }
       return [
         href,

package/dist/types/virtual.d.ts

@@ -51,6 +51,7 @@ declare module '#imports' {
   export const useFetch: typeof import('#app').useFetch
   export const useHead: typeof import('#app').useHead
   export const useNuxtApp: typeof import('#app').useNuxtApp
+  export const tryUseNuxtApp: typeof import('#app').tryUseNuxtApp
   export const useCookie: typeof import('#app').useCookie
   export const useRequestEvent: typeof import('#app').useRequestEvent
   export const useRequestFetch: typeof import('#app').useRequestFetch

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "framework": "vue",
   "name": "@lupinum/ginko-content",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "contributions": {
     "html": {
       "description-markup": "markdown",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lupinum/ginko-content",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Collection-first content engine for Nuxt",
   "homepage": "https://github.com/lupinum-dev/ginko-content",
   "bugs": {