ui-router-effect 0.2.0 → 0.3.0

package/README.md

@@ -15,16 +15,17 @@ npm install ui-router-effect effect
 ## Features
 
 - **`routeRef(router)`**: a `SubscriptionRef<TypedRouteSnapshot>` of the current state, params and transition. There is one ref, and one `onSuccess` hook, per router, attached lazily on first use. Every value it holds is a settled route.
+- **`pendingRef(router)`** and **`errorRef(router)`**: `SubscriptionRef`s of the newest transition, kept out of `RouteSnapshot`. Two refs, and one `onStart` hook, per router, attached lazily on first use of either. `pendingRef` holds the transition still in flight, cleared when that transition settles, however it settles, unless a newer one has started. `errorRef` holds that transition's `RejectType.ERROR` rejection, cleared when the next transition starts.
 - **`RouteSnapshot`** and **`snapshotRoute(router, transition?)`**: the value the ref holds. Its `includes()` evaluates `StateService.includes` against the snapshot, not the live router.
 - **`RouteTypes`**: an empty interface an app or a registry fills in by module augmentation. Its `snapshot` member types the ref's value, so a snapshot whose `includes(name)` is a type predicate narrows `current` and `params`. Empty, the ref holds a `RouteSnapshot`. `snapshotRoute` stays untyped.
 
 ## Usage
 
 ```typescript
-import { Effect, Stream } from 'effect';
+import { Effect, Stream, SubscriptionRef } from 'effect';
 import { routeRef } from 'ui-router-effect';
 
-const names = routeRef(router).changes.pipe(
+const names = SubscriptionRef.changes(routeRef(router)).pipe(
   Stream.map((route) => route.current?.name),
   Stream.changes,
 );
@@ -32,6 +33,25 @@ const names = routeRef(router).changes.pipe(
 Effect.runFork(Stream.runForEach(names, (name) => Effect.log(name)));
 ```
 
+### Loading and error state
+
+```ts
+import { Effect, Stream, SubscriptionRef } from 'effect';
+import { errorRef, pendingRef } from 'ui-router-effect';
+
+const status = Stream.zipLatestWith(
+  SubscriptionRef.changes(pendingRef(router)),
+  SubscriptionRef.changes(errorRef(router)),
+  (pending, error) => (pending ? 'loading' : error ? 'error' : 'idle'),
+).pipe(Stream.changes);
+
+Effect.runFork(
+  Stream.runForEach(status, (value) =>
+    Effect.sync(() => (document.body.dataset.routeStatus = value)),
+  ),
+);
+```
+
 ## Dependencies
 
 `@uirouter/core` and `effect` are peer dependencies. `lit` and `lit-ui-router` are not, and the `bundleProbe` claim in `package.json` holds the entry free of them.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { errorRef, pendingRef } from "./transition-refs.js";
 export { routeRef } from "./route-ref.js";
 export { type RouteSnapshot, snapshotRoute } from "./shared/route-snapshot.js";
 export { type RouteTypes, type TypedRouteSnapshot } from "./route-types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","mappings":"AAAA,SAAS,gBAAgB;AAEzB,cAAc,eAAe,qBAAqB;AAElD,cAAc,iBAAiB,0BAA0B","names":[],"ignoreList":[],"sources":["../src/index.ts"]}
+{"version":3,"file":"index.d.ts","mappings":"AAAA,SAAS,UAAU,kBAAkB;AAErC,SAAS,gBAAgB;AAEzB,cAAc,eAAe,qBAAqB;AAElD,cAAc,iBAAiB,0BAA0B","names":[],"ignoreList":[],"sources":["../src/index.ts"]}

package/dist/index.js

@@ -1,3 +1,4 @@
+export { errorRef, pendingRef } from "./transition-refs.js";
 export { routeRef } from "./route-ref.js";
 export { snapshotRoute } from "./shared/route-snapshot.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","mappings":"AAAA,SAAS,gBAAgB;AAEzB,SAA6B,qBAAqB","names":[],"ignoreList":[],"sources":["../src/index.ts"]}
+{"version":3,"file":"index.js","mappings":"AAAA,SAAS,UAAU,kBAAkB;AAErC,SAAS,gBAAgB;AAEzB,SAA6B,qBAAqB","names":[],"ignoreList":[],"sources":["../src/index.ts"]}

package/dist/shared/transition-status.d.ts

@@ -0,0 +1,33 @@
+import { Rejection, Transition, UIRouter } from "@uirouter/core";
+/** The router's newest transition: in flight, or how it last failed. */
+export interface TransitionStatus {
+	/** The newest transition still in flight; `undefined` when none is. */
+	readonly pending: Transition | undefined;
+	/**
+	* The newest transition's `RejectType.ERROR` rejection; `undefined` while
+	* one is in flight, after a success, and after any other rejection.
+	*/
+	readonly error: Rejection | undefined;
+}
+/**
+* Mirrors the status of the router's newest transition into `set`, one
+* whole {@link TransitionStatus} per change: `{ pending: transition }` when
+* it starts, then `{ pending: undefined, error }` once it settles, however it
+* settles. `error` is the transition's `error()` only for a
+* `RejectType.ERROR` rejection; superseded, redirected, aborted and ignored
+* transitions leave it `undefined`. Invalid transitions are rejected before
+* `onStart`, so they never reach the tracker.
+*
+* `onStart` records each transition as the newest. Its promise settles the
+* status only while it is still the newest, so a superseded transition never
+* clears or fails its successor. `onFinish` would miss failures: it never
+* fires for a transition that errors or is aborted.
+*
+* A transition already running when this attaches is picked up too, so a
+* mirror created mid-navigation reads it as pending.
+*
+* @returns the `onStart` hook's deregistration function. A transition
+* already pending still settles when it does.
+*/
+export declare function trackTransitionStatus(router: UIRouter, set: (status: TransitionStatus) => void): () => void;
+//# sourceMappingURL=transition-status.d.ts.map

package/dist/shared/transition-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-status.d.ts","mappings":"AAAA,SAAS,WAAuB,YAAY,gBAAgB;;AAG5D,iBAAiB,iBAAiB;;UAEvB,SAAS;;;;;UAKT,OAAO;AAClB;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,iBAAS,sBACd,QAAQ,UACR,MAAM,QAAQ","names":[],"ignoreList":[],"sources":["../../../shared/transition-status/src/transition-status.ts"],"sourcesContent":["import { Rejection, RejectType, Transition, UIRouter } from '@uirouter/core';\n\n/** The router's newest transition: in flight, or how it last failed. */\nexport interface TransitionStatus {\n  /** The newest transition still in flight; `undefined` when none is. */\n  readonly pending: Transition | undefined;\n  /**\n   * The newest transition's `RejectType.ERROR` rejection; `undefined` while\n   * one is in flight, after a success, and after any other rejection.\n   */\n  readonly error: Rejection | undefined;\n}\n\n/**\n * Mirrors the status of the router's newest transition into `set`, one\n * whole {@link TransitionStatus} per change: `{ pending: transition }` when\n * it starts, then `{ pending: undefined, error }` once it settles, however it\n * settles. `error` is the transition's `error()` only for a\n * `RejectType.ERROR` rejection; superseded, redirected, aborted and ignored\n * transitions leave it `undefined`. Invalid transitions are rejected before\n * `onStart`, so they never reach the tracker.\n *\n * `onStart` records each transition as the newest. Its promise settles the\n * status only while it is still the newest, so a superseded transition never\n * clears or fails its successor. `onFinish` would miss failures: it never\n * fires for a transition that errors or is aborted.\n *\n * A transition already running when this attaches is picked up too, so a\n * mirror created mid-navigation reads it as pending.\n *\n * @returns the `onStart` hook's deregistration function. A transition\n * already pending still settles when it does.\n */\nexport function trackTransitionStatus(\n  router: UIRouter,\n  set: (status: TransitionStatus) => void,\n): () => void {\n  let newest: Transition | undefined;\n\n  const start = (transition: Transition): void => {\n    newest = transition;\n    set({ pending: transition, error: undefined });\n\n    const settle = (): void => {\n      if (newest !== transition) return;\n      newest = undefined;\n      // SAFETY: `error()` is undefined after a success; core types it as `Rejection`.\n      const error = transition.error() as Rejection | undefined;\n      set({\n        pending: undefined,\n        error: error?.type === RejectType.ERROR ? error : undefined,\n      });\n    };\n\n    // Handled here, the rejection still reaches the transition's own callers and onError hooks.\n    void transition.promise.then(settle, settle);\n  };\n\n  const running = router.globals.transition;\n\n  // SAFETY: `success` stays undefined until the transition settles; core types it as `boolean`.\n  if (running && (running.success as boolean | undefined) === undefined) {\n    start(running);\n  }\n\n  // SAFETY: `onStart` returns its deregistration function, typed only as `Function`.\n  return router.transitionService.onStart({}, start) as () => void;\n}\n"]}

package/dist/shared/transition-status.js

@@ -0,0 +1,27 @@
+import { RejectType } from "@uirouter/core";
+export function trackTransitionStatus(router, set) {
+	let newest;
+	const start = (transition) => {
+		newest = transition;
+		set({
+			pending: transition,
+			error: undefined
+		});
+		const settle = () => {
+			if (newest !== transition) return;
+			newest = undefined;
+			const error = transition.error();
+			set({
+				pending: undefined,
+				error: error?.type === RejectType.ERROR ? error : undefined
+			});
+		};
+		void transition.promise.then(settle, settle);
+	};
+	const running = router.globals.transition;
+	if (running && running.success === undefined) {
+		start(running);
+	}
+	return router.transitionService.onStart({}, start);
+}
+//# sourceMappingURL=transition-status.js.map

package/dist/shared/transition-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-status.js","mappings":"AAAA,SAAoB,kBAAwC;AAiC5D,OAAO,SAAS,sBACd,QACA,KACY;CACZ,IAAI;CAEJ,MAAM,SAAS,eAAiC;EAC9C,SAAS;EACT,IAAI;GAAE,SAAS;GAAY,OAAO;EAAU,CAAC;EAE7C,MAAM,eAAqB;GACzB,IAAI,WAAW,YAAY;GAC3B,SAAS;GAET,MAAM,QAAQ,WAAW,MAAM;GAC/B,IAAI;IACF,SAAS;IACT,OAAO,OAAO,SAAS,WAAW,QAAQ,QAAQ;GACpD,CAAC;EACH;EAGA,KAAK,WAAW,QAAQ,KAAK,QAAQ,MAAM;CAC7C;CAEA,MAAM,UAAU,OAAO,QAAQ;CAG/B,IAAI,WAAY,QAAQ,YAAoC,WAAW;EACrE,MAAM,OAAO;CACf;CAGA,OAAO,OAAO,kBAAkB,QAAQ,CAAC,GAAG,KAAK;AACnD","names":[],"ignoreList":[],"sources":["../../../shared/transition-status/src/transition-status.ts"],"sourcesContent":["import { Rejection, RejectType, Transition, UIRouter } from '@uirouter/core';\n\n/** The router's newest transition: in flight, or how it last failed. */\nexport interface TransitionStatus {\n  /** The newest transition still in flight; `undefined` when none is. */\n  readonly pending: Transition | undefined;\n  /**\n   * The newest transition's `RejectType.ERROR` rejection; `undefined` while\n   * one is in flight, after a success, and after any other rejection.\n   */\n  readonly error: Rejection | undefined;\n}\n\n/**\n * Mirrors the status of the router's newest transition into `set`, one\n * whole {@link TransitionStatus} per change: `{ pending: transition }` when\n * it starts, then `{ pending: undefined, error }` once it settles, however it\n * settles. `error` is the transition's `error()` only for a\n * `RejectType.ERROR` rejection; superseded, redirected, aborted and ignored\n * transitions leave it `undefined`. Invalid transitions are rejected before\n * `onStart`, so they never reach the tracker.\n *\n * `onStart` records each transition as the newest. Its promise settles the\n * status only while it is still the newest, so a superseded transition never\n * clears or fails its successor. `onFinish` would miss failures: it never\n * fires for a transition that errors or is aborted.\n *\n * A transition already running when this attaches is picked up too, so a\n * mirror created mid-navigation reads it as pending.\n *\n * @returns the `onStart` hook's deregistration function. A transition\n * already pending still settles when it does.\n */\nexport function trackTransitionStatus(\n  router: UIRouter,\n  set: (status: TransitionStatus) => void,\n): () => void {\n  let newest: Transition | undefined;\n\n  const start = (transition: Transition): void => {\n    newest = transition;\n    set({ pending: transition, error: undefined });\n\n    const settle = (): void => {\n      if (newest !== transition) return;\n      newest = undefined;\n      // SAFETY: `error()` is undefined after a success; core types it as `Rejection`.\n      const error = transition.error() as Rejection | undefined;\n      set({\n        pending: undefined,\n        error: error?.type === RejectType.ERROR ? error : undefined,\n      });\n    };\n\n    // Handled here, the rejection still reaches the transition's own callers and onError hooks.\n    void transition.promise.then(settle, settle);\n  };\n\n  const running = router.globals.transition;\n\n  // SAFETY: `success` stays undefined until the transition settles; core types it as `boolean`.\n  if (running && (running.success as boolean | undefined) === undefined) {\n    start(running);\n  }\n\n  // SAFETY: `onStart` returns its deregistration function, typed only as `Function`.\n  return router.transitionService.onStart({}, start) as () => void;\n}\n"]}

package/dist/transition-refs.d.ts

@@ -0,0 +1,28 @@
+import { SubscriptionRef } from "effect";
+import { Rejection, Transition, UIRouter } from "@uirouter/core";
+/**
+* The pending-transition ref for a router — one per router instance,
+* attached lazily.
+*
+* It holds the newest transition still in flight, and `undefined` when none
+* is. The first caller of this or {@link errorRef} creates both refs and
+* registers the single `onStart` hook that feeds them; the transition's
+* promise clears it when that transition settles, whether it succeeds,
+* errors or is aborted, unless a newer one has started. A transition already
+* running on first use counts as pending. Kept out of `RouteSnapshot`, whose
+* every value is a settled route.
+*/
+export declare function pendingRef(router: UIRouter): SubscriptionRef.SubscriptionRef<Transition | undefined>;
+/**
+* The failed-transition ref for a router — one per router instance,
+* attached lazily, sharing {@link pendingRef}'s `onStart` hook.
+*
+* It holds the newest transition's failure as core's `Rejection`, and
+* `undefined` otherwise. Only a `RejectType.ERROR` rejection, such as a
+* resolve that throws, sets it; superseded, redirected, aborted and ignored
+* transitions leave it `undefined`, as does a success. The next transition
+* clears it as it starts, and a superseded transition that fails late never
+* sets it. Kept out of `RouteSnapshot`.
+*/
+export declare function errorRef(router: UIRouter): SubscriptionRef.SubscriptionRef<Rejection | undefined>;
+//# sourceMappingURL=transition-refs.d.ts.map

package/dist/transition-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-refs.d.ts","mappings":"AAAA,SAAiB,uBAAuB;AACxC,SAAS,WAAW,YAAY,gBAAgB;;;;;;;;;;;;;AA6DhD,OAAO,iBAAS,WACd,QAAQ,WACP,gBAAgB,gBAAgB;;;;;;;;;;;;AAenC,OAAO,iBAAS,SACd,QAAQ,WACP,gBAAgB,gBAAgB","names":[],"ignoreList":[],"sources":["../src/transition-refs.ts"]}

package/dist/transition-refs.js

@@ -0,0 +1,35 @@
+import { Effect, SubscriptionRef } from "effect";
+import { trackTransitionStatus } from "./shared/transition-status.js";
+const transitionRefs = new WeakMap();
+function refsFor(router) {
+	const existing = transitionRefs.get(router);
+	if (existing) return existing;
+	const refs = {
+		pending: Effect.runSync(SubscriptionRef.make(undefined)),
+		error: Effect.runSync(SubscriptionRef.make(undefined))
+	};
+	let error;
+	const setError = (next) => {
+		if (next === error) return;
+		error = next;
+		Effect.runSync(SubscriptionRef.set(refs.error, next));
+	};
+	transitionRefs.set(router, refs);
+	trackTransitionStatus(router, (status) => {
+		if (status.pending) {
+			Effect.runSync(SubscriptionRef.set(refs.pending, status.pending));
+			setError(status.error);
+		} else {
+			setError(status.error);
+			Effect.runSync(SubscriptionRef.set(refs.pending, undefined));
+		}
+	});
+	return refs;
+}
+export function pendingRef(router) {
+	return refsFor(router).pending;
+}
+export function errorRef(router) {
+	return refsFor(router).error;
+}
+//# sourceMappingURL=transition-refs.js.map

package/dist/transition-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-refs.js","mappings":"AAAA,SAAS,QAAQ,uBAAuB;AAGxC,SAAS,6BAA6B;AAOtC,MAAM,iBAAiB,IAAI,QAAkC;AAG7D,SAAS,QAAQ,QAAkC;CACjD,MAAM,WAAW,eAAe,IAAI,MAAM;CAE1C,IAAI,UAAU,OAAO;CAErB,MAAM,OAAuB;EAC3B,SAAS,OAAO,QACd,gBAAgB,KAA6B,SAAS,CACxD;EACA,OAAO,OAAO,QACZ,gBAAgB,KAA4B,SAAS,CACvD;CACF;CAEA,IAAI;CAEJ,MAAM,YAAY,SAAsC;EACtD,IAAI,SAAS,OAAO;EACpB,QAAQ;EACR,OAAO,QAAQ,gBAAgB,IAAI,KAAK,OAAO,IAAI,CAAC;CACtD;CAEA,eAAe,IAAI,QAAQ,IAAI;CAE/B,sBAAsB,SAAS,WAAW;EACxC,IAAI,OAAO,SAAS;GAClB,OAAO,QAAQ,gBAAgB,IAAI,KAAK,SAAS,OAAO,OAAO,CAAC;GAChE,SAAS,OAAO,KAAK;EACvB,OAAO;GACL,SAAS,OAAO,KAAK;GACrB,OAAO,QAAQ,gBAAgB,IAAI,KAAK,SAAS,SAAS,CAAC;EAC7D;CACF,CAAC;CAED,OAAO;AACT;AAcA,OAAO,SAAS,WACd,QACyD;CACzD,OAAO,QAAQ,MAAM,CAAC,CAAC;AACzB;AAaA,OAAO,SAAS,SACd,QACwD;CACxD,OAAO,QAAQ,MAAM,CAAC,CAAC;AACzB","names":[],"ignoreList":[],"sources":["../src/transition-refs.ts"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-router-effect",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Effect bindings for UI-Router: a framework-agnostic SubscriptionRef of the router's current state",
   "homepage": "https://lit-ui-router.dev/packages/ui-router-effect",
   "bugs": {

package/src/index.ts

@@ -1,3 +1,5 @@
+export { errorRef, pendingRef } from './transition-refs.js';
+
 export { routeRef } from './route-ref.js';
 
 export { type RouteSnapshot, snapshotRoute } from '@repo/route-snapshot';

package/src/transition-refs.ts

@@ -0,0 +1,84 @@
+import { Effect, SubscriptionRef } from 'effect';
+import { Rejection, Transition, UIRouter } from '@uirouter/core';
+
+import { trackTransitionStatus } from '@repo/transition-status';
+
+interface TransitionRefs {
+  readonly pending: SubscriptionRef.SubscriptionRef<Transition | undefined>;
+  readonly error: SubscriptionRef.SubscriptionRef<Rejection | undefined>;
+}
+
+const transitionRefs = new WeakMap<UIRouter, TransitionRefs>();
+
+/** Both refs for a router, fed by one `onStart` hook registered on first use. */
+function refsFor(router: UIRouter): TransitionRefs {
+  const existing = transitionRefs.get(router);
+
+  if (existing) return existing;
+
+  const refs: TransitionRefs = {
+    pending: Effect.runSync(
+      SubscriptionRef.make<Transition | undefined>(undefined),
+    ),
+    error: Effect.runSync(
+      SubscriptionRef.make<Rejection | undefined>(undefined),
+    ),
+  };
+
+  let error: Rejection | undefined;
+
+  const setError = (next: Rejection | undefined): void => {
+    if (next === error) return;
+    error = next;
+    Effect.runSync(SubscriptionRef.set(refs.error, next));
+  };
+
+  transitionRefs.set(router, refs);
+  // `pending` is set before `error` clears, and `error` before `pending` clears, so no read between the two looks idle.
+  trackTransitionStatus(router, (status) => {
+    if (status.pending) {
+      Effect.runSync(SubscriptionRef.set(refs.pending, status.pending));
+      setError(status.error);
+    } else {
+      setError(status.error);
+      Effect.runSync(SubscriptionRef.set(refs.pending, undefined));
+    }
+  });
+
+  return refs;
+}
+
+/**
+ * The pending-transition ref for a router — one per router instance,
+ * attached lazily.
+ *
+ * It holds the newest transition still in flight, and `undefined` when none
+ * is. The first caller of this or {@link errorRef} creates both refs and
+ * registers the single `onStart` hook that feeds them; the transition's
+ * promise clears it when that transition settles, whether it succeeds,
+ * errors or is aborted, unless a newer one has started. A transition already
+ * running on first use counts as pending. Kept out of `RouteSnapshot`, whose
+ * every value is a settled route.
+ */
+export function pendingRef(
+  router: UIRouter,
+): SubscriptionRef.SubscriptionRef<Transition | undefined> {
+  return refsFor(router).pending;
+}
+
+/**
+ * The failed-transition ref for a router — one per router instance,
+ * attached lazily, sharing {@link pendingRef}'s `onStart` hook.
+ *
+ * It holds the newest transition's failure as core's `Rejection`, and
+ * `undefined` otherwise. Only a `RejectType.ERROR` rejection, such as a
+ * resolve that throws, sets it; superseded, redirected, aborted and ignored
+ * transitions leave it `undefined`, as does a success. The next transition
+ * clears it as it starts, and a superseded transition that fails late never
+ * sets it. Kept out of `RouteSnapshot`.
+ */
+export function errorRef(
+  router: UIRouter,
+): SubscriptionRef.SubscriptionRef<Rejection | undefined> {
+  return refsFor(router).error;
+}