@dynamicforms/fastapi-viewsets 0.5.6 → 0.6.0

package/dist/index.d.ts

@@ -1,11 +1,695 @@
-export { BulkCreateMixin, BulkDestroyMixin, BulkOnlyCreateMixin, BulkOnlyDestroyMixin, BulkOnlyUpdateMixin, BulkUpdateMixin, BulkViewSetMixin, CreateMixin, CursorListMixin, DestroyMixin, ListMixin, LookupMixin, PaginatedListMixin, ReadOnlyViewSetMixin, RetrieveMixin, UpdateMixin, ViewSetMixin, } from './mixins';
-export type { ActionName, ActionSurface, CursorPage, DestroyReturnData, CursorParams, KeyType, ListParams, LookupItem, PageParams, PaginatedList, } from './mixins';
-export type { HttpMethod, ProxyBaseOptions, QueryParams, RequestOptions, ViewSetMixinDeclaration } from './proxy-base';
-export { ViewSetInternals, ViewSetProxyBase, ViewSetRequestError } from './proxy-base';
-export type { PkFieldName, ViewSetClass, ViewSetMixinClass } from './viewset';
-export { muxwsViewSet, restViewSet } from './viewset';
-export type { RestProxy, RestProxyOptions } from './rest-proxy';
-export { route_rest, RestProxyImpl } from './rest-proxy';
-export type { MuxwsPeerLike, MuxwsPeerSource, MuxwsProxy, MuxwsProxyOptions, MuxwsStreamLike } from './muxws-proxy';
-export { route_muxws, MuxwsProxyImpl } from './muxws-proxy';
-//# sourceMappingURL=index.d.ts.map
+import { AxiosInstance } from 'axios';
+import { TranslateStringsCallback } from '@dynamicforms/translatable';
+
+/** Every action name there is: `A = string` selects all of them. */
+export declare type ActionName = keyof ActionSurface<KeyType_2, unknown, never, string>;
+
+/**
+ * The actions a mixin class names, read off its instance type.
+ *
+ * The instance type rather than the `actions` tuple, because a tuple would have to be `as const` on
+ * every mixin, and a `readonly ['create']` static cannot then be inherited by a composite whose own
+ * static is a different tuple (TS2417). `D` is naked so that a union of mixins distributes.
+ */
+declare type ActionsOf<D> = D extends abstract new (...args: any[]) => infer I ? Extract<keyof I, ActionName> : never;
+
+/**
+ * The actions named by `A`, each with the signature the mixin that contributes it declares. One
+ * conditional per single-action mixin; the composites are absent on purpose, so that any action's
+ * signature is written in exactly one place.
+ *
+ * An intersection rather than `Pick<>` of a table: a mapped type turns a method into a property,
+ * and a subclass cannot then override an action with a method (TS2425).
+ */
+export declare type ActionSurface<K extends KeyType_2, T, PK extends keyof T, A> = ('create' extends A ? CreateMixin<T, PK> : unknown) & ('bulkCreate' extends A ? BulkOnlyCreateMixin<T, PK> : unknown) & ('list' extends A ? ListMixin<T> : unknown) & ('listPage' extends A ? PaginatedListMixin<T> : unknown) & ('listCursor' extends A ? CursorListMixin<T> : unknown) & ('retrieve' extends A ? RetrieveMixin<K, T> : unknown) & ('update' extends A ? UpdateMixin<K, T> : unknown) & ('bulkUpdate' extends A ? BulkOnlyUpdateMixin<K, T> : unknown) & ('destroy' extends A ? DestroyMixin<K> : unknown) & ('bulkDestroy' extends A ? BulkOnlyDestroyMixin<K> : unknown) & ('lookup' extends A ? LookupMixin : unknown);
+
+/**
+ * A failed request's response body. `detail` is always a plain string - unchanged from what it has
+ * always been. `detail_code` and `detail_params` are additive, and appear only when the server has
+ * registered `df_viewset_exception_handler` (see the Python side's `fastapi_viewsets.exceptions`)
+ * for one of this package's own built-in errors; a view's own `raise HTTPException(status_code,
+ * detail="...")` never carries them.
+ */
+export declare interface ApiErrorBody {
+    detail: string;
+    detail_code?: string;
+    detail_params?: Record<string, unknown>;
+}
+
+export declare interface BulkCreateMixin<T, PK extends keyof T> extends CreateMixin<T, PK>, BulkOnlyCreateMixin<T, PK> {
+}
+
+export declare class BulkCreateMixin<T, PK extends keyof T> extends CreateMixin<T, PK> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface BulkDestroyMixin<K extends KeyType_2> extends DestroyMixin<K>, BulkOnlyDestroyMixin<K> {
+}
+
+export declare class BulkDestroyMixin<K extends KeyType_2> extends DestroyMixin<K> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface BulkOnlyCreateMixin<T, PK extends keyof T> {
+    bulkCreate(data: Omit<T, PK>[]): Promise<T[]>;
+}
+
+export declare class BulkOnlyCreateMixin<T, PK extends keyof T> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface BulkOnlyDestroyMixin<K extends KeyType_2> {
+    bulkDestroy(pks: K[]): Promise<DestroyReturnData[]>;
+}
+
+export declare class BulkOnlyDestroyMixin<K extends KeyType_2> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface BulkOnlyUpdateMixin<K extends KeyType_2, T> {
+    bulkUpdate(records: Record<K, T>): Promise<T[]>;
+    bulkPartialUpdate(records: Record<K, Partial<T>>): Promise<T[]>;
+}
+
+export declare class BulkOnlyUpdateMixin<K extends KeyType_2, T> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface BulkUpdateMixin<K extends KeyType_2, T> extends UpdateMixin<K, T>, BulkOnlyUpdateMixin<K, T> {
+}
+
+export declare class BulkUpdateMixin<K extends KeyType_2, T> extends UpdateMixin<K, T> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface BulkViewSetMixin<K extends KeyType_2, T, PK extends keyof T> extends ViewSetMixin<K, T, PK>, BulkOnlyCreateMixin<T, PK>, BulkOnlyUpdateMixin<K, T>, BulkOnlyDestroyMixin<K> {
+}
+
+export declare class BulkViewSetMixin<K extends KeyType_2, T, PK extends keyof T> extends ViewSetMixin<K, T, PK> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface CreateMixin<T, PK extends keyof T> {
+    create(data: Omit<T, PK>): Promise<T>;
+}
+
+export declare class CreateMixin<T, PK extends keyof T> {
+    static readonly actions: readonly string[];
+}
+
+/** FE counterpart of the BE CursorListMixin. See PaginatedListMixin on declaring several shapes. */
+export declare interface CursorListMixin<T> {
+    listCursor(params?: CursorParams): Promise<CursorPage<T>>;
+}
+
+export declare class CursorListMixin<T> {
+    static readonly actions: readonly string[];
+}
+
+/**
+ * One cursor page.
+ *
+ * `next`/`previous` are exclusive, so following them never repeats a row. `first`/`last` are the
+ * same two edges read inclusively: they return their own row again — one duplicate to drop — and
+ * in exchange they survive rows being inserted at that edge, which is what polling a live list
+ * needs. They are present whenever the page is non-empty, even when `next` is null.
+ *
+ * There is no total count: producing one costs a second full pass per request and is stale by the
+ * time it is read.
+ */
+export declare interface CursorPage<T> {
+    results: T[];
+    limit: number;
+    hasMore: boolean;
+    hasPrevious: boolean;
+    next: string | null;
+    previous: string | null;
+    first: string | null;
+    last: string | null;
+}
+
+export declare interface CursorParams extends ListParams {
+    cursor?: string;
+    limit?: number;
+}
+
+export declare interface DestroyMixin<K extends KeyType_2> {
+    destroy(pk: K): Promise<DestroyReturnData>;
+}
+
+export declare class DestroyMixin<K extends KeyType_2> {
+    static readonly actions: readonly string[];
+}
+
+export declare type DestroyReturnData = Record<KeyType_2, any>;
+
+/**
+ * Marks a class's `declares` as coming from the ViewSet factory (viewset.ts's `FactoryDeclares<D>`)
+ * rather than being hand-written. Declared here, the module both viewset.ts and the two proxy
+ * implementations already import from, so all three sides see the same `unique symbol` and a
+ * structural check against it type-checks identically everywhere - `route_rest`/`route_muxws` use it
+ * to reject a factory-built class at the call site (see rest-proxy.ts, muxws-proxy.ts), which would
+ * otherwise type-check and hand back a bare proxy missing the class's own custom methods.
+ */
+declare const FACTORY_BUILT: unique symbol;
+
+/** Never assigned; its only use is `typeof FACTORY_BUILT_REJECTION` as a self-describing return type. */
+declare const FACTORY_BUILT_REJECTION: 'route_rest cannot take a factory-built class - extend it directly instead';
+
+/** Never assigned; its only use is `typeof FACTORY_BUILT_REJECTION` as a self-describing return type. */
+declare const FACTORY_BUILT_REJECTION_2: 'route_muxws cannot take a factory-built class - extend it directly instead';
+
+/**
+ * The shape a factory-built class's constructor has, purely to give `route_rest` an overload that
+ * rejects it - a type parameter conditioned on the argument (`C extends FactoryBuiltClass ? ... :
+ * C`) cannot be inferred from that position at all, so an overload with this as a plain parameter
+ * type is the only form that actually sees the real argument.
+ *
+ * `route_rest` uses its `viewSetClass` argument only for the `declares` on it (see the function
+ * body - the class itself is never `new`'d), then builds a bare `RestProxyImpl` and hands it back
+ * cast to `M`. Pass a factory-built class and this still type-checks without the overload below -
+ * `M` is usually inferred as `InstanceType<typeof ItemApi>` - but the object it returns is not an
+ * `ItemApi`, so any custom method the factory-built class added is `undefined` at runtime despite
+ * compiling. `declares` is required here, not optional: a hand-written class
+ * (`class ItemViewSet extends RestProxyImpl<...> {}`) may have no `declares` at all, or one that is
+ * a plain array rather than carrying `FACTORY_BUILT`, and either must fall through to the real
+ * overload below rather than match this one.
+ */
+declare type FactoryBuiltClass = (abstract new (...args: any[]) => any) & {
+    declares: {
+        readonly [FACTORY_BUILT]: any;
+    };
+};
+
+/**
+ * The shape a factory-built class's constructor has, purely to give `route_muxws` an overload that
+ * rejects it - see rest-proxy.ts's `FactoryBuiltClass` for why this has to be a plain overload
+ * parameter rather than a type parameter conditioned on the argument.
+ */
+declare type FactoryBuiltClass_2 = (abstract new (...args: any[]) => any) & {
+    declares: {
+        readonly [FACTORY_BUILT]: any;
+    };
+};
+
+/**
+ * Brands a factory-built class's `declares` so a subclass restating it fails on one flat "missing
+ * property" line naming `declares` itself, rather than TypeScript recursing into which method each
+ * mixin in the plain, unbranded replacement array is missing relative to the original. A record
+ * type wrapping `D` behind the phantom key, not `D & {brand}`: an intersection would still expose
+ * `D`'s own array shape to the comparison and recurse into it exactly as before; a plain array
+ * literal has no property at all under this key, so the mismatch stops at the top. Erased at
+ * runtime - `bindViewSet` casts through `unknown`, so the actual `static declares` stays a plain
+ * array, and every internal reader (rest-proxy.ts, muxws-proxy.ts, proxy-base.ts's
+ * `declaredActions`) already reads it through its own cast rather than this type.
+ *
+ * `FACTORY_BUILT` lives in proxy-base.ts, not here, so `route_rest`/`route_muxws` can check for the
+ * same brand without importing from this module - see proxy-base.ts's doc comment on the symbol.
+ */
+declare type FactoryDeclares<D extends readonly ViewSetMixinClass[]> = {
+    readonly [FACTORY_BUILT]: D;
+};
+
+export declare type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+declare type KeyType_2 = string | number;
+export { KeyType_2 as KeyType }
+
+export declare interface ListMixin<T> {
+    list(params?: ListParams): Promise<T[]>;
+}
+
+export declare class ListMixin<T> {
+    static readonly actions: readonly string[];
+}
+
+/** Query parameters a list call accepts. `sort` is 'column:asc,other:desc'; the rest are filters. */
+export declare interface ListParams {
+    sort?: string;
+    [key: string]: string | number | boolean | null | undefined | Array<string | number>;
+}
+
+/**
+ * FE counterpart of BE mixins.py — the mixins a ViewSet declaration is composed of.
+ *
+ * Each mixin is an interface merged into a class of the same name. The interface names the actions
+ * and their signatures; the class carries the `actions` list that the schema check reads at
+ * runtime. Both halves are needed because neither alone can do the job: a TypeScript `implements`
+ * clause is erased before anything runs, and a runtime list of strings says nothing about types.
+ *
+ *   class ItemViewSet extends restViewSet<Item>()('id', [ReadOnlyViewSetMixin, LookupMixin]) {}
+ *
+ * The list is written once, as values. `restViewSet` reads the action names off the mixins'
+ * instance types to build the ViewSet's public surface, and hands the same list to the proxy so
+ * that the schema check can compare it against the BE.
+ *
+ * The members are methods rather than properties, and are reached through an intersection rather
+ * than a `Pick<>` of a lookup table: a mapped type re-emits a method as a function-valued property,
+ * and a subclass may then not override an action with a method (TS2425). Overriding one to add
+ * caching or reshape parameters works on a hand-written proxy subclass today, and must keep
+ * working here.
+ *
+ * A composite mixin restates nothing: its interface extends the leaves its `actions` spread names,
+ * so each action's signature exists in exactly one place.
+ *
+ * The methods have no implementation anywhere in this file. The implementation is one HTTP call in
+ * ViewSetProxyBase, and a mixin carrying its own would be a second copy of it.
+ */
+export declare interface LookupItem {
+    group: unknown;
+    pk: unknown;
+    title: string;
+    icon: string | null;
+}
+
+export declare interface LookupMixin {
+    lookup(): Promise<LookupItem[]>;
+}
+
+export declare class LookupMixin {
+    static readonly actions: readonly string[];
+}
+
+export declare interface MuxwsPeerLike {
+    open(payload?: unknown, options?: {
+        headers?: Record<string, unknown>;
+        end?: boolean;
+    }): MuxwsStreamLike;
+}
+
+/**
+ * Where the peer comes from. A bare peer is the simple case; a function is for the common shape
+ * where the proxy is constructed at module scope but `connect()` has not resolved yet. The
+ * function is called once and its result cached — a muxws Peer survives its own reconnects, so
+ * there is nothing to re-resolve afterwards.
+ */
+export declare type MuxwsPeerSource = MuxwsPeerLike | (() => MuxwsPeerLike | Promise<MuxwsPeerLike>);
+
+export declare type MuxwsProxy<M> = M;
+
+export declare class MuxwsProxyImpl<K extends KeyType_2, T, PK extends keyof T> extends ViewSetProxyBase<K, T, PK> {
+    private readonly peerSource;
+    private readonly timeoutMs?;
+    private readonly headers;
+    private peerPromise?;
+    constructor(options: MuxwsProxyOptions);
+    private peer;
+    protected request<R>(method: HttpMethod, path: string, options?: RequestOptions): Promise<R>;
+}
+
+export declare interface MuxwsProxyOptions extends ProxyBaseOptions {
+    peer: MuxwsPeerSource;
+    /** Per-request timeout in milliseconds. muxws resets the stream with TIMEOUT when it expires. */
+    timeoutMs?: number;
+    /**
+     * Headers added to every request this proxy makes. The WebSocket handshake already carries
+     * whatever identified the session and the server treats that as the baseline; these override it
+     * for this proxy's calls. There is no per-call header: `RequestOptions` is `{ query, body }`.
+     */
+    headers?: Record<string, string>;
+}
+
+/**
+ * The bits of a muxws Peer this proxy uses. Typed structurally rather than by importing the muxws
+ * types, so that `muxws` stays an optional dependency: an application that only uses route_rest
+ * should not have to install it.
+ */
+export declare interface MuxwsStreamLike {
+    result(options?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    readonly replyHeadersArrived: Promise<void>;
+    readonly replyHeaders: Record<string, unknown> | null | undefined;
+}
+
+/** A muxws ViewSet base class. See `restViewSet` for why the call is curried. */
+export declare function muxwsViewSet<T>(): <PK extends PkFieldName<T> & keyof T, D extends readonly ViewSetMixinClass[]>(pkFieldName: PK, declares: D) => ViewSetClass<T, PK, D, MuxwsProxyOptions>;
+
+export declare interface PageParams extends ListParams {
+    offset?: number;
+    limit?: number;
+}
+
+/**
+ * One page, mirroring the BE PaginatedList.
+ *
+ * `count` is null when the backend could not know it without draining a lazy source. `hasMore` and
+ * `hasPrevious` are stated rather than inferred — a client that guesses from a null gets the guess
+ * wrong exactly at the boundary where it matters.
+ */
+export declare interface PaginatedList<T> {
+    results: T[];
+    offset: number;
+    limit: number | null;
+    count: number | null;
+    hasMore: boolean;
+    hasPrevious: boolean;
+}
+
+/**
+ * FE counterpart of the BE PaginatedListMixin. `GET {basePath}` is one endpoint answering in the
+ * shape the BE viewset declared as its default; this client sends no X-List-Shape header, so a
+ * ViewSet declares the mixin matching that default rather than one per shape it might want.
+ */
+export declare interface PaginatedListMixin<T> {
+    listPage(params?: PageParams): Promise<PaginatedList<T>>;
+}
+
+export declare class PaginatedListMixin<T> {
+    static readonly actions: readonly string[];
+}
+
+/** The fields of `T` that could be a primary key. */
+export declare type PkFieldName<T> = Extract<{
+    [F in keyof T]-?: NonNullable<T[F]> extends KeyType_2 ? F : never;
+}[keyof T], string>;
+
+declare type PkType<T, PK extends keyof T> = NonNullable<T[PK]> & KeyType_2;
+
+export declare interface ProxyBaseOptions {
+    /** Base path to the resource, e.g. '/items'. */
+    basePath: string;
+    /** Name of the PK field on the model, e.g. 'id'. */
+    pkFieldName: string;
+    /** Set false to skip the startup schema check (it is advisory and costs one request). */
+    validateSchema?: boolean;
+    /**
+     * The mixins the ViewSet declares, for the `route_rest` / `route_muxws` path: those build a bare
+     * proxy and use the ViewSet class only for typing, so a `static declares` on it would otherwise
+     * never reach the object being checked.
+     */
+    declares?: readonly ViewSetMixinDeclaration[];
+}
+
+/** Query values; an array becomes a repeated key, which is how FastAPI binds `list[str]`. */
+export declare type QueryParams = Record<string, string | number | boolean | null | undefined | Array<string | number>>;
+
+export declare interface ReadOnlyViewSetMixin<K extends KeyType_2, T> extends ListMixin<T>, RetrieveMixin<K, T> {
+}
+
+export declare class ReadOnlyViewSetMixin<K extends KeyType_2, T> extends ListMixin<T> {
+    static readonly actions: readonly string[];
+}
+
+export declare interface RequestOptions {
+    query?: QueryParams;
+    body?: unknown;
+}
+
+/**
+ * The REST proxy type is simply the mixin interface `M` the caller declares.
+ * Because TypeScript cannot inspect Python class hierarchies at runtime, the
+ * caller provides the explicit type via the generic parameter `M` (see route_rest).
+ */
+export declare type RestProxy<M> = M;
+
+export declare class RestProxyImpl<K extends KeyType_2, T, PK extends keyof T> extends ViewSetProxyBase<K, T, PK> {
+    protected readonly http: AxiosInstance;
+    constructor(options: RestProxyOptions);
+    /**
+     * Dispatches to axios' per-verb methods rather than to `http.request()`, deliberately. Those
+     * are the calls this proxy has always made, and they are what application interceptors and test
+     * doubles are written against — routing everything through `request()` would be invisible on
+     * the wire but would break every one of them.
+     *
+     * axios throws its own AxiosError on a non-2xx, which already carries `response.status` — the
+     * shape ViewSetRequestError mirrors for the muxws side. Nothing to translate here.
+     */
+    protected request<R>(method: HttpMethod, path: string, options?: RequestOptions): Promise<R>;
+}
+
+export declare interface RestProxyOptions extends ProxyBaseOptions {
+    /** Optional: existing axios instance. Defaults to the global axios. */
+    axiosInstance?: AxiosInstance;
+}
+
+/**
+ * A REST ViewSet base class.
+ *
+ * The empty `()` is not decoration: TypeScript has no partial type-argument inference, so the model
+ * cannot be given explicitly while the pk field and the mixin list are inferred from arguments in
+ * the same call (TS2558). Currying is the only way to have both.
+ */
+export declare function restViewSet<T>(): <PK extends PkFieldName<T> & keyof T, D extends readonly ViewSetMixinClass[]>(pkFieldName: PK, declares: D) => ViewSetClass<T, PK, D, RestProxyOptions>;
+
+export declare interface RetrieveMixin<K extends KeyType_2, T> {
+    retrieve(pk: K): Promise<T>;
+}
+
+export declare class RetrieveMixin<K extends KeyType_2, T> {
+    static readonly actions: readonly string[];
+}
+
+export declare function route_muxws<M = never>(viewSetClass: FactoryBuiltClass_2, options: MuxwsProxyOptions): typeof FACTORY_BUILT_REJECTION_2;
+
+/**
+ * Registers a muxws proxy for the given ViewSet class. The mirror of route_rest, and it takes the
+ * same generic parameter for the same reason: TypeScript cannot inspect the Python class.
+ */
+export declare function route_muxws<M>(viewSetClass: ViewSetClass_3, options: MuxwsProxyOptions): MuxwsProxy<M>;
+
+/**
+ * Registers a REST proxy for the given ViewSet class.
+ *
+ * The generic parameter `M` determines which mixin interfaces are available —
+ * typically the ViewSet type (or a union of mixin interfaces).
+ *
+ * @example
+ * ```ts
+ * import type { BulkViewSetMixin, LookupMixin } from './mixins';
+ *
+ * interface Item { id: number; name: string }
+ *
+ * // with separate arguments (recommended)
+ * const restItems = route_rest<BulkViewSetMixin<number, Item> & LookupMixin>(
+ *   ItemViewSet, '/items', 'id',
+ * );
+ *
+ * // or with an options object
+ * const restItems2 = route_rest<BulkViewSetMixin<number, Item> & LookupMixin>(
+ *   ItemViewSet, { basePath: '/items', pkFieldName: 'id' },
+ * );
+ *
+ * const items = await restItems.list();
+ * const item  = await restItems.retrieve(1);
+ * ```
+ */
+export declare function route_rest<M = never>(viewSetClass: FactoryBuiltClass, basePath: string, pkFieldName: string, axiosInstance?: AxiosInstance): typeof FACTORY_BUILT_REJECTION;
+
+export declare function route_rest<M = never>(viewSetClass: FactoryBuiltClass, options: RestProxyOptions): typeof FACTORY_BUILT_REJECTION;
+
+export declare function route_rest<M>(_viewSetClass: ViewSetClass_2, basePath: string, pkFieldName: string, axiosInstance?: AxiosInstance): RestProxy<M>;
+
+export declare function route_rest<M>(_viewSetClass: ViewSetClass_2, options: RestProxyOptions): RestProxy<M>;
+
+export declare const translatableStrings: {
+    not_found: string;
+    session_expired: string;
+    not_authorized: string;
+    rate_limited: string;
+    unsupported_list_shape: string;
+    cursor_unreadable: string;
+    cursor_missing_position: string;
+    cursor_stale: string;
+    cursor_missing_keys: string;
+    cursor_value_mismatch: string;
+};
+
+/**
+ * A translated, interpolated message for a failed request - `body.detail` unchanged when
+ * `detail_code` is absent (the server has not registered the handler, or this is a view's own
+ * plain-string error) or names a code this table does not (yet) cover.
+ */
+export declare function translateApiError(body: ApiErrorBody): string;
+
+export declare const translateStrings: (cb: TranslateStringsCallback<    {
+not_found: string;
+session_expired: string;
+not_authorized: string;
+rate_limited: string;
+unsupported_list_shape: string;
+cursor_unreadable: string;
+cursor_missing_position: string;
+cursor_stale: string;
+cursor_missing_keys: string;
+cursor_value_mismatch: string;
+}>) => void;
+
+export declare interface UpdateMixin<K extends KeyType_2, T> {
+    update(pk: K, data: T): Promise<T>;
+    partialUpdate(pk: K, data: Partial<T>): Promise<T>;
+}
+
+export declare class UpdateMixin<K extends KeyType_2, T> {
+    static readonly actions: readonly string[];
+}
+
+/**
+ * What the factory hands back: a class to extend.
+ *
+ * A `declares` list naming no action — `[]`, or one annotated `ViewSetMixinClass[]`, which erases
+ * which mixins are in it — would otherwise produce a ViewSet with no actions and no complaint.
+ * TS2507 prints the type it was given, so the type is the sentence.
+ *
+ * `pkFieldName: PK` is added on top of `ViewSetInternals` explicitly: the constructed instance's
+ * real runtime type is `ProxyBaseOptions`'s `ViewSetProxyBase`, which already carries the public
+ * `pkFieldName`, but `ViewSetInternals` is deliberately narrow (see its own doc comment), so this
+ * type would otherwise hide a field that is genuinely there. Typed as the literal `PK` rather than
+ * `string`, since the factory already knows exactly which field it is.
+ */
+export declare type ViewSetClass<T, PK extends keyof T, D extends readonly ViewSetMixinClass[], O extends ProxyBaseOptions> = [
+ActionsOf<D[number]>
+] extends [never] ? 'declares must name at least one action: pass the mixin classes themselves, unannotated' : {
+    new (options: Omit<O, 'pkFieldName' | 'declares'>): ViewSetInternals & ActionSurface<PkType<T, PK>, T, PK, ActionsOf<D[number]>> & {
+        readonly pkFieldName: PK;
+    };
+    readonly declares: FactoryDeclares<D>;
+};
+
+/** ViewSet class constructor (for type-level introspection only). */
+declare type ViewSetClass_2 = abstract new (...args: any[]) => any;
+
+declare type ViewSetClass_3 = abstract new (...args: any[]) => any;
+
+/**
+ * What a ViewSet's own methods may reach - everything a custom endpoint needs, and nothing a caller
+ * does.
+ *
+ * A real base class rather than a type, because `protected` is checked nominally: a subclass body
+ * reaches `request()` only if it genuinely descends from the class that declared it. The ViewSet
+ * factory hands back a class typed as this plus the declared actions, which is how a factory-built
+ * ViewSet ends up with a narrow public surface and a usable private one.
+ */
+export declare abstract class ViewSetInternals {
+    protected readonly basePath: string;
+    protected constructor(basePath: string);
+    /**
+     * Sends one request and returns the decoded response body.
+     *
+     * `path` is relative to `basePath` — '' for the collection, '/1' for a record, '/bulk', and so
+     * on. Implementations must throw on a status of 400 or above, with `response.status` readable on
+     * the thrown value. Below 400 the two differ, on a band a caller rarely sees: the muxws proxy
+     * returns the body for any 3xx, while the REST proxy follows a redirect it can follow and rejects
+     * whatever axios' default `validateStatus` then leaves outside 200-299.
+     *
+     * Concrete here, and never reached: ViewSetProxyBase re-declares it abstract, which is where a
+     * transport is actually held to implementing it. It cannot be abstract at this level because
+     * TypeScript propagates an abstract member through a constructor type, and the factory hands one
+     * back - every ViewSet a consumer wrote would then fail TS2515 for a method the transport
+     * underneath it has always implemented.
+     */
+    protected request<R>(method: HttpMethod, path: string, options?: RequestOptions): Promise<R>;
+}
+
+export declare interface ViewSetMixin<K extends KeyType_2, T, PK extends keyof T> extends ReadOnlyViewSetMixin<K, T>, CreateMixin<T, PK>, UpdateMixin<K, T>, DestroyMixin<K> {
+}
+
+export declare class ViewSetMixin<K extends KeyType_2, T, PK extends keyof T> extends ReadOnlyViewSetMixin<K, T> {
+    static readonly actions: readonly string[];
+}
+
+/** A mixin class: the runtime `actions` the schema check reads, and the type naming those actions. */
+export declare type ViewSetMixinClass = ViewSetMixinDeclaration & (abstract new (...args: any[]) => object);
+
+/** One entry of a ViewSet's `static declares` list: a mixin naming the actions it contributes. */
+export declare interface ViewSetMixinDeclaration {
+    readonly actions: readonly string[];
+}
+
+export declare abstract class ViewSetProxyBase<K extends KeyType_2, T, PK extends keyof T> extends ViewSetInternals implements BulkViewSetMixin<K, T, PK>, CursorListMixin<T>, PaginatedListMixin<T>, LookupMixin {
+    /**
+     * The mixins this ViewSet is composed of — the FE counterpart of a BE viewset's base classes.
+     *
+     *     class ItemViewSet extends RestProxyImpl<number, Item, 'id'> {
+     *       static declares = [ReadOnlyViewSetMixin, LookupMixin];
+     *     }
+     *
+     * Left undefined, the ViewSet is not checked against the BE schema at all. That is deliberate:
+     * a ViewSet that never said what it has cannot be caught contradicting itself, and guessing on
+     * its behalf is what made the check report actions nobody ever claimed.
+     */
+    static declares?: readonly ViewSetMixinDeclaration[];
+    /**
+     * Which field of `T` is the primary key, e.g. `'id'`. `public`, not `protected`: nothing in this
+     * library reads it back, but a generic caller holding a ViewSet instance - a grid or table
+     * component needing to know which column identifies a row - has no other way to ask.
+     */
+    readonly pkFieldName: string;
+    private readonly schemaValidationEnabled;
+    private readonly declaredMixins?;
+    protected constructor(options: ProxyBaseOptions);
+    /**
+     * Starts the advisory schema check. Subclasses must call this as the *last* statement of their
+     * constructor, never the base constructor itself: `request()` reads fields the subclass has not
+     * assigned yet while `super()` is still running, and since the check swallows its own errors,
+     * doing it here would leave it permanently and silently dead.
+     */
+    protected initSchemaValidation(): void;
+    /** Abstract here, where a transport is actually held to it. See ViewSetInternals.request. */
+    protected abstract request<R>(method: HttpMethod, path: string, options?: RequestOptions): Promise<R>;
+    /**
+     * Fetches the BE schema and compares it against what this ViewSet declared.
+     * Logs a console warning for any mismatch found.
+     *
+     * The comparison is against `static declares`, not against which methods exist on the object:
+     * every action is implemented unconditionally on this class, so `typeof this[action]` is true for
+     * every ViewSet and answers a question nobody asked. `declares` is the only place the FE says
+     * anything a BE viewset could disagree with.
+     *
+     * Non-critical: errors during fetch or parsing are silently ignored. Note that the schema is
+     * fetched over this proxy's own transport, so a muxws proxy validates against the muxws
+     * endpoint set and a REST proxy against the REST one — which is the point, since the two are
+     * allowed to differ.
+     */
+    private validateAgainstSchema;
+    create(data: Omit<T, PK>): Promise<T>;
+    bulkCreate(data: Omit<T, PK>[]): Promise<T[]>;
+    list(params?: ListParams): Promise<T[]>;
+    /**
+     * Fetches one page. Only meaningful against a viewset built on the BE PaginatedListMixin — a
+     * plain ListMixin ignores offset/limit and answers with the whole collection, which would not
+     * match this return type.
+     *
+     * The BE speaks snake_case (`has_more`); the rest of this client speaks whatever the model
+     * declares, so only the envelope's own fields are renamed here. The records inside are passed
+     * through untouched.
+     */
+    /**
+     * Fetches one cursor page. Only meaningful against a viewset built on the BE CursorListMixin.
+     *
+     * Follow `next` to walk forward. Unlike offset paging, a row inserted or removed behind you
+     * cannot make the next page repeat or skip anything.
+     */
+    listCursor(params?: CursorParams): Promise<CursorPage<T>>;
+    listPage(params?: PageParams): Promise<PaginatedList<T>>;
+    retrieve(pk: K): Promise<T>;
+    update(pk: K, data: T): Promise<T>;
+    partialUpdate(pk: K, data: Partial<T>): Promise<T>;
+    bulkUpdate(records: Record<K, T>): Promise<T[]>;
+    bulkPartialUpdate(records: Record<K, Partial<T>>): Promise<T[]>;
+    destroy(pk: K): Promise<DestroyReturnData>;
+    bulkDestroy(pks: K[]): Promise<DestroyReturnData[]>;
+    lookup(): Promise<LookupItem[]>;
+}
+
+/**
+ * What a failed call throws over muxws, where there is no axios to raise anything.
+ *
+ * The shape mirrors `AxiosError` — `error.response.status`, `error.response.data` and
+ * `error.response.headers` — so a caller reads the same fields whichever transport the ViewSet
+ * speaks. Over HTTP axios raises its own error, already in that shape, and it is passed through
+ * untouched.
+ *
+ * `response` is always set here, unlike `AxiosError.response`, which is absent when the request
+ * never reached a reply.
+ */
+export declare class ViewSetRequestError extends Error {
+    readonly response: {
+        status: number;
+        data: unknown;
+        headers: Record<string, string>;
+    };
+    constructor(status: number, data: unknown, headers?: Record<string, string>);
+}
+
+export { }