@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

package/src/utils/deep-merge.js

@@ -1,32 +1,45 @@
+/**
+ * This module contains a simple utility function to merge two objects deeply
+ * @module
+ */
 function isObject(item) {
-  return item && typeof item === "object" && !Array.isArray(item);
+    return item && typeof item === 'object' && !Array.isArray(item);
 }
 function isArray(item) {
-  return Array.isArray(item);
+    return Array.isArray(item);
 }
-function deepMerge(target, source) {
-  if (isArray(target) && isArray(source)) {
-    return [...target, ...source];
-  }
-  if (!isObject(target) || !isObject(source)) {
-    return source;
-  }
-  const output = Object.assign({}, target);
-  for (const key in source) {
-    if (isObject(source[key])) {
-      if (!target[key]) {
-        Object.assign(output, { [key]: source[key] });
-      } else {
-        output[key] = deepMerge(target[key], source[key]);
-      }
-    } else if (isArray(source[key])) {
-      output[key] = [...target[key] || [], ...source[key]];
-    } else if (source[key] !== void 0) {
-      Object.assign(output, { [key]: source[key] });
+/**
+ * Deeply merges two objects or arrays
+ * @function deepMerge
+ * @template T - Type of target object
+ * @template U - Type of source object
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns A new object with merged properties
+ */
+export function deepMerge(target, source) {
+    if (isArray(target) && isArray(source)) {
+        return [...target, ...source];
     }
-  }
-  return output;
+    if (!isObject(target) || !isObject(source)) {
+        return source;
+    }
+    const output = Object.assign({}, target);
+    for (const key in source) {
+        if (isObject(source[key])) {
+            if (!target[key]) {
+                Object.assign(output, { [key]: source[key] });
+            }
+            else {
+                output[key] = deepMerge(target[key], source[key]);
+            }
+        }
+        else if (isArray(source[key])) {
+            output[key] = [...(target[key] || []), ...source[key]];
+        }
+        else if (source[key] !== undefined) {
+            Object.assign(output, { [key]: source[key] });
+        }
+    }
+    return output;
 }
-export {
-  deepMerge
-};

package/src/utils/ecopages-route-info.d.ts

@@ -0,0 +1,26 @@
+import type { EcopagesRouteInfo } from '../types/public-types.js';
+/**
+ * Maps a static-generation or registry route into the public slim route shape.
+ */
+export declare function toEcopagesRouteInfo(route: {
+    pathname: string;
+    params: Record<string, string | string[]>;
+}): EcopagesRouteInfo;
+/**
+ * Flattens string | string[] route params into string values for public APIs.
+ */
+export declare function normalizeRouteParams(params: Record<string, string | string[]>): Record<string, string>;
+type StaticGenerationRouteLister = (input: {
+    runtimeOrigin: string;
+}) => Promise<readonly {
+    pathname: string;
+    params: Record<string, string | string[]>;
+}[]>;
+/**
+ * Resolves {@link EcopagesRouteInfo} entries for app-start and similar consumers.
+ */
+export declare function resolveAppStartRoutes(input: {
+    listStaticGenerationRoutes?: StaticGenerationRouteLister;
+    runtimeOrigin: string;
+}): Promise<EcopagesRouteInfo[]>;
+export {};

package/src/utils/ecopages-route-info.js

@@ -0,0 +1,30 @@
+import { normalizePathname } from './path-pattern.js';
+/**
+ * Maps a static-generation or registry route into the public slim route shape.
+ */
+export function toEcopagesRouteInfo(route) {
+    return {
+        pathname: normalizePathname(route.pathname),
+        params: normalizeRouteParams(route.params),
+    };
+}
+/**
+ * Flattens string | string[] route params into string values for public APIs.
+ */
+export function normalizeRouteParams(params) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(params)) {
+        normalized[key] = Array.isArray(value) ? value.join('/') : value;
+    }
+    return normalized;
+}
+/**
+ * Resolves {@link EcopagesRouteInfo} entries for app-start and similar consumers.
+ */
+export async function resolveAppStartRoutes(input) {
+    if (!input.listStaticGenerationRoutes) {
+        return [];
+    }
+    const routes = await input.listStaticGenerationRoutes({ runtimeOrigin: input.runtimeOrigin });
+    return routes.map(toEcopagesRouteInfo);
+}

package/src/utils/hash.js

@@ -1,7 +1,4 @@
-import { runtimeHash } from "./runtime.js";
-const rapidhash = (content) => {
-  return runtimeHash(content);
-};
-export {
-  rapidhash
+import { runtimeHash } from './runtime.js';
+export const rapidhash = (content) => {
+    return runtimeHash(content);
 };

package/src/utils/html-escaping.d.ts

@@ -5,3 +5,10 @@
  * @returns Escaped attribute-safe string.
  */
 export declare function escapeHtmlAttribute(value: string): string;
+/**
+ * Escapes a string for safe use as XML text content (e.g. `<loc>` values).
+ *
+ * @param value Raw text node value.
+ * @returns Escaped XML-safe string.
+ */
+export declare function escapeXmlText(value: string): string;

package/src/utils/html-escaping.js

@@ -1,6 +1,23 @@
-function escapeHtmlAttribute(value) {
-  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+/**
+ * Escapes a string for safe use inside a double-quoted HTML attribute value.
+ *
+ * @param value Raw attribute value.
+ * @returns Escaped attribute-safe string.
+ */
+export function escapeHtmlAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+/**
+ * Escapes a string for safe use as XML text content (e.g. `<loc>` values).
+ *
+ * @param value Raw text node value.
+ * @returns Escaped XML-safe string.
+ */
+export function escapeXmlText(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
 }
-export {
-  escapeHtmlAttribute
-};

package/src/utils/invariant.js

@@ -1,11 +1,12 @@
-const prefix = "[ecopages]";
-function invariant(condition, message) {
-  if (condition) {
-    return;
-  }
-  const value = message ? `${prefix} ${message}` : `${prefix} An error occurred`;
-  throw new Error(value);
+/**
+ * This module contains a simple utility invariant function that throws an error if the condition is not met
+ * @module
+ */
+const prefix = '[ecopages]';
+export function invariant(condition, message) {
+    if (condition) {
+        return;
+    }
+    const value = message ? `${prefix} ${message}` : `${prefix} An error occurred`;
+    throw new Error(value);
 }
-export {
-  invariant
-};

package/src/utils/locals-utils.js

@@ -1,24 +1,34 @@
-function createRequire(getLocals) {
-  return (keyOrKeys, onMissing) => {
-    const locals = getLocals();
-    if (Array.isArray(keyOrKeys)) {
-      const result = {};
-      for (const key of keyOrKeys) {
-        const value2 = locals[key];
-        if (value2 === void 0 || value2 === null) {
-          throw onMissing();
+/**
+ * Creates a require function for validating and retrieving request locals.
+ * Supports both single key access and multiple keys with type safety.
+ *
+ * @param getLocals - Function that returns the current locals object
+ * @returns A require function that throws the onMissing response if keys are not found
+ *
+ * @example
+ * ```ts
+ * const require = createRequire(() => context.locals);
+ * const userId = require('userId', () => new Response('Unauthorized', { status: 401 }));
+ * ```
+ */
+export function createRequire(getLocals) {
+    return (keyOrKeys, onMissing) => {
+        const locals = getLocals();
+        if (Array.isArray(keyOrKeys)) {
+            const result = {};
+            for (const key of keyOrKeys) {
+                const value = locals[key];
+                if (value === undefined || value === null) {
+                    throw onMissing();
+                }
+                result[key] = value;
+            }
+            return result;
         }
-        result[key] = value2;
-      }
-      return result;
-    }
-    const value = locals[keyOrKeys];
-    if (value === void 0 || value === null) {
-      throw onMissing();
-    }
-    return value;
-  };
+        const value = locals[keyOrKeys];
+        if (value === undefined || value === null) {
+            throw onMissing();
+        }
+        return value;
+    };
 }
-export {
-  createRequire
-};

package/src/utils/parse-cli-args.d.ts

@@ -14,6 +14,7 @@ export type ReturnParseCliArgs = {
     start: boolean;
     dev: boolean;
     force: boolean;
+    serveOnly: boolean;
     port?: number;
     hostname?: string;
     reactFastRefresh?: boolean;

package/src/utils/parse-cli-args.js

@@ -1,65 +1,76 @@
-import { parseArgs } from "node:util";
-import { getRuntimeArgv } from "./runtime.js";
+import { parseArgs } from 'node:util';
+import { getRuntimeArgv } from './runtime.js';
 function getEmbeddedRuntimeCommandOptions() {
-  const isDevelopment = process.env.NODE_ENV === "development";
-  return {
-    preview: false,
-    build: false,
-    start: !isDevelopment,
-    dev: isDevelopment,
-    force: false,
-    port: void 0,
-    hostname: void 0,
-    reactFastRefresh: void 0
-  };
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    return {
+        preview: false,
+        build: false,
+        start: !isDevelopment,
+        dev: isDevelopment,
+        force: false,
+        serveOnly: false,
+        port: undefined,
+        hostname: undefined,
+        reactFastRefresh: undefined,
+    };
 }
-const ECOPAGES_BIN_FILES = ["ecopages.ts", "ecopages.js", "cli.js"];
-const ECOPAGES_AVAILABLE_COMMANDS = ["dev", "build", "start", "preview"];
-function parseCliArgs(options = {}) {
-  if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === "true") {
-    return getEmbeddedRuntimeCommandOptions();
-  }
-  const runtimeArgv = getRuntimeArgv();
-  const { values } = parseArgs({
-    args: runtimeArgv,
-    options: {
-      dev: { type: "boolean" },
-      preview: { type: "boolean" },
-      build: { type: "boolean" },
-      force: { type: "boolean" },
-      port: { type: "string" },
-      hostname: { type: "string" },
-      "react-fast-refresh": { type: "boolean" }
-    },
-    allowPositionals: true
-  });
-  let command = "";
-  const ecopagesIndex = runtimeArgv.findIndex((arg) => ECOPAGES_BIN_FILES.some((filename) => arg.endsWith(filename)));
-  const isAvailableCommand = ecopagesIndex !== -1;
-  if (isAvailableCommand) {
-    command = ecopagesIndex < runtimeArgv.length - 1 && ECOPAGES_AVAILABLE_COMMANDS.some((cmd) => {
-      return runtimeArgv[ecopagesIndex + 1] === cmd;
-    }) ? runtimeArgv[ecopagesIndex + 1] : "start";
-  }
-  const isStartCommand = command === "start" || !values.dev && !values.build && !values.preview;
-  const isDevCommand = command === "dev" || !!values.dev;
-  const isBuildCommand = command === "build" || !!values.build;
-  const isPreviewCommand = command === "preview" || !!values.preview;
-  const parsedCommandOptions = {
-    preview: isPreviewCommand,
-    build: isBuildCommand,
-    start: isStartCommand,
-    dev: isDevCommand,
-    force: !!values.force,
-    port: values.port ? Number(values.port) : void 0,
-    hostname: values.hostname,
-    reactFastRefresh: values["react-fast-refresh"]
-  };
-  if (!process.env.NODE_ENV) {
-    process.env.NODE_ENV = isDevCommand ? "development" : "production";
-  }
-  return parsedCommandOptions;
+const ECOPAGES_BIN_FILES = ['ecopages.ts', 'ecopages.js', 'cli.js'];
+const ECOPAGES_AVAILABLE_COMMANDS = ['dev', 'build', 'start', 'preview'];
+/**
+ * Parses command line arguments for the server.
+ * It returns {@link ReturnParseCliArgs}
+ */
+export function parseCliArgs(options = {}) {
+    if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === 'true') {
+        return getEmbeddedRuntimeCommandOptions();
+    }
+    const runtimeArgv = getRuntimeArgv();
+    const { values } = parseArgs({
+        args: runtimeArgv,
+        options: {
+            dev: { type: 'boolean' },
+            preview: { type: 'boolean' },
+            build: { type: 'boolean' },
+            force: { type: 'boolean' },
+            'serve-only': { type: 'boolean' },
+            port: { type: 'string' },
+            hostname: { type: 'string' },
+            'react-fast-refresh': { type: 'boolean' },
+        },
+        allowPositionals: true,
+    });
+    let command = '';
+    const ecopagesIndex = runtimeArgv.findIndex((arg) => ECOPAGES_BIN_FILES.some((filename) => arg.endsWith(filename)));
+    const isAvailableCommand = ecopagesIndex !== -1;
+    if (isAvailableCommand) {
+        command =
+            ecopagesIndex < runtimeArgv.length - 1 &&
+                ECOPAGES_AVAILABLE_COMMANDS.some((cmd) => {
+                    return runtimeArgv[ecopagesIndex + 1] === cmd;
+                })
+                ? runtimeArgv[ecopagesIndex + 1]
+                : 'start';
+    }
+    const isStartCommand = command === 'start' || (!values.dev && !values.build && !values.preview);
+    const isDevCommand = command === 'dev' || !!values.dev;
+    const isBuildCommand = command === 'build' || !!values.build;
+    const isPreviewCommand = command === 'preview' || !!values.preview;
+    const parsedCommandOptions = {
+        preview: isPreviewCommand,
+        build: isBuildCommand,
+        start: isStartCommand,
+        dev: isDevCommand,
+        force: !!values.force,
+        serveOnly: !!values['serve-only'] || process.env.ECOPAGES_PREVIEW_SERVE_ONLY === 'true',
+        port: values.port ? Number(values.port) : undefined,
+        hostname: values.hostname,
+        reactFastRefresh: values['react-fast-refresh'],
+    };
+    if (isDevCommand) {
+        process.env.NODE_ENV ??= 'development';
+    }
+    else {
+        process.env.NODE_ENV = 'production';
+    }
+    return parsedCommandOptions;
 }
-export {
-  parseCliArgs
-};

package/src/utils/path-pattern.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalizes a URL pathname for matching and sitemap location building.
+ *
+ * @remarks
+ * Ensures a leading slash and strips trailing slashes except for `/`.
+ */
+export declare function normalizePathname(pathname: string): string;
+/**
+ * Matches a pathname against a small set of supported patterns.
+ *
+ * @remarks
+ * Supported forms:
+ * - exact: `/admin`
+ * - prefix wildcard: `/admin/**` (matches `/admin` and descendants)
+ * - trailing `**` only as a full segment after `/`
+ *
+ * This is not a full glob engine. Unsupported patterns are treated as exact matches.
+ */
+export declare function matchPathPattern(pathname: string, pattern: string): boolean;
+/**
+ * Returns true when the pathname matches any of the patterns.
+ */
+export declare function matchesAnyPathPattern(pathname: string, patterns: readonly string[]): boolean;

package/src/utils/path-pattern.js

@@ -0,0 +1,42 @@
+/**
+ * Normalizes a URL pathname for matching and sitemap location building.
+ *
+ * @remarks
+ * Ensures a leading slash and strips trailing slashes except for `/`.
+ */
+export function normalizePathname(pathname) {
+    if (!pathname || pathname === '/') {
+        return '/';
+    }
+    const withLeadingSlash = pathname.startsWith('/') ? pathname : `/${pathname}`;
+    return withLeadingSlash.replace(/\/+$/, '') || '/';
+}
+/**
+ * Matches a pathname against a small set of supported patterns.
+ *
+ * @remarks
+ * Supported forms:
+ * - exact: `/admin`
+ * - prefix wildcard: `/admin/**` (matches `/admin` and descendants)
+ * - trailing `**` only as a full segment after `/`
+ *
+ * This is not a full glob engine. Unsupported patterns are treated as exact matches.
+ */
+export function matchPathPattern(pathname, pattern) {
+    const normalizedPath = normalizePathname(pathname);
+    const normalizedPattern = pattern.trim();
+    if (normalizedPattern.endsWith('/**')) {
+        const prefix = normalizePathname(normalizedPattern.slice(0, -3));
+        if (prefix === '/') {
+            return true;
+        }
+        return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
+    }
+    return normalizedPath === normalizePathname(normalizedPattern);
+}
+/**
+ * Returns true when the pathname matches any of the patterns.
+ */
+export function matchesAnyPathPattern(pathname, patterns) {
+    return patterns.some((pattern) => matchPathPattern(pathname, pattern));
+}

package/src/utils/path-utils.module.js

@@ -1,14 +1,11 @@
-import path from "node:path";
+import path from 'node:path';
 function getEcoTemplateExtension(filePath) {
-  const { name, ext } = path.parse(filePath);
-  const nameParts = name.split(".");
-  const descriptor = nameParts.length > 1 ? nameParts.pop() : void 0;
-  const templateExtension = descriptor ? `.${descriptor}${ext}` : ext;
-  return templateExtension;
+    const { name, ext } = path.parse(filePath);
+    const nameParts = name.split('.');
+    const descriptor = nameParts.length > 1 ? nameParts.pop() : undefined;
+    const templateExtension = descriptor ? `.${descriptor}${ext}` : ext;
+    return templateExtension;
 }
-const PathUtils = {
-  getEcoTemplateExtension
-};
-export {
-  PathUtils
+export const PathUtils = {
+    getEcoTemplateExtension,
 };

package/src/utils/resolve-entry-file.js

@@ -1,41 +1,73 @@
-import { parseArgs } from "node:util";
-import { getRuntimeArgv } from "./runtime.js";
-const DEFAULT_ENTRY_FILE = "app.ts";
-const ENTRY_FILE_ENV = "ECOPAGES_ENTRY_FILE";
-const entryFileOptions = {
-  "entry-file": { type: "string", short: "e" }
+import { parseArgs } from 'node:util';
+import { getRuntimeArgv } from './runtime.js';
+/**
+ * The default entry file name when no other source provides a value.
+ */
+export const DEFAULT_ENTRY_FILE = 'app.ts';
+/**
+ * The environment variable used to override the entry file path.
+ */
+export const ENTRY_FILE_ENV = 'ECOPAGES_ENTRY_FILE';
+/**
+ * Centralized definition of the entry-file CLI argument.
+ *
+ * Exported so callers (CLI, tests, docs) reference a single source of truth
+ * for the flag name, short alias, and type. Keep this in sync with
+ * `resolveEntryFile` below.
+ */
+export const entryFileOptions = {
+    'entry-file': { type: 'string', short: 'e' },
 };
-const ENTRY_FILE_FLAG = "entry-file";
-function resolveEntryFile({
-  entryFile,
-  env = process.env,
-  argv = getRuntimeArgv()
-} = {}) {
-  if (entryFile && entryFile.length > 0) return entryFile;
-  const fromEnv = env[ENTRY_FILE_ENV];
-  if (fromEnv && fromEnv.length > 0) return fromEnv;
-  const fromFlag = readEntryFileFlag(argv);
-  if (fromFlag) return fromFlag;
-  return DEFAULT_ENTRY_FILE;
+/**
+ * The long flag name for the entry file option. Re-exported as a
+ * constant so consumers don't hardcode the string.
+ */
+export const ENTRY_FILE_FLAG = 'entry-file';
+/**
+ * Resolves the entry file path using standard precedence.
+ *
+ * This is the single source of truth for entry-file resolution across
+ * the CLI, build pipeline, and runtime. Both the CLI layer and the
+ * runtime builders call into this function instead of reimplementing
+ * the precedence chain.
+ *
+ * @example
+ *   resolveEntryFile();                                     // 'app.ts' (or env/argv)
+ *   resolveEntryFile({ entryFile: 'src/server.ts' });       // 'src/server.ts'
+ *   resolveEntryFile({ env: { ECOPAGES_ENTRY_FILE: 'x' }}); // 'x'
+ *   resolveEntryFile({ argv: ['node', '-e', 'flag.ts'] });  // 'flag.ts'
+ */
+export function resolveEntryFile({ entryFile, env = process.env, argv = getRuntimeArgv(), } = {}) {
+    if (entryFile && entryFile.length > 0)
+        return entryFile;
+    const fromEnv = env[ENTRY_FILE_ENV];
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    const fromFlag = readEntryFileFlag(argv);
+    if (fromFlag)
+        return fromFlag;
+    return DEFAULT_ENTRY_FILE;
 }
-function readEntryFileFlag(argv = getRuntimeArgv()) {
-  const { values } = parseArgs({
-    args: argv.slice(1),
-    options: { ...entryFileOptions },
-    strict: false
-  });
-  const raw = values[ENTRY_FILE_FLAG];
-  return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+/**
+ * Parses argv for the entry-file flag using the shared `parseArgs` config.
+ *
+ * Exposed for callers that need the raw flag value without the full
+ * precedence chain (e.g. CLI help text, validation).
+ */
+export function readEntryFileFlag(argv = getRuntimeArgv()) {
+    const { values } = parseArgs({
+        args: argv.slice(1),
+        options: { ...entryFileOptions },
+        strict: false,
+    });
+    const raw = values[ENTRY_FILE_FLAG];
+    return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
 }
-const SERVER_BUNDLE_DIR = ".server";
-const SERVER_BUNDLE_FILENAME = "app.mjs";
-export {
-  DEFAULT_ENTRY_FILE,
-  ENTRY_FILE_ENV,
-  ENTRY_FILE_FLAG,
-  SERVER_BUNDLE_DIR,
-  SERVER_BUNDLE_FILENAME,
-  entryFileOptions,
-  readEntryFileFlag,
-  resolveEntryFile
-};
+/**
+ * The subdirectory inside `dist/` where the bundled server entry is placed.
+ */
+export const SERVER_BUNDLE_DIR = '.server';
+/**
+ * The filename of the bundled server entry.
+ */
+export const SERVER_BUNDLE_FILENAME = 'app.mjs';