bazis 0.96.1

package/library/orm/Repository/Repository.ts

@@ -0,0 +1,68 @@
+import type { DbContext } from "../DbContext";
+import type { DatabaseFacade } from "../DatabaseFacade";
+import type { DbSet } from "../Query/DbSet";
+import type { ChangeTracker } from "../Tracking/ChangeTracker";
+import type { EntityState } from "../Tracking/EntityState";
+
+type EntityClass<T extends object> = new () => T;
+
+/**
+ * Scoped repository implementation: a thin wrapper over `DbSet<T>` and `DbContext`
+ * without duplicating SQL or change tracking. Structurally compatible with
+ * `IRepository<T>` from `@/core/orm` (the engine does not depend on the DI layer).
+ */
+export class Repository<T extends object> {
+  constructor(
+    private readonly context: DbContext,
+    private readonly entityClass: EntityClass<T>,
+  ) {}
+
+  get dbSet(): DbSet<T> {
+    return this.context.setOf(this.entityClass);
+  }
+
+  query(): DbSet<T> {
+    return this.dbSet;
+  }
+
+  find(key: unknown): Promise<T | null> {
+    return this.dbSet.find(key);
+  }
+
+  add(entity: T): T {
+    return this.dbSet.add(entity);
+  }
+
+  addRange(entities: readonly T[]): void {
+    this.dbSet.addRange(entities);
+  }
+
+  update(entity: T): T {
+    return this.dbSet.update(entity);
+  }
+
+  remove(entity: T): T {
+    return this.dbSet.remove(entity);
+  }
+
+  attach(entity: T): T {
+    return this.dbSet.attach(entity);
+  }
+
+  stateOf(entity: T): EntityState {
+    return this.context.stateOf(entity);
+  }
+
+  /** Saves the whole DbContext, including changes of its other DbSets. */
+  saveChanges(): Promise<number> {
+    return this.context.saveChanges();
+  }
+
+  get changeTracker(): ChangeTracker {
+    return this.context.changeTracker;
+  }
+
+  get database(): DatabaseFacade {
+    return this.context.database;
+  }
+}

package/library/orm/Saving/CommandBuilder.ts

@@ -0,0 +1,139 @@
+import { isDatabaseGenerated, type EntityModel, type PropertyModel } from "../Metadata/types";
+import type { SqlDialect, SqlParam } from "../Providers/types";
+import { encodeProperty } from "../Providers/propertyConversion";
+import { EntityState } from "../Tracking/EntityState";
+import type { TrackedEntry } from "../Tracking/ChangeTracker";
+
+export interface DbCommand {
+  readonly sql: string;
+  readonly params: SqlParam[];
+  /**
+   * Column of the generated key to read from the result row (identity INSERT
+   * through `RETURNING`), or `undefined`. The calling code takes the key
+   * property from the model.
+   */
+  readonly returnsGeneratedKey?: { readonly column: string; readonly property: string; readonly type: PropertyModel["type"] };
+}
+
+/**
+ * Builds parameterized SQL commands for tracked entities.
+ * All values go only into the parameter array.
+ */
+export class CommandBuilder {
+  constructor(private readonly dialect: SqlDialect) {}
+
+  build(entry: TrackedEntry): DbCommand {
+    switch (entry.state) {
+      case EntityState.Added:
+        return this.insert(entry.entity as Record<string, unknown>, entry.model);
+      case EntityState.Modified:
+        return this.update(entry.entity as Record<string, unknown>, entry.model, entry.modifiedProperties);
+      case EntityState.Deleted:
+        if (entry.model.softDeleteProperty) {
+          return this.softDelete(entry.entity as Record<string, unknown>, entry.model);
+        }
+        return this.delete(entry.entity as Record<string, unknown>, entry.model);
+      default:
+        throw new Error(`No command for entity state "${entry.state}".`);
+    }
+  }
+
+  private insert(entity: Record<string, unknown>, model: EntityModel): DbCommand {
+    return this.insertMany([entity], model);
+  }
+
+  /**
+   * Batch insert into one table: `INSERT ... VALUES (..),(..),...`. For identity
+   * keys it adds `RETURNING`; keys are read in row order. The columns are the
+   * same for all Added entries of one entity, so the batch is safe.
+   */
+  insertMany(entities: readonly Record<string, unknown>[], model: EntityModel): DbCommand {
+    const scalarKey = model.key.length === 1 ? model.key[0] : undefined;
+    const dbGeneratedKey = scalarKey !== undefined && isDatabaseGenerated(scalarKey.generation);
+    const columns = model.properties.filter((property) => !isDatabaseGenerated(property.generation));
+    const columnList = columns.map((property) => this.dialect.quoteId(property.columnName)).join(", ");
+    const params: SqlParam[] = [];
+    const tuples = entities.map((entity) => {
+      const placeholders = columns.map((property) => {
+        const placeholder = this.dialect.parameter(params.length);
+        params.push(encodeProperty(property, entity[property.propertyName], this.dialect));
+        return placeholder;
+      });
+      return `(${placeholders.join(", ")})`;
+    });
+    const returning =
+      dbGeneratedKey && this.dialect.supportsReturning
+        ? ` RETURNING ${this.dialect.quoteId(scalarKey!.columnName)}`
+        : "";
+
+    if (columns.length === 0) {
+      if (entities.length !== 1) {
+        throw new Error(
+          `Batch insert into "${model.tableName}" with only a DB-generated key supports one row at a time.`,
+        );
+      }
+      const sql = `INSERT INTO ${this.dialect.qualifyTable(model)} DEFAULT VALUES${returning}`;
+      return {
+        sql,
+        params: [],
+        returnsGeneratedKey: dbGeneratedKey
+          ? { column: scalarKey!.columnName, property: scalarKey!.propertyName, type: scalarKey!.type }
+          : undefined,
+      };
+    }
+
+    const sql = `INSERT INTO ${this.dialect.qualifyTable(model)} (${columnList}) VALUES ${tuples.join(", ")}${returning}`;
+    return {
+      sql,
+      params,
+      returnsGeneratedKey: dbGeneratedKey
+        ? { column: scalarKey!.columnName, property: scalarKey!.propertyName, type: scalarKey!.type }
+        : undefined,
+    };
+  }
+
+  private update(entity: Record<string, unknown>, model: EntityModel, changed: ReadonlySet<string>): DbCommand {
+    const columns = model.properties.filter(
+      (property) => !property.isKey && (changed.size === 0 || changed.has(property.propertyName)),
+    );
+    const params: SqlParam[] = [];
+    const assignments = columns.map((property) => {
+      const placeholder = this.dialect.parameter(params.length);
+      params.push(encodeProperty(property, entity[property.propertyName], this.dialect));
+      return `${this.dialect.quoteId(property.columnName)} = ${placeholder}`;
+    });
+    const where = this.keyPredicate(model, entity, params);
+    const sql = `UPDATE ${this.dialect.qualifyTable(model)} SET ${assignments.join(
+      ", ",
+    )} WHERE ${where}`;
+    return { sql, params };
+  }
+
+  private delete(entity: Record<string, unknown>, model: EntityModel): DbCommand {
+    const params: SqlParam[] = [];
+    const sql = `DELETE FROM ${this.dialect.qualifyTable(model)} WHERE ${this.keyPredicate(model, entity, params)}`;
+    return { sql, params };
+  }
+
+  /** Soft delete: an UPDATE of the timestamp instead of DELETE. */
+  private softDelete(entity: Record<string, unknown>, model: EntityModel): DbCommand {
+    const propName = model.softDeleteProperty!;
+    const property = model.propertyByName(propName)!;
+    const deletedAt = new Date();
+    entity[propName] = deletedAt;
+    const placeholder = this.dialect.parameter(0);
+    const params: SqlParam[] = [encodeProperty(property, deletedAt, this.dialect)];
+    const sql = `UPDATE ${this.dialect.qualifyTable(model)} SET ${this.dialect.quoteId(
+      property.columnName,
+    )} = ${placeholder} WHERE ${this.keyPredicate(model, entity, params)}`;
+    return { sql, params };
+  }
+
+  private keyPredicate(model: EntityModel, entity: Record<string, unknown>, params: SqlParam[]): string {
+    return model.key.map((key) => {
+      const placeholder = this.dialect.parameter(params.length);
+      params.push(encodeProperty(key, entity[key.propertyName], this.dialect));
+      return `${this.dialect.quoteId(key.columnName)} = ${placeholder}`;
+    }).join(" AND ");
+  }
+}

package/library/orm/Saving/ExecutionStrategy.ts

@@ -0,0 +1,128 @@
+import type { DatabaseProvider } from "../Providers/types";
+import { isCommittedOutcome } from "../errors";
+import { isUnknownTransactionOutcome } from "../Providers/transactionOutcome";
+
+const EXECUTION_STRATEGY_BASE_PROVIDERS = new WeakMap<DatabaseProvider, DatabaseProvider>();
+
+/** Private bounded unwrap for framework ownership checks. */
+export function knownExecutionStrategyBase(provider: DatabaseProvider): DatabaseProvider | undefined {
+  let current = provider;
+  const seen = new Set<DatabaseProvider>();
+  for (let depth = 0; depth < 16; depth += 1) {
+    if (seen.has(current)) return undefined;
+    seen.add(current);
+    const inner = EXECUTION_STRATEGY_BASE_PROVIDERS.get(current);
+    if (!inner) return current;
+    current = inner;
+  }
+  return undefined;
+}
+
+/** Options of the retry strategy for transient database errors. */
+export interface ExecutionStrategyOptions {
+  /** Maximum retries after the first failure (default 3). */
+  readonly maxRetries?: number;
+  /** Base delay between attempts, ms (exponential backoff). */
+  readonly baseDelayMs?: number;
+  /** Tells whether an error is transient and worth retrying. */
+  readonly isTransient?: (error: unknown) => boolean;
+}
+
+/**
+ * Execution strategy with retries (the counterpart of EF `EnableRetryOnFailure`).
+ * Wraps SaveChanges and can be used for user transactions.
+ */
+export class ExecutionStrategy {
+  private readonly maxRetries: number;
+  private readonly baseDelayMs: number;
+  private readonly isTransient: (error: unknown) => boolean;
+
+  constructor(options: ExecutionStrategyOptions = {}) {
+    this.maxRetries = options.maxRetries ?? 3;
+    this.baseDelayMs = options.baseDelayMs ?? 50;
+    this.isTransient = options.isTransient ?? ExecutionStrategy.defaultIsTransient;
+  }
+
+  static defaultIsTransient(error: unknown): boolean {
+    if (isUnknownTransactionOutcome(error) || isCommittedOutcome(error)) return false;
+    const message = error instanceof Error ? error.message : String(error);
+    if (/ECONNRESET|ETIMEDOUT|connection terminated|deadlock detected|could not serialize|40001|08006|57P01/i.test(message)) {
+      return true;
+    }
+    const code = (error as { code?: string } | null | undefined)?.code;
+    if (code === "ERR_POSTGRES_CONNECTION_CLOSED") {
+      return true;
+    }
+    return false;
+  }
+
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    let attempt = 0;
+    for (;;) {
+      try {
+        return await operation();
+      } catch (error) {
+        if (isCommittedOutcome(error) || isUnknownTransactionOutcome(error) || attempt >= this.maxRetries || !this.isTransient(error)) {
+          throw error;
+        }
+        const delay = this.baseDelayMs * 2 ** attempt;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        attempt += 1;
+      }
+    }
+  }
+}
+
+/** Provider wrapper with retries on every execute/query (optional). */
+export function withRetry(provider: DatabaseProvider, options?: ExecutionStrategyOptions): DatabaseProvider {
+  const strategy = new ExecutionStrategy(options);
+  const transactionScope = provider.transactionScope?.bind(provider);
+  const isTransactionActive = provider.isTransactionActive?.bind(provider);
+  const retryOnlyWhenKnownTopLevel = <T>(operation: () => Promise<T>): Promise<T> => {
+    // Retrying one statement or callback inside an ambient transaction can
+    // replay it after partial writes on the same physical transaction. Custom
+    // providers without an activity probe are treated conservatively as well.
+    return isTransactionActive?.() === false
+      ? strategy.execute(operation)
+      : Promise.resolve().then(operation);
+  };
+  // Explicit delegation: a `{...provider}` spread would lose the class methods
+  // (they live on the prototype), leaving the wrapper without ping/introspect/close.
+  const wrapped: DatabaseProvider = {
+    name: provider.name,
+    dialect: provider.dialect,
+    limits: provider.limits,
+    diagnostics: provider.diagnostics ? () => provider.diagnostics!() : undefined,
+    query: (sql, params) => retryOnlyWhenKnownTopLevel(() => provider.query(sql, params)),
+    execute: (sql, params) => retryOnlyWhenKnownTopLevel(() => provider.execute(sql, params)),
+    transaction: (work) => retryOnlyWhenKnownTopLevel(() => provider.transaction(work)),
+    transactionScope: transactionScope
+      ? (work) => retryOnlyWhenKnownTopLevel(() => transactionScope(work))
+      : undefined,
+    isTransactionActive: isTransactionActive ? () => isTransactionActive() : undefined,
+    afterCommit: provider.afterCommit ? (callback) => provider.afterCommit!(callback) : undefined,
+    afterRollback: provider.afterRollback ? (callback) => provider.afterRollback!(callback) : undefined,
+    ping: (signal) => provider.ping(signal),
+    introspect: () => provider.introspect(),
+    schemaAdmissionCapability: provider.schemaAdmissionCapability,
+    withMigrationLock: provider.withMigrationLock ? (work) => provider.withMigrationLock!(work) : undefined,
+    listen: provider.listen ? (channel, handler) => provider.listen!(channel, handler) : undefined,
+    notify: provider.notify ? (channel, payload) => provider.notify!(channel, payload) : undefined,
+    close: () => provider.close(),
+  };
+  EXECUTION_STRATEGY_BASE_PROVIDERS.set(wrapped, provider);
+  return wrapped;
+}
+
+/** Lets a subsystem with its own bounded whole-command retry policy avoid nested retries. */
+export function withoutExecutionStrategyRetries(provider: DatabaseProvider): DatabaseProvider {
+  let current = provider;
+  const seen = new Set<DatabaseProvider>();
+  while (!seen.has(current)) {
+    seen.add(current);
+    const inner = EXECUTION_STRATEGY_BASE_PROVIDERS.get(current);
+    if (inner === undefined) return current;
+    current = inner;
+  }
+  return current;
+}