@zubra/runtime 5.8.0 → 5.9.1

package/types/effect.d.ts

@@ -1,15 +1,28 @@
+/**
+ * `[Symbol.dispose]()`, so `using` and `DisposableStack` accept it, when the project's `lib`
+ * has Explicit Resource Management (`esnext.disposable`, or `esnext`); nothing otherwise, so
+ * older `lib` settings still type-check.
+ */
+export type Disposal = SymbolConstructor extends { readonly dispose: infer K extends symbol }
+  ? { [P in K]: () => void }
+  : {};
+
 /** Something to run when an effect re-runs or is disposed. */
 export type Cleanup = () => void;
 
 /**
  * Run `fn` now and again whenever a signal it read changes (batched: several writes in one task
  * cause one re-run, in a microtask). `fn` may return a cleanup. Returns a function that disposes
- * the effect. Effects created inside another effect or scope belong to it.
+ * the effect, and is also disposable (`using stop = effect(…)`). Effects created inside another
+ * effect or scope belong to it.
  */
-export declare function effect(fn: () => void | Cleanup): () => void;
+export declare function effect(fn: () => void | Cleanup): (() => void) & Disposal;
 
-/** An ownership root: disposing, pausing or resuming it applies to every effect inside. */
-export interface Scope {
+/**
+ * An ownership root: disposing, pausing or resuming it applies to every effect inside. It's
+ * disposable too (`using s = scope(…)`); pausing isn't disposal, and a paused scope resumes.
+ */
+export interface Scope extends Disposal {
   run<T>(fn: () => T): T;
   dispose(): void;
   pause(): void;

package/types/index.d.ts

@@ -2,7 +2,8 @@
 import type { Signal } from './signal.js';
 
 export { Signal, isNative } from './signal.js';
-export { effect, scope, flush, tick, type Cleanup, type Scope } from './effect.js';
+export { effect, scope, flush, tick, type Cleanup, type Disposal, type Scope } from './effect.js';
+import type { Disposal } from './effect.js';
 
 /** A value, or a signal holding one: what templates and most hooks accept. */
 export type MaybeSignal<T> = T | Signal.State<T> | Signal.Computed<T>;
@@ -23,7 +24,7 @@ export declare function computed<T>(fn: () => T, options?: Signal.Options<T>): S
 export declare function watch<T>(source: (() => T) | MaybeSignal<T>, callback: (next: T, previous: T) => void): void;
 
 /** Async data as signals; see `resource()`. Awaitable: resolves to the current run's value. */
-export interface Resource<T> extends PromiseLike<T> {
+export interface Resource<T> extends PromiseLike<T>, Disposal {
   /** The latest run's value (or `initial`); kept while the next run is pending. */
   readonly value: T | undefined;
   readonly error: unknown;
@@ -31,6 +32,8 @@ export interface Resource<T> extends PromiseLike<T> {
   readonly loading: boolean;
   /** Run the fetcher again. */
   refresh(): void;
+  /** Stop: abort the run in flight and never run again. `using` does this through `Symbol.dispose`. */
+  dispose(): void;
 }
 /**
  * Run `fetcher` now and whenever a signal it read before its first `await` changes; a new run
@@ -55,7 +58,7 @@ export declare function host<E extends HTMLElement = HTMLElement>(): E;
  * declares every event it sees. Returns false if a listener called `preventDefault()` on a
  * cancelable (`before…`) event.
  */
-export declare function emit(name: string, detail?: unknown): boolean;
+export declare function emit<Detail = unknown>(name: string, detail?: Detail): boolean;
 
 /**
  * The signal itself, where a script passes a signal `const` along: `watch(signal(count), …)`.

package/types/track.d.ts

@@ -0,0 +1,19 @@
+// @zubra/runtime/track: reads after an `await` in a resource's fetcher.
+
+/** What a fetcher wrapped by `tracked()` is given for each run. */
+export interface TrackedRun {
+  /** Aborted when a newer run starts or the resource is disposed. */
+  signal: AbortSignal;
+  /**
+   * Read signals and follow them, after an `await` too: when what `read` returns changes, the
+   * resource runs the fetcher again. A replaced run still reads, without subscribing.
+   */
+  track<V>(read: () => V): V;
+}
+
+/**
+ * Wraps a resource's fetcher so it is also given `track()`:
+ * `resource(tracked(async ({ signal, track }) => …))`. The compiler writes it for an async
+ * fetcher in a `.zb` script.
+ */
+export declare function tracked<T>(fetcher: (run: TrackedRun) => T | PromiseLike<T>): (context: { signal: AbortSignal }) => T | PromiseLike<T>;