@qzsy/vinext 0.1.7

package/dist/server/metadata-route-build-data.js

@@ -0,0 +1,148 @@
+import { routePatternParts } from "../routing/route-pattern.js";
+import { getMetadataRouteKind } from "./metadata-routes.js";
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { imageSize } from "image-size";
+//#region src/server/metadata-route-build-data.ts
+function createMetadataContentHash(buffer) {
+	return createHash("sha1").update(buffer).digest("hex").slice(0, 16);
+}
+function readMetadataRouteFile(route) {
+	try {
+		return fs.readFileSync(route.filePath);
+	} catch (error) {
+		const reason = error instanceof Error && error.message ? `: ${error.message}` : "";
+		throw new Error(`[vinext] Failed to read metadata route file ${route.filePath} for ${route.servedUrl}${reason}`, { cause: error });
+	}
+}
+function readMetadataRouteTextFile(filePath, route) {
+	try {
+		return fs.readFileSync(filePath, "utf8");
+	} catch (error) {
+		const reason = error instanceof Error && error.message ? `: ${error.message}` : "";
+		throw new Error(`[vinext] Failed to read metadata route file ${filePath} for ${route.servedUrl}${reason}`, { cause: error });
+	}
+}
+function readMetadataRouteAltText(route) {
+	return route.altFilePath ? readMetadataRouteTextFile(route.altFilePath, route) : void 0;
+}
+function readMetadataImageDimensions(buffer, route) {
+	try {
+		const dimensions = imageSize(buffer);
+		return {
+			width: dimensions.width,
+			height: dimensions.height
+		};
+	} catch (error) {
+		const reason = error instanceof Error && error.message ? `: ${error.message}` : "";
+		throw new Error(`[vinext] Failed to read metadata image dimensions for ${route.filePath} (${route.servedUrl})${reason}`, { cause: error });
+	}
+}
+function resolveIconSizes(routeKind, isSvgRoute, dimensions) {
+	if (routeKind !== "favicon" && routeKind !== "icon" && routeKind !== "apple") return;
+	if (isSvgRoute) return "any";
+	if (dimensions.width && dimensions.height) return `${dimensions.width}x${dimensions.height}`;
+	return "any";
+}
+function createMetadataHeadData(input) {
+	const { route, contentHash, dimensions, altText } = input;
+	const routeKind = getMetadataRouteKind(route);
+	if (!routeKind) return null;
+	if (routeKind === "manifest") return {
+		kind: "manifest",
+		href: route.servedUrl
+	};
+	const href = `${route.servedUrl}?${contentHash}`;
+	const isSvgRoute = route.contentType === "image/svg+xml" || route.servedUrl.toLowerCase().endsWith(".svg");
+	if (routeKind === "favicon" || routeKind === "icon" || routeKind === "apple") return {
+		kind: routeKind,
+		href,
+		type: route.contentType,
+		sizes: resolveIconSizes(routeKind, isSvgRoute, dimensions)
+	};
+	return {
+		kind: routeKind,
+		href,
+		type: route.contentType,
+		width: dimensions.width,
+		height: dimensions.height,
+		alt: altText
+	};
+}
+function createBaseEntryData(route, contentHash) {
+	return {
+		type: route.type,
+		isDynamic: route.isDynamic,
+		routePrefix: route.routePrefix,
+		routeSegments: route.routeSegments ?? [],
+		servedUrl: route.servedUrl,
+		contentType: route.contentType,
+		contentHash
+	};
+}
+function readStaticMetadataImageDimensions(route, buffer) {
+	return route.contentType.startsWith("image/") ? readMetadataImageDimensions(buffer, route) : {};
+}
+function createMetadataRouteEntryData(route) {
+	const buffer = readMetadataRouteFile(route);
+	const contentHash = createMetadataContentHash(buffer);
+	const entryData = createBaseEntryData(route, contentHash);
+	if (route.isDynamic) {
+		if (route.type === "manifest") return {
+			...entryData,
+			headData: {
+				kind: "manifest",
+				href: route.servedUrl
+			}
+		};
+		return entryData;
+	}
+	return {
+		...entryData,
+		headData: createMetadataHeadData({
+			route,
+			contentHash,
+			dimensions: readStaticMetadataImageDimensions(route, buffer),
+			altText: readMetadataRouteAltText(route)
+		}),
+		fileDataBase64: buffer.toString("base64")
+	};
+}
+function pushEntryProperty(lines, key, value) {
+	if (value !== void 0) lines.push(`${key}: ${JSON.stringify(value)},`);
+}
+function createMetadataRoutePatternParts(route) {
+	if (!route.isDynamic || !route.servedUrl.includes("[")) return null;
+	return routePatternParts(route.servedUrl);
+}
+function getDynamicMetadataRouteModuleName(route, moduleNames) {
+	if (!route.isDynamic) return;
+	const moduleName = moduleNames.get(route.filePath);
+	if (!moduleName) throw new Error(`[vinext] Missing generated module import for dynamic metadata route ${route.filePath}`);
+	return moduleName;
+}
+function createMetadataRouteEntrySource(input) {
+	const { entryData, moduleName, patternParts } = input;
+	const lines = [];
+	pushEntryProperty(lines, "type", entryData.type);
+	pushEntryProperty(lines, "isDynamic", entryData.isDynamic);
+	pushEntryProperty(lines, "routePrefix", entryData.routePrefix);
+	pushEntryProperty(lines, "routeSegments", entryData.routeSegments);
+	pushEntryProperty(lines, "servedUrl", entryData.servedUrl);
+	pushEntryProperty(lines, "contentType", entryData.contentType);
+	pushEntryProperty(lines, "contentHash", entryData.contentHash);
+	pushEntryProperty(lines, "headData", entryData.headData);
+	pushEntryProperty(lines, "fileDataBase64", entryData.fileDataBase64);
+	if (moduleName) lines.push(`module: ${moduleName},`);
+	if (patternParts) lines.push(`patternParts: ${JSON.stringify(patternParts)},`);
+	return `  {\n    ${lines.join("\n    ")}\n  }`;
+}
+function createMetadataRouteEntriesSource(routes, moduleNames) {
+	return routes.map((route) => createMetadataRouteEntrySource({
+		entryData: createMetadataRouteEntryData(route),
+		moduleName: getDynamicMetadataRouteModuleName(route, moduleNames),
+		patternParts: createMetadataRoutePatternParts(route)
+	}));
+}
+//#endregion
+export { createMetadataRouteEntriesSource, createMetadataRouteEntryData, createMetadataRouteEntrySource };

package/dist/server/metadata-route-response.d.ts

@@ -0,0 +1,16 @@
+import { MetadataFileRoute } from "./metadata-routes.js";
+
+//#region src/server/metadata-route-response.d.ts
+type AppPageParams = Record<string, string | string[]>;
+type MetadataRouteMakeThenableParams = (params: AppPageParams) => unknown;
+type MetadataRuntimeRoute = MetadataFileRoute & {
+  fileDataBase64?: string;
+};
+type MetadataRouteRequestOptions = {
+  metadataRoutes: readonly MetadataRuntimeRoute[];
+  cleanPathname: string;
+  makeThenableParams: MetadataRouteMakeThenableParams;
+};
+declare function handleMetadataRouteRequest(options: MetadataRouteRequestOptions): Promise<Response | null>;
+//#endregion
+export { MetadataRuntimeRoute, handleMetadataRouteRequest };

package/dist/server/metadata-route-response.js

@@ -0,0 +1,205 @@
+import { notFoundResponse } from "./http-error-responses.js";
+import { isValidMetadataImageId, manifestToJson, matchMetadataRoutePattern, robotsToText, sitemapToXml } from "./metadata-routes.js";
+//#region src/server/metadata-route-response.ts
+const routeFunctionCache = /* @__PURE__ */ new WeakMap();
+const CACHE_HEADERS = {
+	noCache: "no-cache, no-store",
+	revalidate: "public, max-age=0, must-revalidate"
+};
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function readFunction(module, key) {
+	if (!module) return null;
+	const value = Reflect.get(module, key);
+	if (typeof value !== "function") return null;
+	return (props) => Reflect.apply(value, module, [props]);
+}
+function isSitemapEntries(value) {
+	return Array.isArray(value);
+}
+function isRobotsConfig(value) {
+	return isObject(value) && !Array.isArray(value);
+}
+function isManifestConfig(value) {
+	return isObject(value) && !Array.isArray(value);
+}
+function isImageMetadataRoute(route) {
+	return route.type === "icon" || route.type === "apple-icon" || route.type === "opengraph-image" || route.type === "twitter-image";
+}
+function metadataRouteCacheHeader(route) {
+	if (route.isDynamic && isImageMetadataRoute(route) && process.env.NODE_ENV === "development") return CACHE_HEADERS.noCache;
+	return CACHE_HEADERS.revalidate;
+}
+function withMetadataRouteCacheHeader(response, route) {
+	const headers = new Headers(response.headers);
+	if (!headers.has("Cache-Control")) headers.set("Cache-Control", metadataRouteCacheHeader(route));
+	return new Response(response.body, {
+		headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+}
+function getMetadataRouteFunctions(route) {
+	const cached = routeFunctionCache.get(route);
+	if (cached) return cached;
+	const generateImageMetadata = route.isDynamic && isImageMetadataRoute(route) ? readFunction(route.module, "generateImageMetadata") : null;
+	const functions = {
+		defaultExport: route.isDynamic ? readFunction(route.module, "default") : null,
+		generateImageMetadata,
+		generateSitemaps: route.type === "sitemap" && route.isDynamic ? readFunction(route.module, "generateSitemaps") : null,
+		hasGeneratedImageMetadata: route.isDynamic && isImageMetadataRoute(route) && Boolean(generateImageMetadata)
+	};
+	routeFunctionCache.set(route, functions);
+	return functions;
+}
+function matchMetadataRoute(route, cleanPathname, functions, getUrlParts) {
+	if (route.patternParts) {
+		const urlParts = getUrlParts();
+		if (functions.hasGeneratedImageMetadata && urlParts.length > 0) {
+			const params = matchMetadataRoutePattern(urlParts.slice(0, -1), route.patternParts);
+			if (params) return {
+				params,
+				imageId: urlParts[urlParts.length - 1]
+			};
+		}
+		const params = matchMetadataRoutePattern(urlParts, route.patternParts);
+		return params ? {
+			params,
+			imageId: null
+		} : null;
+	}
+	if (functions.hasGeneratedImageMetadata && cleanPathname.startsWith(`${route.servedUrl}/`)) {
+		const imageSuffix = cleanPathname.slice(route.servedUrl.length + 1);
+		if (!imageSuffix || imageSuffix.includes("/")) return null;
+		return {
+			params: Object.create(null),
+			imageId: imageSuffix
+		};
+	}
+	return cleanPathname === route.servedUrl ? {
+		params: null,
+		imageId: null
+	} : null;
+}
+function findGeneratedSitemapId(entries, rawId) {
+	if (!Array.isArray(entries)) return null;
+	for (const entry of entries) {
+		if (!isObject(entry) || Reflect.get(entry, "id") == null) throw new Error("id property is required for every item returned from generateSitemaps");
+		const id = Reflect.get(entry, "id");
+		if (String(id) === rawId) return rawId;
+	}
+	return null;
+}
+function makeThenableMetadataRouteId(id) {
+	return Object.assign(Promise.resolve(id), {
+		toString() {
+			return id;
+		},
+		valueOf() {
+			return id;
+		},
+		[Symbol.toPrimitive]() {
+			return id;
+		}
+	});
+}
+async function handleGeneratedSitemap(route, cleanPathname, functions) {
+	if (!functions.generateSitemaps || !functions.defaultExport) return null;
+	const sitemapPrefix = route.servedUrl.slice(0, -4);
+	if (!cleanPathname.startsWith(`${sitemapPrefix}/`) || !cleanPathname.endsWith(".xml")) return null;
+	const rawId = cleanPathname.slice(sitemapPrefix.length + 1, -4);
+	if (rawId.includes("/")) return null;
+	const matchedId = findGeneratedSitemapId(await functions.generateSitemaps({}), rawId);
+	if (!matchedId) return notFoundResponse();
+	const result = await functions.defaultExport({ id: makeThenableMetadataRouteId(matchedId) });
+	if (result instanceof Response) return withMetadataRouteCacheHeader(result, route);
+	if (!isSitemapEntries(result)) throw new TypeError("Metadata sitemap routes must return an array.");
+	return new Response(sitemapToXml(result), { headers: {
+		"Content-Type": route.contentType,
+		"Cache-Control": metadataRouteCacheHeader(route)
+	} });
+}
+function findGeneratedImageId(imageMetadata, imageId, servedUrl) {
+	if (!Array.isArray(imageMetadata)) return null;
+	for (const item of imageMetadata) {
+		if (!isObject(item) || Reflect.get(item, "id") == null) throw new Error("id property is required for every item returned from generateImageMetadata");
+		const itemId = String(Reflect.get(item, "id"));
+		if (!isValidMetadataImageId(itemId)) {
+			console.warn(`[vinext] Skipping metadata route ${servedUrl} image id "${itemId}" because metadata image ids must match /^[a-zA-Z0-9-_.]+$/.`);
+			continue;
+		}
+		if (itemId === imageId) return itemId;
+	}
+	return null;
+}
+async function callDynamicMetadataRoute(route, match, makeThenableParams, functions) {
+	if (!functions.defaultExport) {
+		console.warn(`[vinext] Dynamic metadata route ${route.servedUrl} has no default export.`);
+		return notFoundResponse();
+	}
+	const paramsThenable = makeThenableParams(match.params ?? {});
+	let result;
+	if (functions.hasGeneratedImageMetadata) {
+		if (match.imageId === null || !isValidMetadataImageId(match.imageId)) return notFoundResponse();
+		if (!functions.generateImageMetadata) return notFoundResponse();
+		const matchedImageId = findGeneratedImageId(await functions.generateImageMetadata({ params: paramsThenable }), match.imageId, route.servedUrl);
+		if (!matchedImageId) return notFoundResponse();
+		result = await functions.defaultExport({
+			params: paramsThenable,
+			id: makeThenableMetadataRouteId(matchedImageId)
+		});
+	} else result = await functions.defaultExport({ params: paramsThenable });
+	if (result instanceof Response) return withMetadataRouteCacheHeader(result, route);
+	let body;
+	if (route.type === "sitemap") {
+		if (!isSitemapEntries(result)) throw new TypeError("Metadata sitemap routes must return an array.");
+		body = sitemapToXml(result);
+	} else if (route.type === "robots") {
+		if (!isRobotsConfig(result)) throw new TypeError("Metadata robots routes must return an object.");
+		body = robotsToText(result);
+	} else if (route.type === "manifest") {
+		if (!isManifestConfig(result)) throw new TypeError("Metadata manifest routes must return an object.");
+		body = manifestToJson(result);
+	} else if (isImageMetadataRoute(route)) throw new TypeError(`Dynamic metadata ${route.type} route ${route.servedUrl} must return a Response.`);
+	else body = JSON.stringify(result);
+	return new Response(body, { headers: {
+		"Content-Type": route.contentType,
+		"Cache-Control": metadataRouteCacheHeader(route)
+	} });
+}
+function serveStaticMetadataRoute(route) {
+	if (typeof route.fileDataBase64 !== "string") throw new Error(`[vinext] Static metadata route ${route.servedUrl} is missing embedded file data.`);
+	try {
+		const binary = atob(route.fileDataBase64);
+		const bytes = new Uint8Array(binary.length);
+		for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+		return new Response(bytes, { headers: {
+			"Content-Type": route.contentType,
+			"Cache-Control": metadataRouteCacheHeader(route)
+		} });
+	} catch (error) {
+		const reason = error instanceof Error && error.message ? `: ${error.message}` : "";
+		throw new Error(`[vinext] Failed to decode embedded metadata route file data for ${route.servedUrl}${reason}`, { cause: error });
+	}
+}
+async function handleMetadataRouteRequest(options) {
+	let urlParts;
+	const getUrlParts = () => urlParts ??= options.cleanPathname.split("/").filter(Boolean);
+	for (const route of options.metadataRoutes) {
+		const functions = getMetadataRouteFunctions(route);
+		if (route.type === "sitemap" && route.isDynamic) {
+			if (functions.generateSitemaps) {
+				const generatedSitemapResponse = await handleGeneratedSitemap(route, options.cleanPathname, functions);
+				if (generatedSitemapResponse) return generatedSitemapResponse;
+				continue;
+			}
+		}
+		const match = matchMetadataRoute(route, options.cleanPathname, functions, getUrlParts);
+		if (!match) continue;
+		return route.isDynamic ? callDynamicMetadataRoute(route, match, options.makeThenableParams, functions) : serveStaticMetadataRoute(route);
+	}
+	return null;
+}
+//#endregion
+export { handleMetadataRouteRequest };

package/dist/server/metadata-routes.d.ts

@@ -0,0 +1,139 @@
+//#region src/server/metadata-routes.d.ts
+type SitemapEntry = {
+  url: string;
+  lastModified?: string | Date;
+  changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+  priority?: number;
+  alternates?: {
+    languages?: Record<string, string>;
+  };
+  images?: string[];
+  videos?: Array<{
+    title: string;
+    thumbnail_loc: string;
+    description: string;
+    content_loc?: string;
+    player_loc?: string;
+    duration?: number;
+    expiration_date?: string | Date;
+    rating?: number;
+    view_count?: number;
+    publication_date?: string | Date;
+    family_friendly?: "yes" | "no";
+    restriction?: {
+      relationship: "allow" | "deny";
+      content: string;
+    };
+    platform?: {
+      relationship: "allow" | "deny";
+      content: string;
+    };
+    requires_subscription?: "yes" | "no";
+    uploader?: {
+      info?: string;
+      content?: string;
+    };
+    live?: "yes" | "no";
+    tag?: string;
+  }>;
+};
+type RobotsRule = {
+  userAgent?: string | string[];
+  allow?: string | string[];
+  disallow?: string | string[];
+  crawlDelay?: number;
+  other?: Record<string, string | number | Array<string | number>>;
+};
+type RobotsConfig = {
+  rules: RobotsRule | RobotsRule[];
+  sitemap?: string | string[];
+  host?: string;
+};
+type ManifestConfig = {
+  name?: string;
+  short_name?: string;
+  description?: string;
+  start_url?: string;
+  display?: "fullscreen" | "standalone" | "minimal-ui" | "browser";
+  background_color?: string;
+  theme_color?: string;
+  icons?: Array<{
+    src: string;
+    sizes?: string;
+    type?: string;
+    purpose?: string;
+  }>;
+  [key: string]: unknown;
+};
+/** Map of metadata file base names to their URL path and content type. */
+declare const METADATA_FILE_MAP: Record<string, {
+  /** URL path this file is served at */urlPath: string; /** Content type for the response */
+  contentType: string; /** Whether this can be dynamic (.ts/.tsx/.js) */
+  canBeDynamic: boolean; /** File extensions for static variants */
+  staticExtensions: string[]; /** File extensions for dynamic variants */
+  dynamicExtensions: string[]; /** Whether this can be nested in sub-segments */
+  nestable: boolean;
+}>;
+/**
+ * Convert a sitemap array to XML string.
+ */
+declare function sitemapToXml(entries: SitemapEntry[]): string;
+/**
+ * Convert a robots config to text format.
+ */
+declare function robotsToText(config: RobotsConfig): string;
+/**
+ * Convert a manifest config to JSON string.
+ */
+declare function manifestToJson(config: ManifestConfig): string;
+/**
+ * Compute the static URL for a metadata file given its app directory
+ * parent path and filename.
+ *
+ * Example:
+ *   fillStaticMetadataSegment("/", "favicon.ico") -> "/favicon.ico"
+ *   fillStaticMetadataSegment("/blog/[slug]", "favicon.ico") -> "/blog/-/favicon.ico"
+ *   fillStaticMetadataSegment("/(group)/group", "icon.png") -> "/group/icon-131tc6.png"
+ */
+declare function fillStaticMetadataSegment(appDirPath: string, lastSegment: string): string;
+type MetadataFileRoute = {
+  /** Type of metadata file */type: string; /** Whether this is a dynamic (code-generated) route */
+  isDynamic: boolean; /** Imported dynamic module for code-generated metadata routes. */
+  module?: Record<string, unknown>; /** Absolute file path */
+  filePath: string; /** Route prefix where this metadata applies, preserving dynamic segment names. */
+  routePrefix: string; /** Raw app tree segments where this metadata file is colocated. */
+  routeSegments?: string[]; /** Pattern parts for matching dynamic metadata routes at request time. */
+  patternParts?: string[]; /** URL path this file is served at */
+  servedUrl: string; /** Content type for the response */
+  contentType: string; /** Optional metadata used to inject file-based routes into <head>. */
+  headData?: MetadataRouteHeadData; /** Optional content hash for cache-busting metadata links. */
+  contentHash?: string; /** Sibling .alt.txt file for static social image metadata routes. */
+  altFilePath?: string;
+};
+type MetadataRouteHeadData = {
+  kind: "favicon" | "icon" | "apple";
+  href: string;
+  type?: string;
+  sizes?: string;
+} | {
+  kind: "openGraph" | "twitter";
+  href: string;
+  type?: string;
+  width?: number;
+  height?: number;
+  alt?: string;
+} | {
+  kind: "manifest";
+  href: string;
+};
+declare function getMetadataRouteKind(route: Pick<MetadataFileRoute, "type">): MetadataRouteHeadData["kind"] | null;
+declare function getMetadataImageRouteKind(route: Pick<MetadataFileRoute, "type">): Extract<MetadataRouteHeadData["kind"], "icon" | "apple" | "openGraph" | "twitter"> | null;
+declare function isValidMetadataImageId(id: string): boolean;
+declare function matchMetadataRoutePattern(urlParts: string[], patternParts: string[]): Record<string, string | string[]> | null;
+declare function matchMetadataFileBaseName(metaType: string, baseName: string): string | null;
+/**
+ * Scan an app directory for metadata files.
+ */
+declare function scanMetadataFiles(appDir: string): MetadataFileRoute[];
+//#endregion
+export { METADATA_FILE_MAP, ManifestConfig, MetadataFileRoute, MetadataRouteHeadData, RobotsConfig, SitemapEntry, fillStaticMetadataSegment, getMetadataImageRouteKind, getMetadataRouteKind, isValidMetadataImageId, manifestToJson, matchMetadataFileBaseName, matchMetadataRoutePattern, robotsToText, scanMetadataFiles, sitemapToXml };