Skip to content

Commit a090992

Browse files
committed
docs: restore the trailing options arg on IDataEngine reads (#4486)
The `IDataEngine` block in data-engine.mdx wrote all four read methods with two parameters, dropping the trailing `options?: BaseEngineOptions` that the real contract gives each of them (packages/spec/src/contracts/data-engine.ts :70/85/89/90). The write methods in the same block each carried their own `options`, so the block taught exactly the wrong model -- "writes take options, reads do not" -- and that is the misconception #4251 existed to fix. The parameter is not incidental: the same `{ context }` object is correct as insert's 3rd argument but was SILENTLY DROPPED as find's, so an intended `isSystem` bypass vanished and control-plane reads came back empty once org-scoping hooks landed. Anyone -- human or agent -- writing code from this block was being led back to the pre-#4251 shape, against a failure mode that raises no error. Adds `BaseEngineOptions` to the block's import list (the contract imports it from the same module), and a callout recording the precedence the contract states: `query.context` remains supported, and when both are given `options.context` wins. `content/docs/kernel/contracts/` is hand-written -- only `content/docs/ references/` is generated -- so no generator run is involved. Fixes #4486
1 parent f4d8990 commit a090992

1 file changed

Lines changed: 21 additions & 5 deletions

File tree

content/docs/kernel/contracts/data-engine.mdx

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ The canonical `IDataEngine` interface uses **QueryAST-aligned parameter names**
2121

2222
```typescript
2323
import type {
24+
BaseEngineOptions,
2425
EngineQueryOptions,
2526
DataEngineInsertOptions,
2627
EngineUpdateOptions,
@@ -31,11 +32,12 @@ import type {
3132
} from '@objectstack/spec/data';
3233

3334
export interface IDataEngine {
34-
// Query
35-
find(objectName: string, query?: EngineQueryOptions): Promise<any[]>;
36-
findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
37-
count(objectName: string, query?: EngineCountOptions): Promise<number>;
38-
aggregate(objectName: string, query: EngineAggregateOptions): Promise<any[]>;
35+
// Query (reads take the execution context in a TRAILING options argument —
36+
// the same position the write methods take theirs)
37+
find(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any[]>;
38+
findOne(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any>;
39+
count(objectName: string, query?: EngineCountOptions, options?: BaseEngineOptions): Promise<number>;
40+
aggregate(objectName: string, query: EngineAggregateOptions, options?: BaseEngineOptions): Promise<any[]>;
3941

4042
// Mutation (write ops also accept in-process WriteObservabilityOptions — see `update`)
4143
insert(objectName: string, data: any | any[], options?: DataEngineInsertOptions & WriteObservabilityOptions): Promise<any>;
@@ -65,6 +67,20 @@ export interface IDataEngine {
6567

6668
All query methods use canonical **QueryAST parameter names**: `where`, `fields`, `orderBy`, `limit`, `offset`, `expand`.
6769

70+
<Callout type="warn">
71+
**Reads take the execution context in the trailing `options` argument**, the same
72+
position the write methods take theirs — `find`, `findOne`, `count` and `aggregate`
73+
all accept `options?: BaseEngineOptions`.
74+
75+
This matters because the mistake it prevents is silent. The same `{ context }` object
76+
is correct as the third argument to `insert`, and passing it as the third argument to
77+
`find` used to be **dropped without error** — so an intended `isSystem` bypass simply
78+
vanished, and control-plane reads started coming back empty once org-scoping hooks
79+
landed (#4251).
80+
81+
`query.context` remains supported. When **both** are given, `options.context` wins.
82+
</Callout>
83+
6884
### find
6985

7086
Executes a structured query with filtering, sorting, pagination, and field selection. Returns an array of records.

0 commit comments

Comments
 (0)