@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/src/runtime/views.ts

@@ -0,0 +1,385 @@
+import path from 'node:path';
+import { access, stat } from 'node:fs/promises';
+
+import { resolveWorkspaceRoot } from '../workspace.js';
+import { readTextFile } from '../utils/bun.js';
+
+export interface EnvAccessorLike {
+  get(name: string): string | undefined;
+  require(name: string): string;
+  entries(): Record<string, string | undefined>;
+}
+
+export interface LoggerLike {
+  readonly level?: string;
+  log?(level: string, message: string, metadata?: Record<string, unknown>): void;
+  debug?(message: string, metadata?: Record<string, unknown>): void;
+  info?(message: string, metadata?: Record<string, unknown>): void;
+  warn?(message: string, metadata?: Record<string, unknown>): void;
+  error?(message: string, metadata?: Record<string, unknown>): void;
+  with?(bindings: Record<string, unknown>): LoggerLike;
+}
+
+export interface ViewDefinitionLike {
+  name?: string;
+  path?: string;
+  renderMode?: 'ssg' | 'ssr' | 'spa';
+}
+
+export type RequestTimeDocumentCacheStatus = 'miss' | 'hit' | 'stale';
+
+export interface RequestTimeDocumentCacheMetadata {
+  readonly status: RequestTimeDocumentCacheStatus;
+  readonly documentPath: string;
+}
+
+export interface RenderedRequestTimeView {
+  readonly html: string;
+  readonly documentCache: RequestTimeDocumentCacheMetadata;
+}
+
+export interface SSRContextLike {
+  readonly url: URL;
+  readonly params: Record<string, string>;
+  readonly cookies: Record<string, string>;
+  readonly headers: Record<string, string>;
+  readonly auth: unknown;
+  readonly session: Record<string, unknown> | null;
+  readonly env: EnvAccessorLike;
+  readonly logger: LoggerLike;
+  readonly requestId?: string;
+  readonly now: () => Date;
+}
+
+export interface ModuleViewLike {
+  readonly definition?: ViewDefinitionLike;
+  readonly load?: (context: SSRContextLike) => Promise<unknown> | unknown;
+}
+
+export interface CompiledView {
+  readonly name: string;
+  readonly pathPattern: string;
+  readonly definition?: ViewDefinitionLike;
+  readonly load?: ModuleViewLike['load'];
+  readonly match: (pathname: string) => {
+    matched: boolean;
+    params: Record<string, string>;
+  };
+}
+
+export function compileViews(views: readonly ModuleViewLike[]): CompiledView[] {
+  const compiled: CompiledView[] = [];
+  for (const view of views) {
+    const pathPattern = normalizePath(view.definition?.path ?? '/');
+    compiled.push({
+      name: view.definition?.name ?? pathPattern,
+      pathPattern,
+      definition: view.definition,
+      load: view.load,
+      match: createPathMatcher(pathPattern),
+    });
+  }
+  return compiled;
+}
+
+export function matchView(
+  views: readonly CompiledView[],
+  pathname: string,
+): { view: CompiledView; params: Record<string, string> } | undefined {
+  for (const view of views) {
+    const matched = view.match(pathname);
+    if (matched.matched) {
+      return {
+        view,
+        params: matched.params,
+      };
+    }
+  }
+  return undefined;
+}
+
+export async function renderRequestTimeView(options: {
+  workspaceRoot?: string;
+  url: URL;
+  view: CompiledView;
+  params: Record<string, string>;
+  cookies: Record<string, string>;
+  headers: Record<string, string>;
+  auth: unknown;
+  session: Record<string, unknown> | null;
+  env: EnvAccessorLike;
+  logger: LoggerLike;
+  requestId?: string;
+  now?: () => Date;
+}): Promise<RenderedRequestTimeView> {
+  const {
+    workspaceRoot,
+    url,
+    view,
+    params,
+    cookies,
+    headers,
+    auth,
+    session,
+    env,
+    logger,
+    requestId,
+  } = options;
+  const now = options.now ?? (() => new Date());
+  const document = await loadFrontendDocument(resolveWorkspaceRoot(workspaceRoot), url.pathname);
+
+  const viewData = view.load
+    ? await view.load({
+        url,
+        params,
+        cookies,
+        headers,
+        auth,
+        session,
+        env,
+        logger,
+        requestId,
+        now,
+      })
+    : null;
+
+  return {
+    html: injectViewState(document.html, {
+      name: view.name,
+      templatePath: view.pathPattern,
+      pathname: normalizePath(url.pathname),
+      params,
+      data: viewData ?? null,
+      requestId,
+    }),
+    documentCache: {
+      status: document.cacheStatus,
+      documentPath: document.path,
+    },
+  };
+}
+
+export function toHeaderRecord(
+  headers: Record<string, string | string[] | undefined>,
+): Record<string, string> {
+  const normalized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (typeof value === 'string') {
+      normalized[key] = value;
+      continue;
+    }
+    if (Array.isArray(value)) {
+      normalized[key] = value.join(', ');
+    }
+  }
+  return normalized;
+}
+
+function createPathMatcher(pattern: string) {
+  const normalized = normalizePath(pattern);
+  const paramRegex = /:([A-Za-z0-9_]+)/g;
+  const regex = new RegExp(
+    '^' +
+      normalized
+        .replace(/\//g, '\\/')
+        .replace(paramRegex, (_segment, name) => `(?<${name}>[^/]+)`) +
+      '$',
+  );
+
+  return (pathname: string) => {
+    const pathToTest = normalizePath(pathname);
+    const match = regex.exec(pathToTest);
+    if (!match) {
+      return { matched: false, params: {} };
+    }
+    return {
+      matched: true,
+      params: (match.groups ?? {}) as Record<string, string>,
+    };
+  };
+}
+
+function normalizePath(value: string | undefined): string {
+  if (!value || value === '/') {
+    return '/';
+  }
+  const trimmed = value.endsWith('/') ? value.slice(0, -1) : value;
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+function firstPathSegment(pathname: string): string | undefined {
+  const normalized = normalizePath(pathname);
+  if (normalized === '/') {
+    return undefined;
+  }
+  const parts = normalized.split('/').filter(Boolean);
+  return parts[0];
+}
+
+const documentTemplateCache = new Map<
+  string,
+  {
+    html: string;
+    ctimeMs: number;
+    mtimeMs: number;
+    size: number;
+  }
+>();
+
+async function loadFrontendDocument(
+  workspaceRoot: string,
+  pathname: string,
+): Promise<{
+  path: string;
+  html: string;
+  cacheStatus: RequestTimeDocumentCacheStatus;
+}> {
+  const documentPath = await resolveFrontendDocumentPath(workspaceRoot, pathname);
+  const documentStats = await stat(documentPath);
+  const cached = documentTemplateCache.get(documentPath);
+
+  if (
+    cached &&
+    cached.ctimeMs === documentStats.ctimeMs &&
+    cached.mtimeMs === documentStats.mtimeMs &&
+    cached.size === documentStats.size
+  ) {
+    return {
+      path: documentPath,
+      html: cached.html,
+      cacheStatus: 'hit',
+    };
+  }
+
+  const html = await readTextFile(documentPath);
+  documentTemplateCache.set(documentPath, {
+    html,
+    ctimeMs: documentStats.ctimeMs,
+    mtimeMs: documentStats.mtimeMs,
+    size: documentStats.size,
+  });
+
+  return {
+    path: documentPath,
+    html,
+    cacheStatus: cached ? 'stale' : 'miss',
+  };
+}
+
+async function resolveFrontendDocumentPath(
+  workspaceRoot: string,
+  pathname: string,
+): Promise<string> {
+  const candidates = getFrontendDocumentCandidates(workspaceRoot, pathname);
+
+  for (const candidate of candidates) {
+    if (await fileExists(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `Frontend document for ${normalizePath(pathname)} was not found. Checked ${candidates.join(', ')}.`,
+  );
+}
+
+function getFrontendDocumentCandidates(workspaceRoot: string, pathname: string): string[] {
+  const pageName = firstPathSegment(pathname) ?? 'home';
+  const relativeCandidates =
+    pageName === 'home'
+      ? [
+          path.join('pages', 'home', 'index.html'),
+          path.join('home', 'index.html'),
+          'home.html',
+          'index.html',
+        ]
+      : [
+          path.join('pages', pageName, 'index.html'),
+          path.join(pageName, 'index.html'),
+          `${pageName}.html`,
+        ];
+
+  const candidates = [
+    ...relativeCandidates.map((relativePath) =>
+      path.join(workspaceRoot, 'build', 'frontend', relativePath),
+    ),
+    ...relativeCandidates.map((relativePath) =>
+      path.join(workspaceRoot, 'dist', 'frontend', relativePath),
+    ),
+  ];
+
+  return Array.from(new Set(candidates));
+}
+
+async function fileExists(targetPath: string): Promise<boolean> {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function injectViewState(
+  documentHtml: string,
+  state: {
+    name: string;
+    templatePath: string;
+    pathname: string;
+    params: Record<string, string>;
+    data: unknown;
+    requestId?: string;
+  },
+): string {
+  const payload = serializeJsonForHtml({
+    view: {
+      name: state.name,
+      path: state.templatePath,
+      pathname: state.pathname,
+      params: state.params,
+    },
+    data: state.data,
+    requestId: state.requestId ?? null,
+  });
+
+  const scriptTag = `<script type="application/json" id="webstir-view-state">${payload}</script>`;
+  const htmlWithBodyAttributes = documentHtml.replace(
+    /<body\b([^>]*)>/i,
+    (_match, existingAttributes) => {
+      const attrs = [
+        `data-webstir-view-name="${escapeHtmlAttribute(state.name)}"`,
+        `data-webstir-view-pathname="${escapeHtmlAttribute(state.pathname)}"`,
+        `data-webstir-view-template="${escapeHtmlAttribute(state.templatePath)}"`,
+      ];
+      return `<body${existingAttributes} ${attrs.join(' ')}>`;
+    },
+  );
+
+  if (/<\/body>/i.test(htmlWithBodyAttributes)) {
+    return htmlWithBodyAttributes.replace(/<\/body>/i, `${scriptTag}\n</body>`);
+  }
+
+  if (/<\/html>/i.test(htmlWithBodyAttributes)) {
+    return htmlWithBodyAttributes.replace(/<\/html>/i, `${scriptTag}\n</html>`);
+  }
+
+  return `${htmlWithBodyAttributes}\n${scriptTag}`;
+}
+
+function serializeJsonForHtml(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}

package/src/scaffold/assets.ts

@@ -4,78 +4,82 @@ import { fileURLToPath } from 'node:url';
 import type { ModuleAsset } from '@webstir-io/module-contract';
 
 export async function getBackendScaffoldAssets(): Promise<readonly ModuleAsset[]> {
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    const packageRoot = path.resolve(here, '..', '..');
-    const templatesRoot = path.join(packageRoot, 'templates', 'backend');
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(here, '..', '..');
+  const templatesRoot = path.join(packageRoot, 'templates', 'backend');
 
-    return [
-        {
-            sourcePath: path.join(templatesRoot, 'tsconfig.json'),
-            targetPath: path.join('src', 'backend', 'tsconfig.json')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'index.ts'),
-            targetPath: path.join('src', 'backend', 'index.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'server', 'fastify.ts'),
-            targetPath: path.join('src', 'backend', 'server', 'fastify.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'module.ts'),
-            targetPath: path.join('src', 'backend', 'module.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'auth', 'adapter.ts'),
-            targetPath: path.join('src', 'backend', 'auth', 'adapter.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'observability', 'logger.ts'),
-            targetPath: path.join('src', 'backend', 'observability', 'logger.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'observability', 'metrics.ts'),
-            targetPath: path.join('src', 'backend', 'observability', 'metrics.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'env.ts'),
-            targetPath: path.join('src', 'backend', 'env.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'functions', 'hello', 'index.ts'),
-            targetPath: path.join('src', 'backend', 'functions', 'hello', 'index.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'jobs', 'nightly', 'index.ts'),
-            targetPath: path.join('src', 'backend', 'jobs', 'nightly', 'index.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'jobs', 'runtime.ts'),
-            targetPath: path.join('src', 'backend', 'jobs', 'runtime.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'jobs', 'scheduler.ts'),
-            targetPath: path.join('src', 'backend', 'jobs', 'scheduler.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'db', 'connection.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'connection.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'db', 'migrate.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'migrate.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'db', 'migrations', '0001-example.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'migrations', '0001-example.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'db', 'types.d.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'types.d.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, '.env.example'),
-            targetPath: path.join('.env.example')
-        }
-    ];
+  return [
+    {
+      sourcePath: path.join(templatesRoot, 'tsconfig.json'),
+      targetPath: path.join('src', 'backend', 'tsconfig.json'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'index.ts'),
+      targetPath: path.join('src', 'backend', 'index.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'module.ts'),
+      targetPath: path.join('src', 'backend', 'module.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'auth', 'adapter.ts'),
+      targetPath: path.join('src', 'backend', 'auth', 'adapter.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'observability', 'logger.ts'),
+      targetPath: path.join('src', 'backend', 'observability', 'logger.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'observability', 'metrics.ts'),
+      targetPath: path.join('src', 'backend', 'observability', 'metrics.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'env.ts'),
+      targetPath: path.join('src', 'backend', 'env.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'session', 'store.ts'),
+      targetPath: path.join('src', 'backend', 'session', 'store.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'session', 'sqlite.ts'),
+      targetPath: path.join('src', 'backend', 'session', 'sqlite.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'functions', 'hello', 'index.ts'),
+      targetPath: path.join('src', 'backend', 'functions', 'hello', 'index.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'jobs', 'nightly', 'index.ts'),
+      targetPath: path.join('src', 'backend', 'jobs', 'nightly', 'index.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'jobs', 'runtime.ts'),
+      targetPath: path.join('src', 'backend', 'jobs', 'runtime.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'jobs', 'scheduler.ts'),
+      targetPath: path.join('src', 'backend', 'jobs', 'scheduler.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'db', 'connection.ts'),
+      targetPath: path.join('src', 'backend', 'db', 'connection.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'db', 'migrate.ts'),
+      targetPath: path.join('src', 'backend', 'db', 'migrate.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'db', 'migrations', '0001-example.ts'),
+      targetPath: path.join('src', 'backend', 'db', 'migrations', '0001-example.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, 'db', 'types.d.ts'),
+      targetPath: path.join('src', 'backend', 'db', 'types.d.ts'),
+    },
+    {
+      sourcePath: path.join(templatesRoot, '.env.example'),
+      targetPath: path.join('.env.example'),
+    },
+  ];
 }

package/src/testing/context.js

@@ -1,14 +1,13 @@
 const GLOBAL_KEY = '__webstirBackendTestContext__';
 export function setBackendTestContext(context) {
-    const target = globalThis;
-    if (context) {
-        target[GLOBAL_KEY] = context;
-    }
-    else {
-        delete target[GLOBAL_KEY];
-    }
+  const target = globalThis;
+  if (context) {
+    target[GLOBAL_KEY] = context;
+  } else {
+    delete target[GLOBAL_KEY];
+  }
 }
 export function getBackendTestContext() {
-    const target = globalThis;
-    return (target[GLOBAL_KEY] ?? null);
+  const target = globalThis;
+  return target[GLOBAL_KEY] ?? null;
 }

package/src/testing/context.ts

@@ -1,17 +1,17 @@
 import type { BackendTestContext } from './types.js';
 
-const GLOBAL_KEY = '__webstirBackendTestContext__';
+const GLOBAL_KEY = Symbol.for('webstir.backendTestContext');
 
 export function setBackendTestContext(context: BackendTestContext | null): void {
-    const target = globalThis as Record<string, unknown>;
-    if (context) {
-        target[GLOBAL_KEY] = context;
-    } else {
-        delete target[GLOBAL_KEY];
-    }
+  const target = globalThis as Record<string | symbol, unknown>;
+  if (context) {
+    target[GLOBAL_KEY] = context;
+  } else {
+    delete target[GLOBAL_KEY];
+  }
 }
 
 export function getBackendTestContext(): BackendTestContext | null {
-    const target = globalThis as Record<string, unknown>;
-    return (target[GLOBAL_KEY] ?? null) as BackendTestContext | null;
+  const target = globalThis as Record<string | symbol, unknown>;
+  return (target[GLOBAL_KEY] ?? null) as BackendTestContext | null;
 }

package/src/testing/index.d.ts

@@ -1,6 +1,17 @@
 import { getBackendTestContext, setBackendTestContext } from './context.js';
-import type { BackendTestCallback, BackendTestHarness, BackendTestHarnessOptions } from './types.js';
-export type { BackendTestCallback, BackendTestContext, BackendTestHarness, BackendTestHarnessOptions } from './types.js';
+import type {
+  BackendTestCallback,
+  BackendTestHarness,
+  BackendTestHarnessOptions,
+} from './types.js';
+export type {
+  BackendTestCallback,
+  BackendTestContext,
+  BackendTestHarness,
+  BackendTestHarnessOptions,
+} from './types.js';
 export { getBackendTestContext, setBackendTestContext };
-export declare function createBackendTestHarness(options?: BackendTestHarnessOptions): Promise<BackendTestHarness>;
+export declare function createBackendTestHarness(
+  options?: BackendTestHarnessOptions,
+): Promise<BackendTestHarness>;
 export declare function backendTest(name: string, callback: BackendTestCallback): void;