@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
@@ -1,62 +1,76 @@
1
- export declare class PerspectiveAction {
2
- action: string;
3
- source: string;
4
- predicate: string;
5
- target: string;
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
6
  }
7
- export declare function addLink(source: string, predicate: string, target: string): PerspectiveAction;
8
- export declare function hasLink(predicate: string): string;
9
- export interface InstanceQueryParams {
7
+ /** Metadata stored for each relation via @HasMany / @HasOne / @BelongsToOne / @BelongsToMany */
8
+ export interface RelationMetadataEntry {
9
+ predicate: string;
10
+ /** Target model class thunk. Optional for untyped string relations. */
11
+ target?: () => Ad4mModelLike;
12
+ kind: 'hasMany' | 'hasOne' | 'belongsToOne' | 'belongsToMany';
10
13
  /**
11
- * An object representing the WHERE clause of the query.
14
+ * Maximum number of related instances.
15
+ * Set automatically: 1 for `@HasOne`/`@BelongsToOne`, undefined (unlimited) for `*Many`.
12
16
  */
13
- where?: object;
17
+ maxCount?: number;
18
+ local?: boolean;
14
19
  /**
15
- * A string representing the Prolog condition clause of the query.
20
+ * Custom SurrealQL getter to resolve the relation values.
21
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
16
22
  */
17
- prologCondition?: string;
23
+ getter?: string;
18
24
  }
19
25
  /**
20
- * Decorator for querying instances of a model class.
21
- *
22
- * @category Decorators
23
- *
24
- * @description
25
- * Allows you to define static query methods on your model class to retrieve instances based on custom conditions.
26
- * This decorator can only be applied to static async methods that return a Promise of an array of model instances.
27
- *
28
- * The query can be constrained using either:
29
- * - A `where` clause that matches property values
30
- * - A custom Prolog `condition` for more complex queries
31
- *
32
- * @example
33
- * ```typescript
34
- * class Recipe extends Ad4mModel {
35
- * @Property({ through: "recipe://name" })
36
- * name: string = "";
37
- *
38
- * @Property({ through: "recipe://rating" })
39
- * rating: number = 0;
40
- *
41
- * // Get all recipes
42
- * @InstanceQuery()
43
- * static async all(perspective: PerspectiveProxy): Promise<Recipe[]> { return [] }
44
- *
45
- * // Get recipes by name
46
- * @InstanceQuery({ where: { name: "Chocolate Cake" }})
47
- * static async findByName(perspective: PerspectiveProxy): Promise<Recipe[]> { return [] }
48
- *
49
- * // Get highly rated recipes using a custom condition
50
- * @InstanceQuery({ prologCondition: "triple(Instance, 'recipe://rating', Rating), Rating > 4" })
51
- * static async topRated(perspective: PerspectiveProxy): Promise<Recipe[]> { return [] }
52
- * }
53
- * ```
54
- *
55
- * @param {Object} [options] - Query options
56
- * @param {object} [options.where] - Object with property-value pairs to match
57
- * @param {string} [options.prologCondition] - Custom Prolog condition for more complex queries
26
+ * Retrieve property metadata for a given class constructor.
27
+ * Walks the prototype chain so subclass decorators compose with parent decorators.
28
+ */
29
+ export declare function getPropertiesMetadata(ctor: Function): Record<string, PropertyMetadataEntry>;
30
+ /**
31
+ * Retrieve relation metadata for a given class constructor.
32
+ * Walks the prototype chain so subclass decorators compose with parent decorators.
33
+ */
34
+ export declare function getRelationsMetadata(ctor: Function): Record<string, RelationMetadataEntry>;
35
+ /**
36
+ * Programmatically register property metadata for a given constructor.
37
+ * Used by `fromJSONSchema()` and other dynamic model builders.
38
+ */
39
+ export declare function setPropertyRegistryEntry(ctor: Function, propName: string, meta: PropertyMetadataEntry & {
40
+ writable?: boolean;
41
+ }): void;
42
+ /**
43
+ * Programmatically register relation metadata for a given constructor.
44
+ * Used by `fromJSONSchema()` and other dynamic model builders.
45
+ */
46
+ export declare function setRelationRegistryEntry(ctor: Function, relName: string, meta: RelationMetadataEntry): void;
47
+ /**
48
+ * Interface for any class that looks like an Ad4mModel (used in circular-ref-safe typings).
58
49
  */
59
- export declare function InstanceQuery(options?: InstanceQueryParams): <T>(target: T, key: keyof T, descriptor: PropertyDescriptor) => void;
50
+ export interface Ad4mModelLike {
51
+ new (...args: any[]): any;
52
+ className?: string;
53
+ generateSDNA?: () => any;
54
+ generateSHACL?: () => any;
55
+ }
56
+ /**
57
+ * Convert a model instance to a plain serializable object.
58
+ * Reads the property metadata and extracts values from the instance.
59
+ */
60
+ export declare function instanceToSerializable(instance: any): Record<string, any>;
61
+ /**
62
+ * Generate a random identifier string (lowercase alpha).
63
+ * Generate a random identifier string of the given length (lowercase alpha).
64
+ */
65
+ export declare function makeRandomId(length: number): string;
66
+ export declare class PerspectiveAction {
67
+ action: string;
68
+ source: string;
69
+ predicate: string;
70
+ target: string;
71
+ }
72
+ export declare function addLink(source: string, predicate: string, target: string): PerspectiveAction;
73
+ export declare function hasLink(predicate: string): string;
60
74
  export interface PropertyOptions {
61
75
  /**
62
76
  * The predicate of the property. All properties must have this option.
@@ -71,9 +85,10 @@ export interface PropertyOptions {
71
85
  */
72
86
  required?: boolean;
73
87
  /**
74
- * Indicates whether the property is writable. If true, a setter will be available in the prolog engine.
88
+ * Indicates whether the property is read-only. If true, no setter will be generated.
89
+ * Defaults to false (property is writable).
75
90
  */
76
- writable?: boolean;
91
+ readOnly?: boolean;
77
92
  /**
78
93
  * The language used to store the property. Can be the default `Literal` Language or a custom language address.
79
94
  */
@@ -104,83 +119,24 @@ export interface PropertyOptions {
104
119
  transform?: (value: any) => any;
105
120
  }
106
121
  /**
107
- * Decorator for defining optional properties on model classes.
122
+ * Convenience decorator for defining optional (not required) properties.
108
123
  *
109
124
  * @category Decorators
110
125
  *
111
126
  * @description
112
- * The most flexible property decorator that allows you to define properties with full control over:
113
- * - Whether the property is required
114
- * - Whether the property is writable
115
- * - How values are stored and retrieved
116
- * - Custom getter/setter logic
117
- * - Local vs network storage
118
- *
119
- * Both @Property and @ReadOnly are specialized versions of @Optional with preset configurations.
127
+ * Equivalent to `@Property` but defaults `required` to `false` and does not
128
+ * apply `resolveLanguage` or `initial` defaults. Use this when a property
129
+ * may or may not have a value, and you want full control over its configuration.
120
130
  *
121
131
  * @example
122
132
  * ```typescript
123
133
  * class Recipe extends Ad4mModel {
124
- * // Basic optional property
125
- * @Optional({
126
- * through: "recipe://description"
127
- * })
134
+ * @Optional({ through: "recipe://description" })
128
135
  * description?: string;
129
- *
130
- * // Optional property with custom initial value
131
- * @Optional({
132
- * through: "recipe://status",
133
- * initial: "recipe://draft",
134
- * required: true
135
- * })
136
- * status: string = "";
137
- *
138
- * // Read-only property with custom getter
139
- * @Optional({
140
- * through: "recipe://rating",
141
- * writable: false,
142
- * getter: `
143
- * findall(Rating, triple(Base, "recipe://user_rating", Rating), Ratings),
144
- * sum_list(Ratings, Sum),
145
- * length(Ratings, Count),
146
- * Value is Sum / Count
147
- * `
148
- * })
149
- * averageRating: number = 0;
150
- *
151
- * // Property that resolves to a Literal and is stored locally
152
- * @Optional({
153
- * through: "recipe://notes",
154
- * resolveLanguage: "literal",
155
- * local: true
156
- * })
157
- * notes?: string;
158
- *
159
- * // Property with custom getter and setter logic
160
- * @Optional({
161
- * through: "recipe://ingredients",
162
- * getter: `
163
- * triple(Base, "recipe://ingredients", RawValue),
164
- * atom_json_term(RawValue, Value)
165
- * `,
166
- * setter: `
167
- * atom_json_term(Value, JsonValue),
168
- * Actions = [{"action": "setSingleTarget", "source": "this", "predicate": "recipe://ingredients", "target": JsonValue}]
169
- * `
170
- * })
171
- * ingredients: string[] = [];
172
136
  * }
173
137
  * ```
174
138
  *
175
- * @param {PropertyOptions} opts - Property configuration options
176
- * @param {string} opts.through - The predicate URI for the property
177
- * @param {string} [opts.initial] - Initial value (required if property is required)
178
- * @param {boolean} [opts.required] - Whether the property must have a value
179
- * @param {boolean} [opts.writable=true] - Whether the property can be modified
180
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
181
- * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
182
- * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
183
- * @param {boolean} [opts.local] - Whether the property should only be stored locally
139
+ * @param {PropertyOptions} opts - Property configuration (same options as @Property)
184
140
  */
185
141
  export declare function Optional(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
186
142
  export interface FlagOptions {
@@ -247,106 +203,7 @@ export interface FlagOptions {
247
203
  * @param {string} opts.value - The fixed value for the flag
248
204
  */
249
205
  export declare function Flag(opts: FlagOptions): <T>(target: T, key: keyof T) => void;
250
- interface WhereOptions {
251
- isInstance?: any;
252
- prologCondition?: string;
253
- condition?: string;
254
- }
255
- export interface CollectionOptions {
256
- /**
257
- * The predicate of the property. All properties must have this option.
258
- */
259
- through: string;
260
- /**
261
- * An object representing the WHERE clause of the query.
262
- */
263
- where?: WhereOptions;
264
- /**
265
- * Custom SurrealQL getter to resolve the collection values. Use this for custom graph traversals.
266
- * The expression can reference 'Base' which will be replaced with the instance's base expression.
267
- * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)"
268
- */
269
- getter?: string;
270
- /**
271
- * 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.
272
- */
273
- local?: boolean;
274
- }
275
- /**
276
- * Decorator for defining collections on model classes.
277
- *
278
- * @category Decorators
279
- *
280
- * @description
281
- * Defines a property that represents a collection of values linked to the model instance.
282
- * Collections are always arrays and support operations for adding, removing, and setting values.
283
- *
284
- * For each collection property, the following methods are automatically generated:
285
- * - `addX(value)` - Add a value to the collection
286
- * - `removeX(value)` - Remove a value from the collection
287
- * - `setCollectionX(values)` - Replace all values in the collection
288
- *
289
- * Where X is the capitalized property name.
290
- *
291
- * Collections can be filtered using the `where` option to only include values that:
292
- * - Are instances of a specific model class
293
- * - Match a custom Prolog condition
294
- *
295
- * @example
296
- * ```typescript
297
- * class Recipe extends Ad4mModel {
298
- * // Basic collection of ingredients
299
- * @Collection({
300
- * through: "recipe://ingredient"
301
- * })
302
- * ingredients: string[] = [];
303
- *
304
- * // Collection that only includes instances of another model
305
- * @Collection({
306
- * through: "recipe://comment",
307
- * where: { isInstance: Comment }
308
- * })
309
- * comments: string[] = [];
310
- *
311
- * // Collection with custom Prolog filter condition
312
- * @Collection({
313
- * through: "recipe://step",
314
- * where: { prologCondition: `triple(Target, "step://order", Order), Order < 3` }
315
- * })
316
- * firstSteps: string[] = [];
317
- *
318
- * // Collection with custom SurrealDB filter condition
319
- * @Collection({
320
- * through: "recipe://entries",
321
- * where: { condition: `WHERE in.uri = Target AND predicate = 'recipe://has_ingredient' AND out.uri = 'recipe://test')`
322
- * })
323
- * ingredients: string[] = [];
324
- *
325
- * // Local-only collection not shared with network
326
- * @Collection({
327
- * through: "recipe://note",
328
- * local: true
329
- * })
330
- * privateNotes: string[] = [];
331
- * }
332
- *
333
- * // Using the generated methods:
334
- * const recipe = new Recipe(perspective);
335
- * await recipe.addIngredients("ingredient://flour");
336
- * await recipe.removeIngredients("ingredient://sugar");
337
- * await recipe.setCollectionIngredients(["ingredient://butter", "ingredient://eggs"]);
338
- * ```
339
- *
340
- * @param {CollectionOptions} opts - Collection configuration
341
- * @param {string} opts.through - The predicate URI for collection links
342
- * @param {WhereOptions} [opts.where] - Filter conditions for collection values
343
- * @param {any} [opts.where.isInstance] - Model class to filter instances by
344
- * @param {string} [opts.where.prologCondition] - Custom Prolog condition for filtering
345
- * @param {boolean} [opts.local] - Whether collection links are stored locally only
346
- */
347
- export declare function Collection(opts: CollectionOptions): <T>(target: T, key: keyof T) => void;
348
- export declare function makeRandomPrologAtom(length: number): string;
349
- export interface ModelOptionsOptions {
206
+ export interface ModelConfig {
350
207
  /**
351
208
  * The name of the entity.
352
209
  */
@@ -364,13 +221,13 @@ export interface ModelOptionsOptions {
364
221
  *
365
222
  * This decorator:
366
223
  * - Registers the class with a unique name in the AD4M system
367
- * - Generates the necessary SDNA code for the model's properties and collections
368
- * - Enables the use of other model decorators (@Property, @Collection, etc.)
224
+ * - Generates the necessary SDNA code for the model's properties and relations
225
+ * - Enables the use of other model decorators (@Property, @HasMany, etc.)
369
226
  * - Provides static query methods through the Ad4mModel base class
370
227
  *
371
228
  * @example
372
229
  * ```typescript
373
- * @ModelOptions({ name: "Recipe" })
230
+ * @Model({ name: "Recipe" })
374
231
  * class Recipe extends Ad4mModel {
375
232
  * @Property({
376
233
  * through: "recipe://name",
@@ -378,7 +235,7 @@ export interface ModelOptionsOptions {
378
235
  * })
379
236
  * name: string = "";
380
237
  *
381
- * @Collection({ through: "recipe://ingredient" })
238
+ * @HasMany({ through: "recipe://ingredient" })
382
239
  * ingredients: string[] = [];
383
240
  *
384
241
  * // Static query methods from Ad4mModel:
@@ -403,60 +260,68 @@ export interface ModelOptionsOptions {
403
260
  * await perspective.ensureSDNASubjectClass(Recipe);
404
261
  * ```
405
262
  *
406
- * @param {ModelOptionsOptions} opts - Model configuration
263
+ * @param {ModelConfig} opts - Model configuration
407
264
  * @param {string} opts.name - Unique name for the model class in AD4M
408
265
  */
409
- export declare function ModelOptions(opts: ModelOptionsOptions): (target: any) => void;
266
+ export declare function Model(opts: ModelConfig): (target: any) => void;
410
267
  /**
411
- * Decorator for defining required and writable properties on model classes.
268
+ * The primary property decorator for AD4M model classes.
412
269
  *
413
270
  * @category Decorators
414
271
  *
415
272
  * @description
416
- * A convenience decorator that defines a required property that must have an initial value and is writable by default.
417
- * This is equivalent to using @Optional with `required: true` and `writable: true`.
273
+ * The core property decorator with smart defaults. All other property decorators
274
+ * (@Optional, @ReadOnly) are thin wrappers that adjust these defaults.
418
275
  *
419
- * Properties defined with this decorator:
420
- * - Must have a value (required)
421
- * - Can be modified after creation (writable)
422
- * - Default to "literal://string:uninitialized" if no initial value is provided
276
+ * Smart defaults (all overridable):
277
+ * - `required` → `false`
278
+ * - `readOnly` → `false`
279
+ * - `resolveLanguage` → `"literal"`
280
+ * - `initial` → `undefined` (no link created until a value is explicitly set)
281
+ *
282
+ * Properties are optional by default. When a model instance is created without
283
+ * providing a value for an optional property, no link is added to the graph.
284
+ * Set `required: true` explicitly when a property must always be present (this
285
+ * also adds a `"literal://string:uninitialized"` sentinel as the initial value
286
+ * so that the SDNA constructor creates a placeholder link).
423
287
  *
424
288
  * @example
425
289
  * ```typescript
426
290
  * class User extends Ad4mModel {
427
- * // Basic required property with default initial value
291
+ * // Optional property (default) — no link created until a value is set
428
292
  * @Property({
429
293
  * through: "user://name"
430
294
  * })
431
295
  * name: string = "";
432
296
  *
433
- * // Required property with custom initial value
297
+ * // Explicitly required property with sentinel initial value
434
298
  * @Property({
435
299
  * through: "user://status",
436
- * initial: "user://active"
300
+ * required: true
437
301
  * })
438
302
  * status: string = "";
439
303
  *
440
- * // Required property with literal resolution
304
+ * // Required property with custom initial value
441
305
  * @Property({
442
- * through: "user://bio",
443
- * resolveLanguage: "literal"
306
+ * through: "user://role",
307
+ * required: true,
308
+ * initial: "user://member"
444
309
  * })
445
- * bio: string = "";
310
+ * role: string = "";
446
311
  *
447
- * // Required property with custom getter/setter
312
+ * // Optional property with literal resolution
448
313
  * @Property({
449
- * through: "user://age",
450
- * getter: `triple(Base, "user://birthYear", Year), Value is 2024 - Year`,
451
- * setter: `Year is 2024 - Value, Actions = [{"action": "setSingleTarget", "source": "this", "predicate": "user://birthYear", "target": Year}]`
314
+ * through: "user://bio",
315
+ * resolveLanguage: "literal"
452
316
  * })
453
- * age: number = 0;
317
+ * bio: string = "";
454
318
  * }
455
319
  * ```
456
320
  *
457
321
  * @param {PropertyOptions} opts - Property configuration
458
322
  * @param {string} opts.through - The predicate URI for the property
459
- * @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized")
323
+ * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
324
+ * @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized" when required)
460
325
  * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
461
326
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
462
327
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
@@ -469,8 +334,8 @@ export declare function Property(opts: PropertyOptions): <T>(target: T, key: key
469
334
  * @category Decorators
470
335
  *
471
336
  * @description
472
- * A convenience decorator that defines a property that can only be read and cannot be modified after initialization.
473
- * This is equivalent to using @Optional with `writable: false`.
337
+ * A convenience decorator that defines a read-only property.
338
+ * Equivalent to `@Property` with `readOnly: true`.
474
339
  *
475
340
  * Read-only properties are ideal for:
476
341
  * - Computed or derived values
@@ -519,4 +384,151 @@ export declare function Property(opts: PropertyOptions): <T>(target: T, key: key
519
384
  * @param {boolean} [opts.local] - Whether the property should only be stored locally
520
385
  */
521
386
  export declare function ReadOnly(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
522
- export {};
387
+ /**
388
+ * Options for relation decorators (@HasMany, @HasOne, @BelongsToOne, @BelongsToMany).
389
+ */
390
+ export interface RelationOptions {
391
+ /** The predicate URI used to link the two models */
392
+ through: string;
393
+ /** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string relations. */
394
+ target?: () => Ad4mModelLike;
395
+ /**
396
+ * Custom SurrealQL getter to resolve the relation values. Use this for custom graph traversals.
397
+ * The expression can reference 'Base' which will be replaced with the instance's base expression.
398
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].out.uri)"
399
+ */
400
+ getter?: string;
401
+ /** Whether the link is stored locally (not shared on the network) */
402
+ local?: boolean;
403
+ }
404
+ /**
405
+ * Utility type that describes the auto-generated helper methods for a HasMany
406
+ * relation. For a property named `comments` on a class `Post`, the following
407
+ * methods will be available on instances:
408
+ *
409
+ * post.addComment(value)
410
+ * post.removeComment(value)
411
+ * post.setComment(values)
412
+ */
413
+ export type HasManyMethods<Keys extends string> = {
414
+ [K in Keys as `add${Capitalize<K>}`]: (value: string | {
415
+ id: string;
416
+ }, batchId?: string) => Promise<void>;
417
+ } & {
418
+ [K in Keys as `remove${Capitalize<K>}`]: (value: string | {
419
+ id: string;
420
+ }, batchId?: string) => Promise<void>;
421
+ } & {
422
+ [K in Keys as `set${Capitalize<K>}`]: (values: (string | {
423
+ id: string;
424
+ })[], batchId?: string) => Promise<void>;
425
+ };
426
+ /**
427
+ * Decorator for defining a one-to-many relation.
428
+ *
429
+ * @category Decorators
430
+ *
431
+ * @description
432
+ * Declares that the decorated property is an array of related model instances.
433
+ * Under the hood it registers the relation in the relation registry and also
434
+ * creates the corresponding relation entry so that the SDNA / SHACL
435
+ * generators continue to emit the correct subject-class code.
436
+ *
437
+ * Supports two calling conventions:
438
+ * ```typescript
439
+ * // Options-object style
440
+ * @HasMany({ through: "post://comment", target: () => Comment })
441
+ *
442
+ * // Target-first shorthand
443
+ * @HasMany(() => Comment, { through: "post://comment" })
444
+ * ```
445
+ *
446
+ * @example
447
+ * ```typescript
448
+ * @Model({ name: "Post" })
449
+ * class Post extends Ad4mModel {
450
+ * @HasMany(() => Comment, { through: "post://comment" })
451
+ * comments: string[] = [];
452
+ * }
453
+ * ```
454
+ */
455
+ export declare function HasMany(opts: RelationOptions): PropertyDecorator;
456
+ export declare function HasMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
457
+ /**
458
+ * Decorator for defining a one-to-one relation (owning side).
459
+ *
460
+ * @category Decorators
461
+ *
462
+ * @description
463
+ * Declares that the decorated property holds a single related model instance.
464
+ * The owning side manages the link.
465
+ *
466
+ * Supports two calling conventions:
467
+ * ```typescript
468
+ * @HasOne({ through: "post://author", target: () => Author })
469
+ * @HasOne(() => Author, { through: "post://author" })
470
+ * ```
471
+ *
472
+ * @example
473
+ * ```typescript
474
+ * @Model({ name: "Post" })
475
+ * class Post extends Ad4mModel {
476
+ * @HasOne(() => Author, { through: "post://author" })
477
+ * author: string = "";
478
+ * }
479
+ * ```
480
+ */
481
+ export declare function HasOne(opts: RelationOptions): PropertyDecorator;
482
+ export declare function HasOne(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
483
+ /**
484
+ * Decorator for defining the inverse side of a one-to-one relation.
485
+ *
486
+ * @category Decorators
487
+ *
488
+ * @description
489
+ * Declares the non-owning (inverse) side of a one-to-one relationship.
490
+ * The property is read-only since the owning side manages the link.
491
+ *
492
+ * Supports two calling conventions:
493
+ * ```typescript
494
+ * @BelongsToOne({ through: "post://author", target: () => Post })
495
+ * @BelongsToOne(() => Post, { through: "post://author" })
496
+ * ```
497
+ *
498
+ * @example
499
+ * ```typescript
500
+ * @Model({ name: "Author" })
501
+ * class Author extends Ad4mModel {
502
+ * @BelongsToOne(() => Post, { through: "post://author" })
503
+ * post: string = "";
504
+ * }
505
+ * ```
506
+ */
507
+ export declare function BelongsToOne(opts: RelationOptions): PropertyDecorator;
508
+ export declare function BelongsToOne(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
509
+ /**
510
+ * Decorator for defining the inverse side of a many-to-many relation.
511
+ *
512
+ * @category Decorators
513
+ *
514
+ * @description
515
+ * Declares the non-owning (inverse) side of a many-to-many relationship.
516
+ * The property is a read-only relation since the owning side manages links.
517
+ *
518
+ * Supports two calling conventions:
519
+ * ```typescript
520
+ * @BelongsToMany({ through: "post://tag", target: () => Post })
521
+ * @BelongsToMany(() => Post, { through: "post://tag" })
522
+ * ```
523
+ *
524
+ * @example
525
+ * ```typescript
526
+ * @Model({ name: "Tag" })
527
+ * class Tag extends Ad4mModel {
528
+ * @BelongsToMany(() => Post, { through: "post://tag" })
529
+ * posts: string[] = [];
530
+ * }
531
+ * ```
532
+ */
533
+ export declare function BelongsToMany(opts: RelationOptions): PropertyDecorator;
534
+ export declare function BelongsToMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;