Uh oh!
There was an error while loading. Please reload this page.
docs(core,data-objectstack): let each adapter README document its own directory - #6227
Conversation
… directory `packages/core/src/adapters/README.md` was entirely about an ObjectStack adapter that no longer lives in that directory. Its headings, feature list, filter-operator table, query-parameter table and one-entry "Available Adapters" list all described `@object-ui/data-objectstack`, while the exports that directory really ships — `ApiDataSource`, `ValueDataSource`, `resolveDataSource`, `runBatchTransaction`, `emulateBatchTransaction` — were named nowhere. `packages/core` publishes its `src/`, so this shipped to consumers. Measurement first, as the triage required: `packages/data-objectstack`'s own README already carries the setup, features, error hierarchy and API reference, but its query translation is one feature bullet — the operator and parameter mapping tables exist ONLY in the `core` copy. So this is route A as a port, not route B: the tables move to the package that owns the behaviour rather than being dropped. `## Creating Custom Adapters` is unchanged — the one section always about this directory, importing only from `@object-ui/types`. Part of #6213 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019b5UBNMtTzKbVtZZGvFuxe
✅ Console Performance Budget
The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it. 📦 Bundle Size Report
Size Limits
|
yinlianghui-tw
commented
Aug 25, 2026
PM review — ACCEPT. ⭐ Your correction to my order is right, and it is the same defect class the card is about.Reviewed by the ⛔ "Four adapters" was wrong in the card, in triage, and in my order — verified hereI read
⭐ And your reason is the part worth keeping:
That is exact. The page was wrong because it named things that were not exports of the package it told readers to import from; a fix that listed a filename as an adapter would have reproduced the defect in a new place, under a card written to remove it. Three of us wrote "four adapters" by reading the directory listing — the same shortcut, one directory over. Route A as a PORT — the measurement genuinely decided it, and it decided against the cheap answerYou read ⛔ So B — delete, let the owning package have it — would have destroyed material that exists nowhere else. That is precisely the outcome the measurement was there to prevent, and it is the one I would have defaulted to if the reading had come back "already covered." Porting the four blocks into a new Query Translation section, positioned between Features and Metadata Caching, is the right resolution: one source of truth, in the package that owns the behaviour, with nothing lost in transit.
The gate problem you hit, and how you handled it
That is the correct handling of a gate that does not exist yet, and the census reconciles cleanly against #6212's own:
Both deltas are explained by the diff and neither is a surprise. That is what a census is for.
|
Uh oh!
There was an error while loading. Please reload this page.
…ger in this diff The `@object-ui/core` patch changeset described the two repaired import paths in `packages/core/src/adapters/README.md`. #6227 (a26b9e4) has since rewritten that page wholesale — the ObjectStack half is deleted and its material moved to `@object-ui/data-objectstack` — so this branch resolved that file to #6227's version and now contributes nothing to it. What remains here is `scripts/`, `.github/workflows/`, the docs-site guide page and the private root manifest: zero published source of any released package. `check-changeset-presence.mjs` confirms it — "0 of them published source of a package the release covers ... no changeset is owed." Keeping it would have published a release note for a fix this diff does not contain, and double-counted a `@object-ui/core` patch that #6227's own changeset already carries. Note that the presence gate is green either way, so this is a judgement it cannot make. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019b5UBNMtTzKbVtZZGvFuxe
Fixes#6213
Route A, as a port — decided by the measurement the triage named as deciding, not by preference. 3 files, +216 / −108.
The measurement, first, because it chooses A vs B
I read
packages/data-objectstack/README.md(486 lines) before moving anything. Section by section against the ObjectStack half ofpackages/core/src/adapters/README.md:core/src/adapters/README.mdsectiondata-objectstack's README?### Features(6 bullets)## Features(9 bullets) is a superset: CRUD, bulk, metadata, query translation, error handling, plus caching / connection / reconnect / progress### Usage(createObjectStackAdapterbasic)## Usage → ### Basic Setup, same call, correct import path### Advanced Usage—new ObjectStackAdapter({ baseUrl, token, fetch }),connect()## API Reference → ### ObjectStackAdapter → #### Constructorcarries the same shape includingfetch, and#### Methodslistsconnect()### Advanced Usage— thefind()call with$filter/$orderby/$top/$skip, and thegetClient()escape hatchgetClient()is a one-line method entry with no example; the query call appears nowhere### Filter Conversion+#### Supported Filter Operators(11 rows)#### Complex Filter Examples(the'and'AST)### Query Parameter Mapping(5 rows)### Example with Sorting## Available Adapters— one entry,ObjectStackAdapter, "from@object-ui/core"## Creating Custom AdaptersSo B is wrong on the evidence: deleting the page's ObjectStack half would have dropped the operator and parameter tables from the repository entirely —
data-objectstackdocuments that it translates queries and never how. A is a port, and the tables land in the package that owns the behaviour. C stays rejected.What the two pages now say
packages/core/src/adapters/README.md(180 → 171 lines) opens with what the directory holds, sends ObjectStack readers to@object-ui/data-objectstack, and gives each real export a snippet plus itsprovidermapping:ApiDataSourceprovider: 'api'— raw HTTP against theHttpRequestconfigs inViewDataValueDataSourceprovider: 'value'— in-memory array, no networkresolveDataSourceViewDataconfig asks forrunBatchTransaction/emulateBatchTransactionbatchTransactionwhen the adapter has one, sequential non-atomic emulation when it does notFive exports, not the four the card names, and that is deliberate:
batchTransaction.tsexportsemulateBatchTransactionandrunBatchTransaction— there is no export calledbatchTransaction. Naming the file rather than its exports is what put the old page in this state, so the table names whatindex.tsactually re-exports. Every behavioural claim is read from the source, not from the old page:ApiDataSourceignores itsresourceargument (the URL comes from the config) and returns a{ name, fields: {} }stub fromgetObjectSchema;ValueDataSourcedeep-clones on construction and implements$filter/$search/$orderby/$skip/$top/$selectlocally.packages/data-objectstack/README.mdgains one## Query Translationsection (+90 lines) between## Featuresand## Metadata Caching, carrying the ported material above.mainThe dispatch said #6212 was "armed and merging right now" and to "expect #6212's two import-path lines to already be present". Measured rather than assumed, twice — at branch point and again after the final merge:
packages/core/src/adapters/README.md:21onorigin/mainstill readsimport { createObjectStackAdapter } from '@object-ui/core';— the pre-feat(scripts): gate README self-imports against the real export surface #6212 text;git show origin/main:package.json | grep -c "check:readme-exports"→ 0;scripts/check-readme-exports.mjsis not onmain;state: open,merged: false, and it moved frommergeable_state: cleantodirtywhile this card was in flight.Two consequences, both stated rather than worked around:
origin/mainwas merged in as a merge commit atb3bcc49c4, clean, zero conflicts, and it touched none of my three files.check:readme-exportscould not be run as a repo gate, because it does not exist onmain. I ran feat(scripts): gate README self-imports against the real export surface #6212's own script, fetched fromorigin/claude/issue-5043-readme-exports-gateintoscripts/as an untracked file, executed, then deleted (git status --porcelainempty afterwards — it is not in this diff). Declaring that plainly becausenode some/missing/file.mjsexits 1 and would have been indistinguishable from a red gate had I just run the path.Its census on this tree, quoted from the line the script printed:
Against #6212's own census the movements are the expected ones: self-bindings judged 374 → 378 (this page's four new
@object-ui/coreimports —ApiDataSource,ValueDataSource,resolveDataSource,runBatchTransaction, each a real export viapackages/core/src/index.ts'sexport * from './adapters/index.js'), other-package bindings 93 → 91 (the two ObjectStack snippets are gone), 0 wrong-path either way.docs:check-linksis green, and on this page that green is nearly vacuous — stated because a reader would otherwise assume it was checked.SCAN_ROOTS'packages/*row excludes the basenameREADME.mdat every depth, so a nested README is scanned by nothing. The gate's own header names this file as the example (scripts/check-doc-links.mjs, "README.md, at every depth"), andcheck-doc-links.test.tspins it withpackages/core/src/adapters/README.mdas the fixture. So the two relative links I added are unjudged by CI and I verified them by hand:../../../data-objectstack/README.mdfrompackages/core/src/adapters/resolves topackages/data-objectstack/README.md— exists on disk;#cross-object-atomic-batch-batchtransaction— the heading ## Cross-Object Atomic Batch (batchTransaction) is atpackages/data-objectstack/README.md:372, and GitHub's slug for it is exactly that string.That gap is already filed as its own card — #6026, still open, which measured the same four nested READMEs and found zero dead links in them at the time. I did not re-file it; this PR adds two links to one of those four unscanned files, which is worth knowing when #6026 is priced.
Verification — every run at
87fd2a789, the merged head, and re-run after the mergeExit codes captured by redirect before any pipe (
node scripts/GATE-NAME > log 2>&1; E=$?), never$?after a pipeline, and each verdict quoted from the line the gate itself printed.check-doc-snippet-typesrequired a build (turbo run build --filter='./packages/*', 39 successful, 3m03s) — on the unbuilt tree it exits 1 with "the packages it resolves against are not built", which is a real red, not a skip. Same build is what makes the readme-exports export surface readable.Test scope, derived from disk rather than guessed.
grep -rlnfor readers of the three changed paths across*.test.ts/*.test.tsxinpackages,apps,scripts,e2ereturns exactly one file —scripts/__tests__/check-doc-links.test.ts, and it namespackages/core/src/adapters/README.mdonly as a synthetic fixture path, reading nothing off disk. The wholescripts/__tests__directory was run anyway, from the repo root (objectui#3378), never package-scoped. It was re-run after themainmerge because that merge changedscripts/check-doc-snippet-types.mjsand added a suite: 75 files / 2071 tests before, 76 / 2110 after.Lint, stated rather than run. All three changed files are
.md.eslint.config.jsdeclares no markdown processor and no**/*.mdblock, so no file in this diff is inside eslint's population at all — this is not a narrowing, it is an empty intersection.check-lint-coverage.mjsis green at 46/46 regardless.Everything above is local. The authoritative reading is the CI job conclusions on this PR.
Scope
No source, no behaviour, no
content/docs/releases/edit, and thecheck-readme-exportsgate itself was not touched — I only executed a copy of it and deleted the copy.@object-ui/coreand@object-ui/data-objectstackboth take apatchchangeset:corepublishes itssrc/, so this page ships in its tarball, and a README ridesdata-objectstack's tarball too.Generated by Claude Code