Skip to content

Commit 2823374

Browse files
committed
docs(build/data): align data-modeling pages with framework 16.0
- enable.softDelete → enable.trash in the capability example (softDelete is a 16.0 tombstone; object.zod.ts throws with guidance); added a 'Changed in 16.0' callout covering the removed object props (versioning, search→searchableFields, recordName→autonumber nameField, keyPrefix, tags, active, abstract). - referenceFilters warning upgraded from 'accepted but unread' to removed-in-16.0 (stripped at parse; lookupFilters + dependsOn is the only form). - summaryOperations example gains the new 16.0 filter (filtered roll-ups, #1868) with re-aggregation semantics. - Validation rules: 'delete' event removed (guard deletions with beforeDelete — the evaluator never ran on delete); state_machine gains initialStates (#3165) with the events:['insert','update'] requirement called out (events gates dispatch, so insert must be listed or initialStates is dead); noted 16.0 evaluates rules on multi-row updates (#3106). - Formulas: 'New in 16.0' — date-vs-number arithmetic is a build-time error pointing at daysBetween/daysFromNow/addDays/addMonths (#3306); null-guard ternary compiles; floor/ceil registered; date equality now matches via temporal coercion (#3183). - zh-Hans twins updated faithfully; other locale twins' code blocks fixed mechanically. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Kj2MJEPXoUXC4LiC3XYJc
1 parent 70e111f commit 2823374

13 files changed

Lines changed: 89 additions & 23 deletions

content/docs/build/data/formulas.mdx

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,22 @@ Field.formula({
9999
> `coalesce(record.x, '')` when concatenating — or use `joinNonEmpty`
100100
> and skip the ceremony.
101101
102+
### New in 16.0
103+
104+
- **Date arithmetic against numbers is a build-time error.** Expressions
105+
like `record.end_date - record.start_date + 1` or `today() + 30`
106+
always faulted at runtime (silently evaluating to null); the build now
107+
rejects them with an error pointing at `daysBetween(a, b)` for spans
108+
and `daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)` for shifts.
109+
- **The null-guard ternary compiles.** `cond ? value : null` — e.g.
110+
`record.end_date != null ? daysBetween(record.start_date, record.end_date) + 1 : null`
111+
— is the blessed way to keep a formula blank until its inputs exist.
112+
- **`floor(x)` / `ceil(x)` are registered.** They round toward −∞ / +∞
113+
(so `floor(-1.2) == -2`) — not toward zero like integer division.
114+
- **Date equality against `today()` now matches.** Temporal values are
115+
coerced before comparison, so `record.due_date == today()` and
116+
`daysBetween(today(), record.due_date) == 0` both work as expected.
117+
102118
### Formula as record title
103119

104120
Since ADR-0079, a record's title is a designated field via `nameField`

content/docs/build/data/formulas.zh-Hans.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,13 @@ Field.formula({
8787

8888
> **提示:**CEL 遇到 `null + string` 会抛错,所以拼接时把可能为空的操作数包进 `coalesce(record.x, '')` —— 或者直接用 `joinNonEmpty`,省掉这套仪式。
8989
90+
### 16.0 新增
91+
92+
- **日期与数字做算术现在是构建期错误。**`record.end_date - record.start_date + 1``today() + 30` 这样的表达式过去总在运行时出错(静默求值为 null);现在构建会直接拒绝,并在报错中指向 `daysBetween(a, b)`(求跨度)以及 `daysFromNow(n)` / `addDays(d, n)` / `addMonths(d, n)`(移动日期)。
93+
- **空值守卫三元表达式可以编译了。**`cond ? value : null` —— 例如 `record.end_date != null ? daysBetween(record.start_date, record.end_date) + 1 : null` —— 是让公式在输入就绪前保持空白的推荐写法。
94+
- **注册了 `floor(x)` / `ceil(x)`**它们分别向 −∞ / +∞ 取整(所以 `floor(-1.2) == -2`)—— 不像整数除法那样向零取整。
95+
- **日期与 `today()` 的相等比较现在能匹配了。**时间值会在比较前先做类型归一,因此 `record.due_date == today()``daysBetween(today(), record.due_date) == 0` 都能按预期工作。
96+
9097
### 公式作为记录标题
9198

9299
自 ADR-0079 起,记录的标题由 `nameField` 指定的字段决定 —— 组合式标题可以用文本公式:

content/docs/build/data/index.de.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,7 @@ ObjectSchema.create({
216216
apiEnabled: true, // generated REST endpoints
217217
trackHistory: true, // audit log of field changes
218218
feeds: true, // sys_comment / sys_activity / @mentions
219-
softDelete: true, // tombstone instead of hard delete
219+
trash: true, // soft-delete with restore (default true)
220220
},
221221
});
222222
```

content/docs/build/data/index.es.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ ObjectSchema.create({
215215
apiEnabled: true, // generated REST endpoints
216216
trackHistory: true, // audit log of field changes
217217
feeds: true, // sys_comment / sys_activity / @mentions
218-
softDelete: true, // tombstone instead of hard delete
218+
trash: true, // soft-delete with restore (default true)
219219
},
220220
});
221221
```

content/docs/build/data/index.fr.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,7 @@ ObjectSchema.create({
217217
apiEnabled: true, // generated REST endpoints
218218
trackHistory: true, // audit log of field changes
219219
feeds: true, // sys_comment / sys_activity / @mentions
220-
softDelete: true, // tombstone instead of hard delete
220+
trash: true, // soft-delete with restore (default true)
221221
},
222222
});
223223
```

content/docs/build/data/index.ja.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,7 @@ ObjectSchema.create({
216216
apiEnabled: true, // generated REST endpoints
217217
trackHistory: true, // audit log of field changes
218218
feeds: true, // sys_comment / sys_activity / @mentions
219-
softDelete: true, // tombstone instead of hard delete
219+
trash: true, // soft-delete with restore (default true)
220220
},
221221
});
222222
```

content/docs/build/data/index.ko.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ ObjectSchema.create({
214214
apiEnabled: true, // generated REST endpoints
215215
trackHistory: true, // audit log of field changes
216216
feeds: true, // sys_comment / sys_activity / @mentions
217-
softDelete: true, // tombstone instead of hard delete
217+
trash: true, // soft-delete with restore (default true)
218218
},
219219
});
220220
```

content/docs/build/data/index.mdx

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,11 +217,19 @@ ObjectSchema.create({
217217
feeds: true, // sys_comment / @mentions (default true)
218218
activities: true, // mirror CRUD to sys_activity timeline (default true)
219219
files: true, // Attachments panel (opt-in, default false)
220-
softDelete: true, // tombstone instead of hard delete
220+
trash: true, // soft-delete with restore (default true)
221221
},
222222
});
223223
```
224224

225+
> **Changed in 16.0:** the object-level `softDelete` prop is removed —
226+
> `ObjectSchema.create` now throws a located error if you pass it. The
227+
> shipped equivalent is `enable: { trash: true }` (soft-delete with
228+
> restore), on by default. The same cleanup removed `versioning`,
229+
> `search` (use top-level `searchableFields`), `recordName` (use an
230+
> autonumber field as `nameField`), `keyPrefix`, `tags`, `active`, and
231+
> `abstract`.
232+
225233
Since ObjectStack 14 the `enable.*` flags are **enforced**, not
226234
advisory: `feeds: false` rejects comment creation with 403
227235
`FEEDS_DISABLED`, `files` must be opted in before `sys_attachment` rows

content/docs/build/data/index.zh-Hans.mdx

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,11 +208,18 @@ ObjectSchema.create({
208208
feeds: true, // sys_comment / @提及(默认 true)
209209
activities: true, // CRUD 镜像到 sys_activity 时间线(默认 true)
210210
files: true, // 附件面板(需显式开启,默认 false)
211-
softDelete: true, // 软删除而非硬删除
211+
trash: true, // 软删除并可恢复(默认 true)
212212
},
213213
});
214214
```
215215

216+
> **16.0 变更:**对象级 `softDelete` 属性已被移除 —— 再传入它,
217+
> `ObjectSchema.create` 会抛出带定位信息的错误。对应的现行能力是
218+
> `enable: { trash: true }`(软删除并可恢复),默认开启。同一轮清理还
219+
> 移除了 `versioning``search`(改用顶层 `searchableFields`)、
220+
> `recordName`(改用作为 `nameField` 的自动编号字段)、`keyPrefix`
221+
> `tags``active``abstract`
222+
216223
自 ObjectStack 14 起,`enable.*` 开关是**强制执行**的,而不再只是声明:
217224
`feeds: false` 会以 403 `FEEDS_DISABLED` 拒绝评论创建;`files` 必须显式开启
218225
后才能创建 `sys_attachment` 行(否则返回 403 `FILES_DISABLED`);

content/docs/build/data/relationships.mdx

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -68,9 +68,10 @@ contact: Field.lookup('contact', {
6868
```
6969

7070
> **Warning:** The legacy `referenceFilters: string[]` property (e.g.
71-
> `['is_active = true']`) is accepted by the schema but **not read by
72-
> the record-picker UI** — it filters nothing. Always use the
73-
> structured `lookupFilters` + `dependsOn` shown above.
71+
> `['is_active = true']`) is **removed in 16.0** — it is stripped at
72+
> parse time, and even before removal the record-picker UI never read
73+
> it, so it filtered nothing. The structured `lookupFilters` +
74+
> `dependsOn` shown above is the only supported form.
7475
7576
## Master-detail (owned children)
7677

@@ -167,13 +168,20 @@ total_lines: {
167168
object: 'order_line', // child object to aggregate
168169
field: 'quantity', // field to aggregate
169170
function: 'sum', // count | sum | min | max | avg
171+
filter: { status: 'active' }, // new in 16.0: aggregate only matching children
170172
},
171173
}
172174
```
173175

174176
Summary fields are read-only and computed from the children — you never
175177
write them directly.
176178

179+
**New in 16.0:** the optional `filter` is a query-style `where`
180+
predicate — only child rows matching it are aggregated (e.g. count only
181+
`status == 'active'` children), and the roll-up re-aggregates when a
182+
child moves in or out of the predicate. It also lets several summaries
183+
roll up the *same* child object into different totals.
184+
177185
## Querying across relationships
178186

179187
Load related records in one call with `expand` — the query API follows

0 commit comments

Comments
 (0)