@typed/navigation 0.1.0

package/src/history.ts

@@ -0,0 +1,141 @@
+import * as Cause from '@effect/io/Cause'
+import * as Effect from '@effect/io/Effect'
+import * as Fiber from '@effect/io/Fiber'
+import * as Runtime from '@effect/io/Runtime'
+import * as Scope from '@effect/io/Scope'
+import { History } from '@typed/dom'
+import * as Fx from '@typed/fx'
+
+import { Destination, NavigationError } from './Navigation.js'
+import { ServiceId } from './constant.js'
+import { DomIntent } from './dom-intent.js'
+
+export type HistoryEvent = PushStateEvent | ReplaceStateEvent | GoEvent | BackEvent | ForwardEvent
+
+export interface PushStateEvent {
+  readonly _tag: 'PushState'
+  readonly state: unknown
+  readonly url: string
+}
+
+export interface ReplaceStateEvent {
+  readonly _tag: 'ReplaceState'
+  readonly state: unknown
+  readonly url: string
+}
+
+export interface GoEvent {
+  readonly _tag: 'Go'
+  readonly delta: number
+}
+
+export interface BackEvent {
+  readonly _tag: 'Back'
+}
+
+export interface ForwardEvent {
+  readonly _tag: 'Forward'
+}
+
+export const patchHistory: Effect.Effect<
+  History | Scope.Scope,
+  never,
+  Fx.Subject<never, HistoryEvent>
+> = Effect.gen(function* ($) {
+  const history = yield* $(History)
+  const scope = yield* $(Effect.scope)
+  const historyEvents = Fx.makeSubject<never, HistoryEvent>()
+  const runtime = yield* $(Effect.runtime<never>())
+  const runFork = Runtime.runFork(runtime)
+  const cleanup = patchHistory_(history, (event: HistoryEvent) =>
+    runFork(Effect.flatMap(Effect.forkIn(historyEvents.event(event), scope), Fiber.join)),
+  )
+
+  // unpatch history upon finalization
+  yield* $(Effect.addFinalizer(() => Effect.sync(cleanup)))
+
+  return historyEvents
+})
+
+function patchHistory_(history: History, sendEvent: (event: HistoryEvent) => void) {
+  const pushState = history.pushState.bind(history)
+  const replaceState = history.replaceState.bind(history)
+  const go = history.go.bind(history)
+  const back = history.back.bind(history)
+  const forward = history.forward.bind(history)
+
+  history.pushState = function (state, title, url) {
+    pushState(state, title, url)
+
+    if (url && this !== ServiceId) sendEvent({ _tag: 'PushState', state, url: url.toString() })
+  }
+
+  history.replaceState = function (state, title, url) {
+    replaceState(state, title, url)
+
+    if (url && this !== ServiceId) sendEvent({ _tag: 'ReplaceState', state, url: url.toString() })
+  }
+
+  history.go = function (delta) {
+    if (!delta) return
+
+    go(delta)
+    if (this !== ServiceId) sendEvent({ _tag: 'Go', delta })
+  }
+
+  history.back = function () {
+    back()
+    if (this !== ServiceId) sendEvent({ _tag: 'Back' })
+  }
+
+  history.forward = function () {
+    forward()
+    if (this !== ServiceId) sendEvent({ _tag: 'Forward' })
+  }
+
+  const stateDescriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(history), 'state')
+  Object.defineProperty(history, 'state', {
+    ...stateDescriptor,
+    get() {
+      return stateDescriptor?.get?.()?.state
+    },
+  })
+  Object.defineProperty(history, 'originalState', {
+    ...stateDescriptor,
+  })
+
+  // Reset history to original state
+  return () => {
+    history.pushState = pushState
+    history.replaceState = replaceState
+    history.go = go
+    history.back = back
+    history.forward = forward
+
+    if (stateDescriptor) Object.defineProperty(history, 'state', stateDescriptor)
+  }
+}
+
+export function onHistoryEvent(
+  event: HistoryEvent,
+  intent: DomIntent,
+): Effect.Effect<
+  History | Location | Storage,
+  Cause.NoSuchElementException | NavigationError,
+  Destination
+> {
+  return Effect.gen(function* ($) {
+    switch (event._tag) {
+      case 'PushState':
+        return yield* $(intent.push(event.url, { state: event.state }, true))
+      case 'ReplaceState':
+        return yield* $(intent.replace(event.url, { state: event.state }, true))
+      case 'Back':
+        return yield* $(intent.back(true))
+      case 'Forward':
+        return yield* $(intent.forward(true))
+      case 'Go':
+        return yield* $(intent.go(event.delta, true))
+    }
+  })
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './Navigation.js'
+export * from './DOM.js'
+export * from './Memory.js'

package/src/json.ts

@@ -0,0 +1,31 @@
+import { Destination, NavigationEvent } from './Navigation.js'
+
+export type NavigationEventJson = {
+  readonly [K in keyof NavigationEvent]: NavigationEvent[K] extends Destination
+    ? DestinationJson
+    : NavigationEvent[K]
+}
+
+type DestinationJson = {
+  readonly [K in keyof Destination]: Destination[K] extends URL ? string : Destination[K]
+}
+
+export const decodeDestination = (d: DestinationJson): Destination => ({
+  ...d,
+  url: new URL(d.url),
+})
+
+export const decodeNavigationEvent = (event: NavigationEventJson): NavigationEvent => ({
+  ...event,
+  destination: decodeDestination(event.destination),
+})
+
+export const encodeEvent = (event: NavigationEvent): NavigationEventJson => ({
+  ...event,
+  destination: encodeDestination(event.destination),
+})
+
+export const encodeDestination = (destination: Destination): DestinationJson => ({
+  ...destination,
+  url: destination.url.href,
+})

package/src/memory-intent.ts

@@ -0,0 +1,221 @@
+import { Option } from '@effect/data/Option'
+import * as Cause from '@effect/io/Cause'
+import * as Effect from '@effect/io/Effect'
+
+import type { MemoryNavigationOptions } from './Memory.js'
+import {
+  Destination,
+  NavigateOptions,
+  NavigationError,
+  NavigationEvent,
+  NavigationType,
+} from './Navigation.js'
+import { Model } from './model.js'
+import {
+  Notify,
+  Save,
+  makeGoTo,
+  makeNotify,
+  makeOnNavigation,
+  makeOnNavigationEnd,
+} from './shared-intent.js'
+import { createKey, getUrl } from './util.js'
+
+// Roughly the number of History entries in a browser anyways
+const DEFAULT_MAX_ENTRIES = 50
+
+export type MemoryIntent = {
+  readonly back: ReturnType<ReturnType<typeof makeGo>>
+
+  readonly forward: ReturnType<ReturnType<typeof makeGo>>
+
+  readonly push: ReturnType<typeof makePush>
+
+  readonly replace: ReturnType<typeof makeReplace>
+
+  readonly navigate: (
+    url: string,
+    options?: NavigateOptions,
+  ) => ReturnType<ReturnType<typeof makePush | typeof makeReplace>>
+
+  readonly notify: Notify
+
+  readonly go: ReturnType<typeof makeGo>
+
+  readonly goTo: (
+    key: string,
+  ) => Effect.Effect<never, Cause.NoSuchElementException | NavigationError, Option<Destination>>
+
+  readonly reload: ReturnType<typeof makeReload>
+
+  readonly onNavigation: ReturnType<typeof makeOnNavigation>
+
+  readonly onNavigationEnd: ReturnType<typeof makeOnNavigationEnd>
+}
+
+export function makeIntent(model: Model, options: MemoryNavigationOptions): MemoryIntent {
+  const { origin } = options.initialUrl
+  const base = options.base ?? '/'
+  const maxEntries = Math.abs(options.maxEntries ?? DEFAULT_MAX_ENTRIES)
+  const notify = makeNotify(model)
+  const save = makeSave(model)
+  const go = makeGo(model, notify, save)
+  const replace = makeReplace(model, notify, save, base, origin)
+  const push = makePush(model, notify, save, base, origin, maxEntries)
+
+  return {
+    back: go(-1),
+    forward: go(1),
+    push,
+    replace,
+    navigate: (url: string, options: NavigateOptions = {}) =>
+      options.history === 'replace' ? replace(url, options) : push(url, options),
+    go: go,
+    goTo: makeGoTo(model, go),
+    reload: makeReload(model, notify, save),
+    onNavigation: makeOnNavigation(model),
+    onNavigationEnd: makeOnNavigationEnd(model),
+    notify,
+  } as const
+}
+
+export type Intent = ReturnType<typeof makeIntent>
+
+export const makeSave: (
+  model: Model,
+) => (event: NavigationEvent) => Effect.Effect<never, Cause.NoSuchElementException, void> =
+  (model: Model) => (event: NavigationEvent) =>
+    Effect.gen(function* ($) {
+      const events = yield* $(model.events)
+      const index = yield* $(model.index)
+
+      // Update current entry
+      yield* $(model.currentEntry.set(event.destination))
+
+      // Update canGoBack
+      yield* $(model.canGoBack.set(index > 0))
+
+      // Update canGoForward
+      yield* $(model.canGoForward.set(index < events.length - 1))
+    })
+
+export const makeReload = (model: Model, notify: Notify, save: Save<never>) =>
+  Effect.gen(function* ($) {
+    const i = yield* $(model.index.get)
+    const e = yield* $(model.events)
+    const event = e[i]
+    const reloadEvent = { ...event, navigationType: NavigationType.Reload }
+
+    yield* $(notify(reloadEvent))
+    yield* $(save(reloadEvent))
+
+    return event.destination
+  })
+
+export const makeReplace =
+  (model: Model, notify: Notify, save: Save<never>, base: string, origin: string) =>
+  (url: string, options: NavigateOptions = {}) =>
+    Effect.gen(function* ($) {
+      const entry = yield* $(model.currentEntry.get)
+      const destination: Destination = {
+        key: entry.key,
+        url: getUrl(url, base, origin),
+        state: options.state,
+      }
+      const event: NavigationEvent = {
+        destination,
+        hashChange: entry.url.hash !== destination.url.hash,
+        navigationType: NavigationType.Replace,
+      }
+
+      yield* $(notify(event))
+
+      const currentIndex = yield* $(model.index)
+
+      yield* $(
+        model.events.update((entries) => {
+          const updated = entries.slice(0)
+          updated[currentIndex] = event
+          return updated
+        }),
+      )
+
+      yield* $(save(event))
+
+      return destination
+    })
+
+export const makePush =
+  (
+    model: Model,
+    notify: Notify,
+    save: Save<never>,
+    base: string,
+    origin: string,
+    maxEntries: number,
+  ) =>
+  (url: string, options: NavigateOptions = {}) =>
+    Effect.gen(function* ($) {
+      const entry = yield* $(model.currentEntry.get)
+      const destination: Destination = {
+        key: yield* $(createKey),
+        url: getUrl(url, base, origin),
+        state: options.state,
+      }
+      const event: NavigationEvent = {
+        destination,
+        hashChange: entry.url.hash !== destination.url.hash,
+        navigationType: NavigationType.Push,
+      }
+
+      // Notify event handlers
+      yield* $(notify(event))
+
+      const currentIndex = yield* $(model.index)
+
+      // Remove all entries after the current index
+      // and add the new destination to the end
+      yield* $(
+        model.events.update((entries) => {
+          const updated = entries.slice(0, currentIndex + 1)
+          updated.push(event)
+          return updated.slice(-maxEntries)
+        }),
+      )
+
+      // Update the index to the new destination
+      yield* $(model.index.update((i) => i + 1))
+
+      yield* $(save(event))
+
+      return destination
+    })
+
+export const makeGo = (model: Model, notify: Notify, save: Save<never>) => (delta: number) =>
+  Effect.gen(function* ($) {
+    const currentEntries = yield* $(model.events)
+    const totalEntries = currentEntries.length
+    const currentIndex = yield* $(model.index)
+
+    // Nothing to do here
+    if (delta === 0) return currentEntries[currentIndex].destination
+
+    const nextIndex =
+      delta > 0
+        ? Math.min(currentIndex + delta, totalEntries - 1)
+        : Math.max(currentIndex + delta, 0)
+    const nextEntry = currentEntries[nextIndex]
+
+    yield* $(
+      notify({
+        ...nextEntry,
+        navigationType: nextIndex > currentIndex ? NavigationType.Forward : NavigationType.Back,
+      }),
+    )
+
+    yield* $(model.index.set(nextIndex))
+
+    yield* $(save(nextEntry))
+
+    return nextEntry.destination
+  })

package/src/model.ts

@@ -0,0 +1,54 @@
+import * as Effect from '@effect/io/Effect'
+import * as Scope from '@effect/io/Scope'
+import * as Fx from '@typed/fx'
+
+import { Destination, NavigationError, NavigationEvent, OnNavigationOptions } from './Navigation.js'
+
+export interface Model {
+  readonly onNavigationHandlers: Set<
+    readonly [
+      (event: NavigationEvent) => Effect.Effect<never, NavigationError, unknown>,
+      OnNavigationOptions?,
+    ]
+  >
+  readonly onNavigationEndHandlers: Set<
+    readonly [
+      (event: NavigationEvent) => Effect.Effect<never, never, unknown>,
+      OnNavigationOptions?,
+    ]
+  >
+  readonly events: Fx.RefSubject<never, readonly NavigationEvent[]>
+  readonly index: Fx.RefSubject<never, number>
+  readonly entries: Fx.Computed<never, never, Destination[]>
+  readonly currentEntry: Fx.RefSubject<never, Destination>
+  readonly canGoBack: Fx.RefSubject<never, boolean>
+  readonly canGoForward: Fx.RefSubject<never, boolean>
+}
+
+export const makeModel = (
+  initialEntries: readonly NavigationEvent[],
+  initialIndex: number,
+): Effect.Effect<Scope.Scope, never, Model> =>
+  Effect.gen(function* ($) {
+    const events = yield* $(Fx.makeRef(Effect.succeed(initialEntries)))
+    const index = yield* $(Fx.makeRef(Effect.succeed(initialIndex)))
+    const entries = events.map((es) => es.map((e) => e.destination))
+    const currentEntry = yield* $(
+      Fx.makeRef(Effect.succeed(initialEntries[initialIndex].destination)),
+    )
+    const canGoBack = yield* $(Fx.makeRef(Effect.succeed(initialIndex > 0)))
+    const canGoForward = yield* $(
+      Fx.makeRef(Effect.succeed(initialIndex < initialEntries.length - 1)),
+    )
+
+    return {
+      onNavigationHandlers: new Set(),
+      onNavigationEndHandlers: new Set(),
+      events,
+      index,
+      entries,
+      currentEntry,
+      canGoBack,
+      canGoForward,
+    }
+  })

package/src/shared-intent.ts

@@ -0,0 +1,120 @@
+import * as Option from '@effect/data/Option'
+import * as Cause from '@effect/io/Cause'
+import * as Effect from '@effect/io/Effect'
+import * as Scope from '@effect/io/Scope'
+
+import { Destination, NavigationError, NavigationEvent, OnNavigationOptions } from './Navigation.js'
+import { Model } from './model.js'
+
+export type Notify = (event: NavigationEvent) => Effect.Effect<never, NavigationError, void>
+export type NotifyEnd = (event: NavigationEvent) => Effect.Effect<never, never, void>
+
+export type Save<R> = (
+  event: NavigationEvent,
+) => Effect.Effect<R, Cause.NoSuchElementException, void>
+
+// Anytime there are changes to the model, we need to notify all event handlers
+export const makeNotify = (model: Model) => (event: NavigationEvent) =>
+  Effect.gen(function* ($) {
+    // Notify event handlers
+    if (model.onNavigationHandlers.size > 0)
+      yield* $(
+        Effect.forEach(
+          model.onNavigationHandlers,
+          ([handler, options]) => (options?.passive ? Effect.fork(handler(event)) : handler(event)),
+          { discard: true },
+        ),
+      )
+  })
+
+export const makeOnNavigation =
+  (model: Model) =>
+  <R>(
+    handler: (event: NavigationEvent) => Effect.Effect<R, NavigationError, unknown>,
+    options?: OnNavigationOptions,
+  ): Effect.Effect<R | Scope.Scope, NavigationError, void> =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function* ($) {
+        const context = yield* $(Effect.context<R>())
+        const handler_ = (event: NavigationEvent) =>
+          restore(Effect.provideContext(handler(event), context))
+        const entry = [handler_, options] as const
+
+        model.onNavigationHandlers.add(entry)
+
+        yield* $(
+          Effect.addFinalizer(() => Effect.sync(() => model.onNavigationHandlers.delete(entry))),
+        )
+
+        // Send the latest navigation event on subscription
+        const events = yield* $(model.events)
+        const index = yield* $(model.index)
+        const event = events[index]
+
+        yield* $(restore(handler(event)))
+      }),
+    )
+
+// Anytime there are changes to the model, we need to notify all event handlers
+export const makeNotifyEnd = (model: Model) => (event: NavigationEvent) =>
+  Effect.gen(function* ($) {
+    // Notify event handlers
+    if (model.onNavigationEndHandlers.size > 0)
+      yield* $(
+        Effect.forEach(
+          model.onNavigationEndHandlers,
+          ([handler, options]) => (options?.passive ? Effect.fork(handler(event)) : handler(event)),
+          { discard: true },
+        ),
+      )
+  })
+
+export const makeOnNavigationEnd =
+  (model: Model) =>
+  <R>(
+    handler: (event: NavigationEvent) => Effect.Effect<R, never, unknown>,
+    options?: OnNavigationOptions,
+  ): Effect.Effect<R | Scope.Scope, never, void> =>
+    Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function* ($) {
+        const context = yield* $(Effect.context<R>())
+        const handler_ = (event: NavigationEvent) =>
+          restore(Effect.provideContext(handler(event), context))
+        const entry = [handler_, options] as const
+
+        model.onNavigationEndHandlers.add(entry)
+
+        yield* $(
+          Effect.addFinalizer(() => Effect.sync(() => model.onNavigationEndHandlers.delete(entry))),
+        )
+
+        // Send the latest navigation event on subscription
+        const events = yield* $(model.events)
+        const index = yield* $(model.index)
+        const event = events[index]
+
+        yield* $(restore(handler(event)))
+      }),
+    )
+
+export const makeGoTo =
+  <R, E>(
+    model: Model,
+    go: (delta: number, skipHistory?: boolean) => Effect.Effect<R, E, Destination>,
+  ) =>
+  (key: string): Effect.Effect<R, Cause.NoSuchElementException | E, Option.Option<Destination>> =>
+    Effect.gen(function* ($) {
+      const entries = yield* $(model.entries)
+      const currentIndex = yield* $(model.index)
+      const nextIndex = entries.findIndex((destination) => destination.key === key)
+
+      if (nextIndex === -1) return Option.none()
+
+      const delta = nextIndex - currentIndex
+
+      if (delta !== 0) {
+        return Option.some(yield* $(go(delta)))
+      }
+
+      return Option.some(entries[nextIndex])
+    })

package/src/storage.ts

@@ -0,0 +1,101 @@
+import * as Option from '@effect/data/Option'
+import * as Effect from '@effect/io/Effect'
+import { History, Location, getItem, setItem } from '@typed/dom'
+
+import type { DomNavigationOptions } from './DOM.js'
+import { NavigationEvent, Destination, NavigationType } from './Navigation.js'
+import { NavigationEventJson, decodeNavigationEvent } from './json.js'
+import { createKey, getUrl } from './util.js'
+
+const TYPED_NAVIGATION_ENTRIES_KEY = '@typed/navigation/entries'
+const TYPED_NAVIGATION_INDEX_KEY = '@typed/navigation/index'
+
+/**
+ * @internal
+ */
+export const getStoredEvents: Effect.Effect<Storage, never, readonly NavigationEvent[]> =
+  Effect.gen(function* ($) {
+    const option = yield* $(getItem(TYPED_NAVIGATION_ENTRIES_KEY))
+
+    if (Option.isNone(option)) {
+      return []
+    }
+
+    return (JSON.parse(option.value) as readonly NavigationEventJson[]).map(decodeNavigationEvent)
+  })
+
+/**
+ * @internal
+ */
+export const getStoredIndex = Effect.gen(function* ($) {
+  const option = yield* $(getItem(TYPED_NAVIGATION_INDEX_KEY))
+
+  if (Option.isNone(option)) {
+    return Option.none()
+  }
+
+  const n = JSON.parse(option.value) as number
+
+  if (Number.isNaN(n)) {
+    return Option.none()
+  }
+
+  return Option.some(n)
+})
+
+/**
+ * @internal
+ */
+export const getInitialValues = (
+  base: string,
+  options: DomNavigationOptions,
+): Effect.Effect<
+  Storage | History | Location,
+  never,
+  readonly [readonly NavigationEvent[], number]
+> =>
+  Effect.gen(function* ($) {
+    // Get Resources
+    const history = yield* $(History)
+    const location = yield* $(Location)
+
+    // Read the stored entries and index
+    const storedEntries = yield* $(getStoredEvents)
+    const storedIndex = Option.getOrElse(yield* $(getStoredIndex), () => storedEntries.length - 1)
+    const storedEntry = storedEntries[storedIndex]
+
+    // Read the initial url from the location
+    const initialUrl = getUrl(location.href, base, location.origin)
+    const initial: Destination = {
+      key: options.initialKey ?? (yield* $(createKey)),
+      url: initialUrl,
+      state: history.state?.state,
+    }
+    const initialEvent: NavigationEvent = {
+      destination: initial,
+      hashChange: false,
+      navigationType: NavigationType.Push,
+    }
+
+    // If there are no stored entries then we can just use the initial entry
+    if (!storedEntry) {
+      return [[initialEvent], 0] as const
+    }
+
+    // If we're starting on the same page as the initial entry
+    // then we can just use the initial entries
+    if (storedEntry.destination.url.href === initialUrl.href) {
+      return [storedEntries, storedIndex] as const
+    }
+
+    // Otherwise, we need to push the initial entry with the current page
+    const entries = [...storedEntries.slice(0, storedIndex + 1), initialEvent]
+
+    return [entries, entries.length - 1] as const
+  })
+
+export const saveToStorage = (entries: readonly NavigationEvent[], index: number) =>
+  Effect.gen(function* ($) {
+    yield* $(setItem(TYPED_NAVIGATION_ENTRIES_KEY, JSON.stringify(entries)))
+    yield* $(setItem(TYPED_NAVIGATION_INDEX_KEY, JSON.stringify(index)))
+  })

package/src/util.ts

@@ -0,0 +1,20 @@
+import * as Effect from '@effect/io/Effect'
+import { pathJoin } from '@typed/path'
+
+import { DestinationKey } from './Navigation.js'
+
+export function getUrl(href: string, base: string, origin: string) {
+  const url = new URL(href, origin)
+
+  if (!url.pathname.startsWith(base)) {
+    url.pathname = pathJoin(base, url.pathname)
+  }
+
+  return url
+}
+
+export const createKey = Effect.randomWith((random) =>
+  Effect.map(random.nextIntBetween(0, Number.MAX_SAFE_INTEGER), (n) =>
+    DestinationKey(n.toString(36).slice(2, 10)),
+  ),
+)

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["src/**/*.test.ts"]
+}