@hypen-space/core 0.4.46 → 0.4.82

package/README.md

@@ -8,7 +8,7 @@ Hypen lets you write UI templates in a clean, declarative syntax:
 
 ```hypen
 Column {
-  Text("Hello, ${state.user.name}!")
+  Text("Hello, @{state.user.name}!")
   Button(onClick: @actions.logout) {
     Text("Sign Out")
   }
@@ -18,7 +18,7 @@ Column {
 The `@hypen-space/core` package provides the engine that:
 
 1. **Parses** your Hypen templates
-2. **Tracks** reactive state bindings (like `${state.user.name}`)
+2. **Tracks** reactive state bindings (like `@{state.user.name}`)
 3. **Generates patches** when state changes (instead of re-rendering everything)
 4. **Dispatches actions** triggered from the UI (like `@actions.logout`)
 
@@ -44,11 +44,11 @@ Hypen templates describe your UI structure. Components can have:
 
 ### State Bindings
 
-Use `${state.path}` to bind template values to your module's state:
+Use `@{state.path}` to bind template values to your module's state:
 
 ```hypen
-Text("Count: ${state.count}")
-Text("User: ${state.user.name}")
+Text("Count: @{state.count}")
+Text("User: @{state.user.name}")
 ```
 
 When state changes, only the affected parts of the UI update.
@@ -101,7 +101,7 @@ engine.setModule("counter", counter.actions, counter.stateKeys, counter.initialS
 
 engine.renderSource(`
   Column {
-    Text("Count: \${state.count}")
+    Text("Count: @{state.count}")
     Row {
       Button(onClick: @actions.decrement) { Text("-") }
       Button(onClick: @actions.increment) { Text("+") }
@@ -358,8 +358,8 @@ export default app
   .defineState({ items: ["A", "B", "C"] })
   .ui(hypen`
     Column {
-      ForEach(items: ${state.items}) {
-        Text("${index}: ${item}")
+      ForEach(items: @{state.items}) {
+        Text("@{index}: @{item}")
       }
     }
   `);
@@ -526,7 +526,6 @@ events.emit("userLogin", { userId: "123" });
 | `@hypen-space/core/components` | Built-in Router, Route, Link |
 | `@hypen-space/core/result` | Result type for error handling |
 | `@hypen-space/core/disposable` | Disposable pattern utilities |
-| `@hypen-space/core/retry` | Retry with backoff |
 | `@hypen-space/core/logger` | Structured logging |
 | `@hypen-space/core/events` | Typed event emitter |
 | `@hypen-space/server` | Node.js WASM engine, loader, discovery, RemoteServer |

package/dist/app.d.ts

@@ -6,10 +6,21 @@ import type { Action } from "./types.js";
 import type { Session } from "./remote/types.js";
 import { HypenError } from "./result.js";
 import { type DataSourcePlugin } from "./datasource.js";
+import type { StateStore } from "./persistence.js";
 export interface IEngine {
     setModule(name: string, actions: string[], stateKeys: string[], initialState: unknown): void;
+    registerModule(name: string, actions: string[], stateKeys: string[], initialState: unknown): void;
     onAction(actionName: string, handler: (action: Action) => void | Promise<void>): void;
-    notifyStateChange(paths: string[], changedValues: Record<string, unknown>): void;
+    /**
+     * Apply a sparse state update.
+     *
+     * @param scope  Lowercase module name to target a named module registered
+     *               via `registerModule`. Pass `null` (or empty string) to
+     *               target the primary module set via `setModule`.
+     * @param paths  Changed state paths (relative to the targeted module).
+     * @param values Map of `path -> new value`.
+     */
+    updateStateSparse(scope: string | null, paths: string[], values: Record<string, unknown>): void;
 }
 import type { HypenRouter } from "./router.js";
 import type { HypenGlobalContext, ModuleReference } from "./context.js";
@@ -137,6 +148,11 @@ export interface HypenModuleDefinition<T = unknown> {
         plugin: DataSourcePlugin;
         config: unknown;
     }>;
+    /**
+     * Pluggable state store for persistence across sessions.
+     * Set via the `.persist(store)` builder method.
+     */
+    stateStore?: StateStore<T>;
     handlers: {
         onCreated?: LifecycleHandler<T>;
         onAction: Map<string, ActionHandler<T, any>>;
@@ -171,6 +187,7 @@ export declare class HypenAppBuilder<T> {
     private template?;
     private _registry?;
     private dataSourceEntries;
+    private _stateStore?;
     constructor(initialState: T, options?: {
         persist?: boolean;
         version?: number;
@@ -248,6 +265,21 @@ export declare class HypenAppBuilder<T> {
      * @returns Builder for chaining
      */
     onError(fn: ErrorHandler<T>): this;
+    /**
+     * Attach a persistent state store.
+     * The store handles save/restore lifecycle automatically.
+     *
+     * @example
+     * ```typescript
+     * import { durableObjectStore, withKey } from "@hypen-space/cf";
+     *
+     * app
+     *   .defineState({ user: null, todos: [] }, { name: "TodoList" })
+     *   .persist(durableObjectStore(withKey(state => state.user?.id)))
+     *   .build();
+     * ```
+     */
+    persist(store: StateStore<T>): this;
     /**
      * Register a data source plugin for live database subscriptions.
      *
@@ -269,10 +301,10 @@ export declare class HypenAppBuilder<T> {
      *   .build();
      * ```
      *
-     * In Hypen DSL, bind to data source tables with `$provider.table`:
+     * In Hypen DSL, bind to data source tables with `@provider.table`:
      * ```hypen
-     * ForEach(items: $spacetime.message, key: "id") {
-     *   Text("${item.text}")
+     * ForEach(items: @spacetime.message, key: "id") {
+     *   Text("@{item.text}")
      * }
      * ```
      */
@@ -293,7 +325,7 @@ export declare class HypenAppBuilder<T> {
      *   })
      *   .ui(hypen`
      *     Column {
-     *       Text("Count: ${state.count}")
+     *       Text("Count: @{state.count}")
      *       Button { Text("+") }
      *         .onClick("@actions.increment")
      *     }
@@ -407,7 +439,16 @@ export declare class HypenModuleInstance<T extends object = any> {
     private stateChangeCallbacks;
     private dataSourceManager?;
     private dataSourceAccessor;
-    constructor(engine: IEngine, definition: HypenModuleDefinition<T>, router?: HypenRouter | null, globalContext?: HypenGlobalContext);
+    private stateStore?;
+    private currentPersistKey;
+    private persistDebounceTimer;
+    private sessionId;
+    /**
+     * Lowercase name used to address this module in the engine. Empty string
+     * for anonymous modules (which back the engine's primary module slot).
+     */
+    private moduleKey;
+    constructor(engine: IEngine, definition: HypenModuleDefinition<T>, router?: HypenRouter | null, globalContext?: HypenGlobalContext, sessionId?: string);
     /** Promise that resolves when onCreated handler has completed */
     private _readyPromise;
     /**
@@ -430,6 +471,15 @@ export declare class HypenModuleInstance<T extends object = any> {
      * @returns true if the error should be rethrown
      */
     private handleError;
+    /**
+     * Re-evaluate the persistence key and debounce saves on state mutation.
+     * Handles key transitions (null->value, value->null, value->different value).
+     */
+    private persistIfNeeded;
+    /**
+     * Activate persistence for the given key: load stored state and merge.
+     */
+    private activatePersistence;
     /**
      * Call the onCreated handler and connect data source plugins
      */

package/dist/app.js

@@ -723,6 +723,7 @@ class HypenAppBuilder {
   template;
   _registry;
   dataSourceEntries = [];
+  _stateStore;
   constructor(initialState, options, registry) {
     this.initialState = initialState;
     this.options = options || {};
@@ -756,6 +757,10 @@ class HypenAppBuilder {
     this.errorHandler = fn;
     return this;
   }
+  persist(store) {
+    this._stateStore = store;
+    return this;
+  }
   useDataSource(plugin, config2) {
     this.dataSourceEntries.push({ plugin, config: config2 });
     return this;
@@ -780,6 +785,7 @@ class HypenAppBuilder {
       initialState: this.initialState,
       template: this.template,
       dataSources: this.dataSourceEntries.length > 0 ? this.dataSourceEntries : undefined,
+      stateStore: this._stateStore,
       handlers: {
         onCreated: this.createdHandler,
         onAction: this.actionHandlers,
@@ -844,22 +850,33 @@ class HypenModuleInstance {
   stateChangeCallbacks = [];
   dataSourceManager;
   dataSourceAccessor = {};
-  constructor(engine, definition, router, globalContext) {
+  stateStore;
+  currentPersistKey = null;
+  persistDebounceTimer;
+  sessionId;
+  moduleKey = "";
+  constructor(engine, definition, router, globalContext, sessionId) {
     this.engine = engine;
     this.definition = definition;
     this.router = router ?? null;
     this.globalContext = globalContext;
-    const statePrefix = (definition.name || "").toLowerCase();
+    this.sessionId = sessionId ?? crypto.randomUUID();
+    this.stateStore = definition.stateStore;
+    const moduleKey = (definition.name || "").toLowerCase();
+    this.moduleKey = moduleKey;
     this.state = createObservableState(definition.initialState, {
       onChange: (change) => {
-        this.engine.notifyStateChange(change.paths, change.newValues);
+        this.engine.updateStateSparse(moduleKey || null, change.paths, change.newValues);
         this.stateChangeCallbacks.forEach((cb) => cb());
-      },
-      pathPrefix: statePrefix || undefined
+        this.persistIfNeeded();
+      }
     });
     const snapshot = getStateSnapshot(this.state);
-    const prefixedState = statePrefix ? { [statePrefix]: snapshot } : snapshot;
-    this.engine.setModule(definition.name || "AnonymousModule", definition.actions, definition.stateKeys, prefixedState);
+    if (moduleKey) {
+      this.engine.registerModule(moduleKey, definition.actions, definition.stateKeys, snapshot);
+    } else {
+      this.engine.setModule("AnonymousModule", definition.actions, definition.stateKeys, snapshot);
+    }
     for (const [actionName, handler] of definition.handlers.onAction) {
       log2.debug(`Registering action handler: ${actionName} for module ${definition.name}`);
       this.engine.onAction(actionName, async (action) => {
@@ -969,7 +986,54 @@ class HypenModuleInstance {
     log2.error(`${context.actionName ? `Action "${context.actionName}"` : `Lifecycle "${context.lifecycle}"`} error:`, error);
     return false;
   }
+  persistIfNeeded() {
+    if (!this.stateStore)
+      return;
+    const store = this.stateStore;
+    const newKey = store.resolveKey(this.state, this.definition.name || "AnonymousModule", this.sessionId);
+    if (newKey && !this.currentPersistKey) {
+      this.activatePersistence(newKey);
+      return;
+    }
+    if (!newKey && this.currentPersistKey) {
+      this.currentPersistKey = null;
+      return;
+    }
+    if (newKey && newKey !== this.currentPersistKey) {
+      this.activatePersistence(newKey);
+      return;
+    }
+    if (!this.currentPersistKey)
+      return;
+    clearTimeout(this.persistDebounceTimer);
+    this.persistDebounceTimer = setTimeout(() => {
+      const snapshot = getStateSnapshot(this.state);
+      store.save(this.currentPersistKey, snapshot);
+    }, 50);
+  }
+  async activatePersistence(key) {
+    this.currentPersistKey = key;
+    const stored = await this.stateStore.load(key);
+    if (stored) {
+      const merged = { ...this.definition.initialState, ...stored };
+      Object.assign(this.state, merged);
+    } else {
+      const snapshot = getStateSnapshot(this.state);
+      await this.stateStore.save(key, snapshot);
+    }
+  }
   async callCreatedHandler() {
+    if (this.stateStore) {
+      const key = this.stateStore.resolveKey(this.state, this.definition.name || "AnonymousModule", this.sessionId);
+      if (key) {
+        this.currentPersistKey = key;
+        const stored = await this.stateStore.load(key);
+        if (stored) {
+          const merged = { ...this.definition.initialState, ...stored };
+          Object.assign(this.state, merged);
+        }
+      }
+    }
     if (this.definition.dataSources?.length) {
       const dsEngine = this.engine;
       this.dataSourceManager = new DataSourceManager(dsEngine);
@@ -1008,6 +1072,11 @@ class HypenModuleInstance {
   async destroy() {
     if (this.isDestroyed)
       return;
+    if (this.currentPersistKey && this.stateStore) {
+      clearTimeout(this.persistDebounceTimer);
+      const snapshot = getStateSnapshot(this.state);
+      await this.stateStore.save(this.currentPersistKey, snapshot);
+    }
     if (this.dataSourceManager) {
       try {
         await this.dataSourceManager.disconnectAll();
@@ -1047,4 +1116,4 @@ export {
   HypenApp
 };
 
-//# debugId=955468B608A15BFE64756E2164756E21
+//# debugId=B8AA1FCB3E096F2264756E2164756E21