Skip to content

feat(appkit): define named database operations and policies - #688

Merged
ditadi merged 4 commits into
mainfrom
stack/database-stable/02-operation-definitions
Nov 16, 2026
Merged

ditadi merged 4 commits into
mainfrom
stack/database-stable/02-operation-definitions

Conversation

@ditadi

@ditadi ditadi commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

What did you change, and why?

Named operations let an app declare who may call each database action. Inputs are explicit contracts: omitting input means no parameters, so a list or count does not need z.object({}) just to disable an inferred { id } input. Outputs are explicit too: omitting output means no body.

  • Adds defineOperation({ name, method, authorize, execute, input?, output? }) and definePolicy to @databricks/appkit/beta.
  • An explicit input schema determines the parsed callback input and the caller's wire input. Without a schema, callbacks receive undefined and OperationWireInput is void, for every method.
  • A callback cannot read input.id, or use a policy requiring parameters, until its operation declares an input schema. Explicit schemas can refine or transform values.
  • Without an output schema an operation answers no body. execute must resolve to nothing, or to null on GET, PATCH, or PUT, and OperationWireOutput is void. Returning a row, a boolean, or null on POST without an output is a type error. A Zod output declares the response and is its public projection.
  • Adds the metadata validator shared by generation and setup: names, reserved names, duplicates, and malformed contracts. An operation without authorization is skipped with a warning naming its file and export.
  • Makes workspace-client type exports explicit so built declarations type-check without skipLibCheck.

Nothing loads or serves an operation in this layer.

Interface

const signedIn = definePolicy({ allow: () => true });

export const countNotes = defineOperation({
  name: "notes.count",
  method: "GET",
  output: z.number(),
  authorize: signedIn,
  execute: ({ db }) => db.notes.count(),
});

export const getNote = defineOperation({
  name: "notes.get",
  method: "GET",
  input: z.object({ id: z.number().int() }),
  output: z.object({ id: z.number(), body: z.string() }),
  authorize: signedIn,
  execute: ({ db, input }) => db.notes.find(input.id),
});

type CountInput = OperationWireInput<typeof countNotes>; // void
// GetNote input: { id: number }; output: { id: number; body: string }, or 404 for null.

definePolicy supports actor/input decisions or a resource lookup followed by an allow decision. The lookup receives the same context as every callback, actor included. Only literal true admits. A resource lookup that returns null or undefined ends the request before allow or execute runs. Definition freezes a descriptor and performs no I/O.

Validation

The definition/metadata tests and type probes pass (17 tests). Probes check explicit inputs, omitted inputs across all methods, incompatible resource policies, omitted outputs (a row, a boolean, or null on POST without output fails), and built public declarations without skipLibCheck. The package build and documentation build pass.

Stack

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

Design: #683. Previous layer: #687. Next layer: #689.

Review feedback: refactor(appkit): drop entities and default outputs from operation definitions removes entity and the default output types, and documents the actor in policy lookups.

Restacked onto main 1a82e2a: test(appkit): expect the design plugin in operation contexts adds main's new beta plugin to the operation context probe.


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 (+444 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 1.3 MB (-7.5 KB) 484 KB (-1.8 KB)
Type declarations 481 KB (+8.6 KB) 173 KB (+2.8 KB)
Source maps 2.6 MB (-2.9 KB) 902 KB (+265 B)
Other 11 KB 3.7 KB
Total 4.5 MB (-1.9 KB) 1.5 MB (+1.2 KB)
Per-entry composition (own code — deps external (as shipped))
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
. 111 KB 2.5 KB (-1 B) 114 KB (-1 B) external 359 KB
./beta 113 KB (-783 B) 484 B 113 KB (-783 B) external 336 KB (-3.1 KB)
./testing 46 KB 34 KB (+4 B) 80 KB (+4 B) external 233 KB
./tsdown 520 B 0 B 520 B external 813 B
./type-generator 27 KB (+1 B) 0 B 27 KB (+1 B) external 78 KB

Chunks:

Entry Chunk Load Size (gz)
. index.js initial 107 KB
. utils.js initial 4.6 KB
. remote-tunnel-manager.js lazy 2.5 KB
./beta beta.js initial 92 KB
./beta modular.js initial 6.0 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 647 B
./beta index.js initial 20 B
./beta supervisor-api.js lazy 192 B
./beta databricks.js lazy 177 B
./beta index.js lazy 115 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 30 KB
./testing remote-tunnel-manager.js lazy 2.5 KB
./testing utils.js lazy 1.8 KB
./tsdown index.js initial 520 B
./type-generator index.js initial 27 KB

@databricks/appkit-ui

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

dist raw gzip
JS (runtime) 438 KB (-1.9 KB) 150 KB (-774 B)
Type declarations 271 KB (-920 B) 100 KB (-222 B)
Source maps 865 KB (-4.5 KB) 291 KB (-1.4 KB)
CSS 16 KB 3.2 KB
Total 1.6 MB (-7.3 KB) 544 KB (-2.4 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 2.1 KB 0 B 2.1 KB 0 B 5.0 KB
./react 441 KB 49 KB 489 KB 1.4 MB 179 KB
./react/beta 14 KB (-195 B) 0 B 14 KB (-195 B) 25 KB 15 KB (-556 B)

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 2.1 KB
./react index.js initial 439 KB
./react tslib initial 2.1 KB
./react apache-arrow lazy 49 KB
./react/beta beta.js initial 14 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 43896285660 -R databricks/appkit -n appkit-template-0.96.0-pr.09aa53e-stack-database-stable-02-operation-definitions-688 -D appkit-pr-688 \
  && unzip -o "appkit-pr-688/appkit-template-0.96.0-pr.09aa53e-stack-database-stable-02-operation-definitions-688.zip" -d "appkit-pr-688" \
  && databricks apps init --template "appkit-pr-688"

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/02-operation-definitions branch from 3bad942 to 6c6896b 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 review from MarioCadenas and atilafassina and removed request for atilafassina October 28, 2026 11:05
@ditadi
ditadi removed this pull request from stack #693 November 3, 2026 15:18
@ditadi
ditadi force-pushed the stack/database-stable/02-operation-definitions branch from 0a8f15f to cee639c 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/02-operation-definitions branch from cee639c to 2f3d66c Compare November 4, 2026 19:15
@ditadi
ditadi force-pushed the stack/database-stable/02-operation-definitions branch 2 times, most recently from 2f5c59f to ca978b6 Compare November 6, 2026 10:49
@ditadi
ditadi force-pushed the stack/database-stable/02-operation-definitions branch from ca978b6 to 58d4193 Compare November 16, 2026 12:03
Base automatically changed from stack/database-stable/01-remove-hooks to main November 16, 2026 15:25
ditadi and others added 4 commits November 16, 2026 15:26
Add defineOperation and definePolicy to @databricks/appkit/beta. A

required, unique name identifies each operation, and the entity and

method infer its default input and output. The declaration validator

rejects malformed and duplicate operations and skips those without

authorization. Nothing registers or serves an operation yet.

Signed-off-by: ditadi <victordperd@gmail.com>
Signed-off-by: ditadi <victordperd@gmail.com>
…finitions

defineOperation no longer takes an entity, and an operation without an
output schema types its execute result as void, or null on GET, PATCH, and
PUT for a missing record, instead of inferring a row from a table. The
metadata validator stops checking entities, and the definePolicy and
PolicyContext comments say the resource lookup receives the actor like
every other callback.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Main added the beta design plugin, so it is one of the optional SDK
plugins an operation's appkit context can name.

[#tern:skip]

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
@ditadi
ditadi force-pushed the stack/database-stable/02-operation-definitions branch from 58d4193 to ac5445d Compare November 16, 2026 15:26
@ditadi
ditadi merged commit cc2f276 into main Nov 16, 2026
12 checks passed
@ditadi
ditadi deleted the stack/database-stable/02-operation-definitions branch November 16, 2026 21:46
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.

2 participants