@hypen-space/core 0.2.11 → 0.3.0

package/README.md

@@ -124,34 +124,34 @@ interface UserState {
 const userModule = app
   .defineState<UserState>({ user: null, loading: false })
 
-  // Called when module is created
-  .onCreated(async ({ state, next }) => {
+  // Lifecycle handler: receives (state, context?)
+  .onCreated(async (state, context) => {
     state.loading = true;
-    next(); // Sync state changes to engine
+    // State changes are auto-synced via Proxy
   })
 
-  // Handle actions dispatched from UI
-  .onAction("loadUser", async ({ state, action, next }) => {
+  // 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);
     state.loading = false;
-    next();
+    // State changes are auto-synced via Proxy
+    // next.router is available for programmatic navigation
   })
 
-  .onAction("logout", ({ state, next }) => {
+  .onAction("logout", ({ state }) => {
     state.user = null;
-    next();
   })
 
-  // Called when module is destroyed
-  .onDestroyed(({ state }) => {
+  // Lifecycle handler: receives (state, context?)
+  .onDestroyed((state, context) => {
     console.log("Cleanup");
   })
 
   .build();
 ```
 
-The `next()` callback synchronizes state changes with the engine after async operations.
+State mutations are automatically tracked via Proxy and synced to the engine.
 
 ## State
 
@@ -346,6 +346,171 @@ const engine = new BrowserEngine();
 await engine.init({ wasmPath: "/hypen_engine_bg.wasm" });
 ```
 
+## Single-File Components
+
+Use template literals with the `hypen`, `state`, `item`, and `index` helpers:
+
+```typescript
+import { app, hypen, state, item, index } from "@hypen-space/core";
+
+export default app
+  .defineState({ items: ["A", "B", "C"] })
+  .ui(hypen`
+    Column {
+      ForEach(items: ${state.items}) {
+        Text("${index}: ${item}")
+      }
+    }
+  `);
+```
+
+## Error Handling
+
+### Result Type
+
+Type-safe error handling without exceptions:
+
+```typescript
+import { Ok, Err, fromPromise, match, all, isOk, isErr } from "@hypen-space/core";
+
+// Create results
+const success = Ok(42);
+const failure = Err(new Error("failed"));
+
+// Pattern matching
+const message = match(result, {
+  ok: (value) => `Got ${value}`,
+  err: (error) => `Failed: ${error.message}`,
+});
+
+// Convert promises to Result
+const result = await fromPromise(fetch("/api/data"));
+
+// Combine multiple results
+const combined = all([result1, result2, result3]);
+```
+
+### Module Error Handler
+
+Handle errors in module actions:
+
+```typescript
+app
+  .defineState({ error: null })
+  .onError(({ error, action, state }) => {
+    console.error(`Action ${action.name} failed:`, error);
+    state.error = error.message;
+    return { handled: true };  // Prevent error from propagating
+  })
+  .onAction("riskyAction", async ({ state }) => {
+    throw new Error("Something went wrong");
+  });
+```
+
+## Session Lifecycle
+
+Handle connection state for remote UI:
+
+```typescript
+app
+  .defineState({ connected: true })
+  .onDisconnect(({ state, reason }) => {
+    state.connected = false;
+    console.log("Disconnected:", reason);
+  })
+  .onReconnect(({ state, wasExpired }) => {
+    state.connected = true;
+    if (wasExpired) {
+      // Session was restored from server
+    }
+  })
+  .onExpire(({ state, reason }) => {
+    // Session expired, need to re-authenticate
+    state.connected = false;
+  });
+```
+
+## Disposable Pattern
+
+Resource management with automatic cleanup:
+
+```typescript
+import { DisposableStack, using, disposableListener } from "@hypen-space/core";
+
+// Automatic cleanup with using()
+await using(new DisposableStack(), async (stack) => {
+  const listener = stack.use(
+    disposableListener(window, "resize", handleResize)
+  );
+  // listener is automatically removed when scope exits
+});
+
+// Manual stack management
+const stack = new DisposableStack();
+stack.use(disposableTimeout(() => {}, 1000));
+stack.use(disposableInterval(() => {}, 100));
+stack.dispose(); // Cleans up everything
+```
+
+## Retry Utilities
+
+Retry failed operations with backoff:
+
+```typescript
+import { retry, retryResult, RetryPresets } from "@hypen-space/core";
+
+// Simple retry with exponential backoff
+const data = await retry(
+  () => fetch("/api/data"),
+  { maxAttempts: 3, backoff: "exponential" }
+);
+
+// Retry returning Result type
+const result = await retryResult(
+  () => fetchData(),
+  RetryPresets.network  // Pre-configured for network errors
+);
+```
+
+## Logger
+
+Structured logging with levels:
+
+```typescript
+import { createLogger, setLogLevel, Logger } from "@hypen-space/core";
+
+const log = createLogger("MyModule");
+
+log.debug("Detailed info");
+log.info("Normal operation");
+log.warn("Something unexpected");
+log.error("Something failed", error);
+
+// Configure globally
+setLogLevel("warn");  // Only warn and error
+```
+
+## Typed Events
+
+Type-safe event emitter:
+
+```typescript
+import { TypedEventEmitter, createEventEmitter } from "@hypen-space/core";
+
+interface MyEvents {
+  userLogin: { userId: string };
+  dataLoaded: { items: string[] };
+}
+
+const events = createEventEmitter<MyEvents>();
+
+events.on("userLogin", ({ userId }) => {
+  console.log("User logged in:", userId);
+});
+
+events.emit("userLogin", { userId: "123" });
+```
+
 ## Package Exports
 
 | Export | Description |
@@ -362,6 +527,12 @@ await engine.init({ wasmPath: "/hypen_engine_bg.wasm" });
 | `@hypen-space/core/loader` | Component loader |
 | `@hypen-space/core/discovery` | Component discovery |
 | `@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/core/hypen` | Template helpers (hypen, state, item, index) |
 
 ## Requirements