@forinda/kickjs-http 0.3.0

package/dist/index.js

@@ -0,0 +1,64 @@
+import {
+  cleanupFiles,
+  upload
+} from "./chunk-75Z5FSZN.js";
+import {
+  bootstrap
+} from "./chunk-KAWXFLFS.js";
+import {
+  Application
+} from "./chunk-P3YCN5LK.js";
+import {
+  buildRoutes,
+  getControllerPath
+} from "./chunk-U2JYL2NW.js";
+import {
+  validate
+} from "./chunk-JD2RKDKH.js";
+import {
+  RequestContext
+} from "./chunk-RZUH6NBM.js";
+import {
+  FILTER_OPERATORS,
+  buildQueryParams,
+  parseFilters,
+  parsePagination,
+  parseQuery,
+  parseSearchQuery,
+  parseSort
+} from "./chunk-JM7X7SAD.js";
+import {
+  csrf
+} from "./chunk-I6UNTOQD.js";
+import {
+  errorHandler,
+  notFoundHandler
+} from "./chunk-BNWCVQQH.js";
+import {
+  REQUEST_ID_HEADER,
+  requestId
+} from "./chunk-ZI52TGQ4.js";
+import "./chunk-7QVYU63E.js";
+export {
+  Application,
+  FILTER_OPERATORS,
+  REQUEST_ID_HEADER,
+  RequestContext,
+  bootstrap,
+  buildQueryParams,
+  buildRoutes,
+  cleanupFiles,
+  csrf,
+  errorHandler,
+  getControllerPath,
+  notFoundHandler,
+  parseFilters,
+  parsePagination,
+  parseQuery,
+  parseSearchQuery,
+  parseSort,
+  requestId,
+  upload,
+  validate
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/middleware/csrf.d.ts

@@ -0,0 +1,49 @@
+import { Request, Response, NextFunction } from 'express';
+
+interface CsrfOptions {
+    /** Cookie name for the CSRF token (default: '_csrf') */
+    cookie?: string;
+    /** Header name to check for the token (default: 'x-csrf-token') */
+    header?: string;
+    /** HTTP methods that require CSRF validation (default: POST, PUT, PATCH, DELETE) */
+    methods?: string[];
+    /** Paths to exclude from CSRF checks (e.g. webhooks) */
+    ignorePaths?: string[];
+    /** Token byte length before hex encoding (default: 32 = 64 hex chars) */
+    tokenLength?: number;
+    /** Cookie options */
+    cookieOptions?: {
+        httpOnly?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+        secure?: boolean;
+        path?: string;
+    };
+}
+/**
+ * Double-submit cookie CSRF protection middleware.
+ *
+ * On every request, sets a CSRF token cookie. For state-changing methods
+ * (POST, PUT, PATCH, DELETE), validates that the request header matches
+ * the cookie value.
+ *
+ * @example
+ * ```ts
+ * import { csrf } from '@forinda/kickjs-http'
+ *
+ * bootstrap({
+ *   modules,
+ *   middleware: [
+ *     cookieParser(),
+ *     csrf(),
+ *     // ... other middleware
+ *   ],
+ * })
+ * ```
+ *
+ * Client usage:
+ * 1. Read the `_csrf` cookie value
+ * 2. Send it in the `x-csrf-token` header on every mutating request
+ */
+declare function csrf(options?: CsrfOptions): (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+
+export { type CsrfOptions, csrf };

package/dist/middleware/csrf.js

@@ -0,0 +1,8 @@
+import {
+  csrf
+} from "../chunk-I6UNTOQD.js";
+import "../chunk-7QVYU63E.js";
+export {
+  csrf
+};
+//# sourceMappingURL=csrf.js.map

package/dist/middleware/csrf.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,8 @@
+import { Request, Response, NextFunction } from 'express';
+
+/** Catch-all for unmatched routes */
+declare function notFoundHandler(): (_req: Request, res: Response, _next: NextFunction) => void;
+/** Global error handler */
+declare function errorHandler(): (err: any, req: Request, res: Response, _next: NextFunction) => Response<any, Record<string, any>> | undefined;
+
+export { errorHandler, notFoundHandler };

package/dist/middleware/error-handler.js

@@ -0,0 +1,10 @@
+import {
+  errorHandler,
+  notFoundHandler
+} from "../chunk-BNWCVQQH.js";
+import "../chunk-7QVYU63E.js";
+export {
+  errorHandler,
+  notFoundHandler
+};
+//# sourceMappingURL=error-handler.js.map

package/dist/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/middleware/request-id.d.ts

@@ -0,0 +1,7 @@
+import { Request, Response, NextFunction } from 'express';
+
+declare const REQUEST_ID_HEADER = "x-request-id";
+/** Middleware that generates or propagates a unique request ID */
+declare function requestId(): (req: Request, res: Response, next: NextFunction) => void;
+
+export { REQUEST_ID_HEADER, requestId };

package/dist/middleware/request-id.js

@@ -0,0 +1,10 @@
+import {
+  REQUEST_ID_HEADER,
+  requestId
+} from "../chunk-ZI52TGQ4.js";
+import "../chunk-7QVYU63E.js";
+export {
+  REQUEST_ID_HEADER,
+  requestId
+};
+//# sourceMappingURL=request-id.js.map

package/dist/middleware/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/middleware/upload.d.ts

@@ -0,0 +1,57 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { Options } from 'multer';
+
+interface UploadOptions {
+    /** Max file size in bytes (default: 5MB) */
+    maxSize?: number;
+    /** Allowed MIME types (default: all) */
+    allowedTypes?: string[];
+    /** Multer storage config (default: memory storage) */
+    storage?: Options['storage'];
+    /** Multer dest for disk storage shorthand */
+    dest?: string;
+}
+/**
+ * Single file upload middleware. Attaches the file to `req.file`.
+ *
+ * @example
+ * ```ts
+ * @Post('/avatar')
+ * @Middleware(upload.single('avatar', { maxSize: 2 * 1024 * 1024, allowedTypes: ['image/*'] }))
+ * async uploadAvatar(ctx: RequestContext) {
+ *   ctx.json({ filename: ctx.file.originalname })
+ * }
+ * ```
+ */
+declare function single(fieldName: string, options?: UploadOptions): RequestHandler;
+/**
+ * Multiple file upload middleware. Attaches files to `req.files`.
+ */
+declare function array(fieldName: string, maxCount?: number, options?: UploadOptions): RequestHandler;
+/**
+ * No file upload — just parse multipart form data without file fields.
+ */
+declare function none(options?: UploadOptions): RequestHandler;
+/**
+ * Middleware that automatically cleans up uploaded files after the response
+ * is sent. Attach this AFTER your upload middleware.
+ *
+ * Only cleans up disk-stored files (files with a `path` property).
+ *
+ * @example
+ * ```ts
+ * middleware: [
+ *   upload.single('file', { dest: '/tmp/uploads' }),
+ *   cleanupFiles(),
+ * ]
+ * ```
+ */
+declare function cleanupFiles(): (req: Request, res: Response, next: NextFunction) => void;
+/** Upload middleware factory with `.single()`, `.array()`, `.none()` methods */
+declare const upload: {
+    single: typeof single;
+    array: typeof array;
+    none: typeof none;
+};
+
+export { type UploadOptions, cleanupFiles, upload };

package/dist/middleware/upload.js

@@ -0,0 +1,10 @@
+import {
+  cleanupFiles,
+  upload
+} from "../chunk-75Z5FSZN.js";
+import "../chunk-7QVYU63E.js";
+export {
+  cleanupFiles,
+  upload
+};
+//# sourceMappingURL=upload.js.map

package/dist/middleware/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/middleware/validate.d.ts

@@ -0,0 +1,15 @@
+import { Request, Response, NextFunction } from 'express';
+
+interface ValidationSchema {
+    body?: any;
+    query?: any;
+    params?: any;
+}
+/**
+ * Express middleware that validates request body/query/params against schemas.
+ * Works with any validation library that exposes `.safeParse(data)` returning
+ * `{ success: true, data }` or `{ success: false, error: { issues } }`.
+ */
+declare function validate(schema: ValidationSchema): (req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined;
+
+export { type ValidationSchema, validate };

package/dist/middleware/validate.js

@@ -0,0 +1,8 @@
+import {
+  validate
+} from "../chunk-JD2RKDKH.js";
+import "../chunk-7QVYU63E.js";
+export {
+  validate
+};
+//# sourceMappingURL=validate.js.map

package/dist/middleware/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/query/index.d.ts

@@ -0,0 +1,47 @@
+import { c as ParsedQuery, a as FilterItem, P as PaginationParams, d as QueryFieldConfig, S as SortItem } from '../types-Doz6f3AB.js';
+export { F as FILTER_OPERATORS, b as FilterOperator, Q as QueryBuilderAdapter } from '../types-Doz6f3AB.js';
+
+/** Parse filter strings like "status:eq:active" into structured objects */
+declare function parseFilters(filterParam: string | string[] | undefined, allowedFields?: string[]): FilterItem[];
+/** Parse sort strings like "firstName:asc" into structured objects */
+declare function parseSort(sortParam: string | string[] | undefined, allowedFields?: string[]): SortItem[];
+/** Parse page/limit into pagination with computed offset */
+declare function parsePagination(params: {
+    page?: string | number;
+    limit?: string | number;
+}): PaginationParams;
+/** Sanitize and truncate search query */
+declare function parseSearchQuery(q: string | undefined): string;
+/**
+ * Parse a raw Express query object into a structured, ORM-agnostic ParsedQuery.
+ *
+ * @param query - Raw query string object from `req.query` or Zod-validated object
+ * @param fieldConfig - Optional field restrictions (whitelist filterable/sortable/searchable)
+ *
+ * @example
+ * ```ts
+ * // In a controller
+ * @Get('/')
+ * async list(ctx: RequestContext) {
+ *   const parsed = parseQuery(ctx.query, {
+ *     filterable: ['status', 'priority'],
+ *     sortable: ['createdAt', 'title'],
+ *   })
+ *   // Pass to your ORM query builder adapter
+ *   const q = drizzleAdapter.build(parsed, { columns, searchColumns })
+ * }
+ * ```
+ *
+ * Query string format:
+ * - Filters: `?filter=field:operator:value` (repeatable)
+ * - Sort: `?sort=field:asc|desc` (repeatable)
+ * - Pagination: `?page=1&limit=20`
+ * - Search: `?q=search+term`
+ *
+ * Filter operators: eq, neq, gt, gte, lt, lte, between, in, contains, starts, ends
+ */
+declare function parseQuery(query: Record<string, any>, fieldConfig?: QueryFieldConfig): ParsedQuery;
+/** Convert ParsedQuery back into query string parameters */
+declare function buildQueryParams(parsed: Partial<ParsedQuery>): Record<string, string | string[] | number>;
+
+export { FilterItem, PaginationParams, ParsedQuery, QueryFieldConfig, SortItem, buildQueryParams, parseFilters, parsePagination, parseQuery, parseSearchQuery, parseSort };

package/dist/query/index.js

@@ -0,0 +1,20 @@
+import {
+  FILTER_OPERATORS,
+  buildQueryParams,
+  parseFilters,
+  parsePagination,
+  parseQuery,
+  parseSearchQuery,
+  parseSort
+} from "../chunk-JM7X7SAD.js";
+import "../chunk-7QVYU63E.js";
+export {
+  FILTER_OPERATORS,
+  buildQueryParams,
+  parseFilters,
+  parsePagination,
+  parseQuery,
+  parseSearchQuery,
+  parseSort
+};
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/router-builder.d.ts

@@ -0,0 +1,12 @@
+import { Router } from 'express';
+
+/** Get the controller path set by @Controller('/path') */
+declare function getControllerPath(controllerClass: any): string;
+/**
+ * Build an Express Router from a controller class decorated with @Get, @Post, etc.
+ * Resolves the controller from the DI container, wraps handlers in RequestContext,
+ * and applies class-level and method-level middleware.
+ */
+declare function buildRoutes(controllerClass: any): Router;
+
+export { buildRoutes, getControllerPath };

package/dist/router-builder.js

@@ -0,0 +1,13 @@
+import {
+  buildRoutes,
+  getControllerPath
+} from "./chunk-U2JYL2NW.js";
+import "./chunk-JD2RKDKH.js";
+import "./chunk-RZUH6NBM.js";
+import "./chunk-JM7X7SAD.js";
+import "./chunk-7QVYU63E.js";
+export {
+  buildRoutes,
+  getControllerPath
+};
+//# sourceMappingURL=router-builder.js.map

package/dist/router-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-Doz6f3AB.d.ts

@@ -0,0 +1,72 @@
+/** Supported filter operators for query string parsing */
+type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'in' | 'contains' | 'starts' | 'ends';
+declare const FILTER_OPERATORS: Set<string>;
+interface FilterItem {
+    field: string;
+    operator: FilterOperator;
+    value: string;
+}
+interface SortItem {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+interface PaginationParams {
+    page: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * The result of parsing a query string. ORM-agnostic — pass this to
+ * a query builder adapter (Drizzle, Prisma, Sequelize, etc.) to produce
+ * database-specific query objects.
+ */
+interface ParsedQuery {
+    filters: FilterItem[];
+    sort: SortItem[];
+    pagination: PaginationParams;
+    search: string;
+}
+/**
+ * Restrict which fields can be filtered, sorted, or searched.
+ * Fields not in the allow-list are silently ignored.
+ */
+interface QueryFieldConfig {
+    filterable?: string[];
+    sortable?: string[];
+    searchable?: string[];
+}
+/**
+ * Interface for ORM-specific query builder adapters.
+ * Implement this to translate a `ParsedQuery` into your ORM's query format.
+ *
+ * @example
+ * ```ts
+ * // Drizzle adapter
+ * class DrizzleQueryAdapter implements QueryBuilderAdapter<DrizzleQueryResult> {
+ *   build(parsed: ParsedQuery, config: DrizzleConfig): DrizzleQueryResult {
+ *     // Convert filters → Drizzle SQL conditions
+ *     // Convert sort → Drizzle orderBy
+ *     return { where, orderBy, limit, offset }
+ *   }
+ * }
+ *
+ * // Prisma adapter
+ * class PrismaQueryAdapter implements QueryBuilderAdapter<PrismaQueryResult> {
+ *   build(parsed: ParsedQuery, config: PrismaConfig): PrismaQueryResult {
+ *     return { where, orderBy, skip, take }
+ *   }
+ * }
+ * ```
+ */
+interface QueryBuilderAdapter<TResult = any, TConfig = any> {
+    /** Human-readable name for debugging */
+    readonly name: string;
+    /**
+     * Convert a ParsedQuery into an ORM-specific query object.
+     * @param parsed - The ORM-agnostic parsed query
+     * @param config - ORM-specific configuration (column maps, search columns, etc.)
+     */
+    build(parsed: ParsedQuery, config: TConfig): TResult;
+}
+
+export { FILTER_OPERATORS as F, type PaginationParams as P, type QueryBuilderAdapter as Q, type SortItem as S, type FilterItem as a, type FilterOperator as b, type ParsedQuery as c, type QueryFieldConfig as d };

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@forinda/kickjs-http",
+  "version": "0.3.0",
+  "description": "Express 5 integration, router builder, RequestContext, and middleware for KickJS",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./application": {
+      "import": "./dist/application.js",
+      "types": "./dist/application.d.ts"
+    },
+    "./bootstrap": {
+      "import": "./dist/bootstrap.js",
+      "types": "./dist/bootstrap.d.ts"
+    },
+    "./context": {
+      "import": "./dist/context.js",
+      "types": "./dist/context.d.ts"
+    },
+    "./router": {
+      "import": "./dist/router-builder.js",
+      "types": "./dist/router-builder.d.ts"
+    },
+    "./middleware/csrf": {
+      "import": "./dist/middleware/csrf.js",
+      "types": "./dist/middleware/csrf.d.ts"
+    },
+    "./middleware/upload": {
+      "import": "./dist/middleware/upload.js",
+      "types": "./dist/middleware/upload.d.ts"
+    },
+    "./middleware/validate": {
+      "import": "./dist/middleware/validate.js",
+      "types": "./dist/middleware/validate.d.ts"
+    },
+    "./middleware/request-id": {
+      "import": "./dist/middleware/request-id.js",
+      "types": "./dist/middleware/request-id.d.ts"
+    },
+    "./middleware/error-handler": {
+      "import": "./dist/middleware/error-handler.js",
+      "types": "./dist/middleware/error-handler.d.ts"
+    },
+    "./query": {
+      "import": "./dist/query/index.js",
+      "types": "./dist/query/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "cookie-parser": "^1.4.7",
+    "multer": "^2.1.1",
+    "reflect-metadata": "^0.2.2",
+    "@forinda/kickjs-core": "0.3.0"
+  },
+  "peerDependencies": {
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.7.28",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/express": "^5.0.6",
+    "@types/multer": "^2.1.0",
+    "@types/node": "^24.5.2",
+    "express": "^5.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo",
+    "lint": "tsc --noEmit"
+  }
+}