Inertia Types¶

Type definitions and utilities for Inertia.js protocol support.

This module provides the core type definitions used for Inertia.js page rendering, including page props, headers, and configuration for v2 features like deferred props, merge strategies, and infinite scroll.

Available Types¶

PageProps: Generic type representing the complete page object sent to Inertia client. Includes support for v2 features like history encryption, merge props, deferred loading, and infinite scroll.
InertiaProps: Wrapper type for Inertia props.
InertiaHeaderType: TypedDict for Inertia request/response headers.
MergeStrategy: Literal type for merge strategies: “append”, “prepend”, “deep”.
DeferredPropsConfig: Configuration for lazy-loaded props (v2 feature).
ScrollPropsConfig: Configuration for infinite scroll pagination (v2 feature).

Available Functions¶

to_camel_case: Convert snake_case strings to camelCase for JavaScript compatibility.
to_inertia_dict: Convert Python dataclasses to dicts with camelCase keys for Inertia.js protocol.

Inertia protocol types and serialization helpers.

This module defines the Python-side data structures for the Inertia.js protocol and provides helpers to serialize dataclass instances into the camelCase shape expected by the client.

class litestar_vite.inertia.types.DeferredPropsConfig[source]¶

Bases: object

Configuration for deferred props (v2 feature).

Deferred props are loaded lazily after the initial page render. This allows for faster initial page loads by deferring non-critical data.

__init__(group: str = 'default', props: list[str] = <factory>) → None¶

class litestar_vite.inertia.types.InertiaHeaderType[source]¶

Bases: TypedDict

Type for inertia_headers parameter in get_headers().

class litestar_vite.inertia.types.PageProps[source]¶

Bases: Generic[T]

Inertia Page Props Type.

This represents the page object sent to the Inertia client. See: https://inertiajs.com/the-protocol

Note: Field names use snake_case in Python but are serialized to camelCase for the Inertia.js protocol using to_inertia_dict().

component¶

JavaScript component name to render.

Type:: str

url¶

Current page URL.

Type:: str

version¶

Asset version identifier for cache busting.

Type:: str

props¶

Page data/props passed to the component.

Type:: dict[str, Any]

encrypt_history¶

Whether to encrypt browser history state (v2).

Type:: bool

clear_history¶

Whether to clear encrypted history state (v2).

Type:: bool

merge_props¶

Props to append during navigation (v2).

Type:: list[str] | None

prepend_props¶

Props to prepend during navigation (v2).

Type:: list[str] | None

deep_merge_props¶

Props to deep merge during navigation (v2).

Type:: list[str] | None

match_props_on¶

Keys for matching items during merge (v2).

Type:: dict[str, list[str]] | None

deferred_props¶

Configuration for lazy-loaded props (v2).

Type:: dict[str, list[str]] | None

scroll_props¶

Configuration for infinite scroll (v2).

Type:: litestar_vite.inertia.types.ScrollPropsConfig | None

to_dict() → dict[str, Any][source]¶

Convert to Inertia.js protocol format with camelCase keys.

Returns:: The Inertia protocol dictionary.

__init__(component: str, url: str, version: str, props: dict[str, Any], encrypt_history: bool = False, clear_history: bool = False, merge_props: list[str] | None = None, prepend_props: list[str] | None = None, deep_merge_props: list[str] | None = None, match_props_on: dict[str, list[str]] | None = None, deferred_props: dict[str, list[str]] | None = None, scroll_props: ScrollPropsConfig | None = None) → None¶

class litestar_vite.inertia.types.ScrollPagination[source]¶

Bases: Generic[T]

Pagination container optimized for infinite scroll.

A generic pagination type that works seamlessly with Inertia’s infinite scroll feature. Can be constructed directly or created from any pagination container using create_from().

items¶

The paginated items for the current page.

Type:: list[litestar_vite.inertia.types.T]

total¶

Total number of items across all pages.

Type:: int

limit¶

Maximum items per page (page size).

Type:: int

offset¶

Number of items skipped from the start.

Type:: int

Example:

from litestar_vite.inertia.types import ScrollPagination

Direct construction::

@get("/users", component="Users", infinite_scroll=True)
async def list_users() -> ScrollPagination[User]:
    users = await fetch_users(limit=10, offset=0)
    return ScrollPagination(items=users, total=100, limit=10, offset=0)

From an existing pagination container::

@get("/posts", component="Posts", infinite_scroll=True)
async def list_posts() -> ScrollPagination[Post]:
    pagination = await repo.list_paginated(limit=10, offset=0)
    return ScrollPagination.create_from(pagination)

classmethod create_from(pagination: Any) → ScrollPagination[T][source]¶

Create from any pagination container (auto-detects type).

Supports OffsetPagination, ClassicPagination, and any custom pagination class with standard pagination attributes.

Parameters:: pagination¶ – Any pagination container with items attribute.
Returns:: A ScrollPagination instance with normalized offset-based metadata.

Example:

from litestar.pagination import OffsetPagination, ClassicPagination

From OffsetPagination::

offset_page = OffsetPagination(items=[...], limit=10, offset=20, total=100)
scroll = ScrollPagination.create_from(offset_page)

From ClassicPagination::

classic_page = ClassicPagination(items=[...], page_size=10, current_page=3, total_pages=10)
scroll = ScrollPagination.create_from(classic_page)

__init__(items: list[T], total: int, limit: int, offset: int) → None¶

class litestar_vite.inertia.types.ScrollPropsConfig[source]¶

Bases: object

Configuration for infinite scroll (v2 feature).

__init__(page_name: str = 'page', previous_page: int | None = None, next_page: int | None = None, current_page: int = 1) → None¶

litestar_vite.inertia.types.to_camel_case(snake_str: str) → str[source]¶

Convert snake_case string to camelCase.

Parameters:: snake_str¶ – A snake_case string.
Returns:: The camelCase equivalent.

Examples

>>> to_camel_case("encrypt_history")
'encryptHistory'
>>> to_camel_case("deep_merge_props")
'deepMergeProps'

litestar_vite.inertia.types.to_inertia_dict(obj: Any, required_fields: set[str] | None = None) → dict[str, Any][source]¶

Convert a dataclass to a dict with camelCase keys for Inertia.js protocol.

Parameters:

obj¶ – A dataclass instance.
required_fields¶ – Set of field names that should always be included (even if None).

Returns:

A dictionary with camelCase keys, excluding None values for optional fields.

Note

This function avoids using dataclasses.asdict() directly because of a bug in Python 3.10/3.11 that fails when processing dict[str, list[str]] types. See: https://github.com/python/cpython/issues/103000