model.constant.ts

A constant file defines the business shape of a model. It declares fields, enums, embedded scalar values, generated views, and small helper behavior that should travel with the data type.

The current Akan pattern is based on via(). Each class builds a different view of the same business model, and later document, service, signal, store, and UI code reuse those generated types.

Model Layering Pattern

Most document models use the same five layers: Input, Object, Light, full Model, and Insight. Start with this shape unless the model is a small embedded scalar.

Input

Fields accepted when creating or editing the model.

Object

Input plus stored fields controlled by the system or service.

Light

Small view for list, relation, and card-style queries.

Model

Full model that combines Object and Light, often with static helpers.

Insight

Aggregation or reporting fields for analytics.

ticket.constant.ts

Fields And enumOf

Use field() to describe values and enumOf() to define categorical values. Keep field options close to business needs: defaults, optional values, references, hidden or secret fields, examples, and aggregation.

status enum

practical field options

field.hidden And field.secret

field.hidden() and field.secret() are helper forms for fields that should not behave like normal public properties. Both create hidden, nullable fields. field.secret() also sets select: false, so it is not selected by default when documents are loaded.

field.hidden()

Use it for internal state that may exist on the document but should not be treated as a normal visible field.

field.secret()

Use it for sensitive values such as password, phone, token, account id, wallet, or notification settings that should not be selected by default.

user.constant.ts

Extending Generated Models

Some apps extend generated model hooks from the app or library template. Spread generated inputs, objects, lights, models, and insights into via() so custom fields and generated fields stay together.

user.constant.ts

Light And Full Model Helpers

A constant class can include small helper methods when the behavior belongs to the data type itself. Instance helpers fit Light classes, while list or lookup helpers often fit the full Model class as static methods.

LightBoard helper

Board static helper

Resolved Fields

Light and full models can declare resolved fields with the resolve helper. A resolved field is not stored directly on the document. The constant declares the field name and type, and an internal signal defines how to calculate it when the client fetches the model.

This is useful for viewer-specific values such as whether the current user liked a story, read count for this user, permission flags, or other values that depend on request context.

story.constant.ts

story.signal.ts

Scalar Constants And Static Utilities

Scalars are embedded values without their own collection. They can still expose useful static helpers, especially for calculations or transforms that belong to the scalar value.

coordinate.constant.ts

Insight Constants

Insight constants describe aggregated or reporting-oriented values. Use them for dashboard counts, summaries, and grouped statistics instead of mixing reporting fields into the normal model shape.

ticket.constant.ts

Practical Rules

Use the Input, Object, Light, Model, Insight layers for document models unless the value is a small embedded scalar.

Use enumOf for business categories and refer to its value type when you need the union.

Use generated extension spreads when the app template provides inputs, objects, lights, models, or insights.

Use field.hidden for hidden internal values and field.secret for sensitive values that should not be selected by default.

Use resolve fields for values calculated by signal context instead of storing viewer-specific data directly on the model.

Put pure helper behavior on constants only when it clearly belongs to the data type.

Import other constants from direct file paths to avoid circular barrel references.