@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/lib/src/model/types.d.ts
CHANGED
|
@@ -6,7 +6,16 @@
|
|
|
6
6
|
* creating circular runtime dependencies on `Ad4mModel.ts`.
|
|
7
7
|
*/
|
|
8
8
|
import type { Ad4mModel } from "./Ad4mModel";
|
|
9
|
+
import type { LinkStatus } from "../perspectives/PerspectiveProxy";
|
|
9
10
|
import type { NodeExpression } from "../shacl/NodeExpression";
|
|
11
|
+
/**
|
|
12
|
+
* Who wrote a link: a DID, any of several DIDs, or `{ not }` / `{ contains }`
|
|
13
|
+
* over the author DID.
|
|
14
|
+
*/
|
|
15
|
+
export type AuthorCondition = string | string[] | {
|
|
16
|
+
not?: string | string[];
|
|
17
|
+
contains?: string;
|
|
18
|
+
};
|
|
10
19
|
export type WhereOps = {
|
|
11
20
|
not: string | number | boolean | string[] | number[];
|
|
12
21
|
between: [number, number];
|
|
@@ -15,6 +24,16 @@ export type WhereOps = {
|
|
|
15
24
|
gt: number;
|
|
16
25
|
gte: number;
|
|
17
26
|
contains: string | number;
|
|
27
|
+
/** Equality as an operator: `{ eq: X }` is the bare value `X` (an array
|
|
28
|
+
* means any of). It lets a value sit beside `author`, and cannot be
|
|
29
|
+
* combined with the other value operators. */
|
|
30
|
+
eq: string | number | boolean | string[] | number[];
|
|
31
|
+
/** Per-link author: the link that satisfies this property's condition was
|
|
32
|
+
* written by this author, e.g. `{ agent: { eq: did, author: admin } }`.
|
|
33
|
+
* Alone, `{ agent: { author: admin } }`: admin wrote some `agent` link.
|
|
34
|
+
* Only on properties and relations stored as links (not getters,
|
|
35
|
+
* `timestamp` or `id`). See "Filtering by Author" in the model-classes guide. */
|
|
36
|
+
author: AuthorCondition;
|
|
18
37
|
};
|
|
19
38
|
export type WhereCondition = string | number | boolean | string[] | number[] | {
|
|
20
39
|
[K in keyof WhereOps]?: WhereOps[K];
|
|
@@ -26,8 +45,26 @@ export type Where = {
|
|
|
26
45
|
AND?: Where[];
|
|
27
46
|
/** Logical NOT: instance must NOT satisfy the given sub-clause. */
|
|
28
47
|
NOT?: Where;
|
|
48
|
+
/**
|
|
49
|
+
* Only instances that are valid outputs of a completed run of `flow`
|
|
50
|
+
* (optionally: of a run settled into terminal state `state`).
|
|
51
|
+
*
|
|
52
|
+
* Decided executor-side by cryptographic receipt verification, not by a
|
|
53
|
+
* property: an instance passes only when a verified receipt of the flow
|
|
54
|
+
* names it among the outputs its quorum committed to AND its live content
|
|
55
|
+
* still matches that commitment. Fail-closed — a forged, unverifiable or
|
|
56
|
+
* stale receipt excludes the instance — and applied BEFORE `limit`/
|
|
57
|
+
* `offset`, so a page of N is N valid outputs. Only supported as a
|
|
58
|
+
* top-level key on the queried class; anywhere else the query errors.
|
|
59
|
+
*/
|
|
60
|
+
producedByFlow?: ProducedByFlowFilter;
|
|
29
61
|
[propertyName: string]: WhereCondition | undefined;
|
|
30
62
|
};
|
|
63
|
+
/** The `where.producedByFlow` filter — see {@link Where.producedByFlow}. */
|
|
64
|
+
export type ProducedByFlowFilter = {
|
|
65
|
+
flow: string;
|
|
66
|
+
state?: string;
|
|
67
|
+
};
|
|
31
68
|
export type Order = {
|
|
32
69
|
[propertyName: string]: "ASC" | "DESC";
|
|
33
70
|
};
|
|
@@ -49,6 +86,10 @@ export type Order = {
|
|
|
49
86
|
* predicate to write.
|
|
50
87
|
*
|
|
51
88
|
* **Raw form** — explicit predicate string, no metadata lookup.
|
|
89
|
+
*
|
|
90
|
+
* **Traverse form** — bounded traversal from one or more anchors, for reading
|
|
91
|
+
* a tree rather than one node's children. Read-only: AutoProcessor's write
|
|
92
|
+
* scopes reject it, because it names no single parent to write under.
|
|
52
93
|
*/
|
|
53
94
|
export type Scope = {
|
|
54
95
|
model: typeof Ad4mModel;
|
|
@@ -57,7 +98,122 @@ export type Scope = {
|
|
|
57
98
|
} | {
|
|
58
99
|
id: string;
|
|
59
100
|
predicate: string;
|
|
60
|
-
};
|
|
101
|
+
} | TraverseScope;
|
|
102
|
+
/**
|
|
103
|
+
* Walk a predicate from several anchors at once, and optionally all the way
|
|
104
|
+
* down.
|
|
105
|
+
*
|
|
106
|
+
* This exists because a tree read one level at a time costs a round trip per
|
|
107
|
+
* level and — under a subscription — one subscription per *parent*. Asking for
|
|
108
|
+
* every anchor in one query makes both proportional to depth instead.
|
|
109
|
+
*
|
|
110
|
+
* The predicate is named the same two ways the other scopes name it: literally,
|
|
111
|
+
* or by the model and relation that own it. See {@link TraverseByPredicate} and
|
|
112
|
+
* {@link TraverseByModel}.
|
|
113
|
+
*/
|
|
114
|
+
export type TraverseScope = TraverseByPredicate | TraverseByModel;
|
|
115
|
+
/** A traversal naming its predicate literally, as the Raw scope does. */
|
|
116
|
+
export interface TraverseByPredicate extends TraverseOptions {
|
|
117
|
+
predicate: string;
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* A traversal naming its predicate through the model that declares it, as the
|
|
121
|
+
* Model scope does — `{ model: Post, field: 'comments' }` rather than
|
|
122
|
+
* `'test://has_comment'`.
|
|
123
|
+
*
|
|
124
|
+
* Without `field` the predicate is resolved by scanning for a relation on
|
|
125
|
+
* `model` whose target is the queried class, which is the same rule the Model
|
|
126
|
+
* scope uses and the same reason to pass `field` when a parent has more than
|
|
127
|
+
* one relation to the same child.
|
|
128
|
+
*/
|
|
129
|
+
export interface TraverseByModel extends TraverseOptions {
|
|
130
|
+
model: typeof Ad4mModel;
|
|
131
|
+
field?: string;
|
|
132
|
+
}
|
|
133
|
+
/** Everything a traversal says that is not how it names its predicate. */
|
|
134
|
+
export interface TraverseOptions {
|
|
135
|
+
/** The anchors to walk from. A bare string is the single-anchor spelling. */
|
|
136
|
+
ids: string | string[];
|
|
137
|
+
/**
|
|
138
|
+
* Follow the predicate as far as it goes rather than one step.
|
|
139
|
+
*
|
|
140
|
+
* The result is a flat set of everything reachable, and it does **not**
|
|
141
|
+
* describe the shape it came from: SPARQL property paths bind no intermediate
|
|
142
|
+
* variables, so a row says that it is under the anchor and never where. To
|
|
143
|
+
* rebuild a tree, read the inverse relation (`@BelongsToOne`) alongside it and
|
|
144
|
+
* assemble from the parent each row reports.
|
|
145
|
+
*
|
|
146
|
+
* Excludes every named anchor, not just the one a given row was reached through — a caller
|
|
147
|
+
* naming two anchors where one sits below the other gets neither back, exactly as with `levels`.
|
|
148
|
+
* An anchor is where the read started, not something it found, and that holds in a cycle too.
|
|
149
|
+
*
|
|
150
|
+
* Refused alongside `levels`, which is the bounded form of the same walk.
|
|
151
|
+
*/
|
|
152
|
+
transitive?: boolean;
|
|
153
|
+
/**
|
|
154
|
+
* `'out'` (default) matches `anchor --predicate--> result`; `'in'` matches
|
|
155
|
+
* `result --predicate--> anchor`, which is how to *search* among the things
|
|
156
|
+
* pointing at a node — ordered, filtered, limited. A reverse `include`
|
|
157
|
+
* answers the same question for rows already in hand, but cannot narrow them.
|
|
158
|
+
*/
|
|
159
|
+
direction?: 'out' | 'in';
|
|
160
|
+
/**
|
|
161
|
+
* Keep at most this many results per anchor — "the top 5 replies under each
|
|
162
|
+
* of these 20 comments" in one query.
|
|
163
|
+
*
|
|
164
|
+
* Applied by the executor between selecting ids and hydrating them, because
|
|
165
|
+
* SPARQL has no per-group limit (no window functions, and sub-SELECTs are
|
|
166
|
+
* uncorrelated). The practical consequence is that the over-fetch is paid in
|
|
167
|
+
* ids, not records: a branch with 3,000 replies costs 3,000 strings and
|
|
168
|
+
* hydrates 5.
|
|
169
|
+
*
|
|
170
|
+
* Pair it with `order` — without one the "top" N is whatever the store
|
|
171
|
+
* happened to return first. A global `limit`/`offset` is applied to the
|
|
172
|
+
* sliced union afterwards, not before it.
|
|
173
|
+
*
|
|
174
|
+
* Refused alongside `levels`, which applies its own per-anchor limit at
|
|
175
|
+
* every depth.
|
|
176
|
+
*/
|
|
177
|
+
limitPerAnchor?: number;
|
|
178
|
+
/**
|
|
179
|
+
* Walk the relation level by level, keeping this many results per anchor at each depth —
|
|
180
|
+
* `[10, 5, 3]` is "ten replies, five under each of those, three under each of *those*".
|
|
181
|
+
*
|
|
182
|
+
* The walk happens in the executor, which is the point of it. A caller can drive the same walk by
|
|
183
|
+
* asking for one level and using the ids as the next level's anchors, but each step is then a
|
|
184
|
+
* network round trip, and a UI that draws as each answer lands shows the tree assembling itself a
|
|
185
|
+
* level at a time. Inside the executor the levels are sequential queries against a local store
|
|
186
|
+
* with nothing serialised between them, and the records are hydrated once for the union — so
|
|
187
|
+
* three levels cost one request and one hydration rather than three of each.
|
|
188
|
+
*
|
|
189
|
+
* Results come back flat and breadth-first; read the inverse relation alongside to rebuild the
|
|
190
|
+
* tree, exactly as with `transitive`. The anchors are excluded from their own result, also as
|
|
191
|
+
* with `transitive` — a walk that reaches an anchor again, through a cycle or because one anchor
|
|
192
|
+
* was named below another, reports it at neither place.
|
|
193
|
+
*
|
|
194
|
+
* Each record appears once, under whichever anchor the ordering reaches first — a reply to two
|
|
195
|
+
* of the anchors is one reply, not two. It does not spend a place in the other anchors' breadth
|
|
196
|
+
* either: they fill theirs with replies of their own, so a breadth of five means five distinct
|
|
197
|
+
* records wherever five exist.
|
|
198
|
+
*
|
|
199
|
+
* A global `limit`/`offset` applies to that flat union once, after every level has been cut to
|
|
200
|
+
* its own breadth — not to each level.
|
|
201
|
+
*
|
|
202
|
+
* Combining this with `transitive` or `limitPerAnchor` is an **error**, not a preference the
|
|
203
|
+
* executor resolves: `transitive` is the unbounded form of the same walk, and `limitPerAnchor`
|
|
204
|
+
* has no place to act when the walk sets a per-anchor limit at every depth itself. (It is not a
|
|
205
|
+
* substitute either — with a single anchor at the top there is one group, so it caps the total
|
|
206
|
+
* rather than the breadth at each level.) Put the first level's breadth in `levels[0]`.
|
|
207
|
+
*/
|
|
208
|
+
levels?: number[];
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* Whether this scope is a traversal rather than a single named parent.
|
|
212
|
+
*
|
|
213
|
+
* The other two forms carry `id`; this one carries `ids` and may name several,
|
|
214
|
+
* so anything reaching for one parent — every write path — has to ask first.
|
|
215
|
+
*/
|
|
216
|
+
export declare function isTraverseScope(scope: Scope): scope is TraverseScope;
|
|
61
217
|
/**
|
|
62
218
|
* Describes which relations to eager-load when querying.
|
|
63
219
|
*
|
|
@@ -105,6 +261,20 @@ export interface IncludeProjection {
|
|
|
105
261
|
from: string;
|
|
106
262
|
/** When true, attaches an integer count instead of a list. */
|
|
107
263
|
count?: true;
|
|
264
|
+
/**
|
|
265
|
+
* Project over everything reachable through `from`, not just one step.
|
|
266
|
+
*
|
|
267
|
+
* `{ from: 'comments', count: true, transitive: true }` is the whole
|
|
268
|
+
* conversation under each row rather than its direct replies — which is what
|
|
269
|
+
* a reader takes "42 replies" on a collapsed branch to mean. The projection
|
|
270
|
+
* query is already grouped per parent and already asked of every row at once,
|
|
271
|
+
* so this adds no round trip.
|
|
272
|
+
*
|
|
273
|
+
* Cannot be combined with a filter on the link's author or timestamp: those
|
|
274
|
+
* read the reification of one link, and a path has none. Such a projection is
|
|
275
|
+
* skipped with a warning rather than silently answering a different question.
|
|
276
|
+
*/
|
|
277
|
+
transitive?: boolean;
|
|
108
278
|
/**
|
|
109
279
|
* Bare class name of the projection target. Set automatically by
|
|
110
280
|
* `prepareModelQueryParams`; the executor resolves the target's shape
|
|
@@ -147,7 +317,116 @@ export type Query = {
|
|
|
147
317
|
* queries where getter-backed properties are not needed.
|
|
148
318
|
*/
|
|
149
319
|
deepQuery?: boolean;
|
|
320
|
+
/**
|
|
321
|
+
* Read instances as they exist in links of one status only.
|
|
322
|
+
*
|
|
323
|
+
* `'shared'` hydrates from Shared links only: every property, relation,
|
|
324
|
+
* `author` and `updatedAt` comes from links that are gossiped to the
|
|
325
|
+
* neighbourhood, and none from this executor's Local links. That is the
|
|
326
|
+
* read to use when showing data to another user (#1024). `'local'` is the
|
|
327
|
+
* converse. Unset or `null` (the default) reads both, and a property
|
|
328
|
+
* declared `local: true` still reads only its Local links.
|
|
329
|
+
*
|
|
330
|
+
* Relations include typed `@HasMany` / `@HasOne` relations, which are filled
|
|
331
|
+
* by the conformance getter the SDK generates: the executor adds the status
|
|
332
|
+
* check to that getter's relation link. A hand-written `getter` is run as
|
|
333
|
+
* written, so it reads links of any status unless it checks
|
|
334
|
+
* `<ad4m://ontology/status>` itself.
|
|
335
|
+
*
|
|
336
|
+
* Included relations and the instances a `$` projection hydrates inherit
|
|
337
|
+
* the setting, unless an include's sub-query sets its own. The `__links`
|
|
338
|
+
* rows (see {@link Query.links}) are restricted the same way.
|
|
339
|
+
*
|
|
340
|
+
* Combines with {@link Query.includeUnverified}: a link must have the
|
|
341
|
+
* requested status **and** pass the signature check, both on the same link.
|
|
342
|
+
* So a Local link whose signature did not verify is withheld under
|
|
343
|
+
* `linkStatus: 'local'` too, and comes back only with
|
|
344
|
+
* `linkStatus: 'local', includeUnverified: true` (or with no `linkStatus`
|
|
345
|
+
* and `includeUnverified: true`).
|
|
346
|
+
*
|
|
347
|
+
* Scope: this restricts the links that hydrate an instance and the links
|
|
348
|
+
* that *select* it (`where`, the class's flags, `count`/`totalCount`, `$`
|
|
349
|
+
* projections, `parent` scopes and the order behind `limit`/`offset`). So an
|
|
350
|
+
* instance is returned under `'local'` only when it is flagged in a Local
|
|
351
|
+
* link, and under `'shared'` only when it is flagged in a Shared one.
|
|
352
|
+
*/
|
|
353
|
+
linkStatus?: LinkStatus;
|
|
354
|
+
/**
|
|
355
|
+
* Also hydrate from links whose signature did not verify.
|
|
356
|
+
*
|
|
357
|
+
* By default the executor withholds every link whose stored signature
|
|
358
|
+
* verdict is not valid, so a forged or tampered link never becomes a
|
|
359
|
+
* property value, a relation target, `author` or `updatedAt`. That
|
|
360
|
+
* includes a typed relation's generated conformance getter. A `getter` you
|
|
361
|
+
* write yourself runs as written, so it reads unverified links unless it
|
|
362
|
+
* joins the link's `ad4m://ontology/proofValid` itself. Set this to
|
|
363
|
+
* `true` only to *display* an unverified claim, e.g. a UI that marks a value
|
|
364
|
+
* as unverified. Anything that acts on the data, such as a vote counter or a
|
|
365
|
+
* role check, must leave it off.
|
|
366
|
+
*
|
|
367
|
+
* Included relations inherit the setting unless their sub-query sets its own.
|
|
368
|
+
*
|
|
369
|
+
* The same applies to the rows under `__links` and to what *selects* an
|
|
370
|
+
* instance: `where` (including a per-link `author`), the class's flags,
|
|
371
|
+
* `count`/`totalCount`, the order behind `limit`/`offset`, `parent` scopes
|
|
372
|
+
* and `$` projections, `transitive` ones included. With `true`, selection
|
|
373
|
+
* reads unverified links too.
|
|
374
|
+
*/
|
|
375
|
+
includeUnverified?: boolean;
|
|
376
|
+
/**
|
|
377
|
+
* Return the individual links behind each instance, with their own author,
|
|
378
|
+
* timestamp, signature and signature verdict, under `instance.__links`. For
|
|
379
|
+
* a collection this is per-item provenance: who added each member, when, and
|
|
380
|
+
* whether their signature holds.
|
|
381
|
+
*
|
|
382
|
+
* Each entry is a property or relation name the model declares, or an
|
|
383
|
+
* absolute predicate IRI — including one the model does **not** declare
|
|
384
|
+
* (an annotation such as a revocation tombstone). A name wins over the IRI
|
|
385
|
+
* reading. Every requested entry is present on every instance, as `[]` when
|
|
386
|
+
* it has no such link. An entry that is neither a declared name nor an IRI,
|
|
387
|
+
* or that names a reverse relation (`@BelongsToOne` / `@BelongsToMany`),
|
|
388
|
+
* makes the query fail rather than answer `[]`.
|
|
389
|
+
*
|
|
390
|
+
* The rows are read by a second query after the instances are hydrated, so
|
|
391
|
+
* asking for them never changes `createdAt`, `updatedAt` or any property.
|
|
392
|
+
* See {@link LinkRow}.
|
|
393
|
+
*/
|
|
394
|
+
links?: string[];
|
|
150
395
|
};
|
|
396
|
+
/**
|
|
397
|
+
* One stored link as returned under `__links` — the same shape as the
|
|
398
|
+
* `LinkExpression` `perspective.get()` returns, including the signature
|
|
399
|
+
* verdict the executor recorded when the link was stored.
|
|
400
|
+
*
|
|
401
|
+
* `proof.valid` is `true` only when the signature verifies against `author`.
|
|
402
|
+
* A link stored without a proof arrives with `key` and `signature` set to
|
|
403
|
+
* `""` and `valid: false`; that is an unverifiable link, not a valid unsigned
|
|
404
|
+
* one. Anything that acts on a row (counting a vote, granting a role) should
|
|
405
|
+
* require `proof.valid`.
|
|
406
|
+
*
|
|
407
|
+
* `valid` is never `null` here and `invalid` is always `!valid`, the same
|
|
408
|
+
* convention as `perspective.get()`. So `invalid: true` does not by itself mean
|
|
409
|
+
* a signature failed: it also covers a link with no proof, or with no recorded
|
|
410
|
+
* verdict. To tell an unsigned link from a failed signature, check whether
|
|
411
|
+
* `proof.signature` is `""`.
|
|
412
|
+
*/
|
|
413
|
+
export interface LinkRow {
|
|
414
|
+
author: string;
|
|
415
|
+
timestamp: string;
|
|
416
|
+
data: {
|
|
417
|
+
source: string;
|
|
418
|
+
predicate: string;
|
|
419
|
+
target: string;
|
|
420
|
+
};
|
|
421
|
+
proof: {
|
|
422
|
+
key: string;
|
|
423
|
+
signature: string;
|
|
424
|
+
valid: boolean;
|
|
425
|
+
invalid: boolean;
|
|
426
|
+
};
|
|
427
|
+
}
|
|
428
|
+
/** `instance.__links`: requested entry (spelled as requested) → its rows, oldest first. */
|
|
429
|
+
export type LinksMap = Record<string, LinkRow[]>;
|
|
151
430
|
/**
|
|
152
431
|
* Sub-query options for a specific relation inside an `IncludeMap`.
|
|
153
432
|
*
|
|
@@ -194,6 +473,10 @@ type HasNoTypedFields<T extends Ad4mModel> = [
|
|
|
194
473
|
export type StringWhereOps = {
|
|
195
474
|
not?: string | string[];
|
|
196
475
|
contains?: string;
|
|
476
|
+
/** See {@link WhereOps.eq}. */
|
|
477
|
+
eq?: string | string[];
|
|
478
|
+
/** See {@link WhereOps.author}. */
|
|
479
|
+
author?: AuthorCondition;
|
|
197
480
|
};
|
|
198
481
|
export type NumericWhereOps = {
|
|
199
482
|
not?: number | number[];
|
|
@@ -202,8 +485,15 @@ export type NumericWhereOps = {
|
|
|
202
485
|
gt?: number;
|
|
203
486
|
gte?: number;
|
|
204
487
|
between?: [number, number];
|
|
488
|
+
/** See {@link WhereOps.eq}. */
|
|
489
|
+
eq?: number | number[];
|
|
490
|
+
/** See {@link WhereOps.author}. */
|
|
491
|
+
author?: AuthorCondition;
|
|
205
492
|
};
|
|
206
|
-
export type TypedWhereCondition<V> = V extends string ? string | string[] | StringWhereOps : V extends number ? number | number[] | NumericWhereOps : V extends boolean ? boolean
|
|
493
|
+
export type TypedWhereCondition<V> = V extends string ? string | string[] | StringWhereOps : V extends number ? number | number[] | NumericWhereOps : V extends boolean ? boolean | {
|
|
494
|
+
eq?: boolean;
|
|
495
|
+
author?: AuthorCondition;
|
|
496
|
+
} : V extends Array<infer U> ? U extends string ? string | string[] | StringWhereOps : U extends number ? number | number[] | NumericWhereOps : WhereCondition : WhereCondition;
|
|
207
497
|
/** Strict Where: keys constrained to T's properties, plus the well-known
|
|
208
498
|
* link-metadata fields (`id`/`author`/`timestamp`) and logical combinators. */
|
|
209
499
|
type StrictTypedWhere<T extends Ad4mModel> = {
|
|
@@ -211,6 +501,13 @@ type StrictTypedWhere<T extends Ad4mModel> = {
|
|
|
211
501
|
} & {
|
|
212
502
|
base?: string | string[];
|
|
213
503
|
id?: string | string[];
|
|
504
|
+
/** Alone: the instance's `.author`, i.e. its earliest link's author.
|
|
505
|
+
* Beside property/relation conditions in the same object: that, AND
|
|
506
|
+
* each of those conditions is satisfied by a link this author wrote.
|
|
507
|
+
* For "this author wrote the `agent` link" alone, nest it:
|
|
508
|
+
* `{ agent: { eq: did, author } }`. It does not reach into
|
|
509
|
+
* `OR`/`AND`/`NOT` sub-clauses. See "Filtering by Author" in the
|
|
510
|
+
* model-classes guide. */
|
|
214
511
|
author?: WhereCondition;
|
|
215
512
|
timestamp?: WhereCondition;
|
|
216
513
|
OR?: StrictTypedWhere<T>[];
|
|
@@ -220,6 +517,13 @@ type StrictTypedWhere<T extends Ad4mModel> = {
|
|
|
220
517
|
/** Public typed `where` for a model class. Falls back to the loose `Where`
|
|
221
518
|
* shape when T has no declared fields (e.g. fromSHACL-derived classes). */
|
|
222
519
|
export type TypedWhere<T extends Ad4mModel> = HasNoTypedFields<T> extends true ? Where : StrictTypedWhere<T>;
|
|
520
|
+
/** Top-level typed `where` of a query on T: {@link TypedWhere} plus
|
|
521
|
+
* `producedByFlow`. Kept out of `TypedWhere` itself because that shape is
|
|
522
|
+
* reused under `OR`/`AND`/`NOT` and in include sub-queries, where the
|
|
523
|
+
* executor rejects `producedByFlow` (see {@link Where.producedByFlow}). */
|
|
524
|
+
export type TypedQueryWhere<T extends Ad4mModel> = TypedWhere<T> & {
|
|
525
|
+
producedByFlow?: ProducedByFlowFilter;
|
|
526
|
+
};
|
|
223
527
|
type StrictTypedOrder<T extends Ad4mModel> = {
|
|
224
528
|
[K in PropertyKeysOf<T> | 'timestamp' | 'author' | 'createdAt' | 'updatedAt']?: 'ASC' | 'DESC';
|
|
225
529
|
} & {
|
|
@@ -233,6 +537,11 @@ export type TypedRelationSubQuery<U extends Ad4mModel> = {
|
|
|
233
537
|
include?: TypedIncludeMap<U>;
|
|
234
538
|
limit?: number;
|
|
235
539
|
offset?: number;
|
|
540
|
+
/** See {@link Query.linkStatus}. Inherited from the parent query when unset. */
|
|
541
|
+
linkStatus?: LinkStatus;
|
|
542
|
+
/** See {@link Query.includeUnverified}. Inherited from the parent query when unset. */
|
|
543
|
+
includeUnverified?: boolean;
|
|
544
|
+
links?: string[];
|
|
236
545
|
};
|
|
237
546
|
/** Projection — `from` must be a real relation on T; `where`/`order` constrained to that target.
|
|
238
547
|
* Modelled as a discriminated union so the literal `count: true` and `limit: 1`
|
|
@@ -241,14 +550,17 @@ export type TypedIncludeProjection<T extends Ad4mModel> = {
|
|
|
241
550
|
[K in RelationKeysOf<T>]: {
|
|
242
551
|
from: K;
|
|
243
552
|
count: true;
|
|
553
|
+
transitive?: boolean;
|
|
244
554
|
} | {
|
|
245
555
|
from: K;
|
|
246
556
|
limit: 1;
|
|
557
|
+
transitive?: boolean;
|
|
247
558
|
where?: TypedWhere<RelatedModel<T, K>>;
|
|
248
559
|
order?: TypedOrder<RelatedModel<T, K>>;
|
|
249
560
|
} | {
|
|
250
561
|
from: K;
|
|
251
562
|
limit?: number;
|
|
563
|
+
transitive?: boolean;
|
|
252
564
|
where?: TypedWhere<RelatedModel<T, K>>;
|
|
253
565
|
order?: TypedOrder<RelatedModel<T, K>>;
|
|
254
566
|
};
|
|
@@ -286,12 +598,17 @@ type StrictTypedQuery<T extends Ad4mModel> = {
|
|
|
286
598
|
properties?: PropertyKeysOf<T>[];
|
|
287
599
|
include?: TypedIncludeMap<T>;
|
|
288
600
|
includeAll?: boolean;
|
|
289
|
-
where?:
|
|
601
|
+
where?: TypedQueryWhere<T>;
|
|
290
602
|
order?: TypedOrder<T>;
|
|
291
603
|
offset?: number;
|
|
292
604
|
limit?: number;
|
|
293
605
|
count?: boolean;
|
|
294
606
|
deepQuery?: boolean;
|
|
607
|
+
/** See {@link Query.linkStatus}. */
|
|
608
|
+
linkStatus?: LinkStatus;
|
|
609
|
+
/** See {@link Query.includeUnverified}. */
|
|
610
|
+
includeUnverified?: boolean;
|
|
611
|
+
links?: string[];
|
|
295
612
|
};
|
|
296
613
|
export type TypedQuery<T extends Ad4mModel> = HasNoTypedFields<T> extends true ? Query : StrictTypedQuery<T>;
|
|
297
614
|
/** Helper that extracts the `include` literal from a TypedQuery for use with IncludeExtras. */
|
package/lib/src/model/types.js
CHANGED
|
@@ -5,6 +5,15 @@
|
|
|
5
5
|
* (`query-utils.ts`, `decorators.ts`, etc.) can import types without
|
|
6
6
|
* creating circular runtime dependencies on `Ad4mModel.ts`.
|
|
7
7
|
*/
|
|
8
|
+
/**
|
|
9
|
+
* Whether this scope is a traversal rather than a single named parent.
|
|
10
|
+
*
|
|
11
|
+
* The other two forms carry `id`; this one carries `ids` and may name several,
|
|
12
|
+
* so anything reaching for one parent — every write path — has to ask first.
|
|
13
|
+
*/
|
|
14
|
+
export function isTraverseScope(scope) {
|
|
15
|
+
return 'ids' in scope;
|
|
16
|
+
}
|
|
8
17
|
/** Type guard for IncludeProjection objects. */
|
|
9
18
|
export function isIncludeProjection(val) {
|
|
10
19
|
return typeof val === 'object' && val !== null && 'from' in val;
|
|
@@ -221,6 +221,14 @@ export interface AddAutoProcessorConfig {
|
|
|
221
221
|
basePrefix?: string;
|
|
222
222
|
/** Class URIs (SHACL `target_class`) to materialize each pass. */
|
|
223
223
|
interpretationClasses: string[];
|
|
224
|
+
/**
|
|
225
|
+
* Canonical flow URIs (`SHACLFlow` `{namespace}{name}Flow`) this processor
|
|
226
|
+
* is flow-aware of. Flow features — the flow-aware prompt, the
|
|
227
|
+
* transition-proposal pass, and auto-spawn on freshly created items — run
|
|
228
|
+
* only on the flows listed here, mirroring the class selection above.
|
|
229
|
+
* Omit (or pass `[]`) for no flow processing.
|
|
230
|
+
*/
|
|
231
|
+
flows?: string[];
|
|
224
232
|
/** Quiet-window (ms) after the last new item before a pass runs. */
|
|
225
233
|
debounceMs: number;
|
|
226
234
|
/** Minimum items before a pass runs (Flux "wait for N inputs"). Default 1. */
|