storion 0.5.0 → 0.7.0

package/README.md

@@ -282,9 +282,7 @@ export const settingsStore = store({
 
     return {
       // Direct value
-      setTheme: (theme: "light" | "dark") => {
-        setTheme(theme);
-      },
+      setTheme,
 
       // Reducer - returns new value
       toggleTheme: () => {
@@ -387,6 +385,60 @@ export const syncStore = store({
 });
 ```
 
+### Effect Re-run
+
+Effects automatically re-run when their tracked state changes. There are three ways an effect can be triggered to re-run:
+
+**1. Tracked state changes** — The most common case. When any state property read during the effect's execution changes, the effect re-runs automatically.
+
+```ts
+effect(() => {
+  // This effect tracks `state.count` and re-runs when it changes
+  console.log("Count is:", state.count);
+});
+```
+
+**2. Calling `ctx.refresh()` asynchronously** — You can manually trigger a re-run from async code (promises, setTimeout, event handlers).
+
+```ts
+effect((ctx) => {
+  // Schedule a refresh after some async work
+  ctx.safe(fetchData()).then(() => {
+    ctx.refresh(); // Re-runs the effect
+  });
+
+  // Or from a setTimeout
+  setTimeout(() => {
+    ctx.refresh();
+  }, 1000);
+});
+```
+
+**3. Returning `ctx.refresh`** — For synchronous refresh requests, return `ctx.refresh` from the effect. The effect will re-run after the current execution completes.
+
+```ts
+effect((ctx) => {
+  const data = async.wait(state.asyncData); // May throw a promise
+  // If we get here, data is available
+  state.result = transform(data);
+
+  // Return ctx.refresh to request a re-run after this execution
+  if (needsAnotherRun) {
+    return ctx.refresh;
+  }
+});
+```
+
+> **Important:** Effects cannot re-run while already executing. Calling `ctx.refresh()` synchronously during effect execution throws an error:
+>
+> ```ts
+> effect((ctx) => {
+>   ctx.refresh(); // ❌ Error: Effect is already running, cannot refresh
+> });
+> ```
+>
+> This prevents infinite loops and ensures predictable execution. Use the return pattern or async scheduling instead.
+
 ### Effect with Safe Async
 
 **The problem:** When an effect re-runs before an async operation completes, you get stale data or "state update on unmounted component" warnings. Managing this manually is error-prone.
@@ -745,17 +797,14 @@ function Dashboard() {
 
 // 3c. With custom deps - refetch when deps change
 function UserById({ userId }: { userId: string }) {
-  const { user } = useStore(
-    ({ get, trigger }) => {
-      const [state, actions] = get(userStore);
+  const { user } = useStore(({ get, trigger }) => {
+    const [state, actions] = get(userStore);
 
-      // Refetch when userId prop changes
-      trigger(() => actions.currentUser.dispatch(), [userId]);
+    // Refetch when userId prop changes
+    trigger(actions.currentUser.dispatch, [userId]);
 
-      return { user: state.currentUser };
-    },
-    [userId] // selector deps for proper tracking
-  );
+    return { user: state.currentUser };
+  });
 
   return <div>{user.data?.name}</div>;
 }
@@ -824,7 +873,7 @@ function SearchBox() {
 │       │                                                                 │
 │       ├── Once ever? ────►  trigger(fn, [])                             │
 │       │                                                                 │
-│       ├── Every visit? ──►  trigger(fn, [id])                           │
+│       ├── Every visit? ──►  trigger(fn, [context.id])                   │
 │       │                                                                 │
 │       └── When deps change? ► trigger(fn, [dep1, dep2])                 │
 │                                                                         │
@@ -888,9 +937,9 @@ function Dashboard() {
     const [postState, postActions] = get(postStore);
     const [commentState, commentActions] = get(commentStore);
 
-    trigger(userActions.fetch, []);
-    trigger(postActions.fetch, []);
-    trigger(commentActions.fetch, []);
+    trigger(userActions.fetch);
+    trigger(postActions.fetch);
+    trigger(commentActions.fetch);
 
     // Wait for ALL async states - suspends until all are ready
     const [user, posts, comments] = async.all(
@@ -919,10 +968,8 @@ function FastestResult() {
   const { result } = useStore(({ get, trigger }) => {
     const [state, actions] = get(searchStore);
 
-    trigger(() => {
-      actions.searchAPI1(query);
-      actions.searchAPI2(query);
-    }, [query]);
+    trigger(actions.searchAPI1, [], query);
+    trigger(actions.searchAPI2, [], query);
 
     // Returns whichever finishes first
     return {
@@ -946,6 +993,156 @@ function FastestResult() {
 | `async.isLoading(state)` | `boolean`                             | Loading indicator         |
 | `async.isError(state)`   | `boolean`                             | Error check               |
 
+### Derived Async State with `async.derive()`
+
+**The problem:** You need to compute a value from multiple async states. If any source is loading, the derived value should be loading. If any errors, it should error. Writing this logic manually is verbose and error-prone.
+
+**With Storion:** Use `async.derive()` to create computed async state. It uses `async.wait()` internally, so it automatically handles pending/error states and re-computes when sources change.
+
+```ts
+import { store } from "storion";
+import { async, type AsyncState } from "storion/async";
+
+interface User {
+  id: string;
+  name: string;
+}
+
+interface Post {
+  id: string;
+  title: string;
+  authorId: string;
+}
+
+export const dashboardStore = store({
+  name: "dashboard",
+  state: {
+    user: async.fresh<User>(),
+    posts: async.fresh<Post[]>(),
+    // Derived async state - computed from user + posts
+    summary: async.fresh<{ userName: string; postCount: number }>(),
+  },
+  setup({ state, focus }) {
+    // Fetch actions
+    const userActions = async(focus("user"), async (ctx, userId: string) => {
+      const res = await fetch(`/api/users/${userId}`, { signal: ctx.signal });
+      return res.json();
+    });
+
+    const postsActions = async(focus("posts"), async (ctx, userId: string) => {
+      const res = await fetch(`/api/users/${userId}/posts`, {
+        signal: ctx.signal,
+      });
+      return res.json();
+    });
+
+    // Derive summary from user + posts
+    // - If user OR posts is pending → summary is pending
+    // - If user OR posts has error → summary has error
+    // - If both succeed → summary is success with computed value
+    async.derive(focus("summary"), () => {
+      const user = async.wait(state.user);
+      const posts = async.wait(state.posts);
+      return {
+        userName: user.name,
+        postCount: posts.length,
+      };
+    });
+
+    return {
+      fetchUser: userActions.dispatch,
+      fetchPosts: postsActions.dispatch,
+    };
+  },
+});
+```
+
+**Conditional dependencies:**
+
+```ts
+// Derive with conditional async sources
+async.derive(focus("result"), () => {
+  const type = async.wait(state.type);
+
+  // Dynamically choose which async state to wait for
+  if (type === "user") {
+    return async.wait(state.userData);
+  } else {
+    return async.wait(state.guestData);
+  }
+});
+```
+
+**Parallel waiting with `async.all()`:**
+
+```ts
+// Wait for multiple states in parallel (more efficient)
+async.derive(focus("combined"), () => {
+  const [user, posts, comments] = async.all(
+    state.user,
+    state.posts,
+    state.comments
+  );
+  return { user, posts, comments };
+});
+```
+
+**Stale mode - preserve data during recomputation:**
+
+```ts
+state: {
+  // Stale mode: keeps previous computed value while recomputing
+  summary: async.stale({ userName: "Loading...", postCount: 0 }),
+}
+
+// The derive will preserve stale data during pending/error
+async.derive(focus("summary"), () => {
+  const user = async.wait(state.user);
+  const posts = async.wait(state.posts);
+  return { userName: user.name, postCount: posts.length };
+});
+```
+
+**Key behaviors:**
+
+| Source State       | Derived State                       |
+| ------------------ | ----------------------------------- |
+| Any source pending | `pending` (stale: preserves data)   |
+| Any source error   | `error` (stale: preserves data)     |
+| All sources ready  | `success` with computed value       |
+| Sources change     | Auto-recomputes via effect tracking |
+
+**`async.derive()` vs manual effects:**
+
+```ts
+// ❌ Manual - verbose, error-prone
+effect(() => {
+  if (state.user.status === "pending" || state.posts.status === "pending") {
+    state.summary = asyncState("fresh", "pending");
+    return;
+  }
+  if (state.user.status === "error") {
+    state.summary = asyncState("fresh", "error", state.user.error);
+    return;
+  }
+  if (state.posts.status === "error") {
+    state.summary = asyncState("fresh", "error", state.posts.error);
+    return;
+  }
+  state.summary = asyncState("fresh", "success", {
+    userName: state.user.data.name,
+    postCount: state.posts.data.length,
+  });
+});
+
+// ✅ With async.derive - clean and automatic
+async.derive(focus("summary"), () => {
+  const user = async.wait(state.user);
+  const posts = async.wait(state.posts);
+  return { userName: user.name, postCount: posts.length };
+});
+```
+
 ### Dependency Injection
 
 **The problem:** Your stores need shared services (API clients, loggers, config) but importing singletons directly causes issues:
@@ -1026,6 +1223,72 @@ testApp.clear(); // Clear all cached instances
 testApp.dispose(); // Dispose container and all instances
 ```
 
+### Parameterized Factories with `create()`
+
+**The problem:** Some services need configuration at creation time (database connections, loggers with namespaces, API clients with different endpoints). But `get()` only works with parameterless factories since it caches instances.
+
+**With Storion:** Use `create()` for parameterized factories. Unlike `get()`, `create()` always returns fresh instances and supports additional arguments.
+
+```ts
+import { store, container, type Resolver } from "storion";
+
+// Parameterized factory - receives resolver + custom args
+function createLogger(resolver: Resolver, namespace: string) {
+  return {
+    info: (msg: string) => console.log(`[${namespace}] INFO: ${msg}`),
+    error: (msg: string) => console.error(`[${namespace}] ERROR: ${msg}`),
+  };
+}
+
+function createDatabase(
+  resolver: Resolver,
+  config: { host: string; port: number }
+) {
+  return {
+    query: (sql: string) =>
+      fetch(`http://${config.host}:${config.port}/query`, {
+        method: "POST",
+        body: sql,
+      }),
+    close: () => {
+      /* cleanup */
+    },
+  };
+}
+
+// Use in store setup
+const userStore = store({
+  name: "user",
+  state: { users: [] as User[] },
+  setup({ create }) {
+    // Each call creates a fresh instance with specific config
+    const logger = create(createLogger, "user-store");
+    const db = create(createDatabase, { host: "localhost", port: 5432 });
+
+    return {
+      fetchUsers: async () => {
+        logger.info("Fetching users...");
+        await db.query("SELECT * FROM users");
+      },
+    };
+  },
+});
+
+// Also works with container directly
+const app = container();
+const authLogger = app.create(createLogger, "auth");
+const adminDb = app.create(createDatabase, { host: "admin.db", port: 5433 });
+```
+
+**Key differences between `get()` and `create()`:**
+
+| Feature    | `get()`                     | `create()`                                    |
+| ---------- | --------------------------- | --------------------------------------------- |
+| Caching    | Yes (singleton per factory) | No (always fresh)                             |
+| Arguments  | None (parameterless only)   | Supports additional arguments                 |
+| Use case   | Shared services             | Configured instances, child stores            |
+| Middleware | Applied                     | Applied (without args) / Bypassed (with args) |
+
 ### Middleware
 
 **The problem:** You need cross-cutting behavior (logging, persistence, devtools) applied to some or all stores, without modifying each store individually.
@@ -1145,8 +1408,11 @@ const myStore = store({
 ```ts
 interface StoreContext<TState, TActions> {
   state: TState; // First-level props only (state.x = y)
-  get<T>(spec: StoreSpec<T>): StoreTuple; // Get dependency store
-  get<T>(factory: Factory<T>): T; // Get DI service
+  get<T>(spec: StoreSpec<T>): StoreTuple; // Get dependency store (cached)
+  get<T>(factory: Factory<T>): T; // Get DI service (cached)
+  create<T>(spec: StoreSpec<T>): StoreInstance<T>; // Create child store (fresh)
+  create<T>(factory: Factory<T>): T; // Create service (fresh)
+  create<R, A>(factory: (r, ...a: A) => R, ...a: A): R; // Parameterized factory
   focus<P extends Path>(path: P): Focus; // Lens-like accessor
   update(fn: (draft: TState) => void): void; // For nested/array mutations
   dirty(prop?: keyof TState): boolean; // Check if state changed
@@ -1157,6 +1423,29 @@ interface StoreContext<TState, TActions> {
 
 > **Note:** `state` allows direct assignment only for first-level properties. Use `update()` for nested objects, arrays, or batch updates.
 
+**`get()` vs `create()` — When to use each:**
+
+| Method     | Caching  | Use case                                               |
+| ---------- | -------- | ------------------------------------------------------ |
+| `get()`    | Cached   | Shared dependencies, singleton services                |
+| `create()` | No cache | Child stores, parameterized factories, fresh instances |
+
+```ts
+setup({ get, create }) {
+  // get() - cached, same instance every time
+  const api = get(apiService); // Singleton
+
+  // create() - fresh instance each call
+  const childStore = create(childSpec); // New store instance
+
+  // create() with arguments - parameterized factory
+  const db = create(createDatabase, { host: 'localhost', port: 5432 });
+  const logger = create(createLogger, 'auth-store');
+
+  return { /* ... */ };
+}
+```
+
 ### React (`storion/react`)
 
 | Export                     | Description                               |
@@ -1171,10 +1460,13 @@ interface StoreContext<TState, TActions> {
 #### useStore Selector
 
 ```ts
-// Selector receives context with get() for accessing stores
-const result = useStore(({ get, mixin, once }) => {
+// Selector receives context with get(), create(), mixin(), once()
+const result = useStore(({ get, create, mixin, once }) => {
   const [state, actions] = get(myStore);
-  const service = get(myFactory);
+  const service = get(myFactory); // Cached
+
+  // create() for parameterized factories (fresh instance each render)
+  const logger = create(createLogger, "my-component");
 
   // Run once on mount
   once(() => actions.init());
@@ -1194,6 +1486,7 @@ const result = useStore(({ get, mixin, once }) => {
 | `async.all(...states)`            | Wait for all states to be ready             |
 | `async.any(...states)`            | Get first ready state                       |
 | `async.race(states)`              | Race between states                         |
+| `async.derive(focus, computeFn)`  | Derive async state from other async states  |
 | `async.hasData(state)`            | Check if state has data                     |
 | `async.isLoading(state)`          | Check if state is loading                   |
 | `async.isError(state)`            | Check if state has error                    |

package/dist/async/async.d.ts

@@ -114,6 +114,55 @@ export declare namespace async {
         status: "error";
         error: Error;
     };
+    /**
+     * Derive an async state from other async states using a synchronous computation.
+     * The computation function uses `async.wait()` to extract data from async states,
+     * which throws promises when states are pending.
+     *
+     * Key behaviors:
+     * - If `computeFn` throws a promise (via `async.wait`), sets focus to pending and re-runs after promise settles
+     * - If `computeFn` throws an error, sets focus to error state
+     * - If `computeFn` returns a value, sets focus to success state
+     * - If `computeFn` returns a promise (not throws), throws an error - must be synchronous
+     * - Uses a single wrapper promise to avoid cascading re-renders
+     *
+     * @param focus - Focus to update with derived async state
+     * @param computeFn - Synchronous computation function that uses `async.wait()` to read async states
+     * @returns Dispose function to stop the derivation
+     *
+     * @example
+     * // Basic usage - derive from multiple async states
+     * async.derive(focus('c'), () => {
+     *   const a = async.wait(state.a);
+     *   const b = async.wait(state.b);
+     *   return a + b;
+     * });
+     *
+     * @example
+     * // Conditional dependencies
+     * async.derive(focus('result'), () => {
+     *   const type = async.wait(state.type);
+     *   if (type === 'user') {
+     *     return async.wait(state.userData);
+     *   } else {
+     *     return async.wait(state.guestData);
+     *   }
+     * });
+     *
+     * @example
+     * // For parallel waiting, use async.all
+     * async.derive(focus('combined'), () => {
+     *   const [a, b, c] = async.all(state.a, state.b, state.c);
+     *   return { a, b, c };
+     * });
+     *
+     * @example
+     * // With stale mode - preserves data during loading/error
+     * async.derive(focus('result'), () => {
+     *   return async.wait(state.userData);
+     * });
+     */
+    function derive<T, M extends AsyncMode = "fresh">(focus: Focus<AsyncState<T, M>>, computeFn: () => T): VoidFunction;
 }
 export {};
 //# sourceMappingURL=async.d.ts.map

package/dist/async/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/async/async.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/async/async.ts"],"names":[],"mappings":"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"}

package/dist/async/index.js

@@ -1,3 +1,5 @@
+import { e as effect } from "../effect-DPAYSuW3.js";
+import { u as untrack } from "../emitter-BA44OHdL.js";
 class AsyncNotReadyError extends Error {
   constructor(message, status) {
     super(message);
@@ -523,6 +525,54 @@ function asyncState(mode, status, dataOrError, errorOrExtra, extra) {
     return state.status === "error";
   }
   async2.isError = isError;
+  function derive(focus, computeFn) {
+    const [getState, setState] = focus;
+    let hasSetPending = false;
+    return effect((ctx) => {
+      const currentState = untrack(getState);
+      const mode = currentState.mode;
+      const staleData = mode === "stale" ? currentState.data : currentState.status === "success" ? currentState.data : void 0;
+      try {
+        const result = computeFn();
+        if (result !== null && result !== void 0 && typeof result.then === "function") {
+          throw new Error(
+            "async.derive: computeFn must be synchronous. Use async.wait() for async values, not async/await or returning promises."
+          );
+        }
+        hasSetPending = false;
+        if (mode === "stale") {
+          setState(asyncState("stale", "success", result));
+        } else {
+          setState(asyncState("fresh", "success", result));
+        }
+      } catch (ex) {
+        if (ex !== null && ex !== void 0 && typeof ex.then === "function") {
+          if (!hasSetPending) {
+            hasSetPending = true;
+            if (mode === "stale") {
+              setState(
+                asyncState("stale", "pending", staleData)
+              );
+            } else {
+              setState(asyncState("fresh", "pending"));
+            }
+          }
+          ctx.safe(ex).then(ctx.refresh, ctx.refresh);
+        } else {
+          hasSetPending = false;
+          const error = ex instanceof Error ? ex : new Error(String(ex));
+          if (mode === "stale") {
+            setState(
+              asyncState("stale", "error", staleData, error)
+            );
+          } else {
+            setState(asyncState("fresh", "error", error));
+          }
+        }
+      }
+    });
+  }
+  async2.derive = derive;
 })(async || (async = {}));
 export {
   AsyncAggregateError,

package/dist/collection.d.ts

@@ -1,3 +1,15 @@
+export interface Collection<TKey, TValue> {
+    with(key: TKey, callback: (item: TValue) => void): this;
+    has(key: TKey): boolean;
+    get(key: TKey): TValue;
+    set(key: TKey, value: TValue): this;
+    size: number;
+    clear(): this;
+    delete(key: TKey): this;
+    keys(): IterableIterator<TKey>;
+    values(): IterableIterator<TValue>;
+    entries(): IterableIterator<[TKey, TValue]>;
+}
 /**
  * Lazy-instantiation Map wrapper.
  *
@@ -18,25 +30,5 @@
  * @param initialItems - Optional initial entries
  * @returns A Map-like object with lazy instantiation on `get()`
  */
-export declare function collection<TKey, TValue>(createItem: (key: TKey) => TValue, initialItems?: readonly [TKey, TValue][]): {
-    with(key: TKey, callback: (item: TValue) => void): /*elided*/ any;
-    /** Check if key exists (does NOT create item) */
-    has(key: TKey): boolean;
-    /** Get item by key, creating it if it doesn't exist */
-    get(key: TKey): NonNullable<TValue>;
-    /** Explicitly set an item */
-    set(key: TKey, value: TValue): /*elided*/ any;
-    /** Number of items in the collection */
-    readonly size: number;
-    /** Remove all items */
-    clear(): /*elided*/ any;
-    /** Remove a specific item */
-    delete(key: TKey): /*elided*/ any;
-    /** Iterate over keys */
-    keys(): MapIterator<TKey>;
-    /** Iterate over values */
-    values(): MapIterator<TValue>;
-    /** Iterate over [key, value] pairs */
-    entries(): MapIterator<[TKey, TValue]>;
-};
+export declare function collection<TKey, TValue>(createItem: (key: TKey) => TValue, initialItems?: readonly [TKey, TValue][]): Collection<TKey, TValue>;
 //# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EACrC,UAAU,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,EACjC,YAAY,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE;cAK5B,IAAI,YAAY,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;IAOhD,iDAAiD;aACxC,IAAI;IAIb,uDAAuD;aAC9C,IAAI;IAOb,6BAA6B;aACpB,IAAI,SAAS,MAAM;IAK5B,wCAAwC;;IAKxC,uBAAuB;;IAMvB,6BAA6B;gBACjB,IAAI;IAKhB,wBAAwB;;IAKxB,0BAA0B;;IAK1B,sCAAsC;;EAKzC"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU,CAAC,IAAI,EAAE,MAAM;IACtC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACxD,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC;IACxB,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;IACvB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,IAAI,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACnC,OAAO,IAAI,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EACrC,UAAU,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,MAAM,EACjC,YAAY,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GACvC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CA8D1B"}

package/dist/core/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/core/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEhB,MAAM,UAAU,CAAC;AAWlB,UAAU,uBAAuB;IAC/B,sDAAsD;IACtD,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC;IACnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;CACrB;AAYD;;GAEG;AACH,UAAU,WAAW;IACnB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAAC;IAC7C;;OAEG;IACH,QAAQ,EAAE;QACR,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;QACzC,KAAK,IAAI,IAAI,CAAC;KACf,CAAC;CACH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,WAoLvB,CAAC"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/core/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEhB,MAAM,UAAU,CAAC;AAYlB,UAAU,uBAAuB;IAC/B,sDAAsD;IACtD,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC;IACnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;CACrB;AAYD;;GAEG;AACH,UAAU,WAAW;IACnB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAAC;IAC7C;;OAEG;IACH,QAAQ,EAAE;QACR,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;QACzC,KAAK,IAAI,IAAI,CAAC;KACf,CAAC;CACH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,WAkLvB,CAAC"}

package/dist/core/createResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createResolver.d.ts","sourceRoot":"","sources":["../../src/core/createResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,OAAO,EAEP,UAAU,EACV,QAAQ,EACR,eAAe,EAIhB,MAAM,UAAU,CAAC;AAIlB,YAAY,EACV,OAAO,EACP,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,eAAe,GAChB,MAAM,UAAU,CAAC;AAmClB;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAkKtE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAClB,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,EACxC,UAAU,EAAE,UAAU,GACrB,UAAU,CAOZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAa,GAAG,UAAU,CAUvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,GACpD,UAAU,CAMZ"}
+{"version":3,"file":"createResolver.d.ts","sourceRoot":"","sources":["../../src/core/createResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,OAAO,EAEP,UAAU,EACV,QAAQ,EACR,eAAe,EAIhB,MAAM,UAAU,CAAC;AAKlB,YAAY,EACV,OAAO,EACP,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,eAAe,GAChB,MAAM,UAAU,CAAC;AAmClB;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA6JtE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAClB,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,EACxC,UAAU,EAAE,UAAU,GACrB,UAAU,CAOZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAa,GAAG,UAAU,CAUvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,GACpD,UAAU,CAMZ"}

package/dist/core/disposable.d.ts

@@ -0,0 +1,18 @@
+import { Disposable } from '../types';
+
+/**
+ * Attempts to dispose a value if it has a `dispose` property.
+ *
+ * Supports multiple disposal patterns:
+ * - If `dispose` is a function, it will be called directly
+ * - If `dispose` is an array, each item will be processed:
+ *   - Functions are called directly
+ *   - Objects are recursively disposed via `tryDispose`
+ *
+ * @param value - The value to attempt disposal on. Can be any type;
+ *                non-disposable values are safely ignored.
+ */
+export declare function tryDispose(value: unknown): void;
+export declare function isDisposable(value: unknown): value is Disposable;
+export declare function willDispose(value: unknown): VoidFunction;
+//# sourceMappingURL=disposable.d.ts.map

package/dist/core/disposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../src/core/disposable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,QAoBxC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAMhE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAExD"}

package/dist/core/effect.d.ts

@@ -115,6 +115,26 @@ export interface EffectContext {
      * });
      */
     safe<TArgs extends unknown[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn | undefined;
+    /**
+     * Manually trigger a re-run of the effect.
+     * Useful for async.derive pattern where thrown promises should trigger re-computation.
+     *
+     * Note: If called while the effect is currently running, the refresh will be
+     * scheduled for after the current run completes.
+     *
+     * @example
+     * effect((ctx) => {
+     *   try {
+     *     const data = async.wait(state.asyncData); // throws if pending
+     *     state.computed = transform(data);
+     *   } catch (ex) {
+     *     if (isPromise(ex)) {
+     *       ctx.safe(ex).then(ctx.refresh, ctx.refresh);
+     *     }
+     *   }
+     * });
+     */
+    refresh(): void;
 }
 /**
  * Effect function type.