@coasys/ad4m 0.12.0-rc1-dev → 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.
Files changed (128) hide show
  1. package/jest.config.js +4 -4
  2. package/lib/index.cjs +5999 -6044
  3. package/lib/index.js +5977 -6038
  4. package/lib/src/Ad4mClient.d.ts +16 -9
  5. package/lib/src/Ad4mClient.js +25 -46
  6. package/lib/src/Ad4mClient.test.d.ts +1 -0
  7. package/lib/src/Ad4mClient.test.js +1204 -0
  8. package/lib/src/Literal.d.ts +2 -1
  9. package/lib/src/Literal.js +35 -38
  10. package/lib/src/Literal.test.d.ts +1 -0
  11. package/lib/src/Literal.test.js +41 -0
  12. package/lib/src/SmartLiteral.d.ts +2 -1
  13. package/lib/src/SmartLiteral.js +15 -30
  14. package/lib/src/agent/AgentClient.d.ts +4 -1
  15. package/lib/src/agent/AgentClient.js +99 -79
  16. package/lib/src/ai/AIClient.d.ts +2 -1
  17. package/lib/src/ai/AIClient.js +220 -224
  18. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  19. package/lib/src/expression/ExpressionClient.js +86 -73
  20. package/lib/src/index.d.ts +1 -1
  21. package/lib/src/index.js +1 -1
  22. package/lib/src/language/LanguageClient.d.ts +1 -1
  23. package/lib/src/language/LanguageClient.js +52 -52
  24. package/lib/src/model/Ad4mModel.d.ts +157 -937
  25. package/lib/src/model/Ad4mModel.js +212 -2797
  26. package/lib/src/model/Ad4mModel.test.js +1002 -561
  27. package/lib/src/model/decorators.d.ts +94 -426
  28. package/lib/src/model/decorators.js +333 -741
  29. package/lib/src/model/mutation.d.ts +81 -0
  30. package/lib/src/model/mutation.js +317 -0
  31. package/lib/src/model/parentUtils.d.ts +32 -0
  32. package/lib/src/model/parentUtils.js +64 -0
  33. package/lib/src/model/prolog/generatePrologFacts.d.ts +36 -0
  34. package/lib/src/model/prolog/generatePrologFacts.js +139 -0
  35. package/lib/src/model/prolog/index.d.ts +1 -0
  36. package/lib/src/model/prolog/index.js +1 -0
  37. package/lib/src/model/query/ModelQueryBuilder.d.ts +82 -0
  38. package/lib/src/model/query/ModelQueryBuilder.js +115 -0
  39. package/lib/src/model/query/QueryBuilder.d.ts +101 -0
  40. package/lib/src/model/query/QueryBuilder.js +193 -0
  41. package/lib/src/model/query/SurrealQueryBuilder.d.ts +48 -0
  42. package/lib/src/model/query/SurrealQueryBuilder.js +371 -0
  43. package/lib/src/model/query/fetchInstance.d.ts +24 -0
  44. package/lib/src/model/query/fetchInstance.js +144 -0
  45. package/lib/src/model/query/hydration.d.ts +54 -0
  46. package/lib/src/model/query/hydration.js +214 -0
  47. package/lib/src/model/query/operations.d.ts +59 -0
  48. package/lib/src/model/query/operations.js +384 -0
  49. package/lib/src/model/query/snapshot.d.ts +59 -0
  50. package/lib/src/model/query/snapshot.js +106 -0
  51. package/lib/src/model/query/surrealCompiler.d.ts +42 -0
  52. package/lib/src/model/query/surrealCompiler.js +304 -0
  53. package/lib/src/model/schema/fromJSONSchema.d.ts +67 -0
  54. package/lib/src/model/schema/fromJSONSchema.js +264 -0
  55. package/lib/src/model/schema/metadata.d.ts +15 -0
  56. package/lib/src/model/schema/metadata.js +112 -0
  57. package/lib/src/model/subscription.d.ts +47 -0
  58. package/lib/src/model/subscription.js +231 -0
  59. package/lib/src/model/transaction.d.ts +27 -0
  60. package/lib/src/model/transaction.js +32 -0
  61. package/lib/src/model/types.d.ts +195 -0
  62. package/lib/src/model/types.js +8 -0
  63. package/lib/src/model/util.js +7 -7
  64. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +5 -1
  65. package/lib/src/neighbourhood/NeighbourhoodClient.js +263 -181
  66. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +2 -1
  67. package/lib/src/neighbourhood/NeighbourhoodProxy.js +13 -28
  68. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +1 -5
  69. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  70. package/lib/src/perspectives/PerspectiveClient.js +316 -240
  71. package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -92
  72. package/lib/src/perspectives/PerspectiveProxy.js +803 -444
  73. package/lib/src/runtime/RuntimeClient.d.ts +5 -1
  74. package/lib/src/runtime/RuntimeClient.js +412 -238
  75. package/lib/src/shacl/SHACLFlow.test.js +164 -105
  76. package/lib/src/shacl/SHACLShape.d.ts +17 -3
  77. package/lib/src/shacl/SHACLShape.js +127 -90
  78. package/lib/src/shacl/SHACLShape.test.js +244 -176
  79. package/lib/src/utils.d.ts +8 -0
  80. package/lib/src/utils.js +21 -7
  81. package/package.json +8 -13
  82. package/src/Ad4mClient.test.ts +1564 -1315
  83. package/src/Ad4mClient.ts +55 -54
  84. package/src/Literal.test.ts +45 -26
  85. package/src/Literal.ts +82 -66
  86. package/src/SmartLiteral.ts +74 -58
  87. package/src/agent/AgentClient.ts +144 -99
  88. package/src/ai/AIClient.ts +409 -359
  89. package/src/expression/ExpressionClient.ts +142 -96
  90. package/src/index.ts +1 -1
  91. package/src/language/LanguageClient.ts +137 -113
  92. package/src/model/Ad4mModel.test.ts +1128 -647
  93. package/src/model/Ad4mModel.ts +485 -3247
  94. package/src/model/IMPROVEMENTS.md +482 -0
  95. package/src/model/PREDICATE_COLLISION_FIX.md +651 -0
  96. package/src/model/README.md +317 -0
  97. package/src/model/SHACL_MUTATION_DECOUPLING.md +356 -0
  98. package/src/model/SUBSCRIPTION_STRATEGY.md +317 -0
  99. package/src/model/TC39_STAGE_3_DECORATORS.md +609 -0
  100. package/src/model/decorators.ts +689 -1046
  101. package/src/model/mutation.ts +461 -0
  102. package/src/model/parentUtils.ts +91 -0
  103. package/src/model/prolog/generatePrologFacts.ts +176 -0
  104. package/src/model/prolog/index.ts +1 -0
  105. package/src/model/query/ModelQueryBuilder.ts +173 -0
  106. package/src/model/query/fetchInstance.ts +181 -0
  107. package/src/model/query/hydration.ts +273 -0
  108. package/src/model/query/operations.ts +510 -0
  109. package/src/model/query/snapshot.ts +126 -0
  110. package/src/model/query/surrealCompiler.ts +376 -0
  111. package/src/model/schema/fromJSONSchema.ts +411 -0
  112. package/src/model/schema/metadata.ts +148 -0
  113. package/src/model/subscription.ts +307 -0
  114. package/src/model/transaction.ts +60 -0
  115. package/src/model/types.ts +207 -0
  116. package/src/model/util.ts +47 -48
  117. package/src/neighbourhood/NeighbourhoodClient.ts +393 -251
  118. package/src/neighbourhood/NeighbourhoodProxy.test.ts +3 -7
  119. package/src/neighbourhood/NeighbourhoodProxy.ts +58 -40
  120. package/src/perspectives/PerspectiveClient.ts +779 -540
  121. package/src/perspectives/PerspectiveProxy.ts +2860 -2053
  122. package/src/runtime/RuntimeClient.ts +775 -476
  123. package/src/shacl/SHACLFlow.test.ts +196 -129
  124. package/src/shacl/SHACLShape.test.ts +284 -190
  125. package/src/shacl/SHACLShape.ts +225 -172
  126. package/src/utils.ts +31 -17
  127. package/tsconfig.json +9 -10
  128. package/src/model/Subject.ts +0 -159
@@ -1,15 +1,13 @@
1
1
  import { LinkCallback, PerspectiveClient, SyncStateChangeCallback } from "./PerspectiveClient";
2
2
  import { Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkMutations } from "../links/Links";
3
3
  import { LinkQuery } from "./LinkQuery";
4
- import { PerspectiveHandle, PerspectiveState } from './PerspectiveHandle';
4
+ import { PerspectiveHandle, PerspectiveState } from "./PerspectiveHandle";
5
5
  import { Perspective } from "./Perspective";
6
6
  import { ExpressionRendered } from "../expression/Expression";
7
7
  import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
8
8
  import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
9
9
  import { AIClient } from "../ai/AIClient";
10
10
  import { AllInstancesResult } from "../model/Ad4mModel";
11
- import { SHACLShape } from "../shacl/SHACLShape";
12
- import { SHACLFlow } from "../shacl/SHACLFlow";
13
11
  type QueryCallback = (result: AllInstancesResult) => void;
14
12
  /** Proxy object for a subscribed Prolog query that provides real-time updates
15
13
  *
@@ -45,8 +43,19 @@ type QueryCallback = (result: AllInstancesResult) => void;
45
43
  * ```
46
44
  */
47
45
  export declare class QuerySubscriptionProxy {
48
- #private;
49
- isSurrealDB: boolean;
46
+ private _uuid;
47
+ private _subscriptionId;
48
+ private _client;
49
+ private _callbacks;
50
+ private _keepaliveTimer;
51
+ private _unsubscribe?;
52
+ private _latestResult;
53
+ private _disposed;
54
+ private _initialized;
55
+ private _initResolve?;
56
+ private _initReject?;
57
+ private _initTimeoutId?;
58
+ private _query;
50
59
  /** Creates a new query subscription
51
60
  * @param uuid - The UUID of the perspective
52
61
  * @param query - The Prolog query to subscribe to
@@ -104,6 +113,8 @@ export declare class QuerySubscriptionProxy {
104
113
  * ```
105
114
  */
106
115
  onResult(callback: QueryCallback): () => void;
116
+ /** Internal method to notify all callbacks of a new result */
117
+ private _notifyCallbacks;
107
118
  /** Clean up the subscription and stop keepalive signals
108
119
  *
109
120
  * This method:
@@ -123,47 +134,7 @@ interface Parameter {
123
134
  name: string;
124
135
  value: string;
125
136
  }
126
- /**
127
- * PerspectiveProxy provides a high-level interface for working with AD4M Perspectives - agent-centric semantic graphs
128
- * that store and organize links between expressions.
129
- *
130
- * A Perspective is fundamentally a collection of links (subject-predicate-object triples) that represent an agent's view
131
- * of their digital world. Through PerspectiveProxy, you can:
132
- * - Add, remove, and query links
133
- * - Work with Social DNA (subject classes and flows)
134
- * - Subscribe to real-time updates
135
- * - Share perspectives as Neighbourhoods
136
- * - Execute Prolog queries for complex graph patterns
137
- *
138
- *
139
- * @example
140
- * ```typescript
141
- * // Create and work with links
142
- * const perspective = await ad4m.perspective.add("My Space");
143
- * await perspective.add({
144
- * source: "did:key:alice",
145
- * predicate: "knows",
146
- * target: "did:key:bob"
147
- * });
148
- *
149
- * // Query links
150
- * const friends = await perspective.get({
151
- * source: "did:key:alice",
152
- * predicate: "knows"
153
- * });
154
- *
155
- * // Use Social DNA
156
- * await perspective.addSdna(todoClass, "subject_class");
157
- * const todo = await perspective.createSubject("Todo", "expression://123");
158
- *
159
- * // Subscribe to changes
160
- * perspective.addListener("link-added", (link) => {
161
- * console.log("New link added:", link);
162
- * });
163
- * ```
164
- */
165
137
  export declare class PerspectiveProxy {
166
- #private;
167
138
  /** Unique identifier of this perspective */
168
139
  uuid: string;
169
140
  /** Human-readable name of this perspective */
@@ -176,6 +147,12 @@ export declare class PerspectiveProxy {
176
147
  state: PerspectiveState | null;
177
148
  /** List of owners of this perspective */
178
149
  owners?: string[];
150
+ private _handle;
151
+ private _client;
152
+ private _perspectiveLinkAddedCallbacks;
153
+ private _perspectiveLinkRemovedCallbacks;
154
+ private _perspectiveLinkUpdatedCallbacks;
155
+ private _perspectiveSyncStateChangeCallbacks;
179
156
  /**
180
157
  * Creates a new PerspectiveProxy instance.
181
158
  * Note: Don't create this directly, use ad4m.perspective.add() instead.
@@ -199,7 +176,7 @@ export declare class PerspectiveProxy {
199
176
  * Each action is an object with the following format:
200
177
  * ```typescript
201
178
  * {
202
- * action: "addLink" | "removeLink" | "setSingleTarget" | "collectionSetter",
179
+ * action: "addLink" | "removeLink" | "setSingleTarget" | "relationSetter",
203
180
  * source: string, // Usually "this" to reference the current expression
204
181
  * predicate: string, // The predicate URI
205
182
  * target: string // The target value or "value" for parameters
@@ -210,7 +187,7 @@ export declare class PerspectiveProxy {
210
187
  * - `addLink`: Creates a new link
211
188
  * - `removeLink`: Removes an existing link
212
189
  * - `setSingleTarget`: Removes all existing links with the same source/predicate and adds a new one
213
- * - `collectionSetter`: Special command for setting collection properties
190
+ * - `relationSetter`: Special command for bulk-setting a relation (clears existing links, then adds new ones)
214
191
  *
215
192
  * When used with parameters, the special value "value" in the target field will be
216
193
  * replaced with the actual parameter value.
@@ -380,21 +357,21 @@ export declare class PerspectiveProxy {
380
357
  */
381
358
  linkMutations(mutations: LinkMutations, status?: LinkStatus): Promise<LinkExpressionMutations>;
382
359
  /**
383
- * Adds a pre-signed LinkExpression to the perspective.
384
- *
385
- * @param link - The signed LinkExpression to add
386
- * @param status - Whether the link should be shared
387
- * @param batchId - Optional batch ID to group this operation with others
388
- * @returns The added LinkExpression
389
- */
360
+ * Adds a pre-signed LinkExpression to the perspective.
361
+ *
362
+ * @param link - The signed LinkExpression to add
363
+ * @param status - Whether the link should be shared
364
+ * @param batchId - Optional batch ID to group this operation with others
365
+ * @returns The added LinkExpression
366
+ */
390
367
  addLinkExpression(link: LinkExpression, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
391
368
  /**
392
- * Updates an existing link with new data.
393
- *
394
- * @param oldLink - The existing link to update
395
- * @param newLink - The new link data
396
- * @param batchId - Optional batch ID to group this operation with others
397
- */
369
+ * Updates an existing link with new data.
370
+ *
371
+ * @param oldLink - The existing link to update
372
+ * @param newLink - The new link data
373
+ * @param batchId - Optional batch ID to group this operation with others
374
+ */
398
375
  update(oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression>;
399
376
  /**
400
377
  * Removes a link from the perspective.
@@ -579,17 +556,17 @@ export declare class PerspectiveProxy {
579
556
  *
580
557
  * await perspective.addShacl('Recipe', shape);
581
558
  */
582
- addShacl(name: string, shape: SHACLShape): Promise<void>;
559
+ addShacl(name: string, shape: import("../shacl/SHACLShape").SHACLShape): Promise<void>;
583
560
  /**
584
561
  * Retrieve a SHACL shape by name from this Perspective
585
562
  */
586
- getShacl(name: string): Promise<SHACLShape | null>;
563
+ getShacl(name: string): Promise<import("../shacl/SHACLShape").SHACLShape | null>;
587
564
  /**
588
565
  * Get all SHACL shapes stored in this Perspective
589
566
  */
590
567
  getAllShacl(): Promise<Array<{
591
568
  name: string;
592
- shape: SHACLShape;
569
+ shape: import("../shacl/SHACLShape").SHACLShape;
593
570
  }>>;
594
571
  /**
595
572
  * **Recommended way to add Flow definitions.**
@@ -628,14 +605,14 @@ export declare class PerspectiveProxy {
628
605
  * await perspective.addFlow('TODO', todoFlow);
629
606
  * ```
630
607
  */
631
- addFlow(name: string, flow: SHACLFlow): Promise<void>;
608
+ addFlow(name: string, flow: import("../shacl/SHACLFlow").SHACLFlow): Promise<void>;
632
609
  /**
633
610
  * Retrieve a Flow definition by name from this Perspective
634
611
  *
635
612
  * @param name - Flow name to retrieve
636
613
  * @returns The SHACLFlow or null if not found
637
614
  */
638
- getFlow(name: string): Promise<SHACLFlow | null>;
615
+ getFlow(name: string): Promise<import("../shacl/SHACLFlow").SHACLFlow | null>;
639
616
  /** Returns all the Subject classes defined in this perspectives SDNA
640
617
  *
641
618
  * Uses SHACL-based lookup (Prolog-free implementation).
@@ -677,7 +654,7 @@ export declare class PerspectiveProxy {
677
654
  * @param subjectClass Either a string with the name of the subject class, or an object
678
655
  * with the properties of the subject class. In the latter case, the first subject class
679
656
  * that matches the given properties will be used.
680
- */
657
+ */
681
658
  isSubjectInstance<T>(expression: string, subjectClass: T): Promise<boolean>;
682
659
  /** For an existing subject instance (existing in the perspective's links)
683
660
  * this function returns a proxy object that can be used to access the subject's
@@ -690,8 +667,14 @@ export declare class PerspectiveProxy {
690
667
  */
691
668
  getSubjectProxy<T>(base: string, subjectClass: T): Promise<T>;
692
669
  /**
693
- * Gets subject class metadata from SHACL links using SHACLShape.fromLinks().
694
- * Retrieves the SHACL shape and extracts metadata for instance queries.
670
+ * Extracts subject class metadata from SDNA by parsing the Prolog text.
671
+ * Parses the instance rule to extract required predicates.
672
+ * Returns required predicates that define what makes something an instance,
673
+ * plus a map of property/collection names to their predicates.
674
+ */
675
+ /**
676
+ * Gets subject class metadata from SHACL links (Prolog-free implementation).
677
+ * Uses the link API directly instead of SurrealDB queries.
695
678
  */
696
679
  getSubjectClassMetadataFromSDNA(className: string): Promise<{
697
680
  requiredPredicates: string[];
@@ -760,10 +743,9 @@ export declare class PerspectiveProxy {
760
743
  * that match the given properties will be used.
761
744
  */
762
745
  getAllSubjectProxies<T>(subjectClass: T): Promise<T[]>;
763
- /**
764
- * Find a subject class by matching an object's properties/collections against SHACL shapes.
765
- * Queries SHACL links client-side to find a class whose properties contain all required ones.
766
- * @returns The matching class name, or null if no match found.
746
+ private buildQueryFromTemplate;
747
+ /** Finds a single subject class whose SHACL shape matches all properties
748
+ * and collections present on `obj`. Returns `null` when no match is found.
767
749
  */
768
750
  private findClassByProperties;
769
751
  /** Returns all subject classes that match the given template object.
@@ -841,25 +823,5 @@ export declare class PerspectiveProxy {
841
823
  * ```
842
824
  */
843
825
  subscribeInfer(query: string): Promise<QuerySubscriptionProxy>;
844
- /**
845
- * Creates a subscription for a SurrealQL query that updates in real-time.
846
- *
847
- * This method:
848
- * 1. Creates the subscription on the Rust side
849
- * 2. Sets up the subscription callback
850
- * 3. Waits for the initial result to come through the subscription channel
851
- * 4. Returns a fully initialized QuerySubscriptionProxy
852
- *
853
- * The returned subscription is guaranteed to be ready to receive updates,
854
- * as this method waits for the initialization process to complete.
855
- *
856
- * The subscription will be automatically cleaned up on both frontend and backend
857
- * when dispose() is called. Make sure to call dispose() when you're done to
858
- * prevent memory leaks and ensure proper cleanup of resources.
859
- *
860
- * @param query - SurrealQL query string
861
- * @returns Initialized QuerySubscriptionProxy instance
862
- */
863
- subscribeSurrealDB(query: string): Promise<QuerySubscriptionProxy>;
864
826
  }
865
827
  export {};