{ "id": "@typed/navigation/Navigation#Navigation", "canonicalId": "@typed/navigation#Navigation", "symbol": { "id": "@typed/navigation/Navigation#Navigation", "packageName": "@typed/navigation", "moduleName": "Navigation", "exportName": "Navigation", "kind": "class", "signatures": [ "export declare class Navigation extends Navigation_base {\n static readonly origin: Effect.Effect;\n static readonly base: Effect.Effect;\n static readonly currentEntry: RefSubject.Computed<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, never, Navigation>;\n static readonly entries: RefSubject.Computed;\n static readonly transition: RefSubject.Filtered<{\n readonly type: \"push\" | \"replace\" | \"reload\" | \"traverse\";\n readonly from: {\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n };\n readonly to: {\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n readonly key?: string | undefined;\n };\n readonly info?: unknown;\n }, never, Navigation>;\n static readonly canGoBack: RefSubject.Computed;\n static readonly canGoForward: RefSubject.Computed;\n static navigate(url: string | URL, options: NavigationNavigateOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static navigate(url: string | URL, options?: NavigationNavigateOptions): Effect.Effect;\n static readonly back: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly forward: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly traverseTo: (key: Destination[\"key\"], options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: unknown;\n }): Effect.Effect;\n static reload(options: NavigationReloadOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static reload(options?: NavigationReloadOptions): Effect.Effect;\n static readonly onBeforeNavigation: (handler: BeforeNavigationHandler) => Effect.Effect;\n static readonly onNavigation: (handler: NavigationHandler) => Effect.Effect;\n}" ], "summary": "Provides backend-neutral reactive navigation state and Effectful history operations.", "sections": { "Why": "Routers, renderers, and application code can depend on one service whether history comes from a\nbrowser, SSR memory, or a test. Current entry, entries, and transition are RefSubjects so state\nremains renderer-independent.", "Ownership and lifetime": "A provider Layer owns the service, its backend listeners, reactive state, and handler registry.\nHandler registration requires a Scope and unregisters through that scope's finalizer. Each\nnavigation Effect publishes a transition, runs before handlers sequentially, commits, clears the\ntransition, and then runs post-commit handlers. Interruption follows Effect's scoped cleanup.", "Property: back": "Traverses to the preceding retained entry when one exists.", "Property: back: Why": "Bounds behavior stays provider-neutral and preserves the destination's key, id, and state.", "Property: back: Ownership and lifetime": "The provider computes the preceding index and owns the resulting traversal transition. At the\nlower bound it returns the current Destination without creating backend work.", "Property: base": "The structural base path exposed by the active provider.", "Property: base: Why": "Routers can establish a stable mount root separately from the changing current URL.", "Property: base: Ownership and lifetime": "`Navigation.base` reads the active service synchronously; the provider owns the stored string for its Layer lifetime.", "Property: canGoBack": "Whether the retained history contains a preceding entry.", "Property: canGoBack: Why": "Callers can disable back actions without duplicating provider bounds logic.", "Property: canGoBack: Ownership and lifetime": "`Navigation.canGoBack` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: canGoForward": "Whether the retained history contains a following entry.", "Property: canGoForward: Why": "Callers can disable forward actions after pushes truncate the forward branch.", "Property: canGoForward: Ownership and lifetime": "`Navigation.canGoForward` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: currentEntry": "The reactive committed destination at the active history index.", "Property: currentEntry: Why": "Readers observe committed history. A before-navigation decision can still cancel or redirect\nthe separate proposed transition without changing this value. A committed destination does\nnot imply that the selected page has finished loading data or mounting its DOM.", "Property: currentEntry: Ownership and lifetime": "`Navigation.currentEntry` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: entries": "The reactive retained history entries in traversal order.", "Property: entries: Why": "Back, forward, and keyed traversal need an explicit bounded history model in every provider.", "Property: entries: Ownership and lifetime": "`Navigation.entries` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: forward": "Traverses to the following retained entry when one exists.", "Property: forward: Why": "Bounds behavior stays provider-neutral and preserves forward-history identity.", "Property: forward: Ownership and lifetime": "The provider computes the following index and owns the resulting traversal transition. At the\nupper bound it returns the current Destination without creating backend work.", "Method: navigate": "Starts a push or replacement transition to a URL.", "Method: navigate: Why": "All backends use the same ordered guard, redirect, commit, and post-commit protocol.", "Method: navigate: Ownership and lifetime": "The provider owns the proposed transition until it commits, redirects, cancels, fails, or is\ninterrupted. Once its backend mutation commits, later interruption cannot undo that mutation.", "Property: onBeforeNavigation": "Registers a scoped pre-commit navigation handler.", "Property: onBeforeNavigation: Why": "Handlers can allow, redirect, or cancel before the backend mutates history.", "Property: onBeforeNavigation: Ownership and lifetime": "Registration captures the current Effect context and requires Scope. Closing that Scope unregisters the handler and releases retained references.", "Property: onNavigation": "Registers a scoped post-commit navigation handler.", "Property: onNavigation: Why": "Follow-up synchronization runs only after history and current-entry state agree.", "Property: onNavigation: Ownership and lifetime": "Registration captures the current Effect context and requires Scope. Closing that Scope unregisters the handler and releases retained references.", "Property: origin": "The absolute origin used to resolve relative destinations.", "Property: origin: Why": "A single origin makes same-document classification and URL normalization consistent across providers.", "Property: origin: Ownership and lifetime": "`Navigation.origin` reads the active service synchronously; the provider owns the stored string for its Layer lifetime.", "Method: reload": "Reloads the current destination through the active backend.", "Method: reload: Why": "Reload behavior remains explicit without pretending it is a push or keyed traversal.", "Method: reload: Ownership and lifetime": "The active provider owns reload work and decides whether the platform can remain in-process.\nBrowser reload may leave the current JavaScript lifetime once the History API action commits.", "Property: transition": "The reactive transition while navigation is pending.", "Property: transition: Why": "Renderers can show pending work without treating a proposal as the committed destination.", "Property: transition: Ownership and lifetime": "`Navigation.transition` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.\n\nUse `transition.asComputed()` when pending UI must observe `Option.none()` as the transition\nends. The Filtered observation itself emits only present transitions, so it cannot signal\nabsence by publishing another Transition. Reading it while absent has the usual Filtered\n`NoSuchElementError` behavior.", "Property: traverseTo": "Traverses to a retained entry by stable key.", "Property: traverseTo: Why": "A key addresses history identity even when several entries share the same URL.", "Property: traverseTo: Ownership and lifetime": "The provider owns keyed lookup and the resulting backend traversal. The current key is a no-op;\nan unknown key fails with `NavigationError` before any backend commit.", "Method: updateCurrentEntry": "Replaces application state on the current committed entry.", "Method: updateCurrentEntry: Why": "State updates should not create a new navigation position or remount the selected route.", "Method: updateCurrentEntry: Ownership and lifetime": "The provider owns the replacement transition and retains the supplied state only if it commits.\nThe existing Destination key and history position remain current." }, "examples": [ { "language": "text", "code": "```ts\nimport { Navigation } from \"@typed/navigation/Navigation\"\nimport * as Effect from \"effect/Effect\"\n\nconst goToAccount = Navigation.navigate(\"/account\", { history: \"push\" })\nconst current = Navigation.currentEntry\n```\n\nEffect service and Scope concepts follow the Effect v4 model documented at\nhttps://effect.website/docs/requirements-management/services/ and\nhttps://effect.website/docs/resource-management/scope/." } ], "relations": [], "source": { "file": "packages/navigation/src/Navigation.ts", "line": 188 }, "since": "1.0.0", "category": "Navigation service" }, "exposure": { "recordKind": "declaration", "id": "@typed/navigation/Navigation#Navigation", "packageName": "@typed/navigation", "packageVersion": "1.0.0-beta.13", "moduleName": "Navigation", "consumerSpecifier": "@typed/navigation/Navigation", "exportName": "Navigation", "qualifiedName": "Navigation", "declarationKey": "declaration:d2d1aad032e574462f87ae0e", "family": "class", "signatures": [ "export declare class Navigation extends Navigation_base {\n static readonly origin: Effect.Effect;\n static readonly base: Effect.Effect;\n static readonly currentEntry: RefSubject.Computed<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, never, Navigation>;\n static readonly entries: RefSubject.Computed;\n static readonly transition: RefSubject.Filtered<{\n readonly type: \"push\" | \"replace\" | \"reload\" | \"traverse\";\n readonly from: {\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n };\n readonly to: {\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n readonly key?: string | undefined;\n };\n readonly info?: unknown;\n }, never, Navigation>;\n static readonly canGoBack: RefSubject.Computed;\n static readonly canGoForward: RefSubject.Computed;\n static navigate(url: string | URL, options: NavigationNavigateOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static navigate(url: string | URL, options?: NavigationNavigateOptions): Effect.Effect;\n static readonly back: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly forward: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly traverseTo: (key: Destination[\"key\"], options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: unknown;\n }): Effect.Effect;\n static reload(options: NavigationReloadOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static reload(options?: NavigationReloadOptions): Effect.Effect;\n static readonly onBeforeNavigation: (handler: BeforeNavigationHandler) => Effect.Effect;\n static readonly onNavigation: (handler: NavigationHandler) => Effect.Effect;\n}" ], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 188, "column": 1 }, "end": { "line": 495, "column": 2 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 381, "column": 3 }, "end": { "line": 382, "column": 44 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 253, "column": 3 }, "end": { "line": 253, "column": 60 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 321, "column": 3 }, "end": { "line": 323, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 337, "column": 3 }, "end": { "line": 339, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 270, "column": 3 }, "end": { "line": 272, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 286, "column": 3 }, "end": { "line": 286, "column": 98 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 397, "column": 3 }, "end": { "line": 398, "column": 47 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 355, "column": 3 }, "end": { "line": 358, "column": 70 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 359, "column": 3 }, "end": { "line": 362, "column": 62 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 477, "column": 3 }, "end": { "line": 479, "column": 61 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 493, "column": 3 }, "end": { "line": 494, "column": 52 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 239, "column": 3 }, "end": { "line": 239, "column": 64 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 454, "column": 3 }, "end": { "line": 456, "column": 70 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 457, "column": 3 }, "end": { "line": 459, "column": 62 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 305, "column": 3 }, "end": { "line": 307, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 413, "column": 3 }, "end": { "line": 414, "column": 55 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 430, "column": 3 }, "end": { "line": 432, "column": 71 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 433, "column": 3 }, "end": { "line": 435, "column": 63 } } ], "aliases": [ "@typed/navigation#Navigation" ], "isAlias": false, "static": false }, "declaration": { "declarationKey": "declaration:d2d1aad032e574462f87ae0e", "name": "Navigation", "family": "class", "facets": [ { "family": "class", "syntaxKind": "ClassDeclaration", "signatures": [ "export declare class Navigation extends Navigation_base {\n static readonly origin: Effect.Effect;\n static readonly base: Effect.Effect;\n static readonly currentEntry: RefSubject.Computed<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, never, Navigation>;\n static readonly entries: RefSubject.Computed;\n static readonly transition: RefSubject.Filtered<{\n readonly type: \"push\" | \"replace\" | \"reload\" | \"traverse\";\n readonly from: {\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n };\n readonly to: {\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n readonly key?: string | undefined;\n };\n readonly info?: unknown;\n }, never, Navigation>;\n static readonly canGoBack: RefSubject.Computed;\n static readonly canGoForward: RefSubject.Computed;\n static navigate(url: string | URL, options: NavigationNavigateOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static navigate(url: string | URL, options?: NavigationNavigateOptions): Effect.Effect;\n static readonly back: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly forward: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly traverseTo: (key: Destination[\"key\"], options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: unknown;\n }): Effect.Effect;\n static reload(options: NavigationReloadOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static reload(options?: NavigationReloadOptions): Effect.Effect;\n static readonly onBeforeNavigation: (handler: BeforeNavigationHandler) => Effect.Effect;\n static readonly onNavigation: (handler: NavigationHandler) => Effect.Effect;\n}" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 188, "column": 1 }, "end": { "line": 495, "column": 2 } } ], "static": false, "readonly": false, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly back: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n}, NavigationError, Navigation>;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 381, "column": 3 }, "end": { "line": 382, "column": 44 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly base: Effect.Effect;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 253, "column": 3 }, "end": { "line": 253, "column": 60 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly canGoBack: RefSubject.Computed;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 321, "column": 3 }, "end": { "line": 323, "column": 5 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly canGoForward: RefSubject.Computed;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 337, "column": 3 }, "end": { "line": 339, "column": 5 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly currentEntry: RefSubject.Computed<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n}, never, Navigation>;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 270, "column": 3 }, "end": { "line": 272, "column": 5 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly entries: RefSubject.Computed;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 286, "column": 3 }, "end": { "line": 286, "column": 98 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly forward: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n}, NavigationError, Navigation>;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 397, "column": 3 }, "end": { "line": 398, "column": 47 } } ], "static": true, "readonly": true, "optional": false }, { "family": "method", "syntaxKind": "MethodDeclaration", "signatures": [ "static navigate(url: string | URL, options: NavigationNavigateOptions & {\n readonly state: S;\n}): Effect.Effect, NavigationError, Navigation>;", "static navigate(url: string | URL, options?: NavigationNavigateOptions): Effect.Effect;" ], "typeParameters": [ "S" ], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 355, "column": 3 }, "end": { "line": 358, "column": 70 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 359, "column": 3 }, "end": { "line": 362, "column": 62 } } ], "static": true, "readonly": false, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly onBeforeNavigation: (handler: BeforeNavigationHandler) => Effect.Effect;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 477, "column": 3 }, "end": { "line": 479, "column": 61 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly onNavigation: (handler: NavigationHandler) => Effect.Effect;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 493, "column": 3 }, "end": { "line": 494, "column": 52 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly origin: Effect.Effect;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 239, "column": 3 }, "end": { "line": 239, "column": 64 } } ], "static": true, "readonly": true, "optional": false }, { "family": "method", "syntaxKind": "MethodDeclaration", "signatures": [ "static reload(options: NavigationReloadOptions & {\n readonly state: S;\n}): Effect.Effect, NavigationError, Navigation>;", "static reload(options?: NavigationReloadOptions): Effect.Effect;" ], "typeParameters": [ "S" ], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 454, "column": 3 }, "end": { "line": 456, "column": 70 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 457, "column": 3 }, "end": { "line": 459, "column": 62 } } ], "static": true, "readonly": false, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly transition: RefSubject.Filtered<{\n readonly type: \"push\" | \"replace\" | \"reload\" | \"traverse\";\n readonly from: {\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n };\n readonly to: {\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n readonly key?: string | undefined;\n };\n readonly info?: unknown;\n}, never, Navigation>;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 305, "column": 3 }, "end": { "line": 307, "column": 5 } } ], "static": true, "readonly": true, "optional": false }, { "family": "property", "syntaxKind": "PropertyDeclaration", "signatures": [ "static readonly traverseTo: (key: Destination[\"key\"], options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n}, NavigationError, Navigation>;" ], "typeParameters": [], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 413, "column": 3 }, "end": { "line": 414, "column": 55 } } ], "static": true, "readonly": true, "optional": false }, { "family": "method", "syntaxKind": "MethodDeclaration", "signatures": [ "static updateCurrentEntry(options: {\n readonly state: S;\n}): Effect.Effect, NavigationError, Navigation>;", "static updateCurrentEntry(options: {\n readonly state: unknown;\n}): Effect.Effect;" ], "typeParameters": [ "S" ], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 430, "column": 3 }, "end": { "line": 432, "column": 71 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 433, "column": 3 }, "end": { "line": 435, "column": 63 } } ], "static": true, "readonly": false, "optional": false } ], "signatures": [ "export declare class Navigation extends Navigation_base {\n static readonly origin: Effect.Effect;\n static readonly base: Effect.Effect;\n static readonly currentEntry: RefSubject.Computed<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, never, Navigation>;\n static readonly entries: RefSubject.Computed;\n static readonly transition: RefSubject.Filtered<{\n readonly type: \"push\" | \"replace\" | \"reload\" | \"traverse\";\n readonly from: {\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n };\n readonly to: {\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n readonly key?: string | undefined;\n };\n readonly info?: unknown;\n }, never, Navigation>;\n static readonly canGoBack: RefSubject.Computed;\n static readonly canGoForward: RefSubject.Computed;\n static navigate(url: string | URL, options: NavigationNavigateOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static navigate(url: string | URL, options?: NavigationNavigateOptions): Effect.Effect;\n static readonly back: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly forward: (options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static readonly traverseTo: (key: Destination[\"key\"], options?: NavigationInfoOptions) => Effect.Effect<{\n readonly id: string;\n readonly key: string;\n readonly url: URL;\n readonly state: unknown;\n readonly sameDocument: boolean;\n }, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static updateCurrentEntry(options: {\n readonly state: unknown;\n }): Effect.Effect;\n static reload(options: NavigationReloadOptions & {\n readonly state: S;\n }): Effect.Effect, NavigationError, Navigation>;\n static reload(options?: NavigationReloadOptions): Effect.Effect;\n static readonly onBeforeNavigation: (handler: BeforeNavigationHandler) => Effect.Effect;\n static readonly onNavigation: (handler: NavigationHandler) => Effect.Effect;\n}" ], "typeParameters": [ "S" ], "summary": "Provides backend-neutral reactive navigation state and Effectful history operations.", "sections": { "Why": "Routers, renderers, and application code can depend on one service whether history comes from a\nbrowser, SSR memory, or a test. Current entry, entries, and transition are RefSubjects so state\nremains renderer-independent.", "Ownership and lifetime": "A provider Layer owns the service, its backend listeners, reactive state, and handler registry.\nHandler registration requires a Scope and unregisters through that scope's finalizer. Each\nnavigation Effect publishes a transition, runs before handlers sequentially, commits, clears the\ntransition, and then runs post-commit handlers. Interruption follows Effect's scoped cleanup.", "Property: back": "Traverses to the preceding retained entry when one exists.", "Property: back: Why": "Bounds behavior stays provider-neutral and preserves the destination's key, id, and state.", "Property: back: Ownership and lifetime": "The provider computes the preceding index and owns the resulting traversal transition. At the\nlower bound it returns the current Destination without creating backend work.", "Property: base": "The structural base path exposed by the active provider.", "Property: base: Why": "Routers can establish a stable mount root separately from the changing current URL.", "Property: base: Ownership and lifetime": "`Navigation.base` reads the active service synchronously; the provider owns the stored string for its Layer lifetime.", "Property: canGoBack": "Whether the retained history contains a preceding entry.", "Property: canGoBack: Why": "Callers can disable back actions without duplicating provider bounds logic.", "Property: canGoBack: Ownership and lifetime": "`Navigation.canGoBack` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: canGoForward": "Whether the retained history contains a following entry.", "Property: canGoForward: Why": "Callers can disable forward actions after pushes truncate the forward branch.", "Property: canGoForward: Ownership and lifetime": "`Navigation.canGoForward` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: currentEntry": "The reactive committed destination at the active history index.", "Property: currentEntry: Why": "Readers observe committed history. A before-navigation decision can still cancel or redirect\nthe separate proposed transition without changing this value. A committed destination does\nnot imply that the selected page has finished loading data or mounting its DOM.", "Property: currentEntry: Ownership and lifetime": "`Navigation.currentEntry` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: entries": "The reactive retained history entries in traversal order.", "Property: entries: Why": "Back, forward, and keyed traversal need an explicit bounded history model in every provider.", "Property: entries: Ownership and lifetime": "`Navigation.entries` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.", "Property: forward": "Traverses to the following retained entry when one exists.", "Property: forward: Why": "Bounds behavior stays provider-neutral and preserves forward-history identity.", "Property: forward: Ownership and lifetime": "The provider computes the following index and owns the resulting traversal transition. At the\nupper bound it returns the current Destination without creating backend work.", "Method: navigate": "Starts a push or replacement transition to a URL.", "Method: navigate: Why": "All backends use the same ordered guard, redirect, commit, and post-commit protocol.", "Method: navigate: Ownership and lifetime": "The provider owns the proposed transition until it commits, redirects, cancels, fails, or is\ninterrupted. Once its backend mutation commits, later interruption cannot undo that mutation.", "Property: onBeforeNavigation": "Registers a scoped pre-commit navigation handler.", "Property: onBeforeNavigation: Why": "Handlers can allow, redirect, or cancel before the backend mutates history.", "Property: onBeforeNavigation: Ownership and lifetime": "Registration captures the current Effect context and requires Scope. Closing that Scope unregisters the handler and releases retained references.", "Property: onNavigation": "Registers a scoped post-commit navigation handler.", "Property: onNavigation: Why": "Follow-up synchronization runs only after history and current-entry state agree.", "Property: onNavigation: Ownership and lifetime": "Registration captures the current Effect context and requires Scope. Closing that Scope unregisters the handler and releases retained references.", "Property: origin": "The absolute origin used to resolve relative destinations.", "Property: origin: Why": "A single origin makes same-document classification and URL normalization consistent across providers.", "Property: origin: Ownership and lifetime": "`Navigation.origin` reads the active service synchronously; the provider owns the stored string for its Layer lifetime.", "Method: reload": "Reloads the current destination through the active backend.", "Method: reload: Why": "Reload behavior remains explicit without pretending it is a push or keyed traversal.", "Method: reload: Ownership and lifetime": "The active provider owns reload work and decides whether the platform can remain in-process.\nBrowser reload may leave the current JavaScript lifetime once the History API action commits.", "Property: transition": "The reactive transition while navigation is pending.", "Property: transition: Why": "Renderers can show pending work without treating a proposal as the committed destination.", "Property: transition: Ownership and lifetime": "`Navigation.transition` is a provider-backed RefSubject view. The provider owns its state; each consumer Scope owns and releases its observation.\n\nUse `transition.asComputed()` when pending UI must observe `Option.none()` as the transition\nends. The Filtered observation itself emits only present transitions, so it cannot signal\nabsence by publishing another Transition. Reading it while absent has the usual Filtered\n`NoSuchElementError` behavior.", "Property: traverseTo": "Traverses to a retained entry by stable key.", "Property: traverseTo: Why": "A key addresses history identity even when several entries share the same URL.", "Property: traverseTo: Ownership and lifetime": "The provider owns keyed lookup and the resulting backend traversal. The current key is a no-op;\nan unknown key fails with `NavigationError` before any backend commit.", "Method: updateCurrentEntry": "Replaces application state on the current committed entry.", "Method: updateCurrentEntry: Why": "State updates should not create a new navigation position or remount the selected route.", "Method: updateCurrentEntry: Ownership and lifetime": "The provider owns the replacement transition and retains the supplied state only if it commits.\nThe existing Destination key and history position remain current." }, "examples": [ { "language": "text", "code": "```ts\nimport { Navigation } from \"@typed/navigation/Navigation\"\nimport * as Effect from \"effect/Effect\"\n\nconst goToAccount = Navigation.navigate(\"/account\", { history: \"push\" })\nconst current = Navigation.currentEntry\n```\n\nEffect service and Scope concepts follow the Effect v4 model documented at\nhttps://effect.website/docs/requirements-management/services/ and\nhttps://effect.website/docs/resource-management/scope/." } ], "sourceSpans": [ { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 188, "column": 1 }, "end": { "line": 495, "column": 2 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 381, "column": 3 }, "end": { "line": 382, "column": 44 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 253, "column": 3 }, "end": { "line": 253, "column": 60 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 321, "column": 3 }, "end": { "line": 323, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 337, "column": 3 }, "end": { "line": 339, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 270, "column": 3 }, "end": { "line": 272, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 286, "column": 3 }, "end": { "line": 286, "column": 98 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 397, "column": 3 }, "end": { "line": 398, "column": 47 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 355, "column": 3 }, "end": { "line": 358, "column": 70 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 359, "column": 3 }, "end": { "line": 362, "column": 62 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 477, "column": 3 }, "end": { "line": 479, "column": 61 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 493, "column": 3 }, "end": { "line": 494, "column": 52 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 239, "column": 3 }, "end": { "line": 239, "column": 64 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 454, "column": 3 }, "end": { "line": 456, "column": 70 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 457, "column": 3 }, "end": { "line": 459, "column": 62 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 305, "column": 3 }, "end": { "line": 307, "column": 5 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 413, "column": 3 }, "end": { "line": 414, "column": 55 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 430, "column": 3 }, "end": { "line": 432, "column": 71 } }, { "file": "packages/navigation/src/Navigation.ts", "start": { "line": 433, "column": 3 }, "end": { "line": 435, "column": 63 } } ], "since": "1.0.0", "category": "Navigation service" } }