@furystack/shades 14.0.0 → 15.0.1

package/src/services/location-service.tsx

@@ -1,174 +1,208 @@
-import { Injectable, type Injector } from '@furystack/inject'
+import type { Injector, Token } from '@furystack/inject'
+import { defineService } from '@furystack/inject'
 import {
   deserializeQueryString as defaultDeserializeQueryString,
   serializeToQueryString as defaultSerializeToQueryString,
 } from '@furystack/rest'
 import { ObservableValue } from '@furystack/utils'
+
 /**
- * Singleton service that tracks browser location changes (pathname, search, hash)
- * and exposes them as observable values for reactive routing and URL-driven state.
+ * Overridable settings for {@link LocationService}. Bind a replacement factory
+ * via {@link useCustomSearchStateSerializer} to swap the URL query-string
+ * (de)serializers used by the service.
  */
-@Injectable({ lifetime: 'singleton' })
-export class LocationService implements Disposable {
-  constructor(
-    private readonly serializeToQueryString = defaultSerializeToQueryString,
-
-    public readonly deserializeQueryString = defaultDeserializeQueryString,
-  ) {
-    window.addEventListener('popstate', this.popStateListener)
-    window.addEventListener('hashchange', this.hashChangeListener)
-
-    this.onDeserializedLocationSearchChanged = new ObservableValue(this.deserializeQueryString(location.search))
-
-    this.originalPushState = window.history.pushState.bind(window.history)
-    window.history.pushState = ((...args: Parameters<typeof window.history.pushState>) => {
-      this.originalPushState(...args)
-      this.updateState()
-    }).bind(this)
-
-    this.originalReplaceState = window.history.replaceState.bind(window.history)
-    window.history.replaceState = ((...args: Parameters<typeof window.history.replaceState>) => {
-      this.originalReplaceState(...args)
-      this.updateState()
-    }).bind(this)
-  }
-
-  private originalPushState: typeof window.history.pushState
-  private originalReplaceState: typeof window.history.replaceState
+export interface LocationServiceSettings {
+  serialize: typeof defaultSerializeToQueryString
+  deserialize: typeof defaultDeserializeQueryString
+}
 
-  public [Symbol.dispose]() {
-    window.removeEventListener('popstate', this.popStateListener)
-    window.removeEventListener('hashchange', this.hashChangeListener)
-    this.onLocationSearchChanged[Symbol.dispose]()
-    this.onDeserializedLocationSearchChanged[Symbol.dispose]()
-    this.locationDeserializerObserver[Symbol.dispose]()
-    this.onLocationPathChanged[Symbol.dispose]()
-    this.onLocationHashChanged[Symbol.dispose]()
-
-    window.history.pushState = this.originalPushState
-    window.history.replaceState = this.originalReplaceState
-  }
+export const LocationServiceSettings: Token<LocationServiceSettings, 'singleton'> = defineService({
+  name: '@furystack/shades/LocationServiceSettings',
+  lifetime: 'singleton',
+  factory: () => ({
+    serialize: defaultSerializeToQueryString,
+    deserialize: defaultDeserializeQueryString,
+  }),
+})
 
+/**
+ * Singleton service that tracks browser location changes (pathname, search, hash)
+ * and exposes them as observable values for reactive routing and URL-driven state.
+ */
+export interface LocationService {
+  readonly deserializeQueryString: typeof defaultDeserializeQueryString
+  readonly onLocationPathChanged: ObservableValue<string>
+  readonly onLocationHashChanged: ObservableValue<string>
+  readonly onLocationSearchChanged: ObservableValue<string>
+  readonly onDeserializedLocationSearchChanged: ObservableValue<Record<string, unknown>>
+  readonly searchParamObservables: Map<string, ObservableValue<any>>
   /**
-   * Observable value that will be updated when the location pathname (e.g. /page/1) changes
+   * Synchronizes the observable state with the current browser location.
+   * Called internally after navigation events and history state changes.
    */
-  public onLocationPathChanged = new ObservableValue(new URL(location.href).pathname)
-
+  updateState(): void
+  /**
+   * Navigate to a path. Use this instead of raw history.pushState for SPA routing.
+   */
+  navigate(path: string): void
   /**
-   * Observable value that will be updated when the location hash (e.g. #hash) changes
+   * Replace the current history entry with a new path. Use this instead of raw
+   * history.replaceState for SPA redirects where the intermediate URL should
+   * not appear in the browser's back/forward stack.
    */
-  public onLocationHashChanged = new ObservableValue(location.hash.replace('#', ''))
-
+  replace(path: string): void
   /**
-   * Observable value that will be updated when the location search (e.g. ?search=1) changes
+   * Gets or creates an observable for a search parameter.
    */
-  public onLocationSearchChanged = new ObservableValue<string>(location.search)
+  useSearchParam<T>(key: string, defaultValue: T): ObservableValue<T>
+}
 
-  public onDeserializedLocationSearchChanged: ObservableValue<Record<string, unknown>>
+export const LocationService: Token<LocationService, 'singleton'> = defineService({
+  name: '@furystack/shades/LocationService',
+  lifetime: 'singleton',
+  factory: ({ inject, onDispose }) => {
+    const { serialize, deserialize } = inject(LocationServiceSettings)
+
+    const onLocationPathChanged = new ObservableValue(new URL(location.href).pathname)
+    const onLocationHashChanged = new ObservableValue(location.hash.replace('#', ''))
+    const onLocationSearchChanged = new ObservableValue<string>(location.search)
+    const onDeserializedLocationSearchChanged = new ObservableValue<Record<string, unknown>>(
+      deserialize(location.search),
+    )
+    const searchParamObservables = new Map<string, ObservableValue<any>>()
+
+    const updateState = (): void => {
+      onLocationPathChanged.setValue(location.pathname)
+      onLocationHashChanged.setValue(location.hash.replace('#', ''))
+      onLocationSearchChanged.setValue(location.search)
+    }
 
-  public locationDeserializerObserver = this.onLocationSearchChanged.subscribe((search) => {
-    this.onDeserializedLocationSearchChanged.setValue(this.deserializeQueryString(search))
-  })
+    const locationDeserializerObserver = onLocationSearchChanged.subscribe((search) => {
+      onDeserializedLocationSearchChanged.setValue(deserialize(search))
+    })
 
-  /**
-   * Synchronizes the observable state with the current browser location.
-   * Called internally after navigation events and history state changes.
-   */
-  public updateState = (() => {
-    this.onLocationPathChanged.setValue(location.pathname)
-    this.onLocationHashChanged.setValue(location.hash.replace('#', ''))
-    this.onLocationSearchChanged.setValue(location.search)
-  }).bind(this)
+    const popStateListener = (_ev: PopStateEvent): void => {
+      updateState()
+    }
+    const hashChangeListener = (_ev: HashChangeEvent): void => {
+      updateState()
+    }
+    window.addEventListener('popstate', popStateListener)
+    window.addEventListener('hashchange', hashChangeListener)
 
-  /**
-   * Navigate to a path. Use this instead of raw history.pushState for SPA routing.
-   * The LocationService interceptor ensures routing state is updated correctly.
-   */
-  public navigate(path: string): void {
-    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.navigate() implementation.
-    history.pushState(null, '', path)
-    this.updateState()
-  }
+    const originalPushState = window.history.pushState.bind(window.history)
+    window.history.pushState = (...args: Parameters<typeof window.history.pushState>) => {
+      originalPushState(...args)
+      updateState()
+    }
 
-  /**
-   * Replace the current history entry with a new path. Use this instead of
-   * raw history.replaceState for SPA redirects (e.g. the intermediate URL
-   * should not appear in the browser's back/forward stack).
-   */
-  public replace(path: string): void {
-    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.replace() implementation.
-    history.replaceState(null, '', path)
-    this.updateState()
-  }
+    const originalReplaceState = window.history.replaceState.bind(window.history)
+    window.history.replaceState = (...args: Parameters<typeof window.history.replaceState>) => {
+      originalReplaceState(...args)
+      updateState()
+    }
 
-  /**
-   * Internal cache of per-key search parameter observables created by {@link useSearchParam}.
-   */
-  public readonly searchParamObservables = new Map<string, ObservableValue<any>>()
+    const navigate = (path: string): void => {
+      // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.navigate() implementation.
+      history.pushState(null, '', path)
+      updateState()
+    }
 
-  /**
-   * Gets or creates an observable for a search parameter
-   * @param key The search param key (e.g. ?search=1 -> search)
-   * @param defaultValue The default value if not provided
-   * @returns An observable with the current value (or default value) of the search param
-   */
-  public useSearchParam<T>(key: string, defaultValue: T) {
-    const existing = this.searchParamObservables.get(key)
+    const replace = (path: string): void => {
+      // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.replace() implementation.
+      history.replaceState(null, '', path)
+      updateState()
+    }
 
-    if (!existing) {
-      const currentDeserialized = this.onDeserializedLocationSearchChanged.getValue()
+    const useSearchParam = <T,>(key: string, defaultValue: T): ObservableValue<T> => {
+      const existing = searchParamObservables.get(key)
+      if (existing) return existing as ObservableValue<T>
 
+      const currentDeserialized = onDeserializedLocationSearchChanged.getValue()
       const actualValue = Object.prototype.hasOwnProperty.call(currentDeserialized, key)
         ? (currentDeserialized[key] as T)
         : defaultValue
 
       const newObservable = new ObservableValue(actualValue)
-      this.searchParamObservables.set(key, newObservable)
+      searchParamObservables.set(key, newObservable)
 
       newObservable.subscribe((value) => {
-        const currentQueryStringObject = this.onDeserializedLocationSearchChanged.getValue()
+        const currentQueryStringObject = onDeserializedLocationSearchChanged.getValue()
         if (currentQueryStringObject[key] !== value) {
-          const params = this.serializeToQueryString({ ...currentQueryStringObject, [key]: value })
+          const params = serialize({ ...currentQueryStringObject, [key]: value })
           const newUrl = `${location.pathname}?${params}`
           // eslint-disable-next-line furystack/prefer-location-service -- Internal LocationService plumbing for search param sync.
           history.pushState({}, '', newUrl)
         }
       })
 
-      this.onDeserializedLocationSearchChanged.subscribe((search) => {
+      onDeserializedLocationSearchChanged.subscribe((search) => {
         const value = (search[key] as T) ?? defaultValue
-        this.searchParamObservables.get(key)?.setValue(value)
+        searchParamObservables.get(key)?.setValue(value)
       })
+
       return newObservable
     }
-    return existing as ObservableValue<T>
-  }
-
-  private popStateListener = (_ev: PopStateEvent) => {
-    this.updateState()
-  }
 
-  private hashChangeListener = ((_ev: HashChangeEvent) => {
-    this.updateState()
-  }).bind(this)
-}
+    onDispose(() => {
+      window.removeEventListener('popstate', popStateListener)
+      window.removeEventListener('hashchange', hashChangeListener)
+      window.history.pushState = originalPushState
+      window.history.replaceState = originalReplaceState
+      locationDeserializerObserver[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onLocationSearchChanged[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onDeserializedLocationSearchChanged[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onLocationPathChanged[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onLocationHashChanged[Symbol.dispose]()
+    })
+
+    return {
+      deserializeQueryString: deserialize,
+      onLocationPathChanged,
+      onLocationHashChanged,
+      onLocationSearchChanged,
+      onDeserializedLocationSearchChanged,
+      searchParamObservables,
+      updateState,
+      navigate,
+      replace,
+      useSearchParam,
+    }
+  },
+})
 
 /**
- * Configures custom serialization for URL search state.
- * Must be called **before** `LocationService` is first instantiated by the injector.
- * @param injector The root injector
- * @param serialize Function to serialize state to a query string
- * @param deserialize Function to deserialize a query string to state
+ * Configures custom (de)serialization for URL search state by binding
+ * {@link LocationServiceSettings} on the given injector.
+ *
+ * Must be called **before** any consumer resolves {@link LocationService}:
+ * the service patches `history.pushState` / `history.replaceState` and
+ * subscribes to `popstate` / `hashchange` on construction, and those
+ * listeners are only torn down when the owning injector is disposed.
+ * Rebinding after the first resolution would leak the previous instance,
+ * so this helper throws loudly if that happens.
+ *
+ * @param injector The root injector.
+ * @param serialize Function to serialize state to a query string.
+ * @param deserialize Function to deserialize a query string to state.
+ * @throws If {@link LocationService} has already been resolved on
+ *         `injector` (or any reachable ancestor).
  */
 export const useCustomSearchStateSerializer = (
   injector: Injector,
   serialize: typeof defaultSerializeToQueryString,
   deserialize: typeof defaultDeserializeQueryString,
-) => {
-  if (injector.cachedSingletons.has(LocationService)) {
-    throw new Error('useCustomSearchStateSerializer must be called before the LocationService is instantiated')
+): void => {
+  if (injector.isResolved(LocationService)) {
+    throw new Error(
+      'useCustomSearchStateSerializer must be called before LocationService is resolved for the first time. ' +
+        'Configure serializers during injector bootstrap (e.g. before the first render).',
+    )
   }
-
-  const locationService = new LocationService(serialize, deserialize)
-  injector.setExplicitInstance(locationService, LocationService)
+  injector.bind(LocationServiceSettings, () => ({ serialize, deserialize }))
+  injector.invalidate(LocationServiceSettings)
 }

package/src/services/route-match-service.spec.ts

@@ -1,48 +1,57 @@
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
 import { describe, expect, it, vi } from 'vitest'
 import type { MatchChainEntry } from '../components/nested-router.js'
 import { RouteMatchService } from './route-match-service.js'
 
 describe('RouteMatchService', () => {
-  it('should start with an empty match chain', () => {
-    using service = new RouteMatchService()
-    expect(service.currentMatchChain.getValue()).toEqual([])
+  it('should start with an empty match chain', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const service = i.get(RouteMatchService)
+      expect(service.currentMatchChain.getValue()).toEqual([])
+    })
   })
 
-  it('should update the match chain', () => {
-    using service = new RouteMatchService()
-    const chain: MatchChainEntry[] = [
-      {
-        route: { component: () => ({}) as JSX.Element },
-        match: { path: '/about', params: {} },
-        query: null,
-        hash: undefined,
-      },
-    ]
-    service.currentMatchChain.setValue(chain)
-    expect(service.currentMatchChain.getValue()).toBe(chain)
+  it('should update the match chain', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const service = i.get(RouteMatchService)
+      const chain: MatchChainEntry[] = [
+        {
+          route: { component: () => ({}) as JSX.Element },
+          match: { path: '/about', params: {} },
+          query: null,
+          hash: undefined,
+        },
+      ]
+      service.currentMatchChain.setValue(chain)
+      expect(service.currentMatchChain.getValue()).toBe(chain)
+    })
   })
 
-  it('should notify subscribers on match chain change', () => {
-    using service = new RouteMatchService()
-    const listener = vi.fn()
-    using _subscription = service.currentMatchChain.subscribe(listener)
+  it('should notify subscribers on match chain change', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const service = i.get(RouteMatchService)
+      const listener = vi.fn()
+      using _subscription = service.currentMatchChain.subscribe(listener)
 
-    const chain: MatchChainEntry[] = [
-      {
-        route: { meta: { title: 'Home' }, component: () => ({}) as JSX.Element },
-        match: { path: '/', params: {} },
-        query: null,
-        hash: undefined,
-      },
-    ]
-    service.currentMatchChain.setValue(chain)
+      const chain: MatchChainEntry[] = [
+        {
+          route: { meta: { title: 'Home' }, component: () => ({}) as JSX.Element },
+          match: { path: '/', params: {} },
+          query: null,
+          hash: undefined,
+        },
+      ]
+      service.currentMatchChain.setValue(chain)
 
-    expect(listener).toHaveBeenCalledWith(chain)
+      expect(listener).toHaveBeenCalledWith(chain)
+    })
   })
 
-  it('should dispose the observable on service disposal', () => {
-    const service = new RouteMatchService()
-    service[Symbol.dispose]()
+  it('should dispose the observable on injector disposal', async () => {
+    const injector = createInjector()
+    const service = injector.get(RouteMatchService)
+    await injector[Symbol.asyncDispose]()
 
     expect(() => service.currentMatchChain.setValue([])).toThrow()
   })

package/src/services/route-match-service.ts

@@ -1,4 +1,5 @@
-import { Injectable } from '@furystack/inject'
+import type { Token } from '@furystack/inject'
+import { defineService } from '@furystack/inject'
 import { ObservableValue } from '@furystack/utils'
 import type { MatchChainEntry } from '../components/nested-router.js'
 
@@ -7,11 +8,19 @@ import type { MatchChainEntry } from '../components/nested-router.js'
  * NestedRouter as an observable. Consumers (breadcrumbs, document title,
  * navigation trees) subscribe to this instead of re-running route matching.
  */
-@Injectable({ lifetime: 'singleton' })
-export class RouteMatchService implements Disposable {
-  public readonly currentMatchChain = new ObservableValue<MatchChainEntry[]>([])
-
-  public [Symbol.dispose]() {
-    this.currentMatchChain[Symbol.dispose]()
-  }
+export interface RouteMatchService {
+  readonly currentMatchChain: ObservableValue<MatchChainEntry[]>
 }
+
+export const RouteMatchService: Token<RouteMatchService, 'singleton'> = defineService({
+  name: '@furystack/shades/RouteMatchService',
+  lifetime: 'singleton',
+  factory: ({ onDispose }) => {
+    const currentMatchChain = new ObservableValue<MatchChainEntry[]>([])
+    onDispose(() => {
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      currentMatchChain[Symbol.dispose]()
+    })
+    return { currentMatchChain }
+  },
+})

package/src/services/route-meta-utils.spec.ts

@@ -1,4 +1,4 @@
-import { Injector } from '@furystack/inject'
+import { createInjector, Injector } from '@furystack/inject'
 import { describe, expect, expectTypeOf, it } from 'vitest'
 import type { MatchChainEntry, NestedRoute } from '../components/nested-router.js'
 import {
@@ -12,7 +12,7 @@ import {
 type TestRoute = Pick<NestedRoute<unknown, any, any>, 'component'>
 
 describe('resolveRouteTitle', () => {
-  const injector = new Injector()
+  const injector = createInjector()
 
   it('should return undefined when no meta is configured', async () => {
     const entry: MatchChainEntry = {
@@ -92,7 +92,7 @@ describe('resolveRouteTitle', () => {
 })
 
 describe('resolveRouteTitles', () => {
-  const injector = new Injector()
+  const injector = createInjector()
 
   it('should resolve all titles in a mixed chain', async () => {
     const chain: MatchChainEntry[] = [

package/src/services/route-meta-utils.ts

@@ -108,7 +108,7 @@ export const extractNavTree = <TRoutes extends Record<string, NestedRoute<any, a
         fullPath,
         meta: route.meta,
         children: route.children ? build(route.children, fullPath) : undefined,
-      } as NavTreeNode<TRoutes>
+      }
     })
   return build(routes, parentPath)
 }

package/src/services/screen-service.spec.ts

@@ -1,4 +1,4 @@
-import { Injector } from '@furystack/inject'
+import { createInjector } from '@furystack/inject'
 import { usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { ScreenService, ScreenSizes } from './screen-service.js'
@@ -13,16 +13,17 @@ describe('ScreenService', () => {
   })
 
   it('Should be constructed', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const s = i.getInstance(ScreenService)
-      expect(s).toBeInstanceOf(ScreenService)
+    await usingAsync(createInjector(), async (i) => {
+      const s = i.get(ScreenService)
+      expect(s).toBeDefined()
+      expect(s.breakpoints).toBeDefined()
     })
   })
 
   describe('breakpoints', () => {
     it('Should have correct breakpoint definitions', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
 
         expect(s.breakpoints.xs.minSize).toBe(0)
         expect(s.breakpoints.sm.minSize).toBe(600)
@@ -35,8 +36,8 @@ describe('ScreenService', () => {
 
   describe('screenSize.atLeast', () => {
     it('Should have observable for each screen size', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
 
         for (const size of ScreenSizes) {
           expect(s.screenSize.atLeast[size]).toBeDefined()
@@ -46,16 +47,16 @@ describe('ScreenService', () => {
     })
 
     it('Should return true for xs on any screen size', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
         // xs has minSize 0, so it should always be true
         expect(s.screenSize.atLeast.xs.getValue()).toBe(true)
       })
     })
 
     it('Should update screenSize observables on window resize', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
 
         // Mock window.innerWidth to simulate a large screen
         vi.spyOn(window, 'innerWidth', 'get').mockReturnValue(1920)
@@ -86,8 +87,8 @@ describe('ScreenService', () => {
 
   describe('orientation', () => {
     it('Should have an orientation observable', async () => {
-      await usingAsync(new Injector(), async (i) => {
-        const s = i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        const s = i.get(ScreenService)
         const orientation = s.orientation.getValue()
         expect(['landscape', 'portrait']).toContain(orientation)
       })
@@ -98,17 +99,17 @@ describe('ScreenService', () => {
       const matchMediaMock = vi.fn()
       window.matchMedia = matchMediaMock
 
-      await usingAsync(new Injector(), async (i) => {
+      await usingAsync(createInjector(), async (i) => {
         // Set initial orientation to landscape
-        matchMediaMock.mockReturnValue({ matches: true } as MediaQueryList)
-        const s = i.getInstance(ScreenService)
+        matchMediaMock.mockReturnValue({ matches: true })
+        const s = i.get(ScreenService)
 
         // Verify initial landscape
         window.dispatchEvent(new Event('resize'))
         expect(s.orientation.getValue()).toBe('landscape')
 
         // Change to portrait
-        matchMediaMock.mockReturnValue({ matches: false } as MediaQueryList)
+        matchMediaMock.mockReturnValue({ matches: false })
         window.dispatchEvent(new Event('resize'))
         expect(s.orientation.getValue()).toBe('portrait')
       })
@@ -119,8 +120,8 @@ describe('ScreenService', () => {
     it('Should remove resize event listener on dispose', async () => {
       const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener')
 
-      await usingAsync(new Injector(), async (i) => {
-        i.getInstance(ScreenService)
+      await usingAsync(createInjector(), async (i) => {
+        i.get(ScreenService)
       })
 
       expect(removeEventListenerSpy).toHaveBeenCalledWith('resize', expect.any(Function))