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

package/dist/runtime/composables/useConvexPaginatedQuery.js

@@ -0,0 +1,256 @@
+import {
+  useConvexPaginatedQuery as useVuePaginatedQuery
+} from "@lupinum/better-convex-vue";
+import { computed, onScopeDispose, ref, toValue, watch } from "vue";
+import { useAsyncData, useNuxtApp, useRequestEvent, useState } from "#imports";
+import { identityToken } from "../auth/auth-identity.js";
+import { ConvexCallError, normalizeConvexError } from "../errors/index.js";
+import { readConvexRuntimeContext } from "../runtime-context.js";
+import { useConvexIdentityState } from "../utils/auth-identity-state.js";
+import {
+  fetchAuthToken,
+  matchesConvexHydrationIdentity,
+  withAuthDimension
+} from "../utils/convex-cache.js";
+import { createConvexQueryKey, getFunctionName } from "../utils/convex-shared.js";
+import { executeQueryHttp } from "../utils/query-execution.js";
+import { createQueryExecutionGate } from "../utils/query-execution-gate.js";
+import { createConvexQueryAuthContext } from "../utils/query-foundation.js";
+import { normalizeConvexReactiveArgs } from "../utils/reactive-args.js";
+import { getConvexRuntimeConfig } from "../utils/runtime-config.js";
+import { isIncompletePaginationPage } from "../utils/ssr-pagination-state.js";
+function asNativeNuxtPromise(state, resolvePromise) {
+  const awaitedState = Object.freeze({ ...state });
+  const promise = resolvePromise.then(
+    () => awaitedState,
+    () => awaitedState
+  );
+  void Object.assign(promise, state);
+  void Object.defineProperties(promise, {
+    then: { enumerable: true, value: promise.then.bind(promise) },
+    catch: { enumerable: true, value: promise.catch.bind(promise) },
+    finally: { enumerable: true, value: promise.finally.bind(promise) }
+  });
+  return promise;
+}
+export function createConvexPaginatedQueryState(query, args, options, resolveImmediately = false) {
+  const config = getConvexRuntimeConfig();
+  const initialNumItems = options.initialNumItems;
+  if (!Number.isSafeInteger(initialNumItems) || initialNumItems < 1) {
+    throw new Error("[better-convex-nuxt] initialNumItems must be a positive safe integer");
+  }
+  const server = options.server ?? true;
+  const auth = options.auth ?? "optional";
+  if (import.meta.client) {
+    const authContext2 = createConvexQueryAuthContext();
+    const currentBoundary = computed(() => {
+      const currentArgs2 = normalizeConvexReactiveArgs(toValue(args));
+      const gate2 = createQueryExecutionGate({
+        authStatus: authContext2.status.value,
+        authMode: auth,
+        identityKey: authContext2.identityKey.value,
+        skipped: currentArgs2 === "skip"
+      });
+      const key2 = gate2.outcome === "execute" ? withAuthDimension(
+        createConvexQueryKey(
+          query,
+          {
+            ...currentArgs2,
+            paginationOpts: { numItems: initialNumItems, cursor: null }
+          },
+          "convex-paginated"
+        ),
+        auth,
+        gate2.cacheIdentity
+      ) : `convex-paginated:${gate2.outcome}:${getFunctionName(query)}`;
+      return { gate: gate2, key: key2 };
+    });
+    const hydrationBoundary = currentBoundary.value;
+    const hydrationKey = hydrationBoundary.key;
+    const nuxtApp = useNuxtApp();
+    const runtime = readConvexRuntimeContext(nuxtApp);
+    const hydrationIdentityMatches = hydrationBoundary.gate.outcome === "execute" && matchesConvexHydrationIdentity(
+      auth,
+      hydrationBoundary.gate.cacheIdentity,
+      runtime?.attachment.identity.snapshot()
+    );
+    const hydrationRetired = ref(false);
+    const matchesHydrationBoundary = () => {
+      const boundary = currentBoundary.value;
+      return hydrationIdentityMatches && boundary.key === hydrationKey && boundary.gate.outcome === "execute" && matchesConvexHydrationIdentity(
+        auth,
+        boundary.gate.cacheIdentity,
+        runtime?.attachment.identity.snapshot()
+      );
+    };
+    const hydrationBoundaryMatches = computed(
+      () => !hydrationRetired.value && matchesHydrationBoundary()
+    );
+    const stopHydrationBoundaryRetirement = watch(
+      currentBoundary,
+      () => {
+        if (!matchesHydrationBoundary()) hydrationRetired.value = true;
+      },
+      { flush: "sync" }
+    );
+    const hydrated = hydrationIdentityMatches && Object.hasOwn(nuxtApp.payload.data, hydrationKey) ? nuxtApp.payload.data[hydrationKey] : void 0;
+    const hasHydratedPage = hydrated !== null && hydrated !== void 0;
+    const hydratedErrors = useState(
+      "convex:query-errors",
+      () => ({})
+    );
+    let firstPageSettled = Promise.resolve();
+    const result = Reflect.apply(useVuePaginatedQuery, void 0, [
+      query,
+      args,
+      { initialNumItems, auth, keepPreviousData: options.keepPreviousData },
+      {
+        initialPage: hasHydratedPage ? hydrated : void 0,
+        onFirstPageSettled(promise) {
+          firstPageSettled = promise;
+        }
+      }
+    ]);
+    const clearHydratedError = () => {
+      if (!(hydrationKey in hydratedErrors.value)) return;
+      const { [hydrationKey]: _removed, ...rest } = hydratedErrors.value;
+      hydratedErrors.value = rest;
+    };
+    const stopHydratedErrorReconciliation = watch(
+      [result.error, result.status, hydrationBoundaryMatches],
+      ([liveError, liveStatus, boundaryMatches]) => {
+        if (boundaryMatches && (liveError || liveStatus !== "pending")) clearHydratedError();
+      },
+      { flush: "sync" }
+    );
+    onScopeDispose(() => {
+      stopHydrationBoundaryRetirement();
+      stopHydratedErrorReconciliation();
+    });
+    const error2 = computed(
+      () => result.error.value ?? (hydrationBoundaryMatches.value ? hydratedErrors.value[hydrationKey] : void 0) ?? void 0
+    );
+    const status2 = computed(
+      () => error2.value ? "error" : result.status.value
+    );
+    const isLoading = computed(() => status2.value === "pending");
+    const resultData2 = Object.freeze({
+      ...result,
+      error: error2,
+      status: status2,
+      isLoading
+    });
+    return {
+      resultData: resultData2,
+      resolvePromise: resolveImmediately || !server || hasHydratedPage || error2.value !== void 0 || status2.value === "idle" ? Promise.resolve() : firstPageSettled
+    };
+  }
+  const authContext = createConvexQueryAuthContext();
+  const currentArgs = computed(
+    () => normalizeConvexReactiveArgs(toValue(args))
+  );
+  const gate = computed(
+    () => createQueryExecutionGate({
+      authStatus: authContext.status.value,
+      authMode: auth,
+      identityKey: authContext.identityKey.value,
+      skipped: currentArgs.value === "skip"
+    })
+  );
+  const key = computed(() => {
+    if (gate.value.outcome !== "execute") {
+      return `convex-paginated:${gate.value.outcome}:${getFunctionName(query)}`;
+    }
+    return withAuthDimension(
+      createConvexQueryKey(
+        query,
+        {
+          ...currentArgs.value,
+          paginationOpts: { numItems: initialNumItems, cursor: null }
+        },
+        "convex-paginated"
+      ),
+      auth,
+      gate.value.cacheIdentity
+    );
+  });
+  const errors = useState("convex:query-errors", () => ({}));
+  const event = useRequestEvent();
+  const identity = useConvexIdentityState();
+  const cachedToken = computed(() => identityToken(identity.value));
+  const asyncData = useAsyncData(
+    key,
+    async () => {
+      const decision = gate.value;
+      if (decision.outcome !== "execute") return null;
+      if (!config.url) return null;
+      try {
+        const token = fetchAuthToken({
+          auth,
+          cookieHeader: event?.headers.get("cookie") ?? "",
+          cachedToken
+        });
+        if (auth !== "none" && decision.cacheIdentity !== "anonymous" && !token) return null;
+        const value = await executeQueryHttp(
+          config.url,
+          getFunctionName(query),
+          {
+            ...currentArgs.value,
+            paginationOpts: { numItems: initialNumItems, cursor: null }
+          },
+          token,
+          event?.web?.request?.signal
+        );
+        if (isIncompletePaginationPage(value)) {
+          throw new ConvexCallError({
+            kind: "unknown",
+            code: "PAGINATION_SPLIT_REQUIRED",
+            message: "Convex pagination page requires a bounded live split"
+          });
+        }
+        const { [key.value]: _removed, ...rest } = errors.value;
+        errors.value = rest;
+        return value;
+      } catch (error2) {
+        errors.value = {
+          ...errors.value,
+          [key.value]: normalizeConvexError(error2)
+        };
+        return null;
+      }
+    },
+    { server, lazy: resolveImmediately, deep: false }
+  );
+  const data = computed(() => asyncData.data.value?.page);
+  const error = computed(
+    () => errors.value[key.value] ?? (gate.value.outcome === "error" ? authContext.error.value ?? normalizeConvexError(new Error("Authentication failed before the query could execute")) : void 0) ?? void 0
+  );
+  const status = computed(() => {
+    if (error.value) return "error";
+    if (gate.value.outcome === "idle") return "idle";
+    if (gate.value.outcome === "wait" || asyncData.pending.value) return "pending";
+    return asyncData.data.value === null ? "pending" : "success";
+  });
+  const resultData = Object.freeze({
+    data,
+    status,
+    isLoading: computed(() => status.value === "pending"),
+    isStale: computed(() => false),
+    canLoadMore: computed(
+      () => status.value === "success" && asyncData.data.value?.isDone === false
+    ),
+    loadMore: () => {
+    },
+    error,
+    refresh: asyncData.refresh
+  });
+  return {
+    resultData,
+    resolvePromise: server && gate.value.outcome !== "idle" ? Promise.resolve(asyncData).then(() => {
+    }) : Promise.resolve()
+  };
+}
+export function useConvexPaginatedQuery(query, args, options) {
+  const result = createConvexPaginatedQueryState(query, args, options);
+  return asNativeNuxtPromise(result.resultData, result.resolvePromise);
+}

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

@@ -0,0 +1,19 @@
+import { type ConvexAuthMode, type UseConvexQueryOptions, type UseConvexQueryParameters, type UseConvexQueryState } from '@lupinum/better-convex-vue';
+import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
+import { type MaybeRefOrGetter } from 'vue';
+import type { ConvexCallStatus } from '../utils/types.js';
+export type { ConvexAuthMode, ConvexCallStatus };
+export type ConvexQuerySkip = 'skip';
+export type ConvexQueryArgs<Args> = Args | ConvexQuerySkip;
+export interface UseNuxtConvexQueryOptions extends UseConvexQueryOptions {
+    /** Disable the SSR fetch for a genuinely browser-only query. */
+    readonly server?: boolean;
+}
+export type { UseConvexQueryOptions, UseConvexQueryParameters, UseConvexQueryState };
+export type NuxtConvexQuery<Data> = UseConvexQueryState<Data> & Promise<UseConvexQueryState<Data>>;
+interface BuildConvexQueryResult<DataT> {
+    resultData: UseConvexQueryState<DataT>;
+    resolvePromise: Promise<void>;
+}
+export declare function createConvexQueryState<Query extends FunctionReference<'query'>, Args extends ConvexQueryArgs<FunctionArgs<Query>> = FunctionArgs<Query>>(query: Query, args: MaybeRefOrGetter<Args>, options?: UseNuxtConvexQueryOptions): BuildConvexQueryResult<FunctionReturnType<Query>>;
+export declare function useConvexQuery<Query extends FunctionReference<'query'>>(query: Query, ...parameters: UseConvexQueryParameters<Query, UseNuxtConvexQueryOptions>): NuxtConvexQuery<FunctionReturnType<Query>>;

package/dist/runtime/composables/useConvexQuery.js

@@ -0,0 +1,308 @@
+import {
+  useConvexQuery as useVueConvexQuery
+} from "@lupinum/better-convex-vue";
+import {
+  computed,
+  onScopeDispose,
+  ref,
+  toValue,
+  watch
+} from "vue";
+import { useAsyncData, useNuxtApp, useRequestEvent, useState } from "#imports";
+import { identityToken } from "../auth/auth-identity.js";
+import { ConvexCallError, normalizeConvexError } from "../errors/index.js";
+import { readConvexRuntimeContext } from "../runtime-context.js";
+import { useConvexIdentityState } from "../utils/auth-identity-state.js";
+import {
+  fetchAuthToken,
+  matchesConvexHydrationIdentity,
+  withAuthDimension
+} from "../utils/convex-cache.js";
+import { computeQueryStatus, createConvexQueryKey, getFunctionName } from "../utils/convex-shared.js";
+import { executeQueryHttp } from "../utils/query-execution.js";
+import { createQueryExecutionGate } from "../utils/query-execution-gate.js";
+import { createConvexQueryAuthContext } from "../utils/query-foundation.js";
+import { computeConvexQueryPending } from "../utils/query-state.js";
+import { normalizeConvexReactiveArgs } from "../utils/reactive-args.js";
+import { getConvexRuntimeConfig } from "../utils/runtime-config.js";
+function waitForClientTerminal(status) {
+  if (status.value !== "pending") return Promise.resolve();
+  return new Promise((resolve) => {
+    let settled = false;
+    let stop = () => {
+    };
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      stop();
+      resolve();
+    };
+    stop = watch(
+      status,
+      (value) => {
+        if (value === "pending") return;
+        finish();
+      },
+      { flush: "sync" }
+    );
+    onScopeDispose(finish);
+  });
+}
+function asNuxtConvexQuery(state, initialSettlement) {
+  const awaitedState = Object.freeze({ ...state });
+  const promise = initialSettlement.then(
+    () => awaitedState,
+    () => awaitedState
+  );
+  void Object.assign(promise, state);
+  void Object.defineProperties(promise, {
+    then: { enumerable: true, value: promise.then.bind(promise) },
+    catch: { enumerable: true, value: promise.catch.bind(promise) },
+    finally: { enumerable: true, value: promise.finally.bind(promise) }
+  });
+  return promise;
+}
+export function createConvexQueryState(query, args, options) {
+  const config = getConvexRuntimeConfig();
+  const server = options?.server ?? true;
+  const auth = options?.auth ?? "optional";
+  if (import.meta.client) {
+    const authContext2 = createConvexQueryAuthContext();
+    const currentBoundary = computed(() => {
+      const currentArgs2 = normalizeConvexReactiveArgs(toValue(args));
+      const gate2 = createQueryExecutionGate({
+        authStatus: authContext2.status.value,
+        authMode: auth,
+        identityKey: authContext2.identityKey.value,
+        skipped: currentArgs2 === "skip"
+      });
+      const key2 = gate2.outcome === "execute" ? withAuthDimension(
+        createConvexQueryKey(query, currentArgs2),
+        auth,
+        gate2.cacheIdentity
+      ) : `convex:${gate2.outcome}:${getFunctionName(query)}`;
+      return { args: currentArgs2, gate: gate2, key: key2 };
+    });
+    const hydrationBoundary = currentBoundary.value;
+    const hydrationKey = hydrationBoundary.key;
+    const nuxtApp = useNuxtApp();
+    const runtime = readConvexRuntimeContext(nuxtApp);
+    const hydrationIdentityMatches = hydrationBoundary.gate.outcome === "execute" && matchesConvexHydrationIdentity(
+      auth,
+      hydrationBoundary.gate.cacheIdentity,
+      runtime?.attachment.identity.snapshot()
+    );
+    const hydrationRetired = ref(false);
+    const matchesHydrationBoundary = () => {
+      const boundary = currentBoundary.value;
+      return hydrationIdentityMatches && boundary.key === hydrationKey && boundary.gate.outcome === "execute" && matchesConvexHydrationIdentity(
+        auth,
+        boundary.gate.cacheIdentity,
+        runtime?.attachment.identity.snapshot()
+      );
+    };
+    const hydrationBoundaryMatches = computed(
+      () => !hydrationRetired.value && matchesHydrationBoundary()
+    );
+    const stopHydrationBoundaryRetirement = watch(
+      currentBoundary,
+      () => {
+        if (!matchesHydrationBoundary()) hydrationRetired.value = true;
+      },
+      { flush: "sync" }
+    );
+    const hydratedPayload = nuxtApp.payload.data[hydrationKey];
+    const hasHydratedData = hydrationIdentityMatches && hydratedPayload !== null && hydratedPayload !== void 0 && Object.hasOwn(hydratedPayload, "value");
+    const hydratedErrors = useState(
+      "convex:query-errors",
+      () => ({})
+    );
+    const result = Reflect.apply(useVueConvexQuery, void 0, [
+      query,
+      args,
+      { auth, keepPreviousData: options?.keepPreviousData },
+      hasHydratedData ? { value: hydratedPayload.value } : void 0
+    ]);
+    const clearHydratedError = () => {
+      if (!(hydrationKey in hydratedErrors.value)) return;
+      const { [hydrationKey]: _removed, ...rest } = hydratedErrors.value;
+      hydratedErrors.value = rest;
+    };
+    const stopHydratedErrorReconciliation = watch(
+      [result.error, result.pending, hydrationBoundaryMatches],
+      ([error3, pending3, boundaryMatches]) => {
+        if (boundaryMatches && (error3 || !pending3)) clearHydratedError();
+      },
+      { flush: "sync" }
+    );
+    const error2 = computed(
+      () => result.error.value ?? (hydrationBoundaryMatches.value ? hydratedErrors.value[hydrationKey] : void 0)
+    );
+    const pending2 = computed(() => error2.value ? false : result.pending.value);
+    const status2 = computed(
+      () => error2.value ? "error" : result.status.value
+    );
+    const stopDevtools = watch(
+      [status2, result.data, error2],
+      ([currentStatus, data2, currentError]) => {
+        runtime?.getDevtoolsSink()?.upsertQuery({
+          id: hydrationKey,
+          name: getFunctionName(query),
+          args: currentBoundary.value.args,
+          status: currentStatus,
+          data: data2,
+          error: currentError?.message,
+          options: { immediate: true, server, subscribe: true, auth }
+        });
+      },
+      { immediate: true }
+    );
+    onScopeDispose(() => {
+      stopHydrationBoundaryRetirement();
+      stopHydratedErrorReconciliation();
+      stopDevtools();
+      runtime?.getDevtoolsSink()?.removeQuery(hydrationKey);
+    });
+    return {
+      resultData: Object.freeze({
+        ...result,
+        error: error2,
+        pending: pending2,
+        status: status2
+      }),
+      resolvePromise: !server || hasHydratedData || error2.value || status2.value !== "pending" ? Promise.resolve() : waitForClientTerminal(status2)
+    };
+  }
+  const authContext = createConvexQueryAuthContext();
+  const currentArgs = computed(() => normalizeConvexReactiveArgs(toValue(args)));
+  const skipped = computed(() => currentArgs.value === "skip");
+  const gate = computed(
+    () => createQueryExecutionGate({
+      authStatus: authContext.status.value,
+      authMode: auth,
+      identityKey: authContext.identityKey.value,
+      skipped: skipped.value
+    })
+  );
+  const key = computed(() => {
+    if (gate.value.outcome !== "execute") {
+      return `convex:${gate.value.outcome}:${getFunctionName(query)}`;
+    }
+    return withAuthDimension(
+      createConvexQueryKey(query, currentArgs.value),
+      auth,
+      gate.value.cacheIdentity
+    );
+  });
+  const errors = useState(
+    "convex:query-errors",
+    () => ({})
+  );
+  const event = useRequestEvent();
+  const identity = useConvexIdentityState();
+  const cachedToken = computed(() => identityToken(identity.value));
+  const asyncData = useAsyncData(
+    key,
+    async () => {
+      const decision = gate.value;
+      if (decision.outcome !== "execute") {
+        if (decision.outcome === "error") {
+          errors.value = {
+            ...errors.value,
+            [key.value]: authContext.error.value ?? new ConvexCallError({
+              kind: "authentication",
+              message: "Authentication error"
+            })
+          };
+        }
+        return null;
+      }
+      const convexUrl = config.url;
+      if (!convexUrl) return null;
+      try {
+        const token = fetchAuthToken({
+          auth,
+          cookieHeader: event?.headers.get("cookie") ?? "",
+          cachedToken
+        });
+        if (auth !== "none" && decision.cacheIdentity !== "anonymous" && !token) return null;
+        const value = await executeQueryHttp(
+          convexUrl,
+          getFunctionName(query),
+          currentArgs.value,
+          token,
+          event?.web?.request?.signal
+        );
+        const { [key.value]: _removed, ...rest } = errors.value;
+        errors.value = rest;
+        return { value };
+      } catch (error2) {
+        errors.value = {
+          ...errors.value,
+          [key.value]: normalizeConvexError(error2)
+        };
+        return null;
+      }
+    },
+    {
+      server,
+      deep: false,
+      default: () => null
+    }
+  );
+  const error = computed(() => errors.value[key.value]);
+  const pending = computed(
+    () => computeConvexQueryPending({
+      isSkipped: gate.value.outcome === "idle",
+      hasData: asyncData.data.value !== null,
+      hasSettled: asyncData.status.value === "success" || asyncData.status.value === "error",
+      server,
+      resolveImmediately: false,
+      isServer: true,
+      isClient: false,
+      asyncDataPending: asyncData.pending.value,
+      isAuthPending: gate.value.outcome === "wait"
+    })
+  );
+  const data = computed(() => {
+    const payload = asyncData.data.value;
+    return payload === null ? void 0 : payload.value;
+  });
+  const status = computed(
+    () => computeQueryStatus(
+      gate.value.outcome === "idle",
+      error.value !== void 0,
+      pending.value,
+      data.value !== void 0
+    )
+  );
+  return {
+    resultData: Object.freeze({
+      data,
+      error,
+      pending,
+      status,
+      isStale: computed(() => false),
+      async refresh() {
+        await asyncData.refresh().then(
+          () => {
+          },
+          () => {
+          }
+        );
+      }
+    }),
+    resolvePromise: gate.value.outcome === "idle" || !server ? Promise.resolve() : asyncData.then(
+      () => {
+      },
+      () => {
+      }
+    )
+  };
+}
+export function useConvexQuery(query, ...parameters) {
+  const [providedArgs, options] = parameters;
+  const args = parameters.length === 0 ? {} : providedArgs;
+  const result = createConvexQueryState(query, args, options);
+  return asNuxtConvexQuery(result.resultData, result.resolvePromise);
+}

package/dist/runtime/convex-auth/adapter/create-adapter.d.ts

@@ -0,0 +1,33 @@
+import { type DBAdapterDebugLogOption } from 'better-auth/adapters';
+import { type GenericDataModel } from 'convex/server';
+import { type AuthCtx } from '../context.js';
+import type { AuthAdapterComponentApi, AuthComponentTriggers, AuthFunctions } from '../types.js';
+interface AdapterOptions<DataModel extends GenericDataModel> {
+    authFunctions?: AuthFunctions;
+    debugLogs?: DBAdapterDebugLogOption;
+    triggers?: AuthComponentTriggers<DataModel>;
+}
+interface IdTokenProtectionOptions {
+    account?: {
+        encryptOAuthTokens?: boolean;
+        fields?: {
+            idToken?: string;
+        };
+        modelName?: string;
+    };
+    secrets?: Array<{
+        value: string;
+        version: number;
+    }>;
+}
+/**
+ * The pinned Better Auth RC encrypts access/refresh tokens but omits `idToken`
+ * at several persistence call sites. Keep that workaround at the one adapter
+ * boundary so raw provider ID tokens never enter the component database.
+ */
+export declare function createAccountIdTokenProtector(options: IdTokenProtectionOptions): {
+    protect: <T>(model: string, data: T) => Promise<T>;
+    reveal: <T>(model: string, data: T) => Promise<T>;
+};
+export declare function createConvexAuthAdapter<DataModel extends GenericDataModel, Api extends AuthAdapterComponentApi>(ctx: AuthCtx<DataModel>, component: Api, adapterOptions?: AdapterOptions<DataModel>): import("better-auth/adapters").AdapterFactory<import("better-auth").BetterAuthOptions>;
+export {};