@nathan3boss/expressu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nathan3boss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# expressu
+
+![npm version](https://img.shields.io/npm/v/expressu?style=flat&logo=npm)
+![CI](https://img.shields.io/github/actions/workflow/status/nathan2slime/expressu/ci.yml?branch=main&style=flat&logo=github)
+
+Composable Express middleware builders for request validators.
+
+## What it does
+
+- Validates `body`, `params`, and `query`.
+- Supports a global validation message override.
+- Keeps the core adapter-agnostic.
+- Ships adapters for Zod, Yup, and class-transformer.
+
+## Global config
+
+Set a default validation message once at app startup.
+
+```ts
+import { configure } from "expressu";
+
+configure({ validationMessage: "Dados inválidos" });
+```
+
+## Core usage
+
+```ts
+import express from "express";
+import { createBodyValidator, createValidationAdapter } from "expressu";
+
+const app = express();
+
+const adapter = createValidationAdapter((input: { userId: string }) => ({
+  userId: Number(input.userId),
+}));
+
+app.use(express.json());
+
+app.post("/users", createBodyValidator(adapter), (req, res) => {
+  res.json(req.body);
+});
+```
+
+### zod adapter
+
+```ts
+import express from "express";
+import { z } from "zod";
+import { createBodyValidator } from "expressu";
+import { createZodAdapter } from "expressu/zod";
+
+const app = express();
+const schema = z.object({ userId: z.coerce.number().int() });
+
+app.use(express.json());
+app.post("/users", createBodyValidator(createZodAdapter(schema)), (req, res) => {
+  res.json(req.body);
+});
+```
+
+### yup adapter
+
+```ts
+import * as yup from "yup";
+import { createBodyValidator } from "expressu";
+import { createYupAdapter } from "expressu/yup";
+
+const schema = yup.object({ userId: yup.number().required().integer() });
+
+app.post("/users", createBodyValidator(createYupAdapter(schema)), (req, res) => {
+  res.json(req.body);
+});
+```
+
+### class-transformer adapter
+
+```ts
+import { createBodyValidator } from "expressu";
+import { createClassTransformerAdapter } from "expressu/class-transformer";
+
+class UserDto {
+  id!: number;
+  name!: string;
+}
+
+app.post(
+  "/users",
+  createBodyValidator(
+    createClassTransformerAdapter(UserDto, {
+      validate: (value) => value.id > 0 && value.name.length > 0,
+    }),
+  ),
+  (req, res) => {
+    res.json(req.body);
+  },
+);
+```
+
+
+## Scripts
+
+- `pnpm build`
+- `pnpm typecheck`
+- `pnpm lint`
+- `pnpm test`
+- `pnpm test:coverage`

package/dist/adapters/class-transformer.d.ts

@@ -0,0 +1,36 @@
+import { type ClassTransformOptions } from "class-transformer";
+import type { ValidationAdapter } from "../types";
+import { createBodyValidator, createParamsValidator, createQueryValidator, createValidatorMiddleware } from "../validator";
+type ClassConstructor<TOutput> = new () => TOutput;
+/**
+ * Optional overrides supported by the class-transformer adapter.
+ */
+type ClassTransformerAdapterOverrides<TOutput> = Partial<{
+    message: string;
+    validate: (value: TOutput) => boolean;
+}>;
+/**
+ * Adapter options for class-transformer-based validators.
+ */
+export type ClassTransformerAdapterOptions<TOutput> = ClassTransformOptions & ClassTransformerAdapterOverrides<TOutput>;
+/**
+ * Creates a class-transformer-backed validation adapter.
+ */
+export declare const createClassTransformerAdapter: <TOutput>(target: ClassConstructor<TOutput>, options?: ClassTransformerAdapterOptions<TOutput>) => ValidationAdapter<unknown, TOutput>;
+/**
+ * Builds middleware for any request target using class-transformer.
+ */
+export declare const classTransformerMiddleware: <TOutput>(target: ClassConstructor<TOutput>, options?: ClassTransformerAdapterOptions<TOutput>) => ReturnType<typeof createValidatorMiddleware>;
+/**
+ * Builds middleware that validates `req.body` with class-transformer.
+ */
+export declare const classTransformerBodyValidator: <TOutput>(target: ClassConstructor<TOutput>, options?: ClassTransformerAdapterOptions<TOutput>) => ReturnType<typeof createBodyValidator>;
+/**
+ * Builds middleware that validates `req.params` with class-transformer.
+ */
+export declare const classTransformerParamsValidator: <TOutput>(target: ClassConstructor<TOutput>, options?: ClassTransformerAdapterOptions<TOutput>) => ReturnType<typeof createParamsValidator>;
+/**
+ * Builds middleware that validates `req.query` with class-transformer.
+ */
+export declare const classTransformerQueryValidator: <TOutput>(target: ClassConstructor<TOutput>, options?: ClassTransformerAdapterOptions<TOutput>) => ReturnType<typeof createQueryValidator>;
+export {};

package/dist/adapters/yup.d.ts

@@ -0,0 +1,36 @@
+import type { ValidationAdapter } from "../types";
+import { createBodyValidator, createParamsValidator, createQueryValidator, createValidatorMiddleware } from "../validator";
+/**
+ * Options accepted by the Yup adapter.
+ */
+export type YupAdapterOptions = Partial<{
+    abortEarly: boolean;
+    context: Record<string, unknown>;
+    message: string;
+    strict: boolean;
+    stripUnknown: boolean;
+}>;
+type YupSchemaLike<TOutput> = {
+    validateSync(input: unknown, options?: YupAdapterOptions): TOutput;
+};
+/**
+ * Creates a Yup-backed validation adapter.
+ */
+export declare const createYupAdapter: <TOutput, TSchema extends YupSchemaLike<TOutput>>(schema: TSchema, options?: YupAdapterOptions) => ValidationAdapter<unknown, TOutput>;
+/**
+ * Builds middleware for any request target using a Yup schema.
+ */
+export declare const yupMiddleware: <TOutput, TSchema extends YupSchemaLike<TOutput>>(schema: TSchema, options?: YupAdapterOptions) => ReturnType<typeof createValidatorMiddleware>;
+/**
+ * Builds middleware that validates `req.body` with Yup.
+ */
+export declare const yupBodyValidator: <TOutput, TSchema extends YupSchemaLike<TOutput>>(schema: TSchema, options?: YupAdapterOptions) => ReturnType<typeof createBodyValidator>;
+/**
+ * Builds middleware that validates `req.params` with Yup.
+ */
+export declare const yupParamsValidator: <TOutput, TSchema extends YupSchemaLike<TOutput>>(schema: TSchema, options?: YupAdapterOptions) => ReturnType<typeof createParamsValidator>;
+/**
+ * Builds middleware that validates `req.query` with Yup.
+ */
+export declare const yupQueryValidator: <TOutput, TSchema extends YupSchemaLike<TOutput>>(schema: TSchema, options?: YupAdapterOptions) => ReturnType<typeof createQueryValidator>;
+export {};

package/dist/adapters/zod.d.ts

@@ -0,0 +1,23 @@
+import { type ZodTypeAny, z } from "zod";
+import type { ValidationAdapter } from "../types";
+import { createBodyValidator, createParamsValidator, createQueryValidator, createValidatorMiddleware } from "../validator";
+/**
+ * Creates a Zod-backed validation adapter.
+ */
+export declare const createZodAdapter: <TSchema extends ZodTypeAny>(schema: TSchema) => ValidationAdapter<unknown, z.output<TSchema>>;
+/**
+ * Builds middleware for any request target using a Zod schema.
+ */
+export declare const zodMiddleware: <TSchema extends ZodTypeAny>(schema: TSchema, options?: Parameters<typeof createValidatorMiddleware>[1]) => ReturnType<typeof createValidatorMiddleware>;
+/**
+ * Builds middleware that validates `req.body` with Zod.
+ */
+export declare const zodBodyValidator: <TSchema extends ZodTypeAny>(schema: TSchema, options?: Parameters<typeof createBodyValidator>[1]) => ReturnType<typeof createBodyValidator>;
+/**
+ * Builds middleware that validates `req.params` with Zod.
+ */
+export declare const zodParamsValidator: <TSchema extends ZodTypeAny>(schema: TSchema, options?: Parameters<typeof createParamsValidator>[1]) => ReturnType<typeof createParamsValidator>;
+/**
+ * Builds middleware that validates `req.query` with Zod.
+ */
+export declare const zodQueryValidator: <TSchema extends ZodTypeAny>(schema: TSchema, options?: Parameters<typeof createQueryValidator>[1]) => ReturnType<typeof createQueryValidator>;

package/dist/class-transformer.js

@@ -0,0 +1,19 @@
+import { plainToInstance } from "class-transformer";
+import { resolveValidationMessage } from "../config.js";
+import { createBodyValidator, createParamsValidator, createQueryValidator, createValidationAdapter, createValidatorMiddleware } from "../validator.js";
+const defaultFailure = (error, message)=>({
+        message,
+        issues: error instanceof Error ? error.message : error
+    });
+const createClassTransformerAdapter = (target, options = {})=>createValidationAdapter((input)=>{
+        const value = plainToInstance(target, input, options);
+        const message = resolveValidationMessage(options.message);
+        if (Array.isArray(value)) throw new Error(message);
+        if (options.validate && !options.validate(value)) throw new Error(message);
+        return value;
+    }, (error)=>defaultFailure(error, resolveValidationMessage(options.message)));
+const classTransformerMiddleware = (target, options = {})=>createValidatorMiddleware(createClassTransformerAdapter(target, options));
+const classTransformerBodyValidator = (target, options = {})=>createBodyValidator(createClassTransformerAdapter(target, options));
+const classTransformerParamsValidator = (target, options = {})=>createParamsValidator(createClassTransformerAdapter(target, options));
+const classTransformerQueryValidator = (target, options = {})=>createQueryValidator(createClassTransformerAdapter(target, options));
+export { classTransformerBodyValidator, classTransformerMiddleware, classTransformerParamsValidator, classTransformerQueryValidator, createClassTransformerAdapter };

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_VALIDATION_MESSAGE = "Validation failed";
+/**
+ * Global configuration shape for Nexva consumers.
+ */
+export type ExpressuConfig = Partial<{
+    validationMessage: string;
+}>;
+/**
+ * Updates the global Nexva configuration.
+ */
+export declare const configure: (config?: ExpressuConfig) => void;
+/**
+ * Resets the global Nexva configuration to defaults.
+ */
+export declare const resetConfig: () => void;
+/**
+ * Returns the current global Nexva configuration.
+ */
+export declare const getConfig: () => Readonly<ExpressuConfig>;
+/**
+ * Resolves the validation message using the provided override, the global config,
+ * and the package default.
+ */
+export declare const resolveValidationMessage: (message?: string) => string;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./config";
+export * from "./types";
+export * from "./validator";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./config.js";
+export * from "./types.js";
+export * from "./validator.js";

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Supported request targets that validators can replace.
+ */
+export type ValidationTarget = "body" | "params" | "query";
+/**
+ * Standard validation failure payload returned by middleware.
+ */
+export type ValidationFailure = {
+    message: string;
+} & Partial<{
+    issues: unknown;
+}>;
+/**
+ * Generic validation adapter contract for parsing request payloads.
+ */
+export type ValidationAdapter<TInput = unknown, TOutput = TInput> = {
+    parse(input: TInput): TOutput;
+} & Partial<{
+    toFailure: (error: unknown) => ValidationFailure;
+}>;
+/**
+ * Common middleware options for validation builders.
+ */
+export type MiddlewareOptions = Partial<{
+    target: ValidationTarget;
+    statusCode: number;
+    message: string;
+}>;

package/dist/validator.d.ts

@@ -0,0 +1,22 @@
+import type { RequestHandler } from "express";
+import type { MiddlewareOptions, ValidationAdapter, ValidationFailure } from "./types";
+/**
+ * Creates a validation adapter from a parse function and an optional error mapper.
+ */
+export declare const createValidationAdapter: <TInput, TOutput>(parse: (input: TInput) => TOutput, toFailure?: (error: unknown) => ValidationFailure) => ValidationAdapter<TInput, TOutput>;
+/**
+ * Builds Express middleware that validates and replaces a request target.
+ */
+export declare const createValidatorMiddleware: <TInput, TOutput>(adapter: ValidationAdapter<TInput, TOutput>, options?: MiddlewareOptions) => RequestHandler;
+/**
+ * Builds middleware that validates `req.body`.
+ */
+export declare const createBodyValidator: <TInput, TOutput>(adapter: ValidationAdapter<TInput, TOutput>, options?: Omit<MiddlewareOptions, "target">) => RequestHandler;
+/**
+ * Builds middleware that validates `req.params`.
+ */
+export declare const createParamsValidator: <TInput, TOutput>(adapter: ValidationAdapter<TInput, TOutput>, options?: Omit<MiddlewareOptions, "target">) => RequestHandler;
+/**
+ * Builds middleware that validates `req.query`.
+ */
+export declare const createQueryValidator: <TInput, TOutput>(adapter: ValidationAdapter<TInput, TOutput>, options?: Omit<MiddlewareOptions, "target">) => RequestHandler;

package/dist/yup.js

@@ -0,0 +1,23 @@
+import { ValidationError } from "yup";
+import { resolveValidationMessage } from "../config.js";
+import { createBodyValidator, createParamsValidator, createQueryValidator, createValidationAdapter, createValidatorMiddleware } from "../validator.js";
+const defaultFailure = (error, message)=>({
+        message,
+        issues: error instanceof Error ? error.message : error
+    });
+const createYupAdapter = (schema, options = {})=>createValidationAdapter((input)=>schema.validateSync(input, options), (error)=>{
+        if (error instanceof ValidationError) return {
+            message: resolveValidationMessage(options.message),
+            issues: {
+                errors: error.errors,
+                inner: error.inner,
+                path: error.path
+            }
+        };
+        return defaultFailure(error, resolveValidationMessage(options.message));
+    });
+const yupMiddleware = (schema, options = {})=>createValidatorMiddleware(createYupAdapter(schema, options));
+const yupBodyValidator = (schema, options = {})=>createBodyValidator(createYupAdapter(schema, options));
+const yupParamsValidator = (schema, options = {})=>createParamsValidator(createYupAdapter(schema, options));
+const yupQueryValidator = (schema, options = {})=>createQueryValidator(createYupAdapter(schema, options));
+export { createYupAdapter, yupBodyValidator, yupMiddleware, yupParamsValidator, yupQueryValidator };

package/dist/zod.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { resolveValidationMessage } from "../config.js";
+import { createBodyValidator, createParamsValidator, createQueryValidator, createValidationAdapter, createValidatorMiddleware } from "../validator.js";
+const createZodAdapter = (schema)=>createValidationAdapter((input)=>schema.parse(input), (error)=>{
+        if (error instanceof z.ZodError) return {
+            message: resolveValidationMessage(),
+            issues: error.issues
+        };
+        return {
+            message: resolveValidationMessage(),
+            issues: error
+        };
+    });
+const zodMiddleware = (schema, options = {})=>createValidatorMiddleware(createZodAdapter(schema), options);
+const zodBodyValidator = (schema, options = {})=>createBodyValidator(createZodAdapter(schema), options);
+const zodParamsValidator = (schema, options = {})=>createParamsValidator(createZodAdapter(schema), options);
+const zodQueryValidator = (schema, options = {})=>createQueryValidator(createZodAdapter(schema), options);
+export { createZodAdapter, zodBodyValidator, zodMiddleware, zodParamsValidator, zodQueryValidator };

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@nathan3boss/expressu",
+  "version": "0.1.0",
+  "description": "Composable middleware builders for Express validators",
+  "license": "MIT",
+  "author": "nathan2slime",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nathan2slime/expressu.git"
+  },
+  "homepage": "https://github.com/nathan2slime/expressu#readme",
+  "bugs": {
+    "url": "https://github.com/nathan2slime/expressu/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "packageManager": "pnpm@10.30.3",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./zod": {
+      "types": "./dist/adapters/zod.d.ts",
+      "import": "./dist/adapters/zod.js"
+    },
+    "./yup": {
+      "types": "./dist/adapters/yup.d.ts",
+      "import": "./dist/adapters/yup.js"
+    },
+    "./class-transformer": {
+      "types": "./dist/adapters/class-transformer.d.ts",
+      "import": "./dist/adapters/class-transformer.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rslib",
+    "dev": "rslib --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "test": "rstest --globals",
+    "test:coverage": "rstest --globals --coverage",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish",
+    "prepare": "lefthook install"
+  },
+  "peerDependencies": {
+    "class-transformer": "^0.5.1",
+    "express": "^5.2.1",
+    "yup": "^1.6.1",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "class-transformer": {
+      "optional": true
+    },
+    "yup": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@changesets/cli": "^2.29.0",
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0",
+    "@rslib/core": "^0.20.0",
+    "@rstest/core": "^0.9.6",
+    "@rstest/coverage-istanbul": "^0.3.1",
+    "class-transformer": "^0.5.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.12.2",
+    "lefthook": "^1.10.10",
+    "typescript": "^5.9.2",
+    "yup": "^1.6.1",
+    "zod": "^4.3.6"
+  }
+}