Assist_Design/packages/domain/toolkit/README.md

Domain Toolkit

Utility functions and helpers for the domain layer. This package contains utilities only, not validation.

Purpose

The toolkit provides pure utility functions for common operations like:

• String manipulation
• Date/time formatting
• Currency formatting
• URL parsing and manipulation
• Type guards and assertions

Important: For validation functions (e.g., isValidEmail, isValidUuid), use packages/domain/common/validation.ts instead.

Structure

toolkit/
├── formatting/          # Formatting utilities
│   ├── currency.ts      # Currency formatting (e.g., formatCurrency)
│   ├── date.ts          # Date formatting (e.g., formatDate, formatRelativeTime)
│   ├── phone.ts         # Phone number formatting
│   └── text.ts          # Text manipulation (e.g., truncate, capitalize)
│
├── typing/              # Type utilities
│   ├── assertions.ts    # Type assertions (e.g., assertNonNull)
│   ├── guards.ts        # Type guards (e.g., isString, isNumber)
│   └── helpers.ts       # Type helper functions
│
└── validation/          # Validation utilities (NOT validation itself)
    ├── email.ts         # Email utilities (getEmailDomain, normalizeEmail)
    ├── url.ts           # URL utilities (ensureProtocol, getHostname)
    ├── string.ts        # String utilities (isEmpty, hasMinLength)
    └── helpers.ts       # Validation helpers (sanitizePagination, isInRange)

Important Distinction: Validation vs Utilities

❌ Validation (NOT in toolkit)

Validation determines if input is valid or invalid:

// These are VALIDATION functions → Use common/validation.ts
isValidEmail(email); // Returns true/false
isValidUuid(id); // Returns true/false
isValidUrl(url); // Returns true/false
validateUrlOrThrow(url); // Throws if invalid

Location: packages/domain/common/validation.ts

✅ Utilities (IN toolkit)

Utilities transform, extract, or manipulate data:

// These are UTILITY functions → Use toolkit
getEmailDomain(email); // Extracts domain from email
normalizeEmail(email); // Lowercases and trims
ensureProtocol(url); // Adds https:// if missing
getHostname(url); // Extracts hostname

Location: packages/domain/toolkit/

Usage Examples

Formatting

import { Formatting } from "@customer-portal/domain/toolkit";

const price = Formatting.formatCurrency(1000, "JPY"); // "¥1,000"
const date = Formatting.formatDate(new Date()); // "2025-10-08"

Type Guards

import { Typing } from "@customer-portal/domain/toolkit";

if (Typing.isString(value)) {
  // TypeScript knows value is string here
  console.log(value.toUpperCase());
}

URL Utilities

import { Validation } from "@customer-portal/domain/toolkit";

const fullUrl = Validation.ensureProtocol("example.com"); // "https://example.com"
const host = Validation.getHostname("https://example.com/path"); // "example.com"

Email Utilities

import { Validation } from "@customer-portal/domain/toolkit";

const domain = Validation.getEmailDomain("user@example.com"); // "example.com"
const normalized = Validation.normalizeEmail(" User@Example.COM "); // "user@example.com"

When to Use What

Task	Use	Example
Validate email format	common/validation.ts	isValidEmail(email)
Extract email domain	toolkit	Validation.getEmailDomain(email)
Validate URL format	common/validation.ts	isValidUrl(url)
Add protocol to URL	toolkit	Validation.ensureProtocol(url)
Format currency	toolkit	Formatting.formatCurrency(amount, "JPY")
Format date	toolkit	Formatting.formatDate(date)

Best Practices

1. Use validation functions for validation

   // ✅ Good
   import { isValidEmail } from "@customer-portal/domain/common/validation";
   if (!isValidEmail(email)) throw new Error("Invalid email");
   
   // ❌ Bad - don't write custom validation
   if (!email.includes("@")) throw new Error("Invalid email");
   

2. Use utility functions for transformations

   // ✅ Good
   import { Validation } from "@customer-portal/domain/toolkit";
   const clean = Validation.normalizeEmail(email);
   
   // ❌ Bad - don't duplicate utility logic
   const clean = email.trim().toLowerCase();
   

3. Don't mix validation and utilities

   // ❌ Bad - mixing concerns
   function processEmail(email: string) {
     if (!email.includes("@")) return null; // Validation
     return email.toLowerCase(); // Utility
   }
   
   // ✅ Good - separate concerns
   import { isValidEmail } from "@customer-portal/domain/common/validation";
   import { Validation } from "@customer-portal/domain/toolkit";
   
   function processEmail(email: string) {
     if (!isValidEmail(email)) return null;
     return Validation.normalizeEmail(email);
   }
   

Migration Notes

If you're refactoring existing code:

1. Validation functions → Move to common/validation.ts
2. Utility functions → Keep in or move to toolkit/
3. Business logic → Move to domain-specific validation.ts files

Related Documentation

• Validation Patterns Guide - How to implement validation
• Domain Layer Design - Overall domain architecture
• Common Validation - Validation functions

Questions?

If you're unsure whether something belongs in toolkit or common/validation:

• Ask: "Does this determine if input is valid/invalid?"

  • YES → It's validation → Use common/validation.ts
  • NO → It's a utility → Use toolkit/

• Ask: "Does this transform or extract data?"

  • YES → It's a utility → Use toolkit/
  • NO → Might be validation → Use common/validation.ts