Memory Location Hook
Relevant source files
The following files were used as context for generating this wiki page:
The Memory Location Hook is a specialized routing utility in wouter-vue designed for non-browser environments or scenarios where URL persistence in the browser's address bar is not desired. It manages routing state entirely in-memory, making it ideal for Server-Side Rendering (SSR), unit testing, or embedded widgets within a larger application.
This system provides a reactive hook that mimics the behavior of standard browser navigation but stores the history and current path within internal data structures. It leverages Vue's reactivity system (ref and watchEffect) to ensure that components respond immediately to state changes.
Sources: src/memory-location.ts:1-25, README.md:40-55
Architecture and Core Logic
The memory location system is built around a factory function, memoryLocation, which initializes a private state and returns several hooks and navigation utilities. It uses the mitt library for internal event emission to decouple the state management from the Vue-specific reactive hooks.
State Management Flow
The following diagram illustrates how the memoryLocation function initializes state and facilitates updates through navigation.
Configuration Options
The memoryLocation function accepts a MemoryLocationOptions object to define its behavior:
| Option | Type | Default | Description |
|---|---|---|---|
path | string | '/' | The initial path for the memory router. |
searchPath | string | '' | Initial query string parameters. |
static | boolean | false | If true, navigation calls are ignored (useful for SSR). |
record | boolean | undefined | If true, maintains a history array and enables the reset function. |
Sources: src/memory-location.ts:7-16, src/memory-location.ts:27-33
Key Hooks and Utilities
The factory function returns an object containing hooks and methods to interact with the memory-based routing state.
useMemoryLocation (hook)
This is the primary Vue hook. It returns a tuple containing a reactive Ref<string> of the current path and a NavigateFn. It uses watchEffect to synchronize the internal state with the Vue ref whenever the internal emitter fires a 'navigate' event.
Sources: src/memory-location.ts:72-89, test/composables.test.ts:9-30
useMemoryQuery (searchHook)
A specialized hook for managing the query string portion of the URL. It functions similarly to useMemoryLocation but focuses exclusively on the currentSearch state.
Sources: src/memory-location.ts:92-109
Navigation and History
- navigate: A function to change the current path. It supports a
replaceoption which, ifrecordis enabled, replaces the last entry in the history instead of pushing a new one. - history: An array of strings representing the navigation history. This is only populated if the
recordoption is set totrue. - reset: A function that clears the history and returns the state to the
initialPath.
Testing and Implementation Examples
The memoryLocation utility is frequently used in the wouter-vue test suite to simulate navigation without a browser environment.
Unit Testing Example
Testing components often involves providing a custom hook to the <Router /> component to control the environment.
// From test/composables.test.ts
const { hook, navigate } = memoryLocation({ path: '/initial' });
const wrapper = mount(Router, {
props: { hook },
slots: {
default: () => h(TestComponent),
},
});
// Programmatic navigation in tests
navigate('/new-path');
await flushPromises();
expect(locationRef.value).toBe('/new-path');
Sources: test/composables.test.ts:11-35, test/memory-location.test.ts:9-30
Conclusion
The Memory Location Hook provides a robust, platform-agnostic alternative to browser-based routing. By encapsulating state within a closure and exposing reactive Vue hooks, it allows wouter-vue to maintain high performance and consistent API behavior across client-side, server-side, and testing environments.
Sources: package.json:2-10, README.md:10-25