# Migration guide This guide helps you upgrade from dcupl SDK 1.x (1.11.x) to 2.0. 2.0 keeps every 1.x method, but some behaviour changed: check [Behaviour Changes from 1.x](#behaviour-changes-from-1x) first. The new query API method names are optional; the older names still work in 2.0. ## Behaviour changes from 1.x Upgrade `@dcupl/core`, `@dcupl/common` and `@dcupl/loader` together, to the same 2.0 version. If your app uses dcupl Connect ([Debugging](/sdk/guides/debugging)), upgrade `@dcupl/connect` with them: its 1.x release depends on `@dcupl/core` 1.11. ```bash npm install @dcupl/core @dcupl/common @dcupl/loader npm install @dcupl/connect # only with dcupl Connect ``` Then check your code for these changes (compared with 1.11.11): **Data** - `data.update()` and `data.upsert()` replace every attribute in the payload as a whole. 1.x deep-merged arrays and `json` objects: `tags: ['x', 'y']` updated with `['z']` became `['z', 'y']`, now it is `['z']`. To change one key of a `json` attribute, send the whole object ([`update()`](/sdk/api/data#update)). - `data.reset({ model })` is staged like the other data methods: the rows are removed by the next `await dcupl.update()`. 1.x cleared the model at once, and the next `update()` brought the rows back. - `autoGenerateProperties` infers `int`, `float`, `boolean` and `date` (strict ISO 8601) from string values, for example CSV columns. 1.x typed every string column as `string`. Declare the property's type in the model to keep it a `string`. - `boolean` properties accept `'true'`, `'false'`, `'1'` and `'0'` (any case) and the numbers `1` and `0`, so `'false'` and `'0'` now load as `false` (1.x read every non-empty string as `true`). Any other string, number, object or array is a `WrongDataType` error and stays undefined. CSV columns follow the same rule, except that an empty cell counts as no value, not as `WrongDataType`. - Rows with the same key in one `data.set()` payload or data file: the last row wins as a whole, with one `NonUniqueKey` error per replaced row. 1.x merged the later rows into the first. - Keys compare as strings: `data.update([{ key: '1', … }])` changes a row loaded with `key: 1` (1.x ignored the update). A row without a key value (no `key`, or no value for a custom `keyProperty`) is dropped and reported as `MissingKey`; 1.x stored it under the key `'undefined'` (`'null'` for an explicit `null`). See [Rows without a key value](#rows-without-a-key-value). - An explicit `null` on a reference stays `null` (an `eq null` condition matches it) and is reported as `NullValue` unless the reference sets `quality: { nullable: true }`. 1.x turned it into `undefined`. See [Error Types](/sdk/advanced/quality-validation#error-types). - A `dcupl.update()` after `init()` that takes the partial path gives the same result as a full rebuild: derived properties and references (also those on resolved references) are recomputed instead of keeping their old values, an update that can change a query reference's result runs as a full update, and the data quality records equal those of an `init()` on the same data ([Partial updates](/sdk/api/data#partial-updates)). - A list created with `listItemKeys` or `query` stays in sync with the data: after every `dcupl.update()`, partial or full, it serves the current values of its items and drops the removed ones. Items that start matching a seed `query` still join only with `list.update()` or auto-update ([create()](/sdk/api/lists#create)). **Queries** - `invert` applies to every operator. 1.x ignored it on `gt`, `gte`, `lt`, `lte`, `size` and `isTruthy`. - Conditions on `Array<…>` properties match without an index. 1.x returned `[]` until a facet had built the attribute's index. - Dotted paths through references (`customer.country`) are new in 2.0 ([Deep queries](/sdk/queries/query-deep)); in 1.x such a condition or facet matched nothing. - A group without `groupKey` added in `add` mode (`addGroup()`, `apply(group)`) is added as its own group. 1.x ignored such a group (one with `groupKey: undefined` written out was merged into the first such group, overwriting its `groupType`). - A nested group without `groupType` is evaluated as `'and'`. 1.x could return the matches of a later condition when an earlier one matched nothing. A group you pass to `addGroup()`, `setGroup()` or `apply(group)` without `groupType` stays an `'or'` group, as in 1.x. - The `in` operator is new; in 1.x an `in` condition matched nothing ([Query Operators](/sdk/api/query-operators)). - A condition whose `operator` is neither built in nor registered as an [operator script](/sdk/guides/scripts) throws an `UnknownOperator` error ([Custom operators](/sdk/api/query-operators#custom-operators)). 1.x matched nothing, silently. - A sort the SDK can't apply is ignored with a warning: an `order` value other than `'ASC'` or `'DESC'`, an `order` without exactly one entry per attribute, or a sort script key with no registered script. 1.x ignored such a sort silently ([sort scripts](/sdk/guides/scripts#sort--reorder-query-results)). - `aggregate()` `count` is the number of values the attribute holds (0 when no item has one): each value of an `Array<…>` property or of a multi-valued dotted path counts once, and on a number attribute it is the count `avg` divides by. 1.x returned the number of items in the list, or `undefined` when no item had a numeric value, so `count` on a string or date attribute was always `undefined`. `min` and `max` skip items without a value (1.x could return `null` as the minimum). `sum` and `avg` are unchanged. **Models** - `models.set()` replaces the whole definition registered under the key, as `views.set()` already did in 1.x; `models.update()` merges into it ([`set()`](/sdk/api/models#set), [`update()`](/sdk/api/models#update)). In 1.x a second `models.set()` for the same key added its properties to the first one; now the first part is gone. The app loader still merges model files with the same key. - A `models.set()` or `models.update()` after `init()` takes effect on the next `dcupl.update()`, which rebuilds all data like `init()` (a full update, also when only one row changed). Lists created before the change keep working and serve the new definition. - `models.get()` and `views.get()` return a copy, and `models.set()` and `views.set()` store one, so changing either object no longer changes the registered definition (1.x handed out the registered definition). - One app loader per model key: a loader whose `process()` would load a model key that another loader of the instance already loads rejects with `SharedModelKeyError` (exported from `@dcupl/loader`). `dcupl.loaders.remove(key)` removes the models, views and rows that loader loaded on the next `update()` ([Processing](/sdk/api/loader#processing)). **Events and data quality** - `dcupl.update()` emits `result_updated` on every list whose result can have changed, and the global `dcupl_partial_update` event when it applies staged data changes or a model definition change (`models.set()`, `models.update()` or `models.remove()` after `init()`, also with no data staged; see [Events](/sdk/api/events)). 1.x emitted neither on a data update. `dcupl_handle_datacontainer` now fires when `update()` rebuilds everything; a partial update emits it, with just the `$DcuplErrorTrackingErrors` and `$DcuplErrorTrackingSummary` containers, whenever the model has recorded data quality errors, whether or not they changed. While no list over those two models exists, they are built at the first read instead of during `init()`/`update()`, and the event for that build fires then ([Quality reports](/sdk/advanced/quality-validation#quality-reports)). - `dcupl.quality.errors.summary()` is new: error totals per model, attribute and error type. - A CSV column that the model doesn't declare is reported as an `UnknownColumn` error (1.x dropped it without an error). A column whose values all fail type conversion is reported as `WrongDataType` (1.x: `UndefinedAttribute`). - A resource that fails to load is recorded as a loader error even with `quality: { enabled: false }`. **Packages** - The packages are native ES modules (`"type": "module"`), so `import { Dcupl } from '@dcupl/core'` works in Node ESM. 1.x failed there with `ERR_UNSUPPORTED_DIR_IMPORT`; `require()` still works. - The browser script builds are gone: `@dcupl/core` and `@dcupl/loader` no longer ship `dist/browser/*.umd.js`. For a `