Skip to content

feat(appkit): generate the database operation registry and browser contracts - #690

Merged
ditadi merged 12 commits into
mainfrom
stack/database-stable/04-operation-generation
Nov 20, 2026
Merged

ditadi merged 12 commits into
mainfrom
stack/database-stable/04-operation-generation

Conversation

@ditadi

@ditadi ditadi commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

What did you change, and why?

Why: A compiled server has no TypeScript sources to scan, and the browser needs operation types without importing server code.

Change (build time only):

  • Scans server/database/routes/*.ts and writes server/database/routes.gen.ts, a lazy-import registry that satisfies DatabaseRoutes, and shared/appkit-types/database-operations.d.ts, the exact JSON contract of each operation.
  • The Vite plugin and appkit generate-types run it. With NODE_ENV=production, an operation without authorization fails generation. An unsupported Zod schema fails with the operation and the slot it came from.
  • Operations without an input schema generate input: void, regardless of HTTP method, primary keys, or writable columns. Explicit input schemas still render their exact wire types. Operations without an output schema generate output: void, and explicit output schemas render their exact wire types.
  • CI runs a bundled server that loads its operations without sources.
  • A declared schema generates a canonical empty registry before the first operation exists. Adding the first route and removing the last route update that registry; an app with neither schema nor routes creates nothing.
  • Watches shared modules throughout server/database/, including row schemas and policies. Generated .gen.ts and .d.ts files are excluded to prevent generation loops.
  • Safe to deploy alone: generation does not register HTTP handlers.

Interface

Generation scans the *.ts files directly in server/database/routes/ (skipping *.test.ts, *.d.ts, and *.gen.ts) and writes two files that apps commit. For the playground of the last PR of this stack:

// server/database/routes.gen.ts: consumed by the database plugin
import type { DatabaseRoutes } from "@databricks/appkit/beta";

export const databaseRoutes = {
  schema: () => import("../../config/database/schema"),
  modules: [
    { file: "server/database/routes/boards.ts", load: () => import("./routes/boards") },
    { file: "server/database/routes/notes.ts", load: () => import("./routes/notes") },
  ],
} satisfies DatabaseRoutes;
// shared/appkit-types/database-operations.d.ts: the browser client reads these types
declare global {
  interface DatabricksAppKitDatabaseOperations {
    "notes.update": {
      method: "PATCH";
      input: { "id": number; "body": string };
      output: { "id": number; "board_id": number; "author": string; "body": string; "created_at": string };
    };
    "notes.delete": { method: "DELETE"; input: { "id": number }; output: void };
    "notes.count": { method: "GET"; input: void; output: number };
  }
}
  • The AppKit Vite plugin runs it when the dev server starts and when files under config/database/ or server/database/ change, including shared schemas and policies. Generated outputs do not trigger another run. appkit generate-types runs it from the CLI.
  • An operation without authorize is skipped with a warning naming its file#export. With NODE_ENV=production, it fails generation instead.
  • A Zod schema the client cannot type exactly fails generation with the operation and the slot: z.date(), tuples, z.json(), output transforms, coercion, and preprocessing. A failed run writes an empty interface.

How do you know it works?

Testing: Operation generation, generated wire-type equality, and Vite integration pass with the rest of the type generator (626 tests at this layer). A schema that throws on import fails generation and neutralizes the contracts. Coverage includes shared schema/policy add/change/unlink events, ignored generated files, schema-only bootstrapping, final route deletion, strict mode, and explicit/omitted input contracts. The source-less production bundle check loads all three operations under plain Node after TypeScript sources are removed. Repository build, docs, lint/format, and recursive typechecks pass.

Stack

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

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

Review feedback: refactor(appkit): generate void outputs for operations without an output schema drops the entity check and the default output type, and keeps loading the schema so a broken import still neutralizes the contracts.

Review feedback (round 2): fix(appkit): exit after generating types and skip stray route files.

  • generate-types reports any failure itself and exits after its output is flushed, so a route module that keeps a timer open cannot hang the CLI or its worker.
  • Discovery skips dotfiles and dangling symlinks, and a discovery failure neutralizes the contracts.
  • The registry is removed once both the schema and the routes are gone.

A handle opened at import can still keep vite build alive; the guide in #692 says route modules must not open one.

Restack: fix(appkit): render the type lists zod 4.6 writes for nullable values follows main's zod 4.6.7 upgrade.


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

dist raw gzip
JS (runtime) 1.4 MB (+28 KB) 499 KB (+10 KB)
Type declarations 483 KB (+2.5 KB) 174 KB (+1.1 KB)
Source maps 2.7 MB (+53 KB) 928 KB (+18 KB)
Other 11 KB 3.7 KB
Total 4.6 MB (+84 KB) 1.6 MB (+29 KB)
Per-entry composition (own code — deps external (as shipped))
Entry Initial (gz) Lazy (gz) Total (gz) node_modules (min) Own code (min)
. 118 KB (+4.2 KB) 2.4 KB 121 KB (+4.2 KB) external 378 KB (+12 KB)
./beta 115 KB (+346 B) 484 B 115 KB (+346 B) external 341 KB (+936 B)
./testing 47 KB (+266 B) 38 KB (+4.0 KB) 85 KB (+4.2 KB) external 246 KB (+12 KB)
./tsdown 520 B 0 B 520 B external 813 B
./type-generator 31 KB (+3.9 KB) 0 B 31 KB (+3.9 KB) external 90 KB (+11 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 647 B
./beta index.js initial 20 B
./beta supervisor-api.js lazy 191 B
./beta databricks.js lazy 178 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 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): 406 KB (+43 B) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist raw gzip
JS (runtime) 438 KB (+25 B) 150 KB (+13 B)
Type declarations 271 KB (+20 B) 100 KB (+11 B)
Source maps 865 KB (+64 B) 291 KB (+21 B)
CSS 16 KB 3.2 KB
Total 1.6 MB (+109 B) 545 KB (+45 B)
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 (+15 B) 0 B 2.1 KB (+15 B) 0 B 5.0 KB (+22 B)
./react 441 KB 49 KB 489 KB 1.4 MB 179 KB
./react/beta 14 KB (+16 B) 0 B 14 KB (+16 B) 25 KB 15 KB (+22 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 44753715212 -R databricks/appkit -n appkit-template-0.98.0-pr.32b1dee-stack-database-stable-04-operation-generation-690 -D appkit-pr-690 \
  && unzip -o "appkit-pr-690/appkit-template-0.98.0-pr.32b1dee-stack-database-stable-04-operation-generation-690.zip" -d "appkit-pr-690" \
  && databricks apps init --template "appkit-pr-690"

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/04-operation-generation branch from faf1728 to c679be4 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 calvarjorge October 28, 2026 11:05
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from c679be4 to c6b8418 Compare November 3, 2026 13:01
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from c6b8418 to ad8c8e0 Compare November 3, 2026 13:47
@ditadi
ditadi requested review from MarioCadenas and removed request for calvarjorge November 3, 2026 13:55
@ditadi
ditadi removed this pull request from stack #693 November 3, 2026 15:18
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from ad8c8e0 to 1ea5e57 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/04-operation-generation branch 2 times, most recently from 151e6e8 to da12ac4 Compare November 4, 2026 20:06
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from da12ac4 to 435a876 Compare November 6, 2026 10:49
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from 435a876 to 12a3a3d Compare November 16, 2026 12:03
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch 2 times, most recently from b8df200 to 3a1b9f5 Compare November 16, 2026 21:46

@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.

Found 2 P2 bugs, reported inline. Each was independently upheld by all three verifiers.

Reviewed commit 3a1b9f581de4c36e09c624aebf8d2410f49c8935 against the merge base with stack/database-stable/03-operation-authorization, including the PR description, all changed files, and the relevant generator, validator, and CLI callers.

Verification:

  • Executed the actual operation renderer with Zod 4.6.7 and compiled its output with TypeScript 5.9.3: nested readonly arrays fail type equality (TS2344); readonly on both levels emits invalid syntax (TS1354).
  • Executed the extracted CLI orchestration with an injected schema-generation failure: exit status 1, zero operation-generator calls, and existing operation contracts preserved. This was a control-flow check with generator doubles, not a full CLI integration run.
  • Security review found no substantiated security issues.
  • Full repository checks could not run: pnpm install --frozen-lockfile failed to download dependencies from registry.npmjs.org (ECONNREFUSED). A subsequent pnpm run check also attempted installation and could not reach linting. Knip, build, typecheck, changed tests, and the source-less bundle check therefore remain unverified. There is no visual UI change requiring screenshots.

@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from 3a1b9f5 to 9f3c462 Compare November 17, 2026 10:05
@ditadi
ditadi requested a review from MarioCadenas November 17, 2026 11:53
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from 9f3c462 to a31c2c8 Compare November 17, 2026 13:25

@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.

One issue inline: the template's production build can drop an operation without saying so. Reviewed at a31c2c8.

@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from a31c2c8 to a30a485 Compare November 20, 2026 10:04
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from a30a485 to 3d90ff2 Compare November 20, 2026 14:03
Base automatically changed from stack/database-stable/03-operation-authorization to main November 20, 2026 14:20
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch 2 times, most recently from 699d057 to bee37e6 Compare November 20, 2026 14:27
ditadi and others added 12 commits November 20, 2026 14:27
…ntracts

Scan server/database/routes/*.ts and write a lazy routes.gen.ts

registry and the exact JSON contract of each operation. The Vite

plugin and appkit generate-types run it, strictly in production.

An app without that directory generates nothing new.

CI checks the built declarations and a server bundle that loads

its operations without sources.

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

The contract generator renders an omitted output slot as void, the way it
already renders an omitted input, instead of deriving a row type from the
operation's table. Operation generation still loads the schema, so a schema
that cannot be imported fails it and neutralizes the contracts on its own.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Main moved to zod 4.6, whose JSON Schema writes a nullable scalar as
`type: ["string", "null"]` rather than `anyOf`.

[#tern:skip]

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
generate-types reports any failure itself and exits once its work, lock
release, and output are done, so a route module that keeps a timer open
cannot hang the CLI or its worker. Route discovery skips dotfiles and
dangling symlinks and fails through the path that neutralizes the
contracts. The registry is removed once both the schema and the routes
are gone, since it imports the schema.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
`readonly` binds looser than `[]`, so a readonly array inside an array
printed as `readonly string[][]` (modifier on the wrong dimension) or
`readonly readonly string[][]` (TS1354). Group it like a union element.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
A schema failure threw before the operations pass, so the previous
database-operations.d.ts kept advertising operations a failed run should
neutralize. Run both passes and report the first failure, as the Vite
plugin does.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The template's prebuild ran generate-types without NODE_ENV, so typegen ran
non-strict. A build then skipped an operation without authorization with only a
warning, and the deployed app did not serve it. Run the prebuild's typegen with
NODE_ENV=production so that operation fails the build.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
The test skipped unless `dist` existed, so a CI step after the build ran
its whole file just for it. The playground's database typecheck and the
bundle check already exercise the built output.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: ditadi <victordperd@gmail.com>
@ditadi
ditadi force-pushed the stack/database-stable/04-operation-generation branch from bee37e6 to ae612fd Compare November 20, 2026 14:27
@ditadi
ditadi merged commit 691501d into main Nov 20, 2026
12 of 14 checks passed
@ditadi
ditadi deleted the stack/database-stable/04-operation-generation branch November 20, 2026 15:17
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