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:
methodDescription
.arg(name, Type, options?)
Required parameter.
ref names the model an ID points at, so the admin panel offers a picker instead of a text field..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:
methodDescription
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:
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.
Additional Access
Auto-generated Query Methods
For each query defined in Filter, 10 utility methods are auto-generated:
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.
💡 The query name becomes PascalCase in method names: 'inCategory' → 'listInCategory', 'findInCategory'
Custom Loaders
The 4th argument of into() allows defining custom DataLoaders for efficient batched lookups by specific fields.
Custom Loader Definition
methodDescription
byField(field)
Single doc by unique field
byArrayField(field)
Multiple docs by field value
byQuery([fields])
Doc by multiple field conditions
💡 DataLoaders automatically batch multiple .load() calls into a single DB query, improving performance in GraphQL resolvers and loops.
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