Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(database): open drafts immediately and avoid refresh races (#7994)

Wolf Mermelstein44747a4609d6
diff --git a/apps/web/src/features/block-database/queries/table-rows.test.tsx b/apps/web/src/features/block-database/queries/table-rows.test.tsx
index c8a43f00c9..c3aeaf724d 100644
--- a/apps/web/src/features/block-database/queries/table-rows.test.tsx
+++ b/apps/web/src/features/block-database/queries/table-rows.test.tsx
@@ -1316,6 +1316,7 @@ describe("another writer's change", () => {
let name = 'Ada';
const engineRead = engine(() => guests([{ id: 'record', name }]));
const host = {
+ readQuery: async () => ({ kind: 'miss' as const }),
// The view's rerun must not wait on a cache notification.
onCacheChanged: () => () => {},
entityFilter: async () => ({ kind: 'unsupported' as const }),
@@ -1325,7 +1326,7 @@ describe("another writer's change", () => {
}),
} satisfies Pick<
CacheHost,
- 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'
+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'
>;
const since = vi.fn((_version: number) =>
okAsync({
diff --git a/apps/web/src/features/block-database/queries/table-rows.ts b/apps/web/src/features/block-database/queries/table-rows.ts
index d75ff1f22b..be8d9c339f 100644
--- a/apps/web/src/features/block-database/queries/table-rows.ts
+++ b/apps/web/src/features/block-database/queries/table-rows.ts
@@ -618,8 +618,12 @@ export function createDatabaseRowsSource(props: {
: undefined;
},
loading: () => !rowsQuery.outcome() && rowsQuery.error() === undefined,
- refreshing: rowsQuery.loading,
- error: rowsQuery.error,
+ refreshing: () =>
+ rowsQuery.loading() ||
+ (retainedRowIds().length > 0 && retainedQuery.loading()),
+ error: () =>
+ rowsQuery.error() ??
+ (retainedRowIds().length > 0 ? retainedQuery.error() : undefined),
refresh,
addOption: props.addOption,
retain: (rowIds) => setRetainedIds(() => rowIds),
diff --git a/apps/web/src/features/database/primitives/table-controller.test.ts b/apps/web/src/features/database/primitives/table-controller.test.ts
index 09e275c91c..82936a2232 100644
--- a/apps/web/src/features/database/primitives/table-controller.test.ts
+++ b/apps/web/src/features/database/primitives/table-controller.test.ts
@@ -39,7 +39,10 @@ const offline: DatabaseWriteFailure = {
error: { code: 'NETWORK_ERROR', message: 'Offline', refusal: null },
};
-function setup(onSaved?: Parameters<typeof createTableController>[1]) {
+function setup(
+ onSaved?: Parameters<typeof createTableController>[1],
+ overrides: Partial<DatabaseRowsSource> = {}
+) {
const [snapshot, setSnapshot] = createSignal<StoredTable>({
rows: [
{ rowId: 'record', cells: { status: 'To do', title: 'Plan launch' } },
@@ -59,6 +62,7 @@ function setup(onSaved?: Parameters<typeof createTableController>[1]) {
),
addOption: vi.fn<DatabaseRowsSource['addOption']>(() => okAsync(undefined)),
retain: () => {},
+ ...overrides,
};
let dispose!: () => void;
const controller = createRoot((cleanup) => {
@@ -76,6 +80,51 @@ const move: DatabaseRowMutation = {
};
describe('table controller', () => {
+ it('clears a failed-refresh warning when a background schema read succeeds', async () => {
+ const [refreshing, setRefreshing] = createSignal(false);
+ const { controller, source, setSnapshot, dispose } = setup(undefined, {
+ refreshing,
+ });
+ vi.mocked(source.refresh).mockReturnValue(
+ errAsync({ kind: 'fetch', message: 'Offline' })
+ );
+ await controller.refresh();
+ expect(controller.refreshWarning()).toBe(true);
+ setRefreshing(true);
+ setSnapshot({ version: 2, rows: [] });
+ setRefreshing(false);
+ expect(controller.refreshWarning()).toBe(false);
+ dispose();
+ });
+ it('keeps the warning when background revalidation fails', async () => {
+ const [refreshing, setRefreshing] = createSignal(false);
+ const { controller, source, dispose } = setup(undefined, {
+ refreshing,
+ error: () => ({ kind: 'fetch', message: 'Offline' }),
+ });
+ vi.mocked(source.refresh).mockReturnValue(
+ errAsync({ kind: 'fetch', message: 'Offline' })
+ );
+ await controller.refresh();
+ setRefreshing(true);
+ setRefreshing(false);
+ expect(controller.refreshWarning()).toBe(true);
+ dispose();
+ });
+ it('does not let an older failed refresh overwrite a newer success', async () => {
+ const { controller, source, dispose } = setup();
+ const old = deferred<Result<void, { kind: 'fetch'; message: string }>>();
+ vi.mocked(source.refresh)
+ .mockReturnValueOnce(new ResultAsync(old.promise))
+ .mockReturnValueOnce(okAsync(undefined));
+ const earlier = controller.refresh();
+ await controller.refresh();
+ old.resolve(err({ kind: 'fetch', message: 'Old failure' }));
+ await earlier;
+ expect(controller.refreshWarning()).toBe(false);
+ dispose();
+ });
+
it('serializes adding a group with row writes and uses the schema refresh version', async () => {
const { controller, source, setSnapshot, snapshot, dispose } = setup();
const option = deferred<Result<void, DatabaseOpsError>>();
diff --git a/apps/web/src/features/database/primitives/table-controller.ts b/apps/web/src/features/database/primitives/table-controller.ts
index 697dbde945..78e1c3487c 100644
--- a/apps/web/src/features/database/primitives/table-controller.ts
+++ b/apps/web/src/features/database/primitives/table-controller.ts
@@ -1,7 +1,14 @@
import { Telemetry } from '@macro-inc/observability';
import type { DatabaseOpsError } from '@service-storage/databases';
import { err, ok, type Result } from 'neverthrow';
-import { batch, createMemo, createSignal, onCleanup } from 'solid-js';
+import {
+ batch,
+ createEffect,
+ createMemo,
+ createSignal,
+ on,
+ onCleanup,
+} from 'solid-js';
import type {
DatabaseRowsSource,
DatabaseWriteResult,
@@ -93,6 +100,7 @@ export function createTableController(
const [refreshWarning, setRefreshWarning] = createSignal(false);
const [schemaPending, setSchemaPending] = createSignal(0);
let sequence = 0;
+ let refreshGeneration = 0;
// A new column's type settles against the newest version this writer has
// seen, read or written; row ops themselves carry no version.
let lastWrittenVersion: number | undefined;
@@ -264,11 +272,25 @@ export function createTableController(
}
async function refresh(reason: 'after-write' | 'refresh' = 'refresh') {
+ const generation = ++refreshGeneration;
const refreshed = await source.refresh(reason);
+ if (generation !== refreshGeneration) return;
setRefreshWarning(refreshed.isErr());
if (refreshed.isOk()) pruneCommitted();
}
+ // Schema/cache revalidation can finish outside this controller's refresh.
+ // A successful newer read clears an old warning; an older failure cannot restore it.
+ createEffect(
+ on(source.refreshing, (refreshing, previous) => {
+ if (previous && !refreshing && !source.error() && source.snapshot()) {
+ refreshGeneration++;
+ setRefreshWarning(false);
+ pruneCommitted();
+ }
+ })
+ );
+
/** Schema changes share the row-write queue because both advance the table version. */
async function addGroup(
columnId: string,
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsx
index 0788d2a8c7..45cb19a22a 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.test.tsx
@@ -35,6 +35,7 @@ const control = vi.hoisted(() => ({
mounts: 0,
cleanups: 0,
clicks: 0,
+ deferSaved: false,
}));
vi.mock('@core/constant/featureFlags', () => ({
enableDatabases: { key: 'enable-databases' },
@@ -46,7 +47,10 @@ vi.mock('@app/lib/analytics/posthog', () => ({
useFeatureFlag: () => () => ({ enabled: control.enabled() }),
}));
vi.mock('./LazyDecorator', () => ({
- LazyDecorator: (props: { render: () => JSX.Element }) => props.render(),
+ LazyDecorator: (props: {
+ placeholder: JSX.Element;
+ render: () => JSX.Element;
+ }) => (control.deferSaved ? props.placeholder : props.render()),
}));
vi.mock('@app/features/database-query/database-query', () => ({
DatabaseLiveQuestion: (props: { source: { displayMode: string } }) => {
@@ -79,6 +83,41 @@ vi.mock('@app/features/database-query/database-query', () => ({
}));
describe('database answer rollout', () => {
+ it('opens new drafts without waiting for the saved-answer viewport gate', async () => {
+ control.enabled = () => true;
+ control.deferSaved = true;
+ const draft = render(() => (
+ <DatabaseQuery
+ key="draft"
+ theme={{}}
+ queryId=""
+ prompt=""
+ displayMode="scalar"
+ />
+ ));
+ try {
+ await waitFor(() =>
+ expect(draft.getByText('Interactive answer')).toBeTruthy()
+ );
+ const saved = render(() => (
+ <DatabaseQuery
+ key="saved"
+ theme={{}}
+ queryId="saved"
+ prompt=""
+ displayMode="scalar"
+ title="Saved answer"
+ />
+ ));
+ expect(saved.getByText('Saved answer')).toBeTruthy();
+ expect(saved.queryByText('Interactive answer')).toBeNull();
+ saved.unmount();
+ } finally {
+ draft.unmount();
+ control.deferSaved = false;
+ }
+ });
+
it('keeps the saved title without mounting live query wiring when disabled', async () => {
const [enabled, setEnabled] = createSignal(false);
control.enabled = enabled;
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsx
index 5c6b9607dd..46d0fb8291 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/decorator/DatabaseQuery.tsx
@@ -141,23 +141,30 @@ export function DatabaseQuery(props: DatabaseQueryDecoratorProps) {
node.remove();
});
};
+ const liveAnswer = () => (
+ <Suspense fallback={placeholder()}>
+ <LiveQuestion
+ source={source}
+ onSave={canEdit() ? save : undefined}
+ onDiscard={canEdit() ? discard : undefined}
+ />
+ </Suspense>
+ );
const answer = () => (
- <LazyDecorator
- placeholder={placeholder()}
- render={() => (
- <Suspense fallback={placeholder()}>
- <LiveQuestion
- source={source}
- onSave={canEdit() ? save : undefined}
- onDiscard={canEdit() ? discard : undefined}
- />
- </Suspense>
- )}
- />
+ <Show
+ when={!props.queryId}
+ fallback={
+ <LazyDecorator placeholder={placeholder()} render={liveAnswer} />
+ }
+ >
+ {liveAnswer()}
+ </Show>
);
const placeholder = () => (
<span class="mx-0.5 rounded border border-edge-muted bg-hover px-1.5 py-0.5 text-sm text-ink">
- {props.title || props.chart?.title || 'Database answer'}
+ {props.title ||
+ props.chart?.title ||
+ (!props.queryId ? 'Opening database…' : 'Database answer')}
</span>
);
return (
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.ts
index 0b5db3921b..8c15c8f94c 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.ts
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/actions.ts
@@ -8,8 +8,10 @@ import { ListNode } from '@lexical/list';
import { HeadingNode, QuoteNode } from '@lexical/rich-text';
import { INSERT_TABLE_COMMAND, TableNode } from '@lexical/table';
import {
+ $createAwaitNode,
$createDatabaseQueryNode,
$createDocumentMentionNode,
+ $isAwaitNode,
AwaitNode,
CustomCodeNode,
DatabaseQueryNode,
@@ -39,8 +41,8 @@ import TextH1 from '@phosphor/text-h-one.svg';
import TextH3 from '@phosphor/text-h-three.svg';
import TextH2 from '@phosphor/text-h-two.svg';
import TextT from '@phosphor/text-t.svg';
-import type { LexicalEditor } from 'lexical';
-import { $insertNodes } from 'lexical';
+import type { LexicalEditor, NodeKey } from 'lexical';
+import { $getNodeByKey, $insertNodes } from 'lexical';
import { nanoid } from 'nanoid';
import { INSERT_HORIZONTAL_RULE_COMMAND } from '..';
import {
@@ -374,10 +376,30 @@ export const ACTIONS: Action[] = [
action: (editor, context) => {
if (!isFeatureEnabled(enableDatabases)) return;
queueMicrotask(async () => {
+ let placeholderKey: NodeKey | undefined;
try {
+ if (!editor.isEditable()) return;
+ // Anchor and show feedback before the creation module downloads.
+ editor.update(
+ () => {
+ const placeholder = $createAwaitNode({
+ awaitId: nanoid(),
+ text: 'Creating database…',
+ });
+ $insertNodes([placeholder]);
+ placeholderKey = placeholder.getKey();
+ },
+ { discrete: true }
+ );
const { insertNewDatabase } = await import('./insert-database');
- await insertNewDatabase(editor, context);
+ await insertNewDatabase(editor, context, placeholderKey);
} catch (error: unknown) {
+ editor.update(() => {
+ const placeholder = placeholderKey
+ ? $getNodeByKey(placeholderKey)
+ : null;
+ if ($isAwaitNode(placeholder)) placeholder.remove();
+ });
Telemetry.error('database.insert.failed', { error: String(error) });
toast.failure('The database could not be inserted. Try again.');
}
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.ts
index 4f40f8b5c5..64a7303960 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.ts
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.test.ts
@@ -1,12 +1,17 @@
import { registerRichText } from '@lexical/rich-text';
import {
+ $createAwaitNode,
$isDocumentCardNode,
+ AwaitNode,
SupportedNodeTypes,
} from '@macro-inc/lexical-core';
import {
$createParagraphNode,
$createTextNode,
+ $getNodeByKey,
$getRoot,
+ $insertNodes,
+ $nodesOfType,
createEditor,
} from 'lexical';
import { err, ok, type Result } from 'neverthrow';
@@ -84,6 +89,63 @@ describe('creating a database in a document', () => {
});
});
+ it('uses the placeholder already shown while the creation module loaded', async () => {
+ const editor = documentEditor();
+ let key!: string;
+ editor.update(
+ () => {
+ const placeholder = $createAwaitNode({
+ awaitId: 'pending',
+ text: 'Creating database…',
+ });
+ $insertNodes([placeholder]);
+ key = placeholder.getKey();
+ },
+ { discrete: true }
+ );
+ let finish!: (result: Result<string, unknown>) => void;
+ mocks.create.mockReturnValue(
+ new Promise((resolve) => {
+ finish = resolve;
+ })
+ );
+ const creating = insertNewDatabase(editor, undefined, key);
+ expect(editor.read(() => $nodesOfType(AwaitNode))).toHaveLength(1);
+ finish(ok('db-1'));
+ await creating;
+ expect(mocks.create).toHaveBeenCalledOnce();
+ expect(
+ editor.read(() => $getRoot().getChildren().filter($isDocumentCardNode))
+ ).toHaveLength(1);
+ });
+
+ it.each(['removed', 'read-only'] as const)(
+ 'does not create if the pending insert became %s while its module loaded',
+ async (state) => {
+ const editor = documentEditor();
+ let key!: string;
+ editor.update(
+ () => {
+ const placeholder = $createAwaitNode({
+ awaitId: 'pending',
+ text: 'Creating database…',
+ });
+ $insertNodes([placeholder]);
+ key = placeholder.getKey();
+ },
+ { discrete: true }
+ );
+ if (state === 'removed')
+ editor.update(() => $getNodeByKey(key)?.remove(), { discrete: true });
+ else editor.setEditable(false);
+ await insertNewDatabase(editor, undefined, key);
+ expect(mocks.create).not.toHaveBeenCalled();
+ expect(editor.read(() => $getRoot().getTextContent())).toBe(
+ 'Before. After.'
+ );
+ }
+ );
+
it('does not insert elsewhere when the placeholder was removed during creation', async () => {
let finish!: (result: Result<string, unknown>) => void;
mocks.create.mockReturnValue(
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.ts
index d694b69cf7..e0b0e99148 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.ts
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/actions/insert-database.ts
@@ -22,18 +22,31 @@ import type { ActionContext } from './types';
/** Keep the insertion anchored while creation runs, even if the caret moves. */
export async function insertNewDatabase(
editor: LexicalEditor,
- context?: ActionContext
+ context?: ActionContext,
+ placeholderKey?: NodeKey
) {
- if (!editor.isEditable()) return;
- let placeholderKey: NodeKey | undefined;
- editor.update(() => {
- const placeholder = $createAwaitNode({
- awaitId: nanoid(),
- text: 'Creating database…',
+ const pendingKey = placeholderKey;
+ if (!editor.isEditable()) {
+ if (pendingKey)
+ editor.update(() => {
+ const placeholder = $getNodeByKey(pendingKey);
+ if ($isAwaitNode(placeholder)) placeholder.remove();
+ });
+ return;
+ }
+ if (pendingKey) {
+ // The user can remove the pending insert while this module downloads.
+ if (!editor.read(() => $isAwaitNode($getNodeByKey(pendingKey)))) return;
+ } else {
+ editor.update(() => {
+ const placeholder = $createAwaitNode({
+ awaitId: nanoid(),
+ text: 'Creating database…',
+ });
+ $insertNodes([placeholder]);
+ placeholderKey = placeholder.getKey();
});
- $insertNodes([placeholder]);
- placeholderKey = placeholder.getKey();
- });
+ }
let mentionUuid: string | undefined;
let inserted = false;
diff --git a/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.ts b/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.ts
index 9b61e6885b..87bdbddfa1 100644
--- a/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.ts
+++ b/apps/web/src/lib/queries/database-sql/create-database-sql-query.test.ts
@@ -11,6 +11,7 @@ import type { CacheHost } from '@graphql-cache/host/types';
import type {
CacheRevision,
EntityFilterCacheResult,
+ ReadResult,
} from '@graphql-cache/protocol';
import type { SoupQuery } from '@service-storage/graphql/generated/graphql';
import {
@@ -187,6 +188,18 @@ describe('createDatabaseSqlQuery', () => {
{
client: () => client,
cacheHost: () => ({
+ readQuery: async () =>
+ cacheHit
+ ? {
+ kind: 'hit',
+ data: {
+ user: {
+ id: 'macro|[email protected]',
+ soup: { items: [acme], nextCursor: null },
+ },
+ },
+ }
+ : { kind: 'miss' },
onCacheChanged: () => () => {},
entityFilter: vi.fn(),
readRecordsByKeys: vi.fn(),
@@ -207,7 +220,7 @@ describe('createDatabaseSqlQuery', () => {
else expect(query.outcome()).toBeUndefined();
expect(query.error()).toBeUndefined();
expect(query.loading()).toBe(true);
- expect(policies).toEqual(['cache-only', 'network-only']);
+ expect(policies).toEqual(['network-only']);
expect(loadingStates).toEqual([true]);
finishNetwork?.();
await vi.waitFor(() =>
@@ -220,6 +233,69 @@ describe('createDatabaseSqlQuery', () => {
}
);
+ it('lands an after-write refresh while its initial cache probe is still pending', async () => {
+ let finishCache!: (result: ReadResult) => void;
+ const readQuery = vi.fn(
+ () =>
+ new Promise<ReadResult>((resolve) => {
+ finishCache = resolve;
+ })
+ );
+ const policies: string[] = [];
+ const exchange: Exchange = () => (incoming) =>
+ pipe(
+ incoming,
+ mergeMap((operation) => {
+ if (operation.kind === 'teardown') return empty;
+ policies.push(operation.context.requestPolicy);
+ return fromValue({
+ operation,
+ data: {
+ user: {
+ id: 'macro|[email protected]',
+ soup: { items: [globex], nextCursor: null },
+ },
+ },
+ stale: false,
+ hasNext: false,
+ });
+ })
+ );
+ const client = createClient({
+ url: 'http://test.invalid/graphql',
+ exchanges: [exchange],
+ });
+ const query = createRoot((cleanup) => {
+ dispose = cleanup;
+ return createDatabaseSqlQuery(
+ () => ({ schema, sql: 'SELECT name FROM crm.deals' }),
+ {
+ client: () => client,
+ cacheHost: () => ({
+ readQuery,
+ onCacheChanged: () => () => {},
+ entityFilter: vi.fn(),
+ readRecordsByKeys: vi.fn(),
+ }),
+ people: async () => [],
+ catalog: async () => catalog,
+ open: names,
+ }
+ );
+ });
+ await vi.waitFor(() => expect(readQuery).toHaveBeenCalledOnce());
+ expect((await query.refresh('after-write'))._unsafeUnwrap()).toEqual({
+ landed: true,
+ });
+ finishCache({ kind: 'miss' });
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(query.error()).toBeUndefined();
+ expect(query.outcome()?.rows).toEqual([
+ [{ type: 'text', value: 'Globex' }],
+ ]);
+ expect(policies).toEqual(['network-only']);
+ });
+
it('shows a row the cache learns about without reading the network again', async () => {
const requests: Operation[] = [];
const exchange: Exchange = () => (incoming) =>
@@ -258,6 +334,15 @@ describe('createDatabaseSqlQuery', () => {
async () => reconciled
);
const host = {
+ readQuery: async () => ({
+ kind: 'hit' as const,
+ data: {
+ user: {
+ id: 'macro|[email protected]',
+ soup: { items: [acme], nextCursor: null },
+ },
+ },
+ }),
onCacheChanged: (callback: (revision: CacheRevision) => void) => {
cacheChanged = callback;
return () => {};
@@ -272,7 +357,7 @@ describe('createDatabaseSqlQuery', () => {
}),
} satisfies Pick<
CacheHost,
- 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'
+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'
>;
const query = createRoot((cleanup) => {
@@ -294,7 +379,7 @@ describe('createDatabaseSqlQuery', () => {
);
expect(
requests.map((operation) => operation.context.requestPolicy)
- ).toEqual(['cache-only', 'network-only']);
+ ).toEqual(['network-only']);
cacheChanged(revision);
@@ -304,7 +389,7 @@ describe('createDatabaseSqlQuery', () => {
[{ type: 'text', value: 'Acme' }],
])
);
- expect(requests).toHaveLength(2);
+ expect(requests).toHaveLength(1);
expect(entityFilter).toHaveBeenCalledWith({
filters: requests[0]?.variables?.input.initial.filters,
sortMethod: 'CREATED_AT',
@@ -486,6 +571,15 @@ describe('createDatabaseSqlQuery', () => {
let cacheChanged = (_revision: CacheRevision) => {};
// The cache has not heard of the refreshed rows yet.
const host = {
+ readQuery: async () => ({
+ kind: 'hit' as const,
+ data: {
+ user: {
+ id: 'macro|[email protected]',
+ soup: { items: [acme], nextCursor: null },
+ },
+ },
+ }),
onCacheChanged: (callback: (revision: CacheRevision) => void) => {
cacheChanged = callback;
return () => {};
@@ -505,7 +599,7 @@ describe('createDatabaseSqlQuery', () => {
}),
} satisfies Pick<
CacheHost,
- 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'
+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'
>;
const query = createRoot((cleanup) => {
dispose = cleanup;
diff --git a/apps/web/src/lib/queries/database-sql/create-database-sql-query.ts b/apps/web/src/lib/queries/database-sql/create-database-sql-query.ts
index b69a7e4d87..b610fd916a 100644
--- a/apps/web/src/lib/queries/database-sql/create-database-sql-query.ts
+++ b/apps/web/src/lib/queries/database-sql/create-database-sql-query.ts
@@ -76,7 +76,10 @@ type BuildCatalog = (schema: Schema, scope?: string) => Promise<Catalog>;
export interface DatabaseSqlQueryCapabilities {
client: () => Client;
cacheHost: () =>
- | Pick<CacheHost, 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys'>
+ | Pick<
+ CacheHost,
+ 'onCacheChanged' | 'entityFilter' | 'readRecordsByKeys' | 'readQuery'
+ >
| undefined;
people: () => Promise<Person[]>;
/** The engine; the wasm module unless a test says otherwise. */
@@ -191,6 +194,7 @@ export function createDatabaseSqlQuery(
client: capabilities.client(),
catalog: built,
requestPolicy,
+ cache: host,
people: capabilities.people,
membership: host ? { host, baselines, reconcile } : undefined,
}),
diff --git a/apps/web/src/lib/queries/database-sql/graphql-source.test.ts b/apps/web/src/lib/queries/database-sql/graphql-source.test.ts
index 25218b5529..3ff45f27c1 100644
--- a/apps/web/src/lib/queries/database-sql/graphql-source.test.ts
+++ b/apps/web/src/lib/queries/database-sql/graphql-source.test.ts
@@ -1,13 +1,24 @@
import { runDatabaseSql } from '@core/database-sql/driver';
import { readTranscript, replay } from '@core/database-sql/tests/transcript';
+import { normalizedCacheExchange } from '@graphql-cache/exchange/normalized-cache-exchange';
+import type { CacheHost, CacheReadArgs } from '@graphql-cache/host/types';
+import {
+ INITIAL_CACHE_REVISION,
+ type ReadResult,
+} from '@graphql-cache/protocol';
import type {
DatabaseRowFieldsFragment,
DatabaseRowsQuery,
GroupSoupQuery,
SoupPropertyValueFieldsFragment,
} from '@service-storage/graphql/generated/graphql';
-import { createClient, type Exchange, type Operation } from '@urql/core';
-import { describe, expect, it } from 'vitest';
+import {
+ createClient,
+ type Exchange,
+ fetchExchange,
+ type Operation,
+} from '@urql/core';
+import { describe, expect, it, vi } from 'vitest';
import { empty, fromValue, mergeMap, pipe } from 'wonka';
import { createGraphqlRowSource } from './graphql-source';
@@ -370,3 +381,80 @@ describe('the GraphQL row source', () => {
]);
});
});
+
+describe('concurrent SQL cache and network reads', () => {
+ it.each([
+ ['cache-only', false],
+ ['cache-first', false],
+ ['cache-first', true],
+ ] as const)(
+ 'keeps a %s probe independent from a network refresh (hit: %s)',
+ async (requestPolicy, cacheHit) => {
+ const transcript = readTranscript('row-position');
+ let finishCache!: (value: ReadResult) => void;
+ const readQuery = vi.fn(
+ (_args: CacheReadArgs) =>
+ new Promise<ReadResult>((resolve) => {
+ finishCache = resolve;
+ })
+ );
+ const host = {
+ readQuery,
+ writeQuery: async () => ({
+ revision: INITIAL_CACHE_REVISION,
+ revisionAdvanced: true,
+ changed: [],
+ affectedOps: [],
+ reset: false,
+ }),
+ teardown: async () => {},
+ onMutationSettled: () => () => {},
+ onOpsAffected: () => () => {},
+ onCacheGenerationChanged: () => () => {},
+ claimNextMutation: async () => undefined,
+ } as unknown as CacheHost;
+ const fetch = vi.fn(
+ async () =>
+ new Response(
+ JSON.stringify({ data: soupPage([initech, globex, acme], null) }),
+ {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ }
+ )
+ );
+ const client = createClient({
+ url: 'http://test.invalid/graphql',
+ fetch,
+ exchanges: [normalizedCacheExchange(host), fetchExchange],
+ });
+ const read = (policy: 'cache-only' | 'cache-first' | 'network-only') =>
+ runDatabaseSql(transcript.catalog, transcript.sql, {
+ source: createGraphqlRowSource({
+ client,
+ catalog: transcript.catalog,
+ requestPolicy: policy,
+ cache: host,
+ people: noPeople,
+ }),
+ open: replay(transcript),
+ });
+ const probe = read(requestPolicy);
+ await vi.waitFor(() => expect(readQuery).toHaveBeenCalledTimes(1));
+ const refresh = read('network-only');
+ // With a cache-only urql subscription this request joins the probe and
+ // never reaches fetchExchange, even after the cache miss resolves.
+ await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(1));
+ expect(readQuery.mock.calls[0][0].opKey).toBeUndefined();
+ finishCache(
+ cacheHit
+ ? { kind: 'hit', data: soupPage([initech, globex, acme], null) }
+ : { kind: 'miss' }
+ );
+ expect((await refresh)._unsafeUnwrap()).toEqual(transcript.outcome);
+ const cached = await probe;
+ if (requestPolicy === 'cache-only') expect(cached.isErr()).toBe(true);
+ else expect(cached._unsafeUnwrap()).toEqual(transcript.outcome);
+ }
+ );
+});
diff --git a/apps/web/src/lib/queries/database-sql/graphql-source.ts b/apps/web/src/lib/queries/database-sql/graphql-source.ts
index d79f82af6e..0025847141 100644
--- a/apps/web/src/lib/queries/database-sql/graphql-source.ts
+++ b/apps/web/src/lib/queries/database-sql/graphql-source.ts
@@ -44,7 +44,9 @@ import {
import {
type AnyVariables,
type Client,
+ createRequest,
type DocumentInput,
+ getOperationName,
type RequestPolicy,
stringifyDocument,
} from '@urql/core';
@@ -65,6 +67,8 @@ interface GraphqlRowSourceCapabilities {
/** The statement's catalog, for the value kinds of grouped columns. */
catalog: Catalog;
requestPolicy: RequestPolicy;
+ /** Probe the cache without subscribing to a shared urql operation. */
+ cache?: Pick<CacheHost, 'readQuery'>;
/** Everyone the viewer can see. */
people: () => Promise<Person[]>;
/**
@@ -124,29 +128,63 @@ function graphqlQuery<Data, Variables extends AnyVariables>(
variables: Variables,
requestPolicy: RequestPolicy,
name: string,
- step: DatabaseSqlStepTrace
+ step: DatabaseSqlStepTrace,
+ cache?: Pick<CacheHost, 'readQuery'>
): ResultAsync<Data, DatabaseSqlFetchFailure> {
step.request(stringifyDocument(document), variables);
- return ResultAsync.fromPromise(
- client
- .query(document, variables, {
- requestPolicy,
- fetchOptions: { headers: step.headers() },
- })
- .toPromise(),
- thrownFetchFailure
- ).andThen((result): Result<Data, DatabaseSqlFetchFailure> => {
- if (result.error) return err(fetchFailure(result.error.message));
- if (!result.data)
- return err(fetchFailure(`the ${name} query returned no data`));
- return ok(result.data);
- });
+ const network = () =>
+ ResultAsync.fromPromise(
+ client
+ .query(document, variables, {
+ requestPolicy:
+ cache && requestPolicy === 'cache-first'
+ ? 'network-only'
+ : requestPolicy,
+ fetchOptions: { headers: step.headers() },
+ })
+ .toPromise(),
+ thrownFetchFailure
+ ).andThen((result): Result<Data, DatabaseSqlFetchFailure> => {
+ if (!result)
+ return err(fetchFailure(`the ${name} query ended without data`));
+ if (result.error) return err(fetchFailure(result.error.message));
+ if (!result.data)
+ return err(fetchFailure(`the ${name} query returned no data`));
+ return ok(result.data);
+ });
+ // Cache probes must not register an urql operation: a simultaneous refresh
+ // with the same key would join that probe and never send a network request.
+ if (
+ cache &&
+ (requestPolicy === 'cache-only' || requestPolicy === 'cache-first')
+ ) {
+ return ResultAsync.fromPromise(
+ cache.readQuery({
+ query: stringifyDocument(document),
+ operationName: getOperationName(
+ createRequest(document, variables).query
+ ),
+ variables: variables || undefined,
+ }),
+ thrownFetchFailure
+ )
+ .orElse(() => okAsync({ kind: 'miss' as const }))
+ .andThen((result) =>
+ result.kind === 'hit'
+ ? okAsync(result.data as Data)
+ : requestPolicy === 'cache-only'
+ ? errAsync(fetchFailure(`the ${name} query returned no data`))
+ : network()
+ );
+ }
+ return network();
}
export function createGraphqlRowSource({
client,
catalog,
requestPolicy,
+ cache,
people,
membership,
}: GraphqlRowSourceCapabilities): RowSource {
@@ -156,7 +194,7 @@ export function createGraphqlRowSource({
.returnType<ResultAsync<Page, DatabaseSqlFetchFailure>>()
.with({ type: 'soup' }, (soup) =>
soupInput(soup, cursor, limit).asyncAndThen((input) =>
- soupPage(client, requestPolicy, input, membership, step)
+ soupPage(client, requestPolicy, input, membership, step, cache)
)
)
.with({ type: 'people' }, ({ ids }) => peoplePage(catalog, people, ids))
@@ -168,7 +206,7 @@ export function createGraphqlRowSource({
match(query)
.returnType<ResultAsync<Bin[], DatabaseSqlFetchFailure>>()
.with({ type: 'groupSoup' }, (grouped) =>
- groupBins(client, requestPolicy, catalog, grouped, step)
+ groupBins(client, requestPolicy, catalog, grouped, step, cache)
)
.with({ type: P.union('soup', 'people') }, () =>
errAsync(fetchFailure('only a grouped query has bins'))
@@ -323,7 +361,8 @@ function soupPage(
requestPolicy: RequestPolicy,
input: SoupInput,
membership: LocalMembership | undefined,
- step: DatabaseSqlStepTrace
+ step: DatabaseSqlStepTrace,
+ cache?: Pick<CacheHost, 'readQuery'>
): ResultAsync<Page, DatabaseSqlFetchFailure> {
const evidence = input.initial ? JSON.stringify(input) : undefined;
const local: ResultAsync<Page | undefined, DatabaseSqlFetchFailure> =
@@ -339,7 +378,8 @@ function soupPage(
{ input },
requestPolicy,
'database rows',
- step
+ step,
+ cache
).andThen((data) => {
const { items, nextCursor } = data.user.soup;
if (evidence && membership && isNetworkRead(requestPolicy)) {
@@ -477,7 +517,8 @@ function groupBins(
requestPolicy: RequestPolicy,
catalog: Catalog,
{ table, propf, groupBy }: Extract<GqlQuery, { type: 'groupSoup' }>,
- step: DatabaseSqlStepTrace
+ step: DatabaseSqlStepTrace,
+ cache?: Pick<CacheHost, 'readQuery'>
): ResultAsync<Bin[], DatabaseSqlFetchFailure> {
const kind = catalog.tables
.find((candidate) => candidate.id === table)
@@ -517,7 +558,8 @@ function groupBins(
},
requestPolicy,
'grouped Soup',
- step
+ step,
+ cache
)
)
.andThen((data) =>
diff --git a/apps/web/src/lib/queries/storage/databases.test.ts b/apps/web/src/lib/queries/storage/databases.test.ts
index 68262b246a..67555a7127 100644
--- a/apps/web/src/lib/queries/storage/databases.test.ts
+++ b/apps/web/src/lib/queries/storage/databases.test.ts
@@ -236,6 +236,32 @@ describe('creating a database', () => {
});
});
+ it('returns the committed id while database discovery is still refreshing', async () => {
+ mock.create.mockReturnValue(okAsync({ ...detail.database, id: 'new-db' }));
+ let finish!: () => void;
+ const invalidating = vi
+ .spyOn(queryClient, 'invalidateQueries')
+ .mockImplementationOnce(
+ () =>
+ new Promise<void>((resolve) => {
+ finish = resolve;
+ })
+ );
+ try {
+ const created = await createDatabase({
+ name: 'Untitled database',
+ source: 'slash-menu',
+ });
+ expect(created._unsafeUnwrap()).toBe('new-db');
+ expect(invalidating).toHaveBeenCalledWith({
+ queryKey: databasesKeys.list.queryKey,
+ });
+ } finally {
+ finish?.();
+ invalidating.mockRestore();
+ }
+ });
+
it('hands a refusal back to the caller', async () => {
mock.create.mockReturnValue(
errAsync([{ code: 'INVALID_SCHEMA', message: 'name is empty' }])
diff --git a/apps/web/src/lib/queries/storage/databases.ts b/apps/web/src/lib/queries/storage/databases.ts
index 2976770073..538cf6f170 100644
--- a/apps/web/src/lib/queries/storage/databases.ts
+++ b/apps/web/src/lib/queries/storage/databases.ts
@@ -331,13 +331,14 @@ export function createDatabase(params: {
}): ResultAsync<string, ResultError<DatabaseSchemaErrorCode>[]> {
return storageServiceClient.databases
.create({ name: params.name })
- .map(async ({ id }) => {
+ .map(({ id }) => {
analytics.track('create_entity', {
entityType: 'database',
entityId: id,
source: params.source,
});
- await queryClient.invalidateQueries({
+ // Creation is committed. Refresh discovery without blocking the new editor.
+ void queryClient.invalidateQueries({
queryKey: databasesKeys.list.queryKey,
});
return id;
diff --git a/docs/AGENT_GUIDE/databases.md b/docs/AGENT_GUIDE/databases.md
index 88b121046d..c9d41d69bf 100644
--- a/docs/AGENT_GUIDE/databases.md
+++ b/docs/AGENT_GUIDE/databases.md
@@ -9,6 +9,11 @@ match its name, including databases with no view history.
Creating from Home immediately shows the table selector with its **+** menu, **Database
actions**, and **AI** in the top bar; no reload is needed to use them.
+`/database` immediately shows **Creating database…** at the insertion point while
+the creation module loads. Moving the caret keeps that insertion anchored; removing
+it before the module loads cancels creation.
+A successful create opens its new editor while database discovery refreshes in
+the background; a slow discovery refresh must not delay the new database card.
Databases open at
`/app/database/<uuid>`. A database contains tables; records belong to a table and
its properties describe each record. The database name in the split header is an
@@ -19,6 +24,9 @@ split header's `viewer` badge instead.
Reopening a loaded table or view shows its cached rows while a background read
checks for changes. Wait for refreshing to finish before asserting server
reconciliation; visible rows alone do not mean the network read has completed.
+Concurrent cache-only misses must not fail an outstanding network row read. A
+successful background read clears an earlier refresh warning; a genuine failed
+read keeps the warning and its Refresh action.
**AI** in the split header opens an agent chat about the database. Its composer
starts with a mention of the database; the schema and table guidance go to the
@@ -474,7 +482,9 @@ The same tools are exposed to agent sessions through the Macro MCP server.
In a document, channel composer, or the task/document creation composer,
`/query` → **Query** opens the question box with the AI prompt focused
-immediately. The empty input rotates through example questions; a selected database
+immediately. New draft questions bypass the saved-answer viewport gate; a cold
+module load shows **Opening database…** until the question input is ready. Saved
+answers still load when they approach the viewport. The empty input rotates through example questions; a selected database
uses its actual table and column names. Typing hides these hints, and reduced-motion
preferences keep them static. Use the searchable source picker below the question to
choose a database; the entire chosen database is in scope, without a table