JMAP OCaml Module Structure#

Overview#

The JMAP libraries use proper OCaml module wrapping with module aliases for re-export. This provides a clean namespace while allowing both qualified and unqualified access to submodules.

Library Structure#

jmap-core#

Top-level module: Jmap_core

Submodules (re-exported):

• Jmap_core.Jmap_error - Error types and exceptions
• Jmap_core.Jmap_id - JMAP ID type
• Jmap_core.Jmap_primitives - Primitive types (Int53, UnsignedInt, Date, UTCDate)
• Jmap_core.Jmap_capability - Server capabilities
• Jmap_core.Jmap_filter - Generic filter combinators
• Jmap_core.Jmap_comparator - Sort comparators
• Jmap_core.Jmap_standard_methods - Standard JMAP methods (Get, Set, Query, etc.)
• Jmap_core.Jmap_invocation - Type-safe method invocations (GADT-based)
• Jmap_core.Jmap_request - JMAP request wrapper
• Jmap_core.Jmap_response - JMAP response wrapper
• Jmap_core.Jmap_session - Session discovery
• Jmap_core.Jmap_push - Push notifications
• Jmap_core.Jmap_binary - Binary data operations
• Jmap_core.Jmap_parser - JSON parsing helpers

jmap-mail#

Top-level module: Jmap_mail

Submodules (re-exported):

• Jmap_mail.Jmap_mailbox - Mailbox type and operations
• Jmap_mail.Jmap_thread - Thread type and operations
• Jmap_mail.Jmap_email - Email type and operations
• Jmap_mail.Jmap_identity - Identity type and operations
• Jmap_mail.Jmap_email_submission - Email submission type and operations
• Jmap_mail.Jmap_vacation_response - Vacation response type and operations
• Jmap_mail.Jmap_search_snippet - Search snippet type and operations
• Jmap_mail.Jmap_mail_parser - Mail-specific JSON parsing

jmap-client#

Top-level module: Jmap_client

Files:

• Jmap_client - HTTP client (stub implementation)
• Jmap_connection - Connection management (stub implementation)

Usage Patterns#

Pattern 1: Qualified Access#

let id = Jmap_core.Jmap_id.of_string "abc123"
let mailbox = Jmap_mail.Jmap_mailbox.v
  ~id ~name:"Inbox"
  ~sort_order:(Jmap_core.Jmap_primitives.UnsignedInt.of_int 0)
  ...

Pattern 2: Open for Direct Access#

open Jmap_core
open Jmap_mail

let id = Jmap_id.of_string "abc123"
let mailbox = Jmap_mailbox.v
  ~id ~name:"Inbox"
  ~sort_order:(Jmap_primitives.UnsignedInt.of_int 0)
  ...

Pattern 3: Mixed (Recommended)#

(* Open Jmap_core for common types *)
open Jmap_core

(* Use qualified names for specific modules *)
let mailbox = Jmap_mail.Jmap_mailbox.v
  ~id:(Jmap_id.of_string "inbox")
  ~name:"Inbox"
  ...

Benefits of This Structure#

1. Namespace Control: All modules are under Jmap_core or Jmap_mail, avoiding name collisions
2. Flexible Access: Use qualified or unqualified names as needed
3. Clear Dependencies: Module hierarchy reflects the protocol structure
4. Standard Practice: Follows OCaml best practices for library design
5. Tool Compatibility: Works well with merlin, ocamllsp, and other OCaml tools

Building#

dune build

Testing#

dune test

Installation#

dune install

This will install three packages:

• jmap-core - Core JMAP protocol (RFC 8620)
• jmap-mail - Mail extension (RFC 8621)
• jmap-client - HTTP client (stub)