feat(atoms): replace arrays instead of deep merging in mutate shorthand

Arrays in the `.mutate` shorthand now fully replace instead of deep
merging by index. The previous behavior was surprising - e.g.
`signal.mutate({ arr: [1, 2] })` on `[10, 20, 30]` would produce
`[1, 2, 30]`. Now it produces `[1, 2]`. Use the callback form for
index-level updates: `signal.mutate(s => { s.arr[2] = 30 })`.

Also fixes pre-existing type errors by loosening `AtomApiGenerics`
Signal constraint from `Signal` to `AnySignal`, and consolidates
`RecursivePartialWithArrayPlucking` into `RecursivePartial` (with an
array guard added to both core and atoms).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bowheart

packages/atoms/src/classes/proxies.ts

@@ -1,7 +1,7 @@
 import {
   Transaction,
   MutatableTypes,
-  RecursivePartialWithArrayPlucking,
+  RecursivePartial,
 } from '../types/index'
 
 /**
@@ -333,7 +333,7 @@ const mutateSet = (prevVal: Set<any>, newVal: Set<any>) => {
  */
 export function recursivelyMutate<
   State extends any[] | Record<string, any> | Set<any>
->(state: State, update: RecursivePartialWithArrayPlucking<State>) {
+>(state: State, update: RecursivePartial<State>) {
   // the `.mutate` shorthand only supports same-type overwrites (no set ->
   // object, array -> set, etc. type changes). So we assume `update` is a set
   // here.
@@ -350,9 +350,8 @@ export function recursivelyMutate<
 
       if (
         isPlainObject(val)
-          ? isPlainObject(prevVal) || Array.isArray(prevVal)
-          : (Array.isArray(prevVal) && Array.isArray(val)) ||
-            (prevVal instanceof Set && val instanceof Set)
+          ? isPlainObject(prevVal)
+          : prevVal instanceof Set && val instanceof Set
       ) {
         recursivelyMutate(prevVal as any, val)
       } else {

packages/atoms/src/injectors/injectPromise.ts

@@ -208,7 +208,9 @@ export const injectPromise: {
     promise: Promise<Data>
   })
 
-  const dataSignal = injectSignal(initialData, { reactive: false }) as Signal<{
+  const dataSignal = injectSignal(initialData, {
+    reactive: false,
+  }) as unknown as Signal<{
     Events: EventMap
     Params: undefined
     ResolvedState: Data

packages/atoms/src/types/atoms.ts

@@ -74,7 +74,7 @@ export type AtomApiGenerics = Pick<
   AtomGenerics,
   'Exports' | 'Promise' | 'State'
 > & {
-  Signal: Signal | undefined
+  Signal: AnySignal | undefined
 }
 
 export type AtomGenericsToAtomApiGenerics<

packages/atoms/src/types/events.ts

@@ -7,7 +7,7 @@ import {
   ListenerConfig,
   NodeGenerics,
   Prettify,
-  RecursivePartialWithArrayPlucking,
+  RecursivePartial,
 } from './index'
 
 export type CatchAllListener<G extends NodeGenerics> = (
@@ -159,8 +159,8 @@ export type ListenableEvents<G extends NodeGenerics = AnyNodeGenerics> =
   Prettify<G['Events'] & ExplicitEvents & ImplicitEvents<G>>
 
 export type Mutatable<State> =
-  | RecursivePartialWithArrayPlucking<State>
-  | ((state: State) => void | RecursivePartialWithArrayPlucking<State>)
+  | RecursivePartial<State>
+  | ((state: State) => void | RecursivePartial<State>)
 
 export type MutatableTypes = any[] | Record<string, any> | Set<any>
 

packages/atoms/src/types/index.ts

@@ -3,7 +3,6 @@ import { AtomApi } from '../classes/AtomApi'
 import { Ecosystem } from '../classes/Ecosystem'
 import { ZeduxNode } from '../classes/ZeduxNode'
 import { SelectorInstance } from '../classes/SelectorInstance'
-import { Signal } from '../classes/Signal'
 import {
   InternalEvaluationType,
   InternalLifecycleStatus,
@@ -86,7 +85,7 @@ export type SelectorTemplate<State = any, Params extends any[] = any> =
 
 export type AtomStateFactory<
   G extends Pick<AtomGenerics, 'Exports' | 'Params' | 'Promise' | 'State'> & {
-    Signal: Signal | undefined
+    Signal: AnySignal | undefined
   }
 > = (
   ...params: G['Params']
@@ -99,7 +98,7 @@ export type AtomTuple<A extends AnyAtomTemplate> = [A, ParamsOf<A>]
 
 export type AtomValueOrFactory<
   G extends Pick<AtomGenerics, 'Exports' | 'Params' | 'Promise' | 'State'> & {
-    Signal: Signal | undefined
+    Signal: AnySignal | undefined
   }
 > = AtomStateFactory<G> | G['State']
 
@@ -492,12 +491,6 @@ export type RecursivePartial<T> = T extends Record<string, any>
   ? { [P in keyof T]?: RecursivePartial<T[P]> }
   : T
 
-export type RecursivePartialWithArrayPlucking<T> = T extends any[]
-  ? { [K in number]?: RecursivePartialWithArrayPlucking<T[number]> }
-  : T extends Record<string, any>
-    ? { [P in keyof T]?: RecursivePartialWithArrayPlucking<T[P]> }
-    : T
-
 export type Ref<T = any> = MutableRefObject<T>
 
 export interface RefObject<T = any> {

packages/react/test/integrations/__snapshots__/proxies.test.tsx.snap

@@ -8,17 +8,11 @@ exports[`proxies array operations 1`] = `
         "k": [
           "0",
           "a",
-          "0",
         ],
-        "v": 11,
-      },
-      {
-        "k": [
-          "0",
-          "a",
-          "1",
+        "v": [
+          11,
+          33,
         ],
-        "v": 33,
       },
     ],
     [

packages/react/test/integrations/proxies.test.tsx

@@ -259,7 +259,7 @@ describe('proxies', () => {
       ],
       [
         [
-          { k: ['arr', '1'], v: 'b' },
+          { k: 'arr', v: ['a', 'b'] },
           { k: ['set', 'b'], v: undefined },
         ],
         {
@@ -269,7 +269,7 @@ describe('proxies', () => {
       ],
       [
         [
-          { k: ['arr', '2'], v: 'c' },
+          { k: 'arr', v: ['a', 'b', 'c'] },
           { k: ['set', 'c'], v: undefined },
         ],
         {
@@ -312,7 +312,10 @@ describe('proxies', () => {
     })
 
     signal.mutate(draft => [draft[0] + 1, draft[1] + 1])
-    signal.mutate({ 2: 30, 3: 40 })
+    signal.mutate(state => {
+      state[2] = 30
+      state[3] = 40
+    })
 
     expect(signal.get()).toEqual([2, 3, 30, 40, 5])
   })
@@ -373,18 +376,11 @@ describe('proxies', () => {
         calls.push(transactions)
       })
 
-      // Array shorthand should work and only create transactions for changed indices
-      signal.mutate({ arr: { 2: 30 } })
+      // Array shorthand fully replaces the array instead of deep merging
       signal.mutate({ arr: [11, 21] })
 
-      expect(signal.get()).toEqual({ arr: [11, 21, 30] })
-      expect(calls).toEqual([
-        [{ k: ['arr', '2'], v: 30 }],
-        [
-          { k: ['arr', '0'], v: 11 },
-          { k: ['arr', '1'], v: 21 },
-        ],
-      ])
+      expect(signal.get()).toEqual({ arr: [11, 21] })
+      expect(calls).toEqual([[{ k: 'arr', v: [11, 21] }]])
     })
   })
 
@@ -615,13 +611,13 @@ describe('proxies', () => {
       expect(result).not.toBeInstanceOf(Config)
     })
 
-    test('plain object can update specific array indices via shorthand', () => {
+    test('plain object replaces array via shorthand', () => {
       const signal = ecosystem.signal<any>({ data: [1, 2, 3] })
 
-      signal.mutate({ data: { 0: 10 } })
+      signal.mutate({ data: { a: 10 } })
 
-      // plain object recurses into array, updating only index 0
-      expect(signal.get().data).toEqual([10, 2, 3])
+      // plain object fully replaces the array
+      expect(signal.get().data).toEqual({ a: 10 })
     })
 
     test('replacing a plain object with an array assigns directly', () => {
@@ -659,7 +655,7 @@ describe('proxies', () => {
       expect(signal.get().nested).toEqual({ a: 100, b: 2 })
 
       signal.mutate({ arr: [11] })
-      expect(signal.get().arr).toEqual([11, 20])
+      expect(signal.get().arr).toEqual([11])
 
       signal.mutate({ set: new Set([2, 3]) })
       expect(signal.get().set).toEqual(new Set([2, 3]))
@@ -764,8 +760,8 @@ describe('proxies', () => {
       // class instance: directly assigned
       expect(signal.get().tag).toBeInstanceOf(Tag)
       expect(signal.get().tag.name).toBe('user')
-      // array: recursively merged (index 1 preserved)
-      expect(signal.get().scores).toEqual([150, 200])
+      // array: fully replaced (no deep merge)
+      expect(signal.get().scores).toEqual([150])
     })
 
     test('proxy does not wrap non-plain objects when accessed via getter', () => {