@hypen-space/core 0.2.0

package/src/router.ts

@@ -0,0 +1,311 @@
+/**
+ * Hypen Router - Declarative routing system
+ * Integrated with Hypen's reactive state management
+ */
+
+import { createObservableState, getStateSnapshot } from "./state.js";
+
+export type RouteMatch = {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  path: string;
+};
+
+export type RouteState = {
+  currentPath: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  previousPath: string | null;
+};
+
+export type RouteChangeCallback = (route: RouteState) => void;
+
+/**
+ * Hypen Router - Manages application routing with pattern matching
+ */
+export class HypenRouter {
+  private state: RouteState;
+  private subscribers = new Set<RouteChangeCallback>();
+  private isInitialized = false;
+
+  constructor() {
+    // Create observable state for reactivity
+    this.state = createObservableState<RouteState>(
+      {
+        currentPath: "/",
+        params: {},
+        query: {},
+        previousPath: null,
+      },
+      {
+        onChange: () => {
+          this.notifySubscribers();
+        },
+      }
+    );
+
+    // Initialize from browser if available
+    if (typeof window !== "undefined") {
+      this.initializeBrowserSync();
+    }
+  }
+
+  /**
+   * Initialize browser history sync
+   */
+  private initializeBrowserSync() {
+    // Get initial path from hash or pathname
+    const initialPath = this.getPathFromBrowser();
+    this.state.currentPath = initialPath;
+    this.state.params = {};
+    this.state.query = this.parseQuery();
+
+    // Listen for browser back/forward
+    window.addEventListener("popstate", () => {
+      const newPath = this.getPathFromBrowser();
+      this.updatePath(newPath, false); // Don't push to history again
+    });
+
+    // Listen for hash changes
+    window.addEventListener("hashchange", () => {
+      const newPath = this.getPathFromBrowser();
+      this.updatePath(newPath, false);
+    });
+
+    this.isInitialized = true;
+    console.log("Router initialized at:", initialPath);
+  }
+
+  /**
+   * Get path from browser URL (supports both hash and pathname)
+   */
+  private getPathFromBrowser(): string {
+    if (typeof window === "undefined") return "/";
+
+    // Prefer hash-based routing for simplicity
+    const hash = window.location.hash.slice(1);
+    if (hash) return hash;
+
+    // Fallback to pathname
+    return window.location.pathname;
+  }
+
+  /**
+   * Parse query string from URL
+   */
+  private parseQuery(): Record<string, string> {
+    if (typeof window === "undefined") return {};
+
+    const query: Record<string, string> = {};
+    const searchParams = new URLSearchParams(window.location.search);
+
+    searchParams.forEach((value, key) => {
+      query[key] = value;
+    });
+
+    return query;
+  }
+
+  /**
+   * Navigate to a new path
+   */
+  push(path: string) {
+    console.log("Router.push:", path);
+    this.updatePath(path, true);
+  }
+
+  /**
+   * Replace current path without adding to history
+   */
+  replace(path: string) {
+    console.log("Router.replace:", path);
+    this.updatePath(path, true, true);
+  }
+
+  /**
+   * Go back in history
+   */
+  back() {
+    console.log("Router.back");
+    if (typeof window !== "undefined") {
+      window.history.back();
+    }
+  }
+
+  /**
+   * Go forward in history
+   */
+  forward() {
+    console.log("Router.forward");
+    if (typeof window !== "undefined") {
+      window.history.forward();
+    }
+  }
+
+  /**
+   * Update the current path
+   */
+  private updatePath(
+    path: string,
+    updateBrowser: boolean,
+    replace: boolean = false
+  ) {
+    const oldPath = this.state.currentPath;
+    this.state.previousPath = oldPath;
+    this.state.currentPath = path;
+    this.state.query = this.parseQuery();
+
+    // Update browser URL if needed
+    if (updateBrowser && typeof window !== "undefined") {
+      const url = "#" + path;
+      if (replace) {
+        window.history.replaceState(null, "", url);
+      } else {
+        window.history.pushState(null, "", url);
+      }
+
+      // Manually trigger hashchange event
+      const hashChangeEvent = new HashChangeEvent("hashchange", {
+        oldURL: window.location.href.replace(window.location.hash, "#" + oldPath),
+        newURL: window.location.href,
+      });
+      window.dispatchEvent(hashChangeEvent);
+    }
+  }
+
+  /**
+   * Get current path
+   */
+  getCurrentPath(): string {
+    return this.state.currentPath;
+  }
+
+  /**
+   * Get current route params
+   */
+  getParams(): Record<string, string> {
+    return { ...this.state.params };
+  }
+
+  /**
+   * Get current query params
+   */
+  getQuery(): Record<string, string> {
+    return { ...this.state.query };
+  }
+
+  /**
+   * Get full route state snapshot
+   */
+  getState(): RouteState {
+    return getStateSnapshot(this.state);
+  }
+
+  /**
+   * Match a pattern against a path
+   */
+  matchPath(pattern: string, path: string): RouteMatch | null {
+    // Handle invalid inputs gracefully
+    if (!pattern || typeof pattern !== 'string') {
+      return null;
+    }
+    if (!path || typeof path !== 'string') {
+      return null;
+    }
+
+    // Exact match
+    if (pattern === path) {
+      return {
+        params: {},
+        query: this.state.query,
+        path,
+      };
+    }
+
+    // Wildcard match: /dashboard/* matches /dashboard/anything
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      if (path === prefix || path.startsWith(prefix + "/")) {
+        return {
+          params: {},
+          query: this.state.query,
+          path,
+        };
+      }
+      return null;
+    }
+
+    // Parameter match: /users/:id matches /users/123
+    const paramNames: string[] = [];
+    const regexPattern = pattern
+      .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+        paramNames.push(name);
+        return "([^/]+)";
+      })
+      .replace(/\*/g, ".*");
+
+    const regex = new RegExp(`^${regexPattern}$`);
+    const match = path.match(regex);
+
+    if (!match) return null;
+
+    // Extract params
+    const params: Record<string, string> = {};
+    paramNames.forEach((name, i) => {
+      const value = match[i + 1];
+      if (value !== undefined) {
+        params[name] = decodeURIComponent(value);
+      }
+    });
+
+    return {
+      params,
+      query: this.state.query,
+      path,
+    };
+  }
+
+  /**
+   * Subscribe to route changes
+   */
+  onNavigate(callback: RouteChangeCallback): () => void {
+    this.subscribers.add(callback);
+
+    // Call immediately with current state
+    callback(this.getState());
+
+    // Return unsubscribe function
+    return () => {
+      this.subscribers.delete(callback);
+    };
+  }
+
+  /**
+   * Notify all subscribers of route change
+   */
+  private notifySubscribers() {
+    const routeState = this.getState();
+    this.subscribers.forEach((callback) => {
+      callback(routeState);
+    });
+  }
+
+  /**
+   * Check if a path matches the current route
+   */
+  isActive(pattern: string): boolean {
+    return this.matchPath(pattern, this.state.currentPath) !== null;
+  }
+
+  /**
+   * Get a URL with query params
+   */
+  buildUrl(path: string, query?: Record<string, string>): string {
+    if (!query || Object.keys(query).length === 0) {
+      return path;
+    }
+
+    const queryString = new URLSearchParams(query).toString();
+    return `${path}?${queryString}`;
+  }
+}

package/src/state.ts

@@ -0,0 +1,363 @@
+/**
+ * State management with observer pattern and diffing
+ */
+
+export type StatePath = string; // e.g., "user.name", "items.0.title"
+
+/**
+ * Represents a change in state with full path information
+ */
+export interface StateChange {
+  paths: StatePath[];
+  newValues: Record<StatePath, any>;
+}
+
+/**
+ * Options for state observer
+ */
+export interface StateObserverOptions {
+  onChange: (change: StateChange) => void;
+  pathPrefix?: string; // For nested observers
+}
+
+/**
+ * Deep clone an object, handling circular references
+ */
+function deepClone<T>(obj: T): T {
+  // Handle primitives and null
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  // Use a WeakMap to track visited objects and handle circular references
+  const visited = new WeakMap();
+
+  function cloneInternal(value: any): any {
+    // Handle primitives and null
+    if (value === null || typeof value !== 'object') {
+      return value;
+    }
+
+    // Check if we've already cloned this object (circular reference)
+    if (visited.has(value)) {
+      return visited.get(value);
+    }
+
+    // Handle Date
+    if (value instanceof Date) {
+      return new Date(value.getTime());
+    }
+
+    // Handle RegExp
+    if (value instanceof RegExp) {
+      return new RegExp(value.source, value.flags);
+    }
+
+    // Handle Map
+    if (value instanceof Map) {
+      const mapClone = new Map();
+      visited.set(value, mapClone);
+      for (const [k, v] of value.entries()) {
+        mapClone.set(cloneInternal(k), cloneInternal(v));
+      }
+      return mapClone;
+    }
+
+    // Handle Set
+    if (value instanceof Set) {
+      const setClone = new Set();
+      visited.set(value, setClone);
+      for (const item of value.values()) {
+        setClone.add(cloneInternal(item));
+      }
+      return setClone;
+    }
+
+    // Handle WeakMap/WeakSet - cannot be cloned, return as-is
+    if (value instanceof WeakMap || value instanceof WeakSet) {
+      return value;
+    }
+
+    // Handle Array
+    if (Array.isArray(value)) {
+      const arrClone: any[] = [];
+      visited.set(value, arrClone);
+      for (let i = 0; i < value.length; i++) {
+        arrClone[i] = cloneInternal(value[i]);
+      }
+      return arrClone;
+    }
+
+    // Handle plain objects
+    const objClone: any = {};
+    visited.set(value, objClone);
+    for (const key in value) {
+      if (value.hasOwnProperty(key)) {
+        objClone[key] = cloneInternal(value[key]);
+      }
+    }
+    return objClone;
+  }
+
+  return cloneInternal(obj);
+}
+
+/**
+ * Compare two values and detect changes with full paths
+ */
+function diffState(
+  oldState: any,
+  newState: any,
+  basePath: string = ""
+): StateChange {
+  const paths: StatePath[] = [];
+  const newValues: Record<StatePath, any> = {};
+
+  function diff(oldVal: any, newVal: any, path: string) {
+    // Handle null/undefined
+    if (oldVal === newVal) return;
+
+    // Different types or primitives
+    if (
+      typeof oldVal !== "object" ||
+      typeof newVal !== "object" ||
+      oldVal === null ||
+      newVal === null
+    ) {
+      if (oldVal !== newVal) {
+        paths.push(path);
+        newValues[path] = newVal;
+      }
+      return;
+    }
+
+    // Arrays
+    if (Array.isArray(oldVal) || Array.isArray(newVal)) {
+      if (
+        !Array.isArray(oldVal) ||
+        !Array.isArray(newVal) ||
+        oldVal.length !== newVal.length
+      ) {
+        paths.push(path);
+        newValues[path] = newVal;
+        return;
+      }
+
+      for (let i = 0; i < newVal.length; i++) {
+        const itemPath = path ? `${path}.${i}` : `${i}`;
+        diff(oldVal[i], newVal[i], itemPath);
+      }
+      return;
+    }
+
+    // Objects
+    const oldKeys = new Set(Object.keys(oldVal));
+    const newKeys = new Set(Object.keys(newVal));
+
+    // Check for added or changed keys
+    for (const key of newKeys) {
+      const propPath = path ? `${path}.${key}` : key;
+      if (!oldKeys.has(key)) {
+        // New property
+        paths.push(propPath);
+        newValues[propPath] = newVal[key];
+      } else {
+        // Existing property, recurse
+        diff(oldVal[key], newVal[key], propPath);
+      }
+    }
+
+    // Check for removed keys
+    for (const key of oldKeys) {
+      if (!newKeys.has(key)) {
+        const propPath = path ? `${path}.${key}` : key;
+        paths.push(propPath);
+        newValues[propPath] = undefined;
+      }
+    }
+  }
+
+  diff(oldState, newState, basePath);
+  return { paths, newValues };
+}
+
+/**
+ * Create an observable state object that tracks changes
+ */
+export function createObservableState<T extends object>(
+  initialState: T,
+  options?: StateObserverOptions
+): T {
+  // Use default options if not provided
+  const opts: StateObserverOptions = options || { onChange: () => {} };
+
+  // Detect and reject primitive wrapper objects (Number, String, Boolean)
+  if (
+    initialState instanceof Number ||
+    initialState instanceof String ||
+    initialState instanceof Boolean
+  ) {
+    throw new TypeError(
+      "Cannot create observable state from primitive wrapper objects (Number, String, Boolean). " +
+      "Use plain primitives or regular objects instead."
+    );
+  }
+
+  // Keep a snapshot of the last known state
+  let lastSnapshot = deepClone(initialState);
+  const pathPrefix = opts.pathPrefix || "";
+
+  // Track if we're in a batch update
+  let batchDepth = 0;
+  let pendingChange: StateChange | null = null;
+
+  function notifyChange() {
+    if (batchDepth > 0) return;
+
+    // Compare current state with last snapshot
+    const change = diffState(lastSnapshot, state, pathPrefix);
+
+    if (change.paths.length > 0) {
+      // Update snapshot
+      lastSnapshot = deepClone(state);
+
+      // Merge with pending changes if any
+      if (pendingChange) {
+        change.paths.push(...pendingChange.paths);
+        Object.assign(change.newValues, pendingChange.newValues);
+        pendingChange = null;
+      }
+
+      // Notify
+      opts.onChange(change);
+    }
+  }
+
+  // Track if we have a pending microtask notification
+  let notificationPending = false;
+
+  function scheduleBatch() {
+    if (batchDepth === 0) {
+      // If not in a batch, schedule notification in next microtask to coalesce rapid changes
+      if (!notificationPending) {
+        notificationPending = true;
+        queueMicrotask(() => {
+          notificationPending = false;
+          if (batchDepth === 0) {
+            notifyChange();
+          }
+        });
+      }
+    }
+  }
+
+  // Cache proxies to handle circular references
+  const proxyCache = new WeakMap<any, any>();
+
+  function createProxy(target: any, basePath: string): any {
+    // Return cached proxy if it exists (handles circular references)
+    if (proxyCache.has(target)) {
+      return proxyCache.get(target);
+    }
+
+    const proxy = new Proxy(target, {
+      get(obj, prop) {
+        const value = obj[prop];
+
+        // Expose batch control methods
+        if (prop === "__beginBatch") {
+          return () => {
+            batchDepth++;
+          };
+        }
+        if (prop === "__endBatch") {
+          return () => {
+            batchDepth--;
+            if (batchDepth === 0) {
+              notifyChange();
+            }
+          };
+        }
+        if (prop === "__getSnapshot") {
+          return () => deepClone(obj);
+        }
+
+        // Return proxied nested objects/arrays, but NOT special types
+        if (value && typeof value === "object") {
+          // Check for special object types that should not be proxied
+          if (
+            value instanceof Date ||
+            value instanceof RegExp ||
+            value instanceof Map ||
+            value instanceof Set ||
+            value instanceof WeakMap ||
+            value instanceof WeakSet
+          ) {
+            return value;
+          }
+
+          // Proxy regular objects and arrays
+          return createProxy(value, basePath ? `${basePath}.${String(prop)}` : String(prop));
+        }
+
+        return value;
+      },
+
+      set(obj, prop, value) {
+        const oldValue = obj[prop];
+
+        // Set the new value
+        obj[prop] = value;
+
+        if (oldValue !== value) {
+          scheduleBatch();
+        }
+
+        return true;
+      },
+
+      deleteProperty(obj, prop) {
+        if (prop in obj) {
+          delete obj[prop];
+          scheduleBatch();
+        }
+        return true;
+      },
+    });
+
+    // Cache the proxy before returning
+    proxyCache.set(target, proxy);
+    return proxy;
+  }
+
+  const state = createProxy(initialState, pathPrefix);
+  return state as T;
+}
+
+/**
+ * Helper to batch multiple state updates
+ */
+export function batchStateUpdates<T>(state: T, fn: () => void): void {
+  const s = state as any;
+  if (s.__beginBatch && s.__endBatch) {
+    s.__beginBatch();
+    try {
+      fn();
+    } finally {
+      s.__endBatch();
+    }
+  } else {
+    fn();
+  }
+}
+
+/**
+ * Get a snapshot of the current state
+ */
+export function getStateSnapshot<T>(state: T): T {
+  const s = state as any;
+  if (s.__getSnapshot) {
+    return s.__getSnapshot();
+  }
+  return deepClone(state);
+}