import { join } from 'node:path'; import { getLocalizedUrl } from '@intlayer/core/localization'; import { getMarkdownMetadata } from '@intlayer/core/transpiler'; import * as Locales from '@intlayer/types/locales'; import type { LocalesValues } from '@intlayer/types/module_augmentation'; import { isLazyDocument } from './readMarkdownHead'; export const defaultLocale = Locales.ENGLISH; export const GITHUB_URL_PREFIX = 'https://github.com/aymericzip/intlayer/blob/main/docs'; export const URL_PREFIX = 'https://intlayer.org/'; export const getKeys = >(obj: T): (keyof T)[] => Object.keys(obj) as (keyof T)[]; export const getFiles = async < F extends Record<`./${string}`, Record>>, >( files: F, lang: LocalesValues = defaultLocale as LocalesValues ): Promise> => { const filesEntries = await Promise.all( Object.entries(files) .map(([key, value]) => [key, value[lang as LocalesValues]]) .map(async ([key, value]) => [key, await value]) ); const filesResult = Object.fromEntries(filesEntries); return filesResult; }; /** Reads the whole document, or only its front matter when supported. */ const readDocument = ( document: Promise | undefined, headOnly: boolean ): Promise | undefined => headOnly && isLazyDocument(document) ? document.readHead() : document; export const getFile = async < F extends Record>>, >( files: F, docKey: keyof F, locale: LocalesValues = defaultLocale as LocalesValues, { headOnly = false }: { headOnly?: boolean } = {} ): Promise => { const fileRecord = files[docKey]; if (!fileRecord) { throw new Error(`File ${docKey as string} not found`); } const file = await readDocument(fileRecord[locale], headOnly); if (!file) { const englishFile = await readDocument( fileRecord[defaultLocale as LocalesValues], headOnly ); if (!englishFile) { throw new Error(`File ${docKey as string} not found`); } return englishFile; } return file; }; export type FileMetadata = { docKey: string; url: string; relativeUrl: string; githubUrl: string; title: string; slugs: string[]; description: string; keywords: string[]; updatedAt: string; createdAt: string; /** Page importance from 1 (lowest) to 10 (highest), used by the sitemap. */ priority?: number; author?: string; youtubeVideo?: string; applicationTemplate?: string; applicationShowcase?: string; history?: { version: string; date: string; changes: string; }[]; }; export const formatMetadata = ( docKey: string, file: string, locale: LocalesValues = defaultLocale as LocalesValues ): FileMetadata => { const metadata = getMarkdownMetadata(file); const slugs = (metadata.slugs ?? []).map(String); const keywords = (metadata.keywords ?? []).map(String); const relativeUrl = join('/', ...slugs); const slicedDocKey = docKey.slice(1); // Normalise author: accept both a plain string handle (new format) // and a legacy object `{ github: '...' }` — always reduce to a plain string. const rawAuthor = metadata.author as | string | { name?: string; github?: string } | undefined; const author: string | undefined = typeof rawAuthor === 'string' ? rawAuthor || undefined : rawAuthor?.github || undefined; return { ...metadata, docKey, slugs, keywords, author, githubUrl: `${GITHUB_URL_PREFIX}${slicedDocKey}`.replace( '/en/', `/${locale}/` ), relativeUrl: getLocalizedUrl(relativeUrl, locale), url: getLocalizedUrl(join(URL_PREFIX, relativeUrl), locale), } as FileMetadata; }; export const getFileMetadata = async < F extends Record>>, R extends FileMetadata, >( files: F, docKey: keyof F, locale: LocalesValues = defaultLocale as LocalesValues ): Promise => { // Metadata lives in the front matter: skip reading the document body const file = await getFile(files, docKey, locale, { headOnly: true }); return formatMetadata(docKey as string, file, locale) as R; }; /** * Per-locale metadata records, keyed by the entry map they were built from. * * Building a record parses the frontmatter of every document of a category, and * callers such as {@link getFileMetadataBySlug} need the whole record just to * resolve a single slug — which a static site generator repeats for every page * it renders. Documents are read once per process anyway (each entry caches its * own read), so the derived metadata is equally safe to keep. */ const fileMetadataRecordCache = new WeakMap< Record, Map>> >(); const buildFileMetadataRecord = async < F extends Record>>, >( files: F, locale: LocalesValues ): Promise> => { const results = await Promise.allSettled( Object.entries(files).map(async ([key]) => { const metadata = await getFileMetadata(files, key as keyof F, locale); return [key, metadata] as [string, FileMetadata]; }) ); const filesEntries = results .filter( (r): r is PromiseFulfilledResult<[string, FileMetadata]> => r.status === 'fulfilled' ) .map((r) => r.value); const filesResult = Object.fromEntries(filesEntries); return filesResult as Record; }; export const getFileMetadataRecord = async < F extends Record>>, >( files: F, locale: LocalesValues = defaultLocale as LocalesValues ): Promise> => { let localeCache = fileMetadataRecordCache.get(files); if (!localeCache) { localeCache = new Map(); fileMetadataRecordCache.set(files, localeCache); } let record = localeCache.get(locale); if (!record) { record = buildFileMetadataRecord(files, locale); localeCache.set(locale, record); } return (await record) as Record; }; /** * Flattens front-matter slugs into the URL segments they produce. * * `relativeUrl` is built by joining the slugs with `/`, so a slug holding a * slash — `"@intlayer/babel"` — yields more URL segments than the array holds * entries. A requested path, split on `/`, could then never be matched against * the raw array, and the page resolved to nothing. * * @param slugs - Front-matter slugs, or the segments of a requested path. * @returns One entry per URL segment, empty segments dropped. */ const toUrlSegments = (slugs: string[]): string[] => slugs.flatMap((slug) => slug.split('/')).filter(Boolean); /** * Tells whether a file answers a requested slug path. * * Segments are compared case-insensitively, so `/doc/…/useintlayer` still * resolves the `useIntlayer` page and callers can redirect to its canonical * casing instead of answering a 404. * * @param fileMetadata - Metadata of the candidate file. * @param requestedSegments - URL segments asked for, already flattened. * @param strict - Rejects files owning segments beyond the requested ones. * @returns `true` when the file matches the request. */ const matchesRequestedSegments = ( fileMetadata: FileMetadata, requestedSegments: string[], strict: boolean ): boolean => { const fileSegments = toUrlSegments(fileMetadata.slugs ?? []).map((segment) => segment.toLowerCase() ); if (strict && fileSegments.length !== requestedSegments.length) return false; return requestedSegments.every((segment) => fileSegments.includes(segment.toLowerCase()) ); }; export const getFileMetadataBySlug = async < F extends Record>>, >( files: F, slugs: string | string[], locale: LocalesValues = defaultLocale as LocalesValues, strict = false ) => { const requestedSegments = toUrlSegments( Array.isArray(slugs) ? slugs : [slugs] ); const filesMetadata = await getFileMetadataRecord( files, defaultLocale as LocalesValues ); const fileMetadataArray: FileMetadata[] = Object.values(filesMetadata).filter( (fileMetadata) => matchesRequestedSegments(fileMetadata, requestedSegments, strict) ); if (locale !== defaultLocale) { const localizedFileMetadata = await Promise.all( fileMetadataArray.map( async (fileMetadata) => await getFileMetadata(files, fileMetadata.docKey, locale) ) ); return localizedFileMetadata; } return fileMetadataArray; }; export const getFileBySlug = async < F extends Record>>, >( files: F, slugs: string | string[], locale: LocalesValues = defaultLocale as LocalesValues, strict = false ) => { const requestedSegments = toUrlSegments( Array.isArray(slugs) ? slugs : [slugs] ); const filesMetadata = await getFileMetadataRecord( files, defaultLocale as LocalesValues ); const fileMetadataArray = Object.values(filesMetadata).filter( (fileMetadata) => matchesRequestedSegments(fileMetadata, requestedSegments, strict) ); const fileList = await Promise.all( fileMetadataArray.map(async (fileMetadata) => { const file = await getFile(files, fileMetadata.docKey, locale); return file; }) ); return fileList; };