model.signal.ts

Signal은 module의 외부 interface를 정의합니다. service logic을 generated client API, list store, realtime channel, server-side job에 연결합니다.

Internal

resolved field, cron job, lifecycle hook, background process 같은 server-only 작업입니다.

Endpoint

fetch, websocket message, pubsub으로 노출되는 public API와 realtime handler입니다.

Slice

generated store, pagination, insight loading이 사용하는 frontend-facing list surface입니다.

story.signal.ts

Generated signal 확장

app domain이 generated 또는 library 동작을 확장할 때는 inherited signal을 마지막에 spread합니다. base internal, slice, endpoint를 유지하면서 app 전용 method를 추가할 수 있습니다.

user.signal.ts

Internal 작업 정의

page에서 직접 호출하는 API가 아니라 server runtime에 속하는 작업에는 internal()을 사용합니다. resolved field, scheduled task, lifecycle hook, queue job이 여기에 포함됩니다.

method	설명	예제
resolveField(ReturnType)	constant model에 선언된 resolved field를 계산합니다. parent document가 exec에 기본으로 전달됩니다.
interval(ms)	지정한 millisecond 간격으로 server task를 반복 실행합니다.
cron(expression)	cron expression으로 scheduled work를 실행합니다. batch job에는 serverMode option과 함께 자주 사용합니다.
initialize(options?) / destroy(options?)	server process가 시작되거나 종료될 때 setup 또는 teardown logic을 실행합니다.
process(ReturnType)	background queue job을 정의합니다. msg(...)로 job payload를 설명합니다.

resolveField(ReturnType)

constant model에 선언된 resolved field를 계산합니다. parent document가 exec에 기본으로 전달됩니다.

interval(ms)

지정한 millisecond 간격으로 server task를 반복 실행합니다.

cron(expression)

cron expression으로 scheduled work를 실행합니다. batch job에는 serverMode option과 함께 자주 사용합니다.

initialize(options?) / destroy(options?)

server process가 시작되거나 종료될 때 setup 또는 teardown logic을 실행합니다.

process(ReturnType)

background queue job을 정의합니다. msg(...)로 job payload를 설명합니다.

story.signal.ts

Public API 정의

client가 호출할 수 있는 API method에는 endpoint()를 사용합니다. endpoint builder는 read/write API와 realtime surface를 다룹니다.

Method Types

method	설명	예제
query(ReturnType, options?)	읽기 API입니다. 단일 model, 계산된 데이터, public file을 불러올 때 사용합니다.
mutation(ReturnType, options?)	쓰기 API입니다. create, update, delete 또는 business action에 사용합니다.
message(ReturnType, options?)	WebSocket message handler입니다. msg(...)로 들어오는 payload field를 정의합니다.
pubsub(ReturnType, options?)	Realtime subscription channel입니다. room(...)으로 subscription room을 정의합니다.

query(ReturnType, options?)

읽기 API입니다. 단일 model, 계산된 데이터, public file을 불러올 때 사용합니다.

mutation(ReturnType, options?)

쓰기 API입니다. create, update, delete 또는 business action에 사용합니다.

message(ReturnType, options?)

WebSocket message handler입니다. msg(...)로 들어오는 payload field를 정의합니다.

pubsub(ReturnType, options?)

Realtime subscription channel입니다. room(...)으로 subscription room을 정의합니다.

Parameter Builders

parameter builder는 각 값이 어디에서 오는지 설명합니다. 선언 순서가 exec argument 순서가 됩니다. required argument가 nullable argument 뒤에 올 수 없으므로 nullable argument는 뒤쪽에 두세요.

field	설명	예제
.param(name, Type, options?)	필수 path-style argument입니다. query, mutation, slice list method에서 자주 사용합니다.
.search(name, Type, options?)	optional search/query argument입니다. 기본적으로 nullable입니다.
.body(name, Type, options?)	request body 값이며 mutation API에서 주로 사용합니다.
.msg(name, Type, options?)	message 또는 process payload argument입니다.
.room(name, Type, options?)	pubsub subscription channel의 realtime room key입니다.
.with(InternalArg, options?)	Self, Req, Res, Ws 또는 custom internal arg처럼 server에서 주입되는 context입니다.

.param(name, Type, options?)

필수 path-style argument입니다. query, mutation, slice list method에서 자주 사용합니다.

.search(name, Type, options?)

optional search/query argument입니다. 기본적으로 nullable입니다.

.body(name, Type, options?)

request body 값이며 mutation API에서 주로 사용합니다.

.msg(name, Type, options?)

message 또는 process payload argument입니다.

.room(name, Type, options?)

pubsub subscription channel의 realtime room key입니다.

.with(InternalArg, options?)

Self, Req, Res, Ws 또는 custom internal arg처럼 server에서 주입되는 context입니다.

Endpoint Example

story.signal.ts

Realtime Example

chatRoom.signal.ts

Public Path Endpoints

sitemap.xml처럼 일반 API route가 아닌 public path로 method를 노출해야 할 때 endpoint option을 사용합니다.

site.signal.ts

Client Usage (fetch)

generated fetch method는 page loader, component, store, client action에서 endpoint method를 호출할 때 사용합니다.

page.tsx

표준 Model API

Akan은 일반적인 view, edit, merge 흐름을 위한 표준 model API를 생성합니다. 비즈니스 action에 고유한 이름이나 동작이 필요할 때 custom endpoint를 추가합니다.

method	설명	예제
view[Model](id)	model module에서 생성된 detail-view 데이터를 불러옵니다.
edit[Model](id)	model module에서 생성된 edit-view 데이터를 불러옵니다.
merge[Model](id, data)	generated module API를 통해 model data를 생성하거나 수정합니다.

view[Model](id)

model module에서 생성된 detail-view 데이터를 불러옵니다.

edit[Model](id)

model module에서 생성된 edit-view 데이터를 불러옵니다.

merge[Model](id, data)

generated module API를 통해 model data를 생성하거나 수정합니다.

Slice와 Store 정의

page용 list surface를 정의할 때 slice()를 사용합니다. slice는 init()에서 시작해 param, search value, internal arg를 받고 service query를 반환합니다.

root guard는 generated slice surface에 적용됩니다. init({ guards })에 전달한 method guard는 특정 list에만 적용됩니다.

Server Definition

story.signal.ts

Slice Auto-Generated Methods

slice definition은 list, insight, init fetch method를 생성합니다. 이 method들은 보통 store와 zone UI code에서 사용합니다.

method	설명	예제
[model]List[Suffix](...args, skip, limit, sort)	slice definition에 대한 paginated list를 불러옵니다.
[model]Insight[Suffix](...args)	같은 slice query에 대한 aggregation data를 불러옵니다.
init[Model](query?, option?)	기본 model list를 list와 insight data로 초기화합니다.
init[Model][Suffix](...args)	signal.ts에 선언한 arg를 사용해 named slice list를 초기화합니다.

[model]List[Suffix](...args, skip, limit, sort)

slice definition에 대한 paginated list를 불러옵니다.

[model]Insight[Suffix](...args)

같은 slice query에 대한 aggregation data를 불러옵니다.

init[Model](query?, option?)

기본 model list를 list와 insight data로 초기화합니다.

init[Model][Suffix](...args)

signal.ts에 선언한 arg를 사용해 named slice list를 초기화합니다.

Client Usage

page.tsx

Builder 함수 타입

위 builder 함수들은 framework type과 직접 연결됩니다. endpoint builder는 EndpointInfo, slice init은 SliceInfo, internal builder는 InternalInfo를 만듭니다.

Endpoint builders

query(Return), mutation(Return), message(Return), pubsub(Return)

Slice builder

init(signalOption?)

Internal builders

resolveField(Return), interval(ms), cron(expr), timeout(ms), initialize(), destroy(), process(Return)

실전 규칙

server-only job, resolved field, queue process, lifecycle hook에는 Internal을 사용합니다.

명시적인 client call, mutation, websocket message, pubsub subscription에는 Endpoint를 사용합니다.

generated store, pagination, insight loading이 필요한 list surface에는 Slice를 사용합니다.

generated 또는 library domain을 확장할 때는 ...model.internals, ...model.slices, ...model.endpoints를 사용합니다.

signal에서 다른 service를 this.*Service로 사용해야 하면 srv.model.with(otherSrv)를 사용합니다.

required argument가 nullable argument 뒤에 올 수 없으므로 nullable argument는 뒤쪽에 둡니다.

method

설명

예제

resolveField(ReturnType)

constant model에 선언된 resolved field를 계산합니다. parent document가 exec에 기본으로 전달됩니다.

interval(ms)

지정한 millisecond 간격으로 server task를 반복 실행합니다.

cron(expression)

cron expression으로 scheduled work를 실행합니다. batch job에는 serverMode option과 함께 자주 사용합니다.

initialize(options?) / destroy(options?)

server process가 시작되거나 종료될 때 setup 또는 teardown logic을 실행합니다.

process(ReturnType)

background queue job을 정의합니다. msg(...)로 job payload를 설명합니다.

method

설명

예제

query(ReturnType, options?)

읽기 API입니다. 단일 model, 계산된 데이터, public file을 불러올 때 사용합니다.

mutation(ReturnType, options?)

쓰기 API입니다. create, update, delete 또는 business action에 사용합니다.

message(ReturnType, options?)

WebSocket message handler입니다. msg(...)로 들어오는 payload field를 정의합니다.

pubsub(ReturnType, options?)

Realtime subscription channel입니다. room(...)으로 subscription room을 정의합니다.

field

설명

예제

.param(name, Type, options?)

필수 path-style argument입니다. query, mutation, slice list method에서 자주 사용합니다.

.search(name, Type, options?)

optional search/query argument입니다. 기본적으로 nullable입니다.

.body(name, Type, options?)

request body 값이며 mutation API에서 주로 사용합니다.

.msg(name, Type, options?)

message 또는 process payload argument입니다.

.room(name, Type, options?)

pubsub subscription channel의 realtime room key입니다.

.with(InternalArg, options?)

Self, Req, Res, Ws 또는 custom internal arg처럼 server에서 주입되는 context입니다.

method

설명

예제

view[Model](id)

model module에서 생성된 detail-view 데이터를 불러옵니다.

edit[Model](id)

model module에서 생성된 edit-view 데이터를 불러옵니다.

merge[Model](id, data)

generated module API를 통해 model data를 생성하거나 수정합니다.

method

설명

예제

[model]List[Suffix](...args, skip, limit, sort)

slice definition에 대한 paginated list를 불러옵니다.

[model]Insight[Suffix](...args)

같은 slice query에 대한 aggregation data를 불러옵니다.

init[Model](query?, option?)

기본 model list를 list와 insight data로 초기화합니다.

init[Model][Suffix](...args)

signal.ts에 선언한 arg를 사용해 named slice list를 초기화합니다.