model.document.ts

The document file defines database operations for your module. For a high-level overview of the document schema structure (Input, Object, Light, Model), please refer to the Module Overview.

This page focuses on the detailed API methods and properties available in the Document layer.

Filter Definition - from()

The Filter class defines reusable query patterns. Each query becomes a set of auto-generated methods (list, find, count, insight, etc.).

product.document.ts

⚡Built-in Query & Sort

Every Filter automatically includes:

Using Built-in Methods

Understanding filter builder methods:

method	Description	Example
.arg(name, Type, options?)	Required parameter. Options include { ref, renderOption } for UI rendering in admin panels.
.opt(name, Type, options?)	Optional parameter. Value will be undefined if not provided. Use conditional spread in query.
.query((...args) => MongoQuery)	Returns MongoDB query object. Arguments match the order of .arg() and .opt() calls.

.arg(name, Type, options?)

Required parameter. Options include { ref, renderOption } for UI rendering in admin panels.

.opt(name, Type, options?)

Optional parameter. Value will be undefined if not provided. Use conditional spread in query.

.query((...args) => MongoQuery)

Returns MongoDB query object. Arguments match the order of .arg() and .opt() calls.

Auto-generated methods from filters:

Auto-generated Query Methods

Document Class - by()

The Document class defines instance methods that operate on individual documents. Methods should modify 'this' and return 'this' for method chaining.

product.document.ts

Built-in document methods:

method	Description	Example
this.set(data)	Set multiple fields at once. Equivalent to Object.assign(this, data)
await this.save()	Persist changes to MongoDB. Returns the saved document.
await this.refresh()	Reload document from database, discarding local changes.

this.set(data)

Set multiple fields at once. Equivalent to Object.assign(this, data)

await this.save()

Persist changes to MongoDB. Returns the saved document.

await this.refresh()

Reload document from database, discarding local changes.

💡 Best Practice: Document methods should be pure state mutations. Business logic (notifications, validations across services) belongs in the Service layer.

Model Class - into()

The Model class combines Document and Filter, adding collection-level operations. It auto-generates CRUD methods, query methods, and loaders.

into() Signature

Auto-generated CRUD Methods

The Model class automatically generates these CRUD methods based on your model name:

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.

Additional Access

Auto-generated Query Methods

For each query defined in Filter, 10 utility methods are auto-generated:

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.

Custom Loaders

The 4th argument of into() allows defining custom DataLoaders for efficient batched lookups by specific fields.

Custom Loader Definition

method	Description	Example
byField(field)	Single doc by unique field
byArrayField(field)	Multiple docs by field value
byQuery([fields])	Doc by multiple field conditions

byField(field)

Single doc by unique field

byArrayField(field)

Multiple docs by field value

byQuery([fields])

Doc by multiple field conditions

Middleware Class

The Middleware class provides access to the Mongoose schema for adding indexes and hooks. The onSchema method receives the schema for configuration.

product.document.ts

Document in Service

product.service.ts

Best Practices

1️⃣

Document methods return 'this' for chaining: product.sell(5).save()

2️⃣

Keep Document methods pure - external calls belong in Service

3️⃣

Define queries in Filter for type-safe auto-generated methods

4️⃣

Add indexes in Middleware for fields used in filters

5️⃣

Use custom loaders (byField/byArrayField) for N+1 prevention

model.document.ts

Filter Definition - from()

Document Class - by()

Model Class - into()

Auto-generated CRUD Methods

Auto-generated Query Methods

model.document.ts

The document file defines database operations for your module. For a high-level overview of the document schema structure (Input, Object, Light, Model), please refer to the Module Overview.

This page focuses on the detailed API methods and properties available in the Document layer.

Filter Definition - from()

The Filter class defines reusable query patterns. Each query becomes a set of auto-generated methods (list, find, count, insight, etc.).

product.document.ts

⚡Built-in Query & Sort

Every Filter automatically includes:

Using Built-in Methods

Understanding filter builder methods:

method	Description	Example
.arg(name, Type, options?)	Required parameter. Options include { ref, renderOption } for UI rendering in admin panels.
.opt(name, Type, options?)	Optional parameter. Value will be undefined if not provided. Use conditional spread in query.
.query((...args) => MongoQuery)	Returns MongoDB query object. Arguments match the order of .arg() and .opt() calls.

.arg(name, Type, options?)

Required parameter. Options include { ref, renderOption } for UI rendering in admin panels.

.opt(name, Type, options?)

Optional parameter. Value will be undefined if not provided. Use conditional spread in query.

.query((...args) => MongoQuery)

Returns MongoDB query object. Arguments match the order of .arg() and .opt() calls.

Auto-generated methods from filters:

Auto-generated Query Methods

Document Class - by()

The Document class defines instance methods that operate on individual documents. Methods should modify 'this' and return 'this' for method chaining.

product.document.ts

Built-in document methods:

method	Description	Example
this.set(data)	Set multiple fields at once. Equivalent to Object.assign(this, data)
await this.save()	Persist changes to MongoDB. Returns the saved document.
await this.refresh()	Reload document from database, discarding local changes.

this.set(data)

Set multiple fields at once. Equivalent to Object.assign(this, data)

await this.save()

Persist changes to MongoDB. Returns the saved document.

await this.refresh()

Reload document from database, discarding local changes.

💡 Best Practice: Document methods should be pure state mutations. Business logic (notifications, validations across services) belongs in the Service layer.

Model Class - into()

The Model class combines Document and Filter, adding collection-level operations. It auto-generates CRUD methods, query methods, and loaders.

into() Signature

Auto-generated CRUD Methods

The Model class automatically generates these CRUD methods based on your model name:

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.

Additional Access

Auto-generated Query Methods

For each query defined in Filter, 10 utility methods are auto-generated:

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.