@yiin/reactive-proxy-state 1.0.11 → 1.0.13

package/README.md

@@ -18,96 +18,66 @@ bun add @yiin/reactive-proxy-state
 # or yarn add @yiin/reactive-proxy-state
 ```
 
-## Core Concepts
+## Quick Start
 
-1.  **Reactive State**: Create reactive versions of your objects using `reactive`. Any mutations to these wrapped objects will be tracked.
-2.  **Dependency Tracking**: When code inside a `watchEffect` reads a property of a reactive object, a dependency is established.
-3.  **Effect Triggering**: When a tracked property is mutated, any dependent effects (`watchEffect` or `watch` callbacks) are re-run **synchronously**.
+The most common use case is creating reactive state for local applications:
 
-## State Synchronization with `updateState`
+```typescript
+import { reactive, watchEffect } from "@yiin/reactive-proxy-state";
 
-A key feature is `updateState`, which allows applying changes from a plain JavaScript object (often received from serialization) onto an existing reactive state object. It intelligently updates properties, adds/removes array elements, and modifies Maps/Sets to match the target structure, triggering reactive effects only where necessary.
+// Create reactive state
+const state = reactive({
+  count: 0,
+  user: { name: "Alice" },
+  items: ["apple", "banana"],
+});
 
-This is typically used with the `emit` callback of `reactive` for state synchronization:
+// Watch for changes
+watchEffect(() => {
+  console.log(`Count: ${state.count}, User: ${state.user.name}`);
+});
+// Output: Count: 0, User: Alice
 
-```typescript
-import { reactive, updateState, watchEffect } from '@yiin/reactive-proxy-state';
+// Mutations automatically trigger effects
+state.count++;
+// Output: Count: 1, User: Alice
 
-// Assume these functions exist:
-// - getInitialStateFromServer(): Fetches the initial state snapshot.
-// - sendEventToClient(event): Sends a state change event to the client.
-// - listenForServerEvents(callback): Sets up a listener for events from the server.
+state.user.name = "Bob";
+// Output: Count: 1, User: Bob
 
-// --- Source State (e.g., Server) ---
-const sourceData = {
-  counter: 0,
-  user: { name: 'Alice' },
-  items: ['a']
-};
+state.items.push("orange");
+// Arrays, Maps, and Sets are also reactive
+```
 
-// 1. Server creates reactive state & emits deltas via sendEventToClient
-const sourceState = reactive(sourceData, sendEventToClient);
+## Core Concepts
 
+1.  **Reactive State**: Create reactive versions of your objects using `reactive`. Any mutations to these wrapped objects will be tracked.
+2.  **Dependency Tracking**: When code inside a `watchEffect` reads a property of a reactive object, a dependency is established.
+3.  **Effect Triggering**: When a tracked property is mutated, any dependent effects (`watchEffect` or `watch` callbacks) are re-run **synchronously**.
 
-// --- Client Initialization & Sync ---
-// 2. Client creates its reactive state holder *before* data arrives
-const targetState = reactive({});
-console.log('Client: Initial empty target state created:', targetState);
+## Advanced: State Synchronization
 
-// 3. Client watches its local state for changes (e.g., for UI updates)
-watchEffect(() => {
-  console.log('Client: Target state updated:', targetState);
-});
-// Initial output: Client: Target state updated: {}
-
-// 4. Client fetches the initial state snapshot
-const initialSnapshot = getInitialStateFromServer(); // Assume fetches { counter: 0, ... }
-console.log('\n--- Client Received Initial Snapshot ---');
-console.log(initialSnapshot);
-
-// 5. Client applies the initial snapshot using a 'replace' action
-// (Requires updateState implementation to support action: 'replace')
-updateState(targetState, {
-  action: 'replace', 
-  path: [], // Apply to the root
-  newValue: initialSnapshot
-});
-// Output after 'replace': 
-// Client: Target state updated: { counter: 0, user: { name: 'Alice' }, items: [ 'a' ] }
-
-// 6. Client starts listening for subsequent delta events from the server
-listenForServerEvents((event) => {
-  console.log(`Client: Received delta event <- Server:`, event);
-  // Apply the delta event normally
-  updateState(targetState, event);
+For advanced use cases like server-client synchronization, you can track state changes and apply them elsewhere:
+
+```typescript
+import { reactive, updateState } from "@yiin/reactive-proxy-state";
+
+// Server: Track changes and send them to clients
+const serverState = reactive({ count: 0 }, (event) => {
+  // Send event to all connected clients
+  broadcastToClients(event);
 });
 
+// Client: Apply changes received from server
+const clientState = reactive({});
+
+// When client receives events from server
+onServerEvent((event) => {
+  updateState(clientState, event);
+});
 
-// --- Subsequent Server Modifications ---
-// 7. Server state is modified *after* the client has initialized
-console.log('\n--- Server Modifying State (Post-Init) ---');
-sourceState.counter++;
-// Output: (sendEventToClient called with { action: 'set', path: [ 'counter' ], ... })
-sourceState.user.name = 'Charlie';
-// Output: (sendEventToClient called with { action: 'set', path: [ 'user', 'name' ], ... })
-sourceState.items.push('b');
-// Output: (sendEventToClient called with { action: 'array-push', path: [ 'items' ], ... })
-
-// --- Delta Events arrive and are processed asynchronously by the client ---
-
-// Example Console Output Order (assuming async processing):
-// Client: Initial empty target state created: {}
-// Client: Target state updated: {}
-// --- Client Received Initial Snapshot ---
-// { counter: 0, user: { name: 'Alice' }, items: ['a'] }
-// Client: Target state updated: { counter: 0, user: { name: 'Alice' }, items: [ 'a' ] } // From 'replace'
-// --- Server Modifying State (Post-Init) ---
-// Client: Received delta event <- Server: { action: 'set', path: [ 'counter' ], oldValue: 0, newValue: 1 }
-// Client: Target state updated: { counter: 1, user: { name: 'Alice' }, items: [ 'a' ] }
-// Client: Received delta event <- Server: { action: 'set', path: [ 'user', 'name' ], oldValue: 'Alice', newValue: 'Charlie' }
-// Client: Target state updated: { counter: 1, user: { name: 'Charlie' }, items: [ 'a' ] }
-// Client: Received delta event <- Server: { action: 'array-push', path: [ 'items' ], key: 1, items: [ 'b' ] }
-// Client: Target state updated: { counter: 1, user: { name: 'Charlie' }, items: [ 'a', 'b' ] }
+// Now both states stay in sync
+serverState.count = 5; // Automatically synced to all clients
 ```
 
 See the [`updateState` documentation](./docs/api/update-state.md) and [`reactive` documentation](./docs/api/reactive.md) for more details on event emission and application.
@@ -119,21 +89,21 @@ See the [`updateState` documentation](./docs/api/update-state.md) and [`reactive
 Creates a reactive proxy for the given object, Array, Map, or Set. Nested objects/collections are also recursively wrapped.
 
 ```typescript
-import { reactive } from '@yiin/reactive-proxy-state';
+import { reactive } from "@yiin/reactive-proxy-state";
 
 const state = reactive({
   count: 0,
-  user: { name: 'Alice' },
-  items: ['a', 'b'],
-  settings: new Map([['theme', 'dark']]),
-  ids: new Set([1, 2])
+  user: { name: "Alice" },
+  items: ["a", "b"],
+  settings: new Map([["theme", "dark"]]),
+  ids: new Set([1, 2]),
 });
 
 // Mutations to 'state' and its nested properties/elements will be tracked.
 state.count++;
-state.user.name = 'Bob';
-state.items.push('c');
-state.settings.set('theme', 'light');
+state.user.name = "Bob";
+state.items.push("c");
+state.settings.set("theme", "light");
 state.ids.add(3);
 ```
 
@@ -141,17 +111,17 @@ state.ids.add(3);
 
 Creates a reactive "reference" object for any value type (primitive or object). The value is accessed and mutated through the `.value` property. Reactivity is tracked on the `.value` property itself.
 
-**Note:** If a plain object is passed to `ref`, the object *itself* is not made deeply reactive. Only assignment to the `.value` property is tracked. Use `reactive` for deep object reactivity.
+**Note:** If a plain object is passed to `ref`, the object _itself_ is not made deeply reactive. Only assignment to the `.value` property is tracked. Use `reactive` for deep object reactivity.
 
 ```typescript
-import { ref, watchEffect, isRef, unref } from '@yiin/reactive-proxy-state';
+import { ref, watchEffect, isRef, unref } from "@yiin/reactive-proxy-state";
 
 // Ref for a primitive
 const count = ref(0);
 console.log(count.value); // 0
 
 watchEffect(() => {
-  console.log('Count is:', count.value);
+  console.log("Count is:", count.value);
 });
 // Output: Count is: 0
 
@@ -159,19 +129,19 @@ count.value++; // Triggers the effect
 // Output: Count is: 1
 
 // Ref for an object
-const user = ref({ name: 'Alice' });
+const user = ref({ name: "Alice" });
 
 watchEffect(() => {
   // This effect depends on the object reference stored in user.value
-  console.log('User object:', user.value);
+  console.log("User object:", user.value);
 });
 // Output: User object: { name: 'Alice' }
 
 // Mutating the inner object DOES NOT trigger the effect above
-user.value.name = 'Bob'; 
+user.value.name = "Bob";
 
 // Assigning a new object DOES trigger the effect
-user.value = { name: 'Charles' };
+user.value = { name: "Charles" };
 // Output: User object: { name: 'Charles' }
 
 // Helpers
@@ -183,100 +153,39 @@ console.log(unref(123)); // 123 (returns non-refs as is)
 ```
 
 ### `computed<T>(getter: () => T): ComputedRef<T>`
+
 ### `computed<T>(options: { get: () => T, set: (value: T) => void }): WritableComputedRef<T>`
 
 Creates a computed property based on a getter function or a getter/setter pair.
 
--   **Getter-only:** The getter tracks reactive dependencies (`ref`s or reactive object properties) and its result is cached. The computed value only recalculates when a dependency changes. Computed refs created this way are **read-only**.
--   **Getter/Setter:** Provides both a getter for deriving the value and a setter for mutating underlying reactive state when the computed ref's `.value` is assigned.
+- **Getter-only:** The getter tracks reactive dependencies (`ref`s or reactive object properties) and its result is cached. The computed value only recalculates when a dependency changes. Computed refs created this way are **read-only**.
+- **Getter/Setter:** Provides both a getter for deriving the value and a setter for mutating underlying reactive state when the computed ref's `.value` is assigned.
 
 ```typescript
-import { ref, computed, watchEffect, isComputed } from '@yiin/reactive-proxy-state';
+import { ref, computed } from "@yiin/reactive-proxy-state";
 
 // Read-only computed
-const firstName = ref('John');
-const lastName = ref('Doe');
-
-const readOnlyFullName = computed(() => {
-  console.log('Computing readOnlyFullName...');
-  return `${firstName.value} ${lastName.value}`;
-});
-
-// Accessing .value triggers computation
-console.log(readOnlyFullName.value); 
-// Output: Computing readOnlyFullName...
-// Output: John Doe
+const firstName = ref("John");
+const lastName = ref("Doe");
 
-// Accessing again uses the cache
-console.log(readOnlyFullName.value);
-// Output: John Doe
+const fullName = computed(() => `${firstName.value} ${lastName.value}`);
+console.log(fullName.value); // John Doe
 
-watchEffect(() => {
-  console.log('Read-only full name changed:', readOnlyFullName.value);
-});
-// Output: Read-only full name changed: John Doe
-
-// Changing a dependency marks computed as dirty
-firstName.value = 'Jane';
-
-// Accessing .value again triggers re-computation and the effect
-console.log(readOnlyFullName.value);
-// Output: Computing readOnlyFullName...
-// Output: Read-only full name changed: Jane Doe
-// Output: Jane Doe
-
-// Chained computed
-const message = computed(() => `User: ${readOnlyFullName.value}`);
-console.log(message.value); // User: Jane Doe
-
-lastName.value = 'Smith';
-// Output: Computing readOnlyFullName...
-// Output: Read-only full name changed: Jane Smith
-console.log(message.value); // User: Jane Smith (message recomputed automatically)
-
-// Read-only check
-console.warn = () => console.log('Warning triggered!'); // Mock console.warn
-try {
-  (readOnlyFullName as any).value = 'Test'; // Triggers warning
-} catch (e) { /* ... */ }
-// Output: Warning triggered!
-console.log(readOnlyFullName.value); // Jane Smith (value unchanged)
+firstName.value = "Jane";
+console.log(fullName.value); // Jane Doe
 
 // Writable computed
-const source = ref(1);
-const plusOne = computed({
-    get: () => source.value + 1,
-    set: (newValue) => { 
-        console.log(`Setting source based on new value: ${newValue}`);
-        source.value = newValue - 1; 
-    }
-});
-
-console.log(plusOne.value); // 2 (Initial get)
-console.log(source.value);  // 1
-
-watchEffect(() => {
-  console.log('Writable computed changed:', plusOne.value);
+const count = ref(1);
+const doubled = computed({
+  get: () => count.value * 2,
+  set: (value) => {
+    count.value = value / 2;
+  },
 });
-// Output: Writable computed changed: 2
-
-// Set the writable computed value
-plusOne.value = 10;
-// Output: Setting source based on new value: 10
-// Output: Writable computed changed: 10 
 
-console.log(plusOne.value); // 10
-console.log(source.value);  // 9 (Source was updated by the setter)
-
-// Changing the source ref also updates the computed
-source.value = 20;
-// Output: Writable computed changed: 21
-console.log(plusOne.value); // 21
-
-// Helper
-console.log(isComputed(readOnlyFullName)); // true
-console.log(isComputed(plusOne)); // true
-console.log(isComputed(firstName)); // false
+console.log(doubled.value); // 2
+doubled.value = 10;
+console.log(count.value); // 5
 ```
 
 ### `watchEffect(effect: () => void, options?: WatchEffectOptions)`
@@ -284,22 +193,22 @@ console.log(isComputed(firstName)); // false
 Runs a function immediately, tracks its reactive dependencies, and re-runs it synchronously whenever any of those dependencies change.
 
 `WatchEffectOptions`:
-*   `onTrack?(event)`: Debug hook called when a dependency is tracked.
-*   `onTrigger?(event)`: Debug hook called when the effect is triggered by a mutation.
+
+- `onTrack?(event)`: Debug hook called when a dependency is tracked.
+- `onTrigger?(event)`: Debug hook called when the effect is triggered by a mutation.
 
 ```typescript
-import { reactive, ref, watchEffect } from '@yiin/reactive-proxy-state';
+import { reactive, watchEffect } from "@yiin/reactive-proxy-state";
 
-// ... existing watchEffect example using reactive ...
+const state = reactive({ count: 0 });
 
-// Using watchEffect with refs
-const counter = ref(10);
 watchEffect(() => {
-  console.log('Counter:', counter.value);
+  console.log("Count:", state.count);
 });
-// Output: Counter: 10
-counter.value--;
-// Output: Counter: 9
+// Output: Count: 0
+
+state.count++;
+// Output: Count: 1
 ```
 
 ### `watch<T>(source: WatchSource<T> | T, callback: (newValue: T, oldValue: T | undefined) => void, options?: WatchOptions)`
@@ -309,30 +218,23 @@ Watches a specific reactive source (either a getter function, a direct reactive
 `WatchSource<T>`: A function that returns the value to watch, or a `ref`.
 `callback`: Function executed on change. Receives the new value and the old value.
 `WatchOptions`:
-*   `immediate?: boolean`: If `true`, runs the callback immediately with the initial value (oldValue will be `undefined`). Defaults to `false`.
-*   `deep?: boolean`: If `true`, deeply traverses the source for dependency tracking and uses deep comparison logic. **Defaults to `true`**. Set to `false` for shallow watching (only triggers on direct assignment or identity change).
 
-```typescript
-import { reactive, ref, watch } from '@yiin/reactive-proxy-state';
+- `immediate?: boolean`: If `true`, runs the callback immediately with the initial value (oldValue will be `undefined`). Defaults to `false`.
+- `deep?: boolean`: If `true`, deeply traverses the source for dependency tracking and uses deep comparison logic. **Defaults to `true`**. Set to `false` for shallow watching (only triggers on direct assignment or identity change).
 
-// ... existing watch examples using reactive ...
+```typescript
+import { reactive, watch } from "@yiin/reactive-proxy-state";
 
-// Watching a ref
-const count = ref(0);
-watch(count, (newVal, oldVal) => {
-  console.log(`Count changed from ${oldVal} to ${newVal}`);
-});
-count.value = 5; // Output: Count changed from 0 to 5
+const state = reactive({ count: 0 });
 
-// Watching a getter involving a ref
-const doubleCount = ref(100);
 watch(
-  () => doubleCount.value * 2,
-  (newDouble, oldDouble) => {
-    console.log(`Double changed from ${oldDouble} to ${newDouble}`);
+  () => state.count,
+  (newVal, oldVal) => {
+    console.log(`Count changed from ${oldVal} to ${newVal}`);
   }
 );
-doubleCount.value = 110; // Output: Double changed from 200 to 220
+
+state.count = 5; // Output: Count changed from 0 to 5
 ```
 
 ## Collections (Arrays, Maps, Sets)
@@ -340,21 +242,25 @@ doubleCount.value = 110; // Output: Double changed from 200 to 220
 `reactive` automatically handles Arrays, Maps, and Sets. Mutations via standard methods (`push`, `pop`, `splice`, `set`, `delete`, `add`, `clear`, etc.) are reactive and will trigger effects that depend on the collection or its contents (if watched deeply).
 
 ```typescript
-import { reactive, watchEffect } from '@yiin/reactive-proxy-state';
+import { reactive, watchEffect } from "@yiin/reactive-proxy-state";
 
 const state = reactive({
   list: [1, 2],
   data: new Map<string, number>(),
-  tags: new Set<string>()
+  tags: new Set<string>(),
 });
 
-watchEffect(() => console.log('List size:', state.list.length));
-watchEffect(() => console.log('Data has "foo":', state.data.has('foo')));
-watchEffect(() => console.log('Tags:', Array.from(state.tags).join(', ')));
+watchEffect(() => console.log("List size:", state.list.length));
+watchEffect(() => console.log('Data has "foo":', state.data.has("foo")));
+watchEffect(() => console.log("Tags:", Array.from(state.tags).join(", ")));
 
-state.list.push(3);            // Output: List size: 3
-state.data.set('foo', 100);    // Output: Data has "foo": true
-state.tags.add('important');   // Output: Tags: important
-state.data.delete('foo');      // Output: Data has "foo": false
-state.tags.add('urgent');      // Output: Tags: important, urgent
+state.list.push(3); // Output: List size: 3
+state.data.set("foo", 100); // Output: Data has "foo": true
+state.tags.add("important"); // Output: Tags: important
+state.data.delete("foo"); // Output: Data has "foo": false
+state.tags.add("urgent"); // Output: Tags: important, urgent
 ```
+
+## Advanced Usage
+
+For more complex scenarios like state synchronization between different contexts, manual event handling, and detailed API documentation, see our [comprehensive documentation](https://Yiin.github.io/reactive-proxy-state/).

package/dist/computed.d.ts

@@ -15,6 +15,12 @@ interface WritableComputedOptions<T> {
     get: ComputedGetter<T>;
     set: ComputedSetter<T>;
 }
+/**
+ * Creates a computed ref from a getter function
+ *
+ * @param getter - The getter function
+ * @returns A computed ref
+ */
 export declare function computed<T>(getter: ComputedGetter<T>): ComputedRef<T>;
 export declare function computed<T>(options: WritableComputedOptions<T>): WritableComputedRef<T>;
 export declare function isComputed<T>(c: any): c is ComputedRef<T> | WritableComputedRef<T>;

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Special symbols used to mark reactive objects and store metadata.
+ */
+export declare const enum ReactiveFlags {
+    RAW = "__v_raw",// reference to the original object
+    IS_REACTIVE = "__v_isReactive",// flag indicating if an object is reactive  
+    SKIP = "__v_skip"
+}

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './watch';
 export * from './watch-effect';
 export * from './ref';
 export * from './computed';
+export * from './constants';