Skip to content

feat(appkit-ui): call named database operations from the client and hooks - #691

Merged
ditadi merged 11 commits into
mainfrom
stack/database-stable/05-client-operations
Nov 20, 2026
Merged

ditadi merged 11 commits into
mainfrom
stack/database-stable/05-client-operations

Conversation

@ditadi

@ditadi ditadi commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

What did you change, and why?

Why: Browser code needs to call operations by name with generated types, and its state must not outlive a session.

Change (additive):

  • Adds databaseApi.execute, useDatabaseQuery for GET operations, and useDatabaseMutation for writes. Parameterless operations support execute(name), useDatabaseQuery(name), and mutate(). Parameterized operations still require their schema-derived input.
  • No-argument calls send no JSON input query parameter or request body. Pass undefined in the input position when supplying options; option positions stay consistent.
  • A name the server did not publish fails with NOT_EXPOSED without a request. A changed caller or a 401 clears hook state, and a late answer fails with SESSION_CHANGED. A write without a usable answer reports OUTCOME_UNKNOWN. A mutation never retries and restarts the mounted queries.
  • skipToken, exported from the React beta entry, holds a dependent query idle until valid input exists. It sends nothing, aborts an old read, clears its displayed state, and makes refetch() a no-op. The token is accepted only by query hooks, never by imperative calls or mutations.
  • Mutation state is scoped to the current operation identity and session. Changing A → B → A clears stale data/errors; earlier writes still finish and refresh reads without populating the newly selected operation.
  • entity-client.ts is the previous client.ts, moved verbatim, and the entity hooks import it from there. databaseApi keeps its entity calls until the next PR.
  • Safe to deploy alone: no server publishes operations yet, and the entity client and hooks are unchanged.
  • bundle-size-baseline.json accepts the appkit-ui growth, about 21 KB packed (5.3%), because the entity client stays until the next PR removes it. Only the appkit-ui entry changes.

Interface

New in @databricks/appkit-ui/js/beta and @databricks/appkit-ui/react/beta. Names, inputs, and outputs come from the generated DatabricksAppKitDatabaseOperations.

// Simplified argument aliases; void input permits omitting the argument.
type InputArgs<I> = [I] extends [void] ? [input?: I] : [input: I];
type Args<I, O> = [I] extends [void]
  ? [input?: I, options?: O]
  : [input: I, options?: O];

databaseApi.execute<N extends DatabaseOperationName>(
  name: N,
  ...args: Args<DatabaseOperationInput<N>, { signal?: AbortSignal }>
): Promise<DatabaseOperationOutput<N>>;

// GET operations only.
function useDatabaseQuery<N extends DatabaseQueryName>(
  name: N,
  ...args: Args<DatabaseOperationInput<N> | typeof skipToken, { enabled?: boolean }>
): {
  data: DatabaseOperationOutput<N> | undefined;
  isLoading: boolean;
  error: DatabaseApiError | null;
  refetch: () => void;
};

// POST, PATCH, PUT, and DELETE operations. Mounting sends nothing.
function useDatabaseMutation<N extends DatabaseMutationName>(name: N): {
  // Never rejects and never retries.
  mutate: (...args: InputArgs<DatabaseOperationInput<N>>) => Promise<
    | { data: DatabaseOperationOutput<N>; error: null }
    | { data: undefined; error: DatabaseApiError }
  >;
  data: DatabaseOperationOutput<N> | undefined;
  isLoading: boolean;
  error: DatabaseApiError | null;
  reset: () => void;
};

type DatabaseApiErrorCode =
  | DatabaseErrorCategory
  | "NOT_EXPOSED" // the server did not publish the name; nothing was sent
  | "UNAUTHENTICATED"
  | "SESSION_CHANGED" // the answer belongs to an earlier actor
  | "OUTCOME_UNKNOWN"; // a write may have committed without a usable answer

Example, as the playground uses it in the last PR of this stack:

const boards = useDatabaseQuery("boards.list");
const notes = useDatabaseQuery(
  "notes.list",
  boardId === undefined ? skipToken : { board_id: boardId },
);
const createNote = useDatabaseMutation("notes.create");

async function add(body: string) {
  const outcome = await createNote.mutate({ board_id: boardId, body });
  if (outcome.error === null) setDraft(""); // mounted queries reload after a success
}

useDatabaseMutation("notes.list"); // type error: a GET operation is not a mutation

How do you know it works?

Testing: The named-operation client, HTTP, query/mutation hook, and compiler-probe suites pass (104 tests at the final stack tip), and appkit-ui typecheck passes. Coverage includes parameterless calls, required schema-derived inputs, dependent queries, cancellation and late responses, operation-name switches including A → B → A, session changes, and unknown write outcomes. Type probes reject skipToken in imperative calls and mutations. The entity APIs remain intact at this layer until the cutover PR.

Stack

#683 → #687 → #688 → #689 → #690 → #691 → #692

Design: #683. Previous layer: #690. Next layer: #692.

Restacked onto the updated design without changing this layer's implementation patch.

Review feedback (round 2): fix(appkit-ui): recheck the session on failed replies and treat proxy write failures as unknown.

  • An error body, or an unusable success body, that finishes arriving after the session changed rejects with SESSION_CHANGED. It is never settled into the new session.
  • A write answered with a 5xx that lacks the actor header reports OUTCOME_UNKNOWN, not a retryable error. That reply came from a proxy, not the handler.

Stack created with GitHub Stacks CLI • Give Feedback 💬

@ditadi
ditadi added this pull request to stack #693 October 23, 2026 15:01
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 1.3 MB (+53 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 1.4 MB (+214 B) 499 KB (+20 B)
Type declarations 483 KB 174 KB (-2 B)
Source maps 2.7 MB (+33 B) 928 KB (+24 B)
Other 11 KB 3.7 KB
Total 4.6 MB (+247 B) 1.6 MB (+42 B)
Per-entry composition (own code — deps external (as shipped))
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
. 118 KB (-1 B) 2.4 KB (+1 B) 121 KB external 378 KB
./beta 115 KB 484 B 115 KB external 341 KB
./testing 47 KB (-1 B) 38 KB (-1 B) 85 KB (-2 B) external 246 KB
./tsdown 520 B 0 B 520 B external 813 B
./type-generator 31 KB 0 B 31 KB external 90 KB

Chunks:

Entry Chunk Load Size (gz)
. index.js initial 114 KB
. utils.js initial 4.6 KB
. remote-tunnel-manager.js lazy 2.4 KB
./beta beta.js initial 95 KB
./beta modular.js initial 6.1 KB
./beta stream-manager.js initial 5.9 KB
./beta service-context.js initial 4.3 KB
./beta databricks.js initial 3.3 KB
./beta client.js initial 646 B
./beta index.js initial 20 B
./beta supervisor-api.js lazy 192 B
./beta databricks.js lazy 178 B
./beta index.js lazy 114 B
./testing manifest.js initial 33 KB
./testing index.js initial 10 KB
./testing wide-event-emitter.js initial 2.9 KB
./testing index.js lazy 34 KB
./testing remote-tunnel-manager.js lazy 2.4 KB
./testing utils.js lazy 1.8 KB
./tsdown index.js initial 520 B
./type-generator index.js initial 31 KB

@databricks/appkit-ui

npm tarball (packed): 428 KB (+2 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 457 KB 157 KB
Type declarations 281 KB 104 KB
Source maps 906 KB 306 KB
CSS 16 KB 3.2 KB
Total 1.6 MB 571 KB
Per-entry composition (consumer bundle — deps bundled, peerDeps external)
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
./js 5.3 KB 49 KB 55 KB 208 KB 14 KB
./js/beta 3.5 KB 0 B 3.5 KB 0 B 9.4 KB
./react 441 KB 49 KB 489 KB 1.4 MB 179 KB
./react/beta 16 KB 0 B 16 KB 25 KB 22 KB

Chunks:

Entry Chunk Load Size (gz)
./js index.js initial 5.2 KB
./js chunk initial 120 B
./js apache-arrow lazy 49 KB
./js/beta beta.js initial 3.5 KB
./react index.js initial 439 KB
./react tslib initial 2.1 KB
./react apache-arrow lazy 49 KB
./react/beta beta.js initial 16 KB

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 44775546445 -R databricks/appkit -n appkit-template-0.101.0-pr.d624068-stack-database-stable-05-client-operations-691 -D appkit-pr-691 \
  && unzip -o "appkit-pr-691/appkit-template-0.101.0-pr.d624068-stack-database-stable-05-client-operations-691.zip" -d "appkit-pr-691" \
  && databricks apps init --template "appkit-pr-691"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.

@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from ac81ca5 to 7ff200e Compare October 26, 2026 10:41
@ditadi
ditadi marked this pull request as ready for review October 28, 2026 11:05
@ditadi
ditadi requested a review from a team as a code owner October 28, 2026 11:05
@ditadi
ditadi requested a review from MarioCadenas October 28, 2026 11:05
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from 7ff200e to e654d2b Compare November 3, 2026 13:01
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from e654d2b to e1dec02 Compare November 3, 2026 13:47
@ditadi
ditadi removed this pull request from stack #693 November 3, 2026 15:18
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from e1dec02 to c442046 Compare November 3, 2026 15:18
@ditadi
ditadi added this pull request to stack #704 November 3, 2026 15:19
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from c442046 to f56ee2f Compare November 4, 2026 19:15
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from f56ee2f to 6474069 Compare November 4, 2026 20:06
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from 6474069 to 974befb Compare November 6, 2026 10:49
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from 974befb to cec215f Compare November 16, 2026 12:03
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from cec215f to 8c6e079 Compare November 16, 2026 15:26
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from 8c75b12 to 1a24e9b Compare November 17, 2026 10:05

@MarioCadenas MarioCadenas left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read through the client, session and hook changes and ran it locally. I found 2 things worth fixing, both in the session handling.

What I ran on 8c75b12 (secrets unset): pnpm install --frozen-lockfile, pnpm run check, pnpm run knip, pnpm build, pnpm run typecheck, pnpm vitest run --changed <merge-base>. All pass, 10 test files and 219 tests. I also wrote a small Node script that runs the compiled useDatabaseMutation, send and session code with fetch stubbed out, to reproduce the two cases below.

  1. The mutation can show user A's write result after the session has moved to user B (use-database-mutation.ts:119, inline). send() checks the ticket's epoch after JSON.parse, but settle stamps the state with whatever epoch is current when the await resumes, not the epoch the reply was accepted in. If B's reply opens a new epoch in that gap, A's data gets stamped with B's epoch and the hook shows it. In my script the hook ended on epoch 1 with data: { owner: 'a', secret: 'A secret' }. The window is small (a microtask), but the PR says a changed caller clears hook state, and here it doesn't. useDatabaseQuery doesn't have this problem because it stamps with the epoch from the render. Stamping a success with started would close it: if the epoch moved, the hook already hides it.

  2. A 401 that was in flight before sign-in still reaches the new session (session.ts:51, inline). After A gets a 401, actor is null. When B signs in, null to B doesn't open an epoch (opensEpoch = actor !== null). So a read sent while signed out, whose 401 body is still streaming, passes isCurrentDatabaseRequest after B's reply and comes back as UNAUTHENTICATED instead of SESSION_CHANGED. In my script that's exactly what happened. Since no epoch opens, the query showing that error doesn't restart either, so the screen says "sign in" while B is signed in until something refetches. Low impact, but it's the same promise the PR makes.

Nothing to flag on security: no new dependencies, no CI changes, and nothing user-controlled ends up in URLs beyond the published operation names.

@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch 2 times, most recently from 1f9f4a2 to ef7daae Compare November 20, 2026 10:04
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from ef7daae to 9f5069b Compare November 20, 2026 14:03
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch 2 times, most recently from c639c1e to cfe276f Compare November 20, 2026 14:27
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from cfe276f to 6a7c25d Compare November 20, 2026 14:27
Base automatically changed from stack/database-stable/04-operation-generation to main November 20, 2026 15:17
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from 6a7c25d to fd3a0c8 Compare November 20, 2026 15:17
ditadi and others added 11 commits November 20, 2026 16:34
…ooks

Add databaseApi.execute, useDatabaseQuery, and useDatabaseMutation.

A name the server did not publish fails with NOT_EXPOSED and sends

nothing. Answers carry the actor discriminator, so a changed session

clears every query, and a mutation restarts mounted queries.

The entity client and hooks stay until the plugin serves operations.

Signed-off-by: ditadi <victordperd@gmail.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Signed-off-by: ditadi <victordperd@gmail.com>
… write failures as unknown

An error or unusable body that finished arriving after the session moved
now rejects with SESSION_CHANGED instead of settling the old session's error.
A write answered 5xx without the actor header is OUTCOME_UNKNOWN, not TRANSIENT.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
…pted it

A write's reply can be accepted for actor A and then, before the hook
resumes, a later reply naming actor B opens a new session. The hook
stamped the outcome with the session current at that moment, so it
showed A's answer or error to B. Sweep B's reply across the microtasks
around the write's reply and require the hook to end idle every time.
Also pin that a write whose own reply opens the session shows its
answer there.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
… was accepted in

The hook read the session epoch after its await resumed, so a later
reply that opened another actor's session in that gap made the old
actor's answer or error show in the new session. The operation call
now exposes the epoch its latest send belongs to, which only the
request's own reply can move, and the hook stamps every outcome with
it. A write whose own reply opens the session still shows there.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
After a 401 the session recorded no actor, as before any reply, so the
next actor's first reply opened no epoch. A read sent while signed out
whose 401 body was still arriving then rejected UNAUTHENTICATED in the
new session, and queries showing that error never asked again. Pin that
the sign-in opens a session, refuses that body, and restarts those
queries, and that the page's first reply still opens none.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The session used null both before any reply and after a 401, so the
first actor to sign in after a 401 opened no epoch. A 401 body from the
signed-out session could then reach the new one, and queries showing
UNAUTHENTICATED kept showing it. Keep "no reply yet" apart from "a 401
was seen", so any change of who is signed in opens an epoch once some
reply was observed, while the page's first reply still opens none.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Mark "no reply observed yet" with an unexported UNOBSERVED sentinel
and test for the first reply by name, so the actor's three states
read from the code. Rename DatabaseOperationCall's epoch getter to
latestRequestEpoch and drop the comments that explained the old
names.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Rename the race helper's delay to microtasksBeforeActorB and the
filtered outcomes to acceptedBeforeSessionChange, and drop the
comments those names replace.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
… baseline

The operation client and hooks ship next to the entity client until the
next PR removes it, so the packed tarball grows by about 21 KB (5.3%).
Only the appkit-ui entry is regenerated.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
@ditadi
ditadi force-pushed the stack/database-stable/05-client-operations branch from fd3a0c8 to 81bd7c8 Compare November 20, 2026 16:39
@ditadi
ditadi merged commit 9819f8d into main Nov 20, 2026
14 checks passed
@ditadi
ditadi deleted the stack/database-stable/05-client-operations branch November 20, 2026 16:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants