domain-modeling

name	domain-modeling
description	Create production-ready Effect domain models using Schema.TaggedStruct for ADTs, Schema.Data for automatic equality, with comprehensive predicates, orders, guards, and match functions. Use when modeling domain entities, value objects, or any discriminated union types.

Effect Domain Modeling Skill

Use this skill when creating domain models, entities, value objects, or any types that represent core business concepts. This skill covers the complete lifecycle from type definition to runtime utilities.

Core Pattern: Schema.TaggedStruct + Schema.Data

The foundation of Effect domain modeling combines three key features:

1. Schema.TaggedStruct - Automatic _tag discriminator for union types
2. Schema.Data - Automatic Equal implementation for structural equality
3. Schema.decodeSync - Type-safe constructors with validation

import { Schema, Equal } from "effect"

// Define each variant with TaggedStruct
export const Pending = Schema.TaggedStruct("pending", {
  id: Schema.String,
  createdAt: Schema.DateTimeUtcFromSelf,
}).pipe(
  Schema.Data, // Automatic Equal.Symbol implementation
  Schema.annotations({
    identifier: "Pending",
    title: "Pending Task",
    description: "A task that has been created but not yet started",
  })
)

export const Active = Schema.TaggedStruct("active", {
  id: Schema.String,
  createdAt: Schema.DateTimeUtcFromSelf,
  startedAt: Schema.DateTimeUtcFromSelf,
}).pipe(
  Schema.Data,
  Schema.annotations({
    identifier: "Active",
    title: "Active Task",
    description: "A task that is currently being worked on",
  })
)

export const Completed = Schema.TaggedStruct("completed", {
  id: Schema.String,
  createdAt: Schema.DateTimeUtcFromSelf,
  completedAt: Schema.DateTimeUtcFromSelf,
}).pipe(
  Schema.Data,
  Schema.annotations({
    identifier: "Completed",
    title: "Completed Task",
    description: "A task that has been finished",
  })
)

// Union type
export const Task = Schema.Union(Pending, Active, Completed).pipe(
  Schema.annotations({
    identifier: "Task",
    title: "Task",
    description: "A task can be pending, active, or completed",
  })
)

export type Task = Schema.Schema.Type<typeof Task>

// Export member types for refinements
export type Pending = Schema.Schema.Type<typeof Pending>
export type Active = Schema.Schema.Type<typeof Active>
export type Completed = Schema.Schema.Type<typeof Completed>

Why This Pattern?

Schema.TaggedStruct Benefits:

• Automatically adds _tag discriminator (no manual Schema.Literal)
• The _tag is applied automatically in constructors
• Cleaner than Schema.Struct with manual tag fields
• Enables exhaustive pattern matching

Schema.Data Benefits:

• Implements Equal.Symbol automatically
• Enables Equal.equals(a, b) for structural equality
• No manual equality implementation needed
• Works correctly with nested structures

Schema.annotations Benefits:

• Self-documenting schemas with identifier, title, description
• Better error messages in validation failures
• Enables schema introspection

Mandatory Module Exports

Every domain model module MUST include:

1. Type Definition with Schemas

// Export both schema and type for each variant
export const Admin = Schema.TaggedStruct("Admin", {
  id: Schema.String,
  name: Schema.String,
  permissions: Schema.Array(Schema.String),
}).pipe(Schema.Data)

export type Admin = Schema.Schema.Type<typeof Admin>

export const Customer = Schema.TaggedStruct("Customer", {
  id: Schema.String,
  name: Schema.String,
  tier: Schema.Union(
    Schema.Literal("free"),
    Schema.Literal("premium")
  ),
}).pipe(Schema.Data)

export type Customer = Schema.Schema.Type<typeof Customer>

// Union schema
export const User = Schema.Union(Admin, Customer).pipe(
  Schema.annotations({
    identifier: "User",
    title: "User",
    description: "A user can be an admin or a customer",
  })
)

export type User = Schema.Schema.Type<typeof User>

2. Constructors Using Schema.decodeSync

import * as DateTime from "effect/DateTime"

/**
 * Create a pending task.
 *
 * Note: _tag is automatically applied by TaggedStruct.
 *
 * @category Constructors
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 * import * as DateTime from "effect/DateTime"
 *
 * const task = Task.makePending({
 *   id: "task-123",
 *   createdAt: DateTime.unsafeNow()
 * })
 * // Result: { _tag: "pending", id: "task-123", createdAt: ... }
 *
 * // Structural equality from Schema.Data:
 * const another = Task.makePending({
 *   id: "task-123",
 *   createdAt: DateTime.unsafeNow()
 * })
 * Equal.equals(task, another) // true if all fields match
 */
export const makePending = Schema.decodeSync(Pending)

/**
 * Create an active task.
 *
 * @category Constructors
 * @since 0.1.0
 */
export const makeActive = Schema.decodeSync(Active)

/**
 * Create a completed task.
 *
 * @category Constructors
 * @since 0.1.0
 */
export const makeCompleted = Schema.decodeSync(Completed)

Why decodeSync?

• Schema.Data returns a schema that needs decoding
• decodeSync creates a validated constructor
• Automatically applies the _tag discriminator
• Throws on invalid input (use decodeUnknownSync for unknown data)

3. Guards and Type Predicates

/**
 * Type guard for Task union.
 *
 * @category Guards
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 *
 * if (Task.isTask(value)) {
 *   // value is Task
 * }
 */
export const isTask = Schema.is(Task)

/**
 * Refine to Pending variant.
 *
 * @category Guards
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 *
 * if (Task.isPending(task)) {
 *   // task is Pending, access startedAt safely
 *   console.log(task.createdAt)
 * }
 */
export const isPending = (self: Task): self is Pending => self._tag === "pending"

/**
 * Refine to Active variant.
 *
 * @category Guards
 * @since 0.1.0
 */
export const isActive = (self: Task): self is Active => self._tag === "active"

/**
 * Refine to Completed variant.
 *
 * @category Guards
 * @since 0.1.0
 */
export const isCompleted = (self: Task): self is Completed => self._tag === "completed"

4. Match Function (Pattern Matching)

import * as Match from "effect/Match"

/**
 * Pattern match on Task using Match.typeTags.
 *
 * @category Pattern Matching
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 *
 * const status = Task.match({
 *   pending: (t) => `Pending: ${t.id}`,
 *   active: (t) => `Active since ${t.startedAt}`,
 *   completed: (t) => `Completed at ${t.completedAt}`
 * })
 *
 * const result = status(task)
 */
export const match = Match.typeTags<Task>()

Match.typeTags Usage:

• Primary pattern for discriminated unions
• Type-safe and exhaustive
• Works with any _tag discriminator

5. Equivalence (Usually Automatic via Schema.Data)

import * as Equal from "effect/Equal"
import * as Equivalence from "effect/Equivalence"

/**
 * Primary approach: Use Equal.equals() from Schema.Data
 *
 * @example
 * import * as Equal from "effect/Equal"
 *
 * const task1 = Task.makePending({ ... })
 * const task2 = Task.makePending({ ... })
 *
 * // Structural equality (automatic from Schema.Data)
 * if (Equal.equals(task1, task2)) {
 *   // Tasks are structurally equal
 * }
 */

/**
 * Export Equivalence only when you need multiple comparison strategies.
 *
 * @category Equivalence
 * @since 0.1.0
 */
export const Equivalence = Schema.equivalence(Task)

/**
 * Field-based equivalence using Equivalence.mapInput
 *
 * Compare by specific fields when structural equality isn't appropriate.
 *
 * @category Equivalence
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 *
 * // Compare by ID only
 * const areTasksSame = Task.EquivalenceById(task1, task2)
 */
export const EquivalenceById = Equivalence.mapInput(
  Equivalence.string,
  (task: Task) => task.id
)

When to Export Equivalence:

• You need multiple comparison strategies (by ID, by group, etc.)
• Field-based equality is semantically meaningful
• Business logic requires custom equality checks

When NOT to Export Equivalence:

• You only need structural equality (use Equal.equals() directly)
• No custom comparison logic is needed

Conditional Module Exports

Include these when semantically appropriate:

Identity Values

When the type has a natural "zero" or "empty" value:

/**
 * Zero value for monetary amounts.
 *
 * @category Identity
 * @since 0.1.0
 */
export const zero: Cents = make(0n)

/**
 * Empty list.
 *
 * @category Identity
 * @since 0.1.0
 */
export const empty: List<never> = makeEmpty()

Combinators

Functions that combine or transform values:

import { dual } from "effect/Function"

/**
 * Add two monetary values.
 *
 * @category Combinators
 * @since 0.1.0
 * @example
 * import * as Cents from "@/schemas/Cents"
 * import { pipe } from "effect/Function"
 *
 * const total = pipe(price, Cents.add(tax))
 */
export const add: {
  (that: Cents): (self: Cents) => Cents
  (self: Cents, that: Cents): Cents
} = dual(2, (self: Cents, that: Cents): Cents => make(self + that))

/**
 * Get minimum of two values.
 *
 * @category Combinators
 * @since 0.1.0
 */
export const min = (a: Cents, b: Cents): Cents => a < b ? a : b

/**
 * Get maximum of two values.
 *
 * @category Combinators
 * @since 0.1.0
 */
export const max = (a: Cents, b: Cents): Cents => a > b ? a : b

Order Instances

Provide sorting capabilities using Order.mapInput:

import * as Order from "effect/Order"
import * as DateTime from "effect/DateTime"

/**
 * Order by tag (pending < active < completed).
 *
 * Uses Order.mapInput to compose from Order.number.
 *
 * @category Orders
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 * import * as Array from "effect/Array"
 * import { pipe } from "effect/Function"
 *
 * const sorted = pipe(tasks, Array.sort(Task.OrderByTag))
 */
export const OrderByTag: Order.Order<Task> = Order.mapInput(
  Order.number,
  (task) => {
    const priorities = { pending: 0, active: 1, completed: 2 }
    return priorities[task._tag]
  }
)

/**
 * Order by ID.
 *
 * @category Orders
 * @since 0.1.0
 */
export const OrderById: Order.Order<Task> =
  Order.mapInput(Order.string, (task) => task.id)

/**
 * Order by creation date.
 *
 * @category Orders
 * @since 0.1.0
 */
export const OrderByCreatedAt: Order.Order<Task> =
  Order.mapInput(DateTime.Order, (task) => task.createdAt)

/**
 * Combine multiple orders for multi-criteria sorting.
 *
 * Sorts by tag first, then by creation date.
 *
 * @category Orders
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 * import * as Array from "effect/Array"
 *
 * const sorted = Array.sort(tasks, Task.OrderByTagThenDate)
 */
export const OrderByTagThenDate: Order.Order<Task> = Order.combine(
  OrderByTag,
  OrderByCreatedAt
)

Key Pattern: Order.mapInput

• Compose orders from simpler base orders
• Map domain type to comparable value
• Signature: Order.mapInput(baseOrder, (value) => extractField)

Key Pattern: Order.combine

• Combine multiple orders for multi-criteria sorting
• First order takes precedence, then second, etc.

Destructors (Getters)

Safe extraction of inner values:

/**
 * Get the ID from any Task variant.
 *
 * @category Destructors
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 *
 * const id = Task.getId(task) // Works for any variant
 */
export const getId = (self: Task): string => self.id

/**
 * Get creation date.
 *
 * @category Destructors
 * @since 0.1.0
 */
export const getCreatedAt = (self: Task): DateTime.DateTime.Utc =>
  self.createdAt

Setters (Immutable Updates)

import { dual } from "effect/Function"

/**
 * Update a field immutably.
 *
 * @category Setters
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 * import { pipe } from "effect/Function"
 *
 * const updated = pipe(task, Task.setId("new-id"))
 */
export const setId: {
  (id: string): (self: Task) => Task
  (self: Task, id: string): Task
} = dual(2, (self: Task, id: string): Task => ({ ...self, id }))

Advanced Patterns

Recursive Schemas with Schema.suspend

Use for self-referencing types (trees, graphs, nested structures):

import { Schema } from "effect"

/**
 * Recursive domain type: Category with subcategories.
 */

// Separate base fields from recursive field
const baseFields = {
  id: Schema.String,
  name: Schema.String,
}

// Define the recursive type
interface Category extends Schema.Struct.Type<typeof baseFields> {
  readonly subcategories: ReadonlyArray<Category>
}

// Create schema with Schema.suspend for recursion
export const Category = Schema.Struct({
  ...baseFields,
  subcategories: Schema.Array(
    Schema.suspend((): Schema.Schema<Category> => Category)
  ),
}).pipe(
  Schema.Data,
  Schema.annotations({
    identifier: "Category",
    title: "Category",
    description: "A category that can contain nested subcategories",
  })
)

export type Category = Schema.Schema.Type<typeof Category>
export const make = Schema.decodeSync(Category)

/**
 * Example usage:
 *
 * const root = Category.make({
 *   id: "1",
 *   name: "Electronics",
 *   subcategories: [
 *     Category.make({ id: "2", name: "Phones", subcategories: [] }),
 *     Category.make({ id: "3", name: "Laptops", subcategories: [] })
 *   ]
 * })
 */

Key Pattern: Schema.suspend

• Use for self-referencing types
• Separate base fields for clarity
• Define interface first, then schema with Schema.suspend

Branded Types

For types that need additional runtime guarantees:

import * as Brand from "effect/Brand"
import * as Schema from "effect/Schema"

/**
 * Email branded type with validation.
 */
export type Email = Brand.Branded<string, "Email">

export const Email = Brand.refined<Email>(
  (s) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s),
  (s) => Brand.error(`"${s}" is not a valid email`)
)

/**
 * Schema for Email serialization/deserialization.
 */
export const EmailSchema: Schema.BrandSchema<Email, string> =
  Schema.String.pipe(Schema.fromBrand(Email))

/**
 * @example
 * const email = Email("[e-mail]")
 * const decoded = Schema.decodeSync(EmailSchema)("[e-mail]")
 */

Typeclass Instances

Only implement typeclasses that are semantically appropriate.

Check the project's @/typeclass/ directory for available typeclasses:

import * as Schedulable$ from "@/typeclass/Schedulable"

/**
 * Schedulable instance for Task.
 *
 * @category Typeclasses
 * @since 0.1.0
 */
export const Schedulable = Schedulable$.make<Task>(
  (self) => self.createdAt,
  (self, date) => ({ ...self, createdAt: date })
)

// Re-export derived predicates
export const isScheduledBefore = Schedulable$.isScheduledBefore(Schedulable)

// Re-export derived orders
export const OrderByScheduledDate = Schedulable$.OrderByScheduledDate(Schedulable)

Common typeclass examples:

• Schedulable: For types with date/time properties
• Durable: For types with duration properties
• Priceable: For types with price properties
• Identifiable: For types with ID properties

Import Patterns

CRITICAL: Always use namespace imports:

//  CORRECT
import * as Task from "@/schemas/Task"
import * as DateTime from "effect/DateTime"
import * as Array from "effect/Array"
import * as Order from "effect/Order"
import * as Equal from "effect/Equal"

const task = Task.makePending({
  id: "123",
  createdAt: DateTime.unsafeNow()
})
const isPending = Task.isPending(task)
const sorted = Array.sort(tasks, Task.OrderByTag)
const areEqual = Equal.equals(task1, task2)

NEVER do this:

// L WRONG - loses context, causes name clashes
import { makePending, isPending } from "@/schemas/Task"

Namespace Import Benefits:

• Clear context for all functions
• Prevents name clashes
• Enables Task.Pending, Task.Active schema access
• Natural organization: Task.makePending, Task.isPending

Temporal Data

Always use DateTime and Duration, never Date or number:

//  CORRECT
import * as DateTime from "effect/DateTime"
import * as Duration from "effect/Duration"

export const Task = Schema.TaggedStruct("task", {
  createdAt: Schema.DateTimeUtcFromSelf,  // UTC datetime
  duration: Schema.Duration,               // Duration type
}).pipe(Schema.Data)

// L WRONG
export const Task = Schema.TaggedStruct("task", {
  createdAt: Schema.Date,        // Native Date
  duration: Schema.Number,       // Number milliseconds
})

Immutability

Use the Data module for immutable operations:

import { Data } from "effect"

/**
 * Immutable update.
 *
 * @category Setters
 * @since 0.1.0
 */
export const updateStatus = (self: Task, newTag: Task["_tag"]): Task =>
  Data.struct({ ...self, _tag: newTag })

Documentation Standards

Every exported member MUST have:

• JSDoc with description
• @category tag (Constructors, Guards, Pattern Matching, Orders, etc.)
• @since tag (version number)
• @example with fully working code including all imports

/**
 * Create a pending task.
 *
 * Note: _tag is automatically applied by TaggedStruct.
 *
 * @category Constructors
 * @since 0.1.0
 * @example
 * import * as Task from "@/schemas/Task"
 * import * as DateTime from "effect/DateTime"
 *
 * const task = Task.makePending({
 *   id: "task-123",
 *   createdAt: DateTime.unsafeNow()
 * })
 */
export const makePending = Schema.decodeSync(Pending)

Quality Checklist

Mandatory - Every Domain Model

• Type definition using Schema.TaggedStruct for each variant
• .pipe(Schema.Data) for automatic Equal implementation
• Schema annotations (identifier, title, description) on all schemas
• Constructor functions using Schema.decodeSync
• Type guard using Schema.is for union
• Refinement predicates for each variant (e.g., isPending)
• Match function using Match.typeTags
• Export all union member schemas and types
• All exports use namespace pattern (import * as)
• Full JSDoc with @category, @since, @example
• DateTime/Duration for temporal data (not Date/number)
• Data module for immutability
• Examples compile and run
• Format and typecheck pass

Conditional - Include When Appropriate

• Identity values (zero, empty, unit)
• Combinators (add, min, max, combine)
• Order instances using Order.mapInput for common sorting needs
• Order.combine for multi-criteria sorting
• Custom Equivalence via Schema.equivalence() or Equivalence.mapInput
• Destructors (getters for common fields)
• Setters (immutable update helpers)
• Recursive schemas with Schema.suspend (for self-referencing types)
• Branded types for validation constraints
• Typeclass instances (check @/typeclass/ directory first)
• Derived predicates from typeclasses
• Derived orders from typeclasses

Complete Example

/**
 * User domain model demonstrating all patterns.
 *
 * @since 0.1.0
 */
import { Schema, Equal, Match, Data } from "effect"
import * as DateTime from "effect/DateTime"
import * as Order from "effect/Order"
import * as Equivalence from "effect/Equivalence"
import { dual } from "effect/Function"

// =============================================================================
// Models
// =============================================================================

export const Admin = Schema.TaggedStruct("Admin", {
  id: Schema.String,
  name: Schema.String,
  createdAt: Schema.DateTimeUtcFromSelf,
  permissions: Schema.Array(Schema.String),
}).pipe(
  Schema.Data,
  Schema.annotations({
    identifier: "Admin",
    title: "Administrator",
    description: "A user with administrative privileges",
  })
)

export type Admin = Schema.Schema.Type<typeof Admin>

export const Customer = Schema.TaggedStruct("Customer", {
  id: Schema.String,
  name: Schema.String,
  createdAt: Schema.DateTimeUtcFromSelf,
  tier: Schema.Union(Schema.Literal("free"), Schema.Literal("premium")),
}).pipe(
  Schema.Data,
  Schema.annotations({
    identifier: "Customer",
    title: "Customer",
    description: "A customer user",
  })
)

export type Customer = Schema.Schema.Type<typeof Customer>

export const User = Schema.Union(Admin, Customer).pipe(
  Schema.annotations({
    identifier: "User",
    title: "User",
    description: "A user can be an admin or a customer",
  })
)

export type User = Schema.Schema.Type<typeof User>

// =============================================================================
// Constructors
// =============================================================================

/**
 * Create an admin user.
 *
 * @category Constructors
 * @since 0.1.0
 * @example
 * import * as User from "@/schemas/User"
 * import * as DateTime from "effect/DateTime"
 *
 * const admin = User.makeAdmin({
 *   id: "admin-1",
 *   name: "Alice",
 *   createdAt: DateTime.unsafeNow(),
 *   permissions: ["read", "write"]
 * })
 */
export const makeAdmin = Schema.decodeSync(Admin)

/**
 * Create a customer user.
 *
 * @category Constructors
 * @since 0.1.0
 */
export const makeCustomer = Schema.decodeSync(Customer)

// =============================================================================
// Guards
// =============================================================================

/**
 * Type guard for User.
 *
 * @category Guards
 * @since 0.1.0
 */
export const isUser = Schema.is(User)

/**
 * Refine to Admin.
 *
 * @category Guards
 * @since 0.1.0
 */
export const isAdmin = (self: User): self is Admin => self._tag === "Admin"

/**
 * Refine to Customer.
 *
 * @category Guards
 * @since 0.1.0
 */
export const isCustomer = (self: User): self is Customer => self._tag === "Customer"

// =============================================================================
// Pattern Matching
// =============================================================================

/**
 * Pattern match on User.
 *
 * @category Pattern Matching
 * @since 0.1.0
 * @example
 * import * as User from "@/schemas/User"
 *
 * const greeting = User.match({
 *   Admin: (u) => `Hello Admin ${u.name}`,
 *   Customer: (u) => `Hello ${u.tier} customer ${u.name}`
 * })
 *
 * const message = greeting(user)
 */
export const match = Match.typeTags<User>()

// =============================================================================
// Equivalence
// =============================================================================

/**
 * Compare users by ID only.
 *
 * @category Equivalence
 * @since 0.1.0
 */
export const EquivalenceById = Equivalence.mapInput(
  Equivalence.string,
  (user: User) => user.id
)

// =============================================================================
// Orders
// =============================================================================

/**
 * Order by name.
 *
 * @category Orders
 * @since 0.1.0
 */
export const OrderByName: Order.Order<User> =
  Order.mapInput(Order.string, (user) => user.name)

/**
 * Order by creation date.
 *
 * @category Orders
 * @since 0.1.0
 */
export const OrderByCreatedAt: Order.Order<User> =
  Order.mapInput(DateTime.Order, (user) => user.createdAt)

/**
 * Order by tag (Admin < Customer).
 *
 * @category Orders
 * @since 0.1.0
 */
export const OrderByTag: Order.Order<User> = Order.mapInput(
  Order.number,
  (user) => (user._tag === "Admin" ? 0 : 1)
)

// =============================================================================
// Destructors
// =============================================================================

/**
 * Get user ID.
 *
 * @category Destructors
 * @since 0.1.0
 */
export const getId = (self: User): string => self.id

/**
 * Get user name.
 *
 * @category Destructors
 * @since 0.1.0
 */
export const getName = (self: User): string => self.name

/**
 * Get creation date.
 *
 * @category Destructors
 * @since 0.1.0
 */
export const getCreatedAt = (self: User): DateTime.DateTime.Utc => self.createdAt

// =============================================================================
// Setters
// =============================================================================

/**
 * Update user name immutably.
 *
 * @category Setters
 * @since 0.1.0
 */
export const setName: {
  (name: string): (self: User) => User
  (self: User, name: string): User
} = dual(2, (self: User, name: string): User => ({ ...self, name }))

When to Use This Skill

• Creating domain entities (User, Product, Order)
• Modeling value objects (Email, Money, Address)
• Defining discriminated unions (states, events, commands)
• Implementing ADTs (algebraic data types)
• Building type-safe domain models with validation
• Ensuring structural equality with automatic Equal
• Creating self-documenting schemas

Key Principles Summary

1. Schema.TaggedStruct - Use for all tagged union variants
2. Schema.Data - Apply for automatic Equal implementation
3. Schema.decodeSync - Create type-safe constructors
4. Schema.annotations - Document all schemas
5. Order.mapInput - Compose orders from base orders
6. Match.typeTags - Pattern match on discriminated unions
7. Schema.suspend - Handle recursive types
8. Namespace imports - Always use import * as
9. DateTime/Duration - Never use Date/number for temporal data
10. Equal.equals() - Primary equality check (from Schema.Data)

Your domain models should be production-ready, type-safe, and provide excellent developer experience.