iten-devtools 0.4.1 → 0.5.0

package/README.md

@@ -1,5 +1,74 @@
 # iten-devtools
 
-Reserved package for upcoming developer tools for `iten`.
+Adapter-neutral devtools helpers for `iten`.
 
-Use `iten-core` or `jotai-iten` today.
+This package does not render a UI. It subscribes to any `ItenCore`-like router and keeps a bounded event log that custom panels, tests, browser extensions, or embedded app debug views can render.
+
+## Install
+
+```bash
+npm install iten-devtools
+```
+
+## Quick Start
+
+```ts
+import { createItenCore, createRoute, defineRoutes, route } from 'iten-core'
+import { createItenDevtools } from 'iten-devtools'
+
+const routes = defineRoutes({
+  home: route(),
+  detail: route<{ id: string }>(),
+})
+
+const toRoute = createRoute(routes)
+
+const router = createItenCore({
+  initial: toRoute({ name: 'home' }),
+})
+
+const devtools = createItenDevtools({ router })
+
+await router.navigate({ target: toRoute({ name: 'detail', params: { id: '42' } }) })
+
+devtools.getSnapshot().events
+```
+
+## Snapshot Shape
+
+```ts
+type DevtoolsSnapshot = {
+  state: RouterState
+  events: DevtoolsEvent[]
+}
+```
+
+Each event includes:
+
+- `type`: `init`, `route`, `pending`, `error`, `idle`, or `history`
+- `timestamp`
+- `route`
+- `pendingRoute`
+- `error`
+- `canGoBack`
+- `historyLength`
+
+## API
+
+```ts
+const devtools = createItenDevtools({
+  router,
+  maxEvents: 100,
+  now: Date.now,
+})
+
+const stop = devtools.subscribe({
+  listener: (snapshot) => {
+    console.log(snapshot.events)
+  },
+})
+
+devtools.clear()
+stop()
+devtools.dispose()
+```

package/dist/index.cjs

@@ -0,0 +1,89 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+const DEFAULT_MAX_EVENTS = 100;
+function sameRoute({ left, right }) {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+function classifyEvent({ previous, next }) {
+	if (!previous) return "init";
+	if (next.error && next.error !== previous.error) return "error";
+	if (!sameRoute({
+		left: previous.route,
+		right: next.route
+	})) return "route";
+	if (!sameRoute({
+		left: previous.pendingRoute,
+		right: next.pendingRoute
+	})) return "pending";
+	if (previous.isNavigating !== next.isNavigating) return next.isNavigating ? "pending" : "idle";
+	if (previous.history.length !== next.history.length) return "history";
+	return "idle";
+}
+function createItenDevtools({ router, maxEvents = DEFAULT_MAX_EVENTS, now = Date.now }) {
+	const listeners = /* @__PURE__ */ new Set();
+	const events = [];
+	let currentState = router.getState();
+	let previousState = null;
+	let nextId = 1;
+	let disposed = false;
+	function emit({ state }) {
+		if (disposed) return;
+		currentState = state;
+		const event = {
+			id: nextId,
+			type: classifyEvent({
+				previous: previousState,
+				next: state
+			}),
+			timestamp: now(),
+			route: state.route,
+			pendingRoute: state.pendingRoute,
+			error: state.error?.error ?? null,
+			canGoBack: state.canGoBack,
+			historyLength: state.history.length
+		};
+		nextId += 1;
+		previousState = state;
+		events.push(event);
+		if (events.length > maxEvents) events.splice(0, events.length - maxEvents);
+		notify();
+	}
+	function getSnapshot() {
+		return {
+			state: currentState,
+			events: [...events]
+		};
+	}
+	function notify() {
+		const snapshot = getSnapshot();
+		for (const listener of listeners) listener(snapshot);
+	}
+	const stopRouter = router.subscribe({ listener: (state) => {
+		emit({ state });
+	} });
+	emit({ state: currentState });
+	function subscribe({ listener }) {
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	}
+	function clear() {
+		events.splice(0, events.length);
+		notify();
+	}
+	function dispose() {
+		disposed = true;
+		stopRouter();
+		listeners.clear();
+		events.splice(0, events.length);
+	}
+	return {
+		getSnapshot,
+		subscribe,
+		clear,
+		dispose
+	};
+}
+//#endregion
+exports.createItenDevtools = createItenDevtools;

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+import { RouteMapDef, RouteUnion, RouterState } from "iten-core";
+
+//#region src/index.d.ts
+type DevtoolsRouter<M extends RouteMapDef> = {
+  getState: () => RouterState<M>;
+  subscribe: (input: {
+    listener: (state: RouterState<M>) => void;
+  }) => () => void;
+};
+type DevtoolsEventType = "init" | "route" | "pending" | "error" | "idle" | "history";
+type DevtoolsEvent<M extends RouteMapDef> = {
+  id: number;
+  type: DevtoolsEventType;
+  timestamp: number;
+  route: RouteUnion<M> | null;
+  pendingRoute: RouteUnion<M> | null;
+  error: unknown;
+  canGoBack: boolean;
+  historyLength: number;
+};
+type DevtoolsSnapshot<M extends RouteMapDef> = {
+  state: RouterState<M>;
+  events: DevtoolsEvent<M>[];
+};
+type CreateDevtoolsInput<M extends RouteMapDef> = {
+  router: DevtoolsRouter<M>;
+  maxEvents?: number | undefined;
+  now?: (() => number) | undefined;
+};
+type ItenDevtools<M extends RouteMapDef> = {
+  getSnapshot: () => DevtoolsSnapshot<M>;
+  subscribe: (input: {
+    listener: (snapshot: DevtoolsSnapshot<M>) => void;
+  }) => () => void;
+  clear: () => void;
+  dispose: () => void;
+};
+declare function createItenDevtools<M extends RouteMapDef>({
+  router,
+  maxEvents,
+  now
+}: CreateDevtoolsInput<M>): ItenDevtools<M>;
+//#endregion
+export { CreateDevtoolsInput, DevtoolsEvent, DevtoolsEventType, DevtoolsRouter, DevtoolsSnapshot, ItenDevtools, createItenDevtools };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { RouteMapDef, RouteUnion, RouterState } from "iten-core";
+
+//#region src/index.d.ts
+type DevtoolsRouter<M extends RouteMapDef> = {
+  getState: () => RouterState<M>;
+  subscribe: (input: {
+    listener: (state: RouterState<M>) => void;
+  }) => () => void;
+};
+type DevtoolsEventType = "init" | "route" | "pending" | "error" | "idle" | "history";
+type DevtoolsEvent<M extends RouteMapDef> = {
+  id: number;
+  type: DevtoolsEventType;
+  timestamp: number;
+  route: RouteUnion<M> | null;
+  pendingRoute: RouteUnion<M> | null;
+  error: unknown;
+  canGoBack: boolean;
+  historyLength: number;
+};
+type DevtoolsSnapshot<M extends RouteMapDef> = {
+  state: RouterState<M>;
+  events: DevtoolsEvent<M>[];
+};
+type CreateDevtoolsInput<M extends RouteMapDef> = {
+  router: DevtoolsRouter<M>;
+  maxEvents?: number | undefined;
+  now?: (() => number) | undefined;
+};
+type ItenDevtools<M extends RouteMapDef> = {
+  getSnapshot: () => DevtoolsSnapshot<M>;
+  subscribe: (input: {
+    listener: (snapshot: DevtoolsSnapshot<M>) => void;
+  }) => () => void;
+  clear: () => void;
+  dispose: () => void;
+};
+declare function createItenDevtools<M extends RouteMapDef>({
+  router,
+  maxEvents,
+  now
+}: CreateDevtoolsInput<M>): ItenDevtools<M>;
+//#endregion
+export { CreateDevtoolsInput, DevtoolsEvent, DevtoolsEventType, DevtoolsRouter, DevtoolsSnapshot, ItenDevtools, createItenDevtools };

package/dist/index.mjs

@@ -0,0 +1,88 @@
+//#region src/index.ts
+const DEFAULT_MAX_EVENTS = 100;
+function sameRoute({ left, right }) {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+function classifyEvent({ previous, next }) {
+	if (!previous) return "init";
+	if (next.error && next.error !== previous.error) return "error";
+	if (!sameRoute({
+		left: previous.route,
+		right: next.route
+	})) return "route";
+	if (!sameRoute({
+		left: previous.pendingRoute,
+		right: next.pendingRoute
+	})) return "pending";
+	if (previous.isNavigating !== next.isNavigating) return next.isNavigating ? "pending" : "idle";
+	if (previous.history.length !== next.history.length) return "history";
+	return "idle";
+}
+function createItenDevtools({ router, maxEvents = DEFAULT_MAX_EVENTS, now = Date.now }) {
+	const listeners = /* @__PURE__ */ new Set();
+	const events = [];
+	let currentState = router.getState();
+	let previousState = null;
+	let nextId = 1;
+	let disposed = false;
+	function emit({ state }) {
+		if (disposed) return;
+		currentState = state;
+		const event = {
+			id: nextId,
+			type: classifyEvent({
+				previous: previousState,
+				next: state
+			}),
+			timestamp: now(),
+			route: state.route,
+			pendingRoute: state.pendingRoute,
+			error: state.error?.error ?? null,
+			canGoBack: state.canGoBack,
+			historyLength: state.history.length
+		};
+		nextId += 1;
+		previousState = state;
+		events.push(event);
+		if (events.length > maxEvents) events.splice(0, events.length - maxEvents);
+		notify();
+	}
+	function getSnapshot() {
+		return {
+			state: currentState,
+			events: [...events]
+		};
+	}
+	function notify() {
+		const snapshot = getSnapshot();
+		for (const listener of listeners) listener(snapshot);
+	}
+	const stopRouter = router.subscribe({ listener: (state) => {
+		emit({ state });
+	} });
+	emit({ state: currentState });
+	function subscribe({ listener }) {
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	}
+	function clear() {
+		events.splice(0, events.length);
+		notify();
+	}
+	function dispose() {
+		disposed = true;
+		stopRouter();
+		listeners.clear();
+		events.splice(0, events.length);
+	}
+	return {
+		getSnapshot,
+		subscribe,
+		clear,
+		dispose
+	};
+}
+//#endregion
+export { createItenDevtools };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "iten-devtools",
-  "version": "0.4.1",
-  "description": "DevTools for iten — ultralight in-memory router for embedded JS apps. Coming soon.",
+  "version": "0.5.0",
+  "description": "Devtools helpers for iten — inspect ultralight in-memory router state",
   "keywords": [
     "devtools",
     "router",
@@ -19,13 +19,43 @@
     "url": "https://github.com/andrew-bierman/iten/issues"
   },
   "homepage": "https://github.com/andrew-bierman/iten#readme",
-  "main": "index.js",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "files": [
-    "index.js",
-    "README.md"
+    "dist",
+    "src"
   ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "typecheck:types": "bun run build && tsc -p tsconfig.type-tests.json",
+    "test": "bun test ./test"
+  },
+  "dependencies": {
+    "iten-core": "^0.5.0"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "tsdown": "0.21.9",
+    "typescript": "^5.7.0"
   }
 }

package/src/index.ts

@@ -0,0 +1,152 @@
+import type { RouteMapDef, RouterState, RouteUnion } from 'iten-core'
+
+export type DevtoolsRouter<M extends RouteMapDef> = {
+  getState: () => RouterState<M>
+  subscribe: (input: { listener: (state: RouterState<M>) => void }) => () => void
+}
+
+export type DevtoolsEventType = 'init' | 'route' | 'pending' | 'error' | 'idle' | 'history'
+
+export type DevtoolsEvent<M extends RouteMapDef> = {
+  id: number
+  type: DevtoolsEventType
+  timestamp: number
+  route: RouteUnion<M> | null
+  pendingRoute: RouteUnion<M> | null
+  error: unknown
+  canGoBack: boolean
+  historyLength: number
+}
+
+export type DevtoolsSnapshot<M extends RouteMapDef> = {
+  state: RouterState<M>
+  events: DevtoolsEvent<M>[]
+}
+
+export type CreateDevtoolsInput<M extends RouteMapDef> = {
+  router: DevtoolsRouter<M>
+  maxEvents?: number | undefined
+  now?: (() => number) | undefined
+}
+
+export type ItenDevtools<M extends RouteMapDef> = {
+  getSnapshot: () => DevtoolsSnapshot<M>
+  subscribe: (input: { listener: (snapshot: DevtoolsSnapshot<M>) => void }) => () => void
+  clear: () => void
+  dispose: () => void
+}
+
+const DEFAULT_MAX_EVENTS = 100
+
+function sameRoute<M extends RouteMapDef>({
+  left,
+  right,
+}: {
+  left: RouteUnion<M> | null
+  right: RouteUnion<M> | null
+}): boolean {
+  return JSON.stringify(left) === JSON.stringify(right)
+}
+
+function classifyEvent<M extends RouteMapDef>({
+  previous,
+  next,
+}: {
+  previous: RouterState<M> | null
+  next: RouterState<M>
+}): DevtoolsEventType {
+  if (!previous) return 'init'
+  if (next.error && next.error !== previous.error) return 'error'
+  if (!sameRoute({ left: previous.route, right: next.route })) return 'route'
+  if (!sameRoute({ left: previous.pendingRoute, right: next.pendingRoute })) return 'pending'
+  if (previous.isNavigating !== next.isNavigating) return next.isNavigating ? 'pending' : 'idle'
+  if (previous.history.length !== next.history.length) return 'history'
+  return 'idle'
+}
+
+export function createItenDevtools<M extends RouteMapDef>({
+  router,
+  maxEvents = DEFAULT_MAX_EVENTS,
+  now = Date.now,
+}: CreateDevtoolsInput<M>): ItenDevtools<M> {
+  const listeners = new Set<(snapshot: DevtoolsSnapshot<M>) => void>()
+  const events: DevtoolsEvent<M>[] = []
+  let currentState = router.getState()
+  let previousState: RouterState<M> | null = null
+  let nextId = 1
+  let disposed = false
+
+  function emit({ state }: { state: RouterState<M> }): void {
+    if (disposed) return
+    currentState = state
+    const event: DevtoolsEvent<M> = {
+      id: nextId,
+      type: classifyEvent({ previous: previousState, next: state }),
+      timestamp: now(),
+      route: state.route,
+      pendingRoute: state.pendingRoute,
+      error: state.error?.error ?? null,
+      canGoBack: state.canGoBack,
+      historyLength: state.history.length,
+    }
+    nextId += 1
+    previousState = state
+    events.push(event)
+    if (events.length > maxEvents) {
+      events.splice(0, events.length - maxEvents)
+    }
+    notify()
+  }
+
+  function getSnapshot(): DevtoolsSnapshot<M> {
+    return {
+      state: currentState,
+      events: [...events],
+    }
+  }
+
+  function notify(): void {
+    const snapshot = getSnapshot()
+    for (const listener of listeners) {
+      listener(snapshot)
+    }
+  }
+
+  const stopRouter = router.subscribe({
+    listener: (state) => {
+      emit({ state })
+    },
+  })
+
+  emit({ state: currentState })
+
+  function subscribe({
+    listener,
+  }: {
+    listener: (snapshot: DevtoolsSnapshot<M>) => void
+  }): () => void {
+    listeners.add(listener)
+    return () => {
+      listeners.delete(listener)
+    }
+  }
+
+  function clear(): void {
+    events.splice(0, events.length)
+    notify()
+  }
+
+  function dispose(): void {
+    disposed = true
+    stopRouter()
+    listeners.clear()
+    events.splice(0, events.length)
+  }
+
+  return {
+    getSnapshot,
+    subscribe,
+    clear,
+    dispose,
+  }
+}

package/index.js

@@ -1 +0,0 @@
-throw new Error('iten-devtools is reserved for upcoming iten developer tools.')