interaqt 3.1.0 → 4.0.0
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/agent/agentspace/knowledge/usage/04-reactive-computations.md +2 -0
- package/agent/agentspace/knowledge/usage/09-filtered-entities.md +14 -0
- package/agent/agentspace/knowledge/usage/19-common-anti-patterns.md +34 -2
- package/dist/core/Entity.d.ts.map +1 -1
- package/dist/core/Relation.d.ts.map +1 -1
- package/dist/core/propertyNameGuards.d.ts +3 -0
- package/dist/core/propertyNameGuards.d.ts.map +1 -0
- package/dist/index.js +1878 -1672
- package/dist/index.js.map +1 -1
- package/dist/runtime/ComputationSourceMap.d.ts +38 -10
- package/dist/runtime/ComputationSourceMap.d.ts.map +1 -1
- package/dist/runtime/Controller.d.ts.map +1 -1
- package/dist/runtime/Scheduler.d.ts +17 -3
- package/dist/runtime/Scheduler.d.ts.map +1 -1
- package/dist/runtime/migration.d.ts +1 -0
- package/dist/runtime/migration.d.ts.map +1 -1
- package/dist/storage/erstorage/Setup.d.ts +12 -0
- package/dist/storage/erstorage/Setup.d.ts.map +1 -1
- package/package.json +1 -1
|
@@ -137,6 +137,8 @@ Rules:
|
|
|
137
137
|
- Do not set a `defaultValue` on the same property. The allocator supplies the value after the create mutation and before commit.
|
|
138
138
|
- Scope paths can only read stable primitive/ref values already present on the created record.
|
|
139
139
|
- Missing or type-mismatched scope values are errors.
|
|
140
|
+
- **Scope inputs are immutable after numbering.** Updating a scope value field, or removing/replacing a scope ref relation, on a record that already holds a sequence number fails fast — the number is allocated once per scope at creation, and re-scoping would silently duplicate numbers in the target scope (permanently violating the `UniqueConstraint` there). Delete and recreate the record in the new scope, or model the mutable dimension outside the sequence scope. Records the `match` predicate skipped (no number assigned) can move freely.
|
|
141
|
+
- `match` predicate fields are also expected to be create-time stable: a record that starts non-matching and later mutates into the predicate does **not** get a number retroactively.
|
|
140
142
|
- `allowManualValue: true` is for import/backfill and does not advance the counter.
|
|
141
143
|
- Existing data migration should use `initializeFrom` to seed every scope with `MAX(serialNumber)`.
|
|
142
144
|
- Keep the `UniqueConstraint`; the allocator prevents normal duplicates, and the constraint is the integrity backstop.
|
|
@@ -523,6 +523,20 @@ const CategoryStats = Entity.create({
|
|
|
523
523
|
|
|
524
524
|
## Real-time Updates and Event Handling
|
|
525
525
|
|
|
526
|
+
### Event Semantics on Filtered Entity Names
|
|
527
|
+
|
|
528
|
+
A filtered entity name carries three event shapes, for both data-based computations (`dataDeps`) and event-based computations (`StateMachine` triggers, `Transform` `eventDeps`):
|
|
529
|
+
|
|
530
|
+
- `create` — a record **entered** the filtered set (created as a member, or updated into the predicate);
|
|
531
|
+
- `delete` — a record **left** the filtered set (deleted, or updated out of the predicate);
|
|
532
|
+
- `update` — a member's fields changed **while staying in** the set. The framework routes the base record's physical update event to listeners declared on the filtered name and rewrites `event.recordName` to the filtered name; enter/exit updates are delivered as the membership `create`/`delete` above (never double-fired as `update`).
|
|
533
|
+
|
|
534
|
+
So a `StateMachine` transfer like `trigger: { recordName: 'ActiveTicket', type: 'update', keys: ['title'] }` fires exactly for title changes of tickets that are and remain active.
|
|
535
|
+
|
|
536
|
+
The same three-shape semantics apply to **merged input views** (`inputEntities`/`inputRelations` declarations) and to nested filtered chains — every view name resolves to its physical base through the compiled storage schema.
|
|
537
|
+
|
|
538
|
+
Additionally, every declared listener is validated at setup: a `recordName` that no record in the storage schema carries (a typo, an entity not registered on the Controller, or a global dictionary name — dictionary changes are emitted on the `_Dictionary_` record with `record: { key: '<dictName>' }`) fails fast with a `ComputationProtocolError` instead of becoming a silent dead listener.
|
|
539
|
+
|
|
526
540
|
### Automatic Update Mechanism
|
|
527
541
|
|
|
528
542
|
```javascript
|
|
@@ -55,18 +55,50 @@ import { InteractionEventEntity } from 'interaqt';
|
|
|
55
55
|
```javascript
|
|
56
56
|
// ❌ WRONG: identifier property doesn't exist
|
|
57
57
|
Property.create({
|
|
58
|
-
name: '
|
|
58
|
+
name: 'externalId',
|
|
59
59
|
type: 'string',
|
|
60
60
|
identifier: true // This doesn't exist!
|
|
61
61
|
});
|
|
62
62
|
|
|
63
63
|
// ✅ CORRECT: ID uniqueness is handled by storage layer
|
|
64
64
|
Property.create({
|
|
65
|
-
name: '
|
|
65
|
+
name: 'externalId',
|
|
66
66
|
type: 'string'
|
|
67
67
|
});
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
+
### ❌ Declaring Reserved Property Names
|
|
71
|
+
|
|
72
|
+
```javascript
|
|
73
|
+
// ❌ WRONG: 'id' is the framework-managed primary key — Entity.create rejects it.
|
|
74
|
+
// The same applies to '_rowId', and to 'source'/'target' on relation properties.
|
|
75
|
+
Property.create({ name: 'id', type: 'string' });
|
|
76
|
+
|
|
77
|
+
// ✅ CORRECT: use an explicit business identifier name
|
|
78
|
+
Property.create({ name: 'externalId', type: 'string' });
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### ❌ Relation Property Name Colliding with a Value Property
|
|
82
|
+
|
|
83
|
+
```javascript
|
|
84
|
+
// ❌ WRONG: sourceProperty 'email' collides with the scalar property 'email' —
|
|
85
|
+
// they share one attribute namespace per record; setup fails fast.
|
|
86
|
+
const User = Entity.create({
|
|
87
|
+
name: 'User',
|
|
88
|
+
properties: [Property.create({ name: 'email', type: 'string' })]
|
|
89
|
+
});
|
|
90
|
+
Relation.create({
|
|
91
|
+
source: User, sourceProperty: 'email', // collides!
|
|
92
|
+
target: Contact, targetProperty: 'owner', type: '1:n'
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
// ✅ CORRECT: pick distinct names for value properties and relation properties
|
|
96
|
+
Relation.create({
|
|
97
|
+
source: User, sourceProperty: 'contacts',
|
|
98
|
+
target: Contact, targetProperty: 'owner', type: '1:n'
|
|
99
|
+
});
|
|
100
|
+
```
|
|
101
|
+
|
|
70
102
|
### ❌ Using Non-Function defaultValue
|
|
71
103
|
|
|
72
104
|
```javascript
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../../src/core/Entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgC,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;
|
|
1
|
+
{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../../src/core/Entity.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Relation.d.ts","sourceRoot":"","sources":["../../src/core/Relation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgC,MAAM,iBAAiB,CAAC;AAE1E,OAAO,EAAE,gBAAgB,EAAY,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"Relation.d.ts","sourceRoot":"","sources":["../../src/core/Relation.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"propertyNameGuards.d.ts","sourceRoot":"","sources":["../../src/core/propertyNameGuards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAStD,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAC1C,IAAI,EAAE,QAAQ,GAAG,UAAU,QAqB5B"}
|