nuxt-convex-module 0.0.0

package/dist/runtime/vue/composables/use-action.d.ts

@@ -0,0 +1,62 @@
+import type { FunctionReference, FunctionReturnType, OptionalRestArgs } from 'convex/server';
+/**
+ * An interface to execute a Convex action on the server.
+ *
+ * @public
+ */
+export interface VueAction<Action extends FunctionReference<'action'>> {
+    /**
+     * Execute the function on the server, returning a `Promise` of its return value.
+     *
+     * @param args - Arguments for the function to pass up to the server.
+     * @returns The return value of the server-side function call.
+     * @public
+     */
+    (...args: OptionalRestArgs<Action>): Promise<FunctionReturnType<Action>>;
+}
+/**
+ * Construct a new {@link VueAction}.
+ *
+ * Returns a function that you can call to execute a Convex action. Actions
+ * can call third-party APIs and perform side effects. The returned function
+ * is stable for the lifetime of the composable (same reference identity).
+ *
+ * **Error handling:** Actions can fail (e.g., if an external API is down).
+ * Always wrap action calls in try/catch or handle the rejected promise.
+ *
+ * **Note:** In most cases, calling an action directly from a client is an
+ * anti-pattern. Prefer having the client call a mutation that captures the
+ * user's intent (by writing to the database) and then schedules the action
+ * via `ctx.scheduler.runAfter`. This ensures the intent is durably recorded
+ * even if the client disconnects.
+ *
+ * Throws an error if no Convex client has been provided.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useAction } from '#imports'
+ * import { api } from '#convex/api'
+ *
+ * const generate = useAction(api.ai.generateSummary)
+ *
+ * async function handleClick() {
+ *   try {
+ *     const summary = await generate({ text: 'Some long text...' })
+ *     console.log(summary)
+ *   } catch (error) {
+ *     console.error('Action failed:', error)
+ *   }
+ * }
+ * </script>
+ * ```
+ *
+ * @param action - A {@link server.FunctionReference} for the public action
+ * to run like `api.dir1.dir2.filename.func`.
+ * @returns The {@link VueAction} object with that name.
+ *
+ * @public
+ */
+export declare function useAction<Action extends FunctionReference<'action'>>(action: Action): VueAction<Action>;
+/** @public */
+export declare const useConvexAction: typeof useAction;

package/dist/runtime/vue/composables/use-action.js

@@ -0,0 +1,13 @@
+import { makeFunctionReference } from "convex/server";
+import { useConvexOrThrow } from "../client.js";
+function createAction(actionReference, client) {
+  return function(args) {
+    return client.action(actionReference, args);
+  };
+}
+export function useAction(action) {
+  const convex = useConvexOrThrow("useAction");
+  const actionReference = typeof action === "string" ? makeFunctionReference(action) : action;
+  return createAction(actionReference, convex);
+}
+export const useConvexAction = useAction;

package/dist/runtime/vue/composables/use-connection-state.d.ts

@@ -0,0 +1,30 @@
+import type { ConnectionState } from 'convex/browser';
+import type { ShallowRef } from 'vue';
+/**
+ * Vue composable to get the current {@link ConnectionState} and subscribe to changes.
+ *
+ * This composable returns a shallow ref of the current connection state that
+ * automatically updates when any part of the connection state changes (e.g.,
+ * when going online/offline, when requests start/complete, etc.).
+ *
+ * The shape of ConnectionState may change in the future which may cause this
+ * composable to update more frequently.
+ *
+ * Throws an error if no Convex client has been provided.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * const conn = useConvexConnectionState()
+ * </script>
+ *
+ * <template>
+ *   <span v-if="!conn.isWebSocketConnected">Offline</span>
+ * </template>
+ * ```
+ *
+ * @returns The current {@link ConnectionState} with the Convex deployment.
+ *
+ * @public
+ */
+export declare function useConvexConnectionState(): ShallowRef<ConnectionState>;

package/dist/runtime/vue/composables/use-connection-state.js

@@ -0,0 +1,14 @@
+import { useConvexOrThrow } from "../client.js";
+import { useSubscription } from "./use-subscription.js";
+export function useConvexConnectionState() {
+  const convex = useConvexOrThrow("useConvexConnectionState");
+  const getCurrentValue = () => {
+    return convex.connectionState();
+  };
+  const subscribe = (callback) => {
+    return convex.subscribeToConnectionState(() => {
+      callback();
+    });
+  };
+  return useSubscription({ getCurrentValue, subscribe });
+}

package/dist/runtime/vue/composables/use-mutation.d.ts

@@ -0,0 +1,76 @@
+import type { OptimisticUpdate } from 'convex/browser';
+import type { FunctionArgs, FunctionReference, FunctionReturnType, OptionalRestArgs } from 'convex/server';
+import { type ConvexVueClient } from '../client.js';
+/**
+ * An interface to execute a Convex mutation function on the server.
+ *
+ * @public
+ */
+export interface VueMutation<Mutation extends FunctionReference<'mutation'>> {
+    /**
+     * Execute the mutation on the server, returning a `Promise` of its return value.
+     *
+     * @param args - Arguments for the mutation to pass up to the server.
+     * @returns The return value of the server-side function call.
+     */
+    (...args: OptionalRestArgs<Mutation>): Promise<FunctionReturnType<Mutation>>;
+    /**
+     * Define an optimistic update to apply as part of this mutation.
+     *
+     * This is a temporary update to the local query results to facilitate a
+     * fast, interactive UI. It enables query results to update before a mutation
+     * executed on the server.
+     *
+     * When the mutation is invoked, the optimistic update will be applied.
+     *
+     * Optimistic updates can also be used to temporarily remove queries from the
+     * client and create loading experiences until a mutation completes and the
+     * new query results are synced.
+     *
+     * The update will be automatically rolled back when the mutation is fully
+     * completed and queries have been updated.
+     *
+     * @param optimisticUpdate - The optimistic update to apply.
+     * @returns A new `VueMutation` with the update configured.
+     *
+     * @public
+     */
+    withOptimisticUpdate<T extends OptimisticUpdate<FunctionArgs<Mutation>>>(optimisticUpdate: T & (ReturnType<T> extends Promise<any> ? 'Optimistic update handlers must be synchronous' : {})): VueMutation<Mutation>;
+}
+export declare function createMutation(mutationReference: FunctionReference<'mutation'>, client: ConvexVueClient, update?: OptimisticUpdate<any>): VueMutation<any>;
+/**
+ * Construct a new {@link VueMutation}.
+ *
+ * Returns a function that you can call to execute a Convex mutation. The
+ * returned function is stable for the lifetime of the composable (same
+ * reference identity), so it can be safely passed around and memoized.
+ *
+ * Mutations can optionally be configured with
+ * [optimistic updates](https://docs.convex.dev/client/react/optimistic-updates)
+ * for instant UI feedback.
+ *
+ * Throws an error if no Convex client has been provided.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useMutation } from '#imports'
+ * import { api } from '#convex/api'
+ *
+ * const createTask = useMutation(api.tasks.create)
+ *
+ * async function handleClick() {
+ *   await createTask({ text: 'New task' })
+ * }
+ * </script>
+ * ```
+ *
+ * @param mutation - A {@link server.FunctionReference} for the public mutation
+ * to run like `api.dir1.dir2.filename.func`.
+ * @returns The {@link VueMutation} object with that name.
+ *
+ * @public
+ */
+export declare function useMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation): VueMutation<Mutation>;
+/** @public */
+export declare const useConvexMutation: typeof useMutation;

package/dist/runtime/vue/composables/use-mutation.js

@@ -0,0 +1,34 @@
+import { getFunctionName, makeFunctionReference } from "convex/server";
+import { useConvexOrThrow } from "../client.js";
+export function createMutation(mutationReference, client, update) {
+  function mutation(args) {
+    assertNotAccidentalArgument(args);
+    return client.mutation(mutationReference, args, {
+      optimisticUpdate: update
+    });
+  }
+  mutation.withOptimisticUpdate = function withOptimisticUpdate(optimisticUpdate) {
+    if (update !== void 0) {
+      throw new Error(
+        `Already specified optimistic update for mutation ${getFunctionName(
+          mutationReference
+        )}`
+      );
+    }
+    return createMutation(mutationReference, client, optimisticUpdate);
+  };
+  return mutation;
+}
+export function useMutation(mutation) {
+  const mutationReference = typeof mutation === "string" ? makeFunctionReference(mutation) : mutation;
+  const convex = useConvexOrThrow("useMutation");
+  return createMutation(mutationReference, convex);
+}
+export const useConvexMutation = useMutation;
+function assertNotAccidentalArgument(value) {
+  if (typeof value === "object" && value !== null && "bubbles" in value && "cancelable" in value && "preventDefault" in value) {
+    throw new Error(
+      `Convex function called with Event object. Did you use a Convex function as an event handler directly? Event handlers like @click receive an event object as their first argument. These Event objects are not valid Convex values. Try wrapping the function like \`const handler = () => myMutation();\` and using \`handler\` in the event handler.`
+    );
+  }
+}

package/dist/runtime/vue/composables/use-paginated-query.d.ts

@@ -0,0 +1,132 @@
+import type { OptimisticLocalStore } from 'convex/browser';
+import type { Value } from 'convex/values';
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import type { PaginatedQueryReference, PaginatedQueryArgs, PaginatedQueryItem, PaginationStatus, UsePaginatedQueryOptions, UsePaginatedQueryObjectReturnType } from 'convex/react';
+export type { PaginatedQueryReference, PaginatedQueryArgs, PaginatedQueryItem, UsePaginatedQueryResult, UsePaginatedQueryOptions, UsePaginatedQueryObjectReturnType, PaginationStatus, } from 'convex/react';
+/**
+ * Load data reactively from a paginated query to create a growing list.
+ *
+ * This can be used to power "infinite scroll" UIs.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { usePaginatedQuery } from '#imports'
+ * import { api } from '#convex/api'
+ *
+ * const { results, status, loadMore } = usePaginatedQuery(
+ *   api.messages.list,
+ *   { channel: '#general' },
+ *   { initialNumItems: 5 },
+ * )
+ * </script>
+ *
+ * <template>
+ *   <div v-for="{ _id, body } in results" :key="_id">{{ body }}</div>
+ *   <button :disabled="status !== 'CanLoadMore'" @click="loadMore(5)">Load More</button>
+ * </template>
+ * ```
+ *
+ * @public
+ */
+export declare function usePaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: {
+    initialNumItems: number;
+}): UsePaginatedQueryReturnType<Query>;
+/** @internal */
+export declare function resetPaginationId(): void;
+/**
+ * Return shape of {@link usePaginatedQuery} — the fields of upstream's
+ * `UsePaginatedQueryResult` as `ComputedRef`s plus a *stable* `loadMore`
+ * function. This is the Vue translation of upstream's per-render plain object:
+ * it keeps the documented destructuring idiom reactive,
+ * `const { results, status, loadMore } = usePaginatedQuery(...)`.
+ *
+ * (Upstream's name is kept even though the shape is ref-wrapped — the same
+ * treatment as `ConvexAuthState` — so mechanically ported type annotations
+ * keep compiling. The plain union stays available as
+ * {@link UsePaginatedQueryResult}.)
+ *
+ * @public
+ */
+export type UsePaginatedQueryReturnType<Query extends PaginatedQueryReference> = {
+    results: ComputedRef<PaginatedQueryItem<Query>[]>;
+    status: ComputedRef<PaginationStatus>;
+    isLoading: ComputedRef<boolean>;
+    /**
+     * Fetch `numItems` more results. Stable across state changes; only fetches
+     * when `status` is `'CanLoadMore'` (matching the documented semantics).
+     */
+    loadMore: (numItems: number) => void;
+};
+/** @public */
+export declare const useConvexPaginatedQuery: typeof usePaginatedQuery;
+/**
+ * Optimistically update values in a paginated list.
+ *
+ * @public
+ */
+export declare function optimisticallyUpdateValueInPaginatedQuery<Query extends PaginatedQueryReference>(localStore: OptimisticLocalStore, query: Query, args: PaginatedQueryArgs<Query>, updateValue: (currentValue: PaginatedQueryItem<Query>) => PaginatedQueryItem<Query>): void;
+/**
+ * Insert an item at the top of a paginated list, regardless of sort order.
+ *
+ * Only updates if the first page is already loaded — otherwise the insertion
+ * would flash in/out once the real first page arrives.
+ *
+ * @public
+ */
+export declare function insertAtTop<Query extends PaginatedQueryReference>(options: {
+    paginatedQuery: Query;
+    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
+    localQueryStore: OptimisticLocalStore;
+    item: PaginatedQueryItem<Query>;
+}): void;
+/**
+ * Insert an item at the bottom of a paginated list, but only if the final
+ * page has loaded (otherwise it would pop out when the server responds).
+ *
+ * @public
+ */
+export declare function insertAtBottomIfLoaded<Query extends PaginatedQueryReference>(options: {
+    paginatedQuery: Query;
+    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
+    localQueryStore: OptimisticLocalStore;
+    item: PaginatedQueryItem<Query>;
+}): void;
+/**
+ * Insert an item at its sorted position across loaded pages of a paginated
+ * query, given a sort order and a function deriving the sort key.
+ *
+ * @public
+ */
+export declare function insertAtPosition<Query extends PaginatedQueryReference>(options: {
+    paginatedQuery: Query;
+    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
+    sortOrder: 'asc' | 'desc';
+    sortKeyFromItem: (item: PaginatedQueryItem<Query>) => Value | Value[];
+    localQueryStore: OptimisticLocalStore;
+    item: PaginatedQueryItem<Query>;
+}): void;
+/**
+ * Experimental paginated query that adds an object-form overload on top of the
+ * positional {@link usePaginatedQuery}, mirroring the public name React's
+ * Convex integration exposes (`usePaginatedQuery_experimental`).
+ *
+ * The positional overload behaves exactly like {@link usePaginatedQuery}: it
+ * returns the object-of-refs {@link UsePaginatedQueryReturnType} (TitleCase
+ * statuses) and throws on error. The object overload returns a `ComputedRef`
+ * of the lowercase-status discriminated union
+ * {@link UsePaginatedQueryObjectReturnType} — kept whole (not split into refs)
+ * so the `status`/`data`/`error` type narrowing survives — and surfaces errors
+ * via `status: 'error'` (unless `throwOnError: true`).
+ *
+ * Note: React backs its experimental hook with the Convex client's native
+ * `PaginatedQueryClient`, which the published `convex` package does not export.
+ * This port reuses our manual page-management implementation, which produces
+ * identical observable results (`results`/`data`, `status`, `loadMore`).
+ *
+ * @public
+ */
+export declare function usePaginatedQuery_experimental<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: {
+    initialNumItems: number;
+}): UsePaginatedQueryReturnType<Query>;
+export declare function usePaginatedQuery_experimental<Query extends PaginatedQueryReference, ThrowOnError extends boolean = false>(options: MaybeRefOrGetter<UsePaginatedQueryOptions<Query, ThrowOnError>>): ComputedRef<UsePaginatedQueryObjectReturnType<Query, ThrowOnError>>;