@cfdez11/vex 0.8.3 → 0.9.1

package/client/services/navigation/use-query-params.js

@@ -1,225 +0,0 @@
-/**
- * Parses the URL search string into a plain object.
- *
- * This function represents the **raw URL state**:
- * - Keys and values are always strings
- * - No defaults are applied
- * - No parsing or validation is performed
- *
- * Example:
- *   "?page=2&tags=js,spa" → { page: "2", tags: "js,spa" }
- *
- * @param {string} search - window.location.search
- * @returns {Object.<string, string>}
- */
-function parseRawQuery(search) {
-  const out = {};
-  const qs = new URLSearchParams(search);
-
-  for (const [k, v] of qs.entries()) {
-    out[k] = v;
-  }
-
-  return out;
-}
-
-/**
- * Builds a query string from a raw params object.
- *
- * - Values are stringified
- * - `null` and `undefined` values are omitted
- *
- * Example:
- *   { page: "2", tags: "js,spa" } → "page=2&tags=js,spa"
- *
- * @param {Object.<string, any>} raw
- * @returns {string} Query string without leading "?"
- */
-function buildQueryString(raw) {
-  const qs = new URLSearchParams();
-
-  for (const k in raw) {
-    if (raw[k] != null) {
-      qs.set(k, String(raw[k]));
-    }
-  }
-
-  return qs.toString();
-}
-
-/**
- * Manages URL query parameters as application state.
- *
- * This hook provides:
- * - Parsing via schema (similar to nuqs)
- * - Default values
- * - URL synchronization (push / replace)
- * - Back/forward navigation support
- *
- * The URL remains the single source of truth.
- *
- * @param {Object} options
- * @param {Object.<string, Function>} [options.schema]
- *   Map of query param parsers.
- *   Each function receives the raw string value (or undefined)
- *   and must return a parsed value with a default fallback.
- *
- * @param {boolean} [options.replace=false]
- *   If true, uses history.replaceState instead of pushState.
- *
- * @param {boolean} [options.listen=true]
- *   If true, listens to popstate events to keep state in sync.
- *
- * @returns {Object}
- */
-export function useQueryParams(options = {}) {
-  const { schema = {}, replace = false, listen = true } = options;
-
-  /**
-   * Compute default values by executing schema parsers
-   * with an undefined input.
-   */
-  const defaults = {};
-  for (const key in schema) {
-    defaults[key] = schema[key](undefined);
-  }
-
-  /**
-   * Raw query params as strings.
-   * This mirrors exactly what exists in the URL.
-   */
-  let raw = parseRawQuery(window.location.search);
-
-  /**
-   * Parses raw query params using the provided schema.
-   *
-   * - Schema keys are always present (defaults applied)
-   * - Unknown params are passed through as strings
-   *
-   * @param {Object.<string, string>} raw
-   * @returns {Object} Parsed params ready for application use
-   */
-  function parseWithSchema(raw) {
-    const parsed = {};
-
-    // Apply schema parsing and defaults
-    for (const key in schema) {
-      const parser = schema[key];
-      parsed[key] = parser(raw[key]);
-    }
-
-    // Preserve non-declared query params
-    for (const key in raw) {
-      if (!(key in parsed)) {
-        parsed[key] = raw[key];
-      }
-    }
-
-    return parsed;
-  }
-
-  /**
-   * Serializes application-level values into
-   * raw URL-safe string values.
-   *
-   * - Arrays are joined by comma
-   * - null / undefined values are omitted
-   *
-   * @param {Object} next
-   * @returns {Object.<string, string>}
-   */
-  function serializeWithSchema(next) {
-    const out = {};
-
-    for (const key in next) {
-      const value = next[key];
-
-      if (Array.isArray(value)) {
-        out[key] = value.join(",");
-      } else if (value != null) {
-        out[key] = String(value);
-      }
-    }
-
-    return out;
-  }
-
-  /**
-   * Synchronizes the internal raw state with the browser URL.
-   *
-   * @param {Object.<string, string>} nextRaw
-   */
-  function sync(nextRaw) {
-    raw = nextRaw;
-
-    const qs = buildQueryString(raw);
-    const url =
-      window.location.pathname + (qs ? `?${qs}` : "") + window.location.hash;
-
-    history[replace ? "replaceState" : "pushState"](null, "", url);
-  }
-
-  /**
-   * Updates one or more query params.
-   *
-   * Values are serialized and merged with existing params.
-   *
-   * @param {Object} next
-   */
-  function set(next) {
-    const serialized = serializeWithSchema(next);
-    sync({ ...raw, ...serialized });
-  }
-
-  /**
-   * Removes one or more query params.
-   *
-   * @param {...string} keys
-   */
-  function remove(...keys) {
-    const next = { ...raw };
-    keys.forEach((k) => delete next[k]);
-    sync(next);
-  }
-
-  /**
-   * Removes all query params from the URL.
-   */
-  function reset() {
-    sync({});
-  }
-
-  /**
-   * Keeps internal state in sync with browser
-   * back/forward navigation.
-   */
-  if (listen) {
-    window.addEventListener("popstate", () => {
-      raw = parseRawQuery(window.location.search);
-    });
-  }
-
-  return {
-    /**
-     * Parsed query params.
-     *
-     * This is a getter, so values are always derived
-     * from the current raw URL state.
-     */
-    get params() {
-      return parseWithSchema(raw);
-    },
-
-    /**
-     * Raw query params as strings.
-     * Exposed mainly for debugging or tooling.
-     */
-    get raw() {
-      return { ...raw };
-    },
-
-    set,
-    remove,
-    reset,
-  };
-}

package/client/services/navigation/use-route-params.js

@@ -1,76 +0,0 @@
-import { reactive } from "../reactive.js";
-import { routes } from "../_routes.js";
-
-/**
- * Reactive store holding the current route params.
- * This object is updated whenever the URL changes.
- */
-const routeParams = reactive({});
-
-/**
- * Extracts dynamic parameters from a pathname based on route definitions.
- *
- * Supported syntax:
- *   /posts/:id
- *   /users/:userId/:postId
- *
- * @param {string} pathname - URL pathname (no query, no hash)
- * @returns {Object} Extracted params
- */
-function extractParams(pathname) {
-  const pathParts = pathname.split("/").filter(Boolean);
-
-  for (const route of routes) {
-    const routeParts = route.path.split("/").filter(Boolean);
-    if (routeParts.length !== pathParts.length) continue;
-
-    const params = {};
-    let match = true;
-
-    for (let i = 0; i < routeParts.length; i++) {
-      const routePart = routeParts[i];
-      const pathPart = pathParts[i];
-
-      if (routePart.startsWith(":")) {
-        params[routePart.slice(1)] = pathPart;
-      } else if (routePart !== pathPart) {
-        match = false;
-        break;
-      }
-    }
-
-    if (match) return params;
-  }
-
-  return {};
-}
-
-/**
- * Updates the reactive route params based on the current URL.
- * @param {string} [path=window.location.pathname] - URL pathname to extract params from
- * @example
- * updateRouteParams(); // Updates params from current URL
- * updateRouteParams("/posts/42"); // Updates params from given path
- */
-export function updateRouteParams(path = window.location.pathname) {
-  const newParams = extractParams(path);
-
-  Object.keys(routeParams).forEach((k) => delete routeParams[k]);
-  Object.assign(routeParams, newParams);
-}
-
-/**
- * Composition function returning reactive route params.
- *
- * @returns {Object} Reactive route params
- *
- * @example
- * const params = useRouteParams();
- *
- * effect(() => {
- *   console.log(params.id);
- * });
- */
-export function useRouteParams() {
-  return routeParams;
-}

package/client/services/navigation.js

@@ -1,6 +0,0 @@
-// Barrel file for vex/navigation imports.
-// Components import { useRouteParams } from "vex/navigation" which esbuild
-// rewrites to /_vexjs/services/navigation.js (external). All re-exports go
-// through navigation/index.js so the browser module cache ensures the same
-// runtime instance is shared with the index.js bootstrap.
-export { useRouteParams, useQueryParams, navigate } from "./navigation/index.js";

package/client/services/reactive.js

@@ -1,247 +0,0 @@
-/**
- * Tracks the currently executing effect function for dependency collection.
- * This global variable allows the reactive system to know which effect
- * is currently running and should be notified of reactive property changes.
- */
-let activeEffect = null;
-
-/**
- * Adapts primitive values (string, number, boolean, null) to work with the reactive system.
- * Wraps primitive values in an object with a 'value' property and marks them as primitive.
- * Objects are returned as-is since they can already have reactive properties.
- *
- * @param {any} input - The value to adapt for reactivity
- * @returns {object} Object with either the original object or wrapped primitive
- *
- * @example
- * adaptPrimitiveValue(42) // → { value: 42, __isPrimitive: true }
- * adaptPrimitiveValue("hello") // → { value: "hello", __isPrimitive: true }
- * adaptPrimitiveValue({x: 1}) // → {x: 1} (unchanged)
- */
-function adaptPrimitiveValue(input) {
-  if (input === null || typeof input !== "object") {
-    return { value: input, __isPrimitive: true };
-  }
-  return input;
-}
-
-/**
- * Creates a reactive proxy that automatically tracks dependencies and triggers effects.
- * The core of the reactivity system - makes any object or primitive reactive.
- *
- * Features:
- * - Automatic dependency tracking when properties are accessed during effects
- * - Automatic effect triggering when properties change
- * - Support for primitive values through value wrapping
- * - Memory cleanup to prevent leaks
- *
- * @param {any} obj - Object or primitive to make reactive
- * @returns {Proxy} Reactive proxy that tracks dependencies and triggers effects
- *
- * @example
- * With objects
- * const state = reactive({ count: 0, name: "John" });
- * state.count++; // Triggers any effects that used state.count
- *
- * @example
- * With primitives
- * const counter = reactive(0);
- * counter.value++; // Triggers effects that used counter.value
- *
- * @example
- * In components
- * class Counter {
- *   count = reactive(0);
- *
- *   increment() {
- *     this.count.value++; // Automatically re-renders component
- *   }
- *
- *   effect(() => this.render());
- *
- *   render() {
- *     return html`<button @click="${this.increment}">Count: ${this.count.value}</button>`;
- *   }
- * }
- *
- * @example
- * In components with Component base class doesn't require manual effect()
- * class Counter extends Component {
- *   count = reactive(0);
- *
- *   increment() {
- *     this.count.value++; // Automatically re-renders component
- *   }
- *
- *   render() {
- *     return html`<button @click="${this.increment}">Count: ${this.count.value}</button>`;
- *   }
- * }
- *
- */
-export function reactive(obj) {
-  obj = adaptPrimitiveValue(obj);
-
-  // Map to store dependencies for each property
-  const depsMap = new Map();
-
-  const proxy = new Proxy(obj, {
-    get(target, prop) {
-      // Handle primitive value conversion (for template literals, etc.)
-      if (target.__isPrimitive && prop === Symbol.toPrimitive) {
-        // Track "value" dependency so effects using ${counter} re-run on change
-        if (activeEffect) {
-          if (!depsMap.has("value")) depsMap.set("value", new Set());
-          const depSet = depsMap.get("value");
-          depSet.add(activeEffect);
-          if (!activeEffect.deps) activeEffect.deps = [];
-          activeEffect.deps.push(depSet);
-        }
-        return () => target.value;
-      }
-
-      // Use 'value' key for primitives, actual property name for objects
-      const key = target.__isPrimitive ? "value" : prop;
-
-      // Dependency tracking: if an effect is running, register it as dependent on this property
-      if (activeEffect) {
-        if (!depsMap.has(key)) depsMap.set(key, new Set());
-        const depSet = depsMap.get(key);
-        depSet.add(activeEffect);
-
-        // Track dependencies on the effect for cleanup
-        if (!activeEffect.deps) activeEffect.deps = [];
-        activeEffect.deps.push(depSet);
-      }
-
-      return target[key];
-    },
-    set(target, prop, value) {
-      const key = target.__isPrimitive ? "value" : prop;
-      target[key] = value;
-
-      // Trigger all effects that depend on this property
-      if (depsMap.has(key)) {
-        depsMap.get(key).forEach((effect) => effect());
-      }
-
-      return true;
-    },
-  });
-
-  return proxy;
-}
-
-/**
- * Creates a reactive effect that automatically re-runs when its dependencies change.
- * This is the foundation of the reactivity system - it tracks which reactive properties
- * are accessed during execution and re-runs the function when any of them change.
- *
- * @param {function} fn - Function to run reactively. Will re-execute when dependencies change
- * @returns {function} Cleanup function to stop the effect and remove all dependencies
- *
- * @example
- * Basic usage
- * const count = reactive(0);
- * const cleanup = effect(() => {
- *   console.log(`Count is: ${count.value}`); // Logs immediately and on changes
- * });
- *
- * count.value++; // Logs: "Count is: 1"
- * cleanup(); // Stops the effect
- */
-export function effect(fn) {
-  const wrapped = () => {
-    activeEffect = wrapped;
-    fn();
-    activeEffect = null;
-  };
-
-  // Run the effect immediately to collect initial dependencies
-  wrapped();
-
-  // Return cleanup function
-  return () => {
-    if (wrapped.deps) {
-      wrapped.deps.forEach((depSet) => depSet.delete(wrapped));
-    }
-  };
-}
-
-/**
- * Creates a computed reactive value that automatically updates when its dependencies change.
- * @param {Function} getter
- * @returns {{ value: Object }} Computed reactive value
- *
- * @example
- * Basic usage
- * const count = reactive(1);
- * const doubleCount = computed(() => count.value * 2);
- * console.log(doubleCount.value); // 2
- * count.value = 3;
- * console.log(doubleCount.value); // 6
- */
-export function computed(getter) {
-  let value;
-
-  effect(() => {
-    value = getter();
-  });
-
-  return new Proxy({}, {
-    get(_, prop) {
-      if (prop === Symbol.toPrimitive) {
-        return () => value;
-      }
-      if (prop === "value") {
-        return value;
-      }
-      // Delegate any other access (e.g. .map, .length) to the underlying value
-      const v = value?.[prop];
-      return typeof v === "function" ? v.bind(value) : v;
-    },
-  });
-}
-
-/**
- * Watches a reactive source and runs a callback when its value changes.
- *
- * @template T
- * @param {() => T} source - A getter function returning the reactive value to watch.
- * @param {(newValue: T, oldValue: T | undefined, onCleanup: (fn: () => void) => void) => void} callback
- * @param {{ immediate?: boolean }} [options]
- */
-export function watch(source, callback, options = {}) {
-  let oldValue;
-  let cleanupFn;
-
-  const onCleanup = (fn) => {
-    cleanupFn = fn;
-  };
-
-  const runner = () => {
-    const newValue = source();
-
-    // Skip first run if not immediate
-    if (oldValue === undefined && !options.immediate) {
-      oldValue = newValue;
-      return;
-    }
-
-    // Avoid unnecessary executions
-    if (Object.is(newValue, oldValue)) return;
-
-    // Cleanup previous effect
-    if (cleanupFn) {
-      cleanupFn();
-      cleanupFn = null;
-    }
-
-    callback(newValue, oldValue, onCleanup);
-    oldValue = newValue;
-  };
-
-  // Track dependencies reactively
-  effect(runner);
-}
-

package/server/build-static.js

@@ -1,138 +0,0 @@
-import "dotenv/config";
-import fs from "fs/promises";
-import path from "path";
-import { build } from "./utils/component-processor.js";
-import {
-  initializeDirectories,
-  CLIENT_DIR,
-  PROJECT_ROOT,
-  getRootTemplate,
-  generateComponentId,
-  USER_GENERATED_DIR,
-} from "./utils/files.js";
-
-const GENERATED_DIR = path.join(PROJECT_ROOT, ".vexjs");
-const DIST_DIR = path.join(PROJECT_ROOT, "dist");
-
-console.log("🔨 Starting static build...");
-
-// Step 1: Prebuild (components + routes)
-console.log("📁 Initializing directories...");
-await initializeDirectories();
-
-console.log("⚙️  Generating components and routes...");
-const { serverRoutes } = await build();
-
-// Step 2: Create dist/ structure (clean start)
-console.log("🗂️  Creating dist/ structure...");
-await fs.rm(DIST_DIR, { recursive: true, force: true });
-await fs.mkdir(path.join(DIST_DIR, "_vexjs", "_components"), { recursive: true });
-await fs.mkdir(path.join(DIST_DIR, "_vexjs", "user"), { recursive: true });
-
-// Step 3: Generate dist/index.html shell
-console.log("📄 Generating index.html shell...");
-const rootTemplate = await getRootTemplate();
-let shell = rootTemplate
-  .replace(/\{\{metadata\.title\}\}/g, "App")
-  .replace(/\{\{metadata\.description\}\}/g, "")
-  .replace(/\{\{props\.children\}\}/g, "");
-
-const frameworkScripts = [
-  `<style>vex-root { display: contents; }</style>`,
-  `<script type="module" src="/_vexjs/services/index.js"></script>`,
-  `<script src="/_vexjs/services/hydrate-client-components.js"></script>`,
-  `<script src="/_vexjs/services/hydrate.js" id="hydrate-script"></script>`,
-].join("\n  ");
-
-shell = shell.replace("</head>", `  ${frameworkScripts}\n</head>`);
-await fs.writeFile(path.join(DIST_DIR, "index.html"), shell, "utf-8");
-
-// Step 4: Copy static framework assets (favicon.ico, app.webmanifest) → dist/_vexjs/
-// JS runtime files live in .vexjs/services/ (copied in step 5) — no need to
-// copy CLIENT_DIR/services/ separately.
-console.log("📦 Copying framework assets...");
-for (const asset of ["favicon.ico", "app.webmanifest"]) {
-  try {
-    await fs.copyFile(
-      path.join(CLIENT_DIR, asset),
-      path.join(DIST_DIR, "_vexjs", asset)
-    );
-  } catch {
-    // asset not present — skip
-  }
-}
-
-// Step 5: Copy generated services → dist/_vexjs/services/
-// .vexjs/services/ already contains both framework JS (copied by initializeDirectories)
-// and generated files (_routes.js). One copy covers everything.
-console.log("📦 Copying services...");
-await fs.cp(
-  path.join(GENERATED_DIR, "services"),
-  path.join(DIST_DIR, "_vexjs", "services"),
-  { recursive: true }
-);
-
-// Step 6: Copy generated component bundles → dist/_vexjs/_components/
-console.log("📦 Copying component bundles...");
-await fs.cp(
-  path.join(GENERATED_DIR, "_components"),
-  path.join(DIST_DIR, "_vexjs", "_components"),
-  { recursive: true }
-);
-
-// Step 7: Copy pre-bundled user JS files → dist/_vexjs/user/
-// build() already ran esbuild on every user .js file → USER_GENERATED_DIR.
-// npm packages are bundled inline; vex/*, @/*, relative imports stay external.
-console.log("📦 Copying pre-bundled user JS files...");
-try {
-  await fs.cp(USER_GENERATED_DIR, path.join(DIST_DIR, "_vexjs", "user"), { recursive: true });
-} catch {
-  // no user JS files — that's fine
-}
-
-// Step 8: Copy public/ → dist/
-console.log("📦 Copying public assets...");
-const publicDir = path.join(PROJECT_ROOT, "public");
-try {
-  await fs.cp(publicDir, DIST_DIR, { recursive: true });
-} catch {
-  // no public/ directory — that's fine
-}
-
-// Step 9: Copy pre-rendered SSG pages
-const CACHE_DIR = path.join(GENERATED_DIR, "_cache");
-const ssgRoutes = serverRoutes.filter(
-  (r) => r.meta.revalidate === "never" || r.meta.revalidate === false
-);
-if (ssgRoutes.length > 0) {
-  console.log("📄 Copying pre-rendered SSG pages...");
-  for (const route of ssgRoutes) {
-    const cacheFile = path.join(CACHE_DIR, `${generateComponentId(route.serverPath)}.html`);
-    try {
-      const html = await fs.readFile(cacheFile, "utf-8");
-      const routeSegment = route.serverPath === "/" ? "" : route.serverPath;
-      const destPath = path.join(DIST_DIR, routeSegment, "index.html");
-      await fs.mkdir(path.dirname(destPath), { recursive: true });
-      await fs.writeFile(destPath, html, "utf-8");
-      console.log(`   ✓ ${route.serverPath}`);
-    } catch {
-      console.warn(`   ✗ ${route.serverPath} (no cached HTML found)`);
-    }
-  }
-}
-
-// Step 10: Report SSR-only routes (skipped in static build)
-const ssrOnlyRoutes = serverRoutes.filter((r) => r.meta.ssr);
-if (ssrOnlyRoutes.length > 0) {
-  console.warn("\n⚠️  The following routes require a server and were NOT included in the static build:");
-  for (const r of ssrOnlyRoutes) {
-    console.warn(`   ${r.path} (SSR)`);
-  }
-  console.warn("   These routes will show a 404 in the static build.\n");
-}
-
-console.log("✅ Static build complete! Output: dist/");
-console.log("\nTo serve locally:  npx serve dist");
-console.log("Static host note:  configure your host to serve dist/index.html for all 404s (SPA fallback).");
-
-