Repository navigation
finding(data-objectstack): createObjectStackAdapter declares DataSource as its return, so the whole adapter API its own README documents is unreachable in TypeScript #7323
Description
Found while bringing packages/data-objectstack/README.md under check:doc-snippet-types (#5174 batch 8). Filed rather than fixed: packages/*/src is outside that PR's surface.
What the shipped declaration says
packages/data-objectstack/dist/index.d.ts:
declare function createObjectStackAdapter<T = unknown>(config: { ... }): DataSource<T>;
DataSource is @object-ui/types' interface (packages/types/dist/data.d.ts:292). It declares find, findOne, create, update, delete, bulk, batchTransaction, getObjectSchema, aggregate and the import/export job surface — and none of the adapter-only members.
The measured consequence
Compiled against the built dist with the doc-snippet gate's own compiler options and module resolution:
import { createObjectStackAdapter } from '@object-ui/data-objectstack';
declare const dataSource: ReturnType<typeof createObjectStackAdapter>;
dataSource.getClient();
dataSource.getCacheStats();
dataSource.invalidateCache('users');
dataSource.clearCache();
TS2339 Property 'getClient' does not exist on type 'DataSource<unknown>'.
TS2339 Property 'getCacheStats' does not exist on type 'DataSource<unknown>'.
TS2339 Property 'invalidateCache' does not exist on type 'DataSource<unknown>'.
TS2339 Property 'clearCache' does not exist on type 'DataSource<unknown>'.
The same four, plus getConnectionState, isConnected, onConnectionStateChange and onBatchProgress, are exactly the members packages/data-objectstack/README.md's own API Reference — ObjectStackAdapter — Methods list documents, and that four whole README sections (Metadata Caching, Connection State Monitoring, Batch Operation Progress, Troubleshooting/Cache Issues) are built around. The declaration typing the exported ObjectStackAdapter class carries all of them; only the factory's declared return narrows them away.
So a reader who follows the README's own Basic Setup — const dataSource = createObjectStackAdapter({ baseUrl }) — and then follows any of those four sections does not compile. The runtime object has the methods; the declared type does not admit them.
Why this is a producer-side gap, not a doc bug
The methods are real, exported and documented; there is nothing to correct on the page. The cast-free escape a consumer has today is to construct the class instead (new ObjectStackAdapter(config)), which the README's own API Reference documents as public — so the two supported ways of obtaining the same object give different type surfaces.
Options
- A. Widen the factory's declared return to the adapter's own type:
createObjectStackAdapter(config): ObjectStackAdapter(orDataSource<T> and ObjectStackAdapter). One line, and it makes declared match shipped for every documented member at once. - B. Leave the narrow return and add the missing members to
DataSource. Wrong shape: caching, connection state and batch progress are this adapter's concerns, not every data source's, and every otherDataSourceimplementation would then be declaring members it does not have. - C. Document the cast. Cheapest, and the worst of the three under the "declared = enforced" rule — it teaches a cast around a declaration that is simply narrower than the value.
Recommendation: A.
Where this shows up now
Batch 8 ships those README blocks compiling, by declaring the adapter as the exported ObjectStackAdapter class — truthful about the object, and about the one supported way to obtain that type today — and adds a short note to the README's setup section naming this card, so the page does not silently teach a shape the factory's return will reject. The note comes out when this is fixed.
Activity
huangyiirene commentedon Sep 3, 2026
Triage — R+118.
bug·priority:p2·pm:queue·domain:ui. ⛔ Not claimed, not dispatched.Verification (
origin/mainac8d523)Confirmed at the declaration site.
packages/data-objectstack/src/index.ts:5667opensso the declared return really is
DataSource<T>, and everything the adapter carries beyond theDataSourceinterface is unreachable through this entry point in TypeScript. The card namessetSystemCapabilitiesas an example and the JSDoc immediately above the config bag (:5677,[ADR-0066] See {@link ObjectStackAdapter.setSystemCapabilities}) points at exactly that method — so the file's own doc comment refers the reader to an API its declared return type hides.What I did NOT measure
⛔ I did not enumerate which members are lost, and I did not check whether the widening is safe. Two things decide that and neither is answered here:
ObjectStackAdapterexported? If the class is not part of the public surface, widening the return type to it exports the class by implication — a bigger change than it looks, and Clause ② territory.DataSource<T>return is exactly how you keep an adapter swappable. If that was the intent, the defect is the README and the JSDoc promising more, and the fix is prose, not types.⇒ Stop-condition: answer those two from the code before choosing a diff, and put both answers in the report. If the class turns out to be intentionally private, ⛔ do not export it to make the doc true — say so and let the docs change instead.
Anchoring
domain:ui—packages/data-objectstackis a published library ⇒ the objectui three-stream split routes it todomain:ui. ⛔ Notdomain:spec; nopackages/typescontract moves under either fix.Why
p2A published entry point under-declares its own API and the file's own JSDoc points at the hidden half — but nothing misbehaves at runtime and there is a documented workaround (name the class directly). Real, bounded, not urgent.
Generated by Claude Code
os-project-manager commentedon Sep 3, 2026
Claim — session
session_01EMrWaQw3XS5DxTHxp4yRyC, branchclaude/issue-7323-adapter-return-type, dispatched by thedomain:uiPM seat. No earlier claim comment on this thread (the only prior comment is the R+118 triage, which says unclaimed).Clause-②: yes
Why
yes: the branch I am taking is option A — widen the declared return of the published factorycreateObjectStackAdapterfrom the sharedDataSourceinterface to the concrete adapter type. That enlarges the declared public surface reachable through a published entry point (packages/data-objectstack/dist/index.d.ts): members that today are hidden behind the narrow return —getClient,getCacheStats,invalidateCache,clearCache,getConnectionState,isConnected,onConnectionStateChange,onBatchProgress,setSystemCapabilities— become reachable from the factory. The declaration limb is path-independent and judged from the card's content, so it isyesregardless of how few files the diff touches.needs:contract-reviewgoes on both carriers (this card and the PR).Answers to the triage's two stop-condition questions, from the code on today's
origin/main(e17605309), recorded here because they decide the shape:ObjectStackAdapterexported from the public entry? Yes, already.packages/data-objectstack/src/index.ts:2148readsexport class ObjectStackAdapterandtsup.config.tshas exactly one entry,src/index.ts, so the class is in the shippeddist/index.d.ts. Two pin tests already assert the exported spelling in source (cloud-surface-retired-4152.pin.test.ts:114,v3-deep-integration-retired-4241.pin.test.ts:135), andapps/console/src/dataSource.ts:14re-exports it by name. So widening the return does not export the class by implication — there is no new class export in the diff. That removes the triage's specific worry, though not the declaration itself.a5d817061addedautoReconnect/maxReconnectAttempts/reconnectDelayto the factory's own config bag while leaving the members that observe those features off the factory's declared return — the same change configured a feature it made unobservable through its own entry point. (b) The factory's JSDoc, added by41b7ce3ce, points the reader atObjectStackAdapter.setSystemCapabilities, a member its declared return hides. No comment, ADR or test anywhere pins the return asDataSource; there is noEqualassertion on it and no swappability note. The README documents the class constructor as public and today has to tell readers to hold the class instead.Full verification readouts land in the report comment (first line
os-dev-report) when the draft PR is up.Generated by Claude Code
Generated by Claude Code
fix(data-objectstack): createObjectStackAdapter declares the adapter …
os-project-manager commentedon Sep 3, 2026
os-dev-report
{ "issue": 7323, "status": "done", "branch": "claude/issue-7323-adapter-return-type", "pr": "https://github.com/objectstack-ai/objectui/pull/7503", "premise_still_valid": true, "summary": "Option A. `createObjectStackAdapter` now declares the adapter it returns instead of the shared `DataSource` interface (packages/data-objectstack/src/index.ts), so the nine adapter-only members the README documents are reachable through the factory. Q1: `ObjectStackAdapter` was ALREADY exported from the package's only entry (src/index.ts, tsup's single entry; present by name in the shipped dist/index.d.ts export list, which is unchanged name-for-name before and after) — nothing is exported by implication. Q2: the narrow return was NOT deliberate — no comment, ADR, test or `Equal` assertion pinned it, and commit a5d817061 added autoReconnect/maxReconnectAttempts/reconnectDelay to the factory's own config bag while leaving the members that observe those features off its declared return, in the same change; the factory's JSDoc (41b7ce3ce) also links to ObjectStackAdapter.setSystemCapabilities, which its declared return hid. Had either answer gone the other way this would have been a docs-only PR. Also: the README note naming this card is removed, the four sections built on the hidden members now continue from the factory call, a type-level pin with two controls was added, and a changeset states the branch taken. Clause-②: yes; needs:contract-review is on BOTH carriers, read back and confirmed on each. TWO CORRECTIONS TO THE BRIEF: (1) the member count is 9, not 4 — the brief frames four as failing and four more as documented-but-unmeasured, but all nine fail together with TS2339 against the shipped dist, setSystemCapabilities included; there is one tier, not two. (2) the line anchor moved as the brief predicted: the declaration site on e17605309 is src/index.ts:5680, not :5667, and export class ObjectStackAdapter is at :2148. Nothing else in the brief was wrong about the code.", "tests": "All at head 922ca54ec (clean tree), dependency closure built first. BEFORE the fix, the card's own repro against the shipped dist with the doc-snippet gate's compiler options: 9 x TS2339 (getClient, getCacheStats, invalidateCache, clearCache, getConnectionState, isConnected, onConnectionStateChange, onBatchProgress, setSystemCapabilities) — the card listed 4. AFTER: 0 diagnostics. `pnpm --filter @object-ui/data-objectstack type-check` exit 0 (script echoed `tsc --noEmit`); the new pin file is proven IN that program via --listFiles (1 hit, 55 test files, src/index.ts present), which resolves ./index from src and @object-ui/types from packages/types/dist. `pnpm exec vitest run --maxWorkers=2 packages/data-objectstack/` from the REPO ROOT (a package-dir run is refused by objectui#3378's guard, hit and corrected): 55 files / 737 tests passed. Gates, each quoted from its own verdict line, exit codes captured by redirecting before any pipe: check:doc-snippets exit 0 'Semantic phase: 455 of 455 block(s) judged, 0 failed' + 'Every covered documentation snippet compiles against the built types'; check:readme-exports exit 0 '414 self-imports judged (414 real, 0 wrong-path, 0 fabricated); 3305 export symbol(s) read from 37 of 40 tracked package(s) (0 unbuilt)' (first run was exit 1 'not on disk -- run pnpm build first' = a could-not-run, fixed by building --filter=./packages/*); check-changeset-presence exit 0 '1 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s)'; check:doc-fences exit 0; check-control-bytes exit 0 'scanned 6180 tracked text file(s)'. Lint: package lint exit 0, 423 problems / 0 errors / 423 warnings, all pre-existing no-explicit-any; new file 0/0 by eslint --format json. Declared narrowing: lint was run on the CHANGED PACKAGE only, not the repo; objectui's `pnpm lint` is `turbo run lint` and CI runs it in full. Separately probed with --no-inline-config, src/index.ts shows 4 errors at lines 1369-1389 — the documented eslint-disable no-console sites for the spec Logger binding (objectui#4029), ~4300 lines from either of my edits, invisible to the lint CI actually runs. REVERSE VERIFICATION, committed first, mutation and restore both proven on disk under trap ... EXIT INT TERM with an absolute restore path: mutation landed (injected-text count 0->1, removed-text 1->0; mutated blob 447fffc8 != HEAD blob bad31df4). LEG 1 (src pin, no rebuild needed — the pin imports ./index from src and its DataSource comes from packages/types/dist, which the mutation cannot reach): 13 diagnostics, ALL inside the pin file, 0 elsewhere in the package — 10 x TS2339 at lines 75-84 (the nine reads, invalidateCache twice), TS2344 at 89 and 113 (_HasHiddenMembers, _IsTheAdapter), TS7053 at 157 (the runtime member sweep). The two CONTROLS at lines 120 (_NotOnDataSource) and 135 (_StillADataSource) produced ZERO diagnostics — pin red, controls green. vitest on the same mutated tree still passed, which is the point: esbuild erases types, so the colour comes from tsc alone. LEG 2 (dist pin, rebuilt BOTH directions): rebuilt from mutated source, dist preflight showed the widened marker count 0 in dist/index.d.ts; the standalone dist probe reproduced the card exactly (9 x TS2339) and check:doc-snippets went exit 1 '455 of 455 block(s) judged, 4 failed' — precisely the four README sections rewired here. RESTORE proven by state, both halves: source blob back to bad31df4 == HEAD's and `git diff HEAD` 0 bytes; dist rebuilt again with widened marker back to 1, narrow marker 0, dist probe back to 0 diagnostics, check:doc-snippets back to exit 0 / 0 failed. All heavy runs went through the shared lock (scripts/pm/os-verify-lock.sh, slot objectui-7323); longest wait 112s, longest hold 169s; those are shared-box seconds, as the lock's own verdict line states.", "mcp_calls": "7 — issue_read get, issue_read get_comments, add_issue_comment (claim), issue_read get_comments (claim read-back), create_pull_request, issue_read get_labels, add_issue_comment (this report). Both label writes and the PR body read-back went through repo-scoped REST (probed 200 first), not MCP.", "open_questions": [], "out_of_scope_findings": [] }Two corrections to the dispatch brief
dist, all nine fail together with TS2339,setSystemCapabilitiesincluded — the one the file's own JSDoc points at. The brief's framing implies two tiers; there is only one.packages/data-objectstack/src/index.ts:5667was correct at triage time and correct at dispatch; the declaration site onorigin/maine17605309is:5680, andexport class ObjectStackAdapteris at:2148. Re-derived rather than trusted, per the brief's own warning.Nothing else in the brief was wrong. The fork was the right question to ask: Q1 came back "already exported", which is what makes this a one-line fix rather than a public-surface expansion by implication, and Q2 came back "not deliberate", which is what keeps it out of the docs-only branch. The
needs:contract-reviewgate is still warranted on the content limb, and the PR names the one direction in which the change is not purely additive (a hand-written structural stand-in can no longer satisfy the factory's return, because the widened type is a class with private members).Generated by Claude Code
Generated by Claude Code
fix(data-objectstack): createObjectStackAdapter declares the adapter …