@montra-interactive/deepstate 0.1.1 → 0.2.1

package/README.md

@@ -0,0 +1,343 @@
+# @montra-interactive/deepstate
+
+Proxy-based reactive state management powered by RxJS. Each property is its own observable with O(depth) change propagation.
+
+## Features
+
+- **Fine-grained reactivity**: Subscribe to any property at any depth
+- **O(depth) performance**: Changes only notify ancestors, never siblings
+- **Type-safe**: Full TypeScript support with inferred types
+- **RxJS native**: Every node is an Observable - use `pipe()`, `combineLatest`, etc.
+- **Batched updates**: Group multiple changes into a single emission
+- **Immutable reads**: Values are deeply frozen to prevent accidental mutations
+- **Nullable objects**: First-class support for `T | null` properties with deep subscription
+- **Debug mode**: Optional logging for development
+
+## Installation
+
+```bash
+npm install @montra-interactive/deepstate rxjs
+# or
+bun add @montra-interactive/deepstate rxjs
+# or
+yarn add @montra-interactive/deepstate rxjs
+```
+
+## Quick Start
+
+```ts
+import { state } from "@montra-interactive/deepstate";
+
+// Create reactive state
+const store = state({
+  user: { name: "Alice", age: 30 },
+  todos: [{ id: 1, text: "Learn deepstate", done: false }],
+  count: 0,
+});
+
+// Subscribe to any property (it's an Observable)
+store.user.name.subscribe(name => console.log("Name:", name));
+
+// Get values synchronously
+console.log(store.user.name.get()); // "Alice"
+
+// Set values
+store.user.name.set("Bob"); // triggers subscription
+
+// Subscribe to parent nodes (emits when any child changes)
+store.user.subscribe(user => console.log("User changed:", user));
+```
+
+## API Reference
+
+### `state<T>(initialState, options?)`
+
+Creates a reactive state store.
+
+```ts
+import { state } from "@montra-interactive/deepstate";
+
+const store = state({
+  user: { name: "Alice", age: 30 },
+  items: [{ id: 1, name: "Item 1" }],
+  count: 0,
+});
+
+// With debug mode
+const debugStore = state(
+  { count: 0 },
+  { debug: true, name: "counter" }
+);
+// Logs: [deepstate:counter] set count: 0 -> 1
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `debug` | `boolean` | Enable debug logging for all set operations |
+| `name` | `string` | Store name used in debug log prefix |
+
+### Node Methods
+
+Every property on the state is a reactive node with these methods:
+
+| Method | Description |
+|--------|-------------|
+| `.get()` | Get current value synchronously |
+| `.set(value)` | Update the value |
+| `.subscribe(callback)` | Subscribe to changes (RxJS Observable) |
+| `.pipe(operators...)` | Chain RxJS operators |
+| `.subscribeOnce(callback)` | Subscribe to a single emission, then auto-unsubscribe |
+
+```ts
+// Primitives
+store.count.get();          // 0
+store.count.set(5);         // Updates to 5
+
+// Objects
+store.user.get();           // { name: "Alice", age: 30 }
+store.user.name.get();      // "Alice"
+store.user.name.set("Bob");
+
+// Subscribe at any level
+store.user.name.subscribe(name => console.log(name));
+store.user.subscribe(user => console.log(user));
+```
+
+### Batched Updates with `.update()`
+
+Batch multiple changes into a single emission:
+
+```ts
+// Without batching - emits twice
+store.user.name.set("Bob");
+store.user.age.set(31);
+// Subscribers see intermediate state
+
+// With batching - emits once
+store.user.update(user => {
+  user.name.set("Bob");
+  user.age.set(31);
+});
+// Subscribers only see final state
+```
+
+### Arrays
+
+Arrays have additional methods:
+
+```ts
+const store = state({
+  items: [
+    { id: 1, name: "First" },
+    { id: 2, name: "Second" },
+  ],
+});
+
+// Access by index
+store.items.at(0)?.name.get();     // "First"
+store.items.at(0)?.name.set("Updated");
+
+// Array methods
+store.items.push({ id: 3, name: "Third" });  // Returns new length
+store.items.pop();                            // Returns removed item
+store.items.length.get();                     // Current length
+
+// Observable length
+store.items.length.subscribe(len => console.log("Length:", len));
+
+// Non-reactive iteration
+store.items.map((item, i) => item.name);
+store.items.filter(item => item.id > 1);
+
+// Batched array updates
+store.items.update(items => {
+  items.at(0)?.name.set("Modified");
+  items.push({ id: 4, name: "New" });
+});
+```
+
+### `array(value, options?)` - Array with Distinct
+
+Control array emission deduplication:
+
+```ts
+import { state, array } from "@montra-interactive/deepstate";
+
+const store = state({
+  // No deduplication (default)
+  items: [1, 2, 3],
+  
+  // Reference equality per element
+  tags: array(["a", "b"], { distinct: "shallow" }),
+  
+  // JSON comparison (deep equality)
+  settings: array([{ theme: "dark" }], { distinct: "deep" }),
+  
+  // Custom comparator
+  custom: array([1, 2, 3], {
+    distinct: (a, b) => a.length === b.length
+  }),
+});
+```
+
+**Distinct Options:**
+
+| Value | Description |
+|-------|-------------|
+| `false` | No deduplication (default) |
+| `"shallow"` | Reference equality: `a[i] === b[i]` |
+| `"deep"` | JSON comparison: `JSON.stringify(a) === JSON.stringify(b)` |
+| `(a, b) => boolean` | Custom comparator function |
+
+### `nullable(value)` - Nullable Objects
+
+For properties that can be `null` or an object:
+
+```ts
+import { state, nullable } from "@montra-interactive/deepstate";
+
+const store = state({
+  // Start as null, can become object
+  user: nullable<{ name: string; age: number }>(null),
+  
+  // Start as object, can become null
+  profile: nullable({ bio: "Hello", avatar: "url" }),
+});
+
+// Deep subscription works even when null!
+store.user.name.subscribe(name => {
+  console.log(name); // undefined when user is null, value when set
+});
+
+// Transitions
+store.user.set({ name: "Alice", age: 30 });  // Now has value
+store.user.name.set("Bob");                   // Update nested
+store.user.set(null);                         // Back to null
+```
+
+### `select(...observables)` - Combine Observables
+
+```ts
+import { select } from "@montra-interactive/deepstate";
+
+// Array form - returns tuple
+select(store.user.name, store.count).subscribe(([name, count]) => {
+  console.log(`${name}: ${count}`);
+});
+
+// Object form - returns object
+select({
+  name: store.user.name,
+  count: store.count,
+}).subscribe(({ name, count }) => {
+  console.log(`${name}: ${count}`);
+});
+```
+
+### `selectFromEach(arrayNode, selector)` - Select from Array Items
+
+Derive values from each array item with precise change detection:
+
+```ts
+import { selectFromEach } from "@montra-interactive/deepstate";
+
+const store = state({
+  items: [
+    { name: "A", price: 10, qty: 2 },
+    { name: "B", price: 20, qty: 1 },
+  ],
+});
+
+// Select single property from each item
+selectFromEach(store.items, item => item.price).subscribe(prices => {
+  console.log(prices); // [10, 20]
+});
+
+// Derive computed values
+selectFromEach(store.items, item => item.price * item.qty).subscribe(totals => {
+  console.log(totals); // [20, 20]
+});
+
+// Only emits when selected values change
+store.items.at(0)?.name.set("Changed"); // No emission (name wasn't selected)
+store.items.at(0)?.price.set(15);       // Emits [15, 20]
+```
+
+## RxJS Integration
+
+Every node is a full RxJS Observable:
+
+```ts
+import { debounceTime, filter, map } from "rxjs/operators";
+
+store.user.name
+  .pipe(
+    debounceTime(300),
+    filter(name => name.length > 0),
+    map(name => name.toUpperCase())
+  )
+  .subscribe(name => console.log(name));
+```
+
+## TypeScript
+
+Full type inference from your initial state:
+
+```ts
+const store = state({
+  user: { name: "Alice", age: 30 },
+  items: [{ id: 1 }],
+  selectedId: null as string | null,
+});
+
+store.user.name.get();    // string
+store.user.age.get();     // number
+store.items.at(0)?.id;    // RxLeaf<number> | undefined
+store.selectedId.get();   // string | null
+```
+
+### Type Exports
+
+```ts
+import type { RxState, Draft, DeepReadonly } from "@montra-interactive/deepstate";
+```
+
+| Type | Description |
+|------|-------------|
+| `RxState<T>` | The reactive state type returned by `state()` |
+| `Draft<T>` | Type alias for values in update callbacks |
+| `DeepReadonly<T>` | Deep readonly type for returned values |
+
+## Architecture
+
+deepstate uses a **nested BehaviorSubject architecture**:
+
+- **Primitives**: Each has its own `BehaviorSubject`
+- **Objects**: Derived from `combineLatest(children)`
+- **Arrays**: `BehaviorSubject<T[]>` with child projections
+
+This gives **O(depth) performance**: updating `store.a.b.c` only notifies `c`, `b`, `a`, and the root - never siblings like `store.x.y.z`.
+
+## React Integration
+
+See [@montra-interactive/deepstate-react](https://www.npmjs.com/package/@montra-interactive/deepstate-react) for React hooks:
+
+```tsx
+import { useSelect, usePipeSelect } from "@montra-interactive/deepstate-react";
+
+function UserName() {
+  const name = useSelect(store.user.name);
+  return <span>{name}</span>;
+}
+
+function DebouncedSearch() {
+  const query = usePipeSelect(store.search.pipe(debounceTime(300)));
+  return <input value={query ?? ""} />;
+}
+```
+
+## License
+
+MIT

package/dist/deepstate.d.ts

@@ -191,5 +191,44 @@ export declare function state<T extends object>(initialState: T, options?: State
  * store.user?.name.set("Charlie");  // After ?. on user, children are directly accessible
  */
 export declare function nullable<T extends object>(value: T | null): T | null;
+/** Comparison mode for array distinct checking */
+export type ArrayDistinct<T> = false | 'shallow' | 'deep' | ((a: T[], b: T[]) => boolean);
+/** Options for the array() helper */
+export interface ArrayOptions<T> {
+    /**
+     * How to compare arrays to prevent duplicate emissions.
+     * - false: No deduplication (default, always emits on set)
+     * - 'shallow': Reference equality per element (a[i] === b[i])
+     * - 'deep': JSON.stringify comparison (expensive for large arrays)
+     * - function: Custom comparator (a, b) => boolean
+     */
+    distinct?: ArrayDistinct<T>;
+}
+/**
+ * Marks an array with options for how it should behave in state.
+ * Use this to enable deduplication (prevent emissions when setting same values).
+ *
+ * @example
+ * ```ts
+ * const store = state({
+ *   // Default behavior - emits on every set
+ *   items: [1, 2, 3],
+ *
+ *   // Shallow comparison - only emits if elements differ by reference
+ *   tags: array(['a', 'b'], { distinct: 'shallow' }),
+ *
+ *   // Deep comparison - only emits if JSON representation differs
+ *   settings: array([{ theme: 'dark' }], { distinct: 'deep' }),
+ *
+ *   // Custom comparator - you define equality
+ *   users: array([{ id: 1, name: 'Alice' }], {
+ *     distinct: (a, b) =>
+ *       a.length === b.length &&
+ *       a.every((user, i) => user.id === b[i].id)
+ *   }),
+ * });
+ * ```
+ */
+export declare function array<T>(value: T[], options?: ArrayOptions<T>): T[];
 export {};
 //# sourceMappingURL=deepstate.d.ts.map

package/dist/deepstate.d.ts.map

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

package/dist/index.d.ts

@@ -4,12 +4,13 @@
  * Core exports:
  * - state() - Create reactive state from plain objects
  * - nullable() - Mark a property as nullable (can transition between null and object)
+ * - array() - Mark an array with deduplication options
  * - RxState, Draft - Type exports
  *
  * Helper exports:
  * - select() - Combine multiple observables
  * - selectFromEach() - Select from each array item with precise change detection
  */
-export { state, nullable, type RxState, type Draft, type StateOptions } from "./deepstate";
+export { state, nullable, array, type RxState, type Draft, type StateOptions, type ArrayOptions, type ArrayDistinct } from "./deepstate";
 export { select, selectFromEach } from "./helpers";
 //# 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;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACzI,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -164,7 +164,7 @@ function createObjectNode(value) {
     }
   };
 }
-function createArrayNode(value) {
+function createArrayNode(value, comparator) {
   const subject$ = new BehaviorSubject([...value]);
   const childCache = new Map;
   const createChildProjection = (index) => {
@@ -188,7 +188,8 @@ function createArrayNode(value) {
     };
   };
   const lock$ = new BehaviorSubject(true);
-  const locked$ = combineLatest2([subject$, lock$]).pipe(filter(([_, unlocked]) => unlocked), map2(([arr, _]) => arr), map2(deepFreeze), shareReplay(1));
+  const baseLocked$ = combineLatest2([subject$, lock$]).pipe(filter(([_, unlocked]) => unlocked), map2(([arr, _]) => arr));
+  const locked$ = (comparator ? baseLocked$.pipe(distinctUntilChanged2(comparator)) : baseLocked$).pipe(map2(deepFreeze), shareReplay(1));
   locked$.subscribe();
   const length$ = locked$.pipe(map2((arr) => arr.length), distinctUntilChanged2(), shareReplay(1));
   length$.subscribe();
@@ -562,6 +563,12 @@ function createNodeForValue(value, maybeNullable = false) {
     return createLeafNode(value);
   }
   if (Array.isArray(value)) {
+    if (isArrayMarked(value)) {
+      const options = value[ARRAY_MARKER];
+      const comparator = getArrayComparator(options);
+      delete value[ARRAY_MARKER];
+      return createArrayNode(value, comparator);
+    }
     return createArrayNode(value);
   }
   return createObjectNode(value);
@@ -782,9 +789,30 @@ function nullable(value) {
 function isNullableMarked(value) {
   return value !== null && typeof value === "object" && NULLABLE_MARKER in value;
 }
+var ARRAY_MARKER = Symbol("array");
+function array(value, options = {}) {
+  const marked = [...value];
+  marked[ARRAY_MARKER] = options;
+  return marked;
+}
+function isArrayMarked(value) {
+  return Array.isArray(value) && ARRAY_MARKER in value;
+}
+function getArrayComparator(options) {
+  if (!options.distinct)
+    return;
+  if (options.distinct === "shallow") {
+    return (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+  }
+  if (options.distinct === "deep") {
+    return (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  }
+  return options.distinct;
+}
 export {
   state,
   selectFromEach,
   select,
-  nullable
+  nullable,
+  array
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montra-interactive/deepstate",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Proxy-based reactive state management with RxJS. Deep nested state observation with full TypeScript support.",
   "keywords": [
     "state",

package/src/deepstate.ts

@@ -424,7 +424,10 @@ function createObjectNode<T extends object>(value: T): NodeCore<T> & {
   };
 }
 
-function createArrayNode<T>(value: T[]): NodeCore<T[]> & {
+function createArrayNode<T>(
+  value: T[],
+  comparator?: (a: T[], b: T[]) => boolean
+): NodeCore<T[]> & {
   at(index: number): NodeCore<T> | undefined;
   childCache: Map<number, NodeCore<T>>;
   length$: Observable<number> & { get(): number };
@@ -478,10 +481,17 @@ function createArrayNode<T>(value: T[]): NodeCore<T[]> & {
   // Lock for batching updates - when false, emissions are filtered out
   const lock$ = new BehaviorSubject<boolean>(true);
 
-  // Create observable that respects lock
-  const locked$ = combineLatest([subject$, lock$]).pipe(
+  // Create observable that respects lock, with optional distinct comparison
+  const baseLocked$ = combineLatest([subject$, lock$]).pipe(
     filter(([_, unlocked]) => unlocked),
     map(([arr, _]) => arr),
+  );
+  
+  // Apply distinct comparison if provided
+  const locked$ = (comparator 
+    ? baseLocked$.pipe(distinctUntilChanged(comparator))
+    : baseLocked$
+  ).pipe(
     map(deepFreeze),
     shareReplay(1)
   );
@@ -1079,6 +1089,14 @@ function createNodeForValue<T>(value: T, maybeNullable: boolean = false): NodeCo
     return createLeafNode(value as Primitive) as NodeCore<T>;
   }
   if (Array.isArray(value)) {
+    // Check if array was marked with options via array() helper
+    if (isArrayMarked(value)) {
+      const options = value[ARRAY_MARKER];
+      const comparator = getArrayComparator(options);
+      // Remove the marker before creating the node
+      delete (value as Record<symbol, unknown>)[ARRAY_MARKER];
+      return createArrayNode(value, comparator) as unknown as NodeCore<T>;
+    }
     return createArrayNode(value) as unknown as NodeCore<T>;
   }
   return createObjectNode(value as object) as unknown as NodeCore<T>;
@@ -1401,3 +1419,81 @@ export function nullable<T extends object>(value: T | null): T | null {
 function isNullableMarked<T>(value: T): boolean {
   return value !== null && typeof value === "object" && NULLABLE_MARKER in value;
 }
+
+// Symbol to mark an array with distinct options
+const ARRAY_MARKER = Symbol("array");
+
+/** Comparison mode for array distinct checking */
+export type ArrayDistinct<T> = 
+  | false              // No deduplication (default)
+  | 'shallow'          // Reference equality per element
+  | 'deep'             // JSON.stringify comparison
+  | ((a: T[], b: T[]) => boolean);  // Custom comparator
+
+/** Options for the array() helper */
+export interface ArrayOptions<T> {
+  /** 
+   * How to compare arrays to prevent duplicate emissions.
+   * - false: No deduplication (default, always emits on set)
+   * - 'shallow': Reference equality per element (a[i] === b[i])
+   * - 'deep': JSON.stringify comparison (expensive for large arrays)
+   * - function: Custom comparator (a, b) => boolean
+   */
+  distinct?: ArrayDistinct<T>;
+}
+
+interface MarkedArray<T> extends Array<T> {
+  [ARRAY_MARKER]: ArrayOptions<T>;
+}
+
+/**
+ * Marks an array with options for how it should behave in state.
+ * Use this to enable deduplication (prevent emissions when setting same values).
+ * 
+ * @example
+ * ```ts
+ * const store = state({
+ *   // Default behavior - emits on every set
+ *   items: [1, 2, 3],
+ *   
+ *   // Shallow comparison - only emits if elements differ by reference
+ *   tags: array(['a', 'b'], { distinct: 'shallow' }),
+ *   
+ *   // Deep comparison - only emits if JSON representation differs
+ *   settings: array([{ theme: 'dark' }], { distinct: 'deep' }),
+ *   
+ *   // Custom comparator - you define equality
+ *   users: array([{ id: 1, name: 'Alice' }], {
+ *     distinct: (a, b) => 
+ *       a.length === b.length && 
+ *       a.every((user, i) => user.id === b[i].id)
+ *   }),
+ * });
+ * ```
+ */
+export function array<T>(value: T[], options: ArrayOptions<T> = {}): T[] {
+  const marked = [...value] as MarkedArray<T>;
+  marked[ARRAY_MARKER] = options;
+  return marked;
+}
+
+// Check if an array was marked with options
+function isArrayMarked<T>(value: unknown): value is MarkedArray<T> {
+  return Array.isArray(value) && ARRAY_MARKER in value;
+}
+
+// Get the distinct comparator function from array options
+function getArrayComparator<T>(options: ArrayOptions<T>): ((a: T[], b: T[]) => boolean) | undefined {
+  if (!options.distinct) return undefined;
+  
+  if (options.distinct === 'shallow') {
+    return (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+  }
+  
+  if (options.distinct === 'deep') {
+    return (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  }
+  
+  // Custom function
+  return options.distinct;
+}

package/src/index.ts

@@ -4,6 +4,7 @@
  * Core exports:
  * - state() - Create reactive state from plain objects
  * - nullable() - Mark a property as nullable (can transition between null and object)
+ * - array() - Mark an array with deduplication options
  * - RxState, Draft - Type exports
  * 
  * Helper exports:
@@ -11,5 +12,5 @@
  * - selectFromEach() - Select from each array item with precise change detection
  */
 
-export { state, nullable, type RxState, type Draft, type StateOptions } from "./deepstate";
+export { state, nullable, array, type RxState, type Draft, type StateOptions, type ArrayOptions, type ArrayDistinct } from "./deepstate";
 export { select, selectFromEach } from "./helpers";