@oomfware/stacker 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,14 @@
1
+ BSD Zero Clause License
2
+
3
+ Copyright (c) 2026 Mary
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted.
7
+
8
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
9
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
11
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
13
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14
+ PERFORMANCE OF THIS SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,286 @@
1
+ # @oomfware/stacker
2
+
3
+ type-safe stack router for React.
4
+
5
+ ```sh
6
+ npm install @oomfware/stacker
7
+ ```
8
+
9
+ ## usage
10
+
11
+ ```tsx
12
+ import {
13
+ defineRoutes,
14
+ layout,
15
+ Link,
16
+ NavigationHistory,
17
+ Outlet,
18
+ route,
19
+ Router,
20
+ RouterView,
21
+ string,
22
+ } from '@oomfware/stacker';
23
+
24
+ const AppShell = () => (
25
+ <main>
26
+ <nav>
27
+ <Link to="/">home</Link>
28
+ <Link to="/profile/alice">alice</Link>
29
+ </nav>
30
+ <Outlet />
31
+ </main>
32
+ );
33
+
34
+ const Home = () => <h1>home</h1>;
35
+ const Profile = () => <h1>profile</h1>;
36
+
37
+ const routes = defineRoutes({
38
+ app: layout({
39
+ component: AppShell,
40
+ children: {
41
+ Home: route({ component: Home, path: '/' }),
42
+ Profile: route({
43
+ component: Profile,
44
+ params: { actor: string() },
45
+ path: '/profile/:actor',
46
+ }),
47
+ },
48
+ }),
49
+ });
50
+
51
+ const router = new Router({ history: new NavigationHistory(), routes });
52
+
53
+ export const App = () => <RouterView router={router} />;
54
+ ```
55
+
56
+ ### defining routes
57
+
58
+ define routes using a nested tree of `layout` and `route` nodes. leaf names must be unique across
59
+ the tree:
60
+
61
+ ```ts
62
+ import { defineRoutes, layout, route, string } from '@oomfware/stacker';
63
+
64
+ const routes = defineRoutes({
65
+ app: layout({
66
+ component: AppShell,
67
+ children: {
68
+ Home: route({ component: Home, path: '/' }),
69
+ Profile: route({
70
+ component: Profile,
71
+ params: { actor: string() },
72
+ query: { tab: optional(string()) },
73
+ path: '/profile/:actor',
74
+ }),
75
+ Settings: route({ component: Settings, path: '/settings' }),
76
+ },
77
+ }),
78
+ });
79
+ ```
80
+
81
+ configure `type` to control page instance lifetimes:
82
+
83
+ ```ts
84
+ // page (default): new instance and state per history entry
85
+ route({ component: Profile, path: '/profile/:actor', type: 'page' });
86
+
87
+ // singleton: one instance per distinct parameter set
88
+ route({ component: Home, path: '/', type: 'singleton' });
89
+ ```
90
+
91
+ ### parameters
92
+
93
+ declare path and query parameters using codecs. types are inferred automatically:
94
+
95
+ ```ts
96
+ import { boolean, enumOf, integer, optional, route, string, withDefault } from '@oomfware/stacker';
97
+
98
+ route({
99
+ component: SearchPage,
100
+ path: '/search/:tag',
101
+ params: { tag: string() },
102
+ query: {
103
+ page: withDefault(integer(), 1),
104
+ sort: withDefault(enumOf(['new', 'top']), 'new'),
105
+ unread: optional(boolean()),
106
+ },
107
+ });
108
+ ```
109
+
110
+ path parameters are always required. query parameters without a default or optional codec must be
111
+ present in the URL to match the route.
112
+
113
+ write custom codecs by defining `decode` and `encode` methods:
114
+
115
+ ```ts
116
+ import type { Codec } from '@oomfware/stacker';
117
+
118
+ const date: Codec<Date> = {
119
+ decode: (raw) => {
120
+ const ms = Date.parse(raw);
121
+ return Number.isNaN(ms) ? undefined : new Date(ms);
122
+ },
123
+ encode: (value) => value.toISOString(),
124
+ };
125
+ ```
126
+
127
+ `defineRoutes` throws at load time if codecs do not match the `:params` declared in the path.
128
+
129
+ ### navigating
130
+
131
+ use `<Link>` to route in-app:
132
+
133
+ ```tsx
134
+ <Link to="/profile/alice">alice</Link>
135
+ <Link to="/settings" replace>settings</Link>
136
+ ```
137
+
138
+ plain `<a>` elements also route in-app automatically under `NavigationHistory`.
139
+
140
+ drive the router imperatively using either URLs or type-safe route names and parameters:
141
+
142
+ ```ts
143
+ // string-based navigation
144
+ router.push('/profile/alice');
145
+ router.replace('/profile/alice');
146
+
147
+ // name-based navigation (type-checked)
148
+ router.navigate('Profile', { actor: 'alice' });
149
+ router.build('Profile', { actor: 'alice' }); // -> "/profile/alice"
150
+
151
+ // history manipulation
152
+ router.popTo('Messages');
153
+ router.setParams({ tab: 'media' });
154
+ router.back();
155
+ ```
156
+
157
+ `setParams` replaces the current history entry, preserving scroll and focus. undeclared query keys
158
+ are ignored.
159
+
160
+ ### hooks
161
+
162
+ generate type-safe hooks bound to your route configuration using `createRouterHooks`:
163
+
164
+ ```tsx
165
+ import { createRouterHooks } from '@oomfware/stacker';
166
+
167
+ const { useNavigate, useParams } = createRouterHooks(routes);
168
+
169
+ const Profile = () => {
170
+ const [{ actor }, setParams] = useParams('Profile');
171
+ const navigate = useNavigate();
172
+
173
+ return (
174
+ <>
175
+ <h1>@{actor}</h1>
176
+ <button onClick={() => setParams({ tab: 'media' })}>media</button>
177
+ <button onClick={() => navigate('Settings')}>settings</button>
178
+ </>
179
+ );
180
+ };
181
+ ```
182
+
183
+ the package also exports registry-free hooks (`useLocation`, `useRoute`, `useRouter`) for components
184
+ that do not need type-safe route definitions.
185
+
186
+ ### keeping screens alive
187
+
188
+ backward entries stay mounted behind the active screen. control memory usage and pinning behavior
189
+ during router setup:
190
+
191
+ ```ts
192
+ const router = new Router({
193
+ history: new NavigationHistory(),
194
+ routes,
195
+ max: 5, // keep up to 5 backward entries mounted; older ones are evicted
196
+ pins: ["Home"], // keep specified singleton routes mounted indefinitely once visited
197
+ notFound: NotFound,
198
+ defaultFallback: <Spinner />,
199
+ });
200
+ ```
201
+
202
+ use `router.dispose()` to detach the router from history when it is no longer needed.
203
+
204
+ ### focus-aware effects
205
+
206
+ use focus hooks for work that should run when the screen becomes active, rather than when it mounts:
207
+
208
+ ```tsx
209
+ import { useCallback } from 'react';
210
+ import { useFocusEffect, useIsFocused } from '@oomfware/stacker';
211
+
212
+ const Profile = () => {
213
+ const [{ actor }] = useParams('Profile');
214
+
215
+ useFocusEffect(
216
+ useCallback(() => {
217
+ document.title = `@${actor}`;
218
+ }, [actor]),
219
+ );
220
+
221
+ const focused = useIsFocused();
222
+ return <VideoPlayer paused={!focused} />;
223
+ };
224
+ ```
225
+
226
+ `useFocusEffect` relies on reference identity; wrap the callback in `useCallback` to prevent it from
227
+ re-running on every render.
228
+
229
+ ### server-owned URLs
230
+
231
+ exclude specific paths from in-app routing to let the browser handle them:
232
+
233
+ ```ts
234
+ new NavigationHistory({
235
+ ignore: (url) => url.pathname.startsWith('/oauth/'),
236
+ });
237
+ ```
238
+
239
+ ### metadata
240
+
241
+ declare custom route metadata using module augmentation:
242
+
243
+ ```ts
244
+ import { layout, resolveMeta } from '@oomfware/stacker';
245
+
246
+ declare module '@oomfware/stacker' {
247
+ interface RouteMeta {
248
+ readonly requireAuth?: boolean;
249
+ }
250
+ }
251
+
252
+ layout({
253
+ component: AdminShell,
254
+ meta: { requireAuth: true },
255
+ children: {/* ... */},
256
+ });
257
+
258
+ // resolves metadata walking from leaf to root
259
+ resolveMeta(router.route, 'requireAuth');
260
+ ```
261
+
262
+ ### conditional matching
263
+
264
+ use `when` to conditionally reject matches based on custom logic, such as feature flags or query
265
+ parameters:
266
+
267
+ ```ts
268
+ route({
269
+ component: Beta,
270
+ path: '/feed',
271
+ when: ({ rawSearch }) => rawSearch.has('beta'),
272
+ });
273
+ ```
274
+
275
+ ### testing
276
+
277
+ use `MemoryHistory` to test routing behavior in environments without a DOM:
278
+
279
+ ```ts
280
+ import { MemoryHistory } from '@oomfware/stacker/testing';
281
+
282
+ const router = new Router({
283
+ history: new MemoryHistory({ initialEntries: ['/', '/profile/alice'] }),
284
+ routes,
285
+ });
286
+ ```