@hypequery/serve 0.0.7 → 0.0.9

package/dist/pipeline.js

@@ -0,0 +1,424 @@
+import { z } from 'zod';
+import { createTenantScope, warnTenantMisconfiguration } from './tenant.js';
+import { generateRequestId } from './utils.js';
+import { buildOpenApiDocument } from './openapi.js';
+import { buildDocsHtml } from './docs-ui.js';
+import { checkRoleAuthorization, checkScopeAuthorization, } from './auth.js';
+const safeInvokeHook = async (name, hook, payload) => {
+    if (!hook)
+        return;
+    try {
+        await hook(payload);
+    }
+    catch (error) {
+        console.error(`[hypequery/serve] ${name} hook failed`, error);
+    }
+};
+const createErrorResponse = (status, type, message, details, headers) => ({
+    status,
+    headers,
+    body: { error: { type, message, ...(details ? { details } : {}) } },
+});
+const buildContextInput = (request) => {
+    if (request.body !== undefined && request.body !== null) {
+        return request.body;
+    }
+    if (request.query && Object.keys(request.query).length > 0) {
+        return request.query;
+    }
+    return undefined;
+};
+const runMiddlewares = async (middlewares, ctx, handler) => {
+    let current = handler;
+    for (let i = middlewares.length - 1; i >= 0; i -= 1) {
+        const middleware = middlewares[i];
+        const next = current;
+        current = () => middleware(ctx, next);
+    }
+    return current();
+};
+const authenticateRequest = async (strategies, request, metadata) => {
+    for (const strategy of strategies) {
+        const result = await strategy({ request, endpoint: metadata });
+        if (result) {
+            return result;
+        }
+    }
+    return null;
+};
+const gatherAuthStrategies = (endpointStrategy, globalStrategies) => {
+    const combined = [];
+    if (endpointStrategy)
+        combined.push(endpointStrategy);
+    combined.push(...globalStrategies);
+    return combined;
+};
+const computeRequiresAuth = (metadata, endpointStrategy, globalStrategies, endpoint) => {
+    // Explicit .public() overrides everything
+    if (metadata.requiresAuth === false) {
+        return false;
+    }
+    // Explicit .requireAuth() or roles/scopes imply auth
+    if (metadata.requiresAuth === true) {
+        return true;
+    }
+    if ((endpoint.requiredRoles?.length ?? 0) > 0 || (endpoint.requiredScopes?.length ?? 0) > 0) {
+        return true;
+    }
+    if (endpointStrategy) {
+        return true;
+    }
+    return globalStrategies.length > 0;
+};
+const checkAuthorization = (auth, requiredRoles, requiredScopes) => {
+    // Check roles first
+    if (requiredRoles && requiredRoles.length > 0) {
+        const roleResult = checkRoleAuthorization(auth, requiredRoles);
+        if (!roleResult.ok) {
+            const userRoles = auth?.roles ?? [];
+            return { ok: false, reason: roleResult.reason, required: roleResult.missing, actual: userRoles };
+        }
+    }
+    // Check scopes
+    if (requiredScopes && requiredScopes.length > 0) {
+        const scopeResult = checkScopeAuthorization(auth, requiredScopes);
+        if (!scopeResult.ok) {
+            const userScopes = auth?.scopes ?? [];
+            return { ok: false, reason: scopeResult.reason, required: scopeResult.missing, actual: userScopes };
+        }
+    }
+    return { ok: true };
+};
+const validateInput = (schema, payload) => {
+    if (!schema) {
+        return { success: true, data: payload };
+    }
+    const result = schema.safeParse(payload);
+    return result.success
+        ? { success: true, data: result.data }
+        : { success: false, error: result.error };
+};
+const cloneContext = (ctx) => (ctx ? { ...ctx } : {});
+const resolveContext = async (factory, request, auth) => {
+    if (!factory) {
+        return {};
+    }
+    if (typeof factory === 'function') {
+        const value = await factory({ request, auth });
+        return cloneContext(value);
+    }
+    return cloneContext(factory);
+};
+const resolveRequestId = (request, provided) => provided ?? request.headers['x-request-id'] ?? request.headers['x-trace-id'] ?? generateRequestId();
+export const executeEndpoint = async (options) => {
+    const { endpoint, request, requestId: explicitRequestId, authStrategies, contextFactory, globalMiddlewares, tenantConfig, hooks = {}, queryLogger, additionalContext, verboseAuthErrors = false, // Default to secure mode for production safety
+     } = options;
+    const requestId = resolveRequestId(request, explicitRequestId);
+    const locals = {};
+    let cacheTtlMs = endpoint.cacheTtlMs ?? null;
+    const setCacheTtl = (ttl) => {
+        cacheTtlMs = ttl;
+    };
+    const context = {
+        request,
+        input: buildContextInput(request),
+        auth: null,
+        metadata: endpoint.metadata,
+        locals,
+        setCacheTtl,
+    };
+    const startedAt = Date.now();
+    await safeInvokeHook('onRequestStart', hooks.onRequestStart, {
+        requestId,
+        queryKey: endpoint.key,
+        metadata: endpoint.metadata,
+        request,
+        auth: context.auth,
+    });
+    // Skip query logging if no listeners are subscribed
+    if (queryLogger?.listenerCount ?? 0 > 0) {
+        queryLogger?.emit({
+            requestId,
+            endpointKey: endpoint.key,
+            path: endpoint.metadata.path ?? `/${endpoint.key}`,
+            method: request.method,
+            status: 'started',
+            startTime: startedAt,
+            input: request.body ?? request.query,
+        });
+    }
+    try {
+        const endpointAuth = endpoint.auth ?? null;
+        const strategies = gatherAuthStrategies(endpointAuth, authStrategies ?? []);
+        const requiresAuth = computeRequiresAuth(endpoint.metadata, endpointAuth, authStrategies ?? [], endpoint);
+        const metadataWithAuth = {
+            ...endpoint.metadata,
+            requiresAuth,
+        };
+        context.metadata = metadataWithAuth;
+        const authContext = await authenticateRequest(strategies, request, metadataWithAuth);
+        if (!authContext && requiresAuth) {
+            await safeInvokeHook('onAuthFailure', hooks.onAuthFailure, {
+                requestId,
+                queryKey: endpoint.key,
+                metadata: metadataWithAuth,
+                request,
+                auth: context.auth,
+                reason: 'MISSING',
+            });
+            return createErrorResponse(401, 'UNAUTHORIZED', verboseAuthErrors ? 'Authentication required' : 'Access denied', {
+                reason: 'missing_credentials',
+                ...(verboseAuthErrors && { strategies_attempted: strategies.length }),
+                endpoint: endpoint.metadata.path,
+            }, { 'x-request-id': requestId });
+        }
+        context.auth = authContext;
+        // Check role/scope authorization after successful authentication
+        const authzResult = checkAuthorization(authContext, endpoint.requiredRoles, endpoint.requiredScopes);
+        if (!authzResult.ok) {
+            const label = authzResult.reason === 'MISSING_ROLE' ? 'role' : 'scope';
+            await safeInvokeHook('onAuthorizationFailure', hooks.onAuthorizationFailure, {
+                requestId,
+                queryKey: endpoint.key,
+                metadata: metadataWithAuth,
+                request,
+                auth: authContext,
+                reason: authzResult.reason,
+                required: authzResult.required,
+                actual: authzResult.actual,
+            });
+            return createErrorResponse(403, 'FORBIDDEN', verboseAuthErrors
+                ? `Missing required ${label}: ${authzResult.required.join(', ')}`
+                : 'Insufficient permissions', {
+                reason: authzResult.reason.toLowerCase(),
+                ...(verboseAuthErrors && {
+                    required: authzResult.required,
+                    actual: authzResult.actual,
+                }),
+                endpoint: endpoint.metadata.path,
+            });
+        }
+        const resolvedContext = await resolveContext(contextFactory, request, authContext);
+        Object.assign(context, resolvedContext, additionalContext);
+        const activeTenantConfig = endpoint.tenant ?? tenantConfig;
+        if (activeTenantConfig) {
+            const tenantRequired = activeTenantConfig.required !== false;
+            const tenantId = authContext ? activeTenantConfig.extract(authContext) : null;
+            if (!tenantId && tenantRequired) {
+                const errorMessage = activeTenantConfig.errorMessage ??
+                    'Tenant context is required but could not be determined from authentication';
+                await safeInvokeHook('onError', hooks.onError, {
+                    requestId,
+                    queryKey: endpoint.key,
+                    metadata: metadataWithAuth,
+                    request,
+                    auth: context.auth,
+                    durationMs: Date.now() - startedAt,
+                    error: new Error(errorMessage),
+                });
+                return createErrorResponse(403, 'UNAUTHORIZED', errorMessage, {
+                    reason: 'missing_tenant_context',
+                    tenant_required: true,
+                }, { 'x-request-id': requestId });
+            }
+            if (tenantId) {
+                context.tenantId = tenantId;
+                const mode = activeTenantConfig.mode ?? 'manual';
+                const column = activeTenantConfig.column;
+                if (mode === 'auto-inject' && column) {
+                    const contextValues = context;
+                    for (const key of Object.keys(contextValues)) {
+                        const value = contextValues[key];
+                        if (value && typeof value === 'object' && 'table' in value && typeof value.table === 'function') {
+                            contextValues[key] = createTenantScope(value, {
+                                tenantId,
+                                column,
+                            });
+                        }
+                    }
+                }
+                else if (mode === 'manual') {
+                    warnTenantMisconfiguration({
+                        queryKey: endpoint.key,
+                        hasTenantConfig: true,
+                        hasTenantId: true,
+                        mode: 'manual',
+                    });
+                }
+            }
+            else if (!tenantRequired) {
+                warnTenantMisconfiguration({
+                    queryKey: endpoint.key,
+                    hasTenantConfig: true,
+                    hasTenantId: false,
+                    mode: activeTenantConfig.mode,
+                });
+            }
+        }
+        const validationResult = validateInput(endpoint.inputSchema, context.input);
+        if (!validationResult.success) {
+            await safeInvokeHook('onError', hooks.onError, {
+                requestId,
+                queryKey: endpoint.key,
+                metadata: metadataWithAuth,
+                request,
+                auth: context.auth,
+                durationMs: Date.now() - startedAt,
+                error: validationResult.error,
+            });
+            return createErrorResponse(400, 'VALIDATION_ERROR', 'Request validation failed', {
+                issues: validationResult.error.issues,
+            }, { 'x-request-id': requestId });
+        }
+        context.input = validationResult.data;
+        const pipeline = [
+            ...(globalMiddlewares ?? []),
+            ...endpoint.middlewares,
+        ];
+        const result = await runMiddlewares(pipeline, context, () => endpoint.handler(context));
+        const headers = {
+            ...(endpoint.defaultHeaders ?? {}),
+            'x-request-id': requestId,
+        };
+        if (typeof cacheTtlMs === 'number') {
+            headers['cache-control'] = cacheTtlMs > 0 ? `public, max-age=${Math.floor(cacheTtlMs / 1000)}` : 'no-store';
+        }
+        const durationMs = Date.now() - startedAt;
+        await safeInvokeHook('onRequestEnd', hooks.onRequestEnd, {
+            requestId,
+            queryKey: endpoint.key,
+            metadata: metadataWithAuth,
+            request,
+            auth: context.auth,
+            durationMs,
+            result,
+        });
+        // Skip query logging if no listeners are subscribed
+        if (queryLogger?.listenerCount ?? 0 > 0) {
+            queryLogger?.emit({
+                requestId,
+                endpointKey: endpoint.key,
+                path: endpoint.metadata.path ?? `/${endpoint.key}`,
+                method: request.method,
+                status: 'completed',
+                startTime: startedAt,
+                endTime: startedAt + durationMs,
+                durationMs,
+                input: context.input,
+                responseStatus: 200,
+                result,
+            });
+        }
+        return {
+            status: 200,
+            headers,
+            body: result,
+        };
+    }
+    catch (error) {
+        const errorDurationMs = Date.now() - startedAt;
+        await safeInvokeHook('onError', hooks.onError, {
+            requestId,
+            queryKey: endpoint.key,
+            metadata: context.metadata,
+            request,
+            auth: context.auth,
+            durationMs: errorDurationMs,
+            error,
+        });
+        // Skip query logging if no listeners are subscribed
+        if (queryLogger?.listenerCount ?? 0 > 0) {
+            queryLogger?.emit({
+                requestId,
+                endpointKey: endpoint.key,
+                path: endpoint.metadata.path ?? `/${endpoint.key}`,
+                method: request.method,
+                status: 'error',
+                startTime: startedAt,
+                endTime: startedAt + errorDurationMs,
+                durationMs: errorDurationMs,
+                input: context.input,
+                responseStatus: 500,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+        const message = error instanceof Error ? error.message : 'Unexpected error';
+        return createErrorResponse(500, 'INTERNAL_SERVER_ERROR', message, undefined, { 'x-request-id': requestId });
+    }
+};
+export const createServeHandler = ({ router, globalMiddlewares, authStrategies, tenantConfig, contextFactory, hooks, queryLogger, verboseAuthErrors = false, }) => {
+    return async (request) => {
+        const requestId = resolveRequestId(request);
+        const endpoint = router.match(request.method, request.path);
+        if (!endpoint) {
+            return createErrorResponse(404, 'NOT_FOUND', `No endpoint registered for ${request.method} ${request.path}`, undefined, { 'x-request-id': requestId });
+        }
+        return executeEndpoint({
+            endpoint,
+            request,
+            requestId,
+            authStrategies,
+            contextFactory,
+            globalMiddlewares,
+            tenantConfig,
+            hooks,
+            queryLogger,
+            verboseAuthErrors,
+        });
+    };
+};
+export const createOpenApiEndpoint = (path, getEndpoints, options) => {
+    let cachedDocument = null;
+    return {
+        key: '__hypequery_openapi__',
+        method: 'GET',
+        inputSchema: undefined,
+        outputSchema: z.any(),
+        handler: async () => {
+            if (!cachedDocument) {
+                cachedDocument = buildOpenApiDocument(getEndpoints(), options);
+            }
+            return cachedDocument;
+        },
+        query: undefined,
+        middlewares: [],
+        auth: null,
+        metadata: {
+            path,
+            method: 'GET',
+            name: 'OpenAPI schema',
+            summary: 'OpenAPI schema',
+            description: 'Generated OpenAPI specification for the registered endpoints',
+            tags: ['docs'],
+            requiresAuth: false,
+            deprecated: false,
+            visibility: 'internal',
+        },
+        cacheTtlMs: null,
+    };
+};
+export const createDocsEndpoint = (path, openapiPath, options) => ({
+    key: '__hypequery_docs__',
+    method: 'GET',
+    inputSchema: undefined,
+    outputSchema: z.string(),
+    handler: async () => buildDocsHtml(openapiPath, options),
+    query: undefined,
+    middlewares: [],
+    auth: null,
+    metadata: {
+        path,
+        method: 'GET',
+        name: 'Docs',
+        summary: 'API documentation',
+        description: 'Auto-generated documentation for your hypequery endpoints',
+        tags: ['docs'],
+        requiresAuth: false,
+        deprecated: false,
+        visibility: 'internal',
+    },
+    cacheTtlMs: null,
+    defaultHeaders: {
+        'content-type': 'text/html; charset=utf-8',
+    },
+});

package/dist/query-logger.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Backend-agnostic query event logger for the serve layer.
+ *
+ * Fires for every endpoint execution regardless of the underlying
+ * query backend (ClickHouse, BigQuery, mock data, etc.).
+ */
+/**
+ * Event emitted by the serve-layer query logger.
+ */
+export interface ServeQueryEvent {
+    requestId: string;
+    endpointKey: string;
+    path: string;
+    method: string;
+    status: 'started' | 'completed' | 'error';
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    input?: unknown;
+    responseStatus?: number;
+    error?: Error;
+    result?: unknown;
+}
+/**
+ * Callback for serve query events.
+ */
+export type ServeQueryEventCallback = (event: ServeQueryEvent) => void;
+/**
+ * Serve-layer query event emitter.
+ *
+ * Created per `defineServe()` call — not a singleton.
+ * Emits events at the request lifecycle level so that dev tools,
+ * logging, and analytics work with any query backend.
+ */
+export declare class ServeQueryLogger {
+    private listeners;
+    /**
+     * Subscribe to query events.
+     * @returns Unsubscribe function.
+     */
+    on(callback: ServeQueryEventCallback): () => void;
+    /**
+     * Emit a query event to all listeners.
+     */
+    emit(event: ServeQueryEvent): void;
+    /**
+     * Number of active listeners.
+     */
+    get listenerCount(): number;
+    /**
+     * Remove all listeners.
+     */
+    removeAll(): void;
+}
+/**
+ * Format a query event as a human-readable log line.
+ * Returns null for 'started' events (only logs completions).
+ */
+export declare function formatQueryEvent(event: ServeQueryEvent): string | null;
+/**
+ * Format a query event as a structured JSON string for log aggregators.
+ * Returns null for 'started' events (only logs completions).
+ */
+export declare function formatQueryEventJSON(event: ServeQueryEvent): string | null;
+//# sourceMappingURL=query-logger.d.ts.map

package/dist/query-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-logger.d.ts","sourceRoot":"","sources":["../src/query-logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAEvE;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAsC;IAEvD;;;OAGG;IACH,EAAE,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAOjD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAUlC;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,SAAS,IAAI,IAAI;CAGlB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAYtE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAiB1E"}

package/dist/query-logger.js

@@ -0,0 +1,91 @@
+/**
+ * Backend-agnostic query event logger for the serve layer.
+ *
+ * Fires for every endpoint execution regardless of the underlying
+ * query backend (ClickHouse, BigQuery, mock data, etc.).
+ */
+/**
+ * Serve-layer query event emitter.
+ *
+ * Created per `defineServe()` call — not a singleton.
+ * Emits events at the request lifecycle level so that dev tools,
+ * logging, and analytics work with any query backend.
+ */
+export class ServeQueryLogger {
+    constructor() {
+        this.listeners = new Set();
+    }
+    /**
+     * Subscribe to query events.
+     * @returns Unsubscribe function.
+     */
+    on(callback) {
+        this.listeners.add(callback);
+        return () => {
+            this.listeners.delete(callback);
+        };
+    }
+    /**
+     * Emit a query event to all listeners.
+     */
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    /**
+     * Number of active listeners.
+     */
+    get listenerCount() {
+        return this.listeners.size;
+    }
+    /**
+     * Remove all listeners.
+     */
+    removeAll() {
+        this.listeners.clear();
+    }
+}
+/**
+ * Format a query event as a human-readable log line.
+ * Returns null for 'started' events (only logs completions).
+ */
+export function formatQueryEvent(event) {
+    if (event.status === 'started')
+        return null;
+    const status = event.status === 'completed' ? '✓' : '✗';
+    const duration = event.durationMs != null ? `${event.durationMs}ms` : '?';
+    const code = event.responseStatus ?? (event.status === 'error' ? 500 : 200);
+    let line = `  ${status} ${event.method} ${event.path} → ${code} (${duration})`;
+    if (event.status === 'error' && event.error) {
+        line += ` — ${event.error.message}`;
+    }
+    return line;
+}
+/**
+ * Format a query event as a structured JSON string for log aggregators.
+ * Returns null for 'started' events (only logs completions).
+ */
+export function formatQueryEventJSON(event) {
+    if (event.status === 'started')
+        return null;
+    return JSON.stringify({
+        level: event.status === 'error' ? 'error' : 'info',
+        msg: `${event.method} ${event.path}`,
+        requestId: event.requestId,
+        endpoint: event.endpointKey,
+        path: event.path,
+        method: event.method,
+        status: event.responseStatus ?? (event.status === 'error' ? 500 : 200),
+        durationMs: event.durationMs,
+        ...(event.status === 'error' && event.error
+            ? { error: event.error.message }
+            : {}),
+        timestamp: new Date(event.endTime ?? event.startTime).toISOString(),
+    });
+}

package/dist/router.d.ts

@@ -0,0 +1,13 @@
+import type { EndpointRegistry, HttpMethod, ServeEndpoint } from "./types.js";
+export declare const normalizeRoutePath: (path: string) => string;
+export declare const applyBasePath: (basePath: string, path: string) => string;
+export declare class ServeRouter implements EndpointRegistry {
+    private readonly basePath;
+    private routes;
+    constructor(basePath?: string);
+    list(): ServeEndpoint<any, any, any, any, any>[];
+    register(endpoint: ServeEndpoint<any, any, any, any>): void;
+    match(method: HttpMethod, path: string): ServeEndpoint<any, any, any, any, any> | null;
+    markRoutesRequireAuth(): void;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI9E,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,WAG9C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,WAM3D,CAAC;AAEF,qBAAa,WAAY,YAAW,gBAAgB;IAGtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,MAAM,CAA2C;gBAE5B,QAAQ,SAAK;IAE1C,IAAI;IAIJ,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IAuBpD,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM;IAStC,qBAAqB;CAetB"}

package/dist/router.js

@@ -0,0 +1,56 @@
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, "");
+export const normalizeRoutePath = (path) => {
+    const trimmed = trimSlashes(path || "/");
+    return `/${trimmed}`.replace(/\/+/g, "/").replace(/\/$/, trimmed ? "" : "/");
+};
+export const applyBasePath = (basePath, path) => {
+    const parts = [trimSlashes(basePath ?? ""), trimSlashes(path)]
+        .filter(Boolean)
+        .join("/");
+    const combined = parts ? `/${parts}` : "/";
+    return combined.replace(/\/+/g, "/").replace(/\/$/, combined === "/" ? "/" : "");
+};
+export class ServeRouter {
+    constructor(basePath = "") {
+        this.basePath = basePath;
+        this.routes = [];
+    }
+    list() {
+        return [...this.routes];
+    }
+    register(endpoint) {
+        const path = endpoint.metadata.path || "/";
+        const normalizedPath = applyBasePath(this.basePath, path);
+        const method = endpoint.method;
+        const existing = this.routes.find((route) => route.metadata.path === normalizedPath && route.method === method);
+        if (existing) {
+            throw new Error(`Route already registered for ${method} ${normalizedPath}`);
+        }
+        this.routes.push({
+            ...endpoint,
+            metadata: {
+                ...endpoint.metadata,
+                path: normalizedPath,
+                method,
+            },
+        });
+    }
+    match(method, path) {
+        const normalizedPath = normalizeRoutePath(path);
+        return (this.routes.find((route) => route.method === method && route.metadata.path === normalizedPath) ?? null);
+    }
+    markRoutesRequireAuth() {
+        this.routes = this.routes.map((route) => {
+            if (route.metadata.requiresAuth === false) {
+                return route;
+            }
+            return {
+                ...route,
+                metadata: {
+                    ...route.metadata,
+                    requiresAuth: true,
+                },
+            };
+        });
+    }
+}

package/dist/server/builder.d.ts

@@ -0,0 +1,7 @@
+import type { AuthContext, AuthStrategy, HttpMethod, ServeBuilder, ServeEndpointMap, ServeMiddleware, ServeQueriesMap, ServeHandler, ExecuteQueryFunction } from "../types.js";
+import type { ServeRouter } from "../router.js";
+import { ServeQueryLogger } from "../query-logger.js";
+export declare const createBuilderMethods: <TQueries extends ServeQueriesMap<TContext, TAuth>, TContext extends Record<string, unknown>, TAuth extends AuthContext>(queryEntries: ServeEndpointMap<TQueries, TContext, TAuth>, queryLogger: ServeQueryLogger, routeConfig: Record<string, {
+    method: HttpMethod;
+}>, router: ServeRouter, authStrategies: AuthStrategy<TAuth>[], globalMiddlewares: ServeMiddleware<any, any, TContext, TAuth>[], executeQuery: ExecuteQueryFunction<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>, handler: ServeHandler, basePath: string) => ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/server/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EAEZ,gBAAgB,EAChB,eAAe,EAEf,eAAe,EACf,YAAY,EACZ,oBAAoB,EAGrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAKtD,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EACjD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,cAAc,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EACzD,aAAa,gBAAgB,EAC7B,aAAa,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,EACnD,QAAQ,WAAW,EACnB,gBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,EACrC,mBAAmB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,EAC/D,cAAc,oBAAoB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAChG,SAAS,YAAY,EACrB,UAAU,MAAM,KACf,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAoF3E,CAAC"}