@hulla/db-react 0.0.0-stage → 0.1.1
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 +60 -2
- package/dist/index.d.ts +13 -0
- package/dist/index.js +46 -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,61 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @hulla/db-react
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
```sh
|
|
4
|
+
npm install @hulla/db@0.1.0 @hulla/db-react@0.1.0 react
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
React 19 hooks for generated `@hulla/db` query and mutation functions. Configure
|
|
8
|
+
the generated application's browser runtime before mounting components.
|
|
9
|
+
|
|
10
|
+
```tsx
|
|
11
|
+
import { useMutation, useQuery } from "@hulla/db-react";
|
|
12
|
+
import { listNotes, saveNote } from "./generated/notes";
|
|
13
|
+
|
|
14
|
+
function Notes() {
|
|
15
|
+
const notes = useQuery(listNotes, { archived: false });
|
|
16
|
+
const save = useMutation(saveNote);
|
|
17
|
+
|
|
18
|
+
return (
|
|
19
|
+
<section>
|
|
20
|
+
{notes.status === "success" && notes.data.map(note => <p key={note.id}>{note.title}</p>)}
|
|
21
|
+
<button onClick={() => { void save({ title: "New note" }); }}>
|
|
22
|
+
{save.state.status === "pending" ? "Saving…" : "Add note"}
|
|
23
|
+
</button>
|
|
24
|
+
</section>
|
|
25
|
+
);
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Pass the generated function to each hook. Queries begin observing after React
|
|
30
|
+
subscribes, and equivalent query inputs preserve the observation across renders.
|
|
31
|
+
Changing the input releases the previous subscription. Query data is readonly.
|
|
32
|
+
|
|
33
|
+
`useMutation` returns a callable with a readonly `.state` snapshot. Its state starts
|
|
34
|
+
as `idle` and follows the most recently started mutation. Each call returns its
|
|
35
|
+
own awaitable mutation handle, including when multiple writes overlap.
|
|
36
|
+
|
|
37
|
+
For server rendering, pass `{ initialData }` as the query options: after the input
|
|
38
|
+
for queries with input, or as the second hook argument for no-input queries. The
|
|
39
|
+
seed is read once for the initial query/input; later input changes permanently
|
|
40
|
+
discard it, including when returning to the original input. The snapshot remains
|
|
41
|
+
`pending` with stale data until a live result arrives. Rendering starts no network
|
|
42
|
+
requests. Data rendered for a signed-in account also requires `initialAuthKey`
|
|
43
|
+
matching the key supplied to the browser runtime's `setAuth`; anonymous data uses
|
|
44
|
+
the default `null` key. A changed authorization scope retires the seed.
|
|
45
|
+
|
|
46
|
+
`keepPreviousDataOnError: true` preserves the last result for ordinary query
|
|
47
|
+
errors. Authorization failures clear it. The shared database runtime owns query
|
|
48
|
+
caching, optimistic state and recovery.
|
|
49
|
+
|
|
50
|
+
## Live pagination
|
|
51
|
+
|
|
52
|
+
Use `usePaginatedQuery(query, cursor => ({ limit: 20, cursor }))` for a generated
|
|
53
|
+
query that directly returns `Page<Row>`. Read the flattened rows through
|
|
54
|
+
`tasks.data` and append pages with `tasks.next()` or `tasks.next(3)`.
|
|
55
|
+
Changing reactive filters resets all loaded pages; unmounting releases them.
|
|
56
|
+
The optional third argument accepts flattened `initialData`, `initialAuthKey`
|
|
57
|
+
and the ordinary error-retention option. See the
|
|
58
|
+
[pagination guide](https://github.com/hulladev/db/blob/main/docs/framework-bindings.md#load-more-pages-in-a-component).
|
|
59
|
+
|
|
60
|
+
For a complete server-rendered application, see the
|
|
61
|
+
[Next.js recipe](https://github.com/hulladev/db/blob/main/docs/frameworks/next.md).
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type PaginatedQueryFunction, type PageRow, type PaginationSnapshot, type PaginationBindingOptions, type MutationArguments, type MutationFunction, type QueryArguments, type QueryFunction } from "@hulla/db/bindings";
|
|
2
|
+
import type { Input, MutationHandle, MutationState, Output, QueryState } from "@hulla/db";
|
|
3
|
+
/** Observe a generated query. Network observation starts when React subscribes. */
|
|
4
|
+
export declare function useQuery<Q extends QueryFunction>(query: Q, ...args: QueryArguments<Q>): QueryState<Output<Q>>;
|
|
5
|
+
/** Observe a growing list of live page ranges from a direct paginated query. */
|
|
6
|
+
export declare function usePaginatedQuery<Q extends PaginatedQueryFunction>(query: Q, mapper: (cursor: string | null) => Input<Q>, options?: PaginationBindingOptions<NoInfer<PageRow<Q>>>): PaginationSnapshot<PageRow<Q>>;
|
|
7
|
+
/** A render's mutation snapshot accompanies the callable that starts writes. */
|
|
8
|
+
export type MutationResult<M extends MutationFunction> = ((...args: MutationArguments<M>) => MutationHandle<Output<M>>) & {
|
|
9
|
+
readonly state: MutationState<Output<M>> | {
|
|
10
|
+
readonly status: "idle";
|
|
11
|
+
};
|
|
12
|
+
};
|
|
13
|
+
export declare function useMutation<M extends MutationFunction>(mutation: M): MutationResult<M>;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
import { useCallback, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
|
|
3
|
+
import { createMutationObserver, createQueryObserver, createPaginationObserver, queryArguments, queryKey, } from "@hulla/db/bindings";
|
|
4
|
+
/** Observe a generated query. Network observation starts when React subscribes. */
|
|
5
|
+
export function useQuery(query, ...args) {
|
|
6
|
+
const { input, options, hasInput } = queryArguments(query, args);
|
|
7
|
+
const key = queryKey(query, input);
|
|
8
|
+
const [seed, setSeed] = useState(() => ({ query, key, options, valid: true }));
|
|
9
|
+
const eligible = seed.valid && seed.query === query && seed.key === key
|
|
10
|
+
&& seed.options.initialAuthKey === options.initialAuthKey;
|
|
11
|
+
if (seed.valid && !eligible)
|
|
12
|
+
setSeed({ ...seed, valid: false });
|
|
13
|
+
const observer = useMemo(() => {
|
|
14
|
+
const settings = {
|
|
15
|
+
...(options.keepPreviousDataOnError === undefined ? {} : { keepPreviousDataOnError: options.keepPreviousDataOnError }),
|
|
16
|
+
...(eligible && Object.hasOwn(seed.options, "initialData") ? { initialData: seed.options.initialData } : {}),
|
|
17
|
+
...(eligible && seed.options.initialAuthKey !== undefined ? { initialAuthKey: seed.options.initialAuthKey } : {}),
|
|
18
|
+
};
|
|
19
|
+
return createQueryObserver(query, ...(hasInput ? [input, settings] : [settings]));
|
|
20
|
+
}, [query, key, eligible, options.keepPreviousDataOnError]);
|
|
21
|
+
return useSyncExternalStore(observer.subscribe, observer.getSnapshot, observer.getServerSnapshot);
|
|
22
|
+
}
|
|
23
|
+
/** Observe a growing list of live page ranges from a direct paginated query. */
|
|
24
|
+
export function usePaginatedQuery(query, mapper, options = {}) {
|
|
25
|
+
const key = queryKey(query, mapper(null));
|
|
26
|
+
const [seed, setSeed] = useState(() => ({ query, key, options, valid: true }));
|
|
27
|
+
const eligible = seed.valid && seed.query === query && seed.key === key
|
|
28
|
+
&& seed.options.initialAuthKey === options.initialAuthKey;
|
|
29
|
+
if (seed.valid && !eligible)
|
|
30
|
+
setSeed({ ...seed, valid: false });
|
|
31
|
+
const observer = useMemo(() => createPaginationObserver(query, mapper, {
|
|
32
|
+
...(options.keepPreviousDataOnError === undefined ? {} : { keepPreviousDataOnError: options.keepPreviousDataOnError }),
|
|
33
|
+
...(eligible && Object.hasOwn(seed.options, "initialData") ? { initialData: seed.options.initialData } : {}),
|
|
34
|
+
...(eligible && seed.options.initialAuthKey !== undefined ? { initialAuthKey: seed.options.initialAuthKey } : {}),
|
|
35
|
+
}), [query, key, eligible, options.keepPreviousDataOnError]);
|
|
36
|
+
const active = useRef(observer);
|
|
37
|
+
useLayoutEffect(() => { active.current = observer; }, [observer]);
|
|
38
|
+
const next = useCallback((pages = 1) => active.current.getSnapshot().next(pages), []);
|
|
39
|
+
const snapshot = useSyncExternalStore(observer.subscribe, observer.getSnapshot, observer.getServerSnapshot);
|
|
40
|
+
return useMemo(() => ({ ...snapshot, next }), [snapshot, next]);
|
|
41
|
+
}
|
|
42
|
+
export function useMutation(mutation) {
|
|
43
|
+
const observer = useMemo(() => createMutationObserver(mutation), [mutation]);
|
|
44
|
+
const state = useSyncExternalStore(observer.subscribe, observer.getSnapshot, observer.getServerSnapshot);
|
|
45
|
+
return useMemo(() => Object.assign((...args) => observer.invoke(...args), { state }), [observer, state]);
|
|
46
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hulla/db-react",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
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.1",
|
|
18
|
+
"react": "^19.0.0"
|
|
19
|
+
},
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=22.18.0"
|
|
22
|
+
},
|
|
23
|
+
"description": "React hooks 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/react"
|
|
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
|
+
}
|