Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
perf(open-knowledge): single-flight the /api/documents listing fetch (#2280)
Andrew Mikofalvy3b324757a3f0
diff --git a/.changeset/documents-list-single-flight.md b/.changeset/documents-list-single-flight.mdnew file mode 100644index 000000000..89413a6b1--- /dev/null+++ b/.changeset/documents-list-single-flight.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Coalesce the redundant `GET /api/documents` requests fired on load. Several consumers independently fetch the same full listing — the page-list context (asset/folder/file paths), the empty-editor state (entry count for the onboarding branch), and the wiki-link suggestion source (referenced assets) — so on boot and on every file-change push the server ran the same `ready`-gated disk walk two or three times concurrently. These now share a single in-flight request and one JSON parse. It is single-flight, not a result cache: the slot is released as soon as the request settles, so consumers that refetch on a file-change push still get current data. The sidebar file tree keeps its own `depth=1` lazy fetch (a different URL) unchanged.diff --git a/packages/app/src/components/EmptyEditorState.tsx b/packages/app/src/components/EmptyEditorState.tsxindex c8fdb03ce..133be43c3 100644--- a/packages/app/src/components/EmptyEditorState.tsx+++ b/packages/app/src/components/EmptyEditorState.tsx@@ -13,6 +13,7 @@ import { useIsEmbedded } from '@/hooks/use-is-embedded';import { emitCreateTopLevelFile } from '@/lib/create-file-events';import type { OkPackId } from '@/lib/desktop-bridge-types';import { subscribeToDocumentsChanged } from '@/lib/documents-events';+import { fetchDocumentListShared } from '@/lib/documents-fetch';export function EmptyEditorState({ terminalVisible = false }: { terminalVisible?: boolean }) {const [seedDialogOpen, setSeedDialogOpen] = useState(false);@@ -29,10 +30,9 @@ export function EmptyEditorState({ terminalVisible = false }: { terminalVisible?async function refresh() {try {- const res = await fetch('/api/documents');- const body = (await res.json().catch(() => null)) as unknown;+ const { ok, body } = await fetchDocumentListShared();if (cancelled) return;- const success = res.ok ? DocumentListSuccessSchema.safeParse(body) : null;+ const success = ok ? DocumentListSuccessSchema.safeParse(body) : null;if (success?.success) {setDocumentCount(countEntries(success.data.documents));documentCountResolvedRef.current = true;@@ -63,10 +63,9 @@ export function EmptyEditorState({ terminalVisible = false }: { terminalVisible?function handleSeedApplied() {clearTimeout(celebrateTimerRef.current);celebrateTimerRef.current = setTimeout(() => setCelebrateSignal((prev) => prev + 1), 500);- fetch('/api/documents')- .then(async (res) => {- const body = (await res.json().catch(() => null)) as unknown;- if (!res.ok) return;+ fetchDocumentListShared()+ .then(({ ok, body }) => {+ if (!ok) return;const success = DocumentListSuccessSchema.safeParse(body);if (success.success) {setDocumentCount(countEntries(success.data.documents));diff --git a/packages/app/src/components/PageListContext.tsx b/packages/app/src/components/PageListContext.tsxindex eb525f427..7a1a116ab 100644--- a/packages/app/src/components/PageListContext.tsx+++ b/packages/app/src/components/PageListContext.tsx@@ -7,6 +7,7 @@ import {setPageListCache,} from '@/editor/page-list-cache';import { subscribeToDocumentsChanged } from '@/lib/documents-events';+import { fetchDocumentListShared } from '@/lib/documents-fetch';import { parseApiError } from '@/lib/parse-api-error';import { deriveKnownFolderPaths } from './navigation-targets';@@ -101,12 +102,11 @@ async function loadDocumentListSummary(): Promise<{folderPaths: string[];filePaths: string[];}> {- const r = await fetch('/api/documents');- if (!r.ok) {- const body = (await r.json().catch(() => null)) as unknown;- throw new Error(parseApiError(body) ?? `/api/documents responded with ${r.status}`);+ const { ok, status, body } = await fetchDocumentListShared();+ if (!ok) {+ throw new Error(parseApiError(body) ?? `/api/documents responded with ${status}`);}- const data: { documents?: DocumentListEntry[] } = await r.json();+ const data = (body ?? {}) as { documents?: DocumentListEntry[] };if (!Array.isArray(data.documents)) return { assetPaths: [], folderPaths: [], filePaths: [] };const assetPaths = data.documents.filter((entry): entry is DocumentListEntry & { kind: 'asset'; path: string } => {diff --git a/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts b/packages/app/src/editor/extensions/wiki-link-suggestion.test.tsindex cdba3b948..3e36972d4 100644--- a/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts+++ b/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts@@ -1,5 +1,6 @@import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';import type { HeadingEntry } from '@inkeep/open-knowledge-core';+import { __resetDocumentListInflightForTests } from '@/lib/documents-fetch';import {autocompleteBoost,buildAnchorItems,@@ -321,6 +322,7 @@ describe('fetchPages', () => {afterEach(() => {globalThis.fetch = realFetch;+ __resetDocumentListInflightForTests();});test('a folder row survives and maps to a kind:"folder" PageItem', async () => {diff --git a/packages/app/src/editor/extensions/wiki-link-suggestion.ts b/packages/app/src/editor/extensions/wiki-link-suggestion.tsindex 629cebe89..2f88804f4 100644--- a/packages/app/src/editor/extensions/wiki-link-suggestion.ts+++ b/packages/app/src/editor/extensions/wiki-link-suggestion.ts@@ -16,6 +16,7 @@ import type { ResolvedPos } from '@tiptap/pm/model';import { PluginKey } from '@tiptap/pm/state';import { ReactRenderer } from '@tiptap/react';import Suggestion, { type SuggestionKeyDownProps, type SuggestionProps } from '@tiptap/suggestion';+import { fetchDocumentListShared } from '@/lib/documents-fetch';import { HttpResponseParseError } from '../http-client';import { WikiLinkSuggestionMenu } from '../wiki-link-suggestion/WikiLinkSuggestionMenu';import { getEditorDocName } from './doc-context';@@ -289,12 +290,12 @@ export async function fetchPages(): Promise<PageItem[]> {let docData: { documents?: Array<{ kind?: string; path?: string }> };try {- const docResponse = await fetch('/api/documents');- if (!docResponse.ok) {- console.warn('[wiki-link-suggestion] /api/documents responded with', docResponse.status);+ const { ok, status, body } = await fetchDocumentListShared();+ if (!ok) {+ console.warn('[wiki-link-suggestion] /api/documents responded with', status);return pages;}- docData = await docResponse.json();+ docData = (body ?? {}) as { documents?: Array<{ kind?: string; path?: string }> };if (!Array.isArray(docData.documents)) return pages;} catch (err) {console.warn('[wiki-link-suggestion] Failed to fetch referenced assets:', err);diff --git a/packages/app/src/lib/documents-fetch.test.ts b/packages/app/src/lib/documents-fetch.test.tsnew file mode 100644index 000000000..b690b07ab--- /dev/null+++ b/packages/app/src/lib/documents-fetch.test.ts@@ -0,0 +1,87 @@+import { afterEach, describe, expect, test } from 'bun:test';+import { __resetDocumentListInflightForTests, fetchDocumentListShared } from './documents-fetch';++const realFetch = globalThis.fetch;++afterEach(() => {+ globalThis.fetch = realFetch;+ __resetDocumentListInflightForTests();+});++function jsonResponse(body: unknown, status = 200): Response {+ return new Response(JSON.stringify(body), {+ status,+ headers: { 'content-type': 'application/json' },+ });+}++describe('fetchDocumentListShared', () => {+ test('coalesces concurrent callers onto a single in-flight request', async () => {+ let calls = 0;+ let release: () => void = () => {};+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ globalThis.fetch = (async () => {+ calls += 1;+ await gate;+ return jsonResponse({ documents: [{ kind: 'document' }] });+ }) as unknown as typeof fetch;++ const a = fetchDocumentListShared();+ const b = fetchDocumentListShared();+ release();+ const [ra, rb] = await Promise.all([a, b]);++ expect(calls).toBe(1);+ expect(ra.ok).toBe(true);+ expect(ra).toEqual(rb);+ expect((ra.body as { documents: unknown[] }).documents).toHaveLength(1);+ });++ test('refetches after the prior request settles (single-flight, not a cache)', async () => {+ let calls = 0;+ globalThis.fetch = (async () => {+ calls += 1;+ return jsonResponse({ documents: [] });+ }) as unknown as typeof fetch;++ await fetchDocumentListShared();+ await fetchDocumentListShared();+ expect(calls).toBe(2);+ });++ test('a rejected request clears the slot so the next call retries', async () => {+ let calls = 0;+ globalThis.fetch = (async () => {+ calls += 1;+ if (calls === 1) throw new Error('network down');+ return jsonResponse({ documents: [] });+ }) as unknown as typeof fetch;++ await expect(fetchDocumentListShared()).rejects.toThrow('network down');+ const result = await fetchDocumentListShared();+ expect(calls).toBe(2);+ expect(result.ok).toBe(true);+ });++ test('surfaces ok=false and the status for an error response', async () => {+ globalThis.fetch = (async () =>+ jsonResponse({ error: 'nope' }, 503)) as unknown as typeof fetch;+ const { ok, status, body } = await fetchDocumentListShared();+ expect(ok).toBe(false);+ expect(status).toBe(503);+ expect(body).toEqual({ error: 'nope' });+ });++ test('body is null when the response is not valid JSON', async () => {+ globalThis.fetch = (async () =>+ new Response('not json', {+ status: 200,+ headers: { 'content-type': 'text/plain' },+ })) as unknown as typeof fetch;+ const { ok, body } = await fetchDocumentListShared();+ expect(ok).toBe(true);+ expect(body).toBeNull();+ });+});diff --git a/packages/app/src/lib/documents-fetch.ts b/packages/app/src/lib/documents-fetch.tsnew file mode 100644index 000000000..f5e84bd84--- /dev/null+++ b/packages/app/src/lib/documents-fetch.ts@@ -0,0 +1,33 @@+export interface DocumentListFetchResult {+ ok: boolean;+ status: number;+ body: unknown;+}++let inflight: Promise<DocumentListFetchResult> | null = null;++export function fetchDocumentListShared(): Promise<DocumentListFetchResult> {+ if (inflight) return inflight;+ const pending = (async (): Promise<DocumentListFetchResult> => {+ const res = await fetch('/api/documents');+ const body = (await res.json().catch((err: unknown) => {+ console.warn('[documents-fetch] /api/documents response was not valid JSON:', err);+ return null;+ })) as unknown;+ return { ok: res.ok, status: res.status, body };+ })();+ inflight = pending;+ void pending.then(+ () => {+ if (inflight === pending) inflight = null;+ },+ () => {+ if (inflight === pending) inflight = null;+ },+ );+ return pending;+}++export function __resetDocumentListInflightForTests(): void {+ inflight = null;+}