@spfn/core 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/route/index.d.ts

@@ -1,9 +1,8 @@
 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';
-export { HeaderRecord, InferResponseData, RouteMeta, RouteMetadata, RouterMetadata } from './types.js';
 
 /**
  * Route Input Types
@@ -23,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 */
@@ -35,6 +36,18 @@ type RouteInput = {
  * Provides structured input access and response helpers for route handlers
  */
 
+/**
+ * Paginated response structure
+ */
+type PaginatedResult<T> = {
+    items: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+};
 /**
  * Merge input with interceptor-injected fields
  * Server receives both client input and interceptor-injected fields
@@ -50,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']> : {});
 };
@@ -94,7 +108,7 @@ type RouteBuilderContext<TInput extends RouteInput = RouteInput, TInterceptor ex
     json(data: unknown, status?: ContentfulStatusCode, headers?: Record<string, string | string[]>): Response;
     /**
      * Return 201 Created response with optional Location header
-     * Returns data directly (no wrapper)
+     * Returns data directly for type inference
      *
      * @example
      * ```ts
@@ -103,25 +117,29 @@ type RouteBuilderContext<TInput extends RouteInput = RouteInput, TInterceptor ex
      * // Response: 201 Created
      * // Header: Location: /users/123
      * // Body: { id: '123', name: 'John' }
+     * // Type: User (inferred from data)
      * ```
      */
-    created(data: unknown, location?: string): Response;
+    created<T>(data: T, location?: string): T;
     /**
      * Return 202 Accepted response
-     * Returns data directly (no wrapper), or empty body if no data
+     * Returns data directly for type inference
      *
      * @example
      * ```ts
      * // With data
      * return c.accepted({ jobId: '123' });
      * // Response: 202 Accepted, Body: { jobId: '123' }
+     * // Type: { jobId: string }
      *
      * // Without data
      * return c.accepted();
      * // Response: 202 Accepted, Body: (empty)
+     * // Type: void
      * ```
      */
-    accepted(data?: unknown): Response;
+    accepted(): void;
+    accepted<T>(data: T): T;
     /**
      * Return 204 No Content response (empty body)
      *
@@ -130,9 +148,10 @@ type RouteBuilderContext<TInput extends RouteInput = RouteInput, TInterceptor ex
      * await deleteUser(id);
      * return c.noContent();
      * // Response: 204 No Content, Body: (empty)
+     * // Type: void
      * ```
      */
-    noContent(): Response;
+    noContent(): void;
     /**
      * Return 304 Not Modified response (empty body)
      *
@@ -142,12 +161,13 @@ type RouteBuilderContext<TInput extends RouteInput = RouteInput, TInterceptor ex
      *   return c.notModified();
      * }
      * // Response: 304 Not Modified, Body: (empty)
+     * // Type: void
      * ```
      */
-    notModified(): Response;
+    notModified(): void;
     /**
      * Return paginated response with metadata
-     * Returns `{ items: [...], pagination: {...} }` format
+     * Returns `{ items: [...], pagination: {...} }` format with type inference
      *
      * @example
      * ```ts
@@ -163,9 +183,10 @@ type RouteBuilderContext<TInput extends RouteInput = RouteInput, TInterceptor ex
      * //     totalPages: 5
      * //   }
      * // }
+     * // Type: PaginatedResult<User>
      * ```
      */
-    paginated(data: unknown[], page: number, limit: number, total: number): Response;
+    paginated<T>(data: T[], page: number, limit: number, total: number): PaginatedResult<T>;
     /**
      * Redirect to another URL
      *
@@ -501,14 +522,46 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
     /**
      * Define handler function
      *
+     * Response type is automatically inferred from the return value.
+     * Use helper methods like `c.created()`, `c.paginated()` for proper type inference.
+     *
      * @example
      * ```ts
+     * // Direct return - type inferred from data
      * route.get('/users/:id')
      *   .input({ params: Type.Object({ id: Type.String() }) })
      *   .handler(async (c) => {
      *     const { params } = await c.data();
-     *     const user = await getUser(params.id);
-     *     return user; // Type inferred!
+     *     return await getUser(params.id); // Type: User
+     *   })
+     *
+     * // Using c.created() - returns data with 201 status, type preserved
+     * route.post('/users')
+     *   .input({ body: Type.Object({ name: Type.String() }) })
+     *   .handler(async (c) => {
+     *     const { body } = await c.data();
+     *     return c.created(await createUser(body)); // Type: User
+     *   })
+     *
+     * // Using c.paginated() - returns PaginatedResult<T>
+     * route.get('/users')
+     *   .handler(async (c) => {
+     *     const users = await getUsers();
+     *     return c.paginated(users, 1, 20, 100); // Type: PaginatedResult<User>
+     *   })
+     *
+     * // Using c.noContent() - returns void
+     * route.delete('/users/:id')
+     *   .handler(async (c) => {
+     *     await deleteUser(params.id);
+     *     return c.noContent(); // Type: void
+     *   })
+     *
+     * // Using c.json() - returns Response (type inference lost)
+     * // Use only when you need custom status codes not covered by helpers
+     * route.get('/custom')
+     *   .handler(async (c) => {
+     *     return c.json({ data }, 418); // Type: Response
      *   })
      * ```
      */
@@ -646,6 +699,14 @@ declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any,
  * Registers routes defined with route.get()...handler() to Hono app
  */
 
+/**
+ * Registered route information for logging
+ */
+interface RegisteredRoute {
+    method: HttpMethod;
+    path: string;
+    name: string;
+}
 /**
  * Register routes from defineRouter() to Hono app
  *
@@ -653,6 +714,7 @@ declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any,
  * @param router - Router definition
  * @param namedMiddlewares - Optional server-level named middlewares
  *
+ * @param collectedRoutes
  * @example
  * ```ts
  * const appRouter = defineRouter({
@@ -671,7 +733,7 @@ declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any,
 declare function registerRoutes<TRoutes extends Record<string, RouteDef<any> | Router<any>>>(app: Hono, router: Router<TRoutes>, namedMiddlewares?: ReadonlyArray<{
     name: string;
     handler: MiddlewareHandler;
-}>): void;
+}>, collectedRoutes?: RegisteredRoute[]): RegisteredRoute[];
 
 /**
  * Type guard for HttpMethod
@@ -698,4 +760,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, RouteBuilder, 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 };