types: Mark app.server as non-null in START event handler

[kiriDevs]

What?

This PR changes the typing of the handlers for the start event, declaring app.server as non-null for them.

It also updates the example snipped on onStart, removing the optional-chaining that is not needed because of this change anymore.

Why?

A miniscule, personal, stylistic annoyance:

new Elysia().onStart((startedApp) => {
  console.log("Listening on", startedApp.server?.url.host);
});

This is the handler for after the server has started, why do I still have to check the server exists?

After this change, this will work just fine:

console.log("Listening on", startedApp.server.url.host);

(The optional-chaining ("null-check") is no longer needed)

I guess another option would be using app.listen's callback, but that's only feasible for onStart event handlers on the "main" Elysia instance (i.e. outside of plugins).

---

As far as I was able to tell the "start" event handlers are never called from outside of listen, where app.server is set with Bun.serve(…) just before. Since Bun.serve(…) does not return null (or undefined) (according to TypeScript, and the docs don't mention anything contrary), this should be a safe guarantee to make. For what it's worth, tsc (bun run test:types) doesn't have any issues with the changes either.

I completely understand if this can't/won't be merged, be it because it's intentionally typed the current way for future changes/expansions or just because it's super insignificant; as mentioned, it was just a super small annoyance to me and I figured it'd be easy (and quick) enough to change.

Summary by CodeRabbit

• New Features

  • Added a new start lifecycle handler type and updated the start hook signature.
  • Start handlers now always receive a non-optional server object (server.url, server.port available).

• Documentation

  • Updated examples and JSDoc to reflect the guaranteed server property in start handlers.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Replaces the onStart lifecycle handler type: introduces ServerStartHandler (server property non-nullable), updates exports, and changes Elysia.onStart and LifeCycleStore.start to use the new type. Documentation/example adjusted to reflect non-optional server fields.

Changes

Cohort / File(s)	Summary
Type definition src/types.ts	Added ServerStartHandler<in Instance extends AnyElysia> = (data: Instance & { server: NonNullable<Instance["server"]> }) => any; changed LifeCycleStore.start from HookContainer<GracefulHandler<any>>[] to HookContainer<ServerStartHandler<any>>[].
API signature & exports src/index.ts	Exported ServerStartHandler from ./types; updated Elysia.onStart parameter type from MaybeArray<GracefulHandler<this>> to MaybeArray<ServerStartHandler<this>>; updated JSDoc example to treat server as non-optional.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I hopped in the code with a bright little start,
The server now certain — no nullable part.
Types snug and non-optional, tidy and smart,
A rabbit-approved change, a careful new art. ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing a new ServerStartHandler type that marks app.server as non-null in START event handlers, which is the core objective of this PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3f7d0ca and 2fccb58.

📒 Files selected for processing (1)

• src/index.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/index.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/index.ts (1)

88-167: Add ServerStartHandler to root exports and fix JSDoc template literal

The signature change for onStart(handler: MaybeArray<ServerStartHandler<this>>) correctly aligns with the updated LifeCycleStore.start typing. However, two issues prevent this from being a complete public API addition:

1. ServerStartHandler is not re-exported from the root module

The type is imported from ./types but missing from the main export type { … } block. Users cannot currently import it via import type { ServerStartHandler } from 'elysia'. Add it alongside other lifecycle types like GracefulHandler.

2. JSDoc example uses double quotes instead of a template literal

The example string "Running at ${server.url}:${server.port}" won't interpolate. Change to backticks:

- *         console.log("Running at ${server.url}:${server.port}")
+ *         console.log(`Running at ${server.url}:${server.port}`)

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f751caf and 3f7d0ca.

📒 Files selected for processing (2)

• src/index.ts
• src/types.ts

🧰 Additional context used

🧬 Code graph analysis (2)

src/types.ts (1)

src/index.ts (1)

• AnyElysia (175-175)

src/index.ts (1)

src/types.ts (2)

• MaybeArray (284-284)
• ServerStartHandler (1461-1463)

🔇 Additional comments (1)

src/types.ts (1)

626-639: ServerStartHandler typing for start hooks looks sound; just confirm adapter invariants

Typing LifeCycleStore.start as HookContainer<ServerStartHandler<any>>[] and defining ServerStartHandler as receiving Instance & { server: NonNullable<Instance["server"]> } matches the intended contract that server is definitely set by the time start hooks run. This should give nice, precise types for both .onStart and .on('start', …).

The only thing to double‑check is that every ElysiaAdapter.listen implementation (Bun, Node, Web Standard, etc.) continues to set app.server before invoking any start handlers, and never invokes them in contexts where server might still be null. If that invariant ever changes, this new type will become unsound even though the runtime behavior is unchanged.

Also applies to: 1461-1463