@atscript/db 0.1.134 → 0.1.136

package/dist/{buckets-Bys2QXyk.d.mts → buckets-y4EzoX7D.d.mts}

@@ -1,6 +1,6 @@
 import { f as TFieldOps } from "./ops-AqhV7s9o.mjs";
 import { FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, 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, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, ResolvedBucket, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
+import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, ResolvedBucket, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 
 //#region src/query/uniqu-select.d.ts
 /**
@@ -15,7 +15,7 @@ import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, Agg
  * An array `$select` holds plain field names and computed entries —
  * aggregates (`{ $fn, $field }`, {@link aggregates}) and calendar buckets
  * (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
- * (`resolveCalendarBuckets` rejects any other shape before translation).
+ * (`normalizeComputedSelect` rejects any other shape before translation).
  */
 declare class UniquSelect {
   private static readonly UNRESOLVED;
@@ -101,7 +101,7 @@ declare abstract class FieldMappingStrategy {
    * equals a field name).
    *
    * `buckets` are the query's calendar buckets as the core's normalizer
-   * resolved them (`resolveCalendarBuckets` — `AtscriptDbReadable.aggregate`
+   * resolved them (`normalizeComputedSelect` — `AtscriptDbReadable.aggregate`
    * runs it before the guards); they reach adapters with `field` made
    * physical and the source descriptor as `fd`.
    */
@@ -111,7 +111,10 @@ declare abstract class FieldMappingStrategy {
   /**
    * `$select` with its field paths made physical: array-form names and
    * computed `$field`s (`'*'` kept), or the keys of the object
-   * (inclusion / exclusion) form.
+   * (inclusion / exclusion) form. An aggregate's output alias is fixed
+   * (`$as`) from its LOGICAL field first, so a default alias never leaks a
+   * physical name (`sum(amount)` over `@db.column 'amount_cents'` stays
+   * `sum_amount`); a bucket's alias is already resolved.
    */
   protected physicalSelect(select: NonNullable<UniqueryControls["$select"]>, meta: TableMetadata): NonNullable<UniqueryControls["$select"]>;
   /** `$sort` with physical keys; computed `aliases` (grouped queries) pass through. */
@@ -478,13 +481,15 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    *
    * Validates:
    * - `$select` computed entries and calendar buckets (the shared normalizer,
-   *   `resolveCalendarBuckets`: shapes, unit, zone, alias, grouping)
+   *   `normalizeComputedSelect`: shapes, unit, zone, alias, grouping)
    * - Plain fields in $select are a subset of $groupBy
    * - When dimensions/measures are defined (strict mode): $groupBy fields
-   *   must be dimensions, aggregate $field values must be measures (or '*')
+   *   must be dimensions, aggregate $field values must be measures (or '*';
+   *   a `countDistinct` field may also be a dimension)
    * - the path guard (a bucket source must pass `bucketSourceVerdict` —
    *   timestamp type, no JSON ancestor, a dimension in strict mode, an
-   *   adapter with calendar buckets) and the adapter's calendar-bucket units
+   *   adapter with calendar buckets), the adapter's aggregate functions
+   *   (`AGG_FN_NOT_SUPPORTED`) and calendar-bucket units
    *   (`BUCKET_NOT_SUPPORTED`)
    *
    * Translates field names, delegates to adapter.aggregate(),
@@ -497,6 +502,8 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   canFilterField(fd: TDbFieldMeta): boolean;
   /** Calendar-bucket units the adapter can group by (proxies adapter capability; empty = none). */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
+  /** Aggregate functions the adapter renders (proxies adapter capability). @since 0.1.136 */
+  aggregateFns(): ReadonlySet<AggregateFn>;
   /** Whether the adapter can sort by a given field (proxies adapter capability). */
   canSortField(fd: TDbFieldMeta): boolean;
   /** Returns available search indexes from the adapter. */
@@ -799,6 +806,18 @@ declare abstract class BaseDbAdapter {
    * out-of-range source, uniqu's `bucketLabel` semantics). Since 0.1.132.
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
+  /**
+   * Aggregate functions (`{ $fn, $field }` in an aggregate `$select`) this
+   * adapter renders. The default is `sum`, `count`, `avg`, `min` and `max`;
+   * an adapter that also implements `countDistinct` (distinct non-null
+   * values) returns `ALL_AGGREGATE_FNS`. The core rejects a known function
+   * missing from this set with `AGG_FN_NOT_SUPPORTED` before dispatch, so
+   * `aggregate()` only ever receives functions listed here; moost-db's
+   * `/meta` advertises the set as `aggregateFns`.
+   *
+   * @since 0.1.136
+   */
+  aggregateFns(): ReadonlySet<AggregateFn>;
   /**
    * Whether this adapter enforces foreign key constraints natively.
    * When `true`, the generic layer skips application-level cascade/setNull
@@ -1468,8 +1487,6 @@ declare class TableMetadata {
    * 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;
   /** Nearest `@db.encrypted` ancestor of `path` (exclusive), or `undefined`. */
   /**
    * Indexes non-ignored descriptors by logical path and retains the JSON-parent
@@ -1619,6 +1636,14 @@ interface TMetaResponse {
    * none. Since 0.1.132.
    */
   bucketUnits?: BucketUnit[];
+  /**
+   * Aggregate functions the adapter renders (`{ $fn }` in an aggregate
+   * `$select`, URL `sum(field)` / `countDistinct(field)` …) — see
+   * `BaseDbAdapter.aggregateFns()`.
+   *
+   * @since 0.1.136
+   */
+  aggregateFns?: AggregateFn[];
 }
 /** Where the action applies on the UI. */
 type TDbActionLevel = "table" | "row" | "rows";
@@ -1684,12 +1709,24 @@ interface TDbActionInfo {
   disabled?: string;
   /**
    * Name of the `.as` interface the action's `@InputForm()` parameter expects
-   * (the compiled class's `.name`). Present only when the handler declares an
-   * `@InputForm(FormType)` parameter. Clients fetch the serialized schema via
-   * `GET /meta/form/:name` on the same controller and render a form to
-   * collect the `input` field of the action's request envelope.
+   * (the compiled class's `.name`). Present for an `@InputForm(FormType)`
+   * parameter or a class-level `inputForm` entry. Clients fetch the
+   * serialized schema via `GET /meta/form/:name` on the same controller and
+   * render a form to collect the `input` field of the action's request
+   * envelope. A class-level entry may name a form served elsewhere — then
+   * {@link formUrl} is present and clients fetch it instead of `meta/form/:name`.
    */
   inputForm?: string;
+  /**
+   * Server-absolute path of the serialized form schema —
+   * same convention as `value` for `'backend'` actions: clients prefix
+   * their base URL. Present only together with {@link inputForm}, when the
+   * form is served by another endpoint than this controller's
+   * `meta/form/:name`; clients fetch it instead of the relative route.
+   *
+   * @since 0.1.136
+   */
+  formUrl?: string;
 }
 interface TDbInsertResult {
   insertedId: unknown;
@@ -2217,13 +2254,15 @@ interface TBucketFieldSource {
   navFields: ReadonlySet<string>;
 }
 /**
- * The one normalizer of `$select` computed entries (since 0.1.132) — uniqu's
+ * The one normalizer of `$select` computed entries — uniqu's
  * `resolveBuckets` (entry shapes, unit, time zone canonicalization, week
  * start, alias syntax and uniqueness, "grouped queries only", "must also
  * appear in $groupBy", string `$groupBy` entries) with the table's names as
  * the collision set: a bucket alias may not equal a logical path, a physical
  * column or a navigation field, so a label is never reverse-mapped as a
- * column.
+ * column. Aggregate entries are checked against `SUPPORTED_AGGREGATE_FNS`
+ * (and `'*'` is `count`'s only); whether the adapter renders a function is
+ * `guardAggregate`'s (`aggregateFns()` → `AGG_FN_NOT_SUPPORTED`).
  *
  * Which layer validates what:
  * - **Shapes** (this normalizer) run FIRST at every entry point — the core's
@@ -2245,10 +2284,15 @@ interface TBucketFieldSource {
  *
  * @throws DbError `INVALID_QUERY` carrying every issue (`path` `$select` / `$groupBy`).
  */
-declare function resolveCalendarBuckets(controls: {
+declare function normalizeComputedSelect(controls: {
   $select?: unknown;
   $groupBy?: unknown;
 } | undefined, fields: TBucketFieldSource, aggregate?: boolean): ResolvedBucket[];
+/**
+ * @deprecated since 0.1.136 — renamed {@link normalizeComputedSelect} (it
+ * normalizes every computed `$select` entry, aggregates included).
+ */
+declare const resolveCalendarBuckets: typeof normalizeComputedSelect;
 /**
  * Whether a field's TYPE allows it to be the source of a calendar bucket: a
  * `number` / `integer` leaf carrying the `timestamp` tag
@@ -2274,4 +2318,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbWriteGuardContext as $, TDbActionIntent as A, isGeoIndexableType as At, TDbIndexField as B, FieldMappingStrategy as Bt, PrimaryKeyOf$1 as C, TWriteTableResolver as Ct, TCrudOp as D, WithRelation$1 as Dt, TColumnDiff as E, UniqueryControls$1 as Et, TDbDefaultValue as F, DbResponse as Ft, TDbReferentialAction as G, TDbInsertManyResult as H, TGenericLogger as Ht, TDbDeleteResult as I, resolveDesignType as It, TDbRemoveGuardContext as J, TDbRelation as K, TDbFieldMeta as L, DbEncryption as Lt, TDbActionProcessor as M, ALL_BUCKET_UNITS as Mt, TDbCollation as N, BaseDbAdapter as Nt, TCrudPermissions as O, TableMetadata as Ot, TDbDefaultFn as P, AtscriptDbReadable as Pt, TDbWriteGuard as Q, TDbForeignKey as R, TDbEncryptionOptions as Rt, OwnPropsOf$1 as S, TWriteOptions as St, TCascadeTarget as T, Uniquery$1 as Tt, TDbInsertResult as U, UniquSelect as Ut, TDbIndexType as V, NoopLogger as Vt, TDbObjectKind as W, TDbUpdateResult as X, TDbStorageType as Y, TDbWriteAction as Z, FieldOpsFor as _, TSyncColumnResult as _t, jsonValueAncestor as a, TFieldMeta as at, NavPropsOf$1 as b, TTouchManyOptions as bt, AggregateExpr$1 as c, TIdDescriptor as ct, AggregateResult as d, TMetaResponse as dt, TDeleteOptions as et, AtscriptDbWritable as f, TMetadataOverrides as ft, DbRow as g, TSearchIndexInfo as gt, DbQuery as h, TRelationInfo as ht, isJsonValueField as i, TExistingTableOption as it, TDbActionLevel as j, isGeoPointType as jt, TDbActionInfo as k, findAncestorInSet as kt, AggregateFn as l, TIdResolveOptions as lt, DbPatch as m, TReferencingForeignKey as mt, TResolvedBucket as n, TExistingColumn as nt, resolveCalendarBuckets as o, TFkLookupResolver as ot, DbControls as p, TPrimaryKeyChange as pt, TDbRemoveGuard as q, isBucketableField as r, TExistingForeignKey as rt, AggregateControls as s, TFkLookupTarget as st, TBucketFieldSource as t, TEnsureTableOptions as tt, AggregateQuery$1 as u, TIdentification as ut, FilterExpr$1 as v, TTableOptionDiff as vt, TCascadeResolver as w, TypedWithRelation as wt, NullableOptional as x, TValueFormatterPair as xt, FlatOf$1 as y, TTableResolver as yt, TDbIndex as z, DocumentFieldMapper as zt };
+export { TDbWriteGuard as $, TDbActionInfo as A, findAncestorInSet as At, TDbIndex as B, DocumentFieldMapper as Bt, OwnPropsOf$1 as C, TWriteOptions as Ct, TColumnDiff as D, UniqueryControls$1 as Dt, TCascadeTarget as E, Uniquery$1 as Et, TDbDefaultFn as F, AtscriptDbReadable as Ft, TDbObjectKind as G, TDbIndexType as H, NoopLogger as Ht, TDbDefaultValue as I, DbResponse as It, TDbRemoveGuard as J, TDbReferentialAction as K, TDbDeleteResult as L, resolveDesignType as Lt, TDbActionLevel as M, isGeoPointType as Mt, TDbActionProcessor as N, ALL_BUCKET_UNITS as Nt, TCrudOp as O, WithRelation$1 as Ot, TDbCollation as P, BaseDbAdapter as Pt, TDbWriteAction as Q, TDbFieldMeta as R, DbEncryption as Rt, NullableOptional as S, TValueFormatterPair as St, TCascadeResolver as T, TypedWithRelation as Tt, TDbInsertManyResult as U, TGenericLogger as Ut, TDbIndexField as V, FieldMappingStrategy as Vt, TDbInsertResult as W, UniquSelect as Wt, TDbStorageType as X, TDbRemoveGuardContext as Y, TDbUpdateResult as Z, DbRow as _, TSearchIndexInfo as _t, jsonValueAncestor as a, TExistingTableOption as at, FlatOf$1 as b, TTableResolver as bt, AggregateControls as c, TFkLookupTarget as ct, AggregateQuery$1 as d, TIdentification as dt, TDbWriteGuardContext as et, AggregateResult as f, TMetaResponse as ft, DbQuery as g, TRelationInfo as gt, DbPatch as h, TReferencingForeignKey as ht, isJsonValueField as i, TExistingForeignKey as it, TDbActionIntent as j, isGeoIndexableType as jt, TCrudPermissions as k, TableMetadata as kt, AggregateExpr$1 as l, TIdDescriptor as lt, DbControls as m, TPrimaryKeyChange as mt, TResolvedBucket as n, TEnsureTableOptions as nt, normalizeComputedSelect as o, TFieldMeta as ot, AtscriptDbWritable as p, TMetadataOverrides as pt, TDbRelation as q, isBucketableField as r, TExistingColumn as rt, resolveCalendarBuckets as s, TFkLookupResolver as st, TBucketFieldSource as t, TDeleteOptions as tt, AggregateFn$1 as u, TIdResolveOptions as ut, FieldOpsFor as v, TSyncColumnResult as vt, PrimaryKeyOf$1 as w, TWriteTableResolver as wt, NavPropsOf$1 as x, TTouchManyOptions as xt, FilterExpr$1 as y, TTableOptionDiff as yt, TDbForeignKey as z, TDbEncryptionOptions as zt };

package/dist/{db-space-DtGx5HIC.d.cts → db-space-BX4K3vb6.d.mts}

@@ -1,6 +1,6 @@
-import { Ct as TWriteTableResolver, H as TDbInsertManyResult, Ht as TGenericLogger, I as TDbDeleteResult, Lt as DbEncryption, Nt as BaseDbAdapter, Ot as TableMetadata, Pt as AtscriptDbReadable, Rt as TDbEncryptionOptions, St as TWriteOptions, U as TDbInsertResult, X as TDbUpdateResult, bt as TTouchManyOptions, et as TDeleteOptions, g as DbRow, lt as TIdResolveOptions, m as DbPatch, mt as TReferencingForeignKey, ot as TFkLookupResolver, w as TCascadeResolver, x as NullableOptional, yt as TTableResolver } from "./buckets-Bo2IcPZ_.cjs";
-import { FilterExpr } from "@uniqu/core";
+import { Ct as TWriteOptions, Ft as AtscriptDbReadable, L as TDbDeleteResult, Pt as BaseDbAdapter, Rt as DbEncryption, S as NullableOptional, T as TCascadeResolver, U as TDbInsertManyResult, Ut as TGenericLogger, W as TDbInsertResult, Z as TDbUpdateResult, _ as DbRow, bt as TTableResolver, h as DbPatch, ht as TReferencingForeignKey, kt as TableMetadata, st as TFkLookupResolver, tt as TDeleteOptions, ut as TIdResolveOptions, wt as TWriteTableResolver, xt as TTouchManyOptions, zt as TDbEncryptionOptions } from "./buckets-y4EzoX7D.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";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -241,11 +241,23 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
 }
 //#endregion
 //#region src/query/query-tree.d.ts
+/**
+ * `true` when a query-tree operand is a field reference (`{ field, type? }`)
+ * rather than a literal — e.g. the right side of a field-to-field comparison.
+ * @since 0.1.136
+ */
+declare function isFieldRef(value: unknown): value is AtscriptQueryFieldRef;
 /** A single join in a view query plan. */
 interface TViewJoin {
   targetType: () => TAtscriptAnnotatedType;
   targetTable: string;
   condition: AtscriptQueryNode;
+  /**
+   * `inner` (default) drops entry rows without a match; `left` keeps them
+   * with the target's columns as NULL. Joins apply in declaration order.
+   * @since 0.1.136
+   */
+  kind: "inner" | "left";
 }
 /** Resolved view query plan produced by AtscriptDbView. */
 interface TViewPlan {
@@ -263,15 +275,84 @@ interface TViewPlan {
  */
 declare function translateQueryTree(node: AtscriptQueryNode, resolveField: (ref: AtscriptQueryFieldRef) => string): FilterExpr;
 //#endregion
+//#region src/table/view-source.d.ts
+/**
+ * Where a view reads one logical source path from, in PHYSICAL terms.
+ *
+ * Produced by {@link resolveViewSource} — a pure function of the source
+ * table's annotated type that lays the table out with `TableMetadata`'s
+ * rules (flattened `__` columns, `@db.column` renames, `@db.json` / array
+ * JSON columns, document paths on nested-object adapters).
+ * @since 0.1.136
+ */
+interface TViewSource {
+  /**
+   * Physical column (relational) or document path (nested-object adapters).
+   * For a path inside a JSON column this is the JSON column; for a flattened
+   * object it is the object's `__` prefix (no such column exists — its leaves do).
+   */
+  column: string;
+  /** Segments inside {@link column} when the path descends into a JSON column (relational only). */
+  jsonPath?: string[];
+  /** Design type of the addressed node (`string`, `number`, `object`, `array`, …; `unknown` when undeclared). */
+  designType: string;
+  /** Set for a relational object stored as one column per leaf. */
+  flattened?: true;
+  /**
+   * `true` when the value may be absent: the path or an ancestor segment is
+   * optional, or it reads inside a JSON-stored value.
+   */
+  optional: boolean;
+}
+//#endregion
 //#region src/table/db-view.d.ts
+/** Primitive result type of a JSON-leaf extraction. */
+type TViewJsonType = "string" | "number" | "boolean";
 interface TViewColumnMapping {
+  /**
+   * The view's own physical column — its `@db.column` / flattened `__` name
+   * on relational adapters, its document key on nested-object adapters.
+   */
   viewColumn: string;
+  /**
+   * Logical view field path (`address.city` for a flattened object leaf) —
+   * how `@db.view.having` refers to the column.
+   * @since 0.1.136
+   */
+  viewPath: string;
   sourceTable: string;
+  /** Physical source column (or document path). `"*"` for `COUNT(*)`. */
   sourceColumn: string;
-  /** Aggregate function name ('sum'|'avg'|'count'|'min'|'max') if this is an aggregate column. */
+  /**
+   * Set when the source value may be missing for some row: an optional
+   * source field, a leaf inside a JSON-stored value, an undeclared path, or a
+   * column of a left-joined table. Document adapters coalesce such a source
+   * to `null`; a required source is read as a plain path (index-friendly).
+   * @since 0.1.136
+   */
+  nullable?: true;
+  /**
+   * Set when the source is a primitive leaf inside a JSON column
+   * ({@link sourceColumn}): the path within it and the leaf's declared type.
+   * @since 0.1.136
+   */
+  json?: {
+    path: string[];
+    type: TViewJsonType;
+  };
+  /**
+   * Aggregate function name (`sum` | `avg` | `count` | `countDistinct` |
+   * `min` | `max`) if this is an aggregate column.
+   */
   aggFn?: string;
   /** Source field for the aggregate function ('*' for COUNT(*)). */
   aggField?: string;
+  /**
+   * Row predicate of a conditional aggregate — the `@db.agg.*` 2nd argument:
+   * only rows where it holds are aggregated. Refs resolve like
+   * `@db.view.filter` (entry table + joins). @since 0.1.136
+   */
+  aggFilter?: AtscriptQueryNode;
 }
 /**
  * Database view abstraction driven by Atscript `@db.view.*` annotations.
@@ -288,6 +369,7 @@ interface TViewColumnMapping {
  */
 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?;
+  private _columnMappings?;
   get isView(): boolean;
   /**
    * Whether this is an external view — declared with `@db.view` only,
@@ -304,19 +386,56 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    * - `db.view.materialized` → boolean (optional)
    */
   get viewPlan(): TViewPlan;
-  /**
-   * Resolves a query field ref to a quoted `table.column` SQL fragment.
+  /** Whether the adapter stores nested objects natively (document paths, no JSON columns). */
+  private get _nested();
+  /**
+   * Resolves a view query field ref (join condition, `@db.view.filter`,
+   * conditional-aggregate predicate) to its table name and PHYSICAL source on
+   * this view's adapter — the column (or document path) with `TableMetadata`'s
+   * layout rules, the path inside a JSON column, and whether the value may be
+   * absent. An unqualified ref resolves against the entry table.
+   * @throws for a ref without storage (`@db.ignore`, navigation relation) or
+   *   inside an `@db.encrypted` field (relational adapters).
+   * @since 0.1.136
+   */
+  resolveRefSource(ref: AtscriptQueryFieldRef): {
+    table: string;
+    source: TViewSource;
+  };
+  /**
+   * Resolves a query field ref (join condition, `@db.view.filter`) to a
+   * quoted `table.column` SQL fragment — the PHYSICAL column (flattened
+   * `__` name, `@db.column` rename). An unqualified ref
+   * resolves against the entry table.
    *
    * @param ref - The field reference from the query tree.
    * @param qi - Identifier quoting function (e.g. backtick for MySQL, double-quote for SQLite).
    *             Defaults to double-quote wrapping for backwards compatibility.
+   * @throws when the ref reads inside a JSON column (not supported in view conditions).
    */
   resolveFieldRef(ref: AtscriptQueryFieldRef, qi?: (name: string) => string): string;
   /**
-   * Maps each view field to its source table and column via ref chain.
-   * Fields without refs (inline definitions) map to the entry table with the same name.
+   * Maps each view column to its source table and PHYSICAL source column.
+   *
+   * View fields resolve through their chain ref; fields without a ref read
+   * the entry table under the same name; aggregates read their `@db.agg.*`
+   * field from the entry table (or their ref). Source names are
+   * physical (flattened `__` names, `@db.column`, document paths), `viewColumn`
+   * is the view's own physical name, an object field whose source is a
+   * flattened object expands to one mapping per leaf, and a primitive leaf
+   * inside a JSON column carries `json` (rendered by adapters that support
+   * JSON extraction).
+   *
+   * Computed once per view (the plan and the type are immutable).
+   *
+   * @throws for an object field over a JSON column without `@db.json` on the
+   *   view field, a JSON leaf that is not a string / number / boolean, or an
+   *   aggregate other than `count` over `'*'`.
    */
   getViewColumnMappings(): TViewColumnMapping[];
+  private _buildColumnMappings;
+  /** One view column over one physical source (a column or a JSON leaf). */
+  private _leafMapping;
 }
 /**
  * Structural type guard for views: `true` when the readable reports
@@ -436,4 +555,4 @@ declare class DbSpace {
   private _getFkLookupTarget;
 }
 //#endregion
-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 };
+export { IntegrityStrategy as _, TViewColumnMapping as a, AtscriptQueryComparison as c, AtscriptRef as d, TViewJoin as f, AtscriptDbTable as g, translateQueryTree as h, AtscriptDbView as i, AtscriptQueryFieldRef$1 as l, isFieldRef as m, TAdapterFactory as n, TViewJsonType as o, TViewPlan as p, TDbSpaceOptions as r, isAtscriptDbView as s, DbSpace as t, AtscriptQueryNode$1 as u, NativeIntegrity as v };

package/dist/{db-space-grfuZcPR.d.mts → db-space-ClG41vJh.d.cts}

@@ -1,6 +1,6 @@
-import { Ct as TWriteTableResolver, H as TDbInsertManyResult, Ht as TGenericLogger, I as TDbDeleteResult, Lt as DbEncryption, Nt as BaseDbAdapter, Ot as TableMetadata, Pt as AtscriptDbReadable, Rt as TDbEncryptionOptions, St as TWriteOptions, U as TDbInsertResult, X as TDbUpdateResult, bt as TTouchManyOptions, et as TDeleteOptions, g as DbRow, lt as TIdResolveOptions, m as DbPatch, mt as TReferencingForeignKey, ot as TFkLookupResolver, w as TCascadeResolver, x as NullableOptional, yt as TTableResolver } from "./buckets-Bys2QXyk.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 { Ct as TWriteOptions, Ft as AtscriptDbReadable, L as TDbDeleteResult, Pt as BaseDbAdapter, Rt as DbEncryption, S as NullableOptional, T as TCascadeResolver, U as TDbInsertManyResult, Ut as TGenericLogger, W as TDbInsertResult, Z as TDbUpdateResult, _ as DbRow, bt as TTableResolver, h as DbPatch, ht as TReferencingForeignKey, kt as TableMetadata, st as TFkLookupResolver, tt as TDeleteOptions, ut as TIdResolveOptions, wt as TWriteTableResolver, xt as TTouchManyOptions, zt as TDbEncryptionOptions } from "./buckets-kKY0RKYN.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";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -241,11 +241,23 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
 }
 //#endregion
 //#region src/query/query-tree.d.ts
+/**
+ * `true` when a query-tree operand is a field reference (`{ field, type? }`)
+ * rather than a literal — e.g. the right side of a field-to-field comparison.
+ * @since 0.1.136
+ */
+declare function isFieldRef(value: unknown): value is AtscriptQueryFieldRef;
 /** A single join in a view query plan. */
 interface TViewJoin {
   targetType: () => TAtscriptAnnotatedType;
   targetTable: string;
   condition: AtscriptQueryNode;
+  /**
+   * `inner` (default) drops entry rows without a match; `left` keeps them
+   * with the target's columns as NULL. Joins apply in declaration order.
+   * @since 0.1.136
+   */
+  kind: "inner" | "left";
 }
 /** Resolved view query plan produced by AtscriptDbView. */
 interface TViewPlan {
@@ -263,15 +275,84 @@ interface TViewPlan {
  */
 declare function translateQueryTree(node: AtscriptQueryNode, resolveField: (ref: AtscriptQueryFieldRef) => string): FilterExpr;
 //#endregion
+//#region src/table/view-source.d.ts
+/**
+ * Where a view reads one logical source path from, in PHYSICAL terms.
+ *
+ * Produced by {@link resolveViewSource} — a pure function of the source
+ * table's annotated type that lays the table out with `TableMetadata`'s
+ * rules (flattened `__` columns, `@db.column` renames, `@db.json` / array
+ * JSON columns, document paths on nested-object adapters).
+ * @since 0.1.136
+ */
+interface TViewSource {
+  /**
+   * Physical column (relational) or document path (nested-object adapters).
+   * For a path inside a JSON column this is the JSON column; for a flattened
+   * object it is the object's `__` prefix (no such column exists — its leaves do).
+   */
+  column: string;
+  /** Segments inside {@link column} when the path descends into a JSON column (relational only). */
+  jsonPath?: string[];
+  /** Design type of the addressed node (`string`, `number`, `object`, `array`, …; `unknown` when undeclared). */
+  designType: string;
+  /** Set for a relational object stored as one column per leaf. */
+  flattened?: true;
+  /**
+   * `true` when the value may be absent: the path or an ancestor segment is
+   * optional, or it reads inside a JSON-stored value.
+   */
+  optional: boolean;
+}
+//#endregion
 //#region src/table/db-view.d.ts
+/** Primitive result type of a JSON-leaf extraction. */
+type TViewJsonType = "string" | "number" | "boolean";
 interface TViewColumnMapping {
+  /**
+   * The view's own physical column — its `@db.column` / flattened `__` name
+   * on relational adapters, its document key on nested-object adapters.
+   */
   viewColumn: string;
+  /**
+   * Logical view field path (`address.city` for a flattened object leaf) —
+   * how `@db.view.having` refers to the column.
+   * @since 0.1.136
+   */
+  viewPath: string;
   sourceTable: string;
+  /** Physical source column (or document path). `"*"` for `COUNT(*)`. */
   sourceColumn: string;
-  /** Aggregate function name ('sum'|'avg'|'count'|'min'|'max') if this is an aggregate column. */
+  /**
+   * Set when the source value may be missing for some row: an optional
+   * source field, a leaf inside a JSON-stored value, an undeclared path, or a
+   * column of a left-joined table. Document adapters coalesce such a source
+   * to `null`; a required source is read as a plain path (index-friendly).
+   * @since 0.1.136
+   */
+  nullable?: true;
+  /**
+   * Set when the source is a primitive leaf inside a JSON column
+   * ({@link sourceColumn}): the path within it and the leaf's declared type.
+   * @since 0.1.136
+   */
+  json?: {
+    path: string[];
+    type: TViewJsonType;
+  };
+  /**
+   * Aggregate function name (`sum` | `avg` | `count` | `countDistinct` |
+   * `min` | `max`) if this is an aggregate column.
+   */
   aggFn?: string;
   /** Source field for the aggregate function ('*' for COUNT(*)). */
   aggField?: string;
+  /**
+   * Row predicate of a conditional aggregate — the `@db.agg.*` 2nd argument:
+   * only rows where it holds are aggregated. Refs resolve like
+   * `@db.view.filter` (entry table + joins). @since 0.1.136
+   */
+  aggFilter?: AtscriptQueryNode;
 }
 /**
  * Database view abstraction driven by Atscript `@db.view.*` annotations.
@@ -288,6 +369,7 @@ interface TViewColumnMapping {
  */
 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?;
+  private _columnMappings?;
   get isView(): boolean;
   /**
    * Whether this is an external view — declared with `@db.view` only,
@@ -304,19 +386,56 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    * - `db.view.materialized` → boolean (optional)
    */
   get viewPlan(): TViewPlan;
-  /**
-   * Resolves a query field ref to a quoted `table.column` SQL fragment.
+  /** Whether the adapter stores nested objects natively (document paths, no JSON columns). */
+  private get _nested();
+  /**
+   * Resolves a view query field ref (join condition, `@db.view.filter`,
+   * conditional-aggregate predicate) to its table name and PHYSICAL source on
+   * this view's adapter — the column (or document path) with `TableMetadata`'s
+   * layout rules, the path inside a JSON column, and whether the value may be
+   * absent. An unqualified ref resolves against the entry table.
+   * @throws for a ref without storage (`@db.ignore`, navigation relation) or
+   *   inside an `@db.encrypted` field (relational adapters).
+   * @since 0.1.136
+   */
+  resolveRefSource(ref: AtscriptQueryFieldRef): {
+    table: string;
+    source: TViewSource;
+  };
+  /**
+   * Resolves a query field ref (join condition, `@db.view.filter`) to a
+   * quoted `table.column` SQL fragment — the PHYSICAL column (flattened
+   * `__` name, `@db.column` rename). An unqualified ref
+   * resolves against the entry table.
    *
    * @param ref - The field reference from the query tree.
    * @param qi - Identifier quoting function (e.g. backtick for MySQL, double-quote for SQLite).
    *             Defaults to double-quote wrapping for backwards compatibility.
+   * @throws when the ref reads inside a JSON column (not supported in view conditions).
    */
   resolveFieldRef(ref: AtscriptQueryFieldRef, qi?: (name: string) => string): string;
   /**
-   * Maps each view field to its source table and column via ref chain.
-   * Fields without refs (inline definitions) map to the entry table with the same name.
+   * Maps each view column to its source table and PHYSICAL source column.
+   *
+   * View fields resolve through their chain ref; fields without a ref read
+   * the entry table under the same name; aggregates read their `@db.agg.*`
+   * field from the entry table (or their ref). Source names are
+   * physical (flattened `__` names, `@db.column`, document paths), `viewColumn`
+   * is the view's own physical name, an object field whose source is a
+   * flattened object expands to one mapping per leaf, and a primitive leaf
+   * inside a JSON column carries `json` (rendered by adapters that support
+   * JSON extraction).
+   *
+   * Computed once per view (the plan and the type are immutable).
+   *
+   * @throws for an object field over a JSON column without `@db.json` on the
+   *   view field, a JSON leaf that is not a string / number / boolean, or an
+   *   aggregate other than `count` over `'*'`.
    */
   getViewColumnMappings(): TViewColumnMapping[];
+  private _buildColumnMappings;
+  /** One view column over one physical source (a column or a JSON leaf). */
+  private _leafMapping;
 }
 /**
  * Structural type guard for views: `true` when the readable reports
@@ -436,4 +555,4 @@ declare class DbSpace {
   private _getFkLookupTarget;
 }
 //#endregion
-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 };
+export { IntegrityStrategy as _, TViewColumnMapping as a, AtscriptQueryComparison as c, AtscriptRef as d, TViewJoin as f, AtscriptDbTable as g, translateQueryTree as h, AtscriptDbView as i, AtscriptQueryFieldRef$1 as l, isFieldRef as m, TAdapterFactory as n, TViewJsonType as o, TViewPlan as p, TDbSpaceOptions as r, isAtscriptDbView as s, DbSpace as t, AtscriptQueryNode$1 as u, NativeIntegrity as v };