loom.core.cache.repository

Functions

_infer_otm_cache_dep(model, attr_name, rel)	Auto-infer entity:fk_col cache spec for a ONE_TO_MANY relation.
_infer_projection_cache_dep(model, proj)	Auto-infer entity:fk_col cache spec for a projection loader.
_list_element_type(annotation)	Return T for list[T] annotations, or None if not a typed list.
_resolve_loader_model(loader)	Return the domain model class from a projection loader, handling callables.

Classes

CachedRepository(repository, *, config, ...)	Cache-aside wrapper with generational invalidation.
_DependencySpec(entity, fk_field)
_ListIndexPayload(ids, total_count)
_QueryIndexPayload(ids[, total_count, ...])

class loom.core.cache.repository.CachedRepository(repository, *, config, cache, dependency_resolver)

Bases: Repository[OutputT, CreateT, UpdateT, IdT], Generic[OutputT, CreateT, UpdateT, IdT]

Cache-aside wrapper with generational invalidation.

Parameters:

• repository (Repository[OutputT, CreateT, UpdateT, IdT])

• config (CacheConfig)

• cache (CacheBackend)

• dependency_resolver (DependencyResolver)

property entity_name: str

Normalized name of the cached entity.

async get_by_id(obj_id, profile='default')

Fetch a single entity by its primary key.

Parameters:

• obj_id (IdT) – Primary key of the entity.

• profile (str) – Loading profile name for eager-load options.

Returns:

The entity output struct, or None if not found.

Return type:

OutputT | None

async get_by(field, value, profile='default')

Fetch one entity by arbitrary field.

This path intentionally delegates to the wrapped repository without cache-aside behavior for now. Field-based lookups can target mutable columns and the cache invalidation surface is broader than id-based access; keeping it uncached preserves correctness while the lookup cache policy is designed explicitly.

Parameters:

• field (str)

• value (Any)

• profile (str)

Return type:

OutputT | None

async exists_by(field, value)

Check existence by arbitrary field.

Existence checks are delegated directly to the wrapped repository to avoid stale negative/positive cache entries on mutable fields.

Parameters:

• field (str)

• value (Any)

Return type:

bool

async list_paginated(page_params, filter_params=None, profile='default')

Fetch a paginated list of entities.

Parameters:

• page_params (PageParams) – Pagination parameters (page and limit).

• filter_params (FilterParams | None) – Optional filter criteria.

• profile (str) – Loading profile name for eager-load options.

Returns:

A PageResult with the matching items and pagination metadata.

Return type:

PageResult[OutputT]

async list_with_query(query, profile='default')

Fetch entities using a structured QuerySpec.

Supports both offset and cursor pagination, structured filters, and explicit sort directives. The concrete return type depends on query.pagination:

• PaginationMode.OFFSET → PageResult

• PaginationMode.CURSOR → CursorResult

Parameters:

• query (QuerySpec) – Structured query specification.

• profile (str) – Loading profile name for eager-load options.

Returns:

A PageResult for offset queries or a CursorResult for cursor queries.

Return type:

PageResult[OutputT] | CursorResult[OutputT]

async create(data)

Persist a new entity.

Parameters:

data (CreateT) – Creation payload struct.

Returns:

The newly created entity output struct.

Return type:

OutputT

async update(obj_id, data)

Apply a partial update to an existing entity.

Parameters:

• obj_id (IdT) – Primary key of the entity to update.

• data (UpdateT) – Partial update payload struct.

Returns:

The updated entity output struct, or None if not found.

Return type:

OutputT | None

async delete(obj_id)

Delete an entity by its primary key.

Parameters:

obj_id (IdT) – Primary key of the entity to delete.

Returns:

True if the entity was deleted, False if not found.

Return type:

bool