@hypequery/serve 0.1.0 → 0.2.0

package/dist/adapters/node.js

@@ -1,17 +1,30 @@
 import { createServer } from "http";
 import { once } from "node:events";
 import { normalizeHeaders, parseQueryParams, parseRequestBody, serializeResponseBody, } from "./utils.js";
-const readRequestBody = async (req) => {
+const DEFAULT_REQUEST_TIMEOUT = 30000; // 30 seconds
+const DEFAULT_BODY_LIMIT = 1048576; // 1 MB
+const DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT = 10000; // 10 seconds
+const readRequestBody = async (req, bodyLimit) => {
     const chunks = [];
+    let totalLength = 0;
     for await (const chunk of req) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        totalLength += buf.length;
+        if (bodyLimit > 0 && totalLength > bodyLimit) {
+            // Destroy the stream to stop reading
+            req.destroy();
+            const error = new Error("Request body too large");
+            error.code = "PAYLOAD_TOO_LARGE";
+            throw error;
+        }
+        chunks.push(buf);
     }
     return Buffer.concat(chunks);
 };
-const buildServeRequest = async (req) => {
+const buildServeRequest = async (req, bodyLimit) => {
     const method = (req.method ?? "GET").toUpperCase();
     const url = new URL(req.url ?? "/", "http://localhost");
-    const bodyBuffer = await readRequestBody(req);
+    const bodyBuffer = await readRequestBody(req, bodyLimit);
     const headers = normalizeHeaders(req.headers);
     const contentType = headers["content-type"] ?? headers["Content-Type"];
     const body = await parseRequestBody(bodyBuffer, contentType);
@@ -25,6 +38,8 @@ const buildServeRequest = async (req) => {
     };
 };
 const sendResponse = (res, response) => {
+    if (res.writableEnded)
+        return;
     res.statusCode = response.status;
     const headers = response.headers ?? {};
     for (const [key, value] of Object.entries(headers)) {
@@ -39,6 +54,24 @@ const sendResponse = (res, response) => {
     res.end(serialized);
 };
 const sendError = (res, error) => {
+    if (res.writableEnded)
+        return;
+    // Handle body-too-large errors
+    if (error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "PAYLOAD_TOO_LARGE") {
+        sendResponse(res, {
+            status: 413,
+            body: {
+                error: {
+                    type: "PAYLOAD_TOO_LARGE",
+                    message: "Request body exceeds the configured size limit",
+                },
+            },
+        });
+        return;
+    }
     const payload = error && typeof error === "object" && "status" in error
         ? error
         : {
@@ -52,12 +85,39 @@ const sendError = (res, error) => {
         };
     sendResponse(res, payload);
 };
-export const createNodeHandler = (handler) => {
+export const createNodeHandler = (handler, options = {}) => {
+    const bodyLimit = options.bodyLimit ?? DEFAULT_BODY_LIMIT;
+    const requestTimeout = options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     return async (req, res) => {
         try {
-            const request = await buildServeRequest(req);
-            const response = await handler(request);
-            sendResponse(res, response);
+            const request = await buildServeRequest(req, bodyLimit);
+            if (requestTimeout > 0) {
+                // Race the handler against the timeout
+                const timeoutPromise = new Promise((resolve) => {
+                    const timer = setTimeout(() => {
+                        resolve({
+                            status: 504,
+                            body: {
+                                error: {
+                                    type: "GATEWAY_TIMEOUT",
+                                    message: `Request timed out after ${requestTimeout}ms`,
+                                },
+                            },
+                        });
+                    }, requestTimeout);
+                    // Unref so the timer doesn't keep the process alive during shutdown
+                    timer.unref();
+                });
+                const response = await Promise.race([
+                    handler(request),
+                    timeoutPromise,
+                ]);
+                sendResponse(res, response);
+            }
+            else {
+                const response = await handler(request);
+                sendResponse(res, response);
+            }
         }
         catch (error) {
             sendError(res, error);
@@ -65,12 +125,55 @@ export const createNodeHandler = (handler) => {
     };
 };
 export const startNodeServer = async (handler, options = {}) => {
-    const listener = createNodeHandler(handler);
+    const listener = createNodeHandler(handler, options);
     const server = createServer(listener);
     const port = options.port ?? 3000;
     const hostname = options.hostname ?? "0.0.0.0";
+    const gracefulShutdownTimeout = options.gracefulShutdownTimeout ?? DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT;
+    // Track in-flight requests for graceful shutdown
+    let inFlightRequests = 0;
+    let isDraining = false;
+    server.on("request", (_req, res) => {
+        inFlightRequests++;
+        if (isDraining) {
+            // Signal to the client that the connection will close
+            res.setHeader("connection", "close");
+        }
+        res.on("close", () => {
+            inFlightRequests--;
+        });
+    });
+    const gracefulStop = () => new Promise((resolve) => {
+        isDraining = true;
+        // Stop accepting new connections
+        server.close(() => {
+            resolve();
+        });
+        // If there are no in-flight requests, we're done once server.close completes
+        if (inFlightRequests === 0) {
+            return;
+        }
+        // Wait for in-flight requests, with a hard deadline
+        const deadline = setTimeout(() => {
+            if (!options.quiet) {
+                console.log(`[hypequery/serve] Forcing shutdown with ${inFlightRequests} in-flight request(s)`);
+            }
+            // Force-close all remaining connections
+            server.closeAllConnections();
+        }, gracefulShutdownTimeout);
+        deadline.unref();
+        // Also resolve early if all requests finish before the deadline
+        const checkInterval = setInterval(() => {
+            if (inFlightRequests <= 0) {
+                clearTimeout(deadline);
+                clearInterval(checkInterval);
+                // server.close callback will resolve the promise
+            }
+        }, 50);
+        checkInterval.unref();
+    });
     const onAbort = () => {
-        server.close();
+        gracefulStop();
     };
     if (options.signal) {
         if (options.signal.aborted) {
@@ -88,18 +191,8 @@ export const startNodeServer = async (handler, options = {}) => {
             : `${hostname}:${port}`;
         console.log(`hypequery serve listening on ${display}`);
     }
-    const stop = () => new Promise((resolve, reject) => {
-        server.close((err) => {
-            if (err) {
-                reject(err);
-            }
-            else {
-                resolve();
-            }
-        });
-    });
     return {
         server,
-        stop,
+        stop: gracefulStop,
     };
 };

package/dist/auth.d.ts

@@ -1,4 +1,23 @@
-import type { AuthContext, AuthContextWithRoles, AuthContextWithScopes, AuthStrategy, ServeMiddleware, ServeRequest } from "./types.js";
+import type { AuthContext, AuthContextWithRoles, AuthContextWithScopes, AuthStrategy, AuthErrorInfo, ServeMiddleware, ServeRequest } from "./types.js";
+/**
+ * Safely read a header from a ServeRequest with case-insensitive
+ * and array-safe normalization.
+ */
+export declare const getHeader: (request: ServeRequest, name: string) => string | undefined;
+export declare class AuthError extends Error implements AuthErrorInfo {
+    reason: AuthErrorInfo["reason"];
+    details?: Record<string, unknown>;
+    constructor(reason: AuthErrorInfo["reason"], message: string, details?: Record<string, unknown>);
+}
+export interface ApiKeyAuthOptions<TAuth extends AuthContext = AuthContext> {
+    header?: string;
+    allowMissing?: boolean;
+    validate: (key: string, request: ServeRequest) => Promise<TAuth | null> | TAuth | null;
+}
+/**
+ * Simple API key auth adapter with clear missing/invalid errors.
+ */
+export declare const apiKeyAuth: <TAuth extends AuthContext = AuthContext>(options: ApiKeyAuthOptions<TAuth>) => AuthStrategy<TAuth>;
 export interface ApiKeyStrategyOptions<TAuth extends AuthContext = AuthContext> {
     header?: string;
     queryParam?: string;
@@ -60,7 +79,7 @@ export declare const checkScopeAuthorization: (auth: AuthContext | null, require
  *
  * @deprecated Use `query.requireAuth()` instead for per-endpoint authentication.
  *             This middleware is kept for complex use cases where guards aren't suitable.
- *             See: https://hypequery.com/docs/serve/authentication#middleware-helpers
+ *             See: https://hypequery.com/docs/authentication#middleware-helpers
  *
  * Use this as a global middleware via `api.use(requireAuthMiddleware())`.
  * For per-query guards, prefer `query.requireAuth()`.
@@ -72,7 +91,7 @@ export declare const requireAuthMiddleware: <TContext extends Record<string, unk
  *
  * @deprecated Use `query.requireRole(...)` instead for per-endpoint authorization.
  *             This middleware is kept for complex use cases where guards aren't suitable.
- *             See: https://hypequery.com/docs/serve/authentication#middleware-helpers
+ *             See: https://hypequery.com/docs/authentication#middleware-helpers
  *
  * Use this as a global or per-query middleware via `api.use(requireRoleMiddleware('admin'))`.
  * For per-query guards, prefer `query.requireRole('admin')`.
@@ -84,7 +103,7 @@ export declare const requireRoleMiddleware: <TContext extends Record<string, unk
  *
  * @deprecated Use `query.requireScope(...)` instead for per-endpoint authorization.
  *             This middleware is kept for complex use cases where guards aren't suitable.
- *             See: https://hypequery.com/docs/serve/authentication#middleware-helpers
+ *             See: https://hypequery.com/docs/authentication#middleware-helpers
  *
  * Use this as a global or per-query middleware via `api.use(requireScopeMiddleware('read:metrics'))`.
  * For per-query guards, prefer `query.requireScope('read:metrics')`.
@@ -127,7 +146,7 @@ export type TypedAuthContext<TRoles extends string, TScopes extends string> = Au
  *
  * @example
  * ```ts
- * import { createAuthSystem, defineServe, query } from '@hypequery/serve';
+ * import { createAuthSystem, initServe } from '@hypequery/serve';
  *
  * // Define your roles and scopes up front
  * const { useAuth, TypedAuth } = createAuthSystem({
@@ -135,26 +154,36 @@ export type TypedAuthContext<TRoles extends string, TScopes extends string> = Au
  *   scopes: ['read:metrics', 'write:metrics', 'delete:metrics'] as const,
  * });
  *
- * // Extract the typed auth type for use with defineServe
+ * // Extract the typed auth type for use with initServe
  * type AppAuth = TypedAuth;
  *
- * const api = defineServe<AppAuth>({
+ * const { query, serve } = initServe<Record<string, never>, AppAuth>({
  *   auth: useAuth(jwtStrategy),
- *   queries: {
- *     adminOnly: query.requireRole('admin').query(async ({ ctx }) => {
- *       // ✅ TypeScript autocomplete for 'admin'
- *       // ❌ Compile error on typo like 'admn'
- *       return { secret: true };
- *     }),
- *     writeData: query.requireScope('write:metrics').query(async ({ ctx }) => {
- *       // ✅ TypeScript autocomplete for 'write:metrics'
- *       return { success: true };
- *     }),
+ * });
+ *
+ * const adminOnly = query({
+ *   requiredRoles: ['admin'],
+ *   query: async () => {
+ *     // ✅ TypeScript autocomplete for 'admin'
+ *     // ❌ Compile error on typo like 'admn'
+ *     return { secret: true };
  *   },
  * });
+ *
+ * const writeData = query({
+ *   requiredScopes: ['write:metrics'],
+ *   query: async () => {
+ *     // ✅ TypeScript autocomplete for 'write:metrics'
+ *     return { success: true };
+ *   },
+ * });
+ *
+ * const api = serve({
+ *   queries: { adminOnly, writeData },
+ * });
  * ```
  */
-export declare const createAuthSystem: <TRoles extends string = string, TScopes extends string = string>(options?: CreateAuthSystemOptions<TRoles, TScopes>) => {
+export declare const createAuthSystem: <TRoles extends string = string, TScopes extends string = string>() => {
     /**
      * Type-safe wrapper for auth strategies.
      * Ensures the strategy returns auth context with the correct role/scope types.

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;CACxF;AAED,eAAO,MAAM,oBAAoB,GAAI,KAAK,SAAS,WAAW,GAAG,WAAW,EAC1E,SAAS,qBAAqB,CAAC,KAAK,CAAC,KACpC,YAAY,CAAC,KAAK,CA0BpB,CAAC;AAEF,MAAM,WAAW,0BAA0B,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;CAC1F;AAED,eAAO,MAAM,yBAAyB,GAAI,KAAK,SAAS,WAAW,GAAG,WAAW,EAC/E,SAAS,0BAA0B,CAAC,KAAK,CAAC,KACzC,YAAY,CAAC,KAAK,CAepB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAAA;CAAE,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,WAAW,GAAG,IAAI,EACxB,eAAe,MAAM,EAAE,KACtB,mBAWF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,WAAW,GAAG,IAAI,EACxB,gBAAgB,MAAM,EAAE,KACvB,mBAWF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,OACpC,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAS3C,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EAEvC,GAAG,OAAO,MAAM,EAAE,KACjB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAUzC,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EAEvC,GAAG,QAAQ,MAAM,EAAE,KAClB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAUzC,CAAC;AAEJ;;;GAGG;AACH,MAAM,WAAW,uBAAuB,CACtC,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,OAAO,SAAS,MAAM,GAAG,MAAM;IAE/B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAC1B,MAAM,SAAS,MAAM,EACrB,OAAO,SAAS,MAAM,IACpB,oBAAoB,CAAC,MAAM,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,OAAO,SAAS,MAAM,GAAG,MAAM,EAE/B,UAAS,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAM;IAGpD;;;;;;;;;;;;;;;;;;;;;OAqBG;cACO,KAAK,SAAS,WAAW,YACvB,YAAY,CAAC,KAAK,CAAC,KAC5B,YAAY,CAAC,KAAK,CAAC;IAEtB;;;;;;;;OAQG;eAC2B,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC;CAElE,CAAC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AAWpB;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,YAAY,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAexE,CAAC;AAEF,qBAAa,SAAU,SAAQ,KAAM,YAAW,aAAa;IAC3D,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtB,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMhG;AAED,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;CACxF;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,SAAS,WAAW,GAAG,WAAW,EAChE,SAAS,iBAAiB,CAAC,KAAK,CAAC,KAChC,YAAY,CAAC,KAAK,CAiBpB,CAAC;AAEF,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;CACxF;AAED,eAAO,MAAM,oBAAoB,GAAI,KAAK,SAAS,WAAW,GAAG,WAAW,EAC1E,SAAS,qBAAqB,CAAC,KAAK,CAAC,KACpC,YAAY,CAAC,KAAK,CA0BpB,CAAC;AAEF,MAAM,WAAW,0BAA0B,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;CAC1F;AAED,eAAO,MAAM,yBAAyB,GAAI,KAAK,SAAS,WAAW,GAAG,WAAW,EAC/E,SAAS,0BAA0B,CAAC,KAAK,CAAC,KACzC,YAAY,CAAC,KAAK,CAepB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,eAAe,CAAA;CAAE,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,WAAW,GAAG,IAAI,EACxB,eAAe,MAAM,EAAE,KACtB,mBAWF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,WAAW,GAAG,IAAI,EACxB,gBAAgB,MAAM,EAAE,KACvB,mBAWF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,OACpC,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAS3C,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EAEvC,GAAG,OAAO,MAAM,EAAE,KACjB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAUzC,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EAEvC,GAAG,QAAQ,MAAM,EAAE,KAClB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAUzC,CAAC;AAEJ;;;GAGG;AACH,MAAM,WAAW,uBAAuB,CACtC,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,OAAO,SAAS,MAAM,GAAG,MAAM;IAE/B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAC1B,MAAM,SAAS,MAAM,EACrB,OAAO,SAAS,MAAM,IACpB,oBAAoB,CAAC,MAAM,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,SAAS,MAAM,GAAG,MAAM,EAC9B,OAAO,SAAS,MAAM,GAAG,MAAM;IAG7B;;;;;;;;;;;;;;;;;;;;;OAqBG;cACO,KAAK,SAAS,WAAW,YACvB,YAAY,CAAC,KAAK,CAAC,KAC5B,YAAY,CAAC,KAAK,CAAC;IAEtB;;;;;;;;OAQG;eAC2B,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC;CAElE,CAAC"}

package/dist/auth.js

@@ -1,3 +1,60 @@
+const resolveHeaderValue = (value) => {
+    if (Array.isArray(value)) {
+        const first = value.find((item) => typeof item === "string");
+        return typeof first === "string" ? first : undefined;
+    }
+    if (typeof value === "string")
+        return value;
+    return undefined;
+};
+/**
+ * Safely read a header from a ServeRequest with case-insensitive
+ * and array-safe normalization.
+ */
+export const getHeader = (request, name) => {
+    const target = name.toLowerCase();
+    const headers = request.headers;
+    const direct = headers[target] ?? headers[name] ?? headers[name.toLowerCase()];
+    const resolvedDirect = resolveHeaderValue(direct);
+    if (resolvedDirect !== undefined) {
+        const trimmed = resolvedDirect.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    const match = Object.entries(headers).find(([key]) => key.toLowerCase() === target);
+    const resolvedMatch = resolveHeaderValue(match?.[1]);
+    if (resolvedMatch === undefined)
+        return undefined;
+    const trimmed = resolvedMatch.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+};
+export class AuthError extends Error {
+    constructor(reason, message, details) {
+        super(message);
+        this.name = "AuthError";
+        this.reason = reason;
+        this.details = details;
+    }
+}
+/**
+ * Simple API key auth adapter with clear missing/invalid errors.
+ */
+export const apiKeyAuth = (options) => {
+    const headerName = options.header ?? "x-api-key";
+    const allowMissing = options.allowMissing ?? false;
+    return async ({ request }) => {
+        const key = getHeader(request, headerName);
+        if (!key) {
+            if (allowMissing)
+                return null;
+            throw new AuthError("MISSING", `Missing API key in "${headerName}" header`, { header: headerName });
+        }
+        const auth = await options.validate(key, request);
+        if (!auth) {
+            throw new AuthError("INVALID", `Invalid API key in "${headerName}" header`, { header: headerName });
+        }
+        return auth;
+    };
+};
 export const createApiKeyStrategy = (options) => {
     const headerName = options.header ?? "authorization";
     const queryParam = options.queryParam;
@@ -7,8 +64,8 @@ export const createApiKeyStrategy = (options) => {
             key = request.query[queryParam];
         }
         if (!key) {
-            const headerValue = request.headers[headerName] ?? request.headers[headerName.toLowerCase()];
-            if (typeof headerValue === "string") {
+            const headerValue = getHeader(request, headerName);
+            if (headerValue) {
                 key = headerValue.startsWith("Bearer ")
                     ? headerValue.slice("Bearer ".length)
                     : headerValue;
@@ -24,7 +81,7 @@ export const createBearerTokenStrategy = (options) => {
     const headerName = options.header ?? "authorization";
     const prefix = options.prefix ?? "Bearer ";
     return async ({ request }) => {
-        const raw = request.headers[headerName] ?? request.headers[headerName.toLowerCase()];
+        const raw = getHeader(request, headerName);
         if (typeof raw !== "string" || !raw.startsWith(prefix)) {
             return null;
         }
@@ -95,7 +152,7 @@ export const checkScopeAuthorization = (auth, requiredScopes) => {
  *
  * @deprecated Use `query.requireAuth()` instead for per-endpoint authentication.
  *             This middleware is kept for complex use cases where guards aren't suitable.
- *             See: https://hypequery.com/docs/serve/authentication#middleware-helpers
+ *             See: https://hypequery.com/docs/authentication#middleware-helpers
  *
  * Use this as a global middleware via `api.use(requireAuthMiddleware())`.
  * For per-query guards, prefer `query.requireAuth()`.
@@ -115,7 +172,7 @@ export const requireAuthMiddleware = () => async (ctx, next) => {
  *
  * @deprecated Use `query.requireRole(...)` instead for per-endpoint authorization.
  *             This middleware is kept for complex use cases where guards aren't suitable.
- *             See: https://hypequery.com/docs/serve/authentication#middleware-helpers
+ *             See: https://hypequery.com/docs/authentication#middleware-helpers
  *
  * Use this as a global or per-query middleware via `api.use(requireRoleMiddleware('admin'))`.
  * For per-query guards, prefer `query.requireRole('admin')`.
@@ -133,7 +190,7 @@ export const requireRoleMiddleware = (...roles) => async (ctx, next) => {
  *
  * @deprecated Use `query.requireScope(...)` instead for per-endpoint authorization.
  *             This middleware is kept for complex use cases where guards aren't suitable.
- *             See: https://hypequery.com/docs/serve/authentication#middleware-helpers
+ *             See: https://hypequery.com/docs/authentication#middleware-helpers
  *
  * Use this as a global or per-query middleware via `api.use(requireScopeMiddleware('read:metrics'))`.
  * For per-query guards, prefer `query.requireScope('read:metrics')`.
@@ -155,7 +212,7 @@ export const requireScopeMiddleware = (...scopes) => async (ctx, next) => {
  *
  * @example
  * ```ts
- * import { createAuthSystem, defineServe, query } from '@hypequery/serve';
+ * import { createAuthSystem, initServe } from '@hypequery/serve';
  *
  * // Define your roles and scopes up front
  * const { useAuth, TypedAuth } = createAuthSystem({
@@ -163,26 +220,36 @@ export const requireScopeMiddleware = (...scopes) => async (ctx, next) => {
  *   scopes: ['read:metrics', 'write:metrics', 'delete:metrics'] as const,
  * });
  *
- * // Extract the typed auth type for use with defineServe
+ * // Extract the typed auth type for use with initServe
  * type AppAuth = TypedAuth;
  *
- * const api = defineServe<AppAuth>({
+ * const { query, serve } = initServe<Record<string, never>, AppAuth>({
  *   auth: useAuth(jwtStrategy),
- *   queries: {
- *     adminOnly: query.requireRole('admin').query(async ({ ctx }) => {
- *       // ✅ TypeScript autocomplete for 'admin'
- *       // ❌ Compile error on typo like 'admn'
- *       return { secret: true };
- *     }),
- *     writeData: query.requireScope('write:metrics').query(async ({ ctx }) => {
- *       // ✅ TypeScript autocomplete for 'write:metrics'
- *       return { success: true };
- *     }),
+ * });
+ *
+ * const adminOnly = query({
+ *   requiredRoles: ['admin'],
+ *   query: async () => {
+ *     // ✅ TypeScript autocomplete for 'admin'
+ *     // ❌ Compile error on typo like 'admn'
+ *     return { secret: true };
  *   },
  * });
+ *
+ * const writeData = query({
+ *   requiredScopes: ['write:metrics'],
+ *   query: async () => {
+ *     // ✅ TypeScript autocomplete for 'write:metrics'
+ *     return { success: true };
+ *   },
+ * });
+ *
+ * const api = serve({
+ *   queries: { adminOnly, writeData },
+ * });
  * ```
  */
-export const createAuthSystem = (options = {}) => {
+export const createAuthSystem = () => {
     return {
         /**
          * Type-safe wrapper for auth strategies.

package/dist/cors.d.ts

@@ -0,0 +1,17 @@
+import type { CorsConfig, ServeRequest, ServeResponse } from './types.js';
+export interface ResolvedCorsConfig {
+    origin: string | string[] | ((origin: string) => boolean);
+    methods: string[];
+    allowedHeaders: string[];
+    exposedHeaders: string[];
+    credentials: boolean;
+    maxAge: number;
+}
+export declare const resolveCorsConfig: (config: boolean | CorsConfig | undefined) => ResolvedCorsConfig | null;
+export declare const buildCorsHeaders: (config: ResolvedCorsConfig, requestOrigin: string | undefined) => Record<string, string>;
+export declare const buildPreflightHeaders: (config: ResolvedCorsConfig, requestOrigin: string | undefined) => Record<string, string>;
+export declare const handleCorsRequest: (config: ResolvedCorsConfig | null, request: ServeRequest) => {
+    preflightResponse: ServeResponse | null;
+    corsHeaders: Record<string, string>;
+};
+//# sourceMappingURL=cors.d.ts.map

package/dist/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAM1E,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,OAAO,GAAG,UAAU,GAAG,SAAS,KACvC,kBAAkB,GAAG,IAavB,CAAC;AA8BF,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,kBAAkB,EAC1B,eAAe,MAAM,GAAG,SAAS,KAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAqBvB,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,QAAQ,kBAAkB,EAC1B,eAAe,MAAM,GAAG,SAAS,KAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,kBAAkB,GAAG,IAAI,EACjC,SAAS,YAAY,KACpB;IAAE,iBAAiB,EAAE,aAAa,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAsBhF,CAAC"}

package/dist/cors.js

@@ -0,0 +1,82 @@
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+const DEFAULT_ALLOWED_HEADERS = ['Content-Type', 'Authorization', 'X-Request-ID'];
+const DEFAULT_MAX_AGE = 86400; // 24 hours
+export const resolveCorsConfig = (config) => {
+    if (!config)
+        return null;
+    const opts = config === true ? {} : config;
+    return {
+        origin: opts.origin ?? '*',
+        methods: opts.methods ?? DEFAULT_METHODS,
+        allowedHeaders: opts.allowedHeaders ?? DEFAULT_ALLOWED_HEADERS,
+        exposedHeaders: opts.exposedHeaders ?? [],
+        credentials: opts.credentials ?? false,
+        maxAge: opts.maxAge ?? DEFAULT_MAX_AGE,
+    };
+};
+const matchOrigin = (config, requestOrigin) => {
+    if (!requestOrigin)
+        return null;
+    const { origin } = config;
+    if (origin === '*') {
+        // When credentials are enabled, we must echo the origin instead of "*"
+        return config.credentials ? requestOrigin : '*';
+    }
+    if (typeof origin === 'string') {
+        return origin === requestOrigin ? origin : null;
+    }
+    if (Array.isArray(origin)) {
+        return origin.includes(requestOrigin) ? requestOrigin : null;
+    }
+    if (typeof origin === 'function') {
+        return origin(requestOrigin) ? requestOrigin : null;
+    }
+    return null;
+};
+export const buildCorsHeaders = (config, requestOrigin) => {
+    const headers = {};
+    const allowedOrigin = matchOrigin(config, requestOrigin);
+    if (!allowedOrigin)
+        return headers;
+    headers['access-control-allow-origin'] = allowedOrigin;
+    if (allowedOrigin !== '*') {
+        headers['vary'] = 'Origin';
+    }
+    if (config.credentials) {
+        headers['access-control-allow-credentials'] = 'true';
+    }
+    if (config.exposedHeaders.length > 0) {
+        headers['access-control-expose-headers'] = config.exposedHeaders.join(', ');
+    }
+    return headers;
+};
+export const buildPreflightHeaders = (config, requestOrigin) => {
+    const headers = buildCorsHeaders(config, requestOrigin);
+    // No matching origin → don't add preflight headers
+    if (!headers['access-control-allow-origin'])
+        return headers;
+    headers['access-control-allow-methods'] = config.methods.join(', ');
+    headers['access-control-allow-headers'] = config.allowedHeaders.join(', ');
+    headers['access-control-max-age'] = String(config.maxAge);
+    return headers;
+};
+export const handleCorsRequest = (config, request) => {
+    if (!config) {
+        return { preflightResponse: null, corsHeaders: {} };
+    }
+    const requestOrigin = request.headers['origin'];
+    if (request.method === 'OPTIONS') {
+        return {
+            preflightResponse: {
+                status: 204,
+                headers: buildPreflightHeaders(config, requestOrigin),
+                body: '',
+            },
+            corsHeaders: {},
+        };
+    }
+    return {
+        preflightResponse: null,
+        corsHeaders: buildCorsHeaders(config, requestOrigin),
+    };
+};

package/dist/dev.js

@@ -7,7 +7,7 @@ export const serveDev = async (api, options = {}) => {
     const port = options.port ?? Number(process.env.PORT ?? 4000);
     const hostname = options.hostname ?? "localhost";
     const logger = options.logger ?? defaultLogger;
-    const unsubscribe = api.queryLogger.on((event) => {
+    api.queryLogger.on((event) => {
         const line = formatQueryEvent(event);
         if (line)
             logger(line);

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+import type { ServeErrorType } from './types.js';
+/**
+ * Structured error class for hypequery serve handlers and middleware.
+ *
+ * Throw this from a handler or middleware to return a specific HTTP status
+ * and error type to the client. The pipeline catch block recognises the
+ * `status` + `payload` shape and forwards it as-is.
+ *
+ * @example
+ * ```ts
+ * throw new ServeHttpError(403, 'UNAUTHORIZED', 'Insufficient permissions');
+ * throw new ServeHttpError(429, 'RATE_LIMITED', 'Too fast', { 'retry-after': '60' });
+ * ```
+ */
+export declare class ServeHttpError extends Error {
+    readonly status: number;
+    readonly payload: {
+        type: ServeErrorType;
+        message: string;
+    };
+    readonly headers?: Record<string, string>;
+    constructor(status: number, type: ServeErrorType, message: string, headers?: Record<string, string>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAGxC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAQnC"}

package/dist/errors.js

@@ -0,0 +1,22 @@
+/**
+ * Structured error class for hypequery serve handlers and middleware.
+ *
+ * Throw this from a handler or middleware to return a specific HTTP status
+ * and error type to the client. The pipeline catch block recognises the
+ * `status` + `payload` shape and forwards it as-is.
+ *
+ * @example
+ * ```ts
+ * throw new ServeHttpError(403, 'UNAUTHORIZED', 'Insufficient permissions');
+ * throw new ServeHttpError(429, 'RATE_LIMITED', 'Too fast', { 'retry-after': '60' });
+ * ```
+ */
+export class ServeHttpError extends Error {
+    constructor(status, type, message, headers) {
+        super(message);
+        this.name = 'ServeHttpError';
+        this.status = status;
+        this.payload = { type, message };
+        this.headers = headers;
+    }
+}

package/dist/index.d.ts

@@ -6,10 +6,14 @@ export * from "./endpoint.js";
 export * from "./openapi.js";
 export * from "./docs-ui.js";
 export * from "./auth.js";
+export * from "./cors.js";
+export * from "./errors.js";
+export * from "./rate-limit.js";
 export * from "./client-config.js";
 export * from "./utils.js";
 export * from "./adapters/node.js";
 export * from "./adapters/fetch.js";
 export * from "./adapters/vercel.js";
 export * from "./dev.js";
+export * from "./serve.js";
 //# sourceMappingURL=index.d.ts.map