feat: refine public API exports

AGENTS.md

@@ -32,6 +32,11 @@ Keep implementation, runtime tests, and type tests close together in `src/`.
 When adding a public symbol, export it through the nearest barrel file and make
 sure it is reachable from `src/index.ts`.
 
+The folder barrel files intentionally enumerate the public API. Do not replace
+their named exports with `export *`: registration, resolution, identity, cache,
+and builder implementations must remain internal. Internal code should import
+those symbols from their defining files rather than from a public barrel.
+
 ## Runtime model and invariants
 
 - A module registers, in order: hooks, installers, controllers, then child

package.json

@@ -37,7 +37,6 @@
   "license": "MIT",
   "devDependencies": {
     "@eslint/js": "^9.39.4",
-    "@sinclair/typebox": "^0.34.49",
     "@types/node": "^25.9.4",
     "c8": "^10.1.3",
     "eslint": "^9.39.4",
@@ -51,6 +50,7 @@
     "typescript-eslint": "^8.62.0"
   },
   "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
     "fastify": "^5.8.5",
     "fastify-plugin": "^5.1.0"
   },

src/container/container.ts

@@ -1,10 +1,10 @@
-import { ModuleContext } from "../modules";
+import type { ModuleContext } from "../modules/module.types";
 import type {
   DepValues,
   ProviderAny,
   ProviderDef,
   BaseProviderDepsMap,
-} from "../providers";
+} from "../providers/providers.types";
 
 export class Container {
   private singletons = new WeakMap<object, Promise<unknown>>();

src/controllers/controllers.ts

@@ -1,11 +1,9 @@
-import type { ProvidersMap } from "../providers";
+import type { ProvidersMap } from "../providers/providers.types";
 import { RoutesBuilder } from "./routes-builder";
-import {
-  ControllerConfig,
-  ControllerOptions,
-  resolveProviderMap,
-} from "../modules";
-import { AdapterMap, resolveAdapterMap } from "../fastify";
+import type { ControllerConfig, ControllerOptions } from "./controllers.types";
+import { resolveProviderMap } from "../modules/module";
+import { resolveAdapterMap } from "../fastify/adapters";
+import type { AdapterMap } from "../fastify/adapters.types";
 
 export function createController<
   Providers extends ProvidersMap,
@@ -46,5 +44,3 @@ export function createController<
     },
   };
 }
-
-export const controller = createController;

src/controllers/controllers.types.ts

@@ -20,8 +20,12 @@ import { Static, TSchema } from "@sinclair/typebox";
 import { ExposeDeps, ProvidersMap } from "../providers";
 import { RoutesBuilder } from "./routes-builder";
 import { Container } from "../container/container";
-import { AdapterCache, AdapterMap, AdapterValues } from "../fastify";
-import { ModuleContext } from "../modules";
+import type {
+  AdapterCache,
+  AdapterMap,
+  AdapterValues,
+} from "../fastify/adapters.types";
+import type { ModuleContext } from "../modules/module.types";
 
 type ErrorHandler = (
   error: unknown,

src/controllers/index.ts

@@ -1,3 +1,12 @@
-export * from "./routes-builder";
-export * from "./controllers";
-export * from "./controllers.types";
+export {
+  createController,
+  createController as controller,
+} from "./controllers";
+export type {
+  BaseStratifyRouteOptions,
+  ControllerBuilderCallback,
+  ControllerConfig,
+  ControllerOptions,
+  ExtractRouteGenerics,
+  StratifyRouteOptions,
+} from "./controllers.types";

src/fastify/adapter-fastify-instance.ts

@@ -51,11 +51,11 @@ const forbiddenAdapterFastifyProperties = [
   "addHttpMethod",
   "addConstraintStrategy",
   "supportedMethods",
-  Symbol.asyncDispose,
 ] as const;
 
 type ForbiddenAdapterFastifyProperty =
-  (typeof forbiddenAdapterFastifyProperties)[number];
+  | (typeof forbiddenAdapterFastifyProperties)[number]
+  | Extract<keyof FastifyInstance, symbol>;
 
 /**
  * Read-only Fastify view available to adapters.
@@ -68,9 +68,10 @@ export type AdapterFastifyInstance = Readonly<
   Omit<FastifyInstance, ForbiddenAdapterFastifyProperty>
 >;
 
-const forbiddenProperties = new Set<PropertyKey>(
-  forbiddenAdapterFastifyProperties,
-);
+const forbiddenProperties = new Set<PropertyKey>([
+  ...forbiddenAdapterFastifyProperties,
+  Symbol.asyncDispose,
+]);
 
 export function restrictFastifyForAdapter(
   fastify: FastifyInstance,

src/fastify/adapters.ts

@@ -45,5 +45,3 @@ export async function resolveAdapterMap<AMap extends AdapterMap>(
 
   return out as AdapterValues<AMap>;
 }
-
-export const adapter = createAdapter;

src/fastify/index.ts

@@ -1,4 +1,15 @@
-export * from "./installers";
-export * from "./installers.types";
-export * from "./adapters";
-export * from "./adapters.types";
+export { createAdapter, createAdapter as adapter } from "./adapters";
+export { createInstaller, createInstaller as installer } from "./installers";
+export type {
+  AdapterAny,
+  AdapterDef,
+  AdapterFastifyInstance,
+  AdapterMap,
+  AdapterOptions,
+  AdapterValues,
+} from "./adapters.types";
+export type {
+  InstallerBuilderCallback,
+  InstallerConfig,
+  InstallerOptions,
+} from "./installers.types";

src/fastify/installers.ts

@@ -1,7 +1,8 @@
 import type { FastifyInstance } from "fastify";
-import type { ProvidersMap } from "../../src/providers";
+import type { ProvidersMap } from "../providers/providers.types";
 import type { Container } from "../../src/container/container";
-import { resolveProviderMap, type ModuleContext } from "../../src/modules";
+import { resolveProviderMap } from "../modules/module";
+import type { ModuleContext } from "../modules/module.types";
 import type { InstallerOptions, InstallerConfig } from "./installers.types";
 
 export function createInstaller<Providers extends ProvidersMap>(
@@ -28,5 +29,3 @@ export function createInstaller<Providers extends ProvidersMap>(
     },
   };
 }
-
-export const installer = createInstaller;

src/fastify/installers.types.ts

@@ -1,7 +1,7 @@
 import type { FastifyInstance } from "fastify";
 import type { ProvidersMap, ExposeDeps } from "../../src/providers";
 import type { Container } from "../../src/container/container";
-import { ModuleContext } from "../modules";
+import type { ModuleContext } from "../modules/module.types";
 
 /**
  * Installer builder callback.

src/hooks/hooks.ts

@@ -1,5 +1,5 @@
 import { FastifyInstance } from "fastify";
-import { ProvidersMap } from "../providers";
+import type { ProvidersMap } from "../providers/providers.types";
 import {
   AppHooksConfig,
   AppHooksOptions,
@@ -9,8 +9,10 @@ import {
 import { Container } from "../container/container";
 import { HttpHooksBuilder } from "./http-hooks-builder";
 import { AppHooksBuilder } from "./application-hooks-builder";
-import { ModuleContext, resolveProviderMap } from "../modules";
-import { AdapterCache, AdapterMap, resolveAdapterMap } from "../fastify";
+import { resolveProviderMap } from "../modules/module";
+import type { ModuleContext } from "../modules/module.types";
+import { resolveAdapterMap } from "../fastify/adapters";
+import type { AdapterCache, AdapterMap } from "../fastify/adapters.types";
 
 export function createHooks<
   Providers extends ProvidersMap,
@@ -71,5 +73,3 @@ export function createHooks<
     },
   };
 }
-
-export const hooks = createHooks;

src/hooks/hooks.types.ts

@@ -7,13 +7,16 @@ import {
   RequestPayload,
   RouteOptions,
 } from "fastify";
-import { ApplicationHook, LifecycleHook } from "fastify/types/hooks";
 import { HttpHooksBuilder } from "./http-hooks-builder";
 import { ExposeDeps, ProvidersMap } from "../providers";
 import { Container } from "../container/container";
 import { AppHooksBuilder } from "./application-hooks-builder";
-import { AdapterCache, AdapterMap, AdapterValues } from "../fastify";
-import { ModuleContext } from "../modules";
+import type {
+  AdapterCache,
+  AdapterMap,
+  AdapterValues,
+} from "../fastify/adapters.types";
+import type { ModuleContext } from "../modules/module.types";
 
 // --- HTTP  hooks ---
 export type OnRequestHandler = (
@@ -60,8 +63,6 @@ export type OnRequestAbortHandler = (
   request: FastifyRequest,
 ) => Promise<unknown>;
 
-export type HttpHookName = LifecycleHook;
-
 export type HttpHookMap = {
   onRequest: OnRequestHandler[];
   preParsing: OnPreParsingHandler[];
@@ -75,6 +76,8 @@ export type HttpHookMap = {
   onRequestAbort: OnRequestAbortHandler[];
 };
 
+export type HttpHookName = keyof HttpHookMap;
+
 export type HttpHookHandlers<K extends keyof HttpHookMap> = HttpHookMap[K];
 export type HttpHookHandler<K extends keyof HttpHookMap> =
   HttpHookHandlers<K>[number];
@@ -133,8 +136,6 @@ export type OnRegisterHandler = (
   opts: RegisterOptions & FastifyPluginOptions,
 ) => void;
 
-export type AppHookName = ApplicationHook;
-
 export type AppHookMap = {
   onReady: OnReadyHandler[];
   onClose: OnCloseHandler[];
@@ -144,6 +145,8 @@ export type AppHookMap = {
   preClose: OnPreCloseHandler[];
 };
 
+export type AppHookName = keyof AppHookMap;
+
 type ApplicationHooksBuilderCallback<
   Providers extends ProvidersMap,
   Adaps extends AdapterMap,

src/hooks/index.ts

@@ -1,4 +1,29 @@
-export * from "./hooks.types";
-export * from "./hooks";
-export * from "./http-hooks-builder";
-export * from "./application-hooks-builder";
+export { createHooks, createHooks as hooks } from "./hooks";
+export type {
+  AppHookMap,
+  AppHookName,
+  AppHooksConfig,
+  AppHooksOptions,
+  HttpHookHandler,
+  HttpHookHandlers,
+  HttpHookMap,
+  HttpHookName,
+  HttpHooksConfig,
+  HttpHooksOptions,
+  OnCloseHandler,
+  OnErrorHookHandler,
+  OnListenHandler,
+  OnPreCloseHandler,
+  OnPreHandlerHandler,
+  OnPreParsingHandler,
+  OnPreSerializationHandler,
+  OnPreValidationHandler,
+  OnReadyHandler,
+  OnRegisterHandler,
+  OnRequestAbortHandler,
+  OnRequestHandler,
+  OnResponseHandler,
+  OnRouteHandler,
+  OnSendHookHandler,
+  OnTimeoutHandler,
+} from "./hooks.types";

src/index.ts

@@ -9,10 +9,12 @@ export * from "./hooks";
 export * from "./controllers";
 export * from "./fastify";
 
-import { getProviderId, resolveDeps, type ProviderAny } from "./providers";
+import { getProviderId, resolveDeps } from "./providers/providers";
+import type { ProviderAny } from "./providers/providers.types";
 import { Container } from "./container/container";
 import { describeTree } from "./printer/describe-tree";
-import { getModuleId, ModuleAny, registerModule } from "./modules";
+import { getModuleId, registerModule } from "./modules/module";
+import type { ModuleAny } from "./modules/module.types";
 
 export interface CreateAppOptions {
   root: ModuleAny;

src/modules/index.ts

@@ -1,3 +1,7 @@
-export * from "./module";
-export * from "./module.types";
-export * from "../controllers/controllers.types";
+export { createModule, createModule as mod } from "./module";
+export type {
+  ModuleAny,
+  ModuleDef,
+  ModuleOptions,
+  SubModulesMap,
+} from "./module.types";

src/modules/module.ts

@@ -8,8 +8,8 @@ import {
   ModuleOptions,
   SubModulesMap,
 } from "./module.types";
-import { ProvidersMap } from "../providers";
-import { AdapterCache } from "../fastify";
+import type { AdapterCache } from "../fastify/adapters.types";
+import type { ProvidersMap } from "../providers/providers.types";
 
 const kModuleId = Symbol("fastify-dependency-injection:moduleId");
 let __seq = 0;
@@ -97,5 +97,3 @@ export async function resolveProviderMap(
 
   return out;
 }
-
-export const mod = createModule;

src/printer/describe-tree.ts

@@ -1,6 +1,8 @@
-import { AdapterAny } from "../fastify";
-import { getModuleId, type ModuleAny } from "../modules";
-import { getProviderId, type ProviderAny } from "../providers";
+import type { AdapterAny } from "../fastify/adapters.types";
+import { getModuleId } from "../modules/module";
+import type { ModuleAny } from "../modules/module.types";
+import { getProviderId } from "../providers/providers";
+import type { ProviderAny } from "../providers/providers.types";
 
 const useColor = process.stdout.isTTY;
 const wrap = (code: number, s: string, enabled: boolean) => {

src/providers/index.ts

@@ -1,2 +1,16 @@
-export * from "./providers";
-export * from "./providers.types";
+export {
+  contract,
+  createProvider,
+  createProvider as provider,
+} from "./providers";
+export type {
+  BaseProviderDepsMap,
+  DepValues,
+  ExposeDeps,
+  InferProviderContract,
+  ProviderAny,
+  ProviderContract,
+  ProviderDef,
+  ProviderOptions,
+  ProvidersMap,
+} from "./providers.types";