use-convex 1.0.0 → 1.2.0

package/README.md

@@ -26,7 +26,7 @@ export default defineNuxtConfig({
 <script setup lang="ts">
 import { api } from '~~/convex/_generated/api'
 
-const { data, pending, error } = await useConvexQuery(api.tasks.list, {})
+const { data, pending, error } = await useConvexQuery(api.tasks.list, {}, { authenticated: true })
 </script>
 ```
 
@@ -58,6 +58,7 @@ Set `convex.server: false` to skip SSR snapshots globally, or pass `{ server: fa
 const { data, pending, error, refresh } = await useConvexQuery(
   api.tasks.list,
   {}, // args, a ref / getter, or 'skip'
+  { authenticated: true }, // wait for Convex auth before live subscribe
 )
 ```
 
@@ -84,11 +85,14 @@ prewarmQuery(api.tasks.list, {})
 
 ### Several queries
 
+Browser-only live map (no SSR). Each value is `data | undefined` (loading) | `Error`. Combine with `useConvexQuery` when you need an SSR snapshot for known queries.
+
 ```ts
 const results = useConvexQueries(() => ({
-  inbox: { query: api.messages.list, args: { channel: 'inbox' } },
-  later: selectedId.value ? { query: api.messages.get, args: { id: selectedId.value } } : 'skip',
+  tasks: { query: api.tasks.list, args: {} },
+  files: showFiles.value ? { query: api.files.list, args: {} } : 'skip',
 }))
+// results.value.tasks
 ```
 
 ### Pagination
@@ -97,8 +101,9 @@ const results = useConvexQueries(() => ({
 const { results, status, isLoading, loadMore } = await useConvexPaginatedQuery(
   api.tasks.listPaginated,
   {},
-  { initialNumItems: 20 },
+  { initialNumItems: 20, authenticated: true },
 )
+// loadMore() when status === 'CanLoadMore'
 ```
 
 The first page is SSR'd. On the browser, every loaded page stays live. `loadMore` fetches the next page.
@@ -115,10 +120,10 @@ const { mutate, pending, error } = useConvexMutation(api.tasks.create, {
     ])
   },
 })
-await mutate({ text: 'Ship it' })
+await mutate({ text: 'Ship it' }) // browser-only
 
-const { run } = useConvexAction(api.ai.summarize)
-await run({ text: '…' })
+const { run, pending, error } = useConvexAction(api.tasks.shout)
+const shouted = await run({ text: 'hello' }) // browser-only
 ```
 
 For paginated lists:
@@ -133,7 +138,7 @@ insertAtTop({
 
 Also available: `insertAtBottomIfLoaded`, `insertAtPosition`, `optimisticallyUpdateValueInPaginatedQuery`.
 
-`useConvex()` returns the browser `ConvexClient` when you need an escape hatch. `useConvexConnectionState()` is a reactive WebSocket `ConnectionState`.
+`useConvex()` returns the browser `ConvexClient` when you need an escape hatch. `useConvexConnectionState()` is a reactive `ShallowRef<ConnectionState | null>` (WebSocket status: `isWebSocketConnected`, `hasInflightRequests`, …).
 
 ## File uploads
 
@@ -145,7 +150,7 @@ const { upload, pending, error, progress } = useConvexFileUpload({
   saveFile: api.files.save, // ({ storageId, name, contentType, size, ... }) => Id<"files">
 })
 
-await upload(file)
+await upload(file) // progress: 0..1 while bytes fly
 // optional extra save args: await upload(file, { caption: '…' })
 ```
 
@@ -169,8 +174,9 @@ export const { generateUploadUrl, syncMetadata } = r2.clientApi({
 ```
 
 ```ts
+// Pass r2.clientApi() exports: { generateUploadUrl, syncMetadata }
 const { upload, pending, error, progress } = useConvexR2Upload(api.r2)
-const key = await upload(file)
+const key = await upload(file) // R2 object key
 ```
 
 That runs `generateUploadUrl` → `PUT` to the signed URL → `syncMetadata({ key })`, with XHR progress. Use built-in `useConvexFileUpload` for Convex storage; use this helper when you adopt the R2 component.
@@ -303,6 +309,15 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
+```ts
+// server/api/shout.post.ts
+export default defineEventHandler(async (event) => {
+  requireConvexAuth(event)
+  const { text } = await readBody(event)
+  return await fetchAction(api.tasks.shout, { text }, { event })
+})
+```
+
 `fetchAction` uses the same options. Each helper builds a fresh `ConvexHttpClient`. Override with `{ token }` when you already have a JWT. `getConvexToken(event)` reads the cookie without throwing.
 
 ## Config
@@ -353,7 +368,8 @@ pnpm run dev
 
 | Route     | What it shows                                         |
 | --------- | ----------------------------------------------------- |
-| `/`       | SSR snapshot + live overlay (sign up, CRUD todos)     |
+| `/`       | Shell session: features + composable call-shape demos |
+| `/live`   | SSR snapshot + live overlay (sign up, CRUD todos)     |
 | `/server` | Nitro `fetchQuery` / `fetchMutation` / `fetchAction`  |
 | `/files`  | `useConvexFileUpload` (upload, list, preview, delete) |
 | `/extras` | `live: false`, pagination, action, connection state   |
@@ -362,17 +378,24 @@ On `/server`: `GET /api/health` is public; `GET`/`POST /api/tasks` use the cooki
 
 ## Releasing
 
-Releases run from `.github/workflows/release.yml` when commits land on `main`. Version bumps follow [conventional commits](https://www.conventionalcommits.org/):
+Releases run from `.github/workflows/release.yml` when commits that touch `src/` land on `main` (or when the workflow is run manually). Version bumps follow [conventional commits](https://www.conventionalcommits.org/):
 
 | Commit                         | Release |
 | ------------------------------ | ------- |
-| `fix:`                         | patch   |
-| `feat:`                        | minor   |
 | `feat!:` or `BREAKING CHANGE:` | major   |
-| `chore:`, `docs:`, `ci:`, …    | none    |
+| `feat:`                        | minor   |
+| anything else under `src/`     | patch   |
 
 semantic-release publishes `use-convex` to npm, tags `vX.Y.Z`, and opens a GitHub Release. The repo `package.json` version is not committed back.
 
+Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC), not an `NPM_TOKEN`. On [the `use-convex` package settings](https://www.npmjs.com/package/use-convex?activeTab=settings) add a GitHub Actions trusted publisher:
+
+- **Organization or user:** `jrmybtlr`
+- **Repository:** `convex-nuxt`
+- **Workflow filename:** `release.yml`
+- **Environment:** leave empty
+- **Allowed actions:** include **`npm publish`** (new publishers default to staged publish only)
+
 ## License
 
 MIT

package/dist/module.d.mts

@@ -9,6 +9,7 @@ export { ConvexR2UploadApi, ConvexR2UploadProgress } from '../dist/runtime/compo
 export { PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference, PaginationStatus, UseConvexPaginatedQueryOptions, UseConvexPaginatedQueryReturn } from '../dist/runtime/composables/useConvexPaginatedQuery.js';
 export { ConvexQueriesRequest, ConvexQueriesResult, ConvexQueryRequestEntry } from '../dist/runtime/composables/useConvexQueries.js';
 export { ConvexFetchOptions } from '../dist/runtime/server/fetch.js';
+export { ConvexRef } from '../dist/runtime/utils/functionReference.js';
 export { ConvexAuthContext, ConvexNuxtContext } from '../dist/runtime/utils/context.js';
 export { ConnectionState } from '../dist/runtime/composables/useConvexConnectionState.js';
 export { ConvexGate } from '../dist/runtime/composables/useConvexGate.js';

package/dist/runtime/composables/prewarmQuery.d.ts

@@ -1,4 +1,5 @@
-import type { FunctionArgs, FunctionReference } from 'convex/server';
+import type { FunctionArgs } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 /**
  * Start a live subscription early so the first `useConvexQuery` / screen
  * paint can reuse warm client state (React `prewarmQuery` parity).
@@ -6,4 +7,4 @@ import type { FunctionArgs, FunctionReference } from 'convex/server';
  * Returns an unsubscribe function. When called during Vue `setup`, the
  * subscription is also cleaned up with the current effect scope.
  */
-export declare function prewarmQuery<Query extends FunctionReference<'query'>>(query: Query, args?: FunctionArgs<Query>): () => void;
+export declare function prewarmQuery<Query extends ConvexRef<'query'>>(query: Query, args?: FunctionArgs<Query>): () => void;

package/dist/runtime/composables/useConvexAction.d.ts

@@ -1,12 +1,13 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import { type MaybeRefOrGetter } from 'vue';
+import type { ConvexRef } from '../utils/functionReference.js';
 /**
  * Browser action helper. Returns `{ run, error, pending }`.
  *
  * Safe to call during SSR setup — the ConvexClient is only touched when
  * `run()` runs in the browser.
  */
-export declare function useConvexAction<Action extends FunctionReference<'action'>>(action: Action): {
+export declare function useConvexAction<Action extends ConvexRef<'action'>>(action: Action): {
     run: (args?: MaybeRefOrGetter<FunctionArgs<Action>>) => Promise<FunctionReturnType<Action>>;
     error: import("vue").Ref<Error | null, Error | null>;
     pending: import("vue").ComputedRef<boolean>;

package/dist/runtime/composables/useConvexFileUpload.d.ts

@@ -1,4 +1,5 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 /** Built-in fields the composable always passes into `saveFile`. */
 export type ConvexFileUploadMeta = {
     storageId: string;
@@ -6,8 +7,8 @@ export type ConvexFileUploadMeta = {
     contentType: string;
     size: number;
 };
-export type ConvexFileUploadExtraArgs<SaveFile extends FunctionReference<'mutation'>> = Omit<FunctionArgs<SaveFile>, 'storageId' | 'name' | 'contentType' | 'size'>;
-export interface UseConvexFileUploadOptions<GenerateUploadUrl extends FunctionReference<'mutation'>, SaveFile extends FunctionReference<'mutation'>> {
+export type ConvexFileUploadExtraArgs<SaveFile extends ConvexRef<'mutation'>> = Omit<FunctionArgs<SaveFile>, 'storageId' | 'name' | 'contentType' | 'size'>;
+export interface UseConvexFileUploadOptions<GenerateUploadUrl extends ConvexRef<'mutation'>, SaveFile extends ConvexRef<'mutation'>> {
     /**
      * Mutation that returns a short-lived Convex upload URL
      * (`ctx.storage.generateUploadUrl()`). Must enforce auth itself.
@@ -35,7 +36,7 @@ export declare function postFileToUploadUrl(uploadUrl: string, file: File, onPro
  * in the browser. Your Convex mutations must enforce auth; never expose an
  * unauthenticated `generateUploadUrl`.
  */
-export declare function useConvexFileUpload<GenerateUploadUrl extends FunctionReference<'mutation'>, SaveFile extends FunctionReference<'mutation'>>(options: UseConvexFileUploadOptions<GenerateUploadUrl, SaveFile>): {
+export declare function useConvexFileUpload<GenerateUploadUrl extends ConvexRef<'mutation'>, SaveFile extends ConvexRef<'mutation'>>(options: UseConvexFileUploadOptions<GenerateUploadUrl, SaveFile>): {
     upload: (file: File, extra?: ConvexFileUploadExtraArgs<SaveFile> extends Record<string, never> ? undefined : ConvexFileUploadExtraArgs<SaveFile>) => Promise<FunctionReturnType<SaveFile>>;
     error: import("vue").Ref<Error | null, Error | null>;
     pending: import("vue").ComputedRef<boolean>;

package/dist/runtime/composables/useConvexMutation.d.ts

@@ -1,8 +1,9 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import type { OptimisticUpdate } from 'convex/browser';
 import { type MaybeRefOrGetter } from 'vue';
+import type { ConvexRef } from '../utils/functionReference.js';
 export type { OptimisticUpdate };
-export interface UseConvexMutationOptions<Mutation extends FunctionReference<'mutation'>> {
+export interface UseConvexMutationOptions<Mutation extends ConvexRef<'mutation'>> {
     /**
      * Local query update applied while the mutation is in flight.
      * Passed through to `ConvexClient.mutation` → `BaseConvexClient`.
@@ -18,7 +19,7 @@ export interface UseConvexMutationOptions<Mutation extends FunctionReference<'mu
  * Pass `{ optimisticUpdate }` to apply temporary local query results while
  * the mutation is in flight (same contract as React `withOptimisticUpdate`).
  */
-export declare function useConvexMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, options?: UseConvexMutationOptions<Mutation>): {
+export declare function useConvexMutation<Mutation extends ConvexRef<'mutation'>>(mutation: Mutation, options?: UseConvexMutationOptions<Mutation>): {
     mutate: (args?: MaybeRefOrGetter<FunctionArgs<Mutation>>) => Promise<FunctionReturnType<Mutation>>;
     error: import("vue").Ref<Error | null, Error | null>;
     pending: import("vue").ComputedRef<boolean>;

package/dist/runtime/composables/useConvexPaginatedQuery.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType, PaginationOptions, PaginationResult } from 'convex/server';
+import type { FunctionArgs, FunctionReference, FunctionReference_future, FunctionReturnType, PaginationOptions, PaginationResult } from 'convex/server';
 import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
 /**
  * A query usable with {@link useConvexPaginatedQuery}.
@@ -6,6 +6,8 @@ import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
  */
 export type PaginatedQueryReference = FunctionReference<'query', 'public', {
     paginationOpts: PaginationOptions;
+}, PaginationResult<unknown>> | FunctionReference_future<'query', 'public', {
+    paginationOpts: PaginationOptions;
 }, PaginationResult<unknown>>;
 export type PaginatedQueryArgs<Query extends PaginatedQueryReference> = Omit<FunctionArgs<Query>, 'paginationOpts'>;
 export type PaginatedQueryItem<Query extends PaginatedQueryReference> = FunctionReturnType<Query>['page'][number];

package/dist/runtime/composables/useConvexQueries.d.ts

@@ -1,7 +1,8 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import type { ConvexRef } from '../utils/functionReference.js';
 /** One entry in a {@link useConvexQueries} request map. */
-export type ConvexQueryRequestEntry<Query extends FunctionReference<'query'> = FunctionReference<'query'>> = {
+export type ConvexQueryRequestEntry<Query extends ConvexRef<'query'> = ConvexRef<'query'>> = {
     query: Query;
     args: FunctionArgs<Query>;
 };
@@ -14,7 +15,7 @@ export type ConvexQueriesResult<Request extends ConvexQueriesRequest> = {
     [K in keyof Request]: Request[K] extends {
         query: infer Query;
         args: infer _Args;
-    } ? Query extends FunctionReference<'query'> ? FunctionReturnType<Query> | undefined | Error : undefined : undefined;
+    } ? Query extends ConvexRef<'query'> ? FunctionReturnType<Query> | undefined | Error : undefined : undefined;
 };
 /**
  * Subscribe to a dynamic map of Convex queries (React `useQueries` parity).

package/dist/runtime/composables/useConvexQuery.d.ts

@@ -1,6 +1,7 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
-export type ConvexQueryArgs<Query extends FunctionReference<'query'>> = FunctionArgs<Query> | 'skip';
+export type ConvexQueryArgs<Query extends ConvexRef<'query'>> = FunctionArgs<Query> | 'skip';
 export interface UseConvexQueryOptions {
     /**
      * Explicit Nuxt payload/cache key.
@@ -53,4 +54,4 @@ export interface UseConvexQueryReturn<T> {
  * a duplicate HTTP request. On the browser, a live `ConvexClient` subscription
  * overlays the payload (`live ?? payload`), matching Next.js `usePreloadedQuery`.
  */
-export declare function useConvexQuery<Query extends FunctionReference<'query'>>(query: Query, args?: MaybeRefOrGetter<ConvexQueryArgs<Query>>, options?: UseConvexQueryOptions): Promise<UseConvexQueryReturn<FunctionReturnType<Query>>>;
+export declare function useConvexQuery<Query extends ConvexRef<'query'>>(query: Query, args?: MaybeRefOrGetter<ConvexQueryArgs<Query>>, options?: UseConvexQueryOptions): Promise<UseConvexQueryReturn<FunctionReturnType<Query>>>;

package/dist/runtime/composables/useConvexR2Upload.d.ts

@@ -1,11 +1,12 @@
-import type { FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionReturnType } from 'convex/server';
+import type { ConvexRef } from '../utils/functionReference.js';
 /**
  * Subset of `@convex-dev/r2` `clientApi()` exports needed for client uploads.
  * Pass `api.example` (or any module that re-exports these two mutations).
  */
 export type ConvexR2UploadApi = {
-    generateUploadUrl: FunctionReference<'mutation'>;
-    syncMetadata: FunctionReference<'mutation'>;
+    generateUploadUrl: ConvexRef<'mutation'>;
+    syncMetadata: ConvexRef<'mutation'>;
 };
 export type ConvexR2UploadProgress = {
     loaded: number;

package/dist/runtime/server/fetch.d.ts

@@ -1,5 +1,6 @@
-import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import type { FunctionArgs, FunctionReturnType } from 'convex/server';
 import type { H3Event } from 'h3';
+import type { ConvexRef } from '../utils/functionReference.js';
 export interface ConvexFetchOptions {
     /**
      * Deployment URL. Defaults to `NUXT_PUBLIC_CONVEX_URL` / runtimeConfig.
@@ -30,12 +31,12 @@ export declare function resolveToken(options: ConvexFetchOptions): string | unde
  * })
  * ```
  */
-export declare function fetchQuery<Query extends FunctionReference<'query'>>(query: Query, args?: FunctionArgs<Query>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Query>>;
+export declare function fetchQuery<Query extends ConvexRef<'query'>>(query: Query, args?: FunctionArgs<Query>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Query>>;
 /**
  * One-shot mutation via ConvexHttpClient. Use in Nitro routes / server middleware.
  */
-export declare function fetchMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, args?: FunctionArgs<Mutation>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Mutation>>;
+export declare function fetchMutation<Mutation extends ConvexRef<'mutation'>>(mutation: Mutation, args?: FunctionArgs<Mutation>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Mutation>>;
 /**
  * One-shot action via ConvexHttpClient. Use in Nitro routes / server middleware.
  */
-export declare function fetchAction<Action extends FunctionReference<'action'>>(action: Action, args?: FunctionArgs<Action>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Action>>;
+export declare function fetchAction<Action extends ConvexRef<'action'>>(action: Action, args?: FunctionArgs<Action>, options?: ConvexFetchOptions): Promise<FunctionReturnType<Action>>;

package/dist/runtime/utils/functionReference.d.ts

@@ -0,0 +1,10 @@
+import type { FunctionReference, FunctionReference_future, FunctionType } from 'convex/server';
+/**
+ * Function reference accepted by use-convex client APIs.
+ *
+ * Convex 1.46+ introduced {@link FunctionReference_future} for stricter
+ * callback argument checking. Generated `api` refs remain plain
+ * {@link FunctionReference}; library surfaces accept either kind so callers
+ * can pass both (same contract as Convex React hooks).
+ */
+export type ConvexRef<Type extends FunctionType> = FunctionReference<Type> | FunctionReference_future<Type>;

package/dist/runtime/utils/queryKey.d.ts

@@ -1,8 +1,8 @@
-import type { FunctionReference } from 'convex/server';
+import type { ConvexRef } from './functionReference.js';
 /**
  * Stable Nuxt payload / useAsyncData key for a Convex query.
  *
  * `'skip'` means "don't fetch" — it must not change the key, otherwise
  * auth-gated queries lose the SSR payload on the client.
  */
-export declare function convexQueryKey(query: FunctionReference<'query'>, args: unknown, explicitKey?: string): string;
+export declare function convexQueryKey(query: ConvexRef<'query'>, args: unknown, explicitKey?: string): string;

package/dist/types.d.mts

@@ -22,6 +22,8 @@ export { type ConvexQueriesRequest, type ConvexQueriesResult, type ConvexQueryRe
 
 export { type ConvexFetchOptions } from '../dist/runtime/server/fetch.js'
 
+export { type ConvexRef } from '../dist/runtime/utils/functionReference.js'
+
 export { type ConvexAuthContext, type ConvexNuxtContext } from '../dist/runtime/utils/context.js'
 
 export { type ConnectionState } from '../dist/runtime/composables/useConvexConnectionState.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-convex",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "First-class Convex integration for Nuxt",
   "license": "MIT",
   "repository": {
@@ -50,7 +50,7 @@
     "@nuxt/schema": "^4.0.0",
     "@nuxt/test-utils": "^3.23.0",
     "@types/node": "^26.5.0",
-    "convex": "^1.45.0",
+    "convex": "^1.46.0",
     "convex-test": "^0.0.56",
     "happy-dom": "^20.14.0",
     "nitropack": "^2.13.0",
@@ -63,7 +63,7 @@
     "vue-tsc": "^3.0.0"
   },
   "peerDependencies": {
-    "convex": "^1.21.0",
+    "convex": "^1.46.0",
     "nuxt": "^4.0.0",
     "vue": "^3.5.0"
   },