model.service.ts

A service file is where business workflows run. It coordinates documents, other services, signals, external APIs, environment options, and service lifecycle hooks.

Use service methods for operations that need more than one model, external runtime objects, background jobs, or server-only logic. Keep simple state changes on the document when possible.

Service Shapes

Most services are database services created with serve(db.model, ...). Some services are plain runtime services created with serve("name" as const, ...). Apps can also extend generated or library services with the rest argument.

story.service.ts

base.service.ts

user.service.ts

What serve() Gives You

serve() creates a typed service class. For database services, it also adds the model adaptor, generated document helpers, logger, lifecycle hooks, and injected properties.

Database service

serve(db.story, builder) automatically injects storyModel and __databaseModel, then exposes generated helpers such as getStory, loadStory, createStory, and query-based document methods.

Plain service

serve("base" as const, builder) creates a service without a database model. Use it for runtime coordination, scheduled behavior, shared server features, or app-level orchestration.

Service option

The optional service option can disable a service or limit it to a server mode such as batch or federation.

Extension services

Extra service classes passed after the injection builder are mixed into the final service. Their injection maps and lifecycle hooks are merged first.

serve signatures

Generated Methods

Database services receive model access and generated helper methods from the document definition. These names are based on the model name and document filters.

Predefined Variables

field	Description	Example
<model>Model	Database model adaptor automatically injected for database services.
__databaseModel	Internal database model adaptor injected together with the named model property.
logger	Built-in logger for service logs.

<model>Model

Database model adaptor automatically injected for database services.

__databaseModel

Internal database model adaptor injected together with the named model property.

logger

Built-in logger for service logs.

Predefined Methods (CRUD)

method	Description	Example
get<Model>(id)	Load one document by id. Throws when it cannot be found.
load<Model>(id?)	Load one document by id. Returns null when it cannot be found.
load<Model>Many(ids)	Batch load documents by ids.
create<Model>(data)	Create a document from input data.
update<Model>(id, data)	Update a document and return the updated document.
remove<Model>(id)	Remove or soft-remove a document through the generated database service flow.
search<Model>(text, option?)	Search documents and return docs with count.
searchDocs<Model>(text, option?)	Search documents and return docs only.
searchCount<Model>(text)	Count documents that match search text.

get<Model>(id)

Load one document by id. Throws when it cannot be found.

load<Model>(id?)

Load one document by id. Returns null when it cannot be found.

load<Model>Many(ids)

Batch load documents by ids.

create<Model>(data)

Create a document from input data.

update<Model>(id, data)

Update a document and return the updated document.

remove<Model>(id)

Remove or soft-remove a document through the generated database service flow.

search<Model>(text, option?)

Search documents and return docs with count.

searchDocs<Model>(text, option?)

Search documents and return docs only.

searchCount<Model>(text)

Count documents that match search text.

Query Based Methods

Query based methods are generated from filters declared in the document file.

method	Description	Example
list<Query>(...args, option?)	List documents matching a document filter.
listIds<Query>(...args, option?)	List document ids matching a document filter.
find<Query>(...args, option?)	Find one matching document or return null.
findId<Query>(...args, option?)	Find one matching document id or return null.
pick<Query>(...args, option?)	Find one matching document. Throws when missing.
pickId<Query>(...args, option?)	Find one matching document id. Throws when missing.
exists<Query>(...args)	Check whether a matching document exists.
count<Query>(...args)	Count matching documents.
insight<Query>(...args)	Load aggregated insight for matching documents.
query<Query>(...args)	Return the raw query object for a document filter.

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

List documents matching a document filter.

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

List document ids matching a document filter.

Service Extension

Generated app domains can extend library service behavior with ...model.services. This keeps shared behavior in the generated/library layer while allowing the app service to add app-specific integrations.

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

Injection Builder

The second argument of serve() is an injection builder. It receives helpers for database, service, use, signal, plug, env, and memory. Each returned key becomes a readonly property on this service instance.

service injection shape

Injection Types

Choose the injection helper based on where the value comes from. Service dependencies, global runtime objects, signals, adaptors, environment options, and cached memory each use a different helper.

database()

Database model injection is usually automatic for database services. Use the generated property such as storyModel instead of declaring database() by hand.

model access

service<T>()

Inject another Akan service. The property key must end with Service so the runtime can resolve the registered service.

story.service.ts

use<T>()

Inject a globally registered runtime object such as an API client, host value, or server-only wrapper from srvkit.

user.service.ts

Business Logic Flow

Service methods should read like business actions. They can load documents, call document methods, coordinate other services, update logs, and enqueue signals in one transaction-like workflow.

story.service.ts

dbBackup.service.ts

Lifecycle Hooks

Use hooks when a rule must always run around create, update, remove, init, or destroy. If the behavior is only one business action, prefer a normal service method.

method	Description	Example
_preCreate(data)	Runs before create. Return the input data to continue.
_postCreate(doc)	Runs after create. Return the document to continue.
_preUpdate(id, data)	Runs before update. Return the update data to continue.
_postUpdate(doc)	Runs after update. Return the document to continue.
pre remove hook	Runs before remove.
_postRemove(doc)	Runs after remove. Return the document to continue.

_preCreate(data)

Runs before create. Return the input data to continue.

_postCreate(doc)

Runs after create. Return the document to continue.

_preUpdate(id, data)

Runs before update. Return the update data to continue.

_postUpdate(doc)

Practical Rules

Put workflows that coordinate multiple models, services, signals, or external APIs in service methods.

Use document methods for simple state changes on one document, then call .save() from the service when persistence is needed.

Name injected services with a Service suffix and injected signals with a Signal suffix.

Wrap external packages in srvkit, register them as use or adaptor values, then inject them into service files.

Use service extension for generated/library behavior, but keep app-specific integrations in the app service.

Avoid circular service dependencies. If two services need each other, move the shared operation into a smaller service or srvkit helper.

model.service.ts

Service Shapes

What serve() Gives You

field

Description

Example

<model>Model

Database model adaptor automatically injected for database services.

__databaseModel

Internal database model adaptor injected together with the named model property.

logger

Built-in logger for service logs.

method

Description

Example

get<Model>(id)

Load one document by id. Throws when it cannot be found.

load<Model>(id?)

Load one document by id. Returns null when it cannot be found.

load<Model>Many(ids)

Batch load documents by ids.

create<Model>(data)

Create a document from input data.

update<Model>(id, data)

Update a document and return the updated document.

remove<Model>(id)

Remove or soft-remove a document through the generated database service flow.

search<Model>(text, option?)

Search documents and return docs with count.

searchDocs<Model>(text, option?)

Search documents and return docs only.

searchCount<Model>(text)

Count documents that match search text.

method

Description

Example

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

List documents matching a document filter.

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

List document ids matching a document filter.

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

Find one matching document or return null.

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

Find one matching document id or return null.

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

Find one matching document. Throws when missing.

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

Find one matching document id. Throws when missing.

exists<Query>(...args)

Check whether a matching document exists.

count<Query>(...args)

Count matching documents.

insight<Query>(...args)

Load aggregated insight for matching documents.

query<Query>(...args)

Return the raw query object for a document filter.

method

Description

Example

_preCreate(data)

Runs before create. Return the input data to continue.

_postCreate(doc)

Runs after create. Return the document to continue.

_preUpdate(id, data)

Runs before update. Return the update data to continue.

_postUpdate(doc)

Runs after update. Return the document to continue.

pre remove hook

Runs before remove.

_postRemove(doc)

Runs after remove. Return the document to continue.