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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-present Lupinum OG and contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,68 @@
1
+ <p align="center"><img src="https://raw.githubusercontent.com/lupinum-dev/better-convex/main/docs/public/web-app-manifest-512x512.png" width="128" alt="Better Convex icon"></p>
2
+
3
+ <h1 align="center">@lupinum/better-convex-vue</h1>
4
+
5
+ <p align="center">Use identity-safe Convex queries and calls in plain or embedded Vue applications.</p>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/@lupinum/better-convex-vue"><img src="https://img.shields.io/npm/v/@lupinum/better-convex-vue?label=npm" alt="npm version"></a>
9
+ <a href="https://github.com/lupinum-dev/better-convex/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/better-convex/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
10
+ <a href="https://github.com/lupinum-dev/better-convex/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
11
+ </p>
12
+
13
+ > [!WARNING]
14
+ > This package is beta software. Read the changelog before every upgrade.
15
+
16
+ ## Purpose
17
+
18
+ Use this package when Vue must own the Convex client lifecycle. Use `@lupinum/better-convex-nuxt` when Nuxt must own SSR, Nitro calls, generated aliases, or optional Better Auth.
19
+
20
+ ## Requirements
21
+
22
+ The package requires Node.js 22.14 or newer, Vue 3.5, and Convex 1.42.2.
23
+
24
+ ## Installation
25
+
26
+ ```bash
27
+ pnpm add @lupinum/better-convex-vue@0.8.0-beta.40 convex@1.42.2 vue@^3.5.0
28
+ ```
29
+
30
+ ## Quick start
31
+
32
+ ```ts
33
+ import { createApp } from 'vue'
34
+ import { createBetterConvex } from '@lupinum/better-convex-vue'
35
+ import App from './App.vue'
36
+
37
+ createApp(App)
38
+ .use(createBetterConvex({ convexUrl: import.meta.env.VITE_CONVEX_URL }))
39
+ .mount('#app')
40
+ ```
41
+
42
+ Use generated Convex references inside `setup`:
43
+
44
+ ```ts
45
+ import { useConvexMutation, useConvexQuery } from '@lupinum/better-convex-vue'
46
+ import { api } from '../convex/_generated/api'
47
+
48
+ const notes = useConvexQuery(api.notes.list, {})
49
+ const rename = useConvexMutation(api.notes.rename)
50
+ ```
51
+
52
+ ## Exports
53
+
54
+ Pass `'skip'` to pause a query. A Convex `null` result remains valid data.
55
+
56
+ Advanced hosts can use the `embedded` export. MCP App UIs can use the `mcp-app` export with its exact optional peers.
57
+
58
+ ## Documentation
59
+
60
+ Read the [Vue documentation](https://better-convex.lupinum.com/docs/get-started/choose-your-path).
61
+
62
+ ## Support and security
63
+
64
+ Open a [GitHub issue](https://github.com/lupinum-dev/better-convex/issues) for support. Report vulnerabilities through the [private security process](https://github.com/lupinum-dev/better-convex/security/policy).
65
+
66
+ ## License
67
+
68
+ This package uses the [MIT License](https://github.com/lupinum-dev/better-convex/blob/main/LICENSE).
@@ -0,0 +1,3 @@
1
+ export { B as BetterConvexAttachment, c as createBetterConvexAttachment } from './shared/better-convex-vue.DqndC1Pn.mjs';
2
+ import 'convex/browser';
3
+ import './errors.mjs';
@@ -0,0 +1,3 @@
1
+ export { B as BetterConvexAttachment, c as createBetterConvexAttachment } from './shared/better-convex-vue.D51uUfoq.js';
2
+ import 'convex/browser';
3
+ import './errors.js';
@@ -0,0 +1,4 @@
1
+ export { c as createBetterConvexAttachment } from './shared/better-convex-vue.vyh3n_Te.mjs';
2
+ import 'vue';
3
+ import './errors.mjs';
4
+ import 'convex/values';
@@ -0,0 +1,99 @@
1
+ /**
2
+ * The public, framework-free error contract for Better Convex.
3
+ *
4
+ * This module is deliberately unaware of Nuxt, Vue, Nitro, Better Auth, the DOM,
5
+ * and Node built-ins. Its only third-party import is the public Convex error
6
+ * value (`convex/values`), because honest classification of application errors
7
+ * requires recognizing `ConvexError`. The boundary is enforced mechanically by
8
+ * `scripts/check-boundaries.mjs` (`errors-framework-free`) and by the packed
9
+ * purity probe (architecture invariant).
10
+ */
11
+ /**
12
+ * The locked public kind set. There is intentionally no
13
+ * `validation` kind: the pinned Convex package exposes no stable
14
+ * argument-validation class or marker, and normalization never classifies from message
15
+ * text. Add a new kind only when a future pinned Convex release provides a
16
+ * mechanically testable signal.
17
+ *
18
+ * | Kind | Only valid sources |
19
+ * | ---------------- | ---------------------------------------------------------------- |
20
+ * | `authentication` | Missing required identity, token exchange 401/403, explicit |
21
+ * | | auth-engine classification. |
22
+ * | `transport` | Fetch/XHR failure, timeout, abort, unusable/oversized/malformed |
23
+ * | | response, or unexpected upstream HTTP response observed at a |
24
+ * | | library-owned HTTP boundary. |
25
+ * | `server` | Convex application/function error with `data` preserved verbatim.|
26
+ * | `unknown` | Anything not mechanically classifiable above. |
27
+ */
28
+ type ConvexCallErrorKind = 'authentication' | 'transport' | 'server' | 'unknown';
29
+ interface ConvexCallErrorInput {
30
+ kind: ConvexCallErrorKind;
31
+ message: string;
32
+ code?: string;
33
+ status?: number;
34
+ data?: unknown;
35
+ }
36
+ /**
37
+ * The single honest error type every failed Convex operation exposes.
38
+ *
39
+ * Raw upstream causes are deliberately not retained on this public error
40
+ * object. Library-owned credentials, tokens, cookies, request/response objects,
41
+ * authorization headers, stacks, and response bodies must never enter its
42
+ * public fields.
43
+ */
44
+ declare class ConvexCallError extends Error {
45
+ readonly kind: ConvexCallErrorKind;
46
+ readonly code?: string;
47
+ readonly status?: number;
48
+ readonly data?: unknown;
49
+ constructor(input: ConvexCallErrorInput);
50
+ /**
51
+ * The public serialized shape. `cause` is intentionally omitted so no
52
+ * private upstream value can escape into a payload, log, or DevTools event.
53
+ */
54
+ toJSON(): {
55
+ name: string;
56
+ kind: ConvexCallErrorKind;
57
+ message: string;
58
+ code: string | undefined;
59
+ status: number | undefined;
60
+ data: unknown;
61
+ };
62
+ }
63
+ /** The exact object shape produced by {@link ConvexCallError.toJSON}. */
64
+ interface SerializedConvexCallError {
65
+ name: 'ConvexCallError';
66
+ kind: ConvexCallErrorKind;
67
+ message: string;
68
+ code?: string;
69
+ status?: number;
70
+ data?: unknown;
71
+ }
72
+ /**
73
+ * Mechanically safe, framework-free normalization (architecture invariant).
74
+ *
75
+ * - An existing {@link ConvexCallError} passes through unchanged, so
76
+ * re-normalizing a boundary-classified `transport`/`authentication` instance
77
+ * never downgrades it.
78
+ * - A Convex application error becomes `server` with its `data` preserved
79
+ * verbatim and a fixed display message. Convex's wire message may contain UDF
80
+ * frames, so it is never copied into the public error.
81
+ * - Everything else becomes `unknown` with a fixed display message. The pure
82
+ * normalizer NEVER classifies a `TypeError` as `transport` (it cannot know
83
+ * whether user code or a network API created it) and NEVER classifies from
84
+ * message text. Fetch, XHR,
85
+ * timeout, abort, oversized-, malformed-, and unexpected-upstream-HTTP
86
+ * boundaries construct `ConvexCallError({ kind: 'transport', ... })`
87
+ * themselves, while the boundary still knows the source.
88
+ */
89
+ declare function normalizeConvexError(error: unknown): ConvexCallError;
90
+ /**
91
+ * Strict structural validation of the serialized public fields. This gates
92
+ * payload revival: an arbitrary object is NOT revived
93
+ * just because it carries `name: 'ConvexCallError'` — every public field must
94
+ * be present and well-typed. `cause` is never part of the serialized shape.
95
+ */
96
+ declare function isSerializedConvexCallError(value: unknown): value is SerializedConvexCallError;
97
+
98
+ export { ConvexCallError, isSerializedConvexCallError, normalizeConvexError };
99
+ export type { ConvexCallErrorInput, ConvexCallErrorKind, SerializedConvexCallError };
@@ -0,0 +1,99 @@
1
+ /**
2
+ * The public, framework-free error contract for Better Convex.
3
+ *
4
+ * This module is deliberately unaware of Nuxt, Vue, Nitro, Better Auth, the DOM,
5
+ * and Node built-ins. Its only third-party import is the public Convex error
6
+ * value (`convex/values`), because honest classification of application errors
7
+ * requires recognizing `ConvexError`. The boundary is enforced mechanically by
8
+ * `scripts/check-boundaries.mjs` (`errors-framework-free`) and by the packed
9
+ * purity probe (architecture invariant).
10
+ */
11
+ /**
12
+ * The locked public kind set. There is intentionally no
13
+ * `validation` kind: the pinned Convex package exposes no stable
14
+ * argument-validation class or marker, and normalization never classifies from message
15
+ * text. Add a new kind only when a future pinned Convex release provides a
16
+ * mechanically testable signal.
17
+ *
18
+ * | Kind | Only valid sources |
19
+ * | ---------------- | ---------------------------------------------------------------- |
20
+ * | `authentication` | Missing required identity, token exchange 401/403, explicit |
21
+ * | | auth-engine classification. |
22
+ * | `transport` | Fetch/XHR failure, timeout, abort, unusable/oversized/malformed |
23
+ * | | response, or unexpected upstream HTTP response observed at a |
24
+ * | | library-owned HTTP boundary. |
25
+ * | `server` | Convex application/function error with `data` preserved verbatim.|
26
+ * | `unknown` | Anything not mechanically classifiable above. |
27
+ */
28
+ type ConvexCallErrorKind = 'authentication' | 'transport' | 'server' | 'unknown';
29
+ interface ConvexCallErrorInput {
30
+ kind: ConvexCallErrorKind;
31
+ message: string;
32
+ code?: string;
33
+ status?: number;
34
+ data?: unknown;
35
+ }
36
+ /**
37
+ * The single honest error type every failed Convex operation exposes.
38
+ *
39
+ * Raw upstream causes are deliberately not retained on this public error
40
+ * object. Library-owned credentials, tokens, cookies, request/response objects,
41
+ * authorization headers, stacks, and response bodies must never enter its
42
+ * public fields.
43
+ */
44
+ declare class ConvexCallError extends Error {
45
+ readonly kind: ConvexCallErrorKind;
46
+ readonly code?: string;
47
+ readonly status?: number;
48
+ readonly data?: unknown;
49
+ constructor(input: ConvexCallErrorInput);
50
+ /**
51
+ * The public serialized shape. `cause` is intentionally omitted so no
52
+ * private upstream value can escape into a payload, log, or DevTools event.
53
+ */
54
+ toJSON(): {
55
+ name: string;
56
+ kind: ConvexCallErrorKind;
57
+ message: string;
58
+ code: string | undefined;
59
+ status: number | undefined;
60
+ data: unknown;
61
+ };
62
+ }
63
+ /** The exact object shape produced by {@link ConvexCallError.toJSON}. */
64
+ interface SerializedConvexCallError {
65
+ name: 'ConvexCallError';
66
+ kind: ConvexCallErrorKind;
67
+ message: string;
68
+ code?: string;
69
+ status?: number;
70
+ data?: unknown;
71
+ }
72
+ /**
73
+ * Mechanically safe, framework-free normalization (architecture invariant).
74
+ *
75
+ * - An existing {@link ConvexCallError} passes through unchanged, so
76
+ * re-normalizing a boundary-classified `transport`/`authentication` instance
77
+ * never downgrades it.
78
+ * - A Convex application error becomes `server` with its `data` preserved
79
+ * verbatim and a fixed display message. Convex's wire message may contain UDF
80
+ * frames, so it is never copied into the public error.
81
+ * - Everything else becomes `unknown` with a fixed display message. The pure
82
+ * normalizer NEVER classifies a `TypeError` as `transport` (it cannot know
83
+ * whether user code or a network API created it) and NEVER classifies from
84
+ * message text. Fetch, XHR,
85
+ * timeout, abort, oversized-, malformed-, and unexpected-upstream-HTTP
86
+ * boundaries construct `ConvexCallError({ kind: 'transport', ... })`
87
+ * themselves, while the boundary still knows the source.
88
+ */
89
+ declare function normalizeConvexError(error: unknown): ConvexCallError;
90
+ /**
91
+ * Strict structural validation of the serialized public fields. This gates
92
+ * payload revival: an arbitrary object is NOT revived
93
+ * just because it carries `name: 'ConvexCallError'` — every public field must
94
+ * be present and well-typed. `cause` is never part of the serialized shape.
95
+ */
96
+ declare function isSerializedConvexCallError(value: unknown): value is SerializedConvexCallError;
97
+
98
+ export { ConvexCallError, isSerializedConvexCallError, normalizeConvexError };
99
+ export type { ConvexCallErrorInput, ConvexCallErrorKind, SerializedConvexCallError };
@@ -0,0 +1,110 @@
1
+ import { ConvexError } from 'convex/values';
2
+
3
+ const CONVEX_CALL_ERROR_KINDS = [
4
+ "authentication",
5
+ "transport",
6
+ "server",
7
+ "unknown"
8
+ ];
9
+ const CONVEX_APPLICATION_ERROR_MESSAGE = "Convex application error";
10
+ const UNKNOWN_CONVEX_ERROR_MESSAGE = "Unknown Convex error";
11
+ class ConvexCallError extends Error {
12
+ kind;
13
+ code;
14
+ status;
15
+ data;
16
+ constructor(input) {
17
+ super(input.message);
18
+ this.name = "ConvexCallError";
19
+ this.kind = input.kind;
20
+ this.code = input.code;
21
+ this.status = input.status;
22
+ this.data = input.data;
23
+ }
24
+ /**
25
+ * The public serialized shape. `cause` is intentionally omitted so no
26
+ * private upstream value can escape into a payload, log, or DevTools event.
27
+ */
28
+ toJSON() {
29
+ return {
30
+ name: this.name,
31
+ kind: this.kind,
32
+ message: this.message,
33
+ code: this.code,
34
+ status: this.status,
35
+ data: this.data
36
+ };
37
+ }
38
+ }
39
+ const NODE_INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
40
+ Object.defineProperty(ConvexCallError.prototype, NODE_INSPECT_CUSTOM, {
41
+ value() {
42
+ return this.toJSON();
43
+ },
44
+ enumerable: false,
45
+ writable: true,
46
+ configurable: true
47
+ });
48
+ function isRecordLike(value) {
49
+ return typeof value === "object" && value !== null;
50
+ }
51
+ function asNonEmptyString(value) {
52
+ return typeof value === "string" && value.length > 0 ? value : void 0;
53
+ }
54
+ function asFiniteNumber(value) {
55
+ return typeof value === "number" && Number.isFinite(value) ? value : void 0;
56
+ }
57
+ function isConvexCallErrorKind(value) {
58
+ return CONVEX_CALL_ERROR_KINDS.includes(value);
59
+ }
60
+ function isConvexApplicationError(error) {
61
+ if (error instanceof ConvexError) return true;
62
+ if (!isRecordLike(error)) return false;
63
+ return error[Symbol.for("ConvexError")] === true;
64
+ }
65
+ function readStructuredData(error) {
66
+ return isRecordLike(error) ? error.data : void 0;
67
+ }
68
+ function readCode(error) {
69
+ const data = readStructuredData(error);
70
+ if (isRecordLike(data)) {
71
+ const fromData = asNonEmptyString(data.code);
72
+ if (fromData) return fromData;
73
+ }
74
+ return isRecordLike(error) ? asNonEmptyString(error.code) : void 0;
75
+ }
76
+ function readStatus(error) {
77
+ const data = readStructuredData(error);
78
+ if (isRecordLike(data)) {
79
+ const fromData = asFiniteNumber(data.status);
80
+ if (fromData !== void 0) return fromData;
81
+ }
82
+ return isRecordLike(error) ? asFiniteNumber(error.status) : void 0;
83
+ }
84
+ function normalizeConvexError(error) {
85
+ if (error instanceof ConvexCallError) return error;
86
+ if (isConvexApplicationError(error)) {
87
+ return new ConvexCallError({
88
+ kind: "server",
89
+ message: CONVEX_APPLICATION_ERROR_MESSAGE,
90
+ code: readCode(error),
91
+ status: readStatus(error),
92
+ data: readStructuredData(error)
93
+ });
94
+ }
95
+ return new ConvexCallError({
96
+ kind: "unknown",
97
+ message: UNKNOWN_CONVEX_ERROR_MESSAGE
98
+ });
99
+ }
100
+ function isSerializedConvexCallError(value) {
101
+ if (!isRecordLike(value)) return false;
102
+ if (value.name !== "ConvexCallError") return false;
103
+ if (!isConvexCallErrorKind(value.kind)) return false;
104
+ if (typeof value.message !== "string") return false;
105
+ if (value.code !== void 0 && typeof value.code !== "string") return false;
106
+ if (value.status !== void 0 && typeof value.status !== "number") return false;
107
+ return true;
108
+ }
109
+
110
+ export { ConvexCallError, isSerializedConvexCallError, normalizeConvexError };
@@ -0,0 +1,120 @@
1
+ import { ConvexCallError } from './errors.mjs';
2
+ import * as vue from 'vue';
3
+ import { ObjectPlugin, Ref, ComputedRef, MaybeRefOrGetter } from 'vue';
4
+ import { C as ConvexClientHandle } from './shared/better-convex-vue.DqndC1Pn.mjs';
5
+ import { BetterConvexAttachment } from './embedded.mjs';
6
+ import * as convex_browser from 'convex/browser';
7
+ import { AuthTokenFetcher, OptimisticLocalStore } from 'convex/browser';
8
+ import { FunctionReference, OptionalRestArgs, FunctionReturnType, FunctionArgs, PaginationOptions, PaginationResult } from 'convex/server';
9
+
10
+ type BrowserAuthStatus = 'loading' | 'authenticated' | 'anonymous' | 'error';
11
+ /** Provider-neutral browser identity snapshot. It contains no credential or client control. */
12
+ interface BrowserAuthSnapshot {
13
+ readonly status: BrowserAuthStatus;
14
+ /** Stable, non-secret provider subject used only for local state isolation. */
15
+ readonly identityKey: string | null;
16
+ /** Non-secret monotonic credential lifecycle owned by the provider adapter. */
17
+ readonly sessionGeneration: number;
18
+ readonly error: Error | null;
19
+ }
20
+ /** Provider-neutral auth adapter. It deliberately contains no client controls. */
21
+ interface BrowserAuthAdapter {
22
+ snapshot(): BrowserAuthSnapshot;
23
+ subscribe(listener: () => void): () => void;
24
+ fetchToken: AuthTokenFetcher;
25
+ refreshSession(): Promise<void>;
26
+ }
27
+
28
+ type BetterConvexAuthAdapter = BrowserAuthAdapter;
29
+ type CreateBetterConvexOptions = {
30
+ convexUrl: string;
31
+ auth?: BetterConvexAuthAdapter;
32
+ attachment?: never;
33
+ } | {
34
+ attachment: BetterConvexAttachment;
35
+ convexUrl?: never;
36
+ auth?: never;
37
+ };
38
+ type BetterConvexPlugin = ObjectPlugin & {
39
+ /** Safe cross-framework attachment; available after plugin installation. */
40
+ attachment(): BetterConvexAttachment;
41
+ };
42
+ declare function createBetterConvex(options: CreateBetterConvexOptions): BetterConvexPlugin;
43
+
44
+ declare function useConvex(): ConvexClientHandle;
45
+
46
+ declare function useConvexConnectionState(): Readonly<{
47
+ state: vue.ComputedRef<convex_browser.ConnectionState>;
48
+ isConnected: vue.ComputedRef<boolean>;
49
+ isReconnecting: vue.ComputedRef<boolean>;
50
+ pendingMutations: vue.ComputedRef<number>;
51
+ pendingActions: vue.ComputedRef<number>;
52
+ }>;
53
+
54
+ type ClientCallStatus = 'idle' | 'pending' | 'success' | 'error';
55
+
56
+ type ConvexCallStatus$1 = ClientCallStatus;
57
+ type OptimisticUpdate<Args> = (store: OptimisticLocalStore, args: Args) => undefined;
58
+ type UseConvexMutationOptions<Args> = Readonly<{
59
+ optimisticUpdate?: OptimisticUpdate<Args>;
60
+ }>;
61
+ interface UseConvexCall<Reference extends FunctionReference<'mutation' | 'action'>> {
62
+ (...args: OptionalRestArgs<Reference>): Promise<FunctionReturnType<Reference>>;
63
+ readonly data: Readonly<Ref<FunctionReturnType<Reference> | undefined>>;
64
+ readonly status: ComputedRef<ConvexCallStatus$1>;
65
+ readonly pending: ComputedRef<boolean>;
66
+ readonly error: Readonly<Ref<ConvexCallError | undefined>>;
67
+ }
68
+ declare function useConvexMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, options?: UseConvexMutationOptions<FunctionArgs<Mutation>>): UseConvexCall<Mutation>;
69
+ declare function useConvexAction<Action extends FunctionReference<'action'>>(action: Action): UseConvexCall<Action>;
70
+
71
+ type ConvexAuthMode = 'required' | 'optional' | 'none';
72
+ type ConvexQuerySkip = 'skip';
73
+ type ConvexQueryArgs<Args> = Args | ConvexQuerySkip;
74
+ type ConvexCallStatus = ClientCallStatus;
75
+ interface UseConvexQueryOptions {
76
+ readonly auth?: ConvexAuthMode;
77
+ readonly keepPreviousData?: boolean;
78
+ }
79
+ interface UseConvexQueryState<Data> {
80
+ readonly data: ComputedRef<Data | undefined>;
81
+ readonly status: ComputedRef<ConvexCallStatus>;
82
+ readonly pending: ComputedRef<boolean>;
83
+ readonly error: ComputedRef<ConvexCallError | undefined>;
84
+ readonly isStale: ComputedRef<boolean>;
85
+ refresh(): Promise<void>;
86
+ }
87
+ type EmptyConvexArgs$1 = Record<string, never>;
88
+ type StrictEmptyConvexArgs$1 = Record<PropertyKey, never>;
89
+ type TightenEmptyConvexArgs$1<Args> = Args extends unknown ? Args extends EmptyConvexArgs$1 ? StrictEmptyConvexArgs$1 : Args : never;
90
+ type QueryArgsParameter<Query extends FunctionReference<'query'>> = MaybeRefOrGetter<ConvexQueryArgs<TightenEmptyConvexArgs$1<FunctionArgs<Query>>>>;
91
+ type UseConvexQueryParameters<Query extends FunctionReference<'query'>, Options extends UseConvexQueryOptions = UseConvexQueryOptions> = [FunctionArgs<Query>] extends [EmptyConvexArgs$1] ? [] | [args: QueryArgsParameter<Query>, options?: Options] : [args: QueryArgsParameter<Query>, options?: Options];
92
+ declare function useConvexQuery<Query extends FunctionReference<'query'>>(query: Query, ...parameters: UseConvexQueryParameters<Query>): UseConvexQueryState<FunctionReturnType<Query>>;
93
+
94
+ type PaginatedQueryReference = FunctionReference<'query', 'public', {
95
+ paginationOpts: PaginationOptions;
96
+ }, PaginationResult<unknown>>;
97
+ type EmptyConvexArgs = Record<string, never>;
98
+ type StrictEmptyConvexArgs = Record<PropertyKey, never>;
99
+ type TightenEmptyConvexArgs<Args> = Args extends unknown ? Args extends EmptyConvexArgs ? StrictEmptyConvexArgs : Args : never;
100
+ type PaginatedQueryArgs<Query extends PaginatedQueryReference> = TightenEmptyConvexArgs<Omit<FunctionArgs<Query>, 'paginationOpts'>>;
101
+ type PaginatedQueryItem<Query extends PaginatedQueryReference> = FunctionReturnType<Query>['page'][number];
102
+ interface UseConvexPaginatedQueryOptions {
103
+ readonly initialNumItems: number;
104
+ readonly auth?: ConvexAuthMode;
105
+ readonly keepPreviousData?: boolean;
106
+ }
107
+ interface UseConvexPaginatedQueryState<Item> {
108
+ readonly data: ComputedRef<readonly Item[] | undefined>;
109
+ readonly status: ComputedRef<'idle' | 'pending' | 'success' | 'error'>;
110
+ readonly isLoading: ComputedRef<boolean>;
111
+ readonly canLoadMore: ComputedRef<boolean>;
112
+ readonly error: ComputedRef<ConvexCallError | undefined>;
113
+ readonly isStale: ComputedRef<boolean>;
114
+ loadMore(numItems: number): void;
115
+ refresh(): Promise<void>;
116
+ }
117
+ declare function useConvexPaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: UseConvexPaginatedQueryOptions): UseConvexPaginatedQueryState<PaginatedQueryItem<Query>>;
118
+
119
+ export { ConvexCallError, ConvexClientHandle, createBetterConvex, useConvex, useConvexAction, useConvexConnectionState, useConvexMutation, useConvexPaginatedQuery, useConvexQuery };
120
+ export type { BetterConvexAuthAdapter, BetterConvexPlugin, ConvexAuthMode, ConvexCallStatus$1 as ConvexCallStatus, ConvexQueryArgs, CreateBetterConvexOptions, OptimisticUpdate, PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference, UseConvexCall, UseConvexMutationOptions, UseConvexPaginatedQueryOptions, UseConvexPaginatedQueryState, UseConvexQueryOptions, UseConvexQueryParameters, UseConvexQueryState };
@@ -0,0 +1,120 @@
1
+ import { ConvexCallError } from './errors.js';
2
+ import * as vue from 'vue';
3
+ import { ObjectPlugin, Ref, ComputedRef, MaybeRefOrGetter } from 'vue';
4
+ import { C as ConvexClientHandle } from './shared/better-convex-vue.D51uUfoq.js';
5
+ import { BetterConvexAttachment } from './embedded.js';
6
+ import * as convex_browser from 'convex/browser';
7
+ import { AuthTokenFetcher, OptimisticLocalStore } from 'convex/browser';
8
+ import { FunctionReference, OptionalRestArgs, FunctionReturnType, FunctionArgs, PaginationOptions, PaginationResult } from 'convex/server';
9
+
10
+ type BrowserAuthStatus = 'loading' | 'authenticated' | 'anonymous' | 'error';
11
+ /** Provider-neutral browser identity snapshot. It contains no credential or client control. */
12
+ interface BrowserAuthSnapshot {
13
+ readonly status: BrowserAuthStatus;
14
+ /** Stable, non-secret provider subject used only for local state isolation. */
15
+ readonly identityKey: string | null;
16
+ /** Non-secret monotonic credential lifecycle owned by the provider adapter. */
17
+ readonly sessionGeneration: number;
18
+ readonly error: Error | null;
19
+ }
20
+ /** Provider-neutral auth adapter. It deliberately contains no client controls. */
21
+ interface BrowserAuthAdapter {
22
+ snapshot(): BrowserAuthSnapshot;
23
+ subscribe(listener: () => void): () => void;
24
+ fetchToken: AuthTokenFetcher;
25
+ refreshSession(): Promise<void>;
26
+ }
27
+
28
+ type BetterConvexAuthAdapter = BrowserAuthAdapter;
29
+ type CreateBetterConvexOptions = {
30
+ convexUrl: string;
31
+ auth?: BetterConvexAuthAdapter;
32
+ attachment?: never;
33
+ } | {
34
+ attachment: BetterConvexAttachment;
35
+ convexUrl?: never;
36
+ auth?: never;
37
+ };
38
+ type BetterConvexPlugin = ObjectPlugin & {
39
+ /** Safe cross-framework attachment; available after plugin installation. */
40
+ attachment(): BetterConvexAttachment;
41
+ };
42
+ declare function createBetterConvex(options: CreateBetterConvexOptions): BetterConvexPlugin;
43
+
44
+ declare function useConvex(): ConvexClientHandle;
45
+
46
+ declare function useConvexConnectionState(): Readonly<{
47
+ state: vue.ComputedRef<convex_browser.ConnectionState>;
48
+ isConnected: vue.ComputedRef<boolean>;
49
+ isReconnecting: vue.ComputedRef<boolean>;
50
+ pendingMutations: vue.ComputedRef<number>;
51
+ pendingActions: vue.ComputedRef<number>;
52
+ }>;
53
+
54
+ type ClientCallStatus = 'idle' | 'pending' | 'success' | 'error';
55
+
56
+ type ConvexCallStatus$1 = ClientCallStatus;
57
+ type OptimisticUpdate<Args> = (store: OptimisticLocalStore, args: Args) => undefined;
58
+ type UseConvexMutationOptions<Args> = Readonly<{
59
+ optimisticUpdate?: OptimisticUpdate<Args>;
60
+ }>;
61
+ interface UseConvexCall<Reference extends FunctionReference<'mutation' | 'action'>> {
62
+ (...args: OptionalRestArgs<Reference>): Promise<FunctionReturnType<Reference>>;
63
+ readonly data: Readonly<Ref<FunctionReturnType<Reference> | undefined>>;
64
+ readonly status: ComputedRef<ConvexCallStatus$1>;
65
+ readonly pending: ComputedRef<boolean>;
66
+ readonly error: Readonly<Ref<ConvexCallError | undefined>>;
67
+ }
68
+ declare function useConvexMutation<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, options?: UseConvexMutationOptions<FunctionArgs<Mutation>>): UseConvexCall<Mutation>;
69
+ declare function useConvexAction<Action extends FunctionReference<'action'>>(action: Action): UseConvexCall<Action>;
70
+
71
+ type ConvexAuthMode = 'required' | 'optional' | 'none';
72
+ type ConvexQuerySkip = 'skip';
73
+ type ConvexQueryArgs<Args> = Args | ConvexQuerySkip;
74
+ type ConvexCallStatus = ClientCallStatus;
75
+ interface UseConvexQueryOptions {
76
+ readonly auth?: ConvexAuthMode;
77
+ readonly keepPreviousData?: boolean;
78
+ }
79
+ interface UseConvexQueryState<Data> {
80
+ readonly data: ComputedRef<Data | undefined>;
81
+ readonly status: ComputedRef<ConvexCallStatus>;
82
+ readonly pending: ComputedRef<boolean>;
83
+ readonly error: ComputedRef<ConvexCallError | undefined>;
84
+ readonly isStale: ComputedRef<boolean>;
85
+ refresh(): Promise<void>;
86
+ }
87
+ type EmptyConvexArgs$1 = Record<string, never>;
88
+ type StrictEmptyConvexArgs$1 = Record<PropertyKey, never>;
89
+ type TightenEmptyConvexArgs$1<Args> = Args extends unknown ? Args extends EmptyConvexArgs$1 ? StrictEmptyConvexArgs$1 : Args : never;
90
+ type QueryArgsParameter<Query extends FunctionReference<'query'>> = MaybeRefOrGetter<ConvexQueryArgs<TightenEmptyConvexArgs$1<FunctionArgs<Query>>>>;
91
+ type UseConvexQueryParameters<Query extends FunctionReference<'query'>, Options extends UseConvexQueryOptions = UseConvexQueryOptions> = [FunctionArgs<Query>] extends [EmptyConvexArgs$1] ? [] | [args: QueryArgsParameter<Query>, options?: Options] : [args: QueryArgsParameter<Query>, options?: Options];
92
+ declare function useConvexQuery<Query extends FunctionReference<'query'>>(query: Query, ...parameters: UseConvexQueryParameters<Query>): UseConvexQueryState<FunctionReturnType<Query>>;
93
+
94
+ type PaginatedQueryReference = FunctionReference<'query', 'public', {
95
+ paginationOpts: PaginationOptions;
96
+ }, PaginationResult<unknown>>;
97
+ type EmptyConvexArgs = Record<string, never>;
98
+ type StrictEmptyConvexArgs = Record<PropertyKey, never>;
99
+ type TightenEmptyConvexArgs<Args> = Args extends unknown ? Args extends EmptyConvexArgs ? StrictEmptyConvexArgs : Args : never;
100
+ type PaginatedQueryArgs<Query extends PaginatedQueryReference> = TightenEmptyConvexArgs<Omit<FunctionArgs<Query>, 'paginationOpts'>>;
101
+ type PaginatedQueryItem<Query extends PaginatedQueryReference> = FunctionReturnType<Query>['page'][number];
102
+ interface UseConvexPaginatedQueryOptions {
103
+ readonly initialNumItems: number;
104
+ readonly auth?: ConvexAuthMode;
105
+ readonly keepPreviousData?: boolean;
106
+ }
107
+ interface UseConvexPaginatedQueryState<Item> {
108
+ readonly data: ComputedRef<readonly Item[] | undefined>;
109
+ readonly status: ComputedRef<'idle' | 'pending' | 'success' | 'error'>;
110
+ readonly isLoading: ComputedRef<boolean>;
111
+ readonly canLoadMore: ComputedRef<boolean>;
112
+ readonly error: ComputedRef<ConvexCallError | undefined>;
113
+ readonly isStale: ComputedRef<boolean>;
114
+ loadMore(numItems: number): void;
115
+ refresh(): Promise<void>;
116
+ }
117
+ declare function useConvexPaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: MaybeRefOrGetter<PaginatedQueryArgs<Query> | 'skip'>, options: UseConvexPaginatedQueryOptions): UseConvexPaginatedQueryState<PaginatedQueryItem<Query>>;
118
+
119
+ export { ConvexCallError, ConvexClientHandle, createBetterConvex, useConvex, useConvexAction, useConvexConnectionState, useConvexMutation, useConvexPaginatedQuery, useConvexQuery };
120
+ export type { BetterConvexAuthAdapter, BetterConvexPlugin, ConvexAuthMode, ConvexCallStatus$1 as ConvexCallStatus, ConvexQueryArgs, CreateBetterConvexOptions, OptimisticUpdate, PaginatedQueryArgs, PaginatedQueryItem, PaginatedQueryReference, UseConvexCall, UseConvexMutationOptions, UseConvexPaginatedQueryOptions, UseConvexPaginatedQueryState, UseConvexQueryOptions, UseConvexQueryParameters, UseConvexQueryState };