reactive/data-client / .agents/skills/data-client-v0.19-migration
data-client-v0.19-migration
VerifiedUpgrade apps that already use @data-client to v0.19. Runs the v0.19 codemod, then fixes what it flags and what it can't see. Use when bumping @data-client packages to 0.19, or when Controller.fetchIfStale(), custom Managers or the managers prop break after upgrading. Not for adopting Data Client for the first time.
@data-client v0.19 Migration
Every breaking change, with Before/After code: v0.19 migration guide.
Step 1: bump and run the codemod
Bump the app's @data-client/* dependencies to ^0.19.0 together.
@data-client/testnow requires@data-client/react0.19;typescriptmust be 4.0 or later, andvue3.4 or later.- React Native: tests with
@data-client/testneed@testing-library/react-native. Apps now load the native build, so with React Navigation, stale data refetches on screen focus. @data-client/ssrhas no 0.19 release; if it's installed, read Step 4 first.- If the repo links skills with
data-client-skills, runnpx --no data-client-skills --upgradeafter the bump so the linked skills match 0.19 (Step 12 unlinks the migration skills).
Commit first so you can review the diff, then point the codemod at your source roots, not the repo root (it skips only
node_modules). Also pass any folder of debugging or end-to-end scripts that reads __DC_CONTROLLERS__
(rg -l '__DC_CONTROLLERS__' .); the codemod migrates those files even without an @data-client/* import:
npx @data-client/codemods v0.19 <source-root> --deprecations=false
0 errors, N unmodified is a clean run, not a failure. The codemod parses JavaScript and TypeScript only, and skips
files without an @data-client/* import (except to migrate __DC_CONTROLLERS__); the searches below find what it
skipped, including .vue and other single-file components.
Step 2: Controller.fetchIfStale() always returns a Promise
It used to return the data synchronously when fresh. Now it always returns a Promise, and a call you don't await never rejects unhandled: the error is stored for components, like any fetch error. Details.
Skip this step if rg -n 'fetchIfStale' <source-root> finds nothing.
Where an instanceof Promise or isPromise() check had a branch that awaited the result and read the data (or the
other branch was empty), the codemod already kept that branch and deleted the other. What's left:
- Fix each
TODO(data-client): fetchIfStale() always returns a Promisecomment. The code below it reads the result as data (a check whose Promise branch did nothing, a field, destructuring, anif).awaitthe call where the data is needed, delete the branch that handled synchronous data, then delete the comment. - Fix each
TODO(data-client): an awaited fetchIfStale() rejectscomment. Awaited calls now reject when the latest fetch failed within errorExpiryLength; they used to resolveundefined. Move the fallback below the comment (?? fallback,if (!data)) into a.catch()ortry/catcharound the call when it was meant for failures. Other awaited calls are fine as they are: a router shows its error UI. - Check every other
fetchIfStale(call for reads the codemod can't follow: results passed to a function, stored on an object or class field, or in files and components it skipped. A sync-data branch behind such a check now never runs, and nothing fails to type-check. To check freshness without fetching, usectrl.getResponse(endpoint, ...args, ctrl.getState()). - A
.then()chain or anasyncfunction around an unawaited call makes a new Promise that can reject, so end the chain in.catch(), or catch inside the function. A bare unawaited call needs none. - Controller subclasses that override
fetchIfStale()must return a Promise.
// Before
const issue = ctrl.fetchIfStale(IssueResource.get, { id });
if (!(issue instanceof Promise)) render(issue);
// After
const issue = await ctrl.fetchIfStale(IssueResource.get, { id });
render(issue);
Step 3: unawaited reads never reject unhandled
ctrl.fetch() of an endpoint without sideEffect (a GET or other read) is now safe to call without awaiting, like
fetchIfStale(): the error is stored for components reading that endpoint. Mutations still reject unhandled, and
await or .catch() still get the error, so no code breaks.
Details.
- Error monitoring: failures of unawaited reads (
fetch()orfetchIfStale()) no longer reach global unhandled-rejection handlers (Sentry and similar). If the app uses an error tracker, say so in your summary and suggest the error reporting Manager. Don't add it unasked: it reports every failed fetch, not only these. - No-op catches: the codemod deleted
.catch(() => {})on unawaitedfetchIfStale()and on unawaitedfetch()of a resource'sget,getListorgetList.getPage. Other no-op catches are harmless, so leave them. - A read no component renders (a "load more"
getPage, a refresh of an off-screen list) now fails silently: wrap it inuseLoading()so its error shows.
Step 4: Next.js Pages Router is not supported
Skip this step unless the app uses @data-client/ssr (DataClientDocument, AppDataProvider in pages/_document or
pages/_app). It stops at @data-client/react 0.14, and 0.19 supports only the App Router: render DataProvider from
@data-client/react/nextjs in app/layout.tsx, then uninstall @data-client/ssr (and @data-client/redux if nothing
else uses it). Moving pages to the App Router is a routing migration, so confirm with the owner before starting it.
Details.
Step 5: custom Managers
Skip this step if
rg -n 'managers|implements Manager|extends \w*Manager|: Manager\b|getMiddleware|cleanupDate' <source-root> finds
nothing. Otherwise bring each custom Manager to the 0.19 lifecycle in skill "data-client-manager" (the current copy
ships at node_modules/@data-client/core/skills/data-client-manager/SKILL.md; one linked into the project may be older):
cleanup() pauses without ending the store, and each store gets new Managers. The codemod renamed getMiddleware()
where it only returned a function, and gave Managers without middleware a pass-through. What's left:
- Fix each
TODO(data-client)comment aboutgetMiddleware(),managersorcleanupDate, then delete it:getMiddleware()that does work first: move the work intoinit(), and define amiddlewareproperty.super.getMiddleware():supercan't reach the parent's property, and a redeclared field can't read it (TS2729). Wrap it in the constructor instead, without redeclaring the field:constructor() { super(); const parent = this.middleware; this.middleware = controller => ... }.() => managersaround an array built elsewhere: it still shares those instances between stores. Make the array's definition the function, so eachnewruns per store, and pass that function.cleanupDate: it's removed; delete the code that reads or sets it.
- Move setup out of the constructor and
middlewareintoinit(): StrictMode and<Activity>callcleanup()and laterinit()on the same store. Save the controller inmiddleware(this.controller = controller) forinit()to use. Stop resetting store state incleanup(), and guard middleware side effects with a fieldcleanup()clears (this.socket?.send()), since actions can still arrive after it. - Arrays in files without an
@data-client/*import aren't converted, and throw amanagers is not a functionTypeError on mount. - Managers that call
controller.resolve()pass themeta.fetchedAtof the fetch action they resolve: 0.19 matches responses to fetches by it, afterresetEntireStore()and against newer fetches. The codemod did this where the endpoint wasaction.endpointunder anactionTypes.FETCHcheck; fix each otherfetchedAt: Date.now()that resolves a fetch action.
Details: middleware, cleanup, managers function.
Step 6: test helpers
- renderDataHook() now runs its
managers; before, it ignored them. The list replaces the defaults, so it needs aNetworkManager, plus aSubscriptionManagerif the hook polls (the codemod adds both to lists ofnewcalls), and the test's Managers now act on its actions. - A custom Provider passed to makeRenderDataHook() must accept
managers: () => Manager[], likeDataProvider. Details.
Step 7: Vue
Skip this step unless the app uses @data-client/vue.
DataClientPlugingarbage-collects unused data by default. Code that readsuseCache()after long idle can getundefined; pass a customgcPolicyonly if the app needs data kept longer.useFetch()is typed as aRef:promise.resolvedbecomespromise.value.resolved.
Step 8: __DC_CONTROLLERS__ is now __DC__
The codemod rewrote __DC_CONTROLLERS__.get(name) to __DC__.store = name and __DC__.controller in the files it
processed. Skip this step if rg -n '__DC_CONTROLLERS__' . finds nothing. What's left is in strings (such as
page.evaluate('...')), HTML, files the codemod didn't process, and code it marked: reads of the first controller, and
code that handled a missing store. Read __DC__.controller, after setting __DC__.store = name when the page has
several stores. It throws when the store isn't mounted, where .get(name) returned undefined, so check
__DC__.stores.includes(name) first where the store may be missing.
Details.
Step 9: verify
- Search for
TODO(data-client): none should remain. Search forrg -n '=> \w*[mM]anagers\b|getMiddleware|cleanupDate|__DC_CONTROLLERS__'and fix what's left. Search forinstanceof Promise,isPromiseand.then ===nearfetchIfStale: each one is a sync-data branch that no longer runs. - Run the type checker. Property reads on a
fetchIfStale()result now fail to type-check, since it is a Promise. A Manager withoutmiddlewarefails too (Step 5). Schemas now type more calls; fix the value or param name instead of casting, since the old code wrote data its schema doesn't describe, or widen the Entity's field types if the data really takes that shape:ctrl.set()values, includingctrl.set(getList.schema.push, args, rows)process(value, params)params, which can beundefined: readparams?.pagegetOptimisticResponse()return values
- Run the tests. The codemod made
spyOn(ctrl, 'fetchIfStale')andfetchIfStale: jest.fn()mocks resolve their value; make any otherfetchIfStalemock, such as a hand-written fake Controller, return a Promise too. Some assertions now fail by design; update them:useLoading()no longer keeps an old error.- A fixture whose request is aborted now rejects with an
AbortError. - A suspended
renderDataHook()now runs its Managers'init(). - After
DataProviderunmounts (React 18+),set(),setResponse(),resetEntireStore()andfetch()of an endpoint withoutsideEffectnever resolve; don'tawaitthem there. - A
DELETEendpoint that declaresbodynow sends its last argument as the body, not url params. If callers pass no body, removebodyfrom the endpoint.
Step 10: deprecated APIs (own commit)
They still work, but a later release removes them, so do this step unless the user opts out. Ask first when the user can answer mid-task; otherwise go ahead. Commit Steps 1-9 first and make this its own commit, so it reverts alone; if the user makes the commits, list the files this step changed instead.
npx @data-client/codemods v0.19 <source-root> --deprecations=only
It renames what has a replacement that does the same thing: resource().create to getList.push (the same request)
where it runs, for resources declared in the file or imported from a relative path or tsconfig paths alias; Vue
waitForNextUpdate() to allSettled(); DevTools actionsBlacklist/actionsWhitelist to
actionsDenylist/actionsAllowlist; and static pk() args to readonly any[]. It leaves a TODO(data-client)
comment naming the replacement on the rest. Fix each, then delete the comment, and repeat Step 9. Gotchas:
*Resource.createit didn't rename (imported from a package, or built with something other thanresource()from@data-client/rest): if the resource'sextend()replacescreateorgetList, check that the call keeps its path and options.- Code that compares endpoints, like
action.endpoint === XResource.create, comparesnames instead:action.endpoint.name === XResource.getList.push.name. Each read ofgetList.pushmakes a new endpoint, so===never matches it. Files the codemod processed carry a TODO there; also checkrg -n '\.create\b' <source-root>for.vueand other files it skipped, and for resources not named*Resource. - The endpoint's
namechanges fromPost.createtoPost.getList.create. Update code that matches the name as a string, such as Managers that log or time requests by name:rg -n "\.create['\"\]" `.
Then fix what's left of rg -n 'waitForNextUpdate|createDataClient|actions(Black|White)list' <source-root>. The blog's
future releases lists changes that will break
later.
Step 11: adopt 0.19 features (optional, own commit)
Nothing here is needed to upgrade: it simplifies code and speeds up store writes with features new in 0.19. Skip it when the user asked for only what the upgrade needs. Ask first when the user can answer mid-task. Otherwise run the codemod part, and list the judgment calls below in your summary instead of making them. Commit Steps 1-10 first and make this its own commit; if the user makes the commits, list the files this step changed instead.
npx @data-client/codemods v0.19 <source-root> --improvements=only
It rewrites only code it can prove does the same thing, apart from the differences noted below. Each item links the release post's example; read it when a rewrite or a judgment call below is unclear.
-
A loop (
for...of,forEach(),rows.map()orPromise.all(rows.map())) that callsset()once per row becomes one batch set():ctrl.set([Ticker], rows). It batches only when:- each row is plain data, never an updater function: an object literal, a row of
JSON.parse()without a reviver whose array the file only reads and doesn't export, or typed as the Entity or a plain object type; - the row calls only globals, imports and methods of values built from the row, with arguments built from the row,
literals and
consts set to a literal, and reads nothis,letorvar; - in a file that can make a getter (it declares a getter or setter, names
defineProperty,defineProperties,setPrototypeOf,__defineGetter__,__proto__orProxy, also destructured or as a string key, or usesObjectorReflectother than to read a named member, likeObject.create(),Object[name]orconst O = Object), the row and dropped args also read only the row, globals, imports,consts set to a literal and variables of plain data, solive.countand{ ...live }can't run a getter there, and the rows are parsed JSON or plain data that only the loop reads ([new Live()]androws.forEach(row => Object.defineProperty(row, 'count', { get }))keep the loop). A parameter counts as an import only when its function is a named function the file uses only to export, so a parameter of a method, a callback or a function the file calls (save(ctrl, rows, live)) keeps the loop; - the Entity's
pk()andprocess()read only the row; - its
pk()andprocess()call only globals, imports and methods of the row, since a helper the file declares could read the store, and read no variable that can change between rows (let seq) and no static getter the file declares (Live.count,this.count) or static field it writes, and never write throughthis; its instance code (constructor, methods, getters, setters and field values, whichpk()can reach throughthisorsuper) names only types, globals, imports, its own variables,consts set to a literal, plain data nothing changes and Entity classes it constructs (author = User.fromJS(), if no class in its chain overridesfromJS()), and never reaches static members (this.constructorornew.target); - it has no
static indexes(oneset()per row keeps only the last row's index entry), no decorators, and no override ofvalidate()or the store-merge methods (shouldUpdate(),shouldReorder(),mergeWithStore(),mergeMetaWithStore()); - nothing in the Entity's file, the loop's file or a barrel it is imported through changes the class's static
members or passes the class to a function outside
@data-client. It reads only those files and the files its schema imports, so check that no other file patches a batched Entity.
It guards each batch over a list that can be empty with
if (rows.length), so an empty list still dispatches nothing; keep that guard when you batch by hand. Three things differ from the loop:- Each batch dispatches one SET action whose
action.schemais the Array ([Ticker]), so check Managers and middleware that match SET actions by schema: matchaction.schema[0]too. - A row that throws while its value is built, or in
pk()orprocess(), makes the whole batch write nothing, where the loop still wrote the rows before it. - Rows with the same
pkin one batch merge with each other, so only the first is checked against the stored entity'sfetchedAt. This differs only when the store holds newer data than the client's clock (such as after SSR from a server whose clock runs ahead), or when the list holds the same row object twice.
- each row is plain data, never an updater function: an object literal, a row of
-
ctrl.set([new Invalidate(Todo)], [{ id }])becomesctrl.set(new Invalidate(Todo), { id })(before/after). Its SET action'saction.schemais then theInvalidateinstead of an Array. -
Vue:
DataClientPlugin'sgcPolicy: new GCPolicy()(now the default) is dropped,GCPolicyis imported from@data-client/vue(before/after), andcomputed(() => args)passed to a composable becomes the getter() => args(before/after). -
|| typeof data === 'symbol'guards in conditions on ReactuseCache()anduseDLE()data are dropped (before/after).
Then, by judgment:
- Batch the
set()loops it left (rg -n -B3 '\.set\(' <source-root>nearfor,forEach,map): mixed Entity types take aUnion, deletes a[new Invalidate(E)], rows keyed by id aValues, and a loop with anifa.filter()first.ctrl.set(R.getList.schema.push, args, row)loops batch into onepushof the list when the Entity'spk()andprocess()don't readparent, which is the row per call and the list in a batch. Keep a loop whose Entity readsargsorparentinpk()orprocess(), whosepk()orprocess()calls a helper the file declares, or whose instance code names one, a loop that passes updater functions or has a loop variable default other than a literal, a name, or an array or object of them (count = currentCount(id)), andunshift(a list goes in as given, one per row reverses it). A Manager that callsset()per message buffers messages and flushes them with oneset()(skill "data-client-manager", batching). Batchctrl.fetch(getList.push, row)loops into one arraypushonly when the API accepts an array body, since it sends one request instead of N. Examples: batch set(), push a list. - Remove casts 0.19 types made unnecessary, then type-check; a cast whose removal fails reveals a value its
schema doesn't describe, so fix the value instead:
as anyonset()args or values,push/unshift/removebodies (also on Collections in aQueryorLazy), unionbodyvalues,FormData,getOptimisticResponse()returns, aControllersubclass passed toDataProvider,prepareStore()'s store,action.meta.promise; andas unknown as T[]onfetch(getList.push, list)results. Typeprocess(value, params)params from the endpoint by removingparams: any. Examples: set() values, process() params, optimistic responses, push bodies, Collections in a Query, FormData, union bodies, other types. - Vue:
computed()stored in a variable only to make composable args reactive can become a getter. Delete a Vitestserver.deps.inlineentry for@data-clientadded to fixuseEnhancedReducer is not a function(details). - Cancellation: a custom
Endpointthat wraps an SDK call can passthis.signalon to it, without declaringthis(example).
Step 12: unlink the migration skills
Whether or not you did Steps 10 and 11: if you ran data-client-skills --upgrade in Step 1, run
npx --no data-client-skills to unlink the migration skills. Not before: it removes this skill.
Reference
- Codemod source:
packages/codemods/src/transforms/v0.19.js
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |