@gracile/engine 0.8.2 → 0.9.0-next.11

package/dist/server/adapters/node.js

@@ -82,7 +82,7 @@ export function nodeAdapter(handler, options) {
                 return response.end(result.body);
             if (result.response.body) {
                 const piped = await result.response.body
-                    .pipeTo(Writable.toWeb(response))
+                    .pipeTo(Writable.toWeb(response) /* NOTE: Minor typing mismatch (node:stream/web vs. TS global) */)
                     .catch((error) => logger.error(String(error)));
                 return piped;
             }
@@ -109,5 +109,5 @@ export function nodeAdapter(handler, options) {
 export function getClientBuildPath(root) {
     return fileURLToPath(new URL(constants.CLIENT_DIST_DIR, root));
 }
-export { printUrls } from '../utils.js';
+export { printUrls } from '../utilities.js';
 export {} from '../request.js';

package/dist/server/request-pipeline.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure, testable pipeline steps extracted from the request handler.
+ *
+ * Each function here is a focused stage of the Gracile request lifecycle.
+ * They are composed by `createGracileHandler` in `./request.ts`.
+ *
+ * @internal
+ */
+import { Readable } from 'node:stream';
+import type { Logger, ViteDevServer } from 'vite';
+import { renderRouteTemplate } from '../render/route-template.js';
+import type { RouteInfos } from '../routes/match.js';
+import type { GracileConfig } from '../user-config.js';
+export type StandardResponse = {
+    response: Response;
+    body?: never;
+    init?: never;
+};
+export type ResponseWithNodeReadable = {
+    response?: never;
+    body: Readable;
+    init: ResponseInit;
+};
+export type HandlerResult = StandardResponse | ResponseWithNodeReadable | null;
+export declare const CONTENT_TYPE_HTML: {
+    readonly 'Content-Type': "text/html";
+};
+export declare const PREMISE_REGEXES: {
+    readonly properties: RegExp;
+    readonly document: RegExp;
+};
+/** Describes which premises endpoint was requested, if any. */
+export interface PremisesDescriptor {
+    propertiesOnly: boolean;
+    documentOnly: boolean;
+}
+/**
+ * Strip the `/__…` suffix so hidden-sibling URLs (premises) resolve to
+ * the parent route.
+ *
+ * @example
+ * rewriteHiddenRoutes('http://localhost/blog/__index.props.json')
+ * // → 'http://localhost/blog/'
+ */
+export declare function rewriteHiddenRoutes(url: string): string;
+/**
+ * Determine if the incoming request targets a premises endpoint
+ * (`__index.props.json` or `__index.doc.html`) and whether the config
+ * allows it.
+ *
+ * @returns A descriptor when premises are enabled, or `null` when not.
+ * @throws  When a premise URL is hit but premises are not enabled.
+ */
+export declare function resolvePremises(requestedUrl: string, gracileConfig: GracileConfig): PremisesDescriptor | null;
+export interface ExecuteHandlerOptions {
+    routeInfos: RouteInfos;
+    method: string;
+    request: Request;
+    fullUrl: string;
+    locals: unknown;
+    responseInit: ResponseInit;
+    premises: PremisesDescriptor | null;
+    routeTemplateOptions: Parameters<typeof renderRouteTemplate>[0];
+}
+/**
+ * Result from `executeHandler`:
+ *
+ * - `{ type: 'response', value }` — return this response directly
+ * - `{ type: 'output', value }` — pass to response building
+ * - `{ type: 'fallthrough' }` — no handler, proceed to template-only render
+ */
+export type ExecuteHandlerResult = {
+    type: 'response';
+    value: StandardResponse;
+} | {
+    type: 'output';
+    value: Readable | Response | null;
+} | {
+    type: 'fallthrough';
+};
+/**
+ * Dispatch the user's route handler (top-level function or method-map).
+ *
+ * This determines whether to call the handler, which method to use,
+ * and whether to short-circuit with premises or a 405.
+ */
+export declare function executeHandler(options: ExecuteHandlerOptions): Promise<ExecuteHandlerResult>;
+/**
+ * Render a page that has no handler — just a document/template.
+ * Handles premises short-circuits.
+ */
+export declare function renderWithoutHandler(options: {
+    premises: PremisesDescriptor | null;
+    routeTemplateOptions: Parameters<typeof renderRouteTemplate>[0];
+}): Promise<StandardResponse | Readable | null>;
+export declare function isRedirect(response: Response): {
+    location: string;
+} | null;
+/**
+ * Convert a handler/render output (Response or Readable stream) into
+ * the final `HandlerResult` shape expected by adapters.
+ */
+export declare function buildResponse(options: {
+    output: Readable | Response | null;
+    responseInit: ResponseInit;
+    vite: ViteDevServer | undefined;
+    logger: Logger;
+}): HandlerResult;
+//# sourceMappingURL=request-pipeline.d.ts.map

package/dist/server/request-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-pipeline.d.ts","sourceRoot":"","sources":["../../src/server/request-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,OAAO,KAAK,EAAc,MAAM,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,IAAI,CAAC,EAAE,KAAK,CAAC;CACb,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,wBAAwB,GAAG,IAAI,CAAC;AAE/E,eAAO,MAAM,iBAAiB;;CAA2C,CAAC;AAE1E,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAEX,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,aAAa,GAC1B,kBAAkB,GAAG,IAAI,CAY3B;AAaD,MAAM,WAAW,qBAAqB;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,oBAAoB,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAE3B;;;;;GAKG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAyF/B;AAID;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IACnD,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,oBAAoB,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE,GAAG,OAAO,CAAC,gBAAgB,GAAG,QAAQ,GAAG,IAAI,CAAC,CAoB9C;AAID,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAM1E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACtC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;CACf,GAAG,aAAa,CAqDhB"}

package/dist/server/request-pipeline.js

@@ -0,0 +1,198 @@
+/**
+ * Pure, testable pipeline steps extracted from the request handler.
+ *
+ * Each function here is a focused stage of the Gracile request lifecycle.
+ * They are composed by `createGracileHandler` in `./request.ts`.
+ *
+ * @internal
+ */
+import { Readable } from 'node:stream';
+import * as assert from '@gracile/internal-utils/assertions';
+import { renderRouteTemplate } from '../render/route-template.js';
+export const CONTENT_TYPE_HTML = { 'Content-Type': 'text/html' };
+export const PREMISE_REGEXES = {
+    properties: /\/__(.*?)\.props\.json$/,
+    document: /\/__(.*?)\.doc\.html$/,
+};
+// ── 1. Rewrite hidden route siblings ─────────────────────────────────
+/**
+ * Strip the `/__…` suffix so hidden-sibling URLs (premises) resolve to
+ * the parent route.
+ *
+ * @example
+ * rewriteHiddenRoutes('http://localhost/blog/__index.props.json')
+ * // → 'http://localhost/blog/'
+ */
+export function rewriteHiddenRoutes(url) {
+    return url.replace(/\/__(.*)$/, '/');
+}
+// ── 2. Resolve premises ──────────────────────────────────────────────
+/**
+ * Determine if the incoming request targets a premises endpoint
+ * (`__index.props.json` or `__index.doc.html`) and whether the config
+ * allows it.
+ *
+ * @returns A descriptor when premises are enabled, or `null` when not.
+ * @throws  When a premise URL is hit but premises are not enabled.
+ */
+export function resolvePremises(requestedUrl, gracileConfig) {
+    const propertiesOnly = PREMISE_REGEXES.properties.test(requestedUrl);
+    const documentOnly = PREMISE_REGEXES.document.test(requestedUrl);
+    const allowPremises = Boolean(gracileConfig.pages?.premises?.expose);
+    if (allowPremises === false && (propertiesOnly || documentOnly))
+        throw new Error('Accessed a page premise but they are not activated. You must enable `pages.premises.expose`.');
+    if (allowPremises)
+        return { propertiesOnly, documentOnly };
+    return null;
+}
+/**
+ * Dispatch the user's route handler (top-level function or method-map).
+ *
+ * This determines whether to call the handler, which method to use,
+ * and whether to short-circuit with premises or a 405.
+ */
+export async function executeHandler(options) {
+    const { routeInfos, method, request, fullUrl, locals, responseInit, premises, routeTemplateOptions, } = options;
+    const handler = routeInfos.routeModule.handler;
+    const shouldDispatch = ('handler' in routeInfos.routeModule && handler !== undefined) ||
+        // NOTE: When a handler exists but has no GET key, and the request
+        // method is not GET, we still dispatch to let it handle the method.
+        (handler && 'GET' in handler === false && method !== 'GET');
+    if (!shouldDispatch)
+        return { type: 'fallthrough' };
+    // Build the frozen context passed to the user handler.
+    let providedLocals = {};
+    if (locals && assert.isUnknownObject(locals))
+        providedLocals = locals;
+    const routeContext = Object.freeze({
+        request,
+        url: new URL(fullUrl),
+        responseInit,
+        params: routeInfos.params,
+        locals: providedLocals,
+    });
+    const hasTopLevelHandler = typeof handler === 'function';
+    if (!hasTopLevelHandler && !(method in handler)) {
+        const statusText = `This route doesn't handle the \`${method}\` method!`;
+        return {
+            type: 'response',
+            value: {
+                response: new Response(statusText, { status: 405, statusText }),
+            },
+        };
+    }
+    const handlerWithMethod = hasTopLevelHandler
+        ? handler
+        : handler[method];
+    if (typeof handlerWithMethod !== 'function')
+        throw new TypeError('Handler must be a function.');
+    const handlerOutput = await Promise.resolve(handlerWithMethod(routeContext));
+    // User returned a raw Response — pass it through.
+    if (assert.isResponseOrPatchedResponse(handlerOutput))
+        return { type: 'output', value: handlerOutput };
+    // User returned data — merge into routeInfos.props for template rendering.
+    routeTemplateOptions.routeInfos.props = hasTopLevelHandler
+        ? handlerOutput
+        : { [method]: handlerOutput };
+    // Short-circuit for premises.
+    if (premises?.documentOnly) {
+        const { document } = await renderRouteTemplate(routeTemplateOptions);
+        return {
+            type: 'response',
+            value: {
+                response: new Response(document, {
+                    headers: { ...CONTENT_TYPE_HTML },
+                }),
+            },
+        };
+    }
+    if (premises?.propertiesOnly)
+        return {
+            type: 'response',
+            value: {
+                response: Response.json(routeTemplateOptions.routeInfos.props),
+            },
+        };
+    const output = await renderRouteTemplate(routeTemplateOptions).then((r) => r.output);
+    return { type: 'output', value: output };
+}
+// ── 4. Render without handler (template-only) ────────────────────────
+/**
+ * Render a page that has no handler — just a document/template.
+ * Handles premises short-circuits.
+ */
+export async function renderWithoutHandler(options) {
+    const { premises, routeTemplateOptions } = options;
+    if (premises?.documentOnly) {
+        const { document } = await renderRouteTemplate(routeTemplateOptions);
+        return {
+            response: new Response(document, {
+                headers: { ...CONTENT_TYPE_HTML },
+            }),
+        };
+    }
+    if (premises?.propertiesOnly)
+        return {
+            response: Response.json(routeTemplateOptions.routeInfos.props || {}),
+        };
+    const output = await renderRouteTemplate(routeTemplateOptions).then((r) => r.output);
+    return output;
+}
+// ── 5. Build the final response from output ──────────────────────────
+export function isRedirect(response) {
+    const location = response.headers.get('location');
+    if (response.status >= 300 && response.status <= 303 && location) {
+        return { location };
+    }
+    return null;
+}
+/**
+ * Convert a handler/render output (Response or Readable stream) into
+ * the final `HandlerResult` shape expected by adapters.
+ */
+export function buildResponse(options) {
+    const { output, responseInit, vite, logger } = options;
+    // Direct Response pass-through (e.g. from handler returning Response)
+    if (assert.isResponseOrPatchedResponse(output)) {
+        const redirect = isRedirect(output);
+        if (redirect?.location)
+            return {
+                response: Response.redirect(redirect.location, output.status),
+            };
+        return { response: output };
+    }
+    // Readable stream — the SSR page render
+    if (output instanceof Readable) {
+        responseInit.headers = {
+            ...responseInit.headers,
+            ...CONTENT_TYPE_HTML,
+        };
+        return {
+            body: output.on('error', (error) => {
+                const errorMessage = `[SSR Error] There was an error while rendering a template chunk on server-side.\n` +
+                    `It was omitted from the resulting HTML.\n`;
+                if (vite) {
+                    logger.error(errorMessage + error.stack);
+                    const payload = {
+                        type: 'error',
+                        err: {
+                            name: 'StreamingError',
+                            message: errorMessage,
+                            stack: error.stack ?? 'No stack trace available',
+                            hint: 'This is often caused by a wrong template location dynamic interpolation.',
+                            cause: error,
+                        },
+                    };
+                    setTimeout(() => {
+                        vite.hot.send(payload);
+                    }, 200);
+                }
+                else {
+                    logger.error(errorMessage);
+                }
+            }),
+            init: responseInit,
+        };
+    }
+    return null;
+}

package/dist/server/request.d.ts

@@ -1,27 +1,14 @@
-import { Readable } from 'node:stream';
 import type { Logger, ViteDevServer } from 'vite';
 import type * as R from '../routes/route.js';
 import type { GracileConfig } from '../user-config.js';
-type StandardResponse = {
-    response: Response;
-    body?: never;
-    init?: never;
-};
-type ResponseWithNodeReadable = {
-    response?: never;
-    body: Readable;
-    init: ResponseInit;
-};
+import { type HandlerResult } from './request-pipeline.js';
 export interface AdapterOptions {
     logger?: Logger;
 }
 /**
  * The underlying handler interface that you can use to build your own adapter.
  */
-export type GracileHandler = (request: Request, locals?: unknown) => Promise<StandardResponse | ResponseWithNodeReadable | null>;
-export declare function isRedirect(response: Response): {
-    location: string;
-} | null;
+export type GracileHandler = (request: Request, locals?: unknown) => Promise<HandlerResult>;
 export declare function createGracileHandler({ vite, routes, routeImports, routeAssets, root, serverMode, gracileConfig, }: {
     vite?: ViteDevServer | undefined;
     routes: R.RoutesManifest;
@@ -31,5 +18,5 @@ export declare function createGracileHandler({ vite, routes, routeImports, route
     serverMode?: boolean | undefined;
     gracileConfig: GracileConfig;
 }): GracileHandler;
-export {};
+export { type StandardResponse, type ResponseWithNodeReadable, isRedirect, } from './request-pipeline.js';
 //# sourceMappingURL=request.d.ts.map

package/dist/server/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAQlD,OAAO,KAAK,KAAK,CAAC,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,KAAK,gBAAgB,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAC3E,KAAK,wBAAwB,GAAG;IAC/B,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,OAAO,KACZ,OAAO,CAAC,gBAAgB,GAAG,wBAAwB,GAAG,IAAI,CAAC,CAAC;AASjE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO1E;AAED,wBAAgB,oBAAoB,CAAC,EACpC,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,WAAW,EACX,IAAI,EACJ,UAAU,EACV,aAAa,GACb,EAAE;IACF,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,cAAc,CAAC;IACzB,YAAY,CAAC,EAAE,CAAC,CAAC,aAAa,GAAG,SAAS,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;CAC7B,kBA8QA"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAOlD,OAAO,KAAK,KAAK,CAAC,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EACN,KAAK,aAAa,EAOlB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,OAAO,KACZ,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,wBAAgB,oBAAoB,CAAC,EACpC,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,WAAW,EACX,IAAI,EACJ,UAAU,EACV,aAAa,GACb,EAAE;IACF,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,cAAc,CAAC;IACzB,YAAY,CAAC,EAAE,CAAC,CAAC,aAAa,GAAG,SAAS,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;CAC7B,kBAuIA;AAyBD,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,UAAU,GACV,MAAM,uBAAuB,CAAC"}