@coasys/ad4m 0.8.2-prerelease-2 → 0.9.0-rc2

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.
@@ -9,6 +9,10 @@ export type QueryPartialEntity<T> = {
9
9
  };
10
10
 
11
11
 
12
+ /**
13
+ * Class representing a subject entity.
14
+ * Can extend this class to create a new subject entity to add methods interact with SDNA and much better experience then using the bare bone methods.
15
+ */
12
16
  export class SubjectEntity {
13
17
  #baseExpression: string;
14
18
  #subjectClass: string;
@@ -17,12 +21,22 @@ export class SubjectEntity {
17
21
  author: string;
18
22
  timestamp: string;
19
23
 
24
+
25
+ /**
26
+ * Constructs a new subject.
27
+ * @param perspective - The perspective that the subject belongs to.
28
+ * @param baseExpression - The base expression of the subject.
29
+ * @param soruce - The source of the subject, the expression this instance is linked too.
30
+ */
20
31
  constructor(perspective: PerspectiveProxy, baseExpression?: string, source?: string) {
21
32
  this.#baseExpression = baseExpression ? baseExpression : Literal.from(makeRandomPrologAtom(24)).toUrl();
22
33
  this.#perspective = perspective;
23
34
  this.#source = source || "ad4m://self";
24
35
  }
25
36
 
37
+ /**
38
+ * Gets the base expression of the subject.
39
+ */
26
40
  get baseExpression() {
27
41
  return this.#baseExpression
28
42
  }
@@ -155,6 +169,17 @@ export class SubjectEntity {
155
169
  }
156
170
  }
157
171
 
172
+ /**
173
+ * Save the subject entity.
174
+ * This method will create a new subject with the base expression and add a new link from the source to the base expression with the predicate "ad4m://has_child".
175
+ *
176
+ * If a property has an action, it will perform the action (Only for collections).
177
+ * If a property is an array and is not empty, it will set the collection.
178
+ * If a property is not undefined, not null, and not an empty string, it will set the property.
179
+ *
180
+ *
181
+ * @throws Will throw an error if the subject entity cannot be converted to a subject class, or if the subject cannot be created, or if the link cannot be added, or if the subject entity cannot be updated.
182
+ */
158
183
  async save() {
159
184
  this.#subjectClass = await this.#perspective.stringOrTemplateObjectToSubjectClass(this)
160
185
 
@@ -171,13 +196,24 @@ export class SubjectEntity {
171
196
  await this.update()
172
197
  }
173
198
 
199
+ /**
200
+ * Update the subject entity.
201
+ *
202
+ * It will iterate over the properties of the subject entity.
203
+ *
204
+ * If a property has an action, it will perform the action (Only for collections).
205
+ * If a property is an array and is not empty, it will set the collection.
206
+ * If a property is not undefined, not null, and not an empty string, it will set the property.
207
+ *
208
+ * @throws Will throw an error if the subject entity cannot be converted to a subject class, or if a property cannot be set, or if a collection cannot be set, or if the data of the subject entity cannot be gotten.
209
+ */
174
210
  async update() {
175
211
  this.#subjectClass = await this.#perspective.stringOrTemplateObjectToSubjectClass(this)
176
212
 
177
213
  const entries = Object.entries(this);
178
214
 
179
215
  for (const [key, value] of entries) {
180
- if (value) {
216
+ if (value !== undefined && value !== null) {
181
217
  if (value?.action) {
182
218
  switch (value.action) {
183
219
  case 'setter':
@@ -194,7 +230,7 @@ export class SubjectEntity {
194
230
  }
195
231
  } else if (Array.isArray(value) && value.length > 0) {
196
232
  await this.setCollectionSetter(key, value)
197
- } else {
233
+ } else if (value !== undefined && value !== null && value !== "") {
198
234
  await this.setProperty(key, value);
199
235
  }
200
236
  }
@@ -203,17 +239,41 @@ export class SubjectEntity {
203
239
  await this.getData();
204
240
  }
205
241
 
242
+ /**
243
+ * Get the subject entity with all the properties & collection populated.
244
+ *
245
+ * @returns The subject entity.
246
+ *
247
+ * @throws Will throw an error if the subject entity cannot be converted to a subject class, or if the data of the subject entity cannot be gotten.
248
+ */
206
249
  async get() {
207
250
  this.#subjectClass = await this.#perspective.stringOrTemplateObjectToSubjectClass(this)
208
251
 
209
252
  return await this.getData()
210
253
  }
211
254
 
255
+
256
+ /**
257
+ * Delete the subject entity.
258
+ * This method will remove the subject from the perspective.
259
+ *
260
+ * @throws Will throw an error if the subject entity cannot be removed.
261
+ */
212
262
  async delete() {
213
263
  await this.#perspective.removeSubject(this, this.#baseExpression);
214
264
  }
215
265
 
216
- // TODO: implement simple quering like limit, skip etc.
266
+ /**
267
+ * Get all the subject entities of the subject class.
268
+ *
269
+ * NOTE: this is a static method and should be called on the class itself.
270
+ *
271
+ * @param perspective - The perspective that the subject belongs to.
272
+ *
273
+ * @returns The subject entities.
274
+ *
275
+ * @throws Will throw an error if the subject entity cannot be converted to a subject class, or if the subject proxies cannot be gotten.
276
+ */
217
277
  static async all(perspective: PerspectiveProxy) {
218
278
  let subjectClass = await perspective.stringOrTemplateObjectToSubjectClass(this)
219
279
  const proxies = await perspective.getAllSubjectProxies(subjectClass)
@@ -233,6 +293,18 @@ export class SubjectEntity {
233
293
  return []
234
294
  }
235
295
 
296
+ /**
297
+ * Query the subject entities of the subject class.
298
+ *
299
+ * NOTE: this is a static method and should be called on the class itself.
300
+ *
301
+ * @param perspective - The perspective that the subject belongs to.
302
+ * @param query - The query of the subject entities.
303
+ *
304
+ * @returns The subject entities.
305
+ *
306
+ * @throws Will throw an error if the subject entity cannot be converted to a subject class, or if the query cannot be inferred, or if the data of the subject entities cannot be gotten.
307
+ */
236
308
  static async query(perspective: PerspectiveProxy, query?: SubjectEntityQueryParam) {
237
309
  const source = query?.source || "ad4m://self";
238
310
  let subjectClass = await perspective.stringOrTemplateObjectToSubjectClass(this)
@@ -286,7 +358,12 @@ export type SubjectArray<T> = T[] | {
286
358
  }
287
359
 
288
360
  export type SubjectEntityQueryParam = {
361
+ // The source of the query.
289
362
  source?: string;
363
+
364
+ // The size of the query.
290
365
  size?: number;
366
+
367
+ // The page of the query.
291
368
  page?: number;
292
369
  }