@coasys/ad4m 0.12.0-rc1-dev.2 → 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 (153) hide show
  1. package/jest.config.js +10 -3
  2. package/lib/index.cjs +6872 -5886
  3. package/lib/index.js +6868 -5874
  4. package/lib/src/Ad4mClient.d.ts +9 -16
  5. package/lib/src/Ad4mClient.js +46 -25
  6. package/lib/src/Literal.d.ts +1 -2
  7. package/lib/src/Literal.js +38 -35
  8. package/lib/src/SmartLiteral.d.ts +1 -2
  9. package/lib/src/SmartLiteral.js +30 -15
  10. package/lib/src/agent/AgentClient.d.ts +1 -4
  11. package/lib/src/agent/AgentClient.js +79 -99
  12. package/lib/src/ai/AIClient.d.ts +1 -2
  13. package/lib/src/ai/AIClient.js +224 -220
  14. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  15. package/lib/src/expression/ExpressionClient.js +73 -86
  16. package/lib/src/index.d.ts +1 -1
  17. package/lib/src/index.js +1 -1
  18. package/lib/src/language/LanguageClient.d.ts +1 -1
  19. package/lib/src/language/LanguageClient.js +52 -52
  20. package/lib/src/model/Ad4mModel.d.ts +1351 -144
  21. package/lib/src/model/Ad4mModel.js +3737 -228
  22. package/lib/src/model/Ad4mModel.test.js +522 -979
  23. package/lib/src/model/Subject.d.ts +3 -3
  24. package/lib/src/model/Subject.js +25 -25
  25. package/lib/src/model/decorators.d.ts +444 -100
  26. package/lib/src/model/decorators.js +686 -321
  27. package/lib/src/model/util.d.ts +6 -6
  28. package/lib/src/model/util.js +24 -24
  29. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +1 -5
  30. package/lib/src/neighbourhood/NeighbourhoodClient.js +179 -242
  31. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +1 -2
  32. package/lib/src/neighbourhood/NeighbourhoodProxy.js +28 -13
  33. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +5 -1
  34. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  35. package/lib/src/perspectives/PerspectiveClient.js +240 -316
  36. package/lib/src/perspectives/PerspectiveProxy.d.ts +99 -61
  37. package/lib/src/perspectives/PerspectiveProxy.js +485 -832
  38. package/lib/src/runtime/RuntimeClient.d.ts +1 -5
  39. package/lib/src/runtime/RuntimeClient.js +238 -412
  40. package/lib/src/shacl/SHACLFlow.test.js +105 -164
  41. package/lib/src/shacl/SHACLShape.d.ts +12 -17
  42. package/lib/src/shacl/SHACLShape.js +115 -128
  43. package/lib/src/shacl/SHACLShape.test.js +176 -244
  44. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  45. package/lib/src/shims/type-graphql.d.ts +32 -0
  46. package/lib/src/src/Ad4mClient.d.ts +28 -0
  47. package/lib/src/src/Address.d.ts +1 -0
  48. package/lib/src/src/DID.d.ts +1 -0
  49. package/lib/src/src/Exception.d.ts +7 -0
  50. package/lib/src/src/Literal.d.ts +7 -0
  51. package/lib/src/src/PubSub.d.ts +17 -0
  52. package/lib/src/src/SmartLiteral.d.ts +12 -0
  53. package/lib/src/src/agent/Agent.d.ts +110 -0
  54. package/lib/src/src/agent/AgentClient.d.ts +62 -0
  55. package/lib/src/src/agent/AgentResolver.d.ts +30 -0
  56. package/lib/src/src/agent/AgentStatus.d.ts +8 -0
  57. package/lib/src/src/ai/AIClient.d.ts +32 -0
  58. package/lib/src/src/ai/AIResolver.d.ts +75 -0
  59. package/lib/src/src/ai/Tasks.d.ts +37 -0
  60. package/lib/src/src/buildSchema.d.ts +1 -0
  61. package/lib/src/src/expression/Expression.d.ts +28 -0
  62. package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
  63. package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
  64. package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
  65. package/lib/src/src/index.d.ts +35 -0
  66. package/lib/src/src/jestSetup.d.ts +1 -0
  67. package/lib/src/src/language/Icon.d.ts +4 -0
  68. package/lib/src/src/language/Language.d.ts +206 -0
  69. package/lib/src/src/language/LanguageClient.d.ts +17 -0
  70. package/lib/src/src/language/LanguageContext.d.ts +37 -0
  71. package/lib/src/src/language/LanguageHandle.d.ts +9 -0
  72. package/lib/src/src/language/LanguageMeta.d.ts +35 -0
  73. package/lib/src/src/language/LanguageRef.d.ts +6 -0
  74. package/lib/src/src/language/LanguageResolver.d.ts +19 -0
  75. package/lib/src/src/links/Links.d.ts +39 -0
  76. package/lib/src/src/links/Links.test.d.ts +1 -0
  77. package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
  78. package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
  79. package/lib/src/src/model/Subject.d.ts +25 -0
  80. package/lib/src/src/model/decorators.d.ts +545 -0
  81. package/lib/src/src/model/util.d.ts +12 -0
  82. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
  83. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
  84. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
  85. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  86. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
  87. package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
  88. package/lib/src/src/perspectives/Perspective.d.ts +38 -0
  89. package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
  90. package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
  91. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
  92. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
  93. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
  94. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
  95. package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
  96. package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
  97. package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
  98. package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
  99. package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
  100. package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
  101. package/lib/src/src/typeDefs.d.ts +1 -0
  102. package/lib/src/src/unwrapApolloResult.d.ts +2 -0
  103. package/lib/src/src/utils.d.ts +25 -0
  104. package/lib/src/utils.d.ts +0 -8
  105. package/lib/src/utils.js +7 -21
  106. package/package.json +15 -14
  107. package/src/Ad4mClient.test.ts +1315 -1564
  108. package/src/Ad4mClient.ts +54 -55
  109. package/src/Literal.test.ts +26 -45
  110. package/src/Literal.ts +66 -82
  111. package/src/SmartLiteral.ts +58 -74
  112. package/src/agent/AgentClient.ts +99 -144
  113. package/src/ai/AIClient.ts +359 -409
  114. package/src/expression/ExpressionClient.ts +96 -142
  115. package/src/index.ts +1 -1
  116. package/src/language/LanguageClient.ts +113 -137
  117. package/src/model/Ad4mModel.test.ts +616 -1114
  118. package/src/model/Ad4mModel.ts +4361 -451
  119. package/src/model/Subject.ts +159 -0
  120. package/src/model/decorators.ts +1168 -667
  121. package/src/model/util.ts +54 -53
  122. package/src/neighbourhood/NeighbourhoodClient.ts +266 -392
  123. package/src/neighbourhood/NeighbourhoodProxy.test.ts +7 -3
  124. package/src/neighbourhood/NeighbourhoodProxy.ts +40 -58
  125. package/src/perspectives/PerspectiveClient.ts +540 -779
  126. package/src/perspectives/PerspectiveProxy.ts +2067 -2860
  127. package/src/runtime/RuntimeClient.ts +476 -775
  128. package/src/shacl/SHACLFlow.test.ts +129 -196
  129. package/src/shacl/SHACLShape.test.ts +190 -284
  130. package/src/shacl/SHACLShape.ts +200 -224
  131. package/src/utils.ts +17 -31
  132. package/tsconfig.json +10 -9
  133. package/src/model/IMPROVEMENTS.md +0 -482
  134. package/src/model/PREDICATE_COLLISION_FIX.md +0 -651
  135. package/src/model/README.md +0 -317
  136. package/src/model/SHACL_MUTATION_DECOUPLING.md +0 -356
  137. package/src/model/SUBSCRIPTION_STRATEGY.md +0 -317
  138. package/src/model/TC39_STAGE_3_DECORATORS.md +0 -609
  139. package/src/model/mutation.ts +0 -461
  140. package/src/model/parentUtils.ts +0 -91
  141. package/src/model/prolog/generatePrologFacts.ts +0 -176
  142. package/src/model/prolog/index.ts +0 -1
  143. package/src/model/query/ModelQueryBuilder.ts +0 -173
  144. package/src/model/query/fetchInstance.ts +0 -181
  145. package/src/model/query/hydration.ts +0 -273
  146. package/src/model/query/operations.ts +0 -510
  147. package/src/model/query/snapshot.ts +0 -126
  148. package/src/model/query/surrealCompiler.ts +0 -376
  149. package/src/model/schema/fromJSONSchema.ts +0 -411
  150. package/src/model/schema/metadata.ts +0 -148
  151. package/src/model/subscription.ts +0 -307
  152. package/src/model/transaction.ts +0 -60
  153. package/src/model/types.ts +0 -207
@@ -1,22 +1,68 @@
1
- export declare const propertyRegistry: WeakMap<Function, Record<string, any>>;
2
- export declare const relationRegistry: WeakMap<Function, Record<string, any>>;
3
- /** Returns the own + inherited property metadata for a given constructor, with own values winning. */
4
- export declare function getPropertiesMetadata(ctor: Function): Record<string, any>;
5
- /** Returns the own + inherited relation metadata for a given constructor, with own values winning. */
6
- export declare function getRelationsMetadata(ctor: Function): Record<string, any>;
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 model class thunk. Optional for untyped string relations. */
11
+ target?: () => Ad4mModelLike;
12
+ kind: 'hasMany' | 'hasOne' | 'belongsToOne' | 'belongsToMany';
13
+ /**
14
+ * Maximum number of related instances.
15
+ * Set automatically: 1 for `@HasOne`/`@BelongsToOne`, undefined (unlimited) for `*Many`.
16
+ */
17
+ maxCount?: number;
18
+ local?: boolean;
19
+ /**
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.
22
+ */
23
+ getter?: string;
24
+ }
7
25
  /**
8
- * Builds a plain, JSON-safe object from a model instance.
9
- *
10
- * Only includes `id` (if present) and decorator-registered \@Property keys.
11
- * All other own enumerable properties are stripped — most importantly the
12
- * TypeScript `private _perspective` field which is stored as a regular
13
- * enumerable property at runtime and holds a PerspectiveProxy whose Apollo
14
- * InMemoryCache creates a circular reference in `JSON.stringify`.
15
- *
16
- * Falls back to a shallow spread for plain objects with no registered props
17
- * (e.g. raw link objects passed through before model hydration).
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).
18
49
  */
19
- export declare function instanceToSerializable(instance: any): Record<string, unknown>;
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;
20
66
  export declare class PerspectiveAction {
21
67
  action: string;
22
68
  source: string;
@@ -31,14 +77,7 @@ export interface PropertyOptions {
31
77
  */
32
78
  through?: string;
33
79
  /**
34
- * The initial value written by the SHACL constructor action.
35
- *
36
- * For non-readOnly properties this is **optional** — Ad4mModel
37
- * automatically derives a placeholder and overwrites it with the real
38
- * instance field value when `save()` is called. Only set this explicitly
39
- * when you need a specific non-literal default URI (e.g. a custom
40
- * `resolveLanguage` address) or want a sentinel value if the property
41
- * is never set.
80
+ * The initial value of the property. Required if the property is marked as required.
42
81
  */
43
82
  initial?: string;
44
83
  /**
@@ -46,20 +85,22 @@ export interface PropertyOptions {
46
85
  */
47
86
  required?: boolean;
48
87
  /**
49
- * Marks the property as read-only — no setter action will be generated and
50
- * the property cannot be updated via the model layer. Defaults to false
51
- * (writable) when `through` is set.
88
+ * Indicates whether the property is read-only. If true, no setter will be generated.
89
+ * Defaults to false (property is writable).
52
90
  */
53
91
  readOnly?: boolean;
54
92
  /**
55
- * The language used to resolve the stored expression into a JS value.
56
- *
57
- * Omitting this (the common case) is equivalent to `"literal"` — scalar values
58
- * (string / number / boolean) are encoded as `literal://` URIs automatically.
59
- * Only specify this when you need a non-literal language (e.g. a custom IPFS
60
- * language address) or want to be explicit for documentation purposes.
93
+ * The language used to store the property. Can be the default `Literal` Language or a custom language address.
61
94
  */
62
95
  resolveLanguage?: string;
96
+ /**
97
+ * Custom Prolog getter to get the value of the property. If not provided, the default getter will be used.
98
+ */
99
+ prologGetter?: string;
100
+ /**
101
+ * Custom Prolog setter to set the value of the property. Only available if the property is writable.
102
+ */
103
+ prologSetter?: string;
63
104
  /**
64
105
  * Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
65
106
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
@@ -76,26 +117,28 @@ export interface PropertyOptions {
76
117
  * The function takes the raw value as input and returns the transformed value.
77
118
  */
78
119
  transform?: (value: any) => any;
79
- /**
80
- * Indicates that this property is a @Flag — a fixed predicate/value pair written
81
- * once by the createSubject constructor action and never changed. Flag properties
82
- * are immutable and will be skipped during updates.
83
- */
84
- flag?: boolean;
85
120
  }
86
121
  /**
87
- * Declares a typed property backed by a single link triple in the perspective.
122
+ * Convenience decorator for defining optional (not required) properties.
123
+ *
124
+ * @category Decorators
125
+ *
126
+ * @description
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.
130
+ *
131
+ * @example
132
+ * ```typescript
133
+ * class Recipe extends Ad4mModel {
134
+ * @Optional({ through: "recipe://description" })
135
+ * description?: string;
136
+ * }
137
+ * ```
88
138
  *
89
- * @param opts.through - Predicate URI (required)
90
- * @param opts.initial - Default value written by the constructor action (auto-derived for non-readOnly properties; only needed for custom URIs)
91
- * @param opts.required - Adds `sh:minCount 1` to the SHACL shape
92
- * @param opts.readOnly - Skips setter generation; property cannot be updated after creation (default: false)
93
- * @param opts.resolveLanguage - Language for value resolution (`"literal"`, etc.)
94
- * @param opts.local - Store only in local perspective, not shared with the network
95
- * @param opts.getter - Custom SurrealQL expression for computed / read-only properties
96
- * @param opts.transform - Post-fetch transform applied to the raw value
139
+ * @param {PropertyOptions} opts - Property configuration (same options as @Property)
97
140
  */
98
- export declare function Property(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
141
+ export declare function Optional(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
99
142
  export interface FlagOptions {
100
143
  /**
101
144
  * The predicate of the property. All properties must have this option.
@@ -107,84 +150,385 @@ export interface FlagOptions {
107
150
  value: string;
108
151
  }
109
152
  /**
110
- * Immutable type-marker property: written once at creation and never modified.
153
+ * Decorator for defining flags on model classes.
154
+ *
155
+ * @category Decorators
156
+ *
157
+ * @description
158
+ * A specialized property decorator for defining immutable type flags or markers on model instances.
159
+ * Flags are always required properties with a fixed value that cannot be changed after creation.
111
160
  *
112
- * Use for type-discrimination predicates (e.g. `ad4m://type = "ad4m://message"`).
113
- * For mutable data prefer `@Property`.
161
+ * Common uses for flags:
162
+ * - Type discrimination between different kinds of models
163
+ * - Marking models with specific capabilities or features
164
+ * - Versioning or compatibility markers
165
+ *
166
+ * Note: Use of Flag is discouraged unless you specifically need type-based filtering or
167
+ * discrimination between different kinds of models. For most cases, regular properties
168
+ * with @Property or @Optional are more appropriate.
114
169
  *
115
170
  * @example
116
171
  * ```typescript
117
- * @Flag({ through: "ad4m://type", value: "ad4m://message" })
118
- * type: string = "";
172
+ * class Message extends Ad4mModel {
173
+ * // Type flag to identify message models
174
+ * @Flag({
175
+ * through: "ad4m://type",
176
+ * value: "ad4m://message"
177
+ * })
178
+ * type: string = "";
179
+ *
180
+ * // Version flag for compatibility
181
+ * @Flag({
182
+ * through: "ad4m://version",
183
+ * value: "1.0.0"
184
+ * })
185
+ * version: string = "";
186
+ *
187
+ * // Feature flag
188
+ * @Flag({
189
+ * through: "message://feature",
190
+ * value: "message://encrypted"
191
+ * })
192
+ * feature: string = "";
193
+ * }
194
+ *
195
+ * // Later you can query for specific types:
196
+ * const messages = await Message.query(perspective)
197
+ * .where({ type: "ad4m://message" })
198
+ * .run();
119
199
  * ```
200
+ *
201
+ * @param {FlagOptions} opts - Flag configuration
202
+ * @param {string} opts.through - The predicate URI for the flag
203
+ * @param {string} opts.value - The fixed value for the flag
120
204
  */
121
205
  export declare function Flag(opts: FlagOptions): <T>(target: T, key: keyof T) => void;
122
- export interface RelationOptions {
206
+ export interface ModelConfig {
123
207
  /**
124
- * The predicate of the property. All properties must have this option.
208
+ * The name of the entity.
125
209
  */
210
+ name: string;
211
+ }
212
+ /**
213
+ * Decorator for defining model classes in AD4M.
214
+ *
215
+ * @category Decorators
216
+ *
217
+ * @description
218
+ * The root decorator that must be applied to any class that represents a model in AD4M.
219
+ * It registers the class as a Social DNA (SDNA) subject class and provides the infrastructure
220
+ * for storing and retrieving instances.
221
+ *
222
+ * This decorator:
223
+ * - Registers the class with a unique name in the AD4M system
224
+ * - Generates the necessary SDNA code for the model's properties and relations
225
+ * - Enables the use of other model decorators (@Property, @HasMany, etc.)
226
+ * - Provides static query methods through the Ad4mModel base class
227
+ *
228
+ * @example
229
+ * ```typescript
230
+ * @Model({ name: "Recipe" })
231
+ * class Recipe extends Ad4mModel {
232
+ * @Property({
233
+ * through: "recipe://name",
234
+ * resolveLanguage: "literal"
235
+ * })
236
+ * name: string = "";
237
+ *
238
+ * @HasMany({ through: "recipe://ingredient" })
239
+ * ingredients: string[] = [];
240
+ *
241
+ * // Static query methods from Ad4mModel:
242
+ * static async findByName(perspective: PerspectiveProxy, name: string) {
243
+ * return Recipe.query(perspective)
244
+ * .where({ name })
245
+ * .run();
246
+ * }
247
+ * }
248
+ *
249
+ * // Using the model:
250
+ * const recipe = new Recipe(perspective);
251
+ * recipe.name = "Chocolate Cake";
252
+ * await recipe.save();
253
+ *
254
+ * // Querying instances:
255
+ * const recipes = await Recipe.query(perspective)
256
+ * .where({ name: "Chocolate Cake" })
257
+ * .run();
258
+ *
259
+ * // Using with PerspectiveProxy:
260
+ * await perspective.ensureSDNASubjectClass(Recipe);
261
+ * ```
262
+ *
263
+ * @param {ModelConfig} opts - Model configuration
264
+ * @param {string} opts.name - Unique name for the model class in AD4M
265
+ */
266
+ export declare function Model(opts: ModelConfig): (target: any) => void;
267
+ /**
268
+ * The primary property decorator for AD4M model classes.
269
+ *
270
+ * @category Decorators
271
+ *
272
+ * @description
273
+ * The core property decorator with smart defaults. All other property decorators
274
+ * (@Optional, @ReadOnly) are thin wrappers that adjust these defaults.
275
+ *
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).
287
+ *
288
+ * @example
289
+ * ```typescript
290
+ * class User extends Ad4mModel {
291
+ * // Optional property (default) — no link created until a value is set
292
+ * @Property({
293
+ * through: "user://name"
294
+ * })
295
+ * name: string = "";
296
+ *
297
+ * // Explicitly required property with sentinel initial value
298
+ * @Property({
299
+ * through: "user://status",
300
+ * required: true
301
+ * })
302
+ * status: string = "";
303
+ *
304
+ * // Required property with custom initial value
305
+ * @Property({
306
+ * through: "user://role",
307
+ * required: true,
308
+ * initial: "user://member"
309
+ * })
310
+ * role: string = "";
311
+ *
312
+ * // Optional property with literal resolution
313
+ * @Property({
314
+ * through: "user://bio",
315
+ * resolveLanguage: "literal"
316
+ * })
317
+ * bio: string = "";
318
+ * }
319
+ * ```
320
+ *
321
+ * @param {PropertyOptions} opts - Property configuration
322
+ * @param {string} opts.through - The predicate URI for the property
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)
325
+ * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
326
+ * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
327
+ * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
328
+ * @param {boolean} [opts.local] - Whether the property should only be stored locally
329
+ */
330
+ export declare function Property(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
331
+ /**
332
+ * Decorator for defining read-only properties on model classes.
333
+ *
334
+ * @category Decorators
335
+ *
336
+ * @description
337
+ * A convenience decorator that defines a read-only property.
338
+ * Equivalent to `@Property` with `readOnly: true`.
339
+ *
340
+ * Read-only properties are ideal for:
341
+ * - Computed or derived values
342
+ * - Properties that should never change after creation
343
+ * - Properties that are set by the system
344
+ * - Properties that represent immutable data
345
+ *
346
+ * @example
347
+ * ```typescript
348
+ * class Post extends Ad4mModel {
349
+ * // Read-only property with custom getter for computed value
350
+ * @ReadOnly({
351
+ * through: "post://likes",
352
+ * getter: `findall(User, triple(Base, "post://liked_by", User), Users), length(Users, Value)`
353
+ * })
354
+ * likeCount: number = 0;
355
+ *
356
+ * // Read-only property for creation timestamp
357
+ * @ReadOnly({
358
+ * through: "post://created_at",
359
+ * initial: new Date().toISOString()
360
+ * })
361
+ * createdAt: string = "";
362
+ *
363
+ * // Read-only property that resolves to a Literal
364
+ * @ReadOnly({
365
+ * through: "post://author",
366
+ * resolveLanguage: "literal"
367
+ * })
368
+ * author: string = "";
369
+ *
370
+ * // Read-only property for system-managed data
371
+ * @ReadOnly({
372
+ * through: "post://version",
373
+ * initial: "1.0.0"
374
+ * })
375
+ * version: string = "";
376
+ * }
377
+ * ```
378
+ *
379
+ * @param {PropertyOptions} opts - Property configuration
380
+ * @param {string} opts.through - The predicate URI for the property
381
+ * @param {string} [opts.initial] - Initial value (if property should have one)
382
+ * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
383
+ * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
384
+ * @param {boolean} [opts.local] - Whether the property should only be stored locally
385
+ */
386
+ export declare function ReadOnly(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
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 */
126
392
  through: string;
393
+ /** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string relations. */
394
+ target?: () => Ad4mModelLike;
127
395
  /**
128
- * Custom SurrealQL getter to resolve the related values. Use this for custom graph traversals.
396
+ * Custom SurrealQL getter to resolve the relation values. Use this for custom graph traversals.
129
397
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
130
- * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)"
398
+ * Example: "(<-link[WHERE predicate = 'flux://has_reply'].out.uri)"
131
399
  */
132
400
  getter?: string;
133
- /**
134
- * 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.
135
- */
401
+ /** Whether the link is stored locally (not shared on the network) */
136
402
  local?: boolean;
137
403
  }
138
- /** Minimal structural type for Ad4mModel instances — used in mutator signatures to avoid circular imports. */
139
- export interface Ad4mModelLike {
140
- readonly id: string;
141
- }
142
404
  /**
143
- * Utility type that generates the runtime methods produced by \@HasMany / \@HasOne decorators.
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:
144
408
  *
145
- * For each relation property `foo`, the decorator generates:
146
- * - `addFoo(value)` — Add a value (string ID or model instance)
147
- * - `removeFoo(value)` — Remove a value
148
- * - `setFoo(values)` — Replace all values
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
+ * ```
149
445
  *
150
- * Pass a string union of your \@HasMany/\@HasOne property names and use interface merging:
151
446
  * @example
152
447
  * ```typescript
153
- * \@Model({ name: 'Post' })
154
- * export class Post extends Ad4mModel {
155
- * \@HasMany(() => Comment, { through: 'post://comment' })
156
- * comments: Comment[] = [];
448
+ * @Model({ name: "Post" })
449
+ * class Post extends Ad4mModel {
450
+ * @HasMany(() => Comment, { through: "post://comment" })
451
+ * comments: string[] = [];
157
452
  * }
158
- * export interface Post extends HasManyMethods<'comments'> {}
159
453
  * ```
160
454
  */
161
- export type HasManyMethods<Keys extends string> = {
162
- [K in Keys as `add${Capitalize<K>}`]: (value: string | Ad4mModelLike, batchId?: string) => Promise<void>;
163
- } & {
164
- [K in Keys as `remove${Capitalize<K>}`]: (value: string | Ad4mModelLike, batchId?: string) => Promise<void>;
165
- } & {
166
- [K in Keys as `set${Capitalize<K>}`]: (values: (string | Ad4mModelLike)[], batchId?: string) => Promise<void>;
167
- };
168
- export declare function HasMany(relatedModelOrOpts: (() => any) | RelationOptions, opts?: RelationOptions): <T>(target: T, key: keyof T) => void;
169
- export declare function HasOne(relatedModelOrOpts: (() => any) | RelationOptions, opts?: RelationOptions): <T>(target: T, key: keyof T) => void;
170
- export declare function BelongsToOne(relatedModel: () => any, opts: RelationOptions): <T>(target: T, key: keyof T) => void;
171
- export declare function BelongsToMany(relatedModel: () => any, opts: RelationOptions): <T>(target: T, key: keyof T) => void;
172
- export declare function makeRandomId(length: number): string;
173
- export interface ModelConfig {
174
- /**
175
- * The name of the entity.
176
- */
177
- name: string;
178
- }
455
+ export declare function HasMany(opts: RelationOptions): PropertyDecorator;
456
+ export declare function HasMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
179
457
  /**
180
- * Registers the class as an AD4M SDNA subject, enabling `Ad4mModel` static query methods.
458
+ * Decorator for defining a one-to-one relation (owning side).
459
+ *
460
+ * @category Decorators
181
461
  *
182
- * Must be applied to every class that extends `Ad4mModel`.
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
+ * ```
183
471
  *
184
472
  * @example
185
473
  * ```typescript
186
- * @Model({ name: "Recipe" })
187
- * class Recipe extends Ad4mModel { ... }
474
+ * @Model({ name: "Post" })
475
+ * class Post extends Ad4mModel {
476
+ * @HasOne(() => Author, { through: "post://author" })
477
+ * author: string = "";
478
+ * }
188
479
  * ```
189
480
  */
190
- export declare function Model(opts: ModelConfig): (target: any) => void;
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;