@atscript/db 0.1.103 → 0.1.105

package/dist/{db-space-BYyVZnL1.d.mts → db-space-0U_4PiNS.d.mts}

@@ -1,4 +1,4 @@
-import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-CXdHBtF6.mjs";
+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-Ds01ezjj.mjs";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 import { FilterExpr } from "@uniqu/core";
 
@@ -124,6 +124,21 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * Ensures the table/collection exists in the database.
    */
   ensureTable(): Promise<void>;
+  /** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
+  protected _guardMutationFilter(filter: FilterExpr): void;
+  /**
+   * Encrypts `@db.encrypted` field values in place on (already validated)
+   * write payloads — between validation and `prepareForWrite`, so adapters
+   * only ever see envelope strings.
+   *
+   * Parent objects along an encrypted path are shallow-cloned before
+   * mutation so caller-shared nested objects are never modified.
+   *
+   * In `patch` mode, operator objects (`$inc`, `$insert`, …) targeting an
+   * encrypted field are rejected with `ENC_FIELD_PATCH_OP` — ciphertext is
+   * opaque; only plain re-assignment (which re-encrypts) is allowed.
+   */
+  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
@@ -259,6 +274,13 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
  * Each readable gets its own adapter (1:1 relationship required by BaseDbAdapter).
  */
 type TAdapterFactory = () => BaseDbAdapter;
+/** Options bag for {@link DbSpace} (second constructor argument). */
+interface TDbSpaceOptions {
+  /** Logger shared by all tables/views in the space. */
+  logger?: TGenericLogger;
+  /** Field-level encryption configuration for `@db.encrypted` fields. */
+  encryption?: TDbEncryptionOptions;
+}
 /**
  * A database space — a registry of tables and views sharing the same adapter type and driver.
  *
@@ -279,13 +301,20 @@ type TAdapterFactory = () => BaseDbAdapter;
  */
 declare class DbSpace {
   protected readonly adapterFactory: TAdapterFactory;
-  protected readonly logger: TGenericLogger;
   private _readables;
   /** All tables created in this space — used for reverse FK lookup during cascade. */
   private _allTables;
   /** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
   private _adminAdapter?;
-  constructor(adapterFactory: TAdapterFactory, logger?: TGenericLogger);
+  protected readonly logger: TGenericLogger;
+  /** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
+  protected readonly _encryption?: DbEncryption;
+  /**
+   * @param adapterFactory - Creates a fresh adapter per table/view.
+   * @param loggerOrOptions - Either a logger (legacy signature) or a
+   *   {@link TDbSpaceOptions} bag carrying `logger` and/or `encryption`.
+   */
+  constructor(adapterFactory: TAdapterFactory, loggerOrOptions?: TGenericLogger | TDbSpaceOptions);
   /**
    * Auto-detects whether the type is a table or view and returns the
    * appropriate instance. Uses `@db.view` or `@db.view.for` presence to distinguish.
@@ -327,4 +356,4 @@ declare class DbSpace {
   private _getFkLookupTarget;
 }
 //#endregion
-export { AtscriptQueryComparison as a, AtscriptRef as c, translateQueryTree as d, AtscriptDbTable as f, TViewColumnMapping as i, TViewJoin as l, NativeIntegrity as m, TAdapterFactory as n, AtscriptQueryFieldRef$1 as o, IntegrityStrategy as p, AtscriptDbView as r, AtscriptQueryNode$1 as s, DbSpace as t, TViewPlan as u };
+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 };

package/dist/{db-space-BhOc9_OO.d.cts → db-space-CWhIEC7E.d.cts}

@@ -1,4 +1,4 @@
-import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-mhPp-MPv.cjs";
+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-BepVc21V.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";
 
@@ -124,6 +124,21 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * Ensures the table/collection exists in the database.
    */
   ensureTable(): Promise<void>;
+  /** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
+  protected _guardMutationFilter(filter: FilterExpr): void;
+  /**
+   * Encrypts `@db.encrypted` field values in place on (already validated)
+   * write payloads — between validation and `prepareForWrite`, so adapters
+   * only ever see envelope strings.
+   *
+   * Parent objects along an encrypted path are shallow-cloned before
+   * mutation so caller-shared nested objects are never modified.
+   *
+   * In `patch` mode, operator objects (`$inc`, `$insert`, …) targeting an
+   * encrypted field are rejected with `ENC_FIELD_PATCH_OP` — ciphertext is
+   * opaque; only plain re-assignment (which re-encrypts) is allowed.
+   */
+  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
@@ -259,6 +274,13 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
  * Each readable gets its own adapter (1:1 relationship required by BaseDbAdapter).
  */
 type TAdapterFactory = () => BaseDbAdapter;
+/** Options bag for {@link DbSpace} (second constructor argument). */
+interface TDbSpaceOptions {
+  /** Logger shared by all tables/views in the space. */
+  logger?: TGenericLogger;
+  /** Field-level encryption configuration for `@db.encrypted` fields. */
+  encryption?: TDbEncryptionOptions;
+}
 /**
  * A database space — a registry of tables and views sharing the same adapter type and driver.
  *
@@ -279,13 +301,20 @@ type TAdapterFactory = () => BaseDbAdapter;
  */
 declare class DbSpace {
   protected readonly adapterFactory: TAdapterFactory;
-  protected readonly logger: TGenericLogger;
   private _readables;
   /** All tables created in this space — used for reverse FK lookup during cascade. */
   private _allTables;
   /** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
   private _adminAdapter?;
-  constructor(adapterFactory: TAdapterFactory, logger?: TGenericLogger);
+  protected readonly logger: TGenericLogger;
+  /** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
+  protected readonly _encryption?: DbEncryption;
+  /**
+   * @param adapterFactory - Creates a fresh adapter per table/view.
+   * @param loggerOrOptions - Either a logger (legacy signature) or a
+   *   {@link TDbSpaceOptions} bag carrying `logger` and/or `encryption`.
+   */
+  constructor(adapterFactory: TAdapterFactory, loggerOrOptions?: TGenericLogger | TDbSpaceOptions);
   /**
    * Auto-detects whether the type is a table or view and returns the
    * appropriate instance. Uses `@db.view` or `@db.view.for` presence to distinguish.
@@ -327,4 +356,4 @@ declare class DbSpace {
   private _getFkLookupTarget;
 }
 //#endregion
-export { AtscriptQueryComparison as a, AtscriptRef as c, translateQueryTree as d, AtscriptDbTable as f, TViewColumnMapping as i, TViewJoin as l, NativeIntegrity as m, TAdapterFactory as n, AtscriptQueryFieldRef$1 as o, IntegrityStrategy as p, AtscriptDbView as r, AtscriptQueryNode$1 as s, DbSpace as t, TViewPlan as u };
+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 };