@typed/navigation 0.1.0

package/src/Memory.ts

@@ -0,0 +1,102 @@
+import { pipe } from '@effect/data/Function'
+import * as Option from '@effect/data/Option'
+import * as Cause from '@effect/io/Cause'
+import * as Effect from '@effect/io/Effect'
+import * as Layer from '@effect/io/Layer'
+
+import type { DomNavigationOptions } from './DOM.js'
+import {
+  Destination,
+  Navigation,
+  NavigationError,
+  NavigationEvent,
+  NavigationType,
+} from './Navigation.js'
+import { makeIntent } from './memory-intent.js'
+import { Model, makeModel } from './model.js'
+import { createKey } from './util.js'
+
+export interface MemoryNavigationOptions extends DomNavigationOptions {
+  readonly initialUrl: URL
+  readonly initialState?: unknown
+  readonly base?: string
+}
+
+export function memory(options: MemoryNavigationOptions): Layer.Layer<never, never, Navigation> {
+  return Navigation.layerScoped(
+    Effect.gen(function* ($) {
+      const initial: Destination = {
+        key: options.initialKey ?? (yield* $(createKey)),
+        url: options.initialUrl,
+        state: options.initialState,
+      }
+      const initialEvent: NavigationEvent = {
+        destination: initial,
+        hashChange: false,
+        navigationType: NavigationType.Push,
+      }
+
+      const model: Model = yield* $(makeModel([initialEvent], 0))
+      const intent = makeIntent(model, options)
+
+      // Used to ensure ordering of navigation events
+      const lock = Effect.unsafeMakeSemaphore(1).withPermits(1)
+
+      const handleNavigationError =
+        (depth: number) =>
+        (
+          error: NavigationError | Cause.NoSuchElementException,
+        ): Effect.Effect<never, never, Destination> =>
+          Effect.gen(function* ($) {
+            if (depth >= 50) {
+              throw new Error(
+                'Too many redirects. You may have an infinite loop of onNavigation handlers that are redirecting.',
+              )
+            }
+
+            switch (error._tag) {
+              case 'NoSuchElementException':
+              case 'CancelNavigation':
+                return yield* $(model.currentEntry.get)
+              case 'RedirectNavigation':
+                return yield* $(
+                  Effect.catchAll(
+                    intent.navigate(error.url, error),
+                    handleNavigationError(depth + 1),
+                  ),
+                )
+            }
+          })
+
+      const catchNavigationError = <R, A>(
+        effect: Effect.Effect<R, NavigationError | Cause.NoSuchElementException, A>,
+      ) => Effect.catchAll(effect, handleNavigationError(0))
+
+      // Construct our service
+      const navigation: Navigation = {
+        back: lock(catchNavigationError(intent.back)),
+        base: '/',
+        canGoBack: model.canGoBack,
+        canGoForward: model.canGoForward,
+        currentEntry: model.currentEntry,
+        entries: model.entries,
+        forward: lock(catchNavigationError(intent.forward)),
+        goTo: (n) =>
+          pipe(
+            n,
+            intent.goTo,
+            Effect.catchAll((a) => pipe(a, handleNavigationError(0), Effect.map(Option.some))),
+            lock,
+          ),
+        navigate: (url, options) => pipe( intent.navigate(url, options), catchNavigationError, lock),
+        onNavigation: (handler, options) =>
+          pipe(intent.onNavigation(handler, options), catchNavigationError, Effect.asUnit),
+        onNavigationEnd: (handler, options) =>
+          Effect.asUnit(intent.onNavigationEnd(handler, options)),
+        reload: lock(catchNavigationError(intent.reload)),
+      }
+
+      return navigation
+    }),
+  )
+}

package/src/Navigation.ts

@@ -0,0 +1,192 @@
+import * as Brand from '@effect/data/Brand'
+import { 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 * as Context from '@typed/context'
+import * as Fx from '@typed/fx'
+
+export interface Navigation {
+  /**
+   * Base path for all navigation entries.
+   */
+  readonly base: string
+
+  /**
+   * The list of navigation entries that are currently kept in-memory and
+   * saved within Local/Session Storage.
+   */
+  readonly entries: Fx.Computed<never, never, readonly Destination[]>
+
+  /**
+   * The currently focused navigation entry.
+   */
+  readonly currentEntry: Fx.Computed<never, never, Destination>
+
+  /**
+   * Navigate to a new URL. NavigateOptions can be used to control how the
+   * navigation is handled via history.pushState or history.replaceState,
+   * set/update the state of the navigation entry, or provide a key to use
+   * for the navigation entry.
+   */
+  readonly navigate: (
+    url: string,
+    options?: NavigateOptions,
+  ) => Effect.Effect<never, never, Destination>
+
+  /**
+   * Subscribe to navigation events. Any handler can cancel the or redirect
+   * the navigation by failing with a CancelNavigation or RedirectNavigation
+   * error.
+   */
+  readonly onNavigation: <R>(
+    handler: (event: NavigationEvent) => Effect.Effect<R, NavigationError, void>,
+    options?: OnNavigationOptions,
+  ) => Effect.Effect<R | Scope.Scope, never, void>
+
+  /**
+   * Subscribe to navigation events after they have been commited.
+   */
+  readonly onNavigationEnd: <R>(
+    handler: (event: NavigationEvent) => Effect.Effect<R, never, void>,
+    options?: OnNavigationOptions,
+  ) => Effect.Effect<R | Scope.Scope, never, void>
+
+  /**
+   * Returns true if there is a previous navigation entry to navigate to.
+   */
+  readonly canGoBack: Fx.Computed<never, never, boolean>
+
+  /**
+   * Navigate to the previous navigation entry. If you're on the first entry
+   * then this will do nothing.
+   */
+  readonly back: Effect.Effect<never, never, Destination>
+
+  /**
+   * Returns true if there is a next navigation entry to navigate to after you have gone back.
+   */
+  readonly canGoForward: Fx.Computed<never, never, boolean>
+
+  /**
+   * Navigate to the next navigation entry. If you're on the last entry then
+   * this will do nothing.
+   */
+  readonly forward: Effect.Effect<never, never, Destination>
+
+  /**
+   * Reload the current navigation entry.
+   */
+  readonly reload: Effect.Effect<never, never, Destination>
+
+  /**
+   * Navigate to a specific navigation entry by key. If the key does not
+   * exist then this will do nothing visible to the user and return Option.none().
+   */
+  readonly goTo: (key: DestinationKey) => Effect.Effect<never, never, Option<Destination>>
+}
+
+export const Navigation = Context.Tag<Navigation>('Navigation')
+
+export const navigate = (url: string, options?: NavigateOptions) =>
+  Navigation.withEffect((n) => n.navigate(url, options))
+
+export const onNavigation = <R>(
+  handler: (event: NavigationEvent) => Effect.Effect<R, never, void>,
+) => Navigation.withEffect((n) => n.onNavigation(handler))
+
+export const canGoBack: Effect.Effect<Navigation, Cause.NoSuchElementException, boolean> &
+  Fx.Fx<Navigation, never, boolean> = Object.assign(
+  Navigation.withEffect((n) => n.canGoBack),
+  Navigation.withFx((n) => n.canGoBack),
+)
+
+export const back = Navigation.withEffect((n) => n.back)
+
+export const canGoForward: Effect.Effect<Navigation, Cause.NoSuchElementException, boolean> &
+  Fx.Fx<Navigation, never, boolean> = Object.assign(
+  Navigation.withEffect((n) => n.canGoForward),
+  Navigation.withFx((n) => n.canGoForward),
+)
+
+export const forward = Navigation.withEffect((n) => n.forward)
+
+export const reload = Navigation.withEffect((n) => n.reload)
+
+export interface NavigateOptions {
+  // State to save to history
+  readonly state?: unknown
+  // History type
+  readonly history?: 'push' | 'replace'
+  // Key to use for Navigation entry
+  readonly key?: string
+}
+
+export interface NavigationEvent {
+  readonly destination: Destination
+  readonly hashChange: boolean
+  readonly navigationType: NavigationType
+}
+
+export function NavigationEvent(
+  destination: Destination,
+  hashChange: boolean,
+  navigationType: NavigationType,
+): NavigationEvent {
+  return { destination, hashChange, navigationType }
+}
+
+export interface Destination {
+  readonly key: DestinationKey
+  readonly url: URL
+  readonly state: unknown
+}
+
+export type DestinationKey = string & Brand.Brand<'DestinationKey'>
+export const DestinationKey = Brand.nominal<DestinationKey>()
+
+export function Destination(key: DestinationKey, url: URL, state?: unknown): Destination {
+  return { key, url, state }
+}
+
+export enum NavigationType {
+  Push = 'push',
+  Reload = 'reload',
+  Replace = 'replace',
+  Back = 'back',
+  Forward = 'forward',
+}
+
+export type NavigationError = CancelNavigation | RedirectNavigation
+
+export interface CancelNavigation {
+  readonly _tag: 'CancelNavigation'
+}
+
+export const cancelNavigation = Effect.fail<CancelNavigation>({ _tag: 'CancelNavigation' })
+
+export function isCancelNavigation(error: NavigationError): error is CancelNavigation {
+  return error._tag === 'CancelNavigation'
+}
+
+export interface RedirectNavigation extends NavigateOptions {
+  readonly _tag: 'RedirectNavigation'
+  readonly url: string
+}
+
+export const redirect = (
+  url: string,
+  options: NavigateOptions = {},
+): Effect.Effect<never, RedirectNavigation, never> =>
+  Effect.fail({ _tag: 'RedirectNavigation', url, ...options })
+
+export function isRedirectNavigation(error: NavigationError): error is RedirectNavigation {
+  return error._tag === 'RedirectNavigation'
+}
+
+export interface OnNavigationOptions {
+  readonly passive?: boolean
+}
+
+export const getCurrentUrl: Effect.Effect<Navigation, Cause.NoSuchElementException, URL> =
+  Navigation.withEffect((n) => n.currentEntry.map((d) => d.url))

package/src/_makeServerWindow.ts

@@ -0,0 +1,28 @@
+import type { Window, GlobalThis } from '@typed/dom'
+import * as happyDom from 'happy-dom'
+
+export interface ServerWindowOptions {
+  readonly url: string
+
+  readonly innerWidth?: number
+  readonly innerHeight?: number
+  readonly settings?: {
+    readonly disableJavaScriptEvaluation: boolean
+    readonly disableJavaScriptFileLoading: boolean
+    readonly disableCSSFileLoading: boolean
+    readonly enableFileSystemHttpRequests: boolean
+  }
+}
+
+export function makeServerWindow(
+  options?: ServerWindowOptions,
+): Window & GlobalThis & Pick<InstanceType<typeof happyDom.Window>, 'happyDOM'> {
+  const win: Window & GlobalThis & Pick<InstanceType<typeof happyDom.Window>, 'happyDOM'> =
+    new happyDom.Window({
+      ...options,
+    }) as any
+
+  return win
+}
+
+export const html5Doctype = '<!DOCTYPE html>'

package/src/constant.ts

@@ -0,0 +1,5 @@
+import * as Global from '@effect/data/Global'
+
+const id = '@typed/navigation/ServiceId'
+
+export const ServiceId: any = Global.globalValue(id, () => Symbol.for(id))

package/src/dom-intent.ts

@@ -0,0 +1,276 @@
+import { Option } from '@effect/data/Option'
+import * as Cause from '@effect/io/Cause'
+import * as Effect from '@effect/io/Effect'
+import { History, Location } from '@typed/dom'
+
+import type { DomNavigationOptions } from './DOM.js'
+import {
+  Destination,
+  NavigateOptions,
+  NavigationError,
+  NavigationEvent,
+  NavigationType,
+} from './Navigation.js'
+import { ServiceId } from './constant.js'
+import { encodeEvent } from './json.js'
+import { Model } from './model.js'
+import {
+  Notify,
+  NotifyEnd,
+  Save,
+  makeGoTo,
+  makeNotify,
+  makeNotifyEnd,
+  makeOnNavigation,
+  makeOnNavigationEnd,
+} from './shared-intent.js'
+import { saveToStorage } from './storage.js'
+import { createKey, getUrl } from './util.js'
+
+// Roughly the number of History entries in a browser anyways
+const DEFAULT_MAX_ENTRIES = 50
+
+export type DomIntent = {
+  readonly back: (skipHistory: boolean) => ReturnType<ReturnType<typeof makeGo>>
+
+  readonly forward: (skipHistory: boolean) => 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<
+    Storage | History,
+    Cause.NoSuchElementException | NavigationError,
+    Option<Destination>
+  >
+
+  readonly reload: ReturnType<typeof makeReload>
+
+  readonly onNavigation: ReturnType<typeof makeOnNavigation>
+
+  readonly onNavigationEnd: ReturnType<typeof makeOnNavigationEnd>
+}
+
+export const makeIntent = (
+  model: Model,
+  base: string,
+  options: DomNavigationOptions,
+): DomIntent => {
+  const maxEntries = Math.abs(options.maxEntries ?? DEFAULT_MAX_ENTRIES)
+  const notify = makeNotify(model)
+  const notifyEnd = makeNotifyEnd(model)
+  const save = makeSave(model)
+  const go = makeGo(model, notify, notifyEnd, save)
+  const replace = makeReplace(model, notify, notifyEnd, save, base)
+  const push = makePush(model, notify, notifyEnd, save, base, maxEntries)
+
+  return {
+    back: (skipHistory: boolean) => go(-1, skipHistory),
+    forward: (skipHistory: boolean) => go(1, skipHistory),
+    push,
+    replace,
+    navigate: (url: string, options: NavigateOptions = {}) =>
+      options.history === 'replace' ? replace(url, options) : push(url, options),
+    notify,
+    go: go,
+    goTo: makeGoTo(model, go),
+    reload: makeReload(model, notify, save),
+    onNavigation: makeOnNavigation(model),
+    onNavigationEnd: makeOnNavigationEnd(model),
+  } as const
+}
+
+export type Intent = ReturnType<typeof makeIntent>
+
+export const makeSave =
+  (model: Model) =>
+  (event: NavigationEvent): Effect.Effect<Storage, Cause.NoSuchElementException, void> =>
+    Effect.gen(function* ($) {
+      const events = yield* $(model.events)
+      const index = yield* $(model.index)
+
+      // Save to storage
+      yield* $(saveToStorage(events, 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<Storage>) =>
+  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))
+
+    const location = yield* $(Location)
+
+    location.reload()
+
+    return event.destination
+  })
+
+export const makeReplace =
+  (model: Model, notify: Notify, notifyEnd: NotifyEnd, save: Save<Storage>, base: string) =>
+  (url: string, options: NavigateOptions = {}, skipHistory = false) =>
+    Effect.gen(function* ($) {
+      const location = yield* $(Location)
+      const entry = yield* $(model.currentEntry.get)
+      const destination: Destination = {
+        key: entry.key,
+        url: getUrl(url, base, location.origin),
+        state: options.state,
+      }
+      const event: NavigationEvent = {
+        destination,
+        hashChange: entry.url.hash !== destination.url.hash,
+        navigationType: NavigationType.Replace,
+      }
+
+      yield* $(notify(event))
+
+      if (!skipHistory) {
+        const history = yield* $(History)
+
+        history.replaceState.call(
+          ServiceId,
+          { state: options.state, event: encodeEvent(event) },
+          '',
+          url,
+        )
+      }
+
+      const currentIndex = yield* $(model.index)
+
+      yield* $(
+        model.events.update((entries) => {
+          const updated = entries.slice(0)
+          updated[currentIndex] = event
+          return updated
+        }),
+      )
+
+      yield* $(save(event))
+      yield* $(notifyEnd(event))
+
+      return destination
+    })
+
+export const makePush =
+  (
+    model: Model,
+    notify: Notify,
+    notifyEnd: NotifyEnd,
+    save: Save<Storage>,
+    base: string,
+    maxEntries: number,
+  ) =>
+  (url: string, options: NavigateOptions = {}, skipHistory = false) =>
+    Effect.gen(function* ($) {
+      const location = yield* $(Location)
+      const entry = yield* $(model.currentEntry.get)
+      const destination: Destination = {
+        key: yield* $(createKey),
+        url: getUrl(url, base, location.origin),
+        state: options.state,
+      }
+      const event: NavigationEvent = {
+        destination,
+        hashChange: entry.url.hash !== destination.url.hash,
+        navigationType: NavigationType.Push,
+      }
+
+      // Notify event handlers
+      yield* $(notify(event))
+
+      if (!skipHistory) {
+        const history = yield* $(History)
+
+        history.pushState.call(
+          ServiceId,
+          { state: options.state, event: encodeEvent(event) },
+          '',
+          url,
+        )
+      }
+
+      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))
+      yield* $(notifyEnd(event))
+
+      return destination
+    })
+
+export const makeGo =
+  (model: Model, notify: Notify, notifyEnd: NotifyEnd, save: Save<Storage>) =>
+  (delta: number, skipHistory = false) =>
+    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,
+        }),
+      )
+
+      if (!skipHistory) {
+        const history = yield* $(History)
+
+        history.go.call(ServiceId, delta)
+      }
+
+      yield* $(model.index.set(nextIndex))
+
+      yield* $(save(nextEntry))
+
+      yield* $(notifyEnd(nextEntry))
+
+      return nextEntry.destination
+    })