npm - create-jen-app - Versions diffs - 1.2.1 → 1.2.3 - Mend

create-jen-app 1.2.1 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (589) hide show

package/templates/static/lib/core/config.d.ts CHANGED Viewed

@@ -1,53 +1,220 @@
+/**
+ * Rendering mode for routes in the application.
+ *
+ * - "ssr": Server-side rendering - renders on each request, optimal for dynamic content
+ * - "ssg": Static site generation - pre-renders routes at build time, fastest for static content
+ * - "isr": Incremental static regeneration - revalidates static pages on demand
+ * - "ppr": Partial pre-rendering - mixes static and dynamic content
+ */
 export type RenderMode = "ssr" | "ssg" | "isr" | "ppr";
+/**
+ * Complete configuration schema for the Jen.js framework.
+ * This type defines all available configuration options for a Jen.js application.
+ * Applications must provide a jen.config.js or jen.config.ts file exporting a FrameworkConfig object.
+ *
+ * @example
+ * ```typescript
+ * import type { FrameworkConfig } from "jenjs";
+ * export default {
+ *   siteDir: "src",
+ *   distDir: "dist",
+ *   routes: {
+ *     fileExtensions: [".tsx", ".ts", ".jsx", ".js"],
+ *     routeFilePattern: /^\(([^)]+)\)/,
+ *     enableIndexFallback: true
+ *   },
+ *   // ... rest of config
+ * } as FrameworkConfig;
+ * ```
+ */
 export type FrameworkConfig = {
-    siteDir: string;
-    distDir: string;
-    routes: {
-        fileExtensions: string[];
-        routeFilePattern: RegExp;
-        enableIndexFallback: boolean;
-    };
-    rendering: {
-        defaultMode: RenderMode;
-        defaultRevalidateSeconds: number;
-    };
-    inject: {
-        head: string[];
-        bodyEnd: string[];
-    };
-    css: {
-        globalScss: string;
-        criticalBudget?: number;
-        extractCritical?: boolean;
-    };
-    assets: {
-        publicDir: string;
-        cacheControl: string;
-        hashLength?: number;
-    };
-    server: {
-        port: number;
-        hostname: string;
-    };
-    build?: {
-        minifyHtml?: boolean;
-        minifyCss?: boolean;
-        minifyJs?: boolean;
-        hashAssets?: boolean;
-        generateManifest?: boolean;
-        generateSitemap?: boolean;
-        cacheDir?: string;
-        incrementalBuild?: boolean;
-        sourceMap?: boolean;
-    };
-    dev?: {
-        enableSSR?: boolean;
-        liveReload?: boolean;
-        port?: number;
-    };
-    seo?: {
-        generateRobotsTxt?: boolean;
-        generateSitemap?: boolean;
-        sitemapBaseUrl?: string;
-    };
+  /**
+   * Root directory where route files, components, and assets are located.
+   * Relative to project root (CWD). Example: "src", "site", "pages".
+   */
+  siteDir: string;
+  /**
+   * Output directory for build artifacts (compiled HTML, CSS, JavaScript).
+   * Relative to project root. Created automatically if it doesn't exist.
+   */
+  distDir: string;
+  /**
+   * Route discovery and file pattern configuration.
+   */
+  routes: {
+    /**
+     * File extensions to treat as route files.
+     * Examples: [".tsx", ".ts", ".jsx", ".js"]
+     */
+    fileExtensions: string[];
+    /**
+     * RegExp pattern to match route file names and extract route segment.
+     * Example: /^\(([^)]+)\)/ matches "(home).tsx" and captures "home"
+     */
+    routeFilePattern: RegExp;
+    /**
+     * Whether to serve /dir/index.html when accessing /dir/
+     */
+    enableIndexFallback: boolean;
+  };
+  /**
+   * Default rendering behavior for all routes.
+   */
+  rendering: {
+    /**
+     * Default render mode if not specified in route module exports.
+     */
+    defaultMode: RenderMode;
+    /**
+     * Default revalidation interval in seconds for ISR mode.
+     * Used if route doesn't specify custom revalidateSeconds.
+     */
+    defaultRevalidateSeconds: number;
+  };
+  /**
+   * HTML content to inject into every rendered page.
+   */
+  inject: {
+    /**
+     * Array of HTML strings to inject into <head>.
+     * Examples: meta tags, link tags, analytics scripts
+     */
+    head: string[];
+    /**
+     * Array of HTML strings to inject before closing </body>.
+     * Examples: analytics, logging scripts
+     */
+    bodyEnd: string[];
+  };
+  /**
+   * CSS and SCSS compilation configuration.
+   */
+  css: {
+    /**
+     * Path to global SCSS file to compile to styles.css.
+     * Relative to siteDir. Example: "styles/global.scss"
+     */
+    globalScss: string;
+    /**
+     * Maximum file size in bytes for critical CSS extraction.
+     * CSS larger than this may not be inlined in <head>.
+     */
+    criticalBudget?: number;
+    /**
+     * Whether to extract and inline critical CSS for above-the-fold content.
+     */
+    extractCritical?: boolean;
+  };
+  /**
+   * Static asset serving configuration.
+   */
+  assets: {
+    /**
+     * Directory containing public assets that should be copied to dist as-is.
+     * Relative to siteDir. Example: "public", "static"
+     */
+    publicDir: string;
+    /**
+     * HTTP Cache-Control header value for assets.
+     * Example: "public, max-age=31536000" for long-term caching
+     */
+    cacheControl: string;
+    /**
+     * Length of hash suffix for versioned asset filenames.
+     * Used for cache-busting. Example: 8 produces "app.a1b2c3d4.js"
+     */
+    hashLength?: number;
+  };
+  /**
+   * HTTP server configuration.
+   */
+  server: {
+    /**
+     * Port number for the development server.
+     * Example: 3000, 8080
+     */
+    port: number;
+    /**
+     * Hostname to bind the development server to.
+     * Example: "localhost", "0.0.0.0", "127.0.0.1"
+     */
+    hostname: string;
+  };
+  /**
+   * Optional build-time optimizations.
+   */
+  build?: {
+    /**
+     * Whether to minify HTML output in production builds.
+     */
+    minifyHtml?: boolean;
+    /**
+     * Whether to minify CSS output in production builds.
+     */
+    minifyCss?: boolean;
+    /**
+     * Whether to minify JavaScript output in production builds.
+     */
+    minifyJs?: boolean;
+    /**
+     * Whether to hash asset filenames for cache-busting.
+     * Example: "app.abc123.js" instead of "app.js"
+     */
+    hashAssets?: boolean;
+    /**
+     * Whether to generate an asset manifest JSON file for reverse lookups.
+     */
+    generateManifest?: boolean;
+    /**
+     * Whether to generate a sitemap.xml for SEO.
+     */
+    generateSitemap?: boolean;
+    /**
+     * Directory for storing build cache to enable incremental builds.
+     */
+    cacheDir?: string;
+    /**
+     * Whether to perform incremental builds (only rebuild changed files).
+     */
+    incrementalBuild?: boolean;
+    /**
+     * Whether to generate source maps for debugging in production.
+     */
+    sourceMap?: boolean;
+  };
+  /**
+   * Optional development server settings.
+   */
+  dev?: {
+    /**
+     * Whether to enable server-side rendering in development mode.
+     */
+    enableSSR?: boolean;
+    /**
+     * Whether to enable live reload on file changes.
+     */
+    liveReload?: boolean;
+    /**
+     * Custom port for development server (overrides server.port).
+     */
+    port?: number;
+  };
+  /**
+   * Optional SEO and search engine optimization settings.
+   */
+  seo?: {
+    /**
+     * Whether to automatically generate robots.txt.
+     */
+    generateRobotsTxt?: boolean;
+    /**
+     * Whether to automatically generate sitemap.xml.
+     */
+    generateSitemap?: boolean;
+    /**
+     * Base URL for sitemap entries.
+     * Example: "https://example.com"
+     */
+    sitemapBaseUrl?: string;
+  };
 };

package/templates/static/lib/core/http.d.ts CHANGED Viewed

@@ -1,3 +1,56 @@
 import type { IncomingMessage } from "node:http";
-export declare function parseCookies(req: IncomingMessage): Record<string, string>;
-export declare function headersToObject(headers: IncomingMessage["headers"]): Record<string, string>;
+/**
+ * Parses the HTTP Cookie header into an object of name-value pairs.
+ *
+ * Cookie format (RFC 6265):
+ * - Multiple cookies separated by semicolons
+ * - Each cookie is name=value with optional whitespace
+ * - Cookie values are URL-encoded and must be decoded
+ *
+ * Edge cases handled:
+ * - Missing or empty Cookie header returns empty object
+ * - Whitespace is trimmed from names and values
+ * - Values may contain equals signs (split only on first =)
+ * - Empty names or values are filtered out
+ * - Values are URL-decoded to handle special characters
+ *
+ * @param req Node.js IncomingMessage with headers property
+ *
+ * @returns Object with cookie names as keys and decoded values
+ *
+ * @example
+ * // Header: "sessionId=abc123; theme=dark; path=/admin"
+ * // Returns: { sessionId: "abc123", theme: "dark", path: "/admin" }
+ *
+ * // Header missing or empty
+ * // Returns: {}
+ */
+export declare function parseCookies(
+  req: IncomingMessage,
+): Record<string, string>;
+/**
+ * Converts Node.js headers object to a flat string-valued object.
+ *
+ * Header normalization:
+ * - Node.js headers may have array values (for multiple headers with same name)
+ * - Arrays are joined with comma-space to follow HTTP spec (RFC 2822)
+ * - Non-array string values are kept as-is
+ * - Header names are already lowercased by Node.js
+ *
+ * Motivation:
+ * Application code typically expects headers as a flat object with string values,
+ * not Node.js's mixed types. This normalizes the data structure for consistency.
+ *
+ * @param headers The headers object from IncomingMessage.headers
+ *
+ * @returns Flat object with header names (lowercase) as keys and string values
+ *
+ * @example
+ * // Input (from Node.js):
+ * { accept: "text/html", "accept-encoding": ["gzip", "deflate"], "content-type": "application/json" }
+ * // Output:
+ * { accept: "text/html", "accept-encoding": "gzip, deflate", "content-type": "application/json" }
+ */
+export declare function headersToObject(
+  headers: IncomingMessage["headers"],
+): Record<string, string>;

package/templates/static/lib/core/http.js CHANGED Viewed

@@ -15,28 +15,74 @@
  * You should have received a copy of the GNU General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
+/**
+ * Parses the HTTP Cookie header into an object of name-value pairs.
+ *
+ * Cookie format (RFC 6265):
+ * - Multiple cookies separated by semicolons
+ * - Each cookie is name=value with optional whitespace
+ * - Cookie values are URL-encoded and must be decoded
+ *
+ * Edge cases handled:
+ * - Missing or empty Cookie header returns empty object
+ * - Whitespace is trimmed from names and values
+ * - Values may contain equals signs (split only on first =)
+ * - Empty names or values are filtered out
+ * - Values are URL-decoded to handle special characters
+ *
+ * @param req Node.js IncomingMessage with headers property
+ *
+ * @returns Object with cookie names as keys and decoded values
+ *
+ * @example
+ * // Header: "sessionId=abc123; theme=dark; path=/admin"
+ * // Returns: { sessionId: "abc123", theme: "dark", path: "/admin" }
+ *
+ * // Header missing or empty
+ * // Returns: {}
+ */
 export function parseCookies(req) {
-    const cookie = req.headers.cookie;
-    if (!cookie)
-        return {};
-    const out = {};
-    for (const part of cookie.split(";")) {
-        const [k, ...rest] = part.trim().split("=");
-        const trimmedName = k.trim();
-        const trimmedValue = rest.join("=").trim();
-        if (trimmedName && trimmedValue) {
-            out[trimmedName] = decodeURIComponent(trimmedValue);
-        }
+  const cookie = req.headers.cookie;
+  if (!cookie) return {};
+  const out = {};
+  for (const part of cookie.split(";")) {
+    const [k, ...rest] = part.trim().split("=");
+    const trimmedName = k.trim();
+    const trimmedValue = rest.join("=").trim();
+    if (trimmedName && trimmedValue) {
+      out[trimmedName] = decodeURIComponent(trimmedValue);
     }
-    return out;
+  }
+  return out;
 }
+/**
+ * Converts Node.js headers object to a flat string-valued object.
+ *
+ * Header normalization:
+ * - Node.js headers may have array values (for multiple headers with same name)
+ * - Arrays are joined with comma-space to follow HTTP spec (RFC 2822)
+ * - Non-array string values are kept as-is
+ * - Header names are already lowercased by Node.js
+ *
+ * Motivation:
+ * Application code typically expects headers as a flat object with string values,
+ * not Node.js's mixed types. This normalizes the data structure for consistency.
+ *
+ * @param headers The headers object from IncomingMessage.headers
+ *
+ * @returns Flat object with header names (lowercase) as keys and string values
+ *
+ * @example
+ * // Input (from Node.js):
+ * { accept: "text/html", "accept-encoding": ["gzip", "deflate"], "content-type": "application/json" }
+ * // Output:
+ * { accept: "text/html", "accept-encoding": "gzip, deflate", "content-type": "application/json" }
+ */
 export function headersToObject(headers) {
-    const out = {};
-    for (const [k, v] of Object.entries(headers)) {
-        if (Array.isArray(v))
-            out[k] = v.join(", ");
-        else if (typeof v === "string")
-            out[k] = v;
-    }
-    return out;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (Array.isArray(v)) out[k] = v.join(", ");
+    else if (typeof v === "string") out[k] = v;
+  }
+  return out;
 }

package/templates/static/lib/core/middleware-hooks.d.ts CHANGED Viewed

@@ -1,46 +1,219 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 /**
- * Route middleware context. Available to middleware functions.
+ * Context object passed to route middleware functions.
+ * Provides access to request data and response methods.
+ *
+ * Route middleware executes before the page loader and renderer.
+ * Middleware can:
+ * - Check authentication and authorization
+ * - Validate or transform request data
+ * - Set response headers or status codes
+ * - Attach data for use in loaders and page components
+ * - Short-circuit rendering by calling redirect() or json()
+ *
+ * Execution flow:
+ * 1. Route middleware array executes sequentially
+ * 2. Each middleware receives this context
+ * 3. Middleware can call next() implicitly by returning/not throwing
+ * 4. Early termination via redirect() or json() throws a sentinel error
+ * 5. After middleware, the loader runs with middleware.data pre-populated
+ *
+ * Example use cases:
+ * - Authentication: Check user session, throw redirect to login if needed
+ * - Data enrichment: Populate ctx.data with user info for the page
+ * - Response control: Set custom headers, status codes, CORS headers
+ * - Request validation: Validate params/query, return error JSON if invalid
  */
 export interface RouteMiddlewareContext {
-    req: IncomingMessage;
-    res: ServerResponse;
-    url: URL;
-    params: Record<string, string>;
-    query: Record<string, string>;
-    headers: Record<string, string>;
-    cookies: Record<string, string>;
-    data?: Record<string, any>;
-    status: (code: number) => RouteMiddlewareContext;
-    setHeader: (key: string, value: string) => RouteMiddlewareContext;
-    redirect: (url: string, statusCode?: number) => never;
-    json: (data: any, statusCode?: number) => never;
+  /**
+   * Node.js IncomingMessage with request method, URL, headers, etc.
+   * Direct access for advanced use cases not covered by the context.
+   */
+  req: IncomingMessage;
+  /**
+   * Node.js ServerResponse for sending responses.
+   * Methods status(), setHeader(), redirect(), and json() wrap this.
+   */
+  res: ServerResponse;
+  /**
+   * Parsed URL object with pathname, searchParams, host, etc.
+   * Same URL available in LoaderContext; middleware and loader see the same URL.
+   */
+  url: URL;
+  /**
+   * Route parameters extracted from the URL path by route matching.
+   * For route "/posts/:id" matching "/posts/42", yields { id: "42" }.
+   */
+  params: Record<string, string>;
+  /**
+   * Query string parameters from the URL search string.
+   * For "/search?q=test&limit=10", yields { q: "test", limit: "10" }.
+   */
+  query: Record<string, string>;
+  /**
+   * HTTP request headers as a normalized object.
+   * Keys are lowercase; values are strings or comma-separated lists.
+   */
+  headers: Record<string, string>;
+  /**
+   * Parsed HTTP cookies as an object.
+   * Keys are cookie names; values are decoded cookie values.
+   */
+  cookies: Record<string, string>;
+  /**
+   * Data object that middleware can populate.
+   * Data is passed to the loader and page component.
+   * Useful for sharing computed values (user info, locale, etc.) from middleware to components.
+   *
+   * @example
+   * ctx.data.userId = 42;  // Set in auth middleware
+   * ctx.data.locale = 'en'; // Set in i18n middleware
+   * // Then in loader and page: function Page({ data }) { ... data.userId ... }
+   */
+  data?: Record<string, any>;
+  /**
+   * Sets the HTTP response status code.
+   * Default is 200 (OK) unless changed by middleware.
+   * Returns this for method chaining.
+   *
+   * @param code HTTP status code (200, 404, 500, etc.)
+   * @returns This context for chaining with other methods
+   *
+   * @example ctx.status(404).json({ error: "Not found" });
+   */
+  status: (code: number) => RouteMiddlewareContext;
+  /**
+   * Sets an HTTP response header.
+   * Multiple calls with the same key overwrite previous values.
+   * Returns this for method chaining.
+   *
+   * @param key Header name (Content-Type, Set-Cookie, etc.)
+   * @param value Header value
+   * @returns This context for chaining
+   *
+   * @example ctx.setHeader("Cache-Control", "no-cache").setHeader("X-Custom", "value");
+   */
+  setHeader: (key: string, value: string) => RouteMiddlewareContext;
+  /**
+   * Sends a redirect response and stops middleware execution.
+   * Sets Location header and sends the response.
+   * Default status code is 302 (temporary redirect); 301 is permanent.
+   *
+   * Throws a sentinel error ("__REDIRECT__") to stop further execution.
+   * This error is caught by executeRouteMiddleware() and not re-thrown.
+   *
+   * @param url Destination URL for the redirect
+   * @param statusCode HTTP status code; defaults to 302 (temporary redirect)
+   * @throws Error with message "__REDIRECT__" to stop execution
+   *
+   * @example
+   * if (!user) ctx.redirect("/login", 302);  // Never returns; throw is implicit
+   */
+  redirect: (url: string, statusCode?: number) => never;
+  /**
+   * Sends a JSON response and stops middleware execution.
+   * Sets Content-Type and sends JSON-stringified data.
+   * Useful for API errors or early JSON responses.
+   *
+   * Throws a sentinel error ("__JSON__") to stop further execution.
+   * This error is caught and not re-thrown.
+   *
+   * @param data Object or value to JSON-encode and send
+   * @param statusCode HTTP status code; defaults to 200 (OK)
+   * @throws Error with message "__JSON__" to stop execution
+   *
+   * @example
+   * if (!params.id) ctx.json({ error: "Missing id" }, 400);  // Never returns
+   */
+  json: (data: any, statusCode?: number) => never;
 }
 /**
- * Route middleware function signature.
- * Return undefined/void to continue to next middleware/page.
- * Call ctx.redirect() or ctx.json() to short-circuit.
+ * Middleware function that executes for a specific route before rendering.
+ *
+ * Signature:
+ * - Accepts RouteMiddlewareContext
+ * - Returns nothing (void or Promise<void>)
+ * - Can be sync or async
+ *
+ * Behavior:
+ * - Return/resolve to continue to next middleware or rendering
+ * - Call ctx.redirect() or ctx.json() to send response and stop
+ * - Throw an error to propagate error to error handler
+ * - Modifying ctx.data shares values with loader and page
+ *
+ * @example
+ * const authMiddleware: RouteMiddleware = async (ctx) => {
+ *   const user = await getUser(ctx.cookies.sessionId);
+ *   if (!user) ctx.redirect("/login");
+ *   ctx.data.user = user;  // Available in loader and page
+ * };
  */
-export type RouteMiddleware = (ctx: RouteMiddlewareContext) => Promise<void> | void;
+export type RouteMiddleware = (
+  ctx: RouteMiddlewareContext,
+) => Promise<void> | void;
 /**
- * Note: Route module types (middleware, hydrate fields) are defined in core/types.ts
- * This module just provides the middleware execution primitives.
+ * Type definitions note:
+ * Route module types (middleware field, hydrate field) are defined in core/types.ts.
+ * This module provides the middleware execution engine and context object.
  */
 /**
- * Create middleware context from request.
- * Called by server before rendering route.
+ * Creates a middleware context object from request data.
+ * Called by the renderer before executing route middleware.
+ *
+ * Initializes:
+ * - All request data (req, res, url, params, query, headers, cookies)
+ * - Empty data object for middleware to populate
+ * - Helper methods (status, setHeader, redirect, json) as chainable methods
+ *
+ * @param opts Configuration with raw request data
+ * @param opts.req Node.js IncomingMessage
+ * @param opts.res Node.js ServerResponse
+ * @param opts.url Parsed URL from request
+ * @param opts.params Route parameters from URL path
+ * @param opts.query Query string parameters
+ * @param opts.headers Normalized headers object
+ * @param opts.cookies Parsed cookies from Cookie header
+ *
+ * @returns Initialized RouteMiddlewareContext ready for middleware execution
  */
 export declare function createRouteMiddlewareContext(opts: {
-    req: IncomingMessage;
-    res: ServerResponse;
-    url: URL;
-    params: Record<string, string>;
-    query: Record<string, string>;
-    headers: Record<string, string>;
-    cookies: Record<string, string>;
+  req: IncomingMessage;
+  res: ServerResponse;
+  url: URL;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
 }): RouteMiddlewareContext;
 /**
- * Execute route middlewares in sequence.
- * If any middleware calls redirect() or json(), it throws and stops execution.
+ * Executes an array of route middleware sequentially for a route.
+ *
+ * Execution model:
+ * 1. Iterates through middlewares in order
+ * 2. Each middleware is awaited (even if synchronous)
+ * 3. Middleware can populate ctx.data for use by loader and page
+ * 4. If middleware calls ctx.redirect() or ctx.json(), error is caught and re-thrown
+ * 5. Other errors are propagated immediately
+ *
+ * Control flow:
+ * - Normal completion: all middlewares finish and function returns
+ * - Early exit: middleware calls ctx.redirect() or ctx.json()
+ * - Error: middleware throws or ctx.redirect()/json() throws sentinel error
+ *
+ * Side effects:
+ * - Response headers, status, and body may be sent by middleware
+ * - ctx.data may be modified by middleware
+ * - Should only be called in server context (SSR); not during SSG build
+ *
+ * @param middlewares Array of middleware functions to execute
+ * @param ctx RouteMiddlewareContext created by createRouteMiddlewareContext()
+ *
+ * @returns Promise that resolves if all middlewares complete normally
+ * @throws Error with message "__REDIRECT__" if middleware calls ctx.redirect()
+ * @throws Error with message "__JSON__" if middleware calls ctx.json()
+ * @throws Error from middleware if it throws
  */
-export declare function executeRouteMiddleware(middlewares: RouteMiddleware[], ctx: RouteMiddlewareContext): Promise<void>;
+export declare function executeRouteMiddleware(
+  middlewares: RouteMiddleware[],
+  ctx: RouteMiddlewareContext,
+): Promise<void>;