model.service.ts

service 파일은 비즈니스 workflow가 실행되는 곳입니다. document, 다른 service, signal, external API, environment option, service lifecycle hook을 조합합니다.

하나 이상의 model, 외부 runtime 객체, background job, server-only logic이 필요한 작업은 service method에 둡니다. 단순 상태 변경은 가능하면 document에 둡니다.

Service 형태

대부분의 service는 serve(db.model, ...)로 만드는 database service입니다. 일부 service는 serve("name" as const, ...)로 만드는 plain runtime service입니다. 앱은 rest argument로 generated 또는 library service를 확장할 수도 있습니다.

story.service.ts

base.service.ts

user.service.ts

serve()가 제공하는 것

serve()는 typed service class를 만듭니다. database service에서는 model adaptor, generated document helper, logger, lifecycle hook, injected property도 함께 붙습니다.

Database service

serve(db.story, builder)는 storyModel과 __databaseModel을 자동 주입하고 getStory, loadStory, createStory, query 기반 document method 같은 generated helper를 노출합니다.

Plain service

serve("base" as const, builder)는 database model 없이 service를 만듭니다. runtime coordination, scheduled behavior, shared server feature, app-level orchestration에 사용합니다.

Service option

선택적 service option으로 service를 비활성화하거나 batch, federation 같은 server mode에만 활성화할 수 있습니다.

Extension services

injection builder 뒤에 전달한 service class들은 최종 service에 mixin됩니다. 해당 service들의 injection map과 lifecycle hook이 먼저 병합됩니다.

serve signatures

Generated Method

database service는 document 정의에서 model access와 generated helper method를 받습니다. method 이름은 model 이름과 document filter를 기준으로 생성됩니다.

Predefined Variables

field	설명	예제
<model>Model	database service에 자동으로 주입되는 database model adaptor입니다.
__databaseModel	이름이 붙은 model property와 함께 주입되는 내부 database model adaptor입니다.
logger	service log를 남기기 위한 built-in logger입니다.

<model>Model

database service에 자동으로 주입되는 database model adaptor입니다.

__databaseModel

이름이 붙은 model property와 함께 주입되는 내부 database model adaptor입니다.

logger

service log를 남기기 위한 built-in logger입니다.

Predefined Methods (CRUD)

method	설명	예제
get<Model>(id)	id로 document 하나를 불러옵니다. 없으면 error를 던집니다.
load<Model>(id?)	id로 document 하나를 불러옵니다. 없으면 null을 반환합니다.
load<Model>Many(ids)	id 배열로 document를 batch load합니다.
create<Model>(data)	input data로 document를 생성합니다.
update<Model>(id, data)	document를 수정하고 수정된 document를 반환합니다.
remove<Model>(id)	generated database service 흐름으로 document를 삭제하거나 soft-remove합니다.
search<Model>(text, option?)	document를 검색하고 docs와 count를 반환합니다.
searchDocs<Model>(text, option?)	document를 검색하고 docs만 반환합니다.
searchCount<Model>(text)	검색어와 일치하는 document 수를 반환합니다.

get<Model>(id)

id로 document 하나를 불러옵니다. 없으면 error를 던집니다.

load<Model>(id?)

id로 document 하나를 불러옵니다. 없으면 null을 반환합니다.

load<Model>Many(ids)

id 배열로 document를 batch load합니다.

create<Model>(data)

input data로 document를 생성합니다.

update<Model>(id, data)

document를 수정하고 수정된 document를 반환합니다.

remove<Model>(id)

generated database service 흐름으로 document를 삭제하거나 soft-remove합니다.

search<Model>(text, option?)

document를 검색하고 docs와 count를 반환합니다.

searchDocs<Model>(text, option?)

document를 검색하고 docs만 반환합니다.

searchCount<Model>(text)

검색어와 일치하는 document 수를 반환합니다.

Query Based Methods

Query based method는 document 파일에 선언한 filter를 기준으로 생성됩니다.

method	설명	예제
list<Query>(...args, option?)	document filter와 일치하는 목록을 조회합니다.
listIds<Query>(...args, option?)	document filter와 일치하는 id 목록을 조회합니다.
find<Query>(...args, option?)	일치하는 document 하나를 찾고 없으면 null을 반환합니다.
findId<Query>(...args, option?)	일치하는 document id 하나를 찾고 없으면 null을 반환합니다.
pick<Query>(...args, option?)	일치하는 document 하나를 찾습니다. 없으면 error를 던집니다.
pickId<Query>(...args, option?)	일치하는 document id 하나를 찾습니다. 없으면 error를 던집니다.
exists<Query>(...args)	일치하는 document가 존재하는지 확인합니다.
count<Query>(...args)	일치하는 document 수를 반환합니다.
insight<Query>(...args)	일치하는 document의 aggregated insight를 조회합니다.
query<Query>(...args)	document filter의 raw query object를 반환합니다.

list<Query>(...args, option?)

document filter와 일치하는 목록을 조회합니다.

listIds<Query>(...args, option?)

document filter와 일치하는 id 목록을 조회합니다.

find<Query>(...args, option?)

Service 확장

generated app domain은 ...model.services로 library service 동작을 확장할 수 있습니다. shared behavior는 generated/library layer에 두고, app service는 app-specific integration을 추가합니다.

apps/myapp/lib/user/user.service.ts

Injection Builder

serve()의 두 번째 인자는 injection builder입니다. database, service, use, signal, plug, env, memory helper를 받습니다. 반환한 key는 service instance의 readonly property가 됩니다.

service injection shape

Injection 타입

값이 어디에서 오는지에 따라 injection helper를 선택합니다. service dependency, global runtime object, signal, adaptor, environment option, cached memory는 각각 다른 helper를 사용합니다.

database()

database model injection은 database service에서 보통 자동입니다. 직접 database()를 선언하기보다 storyModel 같은 generated property를 사용합니다.

model access

service<T>()

다른 Akan service를 주입합니다. runtime이 등록된 service를 찾을 수 있도록 property key는 Service로 끝나야 합니다.

story.service.ts

use<T>()

API client, host 값, srvkit의 server-only wrapper처럼 전역 등록된 runtime object를 주입합니다.

user.service.ts

signal<T>()

service가 background job을 queue하거나 server event를 publish할 수 있도록 server signal을 주입합니다.

dbBackup.service.ts

plug(Adaptor)

adaptor instance를 주입합니다. adaptor role이 등록되어 있으면 runtime이 해당 role implementation을 resolve한 뒤 주입합니다.

file.service.ts

env(factory)

module option 또는 process env에서 파생된 값을 주입합니다. 현재 패턴은 env("KEY")가 아니라 factory function입니다.

devProject.service.ts

memory(modelRef, opts)

service가 소유하는 memory를 주입합니다. local memory는 instance에 writable 값으로 붙고, non-local memory는 등록된 cache adaptor를 사용합니다. Map memory는 of option이 필요합니다.

memory examples

비즈니스 로직 흐름

service method는 비즈니스 action처럼 읽혀야 합니다. document를 load하고, document method를 호출하고, 다른 service와 조합하고, log를 갱신하고, signal을 queue하는 흐름을 한 곳에서 표현할 수 있습니다.

story.service.ts

dbBackup.service.ts

Lifecycle Hook

create, update, remove, init, destroy 전후에 항상 실행되어야 하는 규칙에는 hook을 사용합니다. 특정 business action에서만 필요한 동작이라면 일반 service method를 선호하세요.

method	설명	예제
_preCreate(data)	create 전에 실행됩니다. 계속 진행하려면 input data를 반환합니다.
_postCreate(doc)	create 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.
_preUpdate(id, data)	update 전에 실행됩니다. 계속 진행하려면 update data를 반환합니다.
_postUpdate(doc)	update 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.
pre remove hook	remove 전에 실행됩니다.
_postRemove(doc)	remove 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.

_preCreate(data)

create 전에 실행됩니다. 계속 진행하려면 input data를 반환합니다.

_postCreate(doc)

create 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.

_preUpdate(id, data)

update 전에 실행됩니다. 계속 진행하려면 update data를 반환합니다.

_postUpdate(doc)

update 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.

pre remove hook

remove 전에 실행됩니다.

_postRemove(doc)

remove 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.

pre/post database hooks

service lifecycle

실전 규칙

여러 model, service, signal, external API를 조합하는 workflow는 service method에 둡니다.

하나의 document에 대한 단순 상태 변경은 document method에 두고, 저장이 필요하면 service에서 .save()를 호출합니다.

주입되는 service property는 Service suffix로, signal property는 Signal suffix로 끝나게 이름을 짓습니다.

외부 패키지는 srvkit에서 감싸고 use 또는 adaptor 값으로 등록한 뒤 service 파일에 주입합니다.

generated/library behavior는 service extension으로 확장하고, app-specific integration은 app service에 둡니다.

service 간 순환 의존성을 피합니다. 두 service가 서로 필요하다면 shared operation을 더 작은 service나 srvkit helper로 분리합니다.

field

설명

예제

<model>Model

database service에 자동으로 주입되는 database model adaptor입니다.

__databaseModel

이름이 붙은 model property와 함께 주입되는 내부 database model adaptor입니다.

logger

service log를 남기기 위한 built-in logger입니다.

method

설명

예제

get<Model>(id)

id로 document 하나를 불러옵니다. 없으면 error를 던집니다.

load<Model>(id?)

id로 document 하나를 불러옵니다. 없으면 null을 반환합니다.

load<Model>Many(ids)

id 배열로 document를 batch load합니다.

create<Model>(data)

input data로 document를 생성합니다.

update<Model>(id, data)

document를 수정하고 수정된 document를 반환합니다.

remove<Model>(id)

generated database service 흐름으로 document를 삭제하거나 soft-remove합니다.

search<Model>(text, option?)

document를 검색하고 docs와 count를 반환합니다.

searchDocs<Model>(text, option?)

document를 검색하고 docs만 반환합니다.

searchCount<Model>(text)

검색어와 일치하는 document 수를 반환합니다.

method

설명

예제

list<Query>(...args, option?)

document filter와 일치하는 목록을 조회합니다.

listIds<Query>(...args, option?)

document filter와 일치하는 id 목록을 조회합니다.

find<Query>(...args, option?)

일치하는 document 하나를 찾고 없으면 null을 반환합니다.

findId<Query>(...args, option?)

일치하는 document id 하나를 찾고 없으면 null을 반환합니다.

pick<Query>(...args, option?)

일치하는 document 하나를 찾습니다. 없으면 error를 던집니다.

pickId<Query>(...args, option?)

일치하는 document id 하나를 찾습니다. 없으면 error를 던집니다.

exists<Query>(...args)

일치하는 document가 존재하는지 확인합니다.

count<Query>(...args)

일치하는 document 수를 반환합니다.

insight<Query>(...args)

일치하는 document의 aggregated insight를 조회합니다.

query<Query>(...args)

document filter의 raw query object를 반환합니다.

method

설명

예제

_preCreate(data)

create 전에 실행됩니다. 계속 진행하려면 input data를 반환합니다.

_postCreate(doc)

create 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.

_preUpdate(id, data)

update 전에 실행됩니다. 계속 진행하려면 update data를 반환합니다.

_postUpdate(doc)

update 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.

pre remove hook

remove 전에 실행됩니다.

_postRemove(doc)

remove 후에 실행됩니다. 계속 진행하려면 document를 반환합니다.