image
Akan.js
English
Docs (V1)
image
Akan.js
You are viewing the Akan.js v1 docs.Go to the latest v2 docs
Docs (V1)
Released under the MIT License
Official Akan.js Consulting onAkansoft
Copyright © 2026 Akan.js All rights reserved.
System managed bybassman
Introduction
• Quick Start
• How it works
• Practice a Workflow
Tutorials
• Show Details
• Modifying Status
• Interact in Service
• Displaying with Slice
• UX with Pages
• Using Scalar
• Using Insight
• Relate Data
System Architecture
• Overview
• Backend System
• Frontend System
• Environment Variables
• Primitive Scalar Types
• Domain Based Modules
• CSS
Module 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
Introduction
• Quick Start
• How it works
• Practice a Workflow
Tutorials
• Show Details
• Modifying Status
• Interact in Service
• Displaying with Slice
• UX with Pages
• Using Scalar
• Using Insight
• Relate Data
System Architecture
• Overview
• Backend System
• Frontend System
• Environment Variables
• Primitive Scalar Types
• Domain Based Modules
• CSS
Module 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
Previous
model.dictionary.ts
Next
model.service.ts

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:
methodDescriptionExample
.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:
methodDescriptionExample
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()

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:
methodDescriptionExample
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.

Auto-generated Query Methods

For each query defined in Filter, 10 utility methods are auto-generated:
methodDescriptionExample
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
methodDescriptionExample
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
Custom Loaders
Middleware Class
Document in Service
Best Practices

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.
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
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'
💡 DataLoaders automatically batch multiple .load() calls into a single DB query, improving performance in GraphQL resolvers and loops.