snippetjavascriptTip

Designing a user-centric API for a JavaScript library

Submitted by: @import:30-seconds-of-code·Mar 2, 2026·

Viewed 0 times

javascriptusercentricdesigningapilibraryfor

Problem

In the previous article, I briefly touched upon how <dfn title="Test-driven development (TDD) is a software development methodology where developers write automated tests before writing the actual code. It follows a cyclic process of writing a failing test, implementing minimal code to pass it, then refactoring the code to improve its structure while maintaining functionality.">TDD</dfn> helped me design a better developer experience for a small library I was working on. This time around, I want to focus on the API design side of things.
My project involves around a simple concept - the regular expression <dfn title="A domain-specific language (DSL) is a computer language specialized to a particular application domain. This is in contrast to a general-purpose language (GPL), which is broadly applicable across domains.">DSL</dfn> is hard to write, almost as if it was made for computers, not humans.
I'm sure you're all familiar with this problem to some extent. Writing a RegExp can be a pain, especially when it gets longer and more complex. It's hard to read, hard to maintain, and especially hard to reuse parts of regular expressions. So how can I make it easier for myself and others to write RegExp patterns?
> [!IMPORTANT]
>

Solution

Notice how I leaned into the fact that the end user has **some degree of familiarity** with the DSL. The end user is very important here, as we are trying to make _their_ life easier. Someone unfamiliar with RegExp would describe this in a more verbose way due to unfamiliarity with core constructs, making it less efficient to try and target those users.

### Reusability

The less ambitious goal for this project is to make it easier to **reuse RegExp patterns**. This means that I should be able to create a pattern once and use it in multiple places. This boils down to creating all the necessary **building blocks** to make this possible and making sure they can be combined in all the ways that make sense for the end user.

I'm sure you're all familiar with this problem to some extent. Writing a RegExp can be a pain, especially when it gets longer and more complex. It's hard to read, hard to maintain, and especially hard to reuse parts of regular expressions. So how can I make it easier for myself and others to write RegExp patterns?
> [!IMPORTANT]
>
> The code in this article is not functional. It acts as a rough draft of my thought process, how TDD ties into it, and a way to visualize in code (or pseudocode) what's being discussed. One or more code implementation articles of this project will follow.
My primary goal is to create a more natural way to express regular expressions. As a secondary goal, I also want to make it easier to reuse patterns, so that one could conceptually create building blocks or libraries of RegExp patterns. Finally, as with anything I create, I want code written with this library to be easy to read and maintain.
As stated before, the main ask is a way to describe regular expressions in a more natural way. To that end, I want to be able to express in code what I would describe to a colleague somewhat familiar with the concept, in natural language. This means something like /.*/ would be roughly described as _any character zero or more times_.

Code Snippets

Notice how I leaned into the fact that the end user has **some degree of familiarity** with the DSL. The end user is very important here, as we are trying to make _their_ life easier. Someone unfamiliar with RegExp would describe this in a more verbose way due to unfamiliarity with core constructs, making it less efficient to try and target those users.

### Reusability

The less ambitious goal for this project is to make it easier to **reuse RegExp patterns**. This means that I should be able to create a pattern once and use it in multiple places. This boils down to creating all the necessary **building blocks** to make this possible and making sure they can be combined in all the ways that make sense for the end user.

### Readability & maintainability

Our **health metrics**, if you will, are how easy it is to read and maintain the code written with this library. The main hassle of RegExp is how much time is wasted trying to understand what the last person - or you from the past - did and how they arrived at the pattern before you. Then, an equal, if not greater, amount of time is spent trying to figure out how to change it without breaking anything.

Naturally, we want to avoid this kind of situation. Therefore, it's imperative that the code produced is as **easy to understand** regardless if you wrote it or it's the first time you laid eyes on it. Moreover, it should be **easy to make changes** and reason about them, reducing the barrier to entry for everyone involved.

Context

From 30-seconds-of-code: user-centric-api-design

Revisions (0)

No revisions yet.