@stati/core 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,371 @@
+import type MarkdownIt from 'markdown-it';
+/**
+ * Aging rule for Incremental Static Generation (ISG) cache management.
+ * Defines how cache TTL changes based on content age.
+ *
+ * @example
+ * ```typescript
+ * const rule: AgingRule = {
+ *   untilDays: 7,      // Apply this rule for content older than 7 days
+ *   ttlSeconds: 86400  // Cache for 24 hours
+ * };
+ * ```
+ */
+export interface AgingRule {
+    /** Number of days after which this aging rule applies */
+    untilDays: number;
+    /** Cache time-to-live in seconds for content matching this age */
+    ttlSeconds: number;
+}
+/**
+ * Configuration for Incremental Static Generation (ISG) caching.
+ * Enables smart caching strategies for static site generation.
+ *
+ * @example
+ * ```typescript
+ * const isgConfig: ISGConfig = {
+ *   enabled: true,
+ *   ttlSeconds: 3600,     // Default 1 hour cache
+ *   maxAgeCapDays: 30,    // Max age for aging rules
+ *   aging: [
+ *     { untilDays: 7, ttlSeconds: 86400 },   // 1 day for week-old content
+ *     { untilDays: 30, ttlSeconds: 604800 }  // 1 week for month-old content
+ *   ]
+ * };
+ * ```
+ */
+export interface ISGConfig {
+    /** Whether ISG caching is enabled */
+    enabled?: boolean;
+    /** Default cache time-to-live in seconds */
+    ttlSeconds?: number;
+    /** Maximum age in days for applying aging rules */
+    maxAgeCapDays?: number;
+    /** Array of aging rules for progressive cache extension */
+    aging?: AgingRule[];
+}
+/**
+ * Site-wide configuration settings.
+ * Contains global metadata and URL configuration for the static site.
+ *
+ * @example
+ * ```typescript
+ * const siteConfig: SiteConfig = {
+ *   title: "My Awesome Blog",
+ *   baseUrl: "https://myblog.com",
+ *   defaultLocale: "en-US"
+ * };
+ * ```
+ */
+export interface SiteConfig {
+    /** The site's title, used in templates and metadata */
+    title: string;
+    /** Base URL for the site, used for absolute URL generation */
+    baseUrl: string;
+    /** Default locale for internationalization (optional) */
+    defaultLocale?: string;
+}
+/**
+ * Main configuration interface for Stati static site generator.
+ * Defines all options for site generation, including directories, templates, and features.
+ *
+ * @example
+ * ```typescript
+ * const config: StatiConfig = {
+ *   srcDir: 'site',
+ *   outDir: 'dist',
+ *   staticDir: 'public',
+ *   site: {
+ *     title: 'My Blog',
+ *     baseUrl: 'https://example.com'
+ *   },
+ *   markdown: {
+ *     configure: (md) => md.use(somePlugin)
+ *   }
+ * };
+ * ```
+ */
+export interface StatiConfig {
+    /** Source directory for content files (default: 'site') */
+    srcDir?: string;
+    /** Output directory for generated site (default: 'dist') */
+    outDir?: string;
+    /** Directory for static assets (default: 'public') */
+    staticDir?: string;
+    /** Site-wide configuration */
+    site: SiteConfig;
+    /** Markdown processing configuration */
+    markdown?: {
+        /** Array of plugins to load - each item can be a string (plugin name) or [string, options] tuple */
+        plugins?: (string | [string, unknown])[];
+        /** Function to configure the MarkdownIt instance */
+        configure?: (md: MarkdownIt) => void;
+    };
+    /** Eta template engine configuration */
+    eta?: {
+        /** Custom template filters */
+        filters?: Record<string, (x: unknown) => unknown>;
+    };
+    /** Incremental Static Generation configuration */
+    isg?: ISGConfig;
+    /** Build lifecycle hooks */
+    hooks?: BuildHooks;
+}
+/**
+ * Build context passed to build lifecycle hooks.
+ * Contains the full configuration and all loaded pages.
+ *
+ * @example
+ * ```typescript
+ * const buildHook = async (ctx: BuildContext) => {
+ *   console.log(`Building ${ctx.pages.length} pages`);
+ *   console.log(`Output directory: ${ctx.config.outDir}`);
+ * };
+ * ```
+ */
+export interface BuildContext {
+    /** The resolved Stati configuration */
+    config: StatiConfig;
+    /** Array of all loaded page models */
+    pages: PageModel[];
+}
+/**
+ * Page context passed to page-specific lifecycle hooks.
+ * Contains the current page being processed and site configuration.
+ *
+ * @example
+ * ```typescript
+ * const pageHook = async (ctx: PageContext) => {
+ *   console.log(`Rendering page: ${ctx.page.slug}`);
+ *   // Modify page content or metadata
+ *   ctx.page.frontMatter.customField = 'processed';
+ * };
+ * ```
+ */
+export interface PageContext {
+    /** The page model being processed */
+    page: PageModel;
+    /** The resolved Stati configuration */
+    config: StatiConfig;
+}
+/**
+ * Build lifecycle hooks for customizing the site generation process.
+ * Allows developers to inject custom logic at various stages of the build.
+ *
+ * @example
+ * ```typescript
+ * const hooks: BuildHooks = {
+ *   beforeAll: async (ctx) => {
+ *     console.log('Starting build...');
+ *   },
+ *   beforeRender: async (ctx) => {
+ *     // Add custom data to page context
+ *     ctx.page.frontMatter.buildTime = new Date().toISOString();
+ *   },
+ *   afterAll: async (ctx) => {
+ *     console.log(`Build complete! Generated ${ctx.pages.length} pages.`);
+ *   }
+ * };
+ * ```
+ */
+export interface BuildHooks {
+    /** Called before starting the build process */
+    beforeAll?: (ctx: BuildContext) => Promise<void> | void;
+    /** Called after completing the build process */
+    afterAll?: (ctx: BuildContext) => Promise<void> | void;
+    /** Called before rendering each individual page */
+    /** Called before rendering each individual page */
+    beforeRender?: (ctx: PageContext) => Promise<void> | void;
+    /** Called after rendering each individual page */
+    afterRender?: (ctx: PageContext) => Promise<void> | void;
+}
+/**
+ * Collection aggregation data available to index page templates.
+ * Provides access to child pages and collection metadata for content listing.
+ */
+export interface CollectionData {
+    /** All pages in the current collection */
+    pages: PageModel[];
+    /** Direct child pages of the collection */
+    children: PageModel[];
+    /** Recent pages sorted by publishedAt (most recent first) */
+    recentPages: PageModel[];
+    /** Pages grouped by tags for aggregation */
+    pagesByTag: Record<string, PageModel[]>;
+    /** Collection metadata */
+    metadata: {
+        /** Total number of pages in collection */
+        totalPages: number;
+        /** Whether collection has child pages */
+        hasChildren: boolean;
+        /** Path of the collection */
+        collectionPath: string;
+        /** Name of the collection (derived from path) */
+        collectionName: string;
+    };
+}
+/**
+ * Template rendering context passed to Eta layouts.
+ * Contains all data available to templates during rendering.
+ */
+export interface TemplateContext {
+    /** Site configuration and metadata */
+    site: SiteConfig;
+    /** Current page data including frontmatter and content */
+    page: {
+        path: string;
+        content: string;
+        [key: string]: unknown;
+    };
+    /** Rendered markdown content */
+    content: string;
+    /** Site navigation tree */
+    navigation: NavNode[];
+    /** Discovered partials from underscore folders in hierarchy */
+    partials: Record<string, string>;
+    /** Collection data for index pages (only available on collection index pages) */
+    collection?: CollectionData;
+}
+/**
+ * Represents a single page in the static site.
+ * Contains all metadata, content, and URL information for a page.
+ *
+ * @example
+ * ```typescript
+ * const page: PageModel = {
+ *   slug: 'my-first-post',
+ *   url: '/blog/my-first-post',
+ *   sourcePath: '/content/blog/my-first-post.md',
+ *   frontMatter: {
+ *     title: 'My First Post',
+ *     tags: ['intro', 'blog']
+ *   },
+ *   content: '<p>Hello world!</p>',
+ *   publishedAt: new Date('2024-01-01')
+ * };
+ * ```
+ */
+export interface PageModel {
+    /** URL-friendly identifier for the page */
+    slug: string;
+    /** Full URL path for the page */
+    url: string;
+    /** Absolute path to the source content file */
+    sourcePath: string;
+    /** Parsed front matter metadata */
+    frontMatter: FrontMatter;
+    /** Rendered HTML content */
+    content: string;
+    /** Publication date (parsed from front matter or file stats) */
+    publishedAt?: Date;
+}
+/**
+ * Statistics collected during the build process.
+ * Provides useful metrics about the site generation.
+ *
+ * @example
+ * ```typescript
+ * const stats: BuildStats = {
+ *   totalPages: 15,
+ *   assetsCount: 8,
+ *   buildTimeMs: 1250,
+ *   outputSizeBytes: 2048576,
+ *   cacheHits: 5,
+ *   cacheMisses: 10
+ * };
+ * ```
+ */
+export interface BuildStats {
+    /** Total number of pages processed */
+    totalPages: number;
+    /** Number of static assets copied */
+    assetsCount: number;
+    /** Total build time in milliseconds */
+    buildTimeMs: number;
+    /** Total size of output directory in bytes */
+    outputSizeBytes: number;
+    /** Number of cache hits (if caching enabled) */
+    cacheHits?: number;
+    /** Number of cache misses (if caching enabled) */
+    cacheMisses?: number;
+}
+/**
+ * Navigation node representing a page or collection in the site hierarchy.
+ * Provides structured navigation data for templates.
+ *
+ * @example
+ * ```typescript
+ * const navNode: NavNode = {
+ *   title: 'Blog',
+ *   url: '/blog',
+ *   path: '/blog',
+ *   order: 1,
+ *   children: [
+ *     {
+ *       title: 'My First Post',
+ *       url: '/blog/my-first-post',
+ *       path: '/blog/my-first-post',
+ *       order: 1,
+ *       publishedAt: new Date('2024-01-01')
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+export interface NavNode {
+    /** Display title for the navigation item */
+    title: string;
+    /** URL path for the navigation item */
+    url: string;
+    /** File system path (for organizing hierarchy) */
+    path: string;
+    /** Numeric order for sorting */
+    order?: number;
+    /** Publication date for sorting */
+    publishedAt?: Date;
+    /** Child navigation nodes (for collections/directories) */
+    children?: NavNode[];
+    /** Whether this node represents a collection/directory */
+    isCollection?: boolean;
+}
+/**
+ * Front matter metadata extracted from content files.
+ * Contains page-specific configuration and metadata in YAML format.
+ *
+ * @example
+ * ```typescript
+ * const frontMatter: FrontMatter = {
+ *   title: 'Getting Started with Stati',
+ *   description: 'A comprehensive guide to static site generation',
+ *   tags: ['tutorial', 'documentation'],
+ *   layout: 'post',
+ *   order: 1,
+ *   publishedAt: '2024-01-01',
+ *   ttlSeconds: 3600,
+ *   draft: false
+ * };
+ * ```
+ */
+export interface FrontMatter {
+    /** Page title for SEO and display */
+    title?: string;
+    /** Page description for SEO and meta tags */
+    description?: string;
+    /** Array of tags for categorization */
+    tags?: string[];
+    /** Template layout to use for rendering */
+    layout?: string;
+    /** Numeric order for sorting (useful for navigation) */
+    order?: number;
+    /** Publication date as ISO string */
+    publishedAt?: string;
+    /** Custom cache TTL in seconds (overrides global ISG settings) */
+    ttlSeconds?: number;
+    /** Custom max age cap in days (overrides global ISG settings) */
+    maxAgeCapDays?: number;
+    /** Whether the page is a draft (excludes from build) */
+    draft?: boolean;
+    /** Additional custom properties */
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@stati/core",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "default": "./dist/config/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "eta": "^3.5.0",
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.2.0",
+    "gray-matter": "^4.0.3",
+    "markdown-it": "^14.1.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/markdown-it": "^14.1.2"
+  }
+}