Creating ADTs

Scaffold ADT (Algebraic Data Type) unions with discriminated member types.

CRITICAL

Read the Conventions First

Before creating any ADT, read the convention documents:

• ~/.claude/docs/conventions/namespace-module.md

  — Core

  _.ts

  /

  __.ts

  pattern

• ~/.claude/docs/conventions/library-adt.md

  — ADT-specific patterns

Operations

Create ADT Union

Structure:

src/lib/<adt-name>/
├── _.ts              # export * as AdtName from './__.js'
├── __.ts             # exports member namespaces + union
├── <adt-name>.ts     # Union definition
├── <member-a>.ts     # Member type
└── <member-b>.ts     # Member type

Steps:

1. Create directory at

   src/lib/<adt-name>/

   (kebab-case matching ADT name)
2. Create member files with tagged structs
3. Create union file importing members directly (NOT from

   __.ts

   )
4. Create

   __.ts

   exporting members as namespaces + union exports
5. Create

   _.ts

   pointing to

   __.ts

6. Add package.json imports and tsconfig.json paths

Member File Pattern (Effect Schema)

// <member>.ts
import * as S from 'effect/Schema'

export class MemberName extends S.TaggedClass<MemberName>()('AdtNameMemberName', {
  // fields...
}) {
  static is = S.is(MemberName)
}

Naming Rules:

• Class name = member name (short, local):

  Versioned

• Tag name = fully qualified:

  DocumentVersioned

Union File Pattern

// <adt-name>.ts
import * as S from 'effect/Schema'
import { MemberA } from './member-a.js' // Direct import, NOT from __.ts
import { MemberB } from './member-b.js'

export const AdtName = S.Union(MemberA, MemberB)
export type AdtName = typeof AdtName.Type

Barrel File Pattern (

__.ts

)

// __.ts
export * from './<adt-name>.js'
export * as MemberA from './member-a.js'
export * as MemberB from './member-b.js'

Examples

LifecycleEvent ADT

// added.ts
export class Added extends S.TaggedClass<Added>()('LifecycleEventAdded', {
  schema: SchemaRef,
  revision: Revision,
}) {
  static is = S.is(Added)
}

// removed.ts
export class Removed extends S.TaggedClass<Removed>()('LifecycleEventRemoved', {
  schema: SchemaRef,
  revision: Revision,
}) {
  static is = S.is(Removed)
}

// lifecycle-event.ts
import { Added } from './added.js'
import { Removed } from './removed.js'
export const LifecycleEvent = S.Union(Added, Removed)
export type LifecycleEvent = typeof LifecycleEvent.Type

// __.ts
export * as Added from './added.js'
export * from './lifecycle-event.js'
export * as Removed from './removed.js'

// _.ts
export * as LifecycleEvent from './__.js'

Consumer Usage

// Import ONLY from namespace (_.js)
import { LifecycleEvent } from '#lifecycle-event'

// Access members via namespace
const added = LifecycleEvent.Added.make({ schema, revision })
const removed = LifecycleEvent.Removed.make({ schema, revision })

// Type check
if (LifecycleEvent.Added.is(event)) {
  // event is Added
}

Notes

• Union file imports members directly to avoid circular dependencies
• Consumer code imports ONLY from

  _.js

  , never from

  __.js

• Use

  .make()

  constructor from tagged classes, never manual object construction
• Tag names should be fully qualified (

  AdtNameMemberName

  ) for global uniqueness
• See convention doc for Simple ADT Pattern (alternative when full structure is overkill)