@databricks/appkit-ui 0.95.0 → 0.97.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/CLAUDE.md +16 -7
- package/dist/cli/commands/generate-types.js +36 -7
- package/dist/cli/commands/generate-types.js.map +1 -1
- package/dist/cli/commands/spawn-lock.js +18 -5
- package/dist/cli/commands/spawn-lock.js.map +1 -1
- package/dist/js/database/client.d.ts +2 -2
- package/dist/js/database/client.js +1 -1
- package/dist/js/database/client.js.map +1 -1
- package/dist/react/beta.d.ts +2 -2
- package/dist/react/beta.js +1 -2
- package/dist/react/hooks/use-database-list.d.ts +4 -4
- package/dist/react/hooks/use-database-list.d.ts.map +1 -1
- package/dist/react/hooks/use-database-list.js +1 -2
- package/dist/react/hooks/use-database-list.js.map +1 -1
- package/dist/react/hooks/use-database-read.d.ts +4 -41
- package/dist/react/hooks/use-database-read.d.ts.map +1 -1
- package/dist/react/hooks/use-database-read.js +7 -68
- package/dist/react/hooks/use-database-read.js.map +1 -1
- package/dist/react/hooks/use-database-record.d.ts +3 -3
- package/dist/react/hooks/use-database-record.d.ts.map +1 -1
- package/dist/react/hooks/use-database-record.js +2 -3
- package/dist/react/hooks/use-database-record.js.map +1 -1
- package/dist/react/hooks/use-database-write.d.ts +3 -3
- package/dist/react/hooks/use-database-write.js.map +1 -1
- package/dist/react/ui/button.d.ts +1 -1
- package/dist/shared/src/database/api-types.d.ts +1 -4
- package/dist/shared/src/database/api-types.d.ts.map +1 -1
- package/dist/shared/src/database/index.d.ts +3 -0
- package/dist/shared/src/database/operations.d.ts +11 -0
- package/dist/shared/src/database/operations.d.ts.map +1 -0
- package/dist/shared/src/index.d.ts +1 -0
- package/docs/api/appkit/Class.DatabaseValidationError.md +1 -1
- package/docs/api/appkit/Function.defineOperation.md +61 -0
- package/docs/api/appkit/Function.definePolicy.md +52 -0
- package/docs/api/appkit/Function.defineSchema.md +1 -1
- package/docs/api/appkit/Interface.Actor.md +21 -0
- package/docs/api/appkit/Interface.DatabaseOperationContract.md +30 -0
- package/docs/api/appkit/Interface.DatabaseRoutes.md +30 -0
- package/docs/api/appkit/Interface.OperationContext.md +75 -0
- package/docs/api/appkit/Interface.OperationDefinition.md +77 -0
- package/docs/api/appkit/Interface.PolicyContext.md +49 -0
- package/docs/api/appkit/Interface.PolicyDenial.md +21 -0
- package/docs/api/appkit/TypeAlias.DatabricksAppKitDatabaseOperations.md +8 -0
- package/docs/api/appkit/TypeAlias.IDatabaseConfig.md +0 -10
- package/docs/api/appkit/TypeAlias.OperationMethod.md +8 -0
- package/docs/api/appkit/TypeAlias.OperationWireInput.md +14 -0
- package/docs/api/appkit/TypeAlias.OperationWireOutput.md +14 -0
- package/docs/api/appkit/TypeAlias.Policy.md +15 -0
- package/docs/api/appkit/TypeAlias.PolicyDecision.md +8 -0
- package/docs/api/appkit.md +60 -51
- package/docs/development/type-generation.md +20 -1
- package/docs/plugins/database.md +17 -70
- package/llms.txt +16 -7
- package/package.json +1 -1
- package/sbom.cdx.json +1 -1
- package/docs/api/appkit/Interface.EntityMutationHooks.md +0 -173
- package/docs/api/appkit/Interface.HookApp.md +0 -12
- package/docs/api/appkit/Interface.HookContext.md +0 -21
- package/docs/api/appkit/Interface.ReadSerializerContext.md +0 -21
- package/docs/api/appkit/TypeAlias.EntityHooks.md +0 -25
- package/docs/api/appkit/TypeAlias.ReadSerializer.md +0 -19
|
@@ -3,39 +3,8 @@ import "../../js/database/client.js";
|
|
|
3
3
|
import { DatabaseApiError } from "../../js/database/errors.js";
|
|
4
4
|
|
|
5
5
|
//#region src/react/hooks/use-database-read.d.ts
|
|
6
|
-
declare const DATABASE_SHAPE: unique symbol;
|
|
7
|
-
/**
|
|
8
|
-
* Phantom marker for the row a read serializer returns. It only carries a
|
|
9
|
-
* type; build one with {@link serialized}.
|
|
10
|
-
*/
|
|
11
|
-
interface DatabaseShape<T> {
|
|
12
|
-
readonly [DATABASE_SHAPE]: T;
|
|
13
|
-
}
|
|
14
|
-
/**
|
|
15
|
-
* Declare, without checking, the row a read serializer returns. The entity,
|
|
16
|
-
* id, and params stay checked against the generated registry; only the row
|
|
17
|
-
* type is replaced. It is a promise about the server's serializer, not a
|
|
18
|
-
* runtime check: to check each row, pass a parse function as `shape` instead.
|
|
19
|
-
*
|
|
20
|
-
* @example
|
|
21
|
-
* ```typescript
|
|
22
|
-
* interface NoteCard { id: number; excerpt: string }
|
|
23
|
-
*
|
|
24
|
-
* const notes = useDatabaseList("notes", { limit: 20 }, {
|
|
25
|
-
* shape: serialized<NoteCard>(),
|
|
26
|
-
* });
|
|
27
|
-
* notes.data?.items[0]?.excerpt;
|
|
28
|
-
* ```
|
|
29
|
-
*/
|
|
30
|
-
declare function serialized<T>(): DatabaseShape<T>;
|
|
31
|
-
/**
|
|
32
|
-
* The row a read answers with: `serialized<T>()` to declare it, or a function
|
|
33
|
-
* that checks one decoded row and returns it typed, such as a zod schema's
|
|
34
|
-
* `parse`. A function that throws fails the read with `INTERNAL`.
|
|
35
|
-
*/
|
|
36
|
-
type DatabaseRowShape<Row> = DatabaseShape<Row> | ((row: unknown) => Row);
|
|
37
6
|
/** Options shared by `useDatabaseList` and `useDatabaseRecord`. */
|
|
38
|
-
interface UseDatabaseReadOptions
|
|
7
|
+
interface UseDatabaseReadOptions {
|
|
39
8
|
/** Send the request. `false` keeps the hook idle and sends nothing. Default true. */
|
|
40
9
|
enabled?: boolean;
|
|
41
10
|
/**
|
|
@@ -44,12 +13,6 @@ interface UseDatabaseReadOptions<Row> {
|
|
|
44
13
|
* stays true until the new response arrives. Default false.
|
|
45
14
|
*/
|
|
46
15
|
keepPreviousData?: boolean;
|
|
47
|
-
/**
|
|
48
|
-
* The row a read serializer returns. `serialized<T>()` only declares it; a
|
|
49
|
-
* function checks every row at runtime (each list item, or the record) and
|
|
50
|
-
* its return value becomes the row. It runs once per response.
|
|
51
|
-
*/
|
|
52
|
-
shape?: DatabaseRowShape<Row>;
|
|
53
16
|
}
|
|
54
17
|
/** Latest state of one database read. */
|
|
55
18
|
interface UseDatabaseReadResult<T> {
|
|
@@ -63,13 +26,13 @@ interface UseDatabaseReadResult<T> {
|
|
|
63
26
|
loading: boolean;
|
|
64
27
|
/**
|
|
65
28
|
* Why the latest request failed: `NOT_EXPOSED` when no route exists,
|
|
66
|
-
* `INVALID_REQUEST` for params or an id that cannot be sent
|
|
67
|
-
*
|
|
29
|
+
* `INVALID_REQUEST` for params or an id that cannot be sent. Stable across
|
|
30
|
+
* renders.
|
|
68
31
|
*/
|
|
69
32
|
error: DatabaseApiError | null;
|
|
70
33
|
/** Abort any in-flight request and send it again. No-op while disabled. */
|
|
71
34
|
refetch: () => void;
|
|
72
35
|
}
|
|
73
36
|
//#endregion
|
|
74
|
-
export {
|
|
37
|
+
export { UseDatabaseReadOptions, UseDatabaseReadResult };
|
|
75
38
|
//# sourceMappingURL=use-database-read.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"use-database-read.d.ts","names":[],"sources":["../../../src/react/hooks/use-database-read.ts"],"mappings":"
|
|
1
|
+
{"version":3,"file":"use-database-read.d.ts","names":[],"sources":["../../../src/react/hooks/use-database-read.ts"],"mappings":";;;;;;UA0BiB,sBAAA;EAAA;EAEf,OAAA;;;;AAUF;;EAJE,gBAAA;AAAA;;UAIe,qBAAA;EAMT;;;;;EAAN,IAAA,EAAM,CAAA;EAUC;EARP,OAAA;;;;;;EAMA,KAAA,EAAO,gBAAA;;EAEP,OAAA;AAAA"}
|
|
@@ -5,74 +5,14 @@ import { IDLE_DATABASE_READ, databaseReadScope, getDatabaseReadSnapshot, retainD
|
|
|
5
5
|
import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
|
|
6
6
|
|
|
7
7
|
//#region src/react/hooks/use-database-read.ts
|
|
8
|
-
const SERIALIZED = Object.freeze({});
|
|
9
|
-
/**
|
|
10
|
-
* Declare, without checking, the row a read serializer returns. The entity,
|
|
11
|
-
* id, and params stay checked against the generated registry; only the row
|
|
12
|
-
* type is replaced. It is a promise about the server's serializer, not a
|
|
13
|
-
* runtime check: to check each row, pass a parse function as `shape` instead.
|
|
14
|
-
*
|
|
15
|
-
* @example
|
|
16
|
-
* ```typescript
|
|
17
|
-
* interface NoteCard { id: number; excerpt: string }
|
|
18
|
-
*
|
|
19
|
-
* const notes = useDatabaseList("notes", { limit: 20 }, {
|
|
20
|
-
* shape: serialized<NoteCard>(),
|
|
21
|
-
* });
|
|
22
|
-
* notes.data?.items[0]?.excerpt;
|
|
23
|
-
* ```
|
|
24
|
-
*/
|
|
25
|
-
function serialized() {
|
|
26
|
-
return SERIALIZED;
|
|
27
|
-
}
|
|
28
8
|
const noop = () => {};
|
|
29
|
-
/** Apply a `shape` function to each row of one response. */
|
|
30
|
-
function shapeResponse(operation, data, parse) {
|
|
31
|
-
if (operation === "detail") return parse(data);
|
|
32
|
-
const page = data;
|
|
33
|
-
return {
|
|
34
|
-
...page,
|
|
35
|
-
items: page.items.map((row) => parse(row))
|
|
36
|
-
};
|
|
37
|
-
}
|
|
38
|
-
/**
|
|
39
|
-
* Run a `shape` function once per response. The result is cached on the
|
|
40
|
-
* response's identity, not the function's, so an inline arrow does not
|
|
41
|
-
* reparse on every render or give `data` a new identity.
|
|
42
|
-
*/
|
|
43
|
-
function useShapedData(operation, source, shape) {
|
|
44
|
-
const cache = useRef(null);
|
|
45
|
-
if (typeof shape !== "function" || source === null) return {
|
|
46
|
-
source,
|
|
47
|
-
data: source,
|
|
48
|
-
error: null
|
|
49
|
-
};
|
|
50
|
-
const cached = cache.current;
|
|
51
|
-
if (cached !== null && cached.source === source) return cached;
|
|
52
|
-
let shaped;
|
|
53
|
-
try {
|
|
54
|
-
shaped = {
|
|
55
|
-
source,
|
|
56
|
-
data: shapeResponse(operation, source, shape),
|
|
57
|
-
error: null
|
|
58
|
-
};
|
|
59
|
-
} catch (cause) {
|
|
60
|
-
shaped = {
|
|
61
|
-
source,
|
|
62
|
-
data: null,
|
|
63
|
-
error: new DatabaseApiError("INTERNAL", null, "Database response does not match the read's shape", [], { cause })
|
|
64
|
-
};
|
|
65
|
-
}
|
|
66
|
-
cache.current = shaped;
|
|
67
|
-
return shaped;
|
|
68
|
-
}
|
|
69
9
|
/**
|
|
70
10
|
* One subscribed read, keyed by the resolved URL so params with equal encoded
|
|
71
11
|
* values share a request whatever their object identity. A route the server
|
|
72
12
|
* did not publish resolves to a stable `NOT_EXPOSED` error without a request,
|
|
73
13
|
* and params that cannot be encoded to a stable `INVALID_REQUEST`.
|
|
74
14
|
*/
|
|
75
|
-
function useDatabaseRead({ entity, operation, id, query, include, enabled, accept, keepPreviousData
|
|
15
|
+
function useDatabaseRead({ entity, operation, id, query, include, enabled, accept, keepPreviousData }) {
|
|
76
16
|
const encodedQuery = typeof query === "string" ? query : null;
|
|
77
17
|
const parameter = query instanceof DatabaseQueryEncodingError ? query.parameter : void 0;
|
|
78
18
|
const message = query instanceof DatabaseQueryEncodingError ? query.message : void 0;
|
|
@@ -111,17 +51,16 @@ function useDatabaseRead({ entity, operation, id, query, include, enabled, accep
|
|
|
111
51
|
const refetch = useCallback(() => {
|
|
112
52
|
if (url !== null) startDatabaseRead(url);
|
|
113
53
|
}, [url]);
|
|
114
|
-
const shaped = useShapedData(operation, snapshot.data, shape);
|
|
115
54
|
const loading = snapshot.loading || url !== null && snapshot === IDLE_DATABASE_READ;
|
|
116
|
-
const error = routeError ?? snapshot.error
|
|
55
|
+
const error = routeError ?? snapshot.error;
|
|
117
56
|
const previous = useRef(null);
|
|
118
57
|
useEffect(() => {
|
|
119
|
-
if (url !== null &&
|
|
58
|
+
if (url !== null && snapshot.data !== null) previous.current = {
|
|
120
59
|
url,
|
|
121
|
-
data:
|
|
60
|
+
data: snapshot.data
|
|
122
61
|
};
|
|
123
|
-
}, [url,
|
|
124
|
-
let data =
|
|
62
|
+
}, [url, snapshot.data]);
|
|
63
|
+
let data = snapshot.data;
|
|
125
64
|
if (keepPreviousData && data === null && loading && error === null && previous.current !== null && previous.current.url !== url) data = previous.current.data;
|
|
126
65
|
return {
|
|
127
66
|
data,
|
|
@@ -132,5 +71,5 @@ function useDatabaseRead({ entity, operation, id, query, include, enabled, accep
|
|
|
132
71
|
}
|
|
133
72
|
|
|
134
73
|
//#endregion
|
|
135
|
-
export {
|
|
74
|
+
export { useDatabaseRead };
|
|
136
75
|
//# sourceMappingURL=use-database-read.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"use-database-read.js","names":[],"sources":["../../../src/react/hooks/use-database-read.ts"],"sourcesContent":["import {\n useCallback,\n useEffect,\n useMemo,\n useRef,\n useSyncExternalStore,\n} from \"react\";\nimport { DatabaseQueryEncodingError } from \"shared\";\n\nimport {\n type DatabaseOperation,\n type IdLike,\n resolveDatabaseUrl,\n} from \"@/js/database/client\";\nimport { DatabaseApiError, invalidDatabaseQuery } from \"@/js/database/errors\";\n\nimport {\n databaseReadScope,\n getDatabaseReadSnapshot,\n IDLE_DATABASE_READ,\n retainDatabaseRead,\n startDatabaseRead,\n subscribeDatabaseRead,\n} from \"./database-request-store\";\n\ndeclare const DATABASE_SHAPE: unique symbol;\n\n/**\n * Phantom marker for the row a read serializer returns. It only carries a\n * type; build one with {@link serialized}.\n */\nexport interface DatabaseShape<T> {\n readonly [DATABASE_SHAPE]: T;\n}\n\nconst SERIALIZED = Object.freeze({});\n\n/**\n * Declare, without checking, the row a read serializer returns. The entity,\n * id, and params stay checked against the generated registry; only the row\n * type is replaced. It is a promise about the server's serializer, not a\n * runtime check: to check each row, pass a parse function as `shape` instead.\n *\n * @example\n * ```typescript\n * interface NoteCard { id: number; excerpt: string }\n *\n * const notes = useDatabaseList(\"notes\", { limit: 20 }, {\n * shape: serialized<NoteCard>(),\n * });\n * notes.data?.items[0]?.excerpt;\n * ```\n */\nexport function serialized<T>(): DatabaseShape<T> {\n return SERIALIZED as DatabaseShape<T>;\n}\n\n/**\n * The row a read answers with: `serialized<T>()` to declare it, or a function\n * that checks one decoded row and returns it typed, such as a zod schema's\n * `parse`. A function that throws fails the read with `INTERNAL`.\n */\nexport type DatabaseRowShape<Row> =\n | DatabaseShape<Row>\n | ((row: unknown) => Row);\n\n/** Options shared by `useDatabaseList` and `useDatabaseRecord`. */\nexport interface UseDatabaseReadOptions<Row> {\n /** Send the request. `false` keeps the hook idle and sends nothing. Default true. */\n enabled?: boolean;\n /**\n * While new params load, keep showing the previous params' `data` instead\n * of `null`, so a paginated list does not blank between pages. `loading`\n * stays true until the new response arrives. Default false.\n */\n keepPreviousData?: boolean;\n /**\n * The row a read serializer returns. `serialized<T>()` only declares it; a\n * function checks every row at runtime (each list item, or the record) and\n * its return value becomes the row. It runs once per response.\n */\n shape?: DatabaseRowShape<Row>;\n}\n\n/** Latest state of one database read. */\nexport interface UseDatabaseReadResult<T> {\n /**\n * The last successful response, or `null` before one arrives. A refetch\n * keeps it visible while it loads and after it fails, except a `NOT_FOUND`,\n * which clears it.\n */\n data: T | null;\n /** Whether a request for the current params is in flight. */\n loading: boolean;\n /**\n * Why the latest request failed: `NOT_EXPOSED` when no route exists,\n * `INVALID_REQUEST` for params or an id that cannot be sent, `INTERNAL`\n * when a `shape` function rejected a row. Stable across renders.\n */\n error: DatabaseApiError | null;\n /** Abort any in-flight request and send it again. No-op while disabled. */\n refetch: () => void;\n}\n\n/** What one read hook asks `useDatabaseRead` to subscribe to. */\nexport interface DatabaseReadRequest {\n entity: string;\n operation: Extract<DatabaseOperation, \"list\" | \"detail\">;\n id: IdLike | undefined;\n /** Encoded params, a known validation failure, or `null` for an unknown failure. */\n query: string | DatabaseQueryEncodingError | null;\n /** The params' include tree, to find the tables the read shows. */\n include: unknown;\n enabled: boolean;\n accept: (body: unknown) => body is object;\n keepPreviousData: boolean;\n shape: DatabaseRowShape<unknown> | undefined;\n}\n\ntype Route = { url: string } | { error: DatabaseApiError } | null;\n\nconst noop = () => {};\n\n/** Apply a `shape` function to each row of one response. */\nfunction shapeResponse(\n operation: DatabaseReadRequest[\"operation\"],\n data: unknown,\n parse: (row: unknown) => unknown,\n): unknown {\n if (operation === \"detail\") return parse(data);\n const page = data as { items: unknown[] };\n return { ...page, items: page.items.map((row) => parse(row)) };\n}\n\n/** The shaped response, or why a row failed its `shape`. */\ninterface Shaped {\n source: unknown;\n data: unknown;\n error: DatabaseApiError | null;\n}\n\n/**\n * Run a `shape` function once per response. The result is cached on the\n * response's identity, not the function's, so an inline arrow does not\n * reparse on every render or give `data` a new identity.\n */\nfunction useShapedData(\n operation: DatabaseReadRequest[\"operation\"],\n source: unknown,\n shape: DatabaseRowShape<unknown> | undefined,\n): Shaped {\n const cache = useRef<Shaped | null>(null);\n if (typeof shape !== \"function\" || source === null) {\n return { source, data: source, error: null };\n }\n const cached = cache.current;\n if (cached !== null && cached.source === source) return cached;\n let shaped: Shaped;\n try {\n shaped = {\n source,\n data: shapeResponse(operation, source, shape),\n error: null,\n };\n } catch (cause) {\n // A schema error may quote row values; keep it in `cause` only.\n shaped = {\n source,\n data: null,\n error: new DatabaseApiError(\n \"INTERNAL\",\n null,\n \"Database response does not match the read's shape\",\n [],\n { cause },\n ),\n };\n }\n cache.current = shaped;\n return shaped;\n}\n\n/**\n * One subscribed read, keyed by the resolved URL so params with equal encoded\n * values share a request whatever their object identity. A route the server\n * did not publish resolves to a stable `NOT_EXPOSED` error without a request,\n * and params that cannot be encoded to a stable `INVALID_REQUEST`.\n */\nexport function useDatabaseRead({\n entity,\n operation,\n id,\n query,\n include,\n enabled,\n accept,\n keepPreviousData,\n shape,\n}: DatabaseReadRequest): UseDatabaseReadResult<unknown> {\n const encodedQuery = typeof query === \"string\" ? query : null;\n // Encoding runs every render; only the safe failure fields define its identity.\n const parameter =\n query instanceof DatabaseQueryEncodingError ? query.parameter : undefined;\n const message =\n query instanceof DatabaseQueryEncodingError ? query.message : undefined;\n const route = useMemo((): Route => {\n if (!enabled) return null;\n if (encodedQuery === null) {\n const cause =\n parameter !== undefined && message !== undefined\n ? new DatabaseQueryEncodingError(parameter, message)\n : undefined;\n return { error: invalidDatabaseQuery(cause) };\n }\n try {\n return { url: resolveDatabaseUrl(entity, operation, id, encodedQuery) };\n } catch (error) {\n if (error instanceof DatabaseApiError) return { error };\n throw error;\n }\n }, [enabled, entity, operation, id, encodedQuery, parameter, message]);\n\n const url = route !== null && \"url\" in route ? route.url : null;\n const routeError = route !== null && \"error\" in route ? route.error : null;\n\n // Every subscriber of one URL encodes the same include, so the URL is the\n // include tree's identity; the object passed in may be a fresh literal.\n const scope = useMemo(\n () => (url === null ? null : databaseReadScope(entity, include)),\n [url],\n );\n\n const subscribe = useCallback(\n (listener: () => void) =>\n url === null ? noop : subscribeDatabaseRead(url, listener),\n [url],\n );\n const getSnapshot = useCallback(\n () => (url === null ? IDLE_DATABASE_READ : getDatabaseReadSnapshot(url)),\n [url],\n );\n const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n // The first subscriber of a URL starts the request; later ones share it.\n useEffect(() => {\n if (url === null || scope === null) return;\n return retainDatabaseRead(url, accept, scope);\n }, [url, accept, scope]);\n\n const refetch = useCallback(() => {\n if (url !== null) startDatabaseRead(url);\n }, [url]);\n\n const shaped = useShapedData(operation, snapshot.data, shape);\n\n // Until the effect retains a new URL, its request is about to start.\n const loading =\n snapshot.loading || (url !== null && snapshot === IDLE_DATABASE_READ);\n const error = routeError ?? snapshot.error ?? shaped.error;\n\n // The last data this hook showed for a URL, to hold across a params change.\n const previous = useRef<{ url: string; data: unknown } | null>(null);\n useEffect(() => {\n if (url !== null && shaped.data !== null) {\n previous.current = { url, data: shaped.data };\n }\n }, [url, shaped.data]);\n\n let data = shaped.data;\n if (\n keepPreviousData &&\n data === null &&\n loading &&\n error === null &&\n previous.current !== null &&\n previous.current.url !== url\n ) {\n data = previous.current.data;\n }\n\n return { data, loading, error, refetch };\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"use-database-read.js","names":[],"sources":["../../../src/react/hooks/use-database-read.ts"],"sourcesContent":["import {\n useCallback,\n useEffect,\n useMemo,\n useRef,\n useSyncExternalStore,\n} from \"react\";\nimport { DatabaseQueryEncodingError } from \"shared\";\n\nimport {\n type DatabaseOperation,\n type IdLike,\n resolveDatabaseUrl,\n} from \"@/js/database/client\";\nimport { DatabaseApiError, invalidDatabaseQuery } from \"@/js/database/errors\";\n\nimport {\n databaseReadScope,\n getDatabaseReadSnapshot,\n IDLE_DATABASE_READ,\n retainDatabaseRead,\n startDatabaseRead,\n subscribeDatabaseRead,\n} from \"./database-request-store\";\n\n/** Options shared by `useDatabaseList` and `useDatabaseRecord`. */\nexport interface UseDatabaseReadOptions {\n /** Send the request. `false` keeps the hook idle and sends nothing. Default true. */\n enabled?: boolean;\n /**\n * While new params load, keep showing the previous params' `data` instead\n * of `null`, so a paginated list does not blank between pages. `loading`\n * stays true until the new response arrives. Default false.\n */\n keepPreviousData?: boolean;\n}\n\n/** Latest state of one database read. */\nexport interface UseDatabaseReadResult<T> {\n /**\n * The last successful response, or `null` before one arrives. A refetch\n * keeps it visible while it loads and after it fails, except a `NOT_FOUND`,\n * which clears it.\n */\n data: T | null;\n /** Whether a request for the current params is in flight. */\n loading: boolean;\n /**\n * Why the latest request failed: `NOT_EXPOSED` when no route exists,\n * `INVALID_REQUEST` for params or an id that cannot be sent. Stable across\n * renders.\n */\n error: DatabaseApiError | null;\n /** Abort any in-flight request and send it again. No-op while disabled. */\n refetch: () => void;\n}\n\n/** What one read hook asks `useDatabaseRead` to subscribe to. */\nexport interface DatabaseReadRequest {\n entity: string;\n operation: Extract<DatabaseOperation, \"list\" | \"detail\">;\n id: IdLike | undefined;\n /** Encoded params, a known validation failure, or `null` for an unknown failure. */\n query: string | DatabaseQueryEncodingError | null;\n /** The params' include tree, to find the tables the read shows. */\n include: unknown;\n enabled: boolean;\n accept: (body: unknown) => body is object;\n keepPreviousData: boolean;\n}\n\ntype Route = { url: string } | { error: DatabaseApiError } | null;\n\nconst noop = () => {};\n\n/**\n * One subscribed read, keyed by the resolved URL so params with equal encoded\n * values share a request whatever their object identity. A route the server\n * did not publish resolves to a stable `NOT_EXPOSED` error without a request,\n * and params that cannot be encoded to a stable `INVALID_REQUEST`.\n */\nexport function useDatabaseRead({\n entity,\n operation,\n id,\n query,\n include,\n enabled,\n accept,\n keepPreviousData,\n}: DatabaseReadRequest): UseDatabaseReadResult<unknown> {\n const encodedQuery = typeof query === \"string\" ? query : null;\n // Encoding runs every render; only the safe failure fields define its identity.\n const parameter =\n query instanceof DatabaseQueryEncodingError ? query.parameter : undefined;\n const message =\n query instanceof DatabaseQueryEncodingError ? query.message : undefined;\n const route = useMemo((): Route => {\n if (!enabled) return null;\n if (encodedQuery === null) {\n const cause =\n parameter !== undefined && message !== undefined\n ? new DatabaseQueryEncodingError(parameter, message)\n : undefined;\n return { error: invalidDatabaseQuery(cause) };\n }\n try {\n return { url: resolveDatabaseUrl(entity, operation, id, encodedQuery) };\n } catch (error) {\n if (error instanceof DatabaseApiError) return { error };\n throw error;\n }\n }, [enabled, entity, operation, id, encodedQuery, parameter, message]);\n\n const url = route !== null && \"url\" in route ? route.url : null;\n const routeError = route !== null && \"error\" in route ? route.error : null;\n\n // Every subscriber of one URL encodes the same include, so the URL is the\n // include tree's identity; the object passed in may be a fresh literal.\n const scope = useMemo(\n () => (url === null ? null : databaseReadScope(entity, include)),\n [url],\n );\n\n const subscribe = useCallback(\n (listener: () => void) =>\n url === null ? noop : subscribeDatabaseRead(url, listener),\n [url],\n );\n const getSnapshot = useCallback(\n () => (url === null ? IDLE_DATABASE_READ : getDatabaseReadSnapshot(url)),\n [url],\n );\n const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n // The first subscriber of a URL starts the request; later ones share it.\n useEffect(() => {\n if (url === null || scope === null) return;\n return retainDatabaseRead(url, accept, scope);\n }, [url, accept, scope]);\n\n const refetch = useCallback(() => {\n if (url !== null) startDatabaseRead(url);\n }, [url]);\n\n // Until the effect retains a new URL, its request is about to start.\n const loading =\n snapshot.loading || (url !== null && snapshot === IDLE_DATABASE_READ);\n const error = routeError ?? snapshot.error;\n\n // The last data this hook showed for a URL, to hold across a params change.\n const previous = useRef<{ url: string; data: unknown } | null>(null);\n useEffect(() => {\n if (url !== null && snapshot.data !== null) {\n previous.current = { url, data: snapshot.data };\n }\n }, [url, snapshot.data]);\n\n let data = snapshot.data;\n if (\n keepPreviousData &&\n data === null &&\n loading &&\n error === null &&\n previous.current !== null &&\n previous.current.url !== url\n ) {\n data = previous.current.data;\n }\n\n return { data, loading, error, refetch };\n}\n"],"mappings":";;;;;;;AAyEA,MAAM,aAAa;;;;;;;AAQnB,SAAgB,gBAAgB,EAC9B,QACA,WACA,IACA,OACA,SACA,SACA,QACA,oBACsD;CACtD,MAAM,eAAe,OAAO,UAAU,WAAW,QAAQ;CAEzD,MAAM,YACJ,iBAAiB,6BAA6B,MAAM,YAAY;CAClE,MAAM,UACJ,iBAAiB,6BAA6B,MAAM,UAAU;CAChE,MAAM,QAAQ,cAAqB;AACjC,MAAI,CAAC,QAAS,QAAO;AACrB,MAAI,iBAAiB,KAKnB,QAAO,EAAE,OAAO,qBAHd,cAAc,UAAa,YAAY,SACnC,IAAI,2BAA2B,WAAW,QAAQ,GAClD,OACqC,EAAE;AAE/C,MAAI;AACF,UAAO,EAAE,KAAK,mBAAmB,QAAQ,WAAW,IAAI,aAAa,EAAE;WAChE,OAAO;AACd,OAAI,iBAAiB,iBAAkB,QAAO,EAAE,OAAO;AACvD,SAAM;;IAEP;EAAC;EAAS;EAAQ;EAAW;EAAI;EAAc;EAAW;EAAQ,CAAC;CAEtE,MAAM,MAAM,UAAU,QAAQ,SAAS,QAAQ,MAAM,MAAM;CAC3D,MAAM,aAAa,UAAU,QAAQ,WAAW,QAAQ,MAAM,QAAQ;CAItE,MAAM,QAAQ,cACL,QAAQ,OAAO,OAAO,kBAAkB,QAAQ,QAAQ,EAC/D,CAAC,IAAI,CACN;CAED,MAAM,YAAY,aACf,aACC,QAAQ,OAAO,OAAO,sBAAsB,KAAK,SAAS,EAC5D,CAAC,IAAI,CACN;CACD,MAAM,cAAc,kBACX,QAAQ,OAAO,qBAAqB,wBAAwB,IAAI,EACvE,CAAC,IAAI,CACN;CACD,MAAM,WAAW,qBAAqB,WAAW,aAAa,YAAY;AAG1E,iBAAgB;AACd,MAAI,QAAQ,QAAQ,UAAU,KAAM;AACpC,SAAO,mBAAmB,KAAK,QAAQ,MAAM;IAC5C;EAAC;EAAK;EAAQ;EAAM,CAAC;CAExB,MAAM,UAAU,kBAAkB;AAChC,MAAI,QAAQ,KAAM,mBAAkB,IAAI;IACvC,CAAC,IAAI,CAAC;CAGT,MAAM,UACJ,SAAS,WAAY,QAAQ,QAAQ,aAAa;CACpD,MAAM,QAAQ,cAAc,SAAS;CAGrC,MAAM,WAAW,OAA8C,KAAK;AACpE,iBAAgB;AACd,MAAI,QAAQ,QAAQ,SAAS,SAAS,KACpC,UAAS,UAAU;GAAE;GAAK,MAAM,SAAS;GAAM;IAEhD,CAAC,KAAK,SAAS,KAAK,CAAC;CAExB,IAAI,OAAO,SAAS;AACpB,KACE,oBACA,SAAS,QACT,WACA,UAAU,QACV,SAAS,YAAY,QACrB,SAAS,QAAQ,QAAQ,IAEzB,QAAO,SAAS,QAAQ;AAG1B,QAAO;EAAE;EAAM;EAAS;EAAO;EAAS"}
|
|
@@ -5,7 +5,7 @@ import { UseDatabaseReadOptions, UseDatabaseReadResult } from "./use-database-re
|
|
|
5
5
|
|
|
6
6
|
//#region src/react/hooks/use-database-record.d.ts
|
|
7
7
|
/** Options for {@link useDatabaseRecord}. */
|
|
8
|
-
type UseDatabaseRecordOptions
|
|
8
|
+
type UseDatabaseRecordOptions = UseDatabaseReadOptions;
|
|
9
9
|
/** What {@link useDatabaseRecord} returns: one row and its state. */
|
|
10
10
|
type UseDatabaseRecordResult<Row> = UseDatabaseReadResult<Row>;
|
|
11
11
|
/**
|
|
@@ -20,7 +20,7 @@ type UseDatabaseRecordResult<Row> = UseDatabaseReadResult<Row>;
|
|
|
20
20
|
* @param entity - A table the generated registry exposes with a public key
|
|
21
21
|
* @param id - The row's public key, or `null`/`undefined` to wait
|
|
22
22
|
* @param params - `select` and `include`; pass `{}` to reach `options` alone
|
|
23
|
-
* @param options - `enabled
|
|
23
|
+
* @param options - `enabled` and `keepPreviousData`
|
|
24
24
|
* @returns The row, loading and error state, and `refetch`
|
|
25
25
|
*
|
|
26
26
|
* @example
|
|
@@ -31,7 +31,7 @@ type UseDatabaseRecordResult<Row> = UseDatabaseReadResult<Row>;
|
|
|
31
31
|
* board.data?.notes.length;
|
|
32
32
|
* ```
|
|
33
33
|
*/
|
|
34
|
-
declare function useDatabaseRecord<K extends DatabaseKeyedEntity, const P extends DatabaseRecordParams<K> = Record<never, never
|
|
34
|
+
declare function useDatabaseRecord<K extends DatabaseKeyedEntity, const P extends DatabaseRecordParams<K> = Record<never, never>>(entity: K, id: DatabaseId<K> | null | undefined, params?: P & ExactDatabaseParams<P, DatabaseRecordParams<K>>, options?: UseDatabaseRecordOptions): UseDatabaseRecordResult<DatabaseRecordRow<K, P>>;
|
|
35
35
|
//#endregion
|
|
36
36
|
export { UseDatabaseRecordOptions, UseDatabaseRecordResult, useDatabaseRecord };
|
|
37
37
|
//# sourceMappingURL=use-database-record.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"use-database-record.d.ts","names":[],"sources":["../../../src/react/hooks/use-database-record.ts"],"mappings":";;;;;;;KAsBY,wBAAA,
|
|
1
|
+
{"version":3,"file":"use-database-record.d.ts","names":[],"sources":["../../../src/react/hooks/use-database-record.ts"],"mappings":";;;;;;;KAsBY,wBAAA,GAA2B,sBAAA;;KAG3B,uBAAA,QAA+B,qBAAA,CAAsB,GAAA;;;;;AAAjE;;;;;;;;;AAyBA;;;;;;;;;;iBAAgB,iBAAA,WACJ,mBAAA,kBACM,oBAAA,CAAqB,CAAA,IAAK,MAAA,eAAA,CAE1C,MAAA,EAAQ,CAAA,EACR,EAAA,EAAI,UAAA,CAAW,CAAA,sBACf,MAAA,GAAS,CAAA,GAAI,mBAAA,CAAoB,CAAA,EAAG,oBAAA,CAAqB,CAAA,IACzD,OAAA,GAAS,wBAAA,GACR,uBAAA,CAAwB,iBAAA,CAAkB,CAAA,EAAG,CAAA"}
|
|
@@ -15,7 +15,7 @@ import { useDatabaseRead } from "./use-database-read.js";
|
|
|
15
15
|
* @param entity - A table the generated registry exposes with a public key
|
|
16
16
|
* @param id - The row's public key, or `null`/`undefined` to wait
|
|
17
17
|
* @param params - `select` and `include`; pass `{}` to reach `options` alone
|
|
18
|
-
* @param options - `enabled
|
|
18
|
+
* @param options - `enabled` and `keepPreviousData`
|
|
19
19
|
* @returns The row, loading and error state, and `refetch`
|
|
20
20
|
*
|
|
21
21
|
* @example
|
|
@@ -43,8 +43,7 @@ function useDatabaseRecord(entity, id, params, options = {}) {
|
|
|
43
43
|
include: recordParams.include,
|
|
44
44
|
enabled,
|
|
45
45
|
accept: isDatabaseRow,
|
|
46
|
-
keepPreviousData: options.keepPreviousData ?? false
|
|
47
|
-
shape: options.shape
|
|
46
|
+
keepPreviousData: options.keepPreviousData ?? false
|
|
48
47
|
});
|
|
49
48
|
}
|
|
50
49
|
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"use-database-record.js","names":[],"sources":["../../../src/react/hooks/use-database-record.ts"],"sourcesContent":["import {\n DatabaseQueryEncodingError,\n encodeDatabaseRecordQuery,\n type ExactDatabaseParams,\n} from \"shared\";\n\nimport { isDatabaseRow } from \"@/js/database/client\";\nimport type {\n DatabaseId,\n DatabaseKeyedEntity,\n DatabaseRecordParams,\n DatabaseRecordRow,\n} from \"@/js/database/types\";\n\nimport {\n type DatabaseReadRequest,\n type UseDatabaseReadOptions,\n type UseDatabaseReadResult,\n useDatabaseRead,\n} from \"./use-database-read\";\n\n/** Options for {@link useDatabaseRecord}. */\nexport type UseDatabaseRecordOptions
|
|
1
|
+
{"version":3,"file":"use-database-record.js","names":[],"sources":["../../../src/react/hooks/use-database-record.ts"],"sourcesContent":["import {\n DatabaseQueryEncodingError,\n encodeDatabaseRecordQuery,\n type ExactDatabaseParams,\n} from \"shared\";\n\nimport { isDatabaseRow } from \"@/js/database/client\";\nimport type {\n DatabaseId,\n DatabaseKeyedEntity,\n DatabaseRecordParams,\n DatabaseRecordRow,\n} from \"@/js/database/types\";\n\nimport {\n type DatabaseReadRequest,\n type UseDatabaseReadOptions,\n type UseDatabaseReadResult,\n useDatabaseRead,\n} from \"./use-database-read\";\n\n/** Options for {@link useDatabaseRecord}. */\nexport type UseDatabaseRecordOptions = UseDatabaseReadOptions;\n\n/** What {@link useDatabaseRecord} returns: one row and its state. */\nexport type UseDatabaseRecordResult<Row> = UseDatabaseReadResult<Row>;\n\n/**\n * Subscribe to one row from `GET /api/database/<entity>/:id`. Only entities\n * with a public primary key have this route; a missing row surfaces as a\n * `NOT_FOUND` error, and a refetch that finds the row gone clears `data`.\n *\n * A `null` or `undefined` id holds the hook idle without a request, so a\n * record that depends on another read needs no separate `enabled` flag. An\n * empty, `\".\"`, or `\"..\"` id reports `INVALID_REQUEST` without a request.\n *\n * @param entity - A table the generated registry exposes with a public key\n * @param id - The row's public key, or `null`/`undefined` to wait\n * @param params - `select` and `include`; pass `{}` to reach `options` alone\n * @param options - `enabled` and `keepPreviousData`\n * @returns The row, loading and error state, and `refetch`\n *\n * @example\n * ```tsx\n * const board = useDatabaseRecord(\"boards\", selectedId, {\n * include: { notes: { limit: 20 } },\n * });\n * board.data?.notes.length;\n * ```\n */\nexport function useDatabaseRecord<\n K extends DatabaseKeyedEntity,\n const P extends DatabaseRecordParams<K> = Record<never, never>,\n>(\n entity: K,\n id: DatabaseId<K> | null | undefined,\n params?: P & ExactDatabaseParams<P, DatabaseRecordParams<K>>,\n options: UseDatabaseRecordOptions = {},\n): UseDatabaseRecordResult<DatabaseRecordRow<K, P>> {\n const enabled = (options.enabled ?? true) && id !== null && id !== undefined;\n const recordParams = (params ?? {}) as { include?: unknown };\n // Encode only an enabled read: a held read's params may still be incomplete.\n let query: DatabaseReadRequest[\"query\"] = \"\";\n if (enabled) {\n try {\n query = encodeDatabaseRecordQuery(recordParams);\n } catch (error) {\n query = error instanceof DatabaseQueryEncodingError ? error : null;\n }\n }\n const read = useDatabaseRead({\n entity,\n operation: \"detail\",\n id: id ?? undefined,\n query,\n include: recordParams.include,\n enabled,\n accept: isDatabaseRow,\n keepPreviousData: options.keepPreviousData ?? false,\n });\n // The server projected and encoded the row; the types describe that wire.\n return read as UseDatabaseRecordResult<DatabaseRecordRow<K, P>>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,kBAId,QACA,IACA,QACA,UAAoC,EAAE,EACY;CAClD,MAAM,WAAW,QAAQ,WAAW,SAAS,OAAO,QAAQ,OAAO;CACnE,MAAM,eAAgB,UAAU,EAAE;CAElC,IAAI,QAAsC;AAC1C,KAAI,QACF,KAAI;AACF,UAAQ,0BAA0B,aAAa;UACxC,OAAO;AACd,UAAQ,iBAAiB,6BAA6B,QAAQ;;AAclE,QAXa,gBAAgB;EAC3B;EACA,WAAW;EACX,IAAI,MAAM;EACV;EACA,SAAS,aAAa;EACtB;EACA,QAAQ;EACR,kBAAkB,QAAQ,oBAAoB;EAC/C,CAAC"}
|
|
@@ -21,9 +21,9 @@ interface UseDatabaseWriteState<T> {
|
|
|
21
21
|
interface UseDatabaseWriteOptions {
|
|
22
22
|
/**
|
|
23
23
|
* Reads to restart once a write succeeds. Default `true`: every mounted
|
|
24
|
-
* database read, since a
|
|
25
|
-
*
|
|
26
|
-
* directly or through an include; `false` restarts none.
|
|
24
|
+
* database read, since a foreign key declared with `onDelete("cascade")` can
|
|
25
|
+
* change other tables too. A table list restarts only the reads that show
|
|
26
|
+
* those tables, directly or through an include; `false` restarts none.
|
|
27
27
|
*/
|
|
28
28
|
invalidate?: DatabaseInvalidation;
|
|
29
29
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"use-database-write.js","names":[],"sources":["../../../src/react/hooks/use-database-write.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport type { DatabaseApiError } from \"@/js/database/errors\";\n\nimport {\n asDatabaseApiError,\n type DatabaseInvalidation,\n invalidateDatabaseReads,\n} from \"./database-request-store\";\n\nexport type { DatabaseInvalidation } from \"./database-request-store\";\n\n/** Latest state of a database write hook. */\nexport interface UseDatabaseWriteState<T> {\n /** The latest call's result, or `null` before it answers. */\n data: T | null;\n /**\n * Whether the latest call is in flight, including the reload of the reads\n * it restarts.\n */\n loading: boolean;\n /**\n * Why the latest call failed: `NOT_EXPOSED` when no route exists,\n * `OUTCOME_UNKNOWN` when it may have committed without an answer.\n */\n error: DatabaseApiError | null;\n}\n\n/** Options every database write hook takes. */\nexport interface UseDatabaseWriteOptions {\n /**\n * Reads to restart once a write succeeds. Default `true`: every mounted\n * database read, since a
|
|
1
|
+
{"version":3,"file":"use-database-write.js","names":[],"sources":["../../../src/react/hooks/use-database-write.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport type { DatabaseApiError } from \"@/js/database/errors\";\n\nimport {\n asDatabaseApiError,\n type DatabaseInvalidation,\n invalidateDatabaseReads,\n} from \"./database-request-store\";\n\nexport type { DatabaseInvalidation } from \"./database-request-store\";\n\n/** Latest state of a database write hook. */\nexport interface UseDatabaseWriteState<T> {\n /** The latest call's result, or `null` before it answers. */\n data: T | null;\n /**\n * Whether the latest call is in flight, including the reload of the reads\n * it restarts.\n */\n loading: boolean;\n /**\n * Why the latest call failed: `NOT_EXPOSED` when no route exists,\n * `OUTCOME_UNKNOWN` when it may have committed without an answer.\n */\n error: DatabaseApiError | null;\n}\n\n/** Options every database write hook takes. */\nexport interface UseDatabaseWriteOptions {\n /**\n * Reads to restart once a write succeeds. Default `true`: every mounted\n * database read, since a foreign key declared with `onDelete(\"cascade\")` can\n * change other tables too. A table list restarts only the reads that show\n * those tables, directly or through an include; `false` restarts none.\n */\n invalidate?: DatabaseInvalidation;\n}\n\n/** The generic write lifecycle's callbacks, before each hook names its args. */\ninterface WriteCallbacks<Args extends unknown[], T> {\n invalidate?: DatabaseInvalidation;\n onSuccess?: (data: T, args: Args) => void;\n onError?: (error: DatabaseApiError, args: Args) => void;\n}\n\ninterface DatabaseWrite<\n Args extends unknown[],\n T,\n> extends UseDatabaseWriteState<T> {\n mutate(...args: Args): Promise<T | null>;\n reset(): void;\n}\n\nconst IDLE: UseDatabaseWriteState<never> = Object.freeze({\n data: null,\n loading: false,\n error: null,\n});\n\n/**\n * Run a caller's callback without letting it break the write's promise: the\n * call still resolves, and the exception still reaches the page's error\n * handling (and any error tracker) as an uncaught error.\n */\nfunction runCallback(callback: () => void): void {\n try {\n callback();\n } catch (error) {\n if (typeof globalThis.reportError === \"function\") {\n globalThis.reportError(error);\n } else {\n setTimeout(() => {\n throw error;\n });\n }\n }\n}\n\n/**\n * One write hook's state around `send`, which must be stable per entity.\n *\n * A call never rejects, like `useServingInvoke`: it resolves with the result,\n * or with `null` once the failure is in `error`, so a handler needs no\n * `try/catch`. Callers that want an exception use `databaseApi` directly.\n *\n * A write is never aborted: cancelling the request would not undo a committed\n * transaction. A successful call restarts the reads `invalidate` names and\n * resolves once they have reloaded, so a handler that clears its form sees the\n * new rows already on screen. Only the latest call of a hook updates its\n * state; callbacks run for every call, even after the hook unmounts, since the\n * rows did change.\n */\nexport function useDatabaseWrite<Args extends unknown[], T>(\n send: (...args: Args) => Promise<T>,\n options: WriteCallbacks<Args, T>,\n): DatabaseWrite<Args, T> {\n const [state, setState] = useState<UseDatabaseWriteState<T>>(IDLE);\n const latest = useRef<symbol | null>(null);\n\n // Read at call time, so inline callbacks and an inline `invalidate` list do\n // not change `mutate`'s identity on every render.\n const optionsRef = useRef(options);\n useEffect(() => {\n optionsRef.current = options;\n });\n\n const mutate = useCallback(\n async (...args: Args): Promise<T | null> => {\n const call = Symbol(\"database write\");\n latest.current = call;\n // React ignores a state update after unmount, so only staleness matters.\n const settle = (next: UseDatabaseWriteState<T>) => {\n if (latest.current === call) setState(next);\n };\n\n settle({ data: null, loading: true, error: null });\n let data: T;\n try {\n data = await send(...args);\n } catch (cause) {\n const error = asDatabaseApiError(cause);\n settle({ data: null, loading: false, error });\n const { onError } = optionsRef.current;\n if (onError) runCallback(() => onError(error, args));\n return null;\n }\n // Hold `loading` until the restarted reads answer, so the hook does not\n // report success beside rows that still show the old state.\n await invalidateDatabaseReads(optionsRef.current.invalidate ?? true);\n settle({ data, loading: false, error: null });\n const { onSuccess } = optionsRef.current;\n if (onSuccess) runCallback(() => onSuccess(data, args));\n return data;\n },\n [send],\n );\n\n // A call still in flight keeps running, but no longer reports here.\n const reset = useCallback(() => {\n latest.current = null;\n setState(IDLE);\n }, []);\n\n return { ...state, mutate, reset };\n}\n"],"mappings":";;;;AAsDA,MAAM,OAAqC,OAAO,OAAO;CACvD,MAAM;CACN,SAAS;CACT,OAAO;CACR,CAAC;;;;;;AAOF,SAAS,YAAY,UAA4B;AAC/C,KAAI;AACF,YAAU;UACH,OAAO;AACd,MAAI,OAAO,WAAW,gBAAgB,WACpC,YAAW,YAAY,MAAM;MAE7B,kBAAiB;AACf,SAAM;IACN;;;;;;;;;;;;;;;;;AAmBR,SAAgB,iBACd,MACA,SACwB;CACxB,MAAM,CAAC,OAAO,YAAY,SAAmC,KAAK;CAClE,MAAM,SAAS,OAAsB,KAAK;CAI1C,MAAM,aAAa,OAAO,QAAQ;AAClC,iBAAgB;AACd,aAAW,UAAU;GACrB;CAEF,MAAM,SAAS,YACb,OAAO,GAAG,SAAkC;EAC1C,MAAM,OAAO,OAAO,iBAAiB;AACrC,SAAO,UAAU;EAEjB,MAAM,UAAU,SAAmC;AACjD,OAAI,OAAO,YAAY,KAAM,UAAS,KAAK;;AAG7C,SAAO;GAAE,MAAM;GAAM,SAAS;GAAM,OAAO;GAAM,CAAC;EAClD,IAAI;AACJ,MAAI;AACF,UAAO,MAAM,KAAK,GAAG,KAAK;WACnB,OAAO;GACd,MAAM,QAAQ,mBAAmB,MAAM;AACvC,UAAO;IAAE,MAAM;IAAM,SAAS;IAAO;IAAO,CAAC;GAC7C,MAAM,EAAE,YAAY,WAAW;AAC/B,OAAI,QAAS,mBAAkB,QAAQ,OAAO,KAAK,CAAC;AACpD,UAAO;;AAIT,QAAM,wBAAwB,WAAW,QAAQ,cAAc,KAAK;AACpE,SAAO;GAAE;GAAM,SAAS;GAAO,OAAO;GAAM,CAAC;EAC7C,MAAM,EAAE,cAAc,WAAW;AACjC,MAAI,UAAW,mBAAkB,UAAU,MAAM,KAAK,CAAC;AACvD,SAAO;IAET,CAAC,KAAK,CACP;CAGD,MAAM,QAAQ,kBAAkB;AAC9B,SAAO,UAAU;AACjB,WAAS,KAAK;IACb,EAAE,CAAC;AAEN,QAAO;EAAE,GAAG;EAAO;EAAQ;EAAO"}
|
|
@@ -5,7 +5,7 @@ import * as class_variance_authority_types0 from "class-variance-authority/types
|
|
|
5
5
|
|
|
6
6
|
//#region src/react/ui/button.d.ts
|
|
7
7
|
declare const buttonVariants: (props?: ({
|
|
8
|
-
variant?: "default" | "
|
|
8
|
+
variant?: "default" | "link" | "destructive" | "secondary" | "outline" | "ghost" | null | undefined;
|
|
9
9
|
size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | "icon-lg" | null | undefined;
|
|
10
10
|
} & class_variance_authority_types0.ClassProp) | undefined) => string;
|
|
11
11
|
/** Clickable button with multiple variants and sizes */
|
|
@@ -103,10 +103,7 @@ type RecordRowFor<R, K, P> = ListRowFor<R, K, P>;
|
|
|
103
103
|
type InsertFor<R, K> = WireInput<ApiOf<R, K>["insert"]>;
|
|
104
104
|
/** The body a generated update route accepts for `K`, as JSON carries it. */
|
|
105
105
|
type UpdateFor<R, K> = WireInput<ApiOf<R, K>["update"]>;
|
|
106
|
-
/**
|
|
107
|
-
* The public row a generated create or update route answers with. A read
|
|
108
|
-
* serializer never reshapes a write's response, so this is always the row.
|
|
109
|
-
*/
|
|
106
|
+
/** The public row a generated create or update route answers with. */
|
|
110
107
|
type PublicRowFor<R, K> = WireOutput<PublicRowOf<R, K>>;
|
|
111
108
|
/** The envelope a generated list route answers with. */
|
|
112
109
|
interface DatabaseListPage<Row> {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"api-types.d.ts","names":[],"sources":["../../../../../shared/src/database/api-types.ts"],"mappings":";;AAOA;;;;;UAAiB,gBAAA;EAIN;EAAA,SAFA,SAAA,EAAW,MAAA;EAIX;EAAA,SAFA,QAAA,EAAU,MAAA;EAIR;EAAA,SAFF,GAAA;IAAA,SACE,MAAA;IAAA,SACA,MAAA;IAAA,SACA,OAAA,UAIG;IAAA,SAFH,SAAA,UAMC;IAAA,SAJD,GAAA;EAAA;AAAA;AAAA,KAIR,SAAA;;KAGO,UAAA,MAAgB,CAAA,2BAExB,CAAA,gCACE,UAAA,CAAW,CAAA,MACX,CAAA,gCACgB,CAAA,GAAI,UAAA,CAAW,CAAA,CAAE,CAAA,OAC/B,CAAA;;KAGI,SAAA,MAAe,CAAA,oCAEvB,CAAA,yCACW,SAAA,CAAU,CAAA,MACnB,CAAA,gCACgB,CAAA,GAAI,SAAA,CAAU,CAAA,CAAE,CAAA,OAC9B,CAAA;;KAGI,oBAAA,MAA0B,OAAA,qBAChB,CAAA,mBAAoB,CAAA,WAAY,CAAA;AAAA,KAIjD,OAAA,SAAgB,CAAA,eAAgB,CAAA,GACjC,CAAA,CAAE,CAAA,UAAW,gBAAA,GACX,CAAA,CAAE,CAAA;AAAA,KAGH,WAAA,SAAoB,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,KAC/B,KAAA,SAAc,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,KACzB,UAAA,SAAmB,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,KAC9B,UAAA,mBAA6B,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,QAAA,SAC3C,UAAA,CAAW,CAAA,EAAG,CAAA;AAAA,KACjB,QAAA,mBACH,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,QAAA;EAAoB,EAAA;AAAA,IAAqB,MAAA;AAAA,KACvD,QAAA,mBACH,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,QAAA;EAAoB,IAAA;AAAA;AAAA,KAElC,YAAA,eAA2B,WAAA,CAAY,CAAA,EAAG,CAAA;AAAA,KAC1C,QAAA,SAAiB,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,KACzC,aAAA,kCACK,IAAA,GAAO,MAAA,CAAO,GAAA,oBACpB,OAAA,CAAQ,MAAA,CAAO,OAAA,CAAQ,IAAA,EAAM,GAAA,sBAC/B,IAAA;;AAlCF;;;KAwCY,cAAA,cACJ,oBAAA,CAAqB,CAAA,KAAM,KAAA,CAAM,CAAA,EAAG,CAAA,oCAEtC,CAAA,GACJ,oBAAA,CAAqB,CAAA;AAAA,KAElB,UAAA,SAAmB,WAAA,CAAY,CAAA,EAAG,CAAA,EAAG,KAAA,CAAM,CAAA,EAAG,CAAA,iBAC3C,WAAA,CAAY,CAAA,EAAG,CAAA;;;;;;KAOX,KAAA,SAAc,OAAA,CACxB,UAAA,CAAW,CAAA,EAAG,CAAA,4BACD,SAAA,WACT,UAAA,CAAW,CAAA,EAAG,CAAA;;;;;KAQf,iBAAA;EAAA,SACM,MAAA,YAAkB,YAAA,CAAa,CAAA,EAAG,MAAA;EAAA,SAClC,KAAA,GAAQ,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,MAAA;EAAA,SAC3B,KAAA,GAAQ,QAAA,CAAS,CAAA,EAAG,MAAA;AAAA,KAC1B,MAAA;EAAA,SACU,KAAA;AAAA;EAAA,SACA,KAAA;AAAA,MACZ,MAAA;EAAA,SACc,OAAA,GAAU,iBAAA,CAAkB,CAAA,EAAG,MAAA;AAAA;EAAA,SAC/B,OAAA;AAAA;AAjEjB;;;;AAAA,KAuEY,iBAAA,sEACkB,UAAA,CAAW,CAAA,EAAG,CAAA,YAEtC,iBAAA,CACE,CAAA,EACA,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GACf,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GACf,MAAA;;KAKI,aAAA;EAAA,SACD,KAAA,GAAQ,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,CAAA;EAAA,SAC3B,MAAA,YAAkB,YAAA,CAAa,CAAA,EAAG,CAAA;EAAA,SAClC,OAAA,GAAU,iBAAA,CAAkB,CAAA,EAAG,CAAA;EAAA,SAC/B,KAAA;EAAA,SACA,MAAA;AAAA,MACL,KAAA,CAAM,CAAA,EAAG,CAAA;EAAA,SACA,KAAA,EAAO,aAAA,CAAc,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA;EAAA,SAC9B,KAAA,GAAQ,QAAA,CAAS,CAAA,EAAG,CAAA;AAAA;;KAGvB,eAAA,SAAwB,IAAA,CAClC,aAAA,CAAc,CAAA,EAAG,CAAA;AAAA,KAKd,UAAA,YAAsB,CAAA;EAAA,SAChB,MAAA,iCAAuC,WAAA;AAAA,mBAE/B,OAAA,aACb,OAAA,CACE,IAAA,CAAK,WAAA,CAAY,CAAA,EAAG,CAAA,GAAI,OAAA,iBAAwB,WAAA,CAAY,CAAA,EAAG,CAAA,MAEjE,IAAA,CAAK,WAAA,CAAY,CAAA,EAAG,CAAA,GAAI,OAAA,iBAAwB,WAAA,CAAY,CAAA,EAAG,CAAA,4BAC1C,CAAA,GACrB,OAAA,CAAQ,WAAA,CAAY,CAAA,EAAG,CAAA,KACvB,WAAA,CAAY,CAAA,EAAG,CAAA;AAAA,KAEhB,UAAA,YAAsB,CAAA;EAAA,SAAqB,OAAA;AAAA,yBAEvB,CAAA,SAAU,UAAA,CAAW,CAAA,EAAG,CAAA,IAAK,QAAA,CAC9C,CAAA,EACA,CAAA,EACA,QAAA,iBAEE,KAAA,CAAM,CAAA,EAAG,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GAAW,CAAA,CAAE,QAAA,OACrC,KAAA,CAAM,CAAA,EAAG,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GAAW,CAAA,CAAE,QAAA;AAAA,KAI1C,KAAA,YAAiB,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA,IAAK,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGjD,UAAA,YAAsB,UAAA,CAAW,KAAA,CAAM,CAAA,EAAG,CAAA,EAAG,CAAA;;KAG7C,YAAA,YAAwB,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGzC,SAAA,SAAkB,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,CAAA;;KAGrC,SAAA,SAAkB,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,CAAA
|
|
1
|
+
{"version":3,"file":"api-types.d.ts","names":[],"sources":["../../../../../shared/src/database/api-types.ts"],"mappings":";;AAOA;;;;;UAAiB,gBAAA;EAIN;EAAA,SAFA,SAAA,EAAW,MAAA;EAIX;EAAA,SAFA,QAAA,EAAU,MAAA;EAIR;EAAA,SAFF,GAAA;IAAA,SACE,MAAA;IAAA,SACA,MAAA;IAAA,SACA,OAAA,UAIG;IAAA,SAFH,SAAA,UAMC;IAAA,SAJD,GAAA;EAAA;AAAA;AAAA,KAIR,SAAA;;KAGO,UAAA,MAAgB,CAAA,2BAExB,CAAA,gCACE,UAAA,CAAW,CAAA,MACX,CAAA,gCACgB,CAAA,GAAI,UAAA,CAAW,CAAA,CAAE,CAAA,OAC/B,CAAA;;KAGI,SAAA,MAAe,CAAA,oCAEvB,CAAA,yCACW,SAAA,CAAU,CAAA,MACnB,CAAA,gCACgB,CAAA,GAAI,SAAA,CAAU,CAAA,CAAE,CAAA,OAC9B,CAAA;;KAGI,oBAAA,MAA0B,OAAA,qBAChB,CAAA,mBAAoB,CAAA,WAAY,CAAA;AAAA,KAIjD,OAAA,SAAgB,CAAA,eAAgB,CAAA,GACjC,CAAA,CAAE,CAAA,UAAW,gBAAA,GACX,CAAA,CAAE,CAAA;AAAA,KAGH,WAAA,SAAoB,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,KAC/B,KAAA,SAAc,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,KACzB,UAAA,SAAmB,OAAA,CAAQ,CAAA,EAAG,CAAA;AAAA,KAC9B,UAAA,mBAA6B,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,QAAA,SAC3C,UAAA,CAAW,CAAA,EAAG,CAAA;AAAA,KACjB,QAAA,mBACH,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,QAAA;EAAoB,EAAA;AAAA,IAAqB,MAAA;AAAA,KACvD,QAAA,mBACH,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,QAAA;EAAoB,IAAA;AAAA;AAAA,KAElC,YAAA,eAA2B,WAAA,CAAY,CAAA,EAAG,CAAA;AAAA,KAC1C,QAAA,SAAiB,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA,KACzC,aAAA,kCACK,IAAA,GAAO,MAAA,CAAO,GAAA,oBACpB,OAAA,CAAQ,MAAA,CAAO,OAAA,CAAQ,IAAA,EAAM,GAAA,sBAC/B,IAAA;;AAlCF;;;KAwCY,cAAA,cACJ,oBAAA,CAAqB,CAAA,KAAM,KAAA,CAAM,CAAA,EAAG,CAAA,oCAEtC,CAAA,GACJ,oBAAA,CAAqB,CAAA;AAAA,KAElB,UAAA,SAAmB,WAAA,CAAY,CAAA,EAAG,CAAA,EAAG,KAAA,CAAM,CAAA,EAAG,CAAA,iBAC3C,WAAA,CAAY,CAAA,EAAG,CAAA;;;;;;KAOX,KAAA,SAAc,OAAA,CACxB,UAAA,CAAW,CAAA,EAAG,CAAA,4BACD,SAAA,WACT,UAAA,CAAW,CAAA,EAAG,CAAA;;;;;KAQf,iBAAA;EAAA,SACM,MAAA,YAAkB,YAAA,CAAa,CAAA,EAAG,MAAA;EAAA,SAClC,KAAA,GAAQ,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,MAAA;EAAA,SAC3B,KAAA,GAAQ,QAAA,CAAS,CAAA,EAAG,MAAA;AAAA,KAC1B,MAAA;EAAA,SACU,KAAA;AAAA;EAAA,SACA,KAAA;AAAA,MACZ,MAAA;EAAA,SACc,OAAA,GAAU,iBAAA,CAAkB,CAAA,EAAG,MAAA;AAAA;EAAA,SAC/B,OAAA;AAAA;AAjEjB;;;;AAAA,KAuEY,iBAAA,sEACkB,UAAA,CAAW,CAAA,EAAG,CAAA,YAEtC,iBAAA,CACE,CAAA,EACA,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GACf,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GACf,MAAA;;KAKI,aAAA;EAAA,SACD,KAAA,GAAQ,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,CAAA;EAAA,SAC3B,MAAA,YAAkB,YAAA,CAAa,CAAA,EAAG,CAAA;EAAA,SAClC,OAAA,GAAU,iBAAA,CAAkB,CAAA,EAAG,CAAA;EAAA,SAC/B,KAAA;EAAA,SACA,MAAA;AAAA,MACL,KAAA,CAAM,CAAA,EAAG,CAAA;EAAA,SACA,KAAA,EAAO,aAAA,CAAc,KAAA,CAAM,CAAA,EAAG,CAAA;AAAA;EAAA,SAC9B,KAAA,GAAQ,QAAA,CAAS,CAAA,EAAG,CAAA;AAAA;;KAGvB,eAAA,SAAwB,IAAA,CAClC,aAAA,CAAc,CAAA,EAAG,CAAA;AAAA,KAKd,UAAA,YAAsB,CAAA;EAAA,SAChB,MAAA,iCAAuC,WAAA;AAAA,mBAE/B,OAAA,aACb,OAAA,CACE,IAAA,CAAK,WAAA,CAAY,CAAA,EAAG,CAAA,GAAI,OAAA,iBAAwB,WAAA,CAAY,CAAA,EAAG,CAAA,MAEjE,IAAA,CAAK,WAAA,CAAY,CAAA,EAAG,CAAA,GAAI,OAAA,iBAAwB,WAAA,CAAY,CAAA,EAAG,CAAA,4BAC1C,CAAA,GACrB,OAAA,CAAQ,WAAA,CAAY,CAAA,EAAG,CAAA,KACvB,WAAA,CAAY,CAAA,EAAG,CAAA;AAAA,KAEhB,UAAA,YAAsB,CAAA;EAAA,SAAqB,OAAA;AAAA,yBAEvB,CAAA,SAAU,UAAA,CAAW,CAAA,EAAG,CAAA,IAAK,QAAA,CAC9C,CAAA,EACA,CAAA,EACA,QAAA,iBAEE,KAAA,CAAM,CAAA,EAAG,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GAAW,CAAA,CAAE,QAAA,OACrC,KAAA,CAAM,CAAA,EAAG,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,QAAA,GAAW,CAAA,CAAE,QAAA;AAAA,KAI1C,KAAA,YAAiB,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA,IAAK,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGjD,UAAA,YAAsB,UAAA,CAAW,KAAA,CAAM,CAAA,EAAG,CAAA,EAAG,CAAA;;KAG7C,YAAA,YAAwB,UAAA,CAAW,CAAA,EAAG,CAAA,EAAG,CAAA;;KAGzC,SAAA,SAAkB,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,CAAA;;KAGrC,SAAA,SAAkB,SAAA,CAAU,KAAA,CAAM,CAAA,EAAG,CAAA;;KAGrC,YAAA,SAAqB,UAAA,CAAW,WAAA,CAAY,CAAA,EAAG,CAAA;AApIlD;AAAA,UAuIQ,gBAAA;EACf,KAAA,EAAO,GAAA;EACP,KAAA;EACA,MAAA;AAAA;AAAA,KAGG,MAAA,MAAY,CAAA,yBAA0B,CAAA;AAAA,KACtC,UAAA,cAAwB,WAAA,IAAe,CAAA,mBACxC,CAAA,eAAgB,CAAA,GACd,CAAA,CAAE,CAAA;AAAA,KAGH,YAAA,MAAkB,OAAA,CAAQ,CAAA,EAAG,SAAA;AAAA,KAC7B,SAAA,MAAe,CAAA,gCAAiC,CAAA;AAAA,KAEhD,eAAA,yBAAwC,CAAA,GACzC,CAAA,GACA,mBAAA,CAAoB,CAAA,EAAG,WAAA,CAAY,CAAA;;;;;AArJF;;;KA8JzB,mBAAA,aAAgC,CAAA,SAAU,SAAA,GAClD,CAAA,GACA,CAAA,qDACyB,CAAA,GAAI,mBAAA,CAAoB,CAAA,CAAE,CAAA,GAAI,SAAA,CAAU,KAAA,qBAEjD,CAAA,GAAI,CAAA,SAAU,MAAA,CAAO,YAAA,CAAa,KAAA,KAC1C,eAAA,CAAgB,CAAA,CAAE,CAAA,GAAI,UAAA,CAAW,YAAA,CAAa,KAAA,GAAQ,CAAA"}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import { DatabaseApiEntityFor, DatabaseApiEntry, DatabaseListPage, ExactDatabaseParams, HttpIncludeArgFor, IdFor, InsertFor, KeyedEntityFor, ListParamsFor, ListRowFor, PublicRowFor, RecordParamsFor, RecordRowFor, UpdateFor, WireInput, WireOutput } from "./api-types.js";
|
|
2
|
+
import { DatabaseErrorCategory, DatabaseErrorDetail } from "./errors.js";
|
|
3
|
+
import "./operations.js";
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
//#region ../shared/src/database/operations.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Names the UI resolves without importing a server module. Empty until
|
|
4
|
+
* generation adds one entry per operation name. The declaration is global so
|
|
5
|
+
* a generated `database.d.ts` can augment it without importing this module.
|
|
6
|
+
*/
|
|
7
|
+
declare global {
|
|
8
|
+
interface DatabricksAppKitDatabaseOperations {}
|
|
9
|
+
}
|
|
10
|
+
/** The same global registry, available as a module type for package exports. */
|
|
11
|
+
//# sourceMappingURL=operations.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"operations.d.ts","names":[],"sources":["../../../../../shared/src/database/operations.ts"],"mappings":";;;;;;QAuBQ,MAAA;EAAA,UAEI,kCAAA;AAAA"}
|
|
@@ -5,6 +5,7 @@ import { PluginClientConfigs, PluginEndpointMap, PluginEndpoints } from "./plugi
|
|
|
5
5
|
import "./cache.js";
|
|
6
6
|
import { DatabaseApiEntityFor, DatabaseApiEntry, DatabaseListPage, ExactDatabaseParams, HttpIncludeArgFor, IdFor, InsertFor, KeyedEntityFor, ListParamsFor, ListRowFor, PublicRowFor, RecordParamsFor, RecordRowFor, UpdateFor, WireInput, WireOutput } from "./database/api-types.js";
|
|
7
7
|
import { DatabaseErrorCategory, DatabaseErrorDetail } from "./database/errors.js";
|
|
8
|
+
import "./database/index.js";
|
|
8
9
|
import { GenieAttachmentResponse, GenieMessageResponse, GenieStatementResponse, GenieStreamEvent } from "./genie.js";
|
|
9
10
|
import { MetricFilter, MetricFilterOperatorName, MetricOrderBy, MetricOrderDirection, MetricPredicate } from "./metric-filter.js";
|
|
10
11
|
import { MetricViewColumnDisplay } from "./metric-metadata.js";
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Class: DatabaseValidationError
|
|
2
2
|
|
|
3
|
-
Deliberate validation failure
|
|
3
|
+
Deliberate validation failure. An explicit transaction callback can throw it, and the transaction rethrows that same error. Generated routes answer `422` and echo only the issues naming a public column. Every other failure stays an opaque server error.
|
|
4
4
|
|
|
5
5
|
## Extends[](#extends "Direct link to Extends")
|
|
6
6
|
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Function: defineOperation()
|
|
2
|
+
|
|
3
|
+
## Call Signature[](#call-signature "Direct link to Call Signature")
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
function defineOperation<Name, M, I, O, R>(definition: OperationFields<M, I, O, Name> & {
|
|
7
|
+
authorize: ResourcePolicy<ParsedInput<I>, R>;
|
|
8
|
+
execute: (context: OperationContext<ParsedInput<I>, NonNullable<Awaited<R>>>) => Awaitable<ExecuteResult<M, O>>;
|
|
9
|
+
}): OperationDefinition<M, I, O, R, Name>;
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Declare one database operation. `name` is its public identifier. Declare an `input` Zod schema to accept parameters; without one, callbacks receive `undefined`. Declare an `output` Zod schema to answer a body; without one, the operation answers none. Definition only freezes a descriptor.
|
|
14
|
+
|
|
15
|
+
### Type Parameters[](#type-parameters "Direct link to Type Parameters")
|
|
16
|
+
|
|
17
|
+
| Type Parameter |
|
|
18
|
+
| --------------------------------------- |
|
|
19
|
+
| `Name` *extends* `string` |
|
|
20
|
+
| `M` *extends* `DatabaseOperationMethod` |
|
|
21
|
+
| `I` *extends* `SchemaSlot` |
|
|
22
|
+
| `O` *extends* `SchemaSlot` |
|
|
23
|
+
| `R` *extends* { } |
|
|
24
|
+
|
|
25
|
+
### Parameters[](#parameters "Direct link to Parameters")
|
|
26
|
+
|
|
27
|
+
| Parameter | Type |
|
|
28
|
+
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| `definition` | `OperationFields`<`M`, `I`, `O`, `Name`> & { `authorize`: `ResourcePolicy`<`ParsedInput`<`I`>, `R`>; `execute`: (`context`: [`OperationContext`](./docs/api/appkit/Interface.OperationContext.md)<`ParsedInput`<`I`>, `NonNullable`<`Awaited`<`R`>>>) => `Awaitable`<`ExecuteResult`<`M`, `O`>>; } |
|
|
30
|
+
|
|
31
|
+
### Returns[](#returns "Direct link to Returns")
|
|
32
|
+
|
|
33
|
+
[`OperationDefinition`](./docs/api/appkit/Interface.OperationDefinition.md)<`M`, `I`, `O`, `R`, `Name`>
|
|
34
|
+
|
|
35
|
+
## Call Signature[](#call-signature-1 "Direct link to Call Signature")
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
function defineOperation<Name, M, I, O>(definition: OperationOptions<M, I, O, undefined, Name>): OperationDefinition<M, I, O, undefined, Name>;
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Declare one database operation. `name` is its public identifier. Declare an `input` Zod schema to accept parameters; without one, callbacks receive `undefined`. Declare an `output` Zod schema to answer a body; without one, the operation answers none. Definition only freezes a descriptor.
|
|
43
|
+
|
|
44
|
+
### Type Parameters[](#type-parameters-1 "Direct link to Type Parameters")
|
|
45
|
+
|
|
46
|
+
| Type Parameter | Default type |
|
|
47
|
+
| --------------------------------------- | ------------ |
|
|
48
|
+
| `Name` *extends* `string` | - |
|
|
49
|
+
| `M` *extends* `DatabaseOperationMethod` | - |
|
|
50
|
+
| `I` *extends* `SchemaSlot` | `undefined` |
|
|
51
|
+
| `O` *extends* `SchemaSlot` | `undefined` |
|
|
52
|
+
|
|
53
|
+
### Parameters[](#parameters-1 "Direct link to Parameters")
|
|
54
|
+
|
|
55
|
+
| Parameter | Type |
|
|
56
|
+
| ------------ | ------------------------------------------------------ |
|
|
57
|
+
| `definition` | `OperationOptions`<`M`, `I`, `O`, `undefined`, `Name`> |
|
|
58
|
+
|
|
59
|
+
### Returns[](#returns-1 "Direct link to Returns")
|
|
60
|
+
|
|
61
|
+
[`OperationDefinition`](./docs/api/appkit/Interface.OperationDefinition.md)<`M`, `I`, `O`, `undefined`, `Name`>
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Function: definePolicy()
|
|
2
|
+
|
|
3
|
+
## Call Signature[](#call-signature "Direct link to Call Signature")
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
function definePolicy<In>(policy: AllowPolicy<In>): AllowPolicy<In>;
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Declare a reusable authorization rule. Without `resource` it decides from the actor and input. With `resource` it loads one record first, from the same context every callback receives, `actor` included; annotate the lookup context to fix the input the policy needs. `allow` may return `true`, `false`, or `{ deny }`.
|
|
11
|
+
|
|
12
|
+
### Type Parameters[](#type-parameters "Direct link to Type Parameters")
|
|
13
|
+
|
|
14
|
+
| Type Parameter | Default type |
|
|
15
|
+
| -------------- | ------------ |
|
|
16
|
+
| `In` | `unknown` |
|
|
17
|
+
|
|
18
|
+
### Parameters[](#parameters "Direct link to Parameters")
|
|
19
|
+
|
|
20
|
+
| Parameter | Type |
|
|
21
|
+
| --------- | ------------------- |
|
|
22
|
+
| `policy` | `AllowPolicy`<`In`> |
|
|
23
|
+
|
|
24
|
+
### Returns[](#returns "Direct link to Returns")
|
|
25
|
+
|
|
26
|
+
`AllowPolicy`<`In`>
|
|
27
|
+
|
|
28
|
+
## Call Signature[](#call-signature-1 "Direct link to Call Signature")
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
function definePolicy<In, R>(policy: ResourcePolicy<In, R>): ResourcePolicy<In, R>;
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Declare a reusable authorization rule. Without `resource` it decides from the actor and input. With `resource` it loads one record first, from the same context every callback receives, `actor` included; annotate the lookup context to fix the input the policy needs. `allow` may return `true`, `false`, or `{ deny }`.
|
|
36
|
+
|
|
37
|
+
### Type Parameters[](#type-parameters-1 "Direct link to Type Parameters")
|
|
38
|
+
|
|
39
|
+
| Type Parameter |
|
|
40
|
+
| -------------- |
|
|
41
|
+
| `In` |
|
|
42
|
+
| `R` |
|
|
43
|
+
|
|
44
|
+
### Parameters[](#parameters-1 "Direct link to Parameters")
|
|
45
|
+
|
|
46
|
+
| Parameter | Type |
|
|
47
|
+
| --------- | --------------------------- |
|
|
48
|
+
| `policy` | `ResourcePolicy`<`In`, `R`> |
|
|
49
|
+
|
|
50
|
+
### Returns[](#returns-1 "Direct link to Returns")
|
|
51
|
+
|
|
52
|
+
`ResourcePolicy`<`In`, `R`>
|
|
@@ -5,7 +5,7 @@ function defineSchema<TTables>(builder: (context: SchemaBuilderContext) => TTabl
|
|
|
5
5
|
|
|
6
6
|
```
|
|
7
7
|
|
|
8
|
-
Compile one declared schema. The returned type keeps the table names the builder returned, so `api.tables`
|
|
8
|
+
Compile one declared schema. The returned type keeps the table names the builder returned, so `api.tables` can name only real tables.
|
|
9
9
|
|
|
10
10
|
## Type Parameters[](#type-parameters "Direct link to Type Parameters")
|
|
11
11
|
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Interface: Actor
|
|
2
|
+
|
|
3
|
+
The authenticated caller. The HTTP boundary resolves it before any policy runs.
|
|
4
|
+
|
|
5
|
+
## Properties[](#properties "Direct link to Properties")
|
|
6
|
+
|
|
7
|
+
### email?[](#email "Direct link to email?")
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
readonly optional email: string;
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
***
|
|
15
|
+
|
|
16
|
+
### id[](#id "Direct link to id")
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
readonly id: string;
|
|
20
|
+
|
|
21
|
+
```
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Interface: DatabaseOperationContract
|
|
2
|
+
|
|
3
|
+
The browser-safe contract of one generated operation. `input` and `output` are JSON types. A generated `database.d.ts` fills this interface by name.
|
|
4
|
+
|
|
5
|
+
## Properties[](#properties "Direct link to Properties")
|
|
6
|
+
|
|
7
|
+
### input[](#input "Direct link to input")
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
readonly input: unknown;
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
***
|
|
15
|
+
|
|
16
|
+
### method[](#method "Direct link to method")
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
readonly method: DatabaseOperationMethod;
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
***
|
|
24
|
+
|
|
25
|
+
### output[](#output "Direct link to output")
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
readonly output: unknown;
|
|
29
|
+
|
|
30
|
+
```
|