@spfn/core 0.2.0-beta.9 → 0.3.0-beta.1

package/dist/route/index.js

@@ -11,6 +11,7 @@ var RouteBuilder = class _RouteBuilder {
   _interceptor;
   _middlewares;
   _skipMiddlewares;
+  _contract;
   /**
    * Create a new RouteBuilder with copied properties and optional overrides
    */
@@ -22,6 +23,7 @@ var RouteBuilder = class _RouteBuilder {
     builder._interceptor = overrides?.interceptor ?? this._interceptor;
     builder._middlewares = overrides?.middlewares ?? this._middlewares;
     builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
+    builder._contract = overrides?.contract ?? this._contract;
     return builder;
   }
   /**
@@ -159,6 +161,39 @@ var RouteBuilder = class _RouteBuilder {
   skip(middlewareNames) {
     return this.clone({ skipMiddlewares: middlewareNames });
   }
+  /**
+   * Publish this route as a versioned contract operation
+   *
+   * Marks the route as a promise to clients that are compiled and deployed
+   * separately from the server — a mobile app, an external API consumer.
+   * The `@spfn/core:contract` generator writes every contracted route into
+   * `contracts/current.json`, and the build refuses a change that would break
+   * an already-released client.
+   *
+   * Routes without `.contract()` are unaffected: they simply do not appear in
+   * the contract. A web client needs nothing here — it derives its types from
+   * the router in the same build.
+   *
+   * @example
+   * ```ts
+   * export const getUser = route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .contract({
+   *     since: '1.2.0',
+   *     auth: 'clientProofV1',
+   *     requiresSession: true,
+   *     response: Type.Object({
+   *       id: Type.String(),
+   *       name: Type.String(),
+   *       email: Type.Optional(Type.String()),
+   *     }),
+   *   })
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  contract(contract) {
+    return this.clone({ contract });
+  }
   /**
    * Define handler function
    *
@@ -213,6 +248,7 @@ var RouteBuilder = class _RouteBuilder {
       interceptor: this._interceptor,
       middlewares: this._middlewares,
       skipMiddlewares: this._skipMiddlewares,
+      contract: this._contract,
       handler: fn,
       _input: {},
       _interceptor: {},
@@ -237,12 +273,13 @@ var route = {
 };
 
 // src/route/router.ts
-function createRouterInstance(routes, packageRouters = [], globalMiddlewares = []) {
+function createRouterInstance(routes, packageRouters = [], globalMiddlewares = [], contractVersion = null) {
   return {
     routes,
     _routes: routes,
     _packageRouters: packageRouters,
     _globalMiddlewares: globalMiddlewares,
+    _contractVersion: contractVersion,
     packages(routers) {
       const newPackageRouters = [...this._packageRouters, ...routers];
       for (const pkgRouter of routers) {
@@ -250,13 +287,39 @@ function createRouterInstance(routes, packageRouters = [], globalMiddlewares = [
           newPackageRouters.push(...pkgRouter._packageRouters);
         }
       }
-      return createRouterInstance(this.routes, newPackageRouters, this._globalMiddlewares);
+      return createRouterInstance(
+        this.routes,
+        newPackageRouters,
+        this._globalMiddlewares,
+        this._contractVersion
+      );
     },
     use(middlewares) {
-      return createRouterInstance(this.routes, this._packageRouters, [...this._globalMiddlewares, ...middlewares]);
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        [...this._globalMiddlewares, ...middlewares],
+        this._contractVersion
+      );
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        this._globalMiddlewares,
+        version
+      );
     }
   };
 }
+function assertContractVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(version)) {
+    throw new Error(
+      `contractVersion("${version}") is not a version of the form major.minor.patch. The released snapshot is named from this value and releases are compared by it.`
+    );
+  }
+}
 function defineRouter(routes) {
   return createRouterInstance(routes);
 }
@@ -575,7 +638,7 @@ function registerRoutes(app, router, namedMiddlewares, collectedRoutes) {
   return routes;
 }
 function registerRoute(app, name, routeDef, namedMiddlewares) {
-  const { method, path, input, middlewares = [], skipMiddlewares, handler } = routeDef;
+  const { method, path, input, interceptor, middlewares = [], skipMiddlewares, handler } = routeDef;
   if (!method || !path) {
     logger.warn(`Route "${name}" is missing method or path - skipping`, {
       method,
@@ -584,7 +647,7 @@ function registerRoute(app, name, routeDef, namedMiddlewares) {
     return null;
   }
   const wrappedHandler = async (c) => {
-    const { context, responseMeta } = await createRouteBuilderContext(c, input || {});
+    const { context, responseMeta } = await createRouteBuilderContext(c, input || {}, interceptor);
     const result = await handler(context);
     if (result instanceof Response) {
       return result;
@@ -602,18 +665,30 @@ function registerRoute(app, name, routeDef, namedMiddlewares) {
   const registeredNames = /* @__PURE__ */ new Set();
   const registeredHandlers = /* @__PURE__ */ new Set();
   const skipAll = skipMiddlewares === "*";
+  const autoSkips = /* @__PURE__ */ new Set();
+  for (const mw of middlewares) {
+    if (isNamedMiddleware(mw) && mw.skips) {
+      for (const skipName of mw.skips) {
+        autoSkips.add(skipName);
+      }
+    }
+  }
   if (namedMiddlewares && namedMiddlewares.length > 0) {
     if (skipAll) {
       logger.debug(`\u23ED\uFE0F  Skipping all middlewares (*) for route: ${method} ${path}`, { name });
     } else {
       const skipSet = new Set(Array.isArray(skipMiddlewares) ? skipMiddlewares : []);
       for (const middleware of namedMiddlewares) {
-        if (!skipSet.has(middleware.name)) {
+        if (skipSet.has(middleware.name)) {
+          logger.debug(`\u23ED\uFE0F  Skipping middleware '${middleware.name}' for route: ${method} ${path}`, { name });
+        } else if (autoSkips.has(middleware.name)) {
+          logger.debug(`\u23ED\uFE0F  Auto-skipping middleware '${middleware.name}' for route: ${method} ${path}`, { name });
+        } else if (middleware.name && registeredNames.has(middleware.name)) {
+          logger.debug(`\u{1F504} Skipping duplicate middleware '${middleware.name}' for route: ${method} ${path}`, { name });
+        } else {
           allMiddlewares.push(middleware.handler);
           registeredNames.add(middleware.name);
           registeredHandlers.add(middleware.handler);
-        } else {
-          logger.debug(`\u23ED\uFE0F  Skipping middleware '${middleware.name}' for route: ${method} ${path}`, { name });
         }
       }
     }
@@ -636,29 +711,32 @@ function registerRoute(app, name, routeDef, namedMiddlewares) {
     }
   }
   const methodLower = method.toLowerCase();
-  if (allMiddlewares.length > 0) {
-    app[methodLower](path, ...allMiddlewares, wrappedHandler);
-  } else {
-    app[methodLower](path, wrappedHandler);
-  }
+  const handlers = [...allMiddlewares, wrappedHandler];
+  app.on([methodLower], [path], ...handlers);
   logger.debug(`Registered route: ${method} ${path}`, { name });
   return { method, path, name };
 }
-async function createRouteBuilderContext(c, input) {
+function methodCarriesBody(method) {
+  return method !== "GET" && method !== "HEAD";
+}
+async function createRouteBuilderContext(c, input, interceptor) {
   const params = validateField(input.params, c.req.param(), "path parameters");
   const query = validateField(input.query, extractQueryParams(c), "query parameters");
   const headers = validateField(input.headers, extractHeaders(c), "headers");
   const cookies = validateField(input.cookies, extractCookies(c), "cookies");
   let body = {};
   let formData = {};
-  if (input.body || input.formData) {
+  const injected = methodCarriesBody(c.req.method) ? interceptor : void 0;
+  const expectsBody = input.body ?? injected?.body;
+  const expectsFormData = input.formData ?? injected?.formData;
+  if (expectsBody || expectsFormData) {
     const contentType = c.req.header("content-type") || "";
-    if (contentType.includes("multipart/form-data") && input.formData) {
+    if (contentType.includes("multipart/form-data") && expectsFormData) {
       const rawFormData = await parseFormData(c);
-      formData = validateFormData(input.formData, rawFormData, "form data");
-    } else if (input.body) {
+      formData = input.formData ? validateFormData(input.formData, rawFormData, "form data") : rawFormData;
+    } else if (expectsBody) {
       const rawBody = await parseJsonBody(c);
-      body = validateField(input.body, rawBody, "request body");
+      body = input.body ? validateField(input.body, rawBody, "request body") : rawBody;
     }
   }
   let cachedData = null;
@@ -720,14 +798,16 @@ async function createRouteBuilderContext(c, input) {
 }
 
 // src/route/define-middleware.ts
-function defineMiddleware(name, handlerOrFactory) {
+function defineMiddleware(name, handlerOrFactory, options) {
+  const skips = options?.skips;
   if (typeof handlerOrFactory === "function") {
     const paramCount = handlerOrFactory.length;
     if (paramCount === 2) {
       return {
         name,
         handler: handlerOrFactory,
-        _name: name
+        _name: name,
+        ...skips && { skips }
       };
     } else {
       const factory = handlerOrFactory;
@@ -744,13 +824,22 @@ function defineMiddleware(name, handlerOrFactory) {
         enumerable: false,
         configurable: true
       });
+      if (skips) {
+        Object.defineProperty(wrapper, "skips", {
+          value: skips,
+          writable: false,
+          enumerable: false,
+          configurable: true
+        });
+      }
       return wrapper;
     }
   }
   return {
     name,
     handler: handlerOrFactory,
-    _name: name
+    _name: name,
+    ...skips && { skips }
   };
 }
 function defineMiddlewareFactory(name, factory) {