XState의 Actor 알아보기

https://xstate.js.org/docs/guides/actors.html#actor-api

Actors | XState Docs

XState

 

 

액터(행위자) 모델은 여러 "엔티티"(또는 "행위자")가 서로 통신하는 방법을 단순화하는 메시지 기반 계산의 수학적 모델입니다.

액터는 메시지(이벤트)를 서로 전송하여 통신합니다.

액터의 로컬 상태는 이벤트로 전송하여 다른 액터와 공유하려는 경우가 아니면 private 합니다.

 

액터가 이벤트를 수신하면 세 가지 일이 발생할 수 있습니다.

• 유한 수의 메시지를 다른 액터에게 send 할 수 있습니다.
• 유한 수의 새로운 액터를 spawn할 수 있습니다.
• 액터의 로컬 상태는 변경될 수 있습니다(behavior에 따라 결정됨).

상태 머신 및 상태 차트는 행위 및 논리의 이벤트 기반 모델이기 때문에 액터 모델과 매우 잘 작동합니다.

상태 머신이 이벤트로 인해 전환될 때 다음 상태에는 다음이 포함됩니다.

• 다음 값 및 컨텍스트(액터의 로컬 상태)
• 실행할 다음 작업(아마도 새로 생성되었을 액터 또는 다른 액터에게 보내는 메시지)

액터를 spawn하거나 invoke할 수 있습니다. 스폰된 액터는 호출된 액터와 두 가지 주요 차이점이 있습니다.

• 그것들은 언제든지 스폰될 수 있습니다. (assign(...)액션 내부의 spawn(...)을 통해)
•  언제든지 중지할 수 있습니다. (stop(...) 작업을 통해). 

 

Actor API

---

액터(XState에서 구현됨)에는 다음과 같은 인터페이스가 있습니다.

• id 속성 : 로컬 시스템에서 액터를 고유하게 식별하는 
•  .send(...) 메서드 : 이 액터에 이벤트를 보내는 데 사용
• .getSnapshot() 메서드. : 액터의 마지막 방출 값을 동기적으로 반환

선택적 메서드가 있을 수 있습니다.

•  .stop() 메서드 : 액터를 중지하고 필요한 정리를 수행하는
• .subscribe(...) 메서드 :옵저버블 액터를 위한 

기존 (invoked service patterns)은 이 인터페이스에 맞습니다.

• Invoked promises 는 수신된 이벤트를 무시하고 최대 하나의 이벤트를 부모에게 다시 보내는 액터입니다.
• Invoked callbacks은 부모에게 이벤트를 보내고(첫 번째 콜백 파라미터), 이벤트를 수신(두 번째 onReceive 파라미터)하고, 이에 대해 조치를 취할 수 있는 액터입니다.
• Invoked machines 은 이벤트를 부모(sendParent(...) 액션) 또는 해당 머신이 참조하는 다른 액터에 이벤트를 보내고(send(...) 액션), 이벤트를 수신하고, 이에 대해 반응(상태 전환 및 액션)할 수 있는 액터입니다. 새로운 액터를 생성하고(spawn(...) 함수), 액터를 중지합니다.
• Invoked observables 은 방출된 값이 부모에게 다시 보낼 이벤트를 나타내는 액터입니다.

방출된 값이란 무엇입니까?

액터가 내보낸 값은 구독자가 액터의 .subscribe(...) 메서드에서 받는 값입니다.

• 서비스의 경우 현재 상태가 방출됩니다.
• Promise의 경우 resolved된 값(또는 unfulfilled의 경우 undefined)이 방출됩니다
  • 대기(pending): 이행하지도, 거부하지도 않은 초기 상태.
  • 이행(fulfilled): 연산이 성공적으로 완료됨.
  • 거부(rejected): 연산이 실패함.
• Observable의 경우 가장 최근에 방출된 값이 방출됩니다.
• 콜백의 경우 아무 것도 내보내지 않습니다.

액터 스포닝(Spawn)

---

Akka 또는 Erlang과 같은 액터 모델 기반 언어와 마찬가지로 액터가 생성되고 컨텍스트에서 참조됩니다. (assign(...) 작업의 결과로).

• 'xstate'에서 스폰 기능 가져오기 assign(...)
• 액션에서 spawn(...)을 사용하여 새 액터 참조를 만듭니다.

spawn(...) 함수는 1개 또는 2개의 인수를 제공하여 액터 참조를 생성합니다.

• entity - 액터의 행동을 나타내는 (reactive) 값 또는 기계. 엔티티에 가능한 타입:
  • 머신
  • 콜백
  • 프로미스
  • 옵저버블
• name(선택 사항) - 액터를 고유하게 식별하는 문자열입니다. 이것은 생성된 모든 액터와 호출된 서비스에 대해 고유해야 합니다.

spawn은 다음 옵션을 포함할 수 있는 두 번째 인수로 options 객체를 허용합니다.

• name(선택 사항) - 액터를 고유하게 식별하는 문자열입니다. 이것은 생성된 모든 액터와 호출된 서비스에 대해 고유해야 합니다. autoForward - (선택 사항) 이 시스템에 전송된 모든 이벤트가 호출된 자식에게도 전송(또는 전달)되어야 하는 경우 true(기본적으로 false)
• sync - (선택 사항) 이 머신이 생성한 자식 머신의 상태를 자동으로 구독해야 하는 경우 true, 상태는 자식 머신 참조에 .state로 저장됩니다.

import { createMachine, spawn } from 'xstate';
import { todoMachine } from './todoMachine';

const todosMachine = createMachine({
  // ...
  on: {
    'NEW_TODO.ADD': {
      actions: assign({
        todos: (context, event) => [
          ...context.todos,
          {
            todo: event.todo,
            // add a new todoMachine actor with a unique name
            ref: spawn(todoMachine, `todo-${event.id}`)
          }
        ]
      })
    }
    // ...
  }
});

spawn(...)에 이름 인수를 제공하지 않으면 고유한 이름이 자동으로 생성됩니다.

이 이름은 결정적이지 않습니다 ⚠️.

팁

const ActorRef = spawn(someMachine) 을 컨텍스트의 일반 값으로 취급하십시오.

논리적인 요구 사항에 따라 이 ActorRef를 컨텍스트 내 아무 곳에나 배치할 수 있습니다.

assign(...)의 할당 함수 내에 있는 한 해당 액터가 생성된 서비스로 컨텍스트 범위가 지정됩니다.

경고

할당(assign-assignment) 함수 외부에서 spawn(...)을 호출하지 마십시오.

이것은 효과가 없는 고아 액터(부모 없는)를 생성합니다.

// ❌ Never call spawn(...) externally
const someActorRef = spawn(someMachine);

// ❌ spawn(...) is not an action creator
{
  actions: spawn(someMachine);
}

// ❌ Do not assign spawn(...) outside of an assignment function
{
  actions: assign({
    // remember: this is called immediately, before a service starts
    someActorRef: spawn(someMachine)
  });
}

// ✅ Assign spawn(...) inside an assignment function
{
  actions: assign({
    someActorRef: () => spawn(someMachine)
  });
}

다양한 타입의 값을 액터로 생성할 수 있습니다.

 

Sending Events to Actors (액터로 이벤트 보내기)

---

send() 작업을 사용하면 대상 표현식을 통해 이벤트를 액터에게 보낼 수 있습니다.

(해당 상태에 진입 후, 액터에 신호를 보냄)

const machine = createMachine({
  // ...
  states: {
    active: {
      entry: assign({
        someRef: () => spawn(someMachine)
      }),
      on: {
        SOME_EVENT: {
          // Use a target expression to send an event
          // to the actor reference
          actions: send({ type: 'PING' }, { to: (context) => context.someRef })
        }
      }
    }
  }
});

팁

spawn(...)에 고유한 이름 인수를 제공하면 대상 표현식에서 참조할 수 있습니다.

const loginMachine = createMachine({
  // ...
  entry: assign({
    formRef: () => spawn(formMachine, 'form')
  }),
  states: {
    idle: {
      on: {
        LOGIN: {
          actions: send({ type: 'SUBMIT' }, { to: 'form' })
        }
      }
    }
  }
});

Stopping Actors (액터 종료)

---

액터는 stop(...) 액션 크리에이터를 사용하여 중지됩니다.

const someMachine = createMachine({
  // ...
  entry: [
    // Stopping an actor by reference
    stop((context) => context.someActorRef),
    // Stopping an actor by ID
    stop('some-actor')
  ]
});

Spawning Promises (프로미스 액터 생성)

---

액터가 내보낸 값은 구독자가 액터의 .subscribe(...) 메서드에서 받는 값입니다.

프라미스 호출과 마찬가지로 프라미스는 액터로 생성될 수 있습니다.

Promise의 경우 resolved된 값(또는 unfulfilled의 경우 undefined)이 방출됩니다

수신된 이벤트를 무시하고 최대 하나의 이벤트를 부모에게 다시 보내는 액터입니다.

머신으로 다시 전송되는 이벤트는 'done.invoke.<ID>' 작업이 됩니다. 여기에는 페이로드의 데이터 속성으로 약속 응답이 포함됩니다.

// Returns a promise
const fetchData = (query) => {
  return fetch(`http://example.com?query=${event.query}`).then((data) =>
    data.json()
  );
};

// ...
{
  actions: assign({
    ref: (_, event) => spawn(fetchData(event.query))
  });
}
// ...

 

경고

프라미스 액터를 생성하는 것은 권장하지 않습니다.

프라미스 호출은 상태에 의존하고(자체 취소) 더 예측 가능한 동작을 가지기 때문에 이에 대한 더 나은 패턴이기 때문입니다.

Spawning Callbacks (콜백 액터 생성)

---

부모에게 이벤트를 보내고(첫 번째 콜백 파라미터), 이벤트를 수신(두 번째 onReceive 파라미터)하고,

이에 대해 조치를 취할 수 있는 액터입니다.

아무 값도 방출하지 않습니다.

콜백을 호출하는 것과 마찬가지로 콜백은 액터로 생성될 수 있습니다.

이 예제는 매초 자체적으로 카운트를 증가시키지만 { type: 'INC' } 이벤트에도 반응할 수 있는 카운터 인터벌 액터를 모델링합니다.

const counterInterval = (callback, receive) => {
  let count = 0;

  const intervalId = setInterval(() => {
    callback({ type: 'COUNT.UPDATE', count });
    count++;
  }, 1000);

  receive(event => {
    if (event.type === 'INC') {
      count++;
    }
  });

  return () => { clearInterval(intervalId); }
}

const machine = createMachine({
  // ...
  {
    actions: assign({
      counterRef: () => spawn(counterInterval)
    })
  }
  // ...
});

이벤트를 액터에게 보낼 수 있습니다.

const machine = createMachine({
  // ...
  on: {
    'COUNTER.INC': {
      actions: send({ type: 'INC' }, { to: (context) => context.counterRef })
    }
  }
  // ...
});

 

Spawning Observables (옵저버블 액터 생성)

---

Invoked observables 은 방출된 값이 부모에게 다시 보낼 이벤트를 나타내는 액터입니다.

Observable의 경우 가장 최근에 방출된 값이 방출됩니다.

 

import { interval } from 'rxjs';
import { map } from 'rxjs/operators';

const createCounterObservable = (ms) => interval(ms)
  .pipe(map(count => ({ type: 'COUNT.UPDATE', count })))

const machine = createMachine({
  context: { ms: 1000 },
  // ...
  {
    actions: assign({
      counterRef: ({ ms }) => spawn(createCounterObservable(ms))
    })
  }
  // ...
  on: {
    'COUNT.UPDATE': { /* ... */ }
  }
});

Spawning Machines (상태 기계 생성)

---

상태 기계는 가장 많은 기능을 제공하기 때문에 액터를 사용하는 가장 효과적인 방법입니다.

생성한 머신은 머신이 spawn(machine)으로 전달되는 invoking machine과 같습니다.

 

예제 : 부모 머신인 로컬 머신에 LOCAL.WAKE 명령 => 부모는 자식(Remote)를 깨움. => 자식은 online상태가 된 후 1초 후 부모에 REMOTE.ONLINE 이벤트 전달. 부모는 connected 상태로 전환.

// Remote
const remoteMachine = createMachine({
  id: 'remote',
  initial: 'offline',
  states: {
    offline: {
      on: {
        WAKE: 'online'
      }
    },
    online: {
      after: {
        1000: {
          actions: sendParent('REMOTE.ONLINE')
        }
      }
    }
  }
});

// Local
const parentMachine = createMachine({
  id: 'parent',
  initial: 'waiting',
  context: {
    localOne: null
  },
  states: {
    waiting: {
      entry: assign({
        localOne: () => spawn(remoteMachine)
      }),
      on: {
        'LOCAL.WAKE': {
          actions: send({ type: 'WAKE' }, { to: (context) => context.localOne })
        },
        'REMOTE.ONLINE': { target: 'connected' }
      }
    },
    connected: {}
  }
});

const parentService = interpret(parentMachine)
  .onTransition((state) => console.log(state.value))
  .start();

parentService.send({ type: 'LOCAL.WAKE' });
// => 'waiting'
// ... after 1000ms
// => 'connected'

Syncing and Reading State (상태 동기화 및 상태 읽기)

---

액터 모델의 주요 신조(tenets) 중 하나는 액터 상태가 비공개이고 로컬이라는 것입니다.

액터가 메시지 전달을 통해 공유하도록 선택하지 않는 한 해당 상태는 절대 공유되지 않습니다.

이 모델을 고수하면 액터는 최신 상태로 특별한 "업데이트" 이벤트를 보내 상태가 변경될 때마다 부모에게 알릴 수 있습니다.

즉, 부모 액터는 자식 액터의 상태를 구독할 수 있습니다.

 

이렇게 하려면 { sync: true }를 spawn(...) 옵션으로 설정합니다.

// ...
{
  actions: assign({
    // Actor will send update event to parent whenever its state changes
    someRef: () => spawn(todoMachine, { sync: true })
  });
}
// ...​

이렇게 하면 머신이 생성된 자식 머신의 상태에 자동으로 등록되며, 이 상태는 계속 업데이트되고 getSnapshot()을 통해 액세스할 수 있습니다.

someService.onTransition((state) => {
  const { someRef } = state.context;

  console.log(someRef.getSnapshot());
  // => State {
  //   value: ...,
  //   context: ...
  // }
});​

sync를 해두면 부모에서 아래처럼 자식 상태 가능합니다.

someService.onTransition((state) => {
  const { someRef } = state.context;
  // 자식 상태 접근
  console.log(someRef.state);
  // => State {
  //   value: ...,
  //   context: ...
  // }
});

경고

기본적으로 동기화는 false로 설정됩니다.

동기화가 비활성화된 경우 액터의 .state를 읽지 마십시오. 그렇지 않으면 stale한 상태를 참조하게 됩니다.

 

주 : 해당 패턴은 부모는 자식을 볼 수 있으며, subscribe 하지만 자식은 부모를 모름

Sending Updates (업데이트 보내기) 

---

부모와 동기화되지 않은 액터의 경우 액터는 sendUpdate()를 통해 부모 시스템에 명시적 이벤트를 보낼 수 있습니다.

import { createMachine, sendUpdate } from 'xstate';

const childMachine = createMachine({
  // ...
  on: {
    SOME_EVENT: {
      actions: [
        // ...
        // Creates an action that sends an update event to parent
        sendUpdate()
      ]
    }
  }
});

TIP

모든 상태 변경을 구독하는 것보다 명시적으로 부모에게 이벤트를 보내는 것을 선호합니다(sendUpdate() 선호).

생성된 시스템과 동기화하면 자식에서 업데이트할 때마다 자식에서 부모로 새로운 "xstate.update" 이벤트가 전송되기 때문에

"수다스러운chatty" 이벤트 로그가 생성될 수 있습니다. 

 

Quick Reference

---

Import spawn to spawn actors:

import { spawn } from 'xstate';

Spawn actors in assign action creators:

// ...
{
  actions: assign({
    someRef: (context, event) => spawn(someMachine)
  });
}
// ...

Spawn different types of actors: (다양한 타입의 액터 생성)

// ...
{
  actions: assign({
    // From a promise 
    // 수신된 이벤트를 무시하고 최대 하나의 이벤트를 부모에게 다시 보내는 액터입니다.
    promiseRef: (context, event) =>
      spawn(
        new Promise((resolve, reject) => {
          // ...
        }),
        'my-promise'
      ),

    // From a callback
    // 리턴 값은 무의미함
    callbackRef: (context, event) =>
      spawn((callback, receive) => {
        // send to parent
        callback('SOME_EVENT');

        // receive from parent
        receive((event) => {
          // handle event
        });

        // disposal
        return () => {
          /* do cleanup here */
        };
      }),

    // From an observable
    // 리턴값은 이벤트 객체
    observableRef: (context, event) => spawn(someEvent$),

    // From a machine    
    machineRef: (context, event) =>
      spawn(
        createMachine({
          // ...
        })
      )
  });
}
// ...

액터와 상태 동기화: (비추)

// ...
{
  actions: assign({
    someRef: () => spawn(someMachine, { sync: true })
  });
}
// ...

액터로부터 스냅샷 얻기: 4.20.0+ 버전 이상부터

service.onTransition((state) => {
  const { someRef } = state.context;

  someRef.getSnapshot();
  // => State { ... }
});

액션 크리에이터 send를 사용하여 액터에게 이벤트 보내기:

// ...
{
  actions: send(
    { type: 'SOME_EVENT' },
    {
      to: (context) => context.someRef
    }
  );
}
// ...

send 표현식을 사용하여 액터에 데이터와 함께 이벤트를 보내기

// ...
{
  actions: send((context, event) => ({ ...event, type: 'SOME_EVENT' }), {
    to: (context) => context.someRef
  });
}
// ...

sendParent 액션 크리에이터를 사용하여 액터에서 부모 액터로 이벤트 보내기:

// ...
{
  actions: sendParent({ type: 'ANOTHER_EVENT' });
}
// ...

sendParent 표현식을 사용하여 액터에서 부모 액터로 데이터가 포함된 이벤트를 보냅니다.

// ...
{
  actions: sendParent((context, event) => ({
    ...context,
    type: 'ANOTHER_EVENT'
  }));
}
// ...

컨텍스트에서 액터(자식) 참조:

someService.onTransition((state) => {
  const { someRef } = state.context;

  console.log(someRef);
  // => { id: ..., send: ... }
});