@atozapi/nextjs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AtoZAPI Maintainers
+
+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

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @atozapi/nextjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> FastAPI-style request validation and OpenAPI metadata wrapper for Next.js App Router route handlers.
+
+[![npm version](https://img.shields.io/npm/v/@atozapi/nextjs.svg?style=flat-square&color=2563EB)](https://www.npmjs.com/package/@atozapi/nextjs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+---
+
+## ⚡ Overview
+
+`@atozapi/nextjs` brings the developer experience of **FastAPI** to **Next.js App Router** (`app/api/**/route.js|ts`):
+
+- 🛡️ **Declarative Schema Validation**: Enforce required fields, string constraints, numbers, and regex patterns.
+- 🚫 **FastAPI-Standard 422 Errors**: Standardized RFC-compliant error payloads (`detail: [{ loc, msg, type }]`).
+- ⚡ **Native Web Request Support**: Compatible with native Web standard `Request` and `Response` streams.
+- 📖 **Zero-Code OpenAPI Extraction**: Exposes route metadata for automatic scanning by `@atozapi/cli`.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @atozapi/nextjs
+```
+
+---
+
+## 🚀 Quick Start
+
+In your Next.js route handler (e.g. `app/api/users/route.js`):
+
+```javascript
+import { NextResponse } from 'next/server';
+import { nextAtozapi } from '@atozapi/nextjs';
+
+const UserCreateSchema = {
+  username: { type: 'string', minLength: 3, maxLength: 30 },
+  email: { type: 'string', pattern: '^[^@]+@[^@]+\\.[^@]+$' },
+  age: { type: 'integer', minimum: 18, optional: true }
+};
+
+export const POST = nextAtozapi(UserCreateSchema, async (req, { validatedBody }) => {
+  // validatedBody is strictly typed, validated, and sanitized
+  return NextResponse.json({
+    status: 'success',
+    user: validatedBody
+  }, { status: 201 });
+});
+```
+
+### Automatic 422 Error Response
+
+When invalid or missing data is sent, `@atozapi/nextjs` immediately responds with HTTP 422:
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "username"],
+      "msg": "String should have at least 3 characters",
+      "type": "string_too_short",
+      "ctx": { "min_length": 3 }
+    },
+    {
+      "loc": ["body", "email"],
+      "msg": "Field required",
+      "type": "missing"
+    }
+  ]
+}
+```
+
+---
+
+## 📚 OpenAPI Documentation
+
+Use the `@atozapi/cli` scanner to automatically inspect your Next.js routes and serve interactive Swagger UI docs:
+
+```bash
+npx @atozapi/cli serve
+```
+
+---
+
+## 📄 License
+
+MIT © [AtoZAPI Maintainers](https://github.com/dhirajparihar/AtoZAPI)

package/index.js

@@ -0,0 +1,316 @@
+/**
+ * @atozapi/nextjs
+ * FastAPI-style request validation and OpenAPI metadata wrapper for Next.js App Router route handlers.
+ */
+
+/**
+ * Validates a value against a field schema definition.
+ * @param {string[]} loc - Location array for FastAPI error representation
+ * @param {any} value - Value to validate
+ * @param {object|string} rule - Field validation rule
+ * @param {Array} errors - Error collection array
+ * @returns {any}
+ */
+function validateField(loc, value, rule, errors) {
+  const config = typeof rule === 'string' ? { type: rule, required: true } : (rule || {});
+  const isRequired = config.required !== false && !config.optional;
+
+  if (value === undefined || value === null || value === '') {
+    if (isRequired) {
+      errors.push({
+        loc: [...loc],
+        msg: 'Field required',
+        type: 'missing'
+      });
+    }
+    return config.default !== undefined ? config.default : value;
+  }
+
+  const expectedType = (config.type || 'string').toLowerCase();
+
+  switch (expectedType) {
+    case 'string': {
+      if (typeof value !== 'string') {
+        errors.push({
+          loc: [...loc],
+          msg: 'Input should be a valid string',
+          type: 'string_type'
+        });
+        return value;
+      }
+      if (typeof config.minLength === 'number' && value.length < config.minLength) {
+        errors.push({
+          loc: [...loc],
+          msg: `String should have at least ${config.minLength} characters`,
+          type: 'string_too_short',
+          ctx: { min_length: config.minLength }
+        });
+      }
+      if (typeof config.maxLength === 'number' && value.length > config.maxLength) {
+        errors.push({
+          loc: [...loc],
+          msg: `String should have at most ${config.maxLength} characters`,
+          type: 'string_too_long',
+          ctx: { max_length: config.maxLength }
+        });
+      }
+      if (config.pattern) {
+        const regex = config.pattern instanceof RegExp ? config.pattern : new RegExp(config.pattern);
+        if (!regex.test(value)) {
+          errors.push({
+            loc: [...loc],
+            msg: `String should match pattern '${regex.source}'`,
+            type: 'string_pattern_mismatch'
+          });
+        }
+      }
+      if (config.format === 'email') {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!emailRegex.test(value)) {
+          errors.push({
+            loc: [...loc],
+            msg: 'Input should be a valid email address',
+            type: 'value_error.email'
+          });
+        }
+      }
+      return value;
+    }
+
+    case 'number':
+    case 'int':
+    case 'integer':
+    case 'float': {
+      let num = typeof value === 'number' ? value : Number(value);
+      if (isNaN(num) || typeof value === 'boolean') {
+        errors.push({
+          loc: [...loc],
+          msg: 'Input should be a valid number',
+          type: 'number_type'
+        });
+        return value;
+      }
+
+      if ((expectedType === 'int' || expectedType === 'integer') && !Number.isInteger(num)) {
+        errors.push({
+          loc: [...loc],
+          msg: 'Input should be a valid integer',
+          type: 'int_type'
+        });
+      }
+
+      if (typeof config.min === 'number' && num < config.min) {
+        errors.push({
+          loc: [...loc],
+          msg: `Input should be greater than or equal to ${config.min}`,
+          type: 'greater_than_equal',
+          ctx: { ge: config.min }
+        });
+      }
+
+      if (typeof config.max === 'number' && num > config.max) {
+        errors.push({
+          loc: [...loc],
+          msg: `Input should be less than or equal to ${config.max}`,
+          type: 'less_than_equal',
+          ctx: { le: config.max }
+        });
+      }
+      return num;
+    }
+
+    case 'boolean':
+    case 'bool': {
+      if (typeof value === 'boolean') return value;
+      if (value === 'true' || value === 1 || value === '1') return true;
+      if (value === 'false' || value === 0 || value === '0') return false;
+      errors.push({
+        loc: [...loc],
+        msg: 'Input should be a valid boolean',
+        type: 'bool_type'
+      });
+      return value;
+    }
+
+    case 'array':
+    case 'list': {
+      if (!Array.isArray(value)) {
+        errors.push({
+          loc: [...loc],
+          msg: 'Input should be a valid array',
+          type: 'list_type'
+        });
+        return value;
+      }
+      if (typeof config.minItems === 'number' && value.length < config.minItems) {
+        errors.push({
+          loc: [...loc],
+          msg: `Array should have at least ${config.minItems} items`,
+          type: 'too_short',
+          ctx: { min_length: config.minItems }
+        });
+      }
+      if (config.items) {
+        return value.map((item, index) => validateField([...loc, index], item, config.items, errors));
+      }
+      return value;
+    }
+
+    case 'object': {
+      if (typeof value !== 'object' || Array.isArray(value) || value === null) {
+        errors.push({
+          loc: [...loc],
+          msg: 'Input should be a valid dictionary or object',
+          type: 'dict_type'
+        });
+        return value;
+      }
+      const resultObj = {};
+      const properties = config.properties || {};
+      for (const [key, propRule] of Object.entries(properties)) {
+        resultObj[key] = validateField([...loc, key], value[key], propRule, errors);
+      }
+      return resultObj;
+    }
+
+    default:
+      return value;
+  }
+}
+
+/**
+ * Validates request payload against schema.
+ */
+function validateSchema(schema, payload, rootLoc = 'body') {
+  const errors = [];
+  const validated = {};
+
+  const targetSchema = schema.body || schema;
+  const isTargetObject = typeof targetSchema === 'object' && targetSchema !== null;
+
+  if (!isTargetObject) {
+    return { valid: true, errors: [], data: payload || {} };
+  }
+
+  const rawPayload = (payload && typeof payload === 'object' && !Array.isArray(payload)) ? payload : {};
+
+  if (Object.keys(targetSchema).length > 0 && (!payload || typeof payload !== 'object')) {
+    errors.push({
+      loc: [rootLoc],
+      msg: 'Input should be a valid dictionary or object',
+      type: 'dict_type'
+    });
+    return { valid: false, errors, data: {} };
+  }
+
+  for (const [field, rule] of Object.entries(targetSchema)) {
+    const fieldVal = rawPayload[field];
+    validated[field] = validateField([rootLoc, field], fieldVal, rule, errors);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    data: validated
+  };
+}
+
+/**
+ * Creates a standard JSON Response for Next.js / Web Fetch API environments.
+ */
+function createJsonResponse(data, status = 200) {
+  if (typeof Response !== 'undefined') {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+  // Fallback for non-Fetch mock environments
+  return {
+    status,
+    body: data,
+    headers: { 'content-type': 'application/json' }
+  };
+}
+
+/**
+ * Next.js App Router higher-order route handler wrapper.
+ * Supports both call styles:
+ *   nextAtozapi({ schema, handler })
+ *   nextAtozapi({ schema: userSchema, handler: async (req, { validatedBody }) => { ... } })
+ * Or shorthand:
+ *   nextAtozapi(schema, handler)
+ *
+ * @param {object|Function} optionsOrSchema
+ * @param {Function} [maybeHandler]
+ * @returns {Function} Next.js route handler (req, context) => Promise<Response>
+ */
+function nextAtozapi(optionsOrSchema, maybeHandler) {
+  let schema = {};
+  let handler = null;
+
+  if (typeof optionsOrSchema === 'function') {
+    handler = optionsOrSchema;
+    schema = {};
+  } else if (typeof maybeHandler === 'function') {
+    schema = optionsOrSchema || {};
+    handler = maybeHandler;
+  } else if (optionsOrSchema && typeof optionsOrSchema === 'object') {
+    schema = optionsOrSchema.schema || {};
+    handler = optionsOrSchema.handler;
+  }
+
+  if (typeof handler !== 'function') {
+    throw new Error('[atozapi] Next.js route handler must be a function.');
+  }
+
+  const wrappedRoute = async function atozapiNextRoute(req, context = {}) {
+    let rawBody = {};
+
+    // In Web Request stream (Next.js App Router)
+    if (req && typeof req.json === 'function') {
+      try {
+        const cloned = req.clone ? req.clone() : req;
+        rawBody = await cloned.json();
+      } catch (err) {
+        // If content is empty or unparsable
+        rawBody = {};
+      }
+    } else if (req && req.body) {
+      rawBody = req.body;
+    }
+
+    const result = validateSchema(schema, rawBody, 'body');
+
+    if (!result.valid) {
+      return createJsonResponse({ detail: result.errors }, 422);
+    }
+
+    // Attach validatedBody to request and pass directly into execution callback context
+    try {
+      req.validatedBody = result.data;
+    } catch (_) {
+      // req might be frozen in some environments
+    }
+
+    const enhancedContext = {
+      ...context,
+      validatedBody: result.data,
+      data: result.data
+    };
+
+    return await handler(req, enhancedContext);
+  };
+
+  // Expose schema metadata for automated CLI scanner reflection
+  wrappedRoute.__atozapi = true;
+  wrappedRoute._schema = schema;
+
+  return wrappedRoute;
+}
+
+module.exports = {
+  nextAtozapi,
+  validateSchema,
+  validateField
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@atozapi/nextjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "FastAPI-style request validation and OpenAPI metadata wrapper for Next.js App Router",
+  "main": "index.js",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dhirajparihar/AtoZAPI.git",
+    "directory": "sdk-js/nextjs"
+  },
+  "homepage": "https://github.com/dhirajparihar/AtoZAPI#readme",
+  "bugs": {
+    "url": "https://github.com/dhirajparihar/AtoZAPI/issues"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node index.js"
+  },
+  "keywords": [
+    "atozapi",
+    "fastapi",
+    "nextjs",
+    "app-router",
+    "validation",
+    "openapi"
+  ],
+  "author": "AtoZAPI Maintainers",
+  "license": "MIT"
+}