nuxt-convex-module 0.0.0

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

@@ -0,0 +1,53 @@
+import { makeFunctionReference } from "convex/server";
+import { computed, toValue } from "vue";
+import { useConvexQueries } from "./use-queries.js";
+export function useQuery(query, ...args) {
+  const queryReference = typeof query === "string" ? makeFunctionReference(query) : query;
+  const queries = computed(() => {
+    const rawArgs = toValue(args[0]) ?? {};
+    const skip = rawArgs === "skip";
+    const argsObject = rawArgs === "skip" ? {} : rawArgs;
+    return skip ? {} : { query: { query: queryReference, args: argsObject } };
+  });
+  const results = useConvexQueries(queries);
+  return computed(() => {
+    const result = results.value["query"];
+    if (result instanceof Error) {
+      throw result;
+    }
+    return result;
+  });
+}
+export function useQuery_experimental(options) {
+  const throwOnError = options.throwOnError ?? false;
+  const queryReference = typeof options.query === "string" ? makeFunctionReference(options.query) : options.query;
+  const queries = computed(() => {
+    const rawArgs = toValue(options.args);
+    const skip = rawArgs === "skip";
+    const argsObject = !skip ? rawArgs : {};
+    return skip ? {} : { query: { query: queryReference, args: argsObject } };
+  });
+  const results = useConvexQueries(queries);
+  return computed(() => {
+    const result = results.value["query"];
+    if (result instanceof Error) {
+      if (throwOnError) {
+        throw result;
+      }
+      return {
+        error: result,
+        status: "error"
+      };
+    }
+    if (result === void 0) {
+      return {
+        status: "pending"
+      };
+    }
+    return {
+      data: result,
+      status: "success"
+    };
+  });
+}
+export const useConvexQuery = useQuery;

package/dist/runtime/vue/composables/use-storage-url.d.ts

@@ -0,0 +1,46 @@
+import type { FunctionReference } from 'convex/server';
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import type { StorageId } from './use-upload.js';
+/**
+ * A `getUrl` query: takes `{ storageId }` and returns the file's served URL,
+ * or `null` if the file no longer exists (`await ctx.storage.getUrl(id)`).
+ *
+ * @public
+ */
+export type GetStorageUrl = FunctionReference<'query', 'public', {
+    storageId: StorageId;
+}, string | null>;
+/**
+ * Reactively resolve the served URL for a Convex stored file.
+ *
+ * Thin wrapper over {@link useQuery} that handles the common ergonomics of
+ * serving stored files: it accepts a reactive storage id and automatically
+ * skips the query (returning `undefined`) while the id is `null`/`undefined`,
+ * so you can bind it straight to an id ref without juggling `'skip'`.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useStorageUrl } from '#imports'
+ * import { api } from '#convex/api'
+ *
+ * const { storageId } = useUpload(api.images.generateUploadUrl)
+ * const url = useStorageUrl(api.images.getUrl, storageId)
+ * </script>
+ *
+ * <template>
+ *   <img v-if="url" :src="url">
+ * </template>
+ * ```
+ *
+ * @param getUrl - A `FunctionReference` for the public `getUrl` query.
+ * @param storageId - The storage id to resolve. Accepts a ref, computed, or
+ *   getter; `null`/`undefined` skips the query.
+ * @returns A computed ref of the served URL: `string | null` once loaded
+ *   (`null` if the file is gone), or `undefined` while loading or skipped.
+ *
+ * @public
+ */
+export declare function useStorageUrl(getUrl: GetStorageUrl, storageId: MaybeRefOrGetter<StorageId | string | null | undefined>): ComputedRef<string | null | undefined>;
+/** @public */
+export declare const useConvexStorageUrl: typeof useStorageUrl;

package/dist/runtime/vue/composables/use-storage-url.js

@@ -0,0 +1,9 @@
+import { toValue } from "vue";
+import { useQuery } from "./use-query.js";
+export function useStorageUrl(getUrl, storageId) {
+  return useQuery(getUrl, () => {
+    const id = toValue(storageId);
+    return id ? { storageId: id } : "skip";
+  });
+}
+export const useConvexStorageUrl = useStorageUrl;

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

@@ -0,0 +1,15 @@
+import { type ShallowRef } from 'vue';
+/**
+ * Composable used for safely managing subscriptions in concurrent mode.
+ *
+ * In order to avoid removing and re-adding subscriptions each time this composable is called,
+ * the parameters passed to this composable should be memoized in some way–
+ * either by wrapping the entire params object with useMemo()
+ * or by wrapping the individual callbacks with useCallback().
+ *
+ * @internal
+ */
+export declare function useSubscription<Value>({ getCurrentValue, subscribe, }: {
+    getCurrentValue: () => Value;
+    subscribe: (callback: () => void) => () => void;
+}): ShallowRef<Value>;

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

@@ -0,0 +1,33 @@
+import { shallowRef, watchEffect } from "vue";
+export function useSubscription({
+  // (Synchronously) returns the current value of our subscription.
+  getCurrentValue,
+  // This function is passed an event handler to attach to the subscription.
+  // It should return an unsubscribe function that removes the handler.
+  subscribe
+}) {
+  const state = shallowRef(getCurrentValue());
+  watchEffect((onCleanup) => {
+    if (import.meta.server) {
+      return;
+    }
+    let didUnsubscribe = false;
+    const checkForUpdates = () => {
+      if (didUnsubscribe) {
+        return;
+      }
+      const value = getCurrentValue();
+      if (state.value === value) {
+        return;
+      }
+      state.value = value;
+    };
+    const unsubscribe = subscribe(checkForUpdates);
+    checkForUpdates();
+    onCleanup(() => {
+      didUnsubscribe = true;
+      unsubscribe();
+    });
+  });
+  return state;
+}

package/dist/runtime/vue/composables/use-upload-queue.d.ts

@@ -0,0 +1,117 @@
+import { type Ref } from 'vue';
+import { type GenerateUploadUrl, type StorageId } from './use-upload.js';
+/**
+ * Lifecycle status of a single item in an upload queue.
+ *
+ * @public
+ */
+export type UploadItemStatus = 'pending' | 'uploading' | 'success' | 'error';
+/**
+ * A single entry in the queue managed by {@link useUploadQueue}.
+ *
+ * @public
+ */
+export interface UploadQueueItem {
+    /** Stable id for this queue entry (not the storage id). */
+    id: string;
+    /** The file or blob being uploaded. */
+    file: Blob;
+    /** Current upload status. */
+    status: UploadItemStatus;
+    /** Upload progress for this item, from `0` to `1`. */
+    progress: number;
+    /** The storage id once the upload succeeds, or `null`. */
+    storageId: StorageId | null;
+    /** The error if this item failed, or `null`. */
+    error: Error | null;
+}
+/**
+ * Options for {@link useUploadQueue}.
+ *
+ * @public
+ */
+export interface UseUploadQueueOptions {
+    /** Maximum number of uploads to run at once. Defaults to `3`. */
+    concurrency?: number;
+    /** Called when an individual item finishes uploading. */
+    onItemSuccess?: (storageId: StorageId, item: UploadQueueItem) => void | Promise<void>;
+    /** Called when an individual item fails. */
+    onItemError?: (error: Error, item: UploadQueueItem) => void;
+    /** Called once every queued item has settled (succeeded or failed). */
+    onComplete?: (items: UploadQueueItem[]) => void;
+}
+/** Accepted inputs to {@link VueUploadQueue.enqueue}. */
+type EnqueueInput = Blob | Blob[] | FileList | null | undefined;
+/**
+ * The reactive queue returned by {@link useUploadQueue}.
+ *
+ * @public
+ */
+export interface VueUploadQueue {
+    /** Reactive list of queued items, in insertion order. */
+    items: Readonly<Ref<UploadQueueItem[]>>;
+    /** Add one or more files to the queue; uploading starts automatically. */
+    enqueue: (files: EnqueueInput) => void;
+    /** `true` while any item is pending or uploading. */
+    isUploading: Readonly<Ref<boolean>>;
+    /** Aggregate progress across all items, from `0` to `1`. */
+    progress: Readonly<Ref<number>>;
+    /** Number of items waiting to start. */
+    pendingCount: Readonly<Ref<number>>;
+    /** Number of items currently uploading. */
+    activeCount: Readonly<Ref<number>>;
+    /** Abort all in-flight uploads (queued items stay `pending`). */
+    cancel: () => void;
+    /** Remove an item by id, aborting it first if it is uploading. */
+    remove: (id: string) => void;
+    /** Abort everything and empty the queue. */
+    clear: () => void;
+}
+/**
+ * Upload many files to Convex file storage with bounded concurrency and
+ * per-item reactive progress.
+ *
+ * Built on the same flow as {@link useUpload}, but manages a queue: call
+ * {@link VueUploadQueue.enqueue} with one or more files (or a `FileList` from
+ * a multi-file `<input>`) and the queue uploads up to `concurrency` at a time,
+ * exposing per-item and aggregate progress.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useUploadQueue, useMutation } from '#imports'
+ * import { api } from '#convex/api'
+ *
+ * const saveImage = useMutation(api.images.save)
+ * const { items, enqueue, progress, isUploading } = useUploadQueue(
+ *   api.images.generateUploadUrl,
+ *   { concurrency: 4, onItemSuccess: storageId => saveImage({ storageId }) },
+ * )
+ *
+ * function onPick(event: Event) {
+ *   enqueue((event.target as HTMLInputElement).files)
+ * }
+ * </script>
+ *
+ * <template>
+ *   <input type="file" multiple @change="onPick">
+ *   <progress v-if="isUploading" :value="progress" />
+ *   <ul>
+ *     <li v-for="item in items" :key="item.id">
+ *       {{ item.status }} — {{ Math.round(item.progress * 100) }}%
+ *     </li>
+ *   </ul>
+ * </template>
+ * ```
+ *
+ * @param generateUploadUrl - A `FunctionReference` for the public
+ *   `generateUploadUrl` mutation.
+ * @param options - Optional {@link UseUploadQueueOptions}.
+ * @returns A {@link VueUploadQueue}.
+ *
+ * @public
+ */
+export declare function useUploadQueue(generateUploadUrl: GenerateUploadUrl, options?: UseUploadQueueOptions): VueUploadQueue;
+/** @public */
+export declare const useConvexUploadQueue: typeof useUploadQueue;
+export {};

package/dist/runtime/vue/composables/use-upload-queue.js

@@ -0,0 +1,115 @@
+import { computed, ref } from "vue";
+import { useConvexOrThrow } from "../client.js";
+import { uploadFile } from "./use-upload.js";
+function normalizeFiles(input) {
+  if (!input) return [];
+  if (input instanceof Blob) return [input];
+  if (Array.isArray(input)) return input;
+  return Array.from(input);
+}
+let queueItemId = 0;
+function nextQueueItemId() {
+  return `upload-${++queueItemId}`;
+}
+export function useUploadQueue(generateUploadUrl, options = {}) {
+  const convex = useConvexOrThrow("useUploadQueue");
+  const concurrency = Math.max(1, Math.floor(options.concurrency ?? 3));
+  const items = ref([]);
+  const controllers = /* @__PURE__ */ new Map();
+  const activeCount = computed(
+    () => items.value.filter((item) => item.status === "uploading").length
+  );
+  const pendingCount = computed(
+    () => items.value.filter((item) => item.status === "pending").length
+  );
+  const isUploading = computed(() => activeCount.value > 0 || pendingCount.value > 0);
+  const progress = computed(() => {
+    if (items.value.length === 0) return 0;
+    const total = items.value.reduce((sum, item) => sum + item.progress, 0);
+    return total / items.value.length;
+  });
+  function pump() {
+    if (typeof XMLHttpRequest === "undefined") return;
+    let slots = concurrency - activeCount.value;
+    for (const item of items.value) {
+      if (slots <= 0) break;
+      if (item.status !== "pending") continue;
+      slots--;
+      void run(item);
+    }
+  }
+  async function run(item) {
+    item.status = "uploading";
+    const controller = new AbortController();
+    controllers.set(item.id, controller);
+    try {
+      const url = await convex.mutation(generateUploadUrl, {});
+      const storageId = await uploadFile({
+        url,
+        file: item.file,
+        signal: controller.signal,
+        onProgress: (value) => {
+          item.progress = value;
+        }
+      });
+      item.storageId = storageId;
+      item.progress = 1;
+      item.status = "success";
+      await options.onItemSuccess?.(storageId, item);
+    } catch (caught) {
+      const failure = caught instanceof Error ? caught : new Error(String(caught));
+      item.error = failure;
+      item.status = "error";
+      options.onItemError?.(failure, item);
+    } finally {
+      controllers.delete(item.id);
+      if (pendingCount.value === 0 && activeCount.value === 0) {
+        options.onComplete?.(items.value);
+      } else {
+        pump();
+      }
+    }
+  }
+  function enqueue(files) {
+    const incoming = normalizeFiles(files);
+    if (incoming.length === 0) return;
+    items.value.push(
+      ...incoming.map((file) => ({
+        id: nextQueueItemId(),
+        file,
+        status: "pending",
+        progress: 0,
+        storageId: null,
+        error: null
+      }))
+    );
+    pump();
+  }
+  function cancel() {
+    for (const controller of controllers.values()) {
+      controller.abort();
+    }
+  }
+  function remove(id) {
+    controllers.get(id)?.abort();
+    controllers.delete(id);
+    items.value = items.value.filter((item) => item.id !== id);
+  }
+  function clear() {
+    cancel();
+    controllers.clear();
+    items.value = [];
+  }
+  return {
+    items,
+    enqueue,
+    isUploading,
+    progress,
+    pendingCount,
+    activeCount,
+    cancel,
+    remove,
+    clear
+  };
+}
+export const useConvexUploadQueue = useUploadQueue;

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

@@ -0,0 +1,134 @@
+import type { FunctionReference } from 'convex/server';
+import type { GenericId } from 'convex/values';
+import { type Ref } from 'vue';
+/**
+ * A `generateUploadUrl` mutation: takes no arguments and returns a one-time
+ * Convex upload URL string (`await ctx.storage.generateUploadUrl()`).
+ *
+ * @public
+ */
+export type GenerateUploadUrl = FunctionReference<'mutation', 'public', Record<string, never>, string>;
+/**
+ * A Convex file storage id (`Id<'_storage'>`), branded so it is directly
+ * assignable to mutation/query args validated with `v.id('_storage')`.
+ *
+ * @public
+ */
+export type StorageId = GenericId<'_storage'>;
+/**
+ * Options for the low-level {@link uploadFile} helper.
+ *
+ * @public
+ */
+export interface UploadFileOptions {
+    /** The one-time Convex upload URL from a `generateUploadUrl` mutation. */
+    url: string;
+    /** The file or blob to upload. */
+    file: Blob;
+    /** Receives upload progress as a fraction from `0` to `1`. */
+    onProgress?: (progress: number) => void;
+    /** Abort signal to cancel the in-flight upload. */
+    signal?: AbortSignal;
+}
+/**
+ * Upload a single file to a Convex upload URL, resolving to its storage id.
+ *
+ * Low-level building block used by {@link useUpload} and
+ * {@link useUploadQueue}. Uses `XMLHttpRequest` so real upload progress and
+ * cancellation are available — `fetch` cannot report request-body progress.
+ *
+ * Browser-only: throws if no `XMLHttpRequest` global is available (e.g. during
+ * SSR).
+ *
+ * @param options - {@link UploadFileOptions}.
+ * @returns A promise of the new {@link StorageId}.
+ *
+ * @public
+ */
+export declare function uploadFile(options: UploadFileOptions): Promise<StorageId>;
+/**
+ * Options for {@link useUpload}.
+ *
+ * @public
+ */
+export interface UseUploadOptions {
+    /** Called with upload progress as a fraction from `0` to `1`. */
+    onProgress?: (progress: number) => void;
+    /** Called once the file is stored, with the new storage id and the file. */
+    onSuccess?: (storageId: StorageId, file: Blob) => void | Promise<void>;
+    /** Called if generating the upload URL or the upload itself fails. */
+    onError?: (error: Error, file: Blob) => void;
+}
+/**
+ * The reactive uploader returned by {@link useUpload}.
+ *
+ * @public
+ */
+export interface VueUpload {
+    /**
+     * Upload a file or blob, resolving to its {@link StorageId}.
+     *
+     * Resolves to `null` (instead of throwing) if the upload fails or is called
+     * outside the browser — inspect {@link VueUpload.error} for the reason.
+     */
+    upload: (file: Blob) => Promise<StorageId | null>;
+    /** `true` while an upload is in flight. */
+    isUploading: Readonly<Ref<boolean>>;
+    /** Upload progress of the current/last upload, from `0` to `1`. */
+    progress: Readonly<Ref<number>>;
+    /** The error from the most recent failed upload, or `null`. */
+    error: Readonly<Ref<Error | null>>;
+    /** The storage id from the most recent successful upload, or `null`. */
+    storageId: Readonly<Ref<StorageId | null>>;
+    /** Abort the in-flight upload, if any. */
+    cancel: () => void;
+    /** Reset `progress`, `error`, and `storageId` back to their initial values. */
+    reset: () => void;
+}
+/**
+ * Upload files to Convex file storage from a component, with reactive
+ * progress, error, and cancellation state.
+ *
+ * Wraps the standard Convex flow — call a `generateUploadUrl` mutation, `POST`
+ * the file to the returned URL, and read back the storage id — and exposes it
+ * as reactive refs. Pass the resulting {@link StorageId} to your own mutation
+ * to persist it in your data model.
+ *
+ * Uploads are client-only: calling `upload()` during SSR resolves to `null`
+ * and sets {@link VueUpload.error}.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useUpload, useMutation } from '#imports'
+ * import { api } from '#convex/api'
+ *
+ * const saveImage = useMutation(api.images.save)
+ * const { upload, isUploading, progress, error } = useUpload(
+ *   api.images.generateUploadUrl,
+ *   { onSuccess: storageId => saveImage({ storageId }) },
+ * )
+ *
+ * async function onPick(event: Event) {
+ *   const file = (event.target as HTMLInputElement).files?.[0]
+ *   if (file) await upload(file)
+ * }
+ * </script>
+ *
+ * <template>
+ *   <input type="file" :disabled="isUploading" @change="onPick">
+ *   <progress v-if="isUploading" :value="progress" />
+ *   <p v-if="error">{{ error.message }}</p>
+ * </template>
+ * ```
+ *
+ * @param generateUploadUrl - A `FunctionReference` for the public
+ *   `generateUploadUrl` mutation.
+ * @param options - Optional {@link UseUploadOptions} callbacks.
+ * @returns A {@link VueUpload}.
+ *
+ * @public
+ */
+export declare function useUpload(generateUploadUrl: GenerateUploadUrl, options?: UseUploadOptions): VueUpload;
+/** @public */
+export declare const useConvexUpload: typeof useUpload;

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

@@ -0,0 +1,114 @@
+import { ref, shallowRef } from "vue";
+import { useConvexOrThrow } from "../client.js";
+export function uploadFile(options) {
+  const { url, file, onProgress, signal } = options;
+  if (typeof XMLHttpRequest === "undefined") {
+    return Promise.reject(
+      new Error("uploadFile can only run in the browser (no XMLHttpRequest available).")
+    );
+  }
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("Upload aborted.", "AbortError"));
+      return;
+    }
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", url, true);
+    if (file.type) {
+      xhr.setRequestHeader("Content-Type", file.type);
+    }
+    const onAbort = () => xhr.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    xhr.upload.onprogress = (event) => {
+      if (event.lengthComputable && event.total > 0) {
+        onProgress?.(event.loaded / event.total);
+      }
+    };
+    xhr.onload = () => {
+      cleanup();
+      if (xhr.status >= 200 && xhr.status < 300) {
+        try {
+          const { storageId } = JSON.parse(xhr.responseText);
+          onProgress?.(1);
+          resolve(storageId);
+        } catch {
+          reject(new Error(`Convex upload returned an unexpected response: ${xhr.responseText}`));
+        }
+      } else {
+        reject(new Error(`Convex upload failed with status ${xhr.status}: ${xhr.responseText}`));
+      }
+    };
+    xhr.onerror = () => {
+      cleanup();
+      reject(new Error("Network error during Convex file upload."));
+    };
+    xhr.onabort = () => {
+      cleanup();
+      reject(new DOMException("Upload aborted.", "AbortError"));
+    };
+    xhr.send(file);
+  });
+}
+export function useUpload(generateUploadUrl, options = {}) {
+  const convex = useConvexOrThrow("useUpload");
+  const isUploading = ref(false);
+  const progress = ref(0);
+  const error = shallowRef(null);
+  const storageId = shallowRef(null);
+  let controller = null;
+  async function upload(file) {
+    if (typeof XMLHttpRequest === "undefined") {
+      const browserOnly = new Error("useUpload().upload() can only run in the browser.");
+      error.value = browserOnly;
+      options.onError?.(browserOnly, file);
+      return null;
+    }
+    controller = new AbortController();
+    isUploading.value = true;
+    progress.value = 0;
+    error.value = null;
+    try {
+      const url = await convex.mutation(generateUploadUrl, {});
+      const id = await uploadFile({
+        url,
+        file,
+        signal: controller.signal,
+        onProgress: (value) => {
+          progress.value = value;
+          options.onProgress?.(value);
+        }
+      });
+      storageId.value = id;
+      progress.value = 1;
+      await options.onSuccess?.(id, file);
+      return id;
+    } catch (caught) {
+      const failure = caught instanceof Error ? caught : new Error(String(caught));
+      error.value = failure;
+      options.onError?.(failure, file);
+      return null;
+    } finally {
+      isUploading.value = false;
+      controller = null;
+    }
+  }
+  function cancel() {
+    controller?.abort();
+  }
+  function reset() {
+    progress.value = 0;
+    error.value = null;
+    storageId.value = null;
+  }
+  return {
+    upload,
+    isUploading,
+    progress,
+    error,
+    storageId,
+    cancel,
+    reset
+  };
+}
+export const useConvexUpload = useUpload;