@coasys/ad4m 0.12.0-rc1-dev.1 → 0.12.0-rc1-dev.2

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 (128) hide show
  1. package/jest.config.js +4 -4
  2. package/lib/index.cjs +5999 -6046
  3. package/lib/index.js +5977 -6040
  4. package/lib/src/Ad4mClient.d.ts +16 -9
  5. package/lib/src/Ad4mClient.js +25 -46
  6. package/lib/src/Ad4mClient.test.d.ts +1 -0
  7. package/lib/src/Ad4mClient.test.js +1204 -0
  8. package/lib/src/Literal.d.ts +2 -1
  9. package/lib/src/Literal.js +35 -38
  10. package/lib/src/Literal.test.d.ts +1 -0
  11. package/lib/src/Literal.test.js +41 -0
  12. package/lib/src/SmartLiteral.d.ts +2 -1
  13. package/lib/src/SmartLiteral.js +15 -30
  14. package/lib/src/agent/AgentClient.d.ts +4 -1
  15. package/lib/src/agent/AgentClient.js +99 -79
  16. package/lib/src/ai/AIClient.d.ts +2 -1
  17. package/lib/src/ai/AIClient.js +220 -224
  18. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  19. package/lib/src/expression/ExpressionClient.js +86 -73
  20. package/lib/src/index.d.ts +1 -1
  21. package/lib/src/index.js +1 -1
  22. package/lib/src/language/LanguageClient.d.ts +1 -1
  23. package/lib/src/language/LanguageClient.js +52 -52
  24. package/lib/src/model/Ad4mModel.d.ts +157 -937
  25. package/lib/src/model/Ad4mModel.js +212 -2799
  26. package/lib/src/model/Ad4mModel.test.js +1002 -561
  27. package/lib/src/model/decorators.d.ts +94 -426
  28. package/lib/src/model/decorators.js +333 -741
  29. package/lib/src/model/mutation.d.ts +81 -0
  30. package/lib/src/model/mutation.js +317 -0
  31. package/lib/src/model/parentUtils.d.ts +32 -0
  32. package/lib/src/model/parentUtils.js +64 -0
  33. package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
  34. package/lib/src/model/prolog/generatePrologFacts.js +139 -0
  35. package/lib/src/model/prolog/index.d.ts +1 -0
  36. package/lib/src/model/prolog/index.js +1 -0
  37. package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
  38. package/lib/src/model/query/ModelQueryBuilder.js +115 -0
  39. package/lib/src/model/query/QueryBuilder.d.ts +101 -0
  40. package/lib/src/model/query/QueryBuilder.js +193 -0
  41. package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
  42. package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
  43. package/lib/src/model/query/fetchInstance.d.ts +24 -0
  44. package/lib/src/model/query/fetchInstance.js +144 -0
  45. package/lib/src/model/query/hydration.d.ts +54 -0
  46. package/lib/src/model/query/hydration.js +214 -0
  47. package/lib/src/model/query/operations.d.ts +59 -0
  48. package/lib/src/model/query/operations.js +384 -0
  49. package/lib/src/model/query/snapshot.d.ts +59 -0
  50. package/lib/src/model/query/snapshot.js +106 -0
  51. package/lib/src/model/query/surrealCompiler.d.ts +42 -0
  52. package/lib/src/model/query/surrealCompiler.js +304 -0
  53. package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
  54. package/lib/src/model/schema/fromJSONSchema.js +264 -0
  55. package/lib/src/model/schema/metadata.d.ts +15 -0
  56. package/lib/src/model/schema/metadata.js +112 -0
  57. package/lib/src/model/subscription.d.ts +47 -0
  58. package/lib/src/model/subscription.js +231 -0
  59. package/lib/src/model/transaction.d.ts +27 -0
  60. package/lib/src/model/transaction.js +32 -0
  61. package/lib/src/model/types.d.ts +195 -0
  62. package/lib/src/model/types.js +8 -0
  63. package/lib/src/model/util.js +7 -7
  64. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +5 -1
  65. package/lib/src/neighbourhood/NeighbourhoodClient.js +263 -181
  66. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -1
  67. package/lib/src/neighbourhood/NeighbourhoodProxy.js +13 -28
  68. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +1 -5
  69. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  70. package/lib/src/perspectives/PerspectiveClient.js +316 -240
  71. package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -92
  72. package/lib/src/perspectives/PerspectiveProxy.js +803 -444
  73. package/lib/src/runtime/RuntimeClient.d.ts +5 -1
  74. package/lib/src/runtime/RuntimeClient.js +412 -238
  75. package/lib/src/shacl/SHACLFlow.test.js +164 -105
  76. package/lib/src/shacl/SHACLShape.d.ts +17 -3
  77. package/lib/src/shacl/SHACLShape.js +127 -90
  78. package/lib/src/shacl/SHACLShape.test.js +244 -176
  79. package/lib/src/utils.d.ts +8 -0
  80. package/lib/src/utils.js +21 -7
  81. package/package.json +8 -13
  82. package/src/Ad4mClient.test.ts +1564 -1315
  83. package/src/Ad4mClient.ts +55 -54
  84. package/src/Literal.test.ts +45 -26
  85. package/src/Literal.ts +82 -66
  86. package/src/SmartLiteral.ts +74 -58
  87. package/src/agent/AgentClient.ts +144 -99
  88. package/src/ai/AIClient.ts +409 -359
  89. package/src/expression/ExpressionClient.ts +142 -96
  90. package/src/index.ts +1 -1
  91. package/src/language/LanguageClient.ts +137 -113
  92. package/src/model/Ad4mModel.test.ts +1128 -647
  93. package/src/model/Ad4mModel.ts +485 -3249
  94. package/src/model/IMPROVEMENTS.md +482 -0
  95. package/src/model/PREDICATE_COLLISION_FIX.md +651 -0
  96. package/src/model/README.md +317 -0
  97. package/src/model/SHACL_MUTATION_DECOUPLING.md +356 -0
  98. package/src/model/SUBSCRIPTION_STRATEGY.md +317 -0
  99. package/src/model/TC39_STAGE_3_DECORATORS.md +609 -0
  100. package/src/model/decorators.ts +689 -1046
  101. package/src/model/mutation.ts +461 -0
  102. package/src/model/parentUtils.ts +91 -0
  103. package/src/model/prolog/generatePrologFacts.ts +176 -0
  104. package/src/model/prolog/index.ts +1 -0
  105. package/src/model/query/ModelQueryBuilder.ts +173 -0
  106. package/src/model/query/fetchInstance.ts +181 -0
  107. package/src/model/query/hydration.ts +273 -0
  108. package/src/model/query/operations.ts +510 -0
  109. package/src/model/query/snapshot.ts +126 -0
  110. package/src/model/query/surrealCompiler.ts +376 -0
  111. package/src/model/schema/fromJSONSchema.ts +411 -0
  112. package/src/model/schema/metadata.ts +148 -0
  113. package/src/model/subscription.ts +307 -0
  114. package/src/model/transaction.ts +60 -0
  115. package/src/model/types.ts +207 -0
  116. package/src/model/util.ts +47 -48
  117. package/src/neighbourhood/NeighbourhoodClient.ts +393 -251
  118. package/src/neighbourhood/NeighbourhoodProxy.test.ts +3 -7
  119. package/src/neighbourhood/NeighbourhoodProxy.ts +58 -40
  120. package/src/perspectives/PerspectiveClient.ts +779 -540
  121. package/src/perspectives/PerspectiveProxy.ts +2860 -2053
  122. package/src/runtime/RuntimeClient.ts +775 -476
  123. package/src/shacl/SHACLFlow.test.ts +196 -129
  124. package/src/shacl/SHACLShape.test.ts +284 -190
  125. package/src/shacl/SHACLShape.ts +225 -172
  126. package/src/utils.ts +31 -17
  127. package/tsconfig.json +9 -10
  128. package/src/model/Subject.ts +0 -159
@@ -1,3 +1,22 @@
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>;
7
+ /**
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).
18
+ */
19
+ export declare function instanceToSerializable(instance: any): Record<string, unknown>;
1
20
  export declare class PerspectiveAction {
2
21
  action: string;
3
22
  source: string;
@@ -6,64 +25,20 @@ export declare class PerspectiveAction {
6
25
  }
7
26
  export declare function addLink(source: string, predicate: string, target: string): PerspectiveAction;
8
27
  export declare function hasLink(predicate: string): string;
9
- export interface InstanceQueryParams {
10
- /**
11
- * An object representing the WHERE clause of the query.
12
- */
13
- where?: object;
14
- /**
15
- * A string representing the Prolog condition clause of the query.
16
- */
17
- prologCondition?: string;
18
- }
19
- /**
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
58
- */
59
- export declare function InstanceQuery(options?: InstanceQueryParams): <T>(target: T, key: keyof T, descriptor: PropertyDescriptor) => void;
60
28
  export interface PropertyOptions {
61
29
  /**
62
30
  * The predicate of the property. All properties must have this option.
63
31
  */
64
32
  through?: string;
65
33
  /**
66
- * The initial value of the property. Required if the property is marked as required.
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.
67
42
  */
68
43
  initial?: string;
69
44
  /**
@@ -71,21 +46,20 @@ export interface PropertyOptions {
71
46
  */
72
47
  required?: boolean;
73
48
  /**
74
- * Indicates whether the property is writable. If true, a setter will be available in the prolog engine.
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.
75
52
  */
76
- writable?: boolean;
53
+ readOnly?: boolean;
77
54
  /**
78
- * The language used to store the property. Can be the default `Literal` Language or a custom language address.
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.
79
61
  */
80
62
  resolveLanguage?: string;
81
- /**
82
- * Custom Prolog getter to get the value of the property. If not provided, the default getter will be used.
83
- */
84
- prologGetter?: string;
85
- /**
86
- * Custom Prolog setter to set the value of the property. Only available if the property is writable.
87
- */
88
- prologSetter?: string;
89
63
  /**
90
64
  * Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
91
65
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
@@ -102,87 +76,26 @@ export interface PropertyOptions {
102
76
  * The function takes the raw value as input and returns the transformed value.
103
77
  */
104
78
  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;
105
85
  }
106
86
  /**
107
- * Decorator for defining optional properties on model classes.
108
- *
109
- * @category Decorators
110
- *
111
- * @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.
120
- *
121
- * @example
122
- * ```typescript
123
- * class Recipe extends Ad4mModel {
124
- * // Basic optional property
125
- * @Optional({
126
- * through: "recipe://description"
127
- * })
128
- * 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
- * }
173
- * ```
174
- *
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
87
+ * Declares a typed property backed by a single link triple in the perspective.
88
+ *
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
184
97
  */
185
- export declare function Optional(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
98
+ export declare function Property(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
186
99
  export interface FlagOptions {
187
100
  /**
188
101
  * The predicate of the property. All properties must have this option.
@@ -194,75 +107,25 @@ export interface FlagOptions {
194
107
  value: string;
195
108
  }
196
109
  /**
197
- * Decorator for defining flags on model classes.
198
- *
199
- * @category Decorators
200
- *
201
- * @description
202
- * A specialized property decorator for defining immutable type flags or markers on model instances.
203
- * Flags are always required properties with a fixed value that cannot be changed after creation.
110
+ * Immutable type-marker property: written once at creation and never modified.
204
111
  *
205
- * Common uses for flags:
206
- * - Type discrimination between different kinds of models
207
- * - Marking models with specific capabilities or features
208
- * - Versioning or compatibility markers
209
- *
210
- * Note: Use of Flag is discouraged unless you specifically need type-based filtering or
211
- * discrimination between different kinds of models. For most cases, regular properties
212
- * with @Property or @Optional are more appropriate.
112
+ * Use for type-discrimination predicates (e.g. `ad4m://type = "ad4m://message"`).
113
+ * For mutable data prefer `@Property`.
213
114
  *
214
115
  * @example
215
116
  * ```typescript
216
- * class Message extends Ad4mModel {
217
- * // Type flag to identify message models
218
- * @Flag({
219
- * through: "ad4m://type",
220
- * value: "ad4m://message"
221
- * })
222
- * type: string = "";
223
- *
224
- * // Version flag for compatibility
225
- * @Flag({
226
- * through: "ad4m://version",
227
- * value: "1.0.0"
228
- * })
229
- * version: string = "";
230
- *
231
- * // Feature flag
232
- * @Flag({
233
- * through: "message://feature",
234
- * value: "message://encrypted"
235
- * })
236
- * feature: string = "";
237
- * }
238
- *
239
- * // Later you can query for specific types:
240
- * const messages = await Message.query(perspective)
241
- * .where({ type: "ad4m://message" })
242
- * .run();
117
+ * @Flag({ through: "ad4m://type", value: "ad4m://message" })
118
+ * type: string = "";
243
119
  * ```
244
- *
245
- * @param {FlagOptions} opts - Flag configuration
246
- * @param {string} opts.through - The predicate URI for the flag
247
- * @param {string} opts.value - The fixed value for the flag
248
120
  */
249
121
  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 {
122
+ export interface RelationOptions {
256
123
  /**
257
124
  * The predicate of the property. All properties must have this option.
258
125
  */
259
126
  through: string;
260
127
  /**
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.
128
+ * Custom SurrealQL getter to resolve the related values. Use this for custom graph traversals.
266
129
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
267
130
  * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)"
268
131
  */
@@ -272,251 +135,56 @@ export interface CollectionOptions {
272
135
  */
273
136
  local?: boolean;
274
137
  }
138
+ /** Minimal structural type for Ad4mModel instances — used in mutator signatures to avoid circular imports. */
139
+ export interface Ad4mModelLike {
140
+ readonly id: string;
141
+ }
275
142
  /**
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
143
+ * Utility type that generates the runtime methods produced by \@HasMany / \@HasOne decorators.
288
144
  *
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
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
294
149
  *
150
+ * Pass a string union of your \@HasMany/\@HasOne property names and use interface merging:
295
151
  * @example
296
152
  * ```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[] = [];
153
+ * \@Model({ name: 'Post' })
154
+ * export class Post extends Ad4mModel {
155
+ * \@HasMany(() => Comment, { through: 'post://comment' })
156
+ * comments: Comment[] = [];
331
157
  * }
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"]);
158
+ * export interface Post extends HasManyMethods<'comments'> {}
338
159
  * ```
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
160
  */
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 {
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 {
350
174
  /**
351
175
  * The name of the entity.
352
176
  */
353
177
  name: string;
354
178
  }
355
179
  /**
356
- * Decorator for defining model classes in AD4M.
357
- *
358
- * @category Decorators
359
- *
360
- * @description
361
- * The root decorator that must be applied to any class that represents a model in AD4M.
362
- * It registers the class as a Social DNA (SDNA) subject class and provides the infrastructure
363
- * for storing and retrieving instances.
364
- *
365
- * This decorator:
366
- * - 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.)
369
- * - Provides static query methods through the Ad4mModel base class
370
- *
371
- * @example
372
- * ```typescript
373
- * @ModelOptions({ name: "Recipe" })
374
- * class Recipe extends Ad4mModel {
375
- * @Property({
376
- * through: "recipe://name",
377
- * resolveLanguage: "literal"
378
- * })
379
- * name: string = "";
380
- *
381
- * @Collection({ through: "recipe://ingredient" })
382
- * ingredients: string[] = [];
383
- *
384
- * // Static query methods from Ad4mModel:
385
- * static async findByName(perspective: PerspectiveProxy, name: string) {
386
- * return Recipe.query(perspective)
387
- * .where({ name })
388
- * .run();
389
- * }
390
- * }
391
- *
392
- * // Using the model:
393
- * const recipe = new Recipe(perspective);
394
- * recipe.name = "Chocolate Cake";
395
- * await recipe.save();
396
- *
397
- * // Querying instances:
398
- * const recipes = await Recipe.query(perspective)
399
- * .where({ name: "Chocolate Cake" })
400
- * .run();
401
- *
402
- * // Using with PerspectiveProxy:
403
- * await perspective.ensureSDNASubjectClass(Recipe);
404
- * ```
405
- *
406
- * @param {ModelOptionsOptions} opts - Model configuration
407
- * @param {string} opts.name - Unique name for the model class in AD4M
408
- */
409
- export declare function ModelOptions(opts: ModelOptionsOptions): (target: any) => void;
410
- /**
411
- * Decorator for defining required and writable properties on model classes.
412
- *
413
- * @category Decorators
414
- *
415
- * @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`.
418
- *
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
423
- *
424
- * @example
425
- * ```typescript
426
- * class User extends Ad4mModel {
427
- * // Basic required property with default initial value
428
- * @Property({
429
- * through: "user://name"
430
- * })
431
- * name: string = "";
432
- *
433
- * // Required property with custom initial value
434
- * @Property({
435
- * through: "user://status",
436
- * initial: "user://active"
437
- * })
438
- * status: string = "";
439
- *
440
- * // Required property with literal resolution
441
- * @Property({
442
- * through: "user://bio",
443
- * resolveLanguage: "literal"
444
- * })
445
- * bio: string = "";
446
- *
447
- * // Required property with custom getter/setter
448
- * @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}]`
452
- * })
453
- * age: number = 0;
454
- * }
455
- * ```
456
- *
457
- * @param {PropertyOptions} opts - Property configuration
458
- * @param {string} opts.through - The predicate URI for the property
459
- * @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized")
460
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
461
- * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
462
- * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
463
- * @param {boolean} [opts.local] - Whether the property should only be stored locally
464
- */
465
- export declare function Property(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
466
- /**
467
- * Decorator for defining read-only properties on model classes.
468
- *
469
- * @category Decorators
180
+ * Registers the class as an AD4M SDNA subject, enabling `Ad4mModel` static query methods.
470
181
  *
471
- * @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`.
474
- *
475
- * Read-only properties are ideal for:
476
- * - Computed or derived values
477
- * - Properties that should never change after creation
478
- * - Properties that are set by the system
479
- * - Properties that represent immutable data
182
+ * Must be applied to every class that extends `Ad4mModel`.
480
183
  *
481
184
  * @example
482
185
  * ```typescript
483
- * class Post extends Ad4mModel {
484
- * // Read-only property with custom getter for computed value
485
- * @ReadOnly({
486
- * through: "post://likes",
487
- * getter: `findall(User, triple(Base, "post://liked_by", User), Users), length(Users, Value)`
488
- * })
489
- * likeCount: number = 0;
490
- *
491
- * // Read-only property for creation timestamp
492
- * @ReadOnly({
493
- * through: "post://created_at",
494
- * initial: new Date().toISOString()
495
- * })
496
- * createdAt: string = "";
497
- *
498
- * // Read-only property that resolves to a Literal
499
- * @ReadOnly({
500
- * through: "post://author",
501
- * resolveLanguage: "literal"
502
- * })
503
- * author: string = "";
504
- *
505
- * // Read-only property for system-managed data
506
- * @ReadOnly({
507
- * through: "post://version",
508
- * initial: "1.0.0"
509
- * })
510
- * version: string = "";
511
- * }
186
+ * @Model({ name: "Recipe" })
187
+ * class Recipe extends Ad4mModel { ... }
512
188
  * ```
513
- *
514
- * @param {PropertyOptions} opts - Property configuration
515
- * @param {string} opts.through - The predicate URI for the property
516
- * @param {string} [opts.initial] - Initial value (if property should have one)
517
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
518
- * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
519
- * @param {boolean} [opts.local] - Whether the property should only be stored locally
520
189
  */
521
- export declare function ReadOnly(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
522
- export {};
190
+ export declare function Model(opts: ModelConfig): (target: any) => void;