@atscript/db 0.1.54 → 0.1.55

package/dist/db-error-Cepx-RsQ.mjs

@@ -0,0 +1,29 @@
+//#region src/db-error.ts
+var DbError = class extends Error {
+	name = "DbError";
+	constructor(code, errors, message) {
+		super(message ?? errors[0]?.message ?? "Database error");
+		this.code = code;
+		this.errors = errors;
+		this.stack = void 0;
+	}
+};
+/**
+* Thrown when a write payload nests deeper than the table's
+* declared `@db.depth.limit N`. Surfaced as HTTP 400 in moost-db.
+*/
+var DepthLimitExceededError = class extends DbError {
+	name = "DepthLimitExceededError";
+	constructor(field, declared, actual) {
+		const message = `Nested write depth ${actual} exceeds declared @db.depth.limit ${declared} at '${field}'`;
+		super("DEPTH_EXCEEDED", [{
+			path: field,
+			message
+		}], message);
+		this.field = field;
+		this.declared = declared;
+		this.actual = actual;
+	}
+};
+//#endregion
+export { DepthLimitExceededError as n, DbError as t };

package/dist/db-error-D8tQhNgM.cjs

@@ -0,0 +1,40 @@
+//#region src/db-error.ts
+var DbError = class extends Error {
+	name = "DbError";
+	constructor(code, errors, message) {
+		super(message ?? errors[0]?.message ?? "Database error");
+		this.code = code;
+		this.errors = errors;
+		this.stack = void 0;
+	}
+};
+/**
+* Thrown when a write payload nests deeper than the table's
+* declared `@db.depth.limit N`. Surfaced as HTTP 400 in moost-db.
+*/
+var DepthLimitExceededError = class extends DbError {
+	name = "DepthLimitExceededError";
+	constructor(field, declared, actual) {
+		const message = `Nested write depth ${actual} exceeds declared @db.depth.limit ${declared} at '${field}'`;
+		super("DEPTH_EXCEEDED", [{
+			path: field,
+			message
+		}], message);
+		this.field = field;
+		this.declared = declared;
+		this.actual = actual;
+	}
+};
+//#endregion
+Object.defineProperty(exports, "DbError", {
+	enumerable: true,
+	get: function() {
+		return DbError;
+	}
+});
+Object.defineProperty(exports, "DepthLimitExceededError", {
+	enumerable: true,
+	get: function() {
+		return DepthLimitExceededError;
+	}
+});

package/dist/{db-readable-ktHqF277.d.cts → db-readable-DtrC0BGF.d.cts}

@@ -44,6 +44,120 @@ declare class UniquSelect {
   get hasAggregates(): boolean;
 }
 //#endregion
+//#region src/logger.d.ts
+interface TGenericLogger {
+  error(...messages: any[]): void;
+  warn(...messages: any[]): void;
+  log(...messages: any[]): void;
+  info(...messages: any[]): void;
+  debug(...messages: any[]): void;
+}
+declare const NoopLogger: TGenericLogger;
+//#endregion
+//#region src/table/table-metadata.d.ts
+/**
+ * Computed metadata for a database table or view.
+ *
+ * Contains all field metadata, physical mapping indexes, relation definitions,
+ * and constraint information derived from Atscript annotations. Built lazily
+ * on first access via {@link build}, then immutable.
+ *
+ * This class owns the build pipeline that was previously part of
+ * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
+ * access to this class.
+ */
+declare class TableMetadata {
+  readonly nestedObjects: boolean;
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  fieldDescriptors: readonly TDbFieldMeta[];
+  primaryKeys: string[];
+  originalMetaIdFields: string[];
+  indexes: Map<string, TDbIndex>;
+  foreignKeys: Map<string, TDbForeignKey>;
+  relations: Map<string, TDbRelation>;
+  navFields: Set<string>;
+  ignoredFields: Set<string>;
+  uniqueProps: Set<string>;
+  defaults: Map<string, TDbDefaultValue>;
+  columnMap: Map<string, string>;
+  dimensions: string[];
+  measures: string[];
+  pathToPhysical: Map<string, string>;
+  physicalToPath: Map<string, string>;
+  flattenedParents: Set<string>;
+  jsonFields: Set<string>;
+  selectExpansion: Map<string, string[]>;
+  booleanFields: Set<string>;
+  decimalFields: Set<string>;
+  allPhysicalFields: string[];
+  /** Precomputed parent path → child physical column names for fast null-setting. */
+  childrenByParent: Map<string, string[]>;
+  requiresMappings: boolean;
+  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
+  onlyColumnRenames: boolean;
+  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  /** Leaf field descriptors indexed by physical column name (read path). */
+  leafByPhysical: Map<string, TDbFieldMeta>;
+  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
+  leafByLogical: Map<string, TDbFieldMeta>;
+  private _built;
+  private _collateMap;
+  private _columnFromMap;
+  constructor(nestedObjects: boolean);
+  get isBuilt(): boolean;
+  /**
+   * Runs the full metadata compilation pipeline. Called once by
+   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
+   *
+   * Pipeline steps:
+   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
+   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
+   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
+   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
+   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
+   * 6. Build field descriptors (TDbFieldMeta[])
+   * 7. Build leaf field indexes (skipped for nested-objects adapters)
+   * 8. Finalize indexes (resolve field names to physical)
+   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
+   * 10. Build allPhysicalFields list
+   */
+  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
+  /**
+   * Applies adapter-provided metadata overrides atomically.
+   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
+   */
+  private _applyOverrides;
+  /**
+   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
+   */
+  private _scanGenericAnnotations;
+  private _addIndexField;
+  /**
+   * Classifies each field as column, flattened, json, or parent-object.
+   * Builds the bidirectional pathToPhysical / physicalToPath maps.
+   */
+  private _classifyFields;
+  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
+  private _flattenedPrefix;
+  /**
+   * Indexes `fieldDescriptors` into two lookup maps for unified
+   * read/write field classification in the RelationalFieldMapper.
+   */
+  private _buildLeafIndexes;
+  /**
+   * Builds field descriptors, physical-name lookup, and value formatters.
+   * Called once during build() — everything it needs
+   * (flatMap, indexes, columnMap, etc.) is already populated.
+   */
+  private _buildFieldDescriptors;
+  /**
+   * Resolves `fkTargetField` for FK fields in field descriptors.
+   */
+  private _resolveFkTargetFields;
+  private _finalizeIndexes;
+}
+//#endregion
 //#region src/types.d.ts
 /** Controls with resolved projection. Used in the adapter interface. */
 interface DbControls extends Omit<UniqueryControls, "$select"> {
@@ -290,6 +404,7 @@ interface AtscriptDbTableLike {
   primaryKeys: readonly string[];
   relations: ReadonlyMap<string, TDbRelation>;
   foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  getMetadata(): TableMetadata;
 }
 /** Minimal writable table interface for nested creation/update. */
 interface AtscriptDbWritable {
@@ -375,120 +490,6 @@ interface TDbRelation {
   viaType?: () => TAtscriptAnnotatedType;
 }
 //#endregion
-//#region src/logger.d.ts
-interface TGenericLogger {
-  error(...messages: any[]): void;
-  warn(...messages: any[]): void;
-  log(...messages: any[]): void;
-  info(...messages: any[]): void;
-  debug(...messages: any[]): void;
-}
-declare const NoopLogger: TGenericLogger;
-//#endregion
-//#region src/table/table-metadata.d.ts
-/**
- * Computed metadata for a database table or view.
- *
- * Contains all field metadata, physical mapping indexes, relation definitions,
- * and constraint information derived from Atscript annotations. Built lazily
- * on first access via {@link build}, then immutable.
- *
- * This class owns the build pipeline that was previously part of
- * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
- * access to this class.
- */
-declare class TableMetadata {
-  readonly nestedObjects: boolean;
-  flatMap: Map<string, TAtscriptAnnotatedType>;
-  fieldDescriptors: readonly TDbFieldMeta[];
-  primaryKeys: string[];
-  originalMetaIdFields: string[];
-  indexes: Map<string, TDbIndex>;
-  foreignKeys: Map<string, TDbForeignKey>;
-  relations: Map<string, TDbRelation>;
-  navFields: Set<string>;
-  ignoredFields: Set<string>;
-  uniqueProps: Set<string>;
-  defaults: Map<string, TDbDefaultValue>;
-  columnMap: Map<string, string>;
-  dimensions: string[];
-  measures: string[];
-  pathToPhysical: Map<string, string>;
-  physicalToPath: Map<string, string>;
-  flattenedParents: Set<string>;
-  jsonFields: Set<string>;
-  selectExpansion: Map<string, string[]>;
-  booleanFields: Set<string>;
-  decimalFields: Set<string>;
-  allPhysicalFields: string[];
-  /** Precomputed parent path → child physical column names for fast null-setting. */
-  childrenByParent: Map<string, string[]>;
-  requiresMappings: boolean;
-  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
-  onlyColumnRenames: boolean;
-  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  /** Leaf field descriptors indexed by physical column name (read path). */
-  leafByPhysical: Map<string, TDbFieldMeta>;
-  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
-  leafByLogical: Map<string, TDbFieldMeta>;
-  private _built;
-  private _collateMap;
-  private _columnFromMap;
-  constructor(nestedObjects: boolean);
-  get isBuilt(): boolean;
-  /**
-   * Runs the full metadata compilation pipeline. Called once by
-   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
-   *
-   * Pipeline steps:
-   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
-   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
-   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
-   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
-   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
-   * 6. Build field descriptors (TDbFieldMeta[])
-   * 7. Build leaf field indexes (skipped for nested-objects adapters)
-   * 8. Finalize indexes (resolve field names to physical)
-   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
-   * 10. Build allPhysicalFields list
-   */
-  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
-  /**
-   * Applies adapter-provided metadata overrides atomically.
-   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
-   */
-  private _applyOverrides;
-  /**
-   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
-   */
-  private _scanGenericAnnotations;
-  private _addIndexField;
-  /**
-   * Classifies each field as column, flattened, json, or parent-object.
-   * Builds the bidirectional pathToPhysical / physicalToPath maps.
-   */
-  private _classifyFields;
-  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
-  private _flattenedPrefix;
-  /**
-   * Indexes `fieldDescriptors` into two lookup maps for unified
-   * read/write field classification in the RelationalFieldMapper.
-   */
-  private _buildLeafIndexes;
-  /**
-   * Builds field descriptors, physical-name lookup, and value formatters.
-   * Called once during build() — everything it needs
-   * (flatMap, indexes, columnMap, etc.) is already populated.
-   */
-  private _buildFieldDescriptors;
-  /**
-   * Resolves `fkTargetField` for FK fields in field descriptors.
-   */
-  private _resolveFkTargetFields;
-  private _finalizeIndexes;
-}
-//#endregion
 //#region src/base-adapter.d.ts
 /**
  * Abstract base class for database adapters.
@@ -1106,6 +1107,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
   /** Ensures metadata is built. Called before any metadata access. */
   protected _ensureBuilt(): void;
+  /**
+   * Built table metadata. Triggers a lazy build on first access — safe to call
+   * from peer tables that need this one's relations / nav fields before any
+   * operation has run against it directly.
+   */
+  getMetadata(): TableMetadata;
   protected _ensureSearchable(): void;
   /** Whether this readable is a view (overridden in AtscriptDbView). */
   get isView(): boolean;
@@ -1280,4 +1287,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TValueFormatterPair as $, TDbForeignKey as A, TExistingColumn as B, TCascadeTarget as C, TDbDefaultValue as D, TDbDefaultFn as E, TDbInsertResult as F, TIdDescriptor as G, TFieldMeta as H, TDbReferentialAction as I, TRelationInfo as J, TMetaResponse as K, TDbRelation as L, TDbIndexField as M, TDbIndexType as N, TDbDeleteResult as O, TDbInsertManyResult as P, TTableResolver as Q, TDbStorageType as R, TCascadeResolver as S, TDbCollation as T, TFkLookupResolver as U, TExistingTableOption as V, TFkLookupTarget as W, TSyncColumnResult as X, TSearchIndexInfo as Y, TTableOptionDiff as Z, DbQuery as _, FieldMappingStrategy as a, UniquSelect as at, NavPropsOf$1 as b, NoopLogger as c, AggregateExpr$1 as d, TWriteTableResolver as et, AggregateFn as f, DbControls as g, AtscriptDbWritable as h, DocumentFieldMapper as i, WithRelation$1 as it, TDbIndex as j, TDbFieldMeta as k, TGenericLogger as l, AggregateResult as m, DbResponse as n, Uniquery$1 as nt, BaseDbAdapter as o, AggregateQuery$1 as p, TMetadataOverrides as q, resolveDesignType as r, UniqueryControls$1 as rt, TableMetadata as s, AtscriptDbReadable as t, TypedWithRelation as tt, AggregateControls as u, FieldOpsFor as v, TColumnDiff as w, OwnPropsOf$1 as x, FilterExpr$1 as y, TDbUpdateResult as z };
+export { Uniquery$1 as $, TDbIndexType as A, TFkLookupResolver as B, TDbDefaultFn as C, TDbForeignKey as D, TDbFieldMeta as E, TDbStorageType as F, TRelationInfo as G, TIdDescriptor as H, TDbUpdateResult as I, TTableOptionDiff as J, TSearchIndexInfo as K, TExistingColumn as L, TDbInsertResult as M, TDbReferentialAction as N, TDbIndex as O, TDbRelation as P, TypedWithRelation as Q, TExistingTableOption as R, TDbCollation as S, TDbDeleteResult as T, TMetaResponse as U, TFkLookupTarget as V, TMetadataOverrides as W, TValueFormatterPair as X, TTableResolver as Y, TWriteTableResolver as Z, NavPropsOf$1 as _, FieldMappingStrategy as a, UniquSelect as at, TCascadeTarget as b, AggregateExpr$1 as c, AggregateResult as d, UniqueryControls$1 as et, AtscriptDbWritable as f, FilterExpr$1 as g, FieldOpsFor as h, DocumentFieldMapper as i, TGenericLogger as it, TDbInsertManyResult as j, TDbIndexField as k, AggregateFn as l, DbQuery as m, DbResponse as n, TableMetadata as nt, BaseDbAdapter as o, DbControls as p, TSyncColumnResult as q, resolveDesignType as r, NoopLogger as rt, AggregateControls as s, AtscriptDbReadable as t, WithRelation$1 as tt, AggregateQuery$1 as u, OwnPropsOf$1 as v, TDbDefaultValue as w, TColumnDiff as x, TCascadeResolver as y, TFieldMeta as z };

package/dist/{db-readable-GBjlsJXR.d.mts → db-readable-RTtqL7H4.d.mts}

@@ -1,4 +1,4 @@
-import { u as TFieldOps } from "./ops-DcHDxrjX.mjs";
+import { u as TFieldOps } from "./ops-C61kelof.mjs";
 import { FlatOf, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 
@@ -44,6 +44,120 @@ declare class UniquSelect {
   get hasAggregates(): boolean;
 }
 //#endregion
+//#region src/logger.d.ts
+interface TGenericLogger {
+  error(...messages: any[]): void;
+  warn(...messages: any[]): void;
+  log(...messages: any[]): void;
+  info(...messages: any[]): void;
+  debug(...messages: any[]): void;
+}
+declare const NoopLogger: TGenericLogger;
+//#endregion
+//#region src/table/table-metadata.d.ts
+/**
+ * Computed metadata for a database table or view.
+ *
+ * Contains all field metadata, physical mapping indexes, relation definitions,
+ * and constraint information derived from Atscript annotations. Built lazily
+ * on first access via {@link build}, then immutable.
+ *
+ * This class owns the build pipeline that was previously part of
+ * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
+ * access to this class.
+ */
+declare class TableMetadata {
+  readonly nestedObjects: boolean;
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  fieldDescriptors: readonly TDbFieldMeta[];
+  primaryKeys: string[];
+  originalMetaIdFields: string[];
+  indexes: Map<string, TDbIndex>;
+  foreignKeys: Map<string, TDbForeignKey>;
+  relations: Map<string, TDbRelation>;
+  navFields: Set<string>;
+  ignoredFields: Set<string>;
+  uniqueProps: Set<string>;
+  defaults: Map<string, TDbDefaultValue>;
+  columnMap: Map<string, string>;
+  dimensions: string[];
+  measures: string[];
+  pathToPhysical: Map<string, string>;
+  physicalToPath: Map<string, string>;
+  flattenedParents: Set<string>;
+  jsonFields: Set<string>;
+  selectExpansion: Map<string, string[]>;
+  booleanFields: Set<string>;
+  decimalFields: Set<string>;
+  allPhysicalFields: string[];
+  /** Precomputed parent path → child physical column names for fast null-setting. */
+  childrenByParent: Map<string, string[]>;
+  requiresMappings: boolean;
+  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
+  onlyColumnRenames: boolean;
+  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  /** Leaf field descriptors indexed by physical column name (read path). */
+  leafByPhysical: Map<string, TDbFieldMeta>;
+  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
+  leafByLogical: Map<string, TDbFieldMeta>;
+  private _built;
+  private _collateMap;
+  private _columnFromMap;
+  constructor(nestedObjects: boolean);
+  get isBuilt(): boolean;
+  /**
+   * Runs the full metadata compilation pipeline. Called once by
+   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
+   *
+   * Pipeline steps:
+   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
+   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
+   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
+   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
+   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
+   * 6. Build field descriptors (TDbFieldMeta[])
+   * 7. Build leaf field indexes (skipped for nested-objects adapters)
+   * 8. Finalize indexes (resolve field names to physical)
+   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
+   * 10. Build allPhysicalFields list
+   */
+  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
+  /**
+   * Applies adapter-provided metadata overrides atomically.
+   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
+   */
+  private _applyOverrides;
+  /**
+   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
+   */
+  private _scanGenericAnnotations;
+  private _addIndexField;
+  /**
+   * Classifies each field as column, flattened, json, or parent-object.
+   * Builds the bidirectional pathToPhysical / physicalToPath maps.
+   */
+  private _classifyFields;
+  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
+  private _flattenedPrefix;
+  /**
+   * Indexes `fieldDescriptors` into two lookup maps for unified
+   * read/write field classification in the RelationalFieldMapper.
+   */
+  private _buildLeafIndexes;
+  /**
+   * Builds field descriptors, physical-name lookup, and value formatters.
+   * Called once during build() — everything it needs
+   * (flatMap, indexes, columnMap, etc.) is already populated.
+   */
+  private _buildFieldDescriptors;
+  /**
+   * Resolves `fkTargetField` for FK fields in field descriptors.
+   */
+  private _resolveFkTargetFields;
+  private _finalizeIndexes;
+}
+//#endregion
 //#region src/types.d.ts
 /** Controls with resolved projection. Used in the adapter interface. */
 interface DbControls extends Omit<UniqueryControls, "$select"> {
@@ -290,6 +404,7 @@ interface AtscriptDbTableLike {
   primaryKeys: readonly string[];
   relations: ReadonlyMap<string, TDbRelation>;
   foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  getMetadata(): TableMetadata;
 }
 /** Minimal writable table interface for nested creation/update. */
 interface AtscriptDbWritable {
@@ -375,120 +490,6 @@ interface TDbRelation {
   viaType?: () => TAtscriptAnnotatedType;
 }
 //#endregion
-//#region src/logger.d.ts
-interface TGenericLogger {
-  error(...messages: any[]): void;
-  warn(...messages: any[]): void;
-  log(...messages: any[]): void;
-  info(...messages: any[]): void;
-  debug(...messages: any[]): void;
-}
-declare const NoopLogger: TGenericLogger;
-//#endregion
-//#region src/table/table-metadata.d.ts
-/**
- * Computed metadata for a database table or view.
- *
- * Contains all field metadata, physical mapping indexes, relation definitions,
- * and constraint information derived from Atscript annotations. Built lazily
- * on first access via {@link build}, then immutable.
- *
- * This class owns the build pipeline that was previously part of
- * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
- * access to this class.
- */
-declare class TableMetadata {
-  readonly nestedObjects: boolean;
-  flatMap: Map<string, TAtscriptAnnotatedType>;
-  fieldDescriptors: readonly TDbFieldMeta[];
-  primaryKeys: string[];
-  originalMetaIdFields: string[];
-  indexes: Map<string, TDbIndex>;
-  foreignKeys: Map<string, TDbForeignKey>;
-  relations: Map<string, TDbRelation>;
-  navFields: Set<string>;
-  ignoredFields: Set<string>;
-  uniqueProps: Set<string>;
-  defaults: Map<string, TDbDefaultValue>;
-  columnMap: Map<string, string>;
-  dimensions: string[];
-  measures: string[];
-  pathToPhysical: Map<string, string>;
-  physicalToPath: Map<string, string>;
-  flattenedParents: Set<string>;
-  jsonFields: Set<string>;
-  selectExpansion: Map<string, string[]>;
-  booleanFields: Set<string>;
-  decimalFields: Set<string>;
-  allPhysicalFields: string[];
-  /** Precomputed parent path → child physical column names for fast null-setting. */
-  childrenByParent: Map<string, string[]>;
-  requiresMappings: boolean;
-  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
-  onlyColumnRenames: boolean;
-  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  /** Leaf field descriptors indexed by physical column name (read path). */
-  leafByPhysical: Map<string, TDbFieldMeta>;
-  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
-  leafByLogical: Map<string, TDbFieldMeta>;
-  private _built;
-  private _collateMap;
-  private _columnFromMap;
-  constructor(nestedObjects: boolean);
-  get isBuilt(): boolean;
-  /**
-   * Runs the full metadata compilation pipeline. Called once by
-   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
-   *
-   * Pipeline steps:
-   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
-   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
-   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
-   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
-   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
-   * 6. Build field descriptors (TDbFieldMeta[])
-   * 7. Build leaf field indexes (skipped for nested-objects adapters)
-   * 8. Finalize indexes (resolve field names to physical)
-   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
-   * 10. Build allPhysicalFields list
-   */
-  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
-  /**
-   * Applies adapter-provided metadata overrides atomically.
-   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
-   */
-  private _applyOverrides;
-  /**
-   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
-   */
-  private _scanGenericAnnotations;
-  private _addIndexField;
-  /**
-   * Classifies each field as column, flattened, json, or parent-object.
-   * Builds the bidirectional pathToPhysical / physicalToPath maps.
-   */
-  private _classifyFields;
-  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
-  private _flattenedPrefix;
-  /**
-   * Indexes `fieldDescriptors` into two lookup maps for unified
-   * read/write field classification in the RelationalFieldMapper.
-   */
-  private _buildLeafIndexes;
-  /**
-   * Builds field descriptors, physical-name lookup, and value formatters.
-   * Called once during build() — everything it needs
-   * (flatMap, indexes, columnMap, etc.) is already populated.
-   */
-  private _buildFieldDescriptors;
-  /**
-   * Resolves `fkTargetField` for FK fields in field descriptors.
-   */
-  private _resolveFkTargetFields;
-  private _finalizeIndexes;
-}
-//#endregion
 //#region src/base-adapter.d.ts
 /**
  * Abstract base class for database adapters.
@@ -1106,6 +1107,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
   /** Ensures metadata is built. Called before any metadata access. */
   protected _ensureBuilt(): void;
+  /**
+   * Built table metadata. Triggers a lazy build on first access — safe to call
+   * from peer tables that need this one's relations / nav fields before any
+   * operation has run against it directly.
+   */
+  getMetadata(): TableMetadata;
   protected _ensureSearchable(): void;
   /** Whether this readable is a view (overridden in AtscriptDbView). */
   get isView(): boolean;
@@ -1280,4 +1287,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TValueFormatterPair as $, TDbForeignKey as A, TExistingColumn as B, TCascadeTarget as C, TDbDefaultValue as D, TDbDefaultFn as E, TDbInsertResult as F, TIdDescriptor as G, TFieldMeta as H, TDbReferentialAction as I, TRelationInfo as J, TMetaResponse as K, TDbRelation as L, TDbIndexField as M, TDbIndexType as N, TDbDeleteResult as O, TDbInsertManyResult as P, TTableResolver as Q, TDbStorageType as R, TCascadeResolver as S, TDbCollation as T, TFkLookupResolver as U, TExistingTableOption as V, TFkLookupTarget as W, TSyncColumnResult as X, TSearchIndexInfo as Y, TTableOptionDiff as Z, DbQuery as _, FieldMappingStrategy as a, UniquSelect as at, NavPropsOf$1 as b, NoopLogger as c, AggregateExpr$1 as d, TWriteTableResolver as et, AggregateFn as f, DbControls as g, AtscriptDbWritable as h, DocumentFieldMapper as i, WithRelation$1 as it, TDbIndex as j, TDbFieldMeta as k, TGenericLogger as l, AggregateResult as m, DbResponse as n, Uniquery$1 as nt, BaseDbAdapter as o, AggregateQuery$1 as p, TMetadataOverrides as q, resolveDesignType as r, UniqueryControls$1 as rt, TableMetadata as s, AtscriptDbReadable as t, TypedWithRelation as tt, AggregateControls as u, FieldOpsFor as v, TColumnDiff as w, OwnPropsOf$1 as x, FilterExpr$1 as y, TDbUpdateResult as z };
+export { Uniquery$1 as $, TDbIndexType as A, TFkLookupResolver as B, TDbDefaultFn as C, TDbForeignKey as D, TDbFieldMeta as E, TDbStorageType as F, TRelationInfo as G, TIdDescriptor as H, TDbUpdateResult as I, TTableOptionDiff as J, TSearchIndexInfo as K, TExistingColumn as L, TDbInsertResult as M, TDbReferentialAction as N, TDbIndex as O, TDbRelation as P, TypedWithRelation as Q, TExistingTableOption as R, TDbCollation as S, TDbDeleteResult as T, TMetaResponse as U, TFkLookupTarget as V, TMetadataOverrides as W, TValueFormatterPair as X, TTableResolver as Y, TWriteTableResolver as Z, NavPropsOf$1 as _, FieldMappingStrategy as a, UniquSelect as at, TCascadeTarget as b, AggregateExpr$1 as c, AggregateResult as d, UniqueryControls$1 as et, AtscriptDbWritable as f, FilterExpr$1 as g, FieldOpsFor as h, DocumentFieldMapper as i, TGenericLogger as it, TDbInsertManyResult as j, TDbIndexField as k, AggregateFn as l, DbQuery as m, DbResponse as n, TableMetadata as nt, BaseDbAdapter as o, DbControls as p, TSyncColumnResult as q, resolveDesignType as r, NoopLogger as rt, AggregateControls as s, AtscriptDbReadable as t, WithRelation$1 as tt, AggregateQuery$1 as u, OwnPropsOf$1 as v, TDbDefaultValue as w, TColumnDiff as x, TCascadeResolver as y, TFieldMeta as z };

package/dist/{db-space-DB0MT6B3.d.cts → db-space-BqVLHVq7.d.cts}

@@ -1,4 +1,4 @@
-import { F as TDbInsertResult, O as TDbDeleteResult, P as TDbInsertManyResult, Q as TTableResolver, S as TCascadeResolver, U as TFkLookupResolver, et as TWriteTableResolver, l as TGenericLogger, o as BaseDbAdapter, s as TableMetadata, t as AtscriptDbReadable, z as TDbUpdateResult } from "./db-readable-ktHqF277.cjs";
+import { B as TFkLookupResolver, I as TDbUpdateResult, M as TDbInsertResult, T as TDbDeleteResult, Y as TTableResolver, Z as TWriteTableResolver, it as TGenericLogger, j as TDbInsertManyResult, nt as TableMetadata, o as BaseDbAdapter, t as AtscriptDbReadable, y as TCascadeResolver } from "./db-readable-DtrC0BGF.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";
 
@@ -29,6 +29,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
   protected _fkLookupResolver?: TFkLookupResolver;
   protected readonly _integrity: IntegrityStrategy;
   protected readonly validators: Map<string, Validator<T, DataType>>;
+  private _fromDepthMap?;
   constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver, _writeTableResolver?: TWriteTableResolver);
   /**
    * Sets the cascade resolver for application-level cascade deletes.
@@ -141,6 +142,18 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    */
   protected _extractRecordFilter(payload: Record<string, unknown>): FilterExpr;
   private _prepareFilterValue;
+  /**
+   * Lazy — builds a `normalized-path → from-depth` map from `this._meta.flatMap`
+   * on first use. Only paths reachable through an unbroken chain of `db.rel.from`
+   * nav fields from the root are included (chains crossing `to`/`via` are excluded).
+   */
+  private _getFromDepthMap;
+  /**
+   * Populate the depth-limit bundle on a `DbValidationContext`. Only the root
+   * write call (`depth === 0`) enforces — nested re-entries leave `depthCheck`
+   * unset so the full tree is validated once at the root.
+   */
+  private _applyDepthCtx;
   /**
    * Pre-validate items (type validation + FK constraints) without inserting them.
    * Used by parent tables to validate FROM children before the main insert,