wynkjs 1.0.8 → 1.0.9

package/dist/decorators/guard.decorators.d.ts

@@ -4,17 +4,37 @@ import "reflect-metadata";
  * Guards for route protection and authorization
  */
 /**
- * Execution context interface - provides access to request details
+ * Execution context interface — provides typed access to the current request cycle.
+ * Passed to guards, interceptors, and exception filters.
  */
 export interface ExecutionContext {
+    /** Returns the underlying request object (typed as `T`). */
     getRequest<T = any>(): T;
+    /** Returns the underlying response/set object (typed as `T`). */
     getResponse<T = any>(): T;
+    /** Returns the full Elysia context object (typed as `T`). */
     getContext<T = any>(): T;
+    /** Returns the route handler function currently being invoked. */
     getHandler(): Function;
+    /** Returns the controller class that owns the current route handler. */
     getClass(): any;
+    /**
+     * Returns the transport type of the current request.
+     * WynkJS currently always returns `'http'`.
+     */
+    getType(): 'http' | 'ws' | 'rpc';
 }
 /**
- * CanActivate interface - All guards must implement this
+ * Interface that all guards must implement.
+ *
+ * @example
+ * @Injectable()
+ * export class AuthGuard implements CanActivate {
+ *   canActivate(context: ExecutionContext): boolean {
+ *     const req = context.getRequest<Request>();
+ *     return req.headers.get('authorization') !== null;
+ *   }
+ * }
  */
 export interface CanActivate {
     canActivate(context: ExecutionContext): boolean | Promise<boolean>;
@@ -40,4 +60,3 @@ export declare function createExecutionContext(ctx: any, handler: Function, cont
  * Helper function to execute guards
  */
 export declare function executeGuards(guards: (Function | CanActivate)[], context: ExecutionContext): Promise<boolean>;
-//# sourceMappingURL=guard.decorators.d.ts.map

package/dist/decorators/guard.decorators.js

@@ -37,6 +37,7 @@ export function createExecutionContext(ctx, handler, controllerClass) {
         getContext: () => ctx,
         getHandler: () => handler,
         getClass: () => controllerClass,
+        getType: () => 'http',
     };
 }
 /**

package/dist/decorators/http.decorators.d.ts

@@ -4,12 +4,25 @@ import "reflect-metadata";
  * RESTful route handlers with TypeScript decorators
  * Optimized for WynkJS's performance on Bun runtime
  */
+/**
+ * Options accepted by HTTP method decorators when passed as an object.
+ *
+ * @example
+ * @Post({ path: '/users', body: CreateUserDTO, query: PaginationDTO })
+ * create(@Body() dto: CreateUserType, @Query() q: PaginationQuery) {}
+ */
 export interface RouteOptions {
+    /** Route path (e.g. `'/'`, `'/:id'`). Defaults to `''`. */
     path?: string;
+    /** TypeBox schema used to validate and type the request body. */
     body?: any;
+    /** TypeBox schema used to validate route path parameters. */
     params?: any;
+    /** TypeBox schema used to validate query string parameters. */
     query?: any;
+    /** TypeBox schema used to validate request headers. */
     headers?: any;
+    /** TypeBox schema describing the response shape (informational / Swagger). */
     response?: any;
 }
 /**
@@ -121,6 +134,23 @@ export declare function Header(name: string, value: string): MethodDecorator;
  * redirect() {}
  */
 export declare function Redirect(url: string, statusCode?: number): MethodDecorator;
+/**
+ * Server-Sent Events (SSE) decorator — registers a GET route and marks it as
+ * an SSE endpoint via metadata. Note: the caller is responsible for setting
+ * `Content-Type: text/event-stream` and streaming the response appropriately;
+ * WynkJS does not configure this automatically at this time.
+ *
+ * @param pathOrOptions Route path string or {@link RouteOptions} object.
+ *
+ * @example
+ * ```typescript
+ * @Sse('/events')
+ * streamEvents() {
+ *   // Set Content-Type header and return a streaming response manually
+ * }
+ * ```
+ */
+export declare function Sse(pathOrOptions?: string | RouteOptions): MethodDecorator;
 /**
  * Use decorator - Apply middleware to controller or method
  * Simple middleware pattern like your working code
@@ -135,4 +165,3 @@ export declare function Redirect(url: string, statusCode?: number): MethodDecora
  * async findAll() {}
  */
 export declare function Use(...middlewares: any[]): ClassDecorator & MethodDecorator;
-//# sourceMappingURL=http.decorators.d.ts.map

package/dist/decorators/http.decorators.js

@@ -143,13 +143,9 @@ function createRouteDecorator(method, path, options) {
             methodName: propertyKey,
             options,
         });
-        console.log(`🔹 Storing route: ${method} ${path} on ${constructor.name}.${String(propertyKey)} (routes: ${routes.length})`);
         Reflect.defineMetadata("routes", routes, constructor.prototype);
         // Also store on constructor for compatibility
         Reflect.defineMetadata("routes", routes, constructor);
-        // Verify it was stored
-        const verify = Reflect.getMetadata("routes", constructor.prototype) || [];
-        console.log(`✅ Verified ${verify.length} routes stored on ${constructor.name}.prototype`);
         // Store method-specific metadata
         Reflect.defineMetadata("route:method", method, target, propertyKey);
         Reflect.defineMetadata("route:path", path, target, propertyKey);
@@ -204,6 +200,31 @@ export function Redirect(url, statusCode = 302) {
         return descriptor;
     };
 }
+/**
+ * Server-Sent Events (SSE) decorator — registers a GET route and marks it as
+ * an SSE endpoint via metadata. Note: the caller is responsible for setting
+ * `Content-Type: text/event-stream` and streaming the response appropriately;
+ * WynkJS does not configure this automatically at this time.
+ *
+ * @param pathOrOptions Route path string or {@link RouteOptions} object.
+ *
+ * @example
+ * ```typescript
+ * @Sse('/events')
+ * streamEvents() {
+ *   // Set Content-Type header and return a streaming response manually
+ * }
+ * ```
+ */
+export function Sse(pathOrOptions) {
+    const path = typeof pathOrOptions === "string"
+        ? pathOrOptions
+        : pathOrOptions?.path || "";
+    const options = typeof pathOrOptions === "object" && pathOrOptions !== null
+        ? { ...pathOrOptions, sse: true }
+        : { sse: true };
+    return createRouteDecorator("GET", path, options);
+}
 /**
  * Use decorator - Apply middleware to controller or method
  * Simple middleware pattern like your working code

package/dist/decorators/interceptor.advanced.d.ts

@@ -90,4 +90,3 @@ export declare class SanitizeInterceptor implements WynkInterceptor {
 export declare class PaginationInterceptor implements WynkInterceptor {
     intercept(context: InterceptorContext, next: () => Promise<any>): Promise<any>;
 }
-//# sourceMappingURL=interceptor.advanced.d.ts.map

package/dist/decorators/interceptor.decorators.d.ts

@@ -6,17 +6,55 @@ type ExecutionContext = InterceptorContext;
  * Interceptors for request/response transformation
  */
 /**
- * Call handler interface for interceptors
+ * Provides access to the handler return value as a promise.
+ *
+ * Passed as the second argument to `WynkInterceptor.intercept()`. Call
+ * `handle()` to invoke the next interceptor in the chain or the actual route
+ * handler. You can `await` the result to inspect or transform the response.
+ *
+ * @template T - The type of value returned by the handler
  */
 export interface CallHandler<T = any> {
+    /** Invoke the next interceptor or the route handler and return its result. */
     handle(): Promise<T>;
 }
 /**
- * WynkInterceptor interface - All interceptors must implement this
+ * Interface that all WynkJS interceptors must implement.
+ *
+ * Interceptors sit between the client request and the route handler. They can
+ * execute logic before AND after the handler, transform the result, catch errors,
+ * and even override the response entirely.
+ *
+ * Use `@UseInterceptors()` to apply an interceptor to a controller or route.
+ *
+ * @example
+ * ```typescript
+ * import { Injectable } from "wynkjs";
+ * import { WynkInterceptor } from "wynkjs";
+ *
+ * @Injectable()
+ * export class LoggingInterceptor implements WynkInterceptor {
+ *   async intercept(context: ExecutionContext, next: () => Promise<any>) {
+ *     console.log("Before handler");
+ *     const result = await next();
+ *     console.log("After handler");
+ *     return result;
+ *   }
+ * }
+ * ```
  */
 export interface WynkInterceptor {
+    /**
+     * Called for every request that passes through this interceptor.
+     *
+     * @param context - The execution context for the current request
+     * @param next - Call `next()` to invoke the next interceptor / route handler
+     * @returns The (possibly transformed) response value
+     */
     intercept(context: ExecutionContext, next: () => Promise<any>): Promise<any>;
 }
+/** NestJS-compatible generic alias for {@link WynkInterceptor}. */
+export type NestInterceptor<T = any, R = any> = WynkInterceptor;
 /**
  * @UseInterceptors decorator - Apply interceptors to routes or controllers
  * @param interceptors Interceptor classes to apply
@@ -90,4 +128,3 @@ export declare class LoggingInterceptor implements WynkInterceptor {
     intercept(context: InterceptorContext, next: () => Promise<any>): Promise<any>;
 }
 export {};
-//# sourceMappingURL=interceptor.decorators.d.ts.map

package/dist/decorators/metadata.decorators.d.ts

@@ -0,0 +1,71 @@
+import "reflect-metadata";
+import type { ExecutionContext } from "./guard.decorators";
+/**
+ * Attaches custom metadata to a class or method using the reflect-metadata API.
+ * Retrieve the value at runtime via the `Reflector` class.
+ *
+ * @param metadataKey - The key under which the value is stored
+ * @param metadataValue - The value to store
+ * @returns A decorator applicable to both classes and methods
+ *
+ * @example
+ * // Define a helper decorator
+ * export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
+ *
+ * // Use in controller
+ * @Roles('admin', 'editor')
+ * @Get('/secret')
+ * getSecret() {}
+ */
+export declare function SetMetadata<K = string, V = any>(metadataKey: K, metadataValue: V): MethodDecorator & ClassDecorator;
+/**
+ * Reads metadata stored by `SetMetadata` across one or multiple targets.
+ *
+ * @example
+ * const reflector = new Reflector();
+ *
+ * // In a guard:
+ * const roles = reflector.getAllAndOverride<string[]>('roles', [
+ *   context.getHandler(),
+ *   context.getClass(),
+ * ]);
+ */
+export declare class Reflector {
+    get<TResult = any>(metadataKey: string, target: Function | object): TResult | undefined;
+    getAllAndOverride<TResult = any>(metadataKey: string, targets: (Function | object)[]): TResult | undefined;
+    getAllAndMerge<TResult = any>(metadataKey: string, targets: (Function | object)[]): TResult[];
+}
+/**
+ * Composes multiple decorators into one, applying them left-to-right.
+ *
+ * @param decorators - One or more class/method/property decorators
+ * @returns A single decorator that applies all provided decorators
+ *
+ * @example
+ * export const Auth = (...roles: string[]) => applyDecorators(
+ *   SetMetadata('roles', roles),
+ *   UseGuards(AuthGuard, RolesGuard),
+ * );
+ *
+ * @Get('/admin')
+ * @Auth('admin')
+ * adminOnly() {}
+ */
+export declare function applyDecorators(...decorators: (ClassDecorator | MethodDecorator | PropertyDecorator)[]): (target: any, key?: any, descriptor?: any) => any;
+/**
+ * Creates a custom parameter decorator that calls `factory` to produce the
+ * injected value at request time.
+ *
+ * @param factory - Called with `(data, ctx)` where `data` is the argument passed
+ *   to the decorator and `ctx` is the current `ExecutionContext`.
+ * @returns A decorator factory: `(data?) => ParameterDecorator`
+ *
+ * @example
+ * const CurrentUser = createParamDecorator((data, ctx: ExecutionContext) => {
+ *   return ctx.getRequest().user;
+ * });
+ *
+ * @Get('/profile')
+ * getProfile(@CurrentUser() user: User) {}
+ */
+export declare function createParamDecorator<TData = unknown>(factory: (data: TData, ctx: ExecutionContext) => any): (data?: TData) => ParameterDecorator;

package/dist/decorators/metadata.decorators.js

@@ -0,0 +1,134 @@
+import "reflect-metadata";
+/**
+ * Attaches custom metadata to a class or method using the reflect-metadata API.
+ * Retrieve the value at runtime via the `Reflector` class.
+ *
+ * @param metadataKey - The key under which the value is stored
+ * @param metadataValue - The value to store
+ * @returns A decorator applicable to both classes and methods
+ *
+ * @example
+ * // Define a helper decorator
+ * export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
+ *
+ * // Use in controller
+ * @Roles('admin', 'editor')
+ * @Get('/secret')
+ * getSecret() {}
+ */
+export function SetMetadata(metadataKey, metadataValue) {
+    return (target, propertyKey, descriptor) => {
+        if (propertyKey !== undefined && descriptor !== undefined) {
+            Reflect.defineMetadata(metadataKey, metadataValue, target, propertyKey);
+            return descriptor;
+        }
+        Reflect.defineMetadata(metadataKey, metadataValue, target);
+        return target;
+    };
+}
+/**
+ * Reads metadata stored by `SetMetadata` across one or multiple targets.
+ *
+ * @example
+ * const reflector = new Reflector();
+ *
+ * // In a guard:
+ * const roles = reflector.getAllAndOverride<string[]>('roles', [
+ *   context.getHandler(),
+ *   context.getClass(),
+ * ]);
+ */
+export class Reflector {
+    get(metadataKey, target) {
+        return Reflect.getMetadata(metadataKey, target);
+    }
+    getAllAndOverride(metadataKey, targets) {
+        for (const target of targets) {
+            const value = Reflect.getMetadata(metadataKey, target);
+            if (value !== undefined)
+                return value;
+        }
+        return undefined;
+    }
+    getAllAndMerge(metadataKey, targets) {
+        const result = [];
+        for (const target of targets) {
+            const value = Reflect.getMetadata(metadataKey, target);
+            if (value !== undefined) {
+                if (Array.isArray(value))
+                    result.push(...value);
+                else
+                    result.push(value);
+            }
+        }
+        return result;
+    }
+}
+/**
+ * Composes multiple decorators into one, applying them left-to-right.
+ *
+ * @param decorators - One or more class/method/property decorators
+ * @returns A single decorator that applies all provided decorators
+ *
+ * @example
+ * export const Auth = (...roles: string[]) => applyDecorators(
+ *   SetMetadata('roles', roles),
+ *   UseGuards(AuthGuard, RolesGuard),
+ * );
+ *
+ * @Get('/admin')
+ * @Auth('admin')
+ * adminOnly() {}
+ */
+export function applyDecorators(...decorators) {
+    return (target, key, descriptor) => {
+        let currentTarget = target;
+        let currentDescriptor = descriptor;
+        for (const decorator of decorators) {
+            if (key !== undefined && currentDescriptor !== undefined) {
+                const nextDescriptor = decorator(currentTarget, key, currentDescriptor);
+                currentDescriptor = nextDescriptor ?? currentDescriptor;
+            }
+            else if (key !== undefined) {
+                decorator(currentTarget, key);
+            }
+            else {
+                const nextTarget = decorator(currentTarget);
+                currentTarget = nextTarget ?? currentTarget;
+            }
+        }
+        return currentDescriptor ?? currentTarget;
+    };
+}
+/**
+ * Creates a custom parameter decorator that calls `factory` to produce the
+ * injected value at request time.
+ *
+ * @param factory - Called with `(data, ctx)` where `data` is the argument passed
+ *   to the decorator and `ctx` is the current `ExecutionContext`.
+ * @returns A decorator factory: `(data?) => ParameterDecorator`
+ *
+ * @example
+ * const CurrentUser = createParamDecorator((data, ctx: ExecutionContext) => {
+ *   return ctx.getRequest().user;
+ * });
+ *
+ * @Get('/profile')
+ * getProfile(@CurrentUser() user: User) {}
+ */
+export function createParamDecorator(factory) {
+    return (data) => {
+        return (target, propertyKey, parameterIndex) => {
+            if (!propertyKey)
+                return;
+            const existingParams = Reflect.getMetadata("params", target, propertyKey) || [];
+            existingParams.push({
+                index: parameterIndex,
+                type: "custom",
+                data: data,
+                factory: (d, ctx) => factory(d, ctx),
+            });
+            Reflect.defineMetadata("params", existingParams, target, propertyKey);
+        };
+    };
+}

package/dist/decorators/param.decorators.d.ts

@@ -3,12 +3,38 @@ import "reflect-metadata";
  * Parameter Decorators for WynkJS Framework
  * Extract data from request context
  */
-export type ParamType = "body" | "param" | "query" | "headers" | "request" | "response" | "context" | "user" | "file" | "files";
+/**
+ * Identifies the source from which a parameter decorator extracts its value.
+ *
+ * - `body`    — request body (JSON payload)
+ * - `param`   — URL path parameter (e.g. `/users/:id`)
+ * - `query`   — query string parameter (e.g. `?page=1`)
+ * - `headers` — HTTP request headers
+ * - `request` — full Elysia request object
+ * - `response` — Elysia response/set object
+ * - `context`  — full Elysia context
+ * - `user`     — user object attached to context by a guard
+ * - `file`     — single uploaded file
+ * - `files`    — multiple uploaded files
+ * - `custom`   — value produced by a `createParamDecorator` factory function
+ */
+export type ParamType = "body" | "param" | "query" | "headers" | "request" | "response" | "context" | "user" | "file" | "files" | "custom";
+/**
+ * Internal metadata stored for each decorated parameter in a controller method.
+ * Populated by parameter decorators (`@Body`, `@Param`, `@Query`, etc.) and
+ * consumed by the ultra-optimized handler at request time.
+ */
 export interface ParamMetadata {
+    /** Zero-based position of this parameter in the method signature. */
     index: number;
+    /** Where to extract the value from — see {@link ParamType}. */
     type: ParamType;
+    /** Optional key to pluck from the source (e.g. param name or header name). */
     data?: string;
+    /** Optional pipes applied to the extracted value before it reaches the handler. */
     pipes?: any[];
+    /** Factory function used when `type === 'custom'` (from `createParamDecorator`). */
+    factory?: (data: any, ctx: any) => any;
 }
 /**
  * @Body decorator - Extracts request body
@@ -141,4 +167,3 @@ export declare function Session(property?: string): ParameterDecorator;
  * }
  */
 export declare function HostParam(property: string): ParameterDecorator;
-//# sourceMappingURL=param.decorators.d.ts.map

package/dist/decorators/pipe.advanced.d.ts

@@ -11,33 +11,27 @@ import { WynkPipeTransform, ArgumentMetadata } from "./pipe.decorators";
  * async getByDate(@Param('date', ParseDatePipe) date: Date) {}
  */
 export declare class ParseDatePipe implements WynkPipeTransform<string, Date> {
-    transform(value: string, metadata?: ArgumentMetadata): Date;
-}
-/**
- * Parse File Pipe - Validates and transforms file uploads
- * @example
- * @Post('/upload')
- * async uploadFile(@UploadedFile(ParseFilePipe) file: any) {}
- */
-export declare class ParseFilePipe implements WynkPipeTransform<any, any> {
-    private options?;
-    constructor(options?: {
-        maxSize?: number;
-        allowedTypes?: string[];
-        required?: boolean;
-    } | undefined);
-    transform(value: any, metadata?: ArgumentMetadata): any;
+    transform(value: string, _metadata?: ArgumentMetadata): Date;
 }
 /**
  * Sanitize Pipe - Sanitizes input by removing dangerous characters
+ *
+ * SECURITY NOTICE: This pipe provides basic normalization (script tag removal,
+ * javascript: protocol stripping, inline event handler removal). It is NOT a
+ * replacement for a dedicated XSS sanitization library such as `sanitize-html`
+ * or `DOMPurify` when rendering user content as HTML. Use this pipe for
+ * light input cleaning only; apply a full sanitizer at the HTML rendering layer.
+ *
  * @example
  * @Post()
  * async create(@Body(SanitizePipe) data: any) {}
  */
 export declare class SanitizePipe implements WynkPipeTransform {
     private dangerousPatterns;
-    transform(value: any, metadata?: ArgumentMetadata): any;
+    transform(value: any, _metadata?: ArgumentMetadata): any;
     private sanitizeString;
+    private removeEventHandlers;
+    private removeScriptTags;
 }
 /**
  * Transform Case Pipe - Transforms string case
@@ -48,7 +42,7 @@ export declare class SanitizePipe implements WynkPipeTransform {
 export declare class TransformCasePipe implements WynkPipeTransform<string, string> {
     private caseType;
     constructor(caseType?: "lower" | "upper" | "title");
-    transform(value: string, metadata?: ArgumentMetadata): string;
+    transform(value: string, _metadata?: ArgumentMetadata): string;
 }
 /**
  * Parse JSON Pipe - Parses JSON strings
@@ -57,7 +51,7 @@ export declare class TransformCasePipe implements WynkPipeTransform<string, stri
  * async create(@Body('metadata', ParseJSONPipe) metadata: any) {}
  */
 export declare class ParseJSONPipe implements WynkPipeTransform<string, any> {
-    transform(value: string, metadata?: ArgumentMetadata): any;
+    transform(value: string, _metadata?: ArgumentMetadata): any;
 }
 /**
  * Validate Email Pipe - Validates email format
@@ -67,7 +61,7 @@ export declare class ParseJSONPipe implements WynkPipeTransform<string, any> {
  */
 export declare class ValidateEmailPipe implements WynkPipeTransform<string, string> {
     private emailRegex;
-    transform(value: string, metadata?: ArgumentMetadata): string;
+    transform(value: string, _metadata?: ArgumentMetadata): string;
 }
 /**
  * Validate Length Pipe - Validates string/array length
@@ -79,7 +73,7 @@ export declare class ValidateLengthPipe implements WynkPipeTransform {
     private min?;
     private max?;
     constructor(min?: number | undefined, max?: number | undefined);
-    transform(value: any, metadata?: ArgumentMetadata): any;
+    transform(value: any, _metadata?: ArgumentMetadata): any;
 }
 /**
  * Validate Range Pipe - Validates number is within range
@@ -91,7 +85,7 @@ export declare class ValidateRangePipe implements WynkPipeTransform<number, numb
     private min?;
     private max?;
     constructor(min?: number | undefined, max?: number | undefined);
-    transform(value: number, metadata?: ArgumentMetadata): number;
+    transform(value: number, _metadata?: ArgumentMetadata): number;
 }
 /**
  * Strip HTML Pipe - Removes HTML tags from string
@@ -100,7 +94,7 @@ export declare class ValidateRangePipe implements WynkPipeTransform<number, numb
  * async create(@Body('comment', StripHTMLPipe) comment: string) {}
  */
 export declare class StripHTMLPipe implements WynkPipeTransform<string, string> {
-    transform(value: string, metadata?: ArgumentMetadata): string;
+    transform(value: string, _metadata?: ArgumentMetadata): string;
 }
 /**
  * Slugify Pipe - Converts string to URL-friendly slug
@@ -109,7 +103,7 @@ export declare class StripHTMLPipe implements WynkPipeTransform<string, string>
  * async create(@Body('title', SlugifyPipe) slug: string) {}
  */
 export declare class SlugifyPipe implements WynkPipeTransform<string, string> {
-    transform(value: string, metadata?: ArgumentMetadata): string;
+    transform(value: string, _metadata?: ArgumentMetadata): string;
 }
 /**
  * Parse Comma Separated Pipe - Converts comma-separated string to array
@@ -120,6 +114,5 @@ export declare class SlugifyPipe implements WynkPipeTransform<string, string> {
 export declare class ParseCommaSeparatedPipe implements WynkPipeTransform<string, string[]> {
     private trim;
     constructor(trim?: boolean);
-    transform(value: string, metadata?: ArgumentMetadata): string[];
+    transform(value: string, _metadata?: ArgumentMetadata): string[];
 }
-//# sourceMappingURL=pipe.advanced.d.ts.map