nodstar 0.1.0

nodnod integration for Litestar — declare dependency lifetimes on nodes, inject into handlers by type

nodstar

nodnod integration for Litestar. Declare dependency lifetimes on nodes, inject into handlers by type.

Install

uv add nodstar

Requires Python 3.14+.

Usage

from nodnod import scalar_node
from litestar import Litestar, get
from nodstar import NodstarPlugin, Node, global_node, request

Define nodes

Decorate with a lifetime (@global_node, @request, @per_call) and @scalar_node:

@global_node
@scalar_node
class DatabasePool:
    @classmethod
    async def __compose__(cls) -> AsyncEngine:
        engine = create_async_engine(DATABASE_URL)
        yield engine
        await engine.dispose()


@request
@scalar_node
class DbSession:
    @classmethod
    async def __compose__(cls, pool: DatabasePool) -> AsyncSession:
        async with AsyncSession(pool) as session:
            yield session

Inject into handlers

Use Node[T] in handler signature — nodnod resolves the dependency graph, Litestar injects the value:

@get("/users")
async def get_users(db_session: Node[DbSession]) -> list[User]:
    return await db_session.scalars(select(User))

db_session is fully typed as AsyncSession by the type checker.

Wire up

app = Litestar(
    route_handlers=[get_users],
    plugins=[NodstarPlugin()],
)

That's it. No dependencies={...}, no manual Provide(), no container configuration.

Lifetimes

Decorator	Scope	Created	Destroyed
@global_node	App	On startup	On shutdown
@request	Request	Per HTTP request	After response
@per_call	Call	Per handler invocation	After handler

Nodes declare their own lifetime. The dependency graph is resolved automatically — a @request node can depend on a @global_node, and nodnod will pull the value from the parent scope.

How it works

1. Lifetime decorators register nodes in a global registry
2. NodstarPlugin collects all registered nodes on app init
3. On startup, @global_node nodes are composed into an app-wide scope
4. Per request, a child scope is created and @request/@per_call nodes are composed
5. Node[T] is a type-level alias that resolves to T for type checkers, and at runtime produces Annotated[T, Dependency(skip_validation=True)] so Litestar skips msgspec validation and pulls the value from the nodnod scope

Generator lifecycle

Use yield in __compose__ for setup/teardown:

@request
@scalar_node
class DbSession:
    @classmethod
    async def __compose__(cls, pool: DatabasePool) -> AsyncSession:
        async with AsyncSession(pool) as session:
            yield session
            # teardown runs when request scope closes

License

MIT