@hypen-space/core 0.4.82 → 0.4.83

package/dist/index.d.ts

@@ -50,10 +50,14 @@ export { DataSourceManager } from "./datasource.js";
 export type { DataSourcePlugin, DataSourceStatus, DataSourceQuery, DataSourceSubscription, DataSourceChange, IDataSourceEngine, } from "./datasource.js";
 export { createObservableState, batchStateUpdates, getStateSnapshot, isStateProxy, unwrapProxy, } from "./state.js";
 export type { StatePath, StateChange, StateObserverOptions, } from "./state.js";
+export { setPortableImpl, portable } from "./portable.js";
+export type { PortableImpl } from "./portable.js";
 export { BaseRenderer, ConsoleRenderer } from "./renderer.js";
 export type { Renderer } from "./renderer.js";
 export { HypenRouter } from "./router.js";
 export type { RouteMatch, RouteState, RouteChangeCallback, } from "./router.js";
+export { ManagedRouter } from "./managed-router.js";
+export type { RouteDefinition } from "./managed-router.js";
 export { TypedEventEmitter, createEventEmitter } from "./events.js";
 export type { EventHandler, HypenFrameworkEvents } from "./events.js";
 export { HypenGlobalContext } from "./context.js";

package/dist/index.js

@@ -602,6 +602,53 @@ class DataSourceManager {
   }
 }
 
+// src/portable.ts
+function notInstalled(name) {
+  throw new Error(`[@hypen-space/core] Portable helper "${name}" called before the engine was installed. ` + `Import @hypen-space/server, @hypen-space/web-engine, or call setPortableImpl() before use.`);
+}
+var current = {
+  diffState: () => notInstalled("diffState"),
+  matchPath: () => notInstalled("matchPath"),
+  pathGet: () => notInstalled("pathGet"),
+  pathHas: () => notInstalled("pathHas"),
+  pathSet: () => notInstalled("pathSet"),
+  pathDelete: () => notInstalled("pathDelete"),
+  encodeUriComponent: () => notInstalled("encodeUriComponent"),
+  decodeUriComponent: () => notInstalled("decodeUriComponent"),
+  parseQuery: () => notInstalled("parseQuery"),
+  buildUrl: () => notInstalled("buildUrl")
+};
+function setPortableImpl(impl) {
+  if (impl === null) {
+    current = {
+      diffState: () => notInstalled("diffState"),
+      matchPath: () => notInstalled("matchPath"),
+      pathGet: () => notInstalled("pathGet"),
+      pathHas: () => notInstalled("pathHas"),
+      pathSet: () => notInstalled("pathSet"),
+      pathDelete: () => notInstalled("pathDelete"),
+      encodeUriComponent: () => notInstalled("encodeUriComponent"),
+      decodeUriComponent: () => notInstalled("decodeUriComponent"),
+      parseQuery: () => notInstalled("parseQuery"),
+      buildUrl: () => notInstalled("buildUrl")
+    };
+    return;
+  }
+  current = impl;
+}
+var portable = {
+  diffState: (o, n, b) => current.diffState(o, n, b),
+  matchPath: (p, path) => current.matchPath(p, path),
+  pathGet: (v, p) => current.pathGet(v, p),
+  pathHas: (v, p) => current.pathHas(v, p),
+  pathSet: (v, p, nv) => current.pathSet(v, p, nv),
+  pathDelete: (v, p) => current.pathDelete(v, p),
+  encodeUriComponent: (s) => current.encodeUriComponent(s),
+  decodeUriComponent: (s) => current.decodeUriComponent(s),
+  parseQuery: (f) => current.parseQuery(f),
+  buildUrl: (p, q) => current.buildUrl(p, q)
+};
+
 // src/state.ts
 var IS_PROXY = Symbol.for("hypen.isProxy");
 var RAW_TARGET = Symbol.for("hypen.rawTarget");
@@ -661,51 +708,7 @@ function deepClone(obj) {
   return cloneInternal(obj);
 }
 function diffState(oldState, newState, basePath = "") {
-  const paths = [];
-  const newValues = {};
-  function diff(oldVal, newVal, path) {
-    if (oldVal === newVal)
-      return;
-    if (typeof oldVal !== "object" || typeof newVal !== "object" || oldVal === null || newVal === null) {
-      if (oldVal !== newVal) {
-        paths.push(path);
-        newValues[path] = newVal;
-      }
-      return;
-    }
-    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;
-    }
-    const oldKeys = new Set(Object.keys(oldVal));
-    const newKeys = new Set(Object.keys(newVal));
-    for (const key of newKeys) {
-      const propPath = path ? `${path}.${key}` : key;
-      if (!oldKeys.has(key)) {
-        paths.push(propPath);
-        newValues[propPath] = newVal[key];
-      } else {
-        diff(oldVal[key], newVal[key], propPath);
-      }
-    }
-    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 };
+  return portable.diffState(oldState, newState, basePath);
 }
 function createObservableState(initialState, options) {
   const opts = options || { onChange: () => {} };
@@ -1054,6 +1057,8 @@ class HypenAppBuilder {
   initialState;
   options;
   createdHandler;
+  activatedHandler;
+  deactivatedHandler;
   actionHandlers = new Map;
   destroyedHandler;
   disconnectHandler;
@@ -1077,6 +1082,14 @@ class HypenAppBuilder {
     this.actionHandlers.set(name, fn);
     return this;
   }
+  onActivated(fn) {
+    this.activatedHandler = fn;
+    return this;
+  }
+  onDeactivated(fn) {
+    this.deactivatedHandler = fn;
+    return this;
+  }
   onDestroyed(fn) {
     this.destroyedHandler = fn;
     return this;
@@ -1128,6 +1141,8 @@ class HypenAppBuilder {
       stateStore: this._stateStore,
       handlers: {
         onCreated: this.createdHandler,
+        onActivated: this.activatedHandler,
+        onDeactivated: this.deactivatedHandler,
         onAction: this.actionHandlers,
         onDestroyed: this.destroyedHandler,
         onDisconnect: this.disconnectHandler,
@@ -1185,6 +1200,7 @@ class HypenModuleInstance {
   definition;
   state;
   isDestroyed = false;
+  isActive = false;
   router;
   globalContext;
   stateChangeCallbacks = [];
@@ -1264,6 +1280,43 @@ class HypenModuleInstance {
   async waitForReady() {
     await this._readyPromise;
   }
+  async activate() {
+    if (this.isDestroyed || this.isActive)
+      return;
+    await this._readyPromise;
+    if (this.isDestroyed || this.isActive)
+      return;
+    this.isActive = true;
+    if (this.definition.handlers.onActivated) {
+      const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
+      try {
+        await this.definition.handlers.onActivated(this.state, context);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onActivated", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "activated" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
+    }
+  }
+  async deactivate() {
+    if (this.isDestroyed || !this.isActive)
+      return;
+    this.isActive = false;
+    if (this.definition.handlers.onDeactivated) {
+      const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
+      try {
+        await this.definition.handlers.onDeactivated(this.state, context);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onDeactivated", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "deactivated" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
+    }
+  }
   createGlobalContextAPI() {
     if (!this.globalContext) {
       throw new Error("Global context not available");
@@ -1412,6 +1465,9 @@ class HypenModuleInstance {
   async destroy() {
     if (this.isDestroyed)
       return;
+    if (this.isActive) {
+      await this.deactivate();
+    }
     if (this.currentPersistKey && this.stateStore) {
       clearTimeout(this.persistDebounceTimer);
       const snapshot = getStateSnapshot(this.state);
@@ -1818,46 +1874,22 @@ class HypenRouter {
     return getStateSnapshot(this.state);
   }
   matchPath(pattern, path) {
-    if (!pattern || typeof pattern !== "string") {
+    if (!pattern || typeof pattern !== "string")
       return null;
-    }
-    if (!path || typeof path !== "string") {
+    if (!path || typeof path !== "string")
       return null;
-    }
-    if (pattern === path) {
-      return {
-        params: {},
-        query: this.state.query,
-        path
-      };
-    }
-    if (pattern.endsWith("/*")) {
-      const prefix = pattern.slice(0, -2);
-      if (path === prefix || path.startsWith(prefix + "/")) {
-        return {
-          params: {},
-          query: this.state.query,
-          path
-        };
-      }
-      return null;
-    }
-    const paramNames = [];
-    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 match2 = path.match(regex);
-    if (!match2)
+    const cleanPath = path.split("?")[0] ?? path;
+    const result = portable.matchPath(pattern, cleanPath);
+    if (!result)
       return null;
     const params = {};
-    paramNames.forEach((name, i) => {
-      const value = match2[i + 1];
-      if (value !== undefined) {
-        params[name] = decodeURIComponent(value);
+    for (const [name, raw] of Object.entries(result.params)) {
+      try {
+        params[name] = decodeURIComponent(raw);
+      } catch {
+        params[name] = raw;
       }
-    });
+    }
     return {
       params,
       query: this.state.query,
@@ -2332,13 +2364,13 @@ class RemoteEngine {
     if (!state2 || typeof state2 !== "object")
       return;
     const parts = key.split(".");
-    let current = state2;
+    let current2 = state2;
     for (const part of parts) {
-      if (current == null || typeof current !== "object")
+      if (current2 == null || typeof current2 !== "object")
         return;
-      current = current[part];
+      current2 = current2[part];
     }
-    return typeof current === "string" ? current : undefined;
+    return typeof current2 === "string" ? current2 : undefined;
   }
   dispatchAction(action, payload) {
     if (this.state !== "connected" || !this.ws) {
@@ -2828,6 +2860,204 @@ var Link = app.defineState({
     });
   }
 }).build();
+// src/managed-router.ts
+var log10 = createLogger("ManagedRouter");
+var DEFAULT_MAX_PERSISTED_MODULES = 10;
+
+class ManagedRouter {
+  router;
+  engine;
+  registry;
+  globalContext;
+  routes = [];
+  activeModule = null;
+  activeRoute = null;
+  unsubscribe = null;
+  persistedModules = new Map;
+  maxPersistedModules;
+  navPromise = Promise.resolve();
+  constructor(router, engine, registry, globalContext, options = {}) {
+    this.router = router;
+    this.engine = engine;
+    this.registry = registry;
+    this.globalContext = globalContext;
+    const cap = options.maxPersistedModules ?? DEFAULT_MAX_PERSISTED_MODULES;
+    this.maxPersistedModules = cap > 0 ? cap : DEFAULT_MAX_PERSISTED_MODULES;
+  }
+  addRoute(route) {
+    this.routes.push(route);
+    return this;
+  }
+  start() {
+    this.unsubscribe = this.router.onNavigate((routeState) => {
+      this.handleRouteChange(routeState);
+    });
+    this.installRouterActions();
+  }
+  installRouterActions() {
+    const router = this.router;
+    const defer = (fn) => queueMicrotask(fn);
+    const readTo = (action) => {
+      const payload = action?.payload;
+      const to = payload?.to;
+      return typeof to === "string" && to.length > 0 ? to : null;
+    };
+    this.engine.onAction("router.push", (action) => {
+      const to = readTo(action);
+      if (to)
+        defer(() => router.push(to));
+    });
+    this.engine.onAction("router.replace", (action) => {
+      const to = readTo(action);
+      if (to)
+        defer(() => router.replace(to));
+    });
+    this.engine.onAction("router.back", () => {
+      defer(() => router.back());
+    });
+    this.engine.onAction("router.forward", () => {
+      defer(() => router.forward());
+    });
+  }
+  async stop() {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+    const cleanup = this.navPromise.catch(() => {}).then(async () => {
+      await this.unmountActive();
+      for (const [moduleId, instance] of this.persistedModules) {
+        log10.debug(`Destroying persisted module on stop: ${moduleId}`);
+        try {
+          await instance.destroy();
+        } catch (e) {
+          log10.error(`Error destroying persisted module ${moduleId}:`, e);
+        }
+        this.globalContext.unregisterModule(moduleId);
+      }
+      this.persistedModules.clear();
+    });
+    this.navPromise = cleanup;
+    await cleanup;
+    this.router.dispose();
+  }
+  async waitForNavigation() {
+    try {
+      await this.navPromise;
+    } catch {}
+  }
+  getActiveModule() {
+    return this.activeModule;
+  }
+  getActiveRoute() {
+    return this.activeRoute;
+  }
+  handleRouteChange(routeState) {
+    this.navPromise = this.navPromise.catch((e) => {
+      log10.error("Previous navigation failed:", e);
+    }).then(() => this.processRouteChange(routeState));
+  }
+  async processRouteChange(routeState) {
+    const path = routeState.currentPath;
+    const matched = this.matchRoute(path);
+    if (!matched) {
+      log10.debug(`No route matched for path: ${path}`);
+      await this.unmountActive();
+      return;
+    }
+    if (this.activeRoute && this.activeRoute.path === matched.path) {
+      return;
+    }
+    await this.unmountActive();
+    await this.mount(matched);
+  }
+  matchRoute(path) {
+    for (const route of this.routes) {
+      if (this.router.matchPath(route.path, path) !== null) {
+        return route;
+      }
+    }
+    return null;
+  }
+  async mount(route) {
+    const definition = route.module || this.registry.get(route.component);
+    if (!definition) {
+      log10.debug(`No module definition found for component: ${route.component}`);
+      this.activeRoute = route;
+      return;
+    }
+    const namedDef = {
+      ...definition,
+      name: definition.name || route.component.toLowerCase()
+    };
+    const moduleId = namedDef.name.toLowerCase();
+    const persisted = this.persistedModules.get(moduleId);
+    if (persisted) {
+      log10.debug(`Restoring persisted module: ${moduleId} for route: ${route.path}`);
+      this.activeModule = persisted;
+      this.activeRoute = route;
+      this.persistedModules.delete(moduleId);
+      await persisted.activate();
+      return;
+    }
+    log10.debug(`Mounting module: ${namedDef.name} for route: ${route.path}`);
+    const instance = new HypenModuleInstance(this.engine, namedDef, this.router, this.globalContext);
+    this.globalContext.registerModule(moduleId, instance);
+    this.activeModule = instance;
+    this.activeRoute = route;
+    await instance.activate();
+  }
+  async unmountActive() {
+    if (!this.activeModule || !this.activeRoute) {
+      this.activeModule = null;
+      this.activeRoute = null;
+      return;
+    }
+    const active = this.activeModule;
+    const route = this.activeRoute;
+    const definition = route.module || this.registry.get(route.component);
+    const moduleId = (definition?.name || route.component).toLowerCase();
+    const persist = definition != null && definition.persist !== false;
+    this.activeModule = null;
+    this.activeRoute = null;
+    try {
+      await active.deactivate();
+    } catch (e) {
+      log10.error(`Error deactivating module ${moduleId}:`, e);
+    }
+    if (persist) {
+      log10.debug(`Persisting module: ${moduleId}`);
+      this.persistedModules.delete(moduleId);
+      this.persistedModules.set(moduleId, active);
+      await this.evictPersistedOverflow();
+    } else {
+      log10.debug(`Unmounting module: ${moduleId}`);
+      try {
+        await active.destroy();
+      } catch (e) {
+        log10.error(`Error destroying module ${moduleId}:`, e);
+      }
+      this.globalContext.unregisterModule(moduleId);
+    }
+  }
+  async evictPersistedOverflow() {
+    while (this.persistedModules.size > this.maxPersistedModules) {
+      const oldest = this.persistedModules.keys().next();
+      if (oldest.done)
+        break;
+      const oldestId = oldest.value;
+      const evicted = this.persistedModules.get(oldestId);
+      this.persistedModules.delete(oldestId);
+      log10.debug(`Evicting persisted module (LRU): ${oldestId}`);
+      try {
+        await evicted.destroy();
+      } catch (e) {
+        log10.error(`Error destroying evicted module ${oldestId}:`, e);
+      }
+      this.globalContext.unregisterModule(oldestId);
+    }
+  }
+}
 export {
   withRetry,
   usingSync,
@@ -2837,10 +3067,12 @@ export {
   unwrapOr,
   unwrap,
   state,
+  setPortableImpl,
   setLogLevel,
   setDebugMode,
   retryResult,
   retry,
+  portable,
   match,
   mapErr,
   map,
@@ -2891,6 +3123,7 @@ export {
   RemoteEngine,
   ParseError,
   Ok,
+  ManagedRouter,
   Logger,
   Link,
   HypenRouter,
@@ -2910,4 +3143,4 @@ export {
   ActionError
 };
 
-//# debugId=ABC8BA06546F591964756E2164756E21
+//# debugId=A9CE0B874F21F46D64756E2164756E21