@lupinum/better-convex-nuxt 0.8.0-beta.40

package/dist/runtime/composables/useConvexConfig.js

@@ -0,0 +1,7 @@
+import {
+  getConvexRuntimeConfig,
+  toPublicConvexRuntimeConfig
+} from "../utils/runtime-config.js";
+export function useConvexConfig() {
+  return toPublicConvexRuntimeConfig(getConvexRuntimeConfig());
+}

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

@@ -0,0 +1,33 @@
+export type { ConnectionState } from 'convex/browser';
+/** Deterministic SSR projection around the shared Vue connection store. */
+export declare function useConvexConnectionState(): Readonly<{
+    state: import("vue").ComputedRef<import("convex/browser").ConnectionState>;
+    isConnected: import("vue").ComputedRef<boolean>;
+    isReconnecting: import("vue").ComputedRef<boolean>;
+    pendingMutations: import("vue").ComputedRef<number>;
+    pendingActions: import("vue").ComputedRef<number>;
+}> | Readonly<{
+    state: Readonly<import("vue").Ref<{
+        readonly hasInflightRequests: boolean;
+        readonly isWebSocketConnected: boolean;
+        readonly timeOfOldestInflightRequest: null;
+        readonly hasEverConnected: boolean;
+        readonly connectionCount: number;
+        readonly connectionRetries: number;
+        readonly inflightMutations: number;
+        readonly inflightActions: number;
+    }, {
+        readonly hasInflightRequests: boolean;
+        readonly isWebSocketConnected: boolean;
+        readonly timeOfOldestInflightRequest: null;
+        readonly hasEverConnected: boolean;
+        readonly connectionCount: number;
+        readonly connectionRetries: number;
+        readonly inflightMutations: number;
+        readonly inflightActions: number;
+    }>>;
+    isConnected: import("vue").ComputedRef<boolean>;
+    isReconnecting: import("vue").ComputedRef<boolean>;
+    pendingMutations: import("vue").ComputedRef<number>;
+    pendingActions: import("vue").ComputedRef<number>;
+}>;

package/dist/runtime/composables/useConvexConnectionState.js

@@ -0,0 +1,24 @@
+import { useConvexConnectionState as useVueConvexConnectionState } from "@lupinum/better-convex-vue";
+import { computed, readonly, ref } from "vue";
+export function useConvexConnectionState() {
+  if (import.meta.client) return useVueConvexConnectionState();
+  const state = readonly(
+    ref({
+      hasInflightRequests: false,
+      isWebSocketConnected: false,
+      timeOfOldestInflightRequest: null,
+      hasEverConnected: false,
+      connectionCount: 0,
+      connectionRetries: 0,
+      inflightMutations: 0,
+      inflightActions: 0
+    })
+  );
+  return Object.freeze({
+    state,
+    isConnected: computed(() => false),
+    isReconnecting: computed(() => false),
+    pendingMutations: computed(() => 0),
+    pendingActions: computed(() => 0)
+  });
+}

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

@@ -0,0 +1,169 @@
+/**
+ * File upload composable for Convex storage.
+ *
+ * Inspired by nuxt-convex by @onmax (https://github.com/onmax/nuxt-convex)
+ */
+import type { FunctionReference, OptionalRestArgs } from 'convex/server';
+import type { GenericId } from 'convex/values';
+import { type ComputedRef } from 'vue';
+import { ConvexCallError } from '../errors/index.js';
+import { type UploadProgressInfo } from '../utils/upload-core.js';
+export type { UploadProgressInfo } from '../utils/upload-core.js';
+/** A public Convex mutation that generates a browser upload URL. */
+export type UploadUrlMutation = FunctionReference<'mutation', 'public', Record<string, unknown>, string>;
+/**
+ * Upload status representing the current state of the upload
+ * - 'idle': not yet called or reset
+ * - 'pending': upload in progress
+ * - 'success': upload completed successfully
+ * - 'error': upload failed
+ */
+export type UploadStatus = 'idle' | 'pending' | 'success' | 'error';
+/**
+ * Return value from useConvexFileUpload
+ */
+export interface UseConvexFileUploadReturn<Mutation extends UploadUrlMutation> {
+    /**
+     * Upload a file. Returns the storageId on success.
+     * Automatically tracks status, error, progress, and data.
+     * Throws on error (use try/catch or check error ref after).
+     *
+     * @param file - The file to upload
+     * @param args - Validator-derived args for the generateUploadUrl mutation
+     */
+    upload: (file: File, ...args: OptionalRestArgs<Mutation>) => Promise<GenericId<'_storage'>>;
+    /**
+     * StorageId from the last successful upload.
+     * undefined if upload hasn't succeeded yet.
+     */
+    readonly data: ComputedRef<GenericId<'_storage'> | undefined>;
+    /**
+     * Upload status for explicit state management.
+     */
+    readonly status: ComputedRef<UploadStatus>;
+    /**
+     * True when upload is in progress.
+     * Equivalent to status === 'pending'.
+     */
+    readonly pending: ComputedRef<boolean>;
+    /**
+     * Byte-level progress for the current upload.
+     */
+    readonly progress: ComputedRef<UploadProgressInfo>;
+    /**
+     * Error from the last upload attempt as the normalized {@link ConvexCallError}.
+     * undefined if no error or upload hasn't been called.
+     */
+    readonly error: ComputedRef<ConvexCallError | undefined>;
+    /**
+     * Cancel any in-progress upload and reset state.
+     * Aborts XHR, clears error, data, and progress.
+     */
+    readonly cancel: () => void;
+}
+/**
+ * Options for useConvexFileUpload
+ */
+export interface UseConvexFileUploadOptions {
+    /**
+     * Maximum file size in bytes.
+     * Files exceeding this size will be rejected before upload starts.
+     * @example 5 * 1024 * 1024 // 5MB
+     */
+    readonly maxSize?: number;
+    /**
+     * Allowed MIME types.
+     * Files not matching these types will be rejected before upload starts.
+     *
+     * Supports wildcards: `image/*` matches any image type, `video/*` matches any video, etc.
+     *
+     * @example ['image/jpeg', 'image/png'] // Exact types only
+     * @example ['image/*'] // Any image type
+     * @example ['image/*', 'application/pdf'] // Any image or PDF
+     */
+    readonly allowedTypes?: readonly string[];
+}
+/**
+ * Composable for uploading files to Convex file storage with progress tracking.
+ *
+ * Handles the complete upload flow:
+ * 1. Generating an upload URL via mutation
+ * 2. POSTing the file to that URL (with progress tracking via XHR)
+ * 3. Returning the resulting storageId
+ *
+ * API designed to match useConvexMutation for consistency:
+ * - `data` - storageId from last successful upload
+ * - `status` - 'idle' | 'pending' | 'success' | 'error'
+ * - `pending` - boolean shorthand for status === 'pending'
+ * - `progress` - byte-level upload progress
+ * - `error` - Error | undefined
+ *
+ * Note: File uploads only work on the client side.
+ *
+ * @example Basic usage with progress tracking
+ * ```vue
+ * <script setup>
+ * import { api } from '#convex/api'
+ *
+ * const {
+ *   upload,
+ *   pending,
+ *   progress,
+ *   error,
+ *   data: storageId,
+ * } = useConvexFileUpload(api.files.generateUploadUrl)
+ *
+ * async function handleFile(event: Event) {
+ *   const input = event.target as HTMLInputElement
+ *   if (!input.files?.[0]) return
+ *
+ *   try {
+ *     const id = await upload(input.files[0])
+ *     console.log('Uploaded:', id)
+ *   } catch {
+ *     // error is automatically tracked
+ *   }
+ * }
+ * </script>
+ *
+ * <template>
+ *   <input type="file" @change="handleFile" :disabled="pending" />
+ *   <div v-if="pending">Uploading: {{ progress.percent }}%</div>
+ *   <p v-if="error" class="error">{{ error.message }}</p>
+ * </template>
+ * ```
+ *
+ * @example With cancel support
+ * ```vue
+ * <script setup>
+ * import { api } from '#convex/api'
+ *
+ * const { upload, pending, progress, cancel } = useConvexFileUpload(
+ *   api.files.generateUploadUrl
+ * )
+ * </script>
+ *
+ * <template>
+ *   <div v-if="pending">
+ *     Uploading: {{ progress.percent }}%
+ *     <button @click="cancel">Cancel</button>
+ *   </div>
+ * </template>
+ * ```
+ *
+ * @example Saving storageId to a document
+ * ```vue
+ * <script setup>
+ * import { api } from '#convex/api'
+ *
+ * const { upload, pending, progress } = useConvexFileUpload(api.files.generateUploadUrl)
+ * const saveDocument = useConvexMutation(api.documents.create)
+ *
+ * async function handleUpload(file: File, title: string) {
+ *   const storageId = await upload(file)
+ *   await saveDocument({ title, fileId: storageId })
+ * }
+ * </script>
+ * ```
+ */
+export declare function useConvexFileUpload<Mutation extends UploadUrlMutation>(generateUploadUrlMutation: Mutation, options?: UseConvexFileUploadOptions): UseConvexFileUploadReturn<Mutation>;

package/dist/runtime/composables/useConvexFileUpload.js

@@ -0,0 +1,198 @@
+import { computed, getCurrentScope, onScopeDispose, shallowRef } from "vue";
+import { useNuxtApp } from "#imports";
+import { ConvexCallError, normalizeConvexError } from "../errors/index.js";
+import { readConvexRuntimeContext } from "../runtime-context.js";
+import { assertConvexComposableScope } from "../utils/composable-scope.js";
+import { getFunctionName } from "../utils/convex-shared.js";
+import { createIdentityChangedError, isIdentityChangedError } from "../utils/identity-changed-error.js";
+import { createLogger } from "../utils/logger.js";
+import { isFileTypeAllowed } from "../utils/mime-type.js";
+import { getConvexRuntimeConfig } from "../utils/runtime-config.js";
+import {
+  executeFileUpload,
+  isUploadAbortError
+} from "../utils/upload-core.js";
+const INITIAL_UPLOAD_VIEW_STATE = {
+  status: "idle",
+  error: void 0,
+  data: void 0,
+  progress: Object.freeze({ loaded: 0, total: 0, percent: 0 })
+};
+export function useConvexFileUpload(generateUploadUrlMutation, options) {
+  const fnName = getFunctionName(generateUploadUrlMutation);
+  const currentScope = getCurrentScope();
+  assertConvexComposableScope("useConvexFileUpload", import.meta.client, currentScope);
+  const nuxtApp = useNuxtApp();
+  const runtime = readConvexRuntimeContext(nuxtApp);
+  const attachment = runtime?.attachment;
+  const identityObserver = attachment?.identity;
+  const logger = runtime?.logger ?? createLogger(getConvexRuntimeConfig().logging);
+  const getIdentityGeneration = () => identityObserver?.snapshot().identityGeneration ?? 0;
+  const viewState = shallowRef(INITIAL_UPLOAD_VIEW_STATE);
+  let currentAttempt = null;
+  let observedIdentityGeneration = getIdentityGeneration();
+  const status = computed(() => viewState.value.status);
+  const pending = computed(() => viewState.value.status === "pending");
+  const error = computed(() => viewState.value.error);
+  const data = computed(() => viewState.value.data);
+  const progress = computed(() => viewState.value.progress);
+  const clearUploadState = (error2 = new DOMException("Upload cancelled", "AbortError")) => {
+    const attempt = currentAttempt;
+    viewState.value = INITIAL_UPLOAD_VIEW_STATE;
+    if (currentAttempt === attempt) currentAttempt = null;
+    attempt?.abort(error2);
+  };
+  const cancel = clearUploadState;
+  if (currentScope) {
+    const stopIdentitySubscription = identityObserver?.subscribe(() => {
+      const generation = getIdentityGeneration();
+      if (generation === observedIdentityGeneration) return;
+      observedIdentityGeneration = generation;
+      clearUploadState(createIdentityChangedError("upload"));
+    });
+    onScopeDispose(() => {
+      stopIdentitySubscription?.();
+      clearUploadState();
+    });
+  }
+  const upload = async (file, ...mutationArgs) => {
+    const startTime = Date.now();
+    const identityGeneration = getIdentityGeneration();
+    const identityChanged = () => getIdentityGeneration() !== identityGeneration;
+    if (viewState.value.status === "pending") {
+      const err = new ConvexCallError({
+        kind: "unknown",
+        message: "Upload already in progress for this composable instance"
+      });
+      logger.upload({
+        name: fnName,
+        event: "error",
+        filename: file.name,
+        size: file.size,
+        error: err
+      });
+      throw err;
+    }
+    const requireCurrentIdentity = () => {
+      if (identityChanged()) throw createIdentityChangedError("upload");
+    };
+    const publishTerminalState = (next) => {
+      requireCurrentIdentity();
+      viewState.value = next;
+      requireCurrentIdentity();
+    };
+    const publishConvexError = (err) => {
+      publishTerminalState({
+        ...viewState.value,
+        status: "error",
+        error: err
+      });
+      logger.upload({
+        name: fnName,
+        event: "error",
+        filename: file.name,
+        size: file.size,
+        duration: Date.now() - startTime,
+        error: err
+      });
+      requireCurrentIdentity();
+      return err;
+    };
+    const publishError = (rawError) => publishConvexError(normalizeConvexError(rawError));
+    let validationError;
+    if (options?.maxSize && file.size > options.maxSize) {
+      validationError = new ConvexCallError({
+        kind: "unknown",
+        message: `File size ${file.size} bytes exceeds maximum ${options.maxSize} bytes`
+      });
+    } else if (options?.allowedTypes && !isFileTypeAllowed(file.type, options.allowedTypes)) {
+      validationError = new ConvexCallError({
+        kind: "unknown",
+        message: `File type "${file.type}" not allowed. Allowed: ${options.allowedTypes.join(", ")}`
+      });
+    }
+    if (validationError) throw publishConvexError(validationError);
+    if (import.meta.server || !attachment || typeof attachment.client.mutation !== "function") {
+      throw publishConvexError(
+        new ConvexCallError({
+          kind: "unknown",
+          message: "[useConvexFileUpload] Convex client is unavailable. Upload files from the browser after configuring a Convex URL."
+        })
+      );
+    }
+    const attempt = new AbortController();
+    currentAttempt = attempt;
+    const isCurrentUpload = () => currentAttempt === attempt && !identityChanged() && !attempt.signal.aborted;
+    const requireCurrentUpload = () => {
+      requireCurrentIdentity();
+      if (!isCurrentUpload()) throw new DOMException("Upload cancelled", "AbortError");
+    };
+    try {
+      requireCurrentUpload();
+      viewState.value = {
+        ...viewState.value,
+        status: "pending",
+        error: void 0,
+        progress: { loaded: 0, total: file.size, percent: 0 }
+      };
+      requireCurrentUpload();
+      const storageId = await executeFileUpload(
+        attachment.client,
+        generateUploadUrlMutation,
+        mutationArgs[0] ?? {},
+        file,
+        {
+          signal: attempt.signal,
+          onProgress: (info) => {
+            if (!isCurrentUpload()) return;
+            viewState.value = {
+              ...viewState.value,
+              progress: info
+            };
+          }
+        }
+      );
+      requireCurrentUpload();
+      publishTerminalState({
+        ...viewState.value,
+        status: "success",
+        data: storageId
+      });
+      const duration = Date.now() - startTime;
+      logger.upload({
+        name: fnName,
+        event: "success",
+        filename: file.name,
+        size: file.size,
+        duration
+      });
+      requireCurrentIdentity();
+      return storageId;
+    } catch (e) {
+      if (identityChanged() || isIdentityChangedError(e)) {
+        if (currentAttempt === attempt) {
+          clearUploadState(createIdentityChangedError("upload"));
+        }
+        throw isIdentityChangedError(e) ? e : createIdentityChangedError("upload");
+      }
+      if (currentAttempt !== attempt) {
+        throw isUploadAbortError(e) ? e : new DOMException("Upload cancelled", "AbortError");
+      }
+      if (isUploadAbortError(e)) {
+        throw e;
+      }
+      throw publishError(e);
+    } finally {
+      if (currentAttempt === attempt) currentAttempt = null;
+    }
+  };
+  return {
+    upload,
+    data,
+    status,
+    pending,
+    progress,
+    error,
+    cancel
+  };
+}

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

@@ -0,0 +1,13 @@
+import { type UseConvexCall, type UseConvexMutationOptions as VueMutationOptions } from '@lupinum/better-convex-vue';
+import type { OptimisticLocalStore } from 'convex/browser';
+import type { FunctionArgs, FunctionReference } from 'convex/server';
+export type UseConvexMutationOptions<Args extends Record<string, unknown>> = VueMutationOptions<Args>;
+type OptimisticUpdateCandidate<Args> = (store: OptimisticLocalStore, args: Args) => unknown;
+type ReturnHasThen<Result> = Result extends unknown ? 'then' extends keyof Result ? true : false : never;
+type SynchronousOptimisticUpdate<Update extends (...args: never[]) => unknown> = true extends ReturnHasThen<ReturnType<Update>> ? 'Optimistic update handlers must be synchronous' : unknown;
+/** Nuxt auto-import facade over the one shared Vue callable lifecycle. */
+export declare function useConvexMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, options?: UseConvexMutationOptions<FunctionArgs<Mutation>>): UseConvexCall<Mutation>;
+export declare function useConvexMutation<Mutation extends FunctionReference<'mutation'>, Update extends OptimisticUpdateCandidate<FunctionArgs<Mutation>>>(mutation: Mutation, options: Readonly<{
+    optimisticUpdate: Update;
+}> & SynchronousOptimisticUpdate<Update>): UseConvexCall<Mutation>;
+export {};

package/dist/runtime/composables/useConvexMutation.js

@@ -0,0 +1,24 @@
+import {
+  useConvexMutation as useVueConvexMutation
+} from "@lupinum/better-convex-vue";
+import { getFunctionName } from "convex/server";
+import { useNuxtApp } from "#imports";
+import { readConvexRuntimeContext } from "../runtime-context.js";
+import { createCallableDevtoolsEvents } from "../utils/callable-devtools.js";
+import { CALLABLE_OBSERVER_KEY } from "../utils/callable-observer.js";
+export function useConvexMutation(mutation, options) {
+  const runtime = readConvexRuntimeContext(useNuxtApp());
+  const events = createCallableDevtoolsEvents(
+    {
+      operation: "mutation",
+      fnName: getFunctionName(mutation),
+      hasOptimisticUpdate: Boolean(options?.optimisticUpdate),
+      getSink: () => runtime?.getDevtoolsSink() ?? null
+    }
+  );
+  const internalOptions = {
+    ...options,
+    [CALLABLE_OBSERVER_KEY]: events
+  };
+  return useVueConvexMutation(mutation, internalOptions);
+}

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

@@ -0,0 +1,13 @@
+import { type PaginatedQueryArgs, type PaginatedQueryItem, type PaginatedQueryReference, type UseConvexPaginatedQueryOptions, type UseConvexPaginatedQueryState } from '@lupinum/better-convex-vue';
+import { type MaybeRefOrGetter } from 'vue';
+export type { PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference, UseConvexPaginatedQueryState, };
+export interface UseNuxtConvexPaginatedQueryOptions extends UseConvexPaginatedQueryOptions {
+    readonly server?: boolean;
+}
+export type NuxtConvexPaginatedQuery<Item> = UseConvexPaginatedQueryState<Item> & Promise<UseConvexPaginatedQueryState<Item>>;
+interface BuildConvexPaginatedQueryResult<Item> {
+    resultData: UseConvexPaginatedQueryState<Item>;
+    resolvePromise: Promise<void>;
+}
+export declare function createConvexPaginatedQueryState<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: UseNuxtConvexPaginatedQueryOptions, resolveImmediately?: boolean): BuildConvexPaginatedQueryResult<PaginatedQueryItem<Query>>;
+export declare function useConvexPaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: UseNuxtConvexPaginatedQueryOptions): NuxtConvexPaginatedQuery<PaginatedQueryItem<Query>>;