@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.
- package/jest.config.js +8 -1
- package/lib/index.cjs +13793 -12854
- package/lib/index.js +13782 -12851
- package/lib/src/Ad4mClient.test.d.ts +1 -0
- package/lib/src/Ad4mClient.test.js +1204 -0
- package/lib/src/Literal.test.d.ts +1 -0
- package/lib/src/Literal.test.js +41 -0
- package/lib/src/model/Ad4mModel.d.ts +528 -101
- package/lib/src/model/Ad4mModel.js +1670 -748
- package/lib/src/model/Ad4mModel.test.js +140 -156
- package/lib/src/model/Subject.d.ts +3 -3
- package/lib/src/model/Subject.js +25 -25
- package/lib/src/model/decorators.d.ts +259 -247
- package/lib/src/model/decorators.js +379 -422
- package/lib/src/model/mutation.d.ts +81 -0
- package/lib/src/model/mutation.js +317 -0
- package/lib/src/model/parentUtils.d.ts +32 -0
- package/lib/src/model/parentUtils.js +64 -0
- package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
- package/lib/src/model/prolog/generatePrologFacts.js +139 -0
- package/lib/src/model/prolog/index.d.ts +1 -0
- package/lib/src/model/prolog/index.js +1 -0
- package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
- package/lib/src/model/query/ModelQueryBuilder.js +115 -0
- package/lib/src/model/query/QueryBuilder.d.ts +101 -0
- package/lib/src/model/query/QueryBuilder.js +193 -0
- package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
- package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
- package/lib/src/model/query/fetchInstance.d.ts +24 -0
- package/lib/src/model/query/fetchInstance.js +144 -0
- package/lib/src/model/query/hydration.d.ts +54 -0
- package/lib/src/model/query/hydration.js +214 -0
- package/lib/src/model/query/operations.d.ts +59 -0
- package/lib/src/model/query/operations.js +384 -0
- package/lib/src/model/query/snapshot.d.ts +59 -0
- package/lib/src/model/query/snapshot.js +106 -0
- package/lib/src/model/query/surrealCompiler.d.ts +42 -0
- package/lib/src/model/query/surrealCompiler.js +304 -0
- package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
- package/lib/src/model/schema/fromJSONSchema.js +264 -0
- package/lib/src/model/schema/metadata.d.ts +15 -0
- package/lib/src/model/schema/metadata.js +112 -0
- package/lib/src/model/subscription.d.ts +47 -0
- package/lib/src/model/subscription.js +231 -0
- package/lib/src/model/transaction.d.ts +27 -0
- package/lib/src/model/transaction.js +32 -0
- package/lib/src/model/types.d.ts +195 -0
- package/lib/src/model/types.js +8 -0
- package/lib/src/model/util.d.ts +6 -6
- package/lib/src/model/util.js +22 -22
- package/lib/src/neighbourhood/NeighbourhoodClient.js +31 -12
- package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -9
- package/lib/src/perspectives/PerspectiveProxy.js +63 -51
- package/lib/src/shacl/SHACLShape.d.ts +9 -0
- package/lib/src/shacl/SHACLShape.js +28 -4
- package/lib/src/shims/reflect-metadata.d.ts +0 -0
- package/lib/src/shims/type-graphql.d.ts +32 -0
- package/lib/src/src/Ad4mClient.d.ts +28 -0
- package/lib/src/src/Address.d.ts +1 -0
- package/lib/src/src/DID.d.ts +1 -0
- package/lib/src/src/Exception.d.ts +7 -0
- package/lib/src/src/Literal.d.ts +7 -0
- package/lib/src/src/PubSub.d.ts +17 -0
- package/lib/src/src/SmartLiteral.d.ts +12 -0
- package/lib/src/src/agent/Agent.d.ts +110 -0
- package/lib/src/src/agent/AgentClient.d.ts +62 -0
- package/lib/src/src/agent/AgentResolver.d.ts +30 -0
- package/lib/src/src/agent/AgentStatus.d.ts +8 -0
- package/lib/src/src/ai/AIClient.d.ts +32 -0
- package/lib/src/src/ai/AIResolver.d.ts +75 -0
- package/lib/src/src/ai/Tasks.d.ts +37 -0
- package/lib/src/src/buildSchema.d.ts +1 -0
- package/lib/src/src/expression/Expression.d.ts +28 -0
- package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
- package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
- package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
- package/lib/src/src/index.d.ts +35 -0
- package/lib/src/src/jestSetup.d.ts +1 -0
- package/lib/src/src/language/Icon.d.ts +4 -0
- package/lib/src/src/language/Language.d.ts +206 -0
- package/lib/src/src/language/LanguageClient.d.ts +17 -0
- package/lib/src/src/language/LanguageContext.d.ts +37 -0
- package/lib/src/src/language/LanguageHandle.d.ts +9 -0
- package/lib/src/src/language/LanguageMeta.d.ts +35 -0
- package/lib/src/src/language/LanguageRef.d.ts +6 -0
- package/lib/src/src/language/LanguageResolver.d.ts +19 -0
- package/lib/src/src/links/Links.d.ts +39 -0
- package/lib/src/src/links/Links.test.d.ts +1 -0
- package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
- package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
- package/lib/src/src/model/Subject.d.ts +25 -0
- package/lib/src/src/model/decorators.d.ts +545 -0
- package/lib/src/src/model/util.d.ts +12 -0
- package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
- package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
- package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
- package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
- package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
- package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
- package/lib/src/src/perspectives/Perspective.d.ts +38 -0
- package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
- package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
- package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
- package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
- package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
- package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
- package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
- package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
- package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
- package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
- package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
- package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
- package/lib/src/src/typeDefs.d.ts +1 -0
- package/lib/src/src/unwrapApolloResult.d.ts +2 -0
- package/lib/src/src/utils.d.ts +25 -0
- package/package.json +20 -24
- package/src/model/Ad4mModel.test.ts +132 -149
- package/src/model/Ad4mModel.ts +1930 -784
- package/src/model/Subject.ts +24 -24
- package/src/model/decorators.ts +626 -482
- package/src/model/util.ts +22 -22
- package/src/neighbourhood/NeighbourhoodClient.ts +32 -16
- package/src/perspectives/PerspectiveProxy.ts +69 -55
- package/src/shacl/SHACLShape.ts +33 -4
|
@@ -1,62 +1,76 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
8
|
-
export
|
|
9
|
-
|
|
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
|
-
*
|
|
14
|
+
* Maximum number of related instances.
|
|
15
|
+
* Set automatically: 1 for `@HasOne`/`@BelongsToOne`, undefined (unlimited) for `*Many`.
|
|
12
16
|
*/
|
|
13
|
-
|
|
17
|
+
maxCount?: number;
|
|
18
|
+
local?: boolean;
|
|
14
19
|
/**
|
|
15
|
-
*
|
|
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
|
-
|
|
23
|
+
getter?: string;
|
|
18
24
|
}
|
|
19
25
|
/**
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
*
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
*
|
|
122
|
+
* Convenience decorator for defining optional (not required) properties.
|
|
108
123
|
*
|
|
109
124
|
* @category Decorators
|
|
110
125
|
*
|
|
111
126
|
* @description
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
|
368
|
-
* - Enables the use of other model decorators (@Property, @
|
|
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
|
-
* @
|
|
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
|
-
* @
|
|
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 {
|
|
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
|
|
266
|
+
export declare function Model(opts: ModelConfig): (target: any) => void;
|
|
410
267
|
/**
|
|
411
|
-
*
|
|
268
|
+
* The primary property decorator for AD4M model classes.
|
|
412
269
|
*
|
|
413
270
|
* @category Decorators
|
|
414
271
|
*
|
|
415
272
|
* @description
|
|
416
|
-
*
|
|
417
|
-
*
|
|
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
|
-
*
|
|
420
|
-
* -
|
|
421
|
-
* -
|
|
422
|
-
* -
|
|
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
|
-
* //
|
|
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
|
-
* //
|
|
297
|
+
* // Explicitly required property with sentinel initial value
|
|
434
298
|
* @Property({
|
|
435
299
|
* through: "user://status",
|
|
436
|
-
*
|
|
300
|
+
* required: true
|
|
437
301
|
* })
|
|
438
302
|
* status: string = "";
|
|
439
303
|
*
|
|
440
|
-
* // Required property with
|
|
304
|
+
* // Required property with custom initial value
|
|
441
305
|
* @Property({
|
|
442
|
-
* through: "user://
|
|
443
|
-
*
|
|
306
|
+
* through: "user://role",
|
|
307
|
+
* required: true,
|
|
308
|
+
* initial: "user://member"
|
|
444
309
|
* })
|
|
445
|
-
*
|
|
310
|
+
* role: string = "";
|
|
446
311
|
*
|
|
447
|
-
* //
|
|
312
|
+
* // Optional property with literal resolution
|
|
448
313
|
* @Property({
|
|
449
|
-
* through: "user://
|
|
450
|
-
*
|
|
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
|
-
*
|
|
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 {
|
|
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
|
|
473
|
-
*
|
|
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
|
-
|
|
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;
|