@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-flows-1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/index.cjs +817 -65
- package/lib/index.js +814 -66
- package/lib/src/ai/AIClient.d.ts +13 -0
- package/lib/src/ai/AIClient.js +15 -0
- package/lib/src/ai/AITypes.d.ts +5 -0
- package/lib/src/index.js +2 -0
- package/lib/src/model/Ad4mModel.d.ts +6 -1
- package/lib/src/model/Ad4mModel.js +41 -6
- package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
- package/lib/src/model/ModelQueryBuilder.js +97 -6
- package/lib/src/model/query-common.d.ts +10 -1
- package/lib/src/model/query-common.js +16 -0
- package/lib/src/model/query-sparql.d.ts +11 -0
- package/lib/src/model/query-sparql.js +93 -1
- package/lib/src/model/query-utils.js +16 -0
- package/lib/src/model/shacl-gen.js +12 -0
- package/lib/src/model/types.d.ts +320 -3
- package/lib/src/model/types.js +9 -0
- package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
- package/lib/src/perspectives/FlowInstance.d.ts +176 -12
- package/lib/src/perspectives/FlowInstance.js +77 -13
- package/lib/src/perspectives/FlowModels.d.ts +40 -9
- package/lib/src/perspectives/FlowModels.js +59 -13
- package/lib/src/perspectives/PerspectiveClient.d.ts +18 -0
- package/lib/src/perspectives/PerspectiveClient.js +30 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +69 -2
- package/lib/src/perspectives/PerspectiveProxy.js +157 -7
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
- package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
- package/lib/src/shacl/SHACLFlow.d.ts +43 -0
- package/package.json +1 -1
- package/src/ai/AIClient.ts +16 -0
- package/src/ai/AITypes.ts +5 -0
- package/src/index.ts +2 -0
- package/src/model/Ad4mModel.test.ts +442 -0
- package/src/model/Ad4mModel.ts +39 -7
- package/src/model/ModelQueryBuilder.ts +101 -10
- package/src/model/query-common.ts +20 -1
- package/src/model/query-sparql.test.ts +115 -0
- package/src/model/query-sparql.ts +97 -1
- package/src/model/query-utils.ts +18 -0
- package/src/model/relation-filtering.test.ts +7 -0
- package/src/model/shacl-gen.ts +12 -0
- package/src/model/shacl-roundtrip.test.ts +71 -0
- package/src/model/types-typed-query.test.ts +42 -0
- package/src/model/types.ts +316 -6
- package/src/perspectives/AutoProcessor.ts +8 -0
- package/src/perspectives/FlowInstance.ts +194 -13
- package/src/perspectives/FlowModels.ts +53 -13
- package/src/perspectives/PerspectiveClient.ts +62 -0
- package/src/perspectives/PerspectiveProxy.test.ts +272 -0
- package/src/perspectives/PerspectiveProxy.ts +163 -7
- package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
- package/src/perspectives/WakerSubscriptionManager.ts +197 -9
- package/src/shacl/SHACLFlow.ts +44 -0
package/src/model/types.ts
CHANGED
|
@@ -10,12 +10,22 @@
|
|
|
10
10
|
// Forward type-only reference to Ad4mModel (no runtime circular dependency)
|
|
11
11
|
// ---------------------------------------------------------------------------
|
|
12
12
|
import type { Ad4mModel } from "./Ad4mModel";
|
|
13
|
+
import type { LinkStatus } from "../perspectives/PerspectiveProxy";
|
|
13
14
|
import type { NodeExpression } from "../shacl/NodeExpression";
|
|
14
15
|
|
|
15
16
|
// ---------------------------------------------------------------------------
|
|
16
17
|
// Query DSL types
|
|
17
18
|
// ---------------------------------------------------------------------------
|
|
18
19
|
|
|
20
|
+
/**
|
|
21
|
+
* Who wrote a link: a DID, any of several DIDs, or `{ not }` / `{ contains }`
|
|
22
|
+
* over the author DID.
|
|
23
|
+
*/
|
|
24
|
+
export type AuthorCondition =
|
|
25
|
+
| string
|
|
26
|
+
| string[]
|
|
27
|
+
| { not?: string | string[]; contains?: string };
|
|
28
|
+
|
|
19
29
|
export type WhereOps = {
|
|
20
30
|
not: string | number | boolean | string[] | number[];
|
|
21
31
|
between: [number, number];
|
|
@@ -24,6 +34,16 @@ export type WhereOps = {
|
|
|
24
34
|
gt: number; // greater than
|
|
25
35
|
gte: number; // greater than or equal to
|
|
26
36
|
contains: string | number; // substring/element check
|
|
37
|
+
/** Equality as an operator: `{ eq: X }` is the bare value `X` (an array
|
|
38
|
+
* means any of). It lets a value sit beside `author`, and cannot be
|
|
39
|
+
* combined with the other value operators. */
|
|
40
|
+
eq: string | number | boolean | string[] | number[];
|
|
41
|
+
/** Per-link author: the link that satisfies this property's condition was
|
|
42
|
+
* written by this author, e.g. `{ agent: { eq: did, author: admin } }`.
|
|
43
|
+
* Alone, `{ agent: { author: admin } }`: admin wrote some `agent` link.
|
|
44
|
+
* Only on properties and relations stored as links (not getters,
|
|
45
|
+
* `timestamp` or `id`). See "Filtering by Author" in the model-classes guide. */
|
|
46
|
+
author: AuthorCondition;
|
|
27
47
|
};
|
|
28
48
|
export type WhereCondition =
|
|
29
49
|
| string
|
|
@@ -42,8 +62,23 @@ export type Where = {
|
|
|
42
62
|
AND?: Where[];
|
|
43
63
|
/** Logical NOT: instance must NOT satisfy the given sub-clause. */
|
|
44
64
|
NOT?: Where;
|
|
65
|
+
/**
|
|
66
|
+
* Only instances that are valid outputs of a completed run of `flow`
|
|
67
|
+
* (optionally: of a run settled into terminal state `state`).
|
|
68
|
+
*
|
|
69
|
+
* Decided executor-side by cryptographic receipt verification, not by a
|
|
70
|
+
* property: an instance passes only when a verified receipt of the flow
|
|
71
|
+
* names it among the outputs its quorum committed to AND its live content
|
|
72
|
+
* still matches that commitment. Fail-closed — a forged, unverifiable or
|
|
73
|
+
* stale receipt excludes the instance — and applied BEFORE `limit`/
|
|
74
|
+
* `offset`, so a page of N is N valid outputs. Only supported as a
|
|
75
|
+
* top-level key on the queried class; anywhere else the query errors.
|
|
76
|
+
*/
|
|
77
|
+
producedByFlow?: ProducedByFlowFilter;
|
|
45
78
|
[propertyName: string]: WhereCondition | undefined;
|
|
46
79
|
};
|
|
80
|
+
/** The `where.producedByFlow` filter — see {@link Where.producedByFlow}. */
|
|
81
|
+
export type ProducedByFlowFilter = { flow: string; state?: string };
|
|
47
82
|
export type Order = { [propertyName: string]: "ASC" | "DESC" };
|
|
48
83
|
|
|
49
84
|
/**
|
|
@@ -64,10 +99,137 @@ export type Order = { [propertyName: string]: "ASC" | "DESC" };
|
|
|
64
99
|
* predicate to write.
|
|
65
100
|
*
|
|
66
101
|
* **Raw form** — explicit predicate string, no metadata lookup.
|
|
102
|
+
*
|
|
103
|
+
* **Traverse form** — bounded traversal from one or more anchors, for reading
|
|
104
|
+
* a tree rather than one node's children. Read-only: AutoProcessor's write
|
|
105
|
+
* scopes reject it, because it names no single parent to write under.
|
|
67
106
|
*/
|
|
68
107
|
export type Scope =
|
|
69
108
|
| { model: typeof Ad4mModel; id: string; field?: string }
|
|
70
|
-
| { id: string; predicate: string }
|
|
109
|
+
| { id: string; predicate: string }
|
|
110
|
+
| TraverseScope;
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Walk a predicate from several anchors at once, and optionally all the way
|
|
114
|
+
* down.
|
|
115
|
+
*
|
|
116
|
+
* This exists because a tree read one level at a time costs a round trip per
|
|
117
|
+
* level and — under a subscription — one subscription per *parent*. Asking for
|
|
118
|
+
* every anchor in one query makes both proportional to depth instead.
|
|
119
|
+
*
|
|
120
|
+
* The predicate is named the same two ways the other scopes name it: literally,
|
|
121
|
+
* or by the model and relation that own it. See {@link TraverseByPredicate} and
|
|
122
|
+
* {@link TraverseByModel}.
|
|
123
|
+
*/
|
|
124
|
+
export type TraverseScope = TraverseByPredicate | TraverseByModel;
|
|
125
|
+
|
|
126
|
+
/** A traversal naming its predicate literally, as the Raw scope does. */
|
|
127
|
+
export interface TraverseByPredicate extends TraverseOptions {
|
|
128
|
+
predicate: string;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* A traversal naming its predicate through the model that declares it, as the
|
|
133
|
+
* Model scope does — `{ model: Post, field: 'comments' }` rather than
|
|
134
|
+
* `'test://has_comment'`.
|
|
135
|
+
*
|
|
136
|
+
* Without `field` the predicate is resolved by scanning for a relation on
|
|
137
|
+
* `model` whose target is the queried class, which is the same rule the Model
|
|
138
|
+
* scope uses and the same reason to pass `field` when a parent has more than
|
|
139
|
+
* one relation to the same child.
|
|
140
|
+
*/
|
|
141
|
+
export interface TraverseByModel extends TraverseOptions {
|
|
142
|
+
model: typeof Ad4mModel;
|
|
143
|
+
field?: string;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** Everything a traversal says that is not how it names its predicate. */
|
|
147
|
+
export interface TraverseOptions {
|
|
148
|
+
/** The anchors to walk from. A bare string is the single-anchor spelling. */
|
|
149
|
+
ids: string | string[];
|
|
150
|
+
/**
|
|
151
|
+
* Follow the predicate as far as it goes rather than one step.
|
|
152
|
+
*
|
|
153
|
+
* The result is a flat set of everything reachable, and it does **not**
|
|
154
|
+
* describe the shape it came from: SPARQL property paths bind no intermediate
|
|
155
|
+
* variables, so a row says that it is under the anchor and never where. To
|
|
156
|
+
* rebuild a tree, read the inverse relation (`@BelongsToOne`) alongside it and
|
|
157
|
+
* assemble from the parent each row reports.
|
|
158
|
+
*
|
|
159
|
+
* Excludes every named anchor, not just the one a given row was reached through — a caller
|
|
160
|
+
* naming two anchors where one sits below the other gets neither back, exactly as with `levels`.
|
|
161
|
+
* An anchor is where the read started, not something it found, and that holds in a cycle too.
|
|
162
|
+
*
|
|
163
|
+
* Refused alongside `levels`, which is the bounded form of the same walk.
|
|
164
|
+
*/
|
|
165
|
+
transitive?: boolean;
|
|
166
|
+
/**
|
|
167
|
+
* `'out'` (default) matches `anchor --predicate--> result`; `'in'` matches
|
|
168
|
+
* `result --predicate--> anchor`, which is how to *search* among the things
|
|
169
|
+
* pointing at a node — ordered, filtered, limited. A reverse `include`
|
|
170
|
+
* answers the same question for rows already in hand, but cannot narrow them.
|
|
171
|
+
*/
|
|
172
|
+
direction?: 'out' | 'in';
|
|
173
|
+
/**
|
|
174
|
+
* Keep at most this many results per anchor — "the top 5 replies under each
|
|
175
|
+
* of these 20 comments" in one query.
|
|
176
|
+
*
|
|
177
|
+
* Applied by the executor between selecting ids and hydrating them, because
|
|
178
|
+
* SPARQL has no per-group limit (no window functions, and sub-SELECTs are
|
|
179
|
+
* uncorrelated). The practical consequence is that the over-fetch is paid in
|
|
180
|
+
* ids, not records: a branch with 3,000 replies costs 3,000 strings and
|
|
181
|
+
* hydrates 5.
|
|
182
|
+
*
|
|
183
|
+
* Pair it with `order` — without one the "top" N is whatever the store
|
|
184
|
+
* happened to return first. A global `limit`/`offset` is applied to the
|
|
185
|
+
* sliced union afterwards, not before it.
|
|
186
|
+
*
|
|
187
|
+
* Refused alongside `levels`, which applies its own per-anchor limit at
|
|
188
|
+
* every depth.
|
|
189
|
+
*/
|
|
190
|
+
limitPerAnchor?: number;
|
|
191
|
+
/**
|
|
192
|
+
* Walk the relation level by level, keeping this many results per anchor at each depth —
|
|
193
|
+
* `[10, 5, 3]` is "ten replies, five under each of those, three under each of *those*".
|
|
194
|
+
*
|
|
195
|
+
* The walk happens in the executor, which is the point of it. A caller can drive the same walk by
|
|
196
|
+
* asking for one level and using the ids as the next level's anchors, but each step is then a
|
|
197
|
+
* network round trip, and a UI that draws as each answer lands shows the tree assembling itself a
|
|
198
|
+
* level at a time. Inside the executor the levels are sequential queries against a local store
|
|
199
|
+
* with nothing serialised between them, and the records are hydrated once for the union — so
|
|
200
|
+
* three levels cost one request and one hydration rather than three of each.
|
|
201
|
+
*
|
|
202
|
+
* Results come back flat and breadth-first; read the inverse relation alongside to rebuild the
|
|
203
|
+
* tree, exactly as with `transitive`. The anchors are excluded from their own result, also as
|
|
204
|
+
* with `transitive` — a walk that reaches an anchor again, through a cycle or because one anchor
|
|
205
|
+
* was named below another, reports it at neither place.
|
|
206
|
+
*
|
|
207
|
+
* Each record appears once, under whichever anchor the ordering reaches first — a reply to two
|
|
208
|
+
* of the anchors is one reply, not two. It does not spend a place in the other anchors' breadth
|
|
209
|
+
* either: they fill theirs with replies of their own, so a breadth of five means five distinct
|
|
210
|
+
* records wherever five exist.
|
|
211
|
+
*
|
|
212
|
+
* A global `limit`/`offset` applies to that flat union once, after every level has been cut to
|
|
213
|
+
* its own breadth — not to each level.
|
|
214
|
+
*
|
|
215
|
+
* Combining this with `transitive` or `limitPerAnchor` is an **error**, not a preference the
|
|
216
|
+
* executor resolves: `transitive` is the unbounded form of the same walk, and `limitPerAnchor`
|
|
217
|
+
* has no place to act when the walk sets a per-anchor limit at every depth itself. (It is not a
|
|
218
|
+
* substitute either — with a single anchor at the top there is one group, so it caps the total
|
|
219
|
+
* rather than the breadth at each level.) Put the first level's breadth in `levels[0]`.
|
|
220
|
+
*/
|
|
221
|
+
levels?: number[];
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Whether this scope is a traversal rather than a single named parent.
|
|
226
|
+
*
|
|
227
|
+
* The other two forms carry `id`; this one carries `ids` and may name several,
|
|
228
|
+
* so anything reaching for one parent — every write path — has to ask first.
|
|
229
|
+
*/
|
|
230
|
+
export function isTraverseScope(scope: Scope): scope is TraverseScope {
|
|
231
|
+
return 'ids' in scope;
|
|
232
|
+
}
|
|
71
233
|
|
|
72
234
|
/**
|
|
73
235
|
* Describes which relations to eager-load when querying.
|
|
@@ -117,6 +279,20 @@ export interface IncludeProjection {
|
|
|
117
279
|
from: string;
|
|
118
280
|
/** When true, attaches an integer count instead of a list. */
|
|
119
281
|
count?: true;
|
|
282
|
+
/**
|
|
283
|
+
* Project over everything reachable through `from`, not just one step.
|
|
284
|
+
*
|
|
285
|
+
* `{ from: 'comments', count: true, transitive: true }` is the whole
|
|
286
|
+
* conversation under each row rather than its direct replies — which is what
|
|
287
|
+
* a reader takes "42 replies" on a collapsed branch to mean. The projection
|
|
288
|
+
* query is already grouped per parent and already asked of every row at once,
|
|
289
|
+
* so this adds no round trip.
|
|
290
|
+
*
|
|
291
|
+
* Cannot be combined with a filter on the link's author or timestamp: those
|
|
292
|
+
* read the reification of one link, and a path has none. Such a projection is
|
|
293
|
+
* skipped with a warning rather than silently answering a different question.
|
|
294
|
+
*/
|
|
295
|
+
transitive?: boolean;
|
|
120
296
|
/**
|
|
121
297
|
* Bare class name of the projection target. Set automatically by
|
|
122
298
|
* `prepareModelQueryParams`; the executor resolves the target's shape
|
|
@@ -163,8 +339,110 @@ export type Query = {
|
|
|
163
339
|
* queries where getter-backed properties are not needed.
|
|
164
340
|
*/
|
|
165
341
|
deepQuery?: boolean;
|
|
342
|
+
/**
|
|
343
|
+
* Read instances as they exist in links of one status only.
|
|
344
|
+
*
|
|
345
|
+
* `'shared'` hydrates from Shared links only: every property, relation,
|
|
346
|
+
* `author` and `updatedAt` comes from links that are gossiped to the
|
|
347
|
+
* neighbourhood, and none from this executor's Local links. That is the
|
|
348
|
+
* read to use when showing data to another user (#1024). `'local'` is the
|
|
349
|
+
* converse. Unset or `null` (the default) reads both, and a property
|
|
350
|
+
* declared `local: true` still reads only its Local links.
|
|
351
|
+
*
|
|
352
|
+
* Relations include typed `@HasMany` / `@HasOne` relations, which are filled
|
|
353
|
+
* by the conformance getter the SDK generates: the executor adds the status
|
|
354
|
+
* check to that getter's relation link. A hand-written `getter` is run as
|
|
355
|
+
* written, so it reads links of any status unless it checks
|
|
356
|
+
* `<ad4m://ontology/status>` itself.
|
|
357
|
+
*
|
|
358
|
+
* Included relations and the instances a `$` projection hydrates inherit
|
|
359
|
+
* the setting, unless an include's sub-query sets its own. The `__links`
|
|
360
|
+
* rows (see {@link Query.links}) are restricted the same way.
|
|
361
|
+
*
|
|
362
|
+
* Combines with {@link Query.includeUnverified}: a link must have the
|
|
363
|
+
* requested status **and** pass the signature check, both on the same link.
|
|
364
|
+
* So a Local link whose signature did not verify is withheld under
|
|
365
|
+
* `linkStatus: 'local'` too, and comes back only with
|
|
366
|
+
* `linkStatus: 'local', includeUnverified: true` (or with no `linkStatus`
|
|
367
|
+
* and `includeUnverified: true`).
|
|
368
|
+
*
|
|
369
|
+
* Scope: this restricts the links that hydrate an instance and the links
|
|
370
|
+
* that *select* it (`where`, the class's flags, `count`/`totalCount`, `$`
|
|
371
|
+
* projections, `parent` scopes and the order behind `limit`/`offset`). So an
|
|
372
|
+
* instance is returned under `'local'` only when it is flagged in a Local
|
|
373
|
+
* link, and under `'shared'` only when it is flagged in a Shared one.
|
|
374
|
+
*/
|
|
375
|
+
linkStatus?: LinkStatus;
|
|
376
|
+
/**
|
|
377
|
+
* Also hydrate from links whose signature did not verify.
|
|
378
|
+
*
|
|
379
|
+
* By default the executor withholds every link whose stored signature
|
|
380
|
+
* verdict is not valid, so a forged or tampered link never becomes a
|
|
381
|
+
* property value, a relation target, `author` or `updatedAt`. That
|
|
382
|
+
* includes a typed relation's generated conformance getter. A `getter` you
|
|
383
|
+
* write yourself runs as written, so it reads unverified links unless it
|
|
384
|
+
* joins the link's `ad4m://ontology/proofValid` itself. Set this to
|
|
385
|
+
* `true` only to *display* an unverified claim, e.g. a UI that marks a value
|
|
386
|
+
* as unverified. Anything that acts on the data, such as a vote counter or a
|
|
387
|
+
* role check, must leave it off.
|
|
388
|
+
*
|
|
389
|
+
* Included relations inherit the setting unless their sub-query sets its own.
|
|
390
|
+
*
|
|
391
|
+
* The same applies to the rows under `__links` and to what *selects* an
|
|
392
|
+
* instance: `where` (including a per-link `author`), the class's flags,
|
|
393
|
+
* `count`/`totalCount`, the order behind `limit`/`offset`, `parent` scopes
|
|
394
|
+
* and `$` projections, `transitive` ones included. With `true`, selection
|
|
395
|
+
* reads unverified links too.
|
|
396
|
+
*/
|
|
397
|
+
includeUnverified?: boolean;
|
|
398
|
+
/**
|
|
399
|
+
* Return the individual links behind each instance, with their own author,
|
|
400
|
+
* timestamp, signature and signature verdict, under `instance.__links`. For
|
|
401
|
+
* a collection this is per-item provenance: who added each member, when, and
|
|
402
|
+
* whether their signature holds.
|
|
403
|
+
*
|
|
404
|
+
* Each entry is a property or relation name the model declares, or an
|
|
405
|
+
* absolute predicate IRI — including one the model does **not** declare
|
|
406
|
+
* (an annotation such as a revocation tombstone). A name wins over the IRI
|
|
407
|
+
* reading. Every requested entry is present on every instance, as `[]` when
|
|
408
|
+
* it has no such link. An entry that is neither a declared name nor an IRI,
|
|
409
|
+
* or that names a reverse relation (`@BelongsToOne` / `@BelongsToMany`),
|
|
410
|
+
* makes the query fail rather than answer `[]`.
|
|
411
|
+
*
|
|
412
|
+
* The rows are read by a second query after the instances are hydrated, so
|
|
413
|
+
* asking for them never changes `createdAt`, `updatedAt` or any property.
|
|
414
|
+
* See {@link LinkRow}.
|
|
415
|
+
*/
|
|
416
|
+
links?: string[];
|
|
166
417
|
};
|
|
167
418
|
|
|
419
|
+
/**
|
|
420
|
+
* One stored link as returned under `__links` — the same shape as the
|
|
421
|
+
* `LinkExpression` `perspective.get()` returns, including the signature
|
|
422
|
+
* verdict the executor recorded when the link was stored.
|
|
423
|
+
*
|
|
424
|
+
* `proof.valid` is `true` only when the signature verifies against `author`.
|
|
425
|
+
* A link stored without a proof arrives with `key` and `signature` set to
|
|
426
|
+
* `""` and `valid: false`; that is an unverifiable link, not a valid unsigned
|
|
427
|
+
* one. Anything that acts on a row (counting a vote, granting a role) should
|
|
428
|
+
* require `proof.valid`.
|
|
429
|
+
*
|
|
430
|
+
* `valid` is never `null` here and `invalid` is always `!valid`, the same
|
|
431
|
+
* convention as `perspective.get()`. So `invalid: true` does not by itself mean
|
|
432
|
+
* a signature failed: it also covers a link with no proof, or with no recorded
|
|
433
|
+
* verdict. To tell an unsigned link from a failed signature, check whether
|
|
434
|
+
* `proof.signature` is `""`.
|
|
435
|
+
*/
|
|
436
|
+
export interface LinkRow {
|
|
437
|
+
author: string;
|
|
438
|
+
timestamp: string;
|
|
439
|
+
data: { source: string; predicate: string; target: string };
|
|
440
|
+
proof: { key: string; signature: string; valid: boolean; invalid: boolean };
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/** `instance.__links`: requested entry (spelled as requested) → its rows, oldest first. */
|
|
444
|
+
export type LinksMap = Record<string, LinkRow[]>;
|
|
445
|
+
|
|
168
446
|
/**
|
|
169
447
|
* Sub-query options for a specific relation inside an `IncludeMap`.
|
|
170
448
|
*
|
|
@@ -244,6 +522,10 @@ type HasNoTypedFields<T extends Ad4mModel> =
|
|
|
244
522
|
export type StringWhereOps = {
|
|
245
523
|
not?: string | string[];
|
|
246
524
|
contains?: string;
|
|
525
|
+
/** See {@link WhereOps.eq}. */
|
|
526
|
+
eq?: string | string[];
|
|
527
|
+
/** See {@link WhereOps.author}. */
|
|
528
|
+
author?: AuthorCondition;
|
|
247
529
|
};
|
|
248
530
|
|
|
249
531
|
export type NumericWhereOps = {
|
|
@@ -253,12 +535,16 @@ export type NumericWhereOps = {
|
|
|
253
535
|
gt?: number;
|
|
254
536
|
gte?: number;
|
|
255
537
|
between?: [number, number];
|
|
538
|
+
/** See {@link WhereOps.eq}. */
|
|
539
|
+
eq?: number | number[];
|
|
540
|
+
/** See {@link WhereOps.author}. */
|
|
541
|
+
author?: AuthorCondition;
|
|
256
542
|
};
|
|
257
543
|
|
|
258
544
|
export type TypedWhereCondition<V> =
|
|
259
545
|
V extends string ? string | string[] | StringWhereOps
|
|
260
546
|
: V extends number ? number | number[] | NumericWhereOps
|
|
261
|
-
: V extends boolean ? boolean
|
|
547
|
+
: V extends boolean ? boolean | { eq?: boolean; author?: AuthorCondition }
|
|
262
548
|
: V extends Array<infer U>
|
|
263
549
|
? U extends string ? string | string[] | StringWhereOps
|
|
264
550
|
: U extends number ? number | number[] | NumericWhereOps
|
|
@@ -272,6 +558,13 @@ type StrictTypedWhere<T extends Ad4mModel> =
|
|
|
272
558
|
& {
|
|
273
559
|
base?: string | string[];
|
|
274
560
|
id?: string | string[];
|
|
561
|
+
/** Alone: the instance's `.author`, i.e. its earliest link's author.
|
|
562
|
+
* Beside property/relation conditions in the same object: that, AND
|
|
563
|
+
* each of those conditions is satisfied by a link this author wrote.
|
|
564
|
+
* For "this author wrote the `agent` link" alone, nest it:
|
|
565
|
+
* `{ agent: { eq: did, author } }`. It does not reach into
|
|
566
|
+
* `OR`/`AND`/`NOT` sub-clauses. See "Filtering by Author" in the
|
|
567
|
+
* model-classes guide. */
|
|
275
568
|
author?: WhereCondition;
|
|
276
569
|
timestamp?: WhereCondition;
|
|
277
570
|
OR?: StrictTypedWhere<T>[];
|
|
@@ -284,6 +577,13 @@ type StrictTypedWhere<T extends Ad4mModel> =
|
|
|
284
577
|
export type TypedWhere<T extends Ad4mModel> =
|
|
285
578
|
HasNoTypedFields<T> extends true ? Where : StrictTypedWhere<T>;
|
|
286
579
|
|
|
580
|
+
/** Top-level typed `where` of a query on T: {@link TypedWhere} plus
|
|
581
|
+
* `producedByFlow`. Kept out of `TypedWhere` itself because that shape is
|
|
582
|
+
* reused under `OR`/`AND`/`NOT` and in include sub-queries, where the
|
|
583
|
+
* executor rejects `producedByFlow` (see {@link Where.producedByFlow}). */
|
|
584
|
+
export type TypedQueryWhere<T extends Ad4mModel> =
|
|
585
|
+
TypedWhere<T> & { producedByFlow?: ProducedByFlowFilter };
|
|
586
|
+
|
|
287
587
|
// ---- Typed order -------------------------------------------------------------
|
|
288
588
|
|
|
289
589
|
type StrictTypedOrder<T extends Ad4mModel> =
|
|
@@ -304,6 +604,11 @@ export type TypedRelationSubQuery<U extends Ad4mModel> = {
|
|
|
304
604
|
include?: TypedIncludeMap<U>;
|
|
305
605
|
limit?: number;
|
|
306
606
|
offset?: number;
|
|
607
|
+
/** See {@link Query.linkStatus}. Inherited from the parent query when unset. */
|
|
608
|
+
linkStatus?: LinkStatus;
|
|
609
|
+
/** See {@link Query.includeUnverified}. Inherited from the parent query when unset. */
|
|
610
|
+
includeUnverified?: boolean;
|
|
611
|
+
links?: string[];
|
|
307
612
|
};
|
|
308
613
|
|
|
309
614
|
/** Projection — `from` must be a real relation on T; `where`/`order` constrained to that target.
|
|
@@ -311,9 +616,9 @@ export type TypedRelationSubQuery<U extends Ad4mModel> = {
|
|
|
311
616
|
* variants narrow inference into `IncludeExtras` (count → number, limit-1 → scalar). */
|
|
312
617
|
export type TypedIncludeProjection<T extends Ad4mModel> = {
|
|
313
618
|
[K in RelationKeysOf<T>]:
|
|
314
|
-
| { from: K; count: true }
|
|
315
|
-
| { from: K; limit: 1; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> }
|
|
316
|
-
| { from: K; limit?: number; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> };
|
|
619
|
+
| { from: K; count: true; transitive?: boolean }
|
|
620
|
+
| { from: K; limit: 1; transitive?: boolean; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> }
|
|
621
|
+
| { from: K; limit?: number; transitive?: boolean; where?: TypedWhere<RelatedModel<T, K>>; order?: TypedOrder<RelatedModel<T, K>> };
|
|
317
622
|
}[RelationKeysOf<T>];
|
|
318
623
|
|
|
319
624
|
type StrictTypedIncludeMap<T extends Ad4mModel> =
|
|
@@ -359,12 +664,17 @@ type StrictTypedQuery<T extends Ad4mModel> = {
|
|
|
359
664
|
properties?: PropertyKeysOf<T>[];
|
|
360
665
|
include?: TypedIncludeMap<T>;
|
|
361
666
|
includeAll?: boolean;
|
|
362
|
-
where?:
|
|
667
|
+
where?: TypedQueryWhere<T>;
|
|
363
668
|
order?: TypedOrder<T>;
|
|
364
669
|
offset?: number;
|
|
365
670
|
limit?: number;
|
|
366
671
|
count?: boolean;
|
|
367
672
|
deepQuery?: boolean;
|
|
673
|
+
/** See {@link Query.linkStatus}. */
|
|
674
|
+
linkStatus?: LinkStatus;
|
|
675
|
+
/** See {@link Query.includeUnverified}. */
|
|
676
|
+
includeUnverified?: boolean;
|
|
677
|
+
links?: string[];
|
|
368
678
|
};
|
|
369
679
|
|
|
370
680
|
export type TypedQuery<T extends Ad4mModel> =
|
|
@@ -244,6 +244,14 @@ export interface AddAutoProcessorConfig {
|
|
|
244
244
|
basePrefix?: string;
|
|
245
245
|
/** Class URIs (SHACL `target_class`) to materialize each pass. */
|
|
246
246
|
interpretationClasses: string[];
|
|
247
|
+
/**
|
|
248
|
+
* Canonical flow URIs (`SHACLFlow` `{namespace}{name}Flow`) this processor
|
|
249
|
+
* is flow-aware of. Flow features — the flow-aware prompt, the
|
|
250
|
+
* transition-proposal pass, and auto-spawn on freshly created items — run
|
|
251
|
+
* only on the flows listed here, mirroring the class selection above.
|
|
252
|
+
* Omit (or pass `[]`) for no flow processing.
|
|
253
|
+
*/
|
|
254
|
+
flows?: string[];
|
|
247
255
|
/** Quiet-window (ms) after the last new item before a pass runs. */
|
|
248
256
|
debounceMs: number;
|
|
249
257
|
/** Minimum items before a pass runs (Flux "wait for N inputs"). Default 1. */
|