@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 @@
1
+ export {};
@@ -0,0 +1,25 @@
1
+ import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
2
+ /**
3
+ * Represents a subject in the perspective.
4
+ * A subject is an entity that has properties and collections.
5
+ */
6
+ export declare class Subject {
7
+ #private;
8
+ /**
9
+ * Constructs a new subject.
10
+ * @param perspective - The perspective that the subject belongs to.
11
+ * @param baseExpression - The base expression of the subject.
12
+ * @param subjectClassName - The class name of the subject.
13
+ */
14
+ constructor(perspective: PerspectiveProxy, baseExpression: string, subjectClassName: string);
15
+ /**
16
+ * Gets the base expression of the subject.
17
+ */
18
+ get baseExpression(): string;
19
+ /**
20
+ * Initializes the subject by validating it and defining its properties and collections dynamically.
21
+ *
22
+ * NOTE: This method should be called before using the subject. All the properties and collections of the subject defined are not type-checked.
23
+ */
24
+ init(): Promise<void>;
25
+ }
@@ -0,0 +1,545 @@
1
+ /** Metadata stored for each property via @Property / @Optional / @ReadOnly / @Flag */
2
+ export interface PropertyMetadataEntry extends PropertyOptions {
3
+ /** Internal computed writable flag (inverse of readOnly) for SDNA/SHACL compatibility */
4
+ writable?: boolean;
5
+ flag?: boolean;
6
+ }
7
+ /** Metadata stored for each relation via @HasMany / @HasOne / @BelongsToOne / @BelongsToMany */
8
+ export interface RelationMetadataEntry {
9
+ predicate: string;
10
+ target: () => Ad4mModelLike;
11
+ kind: 'hasMany' | 'hasOne' | 'belongsToOne' | 'belongsToMany';
12
+ /**
13
+ * Maximum number of related instances.
14
+ * Set automatically: 1 for `@HasOne`/`@BelongsToOne`, undefined (unlimited) for `*Many`.
15
+ */
16
+ maxCount?: number;
17
+ local?: boolean;
18
+ }
19
+ /**
20
+ * Retrieve property metadata for a given class constructor.
21
+ * Walks the prototype chain so subclass decorators compose with parent decorators.
22
+ */
23
+ export declare function getPropertiesMetadata(ctor: Function): Record<string, PropertyMetadataEntry>;
24
+ /**
25
+ * Retrieve relation metadata for a given class constructor.
26
+ * Walks the prototype chain so subclass decorators compose with parent decorators.
27
+ */
28
+ export declare function getRelationsMetadata(ctor: Function): Record<string, RelationMetadataEntry>;
29
+ /**
30
+ * Retrieve collection metadata for a given class constructor.
31
+ * Walks the prototype chain so subclass decorators compose with parent decorators.
32
+ * @deprecated Use getRelationsMetadata() for typed relation info. This function
33
+ * returns raw CollectionOptions used internally by SDNA/SHACL generators.
34
+ */
35
+ export declare function getCollectionsMetadata(ctor: Function): Record<string, CollectionOptions>;
36
+ /**
37
+ * Programmatically register property metadata for a given constructor.
38
+ * Used by `fromJSONSchema()` and other dynamic model builders.
39
+ */
40
+ export declare function setPropertyRegistryEntry(ctor: Function, propName: string, meta: PropertyMetadataEntry & {
41
+ writable?: boolean;
42
+ }): void;
43
+ /**
44
+ * Programmatically register collection metadata for a given constructor.
45
+ * Used by `fromJSONSchema()` and other dynamic model builders.
46
+ * @deprecated Prefer registering via relation decorators.
47
+ */
48
+ export declare function setCollectionRegistryEntry(ctor: Function, collName: string, meta: CollectionOptions): void;
49
+ /**
50
+ * Interface for any class that looks like an Ad4mModel (used in circular-ref-safe typings).
51
+ */
52
+ export interface Ad4mModelLike {
53
+ new (...args: any[]): any;
54
+ className?: string;
55
+ generateSDNA?: () => any;
56
+ generateSHACL?: () => any;
57
+ }
58
+ /**
59
+ * Convert a model instance to a plain serializable object.
60
+ * Reads the property metadata and extracts values from the instance.
61
+ */
62
+ export declare function instanceToSerializable(instance: any): Record<string, any>;
63
+ /**
64
+ * Generate a random identifier string (lowercase alpha).
65
+ * Generate a random identifier string of the given length (lowercase alpha).
66
+ */
67
+ export declare function makeRandomId(length: number): string;
68
+ export declare class PerspectiveAction {
69
+ action: string;
70
+ source: string;
71
+ predicate: string;
72
+ target: string;
73
+ }
74
+ export declare function addLink(source: string, predicate: string, target: string): PerspectiveAction;
75
+ export declare function hasLink(predicate: string): string;
76
+ export interface PropertyOptions {
77
+ /**
78
+ * The predicate of the property. All properties must have this option.
79
+ */
80
+ through?: string;
81
+ /**
82
+ * The initial value of the property. Required if the property is marked as required.
83
+ */
84
+ initial?: string;
85
+ /**
86
+ * Indicates whether the property is required. If true, an initial value must be provided.
87
+ */
88
+ required?: boolean;
89
+ /**
90
+ * Indicates whether the property is read-only. If true, no setter will be generated.
91
+ * Defaults to false (property is writable).
92
+ */
93
+ readOnly?: boolean;
94
+ /**
95
+ * The language used to store the property. Can be the default `Literal` Language or a custom language address.
96
+ */
97
+ resolveLanguage?: string;
98
+ /**
99
+ * Custom Prolog getter to get the value of the property. If not provided, the default getter will be used.
100
+ */
101
+ prologGetter?: string;
102
+ /**
103
+ * Custom Prolog setter to set the value of the property. Only available if the property is writable.
104
+ */
105
+ prologSetter?: string;
106
+ /**
107
+ * Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
108
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
109
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)[0]"
110
+ */
111
+ getter?: string;
112
+ /**
113
+ * Indicates whether the property is stored locally in the perspective and not in the network. Useful for properties that are not meant to be shared with the network.
114
+ */
115
+ local?: boolean;
116
+ /**
117
+ * Optional transform function to modify the property value after it is retrieved.
118
+ * This is useful for transforming raw data into a more usable format.
119
+ * The function takes the raw value as input and returns the transformed value.
120
+ */
121
+ transform?: (value: any) => any;
122
+ }
123
+ /**
124
+ * Convenience decorator for defining optional (not required) properties.
125
+ *
126
+ * @category Decorators
127
+ *
128
+ * @description
129
+ * Equivalent to `@Property` but defaults `required` to `false` and does not
130
+ * apply `resolveLanguage` or `initial` defaults. Use this when a property
131
+ * may or may not have a value, and you want full control over its configuration.
132
+ *
133
+ * @example
134
+ * ```typescript
135
+ * class Recipe extends Ad4mModel {
136
+ * @Optional({ through: "recipe://description" })
137
+ * description?: string;
138
+ * }
139
+ * ```
140
+ *
141
+ * @param {PropertyOptions} opts - Property configuration (same options as @Property)
142
+ */
143
+ export declare function Optional(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
144
+ export interface FlagOptions {
145
+ /**
146
+ * The predicate of the property. All properties must have this option.
147
+ */
148
+ through: string;
149
+ /**
150
+ * The value of the property.
151
+ */
152
+ value: string;
153
+ }
154
+ /**
155
+ * Decorator for defining flags on model classes.
156
+ *
157
+ * @category Decorators
158
+ *
159
+ * @description
160
+ * A specialized property decorator for defining immutable type flags or markers on model instances.
161
+ * Flags are always required properties with a fixed value that cannot be changed after creation.
162
+ *
163
+ * Common uses for flags:
164
+ * - Type discrimination between different kinds of models
165
+ * - Marking models with specific capabilities or features
166
+ * - Versioning or compatibility markers
167
+ *
168
+ * Note: Use of Flag is discouraged unless you specifically need type-based filtering or
169
+ * discrimination between different kinds of models. For most cases, regular properties
170
+ * with @Property or @Optional are more appropriate.
171
+ *
172
+ * @example
173
+ * ```typescript
174
+ * class Message extends Ad4mModel {
175
+ * // Type flag to identify message models
176
+ * @Flag({
177
+ * through: "ad4m://type",
178
+ * value: "ad4m://message"
179
+ * })
180
+ * type: string = "";
181
+ *
182
+ * // Version flag for compatibility
183
+ * @Flag({
184
+ * through: "ad4m://version",
185
+ * value: "1.0.0"
186
+ * })
187
+ * version: string = "";
188
+ *
189
+ * // Feature flag
190
+ * @Flag({
191
+ * through: "message://feature",
192
+ * value: "message://encrypted"
193
+ * })
194
+ * feature: string = "";
195
+ * }
196
+ *
197
+ * // Later you can query for specific types:
198
+ * const messages = await Message.query(perspective)
199
+ * .where({ type: "ad4m://message" })
200
+ * .run();
201
+ * ```
202
+ *
203
+ * @param {FlagOptions} opts - Flag configuration
204
+ * @param {string} opts.through - The predicate URI for the flag
205
+ * @param {string} opts.value - The fixed value for the flag
206
+ */
207
+ export declare function Flag(opts: FlagOptions): <T>(target: T, key: keyof T) => void;
208
+ export interface CollectionOptions {
209
+ /**
210
+ * The predicate of the property. All properties must have this option.
211
+ */
212
+ through: string;
213
+ /**
214
+ * Custom SurrealQL getter to resolve the collection values. Use this for custom graph traversals.
215
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
216
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)"
217
+ */
218
+ getter?: string;
219
+ /**
220
+ * Indicates whether the property is stored locally in the perspective and not in the network. Useful for properties that are not meant to be shared with the network.
221
+ */
222
+ local?: boolean;
223
+ }
224
+ export interface ModelConfig {
225
+ /**
226
+ * The name of the entity.
227
+ */
228
+ name: string;
229
+ }
230
+ /**
231
+ * Decorator for defining model classes in AD4M.
232
+ *
233
+ * @category Decorators
234
+ *
235
+ * @description
236
+ * The root decorator that must be applied to any class that represents a model in AD4M.
237
+ * It registers the class as a Social DNA (SDNA) subject class and provides the infrastructure
238
+ * for storing and retrieving instances.
239
+ *
240
+ * This decorator:
241
+ * - Registers the class with a unique name in the AD4M system
242
+ * - Generates the necessary SDNA code for the model's properties and collections
243
+ * - Enables the use of other model decorators (@Property, @Collection, etc.)
244
+ * - Provides static query methods through the Ad4mModel base class
245
+ *
246
+ * @example
247
+ * ```typescript
248
+ * @Model({ name: "Recipe" })
249
+ * class Recipe extends Ad4mModel {
250
+ * @Property({
251
+ * through: "recipe://name",
252
+ * resolveLanguage: "literal"
253
+ * })
254
+ * name: string = "";
255
+ *
256
+ * @Collection({ through: "recipe://ingredient" })
257
+ * ingredients: string[] = [];
258
+ *
259
+ * // Static query methods from Ad4mModel:
260
+ * static async findByName(perspective: PerspectiveProxy, name: string) {
261
+ * return Recipe.query(perspective)
262
+ * .where({ name })
263
+ * .run();
264
+ * }
265
+ * }
266
+ *
267
+ * // Using the model:
268
+ * const recipe = new Recipe(perspective);
269
+ * recipe.name = "Chocolate Cake";
270
+ * await recipe.save();
271
+ *
272
+ * // Querying instances:
273
+ * const recipes = await Recipe.query(perspective)
274
+ * .where({ name: "Chocolate Cake" })
275
+ * .run();
276
+ *
277
+ * // Using with PerspectiveProxy:
278
+ * await perspective.ensureSDNASubjectClass(Recipe);
279
+ * ```
280
+ *
281
+ * @param {ModelConfig} opts - Model configuration
282
+ * @param {string} opts.name - Unique name for the model class in AD4M
283
+ */
284
+ export declare function Model(opts: ModelConfig): (target: any) => void;
285
+ /**
286
+ * The primary property decorator for AD4M model classes.
287
+ *
288
+ * @category Decorators
289
+ *
290
+ * @description
291
+ * The core property decorator with smart defaults. All other property decorators
292
+ * (@Optional, @ReadOnly) are thin wrappers that adjust these defaults.
293
+ *
294
+ * Smart defaults (all overridable):
295
+ * - `required` → `true`
296
+ * - `readOnly` → `false`
297
+ * - `resolveLanguage` → `"literal"`
298
+ * - `initial` → `"literal://string:uninitialized"` (when required)
299
+ *
300
+ * @example
301
+ * ```typescript
302
+ * class User extends Ad4mModel {
303
+ * // Basic required property with default initial value
304
+ * @Property({
305
+ * through: "user://name"
306
+ * })
307
+ * name: string = "";
308
+ *
309
+ * // Required property with custom initial value
310
+ * @Property({
311
+ * through: "user://status",
312
+ * initial: "user://active"
313
+ * })
314
+ * status: string = "";
315
+ *
316
+ * // Required property with literal resolution
317
+ * @Property({
318
+ * through: "user://bio",
319
+ * resolveLanguage: "literal"
320
+ * })
321
+ * bio: string = "";
322
+ *
323
+ * // Required property with custom getter/setter
324
+ * @Property({
325
+ * through: "user://age",
326
+ * getter: `triple(Base, "user://birthYear", Year), Value is 2024 - Year`,
327
+ * setter: `Year is 2024 - Value, Actions = [{"action": "setSingleTarget", "source": "this", "predicate": "user://birthYear", "target": Year}]`
328
+ * })
329
+ * age: number = 0;
330
+ * }
331
+ * ```
332
+ *
333
+ * @param {PropertyOptions} opts - Property configuration
334
+ * @param {string} opts.through - The predicate URI for the property
335
+ * @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized")
336
+ * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
337
+ * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
338
+ * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
339
+ * @param {boolean} [opts.local] - Whether the property should only be stored locally
340
+ */
341
+ export declare function Property(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
342
+ /**
343
+ * Decorator for defining read-only properties on model classes.
344
+ *
345
+ * @category Decorators
346
+ *
347
+ * @description
348
+ * A convenience decorator that defines a read-only property.
349
+ * Equivalent to `@Property` with `readOnly: true`.
350
+ *
351
+ * Read-only properties are ideal for:
352
+ * - Computed or derived values
353
+ * - Properties that should never change after creation
354
+ * - Properties that are set by the system
355
+ * - Properties that represent immutable data
356
+ *
357
+ * @example
358
+ * ```typescript
359
+ * class Post extends Ad4mModel {
360
+ * // Read-only property with custom getter for computed value
361
+ * @ReadOnly({
362
+ * through: "post://likes",
363
+ * getter: `findall(User, triple(Base, "post://liked_by", User), Users), length(Users, Value)`
364
+ * })
365
+ * likeCount: number = 0;
366
+ *
367
+ * // Read-only property for creation timestamp
368
+ * @ReadOnly({
369
+ * through: "post://created_at",
370
+ * initial: new Date().toISOString()
371
+ * })
372
+ * createdAt: string = "";
373
+ *
374
+ * // Read-only property that resolves to a Literal
375
+ * @ReadOnly({
376
+ * through: "post://author",
377
+ * resolveLanguage: "literal"
378
+ * })
379
+ * author: string = "";
380
+ *
381
+ * // Read-only property for system-managed data
382
+ * @ReadOnly({
383
+ * through: "post://version",
384
+ * initial: "1.0.0"
385
+ * })
386
+ * version: string = "";
387
+ * }
388
+ * ```
389
+ *
390
+ * @param {PropertyOptions} opts - Property configuration
391
+ * @param {string} opts.through - The predicate URI for the property
392
+ * @param {string} [opts.initial] - Initial value (if property should have one)
393
+ * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
394
+ * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
395
+ * @param {boolean} [opts.local] - Whether the property should only be stored locally
396
+ */
397
+ export declare function ReadOnly(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
398
+ /**
399
+ * Options for relation decorators (@HasMany, @HasOne, @BelongsToOne, @BelongsToMany).
400
+ */
401
+ export interface RelationOptions {
402
+ /** The predicate URI used to link the two models */
403
+ through: string;
404
+ /** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string collections. */
405
+ target?: () => Ad4mModelLike;
406
+ /**
407
+ * Custom SurrealQL getter to resolve the collection values. Use this for custom graph traversals.
408
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
409
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].out.uri)"
410
+ */
411
+ getter?: string;
412
+ /** Whether the link is stored locally (not shared on the network) */
413
+ local?: boolean;
414
+ }
415
+ /**
416
+ * Utility type that describes the auto-generated helper methods for a HasMany
417
+ * relation. For a property named `comments` on a class `Post`, the following
418
+ * methods will be available on instances:
419
+ *
420
+ * post.addComment(value)
421
+ * post.removeComment(value)
422
+ * post.setComment(values)
423
+ */
424
+ export type HasManyMethods<Keys extends string> = {
425
+ [K in Keys as `add${Capitalize<K>}`]: (value: string | {
426
+ id: string;
427
+ }) => Promise<void>;
428
+ } & {
429
+ [K in Keys as `remove${Capitalize<K>}`]: (value: string | {
430
+ id: string;
431
+ }) => Promise<void>;
432
+ } & {
433
+ [K in Keys as `set${Capitalize<K>}`]: (values: (string | {
434
+ id: string;
435
+ })[]) => Promise<void>;
436
+ };
437
+ /**
438
+ * Decorator for defining a one-to-many relation.
439
+ *
440
+ * @category Decorators
441
+ *
442
+ * @description
443
+ * Declares that the decorated property is an array of related model instances.
444
+ * Under the hood it registers the relation in the relation registry and also
445
+ * creates the corresponding `@Collection` entry so that the SDNA / SHACL
446
+ * generators continue to emit the correct subject-class code.
447
+ *
448
+ * Supports two calling conventions:
449
+ * ```typescript
450
+ * // Options-object style
451
+ * @HasMany({ through: "post://comment", target: () => Comment })
452
+ *
453
+ * // Target-first shorthand
454
+ * @HasMany(() => Comment, { through: "post://comment" })
455
+ * ```
456
+ *
457
+ * @example
458
+ * ```typescript
459
+ * @Model({ name: "Post" })
460
+ * class Post extends Ad4mModel {
461
+ * @HasMany(() => Comment, { through: "post://comment" })
462
+ * comments: string[] = [];
463
+ * }
464
+ * ```
465
+ */
466
+ export declare function HasMany(opts: RelationOptions): PropertyDecorator;
467
+ export declare function HasMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
468
+ /**
469
+ * Decorator for defining a one-to-one relation (owning side).
470
+ *
471
+ * @category Decorators
472
+ *
473
+ * @description
474
+ * Declares that the decorated property holds a single related model instance.
475
+ * The owning side manages the link.
476
+ *
477
+ * Supports two calling conventions:
478
+ * ```typescript
479
+ * @HasOne({ through: "post://author", target: () => Author })
480
+ * @HasOne(() => Author, { through: "post://author" })
481
+ * ```
482
+ *
483
+ * @example
484
+ * ```typescript
485
+ * @Model({ name: "Post" })
486
+ * class Post extends Ad4mModel {
487
+ * @HasOne(() => Author, { through: "post://author" })
488
+ * author: string = "";
489
+ * }
490
+ * ```
491
+ */
492
+ export declare function HasOne(opts: RelationOptions): PropertyDecorator;
493
+ export declare function HasOne(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
494
+ /**
495
+ * Decorator for defining the inverse side of a one-to-one relation.
496
+ *
497
+ * @category Decorators
498
+ *
499
+ * @description
500
+ * Declares the non-owning (inverse) side of a one-to-one relationship.
501
+ * The property is read-only since the owning side manages the link.
502
+ *
503
+ * Supports two calling conventions:
504
+ * ```typescript
505
+ * @BelongsToOne({ through: "post://author", target: () => Post })
506
+ * @BelongsToOne(() => Post, { through: "post://author" })
507
+ * ```
508
+ *
509
+ * @example
510
+ * ```typescript
511
+ * @Model({ name: "Author" })
512
+ * class Author extends Ad4mModel {
513
+ * @BelongsToOne(() => Post, { through: "post://author" })
514
+ * post: string = "";
515
+ * }
516
+ * ```
517
+ */
518
+ export declare function BelongsToOne(opts: RelationOptions): PropertyDecorator;
519
+ export declare function BelongsToOne(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
520
+ /**
521
+ * Decorator for defining the inverse side of a many-to-many relation.
522
+ *
523
+ * @category Decorators
524
+ *
525
+ * @description
526
+ * Declares the non-owning (inverse) side of a many-to-many relationship.
527
+ * The property is a read-only collection since the owning side manages links.
528
+ *
529
+ * Supports two calling conventions:
530
+ * ```typescript
531
+ * @BelongsToMany({ through: "post://tag", target: () => Post })
532
+ * @BelongsToMany(() => Post, { through: "post://tag" })
533
+ * ```
534
+ *
535
+ * @example
536
+ * ```typescript
537
+ * @Model({ name: "Tag" })
538
+ * class Tag extends Ad4mModel {
539
+ * @BelongsToMany(() => Post, { through: "post://tag" })
540
+ * posts: string[] = [];
541
+ * }
542
+ * ```
543
+ */
544
+ export declare function BelongsToMany(opts: RelationOptions): PropertyDecorator;
545
+ export declare function BelongsToMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
@@ -0,0 +1,12 @@
1
+ export declare function capitalize(str: string): string;
2
+ export declare function propertyNameToSetterName(property: string): string;
3
+ export declare function setterNameToPropertyName(setter: string): string;
4
+ export declare function singularToPlural(singular: string): string;
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;
12
+ export declare function stringifyObjectLiteral(obj: any): any;
@@ -0,0 +1,10 @@
1
+ import { Perspective } from "../perspectives/Perspective";
2
+ export declare class Neighbourhood {
3
+ linkLanguage: string;
4
+ meta: Perspective;
5
+ constructor(linkLanguage: string, meta: Perspective);
6
+ }
7
+ declare const NeighbourhoodExpression_base: any;
8
+ export declare class NeighbourhoodExpression extends NeighbourhoodExpression_base {
9
+ }
10
+ export {};
@@ -0,0 +1,25 @@
1
+ import { ApolloClient } from "@apollo/client/core";
2
+ import { Address } from "../Address";
3
+ import { DID } from "../DID";
4
+ import { OnlineAgent, TelepresenceSignalCallback } from "../language/Language";
5
+ import { Perspective, PerspectiveUnsignedInput } from "../perspectives/Perspective";
6
+ import { PerspectiveHandle } from "../perspectives/PerspectiveHandle";
7
+ export declare class NeighbourhoodClient {
8
+ #private;
9
+ constructor(client: ApolloClient<any>);
10
+ publishFromPerspective(perspectiveUUID: string, linkLanguage: Address, meta: Perspective): Promise<string>;
11
+ joinFromUrl(url: string): Promise<PerspectiveHandle>;
12
+ otherAgents(perspectiveUUID: string): Promise<DID[]>;
13
+ hasTelepresenceAdapter(perspectiveUUID: string): Promise<boolean>;
14
+ onlineAgents(perspectiveUUID: string): Promise<OnlineAgent[]>;
15
+ setOnlineStatus(perspectiveUUID: string, status: Perspective): Promise<boolean>;
16
+ setOnlineStatusU(perspectiveUUID: string, status: PerspectiveUnsignedInput): Promise<boolean>;
17
+ sendSignal(perspectiveUUID: string, remoteAgentDid: string, payload: Perspective): Promise<boolean>;
18
+ sendSignalU(perspectiveUUID: string, remoteAgentDid: string, payload: PerspectiveUnsignedInput): Promise<boolean>;
19
+ sendBroadcast(perspectiveUUID: string, payload: Perspective, loopback?: boolean): Promise<boolean>;
20
+ sendBroadcastU(perspectiveUUID: string, payload: PerspectiveUnsignedInput, loopback?: boolean): Promise<boolean>;
21
+ dispatchSignal(perspectiveUUID: string, signal: any): void;
22
+ subscribeToSignals(perspectiveUUID: string): Promise<void>;
23
+ addSignalHandler(perspectiveUUID: string, handler: TelepresenceSignalCallback): Promise<void>;
24
+ removeSignalHandler(perspectiveUUID: string, handler: TelepresenceSignalCallback): void;
25
+ }
@@ -0,0 +1,19 @@
1
+ import { DID } from "../DID";
2
+ import { OnlineAgent } from "../language/Language";
3
+ import { Perspective, PerspectiveExpression, PerspectiveUnsignedInput } from "../perspectives/Perspective";
4
+ import { NeighbourhoodClient } from "./NeighbourhoodClient";
5
+ export declare class NeighbourhoodProxy {
6
+ #private;
7
+ constructor(client: NeighbourhoodClient, pID: string);
8
+ otherAgents(): Promise<DID[]>;
9
+ hasTelepresenceAdapter(): Promise<boolean>;
10
+ onlineAgents(): Promise<OnlineAgent[]>;
11
+ setOnlineStatus(status: Perspective): Promise<boolean>;
12
+ setOnlineStatusU(status: PerspectiveUnsignedInput): Promise<boolean>;
13
+ sendSignal(remoteAgentDid: string, payload: Perspective): Promise<boolean>;
14
+ sendSignalU(remoteAgentDid: string, payload: PerspectiveUnsignedInput): Promise<boolean>;
15
+ sendBroadcast(payload: Perspective, loopback?: boolean): Promise<boolean>;
16
+ sendBroadcastU(payload: PerspectiveUnsignedInput, loopback?: boolean): Promise<boolean>;
17
+ addSignalHandler(handler: (payload: PerspectiveExpression) => void): Promise<void>;
18
+ removeSignalHandler(handler: (payload: PerspectiveExpression) => void): void;
19
+ }
@@ -0,0 +1,24 @@
1
+ import { PerspectiveHandle } from "../perspectives/PerspectiveHandle";
2
+ import { PerspectiveExpression, PerspectiveInput, PerspectiveUnsignedInput } from "../perspectives/Perspective";
3
+ import { DID } from "../DID";
4
+ import { OnlineAgent } from "../language/Language";
5
+ /**
6
+ * Resolver classes are used here to define the GraphQL schema
7
+ * (through the type-graphql annotations)
8
+ * and are spawned in the client tests in Ad4mClient.test.ts.
9
+ * For the latter, they return test fixtures.
10
+ */
11
+ export default class NeighbourhoodResolver {
12
+ neighbourhoodPublishFromPerspective(perspectiveUUID: string, linkLanguage: string, meta: PerspectiveInput): string;
13
+ neighbourhoodJoinFromUrl(url: string, pubSub: any): PerspectiveHandle;
14
+ neighbourhoodOtherAgents(perspectiveUUID: string): DID[];
15
+ neighbourhoodHasTelepresenceAdapter(perspectiveUUID: string): boolean;
16
+ neighbourhoodOnlineAgents(perspectiveUUID: string): OnlineAgent[];
17
+ neighbourhoodSetOnlineStatus(perspectiveUUID: string, status: PerspectiveInput): boolean;
18
+ neighbourhoodSetOnlineStatusU(perspectiveUUID: string, status: PerspectiveUnsignedInput): boolean;
19
+ neighbourhoodSendSignal(perspectiveUUID: string, recipient: DID, signal: PerspectiveInput): boolean;
20
+ neighbourhoodSendSignalU(perspectiveUUID: string, recipient: DID, signal: PerspectiveUnsignedInput): boolean;
21
+ neighbourhoodSendBroadcast(perspectiveUUID: string, signal: PerspectiveInput, loopback?: boolean): boolean;
22
+ neighbourhoodSendBroadcastU(perspectiveUUID: string, signal: PerspectiveUnsignedInput, loopback?: boolean): boolean;
23
+ neighbourhoodSignal(pID: string): PerspectiveExpression;
24
+ }
@@ -0,0 +1,11 @@
1
+ import { Link } from "../links/Links";
2
+ export declare class LinkQuery {
3
+ source?: string;
4
+ target?: string;
5
+ predicate?: string;
6
+ fromDate?: Date;
7
+ untilDate?: Date;
8
+ limit?: number;
9
+ constructor(obj: object);
10
+ isMatch(l: Link): boolean;
11
+ }