@askrjs/askr 0.0.52 → 0.0.53

package/dist/ssg/index.d.ts

@@ -1,4 +1,252 @@
-import { DocumentRenderArgs, DocumentRenderContext, DocumentRenderer } from "../common/ssr.js";
-import { DiscoveredResources, RouteConfig, RouteRenderReason, RouteRenderResult, RouteRenderStatus, SSGGenerateOptions, SSGMetadata, SSGMode, SSGOptions, SSGResult } from "./types.js";
-import { createStaticGen } from "./create-static-gen.js";
-export { type DiscoveredResources, type DocumentRenderArgs, type DocumentRenderContext, type DocumentRenderer, type RouteConfig, type RouteRenderReason, type RouteRenderResult, type RouteRenderStatus, type SSGGenerateOptions, type SSGMetadata, type SSGMode, type SSGOptions, type SSGResult, createStaticGen };
+import { c as RenderableChild, d as DocumentRenderContext, f as DocumentRenderer, s as ComponentFunction, u as DocumentRenderArgs } from "../control-BQvNVfAd.js";
+import { E as RouteOptions, O as RoutePathParams, P as RouteRegistry, b as RouteHandler, k as RoutePolicy } from "../router-CeYvjj5_.js";
+import { AuthRequirement } from "@askrjs/auth";
+//#region src/ssg/types.d.ts
+type SSGMode = 'full' | 'incremental';
+type RouteRenderStatus = 'success' | 'error' | 'skipped' | 'removed';
+type RouteRenderReason = 'full' | 'changed-key' | 'changed-route' | 'new-route' | 'no-keys' | 'unchanged' | 'deleted' | 'runtime-only';
+type RouteConfigParams<Path extends string> = string extends Path ? Record<string, string> : RoutePathParams<Path>;
+type RouteComponentProps<Path extends string> = RouteConfigParams<Path> & Record<string, unknown>;
+type StaticRouteComponent<Path extends string> = (props: RouteComponentProps<Path>, context?: Parameters<ComponentFunction>[1]) => RenderableChild;
+/**
+ * Route config accepted by SSG.
+ *
+ * `handler` is preferred and matches router/SSR naming.
+ * `component` is kept for compatibility and is normalized to `handler`.
+ */
+interface RouteConfig<Path extends string = string> {
+  /** URL path to generate (e.g., "/blog/post-1", "/") */
+  path: Path;
+  /** Route handler compatible with router/SSR */
+  handler?: RouteHandler;
+  /** Backward-compatible alias for handler */
+  component?: StaticRouteComponent<Path>;
+  /** Optional base props merged with route params during render */
+  props?: Record<string, unknown>;
+  /** Optional namespace for router compatibility */
+  namespace?: string;
+  /** Routes with request-auth requirements are runtime-only by default. */
+  auth?: AuthRequirement;
+  /** Advanced runtime access checks disable prerendering by default */
+  policies?: readonly RoutePolicy[];
+  /** Optional path parameter map for template paths like "/blog/{slug}" */
+  params?: RouteConfigParams<Path>;
+  /** Optional explicit invalidation keys for incremental generation */
+  invalidationKeys?: string[];
+  /** Route loader resolved completely before static HTML is rendered. */
+  loader?: RouteOptions['loader'];
+  /**
+   * SSG entry generator for parameterized routes.
+   *
+   * Return one param map per page to be generated.  The path template is
+   * expanded with each map to produce a concrete URL, e.g.:
+   *
+   * ```ts
+   * route('/posts/{slug}', PostPage, {
+   *   entries: async () => getPosts().map(p => ({ slug: p.slug })),
+   * });
+   * ```
+   */
+  entries?: () => Array<RouteConfigParams<Path>> | Promise<Array<RouteConfigParams<Path>>>;
+}
+interface SSGBaseOptions {
+  /** Output directory for generated HTML files */
+  outputDir: string;
+  /** Optional seed for deterministic rendering */
+  seed?: number;
+  /** Optional override data for resources (route-keyed) */
+  dataOverrides?: Record<string, unknown>;
+  /** Optional document wrapper for full HTML output */
+  document?: DocumentRenderer;
+  /** Static files or directories published with the generated routes. */
+  assets?: readonly SSGAssetSource[];
+  /** Optional concurrency limit for rendering (default: 1) */
+  concurrency?: number;
+  /** Preferred render parallelism. `'auto'` resolves from the host machine. */
+  parallelism?: number | 'auto';
+}
+interface SSGAssetSource {
+  /** Source file or directory. Relative paths resolve from the current working directory. */
+  from: string;
+  /** Destination relative to outputDir. Defaults to the source basename. */
+  to?: string;
+}
+/** Options for createStaticGen */
+type SSGOptions<TRoutes extends readonly RouteConfig[] = RouteConfig[]> = SSGBaseOptions & ({
+  /** Routes to generate. Prefer `registry` when routes are already defined through the router DSL. */routes: TRoutes;
+  registry?: never;
+} | {
+  /** Explicit route registry captured with `createRouteRegistry()`. */registry: RouteRegistry;
+  routes?: never;
+});
+/** Options for a single generation run */
+interface SSGGenerateOptions {
+  /** Generation mode */
+  mode?: SSGMode;
+  /** Changed invalidation keys for incremental runs */
+  changedKeys?: string[];
+  /** Changed concrete route paths for incremental runs */
+  changedRoutes?: string[];
+  /** Force a full rebuild even when incremental mode was requested */
+  forceFull?: boolean;
+}
+/** Result of rendering a single route */
+interface RouteRenderResult {
+  /** URL path */
+  path: string;
+  /** Output file path relative to outputDir */
+  filePath: string;
+  /** Generated HTML content */
+  html: string;
+  /** File size in bytes */
+  fileSize: number;
+  /** Render duration in milliseconds */
+  renderDuration: number;
+  /** Number of resources discovered and rendered */
+  resourceCount: number;
+  /** Render or generation status */
+  status: RouteRenderStatus;
+  /** Why this route was rendered, skipped, or removed */
+  reason: RouteRenderReason;
+  /** Whether the output file was written during this run */
+  written: boolean;
+  /** Error message if rendering failed */
+  error?: string;
+}
+/** Overall result from SSG generation */
+interface SSGResult {
+  /** ISO timestamp of generation */
+  generatedAt: string;
+  /** Total number of routes processed */
+  totalRoutes: number;
+  /** Number of successfully generated routes */
+  successful: number;
+  /** Number of failed routes */
+  failed: number;
+  /** Total generation duration in milliseconds */
+  totalDuration: number;
+  /** Effective generation mode */
+  mode: SSGMode;
+  /** Number of routes rendered during this run */
+  rebuilt: number;
+  /** Number of current routes skipped as unchanged */
+  skipped: number;
+  /** Number of stale routes removed from output */
+  removed: number;
+  /** Number of rendered routes whose HTML bytes were unchanged */
+  cacheHits: number;
+  /** Invalidation keys applied to this run */
+  invalidatedKeys: string[];
+  /** Concrete route paths applied to this run */
+  invalidatedRoutes: string[];
+  /** Per-route results */
+  routes: RouteRenderResult[];
+}
+/** Metadata to write to metadata.json */
+interface SSGMetadata extends Record<string, unknown> {
+  /** ISO timestamp of generation */
+  generatedAt: string;
+  /** Total number of routes processed */
+  totalRoutes: number;
+  /** Number of successfully generated routes */
+  successful: number;
+  /** Number of failed routes */
+  failed: number;
+  /** Total generation duration in milliseconds */
+  totalDuration: number;
+  /** Effective generation mode */
+  mode: SSGMode;
+  /** Number of routes rendered during this run */
+  rebuilt: number;
+  /** Number of current routes skipped as unchanged */
+  skipped: number;
+  /** Number of stale routes removed from output */
+  removed: number;
+  /** Number of rendered routes whose HTML bytes were unchanged */
+  cacheHits: number;
+  /** Invalidation keys applied to this run */
+  invalidatedKeys: string[];
+  /** Concrete route paths applied to this run */
+  invalidatedRoutes: string[];
+  /** Per-route details */
+  routes: Array<{
+    /** URL path */path: string; /** Output file path relative to outputDir */
+    filePath: string; /** File size in bytes */
+    fileSize: number; /** Render duration in milliseconds */
+    renderDuration: number; /** Number of resources discovered and rendered */
+    resourceCount: number; /** Render or generation status */
+    status: RouteRenderStatus; /** Why this route was rendered, skipped, or removed */
+    reason: RouteRenderReason; /** Whether the output file was written during this run */
+    written: boolean; /** Error message if rendering failed */
+    error?: string;
+  }>;
+}
+/** Resource discovery result for a single route */
+interface DiscoveredResources {
+  [key: string]: {
+    count: number;
+    dependencies: string[];
+  };
+}
+//#endregion
+//#region src/ssg/create-static-gen.d.ts
+type AnyRouteConfig = RouteConfig<string>;
+type StrictRouteConfig<TRoute extends AnyRouteConfig> = Omit<TRoute, 'params' | 'entries'> & {
+  params?: RouteConfig<TRoute['path']>['params'];
+  entries?: RouteConfig<TRoute['path']>['entries'];
+};
+type StrictRouteConfigs<TRoutes extends readonly AnyRouteConfig[]> = { [TIndex in keyof TRoutes]: TRoutes[TIndex] extends AnyRouteConfig ? StrictRouteConfig<TRoutes[TIndex]> : never };
+type StaticGenRouteSource<TRoutes extends readonly AnyRouteConfig[]> = {
+  routes: TRoutes & StrictRouteConfigs<TRoutes>;
+  registry?: never;
+} | {
+  registry: RouteRegistry;
+  routes?: never;
+};
+/**
+ * Create a Static Site Generator
+ *
+ * Usage:
+ * ```ts
+ * const ssg = createStaticGen({
+ *   routes: [
+ *     { path: '/', component: HomePage },
+ *     { path: '/about', component: AboutPage },
+ *   ],
+ *   outputDir: './dist',
+ *   dataOverrides: {
+ *     '/api/posts': { posts: [...] }
+ *   }
+ * });
+ *
+ * const result = await ssg.generate();
+ * console.log(`Generated ${result.successful}/${result.totalRoutes} routes`);
+ * ```
+ */
+declare function createStaticGen<const TRoutes extends readonly AnyRouteConfig[]>(options: Omit<SSGOptions<TRoutes>, 'routes' | 'registry'> & StaticGenRouteSource<TRoutes>): {
+  /**
+   * Generate static HTML for all routes
+   * Writes to outputDir with metadata.json
+   * Returns detailed results
+   */
+  generate(generateOptions?: SSGGenerateOptions): Promise<SSGResult>;
+  /**
+   * Get effective config in a serializable form for diagnostics.
+   */
+  getConfig(): {
+    routeCount: number;
+    outputDir: string;
+    seed: number;
+    concurrency: number;
+    parallelism: number;
+    hasDataOverrides: boolean;
+    assetCount: number;
+  };
+  /**
+   * Get the last generation result
+   * Returns null if generate() hasn't been called
+   */
+  getResult(): SSGResult | null;
+};
+//#endregion
+export { type DiscoveredResources, type DocumentRenderArgs, type DocumentRenderContext, type DocumentRenderer, type RouteConfig, type RouteRenderReason, type RouteRenderResult, type RouteRenderStatus, type SSGAssetSource, type SSGGenerateOptions, type SSGMetadata, type SSGMode, type SSGOptions, type SSGResult, createStaticGen };