Feature Request: Boot-Time Macro Introspection in Macro v2

[hunterwilhelm]

What is the problem this feature would solve?

In Macro v2, there is currently no way to inspect which routes have which macros applied, or what options those macros were configured with, at boot time. This prevents developers from performing tasks that depend on route introspection before handling requests, such as authorization auditing, documentation generation, and static security verification.

In Macro v1, this was possible due to undocumented behavior where macro options were stored in events.local and accessible through route.hooks during application initialization. That behavior no longer exists in Macro v2, making these workflows impossible without runtime access.

A detailed comparison of this difference can be found here:
https://github.com/hunterwilhelm/elysia-macro-v1-vs-v2

What is the feature you are proposing to solve the problem?

Add a supported way in Macro v2 to access macro configuration data at boot time. This could be achieved by:

Exposing applied macro metadata (such as options or identifiers) through route.hooks, or

Providing a dedicated introspection API (for example, via app.routes), or

Introducing an optional macro lifecycle hook like onRegister, allowing macros to register or expose their configuration when routes are defined.

Any of these approaches would restore the ability to audit, document, and analyze route configurations during startup.

What alternatives have you considered?

Currently, the only alternative is to manually track macro configurations within custom data stores or global variables inside each macro definition. This approach is error-prone, inconsistent, and difficult to maintain across large applications.

Having an official mechanism for boot-time macro introspection would provide a reliable and standardized way to support these workflows, similar to what was implicitly available in Macro v1.

[Komiriko]

That's exactly what I need!!!

[SaltyAom]

54bf6ac, we add introspect hook to macro, allowing you to access/modify the route's hook property

This is pending by 1.4.16 (#1529), allowing you to verify if this solve your problem or we have the same understanding of the context

Usage

new Elysia()
	.macro('a', {
		introspect(option) {
			console.log(option)
		},
		beforeHandle() {
			console.log('before handle a')
		}
	})
	.get('/', () => 'hello world', {
		a: true,
		detail: {
			description: 'a'
		}
	})

this would log:

{
	a: true,
	detail: {
		description: 'a'
	}
}

However, by macro v2 by design is self-destructive in order. Which means if it is used, it will remove itself from the hook.
This means that if you have 2 introspect hook as follows

new Elysia()
	.macro('a', {
		introspect(option) {
			console.log('a', option)
		},
		beforeHandle() {
			console.log('before handle a')
		}
	})
	.macro({
		b: {
			introspect(option) {
				console.log('b', option)
			},
			beforeHandle() {
				console.log('before handle b')
			}
		}
	})
	.get('/', () => 'hello world', {
		a: true,
		b: true,
		detail: {
			description: 'a'
		}
	})

this would log:

a {
  a: true,
  b: true,
  detail: {
    description: "a",
  },
}
b {
  b: true,
  detail: {
    description: "a",
  },
  beforeHandle: [Function: beforeHandle],
}

Installation

This should land on 1.4.16 if we both agree that it works, to test this out now:

bun add https://pkg.pr.new/elysiajs/elysia@1529

Let me know if this is something you're looking for

[Komiriko]

I’ll try that tomorrow! It looks great, I hope I’ll also get the routes where the macro is enabled!
Thank you so much ❤️

[Komiriko]

@SaltyAom That's perfect for me! All I need now is the road + method😅

[hunterwilhelm]

@SaltyAom I agree with @Komiriko, could we get a property in the introspect that shows what route it's coming from?

For example:

const fgaPlugin = new Elysia({ name: "fga-plugin" }).macro({
  fga: (options: FgaOptions) => ({
    introspect(introspectOptions, metadata) {
      console.log("Introspecting with options") 
      console.log("options", options);
      console.log("introspect options", introspectOptions);
      console.log("introspect metadata", metadata);
    },
    beforeHandle() {
      // FGA validation would happen here
      console.log("Validating with options:", options);
    },
  }),
});

const app = new Elysia()
  .use(fgaPlugin)
  .get("/route1", () => "Hello from route1")
  .get(
    "/route2/:id",
    () => "Hello from route2",
    {
      fga: { role: "admin" },
    }
  );

Would show:

Introspecting with options
options {
  role: "admin",
}
introspect options {
  fga: {
    role: "admin",
  },
}
introspect metadata {
  route: "/route2/:id"
}

[hunterwilhelm]

Working on a PR for this