jararaca 0.3.11a12__tar.gz → 0.3.27__tar.gz

{jararaca-0.3.11a12 → jararaca-0.3.27}/PKG-INFO

@@ -1,14 +1,14 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: jararaca
-Version: 0.3.11a12
+Version: 0.3.27
 Summary: A simple and fast API framework for Python
+Home-page: https://github.com/LuscasLeo/jararaca
 Author: Lucas S
 Author-email: me@luscasleo.dev
 Requires-Python: >=3.11,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: docs
 Provides-Extra: http
 Provides-Extra: opentelemetry
@@ -18,15 +18,16 @@ Requires-Dist: croniter (>=3.0.3,<4.0.0)
 Requires-Dist: fastapi (>=0.113.0,<0.114.0)
 Requires-Dist: frozendict (>=2.4.6,<3.0.0)
 Requires-Dist: mako (>=1.3.5,<2.0.0)
-Requires-Dist: opentelemetry-api (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
-Requires-Dist: opentelemetry-distro (>=0.49b2,<0.50) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-api (>=1.38.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-distro (>=0.59b0,<0.60) ; extra == "opentelemetry"
 Requires-Dist: opentelemetry-exporter-otlp (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
-Requires-Dist: opentelemetry-sdk (>=1.27.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-sdk (>=1.38.0,<2.0.0) ; extra == "opentelemetry"
 Requires-Dist: redis (>=5.0.8,<6.0.0)
 Requires-Dist: sqlalchemy (>=2.0.34,<3.0.0)
 Requires-Dist: types-croniter (>=3.0.3.20240731,<4.0.0.0)
 Requires-Dist: types-redis (>=4.6.0.20240903,<5.0.0.0)
+Requires-Dist: urllib3 (>=2.3.0,<3.0.0)
 Requires-Dist: uvicorn (>=0.30.6,<0.31.0)
 Requires-Dist: uvloop (>=0.20.0,<0.21.0)
 Requires-Dist: watchdog (>=3.0.0,<4.0.0) ; extra == "watch"
@@ -73,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.11a12 → jararaca-0.3.27}/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.27/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.