@tahminator/sapling 1.5.27-beta.3d0c6593 → 1.5.28-beta.583b1882

package/dist/index.cjs

@@ -507,6 +507,60 @@ function _resolve(ctor) {
 	return _InjectableRegistry.get(ctor);
 }
 //#endregion
+//#region src/annotation/request.ts
+const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
+function _getOrCreateDef(ctor, fnName) {
+	let byFn = _requestSchemaStore.get(ctor);
+	if (!byFn) {
+		byFn = /* @__PURE__ */ new Map();
+		_requestSchemaStore.set(ctor, byFn);
+	}
+	const existing = byFn.get(fnName);
+	if (existing) return existing;
+	const created = {};
+	byFn.set(fnName, created);
+	return created;
+}
+function _setOnce(def, key, schema, fnName) {
+	if (def[key]) throw new Error(`Duplicate request schema for "${String(key)}" on method "${fnName}"`);
+	def[key] = schema;
+}
+function RequestBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateDef(ctor, fnName), "body", schema, fnName);
+	};
+}
+function RequestParam(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateDef(ctor, fnName), "param", schema, fnName);
+	};
+}
+function RequestQuery(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateDef(ctor, fnName), "query", schema, fnName);
+	};
+}
+function _getRequestSchemas(ctor, fnName) {
+	return _requestSchemaStore.get(ctor)?.get(fnName);
+}
+function _formatIssues(issues) {
+	return issues.map((i) => {
+		const path = Array.isArray(i.path) ? i.path.map((seg) => typeof seg === "object" && seg ? String(seg.key) : String(seg)).join(".") : "";
+		return path ? `${path}: ${i.message}` : i.message;
+	}).join("; ");
+}
+async function _parseOrThrow(schema, input, kind) {
+	const result = await schema["~standard"].validate(input);
+	if (!result.issues) return result.value;
+	throw new ResponseStatusError(400, `${kind === "body" ? "Invalid request body" : kind === "params" ? "Invalid request params" : "Invalid request query"}: ${_formatIssues(result.issues)}`);
+}
+//#endregion
 //#region src/annotation/route.ts
 const _routeStore = /* @__PURE__ */ new WeakMap();
 /**
@@ -613,6 +667,12 @@ function Controller({ prefix = "", deps = [] } = {}) {
 			if (method !== "USE") usedRoutes.add(routeKey);
 			const methodName = methodResolve[method];
 			router[methodName](fp, async (request, response, next) => {
+				const schemas = _getRequestSchemas(target, fnName);
+				if (schemas) {
+					if (schemas.body) request.body = await _parseOrThrow(schemas.body, request.body, "body");
+					if (schemas.param) request.params = await _parseOrThrow(schemas.param, request.params, "params");
+					if (schemas.query) request.query = await _parseOrThrow(schemas.query, request.query, "query");
+				}
 				const result = await fn.bind(controllerInstance)(request, response, next);
 				if (method === "USE") return;
 				if (result instanceof ResponseEntity) {
@@ -656,6 +716,9 @@ exports.PATCH = PATCH;
 exports.POST = POST;
 exports.PUT = PUT;
 exports.RedirectView = RedirectView;
+exports.RequestBody = RequestBody;
+exports.RequestParam = RequestParam;
+exports.RequestQuery = RequestQuery;
 exports.ResponseEntity = ResponseEntity;
 exports.ResponseEntityBuilder = ResponseEntityBuilder;
 exports.ResponseStatusError = ResponseStatusError;
@@ -664,6 +727,8 @@ exports._ControllerRegistry = _ControllerRegistry;
 exports._InjectableDeps = _InjectableDeps;
 exports._InjectableRegistry = _InjectableRegistry;
 exports._Route = _Route;
+exports._getRequestSchemas = _getRequestSchemas;
 exports._getRoutes = _getRoutes;
+exports._parseOrThrow = _parseOrThrow;
 exports._resolve = _resolve;
 exports.methodResolve = methodResolve;

package/dist/index.d.cts

@@ -153,6 +153,96 @@ declare function _getRoutes(ctor: Function): readonly RouteDefinition[];
  */
 declare function MiddlewareClass(...args: Parameters<typeof Controller>): ClassDecorator;
 //#endregion
+//#region node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+//#endregion
+//#region src/annotation/request.d.ts
+type RequestSchemaDefinition = {
+  body?: StandardSchemaV1;
+  param?: StandardSchemaV1;
+  query?: StandardSchemaV1;
+};
+declare function RequestBody(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestParam(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestQuery(schema: StandardSchemaV1): MethodDecorator;
+declare function _getRequestSchemas(ctor: Function, fnName: string): RequestSchemaDefinition | undefined;
+declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: "body" | "params" | "query"): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+//#endregion
 //#region src/helper/redirect.d.ts
 /**
  * Generic HTTP redirect wrapped modeled after Spring's `RedirectView`.
@@ -418,4 +508,4 @@ declare class Sapling {
   static setDeserializeFn(this: void, fn: (value: string) => any): void;
 }
 //#endregion
-export { Class, Controller, DELETE, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRoutes, _resolve, methodResolve };
+export { Class, Controller, DELETE, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };

package/dist/index.d.mts

@@ -153,6 +153,96 @@ declare function _getRoutes(ctor: Function): readonly RouteDefinition[];
  */
 declare function MiddlewareClass(...args: Parameters<typeof Controller>): ClassDecorator;
 //#endregion
+//#region node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+//#endregion
+//#region src/annotation/request.d.ts
+type RequestSchemaDefinition = {
+  body?: StandardSchemaV1;
+  param?: StandardSchemaV1;
+  query?: StandardSchemaV1;
+};
+declare function RequestBody(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestParam(schema: StandardSchemaV1): MethodDecorator;
+declare function RequestQuery(schema: StandardSchemaV1): MethodDecorator;
+declare function _getRequestSchemas(ctor: Function, fnName: string): RequestSchemaDefinition | undefined;
+declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: "body" | "params" | "query"): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+//#endregion
 //#region src/helper/redirect.d.ts
 /**
  * Generic HTTP redirect wrapped modeled after Spring's `RedirectView`.
@@ -418,4 +508,4 @@ declare class Sapling {
   static setDeserializeFn(this: void, fn: (value: string) => any): void;
 }
 //#endregion
-export { Class, Controller, DELETE, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRoutes, _resolve, methodResolve };
+export { Class, Controller, DELETE, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };

package/dist/index.mjs

@@ -483,6 +483,60 @@ function _resolve(ctor) {
 	return _InjectableRegistry.get(ctor);
 }
 //#endregion
+//#region src/annotation/request.ts
+const _requestSchemaStore = /* @__PURE__ */ new WeakMap();
+function _getOrCreateDef(ctor, fnName) {
+	let byFn = _requestSchemaStore.get(ctor);
+	if (!byFn) {
+		byFn = /* @__PURE__ */ new Map();
+		_requestSchemaStore.set(ctor, byFn);
+	}
+	const existing = byFn.get(fnName);
+	if (existing) return existing;
+	const created = {};
+	byFn.set(fnName, created);
+	return created;
+}
+function _setOnce(def, key, schema, fnName) {
+	if (def[key]) throw new Error(`Duplicate request schema for "${String(key)}" on method "${fnName}"`);
+	def[key] = schema;
+}
+function RequestBody(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateDef(ctor, fnName), "body", schema, fnName);
+	};
+}
+function RequestParam(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateDef(ctor, fnName), "param", schema, fnName);
+	};
+}
+function RequestQuery(schema) {
+	return (target, propertyKey) => {
+		const ctor = target.constructor;
+		const fnName = String(propertyKey);
+		_setOnce(_getOrCreateDef(ctor, fnName), "query", schema, fnName);
+	};
+}
+function _getRequestSchemas(ctor, fnName) {
+	return _requestSchemaStore.get(ctor)?.get(fnName);
+}
+function _formatIssues(issues) {
+	return issues.map((i) => {
+		const path = Array.isArray(i.path) ? i.path.map((seg) => typeof seg === "object" && seg ? String(seg.key) : String(seg)).join(".") : "";
+		return path ? `${path}: ${i.message}` : i.message;
+	}).join("; ");
+}
+async function _parseOrThrow(schema, input, kind) {
+	const result = await schema["~standard"].validate(input);
+	if (!result.issues) return result.value;
+	throw new ResponseStatusError(400, `${kind === "body" ? "Invalid request body" : kind === "params" ? "Invalid request params" : "Invalid request query"}: ${_formatIssues(result.issues)}`);
+}
+//#endregion
 //#region src/annotation/route.ts
 const _routeStore = /* @__PURE__ */ new WeakMap();
 /**
@@ -589,6 +643,12 @@ function Controller({ prefix = "", deps = [] } = {}) {
 			if (method !== "USE") usedRoutes.add(routeKey);
 			const methodName = methodResolve[method];
 			router[methodName](fp, async (request, response, next) => {
+				const schemas = _getRequestSchemas(target, fnName);
+				if (schemas) {
+					if (schemas.body) request.body = await _parseOrThrow(schemas.body, request.body, "body");
+					if (schemas.param) request.params = await _parseOrThrow(schemas.param, request.params, "params");
+					if (schemas.query) request.query = await _parseOrThrow(schemas.query, request.query, "query");
+				}
 				const result = await fn.bind(controllerInstance)(request, response, next);
 				if (method === "USE") return;
 				if (result instanceof ResponseEntity) {
@@ -618,4 +678,4 @@ function MiddlewareClass(...args) {
 	return Controller(...args);
 }
 //#endregion
-export { Controller, DELETE, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRoutes, _resolve, methodResolve };
+export { Controller, DELETE, GET, HEAD, Html404ErrorPage, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tahminator/sapling",
-  "version": "1.5.27-beta.3d0c6593",
+  "version": "1.5.28-beta.583b1882",
   "author": "Tahmid Ahmed",
   "description": "A library to help you write cleaner Express.js code",
   "repository": {
@@ -41,6 +41,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@standard-schema/spec": "^1.1.0",
     "@types/express": "^5",
     "@types/supertest": "^7.2.0",
     "@vitest/coverage-istanbul": "^4.1.2",
@@ -56,5 +57,8 @@
     "typescript-eslint": "^8.57.2",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.2"
+  },
+  "inlinedDependencies": {
+    "@standard-schema/spec": "1.1.0"
   }
 }