@typed/navigation 0.5.4 → 0.6.0

package/src/Navigation.ts

@@ -1,192 +1,375 @@
-import * as Brand from '@effect/data/Brand'
-import { Option } from '@effect/data/Option'
-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'
-
+/**
+ * @since 1.0.0
+ */
+
+import { ParseResult } from "@effect/schema"
+import * as Schema from "@effect/schema/Schema"
+import { Tagged } from "@typed/context"
+import * as Computed from "@typed/fx/Computed"
+import type { Uuid } from "@typed/id"
+import * as IdSchema from "@typed/id/Schema"
+import type { Option, Scope } from "effect"
+import { Data, Effect } from "effect"
+
+/**
+ * @since 1.0.0
+ */
 export interface Navigation {
-  /**
-   * Base path for all navigation entries.
-   */
+  readonly origin: string
+
   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>>
-}
+  readonly currentEntry: Computed.Computed<never, never, Destination>
 
-export const Navigation = Context.Tag<Navigation>('Navigation')
+  readonly entries: Computed.Computed<never, never, ReadonlyArray<Destination>>
 
-export const navigate = (url: string, options?: NavigateOptions) =>
-  Navigation.withEffect((n) => n.navigate(url, options))
+  readonly transition: Computed.Computed<never, never, Option.Option<Transition>>
 
-export const onNavigation = <R>(
-  handler: (event: NavigationEvent) => Effect.Effect<R, never, void>,
-) => Navigation.withEffect((n) => n.onNavigation(handler))
+  readonly canGoBack: Computed.Computed<never, never, boolean>
 
-export const canGoBack: Effect.Effect<Navigation, never, boolean> &
-  Fx.Fx<Navigation, never, boolean> = Object.assign(
-  Navigation.withEffect((n) => n.canGoBack),
-  Navigation.withFx((n) => n.canGoBack),
-)
+  readonly canGoForward: Computed.Computed<never, never, boolean>
 
-export const back = Navigation.withEffect((n) => n.back)
+  readonly navigate: (
+    url: string | URL,
+    options?: NavigateOptions
+  ) => Effect.Effect<never, NavigationError, Destination>
 
-export const canGoForward: Effect.Effect<Navigation, never, boolean> &
-  Fx.Fx<Navigation, never, boolean> = Object.assign(
-  Navigation.withEffect((n) => n.canGoForward),
-  Navigation.withFx((n) => n.canGoForward),
-)
+  readonly back: (options?: { readonly info?: unknown }) => Effect.Effect<never, NavigationError, Destination>
 
-export const forward = Navigation.withEffect((n) => n.forward)
+  readonly forward: (options?: { readonly info?: unknown }) => Effect.Effect<never, NavigationError, Destination>
 
-export const reload = Navigation.withEffect((n) => n.reload)
+  readonly traverseTo: (
+    key: Destination["key"],
+    options?: { readonly info?: unknown }
+  ) => Effect.Effect<never, NavigationError, Destination>
 
-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
-}
+  readonly updateCurrentEntry: (
+    options: { readonly state: unknown }
+  ) => Effect.Effect<never, NavigationError, Destination>
 
-export interface NavigationEvent {
-  readonly destination: Destination
-  readonly hashChange: boolean
-  readonly navigationType: NavigationType
-}
+  readonly reload: (
+    options?: { readonly info?: unknown; readonly state?: unknown }
+  ) => Effect.Effect<never, NavigationError, Destination>
 
-export function NavigationEvent(
-  destination: Destination,
-  hashChange: boolean,
-  navigationType: NavigationType,
-): NavigationEvent {
-  return { destination, hashChange, navigationType }
-}
+  readonly beforeNavigation: <R = never, R2 = never>(
+    handler: BeforeNavigationHandler<R, R2>
+  ) => Effect.Effect<R | R2 | Scope.Scope, never, unknown>
 
-export interface Destination {
-  readonly key: DestinationKey
-  readonly url: URL
-  readonly state: unknown
+  readonly onNavigation: <R = never, R2 = never>(
+    handler: NavigationHandler<R, R2>
+  ) => Effect.Effect<R | R2 | Scope.Scope, never, unknown>
 }
 
-export type DestinationKey = string & Brand.Brand<'DestinationKey'>
-export const DestinationKey = Brand.nominal<DestinationKey>()
+/**
+ * @since 1.0.0
+ */
+export const Navigation: Tagged<Navigation> = Tagged<Navigation, Navigation>("@typed/navigation/Navigation")
+
+const urlSchema_ = Schema.instanceOf(URL).pipe(Schema.equivalence((a, b) => a.href === b.href))
+
+const urlSchema = Schema.string.pipe(
+  Schema.transformOrFail(
+    urlSchema_,
+    (s) =>
+      Effect.suspend(() => {
+        try {
+          return Effect.succeed(new URL(s))
+        } catch {
+          return Effect.fail(ParseResult.parseError([ParseResult.type(urlSchema_.ast, s, `Expected a URL`)]))
+        }
+      }),
+    (url) => Effect.succeed(url.toString())
+  )
+)
 
-export function Destination(key: DestinationKey, url: URL, state?: unknown): Destination {
-  return { key, url, state }
+/**
+ * @since 1.0.0
+ */
+export const Destination = Schema.struct({
+  id: IdSchema.uuid,
+  key: IdSchema.uuid,
+  url: urlSchema,
+  state: Schema.unknown,
+  sameDocument: Schema.boolean
+})
+
+/**
+ * @since 1.0.0
+ */
+export type DestinationJson = Schema.Schema.From<typeof Destination>
+/**
+ * @since 1.0.0
+ */
+export interface Destination extends Schema.Schema.To<typeof Destination> {}
+
+/**
+ * @since 1.0.0
+ */
+export const ProposedDestination = Destination.pipe(Schema.omit("id", "key"))
+
+/**
+ * @since 1.0.0
+ */
+export type ProposedDestinationJson = Schema.Schema.From<typeof ProposedDestination>
+/**
+ * @since 1.0.0
+ */
+export interface ProposedDestination extends Schema.Schema.To<typeof ProposedDestination> {}
+
+/**
+ * @since 1.0.0
+ */
+export const NavigationType = Schema.literal("push", "replace", "reload", "traverse")
+/**
+ * @since 1.0.0
+ */
+export type NavigationType = Schema.Schema.To<typeof NavigationType>
+
+/**
+ * @since 1.0.0
+ */
+export const Transition = Schema.struct({
+  type: NavigationType,
+  from: Destination,
+  to: Schema.union(ProposedDestination, Destination)
+})
+
+/**
+ * @since 1.0.0
+ */
+export type TransitionJson = Schema.Schema.From<typeof Transition>
+/**
+ * @since 1.0.0
+ */
+export interface Transition extends Schema.Schema.To<typeof Transition> {}
+
+/**
+ * @since 1.0.0
+ */
+export const BeforeNavigationEvent = Schema.struct({
+  type: NavigationType,
+  from: Destination,
+  delta: Schema.number,
+  to: Schema.union(ProposedDestination, Destination),
+  info: Schema.unknown
+})
+
+/**
+ * @since 1.0.0
+ */
+export type BeforeNavigationEventJson = Schema.Schema.From<typeof BeforeNavigationEvent>
+/**
+ * @since 1.0.0
+ */
+export interface BeforeNavigationEvent extends Schema.Schema.To<typeof BeforeNavigationEvent> {}
+
+/**
+ * @since 1.0.0
+ */
+export const NavigationEvent = Schema.struct({
+  type: NavigationType,
+  destination: Destination,
+  info: Schema.unknown
+})
+
+/**
+ * @since 1.0.0
+ */
+export type NavigationEventJson = Schema.Schema.From<typeof NavigationEvent>
+/**
+ * @since 1.0.0
+ */
+export interface NavigationEvent extends Schema.Schema.To<typeof NavigationEvent> {}
+
+/**
+ * @since 1.0.0
+ */
+export type BeforeNavigationHandler<R, R2> = (
+  event: BeforeNavigationEvent
+) => Effect.Effect<
+  R,
+  RedirectError | CancelNavigation,
+  Option.Option<
+    Effect.Effect<R2, RedirectError | CancelNavigation, unknown>
+  >
+>
+
+/**
+ * @since 1.0.0
+ */
+export type NavigationHandler<R, R2> = (
+  event: NavigationEvent
+) => Effect.Effect<
+  R,
+  never,
+  Option.Option<
+    Effect.Effect<R2, never, unknown>
+  >
+>
+
+/**
+ * @since 1.0.0
+ */
+export class NavigationError extends Data.TaggedError("NavigationError")<{ readonly error: unknown }> {}
+
+/**
+ * @since 1.0.0
+ */
+export class RedirectError extends Data.TaggedError("RedirectError")<
+  {
+    readonly path: string | URL
+    readonly options?: { readonly state?: unknown; readonly info?: unknown } | undefined
+  }
+> {}
+
+/**
+ * @since 1.0.0
+ */
+export class CancelNavigation extends Data.TaggedError("CancelNavigation")<{}> {}
+
+/**
+ * @since 1.0.0
+ */
+export interface NavigateOptions {
+  readonly history?: "replace" | "push" | "auto"
+  readonly state?: unknown
+  readonly info?: unknown
 }
 
-export enum NavigationType {
-  Push = 'push',
-  Reload = 'reload',
-  Replace = 'replace',
-  Back = 'back',
-  Forward = 'forward',
+/**
+ * @since 1.0.0
+ */
+export const cancelNavigation: CancelNavigation = new CancelNavigation()
+
+/**
+ * @since 1.0.0
+ */
+export function redirectToPath(
+  path: string | URL,
+  options?: { readonly state?: unknown; readonly info?: unknown }
+): RedirectError {
+  return new RedirectError({ path, options })
 }
 
-export type NavigationError = CancelNavigation | RedirectNavigation
-
-export interface CancelNavigation {
-  readonly _tag: 'CancelNavigation'
+/**
+ * @since 1.0.0
+ */
+export function isNavigationError(e: unknown): e is NavigationError {
+  return e instanceof NavigationError
 }
 
-export const cancelNavigation = Effect.fail<CancelNavigation>({ _tag: 'CancelNavigation' })
-
-export function isCancelNavigation(error: NavigationError): error is CancelNavigation {
-  return error._tag === 'CancelNavigation'
+/**
+ * @since 1.0.0
+ */
+export function isRedirectError(e: unknown): e is RedirectError {
+  return e instanceof RedirectError
 }
 
-export interface RedirectNavigation extends NavigateOptions {
-  readonly _tag: 'RedirectNavigation'
-  readonly url: string
+/**
+ * @since 1.0.0
+ */
+export function isCancelNavigation(e: unknown): e is CancelNavigation {
+  return e instanceof CancelNavigation
 }
 
-export const redirect = (
-  url: string,
-  options: NavigateOptions = {},
-): Effect.Effect<never, RedirectNavigation, never> =>
-  Effect.fail({ _tag: 'RedirectNavigation', url, ...options })
+/**
+ * @since 1.0.0
+ */
+export const navigate = (
+  url: string | URL,
+  options?: NavigateOptions
+): Effect.Effect<Navigation, NavigationError, Destination> => Navigation.withEffect((n) => n.navigate(url, options))
+
+/**
+ * @since 1.0.0
+ */
+export const back: (options?: { readonly info?: unknown }) => Effect.Effect<Navigation, NavigationError, Destination> =
+  (opts) => Navigation.withEffect((n) => n.back(opts))
+
+/**
+ * @since 1.0.0
+ */
+export const forward: (
+  options?: { readonly info?: unknown }
+) => Effect.Effect<Navigation, NavigationError, Destination> = (
+  opts
+) => Navigation.withEffect((n) => n.forward(opts))
+
+/**
+ * @since 1.0.0
+ */
+export const traverseTo: (
+  key: Uuid,
+  options?: { readonly info?: unknown }
+) => Effect.Effect<Navigation, NavigationError, Destination> = (key, opts) =>
+  Navigation.withEffect((n) => n.traverseTo(key, opts))
+
+/**
+ * @since 1.0.0
+ */
+export const updateCurrentEntry: (
+  options: { readonly state: unknown }
+) => Effect.Effect<Navigation, NavigationError, Destination> = (opts) =>
+  Navigation.withEffect((n) => n.updateCurrentEntry(opts))
+
+/**
+ * @since 1.0.0
+ */
+export const reload: (
+  options?: { readonly info?: unknown; readonly state?: unknown }
+) => Effect.Effect<Navigation, NavigationError, Destination> = (
+  opts
+) => Navigation.withEffect((n) => n.reload(opts))
+
+/**
+ * @since 1.0.0
+ */
+export const CurrentEntry: Computed.Computed<Navigation, never, Destination> = Computed.fromTag(
+  Navigation,
+  (nav) => nav.currentEntry
+)
 
-export function isRedirectNavigation(error: NavigationError): error is RedirectNavigation {
-  return error._tag === 'RedirectNavigation'
+/**
+ * @since 1.0.0
+ */
+export function getCurrentPathFromUrl(location: Pick<URL, "pathname" | "search" | "hash">): string {
+  return location.pathname + location.search + location.hash
 }
 
-export interface OnNavigationOptions {
-  readonly passive?: boolean
-}
+/**
+ * @since 1.0.0
+ */
+export const CurrentPath: Computed.Computed<Navigation, never, string> = CurrentEntry.map((d) =>
+  getCurrentPathFromUrl(d.url)
+)
+
+/**
+ * @since 1.0.0
+ */
+export const CurrentEntries: Computed.Computed<Navigation, never, ReadonlyArray<Destination>> = Computed.fromTag(
+  Navigation,
+  (n) => n.entries
+)
 
-export const getCurrentUrl: Effect.Effect<Navigation, never, URL> = Navigation.withEffect((n) =>
-  n.currentEntry.map((d) => d.url),
+/**
+ * @since 1.0.0
+ */
+export const CanGoForward: Computed.Computed<Navigation, never, boolean> = Computed.fromTag(
+  Navigation,
+  (n) => n.canGoForward
 )
+
+/**
+ * @since 1.0.0
+ */
+export const CanGoBack: Computed.Computed<Navigation, never, boolean> = Computed.fromTag(
+  Navigation,
+  (n) => n.canGoBack
+)
+
+/**
+ * @since 1.0.0
+ */
+export function handleRedirect(error: RedirectError) {
+  return navigate(error.path, error.options)
+}

package/src/index.ts

@@ -1,3 +1,17 @@
-export * from './Navigation.js'
-export * from './DOM.js'
-export * from './Memory.js'
+/**
+ * Re-exports of other modules
+ * @since 1.0.0
+ */
+
+/**
+ * @since 1.0.0
+ */
+export * from "./Blocking"
+/**
+ * @since 1.0.0
+ */
+export * from "./Layer"
+/**
+ * @since 1.0.0
+ */
+export * from "./Navigation"