bazis 0.104.0 → 0.105.0

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.104.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.105.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/library/orm/DbContext.ts

@@ -102,6 +102,6 @@ export abstract class DbContext {
 
   /** Executes a composable ORM transaction scope for this provider identity. */
   transactionScope<TResult>(work: (transaction: OrmTransaction) => Promise<TResult>, options?: OrmTransactionScopeOptions): Promise<TResult> {
-    return transactionScope(this, this.#options.provider, work, options);
+    return transactionScope(this, this.#options.provider, work, options, this.#options.executionStrategy);
   }
 }

package/library/orm/Metadata/ValueConverter.ts

@@ -13,6 +13,12 @@ export interface ValueConverter<TModel = unknown, TProvider = unknown> {
    * the query fails instead of silently matching nothing.
    */
   readonly comparable?: boolean;
+  /**
+   * `true`: the converter also gets `null` (both ways), for example to store
+   * `null` as `""`. By default `null` stays SQL NULL and the converter is
+   * not called, as in EF Core.
+   */
+  readonly convertsNulls?: boolean;
 }
 
 /** Thrown by an encrypted column that cannot be read: another key, or the stored value was changed. */

package/library/orm/Providers/propertyConversion.ts

@@ -2,16 +2,24 @@ import { OrmError } from "../errors";
 import type { PropertyModel } from "../Metadata/types";
 import type { SqlDialect, SqlParam } from "./types";
 
+/**
+ * Whether the converter of the property applies to the value: `null` and
+ * `undefined` stay SQL NULL unless the converter declares `convertsNulls`.
+ */
+export function convertsValue(property: PropertyModel, value: unknown): boolean {
+  return property.converter !== undefined && (property.converter.convertsNulls === true || (value !== null && value !== undefined));
+}
+
 /** Encodes a property value: converter -> dialect. */
 export function encodeProperty(property: PropertyModel, value: unknown, dialect: SqlDialect): SqlParam {
-  const modelValue = property.converter ? property.converter.toProvider(value) : value;
+  const modelValue = convertsValue(property, value) ? property.converter!.toProvider(value) : value;
   return dialect.encode(modelValue, property.type);
 }
 
 /** Decodes a column value: dialect -> converter. A converter failure names the entity and the property. */
 export function decodeProperty(property: PropertyModel, value: unknown, dialect: SqlDialect, owner?: string): unknown {
   const providerValue = dialect.decode(value, property.type);
-  if (!property.converter) return providerValue;
+  if (!property.converter || !convertsValue(property, providerValue)) return providerValue;
   try {
     return property.converter.fromProvider(providerValue);
   } catch (error) {

package/library/orm/Query/ImmediateMutations.ts

@@ -1,6 +1,7 @@
 import { types } from "node:util";
 import { OrmError, OrmTrackedMutationConflictError, OrmUndeclaredConflictTargetError, OrmUnsafeImmediateMutationError } from "../errors";
 import { isDatabaseGenerated, type EntityModel, type PropertyModel } from "../Metadata/types";
+import { convertsValue } from "../Providers/propertyConversion";
 import type { DbContextRuntime } from "../runtime";
 import { hasTrackedEntriesForModel } from "../Tracking/ChangeTracker";
 import { isPostgresJsonScalarParameter } from "../Providers/PostgresDialect";
@@ -136,11 +137,11 @@ function admitInsertValues<T extends object>(model: EntityModel, entity: T): rea
 }
 function unsetKey(value: unknown): boolean { return value === undefined || value === null || value === "" || value === 0; }
 function encodeAssignments(runtime: DbContextRuntime, assignments: readonly AdmittedAssignment[]): readonly { readonly property: PropertyModel; readonly value: SqlParam }[] {
-  return Object.freeze(assignments.map(({ property, value }) => Object.freeze({ property, value: value === null ? null : encode(runtime, property, value) })));
+  return Object.freeze(assignments.map(({ property, value }) => Object.freeze({ property, value: value === null && !convertsValue(property, null) ? null : encode(runtime, property, value) })));
 }
 function encode(runtime: DbContextRuntime, property: PropertyModel, input: unknown, allowNull = false): SqlParam {
   try {
-    const providerValue = property.converter ? property.converter.toProvider(input) : input;
+    const providerValue = convertsValue(property, input) ? property.converter!.toProvider(input) : input;
     const safeProvider = storageValue(providerValue, property.type, allowNull);
     return snapshotEncodedSqlParam(runtime.provider.dialect.encode(safeProvider, property.type));
   } catch {

package/library/orm/Saving/ExecutionStrategy.ts

@@ -56,7 +56,8 @@ export class ExecutionStrategy {
     return false;
   }
 
-  async execute<T>(operation: () => Promise<T>): Promise<T> {
+  /** Runs `operation`, again after a transient failure; `beforeRetry` runs before each new attempt. */
+  async execute<T>(operation: () => Promise<T>, beforeRetry?: (error: unknown) => void): Promise<T> {
     let attempt = 0;
     for (;;) {
       try {
@@ -67,6 +68,7 @@ export class ExecutionStrategy {
         }
         const delay = this.baseDelayMs * 2 ** attempt;
         await new Promise((resolve) => setTimeout(resolve, delay));
+        beforeRetry?.(error);
         attempt += 1;
       }
     }

package/library/orm/Tracking/ChangeTracker.ts

@@ -347,6 +347,11 @@ export function trackedEntriesOf(tracker: ChangeTracker): ReadonlyMap<object, Tr
   return trackerEntries.get(tracker) ?? new Map();
 }
 
+/** Non-barrel helper: how many entities the tracker holds. */
+export function trackedEntryCount(tracker: ChangeTracker): number {
+  return trackerEntries.get(tracker)?.size ?? 0;
+}
+
 /** Non-barrel helper used only by immediate DML admission. */
 export function hasTrackedEntriesForModel(tracker: ChangeTracker, model: EntityModel): boolean {
   return [...(trackerEntries.get(tracker)?.values() ?? [])].some((entry) => entry.model === model);

package/library/orm/Transactions/OrmTransaction.ts

@@ -1,4 +1,5 @@
 import type { DbContext } from "../DbContext";
+import type { ExecutionStrategyOptions } from "../Saving/ExecutionStrategy";
 
 /** A database wall-clock value obtained from the active database session. */
 export interface OrmDatabaseTimeV1 {
@@ -15,6 +16,16 @@ export interface OrmTransactionScopeOptions {
   readonly signal?: AbortSignal;
   /** Total work budget in milliseconds, including admission and COMMIT; positive integer. */
   readonly timeoutMs?: number;
+  /**
+   * Runs the whole scope again after a transient failure (deadlock,
+   * serialization failure, lost connection): `true` takes the context's
+   * `executionStrategy` (or 3 retries from 50 ms), an object sets its own.
+   * Every attempt starts from a clean context: what the failed attempt
+   * loaded or changed is detached, so the callback must read what it
+   * changes. Allowed only for the outermost scope of a context that tracks
+   * nothing yet; a COMMIT without acknowledgement is never retried.
+   */
+  readonly retry?: boolean | ExecutionStrategyOptions;
 }
 
 /** Opaque transaction capability. It deliberately exposes no executor or completion authority. */

package/library/orm/Transactions/TransactionScopeCoordinator.ts

@@ -7,6 +7,8 @@ import { OrmTransaction, type OrmDatabaseTimeV1, type OrmTransactionScopeOptions
 
 import { isUnknownTransactionOutcome, TransactionOutcomeUnknownError } from "../Providers/transactionOutcome";
 import { OperationDeadline, positiveTimeout } from "../Providers/operationDeadline";
+import { ExecutionStrategy, type ExecutionStrategyOptions } from "../Saving/ExecutionStrategy";
+import { trackedEntryCount } from "../Tracking/ChangeTracker";
 
 interface Frame {
   readonly allEnrolled: Set<object>;
@@ -20,6 +22,8 @@ interface Frame {
   activeChildFrame?: Frame;
   rollbackOnly?: unknown;
   cancellationRequested?: boolean;
+  /** Outermost frame of a retried scope: every context of the attempt, cleared before the next one. */
+  readonly retryContexts?: Set<DbContext>;
   readonly pending: Set<PendingTask>;
   readonly abortPromise: Promise<never>;
   abort(error: OrmTransactionScopeError): void;
@@ -173,7 +177,31 @@ function releaseTask(task: PendingTask): void {
   if (task.settled && task.dispatches.size === 0 && task.attached.size === 0) task.frame.pending.delete(task);
 }
 
-export async function transactionScope<TResult>(context: DbContext, provider: DatabaseProvider, work: (transaction: OrmTransaction) => Promise<TResult>, options?: OrmTransactionScopeOptions): Promise<TResult> {
+export async function transactionScope<TResult>(context: DbContext, provider: DatabaseProvider, work: (transaction: OrmTransaction) => Promise<TResult>, options?: OrmTransactionScopeOptions, contextStrategy?: ExecutionStrategyOptions): Promise<TResult> {
+  const retry = options?.retry;
+  if (retry === undefined || retry === false) return runScope(context, provider, work, options);
+  if (views.getStore() !== undefined || provider.isTransactionActive?.() === true) {
+    throw new OrmTransactionScopeError("transactionScope({ retry }) must be the outermost scope: a nested scope is part of the outer transaction, so retry the outer one.");
+  }
+  assertRetryable(context);
+  const contexts = new Set<DbContext>([context]);
+  const strategy = new ExecutionStrategy(retry === true ? contextStrategy ?? {} : retry);
+  return strategy.execute(() => runScope(context, provider, work, options, contexts), () => {
+    // The rolled-back attempt left its loaded and changed entities behind;
+    // the next attempt reads them again instead of applying its changes twice.
+    for (const each of contexts) each.changeTracker.clear();
+    contexts.clear();
+    contexts.add(context);
+  });
+}
+
+function assertRetryable(context: DbContext): void {
+  const tracked = trackedEntryCount(context.changeTracker);
+  if (tracked === 0) return;
+  throw new OrmTransactionScopeError(`transactionScope({ retry }) needs ${contextName(context)} without tracked entities: every attempt starts from a clean context, and the ${tracked} entities tracked before the scope would lose their changes. Start the scope before loading anything, or create a new scope for it.`);
+}
+
+async function runScope<TResult>(context: DbContext, provider: DatabaseProvider, work: (transaction: OrmTransaction) => Promise<TResult>, options: OrmTransactionScopeOptions | undefined, retryContexts?: Set<DbContext>): Promise<TResult> {
   let signal = options?.signal;
   if (options?.timeoutMs !== undefined) positiveTimeout(options.timeoutMs, 30_000, "timeoutMs");
   if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError("ORM transaction signal must be an AbortSignal.");
@@ -230,7 +258,7 @@ export async function transactionScope<TResult>(context: DbContext, provider: Da
       void abortPromise.catch(() => {});
       let cancelDrain!: () => void;
       const cancellationPromise = new Promise<"cancelled">((resolve) => { cancelDrain = () => resolve("cancelled"); });
-      const frame: Frame = { allEnrolled: new Set([token]), id: Symbol("orm transaction"), authority, provider: base, parent, enrolled: parent ? current!.enrolled : new Set([token]), state: "active", pending: new Set(), abortPromise, abort, cancellationPromise, cancelDrain }; childFrame = frame;
+      const frame: Frame = { allEnrolled: new Set([token]), id: Symbol("orm transaction"), authority, provider: base, parent, enrolled: parent ? current!.enrolled : new Set([token]), state: "active", pending: new Set(), abortPromise, abort, cancellationPromise, cancelDrain, retryContexts: parent ? undefined : retryContexts }; childFrame = frame;
       if (parent) parent.activeChildFrame = frame;
       const view: View = { frame, enrolled: frame.enrolled };
       return withProviderDispatchObserver((dispatch) => registerDispatch(frame, dispatch), () => views.run(view, async () => {
@@ -374,6 +402,12 @@ class ScopedOrmTransaction extends OrmTransaction {
     const parent = views.getStore();
     if (!parent || parent.frame !== frame) throw foreignTransaction();
     if (uncertainContexts.has(token)) throw new TransactionOutcomeUnknownError();
+    let root = frame;
+    while (root.parent) root = root.parent;
+    if (root.retryContexts && !root.retryContexts.has(context)) {
+      assertRetryable(context);
+      root.retryContexts.add(context);
+    }
     for (let target: Frame | undefined = frame; target; target = target.parent) target.allEnrolled.add(token);
     const enrolled = new Set(parent.enrolled); enrolled.add(token);
     return views.run({ frame, enrolled }, () => trackTask(frame, () => work(context)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.104.0",
+  "version": "0.105.0",
   "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",