ui-router-effect 0.1.2 → 0.2.0

package/README.md

@@ -14,8 +14,9 @@ npm install ui-router-effect effect
 
 ## Features
 
-- **`routeRef(router)`**: a `SubscriptionRef<RouteSnapshot>` 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.
+- **`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.
 - **`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
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { routeRef } from "./route-ref.js";
 export { type RouteSnapshot, snapshotRoute } from "./shared/route-snapshot.js";
+export { type RouteTypes, type TypedRouteSnapshot } from "./route-types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/route-ref.d.ts

@@ -1,6 +1,6 @@
 import { SubscriptionRef } from "effect";
 import { UIRouter } from "@uirouter/core";
-import { RouteSnapshot } from "./shared/route-snapshot.js";
+import type { TypedRouteSnapshot } from "./route-types.js";
 /**
 * The route ref for a router — one per router instance, attached lazily.
 *
@@ -8,6 +8,7 @@ import { RouteSnapshot } from "./shared/route-snapshot.js";
 * ref and registers the single `onSuccess` hook that feeds it, and both live
 * as long as the router does. `onSuccess` is the only hook a later transition
 * cannot supersede, so every value the ref ever holds is a settled route.
+* Its snapshot is typed by `RouteTypes` when a registry fills it in.
 */
-export declare function routeRef(router: UIRouter): SubscriptionRef.SubscriptionRef<RouteSnapshot>;
+export declare function routeRef(router: UIRouter): SubscriptionRef.SubscriptionRef<TypedRouteSnapshot>;
 //# sourceMappingURL=route-ref.d.ts.map

package/dist/route-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-ref.d.ts","mappings":"AAAA,SAAiB,uBAAuB;AACxC,SAAS,gBAAgB;AAEzB,SAAS,qBAAoC;;;;;;;;;AAe7C,OAAO,iBAAS,SACd,QAAQ,WACP,gBAAgB,gBAAgB","names":[],"ignoreList":[],"sources":["../src/route-ref.ts"]}
+{"version":3,"file":"route-ref.d.ts","mappings":"AAAA,SAAiB,uBAAuB;AACxC,SAAS,gBAAgB;AAIzB,cAAc,0BAA0B;;;;;;;;;;AAgBxC,OAAO,iBAAS,SACd,QAAQ,WACP,gBAAgB,gBAAgB","names":[],"ignoreList":[],"sources":["../src/route-ref.ts"]}

package/dist/route-ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-ref.js","mappings":"AAAA,SAAS,QAAQ,uBAAuB;AAGxC,SAAwB,qBAAqB;AAE7C,MAAM,YAAY,IAAI,QAGpB;AAUF,OAAO,SAAS,SACd,QACgD;CAChD,MAAM,WAAW,UAAU,IAAI,MAAM;CAErC,IAAI,UAAU,OAAO;CACrB,MAAM,MAAM,OAAO,QAAQ,gBAAgB,KAAK,cAAc,MAAM,CAAC,CAAC;CACtE,UAAU,IAAI,QAAQ,GAAG;CACzB,OAAO,kBAAkB,UAAU,CAAC,IAAI,eAAe;EACrD,OAAO,QAAQ,gBAAgB,IAAI,KAAK,cAAc,QAAQ,UAAU,CAAC,CAAC;CAC5E,CAAC;CAED,OAAO;AACT","names":[],"ignoreList":[],"sources":["../src/route-ref.ts"]}
+{"version":3,"file":"route-ref.js","mappings":"AAAA,SAAS,QAAQ,uBAAuB;AAGxC,SAAS,qBAAqB;AAI9B,MAAM,YAAY,IAAI,QAGpB;AAWF,OAAO,SAAS,SACd,QACqD;CACrD,MAAM,WAAW,UAAU,IAAI,MAAM;CAErC,IAAI,UAAU,OAAO;CACrB,MAAM,MAAM,OAAO,QAAQ,gBAAgB,KAAK,cAAc,MAAM,CAAC,CAAC;CACtE,UAAU,IAAI,QAAQ,GAAG;CACzB,OAAO,kBAAkB,UAAU,CAAC,IAAI,eAAe;EACrD,OAAO,QAAQ,gBAAgB,IAAI,KAAK,cAAc,QAAQ,UAAU,CAAC,CAAC;CAC5E,CAAC;CAED,OAAO;AACT","names":[],"ignoreList":[],"sources":["../src/route-ref.ts"]}

package/dist/route-types.d.ts

@@ -0,0 +1,34 @@
+import type { RouteSnapshot } from "./shared/route-snapshot.js";
+/**
+* Typed route snapshots, filled in by module augmentation. Empty, the
+* snapshot is {@link RouteSnapshot}, as it always has been; nothing here
+* emits JavaScript.
+*
+* An app or a registry such as `ui-router-registry` fills it in. Its member:
+*
+* - `snapshot`: the type `routeRef`'s ref holds, a typed view of
+*   {@link RouteSnapshot} whose `includes(name)` narrows `current` and
+*   `params`.
+*
+* ```ts
+* declare module 'ui-router-effect' {
+*   interface RouteTypes {
+*     snapshot: AppRouteSnapshot;
+*   }
+* }
+* ```
+*
+* @category types
+*/
+export interface RouteTypes {}
+/**
+* The route snapshot as {@link RouteTypes} types it: its `snapshot` member,
+* or {@link RouteSnapshot} until it is filled in.
+*
+* @category types
+*/
+export type TypedRouteSnapshot = RouteTypes extends {
+	/** The filled-in snapshot type. */
+	snapshot: infer S;
+} ? S : RouteSnapshot;
+//# sourceMappingURL=route-types.d.ts.map

package/dist/route-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-types.d.ts","mappings":"AAAA,cAAc,qBAAqB;;;;;;;;;;;;;;;;;;;;;;AAwBnC,iBAAiB,WAAW,CAAC;;;;;;;AAQ7B,YAAY,qBAAqB,mBAAmB;;CAElD,gBAAgB;AAClB,IACI,IACA","names":[],"ignoreList":[],"sources":["../src/route-types.ts"]}

package/dist/route-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=route-types.js.map

package/dist/route-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-types.js","mappings":"","names":[],"ignoreList":[],"sources":["../src/route-types.ts"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-router-effect",
-  "version": "0.1.2",
+  "version": "0.2.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 { routeRef } from './route-ref.js';
 
 export { type RouteSnapshot, snapshotRoute } from '@repo/route-snapshot';
+
+export { type RouteTypes, type TypedRouteSnapshot } from './route-types.js';

package/src/route-ref.ts

@@ -1,11 +1,13 @@
 import { Effect, SubscriptionRef } from 'effect';
 import { UIRouter } from '@uirouter/core';
 
-import { RouteSnapshot, snapshotRoute } from '@repo/route-snapshot';
+import { snapshotRoute } from '@repo/route-snapshot';
+
+import type { TypedRouteSnapshot } from './route-types.js';
 
 const routeRefs = new WeakMap<
   UIRouter,
-  SubscriptionRef.SubscriptionRef<RouteSnapshot>
+  SubscriptionRef.SubscriptionRef<TypedRouteSnapshot>
 >();
 
 /**
@@ -15,10 +17,11 @@ const routeRefs = new WeakMap<
  * ref and registers the single `onSuccess` hook that feeds it, and both live
  * as long as the router does. `onSuccess` is the only hook a later transition
  * cannot supersede, so every value the ref ever holds is a settled route.
+ * Its snapshot is typed by `RouteTypes` when a registry fills it in.
  */
 export function routeRef(
   router: UIRouter,
-): SubscriptionRef.SubscriptionRef<RouteSnapshot> {
+): SubscriptionRef.SubscriptionRef<TypedRouteSnapshot> {
   const existing = routeRefs.get(router);
 
   if (existing) return existing;

package/src/route-types.ts

@@ -0,0 +1,38 @@
+import type { RouteSnapshot } from '@repo/route-snapshot';
+
+/**
+ * Typed route snapshots, filled in by module augmentation. Empty, the
+ * snapshot is {@link RouteSnapshot}, as it always has been; nothing here
+ * emits JavaScript.
+ *
+ * An app or a registry such as `ui-router-registry` fills it in. Its member:
+ *
+ * - `snapshot`: the type `routeRef`'s ref holds, a typed view of
+ *   {@link RouteSnapshot} whose `includes(name)` narrows `current` and
+ *   `params`.
+ *
+ * ```ts
+ * declare module 'ui-router-effect' {
+ *   interface RouteTypes {
+ *     snapshot: AppRouteSnapshot;
+ *   }
+ * }
+ * ```
+ *
+ * @category types
+ */
+// oxlint-disable-next-line typescript/no-empty-interface, typescript/no-empty-object-type -- filled in by module augmentation
+export interface RouteTypes {}
+
+/**
+ * The route snapshot as {@link RouteTypes} types it: its `snapshot` member,
+ * or {@link RouteSnapshot} until it is filled in.
+ *
+ * @category types
+ */
+export type TypedRouteSnapshot = RouteTypes extends {
+  /** The filled-in snapshot type. */
+  snapshot: infer S;
+}
+  ? S
+  : RouteSnapshot;