Inertia Helpers

litestar_vite.inertia.helpers.lazy(key: str, value_or_callable: None) → StaticProp[str, None]

litestar_vite.inertia.helpers.lazy(key: str, value_or_callable: T) → StaticProp[str, T]

litestar_vite.inertia.helpers.lazy(key: str, value_or_callable: Callable[[...], None] = None) → DeferredProp[str, None]

litestar_vite.inertia.helpers.lazy(key: str, value_or_callable: Callable[[...], Coroutine[Any, Any, None]] = None) → DeferredProp[str, None]

litestar_vite.inertia.helpers.lazy(key: str, value_or_callable: Callable[[...], T | Coroutine[Any, Any, T]] = None) → DeferredProp[str, T]

Wrap an async function to return a DeferredProp.

Parameters:

• key – The key to store the value under.

• value_or_callable – The value or callable to store.

Returns:

The wrapped value or callable.

litestar_vite.inertia.helpers.defer(key: str, callback: Callable[[...], T | Coroutine[Any, Any, T]], group: str = 'default') → DeferredProp[str, T]

Create a deferred prop with optional grouping (v2 feature).

Deferred props are loaded lazily after the initial page render. Props in the same group are fetched together in a single request.

Parameters:

• key – The key to store the value under.

• callback – A callable (sync or async) that returns the value.

• group – The group name for batched loading. Defaults to “default”.

Returns:

A DeferredProp instance.

Example:

# Basic deferred prop
defer("permissions", lambda: Permission.all())

# Grouped deferred props (fetched together)
defer("teams", lambda: Team.all(), group="attributes")
defer("projects", lambda: Project.all(), group="attributes")

class litestar_vite.inertia.helpers.MergeProp

Bases: Generic[PropKeyT, T]

A wrapper for merge prop configuration (v2 feature).

Merge props allow data to be combined with existing props during partial reloads instead of replacing them entirely.

__init__(key: PropKeyT, value: T, strategy: Literal['append', 'prepend', 'deep'] = 'append', match_on: str | list[str] | None = None) → None

Initialize a MergeProp.

Parameters:

• key – The prop key.

• value – The value to merge.

• strategy – The merge strategy - ‘append’, ‘prepend’, or ‘deep’.

• match_on – Optional key(s) to match items on during merge.

property key: PropKeyT

The prop key.

property value: T

The value to merge.

property strategy: Literal['append', 'prepend', 'deep']

The merge strategy.

property match_on: list[str] | None

Keys to match items on during merge.

litestar_vite.inertia.helpers.merge(key: str, value: T, strategy: Literal['append', 'prepend', 'deep'] = 'append', match_on: str | list[str] | None = None) → MergeProp[str, T]

Create a merge prop for combining data during partial reloads (v2 feature).

Merge props allow new data to be combined with existing props rather than replacing them entirely. This is useful for infinite scroll, load more buttons, and similar patterns.

Note: Prop merging only works during partial reloads. Full page visits will always replace props entirely.

Parameters:

• key – The prop key.

• value – The value to merge.

• strategy – How to merge the data: - ‘append’: Add new items to the end (default) - ‘prepend’: Add new items to the beginning - ‘deep’: Recursively merge nested objects

• match_on – Optional key(s) to match items on during merge, useful for updating existing items instead of duplicating.

Returns:

A MergeProp instance.

Example:

# Append new items to existing list
merge("posts", new_posts)

# Prepend new messages
merge("messages", new_messages, strategy="prepend")

# Deep merge nested data
merge("user_data", updates, strategy="deep")

# Match on ID to update existing items
merge("posts", updated_posts, match_on="id")

litestar_vite.inertia.helpers.is_merge_prop(value: Any) → TypeGuard[MergeProp[Any, Any]]

Check if value is a MergeProp.

Parameters:

value – Any value to check

Returns:

True if value is a MergeProp

Return type:

bool

litestar_vite.inertia.helpers.extract_merge_props(props: dict[str, Any]) → tuple[list[str], list[str], list[str], dict[str, list[str]]]

Extract merge props metadata for the Inertia v2 protocol.

This extracts all MergeProp instances from the props dict and categorizes them by their merge strategy, returning the appropriate lists for the page response.

Parameters:

props – The props dictionary to scan.

Returns:

A tuple of (merge_props, prepend_props, deep_merge_props, match_props_on) where each list contains the prop keys for that strategy, and match_props_on is a dict mapping prop keys to the keys to match on.

Example:

props = {
    "users": [...],  # regular prop
    "posts": merge("posts", new_posts),  # append
    "messages": merge("messages", new_msgs, strategy="prepend"),
    "data": merge("data", updates, strategy="deep"),
    "items": merge("items", items, match_on="id"),
}
merge_props, prepend_props, deep_merge_props, match_props_on = extract_merge_props(props)
# merge_props = ["posts", "items"]
# prepend_props = ["messages"]
# deep_merge_props = ["data"]
# match_props_on = {"items": ["id"]}

class litestar_vite.inertia.helpers.StaticProp

Bases: Generic[PropKeyT, StaticT]

A wrapper for static property evaluation.

__init__(key: PropKeyT, value: StaticT) → None

class litestar_vite.inertia.helpers.DeferredProp

Bases: Generic[PropKeyT, T]

A wrapper for deferred property evaluation.

__init__(key: PropKeyT, value: Callable[[...], T | Coroutine[Any, Any, T] | None] | None = None, group: str = 'default') → None

property group: str

The deferred group this prop belongs to.

litestar_vite.inertia.helpers.is_lazy_prop(value: Any) → TypeGuard[DeferredProp[Any, Any] | StaticProp[Any, Any]]

Check if value is a deferred property.

Parameters:

value – Any value to check

Returns:

True if value is a deferred property

Return type:

bool

litestar_vite.inertia.helpers.is_deferred_prop(value: Any) → TypeGuard[DeferredProp[Any, Any]]

Check if value is specifically a DeferredProp (not StaticProp).

Parameters:

value – Any value to check

Returns:

True if value is a DeferredProp

Return type:

bool

litestar_vite.inertia.helpers.extract_deferred_props(props: dict[str, Any]) → dict[str, list[str]]

Extract deferred props metadata for the Inertia v2 protocol.

This extracts all DeferredProp instances from the props dict and groups them by their group name, returning a dict mapping group -> list of prop keys.

Parameters:

props – The props dictionary to scan.

Returns:

A dict mapping group names to lists of prop keys in that group. Empty dict if no deferred props found.

Example:

props = {
    "users": [...],  # regular prop
    "teams": defer("teams", get_teams, group="attributes"),
    "projects": defer("projects", get_projects, group="attributes"),
    "permissions": defer("permissions", get_permissions),  # default group
}
result = extract_deferred_props(props)
# {"default": ["permissions"], "attributes": ["teams", "projects"]}

litestar_vite.inertia.helpers.should_render(value: Any, partial_data: set[str] | None = None, partial_except: set[str] | None = None) → bool

Check if value should be rendered.

For v2 protocol, partial_except takes precedence over partial_data.

Parameters:

• value – Any value to check

• partial_data – Optional set of keys to include (X-Inertia-Partial-Data)

• partial_except – Optional set of keys to exclude (X-Inertia-Partial-Except, v2)

Returns:

True if value should be rendered

Return type:

bool

litestar_vite.inertia.helpers.is_or_contains_lazy_prop(value: Any) → bool

Check if value is or contains a deferred property.

Parameters:

value – Any value to check

Returns:

True if value is or contains a deferred property

Return type:

bool

litestar_vite.inertia.helpers.lazy_render(value: T, partial_data: set[str] | None = None, portal: BlockingPortal | None = None, partial_except: set[str] | None = None) → T

Filter deferred properties from the value based on partial data.

For v2 protocol, partial_except takes precedence over partial_data.

Parameters:

• value – The value to filter

• partial_data – Keys to include (X-Inertia-Partial-Data)

• portal – Optional portal to use for async rendering

• partial_except – Keys to exclude (X-Inertia-Partial-Except, v2)

Returns:

The filtered value

litestar_vite.inertia.helpers.get_shared_props(request: ASGIConnection[Any, Any, Any, Any], partial_data: set[str] | None = None, partial_except: set[str] | None = None) → dict[str, Any]

Return shared session props for a request.

For v2 protocol, partial_except takes precedence over partial_data.

Parameters:

• request – The ASGI connection.

• partial_data – Optional set of keys to include (X-Inertia-Partial-Data).

• partial_except – Optional set of keys to exclude (X-Inertia-Partial-Except, v2).

Returns:

The shared props.

Return type:

Dict[str, Any]

Note

Be sure to call this before self.create_template_context if you would like to include the flash message details.

litestar_vite.inertia.helpers.share(connection: ASGIConnection[Any, Any, Any, Any], key: str, value: Any) → None

Share a value in the session.

Parameters:

• connection – The ASGI connection.

• key – The key to store the value under.

• value – The value to store.

litestar_vite.inertia.helpers.error(connection: ASGIConnection[Any, Any, Any, Any], key: str, message: str) → None

Set an error message in the session.

Parameters:

• connection – The ASGI connection.

• key – The key to store the error under.

• message – The error message.