nuxt-convex-module 0.0.0

package/dist/runtime/vue/hydration.d.ts

@@ -0,0 +1,66 @@
+import type { FunctionReference } from 'convex/server';
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
+/**
+ * The preloaded query payload, which should be passed to a client component
+ * and passed to {@link usePreloadedQuery}.
+ *
+ * @public
+ */
+export type Preloaded<Query extends FunctionReference<'query'>> = {
+    __type: Query;
+    _name: string;
+    _argsJSON: string;
+    _valueJSON: string;
+};
+/**
+ * Load a reactive query within a Vue component using a `Preloaded` payload
+ * from the server returned by {@link preloadQuery}.
+ *
+ * This Vue composable contains internal state that will cause a rerender
+ * whenever the query result changes.
+ *
+ * Throws an error if no Convex client has been provided (see {@link useConvex}).
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { usePreloadedQuery } from '#imports'
+ *
+ * const props = defineProps<{
+ *   preloaded: Preloaded<typeof api.tasks.list>
+ * }>()
+ *
+ * const tasks = usePreloadedQuery(props.preloaded)
+ * </script>
+ * ```
+ *
+ * @param preloadedQuery - The `Preloaded` query payload from the server.
+ *   Accepts a ref, computed, or getter; a fresh payload re-subscribes with the
+ *   new query and args.
+ * @returns a computed ref with the result of the query. Initially returns the
+ * result fetched by the server. Subsequently returns the result fetched by the client.
+ *
+ * @public
+ */
+export declare function usePreloadedQuery<Query extends FunctionReference<'query'>>(preloadedQuery: MaybeRefOrGetter<Preloaded<Query>>): ComputedRef<Query['_returnType']>;
+/**
+ * Derive the query reference and reactive args/fallback from a (possibly
+ * reactive) `Preloaded` payload. All three are reactive: swapping in a payload
+ * for a different query re-derives the reference, matching upstream's
+ * `usePreloadedQuery`, which recomputes `makeFunctionReference(_name)` on
+ * every render.
+ *
+ * @internal
+ */
+export declare function usePreloadedPayload<Query extends FunctionReference<'query'>>(preloadedQuery: MaybeRefOrGetter<Preloaded<Query>>): {
+    query: ComputedRef<Query>;
+    args: ComputedRef<Query['_args']>;
+    preloadedResult: ComputedRef<Query['_returnType']>;
+};
+/**
+ * A `useQuery` variant whose query *reference* is reactive alongside its args.
+ * Pass `'skip'` args to pause the subscription.
+ *
+ * @internal
+ */
+export declare function useReactiveQuery<Query extends FunctionReference<'query'>>(query: ComputedRef<Query>, args: ComputedRef<Query['_args'] | 'skip'>): ComputedRef<Query['_returnType'] | undefined>;

package/dist/runtime/vue/hydration.js

@@ -0,0 +1,46 @@
+import { makeFunctionReference } from "convex/server";
+import { jsonToConvex } from "convex/values";
+import { computed, toValue } from "vue";
+import { useConvexQueries } from "./composables/use-queries.js";
+export function usePreloadedQuery(preloadedQuery) {
+  const { query, args, preloadedResult } = usePreloadedPayload(preloadedQuery);
+  if (import.meta.server) {
+    return preloadedResult;
+  }
+  const result = useReactiveQuery(query, args);
+  return computed(
+    () => result.value === void 0 ? preloadedResult.value : result.value
+  );
+}
+export function usePreloadedPayload(preloadedQuery) {
+  const args = computed(
+    () => jsonToConvex(toValue(preloadedQuery)._argsJSON)
+  );
+  const preloadedResult = computed(
+    () => jsonToConvex(toValue(preloadedQuery)._valueJSON)
+  );
+  const query = computed(
+    () => makeFunctionReference(toValue(preloadedQuery)._name)
+  );
+  return { query, args, preloadedResult };
+}
+export function useReactiveQuery(query, args) {
+  const queriesInput = computed(() => {
+    const currentArgs = args.value;
+    if (currentArgs === "skip") {
+      return {};
+    }
+    return {
+      query: {
+        query: query.value,
+        args: currentArgs
+      }
+    };
+  });
+  const allResults = useConvexQueries(queriesInput);
+  return computed(() => {
+    const r = allResults.value.query;
+    if (r instanceof Error) throw r;
+    return r;
+  });
+}

package/dist/runtime/vue/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Tools to integrate Convex into Vue applications.
+ *
+ * This module contains:
+ * 1. {@link ConvexVueClient}, a client for using Convex in Vue.
+ * 2. {@link ConvexClientKey}, an injection key that stores this client in Vue context.
+ * 3. {@link Authenticated}, {@link Unauthenticated}, {@link AuthLoading} and {@link AuthRefreshing} helper auth components.
+ * 4. Composables {@link useQuery}, {@link useMutation}, {@link useAction} and more for accessing this
+ *    client from your Vue components.
+ *
+ * ## Usage
+ *
+ * ### Creating the client
+ *
+ * ```typescript
+ * import { ConvexVueClient } from "nuxt-convex-module/client";
+ *
+ * // typically loaded from an environment variable
+ * const address = "https://small-mouse-123.convex.cloud"
+ * const convex = new ConvexVueClient(address);
+ * ```
+ *
+ * ### Storing the client in Vue context
+ *
+ * ```typescript
+ * import { ConvexClientKey } from "nuxt-convex-module/client";
+ *
+ * // (the Nuxt module registers a plugin that does this automatically)
+ * app.provide(ConvexClientKey, convex);
+ * ```
+ *
+ * ### Using the auth helpers
+ *
+ * ```typescript
+ * import { Authenticated, Unauthenticated, AuthLoading, AuthRefreshing } from "nuxt-convex-module/client";
+ *
+ * <Authenticated>
+ *   Logged in
+ * </Authenticated>
+ * <Unauthenticated>
+ *   Logged out
+ * </Unauthenticated>
+ * <AuthLoading>
+ *   Still loading
+ * </AuthLoading>
+ * <AuthRefreshing>
+ *   Refreshing token...
+ * </AuthRefreshing>
+ * ```
+ *
+ * ### Using Vue composables
+ *
+ * ```typescript
+ * import { useQuery, useMutation } from "nuxt-convex-module/client";
+ * import { api } from "../convex/_generated/api";
+ *
+ * // In your component's <script setup>:
+ * const counter = useQuery(api.getCounter.default);
+ * const increment = useMutation(api.incrementCounter.default);
+ * // Your component here!
+ * ```
+ * @module client
+ */
+export * from './composables/use-paginated-query.js';
+export { usePaginatedQuery_experimental, type UsePaginatedQueryOptions, type UsePaginatedQueryObjectReturnType, } from './composables/use-paginated-query.js';
+export { usePaginatedQuery } from './composables/use-paginated-query.js';
+export { useQueries, type RequestForQueries } from './composables/use-queries.js';
+export type { AuthTokenFetcher } from 'convex/browser';
+export * from './auth/helpers.js';
+export * from './auth/index.js';
+export { usePreloadedQuery, type Preloaded } from './hydration.js';
+export { useSubscription } from './composables/use-subscription.js';
+export { type VueMutation } from './composables/use-mutation.js';
+export { type VueAction } from './composables/use-action.js';
+export { type Watch, type WatchQueryOptions, type MutationOptions, type ConvexVueClientOptions, } from './client.js';
+export { type OptionalRestArgsOrSkip, type UseQueryResult, } from './composables/use-query.js';
+export { ConvexVueClient, useConvex, ConvexClientKey, } from './client.js';
+export { useQuery, useQuery_experimental } from './composables/use-query.js';
+export { useMutation } from './composables/use-mutation.js';
+export { useAction } from './composables/use-action.js';
+export { useConvexConnectionState } from './composables/use-connection-state.js';
+export type { QueryOptions } from 'convex/browser';
+export { useConvexQueries } from './composables/use-queries.js';
+export { useConvexQuery } from './composables/use-query.js';
+export { useConvexMutation } from './composables/use-mutation.js';
+export { useConvexAction } from './composables/use-action.js';
+export { type PaginatedWatch, type VueMutationOptions, type ConvexLogger, } from './client.js';
+export type { ConnectionState, OptimisticUpdate, QueryJournal, } from 'convex/browser';
+export type { FunctionReference, FunctionArgs, FunctionReturnType, OptionalRestArgs, ArgsAndOptions, } from 'convex/server';
+export type { Value } from 'convex/values';
+export { useUpload, useConvexUpload, uploadFile, type VueUpload, type UseUploadOptions, type UploadFileOptions, type GenerateUploadUrl, type StorageId, } from './composables/use-upload.js';
+export { useUploadQueue, useConvexUploadQueue, type VueUploadQueue, type UseUploadQueueOptions, type UploadQueueItem, type UploadItemStatus, } from './composables/use-upload-queue.js';
+export { useStorageUrl, useConvexStorageUrl, type GetStorageUrl, } from './composables/use-storage-url.js';
+export { provideConvexApi, useConvexApi, useConvexNamespace, ConvexApiKey, type ConvexApi, } from './provide.js';

package/dist/runtime/vue/index.js

@@ -0,0 +1,42 @@
+export * from "./composables/use-paginated-query.js";
+export {
+  usePaginatedQuery_experimental
+} from "./composables/use-paginated-query.js";
+export { usePaginatedQuery } from "./composables/use-paginated-query.js";
+export { useQueries } from "./composables/use-queries.js";
+export * from "./auth/helpers.js";
+export * from "./auth/index.js";
+export { usePreloadedQuery } from "./hydration.js";
+export { useSubscription } from "./composables/use-subscription.js";
+export {
+  ConvexVueClient,
+  useConvex,
+  ConvexClientKey
+} from "./client.js";
+export { useQuery, useQuery_experimental } from "./composables/use-query.js";
+export { useMutation } from "./composables/use-mutation.js";
+export { useAction } from "./composables/use-action.js";
+export { useConvexConnectionState } from "./composables/use-connection-state.js";
+export { useConvexQueries } from "./composables/use-queries.js";
+export { useConvexQuery } from "./composables/use-query.js";
+export { useConvexMutation } from "./composables/use-mutation.js";
+export { useConvexAction } from "./composables/use-action.js";
+export {
+  useUpload,
+  useConvexUpload,
+  uploadFile
+} from "./composables/use-upload.js";
+export {
+  useUploadQueue,
+  useConvexUploadQueue
+} from "./composables/use-upload-queue.js";
+export {
+  useStorageUrl,
+  useConvexStorageUrl
+} from "./composables/use-storage-url.js";
+export {
+  provideConvexApi,
+  useConvexApi,
+  useConvexNamespace,
+  ConvexApiKey
+} from "./provide.js";

package/dist/runtime/vue/plugin.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base Convex client bootstrap.
+ *
+ * Creates a {@link ConvexVueClient} from the configured deployment URL and
+ * provides it app-wide (server and client) so the data composables
+ * (`useQuery`, `useMutation`, `useAction`, ...) — and the Clerk / Auth0 auth
+ * adapters — can resolve a client via `useConvex()`.
+ *
+ * This runs only when no auth integration is managing the client. When Better
+ * Auth is installed, its own `plugin.client` / `plugin.server` create and
+ * provide the client (alongside session hydration), so the module registers
+ * those instead of this one — see `registerIntegrations` in `src/module.ts`.
+ *
+ * The WebSocket opens lazily on the first subscription; on the server the
+ * preloaded-query helpers short-circuit, so no socket is opened during SSR.
+ */
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/vue/plugin.js

@@ -0,0 +1,16 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+import { ConvexVueClient, ConvexClientKey } from "./client.js";
+export default defineNuxtPlugin({
+  name: "nuxt-convex-module:client",
+  setup(nuxtApp) {
+    const url = useRuntimeConfig().public.convex.url;
+    if (!url) {
+      if (import.meta.client) {
+        console.warn("[nuxt-convex-module] No Convex URL configured; client not created.");
+      }
+      return;
+    }
+    const client = new ConvexVueClient(url);
+    nuxtApp.vueApp.provide(ConvexClientKey, client);
+  }
+});

package/dist/runtime/vue/provide.d.ts

@@ -0,0 +1,39 @@
+import { type App, type InjectionKey } from 'vue';
+/**
+ * The consumer's generated Convex `api` object (`#convex/api`). Its exact shape
+ * is app-specific, so it's kept loose here — composables and components cast the
+ * namespaces they consume (`api.billing`, `api.email`, …) to the precise
+ * `FunctionReference` types they expect.
+ */
+export type ConvexApi = Record<string, Record<string, unknown>>;
+export declare const ConvexApiKey: InjectionKey<ConvexApi>;
+/**
+ * Make the generated Convex `api` available to every `nuxt-convex-module` composable
+ * and component, so `useBilling()`, `<CheckoutLink>`, `useEmailStatus()`, … work
+ * with zero arguments.
+ *
+ * The packaged Nuxt plugin calls this automatically with `#convex/api`. Call it
+ * yourself (e.g. with a custom `api`) only to override that default — pass the
+ * Nuxt `vueApp` so the binding is available during SSR too:
+ *
+ * ```ts
+ * export default defineNuxtPlugin((nuxtApp) => {
+ *   provideConvexApi(api, nuxtApp.vueApp)
+ * })
+ * ```
+ */
+export declare function provideConvexApi(api: ConvexApi, app?: App): void;
+/**
+ * The injected generated `api`, or `undefined` when it hasn't been provided
+ * (e.g. outside a setup context, or before Convex codegen has run). Prefer
+ * {@link useConvexNamespace} for feature access.
+ */
+export declare function useConvexApi(): ConvexApi | undefined;
+/**
+ * The named function group from the generated `api` (e.g. `'billing'`,
+ * `'email'`), or `undefined` when billing/email isn't scaffolded — letting the
+ * feature degrade to a graceful no-op rather than throwing.
+ *
+ * @typeParam T - The expected shape of the namespace's function references.
+ */
+export declare function useConvexNamespace<T = Record<string, unknown>>(name: string): T | undefined;

package/dist/runtime/vue/provide.js

@@ -0,0 +1,15 @@
+import { hasInjectionContext, inject, provide } from "vue";
+export const ConvexApiKey = Symbol("nuxt-convex-module:api");
+export function provideConvexApi(api, app) {
+  if (app) app.provide(ConvexApiKey, api);
+  else provide(ConvexApiKey, api);
+}
+export function useConvexApi() {
+  if (!hasInjectionContext()) return void 0;
+  return inject(ConvexApiKey, void 0);
+}
+export function useConvexNamespace(name) {
+  const api = useConvexApi();
+  const namespace = api?.[name];
+  return namespace;
+}

package/dist/runtime/vue/queries-observer.d.ts

@@ -0,0 +1,41 @@
+import { type Value } from 'convex/values';
+import type { PaginatedWatch, Watch } from './client.js';
+import type { QueryJournal } from 'convex/browser';
+import { type FunctionReference } from 'convex/server';
+import type { RequestForQueries } from './composables/use-queries.js';
+type PaginatedQueryResult<T> = NonNullable<ReturnType<PaginatedWatch<T>['localQueryResult']>>;
+export interface SubscribeToPaginatedQueryOptions {
+    initialNumItems: number;
+    id: number;
+}
+type Identifier = string;
+export interface CreateWatch {
+    (query: FunctionReference<'query'>, args: Record<string, Value>, options: {
+        journal?: QueryJournal;
+        paginationOptions?: SubscribeToPaginatedQueryOptions;
+    }): Watch<Value> | PaginatedWatch<Value>;
+}
+/**
+ * A class for observing the results of multiple queries at the same time.
+ *
+ * Any time the result of a query changes, the listeners are notified.
+ */
+export declare class QueriesObserver {
+    createWatch: CreateWatch;
+    private queries;
+    private listeners;
+    constructor(createWatch: CreateWatch);
+    setQueries(newQueries: Record<Identifier, {
+        query: FunctionReference<'query'>;
+        args: Record<string, Value>;
+        paginationOptions?: SubscribeToPaginatedQueryOptions;
+    }>): void;
+    subscribe(listener: () => void): () => void;
+    getLocalResults(queries: RequestForQueries): Record<Identifier, Value | undefined | Error | PaginatedQueryResult<Value>>;
+    setCreateWatch(createWatch: CreateWatch): void;
+    destroy(): void;
+    private addQuery;
+    private removeQuery;
+    private notifyListeners;
+}
+export {};

package/dist/runtime/vue/queries-observer.js

@@ -0,0 +1,126 @@
+import { convexToJson } from "convex/values";
+import { getFunctionName } from "convex/server";
+export class QueriesObserver {
+  createWatch;
+  queries;
+  listeners;
+  constructor(createWatch) {
+    this.createWatch = createWatch;
+    this.queries = {};
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  setQueries(newQueries) {
+    for (const identifier of Object.keys(newQueries)) {
+      const { query, args, paginationOptions } = newQueries[identifier];
+      getFunctionName(query);
+      if (this.queries[identifier] === void 0) {
+        this.addQuery(
+          identifier,
+          query,
+          args,
+          paginationOptions ? { paginationOptions } : {}
+        );
+      } else {
+        const existingInfo = this.queries[identifier];
+        if (getFunctionName(query) !== getFunctionName(existingInfo.query) || JSON.stringify(convexToJson(args)) !== JSON.stringify(convexToJson(existingInfo.args)) || JSON.stringify(paginationOptions) !== JSON.stringify(existingInfo.paginationOptions)) {
+          this.removeQuery(identifier);
+          this.addQuery(
+            identifier,
+            query,
+            args,
+            paginationOptions ? { paginationOptions } : {}
+          );
+        }
+      }
+    }
+    for (const identifier of Object.keys(this.queries)) {
+      if (newQueries[identifier] === void 0) {
+        this.removeQuery(identifier);
+      }
+    }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  getLocalResults(queries) {
+    const result = {};
+    for (const identifier of Object.keys(queries)) {
+      const { query, args } = queries[identifier];
+      const paginationOptions = queries[identifier].paginationOptions;
+      getFunctionName(query);
+      const watch = this.createWatch(
+        query,
+        args,
+        paginationOptions ? { paginationOptions } : {}
+      );
+      let value;
+      try {
+        value = watch.localQueryResult();
+      } catch (e) {
+        if (e instanceof Error) {
+          value = e;
+        } else {
+          throw e;
+        }
+      }
+      result[identifier] = value;
+    }
+    return result;
+  }
+  setCreateWatch(createWatch) {
+    this.createWatch = createWatch;
+    for (const identifier of Object.keys(this.queries)) {
+      const { query, args, watch, paginationOptions } = this.queries[identifier];
+      const journal = "journal" in watch ? watch.journal() : void 0;
+      this.removeQuery(identifier);
+      this.addQuery(identifier, query, args, {
+        ...journal ? { journal } : [],
+        ...paginationOptions ? { paginationOptions } : {}
+      });
+    }
+  }
+  destroy() {
+    for (const identifier of Object.keys(this.queries)) {
+      this.removeQuery(identifier);
+    }
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  addQuery(identifier, query, args, {
+    paginationOptions,
+    journal
+  }) {
+    if (this.queries[identifier] !== void 0) {
+      throw new Error(
+        `Tried to add a new query with identifier ${identifier} when it already exists.`
+      );
+    }
+    const watch = this.createWatch(query, args, {
+      ...journal ? { journal } : [],
+      ...paginationOptions ? { paginationOptions } : {}
+    });
+    const unsubscribe = watch.onUpdate(() => this.notifyListeners());
+    this.queries[identifier] = {
+      query,
+      args,
+      watch,
+      unsubscribe,
+      ...paginationOptions ? { paginationOptions } : {}
+    };
+  }
+  removeQuery(identifier) {
+    const info = this.queries[identifier];
+    if (info === void 0) {
+      throw new Error(`No query found with identifier ${identifier}.`);
+    }
+    info.unsubscribe();
+    delete this.queries[identifier];
+  }
+  notifyListeners() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+export { type applyConvexSecurityDefaults, type convexConnectSrc, type convexResourceSrc, type convexTypeFallbackContents, default, type formatStartupSummary, type getConvexAliases, type resolveIntegrationState, type validateModuleOptions } from './module.js'
+
+export { type BetterAuthModuleOptions, type IntegrationFlags, type ModuleOptionDiagnostics, type ModuleOptions } from './module.js'