@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
package/src/utils.ts CHANGED
@@ -1,16 +1,30 @@
1
+ /**
2
+ * WebSocket close code 1006 (abnormal closure) is emitted on every active
3
+ * GraphQL subscription when the server process shuts down — it simply means
4
+ * the server didn't send a clean close frame. This is expected at the end
5
+ * of every test run and whenever the executor is stopped, so it must not be
6
+ * treated as an application error. All other errors are still surfaced.
7
+ */
8
+ export function isSocketCloseError(e: any): boolean {
9
+ if (!e) return false;
10
+ if (typeof e.code === "number" && e.code === 1006) return true;
11
+ const msg = String(e?.message ?? e);
12
+ return msg.startsWith("Socket closed with event 1006");
13
+ }
14
+
1
15
  export function formatList(list) {
2
16
  if (!list?.length) {
3
- return "";
17
+ return "";
4
18
  }
5
19
  if (list.length === 1) {
6
- return list.toString();
20
+ return list.toString();
7
21
  }
8
22
  if (list.length === 2) {
9
- return list.join(' and ');
23
+ return list.join(" and ");
10
24
  }
11
25
 
12
- return list.slice(0, -1).join(', ') + ', and ' + list.slice(-1);
13
- };
26
+ return list.slice(0, -1).join(", ") + ", and " + list.slice(-1);
27
+ }
14
28
 
15
29
  export function capSentence(cap) {
16
30
  const can = cap.can.includes("*") ? ["READ", "WRITE", "UPDATE"] : cap.can;
@@ -20,24 +34,24 @@ export function capSentence(cap) {
20
34
  : cap.with.pointers;
21
35
 
22
36
  return `${formatList(
23
- can
37
+ can,
24
38
  )} your ${domain} actions, with access to ${formatList(pointers)}`;
25
39
  }
26
40
 
27
41
  /**
28
42
  * Escapes a string value for safe use in SurrealQL queries.
29
- *
43
+ *
30
44
  * @description
31
45
  * Prevents SQL injection by properly escaping special characters in string values
32
46
  * that will be interpolated into SurrealQL queries. This handles the most common
33
47
  * special characters that could break SQL queries or enable injection attacks.
34
- *
48
+ *
35
49
  * Single quotes, backslashes, and other special characters are escaped using
36
50
  * backslash notation, which is the standard escaping mechanism for SurrealQL.
37
- *
51
+ *
38
52
  * @param value - The string value to escape
39
53
  * @returns The escaped string safe for SurrealQL interpolation (without surrounding quotes)
40
- *
54
+ *
41
55
  * @example
42
56
  * ```typescript
43
57
  * const userInput = "user's input with 'quotes'";
@@ -47,11 +61,11 @@ export function capSentence(cap) {
47
61
  * ```
48
62
  */
49
63
  export function escapeSurrealString(value: string): string {
50
- return value
51
- .replace(/\\/g, '\\\\') // Backslash -> \\
52
- .replace(/'/g, "\\'") // Single quote -> \'
53
- .replace(/"/g, '\\"') // Double quote -> \"
54
- .replace(/\n/g, '\\n') // Newline -> \n
55
- .replace(/\r/g, '\\r') // Carriage return -> \r
56
- .replace(/\t/g, '\\t'); // Tab -> \t
64
+ return value
65
+ .replace(/\\/g, "\\\\") // Backslash -> \\
66
+ .replace(/'/g, "\\'") // Single quote -> \'
67
+ .replace(/"/g, '\\"') // Double quote -> \"
68
+ .replace(/\n/g, "\\n") // Newline -> \n
69
+ .replace(/\r/g, "\\r") // Carriage return -> \r
70
+ .replace(/\t/g, "\\t"); // Tab -> \t
57
71
  }
package/tsconfig.json CHANGED
@@ -1,6 +1,5 @@
1
1
  {
2
2
  "include": ["./src/**/*.ts", "./src/*.ts", "./shims"],
3
- "exclude": ["./src/*.test.ts", "./src/*.test.ts"],
4
3
  "compilerOptions": {
5
4
  /* Visit https://aka.ms/tsconfig.json to read more about this file */
6
5
  // "paths": {
@@ -9,18 +8,18 @@
9
8
  // },
10
9
  /* Basic Options */
11
10
  // "incremental": true, /* Enable incremental compilation */
12
- "target": "es2020", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'es2015', or 'ESNEXT'. */
11
+ "target": "es2020" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'es2015', or 'ESNEXT'. */,
13
12
  "lib": ["es2020", "esnext.asynciterable"],
14
- "module": "es2020", /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */
13
+ "module": "es2020" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
15
14
  // "lib": [], /* Specify library files to be included in the compilation. */
16
15
  // "allowJs": true, /* Allow javascript files to be compiled. */
17
16
  // "checkJs": true, /* Report errors in .js files. */
18
17
  // "jsx": "preserve", /* Specify JSX code generation: 'preserve', 'react-native', 'react', 'react-jsx' or 'react-jsxdev'. */
19
- "declaration": true, /* Generates corresponding '.d.ts' file. */
18
+ "declaration": true /* Generates corresponding '.d.ts' file. */,
20
19
  // "declarationMap": true, /* Generates a sourcemap for each corresponding '.d.ts' file. */
21
20
  // "sourceMap": true, /* Generates corresponding '.map' file. */
22
21
  // "outFile": "./", /* Concatenate and emit output to single file. */
23
- "rootDir": "./", /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
22
+ "rootDir": "./" /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */,
24
23
  "outDir": "./lib",
25
24
  // "composite": true, /* Enable project compilation */
26
25
  // "tsBuildInfoFile": "./", /* Specify file to store incremental compilation information */
@@ -49,14 +48,14 @@
49
48
  // "noPropertyAccessFromIndexSignature": true, /* Require undeclared properties from index signatures to use element accesses. */
50
49
 
51
50
  /* Module Resolution Options */
52
- "moduleResolution": "node", /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
51
+ "moduleResolution": "node" /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */,
53
52
  // "baseUrl": "./", /* Base directory to resolve non-absolute module names. */
54
53
  // "paths": {}, /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
55
54
  // "rootDirs": [], /* List of root folders whose combined content represents the structure of the project at runtime. */
56
55
  // "typeRoots": [], /* List of folders to include type definitions from. */
57
56
  // "types": [], /* Type declaration files to be included in compilation. */
58
57
  // "allowSyntheticDefaultImports": true, /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
59
- "esModuleInterop": true, /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
58
+ "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
60
59
  // "preserveSymlinks": true, /* Do not resolve the real path of symlinks. */
61
60
  // "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */
62
61
 
@@ -71,10 +70,10 @@
71
70
  // "emitDecoratorMetadata": true, /* Enables experimental support for emitting type metadata for decorators. */
72
71
 
73
72
  /* Advanced Options */
74
- "skipLibCheck": true, /* Skip type checking of declaration files. */
75
- "forceConsistentCasingInFileNames": true, /* Disallow inconsistently-cased references to the same file. */
73
+ "skipLibCheck": true /* Skip type checking of declaration files. */,
74
+ "forceConsistentCasingInFileNames": true /* Disallow inconsistently-cased references to the same file. */,
76
75
  "emitDecoratorMetadata": true,
77
76
  "experimentalDecorators": true,
78
77
  "allowSyntheticDefaultImports": true
79
- },
78
+ }
80
79
  }
@@ -1,159 +0,0 @@
1
- import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
2
- import { collectionSetterToName, collectionToAdderName, collectionToRemoverName, collectionToSetterName, propertyNameToSetterName } from "./util";
3
-
4
- /**
5
- * Represents a subject in the perspective.
6
- * A subject is an entity that has properties and collections.
7
- */
8
- export class Subject {
9
- #baseExpression: string;
10
- #subjectClassName: string;
11
- #perspective: PerspectiveProxy
12
-
13
- /**
14
- * Constructs a new subject.
15
- * @param perspective - The perspective that the subject belongs to.
16
- * @param baseExpression - The base expression of the subject.
17
- * @param subjectClassName - The class name of the subject.
18
- */
19
- constructor(perspective: PerspectiveProxy, baseExpression: string, subjectClassName: string) {
20
- this.#baseExpression = baseExpression
21
- this.#subjectClassName = subjectClassName
22
- this.#perspective = perspective
23
- }
24
-
25
- /**
26
- * Gets the base expression of the subject.
27
- */
28
- get baseExpression() {
29
- return this.#baseExpression
30
- }
31
-
32
- /**
33
- * Initializes the subject by validating it and defining its properties and collections dynamically.
34
- *
35
- * NOTE: This method should be called before using the subject. All the properties and collections of the subject defined are not type-checked.
36
- */
37
- async init() {
38
- // Check if the subject is a valid instance of the subject class
39
- let isInstance = await this.#perspective.isSubjectInstance(this.#baseExpression, this.#subjectClassName)
40
- if(!isInstance) {
41
- throw `Not a valid subject instance of ${this.#subjectClassName} for ${this.#baseExpression}`
42
- }
43
-
44
- // Define properties and collections dynamically
45
- let results = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), property(C, Property)`)
46
- let properties = results.map(result => result.Property)
47
-
48
- for(let p of properties) {
49
- const resolveExpressionURI = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), property_resolve(C, "${p}")`)
50
- Object.defineProperty(this, p, {
51
- configurable: true,
52
- get: async () => {
53
- // Use SurrealDB for data queries
54
- try {
55
- return await this.#perspective.getPropertyValueViaSurreal(this.#baseExpression, this.#subjectClassName, p);
56
- } catch (err) {
57
- console.warn(`Failed to get property ${p} via SurrealDB:`, err);
58
- return undefined;
59
- }
60
- }
61
- })
62
- }
63
-
64
- // Define setters
65
- const setters = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), property_setter(C, Property, Setter)`)
66
-
67
- for(let setter of (setters ? setters : [])) {
68
- if(setter) {
69
- const property = setter.Property
70
- const actions = eval(setter.Setter)
71
- const resolveLanguageResults = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), property_resolve_language(C, "${property}", Language)`)
72
- let resolveLanguage
73
- if(resolveLanguageResults && resolveLanguageResults.length > 0) {
74
- resolveLanguage = resolveLanguageResults[0].Language
75
- }
76
- this[propertyNameToSetterName(property)] = async (value: any) => {
77
- if(resolveLanguage) {
78
- value = await this.#perspective.createExpression(value, resolveLanguage)
79
- }
80
- await this.#perspective.executeAction(actions, this.#baseExpression, [{name: "value", value}])
81
- }
82
- }
83
- }
84
-
85
- // Define collections
86
- let results2 = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), collection(C, Collection)`)
87
- if(!results2) results2 = []
88
- let collections = results2.map(result => result.Collection)
89
-
90
- for(let c of collections) {
91
- Object.defineProperty(this, c, {
92
- configurable: true,
93
- get: async () => {
94
- // Use SurrealDB for data queries
95
- try {
96
- return await this.#perspective.getCollectionValuesViaSurreal(this.#baseExpression, this.#subjectClassName, c);
97
- } catch (err) {
98
- console.warn(`Failed to get collection ${c} via SurrealDB:`, err);
99
- return [];
100
- }
101
- }
102
- })
103
- }
104
-
105
- // Define collection adders
106
- let adders = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), collection_adder(C, Collection, Adder)`)
107
- if(!adders) adders = []
108
-
109
- for(let adder of adders) {
110
- if(adder) {
111
- const collection = adder.Collection
112
- const actions = eval(adder.Adder)
113
- this[collectionToAdderName(collection)] = async (value: any) => {
114
- if (Array.isArray(value)) {
115
- await Promise.all(value.map(v => this.#perspective.executeAction(actions, this.#baseExpression, [{name: "value", value: v}])))
116
- } else {
117
- await this.#perspective.executeAction(actions, this.#baseExpression, [{name: "value", value}])
118
- }
119
- }
120
- }
121
- }
122
-
123
- // Define collection removers
124
- let removers = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), collection_remover(C, Collection, Remover)`)
125
- if(!removers) removers = []
126
-
127
- for(let remover of removers) {
128
- if(remover) {
129
- const collection = remover.Collection
130
- const actions = eval(remover.Remover)
131
- this[collectionToRemoverName(collection)] = async (value: any) => {
132
- if (Array.isArray(value)) {
133
- await Promise.all(value.map(v => this.#perspective.executeAction(actions, this.#baseExpression, [{name: "value", value: v}])))
134
- } else {
135
- await this.#perspective.executeAction(actions, this.#baseExpression, [{name: "value", value}])
136
- }
137
- }
138
- }
139
- }
140
-
141
- // Define collection setters
142
- let collectionSetters = await this.#perspective.infer(`subject_class("${this.#subjectClassName}", C), collection_setter(C, Collection, Setter)`)
143
- if(!collectionSetters) collectionSetters = []
144
-
145
- for(let collectionSetter of collectionSetters) {
146
- if(collectionSetter) {
147
- const collection = collectionSetter.Collection
148
- const actions = eval(collectionSetter.Setter)
149
- this[collectionToSetterName(collection)] = async (value: any) => {
150
- if (Array.isArray(value)) {
151
- await this.#perspective.executeAction(actions, this.#baseExpression, value.map(v => ({name: "value", value: v})))
152
- } else {
153
- await this.#perspective.executeAction(actions, this.#baseExpression, [{name: "value", value}])
154
- }
155
- }
156
- }
157
- }
158
- }
159
- }