@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 +21 -0
- package/README.md +68 -0
- package/dist/embedded.d.mts +3 -0
- package/dist/embedded.d.ts +3 -0
- package/dist/embedded.mjs +4 -0
- package/dist/errors.d.mts +99 -0
- package/dist/errors.d.ts +99 -0
- package/dist/errors.mjs +110 -0
- package/dist/index.d.mts +120 -0
- package/dist/index.d.ts +120 -0
- package/dist/index.mjs +2222 -0
- package/dist/mcp-app.d.mts +38 -0
- package/dist/mcp-app.d.ts +38 -0
- package/dist/mcp-app.mjs +184 -0
- package/dist/shared/better-convex-vue.D51uUfoq.d.ts +55 -0
- package/dist/shared/better-convex-vue.DqndC1Pn.d.mts +55 -0
- package/dist/shared/better-convex-vue.vyh3n_Te.mjs +64 -0
- package/package.json +77 -0
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,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 };
|
package/dist/errors.d.ts
ADDED
|
@@ -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 };
|
package/dist/errors.mjs
ADDED
|
@@ -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 };
|
package/dist/index.d.mts
ADDED
|
@@ -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 };
|
package/dist/index.d.ts
ADDED
|
@@ -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 };
|