@coasys/ad4m 0.12.0-rc1-dev.2 → 0.12.0-rc1-dev.4
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 +10 -3
- package/lib/index.cjs +6893 -5884
- package/lib/index.js +6889 -5872
- package/lib/src/Ad4mClient.d.ts +9 -16
- package/lib/src/Ad4mClient.js +46 -25
- package/lib/src/Literal.d.ts +1 -2
- package/lib/src/Literal.js +38 -35
- package/lib/src/SmartLiteral.d.ts +1 -2
- package/lib/src/SmartLiteral.js +30 -15
- package/lib/src/agent/AgentClient.d.ts +1 -4
- package/lib/src/agent/AgentClient.js +79 -99
- package/lib/src/ai/AIClient.d.ts +1 -2
- package/lib/src/ai/AIClient.js +224 -220
- package/lib/src/expression/ExpressionClient.d.ts +1 -1
- package/lib/src/expression/ExpressionClient.js +73 -86
- 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 +1351 -144
- package/lib/src/model/Ad4mModel.js +3760 -228
- package/lib/src/model/Ad4mModel.test.js +522 -979
- package/lib/src/model/Subject.d.ts +3 -3
- package/lib/src/model/Subject.js +25 -25
- package/lib/src/model/decorators.d.ts +444 -100
- package/lib/src/model/decorators.js +686 -321
- package/lib/src/model/util.d.ts +6 -6
- package/lib/src/model/util.js +24 -24
- package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +1 -5
- package/lib/src/neighbourhood/NeighbourhoodClient.js +179 -242
- package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +1 -2
- package/lib/src/neighbourhood/NeighbourhoodProxy.js +28 -13
- package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +5 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
- package/lib/src/perspectives/PerspectiveClient.js +240 -316
- package/lib/src/perspectives/PerspectiveProxy.d.ts +99 -61
- package/lib/src/perspectives/PerspectiveProxy.js +485 -832
- package/lib/src/runtime/RuntimeClient.d.ts +1 -5
- package/lib/src/runtime/RuntimeClient.js +238 -412
- package/lib/src/shacl/SHACLFlow.test.js +105 -164
- package/lib/src/shacl/SHACLShape.d.ts +12 -17
- package/lib/src/shacl/SHACLShape.js +115 -128
- package/lib/src/shacl/SHACLShape.test.js +176 -244
- 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/lib/src/utils.d.ts +0 -8
- package/lib/src/utils.js +7 -21
- package/package.json +15 -14
- package/src/Ad4mClient.test.ts +1315 -1564
- package/src/Ad4mClient.ts +54 -55
- package/src/Literal.test.ts +26 -45
- package/src/Literal.ts +66 -82
- package/src/SmartLiteral.ts +58 -74
- package/src/agent/AgentClient.ts +99 -144
- package/src/ai/AIClient.ts +359 -409
- package/src/expression/ExpressionClient.ts +96 -142
- package/src/index.ts +1 -1
- package/src/language/LanguageClient.ts +113 -137
- package/src/model/Ad4mModel.test.ts +616 -1114
- package/src/model/Ad4mModel.ts +4386 -451
- package/src/model/Subject.ts +159 -0
- package/src/model/decorators.ts +1168 -667
- package/src/model/util.ts +54 -53
- package/src/neighbourhood/NeighbourhoodClient.ts +266 -392
- package/src/neighbourhood/NeighbourhoodProxy.test.ts +7 -3
- package/src/neighbourhood/NeighbourhoodProxy.ts +40 -58
- package/src/perspectives/PerspectiveClient.ts +540 -779
- package/src/perspectives/PerspectiveProxy.ts +2067 -2860
- package/src/runtime/RuntimeClient.ts +476 -775
- package/src/shacl/SHACLFlow.test.ts +129 -196
- package/src/shacl/SHACLShape.test.ts +190 -284
- package/src/shacl/SHACLShape.ts +200 -224
- package/src/utils.ts +17 -31
- package/tsconfig.json +10 -9
- package/src/model/IMPROVEMENTS.md +0 -482
- package/src/model/PREDICATE_COLLISION_FIX.md +0 -651
- package/src/model/README.md +0 -317
- package/src/model/SHACL_MUTATION_DECOUPLING.md +0 -356
- package/src/model/SUBSCRIPTION_STRATEGY.md +0 -317
- package/src/model/TC39_STAGE_3_DECORATORS.md +0 -609
- package/src/model/mutation.ts +0 -461
- package/src/model/parentUtils.ts +0 -91
- package/src/model/prolog/generatePrologFacts.ts +0 -176
- package/src/model/prolog/index.ts +0 -1
- package/src/model/query/ModelQueryBuilder.ts +0 -173
- package/src/model/query/fetchInstance.ts +0 -181
- package/src/model/query/hydration.ts +0 -273
- package/src/model/query/operations.ts +0 -510
- package/src/model/query/snapshot.ts +0 -126
- package/src/model/query/surrealCompiler.ts +0 -376
- package/src/model/schema/fromJSONSchema.ts +0 -411
- package/src/model/schema/metadata.ts +0 -148
- package/src/model/subscription.ts +0 -307
- package/src/model/transaction.ts +0 -60
- package/src/model/types.ts +0 -207
|
@@ -1,22 +1,68 @@
|
|
|
1
|
-
|
|
2
|
-
export
|
|
3
|
-
/**
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
/** Metadata stored for each property via @Property / @Optional / @ReadOnly / @Flag */
|
|
2
|
+
export interface PropertyMetadataEntry extends PropertyOptions {
|
|
3
|
+
/** Internal computed writable flag (inverse of readOnly) for SDNA/SHACL compatibility */
|
|
4
|
+
writable?: boolean;
|
|
5
|
+
flag?: boolean;
|
|
6
|
+
}
|
|
7
|
+
/** Metadata stored for each relation via @HasMany / @HasOne / @BelongsToOne / @BelongsToMany */
|
|
8
|
+
export interface RelationMetadataEntry {
|
|
9
|
+
predicate: string;
|
|
10
|
+
/** Target model class thunk. Optional for untyped string relations. */
|
|
11
|
+
target?: () => Ad4mModelLike;
|
|
12
|
+
kind: 'hasMany' | 'hasOne' | 'belongsToOne' | 'belongsToMany';
|
|
13
|
+
/**
|
|
14
|
+
* Maximum number of related instances.
|
|
15
|
+
* Set automatically: 1 for `@HasOne`/`@BelongsToOne`, undefined (unlimited) for `*Many`.
|
|
16
|
+
*/
|
|
17
|
+
maxCount?: number;
|
|
18
|
+
local?: boolean;
|
|
19
|
+
/**
|
|
20
|
+
* Custom SurrealQL getter to resolve the relation values.
|
|
21
|
+
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
22
|
+
*/
|
|
23
|
+
getter?: string;
|
|
24
|
+
}
|
|
7
25
|
/**
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
26
|
+
* Retrieve property metadata for a given class constructor.
|
|
27
|
+
* Walks the prototype chain so subclass decorators compose with parent decorators.
|
|
28
|
+
*/
|
|
29
|
+
export declare function getPropertiesMetadata(ctor: Function): Record<string, PropertyMetadataEntry>;
|
|
30
|
+
/**
|
|
31
|
+
* Retrieve relation metadata for a given class constructor.
|
|
32
|
+
* Walks the prototype chain so subclass decorators compose with parent decorators.
|
|
33
|
+
*/
|
|
34
|
+
export declare function getRelationsMetadata(ctor: Function): Record<string, RelationMetadataEntry>;
|
|
35
|
+
/**
|
|
36
|
+
* Programmatically register property metadata for a given constructor.
|
|
37
|
+
* Used by `fromJSONSchema()` and other dynamic model builders.
|
|
38
|
+
*/
|
|
39
|
+
export declare function setPropertyRegistryEntry(ctor: Function, propName: string, meta: PropertyMetadataEntry & {
|
|
40
|
+
writable?: boolean;
|
|
41
|
+
}): void;
|
|
42
|
+
/**
|
|
43
|
+
* Programmatically register relation metadata for a given constructor.
|
|
44
|
+
* Used by `fromJSONSchema()` and other dynamic model builders.
|
|
45
|
+
*/
|
|
46
|
+
export declare function setRelationRegistryEntry(ctor: Function, relName: string, meta: RelationMetadataEntry): void;
|
|
47
|
+
/**
|
|
48
|
+
* Interface for any class that looks like an Ad4mModel (used in circular-ref-safe typings).
|
|
18
49
|
*/
|
|
19
|
-
export
|
|
50
|
+
export interface Ad4mModelLike {
|
|
51
|
+
new (...args: any[]): any;
|
|
52
|
+
className?: string;
|
|
53
|
+
generateSDNA?: () => any;
|
|
54
|
+
generateSHACL?: () => any;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Convert a model instance to a plain serializable object.
|
|
58
|
+
* Reads the property metadata and extracts values from the instance.
|
|
59
|
+
*/
|
|
60
|
+
export declare function instanceToSerializable(instance: any): Record<string, any>;
|
|
61
|
+
/**
|
|
62
|
+
* Generate a random identifier string (lowercase alpha).
|
|
63
|
+
* Generate a random identifier string of the given length (lowercase alpha).
|
|
64
|
+
*/
|
|
65
|
+
export declare function makeRandomId(length: number): string;
|
|
20
66
|
export declare class PerspectiveAction {
|
|
21
67
|
action: string;
|
|
22
68
|
source: string;
|
|
@@ -31,14 +77,7 @@ export interface PropertyOptions {
|
|
|
31
77
|
*/
|
|
32
78
|
through?: string;
|
|
33
79
|
/**
|
|
34
|
-
* The initial value
|
|
35
|
-
*
|
|
36
|
-
* For non-readOnly properties this is **optional** — Ad4mModel
|
|
37
|
-
* automatically derives a placeholder and overwrites it with the real
|
|
38
|
-
* instance field value when `save()` is called. Only set this explicitly
|
|
39
|
-
* when you need a specific non-literal default URI (e.g. a custom
|
|
40
|
-
* `resolveLanguage` address) or want a sentinel value if the property
|
|
41
|
-
* is never set.
|
|
80
|
+
* The initial value of the property. Required if the property is marked as required.
|
|
42
81
|
*/
|
|
43
82
|
initial?: string;
|
|
44
83
|
/**
|
|
@@ -46,20 +85,22 @@ export interface PropertyOptions {
|
|
|
46
85
|
*/
|
|
47
86
|
required?: boolean;
|
|
48
87
|
/**
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
* (writable) when `through` is set.
|
|
88
|
+
* Indicates whether the property is read-only. If true, no setter will be generated.
|
|
89
|
+
* Defaults to false (property is writable).
|
|
52
90
|
*/
|
|
53
91
|
readOnly?: boolean;
|
|
54
92
|
/**
|
|
55
|
-
* The language used to
|
|
56
|
-
*
|
|
57
|
-
* Omitting this (the common case) is equivalent to `"literal"` — scalar values
|
|
58
|
-
* (string / number / boolean) are encoded as `literal://` URIs automatically.
|
|
59
|
-
* Only specify this when you need a non-literal language (e.g. a custom IPFS
|
|
60
|
-
* language address) or want to be explicit for documentation purposes.
|
|
93
|
+
* The language used to store the property. Can be the default `Literal` Language or a custom language address.
|
|
61
94
|
*/
|
|
62
95
|
resolveLanguage?: string;
|
|
96
|
+
/**
|
|
97
|
+
* Custom Prolog getter to get the value of the property. If not provided, the default getter will be used.
|
|
98
|
+
*/
|
|
99
|
+
prologGetter?: string;
|
|
100
|
+
/**
|
|
101
|
+
* Custom Prolog setter to set the value of the property. Only available if the property is writable.
|
|
102
|
+
*/
|
|
103
|
+
prologSetter?: string;
|
|
63
104
|
/**
|
|
64
105
|
* Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
|
|
65
106
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
@@ -76,26 +117,28 @@ export interface PropertyOptions {
|
|
|
76
117
|
* The function takes the raw value as input and returns the transformed value.
|
|
77
118
|
*/
|
|
78
119
|
transform?: (value: any) => any;
|
|
79
|
-
/**
|
|
80
|
-
* Indicates that this property is a @Flag — a fixed predicate/value pair written
|
|
81
|
-
* once by the createSubject constructor action and never changed. Flag properties
|
|
82
|
-
* are immutable and will be skipped during updates.
|
|
83
|
-
*/
|
|
84
|
-
flag?: boolean;
|
|
85
120
|
}
|
|
86
121
|
/**
|
|
87
|
-
*
|
|
122
|
+
* Convenience decorator for defining optional (not required) properties.
|
|
123
|
+
*
|
|
124
|
+
* @category Decorators
|
|
125
|
+
*
|
|
126
|
+
* @description
|
|
127
|
+
* Equivalent to `@Property` but defaults `required` to `false` and does not
|
|
128
|
+
* apply `resolveLanguage` or `initial` defaults. Use this when a property
|
|
129
|
+
* may or may not have a value, and you want full control over its configuration.
|
|
130
|
+
*
|
|
131
|
+
* @example
|
|
132
|
+
* ```typescript
|
|
133
|
+
* class Recipe extends Ad4mModel {
|
|
134
|
+
* @Optional({ through: "recipe://description" })
|
|
135
|
+
* description?: string;
|
|
136
|
+
* }
|
|
137
|
+
* ```
|
|
88
138
|
*
|
|
89
|
-
* @param opts
|
|
90
|
-
* @param opts.initial - Default value written by the constructor action (auto-derived for non-readOnly properties; only needed for custom URIs)
|
|
91
|
-
* @param opts.required - Adds `sh:minCount 1` to the SHACL shape
|
|
92
|
-
* @param opts.readOnly - Skips setter generation; property cannot be updated after creation (default: false)
|
|
93
|
-
* @param opts.resolveLanguage - Language for value resolution (`"literal"`, etc.)
|
|
94
|
-
* @param opts.local - Store only in local perspective, not shared with the network
|
|
95
|
-
* @param opts.getter - Custom SurrealQL expression for computed / read-only properties
|
|
96
|
-
* @param opts.transform - Post-fetch transform applied to the raw value
|
|
139
|
+
* @param {PropertyOptions} opts - Property configuration (same options as @Property)
|
|
97
140
|
*/
|
|
98
|
-
export declare function
|
|
141
|
+
export declare function Optional(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
|
|
99
142
|
export interface FlagOptions {
|
|
100
143
|
/**
|
|
101
144
|
* The predicate of the property. All properties must have this option.
|
|
@@ -107,84 +150,385 @@ export interface FlagOptions {
|
|
|
107
150
|
value: string;
|
|
108
151
|
}
|
|
109
152
|
/**
|
|
110
|
-
*
|
|
153
|
+
* Decorator for defining flags on model classes.
|
|
154
|
+
*
|
|
155
|
+
* @category Decorators
|
|
156
|
+
*
|
|
157
|
+
* @description
|
|
158
|
+
* A specialized property decorator for defining immutable type flags or markers on model instances.
|
|
159
|
+
* Flags are always required properties with a fixed value that cannot be changed after creation.
|
|
111
160
|
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
161
|
+
* Common uses for flags:
|
|
162
|
+
* - Type discrimination between different kinds of models
|
|
163
|
+
* - Marking models with specific capabilities or features
|
|
164
|
+
* - Versioning or compatibility markers
|
|
165
|
+
*
|
|
166
|
+
* Note: Use of Flag is discouraged unless you specifically need type-based filtering or
|
|
167
|
+
* discrimination between different kinds of models. For most cases, regular properties
|
|
168
|
+
* with @Property or @Optional are more appropriate.
|
|
114
169
|
*
|
|
115
170
|
* @example
|
|
116
171
|
* ```typescript
|
|
117
|
-
*
|
|
118
|
-
*
|
|
172
|
+
* class Message extends Ad4mModel {
|
|
173
|
+
* // Type flag to identify message models
|
|
174
|
+
* @Flag({
|
|
175
|
+
* through: "ad4m://type",
|
|
176
|
+
* value: "ad4m://message"
|
|
177
|
+
* })
|
|
178
|
+
* type: string = "";
|
|
179
|
+
*
|
|
180
|
+
* // Version flag for compatibility
|
|
181
|
+
* @Flag({
|
|
182
|
+
* through: "ad4m://version",
|
|
183
|
+
* value: "1.0.0"
|
|
184
|
+
* })
|
|
185
|
+
* version: string = "";
|
|
186
|
+
*
|
|
187
|
+
* // Feature flag
|
|
188
|
+
* @Flag({
|
|
189
|
+
* through: "message://feature",
|
|
190
|
+
* value: "message://encrypted"
|
|
191
|
+
* })
|
|
192
|
+
* feature: string = "";
|
|
193
|
+
* }
|
|
194
|
+
*
|
|
195
|
+
* // Later you can query for specific types:
|
|
196
|
+
* const messages = await Message.query(perspective)
|
|
197
|
+
* .where({ type: "ad4m://message" })
|
|
198
|
+
* .run();
|
|
119
199
|
* ```
|
|
200
|
+
*
|
|
201
|
+
* @param {FlagOptions} opts - Flag configuration
|
|
202
|
+
* @param {string} opts.through - The predicate URI for the flag
|
|
203
|
+
* @param {string} opts.value - The fixed value for the flag
|
|
120
204
|
*/
|
|
121
205
|
export declare function Flag(opts: FlagOptions): <T>(target: T, key: keyof T) => void;
|
|
122
|
-
export interface
|
|
206
|
+
export interface ModelConfig {
|
|
123
207
|
/**
|
|
124
|
-
* The
|
|
208
|
+
* The name of the entity.
|
|
125
209
|
*/
|
|
210
|
+
name: string;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Decorator for defining model classes in AD4M.
|
|
214
|
+
*
|
|
215
|
+
* @category Decorators
|
|
216
|
+
*
|
|
217
|
+
* @description
|
|
218
|
+
* The root decorator that must be applied to any class that represents a model in AD4M.
|
|
219
|
+
* It registers the class as a Social DNA (SDNA) subject class and provides the infrastructure
|
|
220
|
+
* for storing and retrieving instances.
|
|
221
|
+
*
|
|
222
|
+
* This decorator:
|
|
223
|
+
* - Registers the class with a unique name in the AD4M system
|
|
224
|
+
* - Generates the necessary SDNA code for the model's properties and relations
|
|
225
|
+
* - Enables the use of other model decorators (@Property, @HasMany, etc.)
|
|
226
|
+
* - Provides static query methods through the Ad4mModel base class
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* ```typescript
|
|
230
|
+
* @Model({ name: "Recipe" })
|
|
231
|
+
* class Recipe extends Ad4mModel {
|
|
232
|
+
* @Property({
|
|
233
|
+
* through: "recipe://name",
|
|
234
|
+
* resolveLanguage: "literal"
|
|
235
|
+
* })
|
|
236
|
+
* name: string = "";
|
|
237
|
+
*
|
|
238
|
+
* @HasMany({ through: "recipe://ingredient" })
|
|
239
|
+
* ingredients: string[] = [];
|
|
240
|
+
*
|
|
241
|
+
* // Static query methods from Ad4mModel:
|
|
242
|
+
* static async findByName(perspective: PerspectiveProxy, name: string) {
|
|
243
|
+
* return Recipe.query(perspective)
|
|
244
|
+
* .where({ name })
|
|
245
|
+
* .run();
|
|
246
|
+
* }
|
|
247
|
+
* }
|
|
248
|
+
*
|
|
249
|
+
* // Using the model:
|
|
250
|
+
* const recipe = new Recipe(perspective);
|
|
251
|
+
* recipe.name = "Chocolate Cake";
|
|
252
|
+
* await recipe.save();
|
|
253
|
+
*
|
|
254
|
+
* // Querying instances:
|
|
255
|
+
* const recipes = await Recipe.query(perspective)
|
|
256
|
+
* .where({ name: "Chocolate Cake" })
|
|
257
|
+
* .run();
|
|
258
|
+
*
|
|
259
|
+
* // Using with PerspectiveProxy:
|
|
260
|
+
* await perspective.ensureSDNASubjectClass(Recipe);
|
|
261
|
+
* ```
|
|
262
|
+
*
|
|
263
|
+
* @param {ModelConfig} opts - Model configuration
|
|
264
|
+
* @param {string} opts.name - Unique name for the model class in AD4M
|
|
265
|
+
*/
|
|
266
|
+
export declare function Model(opts: ModelConfig): (target: any) => void;
|
|
267
|
+
/**
|
|
268
|
+
* The primary property decorator for AD4M model classes.
|
|
269
|
+
*
|
|
270
|
+
* @category Decorators
|
|
271
|
+
*
|
|
272
|
+
* @description
|
|
273
|
+
* The core property decorator with smart defaults. All other property decorators
|
|
274
|
+
* (@Optional, @ReadOnly) are thin wrappers that adjust these defaults.
|
|
275
|
+
*
|
|
276
|
+
* Smart defaults (all overridable):
|
|
277
|
+
* - `required` → `false`
|
|
278
|
+
* - `readOnly` → `false`
|
|
279
|
+
* - `resolveLanguage` → `"literal"`
|
|
280
|
+
* - `initial` → `undefined` (no link created until a value is explicitly set)
|
|
281
|
+
*
|
|
282
|
+
* Properties are optional by default. When a model instance is created without
|
|
283
|
+
* providing a value for an optional property, no link is added to the graph.
|
|
284
|
+
* Set `required: true` explicitly when a property must always be present (this
|
|
285
|
+
* also adds a `"literal://string:uninitialized"` sentinel as the initial value
|
|
286
|
+
* so that the SDNA constructor creates a placeholder link).
|
|
287
|
+
*
|
|
288
|
+
* @example
|
|
289
|
+
* ```typescript
|
|
290
|
+
* class User extends Ad4mModel {
|
|
291
|
+
* // Optional property (default) — no link created until a value is set
|
|
292
|
+
* @Property({
|
|
293
|
+
* through: "user://name"
|
|
294
|
+
* })
|
|
295
|
+
* name: string = "";
|
|
296
|
+
*
|
|
297
|
+
* // Explicitly required property with sentinel initial value
|
|
298
|
+
* @Property({
|
|
299
|
+
* through: "user://status",
|
|
300
|
+
* required: true
|
|
301
|
+
* })
|
|
302
|
+
* status: string = "";
|
|
303
|
+
*
|
|
304
|
+
* // Required property with custom initial value
|
|
305
|
+
* @Property({
|
|
306
|
+
* through: "user://role",
|
|
307
|
+
* required: true,
|
|
308
|
+
* initial: "user://member"
|
|
309
|
+
* })
|
|
310
|
+
* role: string = "";
|
|
311
|
+
*
|
|
312
|
+
* // Optional property with literal resolution
|
|
313
|
+
* @Property({
|
|
314
|
+
* through: "user://bio",
|
|
315
|
+
* resolveLanguage: "literal"
|
|
316
|
+
* })
|
|
317
|
+
* bio: string = "";
|
|
318
|
+
* }
|
|
319
|
+
* ```
|
|
320
|
+
*
|
|
321
|
+
* @param {PropertyOptions} opts - Property configuration
|
|
322
|
+
* @param {string} opts.through - The predicate URI for the property
|
|
323
|
+
* @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
|
|
324
|
+
* @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized" when required)
|
|
325
|
+
* @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
|
|
326
|
+
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
327
|
+
* @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
|
|
328
|
+
* @param {boolean} [opts.local] - Whether the property should only be stored locally
|
|
329
|
+
*/
|
|
330
|
+
export declare function Property(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
|
|
331
|
+
/**
|
|
332
|
+
* Decorator for defining read-only properties on model classes.
|
|
333
|
+
*
|
|
334
|
+
* @category Decorators
|
|
335
|
+
*
|
|
336
|
+
* @description
|
|
337
|
+
* A convenience decorator that defines a read-only property.
|
|
338
|
+
* Equivalent to `@Property` with `readOnly: true`.
|
|
339
|
+
*
|
|
340
|
+
* Read-only properties are ideal for:
|
|
341
|
+
* - Computed or derived values
|
|
342
|
+
* - Properties that should never change after creation
|
|
343
|
+
* - Properties that are set by the system
|
|
344
|
+
* - Properties that represent immutable data
|
|
345
|
+
*
|
|
346
|
+
* @example
|
|
347
|
+
* ```typescript
|
|
348
|
+
* class Post extends Ad4mModel {
|
|
349
|
+
* // Read-only property with custom getter for computed value
|
|
350
|
+
* @ReadOnly({
|
|
351
|
+
* through: "post://likes",
|
|
352
|
+
* getter: `findall(User, triple(Base, "post://liked_by", User), Users), length(Users, Value)`
|
|
353
|
+
* })
|
|
354
|
+
* likeCount: number = 0;
|
|
355
|
+
*
|
|
356
|
+
* // Read-only property for creation timestamp
|
|
357
|
+
* @ReadOnly({
|
|
358
|
+
* through: "post://created_at",
|
|
359
|
+
* initial: new Date().toISOString()
|
|
360
|
+
* })
|
|
361
|
+
* createdAt: string = "";
|
|
362
|
+
*
|
|
363
|
+
* // Read-only property that resolves to a Literal
|
|
364
|
+
* @ReadOnly({
|
|
365
|
+
* through: "post://author",
|
|
366
|
+
* resolveLanguage: "literal"
|
|
367
|
+
* })
|
|
368
|
+
* author: string = "";
|
|
369
|
+
*
|
|
370
|
+
* // Read-only property for system-managed data
|
|
371
|
+
* @ReadOnly({
|
|
372
|
+
* through: "post://version",
|
|
373
|
+
* initial: "1.0.0"
|
|
374
|
+
* })
|
|
375
|
+
* version: string = "";
|
|
376
|
+
* }
|
|
377
|
+
* ```
|
|
378
|
+
*
|
|
379
|
+
* @param {PropertyOptions} opts - Property configuration
|
|
380
|
+
* @param {string} opts.through - The predicate URI for the property
|
|
381
|
+
* @param {string} [opts.initial] - Initial value (if property should have one)
|
|
382
|
+
* @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
|
|
383
|
+
* @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
|
|
384
|
+
* @param {boolean} [opts.local] - Whether the property should only be stored locally
|
|
385
|
+
*/
|
|
386
|
+
export declare function ReadOnly(opts: PropertyOptions): <T>(target: T, key: keyof T) => void;
|
|
387
|
+
/**
|
|
388
|
+
* Options for relation decorators (@HasMany, @HasOne, @BelongsToOne, @BelongsToMany).
|
|
389
|
+
*/
|
|
390
|
+
export interface RelationOptions {
|
|
391
|
+
/** The predicate URI used to link the two models */
|
|
126
392
|
through: string;
|
|
393
|
+
/** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string relations. */
|
|
394
|
+
target?: () => Ad4mModelLike;
|
|
127
395
|
/**
|
|
128
|
-
* Custom SurrealQL getter to resolve the
|
|
396
|
+
* Custom SurrealQL getter to resolve the relation values. Use this for custom graph traversals.
|
|
129
397
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
130
|
-
* Example: "(<-link[WHERE predicate = 'flux://has_reply'].
|
|
398
|
+
* Example: "(<-link[WHERE predicate = 'flux://has_reply'].out.uri)"
|
|
131
399
|
*/
|
|
132
400
|
getter?: string;
|
|
133
|
-
/**
|
|
134
|
-
* Indicates whether the property is stored locally in the perspective and not in the network. Useful for properties that are not meant to be shared with the network.
|
|
135
|
-
*/
|
|
401
|
+
/** Whether the link is stored locally (not shared on the network) */
|
|
136
402
|
local?: boolean;
|
|
137
403
|
}
|
|
138
|
-
/** Minimal structural type for Ad4mModel instances — used in mutator signatures to avoid circular imports. */
|
|
139
|
-
export interface Ad4mModelLike {
|
|
140
|
-
readonly id: string;
|
|
141
|
-
}
|
|
142
404
|
/**
|
|
143
|
-
* Utility type that
|
|
405
|
+
* Utility type that describes the auto-generated helper methods for a HasMany
|
|
406
|
+
* relation. For a property named `comments` on a class `Post`, the following
|
|
407
|
+
* methods will be available on instances:
|
|
144
408
|
*
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
148
|
-
|
|
409
|
+
* post.addComment(value)
|
|
410
|
+
* post.removeComment(value)
|
|
411
|
+
* post.setComment(values)
|
|
412
|
+
*/
|
|
413
|
+
export type HasManyMethods<Keys extends string> = {
|
|
414
|
+
[K in Keys as `add${Capitalize<K>}`]: (value: string | {
|
|
415
|
+
id: string;
|
|
416
|
+
}, batchId?: string) => Promise<void>;
|
|
417
|
+
} & {
|
|
418
|
+
[K in Keys as `remove${Capitalize<K>}`]: (value: string | {
|
|
419
|
+
id: string;
|
|
420
|
+
}, batchId?: string) => Promise<void>;
|
|
421
|
+
} & {
|
|
422
|
+
[K in Keys as `set${Capitalize<K>}`]: (values: (string | {
|
|
423
|
+
id: string;
|
|
424
|
+
})[], batchId?: string) => Promise<void>;
|
|
425
|
+
};
|
|
426
|
+
/**
|
|
427
|
+
* Decorator for defining a one-to-many relation.
|
|
428
|
+
*
|
|
429
|
+
* @category Decorators
|
|
430
|
+
*
|
|
431
|
+
* @description
|
|
432
|
+
* Declares that the decorated property is an array of related model instances.
|
|
433
|
+
* Under the hood it registers the relation in the relation registry and also
|
|
434
|
+
* creates the corresponding relation entry so that the SDNA / SHACL
|
|
435
|
+
* generators continue to emit the correct subject-class code.
|
|
436
|
+
*
|
|
437
|
+
* Supports two calling conventions:
|
|
438
|
+
* ```typescript
|
|
439
|
+
* // Options-object style
|
|
440
|
+
* @HasMany({ through: "post://comment", target: () => Comment })
|
|
441
|
+
*
|
|
442
|
+
* // Target-first shorthand
|
|
443
|
+
* @HasMany(() => Comment, { through: "post://comment" })
|
|
444
|
+
* ```
|
|
149
445
|
*
|
|
150
|
-
* Pass a string union of your \@HasMany/\@HasOne property names and use interface merging:
|
|
151
446
|
* @example
|
|
152
447
|
* ```typescript
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
*
|
|
156
|
-
* comments:
|
|
448
|
+
* @Model({ name: "Post" })
|
|
449
|
+
* class Post extends Ad4mModel {
|
|
450
|
+
* @HasMany(() => Comment, { through: "post://comment" })
|
|
451
|
+
* comments: string[] = [];
|
|
157
452
|
* }
|
|
158
|
-
* export interface Post extends HasManyMethods<'comments'> {}
|
|
159
453
|
* ```
|
|
160
454
|
*/
|
|
161
|
-
export
|
|
162
|
-
|
|
163
|
-
} & {
|
|
164
|
-
[K in Keys as `remove${Capitalize<K>}`]: (value: string | Ad4mModelLike, batchId?: string) => Promise<void>;
|
|
165
|
-
} & {
|
|
166
|
-
[K in Keys as `set${Capitalize<K>}`]: (values: (string | Ad4mModelLike)[], batchId?: string) => Promise<void>;
|
|
167
|
-
};
|
|
168
|
-
export declare function HasMany(relatedModelOrOpts: (() => any) | RelationOptions, opts?: RelationOptions): <T>(target: T, key: keyof T) => void;
|
|
169
|
-
export declare function HasOne(relatedModelOrOpts: (() => any) | RelationOptions, opts?: RelationOptions): <T>(target: T, key: keyof T) => void;
|
|
170
|
-
export declare function BelongsToOne(relatedModel: () => any, opts: RelationOptions): <T>(target: T, key: keyof T) => void;
|
|
171
|
-
export declare function BelongsToMany(relatedModel: () => any, opts: RelationOptions): <T>(target: T, key: keyof T) => void;
|
|
172
|
-
export declare function makeRandomId(length: number): string;
|
|
173
|
-
export interface ModelConfig {
|
|
174
|
-
/**
|
|
175
|
-
* The name of the entity.
|
|
176
|
-
*/
|
|
177
|
-
name: string;
|
|
178
|
-
}
|
|
455
|
+
export declare function HasMany(opts: RelationOptions): PropertyDecorator;
|
|
456
|
+
export declare function HasMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
|
|
179
457
|
/**
|
|
180
|
-
*
|
|
458
|
+
* Decorator for defining a one-to-one relation (owning side).
|
|
459
|
+
*
|
|
460
|
+
* @category Decorators
|
|
181
461
|
*
|
|
182
|
-
*
|
|
462
|
+
* @description
|
|
463
|
+
* Declares that the decorated property holds a single related model instance.
|
|
464
|
+
* The owning side manages the link.
|
|
465
|
+
*
|
|
466
|
+
* Supports two calling conventions:
|
|
467
|
+
* ```typescript
|
|
468
|
+
* @HasOne({ through: "post://author", target: () => Author })
|
|
469
|
+
* @HasOne(() => Author, { through: "post://author" })
|
|
470
|
+
* ```
|
|
183
471
|
*
|
|
184
472
|
* @example
|
|
185
473
|
* ```typescript
|
|
186
|
-
* @Model({ name: "
|
|
187
|
-
* class
|
|
474
|
+
* @Model({ name: "Post" })
|
|
475
|
+
* class Post extends Ad4mModel {
|
|
476
|
+
* @HasOne(() => Author, { through: "post://author" })
|
|
477
|
+
* author: string = "";
|
|
478
|
+
* }
|
|
188
479
|
* ```
|
|
189
480
|
*/
|
|
190
|
-
export declare function
|
|
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;
|