sqlmodel-object-helpers 0.0.3__tar.gz → 0.0.5__tar.gz

sqlmodel_object_helpers-0.0.5/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# MCP config (local)
+.mcp.json
+
+# OS
+Thumbs.db
+Desktop.ini
+.DS_Store

{sqlmodel_object_helpers-0.0.3 → sqlmodel_object_helpers-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-object-helpers
-Version: 0.0.3
+Version: 0.0.5
 Summary: Generic async query helpers for SQLModel: filtering, eager loading, pagination
 Project-URL: Homepage, https://github.com/itstandart/sqlmodel-object-helpers
 Project-URL: Repository, https://github.com/itstandart/sqlmodel-object-helpers
@@ -55,6 +55,8 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 - **Relationship Safety Check** - `check_for_related_records` pre-deletion inspection of ONETOMANY dependencies
 - **Security Limits** - Configurable depth, list size, and pagination caps to prevent abuse
 - **Type Safety** - Full type annotations with PEP 695 generics and `py.typed` marker (PEP 561)
+- **Standalone Mode** - `configure()` + `import sqlmodel_object_helpers.standalone` for auto-session usage without DI
+- **Session Lifecycle Logging** - Transparent session open/commit/rollback logging with hex session IDs and timing
 
 ## Installation
 
@@ -62,13 +64,20 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 pip install sqlmodel-object-helpers
 ```
 
-One import, everything through dot notation:
+Two usage modes:
 
 ```python
+# DI mode — caller provides session (FastAPI Depends, etc.)
 import sqlmodel_object_helpers as soh
 
 soh.get_object(session, ...)
 soh.add_object(session, ...)
+
+# Standalone mode — auto-creates session per call
+import sqlmodel_object_helpers.standalone as soh_sa
+
+soh_sa.get_object(User, pk={"id": 1})
+soh_sa.add_object(User(name="Alice"))
 ```
 
 ## Quick Start
@@ -109,6 +118,107 @@ async def example(session: AsyncSession):
     # page.data -> list[User], page.pagination.total -> int
 ```
 
+## Standalone Mode
+
+For projects that don't use FastAPI DI or need simple one-call-one-transaction semantics.
+
+> **Important:** The session factory **must** use `expire_on_commit=False`.
+> After each standalone call the session commits and closes — with the default `True`,
+> all attributes on returned objects would be expired and inaccessible (`DetachedInstanceError`).
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+import sqlmodel_object_helpers as soh
+import sqlmodel_object_helpers.standalone as soh_sa
+
+engine = create_async_engine("postgresql+asyncpg://...")
+async_session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+# 1. Configure the session factory once at startup
+soh.configure(async_session_factory)
+
+# 2. Use standalone wrappers — each call creates its own session and commits
+user = await soh_sa.get_object(User, pk={"id": 1})
+new_user = await soh_sa.add_object(User(name="Alice"))
+await soh_sa.delete_object(User, pk={"id": 5})
+
+# All 12 functions are available:
+# Queries:  get_object, get_objects, count_objects, exists_object, get_projection
+# Mutations: add_object, add_objects, update_object, update_objects,
+#            delete_object, delete_objects, check_for_related_records
+```
+
+Each standalone call creates a session, executes the operation, commits on success, and rolls back on error. No session parameter needed.
+
+### auto_session - multi-operation transactions
+
+When you need multiple operations in a single atomic transaction:
+
+```python
+import sqlmodel_object_helpers as soh
+
+async with soh.auto_session() as session:
+    billing = await soh.add_object(session, Billing(...))
+    payment = await soh.add_object(session, Payment(...))
+    # commit happens automatically on exit
+    # if any operation fails — ALL are rolled back
+```
+
+## Session Management
+
+### DI mode — `create_session_dependency()`
+
+For FastAPI projects with dependency injection:
+
+```python
+import sqlmodel_object_helpers as soh
+from typing import Annotated
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+get_session = soh.create_session_dependency(async_session_factory)
+DbSession = Annotated[AsyncSession, Depends(get_session)]
+
+@router.get("/users/{user_id}")
+async def get_user(user_id: int, session: DbSession):
+    return await soh.get_object(session, User, pk={"id": user_id})
+```
+
+One session per HTTP request. The dependency commits on success, rolls back on error.
+
+### Standalone mode — `configure()`
+
+For projects without DI or for scripts/CLI:
+
+```python
+import sqlmodel_object_helpers as soh
+
+soh.configure(async_session_factory)
+# Now standalone functions and auto_session() are available
+```
+
+### Session Lifecycle Logging
+
+All session operations are logged via `logging.getLogger("sqlmodel_object_helpers")`:
+
+```
+DEBUG  auto_session[1a2b3c4d] opened
+DEBUG  auto_session[1a2b3c4d] committed (0.015s)
+WARNING auto_session[1a2b3c4d] rollback (0.003s) — MutationError: ...
+```
+
+- **Hex session ID** (`1a2b3c4d`) correlates all log lines for the same session
+- **Prefix** distinguishes mode: `auto_session` (standalone/auto_session) vs `di_session` (DI dependency)
+- **Timing** shows elapsed time from session open to commit/rollback
+- **Level**: `DEBUG` for normal flow, `WARNING` for rollbacks and commit failures
+
+Enable with:
+
+```python
+import logging
+logging.getLogger("sqlmodel_object_helpers").setLevel(logging.DEBUG)
+```
+
 ## Configuration
 
 Override security limits at application startup:
@@ -127,6 +237,7 @@ soh.settings.max_filter_depth = 50
 | `max_load_depth` | `10` | Maximum depth of eager-loading chains |
 | `max_in_list_size` | `1000` | Maximum elements in an IN(...) list |
 | `max_per_page` | `500` | Maximum value for per_page in pagination |
+| `session_factory` | `None` | `async_sessionmaker` instance for standalone mode (set via `soh.configure()`) |
 
 ## Query Operations
 
@@ -194,13 +305,13 @@ users = await soh.get_objects(
 )
 
 # Time filtering
-from datetime import datetime
+from datetime import datetime, timezone
 
 recent = await soh.get_objects(
     session, User,
     time_filter=soh.TimeFilter(
-        created_after=datetime(2026, 1, 1),
-        created_before=datetime(2026, 2, 1),
+        created_after=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        created_before=datetime(2026, 2, 1, tzinfo=timezone.utc),
     ),
 )
 ```
@@ -221,7 +332,7 @@ active = await soh.count_objects(session, User, filters={"is_active": {soh.Opera
 # With time filter
 recent = await soh.count_objects(
     session, User,
-    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1)),
+    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1, tzinfo=timezone.utc)),
 )
 ```
 
@@ -428,7 +539,34 @@ class UserFilter(BaseModel):
     posts: soh.FilterExists | None = None  # exists: bool
 ```
 
-Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterNaiveDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+
+#### Range Filters
+
+`FilterDatetimeRange` and `FilterNaiveDatetimeRange` parse a comma-separated date string into `gt`/`lt` operators:
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Full range: "FROM,TO" → gt + lt
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,2026-05-06")
+f.model_dump(exclude_none=True)
+# {"gt": datetime(2026, 4, 1, tzinfo=UTC), "lt": datetime(2026, 5, 6, tzinfo=UTC)}
+# SQL: WHERE field > '2026-04-01' AND field < '2026-05-06'
+
+# Open end: "FROM," → gt only
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,")
+# SQL: WHERE field > '2026-04-01'
+
+# Open start: ",TO" → lt only
+f = soh.FilterDatetimeRange.model_validate(",2026-05-06")
+# SQL: WHERE field < '2026-05-06'
+```
+
+Each date part accepts ISO (`2026-04-01`, `2026-04-01T00:00:00Z`) and display format (`01.04.2026 00:00`).
+
+- `FilterDatetimeRange` — produces UTC-aware datetimes
+- `FilterNaiveDatetimeRange` — produces naive (timezone-unaware) datetimes
 
 ## Eager Loading
 
@@ -483,6 +621,16 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ## API Reference
 
+### Session Management
+
+- `soh.configure(factory)` -- Register `async_sessionmaker` for standalone mode
+- `soh.auto_session()` -- Async context manager: creates session, commits on success, rolls back on error
+- `soh.create_session_dependency(factory)` -- Create async generator for FastAPI `Depends`
+
+### Standalone Wrappers
+
+- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions without `session` parameter
+
 ### Settings
 
 - `soh.settings` -- Module-level `QueryHelperSettings` instance (mutable at runtime)
@@ -521,7 +669,7 @@ result = await soh.get_objects(session, User, order_by=order)
 ### Loaders
 
 - `soh.build_load_chain(model, path, ...)` -- Build loader option from string/list path
-- `soh.build_load_options(model, attrs)` -- Build single loader option chain
+- `soh.build_load_options(model, attrs, *, suspend_error=False)` -- Build single loader option chain
 
 ### Exceptions
 
@@ -534,16 +682,33 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Filter Types
 
-- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterNaiveDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterDatetimeRange`, `soh.FilterNaiveDatetimeRange` -- Range filters that parse `"FROM,TO"` strings into `gt`/`lt` operators
 - `soh.OrderAsc`, `soh.OrderDesc`, `soh.OrderBy`
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
 
+### Datetime Types
+
+- `soh.UTCDatetime` -- `Annotated[datetime, AfterValidator]` that rejects naive datetimes and converts aware datetimes to UTC
+
 ### Pagination Types
 
 - `soh.Pagination` -- Request model (page, per\_page)
 - `soh.PaginationR` -- Response model (page, per\_page, total)
-- `soh.GetAllPagination[T]` -- Generic wrapper (data: list[T], pagination: PaginationR | None)
+- `soh.GetAllPagination[T]` -- Generic wrapper (table: TableMeta | None, columns: list[ColumnMeta] | None, data: list[T], pagination: PaginationR | None)
+
+### Table Metadata Types
+
+- `soh.TableMeta` -- Table-level metadata (name, header, row_link)
+- `soh.ColumnMeta` -- Column metadata (json_path, label, type, lookup_dict, lookup_path, bool_labels)
+- `soh.ColumnType` -- StrEnum of column data types (string, integer, float, boolean, date, datetime)
+- `soh.BoolLabels` -- Display labels for boolean columns (true_label, false_label)
+
+### Lookup Types
+
+- `soh.LookupMeta` -- Lookup metadata (name used as cache key, matches `ColumnMeta.lookup_dict`)
+- `soh.LookupResponse[T]` -- Generic wrapper for lookup endpoints (meta: LookupMeta, data: list[T])
 
 ### Projection Types
 
@@ -595,6 +760,19 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 - **MINOR** — new features (backwards compatible)
 - **MAJOR** — breaking changes
 
+## Changelog
+
+### 0.0.5
+
+- **FilterDatetimeRange** / **FilterNaiveDatetimeRange** — range filters that parse comma-separated date strings (`"2026-04-01,2026-05-06"`) into `gt`/`lt` operators for SQL filtering
+- **ColumnMeta** / **TableMeta** / **ColumnType** / **BoolLabels** — dynamic table metadata: backend describes columns, types, labels, lookups, and row navigation so the frontend renders any table without hardcoding
+- **GetAllPagination** — now includes optional `table` and `columns` fields for delivering table metadata alongside paginated data
+- **LookupMeta** / **LookupResponse** — standard `{meta, data}` wrapper for lookup (`_lkp`) endpoints, enabling unified frontend caching of dictionaries with `meta.name` as cache key
+
+### 0.0.4
+
+- Initial public release
+
 ## License
 
 This project is licensed under the **PolyForm Noncommercial License 1.0.0**.

{sqlmodel_object_helpers-0.0.3 → sqlmodel_object_helpers-0.0.5}/README.md

@@ -21,6 +21,8 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 - **Relationship Safety Check** - `check_for_related_records` pre-deletion inspection of ONETOMANY dependencies
 - **Security Limits** - Configurable depth, list size, and pagination caps to prevent abuse
 - **Type Safety** - Full type annotations with PEP 695 generics and `py.typed` marker (PEP 561)
+- **Standalone Mode** - `configure()` + `import sqlmodel_object_helpers.standalone` for auto-session usage without DI
+- **Session Lifecycle Logging** - Transparent session open/commit/rollback logging with hex session IDs and timing
 
 ## Installation
 
@@ -28,13 +30,20 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 pip install sqlmodel-object-helpers
 ```
 
-One import, everything through dot notation:
+Two usage modes:
 
 ```python
+# DI mode — caller provides session (FastAPI Depends, etc.)
 import sqlmodel_object_helpers as soh
 
 soh.get_object(session, ...)
 soh.add_object(session, ...)
+
+# Standalone mode — auto-creates session per call
+import sqlmodel_object_helpers.standalone as soh_sa
+
+soh_sa.get_object(User, pk={"id": 1})
+soh_sa.add_object(User(name="Alice"))
 ```
 
 ## Quick Start
@@ -75,6 +84,107 @@ async def example(session: AsyncSession):
     # page.data -> list[User], page.pagination.total -> int
 ```
 
+## Standalone Mode
+
+For projects that don't use FastAPI DI or need simple one-call-one-transaction semantics.
+
+> **Important:** The session factory **must** use `expire_on_commit=False`.
+> After each standalone call the session commits and closes — with the default `True`,
+> all attributes on returned objects would be expired and inaccessible (`DetachedInstanceError`).
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+import sqlmodel_object_helpers as soh
+import sqlmodel_object_helpers.standalone as soh_sa
+
+engine = create_async_engine("postgresql+asyncpg://...")
+async_session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+# 1. Configure the session factory once at startup
+soh.configure(async_session_factory)
+
+# 2. Use standalone wrappers — each call creates its own session and commits
+user = await soh_sa.get_object(User, pk={"id": 1})
+new_user = await soh_sa.add_object(User(name="Alice"))
+await soh_sa.delete_object(User, pk={"id": 5})
+
+# All 12 functions are available:
+# Queries:  get_object, get_objects, count_objects, exists_object, get_projection
+# Mutations: add_object, add_objects, update_object, update_objects,
+#            delete_object, delete_objects, check_for_related_records
+```
+
+Each standalone call creates a session, executes the operation, commits on success, and rolls back on error. No session parameter needed.
+
+### auto_session - multi-operation transactions
+
+When you need multiple operations in a single atomic transaction:
+
+```python
+import sqlmodel_object_helpers as soh
+
+async with soh.auto_session() as session:
+    billing = await soh.add_object(session, Billing(...))
+    payment = await soh.add_object(session, Payment(...))
+    # commit happens automatically on exit
+    # if any operation fails — ALL are rolled back
+```
+
+## Session Management
+
+### DI mode — `create_session_dependency()`
+
+For FastAPI projects with dependency injection:
+
+```python
+import sqlmodel_object_helpers as soh
+from typing import Annotated
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+get_session = soh.create_session_dependency(async_session_factory)
+DbSession = Annotated[AsyncSession, Depends(get_session)]
+
+@router.get("/users/{user_id}")
+async def get_user(user_id: int, session: DbSession):
+    return await soh.get_object(session, User, pk={"id": user_id})
+```
+
+One session per HTTP request. The dependency commits on success, rolls back on error.
+
+### Standalone mode — `configure()`
+
+For projects without DI or for scripts/CLI:
+
+```python
+import sqlmodel_object_helpers as soh
+
+soh.configure(async_session_factory)
+# Now standalone functions and auto_session() are available
+```
+
+### Session Lifecycle Logging
+
+All session operations are logged via `logging.getLogger("sqlmodel_object_helpers")`:
+
+```
+DEBUG  auto_session[1a2b3c4d] opened
+DEBUG  auto_session[1a2b3c4d] committed (0.015s)
+WARNING auto_session[1a2b3c4d] rollback (0.003s) — MutationError: ...
+```
+
+- **Hex session ID** (`1a2b3c4d`) correlates all log lines for the same session
+- **Prefix** distinguishes mode: `auto_session` (standalone/auto_session) vs `di_session` (DI dependency)
+- **Timing** shows elapsed time from session open to commit/rollback
+- **Level**: `DEBUG` for normal flow, `WARNING` for rollbacks and commit failures
+
+Enable with:
+
+```python
+import logging
+logging.getLogger("sqlmodel_object_helpers").setLevel(logging.DEBUG)
+```
+
 ## Configuration
 
 Override security limits at application startup:
@@ -93,6 +203,7 @@ soh.settings.max_filter_depth = 50
 | `max_load_depth` | `10` | Maximum depth of eager-loading chains |
 | `max_in_list_size` | `1000` | Maximum elements in an IN(...) list |
 | `max_per_page` | `500` | Maximum value for per_page in pagination |
+| `session_factory` | `None` | `async_sessionmaker` instance for standalone mode (set via `soh.configure()`) |
 
 ## Query Operations
 
@@ -160,13 +271,13 @@ users = await soh.get_objects(
 )
 
 # Time filtering
-from datetime import datetime
+from datetime import datetime, timezone
 
 recent = await soh.get_objects(
     session, User,
     time_filter=soh.TimeFilter(
-        created_after=datetime(2026, 1, 1),
-        created_before=datetime(2026, 2, 1),
+        created_after=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        created_before=datetime(2026, 2, 1, tzinfo=timezone.utc),
     ),
 )
 ```
@@ -187,7 +298,7 @@ active = await soh.count_objects(session, User, filters={"is_active": {soh.Opera
 # With time filter
 recent = await soh.count_objects(
     session, User,
-    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1)),
+    time_filter=soh.TimeFilter(created_after=datetime(2026, 1, 1, tzinfo=timezone.utc)),
 )
 ```
 
@@ -394,7 +505,34 @@ class UserFilter(BaseModel):
     posts: soh.FilterExists | None = None  # exists: bool
 ```
 
-Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+Available: `FilterInt`, `FilterStr`, `FilterDate`, `FilterDatetime`, `FilterNaiveDatetime`, `FilterTimedelta`, `FilterBool`, `FilterExists`.
+
+#### Range Filters
+
+`FilterDatetimeRange` and `FilterNaiveDatetimeRange` parse a comma-separated date string into `gt`/`lt` operators:
+
+```python
+import sqlmodel_object_helpers as soh
+
+# Full range: "FROM,TO" → gt + lt
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,2026-05-06")
+f.model_dump(exclude_none=True)
+# {"gt": datetime(2026, 4, 1, tzinfo=UTC), "lt": datetime(2026, 5, 6, tzinfo=UTC)}
+# SQL: WHERE field > '2026-04-01' AND field < '2026-05-06'
+
+# Open end: "FROM," → gt only
+f = soh.FilterDatetimeRange.model_validate("2026-04-01,")
+# SQL: WHERE field > '2026-04-01'
+
+# Open start: ",TO" → lt only
+f = soh.FilterDatetimeRange.model_validate(",2026-05-06")
+# SQL: WHERE field < '2026-05-06'
+```
+
+Each date part accepts ISO (`2026-04-01`, `2026-04-01T00:00:00Z`) and display format (`01.04.2026 00:00`).
+
+- `FilterDatetimeRange` — produces UTC-aware datetimes
+- `FilterNaiveDatetimeRange` — produces naive (timezone-unaware) datetimes
 
 ## Eager Loading
 
@@ -449,6 +587,16 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ## API Reference
 
+### Session Management
+
+- `soh.configure(factory)` -- Register `async_sessionmaker` for standalone mode
+- `soh.auto_session()` -- Async context manager: creates session, commits on success, rolls back on error
+- `soh.create_session_dependency(factory)` -- Create async generator for FastAPI `Depends`
+
+### Standalone Wrappers
+
+- `import sqlmodel_object_helpers.standalone as soh_sa` -- All 12 query/mutation functions without `session` parameter
+
 ### Settings
 
 - `soh.settings` -- Module-level `QueryHelperSettings` instance (mutable at runtime)
@@ -487,7 +635,7 @@ result = await soh.get_objects(session, User, order_by=order)
 ### Loaders
 
 - `soh.build_load_chain(model, path, ...)` -- Build loader option from string/list path
-- `soh.build_load_options(model, attrs)` -- Build single loader option chain
+- `soh.build_load_options(model, attrs, *, suspend_error=False)` -- Build single loader option chain
 
 ### Exceptions
 
@@ -500,16 +648,33 @@ result = await soh.get_objects(session, User, order_by=order)
 
 ### Filter Types
 
-- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterInt`, `soh.FilterStr`, `soh.FilterDate`, `soh.FilterDatetime`, `soh.FilterNaiveDatetime`, `soh.FilterTimedelta`, `soh.FilterBool`, `soh.FilterExists`
+- `soh.FilterDatetimeRange`, `soh.FilterNaiveDatetimeRange` -- Range filters that parse `"FROM,TO"` strings into `gt`/`lt` operators
 - `soh.OrderAsc`, `soh.OrderDesc`, `soh.OrderBy`
 - `soh.LogicalFilter`
 - `soh.TimeFilter` -- `created_after`, `created_before`, `updated_after`, `updated_before` with half-open interval `[after, before)`
 
+### Datetime Types
+
+- `soh.UTCDatetime` -- `Annotated[datetime, AfterValidator]` that rejects naive datetimes and converts aware datetimes to UTC
+
 ### Pagination Types
 
 - `soh.Pagination` -- Request model (page, per\_page)
 - `soh.PaginationR` -- Response model (page, per\_page, total)
-- `soh.GetAllPagination[T]` -- Generic wrapper (data: list[T], pagination: PaginationR | None)
+- `soh.GetAllPagination[T]` -- Generic wrapper (table: TableMeta | None, columns: list[ColumnMeta] | None, data: list[T], pagination: PaginationR | None)
+
+### Table Metadata Types
+
+- `soh.TableMeta` -- Table-level metadata (name, header, row_link)
+- `soh.ColumnMeta` -- Column metadata (json_path, label, type, lookup_dict, lookup_path, bool_labels)
+- `soh.ColumnType` -- StrEnum of column data types (string, integer, float, boolean, date, datetime)
+- `soh.BoolLabels` -- Display labels for boolean columns (true_label, false_label)
+
+### Lookup Types
+
+- `soh.LookupMeta` -- Lookup metadata (name used as cache key, matches `ColumnMeta.lookup_dict`)
+- `soh.LookupResponse[T]` -- Generic wrapper for lookup endpoints (meta: LookupMeta, data: list[T])
 
 ### Projection Types
 
@@ -561,6 +726,19 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 - **MINOR** — new features (backwards compatible)
 - **MAJOR** — breaking changes
 
+## Changelog
+
+### 0.0.5
+
+- **FilterDatetimeRange** / **FilterNaiveDatetimeRange** — range filters that parse comma-separated date strings (`"2026-04-01,2026-05-06"`) into `gt`/`lt` operators for SQL filtering
+- **ColumnMeta** / **TableMeta** / **ColumnType** / **BoolLabels** — dynamic table metadata: backend describes columns, types, labels, lookups, and row navigation so the frontend renders any table without hardcoding
+- **GetAllPagination** — now includes optional `table` and `columns` fields for delivering table metadata alongside paginated data
+- **LookupMeta** / **LookupResponse** — standard `{meta, data}` wrapper for lookup (`_lkp`) endpoints, enabling unified frontend caching of dictionaries with `meta.name` as cache key
+
+### 0.0.4
+
+- Initial public release
+
 ## License
 
 This project is licensed under the **PolyForm Noncommercial License 1.0.0**.