|
| 1 | +--- |
| 2 | +"@objectstack/spec": major |
| 3 | +"@objectstack/objectql": patch |
| 4 | +"@objectstack/metadata-protocol": patch |
| 5 | +"@objectstack/driver-mongodb": patch |
| 6 | +"@objectstack/driver-sql": patch |
| 7 | +"@objectstack/driver-memory": patch |
| 8 | +--- |
| 9 | + |
| 10 | +refactor(data)!: a select-list entry is a field name — the nested-select object form is removed (#4196) |
| 11 | + |
| 12 | +`FieldNode` declared two forms for one entry of `QueryAST['fields']`: |
| 13 | + |
| 14 | +```ts |
| 15 | +type FieldNode = |
| 16 | + | string // "name" |
| 17 | + | { field: string; fields?: FieldNode[]; alias?: string }; // nested select |
| 18 | +``` |
| 19 | + |
| 20 | +The object form was **declared-but-inert**. Nothing produced it, and nothing |
| 21 | +read `.fields` or `.alias` — every consumer on the path treats the list as |
| 22 | +`string[]`: `objectql`'s formula projection and its two known-field filters, |
| 23 | +`driver-sql`'s `select()`, `driver-memory`'s `projectFields`. `driver-mongodb` |
| 24 | +keyed its projection with the entry itself, so an object entry asked for a |
| 25 | +column literally named `"[object Object]"`, and the REST ingress stringified |
| 26 | +each entry before comparing it to the field map, so the same entry came back as |
| 27 | +`400 INVALID_FIELD: Unknown field '[object Object]'` — a rejection naming |
| 28 | +something the caller never wrote. An author who wrote |
| 29 | +`fields: [{ field: 'owner', fields: ['name'] }]` got it accepted by validation |
| 30 | +and then dropped or mangled, depending on the driver (ADR-0078 silently-inert |
| 31 | +declaration; ADR-0049 enforce-or-remove). |
| 32 | + |
| 33 | +The capability the object form described is already served, by a different key. |
| 34 | +Removing the second spelling rather than lowering it into the first is Prime |
| 35 | +Directive #12: one capability, one contract. |
| 36 | + |
| 37 | +**FROM → TO** |
| 38 | + |
| 39 | +| Was | Now | |
| 40 | +| :--- | :--- | |
| 41 | +| `fields: [{ field: 'owner', fields: ['name'] }]` | `expand: { owner: { object: 'user', fields: ['name'] } }` | |
| 42 | +| `fields: [{ field: 'owner' }]` | `fields: ['owner']` | |
| 43 | +| `fields: [{ field: 'owner', fields: ['name'] }]`, one column only | `fields: ['owner.name']` (dotted path) | |
| 44 | +| `fields: [{ field: 'total', alias: 't' }]` | `aggregations` / `windowFunctions` — they carry the live `alias` | |
| 45 | + |
| 46 | +The one-line fix: **a `fields[]` entry is a string.** Move nested selection to |
| 47 | +`expand`, which the engine resolves through batch `$in` queries (default max |
| 48 | +depth 3). |
| 49 | + |
| 50 | +There is no `os migrate meta` step, and deliberately so: `QueryAST` is a request |
| 51 | +shape, never stored in stack metadata, so the chain has no source to rewrite. It |
| 52 | +is registered as an ADR-0087 D3 **semantic** migration |
| 53 | +(`query-field-node-object-form-retired`) on the protocol-18 step instead — the |
| 54 | +`EnhancedApiError.fieldErrors` / `BatchOptions.validateOnly` precedent. Callers |
| 55 | +move their own select lists, and both channels tell them how: |
| 56 | + |
| 57 | +- **The parse.** `FieldNodeSchema` narrows to `z.string()` with an error map that |
| 58 | + answers an object entry with the prescription above, not "expected string, |
| 59 | + received object". `z.input` becomes `string`, so `tsc` fails at the authoring |
| 60 | + site first. |
| 61 | +- **The ingress.** `assertProjectionFieldsExist` judges the entry's *shape* |
| 62 | + before consulting the object's field map — it is wrong about the shape, not |
| 63 | + about this object, and a registry-less host would otherwise pass it to a driver |
| 64 | + that cannot read it. The 400 now names the retired form instead of the field |
| 65 | + `"[object Object]"`. |
| 66 | + |
| 67 | +No runtime behaviour changes for anything that ever worked; the defensive |
| 68 | +unwrapping the drivers had grown against a shape nothing sends goes with it. |
0 commit comments