@atscript/db 0.1.54 → 0.1.56

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-GBjlsJXR.d.mts → db-readable-B9Irll4q.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"> {
@@ -86,6 +200,34 @@ interface TMetaResponse {
   relations: TRelationInfo[];
   fields: Record<string, TFieldMeta>;
   type: TSerializedAnnotatedType;
+  actions: TDbActionInfo[];
+}
+/** Where the action applies on the UI. */
+type TDbActionLevel = "table" | "row" | "rows";
+/** Semantic intent the UI maps to its own visual language (color, prominence). */
+type TDbActionIntent = "positive" | "negative" | "primary" | "secondary";
+/** How the UI client should handle the action when invoked. */
+type TDbActionProcessor = "backend" | "navigate" | "custom";
+/**
+ * Single action descriptor in the `/meta` envelope. Flat shape — `processor`
+ * is a string discriminator; `value` is its sibling and is always populated.
+ *
+ * - `processor: 'backend'` — UI POSTs to `value` (full HTTP path).
+ * - `processor: 'navigate'` — UI routes to `value` (URL template; `$1` is the row PK).
+ * - `processor: 'custom'`  — UI dispatches `value` as an event name (defaults to action `name`).
+ */
+interface TDbActionInfo {
+  name: string;
+  label: string;
+  level: TDbActionLevel;
+  processor: TDbActionProcessor;
+  value: string;
+  icon?: string;
+  intent?: TDbActionIntent;
+  description?: string;
+  order?: number;
+  default?: boolean;
+  promptText?: string;
 }
 interface TDbInsertResult {
   insertedId: unknown;
@@ -290,6 +432,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 +518,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 +1135,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 +1315,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 { TTableResolver as $, TDbFieldMeta as A, TDbUpdateResult as B, TDbActionIntent as C, TDbDefaultFn as D, TDbCollation as E, TDbInsertManyResult as F, TFkLookupTarget as G, TExistingTableOption as H, TDbInsertResult as I, TMetadataOverrides as J, TIdDescriptor as K, TDbReferentialAction as L, TDbIndex as M, TDbIndexField as N, TDbDefaultValue as O, TDbIndexType as P, TTableOptionDiff as Q, TDbRelation as R, TDbActionInfo as S, TDbActionProcessor as T, TFieldMeta as U, TExistingColumn as V, TFkLookupResolver as W, TSearchIndexInfo as X, TRelationInfo as Y, TSyncColumnResult as Z, NavPropsOf$1 as _, FieldMappingStrategy as a, WithRelation$1 as at, TCascadeTarget as b, AggregateExpr$1 as c, TGenericLogger as ct, AggregateResult as d, TValueFormatterPair as et, AtscriptDbWritable as f, FilterExpr$1 as g, FieldOpsFor as h, DocumentFieldMapper as i, UniqueryControls$1 as it, TDbForeignKey as j, TDbDeleteResult as k, AggregateFn as l, UniquSelect as lt, DbQuery as m, DbResponse as n, TypedWithRelation as nt, BaseDbAdapter as o, TableMetadata as ot, DbControls as p, TMetaResponse as q, resolveDesignType as r, Uniquery$1 as rt, AggregateControls as s, NoopLogger as st, AtscriptDbReadable as t, TWriteTableResolver as tt, AggregateQuery$1 as u, OwnPropsOf$1 as v, TDbActionLevel as w, TColumnDiff as x, TCascadeResolver as y, TDbStorageType as z };