@hulla/db-svelte 0.0.0-stage → 0.1.0
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 +67 -2
- package/dist/index.d.ts +11 -0
- package/dist/index.js +97 -0
- package/package.json +40 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Samuel Hulla
|
|
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
CHANGED
|
@@ -1,3 +1,68 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @hulla/db-svelte
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
```sh
|
|
4
|
+
npm install @hulla/db@0.1.0 @hulla/db-svelte@0.1.0 svelte
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
Svelte 5 bindings for generated Hulla functions. Install alongside `@hulla/db`
|
|
8
|
+
and `svelte`, then set `database.client` before generation.
|
|
9
|
+
The package ships ordinary JavaScript and declarations; consumers do not compile
|
|
10
|
+
library rune sources.
|
|
11
|
+
|
|
12
|
+
```svelte
|
|
13
|
+
<script lang="ts">
|
|
14
|
+
import { createQuery, createMutation } from "@hulla/db-svelte";
|
|
15
|
+
import { list, save as saveProject } from "./db/_generated/client/projects";
|
|
16
|
+
|
|
17
|
+
let { projectId } = $props<{ projectId: string }>();
|
|
18
|
+
const projects = createQuery(list, () => ({ projectId }));
|
|
19
|
+
const save = createMutation(saveProject);
|
|
20
|
+
// await save({ projectId, title: "New title" });
|
|
21
|
+
// save.state.status is idle, pending, recovering, success or error.
|
|
22
|
+
</script>
|
|
23
|
+
|
|
24
|
+
{#if projects.status === 'pending'}
|
|
25
|
+
<p>Loading…</p>
|
|
26
|
+
{:else if projects.status === 'success'}
|
|
27
|
+
<pre>{JSON.stringify(projects.data)}</pre>
|
|
28
|
+
{/if}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Call bindings during component initialization. Query properties are reactive
|
|
32
|
+
getters: read `projects.status`, `projects.data`, `projects.error` and the snapshot
|
|
33
|
+
indicators directly, without destructuring them into nonreactive variables.
|
|
34
|
+
Getter inputs track rune dependencies. Equivalent encoded inputs retain the
|
|
35
|
+
current subscription. Live observation starts on mount and stops on unmount;
|
|
36
|
+
SSR never subscribes or executes a read. No-input queries take options as their
|
|
37
|
+
second argument. The core runtime owns the cache and authorization.
|
|
38
|
+
|
|
39
|
+
For SSR, await direct server `db` operations in your server loader,
|
|
40
|
+
then pass that request's result to `createQuery` as `initialData`. Supply identical
|
|
41
|
+
input and seed on server and client. The result appears as stale pending data
|
|
42
|
+
until live data arrives. Authenticated seeds also require `initialAuthKey` equal
|
|
43
|
+
to the local key supplied to generated `setAuth` for that account. Input or identity
|
|
44
|
+
changes retire the seed.
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
const projects = createQuery(list, () => ({ projectId }), {
|
|
48
|
+
initialData: data.initialProjects,
|
|
49
|
+
initialAuthKey: data.authKey,
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`createMutation` returns a callable with a reactive `.state` snapshot getter.
|
|
54
|
+
Each call returns its original awaitable mutation handle; `.state` follows the
|
|
55
|
+
most recently started call. There is no provider or additional client.
|
|
56
|
+
|
|
57
|
+
## Live pagination
|
|
58
|
+
|
|
59
|
+
Use `createPaginatedQuery(query, cursor => ({ limit: 20, cursor }))` for a generated
|
|
60
|
+
query that directly returns `Page<Row>`. Read the flattened rows through
|
|
61
|
+
`tasks.data` and append pages with `tasks.next()` or `tasks.next(3)`.
|
|
62
|
+
Changing reactive filters resets all loaded pages; unmounting releases them.
|
|
63
|
+
The optional third argument accepts flattened `initialData`, `initialAuthKey`
|
|
64
|
+
and the ordinary error-retention option. See the
|
|
65
|
+
[pagination guide](https://github.com/hulladev/db/blob/main/docs/framework-bindings.md#load-more-pages-in-a-component).
|
|
66
|
+
|
|
67
|
+
For a complete server-rendered application, see the
|
|
68
|
+
[SvelteKit recipe](https://github.com/hulladev/db/blob/main/docs/frameworks/sveltekit.md).
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { type MutationArguments, type MutationBindingState, type MutationFunction, type PaginatedQueryFunction, type PageRow, type PaginationBindingOptions, type PaginationSnapshot, type QueryArguments, type QueryBindingOptions, type QueryFunction } from "@hulla/db/bindings";
|
|
2
|
+
import type { Input, MutationHandle, Output, QueryState } from "@hulla/db";
|
|
3
|
+
export type ReactiveQueryArguments<Q extends QueryFunction> = [Input<Q>] extends [undefined] ? QueryArguments<Q> : [input: Input<Q> | (() => Input<Q>), options?: QueryBindingOptions<NoInfer<Output<Q>>>];
|
|
4
|
+
/** Call during component initialization. Read properties reactively without destructuring. */
|
|
5
|
+
export declare function createQuery<Q extends QueryFunction>(query: Q, ...args: ReactiveQueryArguments<Q>): QueryState<Output<Q>>;
|
|
6
|
+
/** Call during initialization. Read properties reactively without destructuring. */
|
|
7
|
+
export declare function createPaginatedQuery<Q extends PaginatedQueryFunction>(query: Q, mapper: (cursor: string | null) => Input<Q>, options?: PaginationBindingOptions<NoInfer<PageRow<Q>>>): PaginationSnapshot<PageRow<Q>>;
|
|
8
|
+
export type MutationResult<M extends MutationFunction> = ((...args: MutationArguments<M>) => MutationHandle<Output<M>>) & {
|
|
9
|
+
readonly state: MutationBindingState<Output<M>>;
|
|
10
|
+
};
|
|
11
|
+
export declare function createMutation<M extends MutationFunction>(mutation: M): MutationResult<M>;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { onMount } from "svelte";
|
|
2
|
+
import { createSubscriber } from "svelte/reactivity";
|
|
3
|
+
import { toStore } from "svelte/store";
|
|
4
|
+
import { createMutationObserver, createPaginationObserver, createQueryObserver, queryArguments, queryKey, } from "@hulla/db/bindings";
|
|
5
|
+
/** Call during component initialization. Read properties reactively without destructuring. */
|
|
6
|
+
export function createQuery(query, ...args) {
|
|
7
|
+
const { input: source, options } = queryArguments(query, args);
|
|
8
|
+
const readInput = () => typeof source === "function" ? source() : source;
|
|
9
|
+
const { initialData: _initialData, initialAuthKey: _initialAuthKey, ...liveOptions } = options;
|
|
10
|
+
const observe = (input, seed) => {
|
|
11
|
+
const resolved = [...args];
|
|
12
|
+
if (source !== undefined) {
|
|
13
|
+
resolved[0] = input;
|
|
14
|
+
resolved[1] = seed ? options : liveOptions;
|
|
15
|
+
}
|
|
16
|
+
return createQueryObserver(query, ...resolved);
|
|
17
|
+
};
|
|
18
|
+
let key = queryKey(query, readInput());
|
|
19
|
+
let observer = observe(readInput(), true);
|
|
20
|
+
const updates = new Set();
|
|
21
|
+
const track = createSubscriber(update => { updates.add(update); return () => { updates.delete(update); }; });
|
|
22
|
+
const notify = () => { for (const update of updates)
|
|
23
|
+
update(); };
|
|
24
|
+
// toStore tracks the getter's rune dependencies using Svelte's public API;
|
|
25
|
+
// subscribing only after mount keeps SSR and discarded initialization pure.
|
|
26
|
+
const inputs = toStore(() => { const input = readInput(); return { input, key: queryKey(query, input) }; });
|
|
27
|
+
onMount(() => {
|
|
28
|
+
let stop;
|
|
29
|
+
const stopInputs = inputs.subscribe(next => {
|
|
30
|
+
if (next.key !== key) {
|
|
31
|
+
stop?.();
|
|
32
|
+
key = next.key;
|
|
33
|
+
observer = observe(next.input, false);
|
|
34
|
+
}
|
|
35
|
+
else if (stop)
|
|
36
|
+
return;
|
|
37
|
+
stop = observer.subscribe(notify);
|
|
38
|
+
notify();
|
|
39
|
+
});
|
|
40
|
+
return () => { stopInputs(); stop?.(); };
|
|
41
|
+
});
|
|
42
|
+
const snapshot = () => { track(); return observer.getSnapshot(); };
|
|
43
|
+
return {
|
|
44
|
+
get status() { return snapshot().status; },
|
|
45
|
+
get data() { return snapshot().data; },
|
|
46
|
+
get error() { const state = snapshot(); return state.status === "error" ? state.error : undefined; },
|
|
47
|
+
get isStale() { return snapshot().isStale; },
|
|
48
|
+
get isOptimistic() { return snapshot().isOptimistic; },
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
/** Call during initialization. Read properties reactively without destructuring. */
|
|
52
|
+
export function createPaginatedQuery(query, mapper, options = {}) {
|
|
53
|
+
const { initialData: _initialData, initialAuthKey: _initialAuthKey, ...liveOptions } = options;
|
|
54
|
+
let key = queryKey(query, mapper(null));
|
|
55
|
+
let observer = createPaginationObserver(query, mapper, options);
|
|
56
|
+
const updates = new Set();
|
|
57
|
+
const track = createSubscriber(update => { updates.add(update); return () => { updates.delete(update); }; });
|
|
58
|
+
const notify = () => { for (const update of updates)
|
|
59
|
+
update(); };
|
|
60
|
+
const inputs = toStore(() => queryKey(query, mapper(null)));
|
|
61
|
+
onMount(() => {
|
|
62
|
+
let stop;
|
|
63
|
+
const stopInputs = inputs.subscribe(nextKey => {
|
|
64
|
+
if (nextKey !== key) {
|
|
65
|
+
stop?.();
|
|
66
|
+
key = nextKey;
|
|
67
|
+
observer = createPaginationObserver(query, mapper, liveOptions);
|
|
68
|
+
}
|
|
69
|
+
else if (stop)
|
|
70
|
+
return;
|
|
71
|
+
stop = observer.subscribe(notify);
|
|
72
|
+
notify();
|
|
73
|
+
});
|
|
74
|
+
return () => { stopInputs(); stop?.(); };
|
|
75
|
+
});
|
|
76
|
+
const snapshot = () => { track(); return observer.getSnapshot(); };
|
|
77
|
+
return {
|
|
78
|
+
get status() { return snapshot().status; },
|
|
79
|
+
get data() { return snapshot().data; },
|
|
80
|
+
get error() { const state = snapshot(); return state.status === "error" ? state.error : undefined; },
|
|
81
|
+
get isStale() { return snapshot().isStale; },
|
|
82
|
+
get isOptimistic() { return snapshot().isOptimistic; },
|
|
83
|
+
get hasMore() { return snapshot().hasMore; },
|
|
84
|
+
next: (pages) => observer.getSnapshot().next(pages),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
export function createMutation(mutation) {
|
|
88
|
+
const observer = createMutationObserver(mutation);
|
|
89
|
+
const updates = new Set();
|
|
90
|
+
const track = createSubscriber(update => { updates.add(update); return () => { updates.delete(update); }; });
|
|
91
|
+
onMount(() => observer.subscribe(() => { for (const update of updates)
|
|
92
|
+
update(); }));
|
|
93
|
+
return Object.defineProperty((...args) => observer.invoke(...args), "state", {
|
|
94
|
+
enumerable: true,
|
|
95
|
+
get() { track(); return observer.getSnapshot(); },
|
|
96
|
+
});
|
|
97
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hulla/db-svelte",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"exports": {
|
|
6
|
+
".": {
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"default": "./dist/index.js"
|
|
9
|
+
}
|
|
10
|
+
},
|
|
11
|
+
"files": [
|
|
12
|
+
"dist",
|
|
13
|
+
"README.md",
|
|
14
|
+
"LICENSE"
|
|
15
|
+
],
|
|
16
|
+
"peerDependencies": {
|
|
17
|
+
"@hulla/db": "^0.1.0",
|
|
18
|
+
"svelte": "^5.7.0"
|
|
19
|
+
},
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=22.18.0"
|
|
22
|
+
},
|
|
23
|
+
"description": "Svelte bindings for @hulla/db reactive queries and mutations",
|
|
24
|
+
"license": "MIT",
|
|
25
|
+
"author": {
|
|
26
|
+
"name": "Samuel Hulla",
|
|
27
|
+
"url": "https://hulla.dev"
|
|
28
|
+
},
|
|
29
|
+
"homepage": "https://github.com/hulladev/db#readme",
|
|
30
|
+
"repository": {
|
|
31
|
+
"type": "git",
|
|
32
|
+
"url": "git+https://github.com/hulladev/db.git",
|
|
33
|
+
"directory": "packages/svelte"
|
|
34
|
+
},
|
|
35
|
+
"bugs": {
|
|
36
|
+
"url": "https://github.com/hulladev/db/issues"
|
|
37
|
+
},
|
|
38
|
+
"publishConfig": {
|
|
39
|
+
"access": "public",
|
|
40
|
+
"registry": "https://registry.npmjs.org/"
|
|
41
|
+
}
|
|
42
|
+
}
|