@vexcms/core 0.0.20 → 0.1.0-alpha.2

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

@@ -0,0 +1,65 @@
+import { GenericDataModel, GenericMutationCtx, GenericQueryCtx } from "convex/server";
+import { VexConfig } from "../../config";
+import { AccessCallOptions, MutationCallActionFor, QueryCallActionFor, VexApiAuth } from "../types";
+import { GlobalSlug } from "../../types";
+/**
+ * Base server-side args shared by every globals **query** function
+ * (`getGlobal`, `findGlobals`). Each concrete function extends this with its
+ * own inputs (e.g. `slug`, `populate`, `depth`).
+ *
+ * The RBAC seam rides on `auth` + `config`: when `config.access` is set, the
+ * function runs `hasPermission` for the global's slug using `auth.user` /
+ * `auth.organization`. Resolved server-side by the `globalsApi` factory via
+ * `resolveGetAuth(getAuth)` — never supplied by the client.
+ *
+ * @typeParam TDataModel - The project's generated Convex data model.
+ */
+export interface GenericGlobalsQueryServerArgs<TDataModel extends GenericDataModel, TGlobalSlug extends GlobalSlug = GlobalSlug> {
+    /**
+     * Resolved caller identity for permission checks — `{ user, organization? }`,
+     * or omitted when access control is off. `user` may be `null` for an
+     * unauthenticated caller (→ no roles → deny). Never a client argument;
+     * the factory resolves it from `ctx.auth` per request.
+     */
+    auth?: VexApiAuth;
+    /** Convex query context (read-only DB access). */
+    ctx: GenericQueryCtx<TDataModel>;
+    /**
+     * The resolved `VexConfig`. Required — supplies `config.access` (the
+     * permission matrix the guard enforces) and `config.globals` (used to
+     * resolve the `GlobalConfig` for depth-populate and validation).
+     */
+    config: VexConfig;
+    /** Per-call access overrides. @see {@link AccessCallOptions} */
+    access?: AccessCallOptions<QueryCallActionFor<TGlobalSlug>>;
+}
+/**
+ * Base server-side args shared by every globals **mutation** function
+ * (`upsertGlobal`). Mirrors {@link GenericGlobalsQueryServerArgs} but carries a
+ * mutation context for writes.
+ *
+ * The RBAC seam is identical: when `config.access` is set, the function runs
+ * `hasPermission` for the global's slug (write actions use `throwOnDenied`).
+ *
+ * @typeParam TDataModel - The project's generated Convex data model.
+ */
+export interface GenericGlobalsMutationServerArgs<TDataModel extends GenericDataModel, TGlobalSlug extends GlobalSlug = GlobalSlug> {
+    /**
+     * Resolved caller identity for permission checks — `{ user, organization? }`,
+     * or omitted when access control is off. `user` may be `null` for an
+     * unauthenticated caller (→ no roles → deny). Never a client argument;
+     * the factory resolves it from `ctx.auth` per request.
+     */
+    auth?: VexApiAuth;
+    /** Convex mutation context (read + write DB access). */
+    ctx: GenericMutationCtx<TDataModel>;
+    /**
+     * The resolved `VexConfig`. Required — supplies `config.access` (the
+     * permission matrix the guard enforces) and `config.globals` (used to
+     * resolve the target `GlobalConfig` for input validation).
+     */
+    config: VexConfig;
+    /** Per-call access overrides. @see {@link AccessCallOptions} */
+    access?: AccessCallOptions<MutationCallActionFor<TGlobalSlug>>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/api/globals/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACpG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,6BAA6B,CAC5C,UAAU,SAAS,gBAAgB,EACnC,WAAW,SAAS,UAAU,GAAG,UAAU;IAE3C;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,kDAAkD;IAClD,GAAG,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IACjC;;;;OAIG;IACH,MAAM,EAAE,SAAS,CAAC;IAClB,gEAAgE;IAChE,MAAM,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC;CAC7D;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gCAAgC,CAC/C,UAAU,SAAS,gBAAgB,EACnC,WAAW,SAAS,UAAU,GAAG,UAAU;IAE3C;;;;;OAKG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,wDAAwD;IACxD,GAAG,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACpC;;;;OAIG;IACH,MAAM,EAAE,SAAS,CAAC;IAClB,gEAAgE;IAChE,MAAM,CAAC,EAAE,iBAAiB,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAC;CAChE"}

package/dist/api/globals/upsert.client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns a `useConvexMutation` hook bound to the `globals.update` Convex mutation.
+ * Call the returned function as `mutationFn` inside `useMutation`.
+ *
+ * The mutation accepts `{ slug: string, data: Record<string, unknown> }`.
+ * Pass user field values in `data` — system keys (`_id`, `_creationTime`, `_slug`)
+ * are stripped server-side if they accidentally appear. `GlobalEditView` calls
+ * this internally after stripping system keys from the flat form state.
+ *
+ * Import from `@vexcms/core/client`.
+ *
+ * @returns A `useConvexMutation`-compatible mutation function.
+ *
+ * @example
+ * ```tsx
+ * import { globals } from "@vexcms/core/client";
+ * import { useMutation } from "@tanstack/react-query";
+ *
+ * const mutation = useMutation({ mutationFn: globals.update() });
+ * mutation.mutate({ slug: "siteSettings", data: { siteName: "New Name" } });
+ * ```
+ */
+export declare function updateGlobal(): import("convex/react").ReactMutation<import("convex/server").FunctionReference<"mutation", "public", import("../convex").VexGlobalsUpdateArgs, string>>;
+//# sourceMappingURL=upsert.client.d.ts.map

package/dist/api/globals/upsert.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.client.d.ts","sourceRoot":"","sources":["../../../src/api/globals/upsert.client.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,4JAE3B"}

package/dist/api/globals/upsert.server.d.ts

@@ -0,0 +1,47 @@
+import type { GenericDataModel } from "convex/server";
+import type { GlobalSlug } from "../../types/generated";
+import { GenericGlobalsMutationServerArgs } from "./types";
+/**
+ * Server-side args for `updateGlobal`.
+ *
+ * @typeParam DataModel - Convex data model.
+ * @typeParam TSlug - Global slug.
+ */
+export interface UpsertGlobalServerArgs<DataModel extends GenericDataModel, TGlobalSlug extends GlobalSlug = GlobalSlug> extends GenericGlobalsMutationServerArgs<DataModel, TGlobalSlug> {
+    /** The global slug to upsert. Must match a registered global in config. */
+    slug: TGlobalSlug;
+    /**
+     * User field data. May be the full flat document (system keys `_id`,
+     * `_creationTime`, `_slug` are stripped server-side) or just the field
+     * values. The `GlobalEditView` component sends the flat form values here.
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * Upserts a global document in `vex_globals`. Strips system keys from `data`,
+ * validates remaining user fields against the global's Zod schema, then writes
+ * `{ slug, data: userFields }` to the DB (re-nesting). Patches if a row
+ * already exists for the slug; inserts if not.
+ *
+ * Throws `ConvexError` on Zod validation failure with structured `errors` payload.
+ * Server-side only. Import from `@vexcms/core/server`.
+ *
+ * @typeParam DataModel - Convex data model.
+ * @typeParam TSlug - Global slug.
+ * @param args - `{ ctx, slug, data, globalConfig }`.
+ * @returns The `_id` of the upserted document as a string.
+ *
+ * @example
+ * ```ts
+ * import { updateGlobal } from "@vexcms/core/server";
+ *
+ * const id = await updateGlobal({
+ *   ctx,
+ *   slug: "siteSettings",
+ *   data: { siteName: "New Name" },
+ *   globalConfig: config.globals.find((g) => g.slug === "siteSettings")!,
+ * });
+ * ```
+ */
+export declare function upsertGlobal<DataModel extends GenericDataModel, TSlug extends GlobalSlug = GlobalSlug>(args: UpsertGlobalServerArgs<DataModel, TSlug>): Promise<string>;
+//# sourceMappingURL=upsert.server.d.ts.map

package/dist/api/globals/upsert.server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.server.d.ts","sourceRoot":"","sources":["../../../src/api/globals/upsert.server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,gCAAgC,EAAE,MAAM,SAAS,CAAC;AAM3D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CACrC,SAAS,SAAS,gBAAgB,EAClC,WAAW,SAAS,UAAU,GAAG,UAAU,CAC3C,SAAQ,gCAAgC,CAAC,SAAS,EAAE,WAAW,CAAC;IAChE,2EAA2E;IAC3E,IAAI,EAAE,WAAW,CAAC;IAClB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,YAAY,CAChC,SAAS,SAAS,gBAAgB,EAClC,KAAK,SAAS,UAAU,GAAG,UAAU,EACrC,IAAI,EAAE,sBAAsB,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAwDjE"}

package/dist/api/populate.d.ts

@@ -0,0 +1,23 @@
+import type { GenericDataModel, GenericQueryCtx } from "convex/server";
+import type { CollectionSlug } from "../types/generated";
+import type { Populated, PopulateShape } from "./types";
+/**
+ * Walks `docs` and replaces each relationship field listed in `populate` with
+ * the resolved target doc(s). Returns a shallow-copied array; original docs
+ * are not mutated.
+ *
+ * The `TPopulate` generic is the caller-supplied populate shape. The return
+ * type `Populated<TCollectionSlug, TPopulate>[]` is what TypeScript sees at call sites
+ * — the `as unknown as` cast at the bottom bridges runtime
+ * `Record<string, unknown>[]` to the compile-time `Populated` shape. All
+ * callers (`find`, `get`, `search` server functions) benefit without writing
+ * their own casts.
+ *
+ * @param ctx - The Convex query context (any DataModel).
+ * @param docs - Documents to populate.
+ * @param populate - Relationship fields to resolve, optionally nested.
+ * @returns Same docs with relationship Id arrays replaced by Doc arrays,
+ *   typed as `Populated<TCollectionSlug, TPopulate>[]`.
+ */
+export declare function populateDocs<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug = CollectionSlug, const TPopulate extends PopulateShape<TCollectionSlug> = PopulateShape<TCollectionSlug>>(ctx: GenericQueryCtx<DataModel>, docs: Record<string, unknown>[], populate: TPopulate): Promise<Populated<TCollectionSlug, TPopulate>[]>;
+//# sourceMappingURL=populate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"populate.d.ts","sourceRoot":"","sources":["../../src/api/populate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAyB,MAAM,eAAe,CAAC;AAE9F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAChC,SAAS,SAAS,gBAAgB,EAClC,eAAe,SAAS,cAAc,GAAG,cAAc,EACvD,KAAK,CAAC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,EAEvF,GAAG,EAAE,eAAe,CAAC,SAAS,CAAC,EAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,QAAQ,EAAE,SAAS,GAClB,OAAO,CAAC,SAAS,CAAC,eAAe,EAAE,SAAS,CAAC,EAAE,CAAC,CA4BlD"}

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

@@ -0,0 +1,58 @@
+import type { GenericId } from "convex/values";
+import type { CollectionSlug } from "../../types/generated";
+import type { GenericMutationClientParams } from "../types";
+/**
+ * Client-side args for {@link remove}.
+ *
+ * @example
+ * ```tsx
+ * import { remove, type RemoveClientArgs } from "@vexcms/core/client";
+ * import { useMutation } from "@tanstack/react-query";
+ *
+ * // Inside a React component:
+ * const { mutateAsync } = useMutation({ mutationFn: remove() });
+ * await mutateAsync({ id: postId });
+ * ```
+ */
+export interface RemoveClientArgs<TCollectionSlug extends CollectionSlug> extends GenericMutationClientParams {
+    /**
+     * Document ID(s) to delete.
+     * Pass a single ID in an array for one document, or multiple IDs for bulk delete.
+     */
+    ids: GenericId<TCollectionSlug>[];
+    /**
+     * Optional soft delete field name.
+     * If provided, sets this field to `true` instead of permanently deleting.
+     * @example "deleted" — sets { deleted: true } on the document(s)
+     */
+    softDelete?: string;
+}
+/**
+ * Returns a `mutationFn` for permanently deleting a document from a VexCMS collection.
+ *
+ * Wraps `useConvexMutation(vexConvexApi.remove)`. 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
+ * `remove` from `@vexcms/core/server`.
+ *
+ * @returns A mutation function compatible with tanstack-query `useMutation`.
+ * @see {@link RemoveClientArgs} for the typed args shape.
+ * @example
+ * ```tsx
+ * import { remove } from "@vexcms/core/client";
+ * import { useMutation } from "@tanstack/react-query";
+ *
+ * export function DeleteButton({ id }: { id: Id<"posts"> }) {
+ *   const { mutateAsync, isPending } = useMutation({ mutationFn: remove() });
+ *   return (
+ *     <button onClick={() => mutateAsync({ id })}>
+ *       {isPending ? "Deleting…" : "Delete"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function remove(): import("convex/react").ReactMutation<import("convex/server").FunctionReference<"mutation", "public", import("../convex").VexRemoveArgs, void>>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/remove/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,CACtC,SAAQ,2BAA2B;IACnC;;;OAGG;IACH,GAAG,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,MAAM,mJAErB"}

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

@@ -0,0 +1,65 @@
+import type { GenericDataModel } from "convex/server";
+import type { GenericId } from "convex/values";
+import type { CollectionSlug } from "../../types/generated";
+import type { GenericMutationServerParams } from "../types";
+/**
+ * Server-side args for `remove`.
+ *
+ * @typeParam DataModel - The Convex data model (inferred from `ctx`).
+ * @typeParam TCollectionSlug - Collection slug, recovered from the `Id` brand.
+ */
+export interface RemoveServerArgs<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug> extends GenericMutationServerParams<DataModel> {
+    /** The collection slug to insert into. */
+    collection: TCollectionSlug;
+    /**
+     * Document ID(s) to delete.
+     * Pass a single ID in an array for one document, or multiple IDs for bulk delete.
+     */
+    ids: GenericId<TCollectionSlug>[];
+    /**
+     * Optional soft delete field name.
+     * If provided, sets this field to `true` instead of permanently deleting.
+     * @example "deleted" — sets { deleted: true } on the document(s)
+     */
+    softDelete?: string;
+}
+/**
+ * Deletes one or more documents. Server-side only.
+ * Named `remove` to avoid collision with the JavaScript `delete` keyword.
+ *
+ * Supports both hard delete (permanent) and soft delete (mark as deleted).
+ * Pass `softDelete` field name to soft delete instead of permanently removing.
+ *
+ * Import from `@vexcms/core/server`.
+ *
+ * @typeParam DataModel - Convex data model (inferred from `args.ctx`).
+ * @typeParam TCollectionSlug - Collection slug.
+ * @param args - `{ ctx, ids, softDelete? }`. `ctx` must be a mutation context.
+ * @returns Promise resolving to void.
+ * @example Single delete
+ * ```ts
+ * import { remove } from "@vexcms/core/server";
+ *
+ * export const deletePost = mutation({
+ *   args: { id: v.id("posts") },
+ *   handler: (ctx, args) => remove({ ctx, ids: [args.id] }),
+ * });
+ * ```
+ * @example Bulk delete
+ * ```ts
+ * export const bulkDeletePosts = mutation({
+ *   args: { ids: v.array(v.id("posts")) },
+ *   handler: (ctx, args) => remove({ ctx, ids: args.ids }),
+ * });
+ * ```
+ * @example Soft delete
+ * ```ts
+ * export const softDeletePost = mutation({
+ *   args: { id: v.id("posts") },
+ *   handler: (ctx, args) =>
+ *     remove({ ctx, ids: [args.id], softDelete: "deleted" }),
+ * });
+ * ```
+ */
+export declare function remove<DataModel extends GenericDataModel = GenericDataModel, TCollectionSlug extends CollectionSlug = CollectionSlug>(args: RemoveServerArgs<DataModel, TCollectionSlug>): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/api/remove/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,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,0CAA0C;IAC1C,UAAU,EAAE,eAAe,CAAC;IAC5B;;;OAGG;IACH,GAAG,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,MAAM,CAC1B,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EACrD,eAAe,SAAS,cAAc,GAAG,cAAc,EACvD,IAAI,EAAE,gBAAgB,CAAC,SAAS,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BnE"}

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

@@ -0,0 +1,58 @@
+import { type VexSearchArgs } from "../convex";
+import type { CollectionSlug } from "../../types/generated";
+import type { DocReturnItem, GenericQueryClientParams, PaginationOptions, PaginationResult, PopulateShape, VexQueryOptions } from "../types";
+/**
+ * Client-side args for `search`. Extends {@link GenericQueryClientParams}
+ * to inherit `ctx?: never` and `populate?: TPopulate`.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ */
+export interface SearchClientArgs<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = number> extends GenericQueryClientParams<TCollectionSlug, TPopulate, D> {
+    collection: TCollectionSlug;
+    query: string;
+    searchIndexName: string;
+    searchField: string;
+    limit?: number;
+    paginationOpts?: PaginationOptions;
+}
+/**
+ * Client-side args for `search` with PaginationOptions required. Extends {@link GenericQueryClientParams}
+ * to inherit `ctx?: never` and `populate?: TPopulate`.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ */
+export interface SearchClientPaginatedArgs<TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = number> extends GenericQueryClientParams<TCollectionSlug, TPopulate, D> {
+    collection: TCollectionSlug;
+    query: string;
+    searchIndexName: string;
+    searchField: string;
+    limit?: number;
+    paginationOpts: PaginationOptions;
+}
+/**
+ * Returns tanstack-query options for text search in a VexCMS collection.
+ * Client-side only — pass to `useQuery` / `useSuspenseQuery`.
+ *
+ * Import from `@vexcms/core/client`. For the server-side version, import
+ * `search` from `@vexcms/core/server`.
+ *
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @param args - `{ collection, query, searchIndexName, searchField, limit?, populate? }`.
+ * @returns Tanstack-query `queryOptions`.
+ * @example
+ * ```tsx
+ * import { search } from "@vexcms/core/client";
+ *
+ * const { data: authors } = useQuery(
+ *   search({ collection: "authors", query: q, searchIndexName: "search_name", searchField: "name" }),
+ * );
+ * ```
+ */
+export declare function search<TCollectionSlug extends CollectionSlug, const TPopulate extends PopulateShape<TCollectionSlug> = Record<string, never>, const D extends number = 0>(args: SearchClientArgs<TCollectionSlug, TPopulate, D> & {
+    paginationOpts?: never;
+}): VexQueryOptions<VexSearchArgs, DocReturnItem<TCollectionSlug, TPopulate, D>[]>;
+export declare function search<TCollectionSlug extends CollectionSlug, const TPopulate extends PopulateShape<TCollectionSlug> = Record<string, never>, const D extends number = 0>(args: SearchClientPaginatedArgs<TCollectionSlug, TPopulate, D>): VexQueryOptions<VexSearchArgs, PaginationResult<DocReturnItem<TCollectionSlug, TPopulate, D>>>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/search/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EAGb,eAAe,EAChB,MAAM,UAAU,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAC/B,eAAe,SAAS,cAAc,EACtC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,EAChD,CAAC,SAAS,MAAM,GAAG,MAAM,CACzB,SAAQ,wBAAwB,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/D,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB,CACxC,eAAe,SAAS,cAAc,EACtC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,EAChD,CAAC,SAAS,MAAM,GAAG,MAAM,CACzB,SAAQ,wBAAwB,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/D,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CACpB,eAAe,SAAS,cAAc,EACtC,KAAK,CAAC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC9E,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,EAE1B,IAAI,EAAE,gBAAgB,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG;IAAE,cAAc,CAAC,EAAE,KAAK,CAAA;CAAE,GAGjF,eAAe,CAAC,aAAa,EAAE,aAAa,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;AAClF,wBAAgB,MAAM,CACpB,eAAe,SAAS,cAAc,EACtC,KAAK,CAAC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC9E,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,EAE1B,IAAI,EAAE,yBAAyB,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,GAC7D,eAAe,CAChB,aAAa,EACb,gBAAgB,CAAC,aAAa,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,CAC/D,CAAC"}

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

@@ -0,0 +1,54 @@
+import type { ExpressionOrValue, FilterBuilder, GenericDataModel, NamedTableInfo, TableNamesInDataModel } from "convex/server";
+import type { CollectionSlug } from "../../types/generated";
+import type { DocReturnItem, GenericQueryServerParams, PaginationOptions, PaginationResult, PopulateShape } from "../types";
+/**
+ * Server-side args for `search`.
+ *
+ * Inherits `ctx`, `populate`, `depth`, and `config` (with mutual-exclusion
+ * constraints) from {@link GenericQueryServerParams}.
+ *
+ * @typeParam DataModel - The Convex data model (inferred from `ctx`).
+ * @typeParam TCollectionSlug - Collection slug.
+ * @typeParam TPopulate - Populate object.
+ * @typeParam D - Depth literal (0 = no depth, default).
+ */
+export interface SearchServerArgs<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug, TPopulate extends PopulateShape<TCollectionSlug>, D extends number = 0> extends GenericQueryServerParams<DataModel, TCollectionSlug, TPopulate, D> {
+    /** The collection to search — must match a registered collection slug. */
+    collection: TCollectionSlug;
+    /** The search text. Pass `""` to list recent documents (falls back to `.take()`). */
+    query: string;
+    /** The `.searchIndex()` name declared in the Convex schema (e.g. `"search_name"`). */
+    searchIndexName: string;
+    /** The field the search index is built on. Must match `searchField` in the index declaration. */
+    searchField: string;
+    /** Maximum number of results. Defaults to 20. */
+    limit?: number;
+    /**
+     * Pagination options. When provided, the function returns a `PaginationResult`
+     * with `{ page, continueCursor, isDone }` instead of a plain array.
+     *
+     * Uses Convex's native `.paginate(opts)` API under the hood.
+     */
+    paginationOpts?: PaginationOptions;
+    /**
+     * Filter predicate applied after index narrowing. Equivalent to
+     * `.filter(q => q.eq(q.field("published"), true))` on the Convex query.
+     *
+     * Prefer `withIndex` for performance — `filter` scans every document
+     * in the range and is O(n). Use `filter` for secondary conditions that
+     * can't be expressed as index equality ranges.
+     *
+     * @example
+     * ```ts
+     * find({ ctx, collection: "posts", filter: q => q.eq(q.field("published"), true) })
+     * ```
+     */
+    filter?: (q: FilterBuilder<NamedTableInfo<DataModel, TCollectionSlug extends TableNamesInDataModel<DataModel> ? TCollectionSlug : never>>) => ExpressionOrValue<boolean>;
+}
+export declare function search<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug, const TPopulate extends PopulateShape<TCollectionSlug> = Record<string, never>, const D extends number = 0>(args: SearchServerArgs<DataModel, TCollectionSlug, TPopulate, D> & {
+    paginationOpts?: never;
+}): Promise<DocReturnItem<TCollectionSlug, TPopulate, D>[]>;
+export declare function search<DataModel extends GenericDataModel, TCollectionSlug extends CollectionSlug, const TPopulate extends PopulateShape<TCollectionSlug> = Record<string, never>, const D extends number = 0>(args: SearchServerArgs<DataModel, TCollectionSlug, TPopulate, D> & {
+    paginationOpts: PaginationOptions;
+}): Promise<PaginationResult<DocReturnItem<TCollectionSlug, TPopulate, D>>>;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/api/search/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,cAAc,EAEd,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EAGd,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB,CAC/B,SAAS,SAAS,gBAAgB,EAClC,eAAe,SAAS,cAAc,EACtC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,EAChD,CAAC,SAAS,MAAM,GAAG,CAAC,CACpB,SAAQ,wBAAwB,CAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC;IAC1E,0EAA0E;IAC1E,UAAU,EAAE,eAAe,CAAC;IAC5B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,eAAe,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,cAAc,CAAC,EAAE,iBAAiB,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,CACP,CAAC,EAAE,aAAa,CACd,cAAc,CACZ,SAAS,EACT,eAAe,SAAS,qBAAqB,CAAC,SAAS,CAAC,GAAG,eAAe,GAAG,KAAK,CACnF,CACF,KACE,iBAAiB,CAAC,OAAO,CAAC,CAAC;CACjC;AAGD,wBAAsB,MAAM,CAC1B,SAAS,SAAS,gBAAgB,EAClC,eAAe,SAAS,cAAc,EACtC,KAAK,CAAC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC9E,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,EAE1B,IAAI,EAAE,gBAAgB,CAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG;IACjE,cAAc,CAAC,EAAE,KAAK,CAAC;CACxB,GAGA,OAAO,CAAC,aAAa,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;AAG3D,wBAAsB,MAAM,CAC1B,SAAS,SAAS,gBAAgB,EAClC,eAAe,SAAS,cAAc,EACtC,KAAK,CAAC,SAAS,SAAS,aAAa,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC9E,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,EAE1B,IAAI,EAAE,gBAAgB,CAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG;IACjE,cAAc,EAAE,iBAAiB,CAAC;CACnC,GACA,OAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC"}