@real-router/rx 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/rx",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "commonjs",
   "description": "Reactive Observable API for Real-Router — state$, events$, operators, and TC39 Observable support",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -43,7 +43,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1"
+    "@real-router/core": "^0.45.2"
   },
   "scripts": {
     "test": "vitest",
@@ -52,7 +52,7 @@
     "build": "tsdown --config-loader unrun",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/RxObservable.ts

@@ -0,0 +1,281 @@
+import type {
+  Observer,
+  Subscription,
+  ObservableOptions,
+  SubscribeFn,
+  Operator,
+} from "./types";
+
+declare global {
+  interface SymbolConstructor {
+    readonly observable: symbol;
+  }
+}
+
+export class RxObservable<T> {
+  #subscribeFn: SubscribeFn<T>;
+
+  constructor(subscribeFn: SubscribeFn<T>) {
+    this.#subscribeFn = subscribeFn;
+  }
+
+  subscribe(
+    observerOrNext: Observer<T> | ((value: T) => void),
+    options?: ObservableOptions,
+  ): Subscription {
+    const observer: Observer<T> =
+      typeof observerOrNext === "function"
+        ? { next: observerOrNext }
+        : observerOrNext;
+
+    const { signal } = options ?? {};
+
+    if (signal?.aborted) {
+      return {
+        unsubscribe: () => {},
+        closed: true,
+      };
+    }
+
+    let closed = false;
+    // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- matches SubscribeFn return type
+    let teardown: void | (() => void);
+
+    const safeNext = (value: T) => {
+      if (closed) {
+        return;
+      }
+
+      try {
+        observer.next?.(value);
+      } catch (error) {
+        safeError(error);
+      }
+    };
+
+    const safeError = (err: unknown) => {
+      if (closed) {
+        return;
+      }
+
+      try {
+        if (observer.error) {
+          observer.error(err);
+        } else {
+          console.error("Unhandled error in RxObservable:", err);
+        }
+      } catch {
+        // Errors in error handler are caught silently
+      }
+    };
+
+    const safeComplete = () => {
+      if (closed) {
+        return;
+      }
+
+      closed = true;
+
+      try {
+        observer.complete?.();
+      } catch {
+        // Errors in complete handler are caught silently
+      }
+    };
+
+    const subscription: Subscription = {
+      unsubscribe: () => {
+        if (closed) {
+          return;
+        }
+
+        closed = true;
+
+        if (abortHandler) {
+          signal?.removeEventListener("abort", abortHandler);
+        }
+
+        if (teardown) {
+          try {
+            teardown();
+          } catch {
+            // Teardown errors are caught silently
+          }
+        }
+      },
+      get closed() {
+        return closed;
+      },
+    };
+
+    let abortHandler: (() => void) | undefined;
+
+    if (signal) {
+      abortHandler = () => {
+        subscription.unsubscribe();
+      };
+      signal.addEventListener("abort", abortHandler);
+    }
+
+    try {
+      teardown = this.#subscribeFn({
+        next: safeNext,
+        error: safeError,
+        complete: safeComplete,
+      });
+    } catch (error) {
+      safeError(error);
+    }
+
+    return subscription;
+  }
+
+  pipe(): this;
+  pipe<A>(op1: Operator<T, A>): RxObservable<A>;
+  pipe<A, B>(op1: Operator<T, A>, op2: Operator<A, B>): RxObservable<B>;
+  pipe<A, B, C>(
+    op1: Operator<T, A>,
+    op2: Operator<A, B>,
+    op3: Operator<B, C>,
+  ): RxObservable<C>;
+  pipe<A, B, C, D>(
+    op1: Operator<T, A>,
+    op2: Operator<A, B>,
+    op3: Operator<B, C>,
+    op4: Operator<C, D>,
+  ): RxObservable<D>;
+  pipe<A, B, C, D, E>(
+    op1: Operator<T, A>,
+    op2: Operator<A, B>,
+    op3: Operator<B, C>,
+    op4: Operator<C, D>,
+    op5: Operator<D, E>,
+  ): RxObservable<E>;
+  pipe<A, B, C, D, E, F>(
+    op1: Operator<T, A>,
+    op2: Operator<A, B>,
+    op3: Operator<B, C>,
+    op4: Operator<C, D>,
+    op5: Operator<D, E>,
+    op6: Operator<E, F>,
+  ): RxObservable<F>;
+  pipe<A, B, C, D, E, F, G>(
+    op1: Operator<T, A>,
+    op2: Operator<A, B>,
+    op3: Operator<B, C>,
+    op4: Operator<C, D>,
+    op5: Operator<D, E>,
+    op6: Operator<E, F>,
+    op7: Operator<F, G>,
+  ): RxObservable<G>;
+  pipe<A, B, C, D, E, F, G, H>(
+    op1: Operator<T, A>,
+    op2: Operator<A, B>,
+    op3: Operator<B, C>,
+    op4: Operator<C, D>,
+    op5: Operator<D, E>,
+    op6: Operator<E, F>,
+    op7: Operator<F, G>,
+    op8: Operator<G, H>,
+  ): RxObservable<H>;
+  pipe<A, B, C, D, E, F, G, H, I>(
+    op1: Operator<T, A>,
+    op2: Operator<A, B>,
+    op3: Operator<B, C>,
+    op4: Operator<C, D>,
+    op5: Operator<D, E>,
+    op6: Operator<E, F>,
+    op7: Operator<F, G>,
+    op8: Operator<G, H>,
+    op9: Operator<H, I>,
+  ): RxObservable<I>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  pipe(...operators: Operator<any, any>[]): any {
+    if (operators.length === 0) {
+      return this;
+    }
+
+    // eslint-disable-next-line unicorn/no-this-assignment, @typescript-eslint/no-this-alias -- pipe pattern
+    let result: RxObservable<unknown> = this;
+
+    for (const operator of operators) {
+      result = operator(result);
+    }
+
+    return result;
+  }
+
+  [Symbol.observable](): this {
+    return this;
+  }
+
+  ["@@observable"](): this {
+    return this;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterableIterator<T> {
+    let resolve: (() => void) | null = null;
+    let latestValue: T | undefined;
+    let hasValue = false;
+    let completed = false;
+    let error: unknown = null;
+
+    const subscription = this.subscribe({
+      next: (value) => {
+        latestValue = value;
+        hasValue = true;
+        if (resolve) {
+          const resolveCallback = resolve;
+
+          resolve = null;
+          resolveCallback();
+        }
+      },
+      /* v8 ignore start -- v8 coverage can't track branches inside suspended async generators */
+      error: (err) => {
+        error = err;
+        completed = true;
+        if (resolve) {
+          const resolveCallback = resolve;
+
+          resolve = null;
+          resolveCallback();
+        }
+      },
+      complete: () => {
+        completed = true;
+        if (resolve) {
+          const resolveCallback = resolve;
+
+          resolve = null;
+          resolveCallback();
+        }
+      },
+      /* v8 ignore stop */
+    });
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- v8 ignore affects analysis
+      while (!completed) {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- v8 ignore affects analysis
+        if (hasValue) {
+          const value = latestValue as T;
+
+          hasValue = false;
+          yield value;
+        } else {
+          await new Promise<void>((_resolve) => {
+            resolve = _resolve;
+          });
+
+          if (error !== null) {
+            // eslint-disable-next-line @typescript-eslint/only-throw-error
+            throw error;
+          }
+        }
+      }
+    } finally {
+      subscription.unsubscribe();
+    }
+  }
+}

package/src/events$.ts

@@ -0,0 +1,133 @@
+import { events } from "@real-router/core";
+import { getPluginApi } from "@real-router/core/api";
+
+import { RxObservable } from "./RxObservable";
+
+import type {
+  Router,
+  State,
+  NavigationOptions,
+  RouterError,
+} from "@real-router/core";
+
+export type RouterEvent =
+  | { type: "ROUTER_START" }
+  | { type: "ROUTER_STOP" }
+  | { type: "TRANSITION_START"; toState: State; fromState: State | undefined }
+  | {
+      type: "TRANSITION_LEAVE_APPROVE";
+      toState: State;
+      fromState: State | undefined;
+    }
+  | {
+      type: "TRANSITION_SUCCESS";
+      toState: State;
+      fromState: State | undefined;
+      options: NavigationOptions;
+    }
+  | {
+      type: "TRANSITION_ERROR";
+      toState: State | undefined;
+      fromState: State | undefined;
+      error: RouterError;
+    }
+  | { type: "TRANSITION_CANCEL"; toState: State; fromState: State | undefined };
+
+export function events$(router: Router): RxObservable<RouterEvent> {
+  return new RxObservable<RouterEvent>((observer) => {
+    const api = getPluginApi(router);
+    const unsubscribes: (() => void)[] = [];
+
+    /* eslint-disable unicorn/prefer-single-call -- individual pushes for partial registration safety */
+    try {
+      unsubscribes.push(
+        api.addEventListener(events.ROUTER_START, () => {
+          observer.next?.({ type: "ROUTER_START" });
+        }),
+      );
+      unsubscribes.push(
+        api.addEventListener(events.ROUTER_STOP, () => {
+          observer.next?.({ type: "ROUTER_STOP" });
+        }),
+      );
+      unsubscribes.push(
+        api.addEventListener(
+          events.TRANSITION_START,
+          (toState: State, fromState: State | undefined) => {
+            observer.next?.({ type: "TRANSITION_START", toState, fromState });
+          },
+        ),
+      );
+      unsubscribes.push(
+        api.addEventListener(
+          events.TRANSITION_LEAVE_APPROVE,
+          (toState: State, fromState: State | undefined) => {
+            observer.next?.({
+              type: "TRANSITION_LEAVE_APPROVE",
+              toState,
+              fromState,
+            });
+          },
+        ),
+      );
+      unsubscribes.push(
+        api.addEventListener(
+          events.TRANSITION_SUCCESS,
+          (
+            toState: State,
+            fromState: State | undefined,
+            options: NavigationOptions,
+          ) => {
+            observer.next?.({
+              type: "TRANSITION_SUCCESS",
+              toState,
+              fromState,
+              options,
+            });
+          },
+        ),
+      );
+      unsubscribes.push(
+        api.addEventListener(
+          events.TRANSITION_ERROR,
+          (
+            toState: State | undefined,
+            fromState: State | undefined,
+            error: RouterError,
+          ) => {
+            observer.next?.({
+              type: "TRANSITION_ERROR",
+              toState,
+              fromState,
+              error,
+            });
+          },
+        ),
+      );
+      unsubscribes.push(
+        api.addEventListener(
+          events.TRANSITION_CANCEL,
+          (toState: State, fromState: State | undefined) => {
+            observer.next?.({ type: "TRANSITION_CANCEL", toState, fromState });
+          },
+        ),
+      );
+      /* eslint-enable unicorn/prefer-single-call */
+      /* v8 ignore start -- defensive: partial listener registration failure */
+    } catch (error) {
+      // Clean up any listeners that were successfully registered
+      for (const unsub of unsubscribes) {
+        unsub();
+      }
+
+      throw error;
+    }
+    /* v8 ignore stop */
+
+    return () => {
+      for (const unsub of unsubscribes) {
+        unsub();
+      }
+    };
+  });
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export { RxObservable } from "./RxObservable";
+
+export {
+  map,
+  filter,
+  debounceTime,
+  distinctUntilChanged,
+  takeUntil,
+} from "./operators";
+
+export { state$ } from "./state$";
+
+export type { SubscribeState } from "./state$";
+
+export { events$ } from "./events$";
+
+export type { RouterEvent } from "./events$";
+
+export { observable } from "./observable";
+
+export type {
+  Observer,
+  Subscription,
+  ObservableOptions,
+  SubscribeFn,
+  Operator,
+  UnaryFunction,
+} from "./types";

package/src/observable.ts

@@ -0,0 +1,28 @@
+import { state$, type SubscribeState } from "./state$";
+
+import type { RxObservable } from "./RxObservable";
+import type { Router } from "@real-router/core";
+
+/**
+ * Creates a TC39-compliant Observable from a router instance.
+ *
+ * This is a semantic wrapper over `state$()` that provides TC39 Observable interop.
+ * Use this when you need RxJS compatibility via `from(observable(router))`.
+ *
+ * @param router - Router instance to observe
+ * @returns RxObservable that emits state changes
+ *
+ * @example
+ * ```typescript
+ * import { from } from 'rxjs';
+ * import { observable } from '@real-router/rx';
+ *
+ * const router$ = from(observable(router));
+ * router$.subscribe(({ route, previousRoute }) => {
+ *   console.log('Navigation:', previousRoute?.name, '→', route.name);
+ * });
+ * ```
+ */
+export function observable(router: Router): RxObservable<SubscribeState> {
+  return state$(router);
+}

package/src/operators/createOperator.ts

@@ -0,0 +1,37 @@
+import { RxObservable } from "../RxObservable";
+
+import type { Observer } from "../types";
+
+/**
+ * Creates a stateless operator. Wires error/complete/teardown automatically.
+ * The `next` callback receives each value and the downstream observer.
+ */
+export function createOperator<T, R>(
+  next: (value: T, observer: Observer<R>) => void,
+): (source: RxObservable<T>) => RxObservable<R> {
+  return (source: RxObservable<T>) =>
+    new RxObservable<R>((observer) => {
+      const subscription = source.subscribe({
+        next: (value) => {
+          next(value, observer);
+        },
+        error: (error) => observer.error?.(error),
+        complete: () => observer.complete?.(),
+      });
+
+      return () => {
+        subscription.unsubscribe();
+      };
+    });
+}
+
+/**
+ * Creates a stateful operator. The subscribeFn sets up its own subscriptions
+ * and returns a teardown function.
+ */
+export function createStatefulOperator<T, R>(
+  subscribeFn: (source: RxObservable<T>, observer: Observer<R>) => () => void,
+): (source: RxObservable<T>) => RxObservable<R> {
+  return (source: RxObservable<T>) =>
+    new RxObservable<R>((observer) => subscribeFn(source, observer));
+}

package/src/operators/debounceTime.ts

@@ -0,0 +1,70 @@
+import { RxObservable } from "../RxObservable";
+
+import type { Operator } from "../types";
+
+export function debounceTime<T>(duration: number): Operator<T, T> {
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new RangeError(
+      `debounceTime: duration must be a non-negative finite number, got ${duration}`,
+    );
+  }
+
+  return (source: RxObservable<T>) =>
+    new RxObservable<T>((observer) => {
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      let latestValue: T;
+      let hasValue = false;
+
+      const subscription = source.subscribe({
+        next: (value) => {
+          latestValue = value;
+          hasValue = true;
+
+          if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+          }
+
+          timeoutId = setTimeout(() => {
+            /* v8 ignore start -- defensive: timer fired after flush */
+            if (hasValue) {
+              observer.next?.(latestValue);
+              hasValue = false;
+            }
+            /* v8 ignore stop */
+
+            timeoutId = undefined;
+          }, duration);
+        },
+        error: (error) => {
+          if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+            timeoutId = undefined;
+          }
+
+          observer.error?.(error);
+        },
+        complete: () => {
+          if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+            timeoutId = undefined;
+          }
+
+          if (hasValue) {
+            observer.next?.(latestValue);
+            hasValue = false;
+          }
+
+          observer.complete?.();
+        },
+      });
+
+      return () => {
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId);
+          timeoutId = undefined;
+        }
+
+        subscription.unsubscribe();
+      };
+    });
+}

package/src/operators/distinctUntilChanged.ts

@@ -0,0 +1,40 @@
+import { createStatefulOperator } from "./createOperator";
+
+import type { Operator } from "../types";
+
+export function distinctUntilChanged<T>(
+  comparator?: (a: T, b: T) => boolean,
+): Operator<T, T> {
+  return createStatefulOperator<T, T>((source, observer) => {
+    let hasLast = false;
+    let last: T;
+    const compare = comparator ?? ((prev: T, curr: T) => prev === curr);
+
+    const subscription = source.subscribe({
+      next: (value) => {
+        if (!hasLast) {
+          hasLast = true;
+          last = value;
+          observer.next?.(value);
+
+          return;
+        }
+
+        try {
+          if (!compare(last, value)) {
+            last = value;
+            observer.next?.(value);
+          }
+        } catch (error) {
+          observer.error?.(error);
+        }
+      },
+      error: (error) => observer.error?.(error),
+      complete: () => observer.complete?.(),
+    });
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  });
+}

package/src/operators/filter.ts

@@ -0,0 +1,21 @@
+import { createOperator } from "./createOperator";
+
+import type { Operator } from "../types";
+
+export function filter<T, S extends T>(
+  predicate: (value: T) => value is S,
+): Operator<T, S>;
+
+export function filter<T>(predicate: (value: T) => boolean): Operator<T, T>;
+
+export function filter<T>(predicate: (value: T) => boolean): Operator<T, T> {
+  return createOperator<T, T>((value, observer) => {
+    try {
+      if (predicate(value)) {
+        observer.next?.(value);
+      }
+    } catch (error) {
+      observer.error?.(error);
+    }
+  });
+}

package/src/operators/index.ts

@@ -0,0 +1,9 @@
+export { map } from "./map";
+
+export { filter } from "./filter";
+
+export { debounceTime } from "./debounceTime";
+
+export { distinctUntilChanged } from "./distinctUntilChanged";
+
+export { takeUntil } from "./takeUntil";

package/src/operators/map.ts

@@ -0,0 +1,15 @@
+import { createOperator } from "./createOperator";
+
+import type { Operator } from "../types";
+
+export function map<T, R>(project: (value: T) => R): Operator<T, R> {
+  return createOperator<T, R>((value, observer) => {
+    try {
+      const result = project(value);
+
+      observer.next?.(result);
+    } catch (error) {
+      observer.error?.(error);
+    }
+  });
+}

package/src/operators/takeUntil.ts

@@ -0,0 +1,99 @@
+import { RxObservable } from "../RxObservable";
+
+import type { Operator } from "../types";
+
+export function takeUntil<T>(notifier: RxObservable<unknown>): Operator<T, T> {
+  return (source: RxObservable<T>) =>
+    new RxObservable<T>((observer) => {
+      // eslint-disable-next-line prefer-const -- assigned after usage in complete()
+      let sourceSubscription: ReturnType<typeof source.subscribe> | undefined;
+      // eslint-disable-next-line prefer-const -- assigned after usage in complete()
+      let notifierSubscription:
+        | ReturnType<typeof notifier.subscribe>
+        | undefined;
+      let completed = false;
+
+      const complete = () => {
+        /* v8 ignore start -- defensive: race condition guard */
+        if (completed) {
+          return;
+        }
+        /* v8 ignore stop */
+
+        completed = true;
+
+        // sourceSubscription may be undefined if notifier emits synchronously
+        if (sourceSubscription) {
+          sourceSubscription.unsubscribe();
+        }
+        // notifierSubscription may be undefined if we're inside notifier.subscribe() call
+        if (notifierSubscription) {
+          notifierSubscription.unsubscribe();
+        }
+
+        observer.complete?.();
+      };
+
+      notifierSubscription = notifier.subscribe({
+        next: () => {
+          complete();
+        },
+        error: (error) => {
+          /* v8 ignore start -- defensive: notifier error after completion */
+          if (completed) {
+            return;
+          }
+          /* v8 ignore stop */
+
+          completed = true;
+
+          // sourceSubscription may be undefined if notifier errors synchronously
+          if (sourceSubscription) {
+            sourceSubscription.unsubscribe();
+          }
+
+          observer.error?.(error);
+        },
+      });
+
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive
+      if (completed) {
+        return;
+      }
+
+      sourceSubscription = source.subscribe({
+        next: (value) => {
+          /* v8 ignore start -- defensive: emission after completion */
+
+          if (!completed) {
+            observer.next?.(value);
+          }
+          /* v8 ignore stop */
+        },
+        error: (error) => {
+          /* v8 ignore start -- defensive: race condition guard */
+          if (completed) {
+            return;
+          }
+          /* v8 ignore stop */
+
+          completed = true;
+
+          // notifierSubscription is always defined here (notifier subscribes before source)
+          notifierSubscription.unsubscribe();
+
+          observer.error?.(error);
+        },
+        complete: () => {
+          complete();
+        },
+      });
+
+      return () => {
+        // Both guaranteed defined: notifier subscribes first (line 37),
+        // early return on line 60 if sync complete/error, source subscribes after (line 64)
+        sourceSubscription.unsubscribe();
+        notifierSubscription.unsubscribe();
+      };
+    });
+}

package/src/state$.ts

@@ -0,0 +1,37 @@
+import { events } from "@real-router/core";
+import { getPluginApi } from "@real-router/core/api";
+
+import { RxObservable } from "./RxObservable";
+
+import type { Router, State, SubscribeState } from "@real-router/core";
+
+export type { SubscribeState } from "@real-router/core";
+
+export function state$(
+  router: Router,
+  options?: { replay?: boolean },
+): RxObservable<SubscribeState> {
+  const { replay = true } = options ?? {};
+
+  return new RxObservable<SubscribeState>((observer) => {
+    const api = getPluginApi(router);
+    const unsubscribe = api.addEventListener(
+      events.TRANSITION_SUCCESS,
+      (toState: State, fromState: State | undefined) => {
+        observer.next?.({ route: toState, previousRoute: fromState });
+      },
+    );
+
+    if (replay) {
+      const currentState = router.getState();
+
+      if (currentState) {
+        queueMicrotask(() => {
+          observer.next?.({ route: currentState, previousRoute: undefined });
+        });
+      }
+    }
+
+    return unsubscribe;
+  });
+}

package/src/types.ts

@@ -0,0 +1,27 @@
+// Types for @real-router/rx
+
+// Import for type reference
+import type { RxObservable } from "./RxObservable";
+
+export interface Observer<T> {
+  next?: (value: T) => void;
+  error?: (err: unknown) => void;
+  complete?: () => void;
+}
+
+export interface Subscription {
+  unsubscribe: () => void;
+  readonly closed: boolean;
+}
+
+export interface ObservableOptions {
+  signal?: AbortSignal;
+  replay?: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- void required: subscribe fn may have no return statement
+export type SubscribeFn<T> = (observer: Observer<T>) => void | (() => void);
+
+export type Operator<T, R> = (source: RxObservable<T>) => RxObservable<R>;
+
+export type UnaryFunction<T, R> = (source: T) => R;