v0.1.0-beta.4 - DI Overhaul and Architecture Refinement

ZCore Framework — v0.1.0-beta.4

We are pleased to announce the release of v0.1.0-beta.4. This version introduces critical architectural refinements, improves ASGI/Async performance by eliminating thread-pool bottlenecks, and simplifies the developer experience (DX) for database-backed microservices.

---

🚀 Key Improvements & Features

1. Complete DI Overhaul & Web-Decoupled Scoping

The dependency injection (DI) layer has been restructured to strictly adhere to Clean Architecture:

• ASGI Middleware Session Scoping: The lifetime of the AsyncSession database connection is now managed at the ASGI middleware level (ScopedDependencyMiddleware). This guarantees that a request-scoped database session is initialized and registered in the DI container before FastAPI resolves any routing dependency graphs, preventing race conditions.
• Annotated Type Unpacking: The custom DI container (_auto_wire) now supports python's native typing.Annotated patterns, gracefully extracting the core class definition (e.g., resolving AsyncSession from Annotated[AsyncSession, ...]).
• High-Performance Async Injector: Modified Injector.__call__ to be asynchronous (async def). This allows FastAPI to evaluate dependencies directly on the main event loop, bypassing costly anyio.to_thread.run_sync context switches.

2. Base Query Hook & Extension Layer

Introduced structured hook methods in the base repository layer to allow granular control over queries:

• _get_base_query(): A reusable hook returning the default Select statement (defaults to select(self.model)). Custom repositories can override this to pre-select columns or include defaults.
• _extend_query(): Enables developers to dynamically extend queries (e.g., chaining default criteria or global filters).
• Integrated base query pipeline seamlessly with the SearchEngine dynamic filter compiler.

3. One-Command Database Bootstrapping

• Running zc init <project_name> through the ZCore CLI now automatically touches and creates the default SQLite database file (zcore_dev.db) on the filesystem, ensuring a zero-configuration developer onboarding experience.

4. Dependency Management

• Added uvicorn as a primary core dependency inside pyproject.toml to guarantee the ZCore orchestration server commands (zc run) function correctly out of the box in all environments.

---

⚠️ Breaking Changes & Migration Guide

If you are migrating your test projects or showcase apps from beta.3 to beta.4, please review the following changes:

1. Clean Constructor Parameters (Decoupling Web Defaults)

You no longer need to write = Inject(...) default values or rely on SessionDep in repository/service constructors.

Before (v0.1.0-beta.3):

class UsersRepository(BaseRepository):
    def __init__(self, db: SessionDep):
        super().__init__(model=Users, db=db)

class UsersService(BaseService):
    def __init__(self, repository: UsersRepository = Inject(UsersRepository)):
        super().__init__(model=Users, repository=repository)

After (v0.1.0-beta.4):

class UsersRepository(BaseRepository):
    def __init__(self, db: AsyncSession):  # Standard AsyncSession
        super().__init__(model=Users, db=db)

class UsersService(BaseService):
    def __init__(self, repository: UsersRepository):  # Pure Python, no defaults
        super().__init__(model=Users, repository=repository)

2. Using Inject over Depends in Custom Web Deps

When writing custom FastAPI dependencies (e.g., get_current_user), ensure you use Inject(YourService) instead of Depends(YourService) so that the container handles recursive resolution:

async def get_current_user(
    token: str = Depends(oauth2_scheme),
    service: UsersService = Inject(UsersService)  # Bypasses FastAPI default-resolver errors
) -> Users:
    ...

---

🛠 How to Install / Upgrade

To fetch the latest beta package:

pip install --upgrade fastapi-zcore-framework