bazis 0.136.0 → 0.138.0

package/core/app/runApp.ts

@@ -2,13 +2,13 @@ import {
   collectModuleUiProfiles,
   collectModuleControllers,
   collectModuleGateways,
-  DI,
   Global,
   Module,
   singletonValue,
   CLASS_PROVIDER_HOOK,
   type BazisModuleRef,
 } from "../di";
+import { DI } from "../di/lowLevel";
 import { loadBazisGeneratedRuntime } from "../generatedRuntime";
 import { missingCacheModuleCheck } from "../cache/http/missingCacheModuleCheck";
 import { cacheableClassProviderHook } from "../cache/di/classProviderHook";
@@ -35,14 +35,16 @@ import { resolveUiProfileAuthoringV1, UiProfileV1Registry, type UiLabels } from
 import { UiSurfaceDocumentProvider, UiSurfaceHttpController } from "./ui/uiSurfaceHttp";
 
 /**
- * Application start options. Everything is optional: without `http` and `grpc` the app
- * starts as a worker/CLI (kernel and hosted services only).
+ * What an application is made of besides its modules. Everything is optional:
+ * without `http` and `grpc` the app starts as a worker/CLI (kernel and hosted
+ * services only).
  */
-export interface RunAppOptions {
+export interface AppSettings {
   /**
    * Start the HTTP server. Controllers are collected from the whole module tree
-   * automatically, no need to list them. Pass `{}` for the defaults
-   * (port 3000) or an object with settings (port/prefix/cors/...).
+   * automatically, no need to list them. Pass `{}` for the defaults or an
+   * object with settings (prefix/cors/...). The address comes from the `http`
+   * settings: `BAZIS_HTTP__HOST`, `BAZIS_HTTP__PORT` (port 3000 by default).
    */
   readonly http?: HttpModuleOptions;
   /** gRPC server; discovers feature-module grpcControllers, independently of HTTP. */
@@ -67,7 +69,7 @@ export interface RunAppOptions {
    * (`new NotFoundError("Книга не найдена")`) are never changed.
    *
    * ```ts
-   * await runApp(AppModule, { language: "ru", http: { port: 3000 } });
+   * @App({ modules: [UsersModule], language: "ru", http: {} })
    * ```
    *
    * Several languages — each request gets the best match of its
@@ -75,7 +77,7 @@ export interface RunAppOptions {
    * and `Vary: Accept-Language`, and `ctx.language` names the choice:
    *
    * ```ts
-   * await runApp(AppModule, { language: { default: "ru", supported: ["ru", "en"] } });
+   * @App({ modules: [UsersModule], language: { default: "ru", supported: ["ru", "en"] } })
    * ```
    */
   readonly language?: AppLanguage | AppLanguageOptions;
@@ -100,7 +102,7 @@ export interface RunAppOptions {
    * their tokens, connections open before the servers and close after them.
    *
    * ```ts
-   * await runApp(AppModule, { infra: AppInfra, http: { port: 3000 } });
+   * @App({ modules: [UsersModule], infra: AppInfra, http: {} })
    * ```
    */
   readonly infra?: BazisModuleRef;
@@ -112,7 +114,7 @@ export interface RunAppOptions {
    *
    * ```ts
    * import { memory } from "@/core/cache";
-   * await runApp(AppModule, { cache: memory({ maxEntries: 1000 }), http: {} });
+   * @App({ modules: [UsersModule], cache: memory({ maxEntries: 1000 }), http: {} })
    * ```
    */
   readonly cache?: BazisModuleRef;
@@ -126,11 +128,71 @@ export interface RunAppOptions {
   readonly ui?: RunAppUiOptions;
 }
 
+/** What `@App` takes: the modules of the application and its {@link AppSettings}. */
+export interface AppOptions extends AppSettings {
+  /** The modules of the application. Their controllers, gateways and background work are found by themselves. */
+  readonly modules: readonly BazisModuleRef[];
+}
+
+/** A class marked `@App`. */
+export type AppClass = abstract new (...args: never) => unknown;
+
+const APP_OPTIONS = Symbol.for("bazis/core/app/options");
+
+/**
+ * Declares the application: its modules, its infrastructure and the servers it
+ * starts. One declaration is read by `runApp` and by the tests, so a test starts
+ * the same application as production does.
+ *
+ * ```ts
+ * // src/app/App.ts
+ * @App({
+ *   modules: [ProjectModule, TaskModule],
+ *   infra: AppInfra,
+ *   http: { health: true },
+ * })
+ * export class TodoApp {}
+ *
+ * // src/index.ts
+ * await registerBazisGeneratedRuntime();
+ * await runApp(TodoApp);
+ *
+ * // a test
+ * const app = await startTestApp(TodoApp);
+ * ```
+ *
+ * The class is also the root module: its `imports` are `modules`.
+ */
+export function App(options: AppOptions) {
+  return (target: AppClass, context: ClassDecoratorContext): void => {
+    if (options === null || typeof options !== "object" || !Array.isArray(options.modules)) {
+      throw new KernelError(`@App on ${target.name || "a class"}: modules must be an array of the application's modules.`);
+    }
+    Module({ imports: options.modules })(target, context);
+    Object.defineProperty(target, APP_OPTIONS, { configurable: false, enumerable: false, writable: false, value: Object.freeze({ ...options }) });
+  };
+}
+
+/** @internal What `@App` declared on a class; `undefined` for anything else. */
+export function appOptionsOf(value: unknown): AppOptions | undefined {
+  return typeof value === "function" && Object.hasOwn(value, APP_OPTIONS) ? (Reflect.get(value, APP_OPTIONS) as AppOptions) : undefined;
+}
+
+/** @internal The settings of an `@App` class without its modules: they are the class's own imports. */
+export function appSettingsOf(app: AppClass): AppSettings {
+  const options = appOptionsOf(app);
+  if (options === undefined) {
+    throw new KernelError(`${typeof app === "function" && app.name ? app.name : "The value"} is not an application: mark the class with @App({ modules: [...] }).`);
+  }
+  const { modules: _modules, ...settings } = options;
+  return settings;
+}
+
 /** Adds the WebSocket module when a module declares gateways; settings alone without gateways are a mistake. */
 function withWebSocket(root: BazisModuleRef, options: WebSocketOptions | undefined): BazisModuleRef {
   if (collectModuleGateways([root]).length === 0) {
     if (options !== undefined) {
-      throw new KernelError("runApp: websocket options are set, but no module declares gateways. Add gateways: [ChatGateway] to the module that owns the gateway.");
+      throw new KernelError("@App: websocket options are set, but no module declares gateways. Add gateways: [ChatGateway] to the module that owns the gateway.");
     }
     return root;
   }
@@ -139,7 +201,7 @@ function withWebSocket(root: BazisModuleRef, options: WebSocketOptions | undefin
 
 function withUiRuntime(
   root: BazisModuleRef,
-  option: RunAppOptions["ui"],
+  option: AppSettings["ui"],
   http: HttpModuleOptions | undefined,
 ): BazisModuleRef {
   const declarations = collectModuleUiProfiles([root]);
@@ -234,7 +296,7 @@ function declarationName(value: unknown): string {
 
 /** @internal Exported for hosting contract tests. */
 export function normalizeUiSurfaceHostingOptions(
-  option: RunAppOptions["ui"],
+  option: AppSettings["ui"],
   http: HttpModuleOptions,
 ): UiSurfaceHostingOptions | undefined {
   if (option === undefined) {
@@ -271,34 +333,36 @@ function normalizeAbsolutePath(path: string): string {
 }
 
 /**
- * The single application entry point, simpler than `NestFactory`.
+ * The single application entry point: starts what `@App` declares.
  *
  * ```ts
- * // main.ts
- * import { runApp } from "@/core/app";
- * import { AppModule } from "./modules/App.module";
+ * // src/index.ts
+ * import { runApp } from "bazis/core/app";
+ * import { TodoApp } from "./app/App";
+ * import { registerBazisGeneratedRuntime } from "./generated/bazis/runtime";
  *
- * await runApp(AppModule, { http: { port: 3000, prefix: "api" } });
+ * await registerBazisGeneratedRuntime();
+ * await runApp(TodoApp);
  * ```
  *
  * It does three things you would otherwise write by hand:
  * 1. starts the HTTP server and collects controllers from the whole module tree;
  * 2. plugs in the request body validator (DIP glue between the kernel and the library);
  * 3. starts the kernel with graceful shutdown on SIGINT/SIGTERM.
- *
- * The root module stays clean: `@Module({ imports: [UsersModule] })`.
  */
-export async function runApp(root: BazisModuleRef, options: RunAppOptions = {}): Promise<number> {
+export async function runApp(app: AppClass): Promise<number> {
   await loadBazisGeneratedRuntime();
-  let app: BazisModuleRef;
+  let options: AppSettings;
+  let composed: BazisModuleRef;
   try {
-    app = composeApp(root, options);
+    options = appSettingsOf(app);
+    composed = composeApp(app, options);
   } catch (error) {
     // Composing already reads routes and options: report its errors like the kernel build does.
     return reportBuildFailure(error);
   }
-  return Bazis.run(app, options.kernel, (builder) => {
-    builder.useApplicationRoot(root);
+  return Bazis.run(composed, options.kernel, (builder) => {
+    builder.useApplicationRoot(app);
     options.configure?.(builder);
   });
 }
@@ -308,7 +372,7 @@ export async function runApp(root: BazisModuleRef, options: RunAppOptions = {}):
  * configs next to the feature root, wrapped in the HTTP/gRPC/UI hosts the
  * options ask for. Shared with `startTestApp`, so tests run the same graph.
  */
-export function composeApp(root: BazisModuleRef, options: RunAppOptions = {}): BazisModuleRef {
+export function composeApp(root: BazisModuleRef, options: AppSettings = {}): BazisModuleRef {
   // Checked even without HTTP: an unknown language is a startup error.
   const languages = createLanguages(options.language, options.messages);
   useCodexLanguage(typeof options.language === "object" ? options.language.default : options.language ?? "en");

package/core/cache/ICache.ts

@@ -67,7 +67,7 @@ export interface ICache<TValue = unknown> {
 export const ICache = createToken<ICache>("ICache") as InjectionToken<ICache<unknown>>;
 
 registerNamedDependencyHint((name) => name === "ICache" || name.startsWith("ICache<")
-  ? "The cache is provided by a cache module: add cache: memory() to the runApp options (startTestApp takes the same options)."
+  ? "The cache is provided by a cache module: add cache: memory() to @App (startTestApp takes the same option)."
   : undefined);
 
 /** Typed token for a specific value type. */

package/core/cache/README.md

@@ -46,7 +46,8 @@ import { memory } from "@/core/cache";
 
 // A self-installing value: the output-cache composer is published through the
 // `ROUTE_MIDDLEWARE_COMPOSER` DI token, and `httpModule` picks it up automatically.
-await runApp(AppModule, { cache: memory({ maxEntries: 1000 }), http: {} });
+@App({ modules: [AppModule], cache: memory({ maxEntries: 1000 }), http: {} })
+export class Application {}
 
 // Named policies/tuning go through the advanced builder:
 import { buildCacheModule } from "@/core/cache";
@@ -70,7 +71,8 @@ import { redisConfig } from "../config/redis.config"; // defineConfig("redis", {
 })
 export class AppInfra {}
 
-await runApp(AppModule, { cache: memory(), infra: AppInfra, http: {} });
+@App({ modules: [AppModule], cache: memory(), infra: AppInfra, http: {} })
+export class Application {}
 ```
 
 `@CacheableRedis` / `@OutputRedisCache` find the backend through DI automatically.

package/core/cache/SPEC.md

@@ -163,10 +163,12 @@ flowchart TB
 import { Cacheable, OutputCache, memory } from "@/core/cache";
 import { runApp } from "@/core/app";
 
-await runApp(AppModule, {
+@App({
+  modules: [AppModule],
   cache: memory(),
   http: { prefix: "api" },
-});
+})
+export class Application {}
 ```
 
 Controller:
@@ -214,7 +216,8 @@ import { AppModule } from "@/app/modules/App.module";
 })
 class AppInfra {}
 
-await runApp(AppModule, { cache: memory(), infra: AppInfra, http: {} });
+@App({ modules: [AppModule], cache: memory(), infra: AppInfra, http: {} })
+export class Application {}
 ```
 
 ```ts
@@ -662,7 +665,7 @@ scoped(IUserStore, UserService, deps);
 
 ### 10.2. Module encapsulation
 
-The application must install the cache module once with `runApp(AppModule, { cache: memory() })`
+The application must install the cache module once with `@App({ cache: memory() })`
 or a root import of `memory()`. A feature module registers only its own service:
 
 ```ts
@@ -795,10 +798,12 @@ The order on a route with `@Authorize` and an output cache:
 Connection: installing the cache module is enough. `memory()` (or `buildCacheModule(...)`) registers the output cache composer through the `ROUTE_MIDDLEWARE_COMPOSER` DI token, and `httpModule` picks it up:
 
 ```ts
-await runApp(AppModule, {
+@App({
+  modules: [AppModule],
   cache: memory(),            // registers the output cache ROUTE_MIDDLEWARE_COMPOSER
   http: {},
-});
+})
+export class Application {}
 ```
 
 No manual `routeMiddlewareComposer` wiring is needed; an explicit
@@ -1040,11 +1045,13 @@ import { redisConfig } from "@/app/config/redis.config";
 })
 class AppInfra {}
 
-await runApp(AppModule, {
+@App({
+  modules: [AppModule],
   infra: AppInfra,
   cache: memory(),
-  http: { port: 3000, prefix: "api" },
-});
+  http: { prefix: "api" },
+})
+export class Application {}
 ```
 
 **Service** (one and the same provider for memory and distributed):

package/core/cache/http/missingCacheModuleCheck.ts

@@ -1,4 +1,5 @@
-import { singletonFactoryWithResolver, type InjectionToken, type ProviderDefinition } from "../../di";
+import { type InjectionToken, type ProviderDefinition } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { ROUTE_MIDDLEWARE_COMPOSER, type RouteMiddlewareComposerRegistration } from "../../http";
 import { LOGGER } from "../../kernel";
 import { outputCacheMetaOf, resolveOutputCacheRequirement } from "../decorators/outputCacheMetadata";
@@ -22,7 +23,7 @@ const OUTPUT_CACHE_COMPOSER_ORDER = 100;
  *   decorator has no effect.
  */
 export function missingCacheModuleCheck(): ProviderDefinition {
-  return singletonFactoryWithResolver(ROUTE_MIDDLEWARE_COMPOSER, [], (resolver): RouteMiddlewareComposerRegistration => {
+  return DI.singleton(DI.factoryProviderWithResolver(ROUTE_MIDDLEWARE_COMPOSER, [], (resolver): RouteMiddlewareComposerRegistration => {
     const cacheInstalled = resolver.tryResolve(ICache) !== undefined;
     const logger = resolver.tryResolve(LOGGER);
     const redis = createRouteOutputCacheComposerWithOptions({
@@ -43,11 +44,11 @@ export function missingCacheModuleCheck(): ProviderDefinition {
         if (requirement === undefined || requirement.enabled === false) return [];
         const message = `[cache] @OutputCache on ${controllerClass.name}.${String(methodName)} has no effect: `
           + "no cache module is installed, so every request runs the action. "
-          + "Add `cache: memory()` to the runApp options.";
+          + "Add `cache: memory()` to @App.";
         if (logger) logger.warn(message);
         else console.warn(message);
         return [];
       },
     };
-  });
+  }));
 }

package/core/cache/internal/buildCacheProviders.ts

@@ -1,15 +1,14 @@
 import {
-  DI,
   CLASS_PROVIDER_HOOK,
   OptionsValidationError,
   singleton,
-  singletonFactoryWithResolver,
   singletonValue,
   type InjectionToken,
   type Options,
   type BazisModuleRef,
   type ProviderDefinition,
 } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { ROUTE_MIDDLEWARE_COMPOSER, type RouteMiddlewareComposerRegistration } from "../../http";
 import { HEALTH_CHECK } from "../../kernel";
 import { cacheableClassProviderHook } from "../di/classProviderHook";
@@ -82,7 +81,7 @@ function buildCacheProviders(config: CacheModuleConfig): ProviderDefinition[] {
     singletonValue(CLASS_PROVIDER_HOOK, cacheableClassProviderHook),
     cacheOptionsProvider(config),
     DI.singleton(DI.valueProvider(CACHE_POLICIES, policies)),
-    singleton(token, MemoryCache, [CACHE_OPTIONS] as const),
+    DI.singleton(DI.classProvider(token, MemoryCache, [CACHE_OPTIONS] as const)),
     outputCacheComposerProvider(config),
   ];
 
@@ -115,7 +114,7 @@ function cacheOptionsProvider(config: CacheModuleConfig): ProviderDefinition {
 /** Registers the `@OutputCache` / `@OutputRedisCache` middleware via the HTTP DI token. */
 function outputCacheComposerProvider(config: CacheModuleConfig): ProviderDefinition {
   const token = config.token ?? ICache;
-  return singletonFactoryWithResolver(ROUTE_MIDDLEWARE_COMPOSER, [], (resolver) => ({
+  return DI.singleton(DI.factoryProviderWithResolver(ROUTE_MIDDLEWARE_COMPOSER, [], (resolver) => ({
     order: OUTPUT_CACHE_COMPOSER_ORDER,
     compose: createRouteOutputCacheComposerWithOptions({
       policies: config.policies ?? {},
@@ -129,7 +128,7 @@ function outputCacheComposerProvider(config: CacheModuleConfig): ProviderDefinit
       // start fails and names the route instead of every request failing.
       distributedEnabled: resolver.has(DISTRIBUTED_OUTPUT_CACHE),
     }),
-  } satisfies RouteMiddlewareComposerRegistration));
+  } satisfies RouteMiddlewareComposerRegistration)));
 }
 
 function outputCacheSecurityBehavior(options: CacheOutputCacheOptions | undefined): "throw" | "warn" | "ignore" {

package/core/cache/providers/cachedProviders.ts

@@ -1,11 +1,11 @@
 import {
-  DI,
   type Class,
   type ProviderDefinition,
   type ProviderDependencyList,
   type ServiceResolver,
   type Token,
 } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { randomUUID } from "node:crypto";
 import { ICache } from "../ICache";
 import { CACHE_POLICIES } from "../tokens/CACHE_POLICIES";

package/core/di/index.ts

@@ -32,7 +32,6 @@ export {
   Global,
   markGlobal,
   Module,
-  DI,
   registerModuleMetadataExpander,
   registerModuleOwnedContributionValidator,
   registerModuleOwnedProviderContributor,
@@ -43,9 +42,6 @@ export {
   scoped,
   singleton,
   singletonAsyncFactory,
-  singletonAsyncFactoryWithResolver,
-  singletonFactory,
-  singletonFactoryWithResolver,
   singletonValue,
   transient,
   type DiRegistrar,

package/core/di/lowLevel.ts

@@ -0,0 +1,12 @@
+/**
+ * Low-level provider forms: providers built by hand, factories, dependency
+ * lists, classes bound to their dependencies. The framework's own modules and
+ * packages that extend it (a connector, a host) use them.
+ *
+ * An application does not need this entry point: it registers its services in
+ * the agreed forms of `bazis/core/di` — `scoped(IService, Service)`,
+ * `singleton(...)`, `transient(...)`, `singletonValue(TOKEN, value)`,
+ * `singletonAsyncFactory(TOKEN, [deps], factory)` — and codegen refuses the
+ * forms of this file in `@Module({ providers })` of an application.
+ */
+export { DI } from "./module/DI";

package/core/di/module/index.ts

@@ -34,9 +34,6 @@ export {
   scoped,
   singleton,
   singletonAsyncFactory,
-  singletonAsyncFactoryWithResolver,
-  singletonFactory,
-  singletonFactoryWithResolver,
   singletonValue,
   transient,
 } from "./shortcuts";

package/core/di/module/shortcuts.ts

@@ -1,95 +1,47 @@
 import type { Class, Token } from "../token";
-import type { ServiceResolver } from "../types";
-import type {
-  ProviderDefinition,
-  ProviderDependencyList,
-  ResolvedDeps,
-} from "../provider";
+import type { ProviderDefinition, ProviderDependencyList, ResolvedDeps } from "../provider";
 import { DI } from "./DI";
 
-function registerClassProvider<T, D extends ProviderDependencyList>(
-  lifetime: "singleton" | "scoped" | "transient",
-  provide: Token<T>,
-  useClass: Class<T>,
-  deps?: D,
-): ProviderDefinition<T> {
-  const factory = lifetime === "singleton" ? DI.singleton : lifetime === "scoped" ? DI.scoped : DI.transient;
-  return factory(DI.classProvider(provide, useClass, deps));
+type Lifetime = "singleton" | "scoped" | "transient";
+
+/** A class under its contract, or under itself. Its constructor dependencies come from codegen. */
+function classProvider<T>(lifetime: Lifetime, provide: Token<T>, useClass: Class<T> | undefined): ProviderDefinition<T> {
+  const register = lifetime === "singleton" ? DI.singleton : lifetime === "scoped" ? DI.scoped : DI.transient;
+  return register(DI.classProvider(provide, useClass ?? (provide as Class<T>)));
 }
 
+/**
+ * One instance for the whole application.
+ *
+ * ```ts
+ * singleton(IClock, SystemClock) // under a contract
+ * singleton(Metrics)             // the class is its own contract
+ * ```
+ */
 export function singleton<T>(useClass: Class<T>): ProviderDefinition<T>;
-export function singleton<T, D extends ProviderDependencyList = []>(
-  provide: Token<T>,
-  useClass: Class<T>,
-  deps?: D,
-): ProviderDefinition<T>;
-export function singleton<T, D extends ProviderDependencyList = []>(
-  provide: Token<T>,
-  useClass?: Class<T>,
-  deps?: D,
-): ProviderDefinition<T> {
-  if (!useClass) {
-    const classOnly = provide as Class<T>;
-    return registerClassProvider("singleton", classOnly, classOnly);
-  }
-
-  return registerClassProvider("singleton", provide, useClass, deps);
+export function singleton<T>(provide: Token<T>, useClass: Class<T>): ProviderDefinition<T>;
+export function singleton<T>(provide: Token<T>, useClass?: Class<T>): ProviderDefinition<T> {
+  return classProvider("singleton", provide, useClass);
 }
 
+/** One instance per scope: an HTTP request, a job, a message. */
 export function scoped<T>(useClass: Class<T>): ProviderDefinition<T>;
-export function scoped<T, D extends ProviderDependencyList = []>(
-  provide: Token<T>,
-  useClass: Class<T>,
-  deps?: D,
-): ProviderDefinition<T>;
-export function scoped<T, D extends ProviderDependencyList = []>(
-  provide: Token<T>,
-  useClass?: Class<T>,
-  deps?: D,
-): ProviderDefinition<T> {
-  if (!useClass) {
-    const classOnly = provide as Class<T>;
-    return registerClassProvider("scoped", classOnly, classOnly);
-  }
-
-  return registerClassProvider("scoped", provide, useClass, deps);
+export function scoped<T>(provide: Token<T>, useClass: Class<T>): ProviderDefinition<T>;
+export function scoped<T>(provide: Token<T>, useClass?: Class<T>): ProviderDefinition<T> {
+  return classProvider("scoped", provide, useClass);
 }
 
+/** A new instance each time it is asked for. */
 export function transient<T>(useClass: Class<T>): ProviderDefinition<T>;
-export function transient<T, D extends ProviderDependencyList = []>(
-  provide: Token<T>,
-  useClass: Class<T>,
-  deps?: D,
-): ProviderDefinition<T>;
-export function transient<T, D extends ProviderDependencyList = []>(
-  provide: Token<T>,
-  useClass?: Class<T>,
-  deps?: D,
-): ProviderDefinition<T> {
-  if (!useClass) {
-    const classOnly = provide as Class<T>;
-    return registerClassProvider("transient", classOnly, classOnly);
-  }
-
-  return registerClassProvider("transient", provide, useClass, deps);
-}
-
-export function singletonFactory<T, D extends ProviderDependencyList>(
-  provide: Token<T>,
-  deps: D,
-  useFactory: (...args: ResolvedDeps<D>) => T,
-): ProviderDefinition<T> {
-  return DI.singleton(DI.factoryProvider(provide, deps, useFactory));
-}
-
-export function singletonFactoryWithResolver<T, D extends ProviderDependencyList>(
-  provide: Token<T>,
-  deps: D,
-  useFactory: (resolver: ServiceResolver, ...args: ResolvedDeps<D>) => T,
-): ProviderDefinition<T> {
-  return DI.singleton(DI.factoryProviderWithResolver(provide, deps, useFactory));
+export function transient<T>(provide: Token<T>, useClass: Class<T>): ProviderDefinition<T>;
+export function transient<T>(provide: Token<T>, useClass?: Class<T>): ProviderDefinition<T> {
+  return classProvider("transient", provide, useClass);
 }
 
+/**
+ * A resource that is created asynchronously, once, at startup: a connection, a
+ * loaded key. Everything else is a class with a constructor.
+ */
 export function singletonAsyncFactory<T, D extends ProviderDependencyList>(
   provide: Token<T>,
   deps: D,
@@ -98,14 +50,7 @@ export function singletonAsyncFactory<T, D extends ProviderDependencyList>(
   return DI.singleton(DI.asyncFactoryProvider(provide, deps, useAsyncFactory));
 }
 
-export function singletonAsyncFactoryWithResolver<T, D extends ProviderDependencyList>(
-  provide: Token<T>,
-  deps: D,
-  useAsyncFactory: (resolver: ServiceResolver, ...args: ResolvedDeps<D>) => Promise<T>,
-): ProviderDefinition<T> {
-  return DI.singleton(DI.asyncFactoryProviderWithResolver(provide, deps, useAsyncFactory));
-}
-
+/** A ready value under a token: a constant, a test double. */
 export function singletonValue<T>(provide: Token<T>, useValue: T): ProviderDefinition<T> {
   return DI.singleton(DI.valueProvider(provide, useValue));
 }

package/core/generatedRuntime.ts

@@ -139,8 +139,14 @@ async function loadRuntimeOnce(): Promise<void> {
  * (`bazis new --link-framework`) would otherwise find that checkout's own
  * `src/generated` next to its sources. Framework sources inside the project
  * (`src/bazis`) find the same directory either way.
+ *
+ * A compiled binary looks nowhere: its generated code is inside it and comes
+ * through `registerBazisGeneratedRuntime()` of the entry point. Reading
+ * `src/generated` of whatever directory the binary was started in would run
+ * another project's code.
  */
 async function importGeneratedModule<T>(name: string): Promise<T | undefined> {
+  if (isCompiledBinary()) return undefined;
   const candidates = [path.join(process.cwd(), "src/generated/bazis", name), `../../generated/bazis/${name}`];
   for (const candidate of candidates) {
     try {
@@ -152,6 +158,11 @@ async function importGeneratedModule<T>(name: string): Promise<T | undefined> {
   return undefined;
 }
 
+/** Whether this code runs from a `bun build --compile` binary: its modules live in Bun's embedded file system. */
+function isCompiledBinary(): boolean {
+  return import.meta.url.includes("/$bunfs/") || import.meta.url.includes("~BUN");
+}
+
 function isOptionalGeneratedModuleMissing(error: unknown, generatedPath: string): boolean {
   const message = error instanceof Error ? error.message : String(error);
   return message.includes("Cannot find module") && message.includes(generatedPath);

package/core/grpc/Grpc.module.ts

@@ -1,4 +1,5 @@
-import { DI, DiContainer, HOSTED_SERVICE, Module, SERVICE_PROVIDER, type BazisModule } from "../di";
+import { DiContainer, HOSTED_SERVICE, Module, SERVICE_PROVIDER, type BazisModule } from "../di";
+import { DI } from "../di/lowLevel";
 import type { GrpcModuleOptions } from "./contracts";
 import { GrpcServer } from "./GrpcServer";
 import { collectGrpcControllers, GRPC_CONTROLLERS } from "./moduleControllers";

package/core/grpc/grpcClients.ts

@@ -1,4 +1,5 @@
-import { DI, registerModuleMetadataExpander, type BazisModuleMetadata, type BazisModuleRef, type ServiceResolver } from "../di";
+import { registerModuleMetadataExpander, type BazisModuleMetadata, type BazisModuleRef, type ServiceResolver } from "../di";
+import { DI } from "../di/lowLevel";
 import type { ConfigDefinition } from "../kernel";
 import type { GrpcClientOptions } from "./clientContracts";
 import { GrpcClientBase } from "./GrpcClientBase";

package/core/http/Authorization/metadata.ts

@@ -208,7 +208,7 @@ export function resolveAuthorizeMeta(ctor: object, methodName: string | symbol):
 }
 
 /**
- * The checks a route runs: the server's default checks (`runApp({ http:
+ * The checks a route runs: the server's default checks (`@App({ http:
  * { authorize } })`) first, then the route's own `@Authorize`; each function
  * once. `undefined` — the route is open: `@AllowAnonymous`, or no checks at all.
  */

package/core/http/Decorators/metadata.ts

@@ -1,5 +1,6 @@
 import type { Class } from "../../di";
 import type { ActionFilterHooks, HttpMiddleware } from "../Middleware/types";
+import type { HttpResult } from "../Results/HttpResult";
 
 // Same one-line polyfill as the validation module: Bun executes TC39
 // decorators natively, Symbol.metadata may be missing in the runtime.
@@ -26,6 +27,8 @@ export interface CatchDeclaration {
 export interface ActionMeta {
   routes: RouteDeclaration[];
   httpCode?: number;
+  /** `nullAs` of the route options: the result that stands for `null`. */
+  nullAs?: () => HttpResult;
   produces?: string;
   consumes?: string;
   version?: string;