What is the recommended approach for modularizing routes while retaining inference in Treaty?

[is-jonreeves]

I've only really used Elysia for very small projects where I was fine with chaining all the routes. I recently decided to use it for something larger and couldn't quite figure out how to split out the routes and maintain the Type inferences (I'm using Treaty on the Client-side).

I was hoping that there was maybe some kind of helper factories like createRoute or something that I could use to extend the main router but also influence its type. But didn't see anything like that.

Research

I went through most of the examples and did notice this one, which seemed to suggest that I could build Sub Routers and attach them via .use. To be honest it felt a little clunky but I was able to get it working at least.

I also read through the MVC pages in the documentation which suggested a different approach. Keeping all the routes chained but instead just having them call out to the appropriate functions or class methods.

After playing with both a little, I settled on an approach that makes use of separate Elysia instances as "SubRouters", attached to the main router via .group and .use. This works very well and (at least to my preference) allows for better code-splitting / organization. This wasn't a pattern I've seen with Elysia elsewhere, so was a bit concerned that it was not a wise choice and may introduce some issues I'm not seeing just yet.

Examples

Minimal

Here is a minimal example to illustrate the approach:

/index.ts

import { Elysia, t } from 'elysia';
import { cors } from '@elysiajs/cors';

// Service Routes
const EchoRequestValidation = { query: t.Object({ message: t.String() }) };
const getEcho = new Elysia().get('', ({ query: { message } }) => ({ message }), EchoRequestValidation);
const routerEcho = new Elysia()
  .group('', r => r.use(getEcho));

// API Routes
export const v1 = new Elysia()
  .group('/echo', r => r.use(routerEcho));

// Application
const app = new Elysia()
  // Middleware
  .use(cors())

  // Routes
  .group('/api/v1', r => r.use(v1))

  // Server
  .listen(3001);

// Debug
console.log(`🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`);

// Eden Types
export type ElysiaAPIRoutes = typeof app;

How the expected routes materialize:

curl http://localhost:3001/api/v1/echo?message=Hello     # ✅ { "message": "Hello" }

How it appears via Treaty:

import { treaty } from '@elysiajs/eden';
import { ElysiaAPIRoutes } from '@myapp/server';

const ElysiaClient = treaty<ElysiaAPIRoutes>('localhost:3001');
const response = await ElysiaClient.api.v1.echo.index.get({ query: { message: 'Hello' } });
console.log(response.data);
// { message: 'Hello' }

Extended (API Versions and Services with revisions)

Here is a bigger example that modularizes the code across various files and shows API versioning, using multiple services and those each having their own revisions.

For this kind of work, I personally like TS namespaces an organization mechanism, but you could also just use Classes or simply separate files/imports:

/index.ts

import { Elysia } from 'elysia';
import { cors } from '@elysiajs/cors';
import { compression } from 'elysia-compression';

// Routes
import { v1 } from './api/v1';
import { v2 } from './api/v2';
import { v3 } from './api/v3';

// Application
const app = new Elysia()
  // Middleware
  .use(cors())
  .use(compression())

  // Routes
  .group('/api/v3', r => r.use(v3))
  .group('/api/v2', r => r.use(v2))
  .group('/api/v1', r => r.use(v1))

  // Server
  .listen(3001);

// Debug
console.log(`🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`);

// Eden Types
export type ElysiaAPIRoutes = typeof app;

/api/v1.ts - introduces 1st revisions of Echo and Ping services

import { Elysia } from 'elysia';

import { EchoService } from '../services/echo';
import { PingService } from '../services/ping';

export const v1 = new Elysia()
  .group('/echo', r => r.use(EchoService.Rev1.router))
  .group('/ping', r => r.use(PingService.Rev1.router));

/api/v2.ts - adds Math service and replaces Ping service with new revision

import { Elysia } from 'elysia';

import { EchoService } from '../services/echo';
import { MathService } from '../services/math';
import { PingService } from '../services/ping';

export const v2 = new Elysia()
  .group('/echo', r => r.use(EchoService.Rev1.router))
  .group('/math', r => r.use(MathService.Rev1.router))
  .group('/ping', r => r.use(PingService.Rev2.router));

/api/v3.ts - retires Echo service and adds new revisions for Math and Ping services

import { Elysia } from 'elysia';

import { MathService } from '../services/math';
import { PingService } from '../services/ping';

export const v3 = new Elysia()
  .group('/math', r => r.use(MathService.Rev2.router))
  .group('/ping', r => r.use(PingService.Rev3.router));

/services/echo.ts

import { Elysia, t } from 'elysia';

export namespace EchoService {
  export namespace Rev1 {
    // Validation
    export const EchoRequestValidation = t.Object({ message: t.String() });

    // Handlers
    export const get = new Elysia().get('', ({ query: { message } }) => ({ message }), { query: EchoRequestValidation });

    // Router
    export const router = new Elysia()
      .group('', r => r.use(get));
  }
}

/services/math.ts

import { Elysia, t } from 'elysia';

export namespace MathService {
  export namespace Rev1 {
    // Validation
    export const MathRequestValidation = t.Object({ a: t.Numeric(), b: t.Numeric() });

    // Handlers
    export const add = new Elysia().get('', ({ query: { a, b } }) => ({ result: a + b }), { query: MathRequestValidation });
    export const subtract = new Elysia().get('', ({ query: { a, b } }) => ({ result: a - b }), { query: MathRequestValidation });

    // Router
    export const router = new Elysia()
      .group('/add', r => r.use(add))
      .group('/subtract', r => r.use(subtract));
  }

  export namespace Rev2 {
    // Handlers
    export const multiply = new Elysia().get('', ({ query: { a, b } }) => ({ result: a * b }), { query: MathService.Rev1.MathRequestValidation });
    export const divide = new Elysia().get('', ({ query: { a, b } }) => ({ result: a / b }), { query: MathService.Rev1.MathRequestValidation });

    // Router
    export const router = new Elysia()
      .group('/add', r => r.use(MathService.Rev1.add))
      .group('/subtract', r => r.use(MathService.Rev1.subtract))
      .group('/multiply', r => r.use(multiply))
      .group('/divide', r => r.use(divide));
  }
}

/services/ping.ts

import { Elysia, t } from 'elysia';

export namespace PingService {
  export namespace Rev1 {
    // Handlers
    export const get = new Elysia().get('', () => ({ ping: true }));

    // Router
    export const router = new Elysia()
      .group('', r => r.use(get));
  }

  export namespace Rev2 {
    // Handlers
    export const get = new Elysia().get('', () => ({ ping: true, timestamp: new Date().toISOString() }));

    // Router
    export const router = new Elysia()
      .group('', r => r.use(get));
  }

  export namespace Rev3 {
    // Validation
    export const PingRequestValidation = t.Object({ message: t.String() });

    // Handlers
    export const get = new Elysia().get('', ({ query: { message } }) => ({
      timestamp: new Date().toISOString(),
      ping: true,
      message,
    }), { query: PingRequestValidation });

    // Router
    export const router = new Elysia()
      .group('', r => r.use(get));
  }
}

How the expected routes materialize:

curl http://localhost:3001/api/v1/echo?message=Hello     # ✅ { "message": "Hello" }
curl http://localhost:3001/api/v1/ping                   # ✅ { "ping": true }

curl http://localhost:3001/api/v2/echo?message=Hello     # ✅ { "message": "Hello" }
curl http://localhost:3001/api/v2/math/add?a=10&b=5      # ✅ { "result": 15 }
curl http://localhost:3001/api/v2/math/subtract?a=10&b=5 # ✅ { "result": 5 }
curl http://localhost:3001/api/v2/ping                   # ✅ { "ping": true, "timestamp": "2024-06-04T16:16:27.496Z" }

curl http://localhost:3001/api/v3/echo?message=Hello     # ✅ Error 404
curl http://localhost:3001/api/v3/math/add?a=10&b=5      # ✅ { "result": 15 }
curl http://localhost:3001/api/v3/math/subtract?a=10&b=5 # ✅ { "result": 5 }
curl http://localhost:3001/api/v3/math/multiply?a=10&b=5 # ✅ { "result": 50 }
curl http://localhost:3001/api/v3/math/divide?a=10&b=5   # ✅ { "result": 2 }
curl http://localhost:3001/api/v3/ping?message=pong      # ✅ { "ping": true, "timestamp": "2024-06-04T16:16:59.043Z", "message": "pong" }

How it appears via Treaty:

import { treaty } from '@elysiajs/eden';
import { ElysiaAPIRoutes } from '@myapp/server';

const ElysiaClient = treaty<ElysiaAPIRoutes>('localhost:3001');

await ElysiaClient.api.v1.echo.index.get({ query: { message: 'Hello' } });
await ElysiaClient.api.v1.ping.index.get();

await ElysiaClient.api.v1.echo.index.get({ query: { message: 'Hello' } });
await ElysiaClient.api.v2.math.add.index.get({ query: { a: 10, b: 5 } });
await ElysiaClient.api.v2.math.subtract.index.get({ query: { a: 10, b: 5 } });
await ElysiaClient.api.v1.ping.index.get();

// await ElysiaClient.api.v1.echo.index.get({ query: { message: 'Hello' } }); ... NOT AVAILABLE (expected)
await ElysiaClient.api.v3.math.add.index.get({ query: { a: 10, b: 5 } });
await ElysiaClient.api.v3.math.subtract.index.get({ query: { a: 10, b: 5 } });
await ElysiaClient.api.v3.math.multiply.index.get({ query: { a: 10, b: 5 } });
await ElysiaClient.api.v3.math.divide.index.get({ query: { a: 10, b: 5 } });
await ElysiaClient.api.v3.ping.index.get({ message: 'pong' });

Any Recomendations/Alternatives?

While the above all works great and for me personally feels really well structured, I'm just not confident that it doesn't break some important principals of Elysia's recommended usages. I'd love some guidance/feedback/suggestions about the above approach and any alternatives.

I suspect at least one issue with use of Sub-Routers here, is that they can't have typed knowledge of the context of the main Router. So any middlewares/decorates/state that will be present when attached, aren't known in isolation. I haven't explored this yet, but suspect it will introduce some type annoyances when trying to tap into any of that context.

[ivan-kleshnin]

await ElysiaClient.api.v3.math.add.index.get

5 dot separators are way too many and ubiquitous index and api suffixes add no information, just a boilerplate. I would strive to get something like this:

await ElysiaClient.v3.math.add

P.S. dropping an HTTP verb (RPC style) might be not possible in Elysia, just saying that I find it redundant.

[is-jonreeves]

I would strive to get something like this:
await ElysiaClient.v3.math.add

I agree, would be nice. The api prefix is just because of how I structured my routes. I suspect there is probably a way to tweak what I send to treaty<> to maybe skip that. The index is the bit I that bothered me. It was a while ago now, but I think its because of how I'm using subroutes. I didn't find a way to remove that. The get portion is actually kind of important because often we have both a get and post for the same resource (just not in the minimal examples above).

[david-plugge]

Would be nice if we could use the openapi name of an endpoint instead of the path and method. But then you need the mapping which means codegen...