@coasys/ad4m 0.10.1-release-candidate-3-test-2 → 0.10.1-release-candidate-4-debug-strings

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.
@@ -1,496 +0,0 @@
1
- export declare class PerspectiveAction {
2
- action: string;
3
- source: string;
4
- predicate: string;
5
- target: string;
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 {
10
- /**
11
- * An object representing the WHERE clause of the query.
12
- */
13
- where?: object;
14
- /**
15
- * A string representing the condition clause of the query.
16
- */
17
- condition?: 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({ condition: "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.condition] - 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
- export interface PropertyOptions {
61
- /**
62
- * The predicate of the property. All properties must have this option.
63
- */
64
- through?: string;
65
- /**
66
- * The initial value of the property. Required if the property is marked as required.
67
- */
68
- initial?: string;
69
- /**
70
- * Indicates whether the property is required. If true, an initial value must be provided.
71
- */
72
- required?: boolean;
73
- /**
74
- * Indicates whether the property is writable. If true, a setter will be available in the prolog engine.
75
- */
76
- writable?: boolean;
77
- /**
78
- * The language used to store the property. Can be the default `Literal` Language or a custom language address.
79
- */
80
- resolveLanguage?: string;
81
- /**
82
- * Custom getter to get the value of the property in the prolog engine. If not provided, the default getter will be used.
83
- */
84
- getter?: string;
85
- /**
86
- * Custom setter to set the value of the property in the prolog engine. Only available if the property is writable.
87
- */
88
- setter?: string;
89
- /**
90
- * 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.
91
- */
92
- local?: boolean;
93
- }
94
- /**
95
- * Decorator for defining optional properties on model classes.
96
- *
97
- * @category Decorators
98
- *
99
- * @description
100
- * The most flexible property decorator that allows you to define properties with full control over:
101
- * - Whether the property is required
102
- * - Whether the property is writable
103
- * - How values are stored and retrieved
104
- * - Custom getter/setter logic
105
- * - Local vs network storage
106
- *
107
- * Both @Property and @ReadOnly are specialized versions of @Optional with preset configurations.
108
- *
109
- * @example
110
- * ```typescript
111
- * class Recipe extends Ad4mModel {
112
- * // Basic optional property
113
- * @Optional({
114
- * through: "recipe://description"
115
- * })
116
- * description?: string;
117
- *
118
- * // Optional property with custom initial value
119
- * @Optional({
120
- * through: "recipe://status",
121
- * initial: "recipe://draft",
122
- * required: true
123
- * })
124
- * status: string = "";
125
- *
126
- * // Read-only property with custom getter
127
- * @Optional({
128
- * through: "recipe://rating",
129
- * writable: false,
130
- * getter: `
131
- * findall(Rating, triple(Base, "recipe://user_rating", Rating), Ratings),
132
- * sum_list(Ratings, Sum),
133
- * length(Ratings, Count),
134
- * Value is Sum / Count
135
- * `
136
- * })
137
- * averageRating: number = 0;
138
- *
139
- * // Property that resolves to a Literal and is stored locally
140
- * @Optional({
141
- * through: "recipe://notes",
142
- * resolveLanguage: "literal",
143
- * local: true
144
- * })
145
- * notes?: string;
146
- *
147
- * // Property with custom getter and setter logic
148
- * @Optional({
149
- * through: "recipe://ingredients",
150
- * getter: `
151
- * triple(Base, "recipe://ingredients", RawValue),
152
- * atom_json_term(RawValue, Value)
153
- * `,
154
- * setter: `
155
- * atom_json_term(Value, JsonValue),
156
- * Actions = [{"action": "setSingleTarget", "source": "this", "predicate": "recipe://ingredients", "target": JsonValue}]
157
- * `
158
- * })
159
- * ingredients: string[] = [];
160
- * }
161
- * ```
162
- *
163
- * @param {PropertyOptions} opts - Property configuration options
164
- * @param {string} opts.through - The predicate URI for the property
165
- * @param {string} [opts.initial] - Initial value (required if property is required)
166
- * @param {boolean} [opts.required] - Whether the property must have a value
167
- * @param {boolean} [opts.writable=true] - Whether the property can be modified
168
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
169
- * @param {string} [opts.getter] - Custom Prolog code for getting the property value
170
- * @param {string} [opts.setter] - Custom Prolog code for setting the property value
171
- * @param {boolean} [opts.local] - Whether the property should only be stored locally
172
- */
173
- export declare function Optional(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
174
- export interface FlagOptions {
175
- /**
176
- * The predicate of the property. All properties must have this option.
177
- */
178
- through: string;
179
- /**
180
- * The value of the property.
181
- */
182
- value: string;
183
- }
184
- /**
185
- * Decorator for defining flags on model classes.
186
- *
187
- * @category Decorators
188
- *
189
- * @description
190
- * A specialized property decorator for defining immutable type flags or markers on model instances.
191
- * Flags are always required properties with a fixed value that cannot be changed after creation.
192
- *
193
- * Common uses for flags:
194
- * - Type discrimination between different kinds of models
195
- * - Marking models with specific capabilities or features
196
- * - Versioning or compatibility markers
197
- *
198
- * Note: Use of Flag is discouraged unless you specifically need type-based filtering or
199
- * discrimination between different kinds of models. For most cases, regular properties
200
- * with @Property or @Optional are more appropriate.
201
- *
202
- * @example
203
- * ```typescript
204
- * class Message extends Ad4mModel {
205
- * // Type flag to identify message models
206
- * @Flag({
207
- * through: "ad4m://type",
208
- * value: "ad4m://message"
209
- * })
210
- * type: string = "";
211
- *
212
- * // Version flag for compatibility
213
- * @Flag({
214
- * through: "ad4m://version",
215
- * value: "1.0.0"
216
- * })
217
- * version: string = "";
218
- *
219
- * // Feature flag
220
- * @Flag({
221
- * through: "message://feature",
222
- * value: "message://encrypted"
223
- * })
224
- * feature: string = "";
225
- * }
226
- *
227
- * // Later you can query for specific types:
228
- * const messages = await Message.query(perspective)
229
- * .where({ type: "ad4m://message" })
230
- * .run();
231
- * ```
232
- *
233
- * @param {FlagOptions} opts - Flag configuration
234
- * @param {string} opts.through - The predicate URI for the flag
235
- * @param {string} opts.value - The fixed value for the flag
236
- */
237
- export declare function Flag(opts: FlagOptions): <T>(target: T, key: keyof T) => void;
238
- interface WhereOptions {
239
- isInstance?: any;
240
- condition?: string;
241
- }
242
- export interface CollectionOptions {
243
- /**
244
- * The predicate of the property. All properties must have this option.
245
- */
246
- through: string;
247
- /**
248
- * An object representing the WHERE clause of the query.
249
- */
250
- where?: WhereOptions;
251
- /**
252
- * 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.
253
- */
254
- local?: boolean;
255
- }
256
- /**
257
- * Decorator for defining collections on model classes.
258
- *
259
- * @category Decorators
260
- *
261
- * @description
262
- * Defines a property that represents a collection of values linked to the model instance.
263
- * Collections are always arrays and support operations for adding, removing, and setting values.
264
- *
265
- * For each collection property, the following methods are automatically generated:
266
- * - `addX(value)` - Add a value to the collection
267
- * - `removeX(value)` - Remove a value from the collection
268
- * - `setCollectionX(values)` - Replace all values in the collection
269
- *
270
- * Where X is the capitalized property name.
271
- *
272
- * Collections can be filtered using the `where` option to only include values that:
273
- * - Are instances of a specific model class
274
- * - Match a custom Prolog condition
275
- *
276
- * @example
277
- * ```typescript
278
- * class Recipe extends Ad4mModel {
279
- * // Basic collection of ingredients
280
- * @Collection({
281
- * through: "recipe://ingredient"
282
- * })
283
- * ingredients: string[] = [];
284
- *
285
- * // Collection that only includes instances of another model
286
- * @Collection({
287
- * through: "recipe://comment",
288
- * where: { isInstance: Comment }
289
- * })
290
- * comments: string[] = [];
291
- *
292
- * // Collection with custom filter condition
293
- * @Collection({
294
- * through: "recipe://step",
295
- * where: { condition: `triple(Target, "step://order", Order), Order < 3` }
296
- * })
297
- * firstSteps: string[] = [];
298
- *
299
- * // Local-only collection not shared with network
300
- * @Collection({
301
- * through: "recipe://note",
302
- * local: true
303
- * })
304
- * privateNotes: string[] = [];
305
- * }
306
- *
307
- * // Using the generated methods:
308
- * const recipe = new Recipe(perspective);
309
- * await recipe.addIngredients("ingredient://flour");
310
- * await recipe.removeIngredients("ingredient://sugar");
311
- * await recipe.setCollectionIngredients(["ingredient://butter", "ingredient://eggs"]);
312
- * ```
313
- *
314
- * @param {CollectionOptions} opts - Collection configuration
315
- * @param {string} opts.through - The predicate URI for collection links
316
- * @param {WhereOptions} [opts.where] - Filter conditions for collection values
317
- * @param {any} [opts.where.isInstance] - Model class to filter instances by
318
- * @param {string} [opts.where.condition] - Custom Prolog condition for filtering
319
- * @param {boolean} [opts.local] - Whether collection links are stored locally only
320
- */
321
- export declare function Collection(opts: CollectionOptions): <T>(target: T, key: keyof T) => void;
322
- export declare function makeRandomPrologAtom(length: number): string;
323
- export interface ModelOptionsOptions {
324
- /**
325
- * The name of the entity.
326
- */
327
- name: string;
328
- }
329
- /**
330
- * Decorator for defining model classes in AD4M.
331
- *
332
- * @category Decorators
333
- *
334
- * @description
335
- * The root decorator that must be applied to any class that represents a model in AD4M.
336
- * It registers the class as a Social DNA (SDNA) subject class and provides the infrastructure
337
- * for storing and retrieving instances.
338
- *
339
- * This decorator:
340
- * - Registers the class with a unique name in the AD4M system
341
- * - Generates the necessary SDNA code for the model's properties and collections
342
- * - Enables the use of other model decorators (@Property, @Collection, etc.)
343
- * - Provides static query methods through the Ad4mModel base class
344
- *
345
- * @example
346
- * ```typescript
347
- * @ModelOptions({ name: "Recipe" })
348
- * class Recipe extends Ad4mModel {
349
- * @Property({
350
- * through: "recipe://name",
351
- * resolveLanguage: "literal"
352
- * })
353
- * name: string = "";
354
- *
355
- * @Collection({ through: "recipe://ingredient" })
356
- * ingredients: string[] = [];
357
- *
358
- * // Static query methods from Ad4mModel:
359
- * static async findByName(perspective: PerspectiveProxy, name: string) {
360
- * return Recipe.query(perspective)
361
- * .where({ name })
362
- * .run();
363
- * }
364
- * }
365
- *
366
- * // Using the model:
367
- * const recipe = new Recipe(perspective);
368
- * recipe.name = "Chocolate Cake";
369
- * await recipe.save();
370
- *
371
- * // Querying instances:
372
- * const recipes = await Recipe.query(perspective)
373
- * .where({ name: "Chocolate Cake" })
374
- * .run();
375
- *
376
- * // Using with PerspectiveProxy:
377
- * await perspective.ensureSDNASubjectClass(Recipe);
378
- * ```
379
- *
380
- * @param {ModelOptionsOptions} opts - Model configuration
381
- * @param {string} opts.name - Unique name for the model class in AD4M
382
- */
383
- export declare function ModelOptions(opts: ModelOptionsOptions): (target: any) => void;
384
- /**
385
- * Decorator for defining required and writable properties on model classes.
386
- *
387
- * @category Decorators
388
- *
389
- * @description
390
- * A convenience decorator that defines a required property that must have an initial value and is writable by default.
391
- * This is equivalent to using @Optional with `required: true` and `writable: true`.
392
- *
393
- * Properties defined with this decorator:
394
- * - Must have a value (required)
395
- * - Can be modified after creation (writable)
396
- * - Default to "literal://string:uninitialized" if no initial value is provided
397
- *
398
- * @example
399
- * ```typescript
400
- * class User extends Ad4mModel {
401
- * // Basic required property with default initial value
402
- * @Property({
403
- * through: "user://name"
404
- * })
405
- * name: string = "";
406
- *
407
- * // Required property with custom initial value
408
- * @Property({
409
- * through: "user://status",
410
- * initial: "user://active"
411
- * })
412
- * status: string = "";
413
- *
414
- * // Required property with literal resolution
415
- * @Property({
416
- * through: "user://bio",
417
- * resolveLanguage: "literal"
418
- * })
419
- * bio: string = "";
420
- *
421
- * // Required property with custom getter/setter
422
- * @Property({
423
- * through: "user://age",
424
- * getter: `triple(Base, "user://birthYear", Year), Value is 2024 - Year`,
425
- * setter: `Year is 2024 - Value, Actions = [{"action": "setSingleTarget", "source": "this", "predicate": "user://birthYear", "target": Year}]`
426
- * })
427
- * age: number = 0;
428
- * }
429
- * ```
430
- *
431
- * @param {PropertyOptions} opts - Property configuration
432
- * @param {string} opts.through - The predicate URI for the property
433
- * @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized")
434
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
435
- * @param {string} [opts.getter] - Custom Prolog code for getting the property value
436
- * @param {string} [opts.setter] - Custom Prolog code for setting the property value
437
- * @param {boolean} [opts.local] - Whether the property should only be stored locally
438
- */
439
- export declare function Property(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
440
- /**
441
- * Decorator for defining read-only properties on model classes.
442
- *
443
- * @category Decorators
444
- *
445
- * @description
446
- * A convenience decorator that defines a property that can only be read and cannot be modified after initialization.
447
- * This is equivalent to using @Optional with `writable: false`.
448
- *
449
- * Read-only properties are ideal for:
450
- * - Computed or derived values
451
- * - Properties that should never change after creation
452
- * - Properties that are set by the system
453
- * - Properties that represent immutable data
454
- *
455
- * @example
456
- * ```typescript
457
- * class Post extends Ad4mModel {
458
- * // Read-only property with custom getter for computed value
459
- * @ReadOnly({
460
- * through: "post://likes",
461
- * getter: `findall(User, triple(Base, "post://liked_by", User), Users), length(Users, Value)`
462
- * })
463
- * likeCount: number = 0;
464
- *
465
- * // Read-only property for creation timestamp
466
- * @ReadOnly({
467
- * through: "post://created_at",
468
- * initial: new Date().toISOString()
469
- * })
470
- * createdAt: string = "";
471
- *
472
- * // Read-only property that resolves to a Literal
473
- * @ReadOnly({
474
- * through: "post://author",
475
- * resolveLanguage: "literal"
476
- * })
477
- * author: string = "";
478
- *
479
- * // Read-only property for system-managed data
480
- * @ReadOnly({
481
- * through: "post://version",
482
- * initial: "1.0.0"
483
- * })
484
- * version: string = "";
485
- * }
486
- * ```
487
- *
488
- * @param {PropertyOptions} opts - Property configuration
489
- * @param {string} opts.through - The predicate URI for the property
490
- * @param {string} [opts.initial] - Initial value (if property should have one)
491
- * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
492
- * @param {string} [opts.getter] - Custom Prolog code for getting the property value
493
- * @param {boolean} [opts.local] - Whether the property should only be stored locally
494
- */
495
- export declare function ReadOnly(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
496
- export {};