@coasys/ad4m 0.13.1-staging.2 → 0.13.1-staging.3
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 +584 -203
- package/lib/index.js +581 -204
- package/lib/src/Ad4mClient.d.ts +7 -0
- package/lib/src/Ad4mClient.js +9 -0
- package/lib/src/apiClient.d.ts +13 -0
- package/lib/src/apiClient.js +67 -12
- package/lib/src/generated/api/AuthInfo.d.ts +4 -0
- package/lib/src/generated/api/RuntimeInfo.d.ts +5 -0
- 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 +273 -72
- package/lib/src/runtime/RuntimeTypes.d.ts +2 -0
- package/package.json +2 -2
- package/src/Ad4mClient.test.ts +1 -1
- package/src/Ad4mClient.ts +10 -0
- package/src/apiClient.test.ts +128 -2
- package/src/apiClient.ts +64 -11
- package/src/generated/api/AuthInfo.ts +6 -1
- package/src/generated/api/RuntimeInfo.ts +6 -1
- 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 +398 -80
- package/src/perspectives/WakerSubscriptionManager.ts +318 -82
- package/src/runtime/RuntimeTypes.ts +2 -0
|
@@ -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
|
}
|