bazis 0.98.20 → 0.98.22

package/core/di/errors/NamedDependencyNotFoundError.ts

@@ -1,7 +1,18 @@
 import { DiError } from "./DiError";
 
+/** Returns a hint for a named dependency nobody registers, or `undefined`. */
+export type NamedDependencyHint = (name: string) => string | undefined;
+
+const hints: NamedDependencyHint[] = [];
+
+/** Infrastructure extensions (ORM repositories, …) explain their own named dependencies here. */
+export function registerNamedDependencyHint(hint: NamedDependencyHint): void {
+  hints.push(hint);
+}
+
 export class NamedDependencyNotFoundError extends DiError {
   public constructor(name: string) {
-    super(`No provider token found for named dependency "${name}".`);
+    const hint = hints.map((item) => item(name)).find((text) => text !== undefined);
+    super(`No provider token found for named dependency "${name}".${hint ? ` ${hint}` : ""}`);
   }
 }

package/core/di/module/encapsulation.ts

@@ -84,7 +84,9 @@ export function validateModuleEncapsulation(
         if (isFamilyExport(ref)) {
           continue;
         }
-        if (record.providedTokens.has(ref) || visible.has(ref)) {
+        // A closed token of a visible family (`repositoryFor(Product)` next to an
+        // `ormBazis` that exports the whole `IRepository` family) may be passed on alone.
+        if (record.providedTokens.has(ref) || visible.has(ref) || (typeof ref !== "function" && ref.genericFamilyId !== undefined && allProvidedTokens.has(ref) && visibleFamilies(record).has(ref.genericFamilyId))) {
           result.add(ref);
         } else {
           issues.push(
@@ -173,6 +175,10 @@ export function validateModuleEncapsulation(
   // Why a provided token is not visible: the owner does not export it, or the
   // consumer module does not import the owner. Both used to read "not exported".
   const explainHidden = (token: Token<unknown>, consumer: ModuleGraphRecord): string => {
+    if (typeof token !== "function" && token.genericFamilyId !== undefined) {
+      const family = explainHiddenFamily(token, token.genericFamilyId, consumer);
+      if (family !== undefined) return family;
+    }
     // A module the consumer imports already sees the token but does not pass it
     // on. That export is the fix, whatever inner module (an `ormBazis` feature
     // module, say) registered the token.
@@ -188,6 +194,31 @@ export function validateModuleEncapsulation(
       : `which module "${owner.name}" provides but does not export. Add it to the exports of "${owner.name}".`;
   };
 
+  // A closed token (`IRepository<Product>`) travels with its family export, so
+  // the fix is named in family terms and skips unnamed inner modules such as
+  // the one `ormBazis` creates.
+  const explainHiddenFamily = (token: Token<unknown>, familyId: symbol, consumer: ModuleGraphRecord): string | undefined => {
+    const closed = tokenToDebugName(token);
+    const family = closed.includes("<") ? closed.slice(0, closed.indexOf("<")) : closed;
+    const exportFix = `${family} (or only ${closed})`;
+    const sees = (record: ModuleGraphRecord) => visibleFamilies(record).has(familyId) || visibleTokens(record).has(token);
+    const passes = (record: ModuleGraphRecord) => exportedFamilies(record).has(familyId) || exportedTokens(record).has(token);
+    const named = (record: ModuleGraphRecord) => !/^module#\d+$/.test(record.name);
+    const blocking = consumer.imports.find((imported) => named(imported) && sees(imported) && !passes(imported));
+    if (blocking !== undefined) {
+      return `which its import "${blocking.name}" receives from its own imports but does not export. Add ${exportFix} to the exports of "${blocking.name}".`;
+    }
+    const exporter = records.find((record) => record !== consumer && named(record) && passes(record));
+    if (exporter !== undefined) {
+      return `which module "${exporter.name}" exports, but "${consumer.name}" does not list "${exporter.name}" in its imports. Add "${exporter.name}" to the imports of "${consumer.name}".`;
+    }
+    const host = records.find((record) => record !== consumer && named(record) && sees(record));
+    if (host !== undefined) {
+      return `which module "${host.name}" receives from its own imports but does not export. Add ${exportFix} to the exports of "${host.name}" and "${host.name}" to the imports of "${consumer.name}".`;
+    }
+    return undefined;
+  };
+
   const contexts = new Map<ModuleGraphRecord, DependencyCheckContext>();
   for (let recordIndex = 0; recordIndex < records.length; recordIndex += 1) {
     const record = records[recordIndex] as ModuleGraphRecord;
@@ -302,7 +333,7 @@ function checkDependency(
       !context.familiesVisible.has(token.genericFamilyId)
     ) {
       context.issues.push(
-        `Module "${record.name}": "${consumer}" depends on open generic "${tokenToDebugName(token)}", whose family is not exported by any imported module.`,
+        `Module "${record.name}": "${consumer}" depends on "${tokenToDebugName(token)}", ${context.explainHidden(token, record)}`,
       );
     }
     return;
@@ -363,6 +394,7 @@ export function computeModuleVisibleTokens(
 ): Map<ModuleGraphRecord, Set<Token<unknown>>> {
   const exportedMemo = new Map<ModuleGraphRecord, Set<Token<unknown>>>();
   const visiting = new Set<ModuleGraphRecord>();
+  const allProvided = new Set<Token<unknown>>(records.flatMap((record) => [...record.providedTokens]));
 
   const visibleOf = (record: ModuleGraphRecord): Set<Token<unknown>> => {
     const result = new Set<Token<unknown>>(record.providedTokens);
@@ -401,7 +433,8 @@ export function computeModuleVisibleTokens(
         if (isFamilyExport(ref)) {
           continue;
         }
-        if (record.providedTokens.has(ref) || visible.has(ref)) {
+        // Validation already admitted closed tokens re-exported from a visible family.
+        if (record.providedTokens.has(ref) || visible.has(ref) || (typeof ref !== "function" && ref.genericFamilyId !== undefined && allProvided.has(ref))) {
           result.add(ref);
         }
       }

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.20" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.22" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/orm/OrmHostedPlan.validator.ts

@@ -50,7 +50,7 @@ function validateOrmHostedPlan(services: readonly HostedService[]): void {
       const owner = (service as { __bazisSchemaOwner?: { context: string; mode: string } }).__bazisSchemaOwner;
       return owner ? `${owner.context} uses ${owner.mode}` : "a module uses migrateOnStart or migrations";
     };
-    throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", `Schema admission and legacy ORM schema authority cannot be composed together: ${[...strict, ...legacy].map(describe).join(", ")}. Use one schema mode in the application: ensureCreated in every module, or migrateOnStart/migrations in every module.`);
+    throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", `Schema admission and legacy ORM schema authority cannot be composed together: ${[...strict, ...legacy].map(describe).join(", ")}. Use one schema mode in the application: ensureCreated (with or without migrations) in every module, or migrateOnStart/migrations without ensureCreated in every module.`);
   }
   for (const service of services) {
     const framework = isOrmProviderLifecycle(service)

package/core/orm/OrmLifecycle.ts

@@ -1,6 +1,6 @@
 import { ormHostedPlanValidator } from "./OrmHostedPlan.validator";
 import type { HostedService } from "../di";
-import { DatabaseFacade, type DbContextOptions, type Migration } from "../../library/orm";
+import { DatabaseFacade, type DbContextOptions, type EnsureCreatedWithMigrationsResult, type Migration } from "../../library/orm";
 import { compileExpectedSchema } from "../../library/orm/Schema/ExpectedSchema";
 
 /**
@@ -29,6 +29,8 @@ export class OrmLifecycle implements HostedService {
   };
   /** Internal hosted-plan marker: the context and its startup schema mode, for readable plan errors. */
   readonly __bazisSchemaOwner: { readonly context: string; readonly mode: string };
+  /** `ensureCreated` owns the versioned migrations of this context (run or baselined before the check). */
+  private readonly withMigrations: boolean;
   private connectionClosed = false;
   private closePromise?: Promise<void>;
 
@@ -48,6 +50,7 @@ export class OrmLifecycle implements HostedService {
     contextName = "DbContext",
   ) {
     const modes = [ensureCreated && "ensureCreated", migrateOnStart && "migrateOnStart", runMigrationsOnStart && migrations.length > 0 && "migrations"].filter(Boolean);
+    this.withMigrations = ensureCreated && runMigrationsOnStart && migrations.length > 0;
     this.__bazisSchemaOwner = Object.freeze({ context: contextName, mode: modes.join(" + ") || "none" });
     this.phase = ensureCreated && options.provider.name === "postgres" ? -105 : -100;
     this.__bazisLegacySchemaAuthority = this.phase === -100 && (ensureCreated || migrateOnStart || (runMigrationsOnStart && migrations.length > 0));
@@ -72,10 +75,17 @@ export class OrmLifecycle implements HostedService {
     const database = new DatabaseFacade(this.options.provider, this.options.model);
     try {
       if (this.ensureCreated) {
-        const result = await database.ensureCreated();
+        const result: Partial<EnsureCreatedWithMigrationsResult> & Pick<EnsureCreatedWithMigrationsResult, "warnings"> = this.withMigrations ? await database.ensureCreatedWithMigrations(this.migrations) : await database.ensureCreated();
+        // Logged in execution order: migrations, schema changes, then the baseline record.
+        if (result.migrated && result.migrated.length > 0) {
+          console.info(`[orm:migrations] applied: ${result.migrated.join(", ")}`);
+        }
         if (result.applied && result.applied.length > 0) {
           console.info(`[orm:schema] applied ${result.applied.length} operation(s): ${result.applied.join(", ")}`);
         }
+        if (result.baselined && result.baselined.length > 0) {
+          console.info(`[orm:migrations] baseline: the schema was created from the model, recorded as applied without running: ${result.baselined.join(", ")}`);
+        }
         for (const warning of result.warnings) {
           console.warn(`[orm:schema] ${warning}`);
         }
@@ -89,7 +99,7 @@ export class OrmLifecycle implements HostedService {
           console.warn(`[orm:migrate] ${warning}`);
         }
       }
-      if (this.runMigrationsOnStart && this.migrations.length > 0) {
+      if (this.runMigrationsOnStart && this.migrations.length > 0 && !this.withMigrations) {
         const result = await database.migrateVersioned(this.migrations);
         if (result.applied.length > 0) {
           console.info(`[orm:migrations] applied: ${result.applied.join(", ")}`);

package/core/orm/encapsulationHook.ts

@@ -1,9 +1,13 @@
 import { registerNamedDependencyEncapsulationHook } from "../di/module/encapsulationHooks";
+import { registerNamedDependencyHint } from "../di/errors/NamedDependencyNotFoundError";
 import { IRepository } from "./repository";
 
 let registered = false;
 
-/** Allows closed `IRepository<Entity>` named deps when the module exports open generic `IRepository`. */
+/**
+ * Allows closed `IRepository<Entity>` named deps when the module exports open
+ * generic `IRepository`, and explains a repository nobody registers.
+ */
 export function registerRepositoryEncapsulationHook(): void {
   if (registered) {
     return;
@@ -16,4 +20,10 @@ export function registerRepositoryEncapsulationHook(): void {
     }
     return undefined;
   });
+
+  registerNamedDependencyHint((name) => {
+    const match = /^IRepository<(.+)>$/.exec(name);
+    if (!match) return undefined;
+    return `Repositories are registered by ormBazis for the entities of its context: add ${match[1]} to the entities of an ormBazis module and keep registerRepositories on (the default), or inject that module's DbContext instead.`;
+  });
 }

package/core/orm/ormModule.ts

@@ -121,7 +121,7 @@ export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TC
     attachOwnedStoreRegistration(module, buildConfig.context, buildConfig.entities ?? [], config.ownedStore);
     return module;
   }
-  if (config.ensureCreated && (config.migrateOnStart || config.runMigrationsOnStart || (config.migrations?.length ?? 0) > 0)) throw new OrmError("ensureCreated is mutually exclusive with ORM migration startup options.");
+  if (config.ensureCreated && config.migrateOnStart) throw new OrmError("ensureCreated and migrateOnStart are mutually exclusive: ensureCreated already adds the safe changes. Put other changes into migrations with runMigrationsOnStart: true.");
   if (config.ensureCreated && config.provider?.name === "postgres" && config.context) throw new OrmError("PostgreSQL ensureCreated requires the shared DATABASE_PROVIDER from @Infra.");
   // "Connection" mode: a provider only, no context.
   if (!config.context) {

package/library/orm/DatabaseFacade.ts

@@ -5,6 +5,15 @@ import { Migrator, type MigrationResult } from "./Schema/Migrator";
 import { MigrationRunner, type Migration, type VersionedMigrationResult } from "./Schema/MigrationRunner";
 import { SchemaDiffer } from "./Schema/SchemaDiffer";
 import { SchemaAdmissionEngine, type EnsureCreatedResult } from "./Schema/SchemaAdmission";
+import { entityStorageKey } from "./Schema/tableKey";
+
+/** Result of `ensureCreated` together with versioned migrations. */
+export interface EnsureCreatedWithMigrationsResult extends EnsureCreatedResult {
+  /** Migrations run before the schema check. */
+  readonly migrated: readonly string[];
+  /** Migrations recorded as applied without running, because the schema was created from the model. */
+  readonly baselined: readonly string[];
+}
 import { SchemaAdmissionError } from "./errors";
 import { physicalColumnTypes } from "./Schema/physicalColumnTypes";
 import { bindResolvedForeignKey } from "./Providers/resolvedForeignKey";
@@ -47,6 +56,32 @@ export class DatabaseFacade {
     return { warnings: [] };
   }
 
+  /**
+   * `ensureCreated` with versioned migrations, under the migration lock so that
+   * starting instances do not race:
+   *
+   * - none of the context tables exist yet: `ensureCreated` creates the current
+   *   model and the migrations are recorded as applied without running (a
+   *   baseline: the model already contains their result, so a seed `INSERT` in
+   *   a migration is skipped here too);
+   * - otherwise pending migrations run first (`ALTER`, renames, data moves),
+   *   then `ensureCreated` adds what is still missing and verifies the result.
+   */
+  async ensureCreatedWithMigrations(migrations: readonly Migration[]): Promise<EnsureCreatedWithMigrationsResult> {
+    const work = async (): Promise<EnsureCreatedWithMigrationsResult> => {
+      const runner = new MigrationRunner(this.provider, migrations);
+      const existing = await this.provider.introspect();
+      const fresh = this.models.entities.every((model) => !existing.tables.has(entityStorageKey(model)) && !existing.tables.has(model.tableName));
+      if (fresh) {
+        const created = await this.ensureCreated();
+        return { ...created, migrated: [], baselined: await runner.baseline() };
+      }
+      const { applied } = await runner.migrate();
+      return { ...(await this.ensureCreated()), migrated: applied, baselined: [] };
+    };
+    return this.provider.withMigrationLock ? this.provider.withMigrationLock(work) : work();
+  }
+
   /**
    * Additive auto-migration of the schema for all context entities (enabled in
    * the module: `ormBazis: { migrateOnStart: true }`): introspects the database,

package/library/orm/Repository/README.md

@@ -82,6 +82,9 @@ const DataModule = ormModule({
 ```
 
 `ormModule` exports the `IRepository` family token so importing modules can inject `repositoryFor(User)`.
+A feature module that declares `ormBazis` passes repositories on with its own
+`exports`: `exports: [IRepository]` opens the repositories of all its entities,
+`exports: [repositoryFor(User)]` (since 0.98.22) only that one.
 
 Turning repositories off:
 

package/library/orm/Schema/MigrationRunner.ts

@@ -61,6 +61,27 @@ export class MigrationRunner {
     return { applied, rolledBack: [] };
   }
 
+  /**
+   * Records pending migrations as applied without running them. Used when the
+   * schema was just created from the current model, which already contains
+   * their result.
+   */
+  async baseline(): Promise<readonly string[]> {
+    return this.withMigrationLock(async () => {
+      await this.ensureHistory();
+      const appliedSet = await this.loadApplied();
+      const recorded: string[] = [];
+      for (const migration of this.migrations.filter((item) => !appliedSet.has(item.id))) {
+        await this.provider.execute(
+          `INSERT INTO ${this.quote(HISTORY_TABLE)} (${this.quote("MigrationId")}, ${this.quote("AppliedAt")}) VALUES (${this.param(0)}, ${this.param(1)})`,
+          [migration.id, new Date().toISOString()],
+        );
+        recorded.push(migration.id);
+      }
+      return recorded;
+    });
+  }
+
   /** Rolls back the last `steps` migrations (requires `down`). */
   async rollback(steps = 1): Promise<VersionedMigrationResult> {
     if (!Number.isSafeInteger(steps) || steps < 0) {

package/library/orm/errors.ts

@@ -33,7 +33,7 @@ export class SchemaMigrationRequiredError extends SchemaAdmissionError {
 
 function schemaVerificationMessage(summary: string, verification: SchemaVerificationResult): string {
   return [summary, formatSchemaDifferences(verification),
-    "Check the application version and target database. Align the ORM model and database schema; apply an explicit migration if a database change is intended.",
+    "Check the application version and target database. Align the ORM model and database schema; apply an explicit migration if a database change is intended (with ensureCreated: add it to the module's migrations with runMigrationsOnStart: true).",
   ].filter(Boolean).join("\n");
 }
 

package/library/orm/index.ts

@@ -132,6 +132,7 @@ export type {
 } from "./Schema/introspection";
 export type { SchemaDifferenceCode, SafeSchemaDescriptor, SchemaDifference, SchemaVerificationResult } from "./Schema/ExactSchemaVerifier";
 export type { EnsureCreatedResult } from "./Schema/SchemaAdmission";
+export type { EnsureCreatedWithMigrationsResult } from "./DatabaseFacade";
 export { SchemaAdmissionError, SchemaMigrationRequiredError, SchemaVerificationError } from "./errors";
 export type { SchemaAdmissionErrorCode } from "./errors";
 export { compileCheck, renderCheck } from "./Schema/CheckExpression";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.20",
+  "version": "0.98.22",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",