Web API Feature Grouping

[jderochervlk]

Context

This repository needs a feature and module structure that balances:

• Discoverability for developers familiar with MDN.
• Small, useful feature dependencies.
• Stable public module names.
• Clear ownership for shared DOM types.

The four options under discussion are:

• Domain-oriented grouping: 27 features.
• MDN API categories: 43 features, including WebAPI.Types.
• MDN interface families: 158 interface-level features if each current public
  module gets its own feature. Grouping supporting types would reduce this.
• Domain features with interface modules: 27 features.

The counts are approximate design counts. They depend on whether supporting
types are public and how aggressively interfaces are split into independent
features.

Option 1: Domain-Oriented Grouping

This is the domain-oriented structure that implementation has started to
explore. Feature boundaries follow folders such as:
WebAPI.DOM, WebAPI.HTML, WebAPI.Window, WebAPI.Fetch,
WebAPI.WebAudio, and so on.

Example

src/
├── dom/          feature: WebAPI.DOM
├── html/         feature: WebAPI.HTML
├── window/       feature: WebAPI.Window
├── fetch/        feature: WebAPI.Fetch
├── media/        feature: WebAPI.Media
├── web-audio/    feature: WebAPI.WebAudio
└── workers/      feature: WebAPI.Workers

Feature Contents

• WebAPI.DOM contains foundational DOM types such as document, window,
  event, and eventTarget.
• WebAPI.Window contains Window plus closely related browser entry points
  such as Document, Location, History, Navigator, and
  MediaQueryList.
• WebAPI.Fetch contains Fetch, Request, Response, Headers, and
  FormData.
• WebAPI.Event contains Event, EventTarget, AbortController, and
  related event types.

Pros

• Fewer features than the other options.
• Feature boundaries reflect meaningful platform areas.
• Existing source organization is already close to this model.
• Dependencies can be kept focused without creating one feature per API.

Cons

• Some boundaries are arbitrary or based on implementation history.
• Window, Document, and DOM types are split across related features.
• It does not directly mirror how developers find APIs on MDN.
• Shared types in DOM.res can become a catch-all dependency.

Option 2: MDN API Categories

Features follow MDN API landing pages. The HTML DOM category is one
WebAPI.DOM feature with nested public modules:

WebAPI.DOM.Window.setTimeout
WebAPI.DOM.Document.querySelector
WebAPI.DOM.HTMLInputElement.value

The remaining features follow categories such as WebAPI.Fetch,
WebAPI.WebSockets, WebAPI.IndexedDB, WebAPI.WebAudio, and
WebAPI.ViewTransitions.

If a dedicated base type file is created, shared types live in a separate
WebAPI.Types feature. Types in the existing DOM.res stay with WebAPI.DOM
unless they are deliberately identified as cross-feature base types.

src/
├── dom/                  feature: WebAPI.DOM
│   ├── DOM.res           public root: WebAPI.DOM
│   ├── Window.res        public: WebAPI.DOM.Window
│   └── Document.res      public: WebAPI.DOM.Document
├── base/                 feature: WebAPI.Types
│   └── Types.res         public: WebAPI.Types
├── fetch/                feature: WebAPI.Fetch
├── indexeddb/            feature: WebAPI.IndexedDB
├── web-audio/            feature: WebAPI.WebAudio
└── ...

Feature Contents

• WebAPI.DOM contains the complete HTML DOM category. Its public modules
  include DOM.Window, DOM.Document, DOM.Location, DOM.History,
  DOM.Element, and the DOM.HTML*Element modules.
• WebAPI.Fetch contains the Fetch API family: Fetch, Request, Response,
  Headers, and FormData.
• WebAPI.Events contains general event interfaces and related event types;
  specialized input events may remain in WebAPI.UIEvents.
• WebAPI.Types, if created, contains only shared representations that must be
  consumed by multiple features.

Pros

• Matches MDN's reader-facing API categories.
• Keeps the HTML DOM area together while preserving module-level ownership.
• WebAPI.DOM.Window makes the category relationship explicit.
• Significantly fewer features than interface-first grouping.

Cons

• MDN categories are editorial and can change.
• Some interfaces could reasonably belong to multiple categories.
• Nested public module support may require a facade or namespace design.
• The WebAPI.Types boundary still needs a deliberate type classification.

Option 3: MDN Interface Families

Each MDN interface family becomes a feature. Members remain under their
interface:

WebAPI.Window.setTimeout
WebAPI.Document.querySelector
WebAPI.HTMLInputElement.value

For example, Window, Document, Request, Response,
CanvasRenderingContext2D, and AudioContext each own their members and
closely related types.

src/
├── window/                         feature: WebAPI.Window
│   └── Window.res
├── document/                       feature: WebAPI.Document
│   └── Document.res
├── html-input-element/             feature: WebAPI.HTMLInputElement
│   └── HTMLInputElement.res
├── request/                        feature: WebAPI.Request
│   └── Request.res
├── response/                       feature: WebAPI.Response
│   └── Response.res
├── canvas-rendering-context-2d/    feature: WebAPI.CanvasRenderingContext2D
│   └── CanvasRenderingContext2D.res
├── audio-context/                  feature: WebAPI.AudioContext
│   └── AudioContext.res
└── ...                             one folder per feature

Feature Contents

• WebAPI.Window contains only the Window interface and its properties,
  methods, and events. Location, History, and Document are separate
  features.
• WebAPI.Response contains Response and response-specific supporting
  types; Request, Headers, and FormData are separate features.
• WebAPI.Event contains the base Event interface and its members.
  KeyboardEvent, MouseEvent, PointerEvent, and other specialized events
  each have their own features.
• WebAPI.DOM or WebAPI.Types is not required as a broad owner; shared types
  need an explicit interface owner or a dedicated base feature.

Pros

• Closely matches MDN interface/member URLs.
• Gives every API a clear owner.
• Avoids deciding which category owns cross-cutting interfaces.
• Provides precise feature-level dependency boundaries.

Cons

• Produces a very large number of features.
• Public modules become harder to browse as a group.
• MDN URL changes should not automatically rename package modules.
• Shared types and global functions need explicit ownership rules.

Option 4: Domain Features With Interface Modules

Feature boundaries follow the larger domains from Option 1, but each feature is
organized internally around MDN-style interface modules. The feature owns the
dependency boundary; the modules retain clear interface ownership.

WebAPI.Window.setTimeout
WebAPI.Response.status
WebAPI.KeyboardEvent.key

src/
├── dom/                  feature: WebAPI.DOM
│   ├── Window.res        public: WebAPI.Window
│   ├── Document.res      public: WebAPI.Document
│   ├── Element.res       public: WebAPI.Element
│   └── ...
├── fetch/                feature: WebAPI.Fetch
│   ├── Request.res       public: WebAPI.Request
│   ├── Response.res      public: WebAPI.Response
│   └── ...
├── event/                feature: WebAPI.Event
│   ├── Event.res         public: WebAPI.Event
│   ├── KeyboardEvent.res public: WebAPI.KeyboardEvent
│   └── ...
└── ...                   one folder per domain feature

Feature Contents

• WebAPI.DOM contains interface modules for Window, Document, Node,
  Element, and HTML element interfaces. Window owns Location, History,
  and related browser entry-point interfaces where appropriate.
• WebAPI.Fetch contains separate Request, Response, Headers, and
  FormData modules, but they are distributed as one feature dependency.
• WebAPI.Event contains Event, EventTarget, KeyboardEvent,
  MouseEvent, PointerEvent, and related event modules.
• Other domains follow the same rule: one feature folder, multiple
  interface-oriented modules.

Pros

• Keeps the feature count and dependency model close to Option 1.
• Gives major interfaces clear module names and ownership.
• Avoids creating one feature for every small supporting interface.
• Allows interface-oriented source organization without requiring a feature per
  interface.

Cons

• A consumer cannot depend on Response without depending on all of
  WebAPI.Fetch.
• The feature boundary and module namespace communicate different groupings.
• Cross-domain interfaces still need explicit ownership decisions.
• It is less directly aligned with MDN categories than Option 2 and less
  granular than Option 3.

Questions For Discussion

1. Should the HTML DOM category be exposed as WebAPI.DOM.Window or should
   Window remain a top-level WebAPI.Window module?
2. Which types, if any, should move from DOM.res into Types.res?
3. Are feature counts closer to 27, 43, or 158 useful for package consumers?
4. Should public features optimize for dependency size, documentation
   discoverability, or interface ownership?
5. Should interface modules be independent features, or grouped into domain
   features as in Option 4?