@atscript/db 0.1.127 → 0.1.128

package/dist/{db-space-CSntT6yS.d.cts → db-space-BevOyVrC.d.cts}

@@ -1,4 +1,4 @@
-import { C as TCascadeResolver, F as TDbDeleteResult, H as TDbInsertResult, K as TDbUpdateResult, V as TDbInsertManyResult, X as TFkLookupResolver, _t as TGenericLogger, a as TDbEncryptionOptions, c as BaseDbAdapter, ct as TWriteTableResolver, i as DbEncryption, ot as TTableResolver, pt as TableMetadata, t as AtscriptDbReadable } from "./db-readable-C0nDKX8A.cjs";
+import { C as NullableOptional, Ct as TWriteTableResolver, E as TCascadeResolver, G as TDbInsertResult, Nt as TGenericLogger, Ot as TableMetadata, Q as TDbUpdateResult, R as TDbDeleteResult, St as TWriteOptions, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow } from "./db-readable-CkbZn_z-.cjs";
 import { FilterExpr } from "@uniqu/core";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 
@@ -24,7 +24,7 @@ declare class NativeIntegrity extends IntegrityStrategy {
 }
 //#endregion
 //#region src/table/db-table.d.ts
-declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, FlatType = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = OwnPropsOf<T>, NavType extends Record<string, unknown> = NavPropsOf<T>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
+declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, FlatType = NullableOptional<FlatOf<T>>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = NullableOptional<OwnPropsOf<T>>, NavType extends Record<string, unknown> = NavPropsOf<T>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
   protected _cascadeResolver?: TCascadeResolver;
   protected _fkLookupResolver?: TFkLookupResolver;
   protected readonly _integrity: IntegrityStrategy;
@@ -53,9 +53,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * Inserts a single record. Delegates to {@link insertMany} for unified
    * nested creation support.
    */
-  insertOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbInsertResult>;
+  insertOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbInsertResult>;
   /**
    * Inserts multiple records with batch-optimized nested creation.
    *
@@ -66,17 +64,16 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * (they receive our PKs as their FKs). Fully recursive — nested records
    * with their own nav data trigger further batch inserts at each level.
    * Recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * defaults + validation, with the prepared rows — see {@link TWriteOptions}.
    */
-  insertMany(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbInsertManyResult>;
+  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbInsertManyResult>;
   /**
    * Replaces a single record identified by primary key(s).
    * Delegates to {@link bulkReplace} for unified nested relation support.
    */
-  replaceOne(payload: DataType & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  replaceOne(payload: DbRow<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Replaces multiple records with deep nested relation support.
    *
@@ -84,37 +81,43 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * replaced first (their PKs become our FKs), FROM dependents are replaced
    * after (they receive our PKs as their FKs), VIA relations clear and
    * re-create junction rows. Fully recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * `$cas` extraction, defaults + validation — see {@link TWriteOptions}.
    */
-  bulkReplace(payloads: Array<DataType & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  bulkReplace(payloads: Array<DbRow<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Partially updates a single record identified by primary key(s).
    * Delegates to {@link bulkUpdate} for unified nested relation support.
    */
-  updateOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  updateOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Partially updates multiple records with deep nested relation support.
    *
    * Only TO relations (1:1, N:1) are supported for patching. FROM/VIA
    * relations will error — use {@link bulkReplace} for those.
    * Recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * `$cas` extraction and validation, with the patches (identifying fields
+   * present, `$cas` removed) — see {@link TWriteOptions}.
    */
-  bulkUpdate(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Deletes a single record by any type-compatible identifier — primary key
    * or single-field unique index. Uses the same resolution logic as `findById`.
    *
    * When the adapter does not support native foreign keys (e.g. MongoDB),
    * cascade and setNull actions are applied before the delete.
-   */
-  deleteOne(id: IdType): Promise<TDbDeleteResult>;
-  updateMany(filter: FilterExpr<FlatType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
-  replaceMany(filter: FilterExpr<FlatType>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+   *
+   * `opts.guard` (since 0.1.128) runs inside the transaction once the id has
+   * resolved to a filter, before cascade / delete — see {@link TDeleteOptions}.
+   * An id that resolves to no filter answers `{ deletedCount: 0 }` without
+   * calling the guard.
+   */
+  deleteOne(id: IdType, opts?: TDeleteOptions<DataType>): Promise<TDbDeleteResult>;
+  updateMany(filter: FilterExpr<FlatType>, data: DbPatch<DataType>): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr<FlatType>, data: DbRow<DataType>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr<FlatType>): Promise<TDbDeleteResult>;
   /**
    * Synchronizes indexes between Atscript definitions and the database.
@@ -140,11 +143,31 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    */
   protected _encryptItems(items: Array<Record<string, unknown>>, mode: "write" | "patch"): Promise<void>;
   /**
-   * Applies default values for fields that are missing from the payload.
-   * Defaults handled natively by the DB engine are skipped — the field stays
-   * absent so the DB's own DEFAULT clause applies.
+   * Lazy pre-image read for a guard's `current(i)`: `null` when the row has
+   * no identifying key (e.g. an auto-increment insert) or the key cannot be
+   * resolved — never throws for a missing key.
+   * @internal
+   */
+  _readPreImage(row: unknown): Promise<DataType | null>;
+  /**
+   * Applies `@db.default` values in place to a row's absent fields — the
+   * defaults pass every insert / replace path runs before validation.
+   * Static value defaults (`@db.default 'x'`) are filled on EVERY adapter
+   * (since 0.1.128 — writing the column's own default explicitly is
+   * equivalent to leaving it to the DDL `DEFAULT`, and write guards see the
+   * full row). Function defaults (`now` / `uuid` / `increment` / custom) the
+   * adapter handles natively are NOT filled — the field stays absent so the
+   * engine's own default applies. The version column is never touched.
    */
   protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * The JS value for a `@db.default 'literal'`: strings (including unions of
+   * string literals) are used as-is, every other design type is parsed as
+   * JSON — the same value the SQL adapters put into the DDL `DEFAULT` clause.
+   * A literal that is not valid JSON falls back to the raw string so the
+   * validator reports it against the field instead of a bare `SyntaxError`.
+   */
+  private _parseValueDefault;
   /**
    * Extracts a record-identifying filter from a payload.
    *
@@ -235,7 +258,7 @@ interface TViewColumnMapping {
  * const users = await activeUsers.findMany({ filter: {}, controls: {} })
  * ```
  */
-declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, FlatType = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = OwnPropsOf<T>, NavType extends Record<string, unknown> = NavPropsOf<T>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
+declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, FlatType = NullableOptional<FlatOf<T>>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = NullableOptional<OwnPropsOf<T>>, NavType extends Record<string, unknown> = NavPropsOf<T>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
   private _viewPlan?;
   get isView(): boolean;
   /**
@@ -267,6 +290,16 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    */
   getViewColumnMappings(): TViewColumnMapping[];
 }
+/**
+ * Structural type guard for views: `true` when the readable reports
+ * `isView`, whether or not it is an `AtscriptDbView` instance of THIS copy
+ * of `@atscript/db`. Adapters must use this (or `readable.isView`) instead of
+ * `instanceof AtscriptDbView` — in a bundle that carries two copies of the
+ * core (app bundle + external adapter), `instanceof` is false and the adapter
+ * would create an empty physical table under the view's name.
+ * @since 0.1.128
+ */
+declare function isAtscriptDbView(readable: AtscriptDbReadable<any, any, any, any, any, any, any>): readable is AtscriptDbView<any, any, any, any, any, any, any>;
 //#endregion
 //#region src/table/db-space.d.ts
 /**
@@ -343,6 +376,25 @@ declare class DbSpace {
    * Drops a view by name. Used by schema sync to remove views no longer in the schema.
    */
   dropViewByName(viewName: string): Promise<void>;
+  /**
+   * Drops a group of mutually referencing tables as one operation.
+   * Used by schema sync to remove a foreign-key cycle no longer in the schema.
+   * @since 0.1.128
+   */
+  dropTablesByName(tableNames: string[]): Promise<void>;
+  /**
+   * Live foreign keys referencing `tableName`, or `undefined` when the
+   * adapter cannot introspect them. Used by schema sync for drop ordering
+   * and surviving-reference checks of tables without a registered readable.
+   * @since 0.1.128
+   */
+  getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[] | undefined>;
+  /**
+   * A factory-fresh adapter with NO registered readable. Only the name-taking
+   * primitives may run on it (`dropTableByName`, `dropViewByName`,
+   * `dropTablesByName`, `getReferencingForeignKeys`) — adapters derive the
+   * schema for those from the driver/connection, not from a bound table.
+   */
   private _getAdminAdapter;
   /**
    * Finds all child tables with FKs pointing to the given parent table name.
@@ -356,4 +408,4 @@ declare class DbSpace {
   private _getFkLookupTarget;
 }
 //#endregion
-export { TViewColumnMapping as a, AtscriptQueryNode$1 as c, TViewPlan as d, translateQueryTree as f, NativeIntegrity as h, AtscriptDbView as i, AtscriptRef as l, IntegrityStrategy as m, TAdapterFactory as n, AtscriptQueryComparison as o, AtscriptDbTable as p, TDbSpaceOptions as r, AtscriptQueryFieldRef$1 as s, DbSpace as t, TViewJoin as u };
+export { TViewColumnMapping as a, AtscriptQueryFieldRef$1 as c, TViewJoin as d, TViewPlan as f, NativeIntegrity as g, IntegrityStrategy as h, AtscriptDbView as i, AtscriptQueryNode$1 as l, AtscriptDbTable as m, TAdapterFactory as n, isAtscriptDbView as o, translateQueryTree as p, TDbSpaceOptions as r, AtscriptQueryComparison as s, DbSpace as t, AtscriptRef as u };