@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,609 +0,0 @@
|
|
|
1
|
-
# TC39 Stage 3 Decorator Migration Plan
|
|
2
|
-
|
|
3
|
-
> **Status:** Planning
|
|
4
|
-
> **Created:** 2026-02-28
|
|
5
|
-
> **Estimated effort:** ~7–9 days
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Table of Contents
|
|
10
|
-
|
|
11
|
-
1. [Problem Statement](#problem-statement)
|
|
12
|
-
2. [Why TC39 Decorators](#why-tc39-decorators)
|
|
13
|
-
3. [Current Architecture (Legacy Decorators)](#current-architecture-legacy-decorators)
|
|
14
|
-
4. [Target Architecture (TC39 Decorators)](#target-architecture-tc39-decorators)
|
|
15
|
-
5. [Implementation Roadmap](#implementation-roadmap)
|
|
16
|
-
- [Phase 1: Upgrade TypeScript](#phase-1-upgrade-typescript)
|
|
17
|
-
- [Phase 2: Add `declare` to Flux Model Fields](#phase-2-add-declare-to-flux-model-fields)
|
|
18
|
-
- [Phase 3: Rewrite Decorators to TC39 Spec](#phase-3-rewrite-decorators-to-tc39-spec)
|
|
19
|
-
- [Phase 4: Update Ad4mModel Constructor](#phase-4-update-ad4mmodel-constructor)
|
|
20
|
-
- [Phase 5: Fix Projection (Remove Hacks)](#phase-5-fix-projection-remove-hacks)
|
|
21
|
-
- [Phase 6: Update All Consumer tsconfigs](#phase-6-update-all-consumer-tsconfigs)
|
|
22
|
-
- [Phase 7: Integration Testing](#phase-7-integration-testing)
|
|
23
|
-
6. [Effort Estimate](#effort-estimate)
|
|
24
|
-
7. [What You Get](#what-you-get)
|
|
25
|
-
8. [Gotchas & Risks](#gotchas--risks)
|
|
26
|
-
9. [Appendix: Current State Audit](#appendix-current-state-audit)
|
|
27
|
-
|
|
28
|
-
---
|
|
29
|
-
|
|
30
|
-
## Problem Statement
|
|
31
|
-
|
|
32
|
-
Ad4m's model system needs to:
|
|
33
|
-
|
|
34
|
-
1. **Map class fields ↔ link-triple predicates** (`title` ↔ `"test://title"`)
|
|
35
|
-
2. **Generate SHACL shapes** (W3C standard) from the schema for `ensureSDNASubjectClass`
|
|
36
|
-
3. **Hydrate instances** from SurrealDB query results
|
|
37
|
-
4. **Persist via link mutations** (add/remove/set links)
|
|
38
|
-
5. **Provide instance methods** (`save()`, `addComments()`, `get()`, `delete()`)
|
|
39
|
-
6. **Support inheritance** (`TestDerivedModel extends TestBaseModel`)
|
|
40
|
-
7. **Work with Vue/React reactivity** (no `#private` fields)
|
|
41
|
-
|
|
42
|
-
The current system uses **legacy TypeScript experimental decorators** (`experimentalDecorators: true`). These decorators receive `target` = the **class prototype**, and every decorator writes to it:
|
|
43
|
-
|
|
44
|
-
```ts
|
|
45
|
-
// decorators.ts — current @Property implementation
|
|
46
|
-
Object.defineProperty(target, key, { configurable: true, writable: true });
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
This creates properties like `TestPost.prototype.body = undefined`, `TestPost.prototype.title = undefined`, etc. on the **prototype**, not the instance.
|
|
50
|
-
|
|
51
|
-
### Concrete bugs caused by this
|
|
52
|
-
|
|
53
|
-
- **`delete instance.body` doesn't fully work** — removes the own property, but `'body' in instance` still returns `true` because `TestPost.prototype.body` exists. This broke our `properties` field projection feature.
|
|
54
|
-
- **Setter stubs on the prototype** — `target[setTitle] = () => {}` puts empty functions on the prototype that could mask real setter wiring if the constructor fails.
|
|
55
|
-
- **`Object.keys(instance)` includes hydrated data but not prototype-shadow fields** — leading to asymmetric behaviour depending on whether a field was hydrated or not.
|
|
56
|
-
|
|
57
|
-
---
|
|
58
|
-
|
|
59
|
-
## Why TC39 Decorators
|
|
60
|
-
|
|
61
|
-
| Aspect | Legacy (`experimentalDecorators`) | TC39 Stage 3 (TS ≥ 5.0) |
|
|
62
|
-
| --------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
|
|
63
|
-
| **Spec status** | Deprecated direction; based on an abandoned proposal | JavaScript standard (Stage 3, shipping in engines) |
|
|
64
|
-
| **`target` parameter** | The **prototype** | N/A — field decorators receive `undefined` + a `context` object |
|
|
65
|
-
| **Per-instance init** | Not available — must write to prototype | `context.addInitializer()` runs code in the constructor |
|
|
66
|
-
| **Metadata sharing** | Manual WeakMaps keyed on constructor | `context.metadata` — TC39-standard shared object per class |
|
|
67
|
-
| **`emitDecoratorMetadata`** | Supported (Reflect.getMetadata) | Not supported — use `context.metadata` instead |
|
|
68
|
-
| **Prototype pollution** | Inherent to the pattern | Impossible — field decorators don't receive the prototype |
|
|
69
|
-
|
|
70
|
-
The public API stays **identical** — `@Property({ through: "test://title" })` looks exactly the same to consumers.
|
|
71
|
-
|
|
72
|
-
---
|
|
73
|
-
|
|
74
|
-
## Current Architecture (Legacy Decorators)
|
|
75
|
-
|
|
76
|
-
### How `@Property` works today
|
|
77
|
-
|
|
78
|
-
```ts
|
|
79
|
-
// core/src/model/decorators.ts (current)
|
|
80
|
-
export function Property(opts: PropertyOptions) {
|
|
81
|
-
return function <T>(target: T, key: keyof T) {
|
|
82
|
-
// 1. Register metadata in WeakMap keyed on constructor
|
|
83
|
-
const existing = propertyRegistry.get((target as any).constructor) ?? {};
|
|
84
|
-
propertyRegistry.set((target as any).constructor, {
|
|
85
|
-
...existing,
|
|
86
|
-
[key as string]: { ...existing[key as string], ...opts },
|
|
87
|
-
});
|
|
88
|
-
|
|
89
|
-
// 2. Place setter stub on PROTOTYPE (pollution)
|
|
90
|
-
if (!opts.readOnly) {
|
|
91
|
-
target[`set${capitalize(key as string)}`] = () => {};
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
// 3. Place field descriptor on PROTOTYPE (pollution)
|
|
95
|
-
Object.defineProperty(target, key, { configurable: true, writable: true });
|
|
96
|
-
};
|
|
97
|
-
}
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
**Steps 2 and 3 write to the prototype**, which is the root cause of all the issues.
|
|
101
|
-
|
|
102
|
-
### How `@HasMany` / `@HasOne` work today
|
|
103
|
-
|
|
104
|
-
Same pattern — register metadata, place `addX`/`removeX`/`setX` stubs on the prototype, call `Object.defineProperty` on the prototype.
|
|
105
|
-
|
|
106
|
-
### How `@Model` works today
|
|
107
|
-
|
|
108
|
-
Class decorator. Sets `target.prototype.className`, generates SHACL via `target.generateSHACL = function() { ... }`. This part is fine — class decorators always receive the constructor, not the prototype.
|
|
109
|
-
|
|
110
|
-
### tsconfig settings
|
|
111
|
-
|
|
112
|
-
| Project | `experimentalDecorators` | `emitDecoratorMetadata` | `target` | `useDefineForClassFields` | TypeScript version |
|
|
113
|
-
| ------------------- | ------------------------ | ----------------------- | -------- | ------------------------------------- | ------------------ |
|
|
114
|
-
| `ad4m/core` | `true` | `true` | `ES2020` | not set (default: `false` for ES2020) | `^4.6.2` |
|
|
115
|
-
| `flux/packages/api` | `true` | not set | `ES6` | not set (default: `false` for ES6) | inherited |
|
|
116
|
-
| `we` playground | `true` | `true` | `ES2022` | **`false`** (explicit) | inherited |
|
|
117
|
-
|
|
118
|
-
### Field declaration patterns
|
|
119
|
-
|
|
120
|
-
| Project | Pattern | Example | Count |
|
|
121
|
-
| -------------- | ------------------------------------- | --------------------- | --------------------------- |
|
|
122
|
-
| **Flux** | Bare type annotation (no initializer) | `body: string;` | ~60 fields across 22 models |
|
|
123
|
-
| **Flux** | With initializer (arrays) | `views: App[] = [];` | ~20 fields |
|
|
124
|
-
| **We** | Always has initializer | `body: string = "";` | ~30 fields across 10 models |
|
|
125
|
-
| **ad4m tests** | Always has initializer | `title: string = "";` | ~15 fields across 6 models |
|
|
126
|
-
|
|
127
|
-
---
|
|
128
|
-
|
|
129
|
-
## Target Architecture (TC39 Decorators)
|
|
130
|
-
|
|
131
|
-
### Core idea: field decorators only store metadata, class decorator collects and registers
|
|
132
|
-
|
|
133
|
-
```
|
|
134
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
135
|
-
│ @Property / @HasMany / @Flag (field decorators) │
|
|
136
|
-
│ → write to context.metadata.__ad4m_properties / _relations │
|
|
137
|
-
│ → NO writes to prototype │
|
|
138
|
-
│ → return initializer function (pass-through or flag value) │
|
|
139
|
-
└──────────────────────┬──────────────────────────────────────┘
|
|
140
|
-
│ context.metadata is shared
|
|
141
|
-
▼
|
|
142
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
143
|
-
│ @Model (class decorator) │
|
|
144
|
-
│ → reads context.metadata to get all field/relation info │
|
|
145
|
-
│ → registers in propertyRegistry / relationRegistry WeakMap │
|
|
146
|
-
│ → attaches className, generateSHACL │
|
|
147
|
-
└─────────────────────────────────────────────────────────────┘
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
### `@Property` — TC39 version
|
|
151
|
-
|
|
152
|
-
```ts
|
|
153
|
-
function Property(opts: PropertyOptions) {
|
|
154
|
-
return function (
|
|
155
|
-
_value: undefined, // field decorators receive undefined
|
|
156
|
-
context: ClassFieldDecoratorContext, // TC39 context object
|
|
157
|
-
) {
|
|
158
|
-
const key = String(context.name);
|
|
159
|
-
|
|
160
|
-
// Store metadata in the shared context.metadata object.
|
|
161
|
-
// All field decorators on the same class share this object.
|
|
162
|
-
const meta = context.metadata as any;
|
|
163
|
-
meta.__ad4m_properties ??= {};
|
|
164
|
-
meta.__ad4m_properties[key] = {
|
|
165
|
-
...(meta.__ad4m_properties[key] ?? {}),
|
|
166
|
-
...opts,
|
|
167
|
-
};
|
|
168
|
-
|
|
169
|
-
// Return an initializer function that runs when the field is assigned.
|
|
170
|
-
// For most fields this is a pass-through — the class field initializer
|
|
171
|
-
// (e.g. `body: string = ""`) provides the default value.
|
|
172
|
-
return (initialValue: any) => initialValue;
|
|
173
|
-
|
|
174
|
-
// NO Object.defineProperty on prototype
|
|
175
|
-
// NO setter stubs on prototype
|
|
176
|
-
};
|
|
177
|
-
}
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
### `@Flag` — TC39 version
|
|
181
|
-
|
|
182
|
-
```ts
|
|
183
|
-
function Flag(opts: FlagOptions) {
|
|
184
|
-
return function (_value: undefined, context: ClassFieldDecoratorContext) {
|
|
185
|
-
const key = String(context.name);
|
|
186
|
-
|
|
187
|
-
const meta = context.metadata as any;
|
|
188
|
-
meta.__ad4m_properties ??= {};
|
|
189
|
-
meta.__ad4m_properties[key] = {
|
|
190
|
-
through: opts.through,
|
|
191
|
-
initial: opts.value,
|
|
192
|
-
flag: true,
|
|
193
|
-
readOnly: true,
|
|
194
|
-
required: true,
|
|
195
|
-
};
|
|
196
|
-
|
|
197
|
-
// Return initializer that sets the flag value — regardless of
|
|
198
|
-
// what the class field initializer says, flags always equal opts.value
|
|
199
|
-
return () => opts.value;
|
|
200
|
-
};
|
|
201
|
-
}
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
### `@HasMany` — TC39 version
|
|
205
|
-
|
|
206
|
-
```ts
|
|
207
|
-
function HasMany(
|
|
208
|
-
relatedModelOrOpts: (() => any) | RelationOptions,
|
|
209
|
-
opts?: RelationOptions,
|
|
210
|
-
) {
|
|
211
|
-
const resolvedOpts =
|
|
212
|
-
typeof relatedModelOrOpts === "function" ? opts! : relatedModelOrOpts;
|
|
213
|
-
const relatedModel =
|
|
214
|
-
typeof relatedModelOrOpts === "function" ? relatedModelOrOpts : undefined;
|
|
215
|
-
|
|
216
|
-
return function (_value: undefined, context: ClassFieldDecoratorContext) {
|
|
217
|
-
const key = String(context.name);
|
|
218
|
-
|
|
219
|
-
const meta = context.metadata as any;
|
|
220
|
-
meta.__ad4m_relations ??= {};
|
|
221
|
-
meta.__ad4m_relations[key] = {
|
|
222
|
-
...resolvedOpts,
|
|
223
|
-
direction: "forward" as const,
|
|
224
|
-
...(relatedModel ? { relatedModel } : {}),
|
|
225
|
-
};
|
|
226
|
-
|
|
227
|
-
// Pass through the initializer (typically `= []`)
|
|
228
|
-
return (initialValue: any) => initialValue;
|
|
229
|
-
|
|
230
|
-
// NO addX/removeX/setX stubs on prototype —
|
|
231
|
-
// these are wired in the Ad4mModel constructor already
|
|
232
|
-
};
|
|
233
|
-
}
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
### `@HasOne`, `@BelongsToOne`, `@BelongsToMany` — same pattern
|
|
237
|
-
|
|
238
|
-
Each stores its metadata in `context.metadata.__ad4m_relations` with the appropriate `direction` and `maxCount` values. No prototype writes.
|
|
239
|
-
|
|
240
|
-
### `@Model` — TC39 version
|
|
241
|
-
|
|
242
|
-
```ts
|
|
243
|
-
function Model(opts: ModelConfig) {
|
|
244
|
-
return function <T extends new (...args: any[]) => any>(
|
|
245
|
-
target: T,
|
|
246
|
-
context: ClassDecoratorContext,
|
|
247
|
-
) {
|
|
248
|
-
// At this point, ALL field decorators have already run and populated
|
|
249
|
-
// context.metadata with __ad4m_properties and __ad4m_relations.
|
|
250
|
-
const meta = context.metadata as any;
|
|
251
|
-
const properties = meta.__ad4m_properties ?? {};
|
|
252
|
-
const relations = meta.__ad4m_relations ?? {};
|
|
253
|
-
|
|
254
|
-
// Register in WeakMaps (same as today, but populated cleanly)
|
|
255
|
-
propertyRegistry.set(target, properties);
|
|
256
|
-
relationRegistry.set(target, relations);
|
|
257
|
-
|
|
258
|
-
// Attach className (same as today)
|
|
259
|
-
target.prototype.className = opts.name;
|
|
260
|
-
target.className = opts.name;
|
|
261
|
-
|
|
262
|
-
// Attach generateSHACL (same logic as today — reads from registries)
|
|
263
|
-
target.generateSHACL = function () {
|
|
264
|
-
// ... identical SHACL generation code ...
|
|
265
|
-
};
|
|
266
|
-
|
|
267
|
-
return target;
|
|
268
|
-
};
|
|
269
|
-
}
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
### Inheritance support
|
|
273
|
-
|
|
274
|
-
TC39 `context.metadata` uses prototype-based inheritance automatically:
|
|
275
|
-
|
|
276
|
-
```ts
|
|
277
|
-
@Model({ name: "Base" })
|
|
278
|
-
class Base extends Ad4mModel {
|
|
279
|
-
@Property({ through: "base://content" })
|
|
280
|
-
content: string = "";
|
|
281
|
-
}
|
|
282
|
-
|
|
283
|
-
@Model({ name: "Derived" })
|
|
284
|
-
class Derived extends Base {
|
|
285
|
-
@Property({ through: "derived://extra" })
|
|
286
|
-
extra: string = "";
|
|
287
|
-
}
|
|
288
|
-
// Derived[Symbol.metadata].__ad4m_properties inherits Base's via prototype chain
|
|
289
|
-
// getPropertiesMetadata(Derived) returns { content: {...}, extra: {...} }
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
The existing `getPropertiesMetadata()` / `getRelationsMetadata()` functions that walk the constructor prototype chain continue to work unchanged.
|
|
293
|
-
|
|
294
|
-
---
|
|
295
|
-
|
|
296
|
-
## Implementation Roadmap
|
|
297
|
-
|
|
298
|
-
### Phase 1: Upgrade TypeScript
|
|
299
|
-
|
|
300
|
-
**Files:** root `package.json`, `core/package.json`, all `tsconfig.json` files
|
|
301
|
-
**Effort:** 1–2 days
|
|
302
|
-
**Risk:** High (touches all projects)
|
|
303
|
-
|
|
304
|
-
1. Bump TypeScript to `^5.4` (or latest stable 5.x) in:
|
|
305
|
-
- `ad4m/core/package.json` (currently `^4.6.2`)
|
|
306
|
-
- Any other packages that pin their own TS version
|
|
307
|
-
2. In every `tsconfig.json`:
|
|
308
|
-
- Remove `"experimentalDecorators": true`
|
|
309
|
-
- Remove `"emitDecoratorMetadata": true`
|
|
310
|
-
- Set `"target": "ES2022"` or higher
|
|
311
|
-
- Set `"useDefineForClassFields": true` (explicit, even though it's the default for ES2022+)
|
|
312
|
-
3. Fix any type errors from the TS version bump (likely minimal)
|
|
313
|
-
4. Validate builds pass: `pnpm build` in ad4m root, `yarn build` in flux
|
|
314
|
-
|
|
315
|
-
> **Note:** Do this on a dedicated branch. The tsconfig changes alone will break decorators until Phase 3 is complete, so Phases 1–3 should land together.
|
|
316
|
-
|
|
317
|
-
### Phase 2: Add `declare` to Flux Model Fields
|
|
318
|
-
|
|
319
|
-
**Files:** All ~22 model files in `flux/packages/api/src/`
|
|
320
|
-
**Effort:** 1 day
|
|
321
|
-
**Risk:** Low (mechanical transformation)
|
|
322
|
-
|
|
323
|
-
With `useDefineForClassFields: true`, a bare field like:
|
|
324
|
-
|
|
325
|
-
```ts
|
|
326
|
-
@Property({ through: BODY })
|
|
327
|
-
body: string;
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
would emit `this.body = undefined` in the constructor, clobbering whatever the hydration pipeline sets. The fix:
|
|
331
|
-
|
|
332
|
-
```ts
|
|
333
|
-
@Property({ through: BODY })
|
|
334
|
-
declare body: string;
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
`declare` tells TypeScript "this field exists for type-checking but don't emit any runtime code." The decorator and hydration pipeline handle the actual value.
|
|
338
|
-
|
|
339
|
-
**Rules:**
|
|
340
|
-
|
|
341
|
-
| Field pattern | Action needed |
|
|
342
|
-
| --------------------------------------------- | ------------------------------------------------------------------------- |
|
|
343
|
-
| `body: string;` (no initializer) | Add `declare` → `declare body: string;` |
|
|
344
|
-
| `body: string = "";` (with initializer) | No change — initializer runs in constructor, creates own property |
|
|
345
|
-
| `views: App[] = [];` (array with initializer) | No change |
|
|
346
|
-
| `@Flag type: string;` | Add `declare` → `declare type: string;` (Flag initializer sets the value) |
|
|
347
|
-
|
|
348
|
-
**We models** already use initializers on all fields, so they need **no changes** for this phase.
|
|
349
|
-
|
|
350
|
-
**Ad4m test models** already use initializers on all fields, so they need **no changes** for this phase.
|
|
351
|
-
|
|
352
|
-
### Phase 3: Rewrite Decorators to TC39 Spec
|
|
353
|
-
|
|
354
|
-
**Files:** `core/src/model/decorators.ts`
|
|
355
|
-
**Effort:** 2–3 days
|
|
356
|
-
**Risk:** Medium (core logic unchanged, just new signatures)
|
|
357
|
-
|
|
358
|
-
This is the core of the migration. Each decorator changes its function signature but keeps the same metadata-registration logic. See the [Target Architecture](#target-architecture-tc39-decorators) section above for the full new implementations.
|
|
359
|
-
|
|
360
|
-
**Summary of changes per decorator:**
|
|
361
|
-
|
|
362
|
-
| Decorator | What changes | What stays the same |
|
|
363
|
-
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
|
|
364
|
-
| `@Property` | Signature → `(undefined, ClassFieldDecoratorContext)`. No `Object.defineProperty`. No setter stubs. Stores in `context.metadata`. | PropertyOptions interface. Metadata shape. |
|
|
365
|
-
| `@Flag` | Same as Property. Returns `() => opts.value` as initializer. | FlagOptions interface. |
|
|
366
|
-
| `@HasMany` | Signature → `(undefined, ClassFieldDecoratorContext)`. No `Object.defineProperty`. No add/remove/set stubs. Stores in `context.metadata.__ad4m_relations`. | RelationOptions interface. relatedModel factory. |
|
|
367
|
-
| `@HasOne` | Same as HasMany but adds `maxCount: 1`. | |
|
|
368
|
-
| `@BelongsToOne` | Same pattern, `direction: "reverse"`, `maxCount: 1`. | |
|
|
369
|
-
| `@BelongsToMany` | Same pattern, `direction: "reverse"`. | |
|
|
370
|
-
| `@Model` | Signature → `(target, ClassDecoratorContext)`. Reads `context.metadata` instead of WeakMaps directly. Registers in WeakMaps. SHACL generation unchanged. | ModelConfig interface. All SHACL logic. |
|
|
371
|
-
|
|
372
|
-
**What's deleted:**
|
|
373
|
-
|
|
374
|
-
- Every `Object.defineProperty(target, key, { configurable: true, writable: true })` line
|
|
375
|
-
- Every `target[setterName] = () => {}` line (setter stubs on prototype)
|
|
376
|
-
- Every `target[adderName] = () => {}` / `target[removerName] = () => {}` line
|
|
377
|
-
|
|
378
|
-
**`Symbol.metadata` polyfill** — TC39 `context.metadata` requires `Symbol.metadata` to exist. TypeScript 5.2+ emits the polyfill automatically. For older environments, add at the top of `decorators.ts`:
|
|
379
|
-
|
|
380
|
-
```ts
|
|
381
|
-
Symbol.metadata ??= Symbol("Symbol.metadata");
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
### Phase 4: Update Ad4mModel Constructor
|
|
385
|
-
|
|
386
|
-
**File:** `core/src/model/Ad4mModel.ts`
|
|
387
|
-
**Effort:** 0.5 day
|
|
388
|
-
**Risk:** Low
|
|
389
|
-
|
|
390
|
-
The constructor already wires `addX`/`removeX`/`setX` methods from the relation registry:
|
|
391
|
-
|
|
392
|
-
```ts
|
|
393
|
-
constructor(perspective: PerspectiveProxy, id?: string) {
|
|
394
|
-
this._id = id ? id : Literal.from(makeRandomId(24)).toUrl();
|
|
395
|
-
this._perspective = perspective;
|
|
396
|
-
|
|
397
|
-
// Wire up real relation mutator methods (already exists, no change needed)
|
|
398
|
-
const relations = getRelationsMetadata(proto.constructor);
|
|
399
|
-
for (const key of Object.keys(relations)) {
|
|
400
|
-
if (relations[key].direction === "reverse") continue;
|
|
401
|
-
const cap = capitalize(key);
|
|
402
|
-
this[`add${cap}`] = (value, batchId?) => mutation.setRelationAdder(...);
|
|
403
|
-
this[`remove${cap}`] = (value, batchId?) => mutation.setRelationRemover(...);
|
|
404
|
-
this[`set${cap}`] = (value, batchId?) => mutation.setRelationSetter(...);
|
|
405
|
-
}
|
|
406
|
-
}
|
|
407
|
-
```
|
|
408
|
-
|
|
409
|
-
This **doesn't need to change** — it reads from `relationRegistry` which is populated by `@Model` in Phase 3. The setter stubs that were previously on the prototype are no longer needed because the constructor was already overwriting them with real implementations.
|
|
410
|
-
|
|
411
|
-
**Optional enhancement:** add a `getModelMetadata()` path that can read from `Symbol.metadata` on the constructor as a fallback:
|
|
412
|
-
|
|
413
|
-
```ts
|
|
414
|
-
static getModelMetadata(): ModelMetadata {
|
|
415
|
-
// Primary: WeakMap (populated by @Model)
|
|
416
|
-
const fromRegistry = _getModelMetadata(this);
|
|
417
|
-
if (fromRegistry) return fromRegistry;
|
|
418
|
-
|
|
419
|
-
// Fallback: Symbol.metadata (TC39 standard)
|
|
420
|
-
const meta = (this as any)[Symbol.metadata];
|
|
421
|
-
if (meta) {
|
|
422
|
-
return {
|
|
423
|
-
className: this.prototype.className,
|
|
424
|
-
properties: meta.__ad4m_properties ?? {},
|
|
425
|
-
relations: meta.__ad4m_relations ?? {},
|
|
426
|
-
};
|
|
427
|
-
}
|
|
428
|
-
|
|
429
|
-
throw new Error("Model metadata not found — is @Model applied?");
|
|
430
|
-
}
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
### Phase 5: Fix Projection (Remove Hacks)
|
|
434
|
-
|
|
435
|
-
**Files:**
|
|
436
|
-
|
|
437
|
-
- `core/src/model/query/operations.ts`
|
|
438
|
-
- `tests/js/tests/model/model-query.test.ts`
|
|
439
|
-
|
|
440
|
-
**Effort:** 0.5 day
|
|
441
|
-
**Risk:** Low
|
|
442
|
-
|
|
443
|
-
With no prototype-shadow properties, `delete instance.body` will make `'body' in instance` return `false` correctly.
|
|
444
|
-
|
|
445
|
-
**Revert test assertions** from:
|
|
446
|
-
|
|
447
|
-
```ts
|
|
448
|
-
expect(r).to.not.have.own.property("body"); // current hack
|
|
449
|
-
```
|
|
450
|
-
|
|
451
|
-
back to:
|
|
452
|
-
|
|
453
|
-
```ts
|
|
454
|
-
expect(r).to.not.have.property("body"); // clean assertion
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
The projection code in `operations.ts` (`delete instance[key]`) works correctly with zero workarounds.
|
|
458
|
-
|
|
459
|
-
### Phase 6: Update All Consumer tsconfigs
|
|
460
|
-
|
|
461
|
-
**Files:** Every `tsconfig.json` across `ad4m`, `flux`, `we`
|
|
462
|
-
**Effort:** 0.5 day
|
|
463
|
-
**Risk:** Low
|
|
464
|
-
|
|
465
|
-
Ensure all projects have:
|
|
466
|
-
|
|
467
|
-
```jsonc
|
|
468
|
-
{
|
|
469
|
-
"compilerOptions": {
|
|
470
|
-
// Remove these:
|
|
471
|
-
// "experimentalDecorators": true,
|
|
472
|
-
// "emitDecoratorMetadata": true,
|
|
473
|
-
|
|
474
|
-
// Add/ensure these:
|
|
475
|
-
"target": "ES2022",
|
|
476
|
-
"useDefineForClassFields": true,
|
|
477
|
-
},
|
|
478
|
-
}
|
|
479
|
-
```
|
|
480
|
-
|
|
481
|
-
**Affected tsconfig counts:**
|
|
482
|
-
|
|
483
|
-
- Flux: ~20 tsconfig files with `experimentalDecorators: true`
|
|
484
|
-
- We: ~4 tsconfig files
|
|
485
|
-
- Ad4m: core + test-runner configs
|
|
486
|
-
|
|
487
|
-
### Phase 7: Integration Testing
|
|
488
|
-
|
|
489
|
-
**Effort:** 1–2 days
|
|
490
|
-
**Risk:** Medium
|
|
491
|
-
|
|
492
|
-
1. **Ad4m model tests:** `cd tests/js && pnpm test-model` — all query, transaction, and dirty-tracking tests
|
|
493
|
-
2. **SHACL validation:** Compare generated Turtle output before/after migration — must be byte-identical
|
|
494
|
-
3. **Flux build + dev:** `cd flux && yarn build && yarn dev` — ensure all 22 models hydrate correctly
|
|
495
|
-
4. **We playground:** Build and run the ad4m-model-testing playground
|
|
496
|
-
5. **Flux channel pinning:** The original bug that triggered this whole investigation — verify pinning a channel no longer duplicates conversations
|
|
497
|
-
|
|
498
|
-
---
|
|
499
|
-
|
|
500
|
-
## Effort Estimate
|
|
501
|
-
|
|
502
|
-
| Phase | Effort | Risk |
|
|
503
|
-
| -------------------------------- | ------------- | --------------------------------------------- |
|
|
504
|
-
| 1. Upgrade TypeScript | 1–2 days | High — touches all projects |
|
|
505
|
-
| 2. Add `declare` to Flux models | 1 day | Low — mechanical |
|
|
506
|
-
| 3. Rewrite decorators | 2–3 days | Medium — core logic unchanged, new signatures |
|
|
507
|
-
| 4. Update Ad4mModel constructor | 0.5 day | Low |
|
|
508
|
-
| 5. Fix projection (remove hacks) | 0.5 day | Low |
|
|
509
|
-
| 6. Update tsconfigs | 0.5 day | Low |
|
|
510
|
-
| 7. Integration testing | 1–2 days | Medium |
|
|
511
|
-
| **Total** | **~7–9 days** | |
|
|
512
|
-
|
|
513
|
-
> **Phases 1–3 must land together** on a single branch. The tsconfig changes break legacy decorators, and the new decorators require the tsconfig changes.
|
|
514
|
-
|
|
515
|
-
---
|
|
516
|
-
|
|
517
|
-
## What You Get
|
|
518
|
-
|
|
519
|
-
- **Zero prototype pollution** — decorators never write to the prototype
|
|
520
|
-
- **`delete instance.field` works correctly** — no phantom properties from prototype chain
|
|
521
|
-
- **Future-proof** — using the JavaScript standard, not a deprecated TS experiment
|
|
522
|
-
- **Cleaner separation of concerns** — field decorators only store metadata, class decorator collects and registers
|
|
523
|
-
- **`context.metadata`** — the TC39-standard way to share data between decorators, replacing manual WeakMap coordination
|
|
524
|
-
- **Same public API** — `@Property({ through: "..." })`, `@HasMany(...)`, etc. look identical to consumers
|
|
525
|
-
- **Same SHACL output** — the generated shapes are unchanged
|
|
526
|
-
- **Dirty tracking just works** — no prototype shadows to confuse snapshot comparisons
|
|
527
|
-
- **Projection just works** — `delete` fully removes properties, no `.own.property` hacks needed
|
|
528
|
-
|
|
529
|
-
---
|
|
530
|
-
|
|
531
|
-
## Gotchas & Risks
|
|
532
|
-
|
|
533
|
-
### 1. `emitDecoratorMetadata` is not supported by TC39 decorators
|
|
534
|
-
|
|
535
|
-
If anything relies on `Reflect.getMetadata()` at runtime, it needs to be replaced with `context.metadata`. The Ad4m codebase **does not appear to use** `Reflect.getMetadata()`, so this should be fine. Verify with:
|
|
536
|
-
|
|
537
|
-
```bash
|
|
538
|
-
grep -r "Reflect.getMetadata\|Reflect.defineMetadata\|reflect-metadata" --include="*.ts" core/src/
|
|
539
|
-
```
|
|
540
|
-
|
|
541
|
-
### 2. Decorator execution order changes slightly
|
|
542
|
-
|
|
543
|
-
In legacy decorators, field decorators run when the class is defined (at class parse time). In TC39, field decorator **initializers** run in the constructor. However, the metadata-via-`context.metadata` approach avoids timing issues because:
|
|
544
|
-
|
|
545
|
-
- Field decorators populate `context.metadata` at class definition time (the decorator function itself runs at definition time — only the _initializer_ it returns runs per-instance)
|
|
546
|
-
- The `@Model` class decorator runs at class definition time and reads the already-populated `context.metadata`
|
|
547
|
-
|
|
548
|
-
### 3. `Symbol.metadata` polyfill
|
|
549
|
-
|
|
550
|
-
TC39 `context.metadata` requires `Symbol.metadata` to exist. TypeScript 5.2+ emits the polyfill automatically. For older environments or bundlers that strip it, add at the top of `decorators.ts`:
|
|
551
|
-
|
|
552
|
-
```ts
|
|
553
|
-
Symbol.metadata ??= Symbol("Symbol.metadata");
|
|
554
|
-
```
|
|
555
|
-
|
|
556
|
-
### 4. Flux models without initializers need `declare`
|
|
557
|
-
|
|
558
|
-
With `useDefineForClassFields: true`, a bare `body: string;` emits `this.body = undefined` in the constructor. This would clobber hydrated values. The fix is `declare body: string;`.
|
|
559
|
-
|
|
560
|
-
**Enforcement:** Add an ESLint rule or a custom lint check that flags model fields (decorated with `@Property`, `@HasMany`, etc.) that lack either `declare` or an initializer.
|
|
561
|
-
|
|
562
|
-
### 5. Third-party decorator libraries
|
|
563
|
-
|
|
564
|
-
Check if any dependencies use `experimentalDecorators` in their published types. Most libraries ship plain `.d.ts` files that don't depend on decorator mode, but verify.
|
|
565
|
-
|
|
566
|
-
### 6. Vue reactivity
|
|
567
|
-
|
|
568
|
-
Vue 3's reactivity system uses Proxy-based tracking. `declare` fields that are later set by hydration will still be reactive — Vue tracks property access/mutation on the proxy, regardless of whether the property was declared with `declare` or an initializer. The `#private` concern (which breaks Vue proxies) is unrelated and already avoided in Ad4mModel.
|
|
569
|
-
|
|
570
|
-
---
|
|
571
|
-
|
|
572
|
-
## Appendix: Current State Audit
|
|
573
|
-
|
|
574
|
-
### Model count across projects
|
|
575
|
-
|
|
576
|
-
| Project | Model classes | Fields without initializer | Uses `declare` |
|
|
577
|
-
| ---------- | ------------- | -------------------------------------------- | -------------- |
|
|
578
|
-
| Flux | 22 | ~60 fields (all `@Property`/`@Flag` scalars) | No |
|
|
579
|
-
| We | 10 | 0 (all have initializers) | No |
|
|
580
|
-
| Ad4m tests | 6 | 0 (all have initializers) | No |
|
|
581
|
-
|
|
582
|
-
### Prototype properties created by current decorators
|
|
583
|
-
|
|
584
|
-
For a model like `TestPost` with `@Property title`, `@Property body`, `@Property viewCount`, `@HasMany tags`, `@HasMany comments`, `@HasOne pinnedComment`:
|
|
585
|
-
|
|
586
|
-
```
|
|
587
|
-
TestPost.prototype own keys:
|
|
588
|
-
constructor, type, setTitle, title, setBody, body,
|
|
589
|
-
setViewCount, viewCount, addTags, removeTags, setTags, tags,
|
|
590
|
-
addComments, removeComments, setComments, comments,
|
|
591
|
-
addPinnedComment, removePinnedComment, setPinnedComment, pinnedComment, className
|
|
592
|
-
```
|
|
593
|
-
|
|
594
|
-
Every `@Property` creates 2 prototype entries (field + setter stub).
|
|
595
|
-
Every `@HasMany`/`@HasOne` creates 4 prototype entries (field + add + remove + set stubs).
|
|
596
|
-
|
|
597
|
-
**After TC39 migration:** `TestPost.prototype` will only have `constructor` and `className`. Everything else is either an own property (from class field initializers) or wired in the `Ad4mModel` constructor (mutator methods).
|
|
598
|
-
|
|
599
|
-
### Files to modify
|
|
600
|
-
|
|
601
|
-
| File | Phase | Change |
|
|
602
|
-
| ----------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------ |
|
|
603
|
-
| `ad4m/core/package.json` | 1 | Bump `typescript` to `^5.4` |
|
|
604
|
-
| All `tsconfig.json` (~24 files) | 1, 6 | Remove `experimentalDecorators`/`emitDecoratorMetadata`, set `target: ES2022`, add `useDefineForClassFields: true` |
|
|
605
|
-
| `flux/packages/api/src/**/*.ts` (~22 files) | 2 | Add `declare` to ~60 bare-typed fields |
|
|
606
|
-
| `ad4m/core/src/model/decorators.ts` | 3 | Full decorator rewrite |
|
|
607
|
-
| `ad4m/core/src/model/Ad4mModel.ts` | 4 | Optional: add `Symbol.metadata` fallback in `getModelMetadata()` |
|
|
608
|
-
| `ad4m/core/src/model/query/operations.ts` | 5 | No code change needed — `delete` just works now |
|
|
609
|
-
| `ad4m/tests/js/tests/model/model-query.test.ts` | 5 | Revert `.own.property` → `.have.property` |
|