mates-fullstack 1.0.0-beta.1

package/dist/redirect.d.ts

@@ -0,0 +1,84 @@
+/**
+ * mates-fullstack — redirect.ts
+ *
+ * The redirect() helper for server functions and loaders.
+ *
+ * Throwing redirect() from a server function:
+ *   - During RPC call  → client calls navigateTo(url) or window.location.href
+ *   - During SSR loader → server sends HTTP 302 before page renders
+ *
+ * Internal vs external detection happens on the client:
+ *   - Starts with http:// or https:// or // → window.location.href (full nav)
+ *   - Otherwise → navigateTo(url) (SPA navigation, no page reload)
+ *
+ * Wire format:
+ *   { __type: "Redirect", url: "/dashboard", status: 302 }
+ *   HTTP response status: 302 (or whatever status was passed)
+ */
+/**
+ * Thrown by redirect() to signal a navigation.
+ * Not a real Error — don't extend Error to keep the class hierarchy clean.
+ */
+export declare class Redirect {
+    readonly __type: "Redirect";
+    readonly url: string;
+    readonly status: 301 | 302 | 307 | 308;
+    constructor(url: string, status?: 301 | 302 | 307 | 308);
+}
+/**
+ * Throw this from any server function or loader to redirect the user.
+ *
+ * During a RPC call from the client:
+ *   - Internal URL (/dashboard) → navigateTo("/dashboard") — SPA navigation
+ *   - External URL (https://...) → window.location.href — full browser navigation
+ *
+ * During SSR (loader):
+ *   - Sends HTTP 302 (or specified status) before the page renders
+ *   - Browser follows the Location header
+ *
+ * @example
+ * // Redirect after login
+ * export async function login(payload, ctx) {
+ *   const user = await verify(payload);
+ *   ctx.cookie.set("session", createToken(user), { httpOnly: true });
+ *   throw redirect("/dashboard");
+ * }
+ *
+ * // Guard in SSR loader
+ * export async function loader(payload, ctx) {
+ *   if (!ctx.auth) throw redirect("/login");
+ * }
+ *
+ * // Redirect to external URL (OAuth, Stripe, etc.)
+ * throw redirect("https://accounts.google.com/oauth/...");
+ *
+ * // Permanent redirect
+ * throw redirect("/new-path", 301);
+ */
+export declare function redirect(url: string, status?: 301 | 302 | 307 | 308): never;
+/**
+ * Returns true if the value is a Redirect instance.
+ * Used by rpc-runner and renderer to catch redirect throws.
+ */
+export declare function isRedirect(value: unknown): value is Redirect;
+export interface SerializedRedirect {
+    __type: "Redirect";
+    url: string;
+    status: 301 | 302 | 307 | 308;
+}
+/**
+ * Serialize a Redirect for the wire.
+ */
+export declare function serializeRedirect(r: Redirect): SerializedRedirect;
+/**
+ * Returns true if the serialized object is a redirect response.
+ * Used by the Fetch client to detect redirect responses.
+ */
+export declare function isMatesRedirect(data: unknown): data is SerializedRedirect;
+/**
+ * Returns true if the URL is external (starts with http://, https://, or //).
+ * External redirects use window.location.href on the client.
+ * Internal redirects use navigateTo() for SPA navigation.
+ */
+export declare function isExternalUrl(url: string): boolean;
+//# sourceMappingURL=redirect.d.ts.map

package/dist/redirect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../src/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;GAGG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,MAAM,aAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;gBAE3B,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAS;CAI7D;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAS,GAClC,KAAK,CAEP;AAID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAID,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,GAAG,kBAAkB,CAMjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,kBAAkB,CAOzE;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMlD"}

package/dist/redirect.js

@@ -0,0 +1,105 @@
+/**
+ * mates-fullstack — redirect.ts
+ *
+ * The redirect() helper for server functions and loaders.
+ *
+ * Throwing redirect() from a server function:
+ *   - During RPC call  → client calls navigateTo(url) or window.location.href
+ *   - During SSR loader → server sends HTTP 302 before page renders
+ *
+ * Internal vs external detection happens on the client:
+ *   - Starts with http:// or https:// or // → window.location.href (full nav)
+ *   - Otherwise → navigateTo(url) (SPA navigation, no page reload)
+ *
+ * Wire format:
+ *   { __type: "Redirect", url: "/dashboard", status: 302 }
+ *   HTTP response status: 302 (or whatever status was passed)
+ */
+// ─── Redirect class ───────────────────────────────────────────────────────────
+/**
+ * Thrown by redirect() to signal a navigation.
+ * Not a real Error — don't extend Error to keep the class hierarchy clean.
+ */
+export class Redirect {
+    __type = "Redirect";
+    url;
+    status;
+    constructor(url, status = 302) {
+        this.url = url;
+        this.status = status;
+    }
+}
+// ─── redirect() helper ────────────────────────────────────────────────────────
+/**
+ * Throw this from any server function or loader to redirect the user.
+ *
+ * During a RPC call from the client:
+ *   - Internal URL (/dashboard) → navigateTo("/dashboard") — SPA navigation
+ *   - External URL (https://...) → window.location.href — full browser navigation
+ *
+ * During SSR (loader):
+ *   - Sends HTTP 302 (or specified status) before the page renders
+ *   - Browser follows the Location header
+ *
+ * @example
+ * // Redirect after login
+ * export async function login(payload, ctx) {
+ *   const user = await verify(payload);
+ *   ctx.cookie.set("session", createToken(user), { httpOnly: true });
+ *   throw redirect("/dashboard");
+ * }
+ *
+ * // Guard in SSR loader
+ * export async function loader(payload, ctx) {
+ *   if (!ctx.auth) throw redirect("/login");
+ * }
+ *
+ * // Redirect to external URL (OAuth, Stripe, etc.)
+ * throw redirect("https://accounts.google.com/oauth/...");
+ *
+ * // Permanent redirect
+ * throw redirect("/new-path", 301);
+ */
+export function redirect(url, status = 302) {
+    throw new Redirect(url, status);
+}
+// ─── Type guard ───────────────────────────────────────────────────────────────
+/**
+ * Returns true if the value is a Redirect instance.
+ * Used by rpc-runner and renderer to catch redirect throws.
+ */
+export function isRedirect(value) {
+    return value instanceof Redirect;
+}
+/**
+ * Serialize a Redirect for the wire.
+ */
+export function serializeRedirect(r) {
+    return {
+        __type: "Redirect",
+        url: r.url,
+        status: r.status,
+    };
+}
+/**
+ * Returns true if the serialized object is a redirect response.
+ * Used by the Fetch client to detect redirect responses.
+ */
+export function isMatesRedirect(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        data.__type === "Redirect" &&
+        typeof data.url === "string");
+}
+// ─── URL helpers ──────────────────────────────────────────────────────────────
+/**
+ * Returns true if the URL is external (starts with http://, https://, or //).
+ * External redirects use window.location.href on the client.
+ * Internal redirects use navigateTo() for SPA navigation.
+ */
+export function isExternalUrl(url) {
+    return (url.startsWith("http://") ||
+        url.startsWith("https://") ||
+        url.startsWith("//"));
+}
+//# sourceMappingURL=redirect.js.map

package/dist/redirect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.js","sourceRoot":"","sources":["../src/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,OAAO,QAAQ;IACV,MAAM,GAAG,UAAmB,CAAC;IAC7B,GAAG,CAAS;IACZ,MAAM,CAAwB;IAEvC,YAAY,GAAW,EAAE,SAAgC,GAAG;QAC1D,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,QAAQ,CACtB,GAAW,EACX,SAAgC,GAAG;IAEnC,MAAM,IAAI,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,YAAY,QAAQ,CAAC;AACnC,CAAC;AAUD;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAW;IAC3C,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,MAAM,EAAE,CAAC,CAAC,MAAM;KACjB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACZ,IAAY,CAAC,MAAM,KAAK,UAAU;QACnC,OAAQ,IAAY,CAAC,GAAG,KAAK,QAAQ,CACtC,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,CACL,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;QACzB,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC;QAC1B,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CACrB,CAAC;AACJ,CAAC"}

package/dist/renderer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * mates-ssr — renderer.ts
+ *
+ * The SSR render pipeline. Takes a Mates Component function, runs it through
+ * the custom TemplateResult serializer (ssrTemplate), and returns clean HTML.
+ *
+ * No happy-dom. No DOM. No per-request global patching. Fully concurrent.
+ *
+ * Design decisions:
+ *   - SSR globals (installSsrGlobals) are installed ONCE at boot — no per-request
+ *     Window creation, no global swapping.
+ *   - Requests are fully concurrent — no render queue. ssrTemplate is a pure
+ *     function that walks TemplateResult data structures directly.
+ *   - Async work (onMount, asyncAction) is tracked via the global SSR async
+ *     counter and per-host queues. The render loop drains and re-serializes.
+ *   - CSS-in-JS styles are collected after render via collectSSRStyles().
+ *   - pathAtom is set before each render via explicit .set() call.
+ *   - Components run inside withHost(fakeHost, ...) on the server. No custom
+ *     element is created — hooks get a fake host object that satisfies their
+ *     getCurrentHost() calls.
+ */
+/** A standard Mates Component function: (propsFn) => () => TemplateResult */
+export type ComponentFn = (propsFn: () => Record<string, any>) => () => any;
+export declare const DEFAULT_SSR_TIMEOUT_MS = 10000;
+export interface RenderOptions {
+    /** URL pathname for this request, e.g. "/users". */
+    pathname: string;
+    /** Props to pass to the root component. */
+    props?: Record<string, any>;
+    /** Optional layout component to wrap the app. */
+    layout?: ComponentFn | null;
+    /** Maximum time to wait for SSR async work before failing. */
+    ssrTimeoutMs?: number;
+}
+export interface RenderResult {
+    /** Clean HTML string — ready to inject into the page shell. */
+    html: string;
+    /** SSR styles collected from stylesheet() / globalCSS() calls. */
+    styles: string;
+}
+/**
+ * Render the app from a file path.
+ * Imports client/App.ts (or .js), renders it with pathAtom set to pathname.
+ * This is the main SSR entry point — called once per incoming GET request.
+ *
+ * The app's Router() reads pathAtom and renders the correct page.
+ * No file-based routing on the server — the SPA router IS the server router.
+ */
+export declare function renderApp(appFile: string, pathname: string, dev: boolean, ssrTimeoutMs?: number): Promise<RenderResult & {
+    notFound?: boolean;
+}>;
+/**
+ * Must be called once at server startup, before any route handler runs.
+ * Initialises the boot window and imports lit-html + mates into module cache.
+ *
+ * @param matesPath  Absolute path to the mates ESM dist file, e.g.
+ *   "/project/node_modules/mates/dist/index.esm.js"
+ *   When provided, mates is imported from this exact path so that the module
+ *   instance (and its internal host stack) is shared with the page files.
+ *   When omitted, we attempt a bare `import("mates")` which may resolve to a
+ *   different instance — withHost/getCurrentHost will not share state with
+ *   page files in that case and hooks will not work on the server.
+ */
+export declare function bootRenderer(matesPath?: string): Promise<void>;
+/**
+ * Returns the CSS string collected from all stylesheet() and globalCSS()
+ * Tear down the boot window. Call this when the server is shutting down.
+ */
+export declare function shutdownRenderer(): void;
+/**
+ * Returns the CSS string collected from all stylesheet() and globalCSS()
+ * instances after bootRenderer() completed. Inject this into the HTML <head>
+ * as `<style id="mates-ssr-styles">` to prevent FOUC on first paint.
+ */
+export declare function getSSRStyles(): string;
+/**
+ * Render a Mates Component to an HTML string.
+ *
+ * Enqueues the render so that globals are never mutated concurrently.
+ * Resolves with a clean HTML string (lit-html comment markers stripped).
+ *
+ * @example
+ * const { html } = await renderToString(MyPage, { pathname: '/about', props: {} });
+ */
+export declare function renderToString(component: ComponentFn, options: RenderOptions): Promise<RenderResult>;
+/**
+ * Register a callback to be called on every render completion.
+ * Used by devtools / HMR.
+ */
+export declare function onRenderComplete(cb: () => void): void;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAYH,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,MAAM,GAAG,CAAC;AAE5E,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,iDAAiD;IACjD,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,OAAO,EACZ,YAAY,SAAyB,GACpC,OAAO,CAAC,YAAY,GAAG;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAQhD;AAcD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+DpE;AAgCD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CASvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAErD"}