finding(data-objectstack): `createObjectStackAdapter` declares `DataSource` as its return, so the whole adapter API its own README documents is unreachable in TypeScript

[yinlianghui]

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 (or DataSource<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 other DataSource implementation 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.

[huangyiirene]

Triage — R+118. bug · priority:p2 · pm:queue · domain:ui. ⛔ Not claimed, not dispatched.

Verification (origin/main ac8d523)

Confirmed at the declaration site. packages/data-objectstack/src/index.ts:5667 opens

export function createObjectStackAdapter<T = unknown>(config: { … }): DataSource<T> {

so the declared return really is DataSource<T>, and everything the adapter carries beyond the DataSource interface is unreachable through this entry point in TypeScript. The card names setSystemCapabilities as 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:

1. Is ObjectStackAdapter exported? 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.
2. Is the narrow return deliberate? A 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-objectstack is a published library ⇒ the objectui three-stream split routes it to domain:ui. ⛔ Not domain:spec; no packages/types contract moves under either fix.

Why p2

A 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]

Claim — session session_01EMrWaQw3XS5DxTHxp4yRyC, branch claude/issue-7323-adapter-return-type, dispatched by the domain:ui PM 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 factory createObjectStackAdapter from the shared DataSource interface 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 is yes regardless of how few files the diff touches. needs:contract-review goes 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:

• Q1 — is ObjectStackAdapter exported from the public entry? Yes, already. packages/data-objectstack/src/index.ts:2148 reads export class ObjectStackAdapter and tsup.config.ts has exactly one entry, src/index.ts, so the class is in the shipped dist/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), and apps/console/src/dataSource.ts:14 re-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.
• Q2 — is the narrow return deliberate? No evidence that it is, and two pieces of evidence that it is not. (a) Commit a5d817061 added autoReconnect / maxReconnectAttempts / reconnectDelay to 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 by 41b7ce3ce, points the reader at ObjectStackAdapter.setSystemCapabilities, a member its declared return hides. No comment, ADR or test anywhere pins the return as DataSource; there is no Equal assertion 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