@c9up/aurora 0.1.25 → 0.1.26

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.
Files changed (35) hide show
  1. package/README.md +92 -0
  2. package/dist/AuroraManager.d.ts +22 -1
  3. package/dist/AuroraManager.js +26 -0
  4. package/dist/browser.d.ts +7 -0
  5. package/dist/browser.js +49 -8
  6. package/dist/form.d.ts +19 -9
  7. package/dist/form.js +5 -2
  8. package/dist/http.d.ts +12 -0
  9. package/dist/http.js +51 -2
  10. package/dist/index.d.ts +1 -1
  11. package/dist/live.d.ts +1 -1
  12. package/dist/liveServer.d.ts +12 -0
  13. package/dist/liveServer.js +15 -1
  14. package/dist/relay.js +11 -1
  15. package/dist/route.js +9 -1
  16. package/dist/server/renderPage.d.ts +25 -0
  17. package/dist/server/renderPage.js +52 -13
  18. package/dist/server.d.ts +1 -1
  19. package/dist/services/main.js +9 -0
  20. package/dist/url.d.ts +7 -0
  21. package/dist/url.js +15 -3
  22. package/package.json +1 -1
  23. package/src/AuroraManager.ts +49 -0
  24. package/src/browser.ts +57 -8
  25. package/src/form.ts +20 -7
  26. package/src/http.ts +67 -2
  27. package/src/index.ts +1 -0
  28. package/src/live.ts +1 -0
  29. package/src/liveServer.ts +25 -2
  30. package/src/relay.ts +9 -1
  31. package/src/route.ts +10 -1
  32. package/src/server/renderPage.ts +100 -14
  33. package/src/server.ts +2 -0
  34. package/src/services/main.ts +9 -0
  35. package/src/url.ts +21 -3
package/src/route.ts CHANGED
@@ -72,10 +72,19 @@ const DEFAULT_SHELL = (body: string, entry: string): string =>
72
72
  </head>
73
73
  <body>
74
74
  <div id="aurora-root">${body}</div>
75
- <script type="module" src="${entry}"></script>
75
+ <script type="module" src="${escapeAttr(entry)}"></script>
76
76
  </body>
77
77
  </html>`;
78
78
 
79
+ function escapeAttr(value: string): string {
80
+ return value
81
+ .replace(/&/g, "&amp;")
82
+ .replace(/"/g, "&quot;")
83
+ .replace(/'/g, "&#39;")
84
+ .replace(/</g, "&lt;")
85
+ .replace(/>/g, "&gt;");
86
+ }
87
+
79
88
  /**
80
89
  * Build a Ream-compatible route handler that SSR-renders the given
81
90
  * factory and serves the full HTML document.
package/src/server/renderPage.ts CHANGED
@@ -23,10 +23,11 @@
23
23
  * </body>
24
24
  */
25
25
 
26
- import { setCookieStore } from "../browser.js";
26
+ import { AsyncLocalStorage } from "node:async_hooks";
27
+ import { setCookieStoreReader } from "../browser.js";
27
28
  import type { Pages } from "../Pages.js";
28
29
  import { renderToString } from "../ssr.js";
29
- import { setRouteManifest } from "../url.js";
30
+ import { setRouteManifestReader } from "../url.js";
30
31
 
31
32
  /**
32
33
  * Structural slice of the host framework's response. Same shape
@@ -70,6 +71,29 @@ export interface RenderPageOptions {
70
71
  * targets.
71
72
  */
72
73
  rootId?: string;
74
+ /**
75
+ * Root element tag for the SSR + hydrated tree. Defaults to `div`.
76
+ * Mirrors Inertia's root tag customization (`@inertia({ as: ... })`) while
77
+ * keeping aurora independent from a template engine.
78
+ */
79
+ rootTag?: string;
80
+ /**
81
+ * Optional class attribute on the root element. Mirrors
82
+ * `@inertia({ class: ... })`.
83
+ */
84
+ rootClass?: string;
85
+ /**
86
+ * Shared props merged into every page render before invoking the page factory.
87
+ * Use this for global data such as user, flash and validation errors. A
88
+ * function receives the current HTTP context and may be async, matching
89
+ * Adonis/Inertia's request middleware `share()` model.
90
+ */
91
+ shared?: SharedProps | SharedPropsResolver;
92
+ /**
93
+ * Asset/version marker serialized with the page payload. Apps can use this to
94
+ * detect stale client state when their frontend build changes.
95
+ */
96
+ assetsVersion?: string;
73
97
  /**
74
98
  * Named-route manifest (`name → path-pattern`) for the isomorphic
75
99
  * `urlFor()` helper — build it with Ream's `router.namedManifest()`. It is
@@ -92,11 +116,26 @@ export interface RenderPageOptions {
92
116
  cookies?: string[];
93
117
  }
94
118
 
119
+ export type SharedProps = Record<string, unknown>;
120
+ export type SharedPropsResolver = (
121
+ ctx: RenderHttpContext,
122
+ ) => SharedProps | Promise<SharedProps>;
123
+
95
124
  /** A request that can read a cookie by name — the structural slice we need. */
96
125
  interface CookieReadableRequest {
97
126
  cookie(name: string): string | null;
98
127
  }
99
128
 
129
+ interface RenderScope {
130
+ cookies: Record<string, string>;
131
+ routes: Record<string, string>;
132
+ }
133
+
134
+ const renderScope = new AsyncLocalStorage<RenderScope>();
135
+
136
+ setCookieStoreReader(() => renderScope.getStore()?.cookies);
137
+ setRouteManifestReader(() => renderScope.getStore()?.routes);
138
+
100
139
  function isCookieReadable(request: unknown): request is CookieReadableRequest {
101
140
  return (
102
141
  typeof request === "object" &&
@@ -127,21 +166,31 @@ export async function renderPage<P>(
127
166
  props: P,
128
167
  options: RenderPageOptions = {},
129
168
  ): Promise<void> {
130
- // Install the route manifest BEFORE rendering so a page calling `urlFor`
131
- // during SSR resolves against the same map the client will get.
132
- if (options.routes) setRouteManifest(options.routes);
133
-
134
- // Seed the request's UI cookies so the page reads the SAME state server-side
135
- // that the browser will after hydration. Set synchronously right before the
136
- // (synchronous) render — read cookie signals at the top of the page.
137
- setCookieStore(
138
- options.cookies ? readRequestCookies(ctx.request, options.cookies) : {},
169
+ const scope: RenderScope = {
170
+ cookies: options.cookies
171
+ ? readRequestCookies(ctx.request, options.cookies)
172
+ : {},
173
+ routes: options.routes ?? {},
174
+ };
175
+
176
+ return renderScope.run(scope, () =>
177
+ renderPageInScope(ctx, pages, name, props, options),
139
178
  );
179
+ }
140
180
 
181
+ async function renderPageInScope<P>(
182
+ ctx: RenderHttpContext,
183
+ pages: Pages,
184
+ name: string,
185
+ props: P,
186
+ options: RenderPageOptions,
187
+ ): Promise<void> {
141
188
  const factory = await pages.resolve(name);
189
+ const shared = await resolveSharedProps(ctx, options.shared);
190
+ const pageProps = mergeProps(shared, props);
142
191
  // The factory must be invoked the SAME way client-side for hydrate
143
192
  // to find matching slots — `Page(props)` is the contract.
144
- const tree = await factory(props as never);
193
+ const tree = await factory(pageProps as never);
145
194
  const body = renderToString(tree);
146
195
 
147
196
  const importmap = {
@@ -149,6 +198,8 @@ export async function renderPage<P>(
149
198
  ...options.importmap,
150
199
  };
151
200
  const rootId = options.rootId ?? "aurora-root";
201
+ const rootTag = normalizeRootTag(options.rootTag ?? "div");
202
+ const rootClass = options.rootClass;
152
203
  const lang = options.lang ?? "en";
153
204
  const pageUrl = pages.urlFor(name);
154
205
 
@@ -161,13 +212,14 @@ export async function renderPage<P>(
161
212
  ${options.headExtra ?? ""}
162
213
  </head>
163
214
  <body>
164
- <div id="${escapeAttr(rootId)}">${body}</div>
215
+ <${rootTag}${rootAttrs(rootId, rootClass)}>${body}</${rootTag}>
165
216
  <script id="aurora-page-data" type="application/json">${escapeJsonForScript({
166
217
  name,
167
- props,
218
+ props: pageProps,
168
219
  url: pageUrl,
169
220
  rootId,
170
221
  routes: options.routes ?? {},
222
+ version: options.assetsVersion ?? null,
171
223
  })}</script>
172
224
  <script type="module">
173
225
  import { hydrate, setRouteManifest } from '@c9up/aurora'
@@ -183,6 +235,40 @@ hydrate(document.getElementById(data.rootId), () => Page(data.props))
183
235
  ctx.response.send(doc);
184
236
  }
185
237
 
238
+ async function resolveSharedProps(
239
+ ctx: RenderHttpContext,
240
+ shared: RenderPageOptions["shared"],
241
+ ): Promise<SharedProps> {
242
+ if (!shared) return {};
243
+ return typeof shared === "function" ? shared(ctx) : shared;
244
+ }
245
+
246
+ function mergeProps<P>(shared: SharedProps, props: P): P | SharedProps {
247
+ if (Object.keys(shared).length === 0) return props;
248
+ if (isPlainRecord(props)) return { ...shared, ...props };
249
+ return { ...shared, page: props };
250
+ }
251
+
252
+ function isPlainRecord(value: unknown): value is Record<string, unknown> {
253
+ return (
254
+ typeof value === "object" &&
255
+ value !== null &&
256
+ !Array.isArray(value) &&
257
+ Object.getPrototypeOf(value) === Object.prototype
258
+ );
259
+ }
260
+
261
+ function normalizeRootTag(tag: string): string {
262
+ if (/^[a-z][a-z0-9-]*$/i.test(tag)) return tag.toLowerCase();
263
+ throw new Error(`[aurora] illegal root tag: ${JSON.stringify(tag)}`);
264
+ }
265
+
266
+ function rootAttrs(id: string, className: string | undefined): string {
267
+ const attrs = [`id="${escapeAttr(id)}"`];
268
+ if (className) attrs.push(`class="${escapeAttr(className)}"`);
269
+ return ` ${attrs.join(" ")}`;
270
+ }
271
+
186
272
  function escapeAttr(value: string): string {
187
273
  return value
188
274
  .replace(/&/g, "&amp;")
package/src/server.ts CHANGED
@@ -16,6 +16,8 @@ export {
16
16
  type RenderPageOptions,
17
17
  type RenderResponse,
18
18
  renderPage,
19
+ type SharedProps,
20
+ type SharedPropsResolver,
19
21
  } from "./server/renderPage.js";
20
22
  export {
21
23
  type AssetsHttpContext,
package/src/services/main.ts CHANGED
@@ -26,6 +26,15 @@ export function getAurora(): AuroraManager | undefined {
26
26
 
27
27
  const aurora: AuroraManager = new Proxy({} as AuroraManager, {
28
28
  get(_target, prop) {
29
+ // A module loader inspects what it imports before anyone uses it: it reads
30
+ // `then` to decide whether the namespace is thenable, and various symbols
31
+ // for interop and formatting. Throwing on those turns a plain
32
+ // `import { setX } from ".../services/main"` into a crash at import time,
33
+ // far from any real use. They are not members of what this stands in for,
34
+ // so answer undefined and let a genuine access be the one that reports.
35
+ if (typeof prop === "symbol" || prop === "then") {
36
+ return undefined;
37
+ }
29
38
  if (!instance) {
30
39
  throw new Error(
31
40
  "[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +
package/src/url.ts CHANGED
@@ -19,6 +19,23 @@
19
19
 
20
20
  let manifest: Record<string, string> = {};
21
21
 
22
+ type RouteManifestReader = () => Record<string, string> | undefined;
23
+ let routeManifestReader: RouteManifestReader | undefined;
24
+
25
+ /**
26
+ * @internal Server-side hook used by `renderPage()` to provide a request-scoped
27
+ * route manifest without importing Node built-ins from this browser-safe module.
28
+ */
29
+ export function setRouteManifestReader(
30
+ reader: RouteManifestReader | undefined,
31
+ ): void {
32
+ routeManifestReader = reader;
33
+ }
34
+
35
+ function activeManifest(): Record<string, string> {
36
+ return routeManifestReader?.() ?? manifest;
37
+ }
38
+
22
39
  /**
23
40
  * Install the `name → path-pattern` map `urlFor` resolves against (e.g.
24
41
  * `{ 'users.show': '/users/:id' }`, from Ream's `router.namedManifest()`).
@@ -31,7 +48,7 @@ export function setRouteManifest(routes: Record<string, string>): void {
31
48
 
32
49
  /** The currently-installed route manifest (mainly for tests/introspection). */
33
50
  export function getRouteManifest(): Record<string, string> {
34
- return { ...manifest };
51
+ return { ...activeManifest() };
35
52
  }
36
53
 
37
54
  /**
@@ -44,9 +61,10 @@ export function urlFor(
44
61
  params?: Record<string, string | number>,
45
62
  query?: Record<string, string | number>,
46
63
  ): string {
47
- const pattern = manifest[name];
64
+ const routes = activeManifest();
65
+ const pattern = routes[name];
48
66
  if (pattern === undefined) {
49
- const known = Object.keys(manifest);
67
+ const known = Object.keys(routes);
50
68
  throw new Error(
51
69
  `[aurora] urlFor: unknown route '${name}'. ${
52
70
  known.length > 0