Skip to content

JsWeb v1.2.0 Release

Latest
Latest

Choose a tag to compare

View all tags
@Jones-peter Jones-peter released this 11 Dec 07:35
· 41 commits to main since this release
v1.2.0
364c1dc

JsWeb v1.2.0 Release Notes

Release Date: 11 December 2025
Status: Stable Release

Special Thanks 🩷

A special thank you to @kasimlyee for his valuable contributions, insights, and continuous support throughout the development of JsWeb.
All the features mentioned below were implemented by him with great dedication and expertise. 🙏🚀

What's New 🎉

JsWeb v1.2.0 introduces major improvements to developer experience, API documentation, routing performance, and error handling. This release brings the framework closer to production-ready status with automatic documentation and significant performance optimizations.

Major Features ⚡

Automatic OpenAPI/Swagger Documentation System

JsWeb now includes a complete, production-ready OpenAPI 3.0.3 documentation system that works automatically out of the box.

Key Features:

  • Automatic API Documentation - Docs are automatically generated and available at /docs, /redoc, and /openapi.json
  • Multiple UI Options - Swagger UI, ReDoc, and RapiDoc support
  • Experience - Automatic request validation with Pydantic v2
  • Decorators - Fine-grained documentation control with decorators
  • Zero Configuration - Works automatically when you run jsweb run
  • Hybrid DTO System - Uses Pydantic v2 internally but exposes clean jsweb API

Usage Example:

from jsweb import JsWebApp
from jsweb.dto import JswebBaseModel, Field
from jsweb.docs import api_operation, api_body, api_response
from jsweb.response import json

app = JsWebApp(__name__)

# Define a DTO
class CreateUserDto(JswebBaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    email: str = Field(..., pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    age: int = Field(..., ge=0, le=150)

# Automatic validation and documentation
@app.route('/users', methods=['POST'])
@api_operation(
    summary="Create a new user",
    description="Creates a new user with automatic validation"
)
@api_body(CreateUserDto)  # Auto-validates request body!
@api_response(201, CreateUserDto, description="User created successfully")
async def create_user(req):
    # req.validated_body contains the validated DTO
    user_data = req.validated_data
    return json(user_data, status=201)

What You Get:

  • Automatic request body validation
  • Detailed validation error messages
  • Interactive API documentation at /docs
  • OpenAPI JSON spec at /openapi.json
  • Alternative docs at /redoc

Configuration:
All new projects include OpenAPI configuration in config.py:

ENABLE_OPENAPI_DOCS = True           # Enable automatic API documentation
API_TITLE = "Your Project API"
API_VERSION = "1.0.0"
API_DESCRIPTION = "API documentation for Your Project"
OPENAPI_DOCS_URL = "/docs"           # Swagger UI
OPENAPI_REDOC_URL = "/redoc"         # ReDoc UI
OPENAPI_JSON_URL = "/openapi.json"   # OpenAPI spec JSON

Documentation:

  • Full usage guide: JSWEB_OPENAPI_GUIDE.md
  • Example API: examples/example_api.py

2. Routing Performance Optimizations 📈

Significant improvements to routing performance and efficiency.

Performance Improvements:

  • Optimized Route Matching - Faster route resolution algorithm
  • Static Route Priority - Static routes checked before dynamic routes
  • Method Pre-Filtering - Quick rejection of invalid HTTP methods before regex matching
  • Reduced Overhead - Minimized computational cost per request

Benchmarks:

  • Route resolution is now comparable to other production frameworks
  • Reduced latency for high-traffic applications
  • Better performance with large numbers of routes

Technical Details:

  • Static routes use O(1) dictionary lookup
  • Dynamic routes filter by method before expensive regex matching
  • Optimized route compilation and caching

3. Enhanced DTO System with Pydantic v2

A powerful hybrid DTO system that combines Pydantic's validation speed with a clean jsweb API.

Features:

  • Pydantic v2 Performance - 100x faster validation than v1
  • Clean API - No Pydantic imports needed in user code
  • Automatic Validation - Works seamlessly with @api_body decorator
  • Custom Validators - @validator and @root_validator decorators
  • OpenAPI Integration - Automatic schema generation

Available in jsweb.dto:

  • JswebBaseModel - Base class for DTOs
  • Field() - Field configuration with validation
  • ValidationError - Validation error exception
  • @validator - Field-level validation decorator
  • @root_validator - Model-level validation decorator

Example:

from jsweb.dto import JswebBaseModel, Field, validator

class UserDto(JswebBaseModel):
    name: str = Field(..., min_length=2)
    email: str
    age: int = Field(..., ge=18)

    @validator('email')
    def validate_email(cls, value):
        if '@' not in value:
            raise ValueError('Invalid email format')
        return value.lower()

4. Improved Error Handling

Fixed critical error handling issues in the routing system.

What's Fixed:

  • 404 Not Found - Missing routes now properly return 404 instead of 500
  • 405 Method Not Allowed - Invalid HTTP methods return 405 instead of 500
  • ASGI Compliance - Error responses now properly implement ASGI protocol
  • Better Error Messages - Clear JSON error responses with descriptive messages

Before:

GET /missing-route → 500 Internal Server Error
POST /get-only-route → 500 Internal Server Error

After:

GET /missing-route → 404 {"error": "No route found for /missing-route"}
POST /get-only-route → 405 {"error": "Method POST not allowed for path /get-only-route"}

New Dependencies 🆕

  • pydantic>=2.0,<3.0 - Required for DTO system and OpenAPI documentation

Breaking Changes 💥

None - This release is fully backward compatible with v1.2.0b1.

Files Added 🗃️

Core OpenAPI System

  • jsweb/dto/__init__.py - DTO system exports
  • jsweb/dto/models.py - JswebBaseModel and Field
  • jsweb/dto/validators.py - Validation decorators
  • jsweb/docs/__init__.py - OpenAPI exports
  • jsweb/docs/registry.py - Metadata registry
  • jsweb/docs/decorators.py - NestJS-style decorators
  • jsweb/docs/auto_validation.py - Automatic validation
  • jsweb/docs/schema_builder.py - OpenAPI schema generator
  • jsweb/docs/ui_handlers.py - Swagger/ReDoc handlers
  • jsweb/docs/introspection.py - Route discovery
  • jsweb/docs/setup.py - One-line setup function
  • jsweb/docs/validation_middleware.py - Optional middleware

Documentation & Examples

  • JSWEB_OPENAPI_GUIDE.md - Complete usage guide (~800 lines)
  • examples/example_api.py - Full CRUD API example

Files Modified

Core Framework

  • jsweb/app.py - Fixed error handling for proper 404/405 responses
  • jsweb/cli.py - Added automatic OpenAPI setup on jsweb run
  • jsweb/server.py - Fixed Windows terminal emoji encoding issues

Configuration

  • pyproject.toml - Added Pydantic v2 dependency
  • jsweb/project_templates/config.py.jinja - Added OpenAPI configuration section

Developer Experience Improvements 💻

  1. Zero Configuration Required

    • API docs work automatically with no setup
    • New projects come with OpenAPI pre-configured

  2. FastAPI-Style Validation

    • Automatic request validation on decorated routes
    • Detailed validation error responses
    • Optional - can be disabled per route

  3. Better Error Messages

    • Clear, descriptive error responses
    • Proper HTTP status codes
    • JSON error format

  4. Production-Ready

    • Thread-safe metadata registry
    • Optimized routing performance
    • Comprehensive error handling

Migration Guide 🔀

From v1.2.0b1 to v1.2.0

No breaking changes! Just update your dependencies:

pip install --upgrade jsweb

Optional: Enable OpenAPI Docs

If you're upgrading an existing project, add these to your config.py:

# OpenAPI / Swagger Documentation (Automatic!)
ENABLE_OPENAPI_DOCS = True
API_TITLE = "Your API Name"
API_VERSION = "1.0.0"
API_DESCRIPTION = "Your API description"
OPENAPI_DOCS_URL = "/docs"
OPENAPI_REDOC_URL = "/redoc"
OPENAPI_JSON_URL = "/openapi.json"

That's it! Run jsweb run and visit /docs to see your API documentation.

Bug Fixes 🐞

  • Fixed routing errors returning 500 instead of proper 404/405 status codes
  • Fixed Windows terminal encoding issues with emoji characters
  • Fixed ASGI protocol compliance in error response handling
  • Fixed race conditions in OpenAPI metadata registry (thread-safe)

What's Next 🚀

Looking ahead to v1.3.0:

  • Enhanced middleware system
  • WebSocket support improvements
  • Advanced authentication decorators
  • Request rate limiting
  • Response caching utilities
  • Database migration improvements

Contributors 🩷

Resources 📂

Feedback 📫

We'd love to hear your feedback on v1.2.0 Please:

  • Report bugs on GitHub Issues
  • Share your experience using the new OpenAPI system
  • Suggest improvements for future releases

Thank you for using JsWeb! 🎉

Contributors

kasimlyee
Assets 2
Loading