@spfn/core 0.2.0-beta.4 → 0.2.0-beta.42

package/dist/route/index.d.ts

@@ -1,5 +1,5 @@
 import * as _sinclair_typebox from '@sinclair/typebox';
-import { TSchema, Static } from '@sinclair/typebox';
+import { TSchema, Static, Kind } from '@sinclair/typebox';
 import { Context, MiddlewareHandler, Hono } from 'hono';
 import { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
 import { HttpMethod } from './types.js';
@@ -22,6 +22,8 @@ type RouteInput = {
     query?: TSchema;
     /** Request body (JSON) */
     body?: TSchema;
+    /** Form data (multipart/form-data) for file uploads */
+    formData?: TSchema;
     /** HTTP headers */
     headers?: TSchema;
     /** Cookies */
@@ -61,6 +63,7 @@ type MergedInput<TInput extends RouteInput, TInterceptor extends RouteInput> = {
     params: (TInput['params'] extends TSchema ? Static<TInput['params']> : {}) & (TInterceptor['params'] extends TSchema ? Static<TInterceptor['params']> : {});
     query: (TInput['query'] extends TSchema ? Static<TInput['query']> : {}) & (TInterceptor['query'] extends TSchema ? Static<TInterceptor['query']> : {});
     body: (TInput['body'] extends TSchema ? Static<TInput['body']> : {}) & (TInterceptor['body'] extends TSchema ? Static<TInterceptor['body']> : {});
+    formData: (TInput['formData'] extends TSchema ? Static<TInput['formData']> : {}) & (TInterceptor['formData'] extends TSchema ? Static<TInterceptor['formData']> : {});
     headers: (TInput['headers'] extends TSchema ? Static<TInput['headers']> : {}) & (TInterceptor['headers'] extends TSchema ? Static<TInterceptor['headers']> : {});
     cookies: (TInput['cookies'] extends TSchema ? Static<TInput['cookies']> : {}) & (TInterceptor['cookies'] extends TSchema ? Static<TInterceptor['cookies']> : {});
 };
@@ -233,6 +236,7 @@ type NamedMiddleware<TName extends string = string> = {
     name: TName;
     handler: MiddlewareHandler;
     _name: TName;
+    skips?: string[];
 };
 /**
  * Named middleware factory with type inference
@@ -307,8 +311,27 @@ type NamedMiddlewareFactory<TName extends string = string, TArgs extends any[] =
  *   .handler(async (c) => { ... });
  * ```
  */
-declare function defineMiddleware<TName extends string>(name: TName, handler: MiddlewareHandler): NamedMiddleware<TName>;
-declare function defineMiddleware<TName extends string, TArgs extends any[]>(name: TName, factory: (...args: TArgs) => MiddlewareHandler): NamedMiddlewareFactory<TName, TArgs>;
+/**
+ * Options for defineMiddleware
+ */
+interface DefineMiddlewareOptions {
+    /**
+     * Server-level middleware names to auto-skip when this middleware is used at route level.
+     *
+     * @example
+     * ```ts
+     * // optionalAuth auto-skips the global 'auth' middleware
+     * export const optionalAuth = defineMiddleware('optionalAuth', handler, {
+     *     skips: ['auth']
+     * });
+     *
+     * // Usage: .use([optionalAuth]) — no need for .skip(['auth'])
+     * ```
+     */
+    skips?: string[];
+}
+declare function defineMiddleware<TName extends string>(name: TName, handler: MiddlewareHandler, options?: DefineMiddlewareOptions): NamedMiddleware<TName>;
+declare function defineMiddleware<TName extends string, TArgs extends any[]>(name: TName, factory: (...args: TArgs) => MiddlewareHandler, options?: DefineMiddlewareOptions): NamedMiddlewareFactory<TName, TArgs>;
 /**
  * Define a middleware factory explicitly
  *
@@ -757,4 +780,135 @@ declare const Nullable: <T extends TSchema>(schema: T) => _sinclair_typebox.TUni
  */
 declare const OptionalNullable: <T extends TSchema>(schema: T) => _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[T, _sinclair_typebox.TNull]>>;
 
-export { type ExtractMiddlewareNames, HttpMethod, type MergedInput, type NamedMiddleware, type NamedMiddlewareFactory, Nullable, OptionalNullable, type PaginatedResult, type RegisteredRoute, type RouteBuilderContext, type RouteDef, type RouteHandlerFn, type RouteInput, type Router, defineMiddleware, defineMiddlewareFactory, defineRouter, isHttpMethod, registerRoutes, route };
+/**
+ * File Schema Helpers for TypeBox
+ *
+ * Provides TypeBox schema definitions for file upload handling
+ * with optional validation constraints.
+ */
+
+/**
+ * File validation options
+ */
+interface FileSchemaOptions {
+    /**
+     * Maximum file size in bytes
+     *
+     * @example 5 * 1024 * 1024 // 5MB
+     */
+    maxSize?: number;
+    /**
+     * Allowed MIME types
+     *
+     * @example ['image/jpeg', 'image/png', 'image/webp']
+     */
+    allowedTypes?: string[];
+    /**
+     * Minimum file size in bytes (optional)
+     *
+     * @example 1024 // 1KB minimum
+     */
+    minSize?: number;
+}
+/**
+ * File array validation options
+ */
+interface FileArraySchemaOptions extends FileSchemaOptions {
+    /**
+     * Maximum number of files
+     *
+     * @example 5
+     */
+    maxFiles?: number;
+    /**
+     * Minimum number of files (optional)
+     *
+     * @example 1
+     */
+    minFiles?: number;
+}
+/**
+ * Internal schema type with file validation metadata
+ */
+interface FileSchemaType extends TSchema {
+    [Kind]: 'File';
+    fileOptions?: FileSchemaOptions;
+}
+interface FileArraySchemaType extends TSchema {
+    [Kind]: 'FileArray';
+    fileOptions?: FileArraySchemaOptions;
+}
+/**
+ * Create a File schema with optional validation
+ *
+ * @example
+ * ```ts
+ * // Basic usage (no validation)
+ * formData: Type.Object({
+ *     file: FileSchema()
+ * })
+ *
+ * // With validation
+ * formData: Type.Object({
+ *     avatar: FileSchema({
+ *         maxSize: 5 * 1024 * 1024,  // 5MB
+ *         allowedTypes: ['image/jpeg', 'image/png', 'image/webp']
+ *     })
+ * })
+ * ```
+ */
+declare function FileSchema(options?: FileSchemaOptions): FileSchemaType;
+/**
+ * Create a File array schema with optional validation
+ *
+ * @example
+ * ```ts
+ * // Basic usage (no validation)
+ * formData: Type.Object({
+ *     files: FileArraySchema()
+ * })
+ *
+ * // With validation
+ * formData: Type.Object({
+ *     documents: FileArraySchema({
+ *         maxSize: 10 * 1024 * 1024,  // 10MB per file
+ *         maxFiles: 5,
+ *         allowedTypes: ['application/pdf', 'application/msword']
+ *     })
+ * })
+ * ```
+ */
+declare function FileArraySchema(options?: FileArraySchemaOptions): FileArraySchemaType;
+/**
+ * Create an optional File schema with validation
+ *
+ * @example
+ * ```ts
+ * formData: Type.Object({
+ *     name: Type.String(),
+ *     avatar: OptionalFileSchema({
+ *         maxSize: 2 * 1024 * 1024,
+ *         allowedTypes: ['image/jpeg', 'image/png']
+ *     })
+ * })
+ * ```
+ */
+declare function OptionalFileSchema(options?: FileSchemaOptions): TSchema;
+/**
+ * Check if a schema is a File schema
+ */
+declare function isFileSchema(schema: TSchema): schema is FileSchemaType;
+/**
+ * Check if a schema is a FileArray schema
+ */
+declare function isFileArraySchema(schema: TSchema): schema is FileArraySchemaType;
+/**
+ * Get file options from schema
+ */
+declare function getFileOptions(schema: TSchema): FileSchemaOptions | FileArraySchemaOptions | undefined;
+/**
+ * Format file size for error messages
+ */
+declare function formatFileSize(bytes: number): string;
+
+export { type ExtractMiddlewareNames, FileArraySchema, type FileArraySchemaOptions, type FileArraySchemaType, FileSchema, type FileSchemaOptions, type FileSchemaType, HttpMethod, type MergedInput, type NamedMiddleware, type NamedMiddlewareFactory, Nullable, OptionalFileSchema, OptionalNullable, type PaginatedResult, type RegisteredRoute, type RouteBuilderContext, type RouteDef, type RouteHandlerFn, type RouteInput, type Router, defineMiddleware, defineMiddlewareFactory, defineRouter, formatFileSize, getFileOptions, isFileArraySchema, isFileSchema, isHttpMethod, registerRoutes, route };

package/dist/route/index.js

@@ -1,7 +1,7 @@
 import { logger } from '@spfn/core/logger';
+import { FormatRegistry, Type, Kind } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
 import { ValidationError } from '@spfn/core/errors';
-import { Type } from '@sinclair/typebox';
 
 // src/route/route-builder.ts
 var RouteBuilder = class _RouteBuilder {
@@ -260,6 +260,108 @@ function createRouterInstance(routes, packageRouters = [], globalMiddlewares = [
 function defineRouter(routes) {
   return createRouterInstance(routes);
 }
+function FileSchema(options) {
+  return Type.Unsafe({
+    [Kind]: "File",
+    type: "object",
+    fileOptions: options
+  });
+}
+function FileArraySchema(options) {
+  return Type.Unsafe({
+    [Kind]: "FileArray",
+    type: "array",
+    items: { [Kind]: "File", type: "object" },
+    fileOptions: options
+  });
+}
+function OptionalFileSchema(options) {
+  return Type.Optional(FileSchema(options));
+}
+function isFileSchema(schema) {
+  const kind = schema[Symbol.for("TypeBox.Kind")];
+  return kind === "File";
+}
+function isFileArraySchema(schema) {
+  const kind = schema[Symbol.for("TypeBox.Kind")];
+  return kind === "FileArray";
+}
+function getFileOptions(schema) {
+  return schema.fileOptions;
+}
+function formatFileSize(bytes) {
+  if (bytes >= 1024 * 1024 * 1024) {
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+  }
+  if (bytes >= 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  }
+  if (bytes >= 1024) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  }
+  return `${bytes}B`;
+}
+
+// src/route/validation.ts
+FormatRegistry.Set(
+  "email",
+  (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+);
+FormatRegistry.Set(
+  "uri",
+  (value) => /^https?:\/\/.+/.test(value)
+);
+FormatRegistry.Set(
+  "uuid",
+  (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+);
+FormatRegistry.Set(
+  "date",
+  (value) => /^\d{4}-\d{2}-\d{2}$/.test(value)
+);
+FormatRegistry.Set(
+  "date-time",
+  (value) => !isNaN(Date.parse(value))
+);
+function isFile(value) {
+  return value instanceof File || typeof value === "object" && value !== null && "name" in value && "size" in value && "type" in value && typeof value.arrayBuffer === "function";
+}
+function isFileSchemaDef(schema) {
+  const kind = schema[Symbol.for("TypeBox.Kind")];
+  return kind === "File";
+}
+function isFileArraySchemaDef(schema) {
+  const kind = schema[Symbol.for("TypeBox.Kind")];
+  return kind === "FileArray";
+}
+function getSchemaFileOptions(schema) {
+  return schema.fileOptions;
+}
+function validateSingleFile(file, fieldPath, options, errors) {
+  if (!options) return;
+  const { maxSize, minSize, allowedTypes } = options;
+  if (maxSize !== void 0 && file.size > maxSize) {
+    errors.push({
+      path: fieldPath,
+      message: `File size ${formatFileSize(file.size)} exceeds maximum ${formatFileSize(maxSize)}`,
+      value: file.size
+    });
+  }
+  if (minSize !== void 0 && file.size < minSize) {
+    errors.push({
+      path: fieldPath,
+      message: `File size ${formatFileSize(file.size)} is below minimum ${formatFileSize(minSize)}`,
+      value: file.size
+    });
+  }
+  if (allowedTypes && allowedTypes.length > 0 && !allowedTypes.includes(file.type)) {
+    errors.push({
+      path: fieldPath,
+      message: `File type "${file.type}" is not allowed. Allowed: ${allowedTypes.join(", ")}`,
+      value: file.type
+    });
+  }
+}
 function validateField(schema, rawValue, fieldName) {
   if (!schema) {
     return {};
@@ -278,6 +380,87 @@ function validateField(schema, rawValue, fieldName) {
   }
   return converted;
 }
+function validateFormData(schema, rawValue, fieldName) {
+  if (!schema) {
+    return {};
+  }
+  const schemaProps = schema.properties;
+  if (!schemaProps) {
+    return rawValue;
+  }
+  const result = {};
+  const nonFileData = {};
+  const nonFileSchema = {};
+  const fileErrors = [];
+  for (const [key, value] of Object.entries(rawValue)) {
+    const propSchema = schemaProps[key];
+    if (propSchema && isFileSchemaDef(propSchema)) {
+      result[key] = value;
+      if (isFile(value)) {
+        const fileOptions = getSchemaFileOptions(propSchema);
+        validateSingleFile(value, `/${key}`, fileOptions, fileErrors);
+      }
+    } else if (propSchema && isFileArraySchemaDef(propSchema)) {
+      result[key] = value;
+      const fileOptions = getSchemaFileOptions(propSchema);
+      const files = Array.isArray(value) ? value : [value];
+      const fileArray = files.filter(isFile);
+      if (fileOptions?.maxFiles !== void 0 && fileArray.length > fileOptions.maxFiles) {
+        fileErrors.push({
+          path: `/${key}`,
+          message: `Too many files. Maximum: ${fileOptions.maxFiles}, received: ${fileArray.length}`,
+          value: fileArray.length
+        });
+      }
+      if (fileOptions?.minFiles !== void 0 && fileArray.length < fileOptions.minFiles) {
+        fileErrors.push({
+          path: `/${key}`,
+          message: `Too few files. Minimum: ${fileOptions.minFiles}, received: ${fileArray.length}`,
+          value: fileArray.length
+        });
+      }
+      fileArray.forEach((file, index) => {
+        validateSingleFile(file, `/${key}/${index}`, fileOptions, fileErrors);
+      });
+    } else if (isFile(value) || Array.isArray(value) && value.some(isFile)) {
+      result[key] = value;
+    } else {
+      nonFileData[key] = value;
+      if (propSchema) {
+        nonFileSchema[key] = propSchema;
+      }
+    }
+  }
+  if (fileErrors.length > 0) {
+    throw new ValidationError({
+      message: `Invalid ${fieldName}`,
+      fields: fileErrors
+    });
+  }
+  if (Object.keys(nonFileSchema).length > 0) {
+    const tempSchema = {
+      ...schema,
+      properties: nonFileSchema,
+      required: schema.required?.filter((r) => r in nonFileSchema) ?? []
+    };
+    const converted = Value.Convert(tempSchema, nonFileData);
+    const errors = [...Value.Errors(tempSchema, converted)];
+    if (errors.length > 0) {
+      throw new ValidationError({
+        message: `Invalid ${fieldName}`,
+        fields: errors.map((e) => ({
+          path: e.path,
+          message: e.message,
+          value: e.value
+        }))
+      });
+    }
+    Object.assign(result, converted);
+  } else {
+    Object.assign(result, nonFileData);
+  }
+  return result;
+}
 function extractQueryParams(c) {
   const url = new URL(c.req.url);
   const queryObj = {};
@@ -325,6 +508,34 @@ async function parseJsonBody(c) {
     });
   }
 }
+async function parseFormData(c) {
+  try {
+    const formData = await c.req.formData();
+    const result = {};
+    formData.forEach((value, key) => {
+      const existing = result[key];
+      if (existing !== void 0) {
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          result[key] = [existing, value];
+        }
+      } else {
+        result[key] = value;
+      }
+    });
+    return result;
+  } catch (error) {
+    throw new ValidationError({
+      message: "Invalid form data",
+      fields: [{
+        path: "/",
+        message: "Failed to parse form data",
+        value: error instanceof Error ? error.message : "Unknown error"
+      }]
+    });
+  }
+}
 
 // src/route/register-routes.ts
 function isRouter(value) {
@@ -391,18 +602,28 @@ 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 {
           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 });
         }
       }
     }
@@ -425,11 +646,8 @@ 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 };
 }
@@ -439,9 +657,16 @@ async function createRouteBuilderContext(c, input) {
   const headers = validateField(input.headers, extractHeaders(c), "headers");
   const cookies = validateField(input.cookies, extractCookies(c), "cookies");
   let body = {};
-  if (input.body) {
-    const rawBody = await parseJsonBody(c);
-    body = validateField(input.body, rawBody, "request body");
+  let formData = {};
+  if (input.body || input.formData) {
+    const contentType = c.req.header("content-type") || "";
+    if (contentType.includes("multipart/form-data") && input.formData) {
+      const rawFormData = await parseFormData(c);
+      formData = validateFormData(input.formData, rawFormData, "form data");
+    } else if (input.body) {
+      const rawBody = await parseJsonBody(c);
+      body = validateField(input.body, rawBody, "request body");
+    }
   }
   let cachedData = null;
   const responseMeta = {
@@ -452,7 +677,7 @@ async function createRouteBuilderContext(c, input) {
   const context = {
     data: async () => {
       if (!cachedData) {
-        cachedData = { params, query, body, headers, cookies };
+        cachedData = { params, query, body, formData, headers, cookies };
       }
       return cachedData;
     },
@@ -502,14 +727,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;
@@ -526,13 +753,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) {
@@ -557,6 +793,6 @@ function isHttpMethod(value) {
 var Nullable = (schema) => Type.Union([schema, Type.Null()]);
 var OptionalNullable = (schema) => Type.Optional(Type.Union([schema, Type.Null()]));
 
-export { Nullable, OptionalNullable, defineMiddleware, defineMiddlewareFactory, defineRouter, isHttpMethod, registerRoutes, route };
+export { FileArraySchema, FileSchema, Nullable, OptionalFileSchema, OptionalNullable, defineMiddleware, defineMiddlewareFactory, defineRouter, formatFileSize, getFileOptions, isFileArraySchema, isFileSchema, isHttpMethod, registerRoutes, route };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map