Skip to content

Commit e516cf2

Browse files
docs(skills): objectstack-query examples under check:skill-examples (20 of 42 blocks marked) (#31507)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} --> _Requested by **Steedos** · [project thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9UbbGpTJCNsaq61jSt8xxWSP4N)_ Refs #31112 (slice 1 of a per-skill split: item 4, objectstack-query only; the card stays open) Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:objectstack-query 技能里 42 段 TypeScript 示例中,能独立成立的 20 段现在加了检查标记,CI 会把它们当真代码编译;其余 22 段(纯片段、故意写错的 ❌/✅ 对照)不标记,每个文件用一句话说明。 - 为什么改:AI 读技能写查询时照抄示例;以前这些示例没人编译,键名改了或被移除也不会报错。现在示例里写错键名、用已移除的键(如 `cursor`、`array_agg`)会在 CI 直接变红。 - 风险与回滚:只改技能文档,不动任何运行时代码;示例文字只多了两行类型声明或一行类型标注,教的规则不变。回滚即还原本 PR。 - 先看:`skills/objectstack-query/SKILL.md`(8 处标记与声明行)、`skills/objectstack-query/rules/pagination.md`(字面量改成带类型的 `const`)、`skills/objectstack-query/rules/filters.md`(token 余量为零,只换了一句开头)。 - 两分钟验证:`pnpm --filter @objectstack/spec check:skill-examples`,预期最后一行为 `✅ 307 prose examples type-check across 3 surface(s)`。 - 需要你做的:受管面(skills/** 为 Tier H),请审阅后批准或亲手合并。 ## What changes - 20 of 42 fenced `ts`/`typescript` blocks in `skills/objectstack-query` now carry the opt-in `check:skill-examples` marker on the line above the fence. - Engine-call blocks gain two lines, `import type { IDataEngine } from '@objectstack/spec/contracts';` and `declare const engine: IDataEngine;` (plus one `declare const` for a free variable in two blocks: `name`, `pageNumber`). - Standalone query literals become `const NAME: QueryInput = { ... };` with `import type { QueryInput } from '@objectstack/spec/data';`. - Left unmarked, said once per file: the bare `{ where: ... }` option fragments in `SKILL.md`; all seven `where` fragments in `rules/filters.md`; the ❌/✅ Common Mistakes pairs in `rules/aggregation.md` and `rules/pagination.md` (the ❌ half is wrong on purpose), plus pagination's OData `{ limit }` / `{ top }` pair and its REST request/response sketch. - Example fixes: none. Every marked block compiled as written; no rule's teaching changed. | File | marked / blocks before | after | |:--|:--|:--| | `SKILL.md` | 0 / 14 | 8 / 14 | | `rules/aggregation.md` | 0 / 11 | 8 / 11 | | `rules/filters.md` | 0 / 7 | 0 / 7 | | `rules/pagination.md` | 0 / 10 | 4 / 10 | ### `skills/**` readings (repo `objectstack-ai/objectstack`, `origin/main` a61ddc9 vs this head) | File | lines before → after | tokens before → after (ceiling) | |:--|:--|:--| | `SKILL.md` | 413 → 439 | 4329 → 4596 (5547) | | `rules/aggregation.md` | 241 → 262 | 1860 → 2096 (2357) | | `rules/filters.md` | 211 → 211 | 2477 → 2482 (2482) | | `rules/pagination.md` | 206 → 215 | 1158 → 1289 (1382) | | whole bundle, sum of every `SKILL.md` | 4566 → 4592 | 232095 → 233164 bytes | No ceiling is raised. `filters.md` pays its one sentence by replacing its opening line ("Comprehensive guide for building ObjectStack query filters."), which carried no rule; `aggregation.md` and `pagination.md` replace their equivalent opening lines the same way. ## Tests - `pnpm --filter @objectstack/spec check:skill-examples` exit 0: `✅ 307 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them`. - Reverse check (committed first, restored with `git checkout HEAD --`, `git status --porcelain` empty after): planting `bogusKey: 1` in the SKILL.md search call, `cursor: 'abc'` in a pagination literal and `function: 'array_agg'` in an aggregation literal turned the gate red with exactly three diagnostics: TS2353 unknown key at `SKILL.md:326`, TS2322 on `array_agg` at `aggregation.md:154`, TS2322 on the retired `cursor` key at `pagination.md:132`. ## Acceptance notes - `check:skill-examples` is not in this diff's derived gate list; it was run by hand (above). - `filters.md` now sits at token headroom 0, so the next edit there must pay in the same file. ## Verification Derived gates for this diff (46 commands, `dispatch-gates --commands --repo objectstack-ai/objectstack`) are listed with exit codes in the report comment on the card. --- _Generated by [Claude Code](https://claude.ai/code/session_01QsR2jTUGktmEesT5GaV2gg)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 45916c9 commit e516cf2

5 files changed

Lines changed: 88 additions & 22 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): objectstack-query's self-contained examples are now type-checked by `check:skill-examples`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Twenty of the forty-two fenced TypeScript blocks in `skills/objectstack-query` carry the opt-in check marker: 8 of 14 in `SKILL.md`, 8 of 11 in `rules/aggregation.md`, 4 of 10 in `rules/pagination.md`. Engine calls gain a two-line `IDataEngine` declaration from `@objectstack/spec/contracts`, and standalone query literals are typed as `QueryInput` from `@objectstack/spec/data`, so a renamed key, a removed key (`cursor`, `array_agg`) or an unknown option now fails the gate instead of shipping. Every marked example compiled as written; none needed a correction. The rest are left unmarked and each file says so once: the bare `{ where: … }` option fragments in `SKILL.md`, all seven `where` fragments in `rules/filters.md`, and the ❌/✅ pairs whose ❌ half is wrong on purpose. No rule's teaching changes.

‎skills/objectstack-query/SKILL.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,11 @@ The RLS / system-read escape hatch. A hook, job or endpoint that reads without
5757
one runs as whatever identity the caller carried — org-scoping hooks then return
5858
**fewer rows**, indistinguishable from "there is no data".
5959

60+
<!-- os:check -->
6061
```typescript
62+
import type { IDataEngine } from '@objectstack/spec/contracts';
63+
declare const engine: IDataEngine;
64+
declare const name: string;
6165
const SYS = { isSystem: true } as const;
6266
const [row] = await engine.find('project', { where: { name }, limit: 1, context: SYS });
6367
```
@@ -92,6 +96,8 @@ procedure and the full tombstone register are **objectstack-upgrade**.
9296

9397
## Filter Operators
9498

99+
The bare `{ where: … }` blocks here are option fragments, so `check:skill-examples` skips them.
100+
95101
### Implicit Equality (Shorthand)
96102

97103
The simplest filter — field equals value:
@@ -209,14 +215,16 @@ rules → Field References / Now-Anchored Comparands](./rules/filters.md)**.
209215

210216
Sort with `orderBy` — an array of sort nodes:
211217

218+
<!-- os:check -->
212219
```typescript
213-
{
220+
import type { QueryInput } from '@objectstack/spec/data';
221+
const query: QueryInput = {
214222
object: 'account',
215223
orderBy: [
216224
{ field: 'priority', order: 'desc' },
217225
{ field: 'name', order: 'asc' }, // Secondary sort
218226
]
219-
}
227+
};
220228
```
221229

222230
**Rules:**
@@ -226,9 +234,11 @@ Sort with `orderBy` — an array of sort nodes:
226234

227235
## Pagination
228236

237+
<!-- os:check -->
229238
```typescript
239+
import type { QueryInput } from '@objectstack/spec/data';
230240
// Offset paging — page 3
231-
{ object: 'account', limit: 20, offset: 40 }
241+
const page3: QueryInput = { object: 'account', limit: 20, offset: 40 };
232242
```
233243

234244
**When to use:** UI pages, small datasets, "jump to page N". It degrades on
@@ -245,7 +255,10 @@ The functions (`count`, `sum`, `avg`, `min`, `max`, `count_distinct`), date
245255
bucketing, `having`, and the per-measure `filter` are
246256
**[aggregation rules](./rules/aggregation.md)**. The call shape:
247257

258+
<!-- os:check -->
248259
```typescript
260+
import type { IDataEngine } from '@objectstack/spec/contracts';
261+
declare const engine: IDataEngine;
249262
// Total revenue per region
250263
const rows = await engine.aggregate('deal', {
251264
groupBy: ['region'],
@@ -269,7 +282,10 @@ rows; read each measure under its `alias`, and reference that same name from
269282
Load related records through lookup / master_detail fields. **Keep the foreign
270283
key in `fields`** — the relation is carried by that column:
271284

285+
<!-- os:check -->
272286
```typescript
287+
import type { IDataEngine } from '@objectstack/spec/contracts';
288+
declare const engine: IDataEngine;
273289
const tasks = await engine.find('task', {
274290
fields: ['title', 'status', 'assignee', 'project'], // the FK columns stay
275291
expand: {
@@ -300,7 +316,10 @@ const tasks = await engine.find('task', {
300316

301317
The canonical form is a **bare string** with a sibling `searchFields`:
302318

319+
<!-- os:check -->
303320
```typescript
321+
import type { IDataEngine } from '@objectstack/spec/contracts';
322+
declare const engine: IDataEngine;
304323
const rows = await engine.find('article', {
305324
search: 'machine learning',
306325
searchFields: ['title', 'content'],
@@ -359,7 +378,11 @@ related record's column, `where: { relation: { column: value } }`; to *display*
359378

360379
### Pagination Pattern for APIs
361380

381+
<!-- os:check -->
362382
```typescript
383+
import type { IDataEngine } from '@objectstack/spec/contracts';
384+
declare const engine: IDataEngine;
385+
declare const pageNumber: number;
363386
const page = await engine.find('account', {
364387
where: { status: 'active' },
365388
fields: ['id', 'name', 'email'],
@@ -375,7 +398,10 @@ Every KPI on a dashboard shares **one** aggregate call — unconditional measure
375398
plain, conditional ones carrying their own `filter`. `where` scopes the whole
376399
call, so reach for it only when every measure wants the same scope:
377400

401+
<!-- os:check -->
378402
```typescript
403+
import type { IDataEngine } from '@objectstack/spec/contracts';
404+
declare const engine: IDataEngine;
379405
const [kpis] = await engine.aggregate('deal', {
380406
aggregations: [
381407
{ function: 'count', alias: 'total_deals' },

‎skills/objectstack-query/rules/aggregation.md‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Aggregation Rules
22

3-
Guide for building ObjectStack aggregation queries.
3+
A block pairing ❌ with ✅ is left out of `check:skill-examples`: its ❌ half is wrong on purpose.
44

55
## Aggregation Functions
66

@@ -21,19 +21,24 @@ Guide for building ObjectStack aggregation queries.
2121
2222
## Basic Aggregation
2323

24+
<!-- os:check -->
2425
```typescript
26+
import type { QueryInput } from '@objectstack/spec/data';
2527
// SQL: SELECT COUNT(*) AS total_orders FROM order
26-
{
28+
const query: QueryInput = {
2729
object: 'order',
2830
aggregations: [
2931
{ function: 'count', alias: 'total_orders' }
3032
]
31-
}
33+
};
3234
```
3335

3436
## Aggregation with GROUP BY
3537

38+
<!-- os:check -->
3639
```typescript
40+
import type { IDataEngine } from '@objectstack/spec/contracts';
41+
declare const engine: IDataEngine;
3742
// SQL: SELECT region, SUM(amount) AS total, AVG(amount) AS average
3843
// FROM sale GROUP BY region
3944
const rows = await engine.aggregate('sale', {
@@ -56,9 +61,11 @@ convention in `SKILL.md`).
5661
field into uniform periods — this is the supported way to build time-series
5762
aggregations (never bucket by hand in app code):
5863

64+
<!-- os:check -->
5965
```typescript
66+
import type { QueryInput } from '@objectstack/spec/data';
6067
// Revenue per quarter per region
61-
{
68+
const query: QueryInput = {
6269
object: 'deal',
6370
groupBy: [
6471
'region',
@@ -67,7 +74,7 @@ aggregations (never bucket by hand in app code):
6774
aggregations: [
6875
{ function: 'sum', field: 'amount', alias: 'revenue' }
6976
]
70-
}
77+
};
7178
// Result rows: { region: 'us', closed_at: '2025-Q1', revenue: 42000 }, ...
7279
```
7380

@@ -92,7 +99,10 @@ aggregations (never bucket by hand in app code):
9299
> Ordinary FilterCondition operators plus `$and`/`$or`/`$not`; an unknown
93100
> operator is rejected loudly, never ignored.
94101
102+
<!-- os:check -->
95103
```typescript
104+
import type { IDataEngine } from '@objectstack/spec/contracts';
105+
declare const engine: IDataEngine;
96106
// ✅ Only customers with more than 5 orders
97107
const rows = await engine.aggregate('order', {
98108
groupBy: ['customer_id'],
@@ -112,7 +122,10 @@ use `where` to shrink the scan, `having` to threshold the aggregates.
112122
> conditional aggregate, and one reached directly refuses `NOT_IMPLEMENTED`;
113123
> unfiltered aggregations keep native push-down.
114124
125+
<!-- os:check -->
115126
```typescript
127+
import type { IDataEngine } from '@objectstack/spec/contracts';
128+
declare const engine: IDataEngine;
116129
// ✅ Total and conditional count in one call
117130
const [row] = await engine.aggregate('user', {
118131
aggregations: [
@@ -131,14 +144,16 @@ const [row] = await engine.aggregate('user', {
131144
> `COUNT(DISTINCT *)`. The per-aggregation `distinct: true` flag is NOT its
132145
> equivalent — it is a removed key.
133146
147+
<!-- os:check -->
134148
```typescript
149+
import type { QueryInput } from '@objectstack/spec/data';
135150
// SQL: SELECT COUNT(DISTINCT department) FROM employee
136-
{
151+
const query: QueryInput = {
137152
object: 'employee',
138153
aggregations: [
139154
{ function: 'count_distinct', field: 'department', alias: 'dept_count' }
140155
]
141-
}
156+
};
142157
```
143158

144159
## Window Functions
@@ -151,7 +166,10 @@ working alternatives:
151166
Model rankings in report/dashboard metadata (groupings + measures + sort),
152167
or fetch the ordered rows and rank in app code:
153168

169+
<!-- os:check -->
154170
```typescript
171+
import type { IDataEngine } from '@objectstack/spec/contracts';
172+
declare const engine: IDataEngine;
155173
// Top products per category — order the rows, rank in app code
156174
const rows = await engine.find('product', {
157175
fields: ['name', 'category', 'sales'],
@@ -167,7 +185,10 @@ const rows = await engine.find('product', {
167185

168186
Fetch the ordered rows and accumulate in app code:
169187

188+
<!-- os:check -->
170189
```typescript
190+
import type { IDataEngine } from '@objectstack/spec/contracts';
191+
declare const engine: IDataEngine;
171192
const txns = await engine.find('transaction', {
172193
fields: ['date', 'amount'],
173194
orderBy: [{ field: 'date', order: 'asc' }],

‎skills/objectstack-query/rules/filters.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Filter Rules
22

3-
Comprehensive guide for building ObjectStack query filters.
3+
Every block below is a `where` fragment, so `check:skill-examples` skips it.
44

55
## Operator Reference
66

‎skills/objectstack-query/rules/pagination.md‎

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Pagination Rules
22

3-
Guide for implementing pagination in ObjectStack queries.
3+
Fragments and ❌/✅ pairs are left out of `check:skill-examples`; the ❌ half is wrong on purpose.
44

55
## Strategies Overview
66

@@ -15,24 +15,26 @@ Guide for implementing pagination in ObjectStack queries.
1515
1616
## Offset Pagination
1717

18+
<!-- os:check -->
1819
```typescript
20+
import type { QueryInput } from '@objectstack/spec/data';
1921
// Page 1 (first 20 records)
20-
{
22+
const page1: QueryInput = {
2123
object: 'post',
2224
where: { published: true },
2325
orderBy: [{ field: 'created_at', order: 'desc' }],
2426
limit: 20,
2527
offset: 0
26-
}
28+
};
2729

2830
// Page 3 (records 41–60)
29-
{
31+
const page3: QueryInput = {
3032
object: 'post',
3133
where: { published: true },
3234
orderBy: [{ field: 'created_at', order: 'desc' }],
3335
limit: 20,
3436
offset: 40
35-
}
37+
};
3638
```
3739

3840
### OData Compatibility
@@ -51,21 +53,23 @@ Keyset pagination uses the last record's sort key value to fetch the next
5153
page. Because the `cursor` property was removed (see above), express the
5254
keyset as a `where` filter on the sort field:
5355

56+
<!-- os:check -->
5457
```typescript
58+
import type { QueryInput } from '@objectstack/spec/data';
5559
// First page
56-
{
60+
const first: QueryInput = {
5761
object: 'post',
5862
orderBy: [{ field: 'created_at', order: 'desc' }],
5963
limit: 20
60-
}
64+
};
6165

6266
// Next page — filter past the last record's sort key value
63-
{
67+
const next: QueryInput = {
6468
object: 'post',
6569
where: { created_at: { $lt: '2025-01-15T10:30:00Z' } }, // last seen value
6670
orderBy: [{ field: 'created_at', order: 'desc' }],
6771
limit: 20
68-
}
72+
};
6973
```
7074

7175
**⚠️ CRITICAL:** The keyset `where` field MUST match the `orderBy` field, and
@@ -114,16 +118,18 @@ duplicate key values can skip or repeat rows at page boundaries.
114118

115119
### Multi-field Sorting
116120

121+
<!-- os:check -->
117122
```typescript
123+
import type { QueryInput } from '@objectstack/spec/data';
118124
// Sort by status (asc), then by created date (newest first)
119-
{
125+
const query: QueryInput = {
120126
object: 'task',
121127
orderBy: [
122128
{ field: 'status', order: 'asc' },
123129
{ field: 'created_at', order: 'desc' }
124130
],
125131
limit: 50
126-
}
132+
};
127133
```
128134

129135
## REST API Pagination Pattern
@@ -197,7 +203,10 @@ When building paginated REST endpoints:
197203
> `QueryBuilder.distinct()` is gone with it. Group by the fields instead: each
198204
> unique combination becomes one result row.
199205
206+
<!-- os:check -->
200207
```typescript
208+
import type { IDataEngine } from '@objectstack/spec/contracts';
209+
declare const engine: IDataEngine;
201210
// ✅ groupBy collapses duplicates
202211
const rows = await engine.aggregate('order', {
203212
groupBy: ['customer_id', 'product_category'],

0 commit comments

Comments
 (0)