DEV Community: Sean Maxwell

Build Type-Safe URLs from a Route Tree with jet-paths

Sean Maxwell — Tue, 29 Sep 2026 19:02:28 +0000

Most projects start with a few URL strings. Before long, you have `/api/users/${id}` in one file, '/api/users/' + userId in another, and a route that still points to an endpoint you renamed months ago.

jet-paths gives those URLs one place to live. You define a nested route tree, then call its routes like functions. TypeScript checks the parameters, and the library handles joining segments and encoding values.

Start with a route tree

Install the package:

npm install jet-paths

Then define your paths:

import jetPaths from 'jet-paths';

const Paths = jetPaths({
  $path: '/api',
  Users: {
    $path: '/users',
    Get: '/all',
    One: '/:id',
    Delete: '/delete/:id',
  },
});

Each route is callable, including the Users group:

Paths.Users();                // '/api/users'
Paths.Users.Get();            // '/api/users/all'
Paths.Users.One({ id: 5 });   // '/api/users/5'

You don't have to join /api, /users, and /:id yourself. And because One contains :id, TypeScript knows the call needs an id:

Paths.Users.One();            // Type error: missing argument
Paths.Users.One({ name: 5 }); // Type error: expected `id`

Sometimes you need the template rather than a finished path, such as when registering a server route. Both the local segment and the complete template are available:

Paths.Users.One.$path; // '/:id'
Paths.Users.One.$tmpl; // '/api/users/:id'

If you put the definition in a separate variable, use as const to preserve the literal route strings. Otherwise, TypeScript widens them to string and can't infer names such as id.

const definition = {
  $path: '/api',
  One: '/users/:id',
} as const;

const UserPaths = jetPaths(definition);
UserPaths.One({ id: 5 }); // '/api/users/5'

Add path and search parameters

Path parameters go in the first argument. You can pass search parameters in a second argument:

Paths.Users.Delete({ id: 5 });
// '/api/users/delete/5'

Paths.Users.Delete({ id: 5 }, { permanent: true });
// '/api/users/delete/5?permanent=true'

For a route without path parameters, the first argument is the search parameters:

Paths.Users.Get({ page: 2 });
// '/api/users/all?page=2'

You can pass arrays, too. They become repeated keys. undefined values are omitted, while false and 0 are kept:

Paths.Users.Get({
  tags: ['admin', 'editor'],
  page: 0,
  active: false,
  q: undefined,
});
// '/api/users/all?tags=admin&tags=editor&page=0&active=false'

Pass values as they are; jet-paths encodes them:

Paths.Users.Delete(
  { id: 'team/a' },
  { reason: 'duplicate entry' },
);
// '/api/users/delete/team%2Fa?reason=duplicate%20entry'

Search values must be primitives or arrays of primitives. For something like a Date, convert it to a string first.

Declare query parameters when you want stricter types

If a route accepts a known set of search parameters, you can put their names in the route definition. Add ! to make one required:

const UserPaths = jetPaths({
  $path: '/api',
  Users: {
    $path: '/users',
    Search: '/search?<q!><page><sort>',
    One: '/:id?<expand>',
  },
});

UserPaths.Users.Search({ q: 'sean', page: 2 });
// '/api/users/search?q=sean&page=2'

UserPaths.Users.One({ id: 5 }, { expand: true });
// '/api/users/5?expand=true'

Here, q is required; page and sort are optional. TypeScript also catches misspelled or undeclared keys:

UserPaths.Users.Search({ page: 2 });            // Type error: missing `q`
UserPaths.Users.Search({ q: 'sean', pgae: 2 }); // Type error: unknown key

The declarations describe the query parameters; they aren't included in the path template:

UserPaths.Users.Search.$tmpl; // '/api/users/search'

You can leave query parameters undeclared when a route needs to accept arbitrary keys. Declared keys are also checked at runtime, which helps when values come from JavaScript or escape TypeScript's checks.

Nest routes without repeating parameters

Groups can have path parameters of their own. Child routes inherit them:

const OrgPaths = jetPaths({
  $path: '/api',
  Org: {
    $path: '/orgs/:orgId',
    Members: '/members',
    Member: '/members/:memberId',
  },
});

OrgPaths.Org.Members({ orgId: 7 }, { page: 2 });
// '/api/orgs/7/members?page=2'

OrgPaths.Org.Member({ orgId: 7, memberId: 42 });
// '/api/orgs/7/members/42'

Members doesn't mention orgId in its own segment, but it still requires it because the parent route does.

You can also use $path: '' to organize routes in code without adding a URL segment:

const PublicPaths = jetPaths({
  $path: '/api',
  Public: {
    $path: '',
    Health: '/health',
    Status: '/status',
  },
});

PublicPaths.Public.Health(); // '/api/health'

Add an origin when you need one

The optional prepend setting adds a string to every generated path and complete template:

const Paths = jetPaths(
  {
    $path: '/api',
    Users: {
      $path: '/users',
      One: '/:id',
    },
  },
  { prepend: 'https://example.com' },
);

Paths.Users.One({ id: 5 });
// 'https://example.com/api/users/5'

prepend is added as written. Put dynamic parameters in the route tree, not in the prefix.

There's also a disableRegex option for skipping route-template validation. For example, it allows a static segment such as /@me, which the default validator rejects. Values passed to route functions are still encoded.

What happens with invalid values?

jet-paths validates route templates when you create the tree and checks values when you call a route. A path value can't be empty, . or .., because those values would change the structure of the URL:

Paths.Users.One({ id: '' }); // Throws at runtime

Path values must be primitives, and search values must be primitives or arrays of primitives. Those runtime checks are useful when callers use JavaScript or pass values whose types are broader than expected.

Using it in React

Create the route tree once at module level, then import it where you need it:

// paths.ts
import jetPaths from 'jet-paths';

export const Paths = jetPaths({
  $path: '/api',
  Users: {
    $path: '/users',
    One: '/:id',
  },
});

// UserLink.tsx
import { Paths } from './paths';

function UserLink({ id }: { id: number }) {
  return <a href={Paths.Users.One({ id })}>User {id}</a>;
}

That keeps route creation out of the component's render cycle. Calling an existing route to build a URL is cheap, so the link doesn't need special memoization.

Wrap-up

A route tree makes it easier to see which URLs your app uses and to change them in one place. With jet-paths, that definition also gives you checked path parameters, optional strict query parameters, encoding, and runtime validation.

If your project has URL strings scattered across components and API calls, you can start by moving a small group of routes into one tree and build from there.

I got tired of lining up comment dividers by hand, so I automated it

Sean Maxwell — Fri, 25 Sep 2026 04:44:15 +0000

This is a personal preference thing, but I like to write code top-down. Because of the way hoisting works in TypeScript/JavaScript, I can put the high-level stuff first and the details further down, so I split most files into regions in the same order every time:

Constants → Types → Classes (if any) → Functions → Export

To keep those regions easy to spot when I'm scrolling, I mark them with dividers like these:

// ========================================================================= //
//                                 CONSTANTS                                 //
// ========================================================================= //

const MAX_RETRIES = 3;

// ========================================================================= //
//                                 FUNCTIONS                                 //
// ========================================================================= //

// ============================= Shared Helpers ============================ //

Big three-line headers for regions, and a single line for smaller sections inside a region.

The annoying part

Writing these by hand is tedious. Every label is a different length, so every header needs a different amount of = on each side to stay centered and end at the same column. I was copying and pasting old dividers, then deleting and adding = until the closing // lined up again.

I first wrote a small script for myself that ran when I hit save. Then I needed it on my work computer, then in another project, then for a Python file. Instead of copy-pasting the script everywhere, I turned it into an npm package: code-divider.

How it works

You write a marker on its own line:

// @reg constants

const MAX_RETRIES = 3;

// @reg functions

// @sec shared helpers

Then run:

npx code-divider

The markers are replaced in place with the headers from the top of this post. @reg creates a region, and @sec creates a section. By default, region labels become UPPERCASE and section labels become Capitalized Words, and every line ends at column 79.

With no options it processes the current directory recursively. It skips things like node_modules, dist, and .json files by default. You can also point it at one file or folder:

npx code-divider --path ./src/index.ts

Add --dry-run to see which files would change without touching anything.

Run it on save

This is how I actually use it. I write a marker, hit save, and the header appears.

In VS Code, install the Run on Save extension and add this to your settings.json:

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.(css|js|jsx|ts|tsx)$",
        "cmd": "npx code-divider"
      }
    ]
  }
}

Any editor that can run a command on save works the same way.

"Why not just use snippets?"

Someone asked me this after my first post, and it's a fair question. Snippets can insert a header template, and if you're happy with that, keep using them. The catch is that snippets can change a label's case, but they can't count its characters. The filler stays the same length, so the line gets longer as the label gets longer:

// ================================= Helpers ================================= //
// ================================= Shared Helpers ================================= //

code-divider sizes the filler around each label, so every header ends at the same column. It also works in any editor, or in CI.

Other languages

It isn't just for JavaScript. It ships with support for TypeScript, Java, CSS, SCSS, C, C++, Go, Rust, PHP, Ruby, Python, Bash, and SQL, and it uses each language's comment syntax:

# @sec helpers

becomes

# ================================= Helpers ================================= #

To change the defaults, generate a config file:

npx code-divider --init

That writes a code-divider.config.json with every default setting. You only need to keep the settings you want to change. For example, wider headers with - as the filler:

{
  "All": {
    "CharacterLimit": 100,
    "FillerCharacter": "-"
  }
}

You can also give a language its own settings, or add a language that isn't built in by giving it file extensions and a comment syntax.

Using it in CI

--check works like --dry-run, but exits with code 1 if any file would change. I use it to catch markers I forgot to format before they get committed:

npx code-divider --check

Why I bother

If you don't like dividing code this way, that's fine, and this tool isn't for you. But I find that clearly separated regions make files faster to scan, both for me and for teammates reading my code. I've also found that AI coding tools seem to do better with files that are organized into obvious sections.

If you try it, I'd love to hear what you think. Bug reports, feature requests, and new language configs are all welcome.

I built a unique ID generator that's ~60% faster than nanoid

Sean Maxwell — Sat, 19 Sep 2026 17:37:39 +0000

jet-id is a tiny, zero-dependency unique ID generator for JavaScript and TypeScript. IDs are 28-character Crockford base32 strings, with optional timestamps so they sort by creation time. There's also a strictly ordered variant for when sorting by the millisecond isn't enough.

import jetid from 'jet-id';

jetid();       // '9Q8SWWBTY-7NVXM-FT9S6-XB4R3M'
jetid.timed(); // '1KKNTQ2CN-606ZG-8VF48-76B6F3'  (sorts by creation time)
jetid.mono();    // '1M308A0DM-PR0000-422PKHWX-THHP6B3G-DPQCJ4GCE'  (sorts within the millisecond too)

seanpmaxwell / jet-id

An extremely fast unique ID generator for JavaScript and TypeScript, with optional sorting/timestamping.

jet-id

An extremely fast unique ID generator for JavaScript and TypeScript, with optional timestamping and sorting.

Quick start

npm install jet-id

import jetId from 'jet-id';

jetId(); // '9Q8SWWBTY-7NVXM-FT9S6-XB4R3M'

A plain ID contains 25 random Crockford base32 characters, grouped as 9-5-5-6. Including the three dashes, each ID is 28 characters long.

· · ·

Why jet-id?

Fast: Faster than nanoid() in the included benchmarks.
Small: 6.9 kB packed, with zero runtime dependencies.
TypeScript-ready: Includes type declarations.
Portable: Works in Node.js and modern browsers.
Flexible: Choose random IDs, timestamped IDs, strictly ordered IDs, or secret keys.
Strong randomness: jetId() and jetId.mono() provide 125 random bits. For comparison, UUID v4 has 122.
Simple API: Generate IDs, validate their…

View on GitHub

~81 million IDs/sec, vs. nanoid's ~53 million on my machine
125 random bits from the platform CSPRNG — randomFillSync in Node, crypto.getRandomValues in browsers (UUID v4 has 122)
Strictly ordered when you need it: jetid.mono() orders IDs within a single millisecond without giving up any of those 125 bits
Readable: the Crockford alphabet has no I, L, O, or U to confuse with 1 and 0
Small: zero dependencies, 6.9 kB packed
Universal: runs in Node.js and modern browsers, and there's a CLI too

How it started

I was looking for an ID generator for a web project (mostly for a database column) that used the Crockford alphabet and had optional timestamping. I couldn't find anything that quite fit, so I debated between wrapping nanoid and writing my own. It seemed like a fun project that probably just involved some simple arithmetic (or so I naively thought), so I wrote my own.

The first version took a morning. Then, out of curiosity, I fed it to Fable 5.1 and GPT Astra, and I was blown away. They introduced me to techniques I didn't know existed, like pooling, lookup tables, and bit-shifting. I spent the next two days passing it back and forth between them, benchmarking every change, rolling back anything that got slower, and adding my own tweaks in between.

What makes it fast

Most of the speed comes from doing expensive work rarely and in bulk:

Pooling. IDs are built 256 at a time into a single string, so most calls to jetid() are just a substring. One call to the CSPRNG supplies enough randomness for 1,024 IDs.
Two characters per lookup. A 1,024-entry table turns 10 random bits into two Crockford characters at once, instead of encoding one character at a time.
Four bytes at a time. Each 28-character ID is written as seven 32-bit words through a Uint32Array, dashes included.
One string conversion per chunk. The bytes are decoded to a string once (through Buffer in Node, TextDecoder in browsers), and every ID is sliced from it.
A cached timestamp. For timed IDs, the nine-character timestamp is split into a six-character prefix that only changes every 32 seconds and a three-character suffix that changes each millisecond. The prefix is cached, so most calls re-encode three characters, not nine.

Benchmarks

On my MacBook M4 Pro (Node 24), median of 7 samples of at least 500 ms each, after a 500 ms warmup:

Generator	Chars	Random bits	Ops/sec	Relative
`jetid()`	28	125	81,127,524	1.00x
`nanoid()`	21	126	52,583,004	0.65x
nanoid, Crockford, 25 chars	25	125	46,942,586	0.58x
nanoid, Crockford, 9-5-5-6	28	125	15,589,642	0.19x
`jetid.mono()`	44	125	13,035,960	0.16x
`crypto.randomUUID()`	36	122	9,964,004	0.12x
ulid (monotonic)	26	80	3,637,167	274.9
`uuid` v4	36	122	8,577,377	0.11x

That's roughly 50% faster than nanoid's defaults, even though jet-id's IDs are longer (28 characters vs. 21). Configured to produce the same 9-5-5-6 format, nanoid is about 5x slower. To be fair, nanoid isn't built for dash-separated output, so part of that gap is the formatting wrapper.

jetid.mono() is the slowest of jet-id's own generators because it reads the high-resolution clock and encodes a sequence number on every call, rather than slicing a pre-built pool. It's still faster than either UUID option and ULID's monotonic option.

Why 9-5-5-6?

It looks a bit different, but it isn't arbitrary. The first segment is 9 characters because that's how long the current epoch (in milliseconds) is in Crockford base32, which leaves room for the optional timestamp without changing the ID's length. I wanted at least UUID v4's entropy, which takes 25 random characters, and splitting the remaining 16 into 5-5-6 seemed the most readable.

Timestamped IDs

jetid.timed() encodes the current time in the first nine characters, so plain string sorting is creation order. You can also pass your own epoch in milliseconds, and jetid.timed.parse() reads it back out:

jetid.timed(Date.UTC(2015, 2, 14)); // '19GAS9400-...'

const id = jetid.timed();         // '1KKNTQ2CN-606ZG-8VF48-76B6F3'
jetid.timed.parse(id);            // 1773480413589
new Date(jetid.timed.parse(id));  // 2026-03-14T09:26:53.589Z

Two tradeoffs to know about: timestamped IDs spend those first 9 characters on the time, so they carry 80 random bits instead of 125, and IDs created in the same millisecond have no defined order between them. If that second one matters to you, keep reading.

Strictly ordered IDs

jetid.mono() is for when "sorts by creation time" has to mean exactly — every ID sorts strictly after the one before it, even within a single millisecond.

import jetid from 'jet-id';

jetid.mono(); // '1M308A0DM-PR0000-422PKHWX-THHP6B3G-DPQCJ4GCE'
jetid.mono(); // '1M308A0DM-WR0000-1ZS1A6M5-NE6RKRHN-X9F480HCB'
jetid.mono(); // '1M308A0DM-X50000-XJ1ZENAH-MVX225N0-MZ0BTD8YB'

It's 44 characters in a 9-6-8-8-9 layout: the 9-character timestamp as before, then 6 characters of ordering key (10 bits of sub-millisecond time from performance.now() plus a 20-bit counter for ties), then 25 random characters.

That's why it's longer. Ordering costs 15 characters, and I didn't want to pay for them out of the randomness. At 40 characters the random tail keeps the full 125 bits, so jetid.mono() is exactly as collision-resistant as jetid().

Two caveats. It takes no epoch argument — the ordering guarantee only holds against time it reads itself. And the guarantee is per process: the counter lives in module state, so IDs from separate workers or machines aren't ordered against each other.

jetid.mono.test() and jetid.mono.parse() work like their jetid counterparts; parse returns { epoch, fraction, counter }. Use epoch for dates. The other two are an ordering key, not a finer clock — browsers coarsen performance.now(), so on Firefox and Safari counter does nearly all the work.

Validating IDs

jetid.test() checks whether a value is a well-formed ID. It isn't case-sensitive, and it accepts anything, returning false rather than throwing:

jetid.test('avz6yg1rb-47j6r-xgns9-tqw29a'); // true
jetid.test(null);                           // false

jetid.mono.test() does the same for the 44-character format. Neither accepts the other's IDs.

From the command line

npx jet-id               # one random ID
npx jet-id -c 5          # five, one per line
npx jet-id -t timed      # one timestamped ID
npx jet-id -t mono -c 10  # ten strictly ordered IDs

Feedback welcome

These benchmarks were all done on my local machine using the playground/benchmark.ts script. If they're different for you, or if you know of something faster, feedback is very welcome, especially if there's a flaw in the way I did the benchmarking.

GitHub: https://github.com/seanpmaxwell/jet-id
npm: https://www.npmjs.com/package/jet-id