# API Reference

## LoaderProvider

Provider component that stores page and key loader counters.

```ts
function LoaderProvider(props: { children: React.ReactNode }): React.JSX.Element
```

## useLoaderStates

Hook to access loader state and controls.

```ts
function useLoaderStates(): LoaderContextValue
```

## LoaderContextValue

```ts
interface LoaderContextValue {
  isAnyPageLoading: boolean;
  activePageKeys: string[];
  activeKeys: string[];
  isPageLoading: (pageKey?: string) => boolean;
  startPageLoader: (pageKey?: string) => void;
  stopPageLoader: (pageKey?: string) => void;
  withPageLoader: <T>(promiseInput: Promise<T> | (() => Promise<T>), pageKey?: string) => Promise<T>;
  isKeyLoading: (key: string) => boolean;
  registerLoader: (key: string) => void;
  removeLoader: (key: string) => void;
  withKeyLoader: <T>(key: string, promiseInput: Promise<T> | (() => Promise<T>)) => Promise<T>;
}
```

## withLoader

Generic utility wrapper for custom start/finally handlers.

```ts
function withLoader<T>(
  handlers: { onStart: () => void; onFinally: () => void },
  promiseInput: Promise<T> | (() => Promise<T>)
): Promise<T>
```

## Behavior Notes

- Counters are additive and concurrency-safe.
- Same key can be registered multiple times; loading ends when counter returns to zero.
- pageKey is optional; if omitted, an internal default page key is used.
- withPageLoader and withKeyLoader always stop in finally, even on errors.