@cfdez11/vex 0.1.0

package/client/services/navigation/router.js

@@ -0,0 +1,48 @@
+import { routes } from "../_routes.js";
+
+/**
+ * Converts a route path string with parameters (e.g., "/page/:city/:team")
+ * into a RegExp for matching and extracts parameter keys.
+ *
+ * @param {string} routePath - The route path pattern.
+ * @returns {{ regex: RegExp, keys: string[] }} An object containing the RegExp and parameter names.
+ */
+function pathToRegex(routePath) {
+  const keys = [];
+  const regex = new RegExp(
+    "^" +
+      routePath.replace(/:([^/]+)/g, (_, key) => {
+        keys.push(key);
+        return "([^/]+)";
+      }) +
+      "$"
+  );
+  return { regex, keys };
+}
+
+/**
+ * Finds the first route matching a given path and extracts route parameters.
+ *
+ * Supports both string-based paths with parameters and RegExp-based paths.
+ *
+ * @param {string} path - The URL path to match (e.g., "/page/madrid/barcelona").
+ * @returns {{ route: import('../_routes.js').Route | null, params: Record<string, string> }}
+ *          Returns the matched route and an object of extracted parameters.
+ */
+export function findRouteWithParams(path) {
+  for (const r of routes) {
+    if (typeof r.path === "string") {
+      const { regex, keys } = pathToRegex(r.path);
+      const match = path.match(regex);
+      if (match) {
+        const params = {};
+        keys.forEach((k, i) => (params[k] = match[i + 1]));
+        return { route: r, params };
+      }
+    } else if (r.path instanceof RegExp && r.path.test(path)) {
+      return { route: r, params: {} };
+    }
+  }
+
+  return { route: null, params: {} };
+}

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

@@ -0,0 +1,225 @@
+/**
+ * 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

@@ -0,0 +1,76 @@
+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/reactive.js

@@ -0,0 +1,231 @@
+/**
+ * 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) {
+        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 {
+    get value() {
+      return value;
+    },
+  };
+}
+
+/**
+ * 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/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@cfdez11/vex",
+  "version": "0.1.0",
+  "description": "A vanilla JavaScript meta-framework with file-based routing, SSR/CSR/SSG/ISR and Vue-like reactivity",
+  "type": "module",
+  "main": "./server/index.js",
+  "exports": {
+    ".": "./server/index.js"
+  },
+  "files": [
+    "server",
+    "client"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["framework", "ssr", "ssg", "reactive", "file-based-routing", "express", "vanilla-js"],
+  "license": "MIT",
+  "dependencies": {
+    "dom-serializer": "^2.0.0",
+    "express": "^5.2.1",
+    "htmlparser2": "^10.0.0"
+  }
+}