@hypen-space/core 0.4.82 → 0.4.84

package/README.md

@@ -122,6 +122,8 @@ interface UserState {
   loading: boolean;
 }
 
+interface LoadUserPayload { id: string; }
+
 const userModule = app
   .defineState<UserState>({ user: null, loading: false })
 
@@ -131,15 +133,16 @@ const userModule = app
     // State changes are auto-synced via Proxy
   })
 
-  // Action handler: receives context object { action, state, next, context }
-  .onAction("loadUser", async ({ state, action, next, context }) => {
-    const userId = action.payload?.id;
-    state.user = await fetchUser(userId);
+  // Typed action handler: declare the payload type as a generic so
+  // `action.payload` is statically typed instead of `unknown`.
+  .onAction<LoadUserPayload>("loadUser", async ({ state, action, context }) => {
+    state.user = await fetchUser(action.payload.id);
     state.loading = false;
     // State changes are auto-synced via Proxy
     // context.router is available for programmatic navigation
   })
 
+  // Actions without a payload: omit the generic.
   .onAction("logout", ({ state }) => {
     state.user = null;
   })
@@ -153,6 +156,9 @@ const userModule = app
 ```
 
 State mutations are automatically tracked via Proxy and synced to the engine.
+Action payloads default to `unknown` — always pass a payload type to
+`.onAction<P>(...)` when the action carries data so you get end-to-end
+type safety instead of manual casting.
 
 ## State
 

package/dist/app.d.ts

@@ -112,7 +112,7 @@ export interface ErrorContext<T> {
     /** The action name if error occurred in an action handler */
     actionName?: string;
     /** The lifecycle phase if error occurred in a lifecycle handler */
-    lifecycle?: "created" | "destroyed" | "disconnect" | "reconnect" | "expire";
+    lifecycle?: "created" | "activated" | "deactivated" | "destroyed" | "disconnect" | "reconnect" | "expire";
 }
 /**
  * Error handler return type - controls error propagation
@@ -155,6 +155,20 @@ export interface HypenModuleDefinition<T = unknown> {
     stateStore?: StateStore<T>;
     handlers: {
         onCreated?: LifecycleHandler<T>;
+        /**
+         * Called every time the module becomes the active route target.
+         * Runs after `onCreated` on first mount, and again on each re-mount
+         * from the ManagedRouter's persistence cache. Use for data refresh,
+         * subscription (re)connects, or any "screen became visible" work.
+         */
+        onActivated?: LifecycleHandler<T>;
+        /**
+         * Called every time the module stops being the active route target.
+         * Runs before the module is cached for persistence OR before
+         * `onDestroyed` if the module is being torn down. Use for pausing
+         * timers, tearing down ephemeral subscriptions, etc.
+         */
+        onDeactivated?: LifecycleHandler<T>;
         onAction: Map<string, ActionHandler<T, any>>;
         onDestroyed?: LifecycleHandler<T>;
         /** Called when client disconnects (session persists for TTL) */
@@ -178,6 +192,8 @@ export declare class HypenAppBuilder<T> {
     private initialState;
     private options;
     private createdHandler?;
+    private activatedHandler?;
+    private deactivatedHandler?;
     private actionHandlers;
     private destroyedHandler?;
     private disconnectHandler?;
@@ -215,6 +231,39 @@ export declare class HypenAppBuilder<T> {
      * ```
      */
     onAction<P = unknown>(name: string, fn: ActionHandler<T, P>): this;
+    /**
+     * Register a handler that runs every time the module becomes the active
+     * route target.
+     *
+     * Unlike `onCreated`, which only runs once per module instance, `onActivated`
+     * runs on **every** mount — the first one (right after `onCreated`) and
+     * every subsequent re-entry when a cached module is restored by
+     * `ManagedRouter`. Use this hook for data refresh, (re)connecting
+     * subscriptions, starting timers, and any "screen became visible" work
+     * that should happen on every navigation to this route.
+     *
+     * @example
+     * ```typescript
+     * app
+     *   .defineState({ items: [], loading: false })
+     *   .onActivated(async (state) => {
+     *     state.loading = true;
+     *     state.items = await fetchItems();
+     *     state.loading = false;
+     *   });
+     * ```
+     */
+    onActivated(fn: LifecycleHandler<T>): this;
+    /**
+     * Register a handler that runs every time the module stops being the
+     * active route target.
+     *
+     * Runs before the module is cached for persistence (when the user
+     * navigates to another route) OR before `onDestroyed` if the module is
+     * being torn down. Use this for pausing timers, unsubscribing from
+     * ephemeral streams, and any "screen became hidden" cleanup.
+     */
+    onDeactivated(fn: LifecycleHandler<T>): this;
     /**
      * Register a handler for module destruction
      */
@@ -434,6 +483,13 @@ export declare class HypenModuleInstance<T extends object = any> {
     private definition;
     private state;
     private isDestroyed;
+    /**
+     * True when the module is currently the active route target (i.e.
+     * `onActivated` has fired more recently than `onDeactivated`).
+     * Used to make `activate()` / `deactivate()` idempotent so the
+     * `ManagedRouter` can call them safely regardless of state.
+     */
+    private isActive;
     private router;
     private globalContext?;
     private stateChangeCallbacks;
@@ -456,6 +512,27 @@ export declare class HypenModuleInstance<T extends object = any> {
      * Call this before renderSource to ensure state is fully initialized.
      */
     waitForReady(): Promise<void>;
+    /**
+     * Mark the module as the active route target and fire `onActivated`.
+     *
+     * Idempotent: calling `activate()` on an already-active module is a
+     * no-op. Internally awaits `waitForReady()` so that `onCreated` always
+     * runs to completion before `onActivated` fires, regardless of who
+     * calls this method and when.
+     *
+     * Called by `ManagedRouter` on every route mount — both fresh
+     * constructions and re-mounts from the persistence cache.
+     */
+    activate(): Promise<void>;
+    /**
+     * Mark the module as no longer the active route target and fire
+     * `onDeactivated`.
+     *
+     * Idempotent: calling `deactivate()` on an inactive module is a no-op.
+     * Called by `ManagedRouter` before persisting a module for later reuse
+     * OR before destroying it.
+     */
+    deactivate(): Promise<void>;
     /**
      * Create the global context API for this module
      */

package/dist/app.js

@@ -262,6 +262,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");
@@ -321,51 +368,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: () => {} };
@@ -714,6 +717,8 @@ class HypenAppBuilder {
   initialState;
   options;
   createdHandler;
+  activatedHandler;
+  deactivatedHandler;
   actionHandlers = new Map;
   destroyedHandler;
   disconnectHandler;
@@ -737,6 +742,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;
@@ -788,6 +801,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,
@@ -845,6 +860,7 @@ class HypenModuleInstance {
   definition;
   state;
   isDestroyed = false;
+  isActive = false;
   router;
   globalContext;
   stateChangeCallbacks = [];
@@ -924,6 +940,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");
@@ -1072,6 +1125,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);
@@ -1116,4 +1172,4 @@ export {
   HypenApp
 };
 
-//# debugId=B8AA1FCB3E096F2264756E2164756E21
+//# debugId=94DE9279313C0D1764756E2164756E21