@_linked/core 2.14.1 → 2.14.2-next.20260709132623

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.14.2
+
+### Patch Changes
+
+- [#164](https://github.com/linked-cm/core/pull/164) [`17bfb35`](https://github.com/linked-cm/core/commit/17bfb35049aff5e3482ea54cbcc074639476adbe) Thanks [@flyon](https://github.com/flyon)! - docs: document **owned properties** in the README — a new "Owned properties (`contains` / `dependent`)" section under Shapes explaining exclusive-ownership object properties (`contains: true`) and the automatic cascade cleanup on update-replace, set-remove, and parent-delete, and how the property-level `contains` flag differs from the shape-level `dependent` flag. No code change.
+
 ## 2.14.1
 
 ### Patch Changes

package/README.md

@@ -236,6 +236,48 @@ export class Person extends Shape {
 }
 ```
 
+### Owned properties (`contains` / `dependent`)
+
+By default an object property is a plain *reference*: the two nodes exist independently, and
+removing the link leaves the referenced node untouched. Two optional flags let you model
+**composition** (ownership) instead, so the framework cleans owned nodes up automatically.
+
+**`contains: true` on an object property** — the edge asserts *exclusive ownership* of the
+value. Whenever that edge goes away, the owned node is deleted with it:
+
+- `parent.delete()` deletes the owned child (and its owned sub-tree).
+- `update({ownedProp: newValue})` **replaces** the owned node — the old one is deleted, not
+  orphaned.
+- `update({ownedProp: {remove: [x]}})` deletes `x` itself, not just the link.
+
+```typescript
+@linkedShape
+export class Person extends Shape {
+  static targetClass = ex.Person;
+
+  // Person exclusively owns its avatar image. Replacing or clearing `avatar`,
+  // or deleting the Person, deletes the old ImageObject too.
+  @objectProperty({path: ex.avatar, shape: ImageObject, maxCount: 1, contains: true})
+  declare avatar: ImageObject;
+}
+```
+
+**`dependent: true` on a shape** — marks the shape's *instances* as having no independent
+existence, so they are cascade-deleted when reached through a `contains` edge from a parent
+being deleted. Use it for structural nodes that are only ever owned (e.g. list cells, path
+nodes). It is **not** required for the replace/remove cleanup above — a `contains` edge alone
+is sufficient for the immediately-owned node; `dependent` extends the cascade to owned
+*descendants* several hops deep.
+
+```typescript
+@linkedShape({dependent: true})
+export class ListCell extends Shape { /* ... */ }
+```
+
+> Rule of thumb: put `contains` on the **property** that owns the value; put `dependent` on the
+> **shape** whose instances never stand alone. They are separate mechanisms — `contains` decides
+> *what to follow*, `dependent` decides *what may be deleted when reached*.
+
 ## Queries: Create, Select, Update, Delete
 
 Queries are expressed with the same Shape classes and compile to a query object that a store executes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_linked/core",
-  "version": "2.14.1",
+  "version": "2.14.2-next.20260709132623",
   "license": "MIT",
   "linkedPackage": true,
   "type": "module",