@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
package/src/utils.ts
CHANGED
|
@@ -1,30 +1,16 @@
|
|
|
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
|
-
|
|
15
1
|
export function formatList(list) {
|
|
16
2
|
if (!list?.length) {
|
|
17
|
-
|
|
3
|
+
return "";
|
|
18
4
|
}
|
|
19
5
|
if (list.length === 1) {
|
|
20
|
-
|
|
6
|
+
return list.toString();
|
|
21
7
|
}
|
|
22
8
|
if (list.length === 2) {
|
|
23
|
-
|
|
9
|
+
return list.join(' and ');
|
|
24
10
|
}
|
|
25
11
|
|
|
26
|
-
return list.slice(0, -1).join(
|
|
27
|
-
}
|
|
12
|
+
return list.slice(0, -1).join(', ') + ', and ' + list.slice(-1);
|
|
13
|
+
};
|
|
28
14
|
|
|
29
15
|
export function capSentence(cap) {
|
|
30
16
|
const can = cap.can.includes("*") ? ["READ", "WRITE", "UPDATE"] : cap.can;
|
|
@@ -34,24 +20,24 @@ export function capSentence(cap) {
|
|
|
34
20
|
: cap.with.pointers;
|
|
35
21
|
|
|
36
22
|
return `${formatList(
|
|
37
|
-
can
|
|
23
|
+
can
|
|
38
24
|
)} your ${domain} actions, with access to ${formatList(pointers)}`;
|
|
39
25
|
}
|
|
40
26
|
|
|
41
27
|
/**
|
|
42
28
|
* Escapes a string value for safe use in SurrealQL queries.
|
|
43
|
-
*
|
|
29
|
+
*
|
|
44
30
|
* @description
|
|
45
31
|
* Prevents SQL injection by properly escaping special characters in string values
|
|
46
32
|
* that will be interpolated into SurrealQL queries. This handles the most common
|
|
47
33
|
* special characters that could break SQL queries or enable injection attacks.
|
|
48
|
-
*
|
|
34
|
+
*
|
|
49
35
|
* Single quotes, backslashes, and other special characters are escaped using
|
|
50
36
|
* backslash notation, which is the standard escaping mechanism for SurrealQL.
|
|
51
|
-
*
|
|
37
|
+
*
|
|
52
38
|
* @param value - The string value to escape
|
|
53
39
|
* @returns The escaped string safe for SurrealQL interpolation (without surrounding quotes)
|
|
54
|
-
*
|
|
40
|
+
*
|
|
55
41
|
* @example
|
|
56
42
|
* ```typescript
|
|
57
43
|
* const userInput = "user's input with 'quotes'";
|
|
@@ -61,11 +47,11 @@ export function capSentence(cap) {
|
|
|
61
47
|
* ```
|
|
62
48
|
*/
|
|
63
49
|
export function escapeSurrealString(value: string): string {
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
71
57
|
}
|
package/tsconfig.json
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"include": ["./src/**/*.ts", "./src/*.ts", "./shims"],
|
|
3
|
+
"exclude": ["./src/*.test.ts", "./src/*.test.ts"],
|
|
3
4
|
"compilerOptions": {
|
|
4
5
|
/* Visit https://aka.ms/tsconfig.json to read more about this file */
|
|
5
6
|
// "paths": {
|
|
@@ -8,18 +9,18 @@
|
|
|
8
9
|
// },
|
|
9
10
|
/* Basic Options */
|
|
10
11
|
// "incremental": true, /* Enable incremental compilation */
|
|
11
|
-
"target": "es2020"
|
|
12
|
+
"target": "es2020", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'es2015', or 'ESNEXT'. */
|
|
12
13
|
"lib": ["es2020", "esnext.asynciterable"],
|
|
13
|
-
"module": "es2020"
|
|
14
|
+
"module": "es2020", /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */
|
|
14
15
|
// "lib": [], /* Specify library files to be included in the compilation. */
|
|
15
16
|
// "allowJs": true, /* Allow javascript files to be compiled. */
|
|
16
17
|
// "checkJs": true, /* Report errors in .js files. */
|
|
17
18
|
// "jsx": "preserve", /* Specify JSX code generation: 'preserve', 'react-native', 'react', 'react-jsx' or 'react-jsxdev'. */
|
|
18
|
-
"declaration": true
|
|
19
|
+
"declaration": true, /* Generates corresponding '.d.ts' file. */
|
|
19
20
|
// "declarationMap": true, /* Generates a sourcemap for each corresponding '.d.ts' file. */
|
|
20
21
|
// "sourceMap": true, /* Generates corresponding '.map' file. */
|
|
21
22
|
// "outFile": "./", /* Concatenate and emit output to single file. */
|
|
22
|
-
"rootDir": "./"
|
|
23
|
+
"rootDir": "./", /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
|
|
23
24
|
"outDir": "./lib",
|
|
24
25
|
// "composite": true, /* Enable project compilation */
|
|
25
26
|
// "tsBuildInfoFile": "./", /* Specify file to store incremental compilation information */
|
|
@@ -48,14 +49,14 @@
|
|
|
48
49
|
// "noPropertyAccessFromIndexSignature": true, /* Require undeclared properties from index signatures to use element accesses. */
|
|
49
50
|
|
|
50
51
|
/* Module Resolution Options */
|
|
51
|
-
"moduleResolution": "node"
|
|
52
|
+
"moduleResolution": "node", /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
|
|
52
53
|
// "baseUrl": "./", /* Base directory to resolve non-absolute module names. */
|
|
53
54
|
// "paths": {}, /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
|
|
54
55
|
// "rootDirs": [], /* List of root folders whose combined content represents the structure of the project at runtime. */
|
|
55
56
|
// "typeRoots": [], /* List of folders to include type definitions from. */
|
|
56
57
|
// "types": [], /* Type declaration files to be included in compilation. */
|
|
57
58
|
// "allowSyntheticDefaultImports": true, /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
|
|
58
|
-
"esModuleInterop": true
|
|
59
|
+
"esModuleInterop": true, /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
|
|
59
60
|
// "preserveSymlinks": true, /* Do not resolve the real path of symlinks. */
|
|
60
61
|
// "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */
|
|
61
62
|
|
|
@@ -70,10 +71,10 @@
|
|
|
70
71
|
// "emitDecoratorMetadata": true, /* Enables experimental support for emitting type metadata for decorators. */
|
|
71
72
|
|
|
72
73
|
/* Advanced Options */
|
|
73
|
-
"skipLibCheck": true
|
|
74
|
-
"forceConsistentCasingInFileNames": true
|
|
74
|
+
"skipLibCheck": true, /* Skip type checking of declaration files. */
|
|
75
|
+
"forceConsistentCasingInFileNames": true, /* Disallow inconsistently-cased references to the same file. */
|
|
75
76
|
"emitDecoratorMetadata": true,
|
|
76
77
|
"experimentalDecorators": true,
|
|
77
78
|
"allowSyntheticDefaultImports": true
|
|
78
|
-
}
|
|
79
|
+
},
|
|
79
80
|
}
|
|
@@ -1,482 +0,0 @@
|
|
|
1
|
-
# Ad4mModel — Improvement Backlog
|
|
2
|
-
|
|
3
|
-
Identified gaps and improvement areas for future PRs.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 1. Dirty Tracking (Unit of Work)
|
|
8
|
-
|
|
9
|
-
**Problem:** Every `save()` writes all properties unconditionally. If a model has 20 properties and only one changes, all 20 setter actions are executed, creating unnecessary link churn and network noise.
|
|
10
|
-
|
|
11
|
-
**Solution:** Maintain a `#dirtyFields: Set<string>` on each instance. Intercept property assignments (via `Proxy` or setter generation in `Property()`) to mark fields dirty. `save()` only writes dirty fields; after commit the set is cleared.
|
|
12
|
-
|
|
13
|
-
**Prior art:** TypeORM Unit of Work, MikroORM identity map.
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## 2. SurrealDB-Side Range Filter Push-Down
|
|
18
|
-
|
|
19
|
-
**Problem:** Comparison operators (`gt`, `lt`, `gte`, `lte`, `between`, `contains`) on scalar properties fall through to post-query JavaScript filtering. Because scalar values are stored as `literal://` URIs, SurrealDB cannot index them for range comparisons without `fn::parse_literal()` unwrapping. This means `findAll(p, { where: { rating: { gt: 4 } } })` fetches **all** instances and filters in JS — a full table scan at scale.
|
|
20
|
-
|
|
21
|
-
**Options:**
|
|
22
|
-
|
|
23
|
-
- Store numeric/boolean values in a SurrealDB-native way (separate `value` field alongside the `literal://` URI) so the DB can index them directly.
|
|
24
|
-
- Define SurrealDB computed fields that cache the unwrapped scalar value, then filter against the computed field.
|
|
25
|
-
- Use `fn::parse_literal(out.uri)` inside the graph traversal WHERE clause directly (requires SurrealDB to evaluate the function per-link, no index — but still better than JS filtering).
|
|
26
|
-
|
|
27
|
-
---
|
|
28
|
-
|
|
29
|
-
## 3. N+1 Prevention for Typed Relation Hydration
|
|
30
|
-
|
|
31
|
-
**Problem:** When `relatedModel` is set on a `@HasMany`, hydrating relations calls `_findAllInternal` once per parent instance. 10 posts × 5 comments each = 10 separate `findAll()` queries. No batching exists.
|
|
32
|
-
|
|
33
|
-
**Solution:** In `hydrateInstanceFromLinks` (or a post-hydration pass in `operations.ts`), collect all relation IDs across the entire result set, then run a single batched `findAll({ where: { base: [...ids] } })` for each related model type. Equivalent to a DataLoader / SQL `IN (...)` pattern.
|
|
34
|
-
|
|
35
|
-
---
|
|
36
|
-
|
|
37
|
-
## 4. Runtime Validation
|
|
38
|
-
|
|
39
|
-
**Problem:** There is no validation layer. Setting `recipe.rating = "not a number"` silently persists a type-incorrect value. Errors surface only later (if at all) during hydration.
|
|
40
|
-
|
|
41
|
-
**Solution:** Add an optional `validate` option to `@Property` accepting a predicate function or a class-validator-style decorator. Add a `validate()` method to `Ad4mModel` that checks all properties before `save()`. Optionally throw by default or expose errors as a return value.
|
|
42
|
-
|
|
43
|
-
```typescript
|
|
44
|
-
@Property({ through: "recipe://rating", validate: (v) => typeof v === "number" && v >= 0 })
|
|
45
|
-
rating: number = 0;
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## 5. TypeScript Type Inference for `fromJSONSchema`
|
|
51
|
-
|
|
52
|
-
**Problem:** `fromJSONSchema` returns `typeof Ad4mModel` — TypeScript has no knowledge of the generated class's property types. Autocomplete and type-checking are completely lost for dynamically generated models.
|
|
53
|
-
|
|
54
|
-
**Options:**
|
|
55
|
-
|
|
56
|
-
- A type-level schema builder (fluent API returning typed class) that preserves inference without codegen:
|
|
57
|
-
```typescript
|
|
58
|
-
const Recipe = Ad4mModel.define({
|
|
59
|
-
name: field<string>({ through: "recipe://name" }),
|
|
60
|
-
rating: field<number>({ through: "recipe://rating" }),
|
|
61
|
-
});
|
|
62
|
-
// Recipe is typed: { name: string; rating: number }
|
|
63
|
-
```
|
|
64
|
-
- Code generation from JSON Schema (Prisma-style): a CLI command that produces a `.ts` file with a properly typed class from a `.json` schema file.
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## 6. Robust Create-vs-Update Detection
|
|
69
|
-
|
|
70
|
-
**Problem:** `#savedOnce` tracks whether `save()` was called on the current JS instance. Constructing a model wrapper around a known existing ID (`new Recipe(perspective, existingId)`) starts with `#savedOnce = false`, so the first `save()` runs the create path (calling `createSubject`), which may conflict with the already-existing subject.
|
|
71
|
-
|
|
72
|
-
**Solution:** Before the first `save()` on an instance constructed with an explicit `id`, check the perspective for the subject's actual existence (e.g. `isSubjectInstance`). Cache the result so subsequent saves don't pay the round-trip cost.
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
## 7. Stage 3 Decorator Migration
|
|
77
|
-
|
|
78
|
-
**Problem:** The decorator system uses TypeScript's legacy `experimentalDecorators` (Stage 2) format. TypeScript 5.x introduced Stage 3 decorators with different metadata semantics (`context` object instead of `target`/`key`). The current code will need migration when Stage 3 becomes the ecosystem default.
|
|
79
|
-
|
|
80
|
-
**Action:** Track TC39 Stage 3 stabilisation. When `reflect-metadata` is no longer required by major libraries, plan a migration. The `WeakMap`-keyed registry (`propertyRegistry`, `relationRegistry`) already decouples metadata storage from the decorator protocol, so migration should be largely mechanical — change decorator signatures, keep the registry logic intact.
|
|
81
|
-
|
|
82
|
-
---
|
|
83
|
-
|
|
84
|
-
## 8. `getter` Option — N+1 Footgun
|
|
85
|
-
|
|
86
|
-
**Problem:** `@Property({ getter: "..." })` and `@HasMany({ getter: "..." })` allow arbitrary SurrealQL expressions to be evaluated per-instance after the main link fetch. This fires one additional `querySurrealDB` call _per instance_ in `evaluateCustomGetters()` — a guaranteed N+1 on every `findAll`.
|
|
87
|
-
|
|
88
|
-
**Distinction from `transform`:** `transform` operates on a value already resolved from a link triple (sync, no extra query). `getter` is for properties with **no backing link triple** — values computed entirely from other nodes' data (e.g. `array::len(string::split(...))` aggregations). It covers ground `transform` cannot, so it cannot simply be removed.
|
|
89
|
-
|
|
90
|
-
**Additional limitations:**
|
|
91
|
-
|
|
92
|
-
- `getter` properties are invisible to `where` clauses (skipped in `hydrateInstanceFromLinks`) — `findAll(p, { where: { wordCount: { gt: 100 } } })` silently ignores the filter.
|
|
93
|
-
- Not subscribed correctly — every subscription re-query re-fires all getter calls.
|
|
94
|
-
- Not represented in the SHACL shape — the Rust executor has no knowledge of it.
|
|
95
|
-
|
|
96
|
-
**Proper fix:** Emit getter expressions as SurrealDB computed fields in the SHACL shape (see item #2), so they are evaluated server-side inside the bulk query rather than in a separate per-instance round-trip. Until that exists, `getter` is a necessary escape hatch but should be used only for single-instance `.find()` calls, never in `findAll`.
|
|
97
|
-
|
|
98
|
-
**Action:** Add a dev-time `console.warn` when `getter` is present without `readOnly: true`, reinforcing that it is not a writable/filterable property. Document the N+1 caveat clearly.
|
|
99
|
-
|
|
100
|
-
---
|
|
101
|
-
|
|
102
|
-
## 9. Abort / Rollback for Transactions
|
|
103
|
-
|
|
104
|
-
**Problem:** `runTransaction` catches errors and logs a debug message, but there is no explicit `abortBatch()` on `PerspectiveProxy`. The uncommitted batch is silently discarded by the runtime GC. This is invisible to the caller and relies on runtime-level cleanup.
|
|
105
|
-
|
|
106
|
-
**Solution:** If `PerspectiveProxy` exposes an `abortBatch(id)` call (or can be extended to), call it explicitly in the `catch` block of `runTransaction` for predictable, immediate cleanup rather than relying on GC timing.
|
|
107
|
-
|
|
108
|
-
---
|
|
109
|
-
|
|
110
|
-
## 10. tests/js Integration Test Migration
|
|
111
|
-
|
|
112
|
-
**Background:** The `ad4m/tests/js` Mocha suite is the correct long-term home for all `Ad4mModel` integration tests. The target file is `tests/js/tests/model-decorator-api.test.ts`. Currently scenario 08 (14 tests) lives in the `we` playground. The `tests/js` suite imports deprecated symbols and needs a cleanup pass before new tests can land cleanly.
|
|
113
|
-
|
|
114
|
-
**Action:**
|
|
115
|
-
|
|
116
|
-
1. Fix deprecated imports in `prolog-and-literals.test.ts` and `multi-user-simple.test.ts`
|
|
117
|
-
2. Establish consistent port allocation and setup pattern across the suite
|
|
118
|
-
3. Port scenario 08 models + all current tests into `model-decorator-api.test.ts`
|
|
119
|
-
4. Add subscription lifecycle tests (Phase 3d coverage at executor level)
|
|
120
|
-
5. Write remaining scenarios (01–07, 09–10) directly in `tests/js`
|
|
121
|
-
|
|
122
|
-
**Priority:** Post-merge. Blocking a dedicated follow-up PR.
|
|
123
|
-
|
|
124
|
-
---
|
|
125
|
-
|
|
126
|
-
## 11. CRDT Ordering (Phase 5)
|
|
127
|
-
|
|
128
|
-
**Background:** Concurrent link writes from multiple agents can produce non-deterministic ordering — last-writer-wins SurrealDB timestamp semantics may not match causal intent in a distributed graph.
|
|
129
|
-
|
|
130
|
-
**Goals:**
|
|
131
|
-
|
|
132
|
-
- Make P2P-safe ordering the default, not an afterthought
|
|
133
|
-
- Eliminate boilerplate across all future list-based plugins
|
|
134
|
-
- Provide clear migration path as algorithms improve
|
|
135
|
-
- Enable A/B testing of different strategies
|
|
136
|
-
|
|
137
|
-
---
|
|
138
|
-
|
|
139
|
-
### Developer-Facing API
|
|
140
|
-
|
|
141
|
-
```typescript
|
|
142
|
-
@HasMany(() => Task, {
|
|
143
|
-
through: 'ad4m://has_child',
|
|
144
|
-
ordering: {
|
|
145
|
-
strategy: 'linkedList', // 'linkedList' | 'fractionalIndex' | 'timestamp' | 'manual'
|
|
146
|
-
sortBy: 'taskName', // Fallback for ties (optional)
|
|
147
|
-
}
|
|
148
|
-
})
|
|
149
|
-
orderedTasks: Task[] = [];
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
Developers use normal array operations — the framework generates CRDT links:
|
|
153
|
-
|
|
154
|
-
```typescript
|
|
155
|
-
column.orderedTasks.push(newTask); // Append
|
|
156
|
-
column.orderedTasks.splice(2, 0, task); // Insert at index 2
|
|
157
|
-
column.orderedTasks.splice(1, 1); // Remove at index 1
|
|
158
|
-
await column.update(); // Framework generates CRDT links
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
---
|
|
162
|
-
|
|
163
|
-
### Architecture
|
|
164
|
-
|
|
165
|
-
**Layer 1 — Model Decorator (API Surface)**
|
|
166
|
-
|
|
167
|
-
```typescript
|
|
168
|
-
interface OrderingConfig {
|
|
169
|
-
strategy: "linkedList" | "fractionalIndex" | "timestamp" | "manual";
|
|
170
|
-
sortBy?: string; // Property name for tiebreaker
|
|
171
|
-
conflictResolution?: "lww" | "merge"; // Last-write-wins or merge
|
|
172
|
-
}
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
**Layer 2 — Ordering Strategy Interface**
|
|
176
|
-
|
|
177
|
-
```typescript
|
|
178
|
-
interface OrderingStrategy {
|
|
179
|
-
reconstruct(items: Ad4mModel[], links: Link[]): Ad4mModel[];
|
|
180
|
-
generateLinks(
|
|
181
|
-
items: Ad4mModel[],
|
|
182
|
-
operation: Operation,
|
|
183
|
-
context: OperationContext,
|
|
184
|
-
): Link[];
|
|
185
|
-
garbageCollect?(links: Link[], cutoffDate: Date): Link[];
|
|
186
|
-
}
|
|
187
|
-
|
|
188
|
-
interface Operation {
|
|
189
|
-
type: "insert" | "delete" | "move" | "reorder";
|
|
190
|
-
index: number;
|
|
191
|
-
item?: Ad4mModel;
|
|
192
|
-
targetIndex?: number; // For moves
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
interface OperationContext {
|
|
196
|
-
agentDID: string;
|
|
197
|
-
timestamp: number;
|
|
198
|
-
collectionId: string;
|
|
199
|
-
}
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
**Layer 3 — Concrete Strategies**
|
|
203
|
-
|
|
204
|
-
LinkedList Strategy (RGA-based) uses predicates `ad4m://ordered_after`, `ad4m://position_id`, `ad4m://position_deleted`. Reconstructs by building an `afterMap` from links, sorting same-position items by `${timestamp}_${agentDID}` positionId, then traversing the linked list from `null` head.
|
|
205
|
-
|
|
206
|
-
Fractional Index Strategy uses predicates `ad4m://fractional_position`, `ad4m://position_id`. Reconstructs by sorting items lexicographically by their stored position string with positionId as tiebreaker. Generates new positions as the midpoint between neighbours.
|
|
207
|
-
|
|
208
|
-
Strategy Factory:
|
|
209
|
-
|
|
210
|
-
```typescript
|
|
211
|
-
class OrderingStrategyFactory {
|
|
212
|
-
static create(config?: OrderingConfig): OrderingStrategy {
|
|
213
|
-
switch (config?.strategy) {
|
|
214
|
-
case "linkedList":
|
|
215
|
-
return new LinkedListStrategy();
|
|
216
|
-
case "fractionalIndex":
|
|
217
|
-
return new FractionalIndexStrategy();
|
|
218
|
-
case "timestamp":
|
|
219
|
-
return new TimestampStrategy();
|
|
220
|
-
default:
|
|
221
|
-
return new ManualStrategy(); // current behaviour
|
|
222
|
-
}
|
|
223
|
-
}
|
|
224
|
-
}
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
Custom strategies are supported: `ordering: { strategy: new MyCustomStrategy() }`.
|
|
228
|
-
|
|
229
|
-
**Layer 4 — Array Proxy**
|
|
230
|
-
|
|
231
|
-
`wrapCollectionWithOrdering()` on `Ad4mModel` returns a `Proxy` that intercepts `push`, `unshift`, `splice` and records a pending `Operation`. On `update()`, pending operations are passed to the strategy's `generateLinks()` and the resulting links are batched into the perspective write.
|
|
232
|
-
|
|
233
|
-
---
|
|
234
|
-
|
|
235
|
-
### Migration Strategy
|
|
236
|
-
|
|
237
|
-
Old string-array properties still work. Migration helper:
|
|
238
|
-
|
|
239
|
-
```typescript
|
|
240
|
-
async migrateToOrderedCollection() {
|
|
241
|
-
const oldIds = JSON.parse(this.orderedTaskIds);
|
|
242
|
-
const batchId = await this.perspective.createBatch();
|
|
243
|
-
let previousId = null;
|
|
244
|
-
for (const taskId of oldIds) {
|
|
245
|
-
await this.perspective.addLink({ source: taskId, predicate: 'ad4m://ordered_after', target: previousId || 'null' }, batchId);
|
|
246
|
-
await this.perspective.addLink({ source: taskId, predicate: 'ad4m://position_id', target: `literal://string:${Date.now()}_migration` }, batchId);
|
|
247
|
-
previousId = taskId;
|
|
248
|
-
}
|
|
249
|
-
await this.perspective.commitBatch(batchId);
|
|
250
|
-
this.orderedTaskIds = '[]';
|
|
251
|
-
await this.update();
|
|
252
|
-
}
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
---
|
|
256
|
-
|
|
257
|
-
### Strategy Comparison
|
|
258
|
-
|
|
259
|
-
| | RGA (LinkedList) | YATA | Fractional Index |
|
|
260
|
-
| ----------------------- | ---------------- | --------- | ---------------- |
|
|
261
|
-
| **Insert** | O(n) | O(1)\* | O(1) |
|
|
262
|
-
| **Delete** | O(n) | O(1) | O(n) |
|
|
263
|
-
| **Move** | O(n)×2 | O(1)×2 | O(1) |
|
|
264
|
-
| **Memory/item** | ~64 bytes | ~96 bytes | ~64 bytes |
|
|
265
|
-
| **Links/item** | 2 | 5 | 2 |
|
|
266
|
-
| **Conflict resolution** | Good | Excellent | Good |
|
|
267
|
-
|
|
268
|
-
\*Amortized
|
|
269
|
-
|
|
270
|
-
**RGA/LinkedList** — recommended default. Simple, debuggable, natural for AD4M's triple store. Best for lists < 50 items.
|
|
271
|
-
|
|
272
|
-
**Fractional Index** — simpler to understand, good for deterministic ordering, lists that don't change structure often. Position strings can grow over time and need occasional rebalancing.
|
|
273
|
-
|
|
274
|
-
**YATA** — future option. 3× storage but O(1) amortised ops and best-in-class conflict semantics. Only worth it for heavy concurrent editing (document editors, etc.).
|
|
275
|
-
|
|
276
|
-
---
|
|
277
|
-
|
|
278
|
-
### Open Questions
|
|
279
|
-
|
|
280
|
-
1. **Bulk replace** (`tasks = newArray`) — treat as diff of old vs new, generate appropriate insert/delete operations.
|
|
281
|
-
2. **Custom strategies** — supported via plugin: `ordering: { strategy: new MyCustomStrategy() }`.
|
|
282
|
-
3. **Conflict visualisation** — AD4M inspector extension showing link graph.
|
|
283
|
-
4. **Garbage collection cadence** — run on perspective sync, configurable tombstone threshold (e.g. 30 days).
|
|
284
|
-
5. **Lazy vs eager reconstruction** — lazy on read, cache result, invalidate on link change.
|
|
285
|
-
|
|
286
|
-
---
|
|
287
|
-
|
|
288
|
-
### Implementation Phases
|
|
289
|
-
|
|
290
|
-
- [ ] Add `OrderingStrategy` interface + `LinkedListStrategy` (RGA)
|
|
291
|
-
- [ ] Add `ordering` option to `@HasMany` decorator options type
|
|
292
|
-
- [ ] Create Array Proxy layer in `Ad4mModel`
|
|
293
|
-
- [ ] Update `update()` to flush pending ordering operations
|
|
294
|
-
- [ ] Unit tests for each strategy in isolation
|
|
295
|
-
- [ ] `FractionalIndexStrategy` + `TimestampStrategy`
|
|
296
|
-
- [ ] Garbage collection
|
|
297
|
-
- [ ] Migration helper utility
|
|
298
|
-
- [ ] Integration tests (scenario 10 in playground)
|
|
299
|
-
- [ ] Debugging tools / inspector
|
|
300
|
-
|
|
301
|
-
---
|
|
302
|
-
|
|
303
|
-
### References
|
|
304
|
-
|
|
305
|
-
- [Figma's Fractional Indexing](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/)
|
|
306
|
-
- [CRDT Survey Paper](https://hal.inria.fr/hal-00932836/document)
|
|
307
|
-
- [RGA Algorithm](https://pages.lip6.fr/Marc.Shapiro/papers/RGA-TPDS-2011.pdf)
|
|
308
|
-
- [Yjs Documentation](https://docs.yjs.dev/)
|
|
309
|
-
- [Automerge CRDT](https://automerge.org/)
|
|
310
|
-
|
|
311
|
-
---
|
|
312
|
-
|
|
313
|
-
**Scope:** Changes to `hydration.ts`, `SurrealQueryBuilder.ts`, `@HasMany` decorator options, possibly SHACL-level ordering predicates, and the Rust executor's link ordering. Fills in scenario 10 of the playground test harness.
|
|
314
|
-
|
|
315
|
-
**Priority:** Post-merge. High impact for multi-user apps.
|
|
316
|
-
|
|
317
|
-
---
|
|
318
|
-
|
|
319
|
-
## 12. External Consumer Migration — SubjectRepository (Phase G)
|
|
320
|
-
|
|
321
|
-
**Background:** `flux/packages/api/src/factory/SubjectRepository` and `ad4m-hooks/helpers/src/factory/SubjectRepository` still use Prolog `infer()` + the Subject proxy (`subject.init()`, async getters) for all model queries. They have no knowledge of `Ad4mModel`.
|
|
322
|
-
|
|
323
|
-
**Migration path:**
|
|
324
|
-
|
|
325
|
-
- Replace `getAll()` + `getSubjectData()` with `Ad4mModel.findAll()`
|
|
326
|
-
- Replace paginated `getAll()` with `Ad4mModel.findPage()`
|
|
327
|
-
- Replace Subject proxy getters with `Ad4mModel.getData()`
|
|
328
|
-
- Wire `useSubjects`/`useSubject` hooks to `Ad4mModel.subscribe()` for live updates
|
|
329
|
-
|
|
330
|
-
**Removals after migration:**
|
|
331
|
-
|
|
332
|
-
- `PerspectiveProxy.getSubjectData()` + `getSubjectProxy()`
|
|
333
|
-
- `PerspectiveClient.getSubjectData()`
|
|
334
|
-
- Rust `get_subject_data()` + GQL resolver (currently fires 5 Prolog queries per call)
|
|
335
|
-
- Both `SubjectRepository` classes
|
|
336
|
-
|
|
337
|
-
**Prerequisite:** Flux Phase F (decorator rename) must complete first.
|
|
338
|
-
|
|
339
|
-
**Priority:** Post-merge. Gated on Flux and hooks teams.
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
|
-
## 13. sh:inversePath — Rust/Prolog Side
|
|
344
|
-
|
|
345
|
-
**Background:** `@BelongsToOne`/`@BelongsToMany` set `inversePath: true` on the SHACL shape. The TypeScript SurrealDB hydration path works correctly (reverse `WHERE out.uri = ...` query). However `shacl_parser.rs` has zero handling of `sh:inversePath` — it never emits reverse Prolog predicates, so any Prolog-side lookup for a reverse relation silently returns nothing. `generatePrologFacts.ts` likewise has no reverse-predicate clause.
|
|
346
|
-
|
|
347
|
-
**Action:**
|
|
348
|
-
|
|
349
|
-
- `shacl_parser.rs`: detect `sh:inversePath`, emit reverse Prolog clauses (e.g. `channel_of(X, Y) :- triple(Y, 'predicate', X).`)
|
|
350
|
-
- `generatePrologFacts.ts`: handle `inversePath: true` shapes, emit reverse predicate clause
|
|
351
|
-
|
|
352
|
-
**Priority:** Low — only matters if a consumer writes explicit Prolog queries against reverse relations. The SurrealDB path (the common case) already works.
|
|
353
|
-
|
|
354
|
-
---
|
|
355
|
-
|
|
356
|
-
## 14. Parameterised SurrealQL Queries
|
|
357
|
-
|
|
358
|
-
**Problem:** `SurrealQueryBuilder.ts` and `getData()` still use string interpolation with `formatSurrealValue()` to prevent injection. SurrealDB supports parameterized queries via `querySurrealDB(query, bindings)` which are safe by construction.
|
|
359
|
-
|
|
360
|
-
```typescript
|
|
361
|
-
// Current:
|
|
362
|
-
`SELECT ... FROM link WHERE in.uri = ${formatSurrealValue(base)}`;
|
|
363
|
-
|
|
364
|
-
// Target:
|
|
365
|
-
perspective.querySurrealDB("SELECT ... FROM link WHERE in.uri = $base", {
|
|
366
|
-
base,
|
|
367
|
-
});
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
**Scope:** `queryToSurrealQL`, `getData()`, `fetchInstance.ts`, all raw SurrealQL construction throughout the query layer.
|
|
371
|
-
|
|
372
|
-
**Priority:** Medium. Not a regression (`formatSurrealValue` prevents injection today) but parameterized queries are the industry standard and eliminate an entire class of potential escaping bugs.
|
|
373
|
-
|
|
374
|
-
---
|
|
375
|
-
|
|
376
|
-
## 15. SDNA Wire Protocol Rename (`collection*` → `relation*`)
|
|
377
|
-
|
|
378
|
-
**Background:** The SDNA wire protocol still uses `collection`-prefixed predicate names: `collection/2`, `collection_getter/4`, `collection_adder/3`, `collection_remover/3`, `collection_setter/3`. These appear in 78+ locations across bootstrap languages and are queried by name throughout the Rust executor.
|
|
379
|
-
|
|
380
|
-
**Why deferred:** Renaming is a breaking change to the SDNA wire protocol — any live perspective with existing SDNA would stop working. Requires a versioned format, compatibility shim, or coordinated breaking release.
|
|
381
|
-
|
|
382
|
-
**Scope:**
|
|
383
|
-
|
|
384
|
-
1. Choose new names (`relation/2`, `relation_getter/4`, etc.)
|
|
385
|
-
2. Update all Rust executor references (`engine_pool.rs`, `sdna.rs`, `perspective_instance.rs`)
|
|
386
|
-
3. Update all 78+ bootstrap language `.pl` files
|
|
387
|
-
4. Update `tests/js/sdna/subject.pl`
|
|
388
|
-
5. Write migration strategy
|
|
389
|
-
|
|
390
|
-
**Priority:** Major version / coordinated release item. Not before Phase G is complete.
|
|
391
|
-
|
|
392
|
-
---
|
|
393
|
-
|
|
394
|
-
## 16. Relation Action Duplication — TypeScript vs Rust SHACL
|
|
395
|
-
|
|
396
|
-
**Problem:** Relation adder/remover/setter mutations call `executeAction` with a TypeScript-generated action array. The Rust executor has `get_collection_adder_actions()` that derives the same structure from SHACL. Two implementations of the same logic that must stay in sync manually.
|
|
397
|
-
|
|
398
|
-
**Solution:** Have relation mutations fetch SHACL-derived actions from the executor (the same way `createSubject` does for property setters) rather than generating them independently in TypeScript.
|
|
399
|
-
|
|
400
|
-
**Priority:** Low. The implementations are simple and unlikely to diverge in practice, but the duplication is a maintenance risk for anyone modifying SHACL action formats.
|
|
401
|
-
|
|
402
|
-
---
|
|
403
|
-
|
|
404
|
-
## 17. Lifecycle Hooks
|
|
405
|
-
|
|
406
|
-
**Problem:** No mechanism to run logic before/after model persistence operations. Common patterns (validation before save, cascading deletes, post-load transforms) require subclass overrides with manual `super` calls.
|
|
407
|
-
|
|
408
|
-
**Proposed API:** Override async methods on the model class:
|
|
409
|
-
|
|
410
|
-
```typescript
|
|
411
|
-
@ModelOptions({ name: "Recipe" })
|
|
412
|
-
class Recipe extends Ad4mModel {
|
|
413
|
-
async beforeSave() {
|
|
414
|
-
if (!this.name) throw new Error("Name required");
|
|
415
|
-
}
|
|
416
|
-
|
|
417
|
-
async afterLoad() {
|
|
418
|
-
// post-process after loading from perspective
|
|
419
|
-
}
|
|
420
|
-
|
|
421
|
-
async beforeDelete() {
|
|
422
|
-
// cascade deletes, cleanup, etc.
|
|
423
|
-
await Promise.all(this.ingredients.map((i) => i.delete()));
|
|
424
|
-
}
|
|
425
|
-
}
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
**Scope:** `Ad4mModel.ts` — add protected no-op stub methods; call them at the appropriate points in `save()`, `getData()`/`findAll()`, and `delete()`. Hooks should be `async` and awaited so they can perform perspective operations.
|
|
429
|
-
|
|
430
|
-
**Priority:** Medium. Low effort, high ergonomics win.
|
|
431
|
-
|
|
432
|
-
---
|
|
433
|
-
|
|
434
|
-
## 18. Auto-Inverse Relations
|
|
435
|
-
|
|
436
|
-
**Problem:** Defining both sides of a bidirectional relationship is repetitive and error-prone. If the predicates or models diverge the relationship silently breaks.
|
|
437
|
-
|
|
438
|
-
**Proposed API:** An `inverse` option on `@BelongsToOne` / `@BelongsToMany` that auto-registers the forward `@HasMany` on the related class:
|
|
439
|
-
|
|
440
|
-
```typescript
|
|
441
|
-
@ModelOptions({ name: "Message" })
|
|
442
|
-
class Message extends Ad4mModel {
|
|
443
|
-
@BelongsToOne(() => Channel, {
|
|
444
|
-
through: "ad4m://has_child",
|
|
445
|
-
inverse: "messages", // auto-registers @HasMany on Channel
|
|
446
|
-
})
|
|
447
|
-
channel: Channel;
|
|
448
|
-
}
|
|
449
|
-
|
|
450
|
-
// Channel no longer needs to manually declare:
|
|
451
|
-
// @HasMany(() => Message, { through: 'ad4m://has_child' })
|
|
452
|
-
// messages: Message[] = [];
|
|
453
|
-
```
|
|
454
|
-
|
|
455
|
-
**Scope:** Decorator registration in `decorators.ts` — after `@BelongsToOne`/`@BelongsToMany` registers its own metadata, if `inverse` is set, call `registerRelation` on the related class's prototype for the forward side. Requires deferred resolution (the related class may not be fully defined yet) — use a post-decoration pass or lazy initialisation at first metadata read.
|
|
456
|
-
|
|
457
|
-
**Priority:** Low-medium. Reduces boilerplate in bidirectional models but the manual two-sided declaration is clear and explicit.
|
|
458
|
-
|
|
459
|
-
---
|
|
460
|
-
|
|
461
|
-
## Priority Order (suggested)
|
|
462
|
-
|
|
463
|
-
| # | Item | Impact | Effort |
|
|
464
|
-
| --- | ----------------------------- | ------ | ------ |
|
|
465
|
-
| 2 | Range filter push-down | High | Medium |
|
|
466
|
-
| 1 | Dirty tracking | High | Medium |
|
|
467
|
-
| 3 | N+1 batching | High | Medium |
|
|
468
|
-
| 8 | `getter` N+1 / push-down | High | Medium |
|
|
469
|
-
| 11 | CRDT ordering | High | High |
|
|
470
|
-
| 4 | Runtime validation | Medium | Low |
|
|
471
|
-
| 6 | Create-vs-update detection | Medium | Low |
|
|
472
|
-
| 14 | Parameterised SurrealQL | Medium | Medium |
|
|
473
|
-
| 10 | tests/js migration | Medium | Medium |
|
|
474
|
-
| 12 | External consumer migration | Medium | High |
|
|
475
|
-
| 5 | fromJSONSchema type inference | Medium | High |
|
|
476
|
-
| 13 | sh:inversePath Rust side | Low | Low |
|
|
477
|
-
| 16 | Relation action duplication | Low | Medium |
|
|
478
|
-
| 9 | Transaction abort | Low | Low |
|
|
479
|
-
| 15 | SDNA wire rename | Low | High |
|
|
480
|
-
| 17 | Lifecycle hooks | Medium | Low |
|
|
481
|
-
| 18 | Auto-inverse relations | Low | Medium |
|
|
482
|
-
| 7 | Stage 3 decorators | Low | High |
|