Using Opaque Types in Gleam for Encapsulated Data

Desired outcome

Create a Gleam module that defines an opaque type to hide its internal representation while providing a stable public API for constructing and accessing the value.

Prerequisites

• Gleam toolchain installed (version 1.0.0 or newer).
• A terminal with permission to run gleam commands.
• Basic familiarity with Gleam syntax and project structure.

Procedure

1. Create a new Gleam project:

   gleam new opaque_demo
   cd opaque_demo

2. Define the opaque type in src/types.gleam:

   pub opaque Username = Username(String)
   
   pub fn new_username(s: String) -> Username {
     Username(s)
   }
   
   pub fn username_value(u: Username) -> String {
     let Username(s) = u
     s
   }

3. Create a consumer module in src/user.gleam that uses the opaque type:

   import types/{Username, new_username, username_value}
   
   pub fn greet() -> String {
     let un = new_username("alice")
     let name = username_value(un)
     "Hello, " ++ name
   }

4. Attempt to pattern‑match on the opaque type from src/user.gleam to confirm opacity (this should fail):

   pub fn bad_pattern(u: Username) -> String {
     // Uncommenting the line below causes a compile‑time error
     // let Username(s) = u
     "should not compile"
   }

5. Build the project to see the compiler error for the illegal pattern match:

   gleam build

   Expected output: the build succeeds if the bad_pattern function is commented out or removed; otherwise the compiler reports an error such as "Unable to find constructor Username" confirming the type is opaque.

6. Remove or comment out the illegal pattern match, then build and test:

   gleam build
    gleam test

   Expected outcome: the build succeeds and any tests you write (e.g., asserting that greet() returns "Hello, alice") pass, demonstrating that the opaque type works as intended.

Expected checks

• Compiler error when external code tries to pattern‑match or access the hidden constructor.
• Successful build and test run when only the public constructor and accessor are used.
• Ability to change the underlying representation (e.g., from String to a tuple) and update only new_username and username_value without touching consumer code.

Recovery options

• If the representation changes, adjust the constructor and accessor in the defining module; consumer modules remain unaffected.
• If you need to expose additional operations, add more public functions that work with the opaque type; never expose the internal constructor directly.
• Should you accidentally expose the constructor (e.g., by removing opaque), revert the change and rebuild to restore encapsulation.