release(v0.1.0-rc.3): composite primary keys, DI kwargs auto-wiring, keyset pagination, and route sorting

src/zcore/__init__.py

@@ -1,5 +1,7 @@
 """ZCore Framework Core Package Entrypoint."""
 
+__version__ = "0.1.0-rc.3"
+
 from typing import TYPE_CHECKING, Any
 
 from zcore.config import settings
@@ -113,6 +115,7 @@
     "ZCoreRequest",
     "ZDateTime",
     "Zchema",
+    "__version__",
     "app_exception_handler",
     "background_scope",
     "background_task",

src/zcore/cache/base.py

@@ -8,6 +8,7 @@
 
 import asyncio
 import contextlib
+import threading
 from typing import Any, Generic, TypeVar
 
 import structlog
@@ -29,6 +30,7 @@
 
 _shared_redis_client: Any | None = None
 _eviction_task: asyncio.Task | None = None
+_eviction_lock = threading.Lock()
 
 
 def _ensure_eviction_task(interval: int | None = None) -> None:
@@ -42,10 +44,13 @@ def _ensure_eviction_task(interval: int | None = None) -> None:
     effective_interval: int = int(raw_interval) if raw_interval is not None else 60
     try:
         loop = asyncio.get_running_loop()
-        if _eviction_task is None or _eviction_task.done():
-            _eviction_task = loop.create_task(_start_eviction_loop(interval=effective_interval))
     except RuntimeError:
-        pass
+        return
+
+    if _eviction_task is None or _eviction_task.done():
+        with _eviction_lock:
+            if _eviction_task is None or _eviction_task.done():
+                _eviction_task = loop.create_task(_start_eviction_loop(interval=effective_interval))
 
 
 def init_cache(redis_url: str | None = None, **kwargs: Any) -> None:
@@ -89,11 +94,14 @@ async def close_cache() -> None:
     """Cancel background loops and cleanly close distributed connections."""
     global _shared_redis_client, _eviction_task
 
-    if _eviction_task and not _eviction_task.done():
-        _eviction_task.cancel()
-        with contextlib.suppress(asyncio.CancelledError):
-            await _eviction_task
+    with _eviction_lock:
+        task = _eviction_task
         _eviction_task = None
+
+    if task and not task.done():
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task
         logger.debug("Cache memory eviction loop stopped.")
 
     if _shared_redis_client:

src/zcore/cli/__init__.py

@@ -8,6 +8,7 @@
 import questionary
 from questionary import Choice
 
+from zcore import __version__
 from zcore.cli.commands import (
     DB_DRIVERS,
     find_zcore_projects,
@@ -366,7 +367,7 @@ def main() -> None:
 
         if args.version:
             console.print(
-                f"[bold {ZCORE_PRIMARY}]ZCore Framework[/bold {ZCORE_PRIMARY}] - Version [bold white]0.1.0-rc.2[/bold white]"
+                f"[bold {ZCORE_PRIMARY}]ZCore Framework[/bold {ZCORE_PRIMARY}] - Version [bold white]{__version__}[/bold white]"
             )
             sys.exit(0)
 

src/zcore/cli/templates.py

@@ -5,7 +5,14 @@
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from fastapi import FastAPI
-from zcore import Kernel, db_manager, register_db_event_dispatcher, register_exception_handlers, settings
+from zcore import (
+    Kernel,
+    __version__,
+    db_manager,
+    register_db_event_dispatcher,
+    register_exception_handlers,
+    settings,
+)
 from zcore.logging import setup_logging
 from zcore.web import RequestLogMiddleware, ScopedDependencyMiddleware
 
@@ -33,7 +40,7 @@ async def root():
     return {
         "status": "healthy",
         "framework": "ZCore",
-        "version": "0.1.0-rc.2",
+        "version": __version__,
         "debug": settings.DEBUG
     }
 """

src/zcore/cli/ui.py

@@ -3,6 +3,8 @@
 from questionary import Style
 from rich.console import Console
 
+from zcore import __version__
+
 console = Console()
 
 ZCORE_PRIMARY = "#10b981"
@@ -29,7 +31,7 @@ def print_banner() -> None:
     console.print()
     console.print(
         f"[bold {ZCORE_PRIMARY}]⚡ ZCore Framework[/bold {ZCORE_PRIMARY}] "
-        f"[dim white]v0.1.0-rc.2[/dim white] "
+        f"[dim white]v{__version__}[/dim white] "
         f"[{ZCORE_MUTED}]• Modern Modular Monolith[/{ZCORE_MUTED}]"
     )
     console.print(f" [dim {ZCORE_MUTED}]FastAPI • SQLAlchemy 2.0 • Pydantic V2[/dim {ZCORE_MUTED}]")

src/zcore/config.py

@@ -13,7 +13,7 @@
 from pydantic import AliasChoices, BaseModel, Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from zcore.kernel.di import container
+from zcore.kernel.di import DIException, container
 
 T = TypeVar("T", bound="Settings")
 
@@ -174,6 +174,8 @@ def get_settings(settings_class: type[T] = Settings) -> T:  # type: ignore[assig
         The resolved settings instance of type `T`.
     """
     try:
+        if not container.is_registered(settings_class):
+            raise DIException(f"Settings class {settings_class.__name__} is not initialized.")
         return cast(T, container.resolve(settings_class))
     except Exception:
         settings_inst = settings_class()

src/zcore/db/pagination.py

@@ -11,14 +11,15 @@
 import math
 import uuid
 from collections.abc import Sequence
-from datetime import UTC, datetime
+from datetime import UTC, date, datetime
+from decimal import Decimal
 from typing import Any, Generic, Literal, TypeVar
 
 from pydantic import BaseModel, Field, model_validator
 from sqlalchemy import and_, func, inspect, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.sql import Select
-from sqlalchemy.sql.sqltypes import DateTime
+from sqlalchemy.sql.sqltypes import Date, DateTime
 
 from zcore.config import settings
 from zcore.exceptions.base import ValidationError
@@ -87,10 +88,14 @@ class CursorParams(BaseModel):
         cursor: The base64-encoded keyset cursor string specifying position context.
             If None, fetches from the beginning. Defaults to None.
         size: The maximum quantity of records to yield in the dataset.
+        cursor_field: Target column name used for keyset boundary evaluation. Defaults to None.
+        order: Target sorting order applied during keyset boundary traversal. Defaults to None.
     """
 
     cursor: str | None = None
     size: int | None = None
+    cursor_field: str | None = None
+    order: Literal["asc", "desc"] | str | None = None
 
     @model_validator(mode="after")
     def _validate_and_bound_size(self) -> "CursorParams":
@@ -227,7 +232,7 @@ def __init__(self, cursor_field: str | None = None, order: str = "desc"):
             order: The sorting order ('asc' or 'desc'). Defaults to "desc".
         """
         self.cursor_field = cursor_field
-        self.order = order.lower()
+        self.order = order.lower() if order else "desc"
 
     def _encode_cursor(self, last_item: Any, cursor_field: str, pk_name: str) -> str:
         """Serialize and encode an entity's coordinate parameters to base64.
@@ -244,6 +249,10 @@ def _encode_cursor(self, last_item: Any, cursor_field: str, pk_name: str) -> str
         if isinstance(value, datetime):
             value = value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)
             value = value.isoformat()
+        elif isinstance(value, date):
+            value = value.isoformat()
+        elif isinstance(value, (uuid.UUID, Decimal)):
+            value = str(value)
 
         payload = {"value": value, "pk": str(getattr(last_item, pk_name, ""))}
 
@@ -310,7 +319,9 @@ async def paginate(
         mapper = inspect(model)
         pk_col = mapper.primary_key[0]
         pk_name = pk_col.name
-        effective_cursor_field = self.cursor_field or pk_name
+
+        effective_cursor_field = params.cursor_field or self.cursor_field or pk_name
+        effective_order = (params.order or self.order or "desc").lower()
 
         valid_columns = {col.key for col in mapper.columns}
         if effective_cursor_field not in valid_columns:
@@ -336,22 +347,41 @@ async def paginate(
                 with contextlib.suppress(ValueError):
                     last_pk = uuid.UUID(last_pk)
 
-            if isinstance(col.type, DateTime) and isinstance(val, str):
+            try:
+                col_type = getattr(col.type, "python_type", None)
+            except (NotImplementedError, AttributeError):
+                col_type = None
+
+            if (col_type is datetime or isinstance(col.type, DateTime)) and isinstance(val, str):
                 with contextlib.suppress(ValueError):
                     val = datetime.fromisoformat(val)
+            elif (col_type is date or isinstance(col.type, Date)) and isinstance(val, str):
+                with contextlib.suppress(ValueError):
+                    val = date.fromisoformat(val.split("T")[0])
+            elif col_type is uuid.UUID and isinstance(val, str):
+                with contextlib.suppress(ValueError):
+                    val = uuid.UUID(val)
+            elif col_type is int and isinstance(val, str):
+                with contextlib.suppress(ValueError):
+                    val = int(val)
+            elif col_type is float and isinstance(val, str):
+                with contextlib.suppress(ValueError):
+                    val = float(val)
 
             if effective_cursor_field == pk_name:
-                query = query.where(col < val if self.order == "desc" else col > val)
+                query = query.where(col < val if effective_order == "desc" else col > val)
             else:
-                if self.order == "desc":
+                if effective_order == "desc":
                     query = query.where(or_(col < val, and_(col == val, pk_col < last_pk)))
                 else:
                     query = query.where(or_(col > val, and_(col == val, pk_col > last_pk)))
 
+        query = query.order_by(None)
+
         if effective_cursor_field == pk_name:
-            query = query.order_by(col.desc() if self.order == "desc" else col.asc())
+            query = query.order_by(col.desc() if effective_order == "desc" else col.asc())
         else:
-            if self.order == "desc":
+            if effective_order == "desc":
                 query = query.order_by(col.desc(), pk_col.desc())
             else:
                 query = query.order_by(col.asc(), pk_col.asc())