@stati/core 1.29.2 → 2.0.0

package/dist/core/template-index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The template index: every `.eta` file under the source directory, and the name lookup that
+ * `stati.include()`, `stati.layout()`, front matter `layout:`, layout discovery and the Open
+ * Graph template share, so rendering and the ISG cache resolve every name the same way.
+ * @module core/template-index
+ */
+import type { TemplateLookup } from '../types/index.js';
+/**
+ * A template name, parsed.
+ * - `lookup`: `header` or `partials/header`, searched from the page's folder up to the source
+ *   directory, nearest match first.
+ * - `path`: one possible file, from `/partials/header` (`relative: false`) or from `./icon` and
+ *   `../icons/arrow` resolved against the calling template (`relative: true`). `path` always
+ *   starts with `/` and is relative to the source directory.
+ * - `invalid`: a name that can never resolve, with the reason.
+ */
+export type TemplateName = {
+    kind: 'lookup';
+    name: string;
+} | {
+    kind: 'path';
+    path: string;
+    relative: boolean;
+} | {
+    kind: 'invalid';
+    reason: string;
+};
+/**
+ * Parses a name passed to `stati.include()`, `stati.layout()`, `.has()` or front matter `layout:`.
+ * Backslashes count as `/`, and an `.eta` suffix is dropped.
+ *
+ * @param raw - The name as written
+ * @param callerFile - The calling template, relative to the source directory, or null for a
+ *   template without a file (the built-in Open Graph template)
+ */
+export declare function parseTemplateName(raw: unknown, callerFile: string | null): TemplateName;
+/**
+ * The folder of a file relative to the source directory, `''` for the source directory itself.
+ * Paths outside the source directory count as the source directory.
+ *
+ * @param relativeFile - A path relative to the source directory, with `/` or `\` separators
+ */
+export declare function templateFolderOf(relativeFile: string): string;
+/**
+ * The folders a looked-up name is searched in, nearest first: the folder itself, each parent,
+ * then the source directory (`''`).
+ */
+export declare function lookupFolders(from: string): string[];
+/**
+ * A `./` or `../` name that reaches `target` from `fromFolder`, both relative to the source
+ * directory. Pure string work, unlike `path.relative`, which resolves against the process's
+ * working directory.
+ *
+ * @example
+ * ```typescript
+ * relativeTemplateName('partials', 'partials/icon'); // './icon'
+ * relativeTemplateName('blog/2024', 'blog/post');     // '../post'
+ * relativeTemplateName('', 'layout');                 // './layout'
+ * ```
+ */
+export declare function relativeTemplateName(fromFolder: string, target: string): string;
+/**
+ * Converts an absolute path to the index's form: relative to the source directory, `/`
+ * separators. Returns null for files outside it and for files that are not templates.
+ *
+ * @param srcDir - Absolute source directory
+ * @param absolutePath - Absolute path of a file, with either separator
+ */
+export declare function toTemplateFile(srcDir: string, absolutePath: string): string | null;
+/**
+ * Whether a value read from the cache manifest is a list of template lookups.
+ */
+export declare function isTemplateLookupList(value: unknown): value is TemplateLookup[];
+/**
+ * How a page's layout was chosen, from {@link TemplateIndex.resolvePageLayout}.
+ */
+export interface PageLayoutResolution {
+    /** The layout file, relative to the source directory, or null when no layout applies */
+    file: string | null;
+    /** The lookups that chose it, for the page's cache entry */
+    lookups: TemplateLookup[];
+    /**
+     * A front matter `layout:` value that names no template: the value, why, and templates it
+     * could have meant. Layout discovery chose `file` instead.
+     */
+    unresolvedFrontMatter?: {
+        value: unknown;
+        problem: string;
+        suggestions: string[];
+    };
+}
+/**
+ * Every `.eta` file under a source directory, with memoised name lookups.
+ * Paths are relative to the source directory, with `/` separators and the `.eta` extension.
+ */
+export declare class TemplateIndex {
+    readonly srcDir: string;
+    private readonly templates;
+    private readonly lookupCache;
+    private sorted;
+    /**
+     * @param srcDir - Absolute source directory
+     * @param files - Template files relative to it
+     */
+    constructor(srcDir: string, files: Iterable<string>);
+    /**
+     * Globs the source directory once for its templates.
+     *
+     * @param srcDir - Absolute source directory
+     */
+    static load(srcDir: string): Promise<TemplateIndex>;
+    /** Number of templates */
+    get size(): number;
+    /** Whether a template file exists, given relative to the source directory */
+    has(file: string): boolean;
+    /** Every template file, sorted */
+    files(): readonly string[];
+    /**
+     * Adds a template, for a file created during a dev session.
+     *
+     * @returns Whether the index changed
+     */
+    add(file: string): boolean;
+    /**
+     * Removes a template, for a file deleted during a dev session.
+     *
+     * @returns Whether the index changed
+     */
+    remove(file: string): boolean;
+    private invalidate;
+    /**
+     * Finds the nearest template for a looked-up name, searching `from` and then each parent
+     * folder up to the source directory.
+     *
+     * @param name - A normalized looked-up name, such as `partials/header`
+     * @param from - The folder to start in, relative to the source directory
+     * @returns The template file, or null when no folder has one
+     */
+    lookup(name: string, from: string): string | null;
+    /**
+     * Resolves a parsed name for a page.
+     *
+     * @param name - A parsed, valid name
+     * @param pageFolder - The page's folder, where looked-up names start
+     * @returns The file (or null) and the lookup to record
+     */
+    resolve(name: Exclude<TemplateName, {
+        kind: 'invalid';
+    }>, pageFolder: string): {
+        file: string | null;
+        lookup: TemplateLookup;
+    };
+    /**
+     * Resolves a recorded lookup again, for the cache. Lookups with a `from` folder are searched
+     * like looked-up names; the others are a single path.
+     *
+     * @returns The file the lookup would resolve to now, or null
+     */
+    resolveRecorded(lookup: TemplateLookup): string | null;
+    /**
+     * Whether any recorded lookup would now resolve to a different file than it did.
+     */
+    lookupsChanged(lookups: readonly TemplateLookup[] | undefined): boolean;
+    /**
+     * Names a template could have meant, for an unknown name: templates with the same base name
+     * first, then similar names, written the way the name was written.
+     *
+     * @param name - The unknown name, parsed
+     * @param pageFolder - The page's folder
+     * @param callerFile - The calling template, relative to the source directory
+     * @param limit - Maximum number of suggestions
+     */
+    suggest(name: Exclude<TemplateName, {
+        kind: 'invalid';
+    }>, pageFolder: string, callerFile: string | null, limit?: number): string[];
+    /**
+     * Picks a page's layout: its front matter `layout:` when that names a template, otherwise the
+     * nearest `layout.eta`, or for index pages the nearest `index.eta` or `layout.eta`, whichever
+     * is in a nearer folder (`index.eta` first within a folder).
+     *
+     * @param pageFile - The page's Markdown file, relative to the source directory
+     * @param frontMatterLayout - The page's front matter `layout:` value
+     * @param isIndexPage - Whether the page lists a collection, which enables `index.eta`
+     */
+    resolvePageLayout(pageFile: string, frontMatterLayout: unknown, isIndexPage: boolean): PageLayoutResolution;
+    private discoverLayout;
+}
+/**
+ * Starts a dev server session for a source directory: builds reuse one index, and the dev
+ * server updates it on file events.
+ */
+export declare function startTemplateIndexSession(srcDir: string): void;
+/**
+ * Ends the dev server session for a source directory; later builds read it again. A session
+ * another dev server started for a different directory is left alone.
+ */
+export declare function endTemplateIndexSession(srcDir: string): void;
+/**
+ * Returns the template index for a build: the session's while a dev server watches the
+ * source directory, otherwise a new one.
+ *
+ * @param srcDir - Absolute source directory
+ */
+export declare function loadTemplateIndex(srcDir: string): Promise<TemplateIndex>;
+/**
+ * The dev server session's index for a source directory, or null when there is none yet.
+ */
+export declare function getCachedTemplateIndex(srcDir: string): TemplateIndex | null;
+//# sourceMappingURL=template-index.d.ts.map

package/dist/core/template-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-index.d.ts","sourceRoot":"","sources":["../../src/core/template-index.ts"],"names":[],"mappings":"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"}