@ilha/store 0.2.1 → 0.3.0

package/README.md

@@ -38,6 +38,8 @@ store.setState({ count: 1 });
 store.getState(); // → { count: 1 }
 ```
 
+For consuming a store inside an island, jump to [Usage with Ilha Islands](#usage-with-ilha-islands).
+
 ---
 
 ## API
@@ -87,7 +89,7 @@ store.setState((s) => ({ count: s.count + 1 }));
 
 ### `store.getState()`
 
-Returns the current state snapshot.
+Returns the current state snapshot. Non-reactive — use `select` for reactive reads inside an island.
 
 ```ts
 store.getState(); // → { count: 5 }
@@ -105,9 +107,32 @@ store.getInitialState(); // → { count: 0 }
 
 ---
 
+### `store.select(selector)` — reactive accessor
+
+Projects a slice of state into a **signal-shaped accessor**: a `() => S` function that reads the current value when called, and tracks reactivity automatically inside any ilha tracking scope (`.render()`, `.derived()`, `.effect()`).
+
+```ts
+const store = createStore({ count: 0, name: "Ada" });
+
+const count = store.select((s) => s.count);
+const name = store.select((s) => s.name);
+
+count(); // → 0    (read)
+store.setState({ count: 5 });
+count(); // → 5    (reflects the change)
+```
+
+The returned accessor has the same shape as `signal()` and `context()` from `ilha` core, so it composes naturally with `html\`\``interpolation and`.bind()`. See [Usage with Ilha Islands](#usage-with-ilha-islands) below for the full pattern.
+
+The slice is memoized — accessors only notify dependents when the selected value changes (compared with `Object.is`). Setting `count` to its current value, or mutating an unrelated field, does not trigger downstream re-runs.
+
+> **Hoist `select` calls out of render functions.** Each call allocates a fresh `computed`. Define selectors at module scope or inside an island's closure setup — not inside the `.render()` callback itself.
+
+---
+
 ### `store.subscribe(listener)`
 
-Subscribes to all state changes. The listener receives the next and previous state. Returns an unsubscribe function.
+Subscribes to all state changes. The listener receives the next and previous state. Returns an unsubscribe function. Use this for **imperative** subscriptions outside an island scope (e.g. a WebSocket handler, `localStorage` sync); inside an island, prefer `select`.
 
 ```ts
 const unsub = store.subscribe((state, prev) => {
@@ -161,13 +186,13 @@ store.bind(
 
 ## Usage with Ilha Islands
 
-The most common pattern is reading the store inside an island's `.effect()` and calling `store.subscribe()` to drive reactive re-renders:
+`select` returns the same `() => T` accessor shape as `signal()` and `context()` from `ilha` core. That means store-backed state composes with islands the same way context signals do — read it inside `html\`\``and the surrounding render scope subscribes automatically. No`.effect()`plumbing, no manual`subscribe` wiring.
 
 ```ts
 import { createStore } from "@ilha/store";
 import ilha, { html } from "ilha";
 
-export const cartStore = createStore({ items: [] as string[] }, (set, get) => ({
+const cartStore = createStore({ items: [] as string[] }, (set, get) => ({
   add(item: string) {
     set({ items: [...get().items, item] });
   },
@@ -176,23 +201,53 @@ export const cartStore = createStore({ items: [] as string[] }, (set, get) => ({
   },
 }));
 
-export const CartIsland = ilha
-  .state("items", cartStore.getState().items)
-  .effect(({ state }) => {
-    return cartStore.subscribe(
-      (s) => s.items,
-      (items) => state.items(items),
-    );
+const items = cartStore.select((s) => s.items);
+const itemCount = cartStore.select((s) => s.items.length);
+
+export const CartBadge = ilha.render(() => html`<span>${itemCount()}</span>`);
+
+export const CartList = ilha.render(
+  () => html`
+    <ul>
+      ${items().map((item) => html`<li>${item}</li>`)}
+    </ul>
+  `,
+);
+```
+
+Both islands stay in sync automatically. `CartBadge` only re-renders when `items.length` changes; `CartList` only re-renders when the array itself changes.
+
+### Inside `.derived()` and `.effect()`
+
+`select` accessors work in any tracking scope — the same dependency tracking that powers `.state()` reads applies:
+
+```ts
+const userStore = createStore({ id: 1, name: "Ada" });
+const userId = userStore.select((s) => s.id);
+
+const Profile = ilha
+  .derived("user", async ({ signal }) => {
+    const res = await fetch(`/api/users/${userId()}`, { signal });
+    return res.json();
   })
-  .render(
-    ({ state }) => html`
-      <ul>
-        ${state.items().map((item) => html`<li>${item}</li>`)}
-      </ul>
-    `,
-  );
+  .effect(() => {
+    document.title = `User: ${userStore.select((s) => s.name)()}`;
+    //                ^ inline is fine here — `.effect()` runs once per dep change,
+    //                  not on every render. For hot paths, hoist the `select`.
+  })
+  .render(({ derived }) => html`<p>${derived.user.value?.name ?? "…"}</p>`);
 ```
 
+When `userId()` changes, the derived re-fetches automatically.
+
+### When to use `select` vs `subscribe`
+
+| Use `select`                                          | Use `subscribe`                                        |
+| ----------------------------------------------------- | ------------------------------------------------------ |
+| Reading store state inside an island                  | Imperative side effects outside an island              |
+| Driving `.derived()` or `.effect()` dependencies      | Syncing to `localStorage`, WebSockets, analytics       |
+| Anywhere you'd reach for `context()` from `ilha` core | Anywhere you'd reach for `effect()` from alien-signals |
+
 ---
 
 ## Forms — `@ilha/store/form`
@@ -271,37 +326,38 @@ const formStore = createStore({ errors: {} as FormErrors }, (set) => ({
   },
 }));
 
+const errors = formStore.select((s) => s.errors);
+
 export default ilha
   .on("form@submit", ({ event }) => {
     event.preventDefault();
     formStore.getState().submit(event);
   })
-  .render(() => {
-    const errors = formStore.getState().errors;
-    return html`
+  .render(
+    () => html`
       <form>
         <label>
           Name
           <input name="name" />
-          ${errors.name ? html`<p role="alert">${errors.name.join(", ")}</p>` : ""}
+          ${errors().name ? html`<p role="alert">${errors().name.join(", ")}</p>` : ""}
         </label>
         <label>
           Email
           <input name="email" type="email" />
-          ${errors.email ? html`<p role="alert">${errors.email.join(", ")}</p>` : ""}
+          ${errors().email ? html`<p role="alert">${errors().email.join(", ")}</p>` : ""}
         </label>
         <label>
           Message
           <textarea name="message"></textarea>
-          ${errors.message ? html`<p role="alert">${errors.message.join(", ")}</p>` : ""}
+          ${errors().message ? html`<p role="alert">${errors().message.join(", ")}</p>` : ""}
         </label>
         <button type="submit">Send</button>
       </form>
-    `;
-  });
+    `,
+  );
 ```
 
-The store holds errors, the schema drives types, and `extractFormData` + `validateWithSchema` + `issuesToErrors` form a straight pipeline from DOM to error state.
+The store holds errors, the schema drives types, and `extractFormData` + `validateWithSchema` + `issuesToErrors` form a straight pipeline from DOM to error state. The `errors` accessor is reactive — when `submit` writes new errors, the island re-renders automatically.
 
 ---
 

package/dist/index.d.ts

@@ -20,6 +20,31 @@ interface StoreApi<T extends object> {
   subscribe<S>(selector: (state: T) => S, listener: SliceListener<T, S>): Unsub;
   bind(el: Element, render: (state: T) => RenderResult): Unsub;
   bind<S>(el: Element, selector: (state: T) => S, render: (slice: S) => RenderResult): Unsub;
+  /**
+   * Project a reactive slice of state into a signal-shaped accessor.
+   *
+   * The returned function reads the current value when called. When called
+   * inside an ilha tracking scope (`.render()`, `.derived()`, `.effect()`)
+   * or any other alien-signals reactive context, that scope subscribes to
+   * the slice and re-runs whenever the selector's output changes.
+   *
+   * Hoist the call out of render functions — each `.select()` allocates
+   * a fresh `computed`, so calling it inside a render that re-runs leaks
+   * one per render until the scope is collected. Define selectors at
+   * module scope or in `.onMount()`/closure setup.
+   *
+   * @example
+   * const cartStore = createStore({ items: [] as Item[], total: 0 });
+   * const itemCount = cartStore.select(s => s.items.length);
+   *
+   * const Badge = ilha.render(() => html`<span>${itemCount()}</span>`);
+   *
+   * @example
+   * // Stable identity for downstream comparisons:
+   * const items = cartStore.select(s => s.items);
+   * cartStore.setState({ total: 99 }); // items() returns the same array
+   */
+  select<S>(selector: (state: T) => S): () => S;
 }
 type ActionsCreator<TState extends object, TActions extends object> = (set: SetState<TState>, get: GetState<any>, getInitialState: () => TState) => TActions;
 declare function createStore<TState extends object>(initialState: TState): StoreApi<TState>;

package/dist/index.js

@@ -48,13 +48,17 @@ function createStore(initialState, actionsCreator) {
 			}
 		});
 	}
+	function select(selector) {
+		const sliceComputed = computed(() => selector(stateSignal()));
+		return () => sliceComputed();
+	}
 	function bind(el, renderOrSelector, maybeRender) {
 		if (maybeRender === void 0) return effect(() => {
 			el.innerHTML = unwrap(renderOrSelector(stateSignal()));
 		});
-		const sliceComputed = computed(() => renderOrSelector(stateSignal()));
+		const slice = select(renderOrSelector);
 		return effect(() => {
-			el.innerHTML = unwrap(maybeRender(sliceComputed()));
+			el.innerHTML = unwrap(maybeRender(slice()));
 		});
 	}
 	let resolvedInitialState;
@@ -63,7 +67,8 @@ function createStore(initialState, actionsCreator) {
 		getState,
 		getInitialState: () => resolvedInitialState,
 		subscribe,
-		bind
+		bind,
+		select
 	};
 	const resolvedActions = actionsCreator ? actionsCreator(setState, getState, () => resolvedInitialState) : {};
 	resolvedInitialState = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilha/store",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Typed store.",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",
@@ -29,9 +29,9 @@
   },
   "dependencies": {
     "alien-signals": "3.1.2",
-    "ilha": "0.4.0"
+    "ilha": "0.4.1"
   },
   "devDependencies": {
-    "zod": "^4.4.1"
+    "zod": "^4.4.3"
   }
 }