jararaca 0.3.14__tar.gz → 0.3.16__tar.gz

{jararaca-0.3.14 → jararaca-0.3.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: jararaca
-Version: 0.3.14
+Version: 0.3.16
 Summary: A simple and fast API framework for Python
 Home-page: https://github.com/LuscasLeo/jararaca
 Author: Lucas S
@@ -74,6 +74,7 @@ Jararaca is an async-first microservice framework designed to simplify the devel
 - Command-line tool for generating TypeScript types
 - Support for REST endpoints, WebSocket events, and message bus payloads
 - Type-safe frontend-backend communication
+- **`@ExposeType` decorator** - Explicitly expose types for TypeScript generation without needing them in endpoints
 
 ### Hexagonal Architecture
 - Clear separation of concerns

{jararaca-0.3.14 → jararaca-0.3.16}/README.md

@@ -37,6 +37,7 @@ Jararaca is an async-first microservice framework designed to simplify the devel
 - Command-line tool for generating TypeScript types
 - Support for REST endpoints, WebSocket events, and message bus payloads
 - Type-safe frontend-backend communication
+- **`@ExposeType` decorator** - Explicitly expose types for TypeScript generation without needing them in endpoints
 
 ### Hexagonal Architecture
 - Clear separation of concerns

jararaca-0.3.16/docs/expose-type.md

@@ -0,0 +1,221 @@
+# Exposing Types for TypeScript Generation
+
+The `@ExposeType` decorator allows you to explicitly expose types for TypeScript interface generation without requiring them to be directly referenced in REST endpoints, WebSocket messages, or as indirect dependencies.
+
+## Use Cases
+
+The `@ExposeType` decorator is useful when you have types that:
+
+1. **Are used only on the frontend** - Types that exist for frontend state management, validation, or business logic
+2. **Are part of a shared schema** - Common types that multiple parts of your application use but aren't directly in API contracts
+3. **Need to be pre-generated** - Types that you want available immediately even if they're not yet used in any endpoints
+4. **Are utility types** - Helper types, enums, or constants that the frontend needs to know about
+
+## Basic Usage
+
+Simply decorate any Pydantic model with `@ExposeType()`:
+
+```python
+from pydantic import BaseModel
+
+from jararaca import ExposeType
+
+
+@ExposeType()
+class UserPermission(BaseModel):
+    id: str
+    name: str
+    description: str
+    resource: str
+    action: str
+```
+
+This type will now be included in the generated TypeScript output when you run:
+
+```bash
+jararaca gen-tsi app:app output.ts
+```
+
+## Example: Frontend-Only Types
+
+```python
+from pydantic import BaseModel
+
+from jararaca import ExposeType
+
+
+@ExposeType()
+class FilterState(BaseModel):
+    """Frontend state for table filtering."""
+    search_query: str
+    sort_column: str
+    sort_direction: str
+    page: int
+    page_size: int
+
+@ExposeType()
+class UITheme(BaseModel):
+    """Frontend theme configuration."""
+    primary_color: str
+    secondary_color: str
+    dark_mode: bool
+```
+
+## Example: Error Codes and Constants
+
+```python
+from enum import Enum
+
+from pydantic import BaseModel
+
+from jararaca import ExposeType
+
+
+@ExposeType()
+class ErrorCode(str, Enum):
+    """Standard error codes."""
+    UNAUTHORIZED = "UNAUTHORIZED"
+    NOT_FOUND = "NOT_FOUND"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+@ExposeType()
+class ApiErrorDetail(BaseModel):
+    """Detailed error information."""
+    code: ErrorCode
+    message: str
+    field: str | None = None
+    details: dict[str, str] | None = None
+```
+
+## Example: Complex Nested Types
+
+```python
+from pydantic import BaseModel
+
+from jararaca import ExposeType
+
+
+@ExposeType()
+class Address(BaseModel):
+    street: str
+    city: str
+    country: str
+    postal_code: str
+
+@ExposeType()
+class ContactInfo(BaseModel):
+    email: str
+    phone: str | None = None
+    address: Address
+
+@ExposeType()
+class Organization(BaseModel):
+    """Complete organization structure."""
+    id: str
+    name: str
+    contacts: list[ContactInfo]
+    settings: dict[str, str]
+```
+
+When you expose a type with nested structures, the decorator ensures that all related types are also included in the TypeScript generation.
+
+## Comparison: With vs Without @ExposeType
+
+### Without @ExposeType
+
+```python
+class UserRole(BaseModel):
+    """Only generated if used in an endpoint or as a dependency."""
+    id: str
+    name: str
+
+@RestController("/api/users")
+class UserController:
+    @Get("/{user_id}")
+    async def get_user(self, user_id: str) -> UserResponse:
+        # UserRole is only generated if UserResponse references it
+        return UserResponse(...)
+```
+
+### With @ExposeType
+
+```python
+@ExposeType()
+class UserRole(BaseModel):
+    """Always generated, available immediately."""
+    id: str
+    name: str
+
+@RestController("/api/users")
+class UserController:
+    @Get("/{user_id}")
+    async def get_user(self, user_id: str) -> UserResponse:
+        # UserRole is available in TypeScript even if not used yet
+        return UserResponse(...)
+```
+
+## Integration with Other Decorators
+
+The `@ExposeType` decorator works seamlessly with other TypeScript generation decorators:
+
+```python
+from jararaca import ExposeType, SplitInputOutput
+
+
+@ExposeType()
+@SplitInputOutput()
+class UserProfile(BaseModel):
+    """Generates UserProfileInput and UserProfileOutput interfaces."""
+    id: str
+    username: str
+    email: str
+    created_at: str
+    updated_at: str
+```
+
+This creates both `UserProfileInput` and `UserProfileOutput` TypeScript interfaces.
+
+## Best Practices
+
+1. **Use for shared types**: Apply `@ExposeType` to types that are used across multiple parts of your application
+2. **Document the purpose**: Add clear docstrings explaining why a type is exposed
+3. **Avoid overuse**: Only expose types that the frontend actually needs - don't expose internal implementation details
+4. **Combine with other decorators**: Use alongside `@SplitInputOutput` when appropriate
+5. **Group related types**: Keep exposed types in dedicated modules (e.g., `shared_types.py`)
+
+## Viewing Exposed Types
+
+All types decorated with `@ExposeType` are tracked globally. You can check which types are exposed:
+
+```python
+from jararaca.tools.typescript.decorators import ExposeType
+
+# Get all exposed types
+exposed = ExposeType.get_all_exposed_types()
+print(f"Exposed {len(exposed)} types: {[t.__name__ for t in exposed]}")
+```
+
+## Generated TypeScript
+
+Given this Python code:
+
+```python
+@ExposeType()
+class NotificationPreference(BaseModel):
+    email_enabled: bool
+    push_enabled: bool
+    frequency: str
+```
+
+The generated TypeScript will be:
+
+```typescript
+export interface NotificationPreference {
+  emailEnabled: boolean;
+  pushEnabled: boolean;
+  frequency: string;
+}
+```
+
+The type is available in your TypeScript code even if no REST endpoint uses it yet.

{jararaca-0.3.14 → jararaca-0.3.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "jararaca"
-version = "0.3.14"
+version = "0.3.16"
 description = "A simple and fast API framework for Python"
 authors = ["Lucas S <me@luscasleo.dev>"]
 readme = "README.md"
@@ -62,6 +62,10 @@ mkdocs-mermaid2-plugin = "^1.2.1"
 [tool.poetry.group.dev.dependencies]
 httptools = "^0.6.1"
 httpx = "^0.27.2"
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+pytest-cov = "^4.1.0"
+pytest-mock = "^3.12.0"
 
 [build-system]
 requires = ["poetry-core"]
@@ -84,3 +88,39 @@ jararaca = "jararaca.cli:cli"
 [[tool.mypy.overrides]]
 module = "mako.*"
 ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+]
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests",
+    "slow: Slow tests",
+]
+
+[tool.coverage.run]
+source = ["src/jararaca"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+    "*/.venv/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]

{jararaca-0.3.14 → jararaca-0.3.16}/src/jararaca/__init__.py

@@ -171,6 +171,7 @@ if TYPE_CHECKING:
     from .scheduler.decorators import ScheduledAction
     from .tools.app_config.interceptor import AppConfigurationInterceptor
     from .tools.typescript.decorators import (
+        ExposeType,
         MutationEndpoint,
         QueryEndpoint,
         SplitInputOutput,
@@ -279,6 +280,7 @@ if TYPE_CHECKING:
         "MessageBusPublisherInterceptor",
         "RedisWebSocketConnectionBackend",
         "AppConfigurationInterceptor",
+        "ExposeType",
         "QueryEndpoint",
         "MutationEndpoint",
         "SplitInputOutput",
@@ -510,6 +512,7 @@ _dynamic_imports: "dict[str, tuple[str, str, str | None]]" = {
         "tools.app_config.interceptor",
         None,
     ),
+    "ExposeType": (__SPEC_PARENT__, "tools.typescript.decorators", None),
     "QueryEndpoint": (__SPEC_PARENT__, "tools.typescript.decorators", None),
     "MutationEndpoint": (__SPEC_PARENT__, "tools.typescript.decorators", None),
     "SplitInputOutput": (__SPEC_PARENT__, "tools.typescript.decorators", None),

{jararaca-0.3.14 → jararaca-0.3.16}/src/jararaca/messagebus/decorators.py

@@ -11,6 +11,8 @@ from jararaca.scheduler.decorators import ScheduledAction, ScheduledActionData
 
 DECORATED_FUNC = TypeVar("DECORATED_FUNC", bound=Callable[..., Any])
 DECORATED_T = TypeVar("DECORATED_T", bound=Any)
+INSTANCE_T = TypeVar("INSTANCE_T", bound=Any)
+RETURN_T = TypeVar("RETURN_T", bound=Any)
 
 
 class MessageHandler(Generic[INHERITS_MESSAGE_CO]):
@@ -35,8 +37,9 @@ class MessageHandler(Generic[INHERITS_MESSAGE_CO]):
         self.name = name
 
     def __call__(
-        self, func: Callable[[Any, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]]
-    ) -> Callable[[Any, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]]:
+        self,
+        func: Callable[[INSTANCE_T, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]],
+    ) -> Callable[[INSTANCE_T, MessageOf[INHERITS_MESSAGE_CO]], Awaitable[None]]:
 
         MessageHandler[Any].register(func, self)
 
@@ -52,7 +55,7 @@ class MessageHandler(Generic[INHERITS_MESSAGE_CO]):
 
     @staticmethod
     def get_message_incoming(
-        func: Callable[[MessageOf[Any]], Awaitable[Any]],
+        func: Callable[[Any, MessageOf[Any]], Awaitable[None]],
     ) -> "MessageHandler[Message] | None":
         if not hasattr(func, MessageHandler.MESSAGE_INCOMING_ATTR):
             return None

{jararaca-0.3.14 → jararaca-0.3.16}/src/jararaca/tools/typescript/decorators.py

@@ -93,3 +93,49 @@ class SplitInputOutput:
         Check if the Pydantic model is marked for split interface generation.
         """
         return getattr(cls, SplitInputOutput.METADATA_KEY, False)
+
+
+class ExposeType:
+    """
+    Decorator to explicitly expose types for TypeScript interface generation.
+
+    Use this decorator to include types in the generated TypeScript output without
+    needing them as request/response bodies or indirect dependencies.
+
+    Example:
+        @ExposeType()
+        class UserRole(BaseModel):
+            id: str
+            name: str
+
+        # This ensures UserRole interface is generated even if it's not
+        # directly referenced in any REST endpoint
+    """
+
+    METADATA_KEY = "__jararaca_expose_type__"
+    _exposed_types: set[type] = set()
+
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self, cls: type[BASEMODEL_T]) -> type[BASEMODEL_T]:
+        """
+        Decorate the type to mark it for explicit TypeScript generation.
+        """
+        setattr(cls, self.METADATA_KEY, True)
+        ExposeType._exposed_types.add(cls)
+        return cls
+
+    @staticmethod
+    def is_exposed_type(cls: type) -> bool:
+        """
+        Check if the type is marked for explicit exposure.
+        """
+        return getattr(cls, ExposeType.METADATA_KEY, False)
+
+    @staticmethod
+    def get_all_exposed_types() -> set[type]:
+        """
+        Get all types that have been marked for explicit exposure.
+        """
+        return ExposeType._exposed_types.copy()

{jararaca-0.3.14 → jararaca-0.3.16}/src/jararaca/tools/typescript/interface_parser.py

@@ -36,6 +36,7 @@ from jararaca.presentation.websocket.websocket_interceptor import (
     WebSocketMessageWrapper,
 )
 from jararaca.tools.typescript.decorators import (
+    ExposeType,
     MutationEndpoint,
     QueryEndpoint,
     SplitInputOutput,
@@ -661,6 +662,9 @@ def write_microservice_to_typescript_interface(
     websocket_registries: set[RegisterWebSocketMessage] = set()
     mapped_types_set.add(WebSocketMessageWrapper)
 
+    # Add all explicitly exposed types
+    mapped_types_set.update(ExposeType.get_all_exposed_types())
+
     for controller in microservice.controllers:
         rest_controller = RestController.get_controller(controller)
 
@@ -700,7 +704,7 @@ def write_microservice_to_typescript_interface(
 
 // noinspection JSUnusedGlobalSymbols
 
-import { HttpService, HttpBackend, HttpBackendRequest, ResponseType, createClassQueryHooks , createClassMutationHooks, createClassInfiniteQueryHooks, paginationModelByFirstArgPaginationFilter } from "@jararaca/core";
+import { HttpService, HttpBackend, HttpBackendRequest, ResponseType, createClassQueryHooks , createClassMutationHooks, createClassInfiniteQueryHooks, paginationModelByFirstArgPaginationFilter, recursiveCamelToSnakeCase } from "@jararaca/core";
 
 function makeFormData(data: Record<string, any>): FormData {
   const formData = new FormData();
@@ -723,7 +727,9 @@ function* genFormDataValue(value: any): any {
   } else if (typeof value === "object" && value.constructor === Object) {
     // Stringify plain objects as JSON
     // formData.append(key, JSON.stringify(value));
-    yield JSON.stringify(value);
+    yield JSON.stringify(
+      recursiveCamelToSnakeCase(value)
+    );
   } else {
     // For primitives (string, number, boolean), append as-is
     yield value;