bazis 0.96.1

package/library/orm/Providers/types.ts

@@ -0,0 +1,207 @@
+import type { ColumnType, EntityModel, IndexModel, PropertyModel } from "../Metadata/types";
+import type { IntrospectedSchema } from "../Schema/introspection";
+import type { OrmExpectedSchema } from "../Schema/ExpectedSchema";
+
+/**
+ * A value that can be bound as a query parameter. A wide union, because
+ * PostgreSQL accepts native `boolean`, `Date` and `jsonb` objects. A concrete
+ * provider receives values after `SqlDialect.encode`.
+ */
+export type SqlParam =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | Uint8Array
+  | Date
+  | readonly unknown[]
+  | Record<string, unknown>;
+
+/** A query result row. */
+export type Row = Record<string, unknown>;
+
+/**
+ * Minimal SQL executor. The provider implements it directly (outside a
+ * transaction), and inside a transaction `transaction()` passes a scoped
+ * executor; this is needed for pooled providers (PostgreSQL), where a
+ * transaction is bound to a reserved connection.
+ */
+export interface DbExecutor {
+  query(sql: string, params: readonly SqlParam[]): Promise<Row[]>;
+  execute(sql: string, params: readonly SqlParam[]): Promise<ExecuteResult>;
+}
+
+/** Work tied to completion of the surrounding top-level transaction. */
+export type TransactionCallback = () => Promise<void> | void;
+
+/** Work that must run only after the surrounding top-level transaction commits. */
+export type AfterCommitCallback = TransactionCallback;
+
+/** Row-level lock requested by a SELECT query. */
+export type RowLockMode = "update";
+
+/** Result of a modifying command. */
+export interface ExecuteResult {
+  /** Number of affected rows. */
+  readonly changes: number;
+  /** Id of the last inserted row (for identity keys). */
+  readonly lastInsertId: number | bigint;
+}
+
+/** SQL provider limits that affect the size of batch commands. */
+export interface DatabaseProviderLimits {
+  /** Maximum number of bound parameters in one SQL command. */
+  readonly maxParametersPerCommand: number;
+  /** Optional upper limit of rows in one multi-row INSERT. */
+  readonly maxRowsPerInsert?: number;
+  /** Upper limit of values in one `WHERE ... IN (...)`. */
+  readonly maxParametersPerInList?: number;
+}
+
+/** Provider diagnostic signal for the health check and startup warnings. */
+export interface DatabaseProviderDiagnostic {
+  readonly code: string;
+  readonly severity: "warning" | "error";
+  readonly message: string;
+}
+
+/** PostgreSQL-only capability: locks, transaction, DDL and catalog reads share one reserved session. */
+export interface SchemaAdmissionCapabilityV1 {
+  readonly version: 1;
+  readonly provider: "postgres";
+  readonly distributedLock: true;
+  readonly transactionalDdl: true;
+  readonly exactIntrospection: true;
+  withSchemaAdmission<T>(schemas: readonly string[], work: (scope: SchemaAdmissionScope) => Promise<T>): Promise<T>;
+}
+export interface SchemaAdmissionScope extends DbExecutor { introspectExpected(expected: OrmExpectedSchema): Promise<IntrospectedSchema> }
+
+/**
+ * SQL dialect: everything that differs between DBMSs (quoting, parameter
+ * placeholders, column types, auto-increment). A new provider can be added by
+ * implementing a dialect + a transport.
+ */
+export interface SqlDialect {
+  readonly name: string;
+  /** Quotes one identifier; a dot inside the name is kept literally. */
+  quoteId(name: string): string;
+  /** Qualified table name, taking `EntityModel.schema` into account. */
+  qualifyTable(model: EntityModel): string;
+  /** PostgreSQL parameter placeholder by index (0-based): `$1`, `$2`, …. */
+  parameter(index: number): string;
+  /** Column type in DDL. */
+  columnType(type: ColumnType): string;
+  /** Whether `INSERT ... RETURNING` is supported. */
+  readonly supportsReturning: boolean;
+  /** Encodes a property value into a query parameter for this DBMS. */
+  encode(value: unknown, type: ColumnType): SqlParam;
+  /** Decodes a column value into a property value. */
+  decode(value: unknown, type: ColumnType): unknown;
+  /** SQL suffix for a row-locking SELECT; empty when the dialect has no such clause. */
+  rowLockClause(mode: RowLockMode): string;
+  /** DDL that creates the table (`CREATE TABLE IF NOT EXISTS ...`) with FK constraints. */
+  createTableSql(model: EntityModel, foreignKeys: readonly ForeignKeyConstraint[]): string;
+  /** DDL that creates all indexes of the entity. */
+  createIndexSql(model: EntityModel): readonly string[];
+  /** DDL that creates one index. */
+  createIndexSqlOne(model: EntityModel, index: IndexModel): string;
+  /** DDL that adds a column (`ALTER TABLE ... ADD COLUMN ...`). */
+  addColumnSql(model: EntityModel, property: PropertyModel, foreignKey?: ForeignKeyConstraint): string;
+  /**
+   * DDL that drops a column (`ALTER TABLE ... DROP COLUMN ...`). A destructive
+   * operation: the auto-migration never calls it (see `SchemaDiffer`); only
+   * explicit schema management scenarios do.
+   */
+  dropColumnSql(model: EntityModel, columnName: string): string;
+}
+
+/** FK constraint description for DDL (already resolved into column/table names). */
+export interface ForeignKeyConstraint {
+  readonly column: string;
+  readonly columns?: readonly string[];
+  readonly name?: string;
+  readonly referencedTable: string;
+  readonly referencedColumn: string;
+  readonly referencedColumns?: readonly string[];
+  readonly onDelete?: "noAction" | "restrict" | "cascade" | "setNull";
+  readonly onUpdate?: "noAction" | "restrict" | "cascade" | "setNull";
+  /** Physical type of the FK column when it is more precise than the general `PropertyModel.type` (for example native PostgreSQL UUID). */
+  readonly columnType?: ColumnType | "uuid";
+}
+
+/**
+ * Transport to a concrete DBMS. The methods are async for providers with
+ * network I/O (PostgreSQL). Only parameterized queries are used everywhere.
+ */
+export interface DatabaseProvider {
+  readonly name: string;
+  readonly dialect: SqlDialect;
+  readonly schemaAdmissionCapability?: SchemaAdmissionCapabilityV1;
+  /** Batch command limits of the concrete provider. */
+  readonly limits?: DatabaseProviderLimits;
+  /** Diagnostics of provider capabilities (for example a degraded migration lock). */
+  diagnostics?(): readonly DatabaseProviderDiagnostic[];
+  /** SELECT: returns rows. */
+  query(sql: string, params: readonly SqlParam[]): Promise<Row[]>;
+  /** INSERT/UPDATE/DELETE/DDL: returns the number of changes and lastInsertId. */
+  execute(sql: string, params: readonly SqlParam[]): Promise<ExecuteResult>;
+  /**
+   * Runs work in a transaction (BEGIN/COMMIT, ROLLBACK on exception).
+   * The callback gets an executor bound to the transaction's connection;
+   * all queries inside must go through it.
+   */
+  transaction<T>(work: (tx: DbExecutor) => Promise<T>): Promise<T>;
+  /**
+   * Runs an atomic transaction scope.
+   *
+   * Outside an ambient transaction this is equivalent to {@link transaction}.
+   * Inside an ambient transaction a capable provider creates a real database
+   * savepoint, so a caught inner failure cannot leak partial writes into the
+   * outer commit. The capability is optional for third-party providers; code
+   * that requires composable atomic work must fail fast when it is absent.
+   */
+  transactionScope?<T>(work: (tx: DbExecutor) => Promise<T>): Promise<T>;
+  /** True only in the current async flow while it is joined to an ambient transaction. */
+  isTransactionActive?(): boolean;
+  /**
+   * Registers work after the ambient top-level commit. Outside a transaction
+   * the callback runs immediately. Useful for notifications that must never
+   * expose uncommitted state.
+   */
+  afterCommit?(callback: AfterCommitCallback): Promise<void> | void;
+  /**
+   * Registers compensation after rollback of the ambient top-level
+   * transaction. Intended for restoring in-memory ORM state that was updated
+   * while SQL was executing. Outside a transaction the callback is ignored.
+   */
+  afterRollback?(callback: TransactionCallback): void;
+  /** Connection check for the health check. */
+  ping(signal?: AbortSignal): Promise<boolean>;
+  /** Introspection of the actual database schema (for the auto-migration). */
+  introspect(): Promise<IntrospectedSchema>;
+  /**
+   * Runs `work` under a cross-process migration lock (optional).
+   * PostgreSQL uses an advisory lock so that two instances starting at the
+   * same time do not race to apply migrations.
+   */
+  withMigrationLock?<T>(work: () => Promise<T>): Promise<T>;
+  /**
+   * Subscribes to an async notification channel (PostgreSQL `LISTEN`). Optional:
+   * providers without push support do not implement it, and the subscriber falls
+   * back to polling. `handler` is called for every incoming notification with
+   * its payload.
+   */
+  listen?(channel: string, handler: (payload: string) => void | Promise<void>): Promise<NotificationSubscription>;
+  /**
+   * Sends a notification to a channel (PostgreSQL `NOTIFY` through `pg_notify`). Optional.
+   * Delivered to all channel subscribers, including the sender.
+   */
+  notify?(channel: string, payload?: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Active notification channel subscription; `close()` removes it. */
+export interface NotificationSubscription {
+  close(): Promise<void> | void;
+}

package/library/orm/Query/DbSet.ts

@@ -0,0 +1,78 @@
+import type { EntityModel } from "../Metadata/types";
+import type { DbContextRuntime } from "../runtime";
+import { EntityQuery } from "./EntityQuery";
+import { Operand } from "./conditions";
+import { KeyTuple } from "../Metadata/KeyTuple";
+import { insertIfAbsent, type OrmInsertIfAbsentResultV1, type OrmUniqueKeySelectorV1 } from "./ImmediateMutations";
+
+/**
+ * Table access point: queries (inherited from `EntityQuery`) plus tracker
+ * operations (add/update/remove/attach) and key lookup with `find`.
+ */
+export class DbSet<T extends object> extends EntityQuery<T> {
+  constructor(model: EntityModel, runtime: DbContextRuntime) {
+    super(model, runtime);
+  }
+
+  /** Marks the entity for insertion. */
+  add(entity: T): T {
+    this.runtime.tracker.add(entity, this.model);
+    return entity;
+  }
+
+  addRange(entities: readonly T[]): void {
+    for (const entity of entities) {
+      this.runtime.tracker.add(entity, this.model);
+    }
+  }
+
+  /** Marks the entity as modified (full update). */
+  update(entity: T): T {
+    this.runtime.tracker.update(entity, this.model);
+    return entity;
+  }
+
+  /** Marks the entity for deletion. */
+  remove(entity: T): T {
+    this.runtime.tracker.remove(entity, this.model);
+    return entity;
+  }
+
+  /** Attaches an existing entity as Unchanged (with a snapshot). */
+  attach(entity: T): T {
+    this.runtime.tracker.attach(entity, this.model);
+    return entity;
+  }
+
+  /**
+   * Primary key lookup with the usual query filters/soft delete.
+   * The identity map still returns the canonical tracked instance, but the
+   * query always goes to the database so a cached entity cannot bypass filters.
+   */
+  find(key: unknown): Promise<T | null> {
+    return this.byKey(key).firstOrDefault();
+  }
+
+  /**
+   * Reads the current row and locks it for mutation in the surrounding
+   * transaction. PostgreSQL emits `FOR UPDATE`; query filters remain active.
+   */
+  findForUpdate(key: unknown): Promise<T | null> {
+    return this.byKey(key).forUpdate().firstOrDefault();
+  }
+
+  insertIfAbsent(entity: T, options: { readonly conflictBy: OrmUniqueKeySelectorV1<T> }): Promise<OrmInsertIfAbsentResultV1> {
+    return insertIfAbsent(this.model, this.runtime, entity, options);
+  }
+
+  private byKey(key: unknown): EntityQuery<T> {
+    const tuple = KeyTuple.fromInput(this.model, key);
+    let query: EntityQuery<T> = this;
+    for (let index = 0; index < this.model.key.length; index += 1) {
+      const property = this.model.key[index]!;
+      const value = tuple.values[index];
+      query = query.where((entity) => (entity as unknown as Record<string, Operand>)[property.propertyName]!.eq(value));
+    }
+    return query;
+  }
+}

package/library/orm/Query/EntityQuery.ts

@@ -0,0 +1,247 @@
+import { EntityNotFoundError } from "../errors";
+import type { EntityModel } from "../Metadata/types";
+import type { DbContextRuntime } from "../runtime";
+import { fieldSelector, type KeySelectorFn, type PredicateFn } from "./conditions";
+import { IncludeLoader } from "./IncludeLoader";
+import { materialize, materializeProjection } from "./materialize";
+import { EMPTY_PLAN, withCondition, withOrder, type QueryPlan } from "./QueryPlan";
+import { SqlTranslator } from "./SqlTranslator";
+import { executeImmediateDelete, executeImmediateUpdate, type OrmMutationResultV1, type OrmUpdateValuesV1 } from "./ImmediateMutations";
+
+export interface ForUpdateOptionsV1 { readonly skipLocked?: boolean; }
+
+/** Navigation element type: `Post[]` -> `Post`, `User | undefined` -> `User`. */
+export type NavigationElement<N> = N extends readonly (infer E)[] ? E : NonNullable<N>;
+function captureNavigation<T>(selector: (entity: T) => unknown): string {
+  let captured = "";
+  const proxy = new Proxy(
+    {},
+    {
+      get(_target, property): undefined {
+        captured = String(property);
+        return undefined;
+      },
+    },
+  );
+  selector(proxy as T);
+  if (captured === "") {
+    throw new Error("include/thenInclude selector must access a navigation property, e.g. x => x.posts");
+  }
+  return captured;
+}
+
+/** Captures the `.select(u => ({ alias: u.prop }))` projection. */
+function captureProjection<T, R extends Record<string, unknown>>(
+  selector: (entity: T) => R,
+): { readonly alias: string; readonly property: string }[] {
+  const proxy = new Proxy(
+    {},
+    {
+      get(_target, property): string {
+        return String(property);
+      },
+    },
+  );
+  const mapped = selector(proxy as T);
+  return Object.entries(mapped).map(([alias, propertyName]) => ({ alias, property: String(propertyName) }));
+}
+
+/**
+ * Immutable LINQ-like query over one entity. Each step
+ * (where/orderBy/take/skip/asNoTracking) returns a new `EntityQuery` with an
+ * extended plan; terminal methods (toList/first/count/...) run the SQL.
+ */
+export class EntityQuery<T extends object, TResult = T> {
+  constructor(
+    protected readonly model: EntityModel,
+    protected readonly runtime: DbContextRuntime,
+    protected readonly plan: QueryPlan = EMPTY_PLAN,
+  ) {}
+
+  protected derive(plan: QueryPlan): EntityQuery<T, TResult> {
+    return new EntityQuery<T, TResult>(this.model, this.runtime, plan);
+  }
+
+  /** Filter. Several calls are combined with AND. */
+  where(predicate: PredicateFn<T>): EntityQuery<T, TResult> {
+    const result = predicate(fieldSelector<T>());
+    return this.derive(withCondition(this.plan, result.node));
+  }
+
+  orderBy(selector: KeySelectorFn<T>): EntityQuery<T, TResult> {
+    return this.derive(withOrder(this.plan, { property: selector(fieldSelector<T>()).property, descending: false }));
+  }
+
+  orderByDescending(selector: KeySelectorFn<T>): EntityQuery<T, TResult> {
+    return this.derive(withOrder(this.plan, { property: selector(fieldSelector<T>()).property, descending: true }));
+  }
+
+  take(count: number): EntityQuery<T, TResult> {
+    const invalidRequestedLimit = !Number.isSafeInteger(count) || count <= 0 ? count : this.plan.invalidRequestedLimit;
+    return this.derive({ ...this.plan, limit: Math.max(0, Math.trunc(count)), requestedLimit: count, ...(invalidRequestedLimit === undefined ? {} : { invalidRequestedLimit }) });
+  }
+
+  skip(count: number): EntityQuery<T, TResult> {
+    return this.derive({ ...this.plan, offset: Math.max(0, Math.trunc(count)) });
+  }
+
+  /** Read-only: the result is not tracked by the ChangeTracker (faster). */
+  asNoTracking(): EntityQuery<T, TResult> {
+    return this.derive({ ...this.plan, noTracking: true });
+  }
+
+  /** Do not apply global `@QueryFilter`s and the soft-delete filter. */
+  ignoreQueryFilters(): EntityQuery<T, TResult> {
+    return this.derive({ ...this.plan, ignoreQueryFilters: true });
+  }
+
+  /**
+   * Locks selected rows for mutation until the surrounding transaction ends.
+   * PostgreSQL emits `FOR UPDATE`. Call this only inside a caller-owned
+   * transaction.
+   */
+  forUpdate(options?: ForUpdateOptionsV1): EntityQuery<T, TResult> {
+    return this.derive({ ...this.plan, rowLock: "update", skipLocked: options?.skipLocked === true });
+  }
+
+  /**
+   * Projects columns into a plain object (without materializing the full entity).
+   *
+   * ```ts
+   * await ctx.users.select(u => ({ name: u.name, age: u.age })).toList();
+   * ```
+   */
+  select<R extends Record<string, unknown>>(selector: (entity: T) => R): ProjectedQuery<T, R> {
+    const projections = captureProjection(selector);
+    return new ProjectedQuery<T, R>(this.model, this.runtime, { ...this.plan, projections, noTracking: true });
+  }
+
+  /**
+   * Eager loading of a navigation (split query). Chain `.thenInclude(...)`
+   * to load nested navigations.
+   *
+   * ```ts
+   * ctx.users.include((u) => u.posts).thenInclude((p) => p.comments).toList();
+   * ```
+   */
+  include<N>(selector: (entity: T) => N): IncludableQuery<T, NavigationElement<N>> {
+    const navigation = captureNavigation(selector);
+    const plan: QueryPlan = { ...this.plan, includes: [...this.plan.includes, [navigation]] };
+    return new IncludableQuery<T, NavigationElement<N>>(this.model, this.runtime, plan);
+  }
+
+  protected translator(): SqlTranslator {
+    return new SqlTranslator(this.model, this.runtime.provider.dialect);
+  }
+
+  async toList(): Promise<TResult[]> {
+    assertSkipLocked(this.model, this.runtime, this.plan, "toList");
+    const { sql, params } = this.translator().selectAll(this.plan);
+    const rows = await this.runtime.provider.query(sql, params);
+    const result: T[] = new Array(rows.length);
+    for (let i = 0; i < rows.length; i += 1) {
+      let entity = materialize<T>(this.model, rows[i]!, this.runtime.provider.dialect);
+      if (!this.plan.noTracking) {
+        // trackLoaded returns the canonical instance (identity resolution).
+        entity = this.plan.rowLock
+          ? this.runtime.tracker.trackReloaded(entity, this.model) as T
+          : this.runtime.tracker.trackLoaded(entity, this.model) as T;
+      }
+      result[i] = entity;
+    }
+    if (this.plan.includes.length > 0) {
+      await new IncludeLoader(this.runtime).load(this.model, result as object[], this.plan.includes, this.plan.noTracking);
+    }
+    return result as unknown as TResult[];
+  }
+
+  /** The first element or null. */
+  async firstOrDefault(predicate?: PredicateFn<T>): Promise<TResult | null> {
+    const query = predicate ? this.where(predicate) : this;
+    const rows = await query.take(1).toList();
+    return rows.length > 0 ? rows[0]! : null;
+  }
+
+  /** The first element, or an error if nothing is found. */
+  async first(predicate?: PredicateFn<T>): Promise<TResult> {
+    const result = await this.firstOrDefault(predicate);
+    if (result === null) {
+      throw new EntityNotFoundError(this.model.name);
+    }
+    return result;
+  }
+
+  async count(predicate?: PredicateFn<T>): Promise<number> {
+    const query = predicate ? this.where(predicate) : this;
+    assertSkipLocked(query.model, query.runtime, query.plan, "count");
+    const { sql, params } = query.translator().selectCount(query.plan);
+    const rows = await this.runtime.provider.query(sql, params);
+    return Number((rows[0] as { count?: unknown })?.count ?? 0);
+  }
+
+  async any(predicate?: PredicateFn<T>): Promise<boolean> {
+    return (await this.count(predicate)) > 0;
+  }
+
+  executeUpdate(values: OrmUpdateValuesV1<T>): Promise<OrmMutationResultV1> {
+    return executeImmediateUpdate(this.model, this.runtime, this.plan, values);
+  }
+
+  executeDelete(): Promise<OrmMutationResultV1> {
+    return executeImmediateDelete(this.model, this.runtime, this.plan);
+  }
+
+}
+
+function assertSkipLocked(model: EntityModel, runtime: DbContextRuntime, plan: QueryPlan, terminal: "toList" | "count"): void {
+  if (!plan.skipLocked) return;
+  if (terminal !== "toList" || runtime.provider.isTransactionActive?.() !== true || plan.conditions.length === 0 || plan.invalidRequestedLimit !== undefined || !Number.isSafeInteger(plan.limit) || plan.limit! <= 0 || plan.requestedLimit !== undefined && plan.requestedLimit !== plan.limit || plan.offset !== undefined || plan.projections.length !== 0 || plan.includes.length !== 0) throw new Error("FOR UPDATE SKIP LOCKED requires an active transaction, where, positive take, and terminal materialization.");
+  const ordered = new Set(plan.orders.map((order) => order.property));
+  if (!model.key.every((key) => ordered.has(key.propertyName))) throw new Error("FOR UPDATE SKIP LOCKED requires an explicit complete primary-key order.");
+}
+
+/**
+ * Query with an active Include chain: `thenInclude` loads a navigation of the
+ * last included entity (`TLast`).
+ */
+export class IncludableQuery<T extends object, TLast> extends EntityQuery<T> {
+  thenInclude<N>(selector: (entity: TLast) => N): IncludableQuery<T, NavigationElement<N>> {
+    const navigation = captureNavigation(selector);
+    const includes = this.plan.includes.map((path) => [...path]);
+    const last = includes[includes.length - 1];
+    if (!last) {
+      throw new Error("thenInclude must follow an include().");
+    }
+    last.push(navigation);
+    return new IncludableQuery<T, NavigationElement<N>>(this.model, this.runtime, { ...this.plan, includes });
+  }
+}
+
+/** Query with a `.select(...)` projection: `toList()` returns plain objects. */
+export class ProjectedQuery<T extends object, R> extends EntityQuery<T, R> {
+  protected override derive(plan: QueryPlan): ProjectedQuery<T, R> {
+    return new ProjectedQuery<T, R>(this.model, this.runtime, plan);
+  }
+
+  override async toList(): Promise<R[]> {
+    assertSkipLocked(this.model, this.runtime, this.plan, "toList");
+    const { sql, params } = this.translator().selectAll(this.plan);
+    const rows = await this.runtime.provider.query(sql, params);
+    const dialect = this.runtime.provider.dialect;
+    return rows.map((row) => materializeProjection(this.model, row, dialect, this.plan.projections) as R);
+  }
+
+  override async firstOrDefault(predicate?: PredicateFn<T>): Promise<R | null> {
+    const query = predicate ? this.where(predicate) : this;
+    const rows = await query.take(1).toList();
+    return rows.length > 0 ? rows[0]! : null;
+  }
+
+  override async first(predicate?: PredicateFn<T>): Promise<R> {
+    const result = await this.firstOrDefault(predicate);
+    if (result === null) {
+      throw new EntityNotFoundError(this.model.name);
+    }
+    return result;
+  }
+}