Scalar Document Implementation Guide

The document file (*.document.ts) is an optional file that extends your scalar with custom methods using the by() function. While constant.ts defines the data structure and dictionary.ts provides translations, document.ts adds runtime behavior and utility methods.

This guide covers the by() function syntax, when to use document.ts, and patterns for adding methods.

📁File Structure

🎯When to Use

Add computed properties
Add utility methods
Add data transformation logic
Add validation helpers

Basic Syntax with by()

The by() function wraps your constant class and enables you to add instance methods. It preserves all the fields and types from the constant while allowing you to extend functionality.

Basic Structure

Let's understand each part:

📦import { by } from '@akanjs/document'

Import the by() function from @akanjs/document. This is the only import needed for scalar documents.

🔗import * as cnst

Import the constant module as 'cnst' namespace. This convention prevents naming conflicts between the constant class and document class.

⚡extends by(cnst.YourScalar)

The by() function creates a base class from your constant. Your document class extends this to inherit all fields and add methods.

Minimal Document (No Methods)

Most scalar document files are minimal - they simply wrap the constant class without adding any methods. This is useful for consistency and potential future extensions.

Even empty document files are useful! They provide a clear extension point for future methods and maintain a consistent file structure.

Adding Custom Methods

You can add instance methods directly in the class body. These methods have access to all fields via 'this' and can perform calculations, validations, or transformations.

price.document.ts

Common patterns for document methods:

🧮Computed Properties

Methods that calculate values from existing fields (e.g., getPercentage(), getTotal()).

✅Status Checkers

Methods that check conditions and return booleans (e.g., isActive(), isExpired(), hasStock()).

🔄Data Transformers

Methods that transform or format data (e.g., getFormattedDate(), getDisplayName()).

🔍Parsers/Extractors

Methods that extract specific information from fields (e.g., getService() parsing pod names).

Method Examples

Here are practical examples of methods you might add to scalar documents:

Stock - Computed & Status

DateRange - Formatting

Constant vs Document

You can define methods in either constant.ts or document.ts. Here's when to use each:

📋constant.ts

Simple methods that only use field values
Methods needed on both client and server
No external dependencies needed

📄document.ts

Methods with complex logic
Methods that may need server-side imports
Separation of concerns (schema vs behavior)

Methods in constant.ts

Note: If you define methods in both constant.ts and document.ts, the document.ts methods will override constant.ts methods.

Best Practices

✓Use 'cnst' Namespace

Always import constant as 'cnst' to avoid naming conflicts: import * as cnst from './scalar.constant'

✓Match Class Names

The document class name should match the constant class name for consistency.

✓Keep Methods Pure

Scalar document methods should be pure functions that don't modify state or have side effects.

✓Use Descriptive Names

Use clear method names: getPercentage(), isActive(), hasStock() rather than calc(), check(), has().

✓Create Even If Empty

Create document.ts even without methods for consistency and future extensibility.

Implementation Checklist

File location: __scalar/<name>/<name>.document.ts
Import by from '@akanjs/document'
Import constant as 'cnst' namespace
Class name matches constant class name
Extends by(cnst.ClassName)
Export the document class
Methods use 'this' to access fields
Methods are pure (no side effects)

💡 Pro Tips:

• Document methods are available on both client and server - be careful with server-only imports
• For simple scalars with no methods, an empty document class is perfectly fine
• Consider defining frequently-used methods in constant.ts for better tree-shaking

Scalar Document Implementation Guide

Basic Syntax with by()

Minimal Document (No Methods)

Adding Custom Methods

Method Examples

Constant vs Document

Best Practices

Implementation Checklist

Quick Start

Released under the MIT License

Official Akan.js Consulting onAkansoft

System managed bybassman