YouBothAgent▾
You — Business rules and flows you own. Read these yourself.
Both — Know the idea; your agent follows the details.
Agent — Conventions and references your agent follows. Look up as needed.
Introduction▾
Tutorials▾
System Architecture▾
Module Convention▾
Scalar Convention▾
model.service.ts
The service file is the heart of your business logic. It handles complex operations, coordinates between different modules, and ensures atomic data consistency.
🧠Business Logic
Validations, calculations, and decision-making logic reside here, separate from data definitions.
Service Class Structure
Services are defined using the serve() function, which binds the database model and allows dependency injection via a callback.
product.service.ts
Methods & Variables
The serve() function automatically equips your class with CRUD methods and access to the underlying model.
1.1. Predefined Variables
fieldDescription
<MODEL_NAME>Model
Database model instance declared in model.document.ts
logger
Built-in logger module for stdout logging
1.2. Predefined Methods (CRUD)
methodDescription
getProduct(id: string)
Load document by ID. Throws error if not found.
loadProduct(id?: string)
Load document by ID. Returns null if not found.
loadProductMany(ids: string[])
Batch load documents by IDs. Returns array of docs or nulls.
createProduct(data: db.ProductInput)
Create a new document with input data.
updateProduct(id: string, data: Partial<db.Product>)
Update document by ID. Returns updated document.
removeProduct(id: string)
Soft-delete document by ID. Sets status to 'archived'.
searchProduct(searchText: string, queryOption?: ListQueryOption)
Search documents by text. Returns docs and count.
searchDocsProduct(searchText: string, queryOption?: ListQueryOption)
Search documents by text. Returns docs only.
searchCountProduct(searchText: string)
Count documents matching search text.
1.3. Query Based Methods
Methods generated from 'Filter' definitions in model.document.ts.
methodDescription
list<Query>(...args, option?)
List documents matching defined query.
listIds<Query>(...args, option?)
List document IDs matching defined query.
find<Query>(...args, option?)
Find single document matching defined query.
findId<Query>(...args, option?)
Find single document ID matching defined query.
pick<Query>(...args, option?)
Find single document matching query. Throws if not found.
pickId<Query>(...args, option?)
Find single document ID matching query. Throws if not found.
exists<Query>(...args)
Check if document exists matching defined query. Returns ID or null.
count<Query>(...args)
Count documents matching defined query.
insight<Query>(...args)
Get aggregated statistics matching defined query.
query<Query>(...args)
Get the raw query object defined in Filter.
Middleware Methods
You can override specific middleware methods to hook into the data creation process.
methodDescription
_preCreate(data)
Hook called before creation. Return modified data.
_postCreate(doc)
Hook called after creation. Return modified doc.
_preUpdate(id, data)
Hook called before update.
_postUpdate(doc)
Hook called after update.
_preRemove(id)
Hook called before removal.
_postRemove(doc)
Hook called after removal.
listenPre(type, listener)
Register dynamic pre-hook listener.
listenPost(type, listener)
Register dynamic post-hook listener.
Example: _preCreate
Dependency Injection
Dependencies are injected via the callback function in serve(). This ensures type safety and prevents circular dependency issues.
3.1. Supported Injections
methodDescription
service<T>()
Inject other services.
use<T>()
Inject external classes or variables.
env<T>(key, factory?)
Inject environment variable. Throws if missing.
envOptional<T>(key, factory?)
Inject environment variable safely. Returns undefined if missing.
generate<T>(factory)
Generate a value dynamically based on environment.
signal<T>()
Inject signal (Websocket/Queue) module.
3.2. Examples
Injecting Services & Envs
⚠️Injection Setup
Global injections must be registered in lib/option.ts using useGlobals().
lib/option.ts
Service Best Practices
1️⃣Keep Document Pure
Put simple state changes in Document methods. Put complex logic involving other services in Service methods.
2️⃣Use Auto-generated Methods
Prefer auto-generated list/find methods over raw DB queries. They maintain consistency and type safety.