@ng-org/alien-deepsignals 0.1.2-alpha.6 → 0.1.2-alpha.7

package/README.md

@@ -4,20 +4,23 @@ Deep structural reactivity for plain objects / arrays / Sets built on top of `al
 
 Hooks for Svelte, Vue, and React.
 
-Core idea: wrap a data tree in a `Proxy` that lazily creates per-property signals the first time you read them. Deep mutations emit compact batched patch objects (in a JSON-patch inspired style) that you can track with `watch()`.
+Core idea: wrap a data tree in a `Proxy` that lazily creates per-property signals the first time you read them. Deep mutations emit batched patch objects (in a JSON-patch inspired style) that you can track with `watch()`.
 
 ## Features
 
 - Lazy: signals & child proxies created only when touched.
 - Deep: nested objects, arrays, Sets proxied.
-- Per-property signals: fine‑grained invalidation without traversal on each change.
 - Patch stream: microtask‑batched granular mutations (paths + op) for syncing external stores / framework adapters.
 - Getter => computed: property getters become derived (readonly) signals automatically.
-- Sets: structural `add/delete/clear` emit patches; object entries get synthetic stable ids.
-- Configurable synthetic IDs: custom property generator - the synthetic id is used in the paths of patches to identify objects in sets.
+- Sets: `add/delete/clear/...` methods emit patches; object entries get synthetic stable ids.
+- Configurable synthetic IDs: custom property generator - the synthetic ID is used in the paths of patches to identify objects in sets. By default attached as `@id` property.
 - Read-only properties: protect specific properties from modification.
 - Shallow escape hatch: wrap sub-objects with `shallow(obj)` to track only reference replacement.
 
+## Reference documentation
+
+[Reference documentation is available here on docs.nextgraph.org](https://docs.nextgraph.org/en/reference/alien-deepsignals/).
+
 ## Install
 
 ```bash
@@ -46,15 +49,37 @@ state.settings.add("beta");
 
 ## Frontend Hooks
 
-We provide hooks for Svelte 3/4, Svelte 5, Vue, and React so that you can use deepSignal objects in your frontend framework. Modifying the object within those components works as usual, just that the component will rerender automatically if the object changed (by an event in the component or a modification from elsewhere).
+We provide hooks for Svelte 3/4, Svelte 5, Vue, and React so that you can use deepSignal objects in your frontend framework. Modifying the object within those components works as usual, just that the component will rerender automatically when the object changed (by a modification in the component or a modification from elsewhere).
+
+Note that you can pass existing deepSignal objects to useDeepSignal (that you are using elsewhere too, for example as shared state) as well as plain JavaScript objects (which are then wrapped).
+
+You can (and are often advised to) use deepSignals as a shared state (and sub objects thereof) across components.
 
-Note that you can pass existing deepSignal objects (that you are using elsewhere too, for example as shared state) as well as plain JavaScript objects (which are then wrapped).
+### React
 
 ```tsx
 import { useDeepSignal } from "@ng-org/alien-deepsignals/react";
+import { DeepSignal } from "@ng-org/alien-deepsignals";
+import UserComponent from "./User.tsx";
+import type { User } from "./types.ts";
 
-const users = useDeepSignal([{ username: "Bob" }]);
-// Note: Instead of calling `setState`, you just need to modify a property. That will trigger the required re-render.
+function UserManager() {
+    const users: DeepSignal<User[]> = useDeepSignal([{ username: "Bob" }]);
+
+    return users.map((user) => <UserComponent key={user.id} user={user} />);
+}
+```
+
+In child component `User.tsx`:
+
+```tsx
+function UserComponent({ user }: { user: DeepSignal<User> }) {
+    // Modifications here will trigger a re-render in the parent component
+    // which updates this component.
+    // For performance reasons, you are advised to call `useDeepSignal`
+    // close to where its return value is used.
+    return <input type="text" value={user.name} />;
+}
 ```
 
 ### Vue
@@ -63,12 +88,12 @@ In component `UserManager.vue`
 
 ```vue
 <script setup lang="ts">
-import { DeepSignal } from "@ng-org/alien-deepsignals";
 import { useDeepSignal } from "@ng-org/alien-deepsignals/vue";
+import { DeepSignal } from "@ng-org/alien-deepsignals";
 import UserComponent from "./User.vue";
-import { User } from "./types.ts";
+import type { User } from "./types.ts";
 
-const users: DeepSignal<User> = useDeepSignal([{ username: "Bob", id: 1 }]);
+const users: DeepSignal<User[]> = useDeepSignal([{ username: "Bob", id: 1 }]);
 </script>
 
 <template>
@@ -80,14 +105,12 @@ In a child component, `User.vue`
 
 ```vue
 <script setup lang="ts">
-import { useDeepSignal } from "@ng-org/alien-deepsignals/vue";
-
 const props = defineProps<{
     user: DeepSignal<User>;
 }>();
 
 // The component only rerenders when user.name changes.
-// It behaves the same as an object called with `reactive()`
+// It behaves the same as an object wrapped with `reactive()`
 const user = props.user;
 </script>
 <template>
@@ -113,332 +136,9 @@ import { useDeepSignal } from "@ng-org/alien-deepsignals/svelte";
 const users = useDeepSignal([{ username: "Bob" }]);
 ```
 
-## Configuration options
-
-`deepSignal(obj, options?)` accepts an optional configuration object:
-
-```ts
-type DeepSignalOptions = {
-    propGenerator?: (props: {
-        path: (string | number)[];
-        inSet: boolean;
-        object: any;
-    }) => {
-        syntheticId?: string;
-        extraProps?: Record<string, unknown>;
-    };
-    syntheticIdPropertyName?: string;
-    readOnlyProps?: string[];
-};
-```
-
-### Property generator function
-
-The `propGenerator` function is called when a new object is added to the deep signal tree. It receives:
-
-- `path`: The path of the newly added object
-- `inSet`: Whether the object is being added to a Set (true) or not (false)
-- `object`: The newly added object itself
-
-It can return:
-
-- `syntheticId`: A custom identifier for the object (used in Set entry paths and optionally as a property)
-- `extraProps`: Additional properties to be added to the object (overwriting existing ones).
-
-```ts
-let counter = 0;
-const state = deepSignal(
-    { items: new Set() },
-    {
-        propGenerator: ({ path, inSet, object }) => ({
-            syntheticId: inSet
-                ? `urn:item:${++counter}`
-                : `urn:obj:${path.join("-")}`,
-            extraProps: { createdAt: new Date().toISOString() },
-        }),
-        syntheticIdPropertyName: "@id",
-    }
-);
-
-state.items.add({ name: "Item 1" }); // Gets @id: "urn:item:1" and createdAt property
-state.items.add({ name: "Item 2" }); // Gets @id: "urn:item:2"
-```
-
-### Synthetic ID property name
-
-When `syntheticIdPropertyName` is set (e.g., to `"@id"`), objects receive a readonly, enumerable property with the generated synthetic ID:
-
-```ts
-const state = deepSignal(
-    { data: {} },
-    {
-        propGenerator: ({ path, inSet, object }) => ({
-            syntheticId: `urn:uuid:${crypto.randomUUID()}`,
-        }),
-        syntheticIdPropertyName: "@id",
-    }
-);
-
-state.data.user = { name: "Ada" };
-console.log(state.data.user["@id"]); // e.g., "urn:uuid:550e8400-e29b-41d4-a716-446655440000"
-```
-
-### Read-only properties
-
-The `readOnlyProps` option lets you specify property names that cannot be modified:
-
-```ts
-const state = deepSignal(
-    { data: {} },
-    {
-        propGenerator: ({ path, inSet, object }) => ({
-            syntheticId: `urn:uuid:${crypto.randomUUID()}`,
-        }),
-        syntheticIdPropertyName: "@id",
-        readOnlyProps: ["@id", "@graph"],
-    }
-);
-
-state.data.user = { name: "Ada" };
-state.data.user["@id"] = "new-id"; // TypeError: Cannot modify readonly property '@id'
-```
-
-**Key behaviors:**
-
-- Synthetic IDs are assigned **before** the object is proxied, ensuring availability immediately
-- Properties specified in `readOnlyProps` are **readonly** and **enumerable**
-- Synthetic ID assignment emits a patch just like any other property
-- Objects with existing properties matching `syntheticIdPropertyName` keep their values (not overwritten)
-- Options propagate to all nested objects created after initialization
-- The `propGenerator` function is called for both Set entries (`inSet: true`) and regular objects (`inSet: false`)
-
-## Watching patches
-
-`watch(root, cb, options?)` observes a deepSignal root and invokes your callback with microtask‑batched mutation patches plus snapshots.
-
-```ts
-import { watch } from "alien-deepsignals";
-
-const stop = watch(state, ({ patches, oldValue, newValue }) => {
-    for (const p of patches) {
-        console.log(p.op, p.path.join("."), "value" in p ? p.value : p.type);
-    }
-});
-
-state.user.name = "Lin";
-state.items[0].qty = 3;
-await Promise.resolve(); // flush microtask
-stop();
-```
-
-## Computed (derived) values
-
-Use the `computed()` function to create lazy derived signals that automatically track their dependencies and recompute only when needed.
-
-```ts
-import { computed } from "@ng-org/alien-deepsignals";
-
-const state = deepSignal({
-    firstName: "Ada",
-    lastName: "Lovelace",
-    items: [1, 2, 3],
-});
-
-// Create a computed signal that derives from reactive state
-const fullNaAdd documentationme = computed(() => `${state.firstName} ${state.lastName}`);
-const itemCount = computed(() => state.items.length);
-
-console.log(fullName()); // "Ada Lovelace" - computes on first access
-console.log(itemCount()); // 3
-
-state.firstName = "Grace";
-console.log(fullName()); // "Grace Lovelace" - recomputes automatically
-```
-
-**Key benefits:**
-
-- **Lazy evaluation**: The computation runs only when you actually read the computed value. If you never access `fullName()`, the concatenation never happens—no wasted CPU cycles.
-- **Automatic caching**: Once computed, the result is cached until a dependency changes. Multiple reads return the cached value without re-running the getter.
-- **Fine-grained reactivity**: Only recomputes when its tracked dependencies change. Unrelated state mutations don't trigger unnecessary recalculation.
-- **Composable**: Computed signals can depend on other computed signals, forming efficient dependency chains.
-
-```ts
-// Expensive computation only runs when accessed and dependencies change
-const expensiveResult = computed(() => {
-    console.log("Computing...");
-    return state.items.reduce((sum, n) => sum + n * n, 0);
-});
-
-// No computation happens yet!
-state.items.push(4);
-// Still no computation...
-
-console.log(expensiveResult()); // "Computing..." + result
-console.log(expensiveResult()); // Cached, no log
-state.items.push(5);
-console.log(expensiveResult()); // "Computing..." again (dependency changed)
-```
-
-### Callback event shape
-
-```ts
-type WatchPatchEvent<T> = {
-    patches: DeepPatch[]; // empty only on immediate
-    oldValue: T | undefined; // deep-cloned snapshot before batch
-    newValue: T; // live proxy (already mutated)
-    registerCleanup(fn): void; // register disposer for next batch/stop
-    stopListening(): void; // unsubscribe
-};
-```
-
-### Options
-
-| Option      | Type    | Default | Description                                        |
-| ----------- | ------- | ------- | -------------------------------------------------- |
-| `immediate` | boolean | false   | Fire once right away with `patches: []`.           |
-| `once`      | boolean | false   | Auto stop after first callback (immediate counts). |
-
-`observe()` is an alias of `watch()`.
-
-## DeepPatch format
-
-```ts
-type DeepPatch = {
-    root: symbol; // stable id per deepSignal root
-    path: (string | number)[]; // root-relative segments
-} & (
-    | { op: "add"; type: "object" } // assigned object/array/Set entry object
-    | { op: "add"; value: string | number | boolean } // primitive write
-    | { op: "remove" } // deletion
-    | { op: "add"; type: "set"; value: [] } // Set.clear()
-    | {
-          op: "add";
-          type: "set";
-          value: (string | number | boolean)[] | { [id: string]: object };
-      } // (reserved)
-);
-```
-
-Notes:
-
-- `type:'object'` omits value to avoid deep cloning; read from `newValue` if needed.
-- `Set.add(entry)` emits object vs primitive form depending on entry type; path ends with synthetic id.
-- `Set.clear()` emits one structural patch and suppresses per‑entry removals in same batch.
-
-## Sets & synthetic ids
-
-Object entries inside Sets need a stable key for patch paths. The synthetic ID resolution follows this priority:
-
-1. Explicit custom ID via `setSetEntrySyntheticId(entry, 'myId')` (before `add`)
-2. Custom ID property specified by `syntheticIdPropertyName` option (e.g., `entry['@id']`)
-3. Auto-generated blank node ID (`_bN` format)
-
-### Working with Sets
-
-```ts
-import { addWithId, setSetEntrySyntheticId } from "@ng-org/alien-deepsignals";
-
-// Option 1: Use automatic ID generation via propGenerator
-const state = deepSignal(
-    { items: new Set() },
-    {
-        propGenerator: ({ path, inSet, object }) => ({
-            syntheticId: inSet ? `urn:uuid:${crypto.randomUUID()}` : undefined,
-        }),
-        syntheticIdPropertyName: "@id",
-    }
-);
-const item = { name: "Item 1" };
-state.items.add(item); // Automatically gets @id before being added
-console.log(item["@id"]); // e.g., "urn:uuid:550e8400-..."
-
-// Option 2: Manually set synthetic ID
-const obj = { value: 42 };
-setSetEntrySyntheticId(obj, "urn:custom:my-id");
-state.items.add(obj);
-
-// Option 3: Use convenience helper
-addWithId(state.items as any, { value: 99 }, "urn:item:special");
-
-// Option 4: Pre-assign property matching syntheticIdPropertyName
-const preTagged = { "@id": "urn:explicit:123", data: "..." };
-state.items.add(preTagged); // Uses "urn:explicit:123" as synthetic ID
-```
-
-### Set entry patches and paths
-
-When objects are added to Sets, their **synthetic ID becomes part of the patch path**. This allows patches to uniquely identify which Set entry is being mutated.
-
-```ts
-const state = deepSignal(
-    { s: new Set() },
-    {
-        propGenerator: ({ inSet }) => ({
-            syntheticId: inSet ? "urn:entry:set-entry-1" : undefined,
-        }),
-        syntheticIdPropertyName: "@id",
-    }
-);
-
-watch(state, ({ patches }) => {
-    console.log(JSON.stringify(patches));
-    // [
-    //   {"path":["s","urn:entry:set-entry-1"],"op":"add","type":"object"},
-    //   {"path":["s","urn:entry:set-entry-1","@id"],"op":"add","value":"urn:entry:set-entry-1"},
-    //   {"path":["s","urn:entry:set-entry-1","data"],"op":"add","value":"test"}
-    // ]
-});
-
-state.s.add({ data: "test" });
-```
-
-**Path structure explained:**
-
-- `["s", "urn:entry:set-entry-1"]` - The structural Set patch; the IRI identifies the entry
-- `["s", "urn:entry:set-entry-1", "@id"]` - Patch for the @id property assignment
-- `["s", "urn:entry:set-entry-1", "data"]` - Nested property patch; the IRI identifies which Set entry
-- The synthetic ID (the IRI) is stable across mutations, allowing tracking of the same object
+### Other Frameworks
 
-**Mutating nested properties:**
-
-```ts
-const state = deepSignal(
-    { users: new Set() },
-    {
-        propGenerator: ({ path, inSet }) => ({
-            syntheticId: inSet ? `urn:user:${crypto.randomUUID()}` : undefined,
-        }),
-        syntheticIdPropertyName: "@id",
-    }
-);
-const user = { name: "Ada", age: 30 };
-state.users.add(user); // Gets @id, e.g., "urn:user:550e8400-..."
-
-watch(state, ({ patches }) => {
-    console.log(JSON.stringify(patches));
-    // [{"path":["users","urn:user:550e8400-...","age"],"op":"add","value":31}]
-});
-
-// Later mutation: synthetic ID identifies which Set entry changed
-user.age = 31;
-```
-
-The path `["users", "urn:user:550e8400-...", "age"]` shows:
-
-1. `users` - the Set container
-2. `urn:user:550e8400-...` - the IRI identifying which object in the Set
-3. `age` - the property being mutated
-
-This structure enables precise tracking of nested changes within Set entries, critical for syncing state changes or implementing undo/redo.
-
-## Shallow
-
-Skip deep proxying of a subtree (only reference replacement tracked):
-
-```ts
-import { shallow } from "alien-deepsignals";
-state.config = shallow({ huge: { blob: true } });
-```
+Integrating new frontend frameworks is fairly easy. Get in touch if you are interested.
 
 ## License
 

package/dist/core.d.ts

@@ -1,16 +1,81 @@
-export { signal as alienSignal, computed as alienComputed, effect as alienEffect, } from "alien-signals";
+import { computed as alienComputed, signal as alienSignal_, effect as alienEffect } from "alien-signals";
 /**
  * Execute multiple signal writes in a single batched update frame.
  * All downstream computed/effect re-evaluations are deferred until the function exits.
  *
- * IMPORTANT: The callback MUST be synchronous. If it returns a Promise the batch will
+ * IMPORTANT: The callback must be synchronous. If it returns a Promise the batch will
  * still end immediately after scheduling, possibly causing mid-async flushes.
  *
  * @example
+ * ```ts
  * batch(() => {
  *   count(count() + 1);
  *   other(other() + 2);
  * }); // effects observing both run only once
+ * ```
  */
 export declare function batch<T>(fn: () => T): T;
+/**
+ * Re-export of alien-signals computed function.
+ *
+ * Use the `computed()` function to create lazy derived signals that automatically
+ * track their dependencies and recompute only when needed.
+ *
+ * Key features:
+ * - **Lazy evaluation**: The computation runs only when you actually read the computed value.
+ *     If you never access `fullName()`, the concatenation never happens—no wasted CPU cycles.
+ * - **Automatic caching**: Once computed, the result is cached until a dependency changes.
+ *     Multiple reads return the cached value without re-running the getter.
+ * - **Fine-grained reactivity**: Only recomputes when its tracked dependencies change.
+ *     Unrelated state mutations don't trigger unnecessary recalculation.
+ * - **Composable**: Computed signals can depend on other computed signals,
+ *     forming efficient dependency chains.
+ *
+ * @example
+ * ```ts
+ * import { computed } from "@ng-org/alien-deepsignals";
+ *
+ * const state = deepSignal({
+ *     firstName: "Ada",
+ *     lastName: "Lovelace",
+ *     items: [1, 2, 3],
+ * });
+ *
+ * // Create a computed signal that derives from reactive state
+ * const fullName = computed(() => `${state.firstName} ${state.lastName}`);
+ *
+ * console.log(fullName()); // "Ada Lovelace" - computes on first access
+ *
+ * state.firstName = "Grace";
+ * console.log(fullName()); // "Grace Lovelace" - recomputes automatically
+ *
+ * // Expensive computation only runs when accessed and dependencies change
+ * const expensiveResult = computed(() => {
+ *     console.log("Computing...");
+ *     return state.items.reduce((sum, n) => sum + n * n, 0);
+ * });
+ *
+ * // No computation happens yet!
+ * state.items.push(4);
+ * // Still no computation...
+ *
+ * console.log(expensiveResult()); // "Computing..." + result
+ * console.log(expensiveResult()); // Cached, no log
+ * state.items.push(5);
+ * console.log(expensiveResult()); // "Computing..." again (dependency changed)
+ *
+ * ```
+ */
+export declare const computed: typeof alienComputed;
+/**
+ * Re-export of alien-signals `signal` function which creates a basic signal.
+ */
+export declare const alienSignal: typeof alienSignal_;
+/**
+ * Re-export of alien-signals effect function.
+ *
+ * Callback reruns on every signal modification that is used within its callback.
+ *
+ */
+export declare const effect: typeof alienEffect;
 //# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAWA,OAAO,EACH,MAAM,IAAI,WAAW,EACrB,QAAQ,IAAI,aAAa,EACzB,MAAM,IAAI,WAAW,GACxB,MAAM,eAAe,CAAC;AAOvB;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAOvC"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAUA,OAAO,EAGH,QAAQ,IAAI,aAAa,EACzB,MAAM,IAAI,YAAY,EACtB,MAAM,IAAI,WAAW,EACxB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAOvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,QAAQ,sBAAgB,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,WAAW,qBAAe,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,MAAM,oBAAc,CAAC"}

package/dist/core.js

@@ -9,33 +9,93 @@
 // according to those terms.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.alienEffect = exports.alienComputed = exports.alienSignal = void 0;
+exports.effect = exports.alienSignal = exports.computed = void 0;
 exports.batch = batch;
-// Native re-exports for advanced usage.
-var alien_signals_1 = require("alien-signals");
-Object.defineProperty(exports, "alienSignal", { enumerable: true, get: function () { return alien_signals_1.signal; } });
-Object.defineProperty(exports, "alienComputed", { enumerable: true, get: function () { return alien_signals_1.computed; } });
-Object.defineProperty(exports, "alienEffect", { enumerable: true, get: function () { return alien_signals_1.effect; } });
-const alien_signals_2 = require("alien-signals");
+const alien_signals_1 = require("alien-signals");
 /**
  * Execute multiple signal writes in a single batched update frame.
  * All downstream computed/effect re-evaluations are deferred until the function exits.
  *
- * IMPORTANT: The callback MUST be synchronous. If it returns a Promise the batch will
+ * IMPORTANT: The callback must be synchronous. If it returns a Promise the batch will
  * still end immediately after scheduling, possibly causing mid-async flushes.
  *
  * @example
+ * ```ts
  * batch(() => {
  *   count(count() + 1);
  *   other(other() + 2);
  * }); // effects observing both run only once
+ * ```
  */
 function batch(fn) {
-    (0, alien_signals_2.startBatch)();
+    (0, alien_signals_1.startBatch)();
     try {
         return fn();
     }
     finally {
-        (0, alien_signals_2.endBatch)();
+        (0, alien_signals_1.endBatch)();
     }
 }
+/**
+ * Re-export of alien-signals computed function.
+ *
+ * Use the `computed()` function to create lazy derived signals that automatically
+ * track their dependencies and recompute only when needed.
+ *
+ * Key features:
+ * - **Lazy evaluation**: The computation runs only when you actually read the computed value.
+ *     If you never access `fullName()`, the concatenation never happens—no wasted CPU cycles.
+ * - **Automatic caching**: Once computed, the result is cached until a dependency changes.
+ *     Multiple reads return the cached value without re-running the getter.
+ * - **Fine-grained reactivity**: Only recomputes when its tracked dependencies change.
+ *     Unrelated state mutations don't trigger unnecessary recalculation.
+ * - **Composable**: Computed signals can depend on other computed signals,
+ *     forming efficient dependency chains.
+ *
+ * @example
+ * ```ts
+ * import { computed } from "@ng-org/alien-deepsignals";
+ *
+ * const state = deepSignal({
+ *     firstName: "Ada",
+ *     lastName: "Lovelace",
+ *     items: [1, 2, 3],
+ * });
+ *
+ * // Create a computed signal that derives from reactive state
+ * const fullName = computed(() => `${state.firstName} ${state.lastName}`);
+ *
+ * console.log(fullName()); // "Ada Lovelace" - computes on first access
+ *
+ * state.firstName = "Grace";
+ * console.log(fullName()); // "Grace Lovelace" - recomputes automatically
+ *
+ * // Expensive computation only runs when accessed and dependencies change
+ * const expensiveResult = computed(() => {
+ *     console.log("Computing...");
+ *     return state.items.reduce((sum, n) => sum + n * n, 0);
+ * });
+ *
+ * // No computation happens yet!
+ * state.items.push(4);
+ * // Still no computation...
+ *
+ * console.log(expensiveResult()); // "Computing..." + result
+ * console.log(expensiveResult()); // Cached, no log
+ * state.items.push(5);
+ * console.log(expensiveResult()); // "Computing..." again (dependency changed)
+ *
+ * ```
+ */
+exports.computed = alien_signals_1.computed;
+/**
+ * Re-export of alien-signals `signal` function which creates a basic signal.
+ */
+exports.alienSignal = alien_signals_1.signal;
+/**
+ * Re-export of alien-signals effect function.
+ *
+ * Callback reruns on every signal modification that is used within its callback.
+ *
+ */
+exports.effect = alien_signals_1.effect;

package/dist/deepSignal.d.ts

@@ -2,9 +2,14 @@ import { DeepPatchJITSubscriber, DeepPatchSubscriber, DeepSignal, DeepSignalOpti
 /** Runtime guard that checks whether a value is a deepSignal proxy. */
 export declare function isDeepSignal(value: unknown): value is DeepSignal<any>;
 /**
- * Create a deep reactive proxy for objects, arrays or Sets.
- * Returns the input itself, if it's a deepSignal already.
- * Throws if provided with unsupported input types.
+ * MAIN ENTRY POINT to create a deep reactive proxy for objects, arrays or Sets.
+ *
+ * If input is a deepSignal already and options are provided,
+ * the added subscriberFactories are joined with the existing ones
+ * and `replaceProxiesInBranchOnChange` is or-ed with the current value.
+ *
+ *
+ * @throws if provided with unsupported input types.
  */
 export declare function deepSignal<T extends object>(input: T, options?: DeepSignalOptions): DeepSignal<T>;
 /**
@@ -17,7 +22,14 @@ export declare function subscribeDeepMutations(root: object | symbol, cb: DeepPa
 export declare function getDeepSignalRootId(value: any): symbol | undefined;
 /** Retrieve the current patch version for a deepSignal root (if tracked). */
 export declare function getDeepSignalVersion(root: object | symbol): number | undefined;
-/** Mark an object so deepSignal skips proxying it (shallow boundary). */
+/** Mark an object so deepSignal skips proxying it (shallow boundary).
+ *
+ * @example
+ * ```ts
+ * import { shallow } from "alien-deepsignals";
+ * state.config = shallow({ huge: { blob: true } });
+ * ```
+ */
 export declare function shallow<T extends object>(obj: T): T;
 /** Force a specific synthetic ID to be used for a Set entry prior to insertion. */
 export declare function setSetEntrySyntheticId(obj: object, id: string | number): void;

package/dist/deepSignal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepSignal.d.ts","sourceRoot":"","sources":["../src/deepSignal.ts"],"names":[],"mappings":"AAWA,OAAO,EAGH,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EAOpB,MAAM,SAAS,CAAC;AA2wCjB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,GAAG,CAAC,CAErE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,iBAAiB,GAC5B,UAAU,CAAC,CAAC,CAAC,CAyCf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,EAAE,EAAE,mBAAmB,GAAG,sBAAsB,EAChD,gBAAgB,GAAE,OAAe,GAClC,MAAM,IAAI,CAoBZ;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,GAAG,MAAM,GACtB,MAAM,GAAG,SAAS,CAIpB;AAED,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAGnD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,QAItE;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAa1E;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,OAEhE"}
+{"version":3,"file":"deepSignal.d.ts","sourceRoot":"","sources":["../src/deepSignal.ts"],"names":[],"mappings":"AAWA,OAAO,EAGH,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EAMpB,MAAM,SAAS,CAAC;AAywCjB,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,GAAG,CAAC,CAErE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,iBAAiB,GAC5B,UAAU,CAAC,CAAC,CAAC,CAwCf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,EAAE,EAAE,mBAAmB,GAAG,sBAAsB,EAChD,gBAAgB,GAAE,OAAe,GAClC,MAAM,IAAI,CAoBZ;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,GAAG,MAAM,GACtB,MAAM,GAAG,SAAS,CAIpB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAGnD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,QAItE;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAa1E;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,OAEhE"}

package/dist/deepSignal.js

@@ -146,7 +146,7 @@ function ensureProxiedGetter(signals, target, key, receiver) {
         typeof Object.getOwnPropertyDescriptor(target, key)?.get === "function" // If we have a getter?
     ) {
         signals.set(key, {
-            alienSignal: (0, core_1.alienComputed)(() => Reflect.get(target, key, receiver)),
+            alienSignal: (0, core_1.computed)(() => Reflect.get(target, key, receiver)),
             externalSubscribers: new Map(),
         });
     }
@@ -382,8 +382,8 @@ function ensureSetInfo(meta) {
  * Assign (or reuse) a synthetic identifier for a Set entry, respecting user options:
  * - Use user-provided propGenerator for synthetic ids and add add returned extra properties
  * - Check if the object has a property of `syntheticIdPropertyName` (default `@id`)
- * - Use a blank node id as a fallback.
- * - Add object and id to `idForObject` and `objectForId` maps.
+ * - Use a blank node ID as a fallback.
+ * - Add object and ID to `idForObject` and `objectForId` maps.
  */
 function assignSyntheticId(meta, entry, path, inSet) {
     const rawEntry = entry?.[RAW_KEY] ?? entry;
@@ -1013,15 +1013,19 @@ function isDeepSignal(value) {
     return !!value?.[RAW_KEY];
 }
 /**
- * Create a deep reactive proxy for objects, arrays or Sets.
- * Returns the input itself, if it's a deepSignal already.
- * Throws if provided with unsupported input types.
+ * MAIN ENTRY POINT to create a deep reactive proxy for objects, arrays or Sets.
+ *
+ * If input is a deepSignal already and options are provided,
+ * the added subscriberFactories are joined with the existing ones
+ * and `replaceProxiesInBranchOnChange` is or-ed with the current value.
+ *
+ *
+ * @throws if provided with unsupported input types.
  */
 function deepSignal(input, options) {
     // Is the input already a signal?
     if (isDeepSignal(input)) {
         // Add possibly new external subscribers to existing ones.
-        // TODO: Document this behavior.
         const meta = rawToMeta.get(input[RAW_KEY]);
         meta.options.subscriberFactories =
             meta.options.subscriberFactories.union(options?.subscriberFactories ?? new Set());
@@ -1088,7 +1092,14 @@ function getDeepSignalVersion(root) {
         return undefined;
     return rootStates.get(rootId)?.version;
 }
-/** Mark an object so deepSignal skips proxying it (shallow boundary). */
+/** Mark an object so deepSignal skips proxying it (shallow boundary).
+ *
+ * @example
+ * ```ts
+ * import { shallow } from "alien-deepsignals";
+ * state.config = shallow({ huge: { blob: true } });
+ * ```
+ */
 function shallow(obj) {
     ignored.add(obj);
     return obj;

package/dist/hooks/react/useDeepSignal.d.ts

@@ -6,7 +6,7 @@ import { DeepSignalOptions } from "../..";
  * is rerendered as well.
  *
  * @param object The object that should become reactive
- * @param deepSignalOptions When the object is not a deepSignal already, options passed to `deepSignal`.
+ * @param options When the object is not a deepSignal already, options passed to {@link deepSignal}.
  * @returns The deepSignal object of the object param. On every change, the returned object will change (a new no-op proxy is created) around the deepSignal object.
  */
 declare const useSignal: <T extends object>(object: T, deepSignalOptions?: DeepSignalOptions) => import("../..").DeepSignal<T>;

package/dist/hooks/react/useDeepSignal.js

@@ -19,7 +19,7 @@ const __1 = require("../..");
  * is rerendered as well.
  *
  * @param object The object that should become reactive
- * @param deepSignalOptions When the object is not a deepSignal already, options passed to `deepSignal`.
+ * @param options When the object is not a deepSignal already, options passed to {@link deepSignal}.
  * @returns The deepSignal object of the object param. On every change, the returned object will change (a new no-op proxy is created) around the deepSignal object.
  */
 const useSignal = (object, deepSignalOptions) => {

package/dist/hooks/svelte/useDeepSignal.svelte.d.ts

@@ -7,9 +7,9 @@ import { DeepSignalOptions, DeepSignal } from "../../index";
  * is rerendered as well.
  *
  * @param object The object that should become reactive
- * @param deepSignalObjects When the object is not a deepSignal already, options passed to `deepSignal`.
+ * @param options Options passed to {@link deepSignal}.
  * @returns A rune for using the deepSignal object in svelte.
  */
-export declare function useDeepSignal<T extends object>(object: T, options?: DeepSignalOptions): T extends DeepSignal<any> ? T : DeepSignal<T> | undefined;
+export declare function useDeepSignal<T extends object>(object: T, options?: DeepSignalOptions): T extends DeepSignal<any> ? T : DeepSignal<T>;
 export default useDeepSignal;
 //# sourceMappingURL=useDeepSignal.svelte.d.ts.map

package/dist/hooks/svelte/useDeepSignal.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDeepSignal.svelte.d.ts","sourceRoot":"","sources":["../../../src/hooks/svelte/useDeepSignal.svelte.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,iBAAiB,EAAc,UAAU,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC1C,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,iBAAiB,GAab,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAC1E;AAyBD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"useDeepSignal.svelte.d.ts","sourceRoot":"","sources":["../../../src/hooks/svelte/useDeepSignal.svelte.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,iBAAiB,EAAc,UAAU,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC1C,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,iBAAiB,GAab,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAC9D;AAyBD,eAAe,aAAa,CAAC"}

package/dist/hooks/svelte/useDeepSignal.svelte.js

@@ -20,7 +20,7 @@ const index_1 = require("../../index");
  * is rerendered as well.
  *
  * @param object The object that should become reactive
- * @param deepSignalObjects When the object is not a deepSignal already, options passed to `deepSignal`.
+ * @param options Options passed to {@link deepSignal}.
  * @returns A rune for using the deepSignal object in svelte.
  */
 function useDeepSignal(object, options) {

package/dist/hooks/svelte4/useDeepSignal.svelte.d.ts

@@ -1,5 +1,5 @@
 import { type Readable } from "svelte/store";
-import { DeepSignalOptions, RevertDeepSignal } from "../../index";
+import { DeepSignalOptions, UnwrapDeepSignal } from "../../index";
 /** Base result contract for a deepSignal-backed Svelte integration. */
 export interface UseDeepSignalResult<T> extends Readable<T> {
     /** Derive a nested selection; re-runs when the underlying tree version increments. */
@@ -12,16 +12,16 @@ export interface UseDeepSignalResult<T> extends Readable<T> {
     update(updater: (current: T) => T | void): void;
 }
 /**
- * Create a rune from a deepSignal object (creates one if it is just a regular object).
+ * Create a store from a deepSignal object (creates one if it is just a regular object).
  *
  * Modifications to the returned deepSignal object cause an immediate rerender.
  * If modifications of the object are made from somewhere else, the component
  * is rerendered as well.
  *
  * @param object The object that should become reactive
- * @param deepSignalObjects When the object is not a deepSignal already, options passed to `deepSignal`.
- * @returns A rune for using the deepSignal object in svelte.
+ * @param options Options passed to {@link deepSignal}.
+ * @returns A store for using the deepSignal object in svelte.
  */
-export declare function useDeepSignal<T extends object>(object: T | Promise<T>, options?: DeepSignalOptions): UseDeepSignalResult<RevertDeepSignal<T>>;
+export declare function useDeepSignal<T extends object>(object: T | Promise<T>, options?: DeepSignalOptions): UseDeepSignalResult<UnwrapDeepSignal<T>>;
 export default useDeepSignal;
 //# sourceMappingURL=useDeepSignal.svelte.d.ts.map

package/dist/hooks/svelte4/useDeepSignal.svelte.js

@@ -15,15 +15,15 @@ const svelte_1 = require("svelte");
 const index_1 = require("../../index");
 const deepSignal_1 = require("../../deepSignal");
 /**
- * Create a rune from a deepSignal object (creates one if it is just a regular object).
+ * Create a store from a deepSignal object (creates one if it is just a regular object).
  *
  * Modifications to the returned deepSignal object cause an immediate rerender.
  * If modifications of the object are made from somewhere else, the component
  * is rerendered as well.
  *
  * @param object The object that should become reactive
- * @param deepSignalObjects When the object is not a deepSignal already, options passed to `deepSignal`.
- * @returns A rune for using the deepSignal object in svelte.
+ * @param options Options passed to {@link deepSignal}.
+ * @returns A store for using the deepSignal object in svelte.
  */
 function useDeepSignal(object, options) {
     const version = (0, store_1.writable)(-1);

package/dist/hooks/vue/useDeepSignal.d.ts

@@ -7,7 +7,7 @@ import { DeepSignal, DeepSignalOptions } from "../../";
  * is rerendered as well.
  *
  * @param object The object that should become reactive (can be a ref or getter)
- * @param options When the object is not a deepSignal already, options passed to `deepSignal`.
+ * @param options Options passed to {@link deepSignal}.
  * @returns The deepSignal object of the object param.
  *
  */

package/dist/hooks/vue/useDeepSignal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDeepSignal.d.ts","sourceRoot":"","sources":["../../../src/hooks/vue/useDeepSignal.ts"],"names":[],"mappings":"AAUA,OAAO,EAGH,KAAK,gBAAgB,EAIxB,MAAM,KAAK,CAAC;AAEb,OAAO,EAAE,UAAU,EAAc,iBAAiB,EAAS,MAAM,QAAQ,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC1C,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,iBAAiB,GAC5B,UAAU,CAAC,CAAC,CAAC,CAaf;AAkBD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"useDeepSignal.d.ts","sourceRoot":"","sources":["../../../src/hooks/vue/useDeepSignal.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,gBAAgB,EAAsB,MAAM,KAAK,CAAC;AAEhE,OAAO,EAAE,UAAU,EAAc,iBAAiB,EAAS,MAAM,QAAQ,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC1C,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,iBAAiB,GAC5B,UAAU,CAAC,CAAC,CAAC,CAaf;AAkBD,eAAe,aAAa,CAAC"}

package/dist/hooks/vue/useDeepSignal.js

@@ -19,7 +19,7 @@ const __1 = require("../../");
  * is rerendered as well.
  *
  * @param object The object that should become reactive (can be a ref or getter)
- * @param options When the object is not a deepSignal already, options passed to `deepSignal`.
+ * @param options Options passed to {@link deepSignal}.
  * @returns The deepSignal object of the object param.
  *
  */

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 export { addWithId, deepSignal, getRaw, isDeepSignal, shallow, subscribeDeepMutations, } from "./deepSignal";
 export * from "./core";
 export * from "./watch";
-export * from "./effect";
 export * from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,SAAS,EACT,UAAU,EACV,MAAM,EACN,YAAY,EACZ,OAAO,EACP,sBAAsB,GACzB,MAAM,cAAc,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,SAAS,EACT,UAAU,EACV,MAAM,EACN,YAAY,EACZ,OAAO,EACP,sBAAsB,GACzB,MAAM,cAAc,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -24,5 +24,4 @@ Object.defineProperty(exports, "shallow", { enumerable: true, get: function () {
 Object.defineProperty(exports, "subscribeDeepMutations", { enumerable: true, get: function () { return deepSignal_1.subscribeDeepMutations; } });
 __exportStar(require("./core"), exports);
 __exportStar(require("./watch"), exports);
-__exportStar(require("./effect"), exports);
 __exportStar(require("./types"), exports);

package/dist/test/frontend/utils/mockData.js

@@ -15,12 +15,12 @@ exports.buildInitialState = buildInitialState;
 const buildDefaultObjectSetEntries = () => {
     const baseEntries = [
         {
-            "@id": "urn:object:alpha",
+            "@id": "did:ng:x:alpha",
             label: "Alpha",
             count: 1,
         },
         {
-            "@id": "urn:object:beta",
+            "@id": "did:ng:x:beta",
             label: "Beta",
             count: 3,
         },
@@ -28,7 +28,7 @@ const buildDefaultObjectSetEntries = () => {
     const extraEntries = Array.from({ length: 2 }, (_, index) => {
         const idNumber = (index + 1).toString().padStart(3, "0");
         return {
-            "@id": `urn:object:item-${idNumber}`,
+            "@id": `did:ng:x:item-${idNumber}`,
             label: `Item ${idNumber}`,
             count: 5 + index,
         };

package/dist/test/lib/watch.test.js

@@ -12,7 +12,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
 const __1 = require("../../");
 const watch_1 = require("../../watch");
-const effect_1 = require("../../effect");
 const deepSignal_1 = require("../../deepSignal");
 (0, vitest_1.describe)("watch", () => {
     (0, vitest_1.it)("watch immediate", () => {
@@ -84,15 +83,6 @@ const deepSignal_1 = require("../../deepSignal");
         (0, vitest_1.expect)(versions.length).toBe(1);
         (0, vitest_1.expect)(versions[0]).toBeGreaterThan(0);
     });
-    (0, vitest_1.it)("effect runs and cleans up", () => {
-        const calls = [];
-        const dispose = (0, effect_1.effect)((registerCleanup) => {
-            calls.push("run");
-            registerCleanup?.(() => calls.push("cleanup"));
-        });
-        dispose();
-        (0, vitest_1.expect)(calls).toEqual(["run", "cleanup"]);
-    });
 });
 (0, vitest_1.describe)("watch (patch mode)", () => {
     (0, vitest_1.it)("emits set patches with correct paths and batching", async () => {

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { alienComputed, alienSignal } from "./core";
+import { computed, alienSignal } from "./core";
 /** Deep mutation emitted from a deepSignal root. */
 export type DeepPatch = {
     path: (string | number)[];
@@ -16,20 +16,29 @@ export interface DeepPatchBatch {
     version: number;
     patches: DeepPatch[];
 }
-/** Batched patch payload for justInTime listeners. */
+/** @ignore Batched patch payload for justInTime listeners. */
 export interface DeepPatchJITBatch {
     patches: DeepPatch[];
 }
+/** @ignore */
 export type DeepPatchSubscriber = (batch: DeepPatchBatch) => void;
+/** @ignore */
 export type DeepPatchJITSubscriber = (batch: DeepPatchJITBatch) => void;
-/** Options to pass to {@link deepSignal} */
+/**
+ * Options to pass to {@link deepSignal}
+ * @internal
+ */
 export interface DeepSignalOptions {
-    /** An optional function that is called when new objects are attached and that may return additional properties to be attached. */
+    /**
+     * An optional function that is called when new objects are attached and
+     * that may return additional properties to be attached.
+     */
     propGenerator?: DeepSignalPropGenFn;
     /**
      * The property name which should be used as an object identifier in sets.
      * You will see it when patches are generated with a path to an object in a set.
      * The `syntheticId` will be a patch element then.
+     * Objects with existing properties matching `syntheticIdPropertyName` keep their values (not overwritten).
      */
     syntheticIdPropertyName?: string;
     /**
@@ -50,14 +59,49 @@ export type ExternalSubscriberFactory<T = any> = () => {
     onGet: () => void;
     onSet: (newVal: T) => void;
 };
+/**
+ * @internal
+ *
+ * The `propGenerator` function is called when a new object is added to the deep signal tree.
+ * @example
+ * ```ts
+ * let counter = 0;
+ * const state = deepSignal(
+ *     { items: new Set() },
+ *     {
+ *         propGenerator: ({ path, inSet, object }) => ({
+ *             syntheticId: inSet
+ *                 ? `urn:item:${++counter}`
+ *                 : `urn:obj:${path.join("-")}`,
+ *             extraProps: { createdAt: new Date().toISOString() },
+ *         }),
+ *         syntheticIdPropertyName: "@id",
+ *     }
+ * );
+ *
+ * state.items.add({ name: "Item 1" });
+ * // Attaches `{ name: "Item 1", `@id`: "urn:item:1", createdAt: <current date>`
+ *
+ * state.foo = {bar: 42};
+ * // Attaches `{bar: 42, "@id": "urn:obj:foo", createdAt: <current date>}`
+ * ```
+ */
 export type DeepSignalPropGenFn = (props: {
+    /**
+     * The path of the newly added object.
+     */
     path: (string | number)[];
+    /** Whether the object is being added to a Set (true) or not (false) */
     inSet: boolean;
+    /** The newly added object itself */
     object: any;
 }) => {
+    /** A custom identifier for the object (used in Set entry paths and optionally as a property). */
     syntheticId?: string | number;
+    /** Additional properties to be added to the object (overwriting existing ones). */
     extraProps?: Record<string, unknown>;
 };
+/**@ignore*/
 export interface ProxyMeta {
     raw: object;
     parent?: ProxyMeta;
@@ -67,10 +111,12 @@ export interface ProxyMeta {
     options: DeepSignalOptions;
     setInfo?: SetMeta;
 }
+/** @hidden */
 export interface SetMeta {
     idForObject: WeakMap<object, string>;
     objectForId: Map<string, object>;
 }
+/**@ignore*/
 export interface RootState {
     options?: DeepSignalOptions;
     version: number;
@@ -78,12 +124,15 @@ export interface RootState {
     listeners: Set<DeepPatchSubscriber>;
     pendingPatches: DeepPatch[];
 }
+/** @ignore */
 export type WritableSignal<T = any> = ReturnType<typeof alienSignal<T>>;
-export type ComputedSignal<T = any> = ReturnType<typeof alienComputed<T>>;
+export type ComputedSignal<T = any> = ReturnType<typeof computed<T>>;
 export type SignalLike<T = any> = WritableSignal<T> | ComputedSignal<T>;
-/** Raw and meta key. */
+/** @ignore Raw and meta key. */
 export type DeepSignalObjectProps<T> = {
+    /** The original raw object. */
     __raw__: T;
+    /** @ignore meta information */
     __meta__: ProxyMeta;
 };
 /** Utility functions for sets. */
@@ -99,13 +148,16 @@ export type DeepSignalSetProps<T> = {
     /**
      * Retrieve an object from the Set by its `@graph` and `@id`.
      *
-     * @param graphIri - The `@graph` IRI of the object.
+     * @param graphIri - The `@graph` NURI of the object.
      * @param subjectIri - The `@subject` IRI of the object.
      * @returns The proxied entry if found, undefined otherwise.
      */
     getBy(graphIri: string, subjectIri: string): DeepSignal<T> | undefined;
 };
-/** Reactive Set wrapper that accepts raw or proxied entries. */
+/**
+ * Type alias for `DeepSignal<Set<T>>` and reactive Set wrapper that accepts raw or proxied entries.
+ * Additionally it is decorated with {@link DeepSignalSetProps}.
+ */
 export interface DeepSignalSet<T> extends Set<DeepSignal<T>>, DeepSignalObjectProps<Set<T>>, SetIterator<DeepSignal<T>>, DeepSignalSetProps<T> {
     add(value: T | DeepSignal<T>): this;
     delete(value: T | DeepSignal<T>): boolean;
@@ -114,16 +166,15 @@ export interface DeepSignalSet<T> extends Set<DeepSignal<T>>, DeepSignalObjectPr
     forEach(callbackfn: (value: DeepSignal<T>, index: number) => void, thisArg?: any): void;
 }
 /**
- * The object returned by the @see deepSignal function.
- * It is decorated with utility functions for sets and a
- * `__raw__` prop to get the underlying non-reactive object
- * and `__meta__` prop, to get the internal metadata.
+ * The object returned by the {@link deepSignal} function.
+ * It is decorated with utility functions for sets, see {@link DeepSignalSetProps}
+ * and a `__raw__` prop to get the underlying non-reactive object.
  */
 export type DeepSignal<T> = T extends Function ? T : T extends string | number | boolean ? T : T extends DeepSignalObjectProps<any> | DeepSignalObjectProps<any>[] ? T : T extends Array<infer I> ? DeepSignal<I>[] : T extends Set<infer S> ? DeepSignalSet<S> : T extends object ? DeepSignalObject<T> : T;
 export type DeepSignalObject<T extends object> = {
     [K in keyof T]: DeepSignal<T[K]>;
 };
-export type RevertDeepSignal<T> = T extends DeepSignal<infer S> ? S : T;
+export type UnwrapDeepSignal<T> = T extends DeepSignal<infer S> ? S : T;
 /** Union allowing a plain value or a writable signal wrapping that value. */
 export type MaybeSignal<T = any> = T | ReturnType<typeof alienSignal>;
 /** Union allowing value, writable signal, computed signal or plain getter function. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/watch.d.ts

@@ -25,11 +25,37 @@ export type WatchPatchCallback<T extends object> = (event: WatchPatchEvent<T>) =
 /**
  * Watch for changes to a deepSignal.
  *
- * Whenever a change is made, `callback` with the patches describing the change and the current value.
+ * Whenever a change is made, `callback` is called with the patches describing the change and the new value.
  * If you set `triggerInstantly`, the callback is called on every property change.
  * If not, all changes are aggregated and `callback` is called in a microtask when
  * the current task finishes, e.g. `await` is called (meaning it supports batching).
  *
+ * When objects are added to Sets, their **synthetic ID (usually `@id`) becomes part of the patch path**. This allows patches to uniquely identify which Set entry is being mutated.
+ *
+ * ```ts
+ * const state = deepSignal(
+ *     { s: new Set() },
+ *     { ...}
+ * );
+ *
+ * watch(state, ({ patches }) => {
+ *     console.log(JSON.stringify(patches));
+ * });
+ *
+ * state.s.add({ data: "test" });
+ * // Will log:
+ * // [
+ * //   {"path":["s","did:ng:o:123"],"op":"add","type":"object"},
+ * //   {"path":["s","did:ng:o:123","@id"],"op":"add","value":"did:ng:o:123"},
+ * //   {"path":["s","did:ng:o:123","data"],"op":"add","value":"test"}
+ * // ]
+ *
+ * state.s.getById("did:ng:o:123")!.data = "new value"
+ * // Will log:
+ * // [
+ * //   {"path":["s","did:ng:o:123","data"],"op":"add","value":"new value"}
+ * // ]
+ * ```
  */
 export declare function watch<T extends object>(source: DeepSignalSet<T> | DeepSignalObject<T> | DeepSignal<T>, callback: WatchPatchCallback<T>, options?: WatchOptions): {
     stopListening: () => void;

package/dist/watch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAgBA,OAAO,EACH,SAAS,EAET,UAAU,EACV,gBAAgB,EAChB,aAAa,EAChB,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAE9D,MAAM,WAAW,YAAY;IACzB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM;IAC7C,uBAAuB;IACvB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,IAAI,CAC/C,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KACxB,IAAI,CAAC;AAEV;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAClC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAC9D,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC/B,OAAO,GAAE,YAAiB;;;EAiE7B"}
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAgBA,OAAO,EACH,SAAS,EAET,UAAU,EACV,gBAAgB,EAChB,aAAa,EAChB,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAE9D,MAAM,WAAW,YAAY;IACzB,8FAA8F;IAC9F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM;IAC7C,uBAAuB;IACvB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,IAAI,CAC/C,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KACxB,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAClC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAC9D,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC/B,OAAO,GAAE,YAAiB;;;EAiE7B"}

package/dist/watch.js

@@ -14,11 +14,37 @@ const deepSignal_1 = require("./deepSignal");
 /**
  * Watch for changes to a deepSignal.
  *
- * Whenever a change is made, `callback` with the patches describing the change and the current value.
+ * Whenever a change is made, `callback` is called with the patches describing the change and the new value.
  * If you set `triggerInstantly`, the callback is called on every property change.
  * If not, all changes are aggregated and `callback` is called in a microtask when
  * the current task finishes, e.g. `await` is called (meaning it supports batching).
  *
+ * When objects are added to Sets, their **synthetic ID (usually `@id`) becomes part of the patch path**. This allows patches to uniquely identify which Set entry is being mutated.
+ *
+ * ```ts
+ * const state = deepSignal(
+ *     { s: new Set() },
+ *     { ...}
+ * );
+ *
+ * watch(state, ({ patches }) => {
+ *     console.log(JSON.stringify(patches));
+ * });
+ *
+ * state.s.add({ data: "test" });
+ * // Will log:
+ * // [
+ * //   {"path":["s","did:ng:o:123"],"op":"add","type":"object"},
+ * //   {"path":["s","did:ng:o:123","@id"],"op":"add","value":"did:ng:o:123"},
+ * //   {"path":["s","did:ng:o:123","data"],"op":"add","value":"test"}
+ * // ]
+ *
+ * state.s.getById("did:ng:o:123")!.data = "new value"
+ * // Will log:
+ * // [
+ * //   {"path":["s","did:ng:o:123","data"],"op":"add","value":"new value"}
+ * // ]
+ * ```
  */
 function watch(source, callback, options = {}) {
     if (!(0, deepSignal_1.isDeepSignal)(source)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-org/alien-deepsignals",
-  "version": "0.1.2-alpha.6",
+  "version": "0.1.2-alpha.7",
   "private": false,
   "authors": [
     "Laurin Weger",