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

field	Description	Example
<MODEL_NAME>Model	Database model instance declared in model.document.ts
logger	Built-in logger module for stdout logging

<MODEL_NAME>Model

Database model instance declared in model.document.ts

logger

Built-in logger module for stdout logging

1.2. Predefined Methods (CRUD)

method	Description	Example
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.

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.

method	Description	Example
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.

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.

method	Description	Example
_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.

_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)

listenPost(type, 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

method	Description	Example
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.

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.

model.service.ts

Service Class Structure

Methods & Variables

Middleware Methods

Dependency Injection

Service Best Practices

model.document.ts

model.signal.ts

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

field	Description	Example
<MODEL_NAME>Model	Database model instance declared in model.document.ts
logger	Built-in logger module for stdout logging

<MODEL_NAME>Model

Database model instance declared in model.document.ts

logger

Built-in logger module for stdout logging

1.2. Predefined Methods (CRUD)

method	Description	Example
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.

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.

method	Description	Example
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.

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.

method	Description	Example
_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.

_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)

listenPost(type, 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

method	Description	Example
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.