@coasys/ad4m 0.12.0-rc1-dev.1 → 0.12.0-rc1-dev.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.
Files changed (124) hide show
  1. package/jest.config.js +8 -1
  2. package/lib/index.cjs +13793 -12854
  3. package/lib/index.js +13782 -12851
  4. package/lib/src/Ad4mClient.test.d.ts +1 -0
  5. package/lib/src/Ad4mClient.test.js +1204 -0
  6. package/lib/src/Literal.test.d.ts +1 -0
  7. package/lib/src/Literal.test.js +41 -0
  8. package/lib/src/model/Ad4mModel.d.ts +528 -101
  9. package/lib/src/model/Ad4mModel.js +1670 -748
  10. package/lib/src/model/Ad4mModel.test.js +140 -156
  11. package/lib/src/model/Subject.d.ts +3 -3
  12. package/lib/src/model/Subject.js +25 -25
  13. package/lib/src/model/decorators.d.ts +259 -247
  14. package/lib/src/model/decorators.js +379 -422
  15. package/lib/src/model/mutation.d.ts +81 -0
  16. package/lib/src/model/mutation.js +317 -0
  17. package/lib/src/model/parentUtils.d.ts +32 -0
  18. package/lib/src/model/parentUtils.js +64 -0
  19. package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
  20. package/lib/src/model/prolog/generatePrologFacts.js +139 -0
  21. package/lib/src/model/prolog/index.d.ts +1 -0
  22. package/lib/src/model/prolog/index.js +1 -0
  23. package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
  24. package/lib/src/model/query/ModelQueryBuilder.js +115 -0
  25. package/lib/src/model/query/QueryBuilder.d.ts +101 -0
  26. package/lib/src/model/query/QueryBuilder.js +193 -0
  27. package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
  28. package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
  29. package/lib/src/model/query/fetchInstance.d.ts +24 -0
  30. package/lib/src/model/query/fetchInstance.js +144 -0
  31. package/lib/src/model/query/hydration.d.ts +54 -0
  32. package/lib/src/model/query/hydration.js +214 -0
  33. package/lib/src/model/query/operations.d.ts +59 -0
  34. package/lib/src/model/query/operations.js +384 -0
  35. package/lib/src/model/query/snapshot.d.ts +59 -0
  36. package/lib/src/model/query/snapshot.js +106 -0
  37. package/lib/src/model/query/surrealCompiler.d.ts +42 -0
  38. package/lib/src/model/query/surrealCompiler.js +304 -0
  39. package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
  40. package/lib/src/model/schema/fromJSONSchema.js +264 -0
  41. package/lib/src/model/schema/metadata.d.ts +15 -0
  42. package/lib/src/model/schema/metadata.js +112 -0
  43. package/lib/src/model/subscription.d.ts +47 -0
  44. package/lib/src/model/subscription.js +231 -0
  45. package/lib/src/model/transaction.d.ts +27 -0
  46. package/lib/src/model/transaction.js +32 -0
  47. package/lib/src/model/types.d.ts +195 -0
  48. package/lib/src/model/types.js +8 -0
  49. package/lib/src/model/util.d.ts +6 -6
  50. package/lib/src/model/util.js +22 -22
  51. package/lib/src/neighbourhood/NeighbourhoodClient.js +31 -12
  52. package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -9
  53. package/lib/src/perspectives/PerspectiveProxy.js +63 -51
  54. package/lib/src/shacl/SHACLShape.d.ts +9 -0
  55. package/lib/src/shacl/SHACLShape.js +28 -4
  56. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  57. package/lib/src/shims/type-graphql.d.ts +32 -0
  58. package/lib/src/src/Ad4mClient.d.ts +28 -0
  59. package/lib/src/src/Address.d.ts +1 -0
  60. package/lib/src/src/DID.d.ts +1 -0
  61. package/lib/src/src/Exception.d.ts +7 -0
  62. package/lib/src/src/Literal.d.ts +7 -0
  63. package/lib/src/src/PubSub.d.ts +17 -0
  64. package/lib/src/src/SmartLiteral.d.ts +12 -0
  65. package/lib/src/src/agent/Agent.d.ts +110 -0
  66. package/lib/src/src/agent/AgentClient.d.ts +62 -0
  67. package/lib/src/src/agent/AgentResolver.d.ts +30 -0
  68. package/lib/src/src/agent/AgentStatus.d.ts +8 -0
  69. package/lib/src/src/ai/AIClient.d.ts +32 -0
  70. package/lib/src/src/ai/AIResolver.d.ts +75 -0
  71. package/lib/src/src/ai/Tasks.d.ts +37 -0
  72. package/lib/src/src/buildSchema.d.ts +1 -0
  73. package/lib/src/src/expression/Expression.d.ts +28 -0
  74. package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
  75. package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
  76. package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
  77. package/lib/src/src/index.d.ts +35 -0
  78. package/lib/src/src/jestSetup.d.ts +1 -0
  79. package/lib/src/src/language/Icon.d.ts +4 -0
  80. package/lib/src/src/language/Language.d.ts +206 -0
  81. package/lib/src/src/language/LanguageClient.d.ts +17 -0
  82. package/lib/src/src/language/LanguageContext.d.ts +37 -0
  83. package/lib/src/src/language/LanguageHandle.d.ts +9 -0
  84. package/lib/src/src/language/LanguageMeta.d.ts +35 -0
  85. package/lib/src/src/language/LanguageRef.d.ts +6 -0
  86. package/lib/src/src/language/LanguageResolver.d.ts +19 -0
  87. package/lib/src/src/links/Links.d.ts +39 -0
  88. package/lib/src/src/links/Links.test.d.ts +1 -0
  89. package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
  90. package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
  91. package/lib/src/src/model/Subject.d.ts +25 -0
  92. package/lib/src/src/model/decorators.d.ts +545 -0
  93. package/lib/src/src/model/util.d.ts +12 -0
  94. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
  95. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
  96. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
  97. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  98. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
  99. package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
  100. package/lib/src/src/perspectives/Perspective.d.ts +38 -0
  101. package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
  102. package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
  103. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
  104. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
  105. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
  106. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
  107. package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
  108. package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
  109. package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
  110. package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
  111. package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
  112. package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
  113. package/lib/src/src/typeDefs.d.ts +1 -0
  114. package/lib/src/src/unwrapApolloResult.d.ts +2 -0
  115. package/lib/src/src/utils.d.ts +25 -0
  116. package/package.json +20 -24
  117. package/src/model/Ad4mModel.test.ts +132 -149
  118. package/src/model/Ad4mModel.ts +1930 -784
  119. package/src/model/Subject.ts +24 -24
  120. package/src/model/decorators.ts +626 -482
  121. package/src/model/util.ts +22 -22
  122. package/src/neighbourhood/NeighbourhoodClient.ts +32 -16
  123. package/src/perspectives/PerspectiveProxy.ts +69 -55
  124. package/src/shacl/SHACLShape.ts +33 -4
@@ -0,0 +1,27 @@
1
+ /** Atomic batch-transaction helper — see {@link runTransaction}. */
2
+ import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
3
+ /**
4
+ * An open batch transaction on a perspective.
5
+ *
6
+ * Obtained from the callback argument of {@link runTransaction}. Pass
7
+ * `tx.batchId` to `save()`, `delete()` etc. to enlist those operations in the
8
+ * transaction. Commit and abort are handled automatically by `runTransaction`.
9
+ */
10
+ export interface TransactionContext {
11
+ /** The underlying batch ID — pass to save/delete/add/remove calls. */
12
+ readonly batchId: string;
13
+ /** The perspective this transaction is open on. */
14
+ readonly perspective: PerspectiveProxy;
15
+ }
16
+ /**
17
+ * Commits on success, aborts (discards batch) and re-throws on failure.
18
+ *
19
+ * @example
20
+ * ```typescript
21
+ * await Ad4mModel.transaction(perspective, async (tx) => {
22
+ * await post.save(tx.batchId);
23
+ * await comment.save(tx.batchId);
24
+ * });
25
+ * ```
26
+ */
27
+ export declare function runTransaction<T>(perspective: PerspectiveProxy, callback: (tx: TransactionContext) => Promise<T>): Promise<T>;
@@ -0,0 +1,32 @@
1
+ /** Atomic batch-transaction helper — see {@link runTransaction}. */
2
+ // ─────────────────────────────────────────────────────────────────────────────
3
+ // runTransaction
4
+ // ─────────────────────────────────────────────────────────────────────────────
5
+ /**
6
+ * Commits on success, aborts (discards batch) and re-throws on failure.
7
+ *
8
+ * @example
9
+ * ```typescript
10
+ * await Ad4mModel.transaction(perspective, async (tx) => {
11
+ * await post.save(tx.batchId);
12
+ * await comment.save(tx.batchId);
13
+ * });
14
+ * ```
15
+ */
16
+ export async function runTransaction(perspective, callback) {
17
+ const batchId = await perspective.createBatch();
18
+ const tx = { batchId, perspective };
19
+ try {
20
+ const result = await callback(tx);
21
+ await perspective.commitBatch(batchId);
22
+ return result;
23
+ }
24
+ catch (err) {
25
+ // PerspectiveProxy has no abortBatch — the uncommitted batch will be
26
+ // discarded by the runtime on its next GC cycle. Log at debug level
27
+ // only: the re-thrown error already carries all actionable information,
28
+ // and logging at warn would spam the console for intentional rollbacks.
29
+ console.debug(`[Ad4mModel.transaction] callback threw — batch ${batchId} was NOT committed and will be discarded.`, err);
30
+ throw err;
31
+ }
32
+ }
@@ -0,0 +1,195 @@
1
+ /**
2
+ * Public types for the AD4M model layer.
3
+ *
4
+ * Extracted from Ad4mModel.ts so they can be imported by query builders,
5
+ * hydration helpers, and external consumers without pulling in the full
6
+ * Ad4mModel class.
7
+ */
8
+ type WhereOps = {
9
+ not: string | number | boolean | string[] | number[];
10
+ between: [number, number];
11
+ lt: number;
12
+ lte: number;
13
+ gt: number;
14
+ gte: number;
15
+ contains: string | number;
16
+ };
17
+ export type WhereCondition = string | number | boolean | string[] | number[] | {
18
+ [K in keyof WhereOps]?: WhereOps[K];
19
+ };
20
+ export type Where = {
21
+ [propertyName: string]: WhereCondition;
22
+ };
23
+ export type Order = {
24
+ [propertyName: string]: "ASC" | "DESC";
25
+ };
26
+ /**
27
+ * Prisma-style eager-loading map.
28
+ *
29
+ * Key = relation field name on the model.
30
+ * Value = `true` (hydrate all with no filter) or a `Query` to
31
+ * filter / order / limit the nested set.
32
+ *
33
+ * @example
34
+ * ```typescript
35
+ * Recipe.findAll(perspective, {
36
+ * include: {
37
+ * comments: true,
38
+ * tags: { where: { active: true }, order: { name: 'ASC' }, limit: 5 },
39
+ * },
40
+ * });
41
+ * ```
42
+ */
43
+ export type IncludeMap = {
44
+ [relationName: string]: true | Query;
45
+ };
46
+ /**
47
+ * Minimal interface a parent model class must satisfy for the model-backed
48
+ * `parent` query form. Avoids a circular import between types.ts and Ad4mModel.ts.
49
+ */
50
+ type ParentQueryParentCtor = {
51
+ getModelMetadata(): ModelMetadata;
52
+ };
53
+ /** Raw predicate form — use for ad-hoc or cross-package predicates. */
54
+ export type ParentQueryByPredicate = {
55
+ id: string;
56
+ predicate: string;
57
+ };
58
+ /**
59
+ * Model-backed form — DRY alternative that resolves the predicate from the
60
+ * parent model's `@HasMany` decorator metadata at query time.
61
+ */
62
+ export type ParentQueryByModel = {
63
+ id: string;
64
+ model: ParentQueryParentCtor;
65
+ /** The `@HasMany` field name on `model`. Optional when unambiguous. */
66
+ field?: string;
67
+ };
68
+ /** Union of the two `parent` query forms accepted by {@link Query}. */
69
+ export type ParentQuery = ParentQueryByPredicate | ParentQueryByModel;
70
+ export type Query = {
71
+ properties?: string[];
72
+ /** Eagerly hydrate relations. Key = field name; value = `true` or a sub-`Query`. See {@link IncludeMap}. */
73
+ include?: IncludeMap;
74
+ where?: Where;
75
+ order?: Order;
76
+ offset?: number;
77
+ limit?: number;
78
+ count?: boolean;
79
+ /**
80
+ * When provided, restricts results to instances reachable from the given
81
+ * parent node via the given predicate.
82
+ *
83
+ * The subscription layer also watches this predicate so that adding or
84
+ * removing a child link triggers a live re-query.
85
+ *
86
+ * Two equivalent forms are accepted:
87
+ * - Raw: `{ id, predicate }` — use for ad-hoc / foreign predicates.
88
+ * - Model-backed: `{ id, model, field? }` — DRY, refactor-safe; the
89
+ * predicate is resolved automatically from the parent model's `@HasMany`
90
+ * decorator metadata. `field` is the `@HasMany` field name; when the
91
+ * parent has exactly one `@HasMany` pointing to the child type it may be
92
+ * omitted (but is recommended for clarity).
93
+ *
94
+ * @example
95
+ * // Raw form (still valid for foreign predicates)
96
+ * parent: { id: parentId, predicate: 'custom://my_pred' }
97
+ *
98
+ * // Model-backed form (preferred for schema-declared relations)
99
+ * parent: { id: poll.id, model: Poll, field: 'answers' }
100
+ */
101
+ parent?: ParentQuery;
102
+ };
103
+ /**
104
+ * Extends `Query` (minus `count`) with subscription delivery options.
105
+ * Pass to {@link Ad4mModel.subscribe} or the builder's `.subscribe()`.
106
+ */
107
+ export type SubscribeOptions = Omit<Query, "count"> & {
108
+ /**
109
+ * Debounce delay in milliseconds. Multiple link changes within this window
110
+ * trigger only one re-query. Default: `0` (no debouncing).
111
+ */
112
+ debounce?: number;
113
+ /**
114
+ * Called when the re-query or the callback throws.
115
+ * Defaults to `console.error` so failures are always visible without
116
+ * requiring every caller to handle them.
117
+ */
118
+ onError?: (err: Error) => void;
119
+ };
120
+ /**
121
+ * Handle returned by `Ad4mModel.subscribe()`. Call `unsubscribe()` in cleanup.
122
+ * `lastError` holds the most recent unhandled error, or `null`.
123
+ */
124
+ export type Subscription = {
125
+ unsubscribe(): void;
126
+ /** The most recent unhandled error from re-query or callback, or `null`. */
127
+ readonly lastError: Error | null;
128
+ };
129
+ export type AllInstancesResult = any;
130
+ export type ResultsWithTotalCount<T> = {
131
+ results: T[];
132
+ totalCount?: number;
133
+ };
134
+ export type PaginationResult<T> = {
135
+ results: T[];
136
+ totalCount?: number;
137
+ pageSize: number;
138
+ pageNumber: number;
139
+ };
140
+ /**
141
+ * Metadata for a single property extracted from decorators.
142
+ */
143
+ export interface PropertyMetadata {
144
+ /** The property name */
145
+ name: string;
146
+ /** The predicate URI (through value) */
147
+ predicate: string;
148
+ /** Whether the property is required */
149
+ required: boolean;
150
+ /** Whether the property is read-only (default: false, i.e. writable) */
151
+ readOnly?: boolean;
152
+ /** Initial value if specified */
153
+ initial?: string;
154
+ /** Language for resolution (e.g., "literal") */
155
+ resolveLanguage?: string;
156
+ /** Custom SurrealQL getter code */
157
+ getter?: string;
158
+ /** Whether stored locally only */
159
+ local?: boolean;
160
+ /** Transform function */
161
+ transform?: (value: any) => any;
162
+ /** Whether this is a flag property */
163
+ flag?: boolean;
164
+ }
165
+ /**
166
+ * Metadata for a single relation extracted from decorators.
167
+ */
168
+ export interface RelationMetadata {
169
+ /** The relation name */
170
+ name: string;
171
+ /** The predicate URI (through value) */
172
+ predicate: string;
173
+ /** Custom SurrealQL getter code */
174
+ getter?: string;
175
+ /** Whether stored locally only */
176
+ local?: boolean;
177
+ /** Traversal direction — "forward" (default) for @HasMany/@HasOne, "reverse" for @BelongsToOne/@BelongsToMany */
178
+ direction?: "forward" | "reverse";
179
+ /** Maximum number of results (1 for @BelongsToOne / @HasOne) */
180
+ maxCount?: number;
181
+ /** Model factory for eager hydration — set when decorator is called with () => ModelClass */
182
+ relatedModel?: () => any;
183
+ }
184
+ /**
185
+ * Complete model metadata extracted from decorators.
186
+ */
187
+ export interface ModelMetadata {
188
+ /** The model class name from @ModelOptions */
189
+ className: string;
190
+ /** Map of property name to metadata */
191
+ properties: Record<string, PropertyMetadata>;
192
+ /** Map of relation name to metadata */
193
+ relations: Record<string, RelationMetadata>;
194
+ }
195
+ export {};
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Public types for the AD4M model layer.
3
+ *
4
+ * Extracted from Ad4mModel.ts so they can be imported by query builders,
5
+ * hydration helpers, and external consumers without pulling in the full
6
+ * Ad4mModel class.
7
+ */
8
+ export {};
@@ -3,10 +3,10 @@ export declare function propertyNameToSetterName(property: string): string;
3
3
  export declare function setterNameToPropertyName(setter: string): string;
4
4
  export declare function singularToPlural(singular: string): string;
5
5
  export declare function pluralToSingular(plural: string): string;
6
- export declare function collectionToAdderName(collection: string): string;
7
- export declare function collectionAdderToName(adderName: string): string;
8
- export declare function collectionToRemoverName(collection: string): string;
9
- export declare function collectionRemoverToName(removerName: string): string;
10
- export declare function collectionSetterToName(setterName: string): string;
11
- export declare function collectionToSetterName(collection: string): string;
6
+ export declare function relationToAdderName(relation: string): string;
7
+ export declare function relationAdderToName(adderName: string): string;
8
+ export declare function relationToRemoverName(relation: string): string;
9
+ export declare function relationRemoverToName(removerName: string): string;
10
+ export declare function relationSetterToName(setterName: string): string;
11
+ export declare function relationToSetterName(relation: string): string;
12
12
  export declare function stringifyObjectLiteral(obj: any): any;
@@ -29,36 +29,36 @@ export function pluralToSingular(plural) {
29
29
  }
30
30
  }
31
31
  // e.g. "comments" -> "addComment"
32
- export function collectionToAdderName(collection) {
33
- return `add${capitalize(pluralToSingular(collection))}`;
32
+ export function relationToAdderName(relation) {
33
+ return `add${capitalize(pluralToSingular(relation))}`;
34
34
  }
35
35
  // e.g. "addComments" -> "comments"
36
- export function collectionAdderToName(adderName) {
37
- // Extract the collection name after "add" and lowercase first char
38
- // The method name already has the plural collection name (e.g., "addComments")
39
- let collectionName = adderName.substring(3);
40
- return collectionName.charAt(0).toLowerCase() + collectionName.slice(1);
36
+ export function relationAdderToName(adderName) {
37
+ // Extract the relation name after "add" and lowercase first char
38
+ // The method name already has the plural relation name (e.g., "addComments")
39
+ let relationName = adderName.substring(3);
40
+ return relationName.charAt(0).toLowerCase() + relationName.slice(1);
41
41
  }
42
42
  // e.g. "comments" -> "removeComment"
43
- export function collectionToRemoverName(collection) {
44
- return `remove${capitalize(pluralToSingular(collection))}`;
43
+ export function relationToRemoverName(relation) {
44
+ return `remove${capitalize(pluralToSingular(relation))}`;
45
45
  }
46
46
  // e.g. "removeComments" -> "comments"
47
- export function collectionRemoverToName(removerName) {
48
- // Extract the collection name after "remove" and lowercase first char
49
- // The method name already has the plural collection name (e.g., "removeComments")
50
- let collectionName = removerName.substring(6);
51
- return collectionName.charAt(0).toLowerCase() + collectionName.slice(1);
47
+ export function relationRemoverToName(removerName) {
48
+ // Extract the relation name after "remove" and lowercase first char
49
+ // The method name already has the plural relation name (e.g., "removeComments")
50
+ let relationName = removerName.substring(6);
51
+ return relationName.charAt(0).toLowerCase() + relationName.slice(1);
52
52
  }
53
- export function collectionSetterToName(setterName) {
54
- // Extract the collection name after "setCollection" and lowercase first char
55
- // The method name already has the plural collection name (e.g., "setCollectionComments")
56
- let collectionName = setterName.substring(13);
57
- return collectionName.charAt(0).toLowerCase() + collectionName.slice(1);
53
+ export function relationSetterToName(setterName) {
54
+ // Extract the relation name after "set" and lowercase first char
55
+ // The method name already has the plural relation name (e.g., "setComments")
56
+ let relationName = setterName.substring(3);
57
+ return relationName.charAt(0).toLowerCase() + relationName.slice(1);
58
58
  }
59
- // e.g. "comments" -> "addComment"
60
- export function collectionToSetterName(collection) {
61
- return `setCollection${capitalize(pluralToSingular(collection))}`;
59
+ // e.g. "comments" -> "setComments"
60
+ export function relationToSetterName(relation) {
61
+ return `set${capitalize(relation)}`;
62
62
  }
63
63
  export function stringifyObjectLiteral(obj) {
64
64
  if (Array.isArray(obj)) {
@@ -43,18 +43,18 @@ export class NeighbourhoodClient {
43
43
  name
44
44
  sharedUrl
45
45
  state
46
- neighbourhood {
46
+ neighbourhood {
47
47
  data {
48
- linkLanguage
49
- meta {
48
+ linkLanguage
49
+ meta {
50
50
  links
51
51
  {
52
52
  author
53
53
  timestamp
54
54
  data { source, predicate, target }
55
55
  proof { valid, invalid, signature, key }
56
- }
57
- }
56
+ }
57
+ }
58
58
  }
59
59
  author
60
60
  }
@@ -90,7 +90,7 @@ export class NeighbourhoodClient {
90
90
  status {
91
91
  author
92
92
  timestamp
93
- data {
93
+ data {
94
94
  links {
95
95
  author
96
96
  timestamp
@@ -207,12 +207,19 @@ export class NeighbourhoodClient {
207
207
  dispatchSignal(perspectiveUUID, signal) {
208
208
  const handlers = __classPrivateFieldGet(this, _NeighbourhoodClient_signalHandlers, "f").get(perspectiveUUID);
209
209
  if (handlers) {
210
- handlers.forEach(handler => handler(signal));
210
+ for (const handler of handlers) {
211
+ try {
212
+ handler(signal);
213
+ }
214
+ catch (e) {
215
+ console.error("Error in signal handler:", e);
216
+ }
217
+ }
211
218
  }
212
219
  }
213
220
  async subscribeToSignals(perspectiveUUID) {
214
221
  const that = this;
215
- await __classPrivateFieldGet(this, _NeighbourhoodClient_apolloClient, "f").subscribe({
222
+ __classPrivateFieldGet(this, _NeighbourhoodClient_apolloClient, "f").subscribe({
216
223
  query: gql `subscription neighbourhoodSignal($perspectiveUUID: String!) {
217
224
  neighbourhoodSignal(perspectiveUUID: $perspectiveUUID) {
218
225
  author
@@ -224,7 +231,7 @@ export class NeighbourhoodClient {
224
231
  timestamp
225
232
  data { source, predicate, target }
226
233
  proof { valid, invalid, signature, key }
227
- }
234
+ }
228
235
  }
229
236
  proof { valid, invalid, signature, key }
230
237
  }
@@ -232,8 +239,16 @@ export class NeighbourhoodClient {
232
239
  variables: { perspectiveUUID }
233
240
  }).subscribe({
234
241
  next: (result) => {
235
- const { neighbourhoodSignal } = unwrapApolloResult(result);
236
- that.dispatchSignal(perspectiveUUID, neighbourhoodSignal);
242
+ try {
243
+ const { neighbourhoodSignal } = unwrapApolloResult(result);
244
+ that.dispatchSignal(perspectiveUUID, neighbourhoodSignal);
245
+ }
246
+ catch (e) {
247
+ console.error("Error in signal subscription:", e);
248
+ }
249
+ },
250
+ error: (err) => {
251
+ console.error("Signal subscription error for perspective", perspectiveUUID, err);
237
252
  }
238
253
  });
239
254
  }
@@ -242,9 +257,13 @@ export class NeighbourhoodClient {
242
257
  if (!handlersForPerspective) {
243
258
  handlersForPerspective = [];
244
259
  __classPrivateFieldGet(this, _NeighbourhoodClient_signalHandlers, "f").set(perspectiveUUID, handlersForPerspective);
260
+ // Push handler BEFORE subscribing so it's available when signals arrive
261
+ handlersForPerspective.push(handler);
245
262
  await this.subscribeToSignals(perspectiveUUID);
246
263
  }
247
- handlersForPerspective.push(handler);
264
+ else {
265
+ handlersForPerspective.push(handler);
266
+ }
248
267
  }
249
268
  removeSignalHandler(perspectiveUUID, handler) {
250
269
  const handlersForPerspective = __classPrivateFieldGet(this, _NeighbourhoodClient_signalHandlers, "f").get(perspectiveUUID);
@@ -210,7 +210,7 @@ export declare class PerspectiveProxy {
210
210
  * - `addLink`: Creates a new link
211
211
  * - `removeLink`: Removes an existing link
212
212
  * - `setSingleTarget`: Removes all existing links with the same source/predicate and adds a new one
213
- * - `collectionSetter`: Special command for setting collection properties
213
+ * - `collectionSetter`: Special command for setting relation properties
214
214
  *
215
215
  * When used with parameters, the special value "value" in the target field will be
216
216
  * replaced with the actual parameter value.
@@ -574,7 +574,7 @@ export declare class PerspectiveProxy {
574
574
  * shape.addProperty({
575
575
  * name: 'ingredients',
576
576
  * path: 'recipe://has_ingredient',
577
- * // No maxCount = collection
577
+ * // No maxCount = relation
578
578
  * });
579
579
  *
580
580
  * await perspective.addShacl('Recipe', shape);
@@ -703,7 +703,7 @@ export declare class PerspectiveProxy {
703
703
  predicate: string;
704
704
  resolveLanguage?: string;
705
705
  }>;
706
- collections: Map<string, {
706
+ relations: Map<string, {
707
707
  predicate: string;
708
708
  instanceFilter?: string;
709
709
  condition?: string;
@@ -719,11 +719,11 @@ export declare class PerspectiveProxy {
719
719
  */
720
720
  getPropertyValueViaSurreal(baseExpression: string, className: string, propertyName: string): Promise<any>;
721
721
  /**
722
- * Gets collection values using SurrealDB when Prolog fails.
722
+ * Gets relation values using SurrealDB when Prolog fails.
723
723
  * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
724
724
  * Note: This is used by Subject.ts (legacy pattern). Ad4mModel.ts uses getModelMetadata() instead.
725
725
  */
726
- getCollectionValuesViaSurreal(baseExpression: string, className: string, collectionName: string): Promise<any[]>;
726
+ getRelationValuesViaSurreal(baseExpression: string, className: string, relationName: string): Promise<any[]>;
727
727
  /**
728
728
  * Batch-checks multiple expressions against subject class metadata using a single or limited SurrealDB queries.
729
729
  * This avoids N+1 query problems by checking all values at once.
@@ -738,7 +738,7 @@ export declare class PerspectiveProxy {
738
738
  predicate: string;
739
739
  resolveLanguage?: string;
740
740
  }>;
741
- collections: Map<string, {
741
+ relations: Map<string, {
742
742
  predicate: string;
743
743
  instanceFilter?: string;
744
744
  condition?: string;
@@ -761,16 +761,16 @@ export declare class PerspectiveProxy {
761
761
  */
762
762
  getAllSubjectProxies<T>(subjectClass: T): Promise<T[]>;
763
763
  /**
764
- * Find a subject class by matching an object's properties/collections against SHACL shapes.
764
+ * Find a subject class by matching an object's properties/relations against SHACL shapes.
765
765
  * Queries SHACL links client-side to find a class whose properties contain all required ones.
766
766
  * @returns The matching class name, or null if no match found.
767
767
  */
768
768
  private findClassByProperties;
769
769
  /** Returns all subject classes that match the given template object.
770
770
  * This function looks at the properties of the template object and
771
- * its setters and collections to create a Prolog query that finds
771
+ * its setters and relations to create a Prolog query that finds
772
772
  * all subject classes that would be converted to a proxy object
773
- * with exactly the same properties and collections.
773
+ * with exactly the same properties and relations.
774
774
  *
775
775
  * Since there could be multiple subject classes that match the given
776
776
  * criteria, this function returns a list of class names.