@coasys/ad4m 0.13.1-staging.2 → 0.13.1-staging.4
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 +610 -208
- package/lib/index.js +607 -209
- package/lib/src/Ad4mClient.d.ts +7 -0
- package/lib/src/Ad4mClient.js +9 -0
- package/lib/src/agent/AgentClient.d.ts +16 -1
- package/lib/src/agent/AgentClient.js +21 -2
- package/lib/src/ai/AITypes.d.ts +6 -2
- package/lib/src/apiClient.d.ts +13 -0
- package/lib/src/apiClient.js +67 -12
- package/lib/src/generated/api/Apps.d.ts +4 -0
- package/lib/src/generated/api/AuthInfo.d.ts +4 -0
- package/lib/src/generated/api/Events.d.ts +10 -12
- package/lib/src/generated/api/FlowStateChangedEvent.d.ts +3 -2
- package/lib/src/generated/api/Model.d.ts +4 -0
- package/lib/src/generated/api/ModelApi.d.ts +5 -1
- package/lib/src/generated/api/ModelApiInput.d.ts +7 -1
- package/lib/src/generated/api/Notification.d.ts +5 -1
- package/lib/src/generated/api/NotificationInput.d.ts +4 -0
- package/lib/src/generated/api/PerspectiveEvent.d.ts +8 -0
- package/lib/src/generated/api/{PerspectiveLinkWithOwner.d.ts → PerspectiveLinkEvent.d.ts} +4 -2
- package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.d.ts → PerspectiveLinkUpdatedEvent.d.ts} +4 -2
- package/lib/src/generated/api/PerspectiveRemovedEvent.d.ts +7 -0
- package/lib/src/generated/api/RequestCapabilityRequest.d.ts +1 -0
- package/lib/src/generated/api/RpcMethods.d.ts +10 -1
- package/lib/src/generated/api/RuntimeInfo.d.ts +5 -0
- package/lib/src/generated/api/RuntimeUpdateNotificationParams.d.ts +6 -1
- package/lib/src/generated/api/UsersRevokeAllSessionsParams.d.ts +7 -0
- package/{src/generated/api/PerspectiveRemovedWithOwner.ts → lib/src/generated/api/UsersRevokeAllSessionsParams.js} +1 -2
- package/lib/src/index.d.ts +1 -0
- package/lib/src/index.js +1 -0
- package/lib/src/model/Ad4mModel.js +45 -18
- package/lib/src/model/ModelQueryBuilder.d.ts +7 -3
- package/lib/src/model/ModelQueryBuilder.js +9 -4
- package/lib/src/model/query-common.js +7 -1
- package/lib/src/model/types.d.ts +45 -2
- package/lib/src/model/types.js +8 -0
- package/lib/src/perspectives/Container.d.ts +41 -0
- package/lib/src/perspectives/Container.js +62 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +6 -3
- package/lib/src/perspectives/PerspectiveProxy.js +10 -4
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +94 -12
- package/lib/src/perspectives/WakerSubscriptionManager.js +276 -75
- package/lib/src/runtime/RuntimeClient.d.ts +6 -3
- package/lib/src/runtime/RuntimeClient.js +2 -0
- package/lib/src/runtime/RuntimeTypes.d.ts +7 -1
- package/package.json +2 -2
- package/src/Ad4mClient.test.ts +54 -19
- package/src/Ad4mClient.ts +10 -0
- package/src/agent/AgentClient.ts +26 -2
- package/src/ai/AITypes.ts +6 -2
- package/src/apiClient.test.ts +128 -3
- package/src/apiClient.ts +64 -11
- package/src/generated/api/Apps.ts +6 -1
- package/src/generated/api/AuthInfo.ts +6 -1
- package/src/generated/api/Events.ts +10 -12
- package/src/generated/api/FlowStateChangedEvent.ts +3 -2
- package/src/generated/api/Model.ts +4 -0
- package/src/generated/api/ModelApi.ts +5 -1
- package/src/generated/api/ModelApiInput.ts +8 -1
- package/src/generated/api/Notification.ts +5 -1
- package/src/generated/api/NotificationInput.ts +6 -1
- package/src/generated/api/PerspectiveEvent.ts +7 -0
- package/src/generated/api/{PerspectiveLinkUpdatedWithOwner.ts → PerspectiveLinkEvent.ts} +4 -1
- package/src/generated/api/PerspectiveLinkUpdatedEvent.ts +7 -0
- package/src/generated/api/PerspectiveRemovedEvent.ts +6 -0
- package/src/generated/api/RequestCapabilityRequest.ts +1 -1
- package/src/generated/api/RpcMethods.ts +4 -1
- package/src/generated/api/RuntimeInfo.ts +6 -1
- package/src/generated/api/RuntimeUpdateNotificationParams.ts +7 -1
- package/src/generated/api/UsersRevokeAllSessionsParams.ts +8 -0
- package/src/index.ts +1 -0
- package/src/model/Ad4mModel.ts +51 -19
- package/src/model/ModelQueryBuilder.ts +9 -6
- package/src/model/containment-scope.test.ts +104 -0
- package/src/model/query-common.ts +10 -1
- package/src/model/types.ts +56 -2
- package/src/perspectives/Container.test.ts +65 -0
- package/src/perspectives/Container.ts +46 -0
- package/src/perspectives/PerspectiveProxy.test.ts +11 -0
- package/src/perspectives/PerspectiveProxy.ts +10 -4
- package/src/perspectives/WakerSubscriptionManager.test.ts +400 -82
- package/src/perspectives/WakerSubscriptionManager.ts +321 -85
- package/src/perspectives/link-updated-type.test.ts +2 -2
- package/src/perspectives/listener-leaks.test.ts +3 -3
- package/src/runtime/RuntimeClient.ts +6 -3
- package/src/runtime/RuntimeTypes.ts +10 -1
- package/lib/src/generated/api/MessageReceivedEvent.d.ts +0 -7
- package/lib/src/generated/api/PerspectiveRemovedWithOwner.d.ts +0 -5
- package/lib/src/generated/api/PerspectiveWithOwner.d.ts +0 -6
- package/lib/src/generated/api/PerspectiveWithOwner.js +0 -1
- package/src/generated/api/MessageReceivedEvent.ts +0 -7
- package/src/generated/api/PerspectiveLinkWithOwner.ts +0 -4
- package/src/generated/api/PerspectiveWithOwner.ts +0 -4
- /package/lib/src/generated/api/{MessageReceivedEvent.js → PerspectiveEvent.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveLinkUpdatedWithOwner.js → PerspectiveLinkEvent.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveLinkWithOwner.js → PerspectiveLinkUpdatedEvent.js} +0 -0
- /package/lib/src/generated/api/{PerspectiveRemovedWithOwner.js → PerspectiveRemovedEvent.js} +0 -0
|
@@ -7,7 +7,7 @@ import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSON
|
|
|
7
7
|
import { buildSPARQLQuery, valueToLiteralIri, effectiveLiteralStorage } from "./query-sparql";
|
|
8
8
|
import { ModelQueryBuilder } from "./ModelQueryBuilder";
|
|
9
9
|
import { normalizeValue, } from "./hydration";
|
|
10
|
-
import { isTraverseScope } from "./types";
|
|
10
|
+
import { isContainedScope, isContainmentTraversal, isTraverseScope } from "./types";
|
|
11
11
|
// ---------------------------------------------------------------------------
|
|
12
12
|
// Helpers for Rust-side include resolution
|
|
13
13
|
// ---------------------------------------------------------------------------
|
|
@@ -348,6 +348,24 @@ function jsonToModelInstance(ModelClass, perspective, json, include, properties)
|
|
|
348
348
|
}
|
|
349
349
|
return instance;
|
|
350
350
|
}
|
|
351
|
+
/**
|
|
352
|
+
* Put `childId` under `parent`. A containment scope `{ id }` writes through the
|
|
353
|
+
* built-in `Container` (#1446): the executor runs the adder of the parent's own
|
|
354
|
+
* `children` relation when its class has one (a block's `we://child`), else
|
|
355
|
+
* writes `ad4m://has_child`. The other forms write their one predicate.
|
|
356
|
+
*/
|
|
357
|
+
async function linkToParent(perspective, parent, childCtor, childId, batchId) {
|
|
358
|
+
if (isContainedScope(parent)) {
|
|
359
|
+
await perspective.updateSubject("ad4m://Container", parent.id, { children: { action: "adder", value: [childId] } }, batchId);
|
|
360
|
+
return;
|
|
361
|
+
}
|
|
362
|
+
const link = new Link({
|
|
363
|
+
source: parent.id,
|
|
364
|
+
predicate: resolveParentPredicate(parent, childCtor),
|
|
365
|
+
target: childId,
|
|
366
|
+
});
|
|
367
|
+
await perspective.add(link, 'shared', batchId);
|
|
368
|
+
}
|
|
351
369
|
/**
|
|
352
370
|
* Base class for defining data models in AD4M.
|
|
353
371
|
*
|
|
@@ -1005,7 +1023,28 @@ export class Ad4mModel {
|
|
|
1005
1023
|
query = { ...query, include: { ...expanded, ...query.include } };
|
|
1006
1024
|
}
|
|
1007
1025
|
const queryInput = {};
|
|
1008
|
-
if (query.parent) {
|
|
1026
|
+
if (query.parent && isContainedScope(query.parent)) {
|
|
1027
|
+
// Containment: the executor resolves the predicates from the installed
|
|
1028
|
+
// classes, so only the id travels.
|
|
1029
|
+
queryInput.parent = { id: query.parent.id };
|
|
1030
|
+
}
|
|
1031
|
+
else if (query.parent && isContainmentTraversal(query.parent)) {
|
|
1032
|
+
// A traversal over containment: no predicate travels either.
|
|
1033
|
+
const t = query.parent;
|
|
1034
|
+
const traverse = { ids: t.ids };
|
|
1035
|
+
if (t.transitive !== undefined)
|
|
1036
|
+
traverse.transitive = t.transitive;
|
|
1037
|
+
if (t.direction !== undefined)
|
|
1038
|
+
traverse.direction = t.direction;
|
|
1039
|
+
if (t.limitPerAnchor !== undefined)
|
|
1040
|
+
traverse.limitPerAnchor = t.limitPerAnchor;
|
|
1041
|
+
if (t.levels !== undefined)
|
|
1042
|
+
traverse.levels = t.levels;
|
|
1043
|
+
if (t.maxDepth !== undefined)
|
|
1044
|
+
traverse.maxDepth = t.maxDepth;
|
|
1045
|
+
queryInput.parent = traverse;
|
|
1046
|
+
}
|
|
1047
|
+
else if (query.parent) {
|
|
1009
1048
|
const parentPredicate = resolveParentPredicate(query.parent, this);
|
|
1010
1049
|
// A traversal keeps its own shape on the wire: the executor reads `ids`,
|
|
1011
1050
|
// and flattening it to one `id` here is how a request for a whole level
|
|
@@ -1029,6 +1068,8 @@ export class Ad4mModel {
|
|
|
1029
1068
|
traverse.limitPerAnchor = t.limitPerAnchor;
|
|
1030
1069
|
if (t.levels !== undefined)
|
|
1031
1070
|
traverse.levels = t.levels;
|
|
1071
|
+
if (t.maxDepth !== undefined)
|
|
1072
|
+
traverse.maxDepth = t.maxDepth;
|
|
1032
1073
|
queryInput.parent = traverse;
|
|
1033
1074
|
}
|
|
1034
1075
|
else {
|
|
@@ -1993,14 +2034,7 @@ export class Ad4mModel {
|
|
|
1993
2034
|
if (options?.parent && !options?.batchId) {
|
|
1994
2035
|
const batchId = await perspective.createBatch();
|
|
1995
2036
|
await instance.save(batchId);
|
|
1996
|
-
|
|
1997
|
-
const predicate = resolveParentPredicate(parent, this);
|
|
1998
|
-
const link = new Link({
|
|
1999
|
-
source: parent.id,
|
|
2000
|
-
predicate,
|
|
2001
|
-
target: instance.id,
|
|
2002
|
-
});
|
|
2003
|
-
await perspective.add(link, 'shared', batchId);
|
|
2037
|
+
await linkToParent(perspective, requireSingleParent(options.parent), this, instance.id, batchId);
|
|
2004
2038
|
await perspective.commitBatch(batchId);
|
|
2005
2039
|
// Hydrate the instance now that the batch has been committed (mirrors the
|
|
2006
2040
|
// behaviour of save() when it manages its own batch).
|
|
@@ -2010,14 +2044,7 @@ export class Ad4mModel {
|
|
|
2010
2044
|
await instance.save(options?.batchId);
|
|
2011
2045
|
// Create parent → child link if a parent scope was provided
|
|
2012
2046
|
if (options?.parent) {
|
|
2013
|
-
|
|
2014
|
-
const predicate = resolveParentPredicate(parent, this);
|
|
2015
|
-
const link = new Link({
|
|
2016
|
-
source: parent.id,
|
|
2017
|
-
predicate,
|
|
2018
|
-
target: instance.id,
|
|
2019
|
-
});
|
|
2020
|
-
await perspective.add(link, 'shared', options?.batchId);
|
|
2047
|
+
await linkToParent(perspective, requireSingleParent(options.parent), this, instance.id, options?.batchId);
|
|
2021
2048
|
}
|
|
2022
2049
|
return instance;
|
|
2023
2050
|
}
|
|
@@ -115,9 +115,10 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
115
115
|
* 3. **String id + model class** — same metadata scan (or field lookup if
|
|
116
116
|
* options include `field`).
|
|
117
117
|
* 4. **String id + string predicate** — raw escape hatch, no metadata lookup.
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
118
|
+
* 5. **String id alone** — containment through the built-in `Container`:
|
|
119
|
+
* the id's `ad4m://has_child` targets, and the targets of the `children`
|
|
120
|
+
* relation of every class the id is an instance of. The executor
|
|
121
|
+
* resolves the predicates; nothing is looked up here.
|
|
121
122
|
*
|
|
122
123
|
* @param idOrInstance - The parent's expression URI **or** an Ad4mModel instance
|
|
123
124
|
* @param modelOrPredicate - A model class (predicate auto-resolved) **or** a raw predicate string
|
|
@@ -140,6 +141,9 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
|
|
|
140
141
|
*
|
|
141
142
|
* // String id + raw predicate (escape hatch)
|
|
142
143
|
* Recipe.query(perspective).parent(cookbookId, "cookbook://recipe").get();
|
|
144
|
+
*
|
|
145
|
+
* // String id alone: whatever cookbookId contains
|
|
146
|
+
* Recipe.query(perspective).parent(cookbookId).get();
|
|
143
147
|
* ```
|
|
144
148
|
*/
|
|
145
149
|
parent(idOrInstance: string | Ad4mModel, modelOrPredicate?: typeof Ad4mModel | string | {
|
|
@@ -162,9 +162,10 @@ export class ModelQueryBuilder {
|
|
|
162
162
|
* 3. **String id + model class** — same metadata scan (or field lookup if
|
|
163
163
|
* options include `field`).
|
|
164
164
|
* 4. **String id + string predicate** — raw escape hatch, no metadata lookup.
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
165
|
+
* 5. **String id alone** — containment through the built-in `Container`:
|
|
166
|
+
* the id's `ad4m://has_child` targets, and the targets of the `children`
|
|
167
|
+
* relation of every class the id is an instance of. The executor
|
|
168
|
+
* resolves the predicates; nothing is looked up here.
|
|
168
169
|
*
|
|
169
170
|
* @param idOrInstance - The parent's expression URI **or** an Ad4mModel instance
|
|
170
171
|
* @param modelOrPredicate - A model class (predicate auto-resolved) **or** a raw predicate string
|
|
@@ -187,6 +188,9 @@ export class ModelQueryBuilder {
|
|
|
187
188
|
*
|
|
188
189
|
* // String id + raw predicate (escape hatch)
|
|
189
190
|
* Recipe.query(perspective).parent(cookbookId, "cookbook://recipe").get();
|
|
191
|
+
*
|
|
192
|
+
* // String id alone: whatever cookbookId contains
|
|
193
|
+
* Recipe.query(perspective).parent(cookbookId).get();
|
|
190
194
|
* ```
|
|
191
195
|
*/
|
|
192
196
|
parent(idOrInstance, modelOrPredicate, options) {
|
|
@@ -214,7 +218,8 @@ export class ModelQueryBuilder {
|
|
|
214
218
|
this.queryParams.parent = { id, model: idOrInstance.constructor, ...(field && { field }) };
|
|
215
219
|
}
|
|
216
220
|
else {
|
|
217
|
-
|
|
221
|
+
// String id alone → containment form of Scope
|
|
222
|
+
this.queryParams.parent = { id };
|
|
218
223
|
}
|
|
219
224
|
return this;
|
|
220
225
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Shared query helpers used by both the Prolog and SPARQL query pipelines.
|
|
3
3
|
*/
|
|
4
|
-
import { isTraverseScope } from "./types";
|
|
4
|
+
import { isContainedScope, isContainmentTraversal, isTraverseScope } from "./types";
|
|
5
5
|
import { getRelationsMetadata } from "./decorators";
|
|
6
6
|
/**
|
|
7
7
|
* Resolves the predicate for a parent query.
|
|
@@ -31,6 +31,12 @@ export function resolveParentPredicate(parent, childCtor) {
|
|
|
31
31
|
// Raw form — explicit predicate
|
|
32
32
|
if ('predicate' in parent)
|
|
33
33
|
return parent.predicate;
|
|
34
|
+
// Containment form — one predicate per containment edge, resolved by the
|
|
35
|
+
// executor from the installed classes. There is no single one to return.
|
|
36
|
+
if (isContainedScope(parent) || isContainmentTraversal(parent)) {
|
|
37
|
+
throw new Error('parent(): a containment scope { id } names no single predicate; the executor resolves ' +
|
|
38
|
+
'it. Use the model query path (findAll / query / subscribe) to read it.');
|
|
39
|
+
}
|
|
34
40
|
// Model form — resolve from relation metadata
|
|
35
41
|
const { model } = parent;
|
|
36
42
|
const relMeta = getRelationsMetadata(model);
|
package/lib/src/model/types.d.ts
CHANGED
|
@@ -90,6 +90,13 @@ export type Order = {
|
|
|
90
90
|
* **Traverse form** — bounded traversal from one or more anchors, for reading
|
|
91
91
|
* a tree rather than one node's children. Read-only: AutoProcessor's write
|
|
92
92
|
* scopes reject it, because it names no single parent to write under.
|
|
93
|
+
*
|
|
94
|
+
* **Containment form** — `{ id }` alone: everything contained in `id`, through
|
|
95
|
+
* the built-in `Container`. That is the targets of `id`'s `ad4m://has_child`
|
|
96
|
+
* links, whatever `id` is, and the targets of the `children` relation (by name,
|
|
97
|
+
* or aliased to `children`) of every class `id` is an instance of. The caller
|
|
98
|
+
* names no class and no predicate; the executor resolves them from the
|
|
99
|
+
* installed classes. See {@link ContainedScope}.
|
|
93
100
|
*/
|
|
94
101
|
export type Scope = {
|
|
95
102
|
model: typeof Ad4mModel;
|
|
@@ -98,7 +105,22 @@ export type Scope = {
|
|
|
98
105
|
} | {
|
|
99
106
|
id: string;
|
|
100
107
|
predicate: string;
|
|
101
|
-
} | TraverseScope;
|
|
108
|
+
} | TraverseScope | ContainedScope;
|
|
109
|
+
/**
|
|
110
|
+
* Contained in `id`, through `Container`: `{ id }` and nothing else. A
|
|
111
|
+
* misspelt extra field (`{ id, predicat }`) is an error in the executor,
|
|
112
|
+
* never a containment read.
|
|
113
|
+
*/
|
|
114
|
+
export interface ContainedScope {
|
|
115
|
+
id: string;
|
|
116
|
+
predicate?: never;
|
|
117
|
+
model?: never;
|
|
118
|
+
field?: never;
|
|
119
|
+
}
|
|
120
|
+
/** Whether this traversal follows containment rather than a named predicate. */
|
|
121
|
+
export declare function isContainmentTraversal(scope: Scope): scope is TraverseByContainment;
|
|
122
|
+
/** Whether this scope is the containment form, `{ id }` alone. */
|
|
123
|
+
export declare function isContainedScope(scope: Scope): scope is ContainedScope;
|
|
102
124
|
/**
|
|
103
125
|
* Walk a predicate from several anchors at once, and optionally all the way
|
|
104
126
|
* down.
|
|
@@ -111,7 +133,23 @@ export type Scope = {
|
|
|
111
133
|
* or by the model and relation that own it. See {@link TraverseByPredicate} and
|
|
112
134
|
* {@link TraverseByModel}.
|
|
113
135
|
*/
|
|
114
|
-
export type TraverseScope = TraverseByPredicate | TraverseByModel;
|
|
136
|
+
export type TraverseScope = TraverseByPredicate | TraverseByModel | TraverseByContainment;
|
|
137
|
+
/**
|
|
138
|
+
* A traversal over containment, through the built-in `Container`: it names no
|
|
139
|
+
* predicate, and follows every edge the executor resolves from the installed
|
|
140
|
+
* classes — `ad4m://has_child` on any node, and each class's own `children`
|
|
141
|
+
* relation on its instances. `direction: 'in'` from a record reaches whatever
|
|
142
|
+
* holds it: `Container.findAll(p, { parent: { ids: [x], direction: 'in' } })`.
|
|
143
|
+
*
|
|
144
|
+
* The rows are the queried class; the nodes a transitive walk passes through
|
|
145
|
+
* are any container. With no `order`, a transitive walk's rows come nearest
|
|
146
|
+
* first. `levels` is refused on it, and so is `limitPerAnchor` on a
|
|
147
|
+
* transitive one; bound it with `maxDepth`.
|
|
148
|
+
*/
|
|
149
|
+
export interface TraverseByContainment extends TraverseOptions {
|
|
150
|
+
predicate?: never;
|
|
151
|
+
model?: never;
|
|
152
|
+
}
|
|
115
153
|
/** A traversal naming its predicate literally, as the Raw scope does. */
|
|
116
154
|
export interface TraverseByPredicate extends TraverseOptions {
|
|
117
155
|
predicate: string;
|
|
@@ -181,6 +219,11 @@ export interface TraverseOptions {
|
|
|
181
219
|
* every depth.
|
|
182
220
|
*/
|
|
183
221
|
limitPerAnchor?: number;
|
|
222
|
+
/**
|
|
223
|
+
* With `transitive`, stop the walk after this many hops (`1` is the direct
|
|
224
|
+
* neighbours). Refused without `transitive` and alongside `levels`.
|
|
225
|
+
*/
|
|
226
|
+
maxDepth?: number;
|
|
184
227
|
/**
|
|
185
228
|
* Walk the relation level by level, keeping this many results per anchor at each depth —
|
|
186
229
|
* `[10, 5, 3]` is "ten replies, five under each of those, three under each of *those*".
|
package/lib/src/model/types.js
CHANGED
|
@@ -5,6 +5,14 @@
|
|
|
5
5
|
* (`query-utils.ts`, `decorators.ts`, etc.) can import types without
|
|
6
6
|
* creating circular runtime dependencies on `Ad4mModel.ts`.
|
|
7
7
|
*/
|
|
8
|
+
/** Whether this traversal follows containment rather than a named predicate. */
|
|
9
|
+
export function isContainmentTraversal(scope) {
|
|
10
|
+
return isTraverseScope(scope) && !('predicate' in scope && scope.predicate) && !('model' in scope && scope.model);
|
|
11
|
+
}
|
|
12
|
+
/** Whether this scope is the containment form, `{ id }` alone. */
|
|
13
|
+
export function isContainedScope(scope) {
|
|
14
|
+
return !isTraverseScope(scope) && !('predicate' in scope) && !('model' in scope);
|
|
15
|
+
}
|
|
8
16
|
/**
|
|
9
17
|
* Whether this scope is a traversal rather than a single named parent.
|
|
10
18
|
*
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { Ad4mModel } from "../model/Ad4mModel";
|
|
2
|
+
/**
|
|
3
|
+
* The built-in abstract class `Container { children }` (#1446): what holds
|
|
4
|
+
* other records — a channel, a thread, a post, a call, a document, a board.
|
|
5
|
+
*
|
|
6
|
+
* X is contained in P when `P ad4m://has_child X` exists, whatever P is (an
|
|
7
|
+
* instance of any class, or a node no class describes, such as
|
|
8
|
+
* `ad4m://self`), or when P is an instance of a class whose `children`
|
|
9
|
+
* relation (by name, or aliased to `children`) links X:
|
|
10
|
+
*
|
|
11
|
+
* ```typescript
|
|
12
|
+
* @Model({ name: "Block", implements: [Container] })
|
|
13
|
+
* class Block extends Ad4mModel {
|
|
14
|
+
* @HasMany({ through: "we://child", alias: { Container: "children" } })
|
|
15
|
+
* blocks: string[] = [];
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* // Messages held by P, through has_child or a Block's we://child:
|
|
19
|
+
* await Message.findAll(perspective, { parent: { id: P } });
|
|
20
|
+
* // Everything that holds X:
|
|
21
|
+
* await Container.findAll(perspective, { parent: { ids: [X], direction: "in" } });
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* A row's `children` is everything it holds, merged across its classes. A
|
|
25
|
+
* node no class describes is a row of its own when it holds something by
|
|
26
|
+
* `has_child`. Always scope a `Container` query (`where: { id }`, a
|
|
27
|
+
* `children` filter or `parent`): unscoped, it reads every holder in the
|
|
28
|
+
* perspective.
|
|
29
|
+
*
|
|
30
|
+
* Built in: the executor declares it (mirrors
|
|
31
|
+
* `rust-executor/src/perspectives/hardwired_sdna/container.json`) and reads
|
|
32
|
+
* it by its URI, `ad4m://Container`, so a perspective never stores it and an
|
|
33
|
+
* app class named `Container` does not replace it. `register()` on it writes
|
|
34
|
+
* nothing.
|
|
35
|
+
*/
|
|
36
|
+
export declare class Container extends Ad4mModel {
|
|
37
|
+
/** The URI the executor reads it by. */
|
|
38
|
+
static readonly builtinUri = "ad4m://Container";
|
|
39
|
+
/** What it holds, whatever their class. */
|
|
40
|
+
children: string[];
|
|
41
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
|
|
2
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
3
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
4
|
+
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
5
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
6
|
+
};
|
|
7
|
+
var __metadata = (this && this.__metadata) || function (k, v) {
|
|
8
|
+
if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
|
|
9
|
+
};
|
|
10
|
+
import { Ad4mModel } from "../model/Ad4mModel";
|
|
11
|
+
import { HasMany, Model } from "../model/decorators";
|
|
12
|
+
/**
|
|
13
|
+
* The built-in abstract class `Container { children }` (#1446): what holds
|
|
14
|
+
* other records — a channel, a thread, a post, a call, a document, a board.
|
|
15
|
+
*
|
|
16
|
+
* X is contained in P when `P ad4m://has_child X` exists, whatever P is (an
|
|
17
|
+
* instance of any class, or a node no class describes, such as
|
|
18
|
+
* `ad4m://self`), or when P is an instance of a class whose `children`
|
|
19
|
+
* relation (by name, or aliased to `children`) links X:
|
|
20
|
+
*
|
|
21
|
+
* ```typescript
|
|
22
|
+
* @Model({ name: "Block", implements: [Container] })
|
|
23
|
+
* class Block extends Ad4mModel {
|
|
24
|
+
* @HasMany({ through: "we://child", alias: { Container: "children" } })
|
|
25
|
+
* blocks: string[] = [];
|
|
26
|
+
* }
|
|
27
|
+
*
|
|
28
|
+
* // Messages held by P, through has_child or a Block's we://child:
|
|
29
|
+
* await Message.findAll(perspective, { parent: { id: P } });
|
|
30
|
+
* // Everything that holds X:
|
|
31
|
+
* await Container.findAll(perspective, { parent: { ids: [X], direction: "in" } });
|
|
32
|
+
* ```
|
|
33
|
+
*
|
|
34
|
+
* A row's `children` is everything it holds, merged across its classes. A
|
|
35
|
+
* node no class describes is a row of its own when it holds something by
|
|
36
|
+
* `has_child`. Always scope a `Container` query (`where: { id }`, a
|
|
37
|
+
* `children` filter or `parent`): unscoped, it reads every holder in the
|
|
38
|
+
* perspective.
|
|
39
|
+
*
|
|
40
|
+
* Built in: the executor declares it (mirrors
|
|
41
|
+
* `rust-executor/src/perspectives/hardwired_sdna/container.json`) and reads
|
|
42
|
+
* it by its URI, `ad4m://Container`, so a perspective never stores it and an
|
|
43
|
+
* app class named `Container` does not replace it. `register()` on it writes
|
|
44
|
+
* nothing.
|
|
45
|
+
*/
|
|
46
|
+
let Container = class Container extends Ad4mModel {
|
|
47
|
+
constructor() {
|
|
48
|
+
super(...arguments);
|
|
49
|
+
/** What it holds, whatever their class. */
|
|
50
|
+
this.children = [];
|
|
51
|
+
}
|
|
52
|
+
};
|
|
53
|
+
/** The URI the executor reads it by. */
|
|
54
|
+
Container.builtinUri = "ad4m://Container";
|
|
55
|
+
__decorate([
|
|
56
|
+
HasMany({ through: "ad4m://has_child" }),
|
|
57
|
+
__metadata("design:type", Array)
|
|
58
|
+
], Container.prototype, "children", void 0);
|
|
59
|
+
Container = __decorate([
|
|
60
|
+
Model({ name: "Container", abstract: true })
|
|
61
|
+
], Container);
|
|
62
|
+
export { Container };
|
|
@@ -18,7 +18,7 @@ import { SHACLShape } from "../shacl/SHACLShape";
|
|
|
18
18
|
import { SHACLFlow } from "../shacl/SHACLFlow";
|
|
19
19
|
import type { AddAutoProcessorConfig, InterpretationOverlayInfo, RawScope, RunInterpretationObserveOptions } from "./AutoProcessor";
|
|
20
20
|
type QueryCallback = (result: AllInstancesResult) => void;
|
|
21
|
-
/** A live SPARQL query with its latest result.
|
|
21
|
+
/** A live SPARQL or model query with its latest result.
|
|
22
22
|
*
|
|
23
23
|
* `subscribe()` opens the query and resolves once the first result is in;
|
|
24
24
|
* `onResult()` callbacks then get every later result. The executor sends
|
|
@@ -33,7 +33,10 @@ type QueryCallback = (result: AllInstancesResult) => void;
|
|
|
33
33
|
*/
|
|
34
34
|
export declare class QuerySubscriptionProxy {
|
|
35
35
|
#private;
|
|
36
|
-
|
|
36
|
+
/** With `className`, `query` is a model query (JSON) over that class or
|
|
37
|
+
* union of classes, opened with `modelSubscribe`; results are
|
|
38
|
+
* `{ instances, totalCount }`. Without it, `query` is SPARQL. */
|
|
39
|
+
constructor(uuid: string, query: string, client: PerspectiveClient, className?: string | string[]);
|
|
37
40
|
/** Open the query; resolves with the first result delivered. */
|
|
38
41
|
subscribe(): Promise<void>;
|
|
39
42
|
/** The executor's id for this subscription. */
|
|
@@ -336,7 +339,7 @@ export declare class PerspectiveProxy {
|
|
|
336
339
|
*
|
|
337
340
|
* The state is not stored on the graph: the engine derives it from the
|
|
338
341
|
* signed proposals and keeps what it derived per agent, outside the
|
|
339
|
-
* perspective. So no other agent — a co-owner on the same
|
|
342
|
+
* perspective. So no other agent — a co-owner on the same executor included —
|
|
340
343
|
* can read or write your entries, and a link query never sees them.
|
|
341
344
|
* `FlowInstance.findAll` / `start` call this for you.
|
|
342
345
|
*/
|
|
@@ -31,7 +31,7 @@ function extractNamespaceFromUri(uri) {
|
|
|
31
31
|
return uri.substring(0, colonIdx + 1);
|
|
32
32
|
return uri;
|
|
33
33
|
}
|
|
34
|
-
/** A live SPARQL query with its latest result.
|
|
34
|
+
/** A live SPARQL or model query with its latest result.
|
|
35
35
|
*
|
|
36
36
|
* `subscribe()` opens the query and resolves once the first result is in;
|
|
37
37
|
* `onResult()` callbacks then get every later result. The executor sends
|
|
@@ -45,14 +45,20 @@ function extractNamespaceFromUri(uri) {
|
|
|
45
45
|
* ```
|
|
46
46
|
*/
|
|
47
47
|
export class QuerySubscriptionProxy {
|
|
48
|
-
|
|
48
|
+
/** With `className`, `query` is a model query (JSON) over that class or
|
|
49
|
+
* union of classes, opened with `modelSubscribe`; results are
|
|
50
|
+
* `{ instances, totalCount }`. Without it, `query` is SPARQL. */
|
|
51
|
+
constructor(uuid, query, client, className) {
|
|
49
52
|
_QuerySubscriptionProxy_instances.add(this);
|
|
50
53
|
_QuerySubscriptionProxy_live.set(this, void 0);
|
|
51
54
|
_QuerySubscriptionProxy_callbacks.set(this, new Set());
|
|
52
55
|
_QuerySubscriptionProxy_initialized.set(this, void 0);
|
|
53
56
|
_QuerySubscriptionProxy_initResolve.set(this, void 0);
|
|
54
57
|
_QuerySubscriptionProxy_initReject.set(this, void 0);
|
|
55
|
-
|
|
58
|
+
const open = className === undefined
|
|
59
|
+
? () => client.subscribeQuery(uuid, query)
|
|
60
|
+
: () => client.modelSubscribe(uuid, className, query);
|
|
61
|
+
__classPrivateFieldSet(this, _QuerySubscriptionProxy_live, new LiveQuery(client, uuid, open, result => __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_deliver).call(this, result)), "f");
|
|
56
62
|
__classPrivateFieldSet(this, _QuerySubscriptionProxy_initialized, new Promise((resolve, reject) => {
|
|
57
63
|
__classPrivateFieldSet(this, _QuerySubscriptionProxy_initResolve, resolve, "f");
|
|
58
64
|
__classPrivateFieldSet(this, _QuerySubscriptionProxy_initReject, reject, "f");
|
|
@@ -474,7 +480,7 @@ export class PerspectiveProxy {
|
|
|
474
480
|
*
|
|
475
481
|
* The state is not stored on the graph: the engine derives it from the
|
|
476
482
|
* signed proposals and keeps what it derived per agent, outside the
|
|
477
|
-
* perspective. So no other agent — a co-owner on the same
|
|
483
|
+
* perspective. So no other agent — a co-owner on the same executor included —
|
|
478
484
|
* can read or write your entries, and a link query never sees them.
|
|
479
485
|
* `FlowInstance.findAll` / `start` call this for you.
|
|
480
486
|
*/
|
|
@@ -11,14 +11,61 @@ export interface WakerSubscription {
|
|
|
11
11
|
type: "mention" | "channel-messages";
|
|
12
12
|
perspective: string;
|
|
13
13
|
channel: string;
|
|
14
|
+
/** SPARQL, or with `className` a model query (JSON) over that class. */
|
|
14
15
|
query: string;
|
|
16
|
+
/**
|
|
17
|
+
* The class `query` reads, as a model query. A mention subscription has
|
|
18
|
+
* one, from the executor's `get_mention_waker_config`: the built-in
|
|
19
|
+
* `ad4m://TextContent`; a children subscription has the built-in
|
|
20
|
+
* `ad4m://Container`, from `generate_waker_query` (#1446). Without it
|
|
21
|
+
* `query` is SPARQL.
|
|
22
|
+
*/
|
|
23
|
+
className?: string;
|
|
24
|
+
/**
|
|
25
|
+
* A mention subscription's terms (profile names and the DID), from
|
|
26
|
+
* `get_mention_waker_config`. The query matches substrings, so a record
|
|
27
|
+
* wakes only when its text holds one of these as a whole word
|
|
28
|
+
* ({@link holdsAWholeWordTerm}); without them a mention subscription is
|
|
29
|
+
* refused.
|
|
30
|
+
*/
|
|
31
|
+
terms?: string[];
|
|
15
32
|
neighbourhood?: string;
|
|
16
33
|
}
|
|
34
|
+
/**
|
|
35
|
+
* How much of a record's text the word check reads. Dropping markup costs time
|
|
36
|
+
* quadratic in a run of unclosed `<script>`, `<style>` or `<!--` openers, so a
|
|
37
|
+
* very long text could hold the event loop for seconds, and a row that holds
|
|
38
|
+
* no term is checked again on every result while it is in the window. A term
|
|
39
|
+
* past this many characters does not wake.
|
|
40
|
+
*/
|
|
41
|
+
export declare const MENTION_TEXT_LIMIT = 16384;
|
|
42
|
+
/**
|
|
43
|
+
* Whether `text` holds one of `terms` as a whole word, case-insensitively:
|
|
44
|
+
* "Data" is in "hi Data!", "@data" and "Data's turn", not in "metadata" or
|
|
45
|
+
* "database". A term is matched literally (regex characters, quotes) and must
|
|
46
|
+
* not touch a letter, mark, digit or underscore on either side, so a name
|
|
47
|
+
* that starts or ends with punctuation still matches. Same rule as #1459's
|
|
48
|
+
* SPARQL `(?:^|\W)term(?:\W|$)`.
|
|
49
|
+
*
|
|
50
|
+
* The rule runs on the visible text only: in HTML, tags and attributes are
|
|
51
|
+
* dropped and entities decoded first. A mention's target attribute
|
|
52
|
+
* (`href`, `data-id`, `data-did`) matches an exact, case-sensitive DID term, which
|
|
53
|
+
* is how a mention by DID is found when the DID is not in the visible text.
|
|
54
|
+
*
|
|
55
|
+
* The mention query's `contains` matches substrings (model query has no word
|
|
56
|
+
* match); this is the check that keeps "data" from waking on "metadata".
|
|
57
|
+
* It reads the first {@link MENTION_TEXT_LIMIT} characters only.
|
|
58
|
+
*/
|
|
59
|
+
export declare function holdsAWholeWordTerm(text: string, terms: string[]): boolean;
|
|
17
60
|
/** Per-message parent resolution result for mention subscriptions. */
|
|
18
61
|
export interface MentionMessage {
|
|
19
|
-
/** The
|
|
62
|
+
/** The mentioned record's id. */
|
|
20
63
|
address: string;
|
|
21
|
-
/**
|
|
64
|
+
/**
|
|
65
|
+
* Every container holding it (channels, threads, calls, blocks): whatever
|
|
66
|
+
* links it with `ad4m://has_child`, and every instance of a class whose
|
|
67
|
+
* `children` relation links it. A record can sit in several.
|
|
68
|
+
*/
|
|
22
69
|
parents: string[];
|
|
23
70
|
/**
|
|
24
71
|
* Everything above the parents, nearest first: their parents, theirs, and so on up to the
|
|
@@ -46,9 +93,13 @@ export interface WakerSubscriptionManagerOptions {
|
|
|
46
93
|
* what the levels hold. 0 reports parents only.
|
|
47
94
|
*/
|
|
48
95
|
ancestorDepth?: number;
|
|
49
|
-
/**
|
|
50
|
-
*
|
|
51
|
-
|
|
96
|
+
/**
|
|
97
|
+
* Called when a subscription fires (after debounce). For mention subs, `mentions` holds every
|
|
98
|
+
* mention not yet delivered, with its parent info. Resolve `false` (or reject) when the wake did
|
|
99
|
+
* not reach the agent: those mentions stay out of the persisted seen set and are offered again
|
|
100
|
+
* after `retryWakeMs`, so a wake lost to a restarting gateway is not lost for good.
|
|
101
|
+
*/
|
|
102
|
+
onWake: (sub: WakerSubscription, result: any, mentions?: MentionMessage[]) => void | boolean | Promise<void | boolean>;
|
|
52
103
|
/** Called when the active subscription list changes (for persistence). */
|
|
53
104
|
onPersist?: (subscriptions: WakerSubscription[], seenMessages: Record<string, string[]>) => void;
|
|
54
105
|
/** Previously persisted seen message IDs per subscription. Seeds seenMessages on resubscribe to avoid duplicate wakes. */
|
|
@@ -67,6 +118,9 @@ export interface WakerSubscriptionManagerOptions {
|
|
|
67
118
|
* so the re-attempt cycle never saw it (#1016).
|
|
68
119
|
*/
|
|
69
120
|
subscribeTimeoutMs?: number;
|
|
121
|
+
/** First delay before offering an undelivered mention wake again (default 5000); doubles per
|
|
122
|
+
* failed attempt, up to 60000. */
|
|
123
|
+
retryWakeMs?: number;
|
|
70
124
|
}
|
|
71
125
|
/**
|
|
72
126
|
* Add a short cause hint to known subscription failures.
|
|
@@ -85,6 +139,7 @@ export declare class WakerSubscriptionManager {
|
|
|
85
139
|
private previousSeenMessages;
|
|
86
140
|
private retryPendingMs;
|
|
87
141
|
private subscribeTimeoutMs;
|
|
142
|
+
private retryWakeMs;
|
|
88
143
|
private proxies;
|
|
89
144
|
private activeSubscriptions;
|
|
90
145
|
/** Subscriptions the executor rejected, waiting to be re-attempted. */
|
|
@@ -106,13 +161,27 @@ export declare class WakerSubscriptionManager {
|
|
|
106
161
|
/** Per-subscription set of already-processed message addresses (for mention subs)
|
|
107
162
|
* or serialized result hash (for channel-messages subs). */
|
|
108
163
|
private seenMessages;
|
|
164
|
+
/**
|
|
165
|
+
* Per mention subscription: the addresses whose wake was delivered, or that were history when
|
|
166
|
+
* the subscription opened. This, not `seenMessages`, is what gets persisted: an address joins
|
|
167
|
+
* `seenMessages` as soon as it is read, while its parents are still resolving and before any
|
|
168
|
+
* wake, so a restart in between must not take it as done.
|
|
169
|
+
*/
|
|
170
|
+
private delivered;
|
|
171
|
+
/**
|
|
172
|
+
* Per mention subscription: mentions read but whose wake has not been delivered yet, keyed by
|
|
173
|
+
* address. They accumulate across a debounce window, so one wake names all of them.
|
|
174
|
+
*/
|
|
175
|
+
private undelivered;
|
|
176
|
+
/** Failed wake attempts in a row per subscription, for the retry backoff. */
|
|
177
|
+
private wakeFailures;
|
|
109
178
|
constructor(options: WakerSubscriptionManagerOptions);
|
|
110
179
|
/** A token identifying this attempt at subscribing `id`. */
|
|
111
180
|
private beginAttempt;
|
|
112
181
|
/** Whether this attempt has been superseded by a dispose or a newer one. */
|
|
113
182
|
private isStale;
|
|
114
183
|
/**
|
|
115
|
-
* Create a live SPARQL
|
|
184
|
+
* Create a live subscription: SPARQL, or a model query when `sub.className` is set.
|
|
116
185
|
* If a subscription with the same id already exists, it is disposed first.
|
|
117
186
|
*/
|
|
118
187
|
subscribe(sub: WakerSubscription): Promise<void>;
|
|
@@ -132,21 +201,34 @@ export declare class WakerSubscriptionManager {
|
|
|
132
201
|
* @param persist — if false, skip calling onPersist (used during batch cleanup).
|
|
133
202
|
*/
|
|
134
203
|
dispose(id: string, persist?: boolean): void;
|
|
204
|
+
/** (Re)start the timer that offers `sub`'s undelivered mentions to `onWake` after `delayMs`. */
|
|
205
|
+
private scheduleMentionWake;
|
|
206
|
+
/**
|
|
207
|
+
* Offer every undelivered mention of `sub` in one wake. On delivery they join the persisted
|
|
208
|
+
* seen set; on failure they stay undelivered and are offered again with backoff.
|
|
209
|
+
*/
|
|
210
|
+
private deliverMentions;
|
|
135
211
|
/** Dispose all active subscriptions and drop anything still pending. */
|
|
136
212
|
disposeAll(): void;
|
|
137
213
|
/** Get all active subscriptions. */
|
|
138
214
|
getActive(): WakerSubscription[];
|
|
139
215
|
/** Check if a subscription exists. */
|
|
140
216
|
has(id: string): boolean;
|
|
141
|
-
/**
|
|
217
|
+
/**
|
|
218
|
+
* Everything holding any of `addresses`, in one model query: a `Container`
|
|
219
|
+
* step in (#1446). The executor follows `ad4m://has_child` on any node and
|
|
220
|
+
* each class's own `children` relation on its instances, so the waker
|
|
221
|
+
* looks up no predicate. Failures count as none.
|
|
222
|
+
*/
|
|
142
223
|
private parentsOf;
|
|
143
224
|
/**
|
|
144
|
-
* The chain above an item's parents,
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
148
|
-
* Each level uses one batched parent lookup, bounded by the depth.
|
|
225
|
+
* The chain above an item's parents, nearest first, up to `ancestorDepth` levels: one
|
|
226
|
+
* transitive `Container` walk in from the parents, bounded by `maxDepth`. The executor walks
|
|
227
|
+
* containment as a graph, so each address comes once however many paths reach it, and a
|
|
228
|
+
* cycle ends. The item and its parents are never reported as ancestors.
|
|
149
229
|
*/
|
|
150
230
|
private ancestorsOf;
|
|
231
|
+
/** The ids of the `Container` rows `parent` scopes to, in the executor's order. */
|
|
232
|
+
private containers;
|
|
151
233
|
private persist;
|
|
152
234
|
}
|