najm-validation 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+import * as diject from 'diject';
+import * as najm_core from 'najm-core';
+
+/**
+ * Validation target type
+ */
+type ValidationTarget = 'body' | 'params' | 'query' | 'headers';
+/**
+ * Minimal schema shape required by validation plugin.
+ * Supports both Zod v3 and v4 schema instances.
+ */
+interface ValidationSchema {
+    parse(data: unknown): unknown;
+    strip?: () => ValidationSchema;
+}
+/**
+ * Minimal Zod issue shape used for error formatting.
+ */
+interface ZodIssueLike {
+    path: PropertyKey[];
+    message: string;
+    code: string;
+}
+/**
+ * Minimal Zod error shape used by framework internals.
+ * Compatible with Zod v3 and v4 errors.
+ */
+interface ZodErrorLike {
+    issues: ZodIssueLike[];
+}
+/**
+ * Error formatter function type
+ */
+type ErrorFormatter = (error: ZodErrorLike, target: ValidationTarget) => any;
+/**
+ * Validation configuration for @Validate decorator
+ */
+interface ValidationConfig {
+    /**
+     * Zod schema for request body validation
+     */
+    body?: ValidationSchema;
+    /**
+     * Zod schema for route params validation
+     */
+    params?: ValidationSchema;
+    /**
+     * Zod schema for query parameters validation
+     */
+    query?: ValidationSchema;
+    /**
+     * Zod schema for request headers validation
+     */
+    headers?: ValidationSchema;
+    /**
+     * Remove unknown fields from validated data (default: false)
+     */
+    stripUnknown?: boolean;
+    /**
+     * HTTP status code for validation errors (default: 400)
+     */
+    errorStatus?: number;
+    /**
+     * Custom error formatter for validation errors
+     */
+    errorFormatter?: ErrorFormatter;
+}
+/**
+ * Input type for @Validate decorator
+ * Can be a Zod schema (assumes body validation) or full config object
+ */
+type ValidateInput = ValidationSchema | ValidationConfig;
+/**
+ * Plugin configuration options
+ */
+interface ValidationPluginConfig {
+    /**
+     * Enable or disable validation globally (default: true)
+     */
+    enabled?: boolean;
+    /**
+     * Default strip unknown fields behavior (default: false)
+     */
+    stripUnknown?: boolean;
+    /**
+     * Default HTTP status code for validation errors (default: 400)
+     */
+    errorStatus?: number;
+    /**
+     * Global error formatter
+     */
+    errorFormatter?: ErrorFormatter;
+}
+
+/**
+ * Metadata key for @Validate decorator
+ */
+declare const VALIDATE_META: unique symbol;
+/**
+ * Configuration token for validation plugin
+ */
+declare const VALIDATION_CONFIG: unique symbol;
+/**
+ * ALS tokens for validated request data
+ * Stored in AsyncLocalStorage for request-scoped access
+ */
+declare const VALIDATED_BODY: diject.AlsToken<any>;
+declare const VALIDATED_PARAMS: diject.AlsToken<any>;
+declare const VALIDATED_QUERY: diject.AlsToken<any>;
+declare const VALIDATED_HEADERS: diject.AlsToken<any>;
+
+/**
+ * @Validate decorator - Validates request data using Zod schemas
+ *
+ * Smart defaults: Pass a schema directly for body validation (most common use case)
+ *
+ * @example
+ * // Body validation (90% use case)
+ * @Validate(CreateUserSchema)
+ * createUser(@Body() data) { ... }
+ *
+ * @example
+ * // Multiple targets
+ * @Validate({
+ *   body: CreateUserSchema,
+ *   params: z.object({ id: z.string().uuid() })
+ * })
+ * updateUser(@Params('id') id, @Body() data) { ... }
+ *
+ * @example
+ * // With options
+ * @Validate({
+ *   body: CreateUserSchema,
+ *   stripUnknown: true,
+ *   errorStatus: 422
+ * })
+ * createUser(@Body() data) { ... }
+ */
+declare function Validate(input: ValidateInput): MethodDecorator;
+/**
+ * Helper to retrieve validation config from metadata
+ */
+declare function getValidationConfig(target: any, methodName?: string | symbol): ValidationConfig | undefined;
+
+/**
+ * Validation plugin factory
+ *
+ * Provides request validation using Zod schemas with smart defaults
+ *
+ * @example
+ * // Default configuration
+ * const server = new Server()
+ *   .use(validation())
+ *
+ * @example
+ * // Custom configuration
+ * const server = new Server()
+ *   .use(validation({
+ *     stripUnknown: true,
+ *     errorStatus: 422,
+ *     errorFormatter: customFormatter
+ *   }))
+ *
+ * @example
+ * // Disable validation
+ * const server = new Server()
+ *   .use(validation({ enabled: false }))
+ */
+declare const validation: (config?: ValidationPluginConfig) => najm_core.NajmPlugin;
+
+declare class ValidationService {
+    private container;
+    private scanner;
+    private config;
+    private log;
+    private validationCount;
+    private defaultErrorStatus;
+    private defaultStripUnknown;
+    private defaultErrorFormatter?;
+    scan(): Promise<void>;
+    configure(): Promise<void>;
+    activate(): Promise<void>;
+    onReady(): Promise<void>;
+    /**
+     * Create validation middleware for a specific route
+     * Note: ctx param required by Hono but we use ALS internally
+     */
+    private createValidationMiddleware;
+    /**
+     * Validate a specific request target using ALS
+     */
+    private validateTarget;
+    private isZodErrorLike;
+    /**
+     * Extract data from ALS instead of ctx
+     */
+    private extractData;
+    private throwValidationError;
+}
+
+export { type ErrorFormatter, VALIDATED_BODY, VALIDATED_HEADERS, VALIDATED_PARAMS, VALIDATED_QUERY, VALIDATE_META, VALIDATION_CONFIG, Validate, type ValidateInput, type ValidationConfig, type ValidationPluginConfig, type ValidationSchema, ValidationService, type ValidationTarget, type ZodErrorLike, type ZodIssueLike, getValidationConfig, validation };

package/dist/index.js

@@ -0,0 +1,221 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/tokens.ts
+import { createAlsToken } from "najm-core";
+var VALIDATE_META = /* @__PURE__ */ Symbol("validate");
+var VALIDATION_CONFIG = /* @__PURE__ */ Symbol("validation:config");
+var VALIDATED_BODY = createAlsToken("validated:body");
+var VALIDATED_PARAMS = createAlsToken("validated:params");
+var VALIDATED_QUERY = createAlsToken("validated:query");
+var VALIDATED_HEADERS = createAlsToken("validated:headers");
+
+// src/decorator.ts
+import { MetaHelper } from "najm-core";
+function isValidationSchema(value) {
+  return value !== null && value !== void 0 && typeof value === "object" && "parse" in value && typeof value.parse === "function";
+}
+__name(isValidationSchema, "isValidationSchema");
+function Validate(input) {
+  const config = isValidationSchema(input) ? { body: input } : input;
+  return (target, methodName) => {
+    MetaHelper.define(VALIDATE_META, config, target[methodName]);
+  };
+}
+__name(Validate, "Validate");
+function getValidationConfig(target, methodName) {
+  if (methodName) {
+    return MetaHelper.get(VALIDATE_META, target[methodName]);
+  }
+  return MetaHelper.get(VALIDATE_META, target);
+}
+__name(getValidationConfig, "getValidationConfig");
+
+// src/ValidationPlugin.ts
+import { plugin } from "najm-core";
+
+// src/ValidationService.ts
+import { LoggerService, ScannerService, Scan, ScanType, INJECTION_TYPES, Err } from "najm-core";
+import { Container, DI, Inject, Meta, Service } from "najm-core";
+import { CONTEXT, REQUEST, PARSER } from "najm-core";
+var __decorate = function(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = function(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var _a;
+var _b;
+var _c;
+var ValidationService = class ValidationService2 {
+  static {
+    __name(this, "ValidationService");
+  }
+  container;
+  scanner;
+  config;
+  log;
+  validationCount = 0;
+  defaultErrorStatus = 400;
+  defaultStripUnknown = false;
+  defaultErrorFormatter;
+  async scan() {
+    this.validationCount = 0;
+    if (this.config?.enabled === false) {
+      this.log.info("Validation plugin disabled");
+      return;
+    }
+    this.scanner.scan(ScanType.CONTROLLER, {
+      onMethod: /* @__PURE__ */ __name((controller, methodName) => {
+        const validationConfig = getValidationConfig(controller.prototype, methodName);
+        if (validationConfig) {
+          this.container.setInjection({
+            type: INJECTION_TYPES.MIDDLEWARE,
+            target: controller,
+            methodName,
+            handler: this.createValidationMiddleware(validationConfig),
+            order: 45,
+            source: "validation"
+          });
+          this.validationCount++;
+        }
+      }, "onMethod")
+    });
+  }
+  async configure() {
+    if (this.config) {
+      this.defaultErrorStatus = this.config.errorStatus ?? 400;
+      this.defaultStripUnknown = this.config.stripUnknown ?? false;
+      this.defaultErrorFormatter = this.config.errorFormatter;
+    }
+  }
+  async activate() {
+  }
+  async onReady() {
+    if (this.validationCount > 0) {
+      this.log.info(`Validation: ${this.validationCount} route(s) configured`);
+    }
+  }
+  /**
+   * Create validation middleware for a specific route
+   * Note: ctx param required by Hono but we use ALS internally
+   */
+  createValidationMiddleware(config) {
+    return async (_ctx, next) => {
+      const targets = ["body", "params", "query", "headers"];
+      for (const target of targets) {
+        const schema = config[target];
+        if (schema) {
+          await this.validateTarget(target, schema, config);
+        }
+      }
+      return next();
+    };
+  }
+  /**
+   * Validate a specific request target using ALS
+   */
+  async validateTarget(target, schema, config) {
+    const data = await this.extractData(target);
+    const shouldStrip = config.stripUnknown ?? this.defaultStripUnknown;
+    try {
+      const finalSchema = shouldStrip && typeof schema.strip === "function" ? schema.strip() : schema;
+      const validatedData = finalSchema.parse(data);
+      const tokenMap = {
+        body: VALIDATED_BODY,
+        params: VALIDATED_PARAMS,
+        query: VALIDATED_QUERY,
+        headers: VALIDATED_HEADERS
+      };
+      this.container.set(tokenMap[target], validatedData);
+    } catch (error) {
+      if (this.isZodErrorLike(error)) {
+        this.throwValidationError(error, target, config);
+      }
+      throw error;
+    }
+  }
+  isZodErrorLike(error) {
+    if (!error || typeof error !== "object")
+      return false;
+    const issues = error.issues;
+    return Array.isArray(issues);
+  }
+  /**
+   * Extract data from ALS instead of ctx
+   */
+  async extractData(target) {
+    const request = this.container.get(REQUEST);
+    const parser = this.container.get(PARSER);
+    const context = this.container.get(CONTEXT);
+    switch (target) {
+      case "body":
+        return parser.parseBody();
+      case "params":
+        return context.req.param();
+      // or request.params if HRequest has it parsed
+      case "query":
+        return request.query;
+      case "headers":
+        return request.headers;
+      default:
+        return {};
+    }
+  }
+  throwValidationError(error, target, config) {
+    const errorStatus = config.errorStatus ?? this.defaultErrorStatus;
+    const formatter = config.errorFormatter ?? this.defaultErrorFormatter;
+    if (formatter) {
+      try {
+        const customResponse = formatter(error, target);
+        const customError = Err.createFromZod(error, target, errorStatus);
+        customError.toJSON = () => customResponse;
+        throw customError;
+      } catch (formatterError) {
+        if (formatterError instanceof Error && formatterError.message.includes("Cannot read")) {
+          Err.fromZod(error, target, errorStatus);
+        }
+        throw formatterError;
+      }
+    }
+    Err.fromZod(error, target, errorStatus);
+  }
+};
+__decorate([
+  DI(),
+  __metadata("design:type", typeof (_a = typeof Container !== "undefined" && Container) === "function" ? _a : Object)
+], ValidationService.prototype, "container", void 0);
+__decorate([
+  Scan(),
+  __metadata("design:type", typeof (_b = typeof ScannerService !== "undefined" && ScannerService) === "function" ? _b : Object)
+], ValidationService.prototype, "scanner", void 0);
+__decorate([
+  Inject(VALIDATION_CONFIG),
+  __metadata("design:type", Object)
+], ValidationService.prototype, "config", void 0);
+__decorate([
+  Inject(LoggerService),
+  __metadata("design:type", typeof (_c = typeof LoggerService !== "undefined" && LoggerService) === "function" ? _c : Object)
+], ValidationService.prototype, "log", void 0);
+ValidationService = __decorate([
+  Service(),
+  Meta({ layer: "plugin", order: 45 })
+], ValidationService);
+
+// src/ValidationPlugin.ts
+var validation = /* @__PURE__ */ __name((config = {}) => plugin("validation").version("0.0.1").services(ValidationService).config(VALIDATION_CONFIG, config).build(), "validation");
+export {
+  VALIDATED_BODY,
+  VALIDATED_HEADERS,
+  VALIDATED_PARAMS,
+  VALIDATED_QUERY,
+  VALIDATE_META,
+  VALIDATION_CONFIG,
+  Validate,
+  ValidationService,
+  getValidationConfig,
+  validation
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "najm-validation",
+  "version": "0.1.1",
+  "description": "Request validation plugin for Najm framework using Zod schemas",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "bun": "./src/*.ts",
+      "types": "./src/*.ts",
+      "import": "./src/*.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "typecheck:test": "tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "najm-core": "^0.1.1"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0"
+  }
+}