@vexcms/core 0.0.20 → 0.1.0-alpha.2

package/dist/api/types.d.ts

@@ -0,0 +1,525 @@
+import type { UseSuspenseQueryOptions } from "@tanstack/react-query";
+import type { FunctionReference, GenericDataModel, GenericMutationCtx, GenericQueryCtx, PaginationOptions as ConvexPaginationOptions, PaginationResult as ConvexPaginationResult } from "convex/server";
+import { ADMIN_FIELDS, CheckboxFieldType, DateFieldType, NumberFieldType, SelectFieldType, TextFieldType, type AdminFieldType } from "../fields";
+import type { CollectionsFieldTypeMap, CollectionSlug, CustomActionsBySlug, DocumentBySlug } from "../types/generated";
+import { VexDocument } from "./convex";
+import { VexConfig } from "../config";
+import { QueryAction, DraftAction, CrudAction } from "../access";
+/**
+ * Forces TypeScript to eagerly evaluate a mapped/conditional type into a
+ * concrete object shape rather than displaying the opaque alias. Without this,
+ * hover would show `Populated<"posts", { parent: true }>` instead of the
+ * expanded `{ _id: ...; parent: Post[]; ... }` form.
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Per-call access options. Server-side only — NEVER accept these from a registered
+ * Convex function's `args`: an action no role declares falls through to
+ * `defaultPermissionMode` (default `allow`), so a client-chosen action reads anything.
+ *
+ * @typeParam A - Action union accepted for this call shape.
+ */
+export interface AccessCallOptions<A extends string = string> {
+    /**
+     * Permission action to check instead of the function's natural verb. Use for custom
+     * actions (`listFeatured`) and for draft reads (`readDrafts`).
+     *
+     * @defaultValue the function's natural verb (`read`, `create`, `update`, `delete`)
+     */
+    action?: A;
+    /**
+     * Skip RBAC for this call entirely. Also skips `getAuth`, so a public read costs no
+     * session lookup.
+     *
+     * @defaultValue false
+     */
+    bypass?: boolean;
+}
+/**
+ * Actions a query-shaped call may check. `(string & {})` keeps literal autocomplete.
+ *
+ * NOT `| DraftAction`: `QueryAction` already carries `readDrafts` (the only
+ * query-shaped draft verb), so adding the full draft union would offer
+ * `saveDraft`/`publish`/`unpublish` - mutation verbs - in every query position.
+ */
+export type QueryCallAction = QueryAction | (string & {});
+/** Actions a mutation-shaped call may check. The draft verbs minus `readDrafts`. */
+export type MutationCallAction = CrudAction | Exclude<DraftAction, QueryAction> | (string & {});
+/** Custom actions of one kind declared for slug `S` in the generated registry. @internal */
+type CustomCallActionsFor<S extends string, K extends "query" | "mutation"> = S extends keyof CustomActionsBySlug ? CustomActionsBySlug[S] extends Record<K, infer A extends string> ? A : never : never;
+/**
+ * Actions a query-shaped call on collection `S` may check.
+ *
+ * Pre-generation the registry is `{}`, so this collapses to {@link QueryCallAction} —
+ * arbitrary strings stay accepted, which is what lets core's own tests exercise custom
+ * actions against an unaugmented registry. Post-generation the `(string & {})` arm is
+ * REPLACED by the slug's declared union: a custom verb autocompletes exactly where it
+ * is declared and is a compile error everywhere else.
+ */
+export type QueryCallActionFor<S extends string> = [keyof CustomActionsBySlug] extends [never] ? QueryCallAction : QueryAction | CustomCallActionsFor<S, "query">;
+/** Mutation-shaped counterpart of {@link QueryCallActionFor}. */
+export type MutationCallActionFor<S extends string> = [keyof CustomActionsBySlug] extends [never] ? MutationCallAction : CrudAction | Exclude<DraftAction, QueryAction> | CustomCallActionsFor<S, "mutation">;
+/**
+ * Base shape for client-side args of a `vex.*` query function.
+ *
+ * Carries the `ctx?: never` discriminator (forbids passing a Convex query
+ * context) and the `populate` field, since every query function that returns
+ * documents supports relationship population (the only outlier is `count`,
+ * which returns a number and overrides `populate?: never`).
+ *
+ * Function-specific args interfaces extend this and add their own per-function
+ * fields. `limit` stays per-function because it doesn't apply to single-doc
+ * queries (`get`) or scalar queries (`count`).
+ *
+ * @typeParam TCollectionSlug - The collection slug; used to narrow `populate` keys via
+ *   `RelationshipKeysOf<TCollectionSlug>`. Defaults to the full `CollectionSlug` union.
+ * @typeParam TPopulate - The populate object. Defaults to
+ *   `Record<string, never>` (no relationships populated).
+ *
+ * @example Inheritance pattern
+ * ```ts
+ * // find — adds slug + limit; populate inherited
+ * interface FindClientArgs<TCollectionSlug, TPopulate>
+ *   extends GenericQueryClientParams<TCollectionSlug, TPopulate> {
+ *   slug: TCollectionSlug;
+ *   limit?: number;
+ * }
+ *
+ * // get — adds id; populate inherited; no limit (single-doc)
+ * interface GetClientArgs<TCollectionSlug, TPopulate>
+ *   extends GenericQueryClientParams<TCollectionSlug, TPopulate> {
+ *   id: GenericId<TCollectionSlug>;
+ * }
+ *
+ * // search — adds slug + query + index fields + limit; populate inherited
+ * interface SearchClientArgs<TCollectionSlug, TPopulate>
+ *   extends GenericQueryClientParams<TCollectionSlug, TPopulate> {
+ *   slug: TCollectionSlug;
+ *   query: string;
+ *   searchIndexName: string;
+ *   searchField: string;
+ *   limit?: number;
+ * }
+ *
+ * // count — returns a number, has no docs to populate; overrides populate
+ * interface CountClientArgs<TCollectionSlug>
+ *   extends GenericQueryClientParams<TCollectionSlug> {
+ *   slug: TCollectionSlug;
+ *   populate?: never;
+ * }
+ * ```
+ */
+export interface GenericQueryClientParams<TCollectionSlug extends CollectionSlug = CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug> = Record<string, never>, D extends number = number> {
+    /** Discriminator: client args MUST NOT supply `auth`. */
+    auth?: never;
+    /** Discriminator: client args MUST NOT supply `ctx`. */
+    ctx?: never;
+    /** Recursive populate object, type-narrowed against `RelationshipKeysOf<TCollectionSlug>`. */
+    populate?: TPopulate;
+    /**
+     * Auto-populate all relationship fields to this many levels.
+     *
+     * Inferred as the literal `D` so a wrapper that threads `D` through to its
+     * return type narrows accordingly (`depth: 2` → depth-populated doc). A
+     * non-literal `number` degrades to `VexDocument` via {@link DepthPopulated}'s
+     * guard. `D` defaults to `number`, so wrappers that do not thread it keep the
+     * plain passthrough they had before.
+     *
+     * Use `populate` for documented consumer code; `depth` is internal.
+     */
+    depth?: D;
+    /**
+     * When `true`, the wrapper passes convexQuery's `"skip"` sentinel instead of
+     * args, so the query is not issued. Use for conditional queries (e.g. an id
+     * that is not known yet) without violating the Rules of Hooks.
+     */
+    skip?: boolean;
+}
+/**
+ * Base shape for server-side args of a `vex.*` query function.
+ *
+ * Carries `ctx`, `populate`, `depth`, and `config`. `populate` and `depth`
+ * are mutually exclusive — TypeScript enforces this via conditional constraints:
+ * `populate` becomes `never` when `D ≠ 0`; `depth` and `config` become `never`
+ * when `TPopulate` is non-empty. Passing both is a compile error at the call site.
+ *
+ * All three query functions (`find`, `get`, `search`) extend this base and
+ * inherit these constraints without re-declaring them.
+ *
+ * @typeParam DataModel - The Convex data model (inferred from `ctx`).
+ * @typeParam TCollectionSlug - The collection slug.
+ * @typeParam TPopulate - The populate object.
+ * @typeParam D - Depth literal (0 = no depth, default). Captured as a literal
+ *   via `const D extends number = 0` on the implementing function.
+ */
+export interface GenericQueryServerParams<DataModel extends GenericDataModel = GenericDataModel, TCollectionSlug extends CollectionSlug = CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug> = Record<string, never>, D extends number = 0> {
+    /** Per-call access overrides. @see {@link AccessCallOptions} */
+    access?: AccessCallOptions<QueryCallActionFor<TCollectionSlug>>;
+    /** The auth config of the current user making the query.
+     * @example
+     * ```ts
+     * { user: {...}, organization: {...} }
+     * ```
+     */
+    auth?: VexApiAuth;
+    /** Discriminator: server args MUST supply a Convex query context. */
+    ctx: GenericQueryCtx<DataModel>;
+    /**
+     * Recursive populate object, type-narrowed against `RelationshipKeysOf<TCollectionSlug>`.
+     * Mutually exclusive with `depth` — becomes `never` when `D ≠ 0`.
+     */
+    populate?: [D] extends [0] ? TPopulate : never;
+    /**
+     * Auto-populate all relationship fields to this many levels.
+     * Becomes `never` when `TPopulate` is non-empty. Use `populate` for
+     * consumer-facing code; this is an internal escape hatch for `CollectionListView`.
+     */
+    depth?: [TPopulate] extends [Record<string, never>] ? D : never;
+    /**
+     * The resolved `VexConfig`. Required alongside `depth`; passed
+     * from the `queryApi` factory closure so the Convex handler has schema info.
+     */
+    config?: [TPopulate] extends [Record<string, never>] ? VexConfig : never;
+}
+/**
+ * Base shape for client-side args of a `vex.*` mutation function. Mirrors
+ * {@link GenericQueryClientParams} but exists separately so query-only
+ * options (`populate`) don't leak into the mutation base, and so future
+ * mutation-only shared fields have a clear home.
+ */
+export interface GenericMutationClientParams {
+    /** Discriminator: client args MUST NOT supply `auth`. */
+    auth?: never;
+    /** Discriminator: client args MUST NOT supply `ctx`. */
+    ctx?: never;
+}
+/**
+ * Base shape for server-side args of a `vex.*` mutation function. Used inside
+ * custom Convex mutation handlers; receives the Convex mutation context
+ * (which is a superset of `GenericQueryCtx` — read+write vs. read-only).
+ *
+ * @typeParam DataModel - The Convex data model (inferred from `ctx`).
+ */
+export interface GenericMutationServerParams<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug = CollectionSlug> {
+    /** Per-call access overrides. @see {@link AccessCallOptions} */
+    access?: AccessCallOptions<MutationCallActionFor<TCollectionSlug>>;
+    /** The auth config of the current user making the query.
+     * @example
+     * ```ts
+     * { user: {...}, organization: {...} }
+     * ```
+     */
+    auth?: VexApiAuth;
+    /** Discriminator: server args MUST supply a Convex mutation context. */
+    ctx: GenericMutationCtx<DataModel>;
+    /**
+     * The resolved `VexConfig`. Required for rbac access control during operations
+     * from the `queryApi` factory closure so the Convex handler has schema info.
+     */
+    config: VexConfig;
+}
+/**
+ * Returns the union of field keys on `TCollectionSlug` that have field type `TType`.
+ *
+ * Reads the `CollectionsFieldTypeMap` property on the augmented `GeneratedVexTypes`
+ * registry — populated by `vex generate` from the user's collection configs.
+ * Returns `never` when the slug has no fields of that type, or when the
+ * registry hasn't been augmented yet (fresh project).
+ *
+ * @typeParam TCollectionSlug - The collection slug.
+ * @typeParam TType - The field type literal (e.g., `"text"`, `"relationship"`).
+ *
+ * @example
+ * ```ts
+ * type AuthorRelationships = FieldKeysOfType<"posts", "relationship">;
+ * // → "author" | "category"
+ */
+export type FieldKeysOfType<TCollectionSlug extends CollectionSlug, TType extends AdminFieldType> = TCollectionSlug extends keyof CollectionsFieldTypeMap ? TType extends keyof CollectionsFieldTypeMap[TCollectionSlug] ? CollectionsFieldTypeMap[TCollectionSlug][TType] & string : never : never;
+/** Field keys on `TCollectionSlug` that are relationship fields. */
+export type RelationshipKeysOf<TCollectionSlug extends CollectionSlug> = FieldKeysOfType<TCollectionSlug, typeof ADMIN_FIELDS.relationship.type>;
+/** Field keys on `TCollectionSlug` that are text fields. */
+export type TextKeysOf<TCollectionSlug extends CollectionSlug> = FieldKeysOfType<TCollectionSlug, typeof ADMIN_FIELDS.relationship.type>;
+/**
+ * Field keys on `TCollectionSlug` that are sortable in list views (text, number, date,
+ * checkbox, select). Used by future `defaultSort` typing and the data-table
+ * column registry.
+ */
+export type SortableKeysOf<TCollectionSlug extends CollectionSlug> = FieldKeysOfType<TCollectionSlug, TextFieldType | NumberFieldType | DateFieldType | CheckboxFieldType | SelectFieldType>;
+/**
+ * Resolves a relationship field's target slug.
+ *
+ * Reads the *resolved* `RelationshipField.collection.slug` from the
+ * `GeneratedVexTypes` document shape (the relationship field key on a doc
+ * stores the target slug as part of its branded `Id<TargetSlug>` type).
+ * Falls back to `CollectionSlug` if not resolvable.
+ */
+export type RelationshipTargetOf<TCollectionSlug extends CollectionSlug, TKey extends string> = TCollectionSlug extends keyof DocumentBySlug ? TKey extends keyof DocumentBySlug[TCollectionSlug] ? NonNullable<DocumentBySlug[TCollectionSlug][TKey]> extends ReadonlyArray<{
+    __tableName: infer T;
+}> ? T extends CollectionSlug ? T : CollectionSlug : CollectionSlug : CollectionSlug : CollectionSlug;
+/**
+ * Recursive populate options, type-restricted to relationship field keys per
+ * the augmented `CollectionsFieldTypeMap` registry.
+ *
+ * @typeParam TCollectionSlug - The collection slug to narrow relationship keys against.
+ *   Defaults to the full `CollectionSlug` union for internal recursive use.
+ */
+export type PopulateShape<TCollectionSlug extends CollectionSlug = CollectionSlug> = {
+    [K in RelationshipKeysOf<TCollectionSlug>]?: true | {
+        populate: PopulateShape<RelationshipTargetOf<TCollectionSlug, K>>;
+    };
+};
+/**
+ * Result type of a populated query — `Doc<TCollectionSlug>` with each key listed in
+ * `TPopulate` replaced from `Id<TargetSlug>[]` to `Doc<TargetSlug>[]`.
+ * Recurses if the populate value has a nested `populate` field (D12: unbounded
+ * nesting).
+ *
+ * Keys not in `TPopulate` keep their original `Id[]` type. Non-relationship
+ * keys are left untouched.
+ */
+export type Populated<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>> = TCollectionSlug extends keyof DocumentBySlug ? {
+    [K in keyof DocumentBySlug[TCollectionSlug]]: K extends keyof TPopulate ? K extends string ? RelationshipTargetOf<TCollectionSlug, K> extends infer Target ? Target extends CollectionSlug ? Target extends keyof DocumentBySlug ? TPopulate[K] extends {
+        populate: infer NestedPopulate;
+    } ? NestedPopulate extends PopulateShape<Target> ? Populated<Target, NestedPopulate>[] : DocumentBySlug[Target][] : DocumentBySlug[Target][] : DocumentBySlug[TCollectionSlug][K] : DocumentBySlug[TCollectionSlug][K] : DocumentBySlug[TCollectionSlug][K] : DocumentBySlug[TCollectionSlug][K] : DocumentBySlug[TCollectionSlug][K];
+} : never;
+/**
+ * Computes the equivalent `PopulateShape` for automatically populating all
+ * relationship fields on `TCollectionSlug` to `D` levels deep.
+ *
+ * This is the type-level counterpart of `buildDepthPopulate`. The computed
+ * shape is a valid `PopulateShape<TCollectionSlug>` and can be fed directly into
+ * `Populated<TCollectionSlug, DepthPopulate<TCollectionSlug, D>>`.
+ *
+ * **How the counter works:** `_Counter` is a tuple of `0`s whose `length`
+ * tracks how many levels have been descended. At the penultimate level
+ * (`[..._Counter, 0]["length"] extends D`) fields are emitted as `true`
+ * (populate, no further recursion). At intermediate levels they are emitted as
+ * `{ populate: DepthPopulate<Target, D, [..._Counter, 0]> }`.
+ *
+ * **Practical depth limit: 3.** TypeScript instantiation count grows
+ * exponentially with D × relationship-key-count-per-collection. D=1,2,3 is
+ * safe for typical VexCMS schemas; D≥4 may cause noticeable `tsc` slowdown.
+ * Runtime has no limit.
+ *
+ * @typeParam TCollectionSlug - The collection slug to start from.
+ * @typeParam D - The depth as a literal number (1, 2, or 3 recommended).
+ * @typeParam _Counter - Internal tuple counter — callers must not supply this.
+ *
+ * @example Resolved shape for depth 1 on posts with an author relationship
+ * ```ts
+ * // DepthPopulate<"posts", 1> → { author?: true }
+ * // Equivalent to writing `populate: { author: true }` explicitly
+ * ```
+ * @example Resolved shape for depth 2
+ * ```ts
+ * // DepthPopulate<"posts", 2> → { author?: { populate: { team?: true } } }
+ * // Equivalent to `populate: { author: { populate: { team: true } } }`
+ * ```
+ */
+export type DepthPopulate<TCollectionSlug extends CollectionSlug, D extends number, _Counter extends 0[] = []> = _Counter["length"] extends D ? Record<string, never> : [..._Counter, 0]["length"] extends D ? {
+    [K in RelationshipKeysOf<TCollectionSlug>]?: true;
+} : {
+    [K in RelationshipKeysOf<TCollectionSlug>]?: {
+        populate: DepthPopulate<RelationshipTargetOf<TCollectionSlug, K>, D, [..._Counter, 0]>;
+    };
+};
+/**
+ * Return type of `find` / `get` / `search` when `depth` is provided instead
+ * of an explicit `populate` object.
+ *
+ * Delegates to `Populated<TCollectionSlug, DepthPopulate<TCollectionSlug, D>>` — the same type
+ * the explicit populate path produces — so the narrowed shape is identical to
+ * what you would get by writing all relationship keys by hand.
+ *
+ * **Non-literal fallback:** `number extends D` (i.e., `D` is not a literal)
+ * short-circuits to `VexDocument` to avoid evaluating an infinite recursive
+ * type. `depth` is only called internally with literal values (`1`), so this
+ * only fires when depth comes from a non-literal `number` variable.
+ *
+ * **`depth: 0`** (the default) returns raw un-populated docs — identical to
+ * omitting both `depth` and `populate`.
+ *
+ * @typeParam TCollectionSlug - The collection slug.
+ * @typeParam D - The depth literal.
+ */
+export type DepthPopulated<TCollectionSlug extends CollectionSlug, D extends number> = number extends D ? VexDocument : D extends 0 ? TCollectionSlug extends keyof DocumentBySlug ? DocumentBySlug[TCollectionSlug] : never : TCollectionSlug extends keyof DocumentBySlug ? Prettify<Populated<TCollectionSlug, DepthPopulate<TCollectionSlug, D>>> : never;
+/**
+ * Tanstack-query options as produced by `convexQuery` for a non-`"skip"` call,
+ * with the result pinned to `TReturn` instead of the funcRef's baked type.
+ *
+ * Named deliberately: publishing this contract as `ReturnType<typeof
+ * convexQuery>` instantiates the adapter's generics at their constraints and
+ * collapses the query data to `any`.
+ *
+ * @typeParam TArgs - The endpoint's args shape.
+ * @typeParam TReturn - The narrowed return type for this call.
+ */
+export type VexQueryOptions<TArgs extends Record<string, unknown>, TReturn> = Pick<UseSuspenseQueryOptions<TReturn, Error, TReturn, [
+    "convexQuery",
+    FunctionReference<"query", "public", TArgs, TReturn>,
+    TArgs
+]>, "queryKey" | "queryFn" | "staleTime">;
+/**
+ * The per-document element type shared by `get`, `find`, and `search`:
+ *
+ * - No populate + `D = 0` → `DocumentBySlug[TCollectionSlug]` (raw doc).
+ * - No populate + `D > 0` → `DepthPopulated<TCollectionSlug, D>`.
+ * - With populate → `Prettify<Populated<TCollectionSlug, TPopulate>>`.
+ *
+ * Resolves to `never` when the slug is absent from the generated registry
+ * (pre-`vex generate`). Nullability is applied by the per-operation aliases.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @typeParam D - Depth literal (0 = none).
+ */
+export type DocReturnItem<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number> = [TPopulate] extends [Record<string, never>] ? [D] extends [0] ? TCollectionSlug extends keyof DocumentBySlug ? DocumentBySlug[TCollectionSlug] : never : DepthPopulated<TCollectionSlug, D> : TCollectionSlug extends keyof DocumentBySlug ? Prettify<Populated<TCollectionSlug, TPopulate>> : never;
+/**
+ * Return type of `get` — a {@link DocReturnItem}, or `null` when no document
+ * matches the id. Shared by the server function and the client wrapper's query
+ * data so both narrow identically from the collection slug.
+ *
+ * The `[never]` guard keeps the unregistered-slug case as `never` rather than
+ * collapsing it to `null`.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @typeParam D - Depth literal (0 = none).
+ */
+export type GetReturn<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = 0> = [DocReturnItem<TCollectionSlug, TPopulate, D>] extends [never] ? never : DocReturnItem<TCollectionSlug, TPopulate, D> | null;
+/**
+ * Return type of `find` without `paginationOpts` — an array of
+ * {@link DocReturnItem}. Shared by the server function and the client wrapper's
+ * query data so both narrow identically from the collection slug.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @typeParam D - Depth literal (0 = none).
+ */
+export type FindReturn<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = 0> = DocReturnItem<TCollectionSlug, TPopulate, D>[];
+/**
+ * Return type of `find` with `paginationOpts` — a Convex `PaginationResult`
+ * whose `page` entries are {@link DocReturnItem}.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @typeParam D - Depth literal (0 = none).
+ */
+export type FindReturnPaginated<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = 0> = PaginationResult<DocReturnItem<TCollectionSlug, TPopulate, D>>;
+/**
+ * Return type of `search` without `paginationOpts`. Identical in shape to
+ * {@link FindReturn}; kept as a distinct name so each operation's contract can
+ * diverge without a breaking rename.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @typeParam D - Depth literal (0 = none).
+ */
+export type SearchReturn<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = 0> = DocReturnItem<TCollectionSlug, TPopulate, D>[];
+/**
+ * Return type of `search` with `paginationOpts`.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @typeParam D - Depth literal (0 = none).
+ */
+export type SearchReturnPaginated<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = 0> = PaginationResult<DocReturnItem<TCollectionSlug, TPopulate, D>>;
+/**
+ * Pagination options for Convex queries.
+ * Matches Convex's native `paginationOptsValidator` shape.
+ */
+/**
+ * Pagination options for Convex queries.
+ *
+ * Re-exported from `convex/server` for convenience. This is the exact type
+ * that Convex's `.paginate(opts)` API expects.
+ *
+ * @see https://docs.convex.dev/database/pagination
+ */
+export type PaginationOptions = ConvexPaginationOptions & {
+    /**
+     * Whether to include total document count in the response.
+     *
+     * Only runs on the first page (when cursor is null) to avoid wasteful re-counting.
+     * Counts all documents matching the current filters/search query.
+     *
+     * Returns `null` if the count exceeds Convex transaction limits (>32k documents).
+     *
+     * @default false
+     */
+    totalDocs?: boolean;
+};
+/**
+ * Pagination result from Convex query.
+ *
+ * Re-exported from `convex/server`. Returned by queries using `.paginate(opts)`.
+ *
+ * Includes:
+ * - `page: T[]` — Current page of results
+ * - `isDone: boolean` — Whether this is the last page
+ * - `continueCursor: string` — Cursor to fetch next page
+ * - `splitCursor?: string | null` — Cursor to split large pages (optional)
+ * - `pageStatus?: "SplitRecommended" | "SplitRequired" | null` — Indicates when to split (optional)
+ *
+ * @see https://docs.convex.dev/database/pagination
+ */
+export type PaginationResult<T> = ConvexPaginationResult<T> & {
+    totalDocs?: number | null;
+};
+/**
+ * Client-side pagination state.
+ * Tracks cursor stack for forward/backward navigation.
+ */
+export interface PaginationState {
+    /** Current page number (1-based). */
+    currentPage: number;
+    /** Items per page. */
+    pageSize: number;
+    /** Stack of cursors for backward navigation. */
+    cursorStack: (string | null)[];
+    /** Current cursor (top of stack). */
+    cursor: string | null;
+    /** Whether there are more pages after current page. */
+    hasNextPage: boolean;
+    /** Whether there are previous pages. */
+    hasPreviousPage: boolean;
+    /** Total count of items (optional — requires separate count query). */
+    totalCount?: number;
+}
+/**
+ * Selection mode for data tables.
+ */
+export type SelectionMode = "none" | "page" | "all" | "inverse";
+/**
+ * Selection state for bulk actions.
+ */
+export interface SelectionState {
+    /** Set of selected document IDs. */
+    selectedIds: Set<string>;
+    /** Current selection mode. */
+    mode: SelectionMode;
+}
+/**
+ * The resolved caller identity RBAC guards check against. Returned by a
+ * user-supplied `getAuth` callback.
+ *
+ * @see {@link VexApiOptions} for where `getAuth` is configured.
+ */
+export type VexApiAuth = {
+    /**
+     * Passed as `hasPermission`'s `user` — shape is caller-defined. Must include
+     * whatever field `access.userRolesField` names (a role string or string[])
+     * for role resolution to succeed; a user object without it resolves to an
+     * empty role list and denies every check.
+     */
+    user: Record<string, unknown> | null;
+    /**
+     * Passed as `hasPermission`'s `organization`. Shape is caller-defined; omit
+     * when the access config has no `orgCollectionSlug`.
+     */
+    organization?: Record<string, unknown>;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}

package/dist/api/update/client.d.ts

@@ -0,0 +1,53 @@
+import type { GenericId } from "convex/values";
+import type { CollectionSlug } from "../../types/generated";
+import type { GenericMutationClientParams } from "../types";
+/**
+ * Client-side args for {@link update}.
+ *
+ * @example
+ * ```tsx
+ * import { update, type UpdateClientArgs } from "@vexcms/core/client";
+ * import { useMutation } from "@tanstack/react-query";
+ *
+ * // Inside a React component:
+ * const { mutateAsync } = useMutation({ mutationFn: update() });
+ * await mutateAsync({ id: postId, data: { title: "Updated title" } });
+ * ```
+ */
+export interface UpdateClientArgs<TCollectionSlug extends CollectionSlug = CollectionSlug> extends GenericMutationClientParams {
+    /** The collection slug to patch metadata. */
+    collection: TCollectionSlug;
+    /** The document ID to update. */
+    id: GenericId<TCollectionSlug>;
+    /** Partial field values to merge into the document. */
+    data: Record<string, unknown>;
+}
+/**
+ * Returns a `mutationFn` for patching an existing document in a VexCMS collection.
+ *
+ * Wraps `useConvexMutation(vexConvexApi.update)`. Call at the top level of
+ * a React component (obeys the Rules of Hooks); pass the return value as
+ * `mutationFn` to `useMutation`.
+ *
+ * Import from `@vexcms/core/client`. For the server-side version, import
+ * `update` from `@vexcms/core/server`.
+ *
+ * @returns A mutation function compatible with tanstack-query `useMutation`.
+ * @see {@link UpdateClientArgs} for the typed args shape.
+ * @example
+ * ```tsx
+ * import { update } from "@vexcms/core/client";
+ * import { useMutation } from "@tanstack/react-query";
+ *
+ * export function EditTitleButton({ id }: { id: Id<"posts"> }) {
+ *   const { mutateAsync, isPending } = useMutation({ mutationFn: update() });
+ *   return (
+ *     <button onClick={() => mutateAsync({ id, data: { title: "New title" } })}>
+ *       {isPending ? "Saving…" : "Save"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function update(): import("convex/react").ReactMutation<import("convex/server").FunctionReference<"mutation", "public", import("../convex").VexUpdateArgs, void>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/api/update/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/update/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAG5D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB,CAC/B,eAAe,SAAS,cAAc,GAAG,cAAc,CACvD,SAAQ,2BAA2B;IACnC,6CAA6C;IAC7C,UAAU,EAAE,eAAe,CAAC;IAC5B,iCAAiC;IACjC,EAAE,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC;IAC/B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,mJAErB"}

package/dist/api/update/server.d.ts

@@ -0,0 +1,47 @@
+import type { BetterOmit, DocumentByName, Expand, GenericDataModel, TableNamesInDataModel } from "convex/server";
+import type { GenericId } from "convex/values";
+import type { CollectionSlug } from "../../types/generated";
+import type { GenericMutationServerParams } from "../types";
+/**
+ * Server-side args for `update`.
+ *
+ * @typeParam DataModel - The Convex data model (inferred from `ctx`).
+ * @typeParam TCollectionSlug - Collection slug, recovered from the `Id` brand.
+ */
+export interface UpdateServerArgs<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug> extends GenericMutationServerParams<DataModel> {
+    /** The collection slug to patch this document. */
+    collection: TCollectionSlug;
+    /** The document ID to patch. */
+    id: GenericId<TCollectionSlug>;
+    /**
+     * Partial field values to merge into the document. Only the keys present
+     * here are written; unspecified fields are left unchanged. `_id` and
+     * `_creationTime` are excluded — Convex manages them.
+     *
+     * Passed through `v.any()` at the network boundary; CLI codegen validates
+     * the shape against the Convex schema at build time.
+     */
+    data: Partial<Expand<BetterOmit<DocumentByName<DataModel, TableNamesInDataModel<DataModel>>, "_creationTime" | "_id">>>;
+}
+/**
+ * Patches a document by its `Id<TCollectionSlug>`. Only specified fields are updated;
+ * unspecified fields are left unchanged. Server-side only.
+ *
+ * Import from `@vexcms/core/server`.
+ *
+ * @typeParam DataModel - Convex data model (inferred from `args.ctx`).
+ * @typeParam TCollectionSlug - Collection slug.
+ * @param args - `{ ctx, id, data }`. `ctx` must be a mutation context.
+ * @returns Promise resolving to void.
+ * @example
+ * ```ts
+ * import { update } from "@vexcms/core/server";
+ *
+ * export const updatePost = mutation({
+ *   args: { id: v.id("posts"), data: v.any() },
+ *   handler: (ctx, args) => update({ ctx, id: args.id, data: args.data }),
+ * });
+ * ```
+ */
+export declare function update<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug>(args: UpdateServerArgs<DataModel, TCollectionSlug>): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/api/update/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/api/update/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,MAAM,EACN,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAI5D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAC/B,SAAS,SAAS,gBAAgB,EAClC,eAAe,SAAS,cAAc,CACtC,SAAQ,2BAA2B,CAAC,SAAS,CAAC;IAC9C,kDAAkD;IAClD,UAAU,EAAE,eAAe,CAAC;IAC5B,gCAAgC;IAChC,EAAE,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,IAAI,EAAE,OAAO,CACX,MAAM,CACJ,UAAU,CACR,cAAc,CAAC,SAAS,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC,EAC3D,eAAe,GAAG,KAAK,CACxB,CACF,CACF,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAC1B,SAAS,SAAS,gBAAgB,EAClC,eAAe,SAAS,cAAc,EACtC,IAAI,EAAE,gBAAgB,CAAC,SAAS,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BnE"}