image
Akan.js
English
DocsConventionsReferencesCheatsheet
image
Akan.js
Akan.js v2 docs are now available.View the v1 docs
DocsConventionsReferencesCheatsheet
Released under the MIT License
Official Akan.js Consulting onAkansoft
Copyright © 2026 Akan.js All rights reserved.
System managed bybassman
Workspace Convention
• Structure
• Format & Lint
App & Library Convention
• Assets (public/ private/)
• Components (ui/)
• Server Utils (srvkit/)
• Web Utils (webkit/)
• Common Utils (common/)
• akan.config.ts
Domain Convention
• Overview
• model.constant.ts
• model.dictionary.ts
• model.document.ts
• model.service.ts
• model.signal.ts
• model.store.ts
• Model.Template.tsx
• Model.Unit.tsx
• Model.Util.tsx
• Model.View.tsx
• Model.Zone.tsx
Scalar Convention
• Overview
• scalar.constant.ts
• scalar.dictionary.ts
• scalar.document.ts
• Scalar.Template.tsx
• Scalar.Unit.tsx
Service Convention
• Overview
• service.dictionary.ts
• service.service.ts
• service.signal.ts
• service.store.ts
• Service.Util.tsx
• Service.Zone.tsx
Workspace Convention
• Structure
• Format & Lint
App & Library Convention
• Assets (public/ private/)
• Components (ui/)
• Server Utils (srvkit/)
• Web Utils (webkit/)
• Common Utils (common/)
• akan.config.ts
Domain Convention
• Overview
• model.constant.ts
• model.dictionary.ts
• model.document.ts
• model.service.ts
• model.signal.ts
• model.store.ts
• Model.Template.tsx
• Model.Unit.tsx
• Model.Util.tsx
• Model.View.tsx
• Model.Zone.tsx
Scalar Convention
• Overview
• scalar.constant.ts
• scalar.dictionary.ts
• scalar.document.ts
• Scalar.Template.tsx
• Scalar.Unit.tsx
Service Convention
• Overview
• service.dictionary.ts
• service.service.ts
• service.signal.ts
• service.store.ts
• Service.Util.tsx
• Service.Zone.tsx
Previous
model.document.ts
Next
model.signal.ts

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
fieldDescriptionExample
<model>ModelDatabase model adaptor automatically injected for database services.
__databaseModelInternal database model adaptor injected together with the named model property.
loggerBuilt-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)
methodDescriptionExample
get<Model>(id)

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.
methodDescriptionExample
_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 hookRuns 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
Generated Methods
Service Extension
Injection Builder
Injection Types
Business Logic Flow
Lifecycle Hooks
Practical Rules
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.
methodDescriptionExample
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.

signal<T>()
Inject a server signal so the service can enqueue background jobs or publish server events.
dbBackup.service.ts
plug(Adaptor)
Inject an adaptor instance. If an adaptor role is registered, the runtime resolves the role implementation before injection.
file.service.ts
env(factory)
Inject a value derived from module options or process env. The current pattern is a factory function, not env("KEY").
devProject.service.ts
memory(modelRef, opts)
Inject memory owned by the service. local memory is writable on the instance; non-local memory uses the registered cache adaptor. Map memory requires an of option.
memory examples

Runs after update. Return the document to continue.

pre remove hook

Runs before remove.

_postRemove(doc)

Runs after remove. Return the document to continue.

pre/post database hooks
service lifecycle
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.