@sandlada/common-domain

A library of reusable domain-layer objects and value objects for projects using hexagonal (ports & adapters) architecture. Provides common domain primitives — such as Gender and Duration — so you don't have to rewrite them for every project.

Domain-only. This package contains pure business logic with zero infrastructure, framework, or application-layer concerns.

---

Installation

npm install @sandlada/common-domain

Dependency: @sandlada/result

This library uses @sandlada/result for its Result types (IResultOfT, ok(), err()) and is installed automatically as a dependency.

---

Usage

Gender

A fixed-set value object with four predefined instances: Male, Female, Other, and Unknown.

import { Gender, GenderError } from '@sandlada/common-domain'

// Factory — returns ok(Gender) or err(GenderError)
const result = Gender.From({ value: 'male', displayName: 'Male' })
if (result.isSuccess) {
  console.log(result.value.toString()) // "Male"
}

// Predefined instances
console.log(Gender.Male.value)          // "male"
console.log(Gender.Female.toString())   // "Female"
console.log(Gender.Unknown.value)       // "unknown"

// Enumeration
for (const g of Gender.All) {
  console.log(g.value) // "male", "female", "other", "unknown"
}

// Invalid input produces a domain error
const invalid = Gender.From({ value: 'invalid', displayName: 'Invalid' })
if (invalid.isFailure) {
  console.log(invalid.error.code) // "InvalidValue"
}

Duration

A value object representing a length of time. Supports fixed-length units (seconds, minutes, hours, days, weeks) and calendar units (months, quarters, years) — useful for date arithmetic where months have variable lengths.

import { Duration } from '@sandlada/common-domain'

// From seconds (single number)
const fiveMinutes = Duration.From(300)
if (fiveMinutes.isSuccess) {
  console.log(fiveMinutes.value.totalSeconds) // 300
}

// From positional arguments: (minutes, seconds)
const oneHalfMin = Duration.From(1, 30)
// (hours, minutes, seconds)
const twoHours = Duration.From(2, 0, 0)

// From a named arguments object
const complex = Duration.From({ hours: 2, minutes: 30, days: 1 })
if (complex.isSuccess) {
  console.log(complex.value.toString()) // "1d 2h 30m"
}

// Calendar-aware construction
const quarter = Duration.From({ months: 3 })
console.log(quarter.value.totalMonths) // 3

Arithmetic

const a = Duration.From(60)        // 1 minute
const b = Duration.From({ hours: 1 }) // 1 hour

const sum = a.add(b)
console.log(sum.totalSeconds) // 3660

const diff = b.subtract(a)
console.log(diff.totalSeconds) // 3540

const neg = Duration.From({ years: 1 }).negate()
console.log(neg.totalMonths) // -12

Date Operations

Calendar durations automatically clamp days (e.g., Jan 31 + 1 month → Feb 28):

const oneMonth = Duration.From({ months: 1 })
const jan31 = new Date(2024, 0, 31)

const febDate = oneMonth.applyTo(jan31)
console.log(febDate.getMonth()) // 1 (February)
console.log(febDate.getDate())  // 29 (clamped to Feb 2024)

---

API

Export	Kind	Description
Gender	Value Object	Fixed-set gender with Male, Female, Other, Unknown
GenderError	Domain Error	Error for invalid gender values
Duration	Value Object	Time duration with fixed + calendar units
DurationError	Domain Error	Error for invalid duration values
DomainError	Base Class	Abstract base for all domain errors

---

MySQL DDL Reference

Each domain object in this library ships with a companion DDL file as a quick-start reference for the table structure you need in your MySQL database.

File	Domain Object	Description
gender.vo.sql	Gender	Lookup table for gender values
duration.vo.sql	Duration	Reference columns for duration storage

These files contain lowercase-style create table statements with snake_case identifiers — ready to adapt into your project. They are reference-only: copy, modify, and integrate them into your own migrations as needed.

See the MySQL DDL Convention in AGENTS.md for the full naming and style guide.

---

License

MIT