austial-orm 0.1.5__tar.gz → 0.2.1__tar.gz

{austial_orm-0.1.5 → austial_orm-0.2.1}/.gitignore

@@ -9,3 +9,7 @@ htmlcov/
 dist/
 build/
 *.egg-info/
+.DS_Store
+
+.claude/settings.local.json
+coverage.xml

austial_orm-0.2.1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: austial-orm
+Version: 0.2.1
+Summary: A from-scratch, TypeORM-shaped ORM (entities, relations, Repository, QueryBuilder, DataSource) -- mirrors typeorm, with SQLAlchemy Core hidden behind a pluggable Driver as the SQL-compilation/pooling layer.
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: austial-common
+Requires-Dist: austial-core
+Requires-Dist: greenlet>=3.1.0
+Requires-Dist: sqlalchemy>=2.0.30

{austial_orm-0.1.5 → austial_orm-0.2.1}/pyproject.toml

@@ -1,13 +1,17 @@
 [project]
 name = "austial-orm"
 dynamic = ["version"]
-description = "DatabaseModule wrapping SQLAlchemy's async engine/session -- mirrors @nestjs/typeorm (no main-monorepo equivalent)."
+description = "A from-scratch, TypeORM-shaped ORM (entities, relations, Repository, QueryBuilder, DataSource) -- mirrors typeorm, with SQLAlchemy Core hidden behind a pluggable Driver as the SQL-compilation/pooling layer."
 requires-python = ">=3.11"
 dependencies = [
     "austial-common",
     "austial-core",
     "sqlalchemy>=2.0.30",
+    # SQLAlchemy's async engine requires greenlet, but SQLAlchemy only pulls it in on some
+    # platforms/Python versions (it does not on 3.14), so declare it explicitly.
+    "greenlet>=3.1.0",
     "aiosqlite>=0.20.0",
+    "asyncpg>=0.29.0",
 ]
 
 [build-system]

austial_orm-0.2.1/src/austial/orm/__init__.py

@@ -0,0 +1,110 @@
+"""``austial-orm`` -- a from-scratch, TypeORM-shaped ORM: entities/decorators, relations,
+``Repository``/``EntityManager``, a fluent ``QueryBuilder``, and DI-native ``OrmModule`` wiring.
+SQLAlchemy Core is used only as a hidden SQL-compilation/pooling seam behind ``Driver`` -- nothing
+in this public API is a SQLAlchemy type, with one deliberate exception:
+``DataSource.get_metadata()`` returns a real ``sqlalchemy.MetaData`` for Alembic's ``env.py`` to
+use as ``target_metadata``."""
+
+from austial.orm.data_source import DataSource
+from austial.orm.decorators import (
+    Column,
+    CreateDateColumn,
+    Entity,
+    InjectRepository,
+    JoinColumn,
+    JoinTable,
+    ManyToMany,
+    ManyToOne,
+    OneToMany,
+    OneToOne,
+    PrimaryColumn,
+    PrimaryGeneratedColumn,
+    UpdateDateColumn,
+    repository_token,
+)
+from austial.orm.driver import Driver, PostgresDriver, SQLiteDriver
+from austial.orm.entity_manager import DeleteResult, EntityManager, FindOptions, UpdateResult
+from austial.orm.exceptions import (
+    AppendOnlyViolationError,
+    EntityNotFoundError,
+    MissingPrimaryKeyError,
+    OrmError,
+    QueryFailedError,
+    RelationNotFoundError,
+    TransactionError,
+)
+from austial.orm.expression import AggregateFn, In, IsNull, NotIn, NotNull
+from austial.orm.metadata.column_types import (
+    BigInteger,
+    Boolean,
+    Date,
+    DateTime,
+    EnumType,
+    Float,
+    Integer,
+    JSONType,
+    Numeric,
+    String,
+    Text,
+    Time,
+    UUIDType,
+)
+from austial.orm.naming_strategy import DefaultNamingStrategy, NamingStrategy
+from austial.orm.orm_module import OrmModule
+from austial.orm.query_builder import QueryBuilder
+from austial.orm.repository import Repository
+
+__all__ = [
+    "AggregateFn",
+    "AppendOnlyViolationError",
+    "BigInteger",
+    "Boolean",
+    "Column",
+    "CreateDateColumn",
+    "DataSource",
+    "Date",
+    "DateTime",
+    "DefaultNamingStrategy",
+    "DeleteResult",
+    "Driver",
+    "Entity",
+    "EntityManager",
+    "EntityNotFoundError",
+    "EnumType",
+    "FindOptions",
+    "Float",
+    "In",
+    "IsNull",
+    "InjectRepository",
+    "Integer",
+    "JSONType",
+    "JoinColumn",
+    "JoinTable",
+    "ManyToMany",
+    "ManyToOne",
+    "MissingPrimaryKeyError",
+    "NamingStrategy",
+    "NotIn",
+    "NotNull",
+    "Numeric",
+    "OneToMany",
+    "OneToOne",
+    "OrmError",
+    "OrmModule",
+    "PostgresDriver",
+    "PrimaryColumn",
+    "PrimaryGeneratedColumn",
+    "QueryBuilder",
+    "QueryFailedError",
+    "RelationNotFoundError",
+    "Repository",
+    "SQLiteDriver",
+    "String",
+    "Text",
+    "Time",
+    "TransactionError",
+    "UUIDType",
+    "UpdateDateColumn",
+    "UpdateResult",
+    "repository_token",
+]

austial_orm-0.2.1/src/austial/orm/data_source.py

@@ -0,0 +1,112 @@
+"""``DataSource`` -- mirrors TypeORM's ``DataSource`` (formerly ``Connection``): the single
+object that owns one ``Driver`` and one entity ``SchemaCatalog``, and hands out
+``EntityManager``/``Repository`` instances bound to them.
+
+``austial-core``'s ``module_scanner`` walks ``@Module(imports=[...])`` synchronously and eagerly
+(no async lifecycle hooks exist yet -- see ``orm_module.py``), so constructing a ``DataSource``
+must stay cheap and side-effect-free; the actual DB connection only opens inside
+``initialize()``, which the app entrypoint must call explicitly::
+
+    app = await Austial.create(AppModule)
+    await app.get(DataSource).initialize()
+    await app.listen(8000)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import TypeVar
+
+import sqlalchemy as sa
+
+from austial.orm.driver.base import Driver
+from austial.orm.driver.sqlalchemy_support import SchemaCatalog
+from austial.orm.entity_manager import EntityManager
+from austial.orm.naming_strategy import DefaultNamingStrategy, NamingStrategy
+from austial.orm.repository import Repository
+
+R = TypeVar("R")
+T = TypeVar("T")
+
+
+class DataSource:
+    def __init__(
+        self,
+        driver: Driver,
+        entities: Sequence[type],
+        *,
+        naming_strategy: NamingStrategy | None = None,
+        synchronize: bool = False,
+    ):
+        self.driver = driver
+        self._entities = list(entities)
+        self._naming_strategy = naming_strategy or DefaultNamingStrategy()
+        self._synchronize = synchronize
+        self._catalog: SchemaCatalog | None = None
+        self._manager: EntityManager | None = None
+
+    async def initialize(self) -> DataSource:
+        await self.driver.connect()
+
+        # Phase-1 pragmatic compromise (see `driver/base.py`'s module docstring): only the
+        # SQLAlchemy-backed driver family (`PostgresDriver`/`SQLiteDriver`) exposes
+        # `bind_schema()`/needs a `SchemaCatalog` at all -- a hand-rolled future driver with its
+        # own schema representation simply wouldn't define it, so this call is best-effort rather
+        # than part of the `Driver` ABC surface.
+        bind_schema = getattr(self.driver, "bind_schema", None)
+        if bind_schema is not None:
+            bind_schema(self._entities, self._naming_strategy)
+
+        self._catalog = SchemaCatalog(self._entities, self._naming_strategy)
+        self._manager = EntityManager(self.driver, self._catalog)
+
+        if self._synchronize:
+            # Dev/test convenience only -- issues `CREATE TABLE` for every entity's mapped
+            # schema. Not the production path once migrations exist (see plan's forward-compat
+            # notes); production deployments should run migrations instead.
+            await self.driver.create_all_schemas(self._entities)
+
+        return self
+
+    async def destroy(self) -> None:
+        await self.driver.close()
+
+    @property
+    def manager(self) -> EntityManager:
+        if self._manager is None:
+            raise RuntimeError("DataSource.initialize() must be called before use.")
+        return self._manager
+
+    def get_repository(self, entity: type[T]) -> Repository[T]:
+        return Repository(entity, self.manager)
+
+    def get_metadata(self) -> sa.MetaData:
+        """Returns the ``sqlalchemy.MetaData`` describing every entity this ``DataSource`` was
+        constructed with -- what Alembic's ``env.py`` needs as ``target_metadata``::
+
+            data_source = DataSource(driver, entities=[...])
+            target_metadata = data_source.get_metadata()
+
+        Building the entity ``SchemaCatalog`` only walks entity/relation metadata (no DB
+        connection), so this is safe to call before ``initialize()`` too -- exactly what Alembic
+        needs, since its process must not open the app's real connection pool just to import
+        ``target_metadata`` at module load time.
+
+        The one deliberate exception to this package's "nothing outside ``driver/`` imports
+        ``sqlalchemy`` itself" rule (see ``driver/sqlalchemy_support.py``'s module docstring):
+        Alembic's own API requires a real ``sqlalchemy.MetaData`` instance, so this method is the
+        single documented seam where that type crosses the public API boundary.
+        """
+        if self._catalog is None:
+            self._catalog = SchemaCatalog(self._entities, self._naming_strategy)
+        return self._catalog.sqla_metadata
+
+    async def transaction(self, callback: Callable[[EntityManager], Awaitable[R]]) -> R:
+        """Opens one connection/transaction via ``Driver.transaction()``, binds a fresh
+        ``EntityManager`` to it, and runs ``callback`` -- commits on clean return, rolls back on
+        exception (both handled by the driver's transaction context manager)."""
+        if self._catalog is None:
+            raise RuntimeError("DataSource.initialize() must be called before use.")
+        async with self.driver.transaction() as tx_driver:
+            tx_manager = EntityManager(tx_driver, self._catalog)
+            return await callback(tx_manager)

austial_orm-0.2.1/src/austial/orm/decorators/__init__.py

@@ -0,0 +1,27 @@
+from austial.orm.decorators.column import (
+    Column,
+    CreateDateColumn,
+    PrimaryColumn,
+    PrimaryGeneratedColumn,
+    UpdateDateColumn,
+)
+from austial.orm.decorators.entity import Entity
+from austial.orm.decorators.inject_repository import InjectRepository, repository_token
+from austial.orm.decorators.relations import JoinColumn, JoinTable, ManyToMany, ManyToOne, OneToMany, OneToOne
+
+__all__ = [
+    "Column",
+    "CreateDateColumn",
+    "Entity",
+    "InjectRepository",
+    "JoinColumn",
+    "JoinTable",
+    "ManyToMany",
+    "ManyToOne",
+    "OneToMany",
+    "OneToOne",
+    "PrimaryColumn",
+    "PrimaryGeneratedColumn",
+    "UpdateDateColumn",
+    "repository_token",
+]

austial_orm-0.2.1/src/austial/orm/decorators/column.py

@@ -0,0 +1,107 @@
+"""``Column()``/``PrimaryColumn()``/``PrimaryGeneratedColumn()``/``CreateDateColumn()``/
+``UpdateDateColumn()`` -- mirrors TypeORM's column decorators.
+
+Python has no field-level decorators, so (exactly like ``Inject()`` in ``austial-common``) each
+of these is used as the attribute's *default value* instead::
+
+    @Entity()
+    class Cat:
+        id: int = PrimaryGeneratedColumn()
+        name: str = Column()
+
+``@Entity()`` (``decorators/entity.py``) is what actually reads these markers back off the class
+and converts them into :class:`~austial.orm.metadata.entity_metadata.ColumnMetadata` plus a real
+dataclass field default -- a bare ``ColumnMarker`` never survives past class-decoration time.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from austial.orm.metadata.column_types import ColumnType
+
+
+class ColumnMarker:
+    __slots__ = (
+        "column_name",
+        "create_date",
+        "default",
+        "generated",
+        "nullable",
+        "primary",
+        "type_",
+        "unique",
+        "index",
+        "update_date",
+    )
+
+    def __init__(
+        self,
+        *,
+        name: str | None = None,
+        type_: ColumnType | None = None,
+        primary: bool = False,
+        generated: bool = False,
+        nullable: bool = False,
+        unique: bool = False,
+        index: bool = False,
+        default: Any = None,
+        create_date: bool = False,
+        update_date: bool = False,
+    ):
+        self.column_name = name
+        self.type_ = type_
+        self.primary = primary
+        self.generated = generated
+        self.nullable = nullable
+        self.unique = unique
+        self.index = index
+        self.default = default
+        self.create_date = create_date
+        self.update_date = update_date
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"ColumnMarker(name={self.column_name!r}, primary={self.primary!r})"
+
+
+def Column(
+    *,
+    name: str | None = None,
+    type_: ColumnType | None = None,
+    nullable: bool = False,
+    unique: bool = False,
+    index: bool = False,
+    default: Any = None,
+) -> Any:
+    """A regular mapped column. ``type_`` is inferred from the attribute's Python type
+    annotation unless given explicitly (mirrors TypeORM inferring from the TS type)."""
+    return ColumnMarker(name=name, type_=type_, nullable=nullable, unique=unique, index=index, default=default)
+
+
+def PrimaryColumn(*, name: str | None = None, type_: ColumnType | None = None, default: Any = None) -> Any:
+    """A primary-key column whose value the application assigns (not DB-generated)."""
+    return ColumnMarker(name=name, type_=type_, primary=True, generated=False, nullable=False, default=default)
+
+
+def PrimaryGeneratedColumn(*, name: str | None = None, default: Any = None) -> Any:
+    """An auto-incrementing integer primary key -- the common case, TypeORM's
+    ``@PrimaryGeneratedColumn()``. ``default`` stays ``None`` in virtually every real usage
+    (the DB assigns the value on insert) -- exposed only so a bare ``id: int =
+    PrimaryGeneratedColumn()`` still gets an unset-until-persisted attribute."""
+    from austial.orm.metadata.column_types import Integer
+
+    return ColumnMarker(name=name, type_=Integer(), primary=True, generated=True, nullable=False, default=default)
+
+
+def CreateDateColumn(*, name: str | None = None, default: Any = None) -> Any:
+    """Stamped with the current UTC time by ``EntityManager.save()`` on first insert."""
+    from austial.orm.metadata.column_types import DateTime
+
+    return ColumnMarker(name=name, type_=DateTime(timezone=True), nullable=True, create_date=True, default=default)
+
+
+def UpdateDateColumn(*, name: str | None = None, default: Any = None) -> Any:
+    """Stamped with the current UTC time by ``EntityManager.save()`` on every insert/update."""
+    from austial.orm.metadata.column_types import DateTime
+
+    return ColumnMarker(name=name, type_=DateTime(timezone=True), nullable=True, update_date=True, default=default)

austial_orm-0.2.1/src/austial/orm/decorators/entity.py

@@ -0,0 +1,201 @@
+"""``@Entity()`` -- mirrors TypeORM's ``@Entity()`` class decorator.
+
+Reads back the ``ColumnMarker``/``RelationMarker`` default values declared via ``Column()``,
+``PrimaryGeneratedColumn()``, ``ManyToOne()``, etc. (see ``decorators/column.py``/``relations.py``),
+builds an :class:`~austial.orm.metadata.entity_metadata.EntityMetadata`, registers it in
+:class:`~austial.orm.metadata.registry.MetadataRegistry` *and* on the class itself via the
+framework's own ``set_metadata`` mechanism, and turns the class into a plain ``@dataclass`` so
+instances behave like ordinary mutable Python objects (``Cat(name="Tom")``, attribute access/
+assignment, ``repr``/``eq``) -- no active-record magic, no lazy proxies, no dirty-checking.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import sys
+import typing
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from austial.core.metadata import set_metadata
+from austial.orm.decorators.column import ColumnMarker
+from austial.orm.decorators.relations import RelationMarker, target_resolver
+from austial.orm.metadata.column_types import infer_column_type
+from austial.orm.metadata.entity_metadata import ColumnMetadata, EntityMetadata, RelationMetadata
+from austial.orm.metadata.registry import MetadataRegistry
+from austial.orm.naming_strategy import DefaultNamingStrategy, NamingStrategy
+
+ENTITY_METADATA = "austial:orm:entity"
+
+T = TypeVar("T")
+
+_default_naming_strategy = DefaultNamingStrategy()
+
+
+def _resolve_annotations(cls: type) -> dict[str, Any]:
+    """Best-effort, per-attribute annotation resolution -- unlike ``typing.get_type_hints(cls)``,
+    one unresolvable forward reference doesn't abort resolution of every other attribute.
+
+    This matters because a relation's target is routinely a sibling entity declared *later* in
+    the same module (``Owner.cats: list["Cat"] = OneToMany(lambda: Cat, ...)``, with ``Cat``
+    defined afterwards -- exactly the pattern this framework's own docs use). ``RelationMarker``
+    already carries its target as a lazy callable (see ``decorators/relations.py``'s
+    ``target_resolver``), never the annotation, so a still-unresolved forward reference on a
+    relation attribute is harmless -- only ``Column()``-marked attributes actually consume the
+    resolved type (to infer a ``ColumnType`` when none is given explicitly), and those are always
+    already-defined types (``str``, ``int``, ``datetime.datetime``, ...), never forward refs.
+    """
+    module_globals = vars(sys.modules[cls.__module__])
+    class_locals = dict(vars(cls))
+    resolved: dict[str, Any] = {}
+    for attr_name, raw in getattr(cls, "__annotations__", {}).items():
+        forward = typing.ForwardRef(raw) if isinstance(raw, str) else raw
+        try:
+            resolved[attr_name] = typing._eval_type(forward, module_globals, class_locals)  # type: ignore[attr-defined]
+        except NameError:
+            resolved[attr_name] = raw
+    return resolved
+
+
+def _inherited_markers(cls: type) -> dict[str, tuple[Any, Any]]:
+    """``{attribute: (python_type, marker)}`` for ``Column()``/relation markers declared on plain
+    (non-entity) base classes -- how a mixin such as ``austial.tenancy.Tenanted`` contributes columns.
+
+    Walks the MRO base-first so a nearer base overrides a farther one; an attribute the entity class
+    declares itself always wins (handled by the caller). Bases that are themselves ``@Entity`` classes
+    hold dataclass fields rather than markers, so they contribute nothing here (entities do not inherit
+    mapped columns from one another).
+    """
+    inherited: dict[str, tuple[Any, Any]] = {}
+    for base in reversed(cls.__mro__[1:]):
+        if base is object:
+            continue
+        base_types = _resolve_annotations(base)
+        for attr_name, marker in vars(base).items():
+            if attr_name.startswith("_") or attr_name not in base_types:
+                continue
+            if isinstance(marker, ColumnMarker | RelationMarker):
+                inherited[attr_name] = (base_types[attr_name], marker)
+    return inherited
+
+
+@typing.dataclass_transform()
+def Entity(
+    name: str | None = None,
+    *,
+    naming_strategy: NamingStrategy | None = None,
+    append_only: bool = False,
+) -> Callable[[type[T]], type[T]]:
+    """Class decorator. Usable as ``@Entity()``, ``@Entity("custom_table_name")``, or
+    ``@Entity(append_only=True)`` (composes with the positional ``name``, e.g.
+    ``@Entity("ledger_entry", append_only=True)``).
+
+    ``naming_strategy`` only affects *this* entity's default table/column names when the app's
+    ``DataSource`` doesn't otherwise override them; the vast majority of callers never need it.
+
+    ``append_only=True`` marks the entity as insert-only: ``EntityManager`` (and therefore every
+    ``Repository`` method that funnels through it) rejects UPDATE/remove/delete against it,
+    raising :class:`~austial.orm.exceptions.AppendOnlyViolationError` -- see that class's
+    docstring for what this guard does and does not cover.
+    """
+    strategy = naming_strategy or _default_naming_strategy
+
+    def decorator(cls: type[T]) -> type[T]:
+        hints = _resolve_annotations(cls)
+        columns: list[ColumnMetadata] = []
+        relations: list[RelationMetadata] = []
+        dataclass_fields: dict[str, Any] = {}
+
+        # Mapped attributes contributed by mixin bases (own declarations take precedence). They are
+        # appended after the class's own attributes and added to ``__annotations__`` so the
+        # ``@dataclass`` step below makes them constructor fields too.
+        inherited = {name: found for name, found in _inherited_markers(cls).items() if name not in hints}
+        for attr_name, (inherited_type, _) in inherited.items():
+            hints[attr_name] = inherited_type
+        if inherited:
+            cls.__annotations__ = {**getattr(cls, "__annotations__", {}), **{n: t for n, (t, _) in inherited.items()}}
+
+        for attr_name, python_type in hints.items():
+            if attr_name.startswith("_"):
+                continue
+            marker = cls.__dict__.get(attr_name)
+            if attr_name in inherited:
+                marker = inherited[attr_name][1]
+
+            if isinstance(marker, ColumnMarker):
+                column_type = marker.type_ or infer_column_type(python_type)
+                columns.append(
+                    ColumnMetadata(
+                        attribute_name=attr_name,
+                        column_name=strategy.column_name(attr_name, marker.column_name),
+                        type_=column_type,
+                        python_type=python_type,
+                        primary=marker.primary,
+                        generated=marker.generated,
+                        nullable=marker.nullable,
+                        unique=marker.unique,
+                        index=marker.index,
+                        default=marker.default,
+                        create_date=marker.create_date,
+                        update_date=marker.update_date,
+                    )
+                )
+                dataclass_fields[attr_name] = dataclasses.field(default=marker.default)
+
+            elif isinstance(marker, RelationMarker):
+                is_to_many = marker.relation_type.name in ("ONE_TO_MANY", "MANY_TO_MANY")
+                relations.append(
+                    RelationMetadata(
+                        attribute_name=attr_name,
+                        relation_type=marker.relation_type,
+                        target_resolver=target_resolver(marker.target),
+                        inverse_side=marker.inverse_side,
+                        nullable=marker.nullable,
+                        on_delete=marker.on_delete,
+                        cascade=marker.cascade,
+                        join_column=marker.join_column.to_metadata() if marker.join_column else None,
+                        join_table=marker.join_table.to_metadata() if marker.join_table else None,
+                    )
+                )
+                dataclass_fields[attr_name] = (
+                    dataclasses.field(default_factory=marker.default_factory or list)
+                    if is_to_many
+                    else dataclasses.field(default=marker.default)
+                )
+            elif attr_name not in dataclass_fields:
+                # A plain, un-marked annotated attribute -- not part of the mapped/persisted
+                # schema (matches TypeORM: only decorated properties are columns/relations), but
+                # still needs *some* default so it can never violate dataclass field-ordering
+                # ("non-default argument follows default argument") relative to the mapped
+                # fields above it, since every mapped field always carries an explicit default.
+                existing = cls.__dict__.get(attr_name, None)
+                dataclass_fields[attr_name] = existing if existing is not None else dataclasses.field(default=None)
+
+        for attr_name, field_spec in dataclass_fields.items():
+            setattr(cls, attr_name, field_spec)
+
+        entity_cls = dataclasses.dataclass(eq=False, repr=True)(cls)
+
+        table_name = strategy.table_name(entity_cls.__name__, name)
+        metadata = EntityMetadata(
+            entity_cls=entity_cls,
+            table_name=table_name,
+            columns=columns,
+            relations=relations,
+            append_only=append_only,
+        )
+
+        set_metadata(ENTITY_METADATA, metadata)(entity_cls)
+        MetadataRegistry.register(entity_cls, metadata)
+        return entity_cls
+
+    return decorator
+
+
+def get_entity_metadata(entity_cls: type) -> EntityMetadata:
+    from austial.orm.exceptions import OrmError
+
+    metadata = MetadataRegistry.get(entity_cls)
+    if metadata is None:
+        raise OrmError(f"{entity_cls!r} is not decorated with @Entity()")
+    return metadata

austial_orm-0.2.1/src/austial/orm/decorators/inject_repository.py

@@ -0,0 +1,33 @@
+"""``@InjectRepository(Entity)`` -- mirrors ``@nestjs/typeorm``'s ``@InjectRepository()``.
+
+Reuses ``austial.common``'s ``InjectMarker`` directly rather than inventing a parallel marker
+type, so the DI container's existing ``isinstance(default, InjectMarker)`` branch
+(``packages/core/src/austial/core/container.py``) resolves it with zero core-package changes::
+
+    @Injectable()
+    class CatsService:
+        def __init__(self, cats: Repository[Cat] = InjectRepository(Cat)):
+            self._cats = cats
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from austial.common.decorators.injectable import InjectMarker
+
+
+def repository_token(entity: type) -> str:
+    """The DI token a given entity's repository is registered/injected under. Computed the same
+    way in ``orm_module.py`` (``OrmModule.for_feature``) and here, so both sides always agree."""
+    return f"austial:orm:repository:{entity.__module__}.{entity.__qualname__}"
+
+
+def InjectRepository(entity: type) -> Any:  # noqa: N802 - decorator-style naming
+    """Returns an ``InjectMarker`` at runtime (see ``Container._resolve_constructor_args``), but is
+    typed ``Any`` -- like every other param-marker helper (``Body()``, ``Inject()``, ...) -- so it
+    can stand as the default for a parameter annotated ``Repository[Cat]`` without mypy flagging an
+    ``InjectMarker``/``Repository[Cat]`` mismatch. The annotation is what callers actually get; this
+    marker is swapped out for the real repository before the constructor ever runs.
+    """
+    return InjectMarker(repository_token(entity))