@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.
- package/jest.config.js +4 -4
- package/lib/index.cjs +5999 -6046
- package/lib/index.js +5977 -6040
- package/lib/src/Ad4mClient.d.ts +16 -9
- package/lib/src/Ad4mClient.js +25 -46
- package/lib/src/Ad4mClient.test.d.ts +1 -0
- package/lib/src/Ad4mClient.test.js +1204 -0
- package/lib/src/Literal.d.ts +2 -1
- package/lib/src/Literal.js +35 -38
- package/lib/src/Literal.test.d.ts +1 -0
- package/lib/src/Literal.test.js +41 -0
- package/lib/src/SmartLiteral.d.ts +2 -1
- package/lib/src/SmartLiteral.js +15 -30
- package/lib/src/agent/AgentClient.d.ts +4 -1
- package/lib/src/agent/AgentClient.js +99 -79
- package/lib/src/ai/AIClient.d.ts +2 -1
- package/lib/src/ai/AIClient.js +220 -224
- package/lib/src/expression/ExpressionClient.d.ts +1 -1
- package/lib/src/expression/ExpressionClient.js +86 -73
- package/lib/src/index.d.ts +1 -1
- package/lib/src/index.js +1 -1
- package/lib/src/language/LanguageClient.d.ts +1 -1
- package/lib/src/language/LanguageClient.js +52 -52
- package/lib/src/model/Ad4mModel.d.ts +157 -937
- package/lib/src/model/Ad4mModel.js +212 -2799
- package/lib/src/model/Ad4mModel.test.js +1002 -561
- package/lib/src/model/decorators.d.ts +94 -426
- package/lib/src/model/decorators.js +333 -741
- 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.js +7 -7
- package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +5 -1
- package/lib/src/neighbourhood/NeighbourhoodClient.js +263 -181
- package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -1
- package/lib/src/neighbourhood/NeighbourhoodProxy.js +13 -28
- package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +1 -5
- package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
- package/lib/src/perspectives/PerspectiveClient.js +316 -240
- package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -92
- package/lib/src/perspectives/PerspectiveProxy.js +803 -444
- package/lib/src/runtime/RuntimeClient.d.ts +5 -1
- package/lib/src/runtime/RuntimeClient.js +412 -238
- package/lib/src/shacl/SHACLFlow.test.js +164 -105
- package/lib/src/shacl/SHACLShape.d.ts +17 -3
- package/lib/src/shacl/SHACLShape.js +127 -90
- package/lib/src/shacl/SHACLShape.test.js +244 -176
- package/lib/src/utils.d.ts +8 -0
- package/lib/src/utils.js +21 -7
- package/package.json +8 -13
- package/src/Ad4mClient.test.ts +1564 -1315
- package/src/Ad4mClient.ts +55 -54
- package/src/Literal.test.ts +45 -26
- package/src/Literal.ts +82 -66
- package/src/SmartLiteral.ts +74 -58
- package/src/agent/AgentClient.ts +144 -99
- package/src/ai/AIClient.ts +409 -359
- package/src/expression/ExpressionClient.ts +142 -96
- package/src/index.ts +1 -1
- package/src/language/LanguageClient.ts +137 -113
- package/src/model/Ad4mModel.test.ts +1128 -647
- package/src/model/Ad4mModel.ts +485 -3249
- package/src/model/IMPROVEMENTS.md +482 -0
- package/src/model/PREDICATE_COLLISION_FIX.md +651 -0
- package/src/model/README.md +317 -0
- package/src/model/SHACL_MUTATION_DECOUPLING.md +356 -0
- package/src/model/SUBSCRIPTION_STRATEGY.md +317 -0
- package/src/model/TC39_STAGE_3_DECORATORS.md +609 -0
- package/src/model/decorators.ts +689 -1046
- package/src/model/mutation.ts +461 -0
- package/src/model/parentUtils.ts +91 -0
- package/src/model/prolog/generatePrologFacts.ts +176 -0
- package/src/model/prolog/index.ts +1 -0
- package/src/model/query/ModelQueryBuilder.ts +173 -0
- package/src/model/query/fetchInstance.ts +181 -0
- package/src/model/query/hydration.ts +273 -0
- package/src/model/query/operations.ts +510 -0
- package/src/model/query/snapshot.ts +126 -0
- package/src/model/query/surrealCompiler.ts +376 -0
- package/src/model/schema/fromJSONSchema.ts +411 -0
- package/src/model/schema/metadata.ts +148 -0
- package/src/model/subscription.ts +307 -0
- package/src/model/transaction.ts +60 -0
- package/src/model/types.ts +207 -0
- package/src/model/util.ts +47 -48
- package/src/neighbourhood/NeighbourhoodClient.ts +393 -251
- package/src/neighbourhood/NeighbourhoodProxy.test.ts +3 -7
- package/src/neighbourhood/NeighbourhoodProxy.ts +58 -40
- package/src/perspectives/PerspectiveClient.ts +779 -540
- package/src/perspectives/PerspectiveProxy.ts +2860 -2053
- package/src/runtime/RuntimeClient.ts +775 -476
- package/src/shacl/SHACLFlow.test.ts +196 -129
- package/src/shacl/SHACLShape.test.ts +284 -190
- package/src/shacl/SHACLShape.ts +225 -172
- package/src/utils.ts +31 -17
- package/tsconfig.json +9 -10
- 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
|
|
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
|
-
*
|
|
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
|
-
|
|
53
|
+
readOnly?: boolean;
|
|
77
54
|
/**
|
|
78
|
-
* The language used to
|
|
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
|
-
*
|
|
108
|
-
*
|
|
109
|
-
* @
|
|
110
|
-
*
|
|
111
|
-
* @
|
|
112
|
-
*
|
|
113
|
-
* -
|
|
114
|
-
* -
|
|
115
|
-
* -
|
|
116
|
-
* -
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
206
|
-
*
|
|
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
|
-
*
|
|
217
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
290
|
-
*
|
|
291
|
-
*
|
|
292
|
-
* -
|
|
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
|
-
*
|
|
298
|
-
*
|
|
299
|
-
*
|
|
300
|
-
*
|
|
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
|
|
348
|
-
|
|
349
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
484
|
-
*
|
|
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
|
|
522
|
-
export {};
|
|
190
|
+
export declare function Model(opts: ModelConfig): (target: any) => void;
|