fluidkit 0.1.0__tar.gz

fluidkit-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: fluidkit
+Version: 0.1.0
+Summary: Automatic TypeScript client generation for FastAPI through runtime introspection
+Author-email: Aswanth Manoj <aswanthmanoj51@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AswanthManoj/Fluidkit
+Project-URL: Repository, https://github.com/AswanthManoj/Fluidkit
+Project-URL: Issues, https://github.com/AswanthManoj/Fluidkit/issues
+Keywords: fastapi,typescript,code-generation,full-stack,type-safety,sveltekit,nextjs,nuxtjs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: fastapi[standard]>=0.115.14; extra == "dev"
+Requires-Dist: pydantic-extra-types>=2.10.5; extra == "dev"
+Requires-Dist: pydantic[email]>=2.11.7; extra == "dev"
+
+# FluidKit
+
+**Automatic TypeScript client generation for FastAPI through runtime introspection. Get tRPC-like developer experience with full-stack type safety across Python and TypeScript.**
+
+## Overview
+
+FluidKit bridges the gap between Python FastAPI backends and modern TypeScript frontends by automatically generating fully-typed clients from your existing FastAPI code. No configuration, no decorators, no manual type definitions.
+
+### 🔧 **Automatic Type-Safe Client Generation**
+
+Write FastAPI, get TypeScript clients with full IDE support automatically:
+
+```python
+# Your FastAPI code (unchanged)
+from fastapi import FastAPI, Query
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: int, include_profile: bool = Query(False)) -> User:
+    return User(id=user_id, name="John", email="john@example.com")
+
+# One line - automatic client generation
+import fluidkit
+fluidkit.integrate(app)
+```
+
+```typescript
+// Auto-generated: Full type safety + IDE autocomplete
+import { get_user } from './.fluidkit/main';
+
+const result = await get_user(123, true);
+//    ^-- Full TypeScript inference, just like tRPC
+//        result.data is typed as User | undefined
+//        result.error is typed as string | undefined
+```
+
+**IDE Experience:**
+- ✅ **Full autocomplete** on function parameters and return types
+- ✅ **Type checking** prevents runtime errors  
+- ✅ **Go-to-definition** jumps to Python code
+- ✅ **Refactor safety** - rename Python functions, TypeScript updates automatically
+
+### 🚀 **FastAPI + Modern Meta-Frameworks**
+
+FluidKit unlocks FastAPI for server-side rendering frameworks like SvelteKit, Next.js, and Nuxt:
+
+```typescript
+// SvelteKit +page.server.ts - server-side rendering
+export const load: PageServerLoad = async () => {
+    const users = await get_users({ status: "active", limit: 10 });
+    return { users: users.data };
+};
+```
+
+```svelte
+<!-- +page.svelte - reactive and type-safe -->
+<script lang="ts">
+    export let data;
+    
+    // Client-side interactions with full type safety
+    async function createUser() {
+        const result = await create_user({
+            name: userName,
+            email: userEmail
+        });
+        
+        if (result.success) {
+            // result.data is fully typed as User
+            users = [...users, result.data];
+        }
+    }
+</script>
+```
+
+**Why This Matters:**
+- **Python developers** can leverage modern frontend frameworks without becoming Node.js experts
+- **Full-stack type safety** from database to UI components
+- **Natural development flow** - write Python, get TypeScript benefits automatically
+- **Server-side rendering** with FastAPI data, client-side interactions with the same API
+
+## Installation
+
+```bash
+# Install directly from GitHub
+pip install git+https://github.com/AswanthManoj/Fluidkit.git
+```
+
+## Quick Start
+
+Add one line to your existing FastAPI app:
+
+```python
+from fastapi import FastAPI
+import fluidkit
+
+app = FastAPI()
+
+# Your existing routes...
+@app.get("/users")
+async def get_users():
+    return [{"id": 1, "name": "John"}]
+
+# Generate TypeScript clients automatically
+fluidkit.integrate(app)
+```
+
+Run your FastAPI app normally:
+```bash
+uvicorn main:app --reload
+```
+
+FluidKit automatically:
+- ✅ **Introspects your FastAPI app** using FastAPI's internal systems
+- ✅ **Discovers all routes and models** through dependency analysis  
+- ✅ **Generates TypeScript clients** with perfect parameter classification
+- ✅ **Updates on code changes** when FastAPI reloads
+
+Generated files:
+```
+project/
+├── main.py
+└── .fluidkit/
+    ├── main.ts          # TypeScript clients
+    └── runtime.ts       # Fetch utilities
+```
+
+Use the generated clients:
+```typescript
+import { get_users } from './.fluidkit/main';
+
+const result = await get_users();
+if (result.success) {
+    console.log(result.data); // Fully typed!
+}
+```
+
+## Key Features
+
+### Zero Configuration
+- **No decorators** - works with existing FastAPI code
+- **No config files** - automatic discovery and generation
+- **No manual types** - inferred from Pydantic models
+
+### Perfect FastAPI Compliance  
+- **Uses FastAPI's internals** for 100% accurate parameter classification
+- **Handles complex types** - generics, unions, optional fields
+- **Supports all FastAPI features** - dependencies, security, multi-method routes
+
+### Production Ready
+- **Environment-aware** - proxy in browser, direct connection on server
+- **Error handling** - structured error responses with status codes
+- **Import resolution** - automatic relative imports between generated files
+
+### Framework Integration
+- **SvelteKit** - works with `+page.server.ts` and client-side code
+- **Next.js** - compatible with App Router and Pages Router
+- **Any TypeScript project** - just import and use
+
+## Development Workflow
+
+FluidKit integrates seamlessly into your Python-first development workflow:
+
+1. **Write FastAPI normally** - routes, models, dependencies
+2. **Add `fluidkit.integrate(app)`** - one line in your app
+3. **Use TypeScript clients** - import generated functions anywhere
+4. **Iterate rapidly** - changes to Python automatically update TypeScript
+
+**For Python developers:**
+- Stay in Python for business logic
+- Get modern frontend benefits automatically  
+- No Node.js configuration required
+- Full-stack type safety without context switching
+
+**For teams:**
+- Backend and frontend stay in sync automatically
+- Impossible to have type mismatches between API and UI
+- Python changes immediately available in TypeScript
+- No API documentation to maintain
+
+## Why FluidKit?
+
+**Traditional full-stack development:**
+```
+Python API ──┐
+             ├── Manual sync ──> TypeScript types
+OpenAPI ─────┘                   Frontend code
+```
+*Brittle, error-prone, requires constant maintenance*
+
+**FluidKit full-stack development:**
+```
+Python API ──> FluidKit ──> Fully-typed TypeScript clients
+```
+*Automatic, reliable, zero maintenance*
+
+FluidKit brings the **tRPC developer experience** to Python developers, enabling modern full-stack development without abandoning the Python ecosystem.
+
+---
+
+**Ready to eliminate the API integration gap?**  
+Add `fluidkit.integrate(app)` to your FastAPI app and experience full-stack type safety.
+
+**Coming Soon:**
+- 🚧 CLI tooling (`fluidkit init`, `fluidkit dev`)
+- 🚧 Project templates and scaffolding
+- 🚧 Watch mode for development
+- 🚧 Additional language support (Python, Zod, JavaScript)

fluidkit-0.1.0/README.md

@@ -0,0 +1,214 @@
+# FluidKit
+
+**Automatic TypeScript client generation for FastAPI through runtime introspection. Get tRPC-like developer experience with full-stack type safety across Python and TypeScript.**
+
+## Overview
+
+FluidKit bridges the gap between Python FastAPI backends and modern TypeScript frontends by automatically generating fully-typed clients from your existing FastAPI code. No configuration, no decorators, no manual type definitions.
+
+### 🔧 **Automatic Type-Safe Client Generation**
+
+Write FastAPI, get TypeScript clients with full IDE support automatically:
+
+```python
+# Your FastAPI code (unchanged)
+from fastapi import FastAPI, Query
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: int, include_profile: bool = Query(False)) -> User:
+    return User(id=user_id, name="John", email="john@example.com")
+
+# One line - automatic client generation
+import fluidkit
+fluidkit.integrate(app)
+```
+
+```typescript
+// Auto-generated: Full type safety + IDE autocomplete
+import { get_user } from './.fluidkit/main';
+
+const result = await get_user(123, true);
+//    ^-- Full TypeScript inference, just like tRPC
+//        result.data is typed as User | undefined
+//        result.error is typed as string | undefined
+```
+
+**IDE Experience:**
+- ✅ **Full autocomplete** on function parameters and return types
+- ✅ **Type checking** prevents runtime errors  
+- ✅ **Go-to-definition** jumps to Python code
+- ✅ **Refactor safety** - rename Python functions, TypeScript updates automatically
+
+### 🚀 **FastAPI + Modern Meta-Frameworks**
+
+FluidKit unlocks FastAPI for server-side rendering frameworks like SvelteKit, Next.js, and Nuxt:
+
+```typescript
+// SvelteKit +page.server.ts - server-side rendering
+export const load: PageServerLoad = async () => {
+    const users = await get_users({ status: "active", limit: 10 });
+    return { users: users.data };
+};
+```
+
+```svelte
+<!-- +page.svelte - reactive and type-safe -->
+<script lang="ts">
+    export let data;
+    
+    // Client-side interactions with full type safety
+    async function createUser() {
+        const result = await create_user({
+            name: userName,
+            email: userEmail
+        });
+        
+        if (result.success) {
+            // result.data is fully typed as User
+            users = [...users, result.data];
+        }
+    }
+</script>
+```
+
+**Why This Matters:**
+- **Python developers** can leverage modern frontend frameworks without becoming Node.js experts
+- **Full-stack type safety** from database to UI components
+- **Natural development flow** - write Python, get TypeScript benefits automatically
+- **Server-side rendering** with FastAPI data, client-side interactions with the same API
+
+## Installation
+
+```bash
+# Install directly from GitHub
+pip install git+https://github.com/AswanthManoj/Fluidkit.git
+```
+
+## Quick Start
+
+Add one line to your existing FastAPI app:
+
+```python
+from fastapi import FastAPI
+import fluidkit
+
+app = FastAPI()
+
+# Your existing routes...
+@app.get("/users")
+async def get_users():
+    return [{"id": 1, "name": "John"}]
+
+# Generate TypeScript clients automatically
+fluidkit.integrate(app)
+```
+
+Run your FastAPI app normally:
+```bash
+uvicorn main:app --reload
+```
+
+FluidKit automatically:
+- ✅ **Introspects your FastAPI app** using FastAPI's internal systems
+- ✅ **Discovers all routes and models** through dependency analysis  
+- ✅ **Generates TypeScript clients** with perfect parameter classification
+- ✅ **Updates on code changes** when FastAPI reloads
+
+Generated files:
+```
+project/
+├── main.py
+└── .fluidkit/
+    ├── main.ts          # TypeScript clients
+    └── runtime.ts       # Fetch utilities
+```
+
+Use the generated clients:
+```typescript
+import { get_users } from './.fluidkit/main';
+
+const result = await get_users();
+if (result.success) {
+    console.log(result.data); // Fully typed!
+}
+```
+
+## Key Features
+
+### Zero Configuration
+- **No decorators** - works with existing FastAPI code
+- **No config files** - automatic discovery and generation
+- **No manual types** - inferred from Pydantic models
+
+### Perfect FastAPI Compliance  
+- **Uses FastAPI's internals** for 100% accurate parameter classification
+- **Handles complex types** - generics, unions, optional fields
+- **Supports all FastAPI features** - dependencies, security, multi-method routes
+
+### Production Ready
+- **Environment-aware** - proxy in browser, direct connection on server
+- **Error handling** - structured error responses with status codes
+- **Import resolution** - automatic relative imports between generated files
+
+### Framework Integration
+- **SvelteKit** - works with `+page.server.ts` and client-side code
+- **Next.js** - compatible with App Router and Pages Router
+- **Any TypeScript project** - just import and use
+
+## Development Workflow
+
+FluidKit integrates seamlessly into your Python-first development workflow:
+
+1. **Write FastAPI normally** - routes, models, dependencies
+2. **Add `fluidkit.integrate(app)`** - one line in your app
+3. **Use TypeScript clients** - import generated functions anywhere
+4. **Iterate rapidly** - changes to Python automatically update TypeScript
+
+**For Python developers:**
+- Stay in Python for business logic
+- Get modern frontend benefits automatically  
+- No Node.js configuration required
+- Full-stack type safety without context switching
+
+**For teams:**
+- Backend and frontend stay in sync automatically
+- Impossible to have type mismatches between API and UI
+- Python changes immediately available in TypeScript
+- No API documentation to maintain
+
+## Why FluidKit?
+
+**Traditional full-stack development:**
+```
+Python API ──┐
+             ├── Manual sync ──> TypeScript types
+OpenAPI ─────┘                   Frontend code
+```
+*Brittle, error-prone, requires constant maintenance*
+
+**FluidKit full-stack development:**
+```
+Python API ──> FluidKit ──> Fully-typed TypeScript clients
+```
+*Automatic, reliable, zero maintenance*
+
+FluidKit brings the **tRPC developer experience** to Python developers, enabling modern full-stack development without abandoning the Python ecosystem.
+
+---
+
+**Ready to eliminate the API integration gap?**  
+Add `fluidkit.integrate(app)` to your FastAPI app and experience full-stack type safety.
+
+**Coming Soon:**
+- 🚧 CLI tooling (`fluidkit init`, `fluidkit dev`)
+- 🚧 Project templates and scaffolding
+- 🚧 Watch mode for development
+- 🚧 Additional language support (Python, Zod, JavaScript)

fluidkit-0.1.0/fluidkit/__init__.py

@@ -0,0 +1,47 @@
+"""
+FluidKit - Automatic TypeScript client code generation for FastAPI
+"""
+
+__version__ = "2.0.0"
+
+def _check_dependencies():
+    """Check for required dependencies and provide helpful error messages"""
+    missing = []
+    
+    try:
+        import fastapi
+    except ImportError:
+        missing.append("fastapi")
+    
+    try:
+        import pydantic
+    except ImportError:
+        missing.append("pydantic")
+    
+    if missing:
+        deps = " and ".join(missing)
+        raise ImportError(
+            f"FluidKit requires {deps} to be installed.\n"
+            f"Install with: pip install {' '.join(missing)}\n"
+            f"FluidKit works with your existing {deps} versions."
+        )
+
+# Check dependencies on import
+_check_dependencies()
+
+# Import main API only after dependency check
+from .core.schema import LanguageType
+from .core.integrator import integrate, introspect_only, generate_only
+
+__all__ = [
+    # Main functions
+    'integrate',
+    'introspect_only', 
+    'generate_only',
+    
+    # Enums
+    'LanguageType',
+    
+    # Version
+    '__version__'
+]

fluidkit-0.1.0/fluidkit/core/__init__.py

@@ -0,0 +1,35 @@
+"""
+Core FluidKit components - for advanced users and plugin developers
+"""
+
+# Main data structures
+from .schema import (
+    FluidKitApp,
+    RouteNode, 
+    ModelNode,
+    Field,
+    FieldAnnotation,
+    FieldConstraints,
+    ModuleLocation,
+    
+    # Enums
+    BaseType,
+    LanguageType,
+    ContainerType, 
+    ParameterType,
+)
+
+# Main integration function
+from .integrator import integrate, introspect_only, generate_only
+
+__all__ = [
+    # Functions
+    'integrate', 'introspect_only', 'generate_only',
+
+    # Data structures
+    'FluidKitApp', 'RouteNode', 'ModelNode', 'Field', 
+    'FieldAnnotation', 'FieldConstraints', 'ModuleLocation',
+
+    # Enums
+    'LanguageType', 'BaseType', 'ContainerType', 'ParameterType',
+]

fluidkit-0.1.0/fluidkit/core/constants.py

@@ -0,0 +1,32 @@
+"""
+FluidKit constants for runtime imports and code generation
+"""
+
+class FluidKitRuntime:
+    """FluidKit runtime function and type names"""
+    
+    # TypeScript runtime exports
+    API_RESULT_TYPE = "ApiResult"
+    GET_BASE_URL_FN = "getBaseUrl"
+    HANDLE_RESPONSE_FN = "handleResponse"
+    
+    # Runtime file locations
+    RUNTIME_DIR = ".fluidkit"
+    RUNTIME_FILE = "runtime.ts"
+    
+    @classmethod
+    def get_all_imports(cls) -> list[str]:
+        """Get all runtime imports for TypeScript"""
+        return [cls.API_RESULT_TYPE, cls.GET_BASE_URL_FN, cls.HANDLE_RESPONSE_FN]
+
+
+class GenerationPaths:
+    """Standard paths for code generation"""
+    
+    FLUIDKIT_DIR = ".fluidkit"
+    TYPESCRIPT_RUNTIME = "runtime.ts"
+    
+    # Future language runtimes
+    PYTHON_RUNTIME = "runtime.py"
+    JAVASCRIPT_RUNTIME = "runtime.js"
+