Skip to content

feat: query hosted data apps by registered ID - #150

Draft
robinvrd wants to merge 7 commits into
mainfrom
robin/operation-registry-client
Draft

robinvrd wants to merge 7 commits into
mainfrom
robin/operation-registry-client

Conversation

@robinvrd

@robinvrd robinvrd commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

What changed

Hosted apps use operations.createDataClient(). Local directory apps keep the operations import type-only and create an HTTP client with shared, browser-safe filter declarations. Both call client.query() with the same operation name and input. In a hosted iframe, client.query() runs the operation's run() function, and each named SQL query crosses the bridge as data:query with a registered query ID and parameter values. Locally, Bun executes the operation through /api/data/:operation. The single-file Bun preview resolves data:query IDs against the extracted defineDataApp manifest. The data:sql route, SQL handler, explicit execution option, and default data:operation iframe route are removed.

API for discussion

const dataApp = defineDataApp({
  title: 'Sales',
  description: 'Sales by region',
  scope: { organization: 'demo', environment: 'production' },
  queries: {
    salesSql: {
      statement: 'SELECT region, total FROM sales WHERE region = $region',
      params: { region: { type: 'string' } },
      projections: {
        region: { type: 'string' },
        total: { type: 'number' },
      },
    },
  },
});

const region = searchFilter({ key: 'region', label: 'Region' });

const operations = dataApp.defineOperations({
  salesByRegion: dataApp.defineOperation({
    filters: { region },
    policy: { maxQueryRows: 100, maxDurationMs: 15000 },
    async run({ query }, { region }) {
      return (await query('salesSql', { region })).rows;
    },
  }),
});

const client = operations.createDataClient();
const result = await client.query('salesByRegion', { region: 'EU' });

For the hosted path, the last call runs salesByRegion in the iframe. Its inner query sends data:query with { queryId: 'salesSql', params: { region: 'EU' }, limit: 100 }. The host passes salesSql to the existing runDataAppQuery mutation; the backend already stores this ID and SQL from defineDataApp({ queries }). The operation name stays inside the app. run() receives the SQL rows and returns the operation result.

For a local directory app, the server imports the same operations registry. Browser code imports only its type and the shared filter declarations:

import type { operations } from './operations';
import { operationFilters } from './filters';

type Operations = Omit<typeof operations, 'createDataClient'>;
const client = createDataClient<Operations>({ filters: operationFilters });
const result = await client.query('salesByRegion', { region: 'EU' });

Companion drafts: product frontend router and MCP render-tool query metadata. Both are needed before deploying this SDK. The existing runDataAppQuery mutation needs no change.

Verification

bun run check with Bun 1.4.4 covers static checks, 1,201 tests, package archives, and starter builds. All of those checks passed locally (the starter gate was rerun after removing an overbroad assertion). GitHub static, package, and three test shards passed. Test shard 4 fails in apps-dates.test.ts:61 on a heading color assertion; the latest main run fails on the identical assertion with the same colors. The dependent final CI gate consequently remains red.

@albert20260301 albert20260301 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The registry needs one consistent snapshot for both execution modes. On 98c6202, defineOperations() freezes a copy for the returned registry, but its browser client closes over the caller's original operations object. I reproduced this through public exports:

  1. Create definitions = { answer: originalOperation } and registry = app.defineOperations(definitions).
  2. Replace definitions.answer with a different operation of the same input/output type.
  3. Create a browser client from registry, and a server handler from that same registry.

The browser returns the replacement result; the server returns the original result, despite Object.isFrozen(registry) === true. Derived server filters are also captured before that replacement.

Please snapshot once and use that same operation snapshot for filter derivation, browser execution and server registration; cover mutation of the input map before a client is created. Local build and the existing 12 operation tests pass, but they do not cover this divergence.

This finding does not decide the draft's shorthand-inference or hosting-build questions. Backend operation registration and browser-safe contract generation remain explicitly unimplemented, as documented.

@robinvrd robinvrd changed the title feat: prototype operation-owned clients for hosted apps feat: query hosted data apps by registered ID Nov 16, 2026
@albert20260301

Copy link
Copy Markdown

On 9db3afb, the preview's registered-ID lookup accepts inherited properties. currentQueries[query.queryId] at packages/data-app-bun/src/preview/serve.ts:322 reads from a normal object, and constructor / toString both pass route validation.

I reproduced this through the public serveAppFile() API with an injected backend: a declared ready query reaches the backend with "SELECT 1"; missing returns 404 without a backend call; constructor and toString both reach lakehouse.queryAll() with a function instead of SQL. The injected backend returned 200; a real adapter may fail differently. Please require an own registered entry (or use a null-prototype map) and cover inherited names returning 404 with zero backend calls.

The earlier registry-snapshot finding also remains reproducible under the new API: an installed public iframe transport in Chromium plus registry.createDataClient() returns "replaced", while createDataHandler(registry, ...) returns "original" after replacing the input map entry before client creation. The new delivery-mode test does not exercise that mutation.

Local static checks and 42 focused operation/message/authoring/preview tests pass. Required CI job 133269041779 fails apps-dates.test.ts:61 with the already-reported heading-color mismatch from merged #149, not a new registered-query failure. No CI rerun or approval. The frontend/backend companion drafts remain deployment prerequisites; I have not verified their integration.

@albert20260301 albert20260301 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Both reported defects are fixed at 1fd7008. The independent Chromium registry-mutation probe now returns original from both browser and server clients. Through public serveAppFile(), declared ready reaches the injected backend with SQL; missing, constructor, and toString return 404 with zero backend calls. The new row-limit bound is also covered by the regression tests.

Reviewed the full delta from the previously reviewed dc44e0a; local static checks and all 40 operation/message/preview tests pass, and required CI is green. This supersedes my earlier changes request for those defects.

This reviews the SDK change, not deployment readiness: the companion frontend #3005/backend #5056 drafts remain prerequisites, and their integration is unverified here.

@albert20260301 albert20260301 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Reviewed the additional 21-file delta through ce22907: query SQL stays literal, unsupported SDK shorthand is rejected, and the date-bound helper and finding starters use explicit parameters. Local static checks, 186 focused tests and all three starter gates pass; required CI is now green.

The earlier registry-snapshot and inherited-query-ID fixes remain intact. This approval covers the updated SDK head; companion frontend #3005/backend #5056 integration and deployment remain unverified.

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