@zap-js/client 0.0.2 → 0.0.4

package/dist/router/ssg.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Static Site Generation (SSG) for ZapJS
+ *
+ * Supports generateStaticParams export for pre-rendering dynamic routes at build time.
+ *
+ * Usage in route files:
+ * ```tsx
+ * // routes/posts/[id].tsx
+ * export async function generateStaticParams() {
+ *   const posts = await getPosts();
+ *   return posts.map(post => ({ id: post.id }));
+ * }
+ *
+ * export default function PostPage({ params }: { params: { id: string } }) {
+ *   // ...
+ * }
+ * ```
+ */
+import type { RouteTree, ScannedRoute } from './types.js';
+/**
+ * Static params returned by generateStaticParams
+ */
+export type StaticParams = Record<string, string>;
+/**
+ * Function signature for generateStaticParams export
+ */
+export type GenerateStaticParamsFn = () => Promise<StaticParams[]> | StaticParams[];
+/**
+ * Pre-rendered route information
+ */
+export interface PrerenderedRoute {
+    /** Original route path pattern (e.g., /posts/:id) */
+    pattern: string;
+    /** Concrete path (e.g., /posts/123) */
+    path: string;
+    /** Route params */
+    params: StaticParams;
+    /** File path for the static HTML */
+    outputPath: string;
+}
+/**
+ * SSG manifest written at build time
+ */
+export interface SsgManifest {
+    version: string;
+    generatedAt: string;
+    routes: PrerenderedRoute[];
+}
+/**
+ * Options for SSG generation
+ */
+export interface SsgOptions {
+    /** Output directory for static files */
+    outputDir: string;
+    /** Routes directory */
+    routesDir: string;
+    /** Route tree from scanner */
+    routeTree: RouteTree;
+    /** Whether to generate HTML files (requires renderer) */
+    generateHtml?: boolean;
+}
+/**
+ * Find all routes that have generateStaticParams export
+ */
+export declare function findSsgRoutes(routeTree: RouteTree): ScannedRoute[];
+/**
+ * Convert route pattern to concrete path with params
+ *
+ * @example
+ * buildPath('/posts/:id', { id: '123' }) => '/posts/123'
+ * buildPath('/blog/:slug/*rest', { slug: 'hello', rest: 'a/b' }) => '/blog/hello/a/b'
+ */
+export declare function buildPath(pattern: string, params: StaticParams): string;
+/**
+ * Get output file path for a static route
+ *
+ * @example
+ * getOutputPath('/posts/123', 'dist') => 'dist/posts/123/index.html'
+ * getOutputPath('/', 'dist') => 'dist/index.html'
+ */
+export declare function getOutputPath(path: string, outputDir: string): string;
+/**
+ * Load generateStaticParams from a route file
+ */
+export declare function loadGenerateStaticParams(filePath: string): Promise<GenerateStaticParamsFn | null>;
+/**
+ * Generate static params for all SSG routes
+ */
+export declare function collectStaticParams(ssgRoutes: ScannedRoute[], routesDir: string): Promise<Map<ScannedRoute, StaticParams[]>>;
+/**
+ * Build all pre-rendered routes
+ */
+export declare function buildPrerenderedRoutes(options: SsgOptions): Promise<PrerenderedRoute[]>;
+/**
+ * Write SSG manifest
+ */
+export declare function writeSsgManifest(routes: PrerenderedRoute[], outputDir: string): void;
+/**
+ * Read SSG manifest
+ */
+export declare function readSsgManifest(outputDir: string): SsgManifest | null;
+/**
+ * Main SSG build function
+ *
+ * Called during `zap build` to generate static paths
+ */
+export declare function buildSsg(options: SsgOptions): Promise<SsgManifest>;
+/**
+ * Check if a path is statically generated
+ */
+export declare function isStaticPath(path: string, manifest: SsgManifest): boolean;
+/**
+ * Get static route info for a path
+ */
+export declare function getStaticRoute(path: string, manifest: SsgManifest): PrerenderedRoute | null;

package/dist/router/ssg.js

@@ -0,0 +1,202 @@
+/**
+ * Static Site Generation (SSG) for ZapJS
+ *
+ * Supports generateStaticParams export for pre-rendering dynamic routes at build time.
+ *
+ * Usage in route files:
+ * ```tsx
+ * // routes/posts/[id].tsx
+ * export async function generateStaticParams() {
+ *   const posts = await getPosts();
+ *   return posts.map(post => ({ id: post.id }));
+ * }
+ *
+ * export default function PostPage({ params }: { params: { id: string } }) {
+ *   // ...
+ * }
+ * ```
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+/**
+ * Find all routes that have generateStaticParams export
+ */
+export function findSsgRoutes(routeTree) {
+    return routeTree.routes.filter((route) => route.hasGenerateStaticParams && route.params.length > 0);
+}
+/**
+ * Convert route pattern to concrete path with params
+ *
+ * @example
+ * buildPath('/posts/:id', { id: '123' }) => '/posts/123'
+ * buildPath('/blog/:slug/*rest', { slug: 'hello', rest: 'a/b' }) => '/blog/hello/a/b'
+ */
+export function buildPath(pattern, params) {
+    let path = pattern;
+    // Replace catch-all params (*param or *param?)
+    path = path.replace(/\*(\w+)\??/g, (_, key) => {
+        return params[key] ?? '';
+    });
+    // Replace regular params (:param or :param?)
+    path = path.replace(/:(\w+)\??/g, (_, key) => {
+        return params[key] ?? '';
+    });
+    // Clean up double slashes and trailing slashes
+    path = path.replace(/\/+/g, '/');
+    if (path !== '/' && path.endsWith('/')) {
+        path = path.slice(0, -1);
+    }
+    return path || '/';
+}
+/**
+ * Get output file path for a static route
+ *
+ * @example
+ * getOutputPath('/posts/123', 'dist') => 'dist/posts/123/index.html'
+ * getOutputPath('/', 'dist') => 'dist/index.html'
+ */
+export function getOutputPath(path, outputDir) {
+    if (path === '/') {
+        return join(outputDir, 'index.html');
+    }
+    // Remove leading slash and add index.html
+    const cleanPath = path.replace(/^\//, '');
+    return join(outputDir, cleanPath, 'index.html');
+}
+/**
+ * Load generateStaticParams from a route file
+ */
+export async function loadGenerateStaticParams(filePath) {
+    try {
+        const module = await import(filePath);
+        if (typeof module.generateStaticParams === 'function') {
+            return module.generateStaticParams;
+        }
+        return null;
+    }
+    catch (error) {
+        console.error(`[SSG] Failed to load generateStaticParams from ${filePath}:`, error);
+        return null;
+    }
+}
+/**
+ * Generate static params for all SSG routes
+ */
+export async function collectStaticParams(ssgRoutes, routesDir) {
+    const results = new Map();
+    for (const route of ssgRoutes) {
+        const generateFn = await loadGenerateStaticParams(route.filePath);
+        if (generateFn) {
+            try {
+                const params = await generateFn();
+                results.set(route, params);
+                console.log(`[SSG] ${route.urlPath}: ${params.length} static paths`);
+            }
+            catch (error) {
+                console.error(`[SSG] Error generating params for ${route.urlPath}:`, error);
+                results.set(route, []);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Build all pre-rendered routes
+ */
+export async function buildPrerenderedRoutes(options) {
+    const { outputDir, routeTree } = options;
+    // Find SSG routes
+    const ssgRoutes = findSsgRoutes(routeTree);
+    if (ssgRoutes.length === 0) {
+        console.log('[SSG] No routes with generateStaticParams found');
+        return [];
+    }
+    console.log(`[SSG] Found ${ssgRoutes.length} routes with generateStaticParams`);
+    // Collect static params
+    const paramsMap = await collectStaticParams(ssgRoutes, options.routesDir);
+    // Build pre-rendered routes
+    const prerenderedRoutes = [];
+    for (const [route, paramsList] of paramsMap) {
+        for (const params of paramsList) {
+            const path = buildPath(route.urlPath, params);
+            const outputPath = getOutputPath(path, outputDir);
+            prerenderedRoutes.push({
+                pattern: route.urlPath,
+                path,
+                params,
+                outputPath,
+            });
+        }
+    }
+    console.log(`[SSG] Generated ${prerenderedRoutes.length} static paths`);
+    return prerenderedRoutes;
+}
+/**
+ * Write SSG manifest
+ */
+export function writeSsgManifest(routes, outputDir) {
+    const manifest = {
+        version: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        routes,
+    };
+    const manifestPath = join(outputDir, 'ssg-manifest.json');
+    ensureDir(dirname(manifestPath));
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    console.log(`[SSG] Wrote manifest to ${manifestPath}`);
+}
+/**
+ * Read SSG manifest
+ */
+export function readSsgManifest(outputDir) {
+    const manifestPath = join(outputDir, 'ssg-manifest.json');
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(manifestPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ensure directory exists
+ */
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Main SSG build function
+ *
+ * Called during `zap build` to generate static paths
+ */
+export async function buildSsg(options) {
+    console.log('[SSG] Starting static generation...');
+    // Build pre-rendered routes
+    const routes = await buildPrerenderedRoutes(options);
+    // Write manifest
+    writeSsgManifest(routes, options.outputDir);
+    const manifest = {
+        version: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        routes,
+    };
+    console.log('[SSG] Static generation complete');
+    return manifest;
+}
+/**
+ * Check if a path is statically generated
+ */
+export function isStaticPath(path, manifest) {
+    return manifest.routes.some((route) => route.path === path);
+}
+/**
+ * Get static route info for a path
+ */
+export function getStaticRoute(path, manifest) {
+    return manifest.routes.find((route) => route.path === path) ?? null;
+}

package/dist/router/types.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Route types for ZapJS file-based routing (Next.js style conventions)
+ *
+ * File naming:
+ * - [param].tsx     → /:param (dynamic segment)
+ * - [...slug].tsx   → /*slug (catch-all)
+ * - [[...slug]].tsx → /*slug? (optional catch-all)
+ */
+export type RouteType = 'page' | 'api' | 'layout' | 'root';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+export interface RouteParam {
+    name: string;
+    /** Position in the URL path segments */
+    index: number;
+    /** Whether this is a catch-all param (e.g., [...slug] or [[...slug]]) */
+    catchAll: boolean;
+    /** Whether this param is optional (e.g., [[...slug]]) */
+    optional: boolean;
+}
+export interface ScannedRoute {
+    /** Absolute file path */
+    filePath: string;
+    /** Relative path from routes directory */
+    relativePath: string;
+    /** Generated URL path (e.g., /posts/:id) */
+    urlPath: string;
+    /** Route type */
+    type: RouteType;
+    /** Extracted route parameters */
+    params: RouteParam[];
+    /** For API routes, the HTTP methods exported */
+    methods?: HttpMethod[];
+    /** Parent layout file path (if any) */
+    layoutPath?: string;
+    /** Route group name (from (group) folders) */
+    group?: string;
+    /** Whether this is an index route */
+    isIndex: boolean;
+    /** Whether this route exports an errorComponent */
+    hasErrorComponent?: boolean;
+    /** Export name for the error component (defaults to 'errorComponent') */
+    errorComponentExport?: string;
+    /** Whether this route exports a pendingComponent */
+    hasPendingComponent?: boolean;
+    /** Export name for the pending component */
+    pendingComponentExport?: string;
+    /** Whether this route exports a meta function for head management */
+    hasMeta?: boolean;
+    /** Whether this route exports middleware */
+    hasMiddleware?: boolean;
+    /** Whether this route exports generateStaticParams for SSG pre-rendering */
+    hasGenerateStaticParams?: boolean;
+    /** Route priority score (higher = more specific) */
+    priority?: number;
+}
+export interface LayoutRoute {
+    /** Absolute file path */
+    filePath: string;
+    /** Relative path from routes directory */
+    relativePath: string;
+    /** URL path segment this layout applies to */
+    urlPath: string;
+    /** Child routes */
+    children: (ScannedRoute | LayoutRoute)[];
+    /** Parent layout path (for nested layouts) */
+    parentLayout?: string;
+    /** Directory path this layout is scoped to */
+    scopePath: string;
+}
+export interface RootRoute extends LayoutRoute {
+    type: 'root';
+}
+export interface WebSocketRoute {
+    /** Absolute file path */
+    filePath: string;
+    /** Relative path from routes directory */
+    relativePath: string;
+    /** WebSocket URL path */
+    urlPath: string;
+    /** Route parameters */
+    params: RouteParam[];
+}
+export interface RouteTree {
+    root: RootRoute | null;
+    routes: ScannedRoute[];
+    layouts: LayoutRoute[];
+    apiRoutes: ScannedRoute[];
+    /** WebSocket routes from ws/ folder or WEBSOCKET exports */
+    wsRoutes: WebSocketRoute[];
+}
+export interface ScanOptions {
+    /** Routes directory path */
+    routesDir: string;
+    /** File extensions to consider as routes */
+    extensions?: string[];
+    /** Whether to include API routes */
+    includeApi?: boolean;
+}
+export interface CodegenOptions {
+    /** Output directory for generated files */
+    outputDir: string;
+    /** Route tree to generate from */
+    routeTree: RouteTree;
+    /** Whether to generate React Router compatible output */
+    reactRouter?: boolean;
+}
+export interface WatchOptions extends ScanOptions {
+    /** Callback when routes change */
+    onChange: (tree: RouteTree) => void | Promise<void>;
+    /** Debounce delay in ms */
+    debounce?: number;
+    /** Skip the initial callback on start (useful when routes are already scanned) */
+    skipInitial?: boolean;
+}
+export interface RouteMatch {
+    route: ScannedRoute;
+    params: Record<string, string>;
+}
+export interface RouteManifest {
+    version: string;
+    generatedAt: string;
+    routes: ScannedRoute[];
+    apiRoutes: ScannedRoute[];
+}

package/dist/router/types.js

@@ -0,0 +1,9 @@
+/**
+ * Route types for ZapJS file-based routing (Next.js style conventions)
+ *
+ * File naming:
+ * - [param].tsx     → /:param (dynamic segment)
+ * - [...slug].tsx   → /*slug (catch-all)
+ * - [[...slug]].tsx → /*slug? (optional catch-all)
+ */
+export {};

package/dist/router/watch.d.ts

@@ -0,0 +1,38 @@
+/**
+ * File watcher for route changes
+ *
+ * Uses chokidar to watch for file changes in the routes directory
+ * and triggers route tree regeneration
+ */
+import type { WatchOptions, RouteTree } from './types.js';
+export declare class RouteWatcher {
+    private watcher;
+    private scanner;
+    private options;
+    private debounceTimer;
+    private pendingChange;
+    constructor(options: WatchOptions);
+    /**
+     * Start watching the routes directory
+     */
+    start(): void;
+    /**
+     * Stop watching
+     */
+    stop(): Promise<void>;
+    /**
+     * Get current route tree without triggering callback
+     */
+    scan(): RouteTree;
+    private handleChange;
+    private scheduleCallback;
+    private triggerCallback;
+}
+/**
+ * Convenience function to create and start a watcher
+ */
+export declare function watchRoutes(options: WatchOptions): RouteWatcher;
+/**
+ * Watch routes and regenerate files on changes
+ */
+export declare function watchAndRegenerate(routesDir: string, outputDir: string, options?: Partial<Omit<WatchOptions, 'routesDir' | 'onChange'>>): RouteWatcher;

package/dist/router/watch.js

@@ -0,0 +1,135 @@
+/**
+ * File watcher for route changes
+ *
+ * Uses chokidar to watch for file changes in the routes directory
+ * and triggers route tree regeneration
+ */
+import chokidar from 'chokidar';
+import { extname } from 'path';
+import { RouteScanner } from './scanner.js';
+const DEFAULT_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
+const DEFAULT_DEBOUNCE = 100;
+export class RouteWatcher {
+    constructor(options) {
+        this.watcher = null;
+        this.debounceTimer = null;
+        this.pendingChange = false;
+        this.options = {
+            debounce: DEFAULT_DEBOUNCE,
+            ...options,
+        };
+        this.scanner = new RouteScanner({
+            routesDir: options.routesDir,
+            extensions: options.extensions,
+            includeApi: options.includeApi,
+        });
+    }
+    /**
+     * Start watching the routes directory
+     */
+    start() {
+        if (this.watcher) {
+            return;
+        }
+        const extensions = this.options.extensions ?? DEFAULT_EXTENSIONS;
+        const patterns = extensions.map((ext) => `**/*${ext}`);
+        this.watcher = chokidar.watch(patterns, {
+            cwd: this.options.routesDir,
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 50,
+                pollInterval: 10,
+            },
+        });
+        this.watcher.on('add', (path) => this.handleChange('add', path));
+        this.watcher.on('change', (path) => this.handleChange('change', path));
+        this.watcher.on('unlink', (path) => this.handleChange('unlink', path));
+        this.watcher.on('addDir', (path) => this.handleChange('addDir', path));
+        this.watcher.on('unlinkDir', (path) => this.handleChange('unlinkDir', path));
+        this.watcher.on('error', (error) => {
+            console.error('[RouteWatcher] Error:', error);
+        });
+        // Initial scan (skip if routes are already known)
+        if (!this.options.skipInitial) {
+            this.triggerCallback();
+        }
+    }
+    /**
+     * Stop watching
+     */
+    async stop() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    /**
+     * Get current route tree without triggering callback
+     */
+    scan() {
+        return this.scanner.scan();
+    }
+    handleChange(event, path) {
+        // Skip non-route files
+        const ext = extname(path);
+        const extensions = this.options.extensions ?? DEFAULT_EXTENSIONS;
+        if (event !== 'addDir' && event !== 'unlinkDir' && !extensions.includes(ext)) {
+            return;
+        }
+        // Skip excluded files/directories
+        if (path.includes('/-') || path.startsWith('-')) {
+            return;
+        }
+        this.pendingChange = true;
+        this.scheduleCallback();
+    }
+    scheduleCallback() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            if (this.pendingChange) {
+                this.pendingChange = false;
+                this.triggerCallback();
+            }
+        }, this.options.debounce);
+    }
+    async triggerCallback() {
+        try {
+            const tree = this.scanner.scan();
+            await this.options.onChange(tree);
+        }
+        catch (error) {
+            console.error('[RouteWatcher] Callback error:', error);
+        }
+    }
+}
+/**
+ * Convenience function to create and start a watcher
+ */
+export function watchRoutes(options) {
+    const watcher = new RouteWatcher(options);
+    watcher.start();
+    return watcher;
+}
+/**
+ * Watch routes and regenerate files on changes
+ */
+export function watchAndRegenerate(routesDir, outputDir, options) {
+    // Import dynamically to avoid circular dependency
+    const { generateRouteTree } = require('./codegen.js');
+    return watchRoutes({
+        routesDir,
+        ...options,
+        onChange: (tree) => {
+            generateRouteTree({ outputDir, routeTree: tree });
+            console.log(`[RouteWatcher] Regenerated route tree (${tree.routes.length} routes, ${tree.apiRoutes.length} API routes)`);
+        },
+    });
+}