ilha 0.6.1 → 0.7.0

package/README.md

@@ -121,11 +121,11 @@ ilha
   .render(({ derived }) => {
     if (derived.user.loading) return `<p>Loading…</p>`;
     if (derived.user.error) return `<p>Error: ${derived.user.error.message}</p>`;
-    return `<p>${derived.user.value.name}</p>`;
+    return `<p>${derived.user().name}</p>`;
   });
 ```
 
-Each derived value exposes `{ loading, value, error }`.
+Read with `derived.name()` like state. Each accessor also exposes `loading`, `value`, and `error` for async work. Write `derived.name(value)` for optimistic UI.
 
 ---
 
@@ -239,12 +239,15 @@ The handler receives an `EffectContext`:
 ```ts
 {
   state: IslandState;
+  derived: IslandDerived;
   input: TInput;
   host: Element;
   signal: AbortSignal; // aborts when the effect re-runs OR the island unmounts
 }
 ```
 
+Reading `derived.name()` subscribes the effect. Writing `derived.name(value)` does not — use writes for optimistic UI without pinning the effect to every derived update.
+
 **Cancelling async work with `ctx.signal`** — unlike `.on()`, race-cancellation is the **default** behaviour for effects (no opt-in modifier needed) because dependency changes invariably make the previous run stale. Pass `signal` to async work to bail out of stale invocations without needing a manual cleanup function:
 
 ```ts

package/dist/index.d.ts

@@ -105,6 +105,13 @@ interface DerivedValue<T> {
   value: T | undefined;
   error: Error | undefined;
 }
+type DerivedAccessor<T> = {
+  readonly loading: boolean;
+  readonly value: T | undefined;
+  readonly error: Error | undefined;
+  (): T | undefined;
+  (value: T): void;
+};
 type DerivedFnContext<TInput, TStateMap extends Record<string, unknown>> = {
   state: IslandState<TStateMap>;
   input: TInput;
@@ -115,7 +122,7 @@ interface DerivedEntry<TInput, TStateMap extends Record<string, unknown>> {
   key: string;
   fn: DerivedFn<TInput, TStateMap, unknown>;
 }
-type IslandDerived<TDerivedMap extends Record<string, unknown>> = { readonly [K in keyof TDerivedMap]: DerivedValue<TDerivedMap[K]> };
+type IslandDerived<TDerivedMap extends Record<string, unknown>> = { readonly [K in keyof TDerivedMap]: DerivedAccessor<TDerivedMap[K]> };
 type ExternalSignal<T = unknown> = SignalAccessor<T>;
 type SignalAccessor<T> = MarkedSignalAccessor<T>;
 type MergeState<TStateMap extends Record<string, unknown>, K extends string, V> = Omit<TStateMap, K> & Record<K, V>;
@@ -147,8 +154,9 @@ type RenderContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMa
   derived: IslandDerived<TDerivedMap>;
   input: TInput;
 };
-type EffectContext<TInput, TStateMap extends Record<string, unknown>> = {
+type EffectContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> = {
   state: IslandState<TStateMap>;
+  derived: IslandDerived<TDerivedMap>;
   input: TInput;
   host: Element;
   /**
@@ -211,8 +219,8 @@ interface OnEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap
   abortable: boolean;
   handler: (ctx: HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>;
 }
-interface EffectEntry<TInput, TStateMap extends Record<string, unknown>> {
-  fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void;
+interface EffectEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
+  fn: (ctx: EffectContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void;
 }
 /** Where the error originated. `"on"` covers sync throws and async rejections
  *  from `.on()` handlers; `"effect"` covers sync throws from `.effect()` runs
@@ -248,7 +256,7 @@ interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDeri
   states: StateEntry<TInput>[];
   deriveds: DerivedEntry<TInput, TStateMap>[];
   ons: OnEntry<TInput, TStateMap, TDerivedMap>[];
-  effects: EffectEntry<TInput, TStateMap>[];
+  effects: EffectEntry<TInput, TStateMap, TDerivedMap>[];
   onMounts: OnMountEntry<TInput, TStateMap, TDerivedMap>[];
   onErrors: OnErrorEntry<TInput, TStateMap, TDerivedMap>[];
   transition: TransitionOptions | null;
@@ -262,7 +270,7 @@ declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap exte
   state<V = undefined, K extends string = string>(key: K, init?: StateInit<TInput, V> | undefined): IlhaBuilder<TInput, MergeState<TStateMap, K, V>, TDerivedMap>;
   derived<K extends string, V>(key: K, fn: DerivedFn<TInput, TStateMap, V>): IlhaBuilder<TInput, TStateMap, TDerivedMap & Record<K, V>>;
   on<S extends string>(selectorOrCombined: S, handler: (ctx: S extends `${string}@${infer E}:${string}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : S extends `${string}@${infer E}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
-  effect(fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  effect(fn: (ctx: EffectContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   onMount(fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   onError(fn: (ctx: ErrorContext<TInput, TStateMap, TDerivedMap>) => void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   transition(opts: TransitionOptions): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
@@ -297,4 +305,4 @@ declare const mount: typeof mountAll;
 declare const from: typeof ilhaFrom;
 declare const context: typeof ilhaContext;
 //#endregion
-export { DerivedValue, ErrorContext, ErrorSource, ExternalSignal, Fragment, HandlerContext, HandlerContextFor, HydratableOptions, ISLAND_MOUNT_INTERNAL, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, batch, context, css, ilha as default, from, html, ilhaSignal, ilhaSignal as signal, jsx, jsxDEV, jsxs, mount, raw, untrack };
+export { DerivedAccessor, DerivedValue, EffectContext, ErrorContext, ErrorSource, ExternalSignal, Fragment, HandlerContext, HandlerContextFor, HydratableOptions, ISLAND_MOUNT_INTERNAL, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, batch, context, css, ilha as default, from, html, ilhaSignal, ilhaSignal as signal, jsx, jsxDEV, jsxs, mount, raw, untrack };

package/dist/index.js

@@ -676,6 +676,38 @@ function batch(fn) {
 		endBatch();
 	}
 }
+function createDerivedAccessor(read, write) {
+	const accessor = markSignalAccessor((...args) => {
+		if (args.length > 0) {
+			if (write) write(args[0]);
+			else if (__DEV__) warn("derived values are read-only");
+			return;
+		}
+		return read().value;
+	});
+	return new Proxy(accessor, { get(target, prop, receiver) {
+		if (prop === "loading" || prop === "value" || prop === "error") return read()[prop];
+		return Reflect.get(target, prop, receiver);
+	} });
+}
+function defaultDerivedAccessor() {
+	return createDerivedAccessor(() => ({
+		loading: false,
+		value: void 0,
+		error: void 0
+	}));
+}
+function buildDerivedAccessors(envelopes) {
+	const accessors = /* @__PURE__ */ new Map();
+	for (const [key, envelope] of Object.entries(envelopes)) accessors.set(key, createDerivedAccessor(() => envelope, (value) => {
+		envelope.loading = false;
+		envelope.value = value;
+		envelope.error = void 0;
+	}));
+	return new Proxy({}, { get(_, key) {
+		return accessors.get(key) ?? defaultDerivedAccessor();
+	} });
+}
 function createDerivedProxy(entries, state, input, derivedSnapshot) {
 	const envelopes = /* @__PURE__ */ new Map();
 	for (const entry of entries) {
@@ -719,14 +751,21 @@ function createDerivedProxy(entries, state, input, derivedSnapshot) {
 		const env = signal(initialEnvelope);
 		envelopes.set(entry.key, env);
 	}
+	const accessors = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const env = envelopes.get(entry.key);
+		accessors.set(entry.key, createDerivedAccessor(() => env(), (value) => {
+			const prevSub = setActiveSub(void 0);
+			env({
+				loading: false,
+				value,
+				error: void 0
+			});
+			setActiveSub(prevSub);
+		}));
+	}
 	const proxy = new Proxy({}, { get(_, key) {
-		const env = envelopes.get(key);
-		if (!env) return {
-			loading: false,
-			value: void 0,
-			error: void 0
-		};
-		return env();
+		return accessors.get(key) ?? defaultDerivedAccessor();
 	} });
 	const setup = () => {
 		const stops = [];
@@ -1183,17 +1222,18 @@ var IlhaBuilder = class IlhaBuilder {
 				}
 			});
 			if (!results.some((r) => r.result instanceof Promise) || sync) {
-				const derived = {};
-				for (const r of results) if (r.result instanceof Promise) derived[r.key] = {
+				const envelopes = {};
+				for (const r of results) if (r.result instanceof Promise) envelopes[r.key] = {
 					loading: true,
 					value: void 0,
 					error: void 0
 				};
-				else derived[r.key] = {
+				else envelopes[r.key] = {
 					loading: false,
 					value: r.result,
 					error: void 0
 				};
+				const derived = buildDerivedAccessors(envelopes);
 				const prevSub = setActiveSub(void 0);
 				try {
 					const { html } = renderWithCtx(() => fn({
@@ -1227,8 +1267,9 @@ var IlhaBuilder = class IlhaBuilder {
 					};
 				}
 			})).then(async (resolved) => {
-				const derived = {};
-				for (const r of resolved) derived[r.key] = r.envelope;
+				const envelopes = {};
+				for (const r of resolved) envelopes[r.key] = r.envelope;
+				const derived = buildDerivedAccessors(envelopes);
 				const prevSub = setActiveSub(void 0);
 				try {
 					const { html } = await renderWithCtx(() => fn({
@@ -1537,6 +1578,7 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 					try {
 						userCleanup = entry.fn({
 							state,
+							derived,
 							input,
 							host,
 							signal: runSignal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilha",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "A tiny, framework-free island architecture library",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",