@vercube/schema 0.0.19

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present - Vercube
+
+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,146 @@
+<div align="center">
+  <a href="https://vercube.dev/"><img src="https://github.com/OskarLebuda/vue-lazy-hydration/raw/main/.github/assets/logo.png?raw=true" alt="Vite logo" width="200"></a>
+  <br>
+  <br>
+
+  # Vercube
+  
+  Next generation HTTP framework
+  
+  <a href="https://www.npmjs.com/package/@vercube/schema">
+    <img src="https://img.shields.io/npm/v/%40vercube%2Fschema?style=for-the-badge&logo=npm&color=%23767eff" alt="npm"/>
+  </a>
+  <a href="https://www.npmjs.com/package/@vercube/schema">
+    <img src="https://img.shields.io/npm/dm/%40vercube%2Fschema?style=for-the-badge&logo=npm&color=%23767eff" alt="npm"/>
+  </a>
+  <a href="https://github.com/vercube/vercube/blob/main/LICENSE" target="_blank">
+    <img src="https://img.shields.io/npm/l/%40vercube%2Fschema?style=for-the-badge&color=%23767eff" alt="License"/>
+  </a>
+  <br/>
+  <br/>
+</div>
+
+An ultra-efficient JavaScript server framework that runs anywhere - Node.js, Bun, or Deno - with unmatched flexibility and complete configurability for developers who refuse to sacrifice speed or control.
+
+---
+
+## 🧩 `@vercube/schema` Module
+
+The `@vercube/schema` module provides a unified, provider-agnostic interface for managing OpenAPI schemas.  
+It abstracts schema definitions into a consistent API that works across tools and environments, enabling easy switching between providers without modifying your application code.
+
+### ✅ Key Features
+
+- Seamless integration with OpenAPI
+- Zod-based schema definition
+- Works out-of-the-box with route decorators
+- Compatible with custom validation and metadata
+- Supports both static and runtime schema generation
+
+---
+
+## 🚀 Installation
+
+```bash
+pnpm install @vercube/schema
+````
+
+---
+
+## ⚙️ Usage
+
+Integrate the Schema plugin into your app setup:
+
+```ts
+import { createApp } from '@vercube/core';
+import { SchemaPlugin } from '@vercube/schema';
+
+const app = createApp({
+  setup: async (app) => {
+    app.addPlugin(SchemaPlugin);
+  }
+});
+```
+
+---
+
+## 🧵 Route Schema Decorators
+
+The `@Schema` decorator lets you define OpenAPI-compatible schema definitions directly on your routes.
+It leverages [`@asteasolutions/zod-to-openapi`](https://github.com/asteasolutions/zod-to-openapi) for automatic schema translation and also supports `.openapi` properties on Zod schemas.
+
+```ts
+import { Controller, Post, Body } from '@vercube/core';
+import { Schema } from '@vercube/schema';
+
+@Controller('/users')
+export class UsersController {
+
+  @Post('/')
+  @Schema({
+    request: {
+      params: ParamsSchema,
+    },
+    responses: {
+      200: {
+        description: 'Retrieve the user',
+        content: {
+          'application/json': {
+            schema: UserSchema,
+          },
+        },
+      },
+    },
+  })
+  public async insertUser(
+    @Body({ validationSchema: UserSchema }) user: User,
+  ): Promise<void> {
+    console.log(user);
+  }
+}
+```
+
+## 📄 Runtime Access to OpenAPI Schema
+
+When the SchemaPlugin is added to your application, a special controller is automatically registered.
+This controller exposes the full OpenAPI schema at runtime and is available without any additional configuration.
+
+You can access it at:
+```
+http://localhost:3000/_schema
+```
+
+This makes it easy to integrate with tools like Swagger UI, Postman, or for debugging and documentation purposes.
+
+### ✨ Automatic Resolution
+
+* The `@Schema` decorator automatically resolves:
+
+  * HTTP method and route path
+  * Request body schema (`@Body`)
+  * Query parameters (`@QueryParams`)
+  * Path parameters (`@Params`)
+
+---
+
+## 📚 Documentation
+
+Full documentation is available at [**vercube.dev**](https://vercube.dev).
+Explore guides, API references, and best practices to master Vercube.
+
+---
+
+## 🙌 Credits
+
+This module is inspired by:
+
+* [@asteasolutions/zod-to-openapi](https://github.com/asteasolutions/zod-to-openapi)
+* [Hono Zod OpenAPI Example](https://hono.dev/examples/zod-openapi)
+* [Nitro OpenAPI](https://nitro.build/config#openapi)
+
+---
+
+## 🪪 License
+
+[MIT License](https://github.com/vercube/vercube/blob/main/LICENSE)
+

package/dist/index.d.mts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { RouteConfig } from "@asteasolutions/zod-to-openapi";
+import { App, BasePlugin } from "@vercube/core";
+
+//#region src/Decorators/Schema.d.ts
+interface SchemaDecoratorOptions extends Omit<RouteConfig, 'method' | 'path'> {}
+/**
+ * A decorator function for registering OpenAPI schema metadata for a route.
+ *
+ * This function creates an instance of the SchemaDecorator class and registers
+ * the schema with the specified options.
+ *
+ * @param {SchemaDecoratorOptions} params - The schema options for the route.
+ * @returns {Function} - The decorator function.
+ */
+declare function Schema(params: SchemaDecoratorOptions): Function;
+//#endregion
+//#region src/Plugins/SchemaPlugin.d.ts
+/**
+ * Schema Plugin for Vercube framework
+ *
+ * Provides OpenAPI/Swagger schema generation and validation capabilities:
+ * - Automatic OpenAPI schema generation from Zod schemas
+ * - Route-level schema validation via @Schema decorator
+ * - Runtime schema access via /_schema endpoint
+ * - Seamless integration with request validation (@Body, @Query, etc)
+ *
+ * @example
+ * ```ts
+ * import { createApp } from '@vercube/core';
+ * import { SchemaPlugin } from '@vercube/schema';
+ *
+ * const app = createApp({
+ *   setup: async (app) => {
+ *     app.addPlugin(SchemaPlugin);
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link https://vercube.dev} for full documentation
+ */
+declare class SchemaPlugin<T = unknown> extends BasePlugin<T> {
+  /**
+   * The name of the plugin.
+   * @override
+   */
+  name: string;
+  /**
+   * Method to use the plugin with the given app.
+   * @param {App} app - The application instance.
+   * @returns {void | Promise<void>}
+   * @override
+   */
+  use(app: App, options: T): void | Promise<void>;
+}
+//#endregion
+export { Schema, SchemaPlugin, z };

package/dist/index.mjs

@@ -0,0 +1,219 @@
+import "node:module";
+import { z } from "zod";
+import { OpenAPIRegistry, OpenApiGeneratorV3, extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { BaseDecorator, Inject, createDecorator } from "@vercube/di";
+import defu from "defu";
+import { BasePlugin, Controller, Get } from "@vercube/core";
+
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function() {
+	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+//#region src/Services/SchemaRegistry.ts
+/**
+* Manages the OpenAPI schema registry and provides utilities to generate OpenAPI components
+* from registered Zod schemas using the @asteasolutions/zod-to-openapi library.
+*
+* This class is intended to be used for collecting and generating OpenAPI-compatible
+* schema definitions for API documentation and validation purposes.
+*/
+var SchemaRegistry = class {
+	/**
+	* Internal registry instance for storing OpenAPI schema definitions.
+	* @private
+	*/
+	fRegistry = new OpenAPIRegistry();
+	/**
+	* Registers a route configuration with the registry.
+	* @param cfg - The route configuration to register.
+	*/
+	register(cfg) {
+		this.fRegistry.registerPath(cfg);
+	}
+	/**
+	* Generates OpenAPI components from the registered schemas.
+	*
+	* @async
+	* @returns {Promise<unknown>} A promise that resolves to the generated OpenAPI components object.
+	*/
+	async generateSchema() {
+		return new OpenApiGeneratorV3(this.fRegistry.definitions).generateDocument({
+			openapi: "3.0.0",
+			info: {
+				title: "API",
+				version: "1.0.0"
+			}
+		});
+	}
+};
+
+//#endregion
+//#region src/Resolvers/SchemaBodyResolver.ts
+/**
+* Resolves the body schema for a given method.
+* @param metadata - The metadata of the method.
+* @param schema - The schema to resolve the body for.
+* @returns void
+*/
+function SchemaBodyResolver(metadata, schema) {
+	const body = metadata.args.find((arg) => arg.type === "body");
+	if (!body || !body.validationSchema) return;
+	schema.request = defu(schema?.request ?? {}, { body: { content: { "application/json": { schema: body.validationSchema } } } });
+}
+
+//#endregion
+//#region src/Resolvers/SchemaQueryParamsResolver.ts
+/**
+* Resolves the query params schema for a given method.
+* @param metadata - The metadata of the method.
+* @param schema - The schema to resolve the query params for.
+* @returns void
+*/
+function SchemaQueryParamsResolver(metadata, schema) {
+	const query = metadata.args.find((arg) => arg.type === "query-params");
+	if (!query || !query.validationSchema) return;
+	schema.request = defu(schema?.request ?? {}, { query: query.validationSchema });
+}
+
+//#endregion
+//#region ../../node_modules/.pnpm/@oxc-project+runtime@0.77.3/node_modules/@oxc-project/runtime/src/helpers/decorate.js
+var require_decorate = __commonJS({ "../../node_modules/.pnpm/@oxc-project+runtime@0.77.3/node_modules/@oxc-project/runtime/src/helpers/decorate.js"(exports, module) {
+	function __decorate(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;
+	}
+	module.exports = __decorate, module.exports.__esModule = true, module.exports["default"] = module.exports;
+} });
+
+//#endregion
+//#region src/Decorators/Schema.ts
+var import_decorate$1 = __toESM(require_decorate());
+/**
+* A decorator class for handling OpenAPI schema registration for routes.
+*
+* This class extends BaseDecorator and is used to register route schemas
+* with the SchemaRegistry. It also applies schema resolvers for responses,
+* body, and query parameters.
+*
+* @extends {BaseDecorator<SchemaDecoratorOptions>}
+*/
+var SchemaDecorator = class extends BaseDecorator {
+	gSchemaRegistry;
+	async created() {
+		await new Promise((resolve) => setTimeout(resolve, 0));
+		const _methodMeta = this.prototype.__metadata.__methods[this.propertyName];
+		const _schema = {
+			method: _methodMeta.method.toLowerCase(),
+			path: _methodMeta.url,
+			...this.options
+		};
+		SchemaBodyResolver(_methodMeta, _schema);
+		SchemaQueryParamsResolver(_methodMeta, _schema);
+		this.gSchemaRegistry.register(_schema);
+	}
+};
+(0, import_decorate$1.default)([Inject(SchemaRegistry)], SchemaDecorator.prototype, "gSchemaRegistry", void 0);
+/**
+* A decorator function for registering OpenAPI schema metadata for a route.
+*
+* This function creates an instance of the SchemaDecorator class and registers
+* the schema with the specified options.
+*
+* @param {SchemaDecoratorOptions} params - The schema options for the route.
+* @returns {Function} - The decorator function.
+*/
+function Schema(params) {
+	return createDecorator(SchemaDecorator, params);
+}
+
+//#endregion
+//#region src/Controllers/SchameController.ts
+var import_decorate = __toESM(require_decorate(), 1);
+let SchemaController = class SchemaController$1 {
+	gSchemaRegistry;
+	/**
+	* Handles GET requests to retrieve the generated OpenAPI schema.
+	*
+	* @returns {Promise<unknown>} The generated OpenAPI schema object.
+	*/
+	async get() {
+		return this.gSchemaRegistry.generateSchema();
+	}
+};
+(0, import_decorate.default)([Inject(SchemaRegistry)], SchemaController.prototype, "gSchemaRegistry", void 0);
+(0, import_decorate.default)([Get("/")], SchemaController.prototype, "get", null);
+SchemaController = (0, import_decorate.default)([Controller("/_schema")], SchemaController);
+
+//#endregion
+//#region src/Plugins/SchemaPlugin.ts
+/**
+* Schema Plugin for Vercube framework
+* 
+* Provides OpenAPI/Swagger schema generation and validation capabilities:
+* - Automatic OpenAPI schema generation from Zod schemas
+* - Route-level schema validation via @Schema decorator
+* - Runtime schema access via /_schema endpoint
+* - Seamless integration with request validation (@Body, @Query, etc)
+* 
+* @example
+* ```ts
+* import { createApp } from '@vercube/core';
+* import { SchemaPlugin } from '@vercube/schema';
+* 
+* const app = createApp({
+*   setup: async (app) => {
+*     app.addPlugin(SchemaPlugin);
+*   }
+* });
+* ```
+* 
+* @see {@link https://vercube.dev} for full documentation
+*/
+var SchemaPlugin = class extends BasePlugin {
+	/**
+	* The name of the plugin.
+	* @override
+	*/
+	name = "SchemaPlugin";
+	/**
+	* Method to use the plugin with the given app.
+	* @param {App} app - The application instance.
+	* @returns {void | Promise<void>}
+	* @override
+	*/
+	use(app, options) {
+		app.container.bind(SchemaRegistry);
+		app.container.bind(SchemaController);
+	}
+};
+
+//#endregion
+//#region src/index.ts
+extendZodWithOpenApi(z);
+
+//#endregion
+export { Schema, SchemaPlugin, z };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vercube/schema",
+  "version": "0.0.19",
+  "description": "Schema (swagger) module for Vercube framework",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercube/vercube.git",
+    "directory": "packages/schema"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "vercube",
+    "schema",
+    "swagger"
+  ],
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "8.0.0",
+    "@standard-schema/spec": "1.0.0",
+    "defu": "6.1.4",
+    "zod": "4.0.10",
+    "@vercube/core": "0.0.19",
+    "@vercube/di": "0.0.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}