@atscript/utils-db 0.1.30 → 0.1.31

package/README.md

@@ -245,9 +245,29 @@ These `@db.*` annotations are defined in `@atscript/core` and processed by `Atsc
 | `@db.index.plain "name"` | Field | B-tree index (optional sort: `"name", "desc"`) |
 | `@db.index.unique "name"` | Field | Unique index |
 | `@db.index.fulltext "name"` | Field | Full-text search index |
+| `@db.json` | Field | Store as a single JSON column (skip flattening) |
 
 Multiple fields with the same index name form a **composite index**.
 
+## Type-Safe Queries with `__flat`
+
+Interfaces annotated with `@db.table` get a `__flat` static property in the generated `.d.ts` file, mapping all dot-notation paths to their value types. This enables autocomplete and type checking for filter expressions and `$select`/`$sort` operations.
+
+Use `FlatOf<T>` to extract the flat type:
+
+```typescript
+import type { FlatOf } from '@atscript/utils-db'
+
+type UserFlat = FlatOf<typeof User>
+// → { id: number; name: string; contact: never; "contact.email": string; ... }
+```
+
+`AtscriptDbTable` uses `FlatOf<T>` as the type parameter for query methods (`findOne`, `findMany`, `count`, `updateMany`, `replaceMany`, `deleteMany`), giving you autocomplete on filter keys and select paths. When `__flat` is not present (no `@db.table`), `FlatOf<T>` falls back to the regular data shape — fully backward-compatible.
+
+### `$select` Parent Path Expansion
+
+Selecting a parent object path (e.g., `$select: ['contact']`) automatically expands to all its leaf physical columns for relational databases. Sorting by parent paths is silently ignored.
+
 ## Cross-Cutting Concerns
 
 Since `AtscriptDbTable` is concrete, extend it for cross-cutting concerns that work with any adapter:
@@ -305,6 +325,7 @@ export { decomposePatch } from './patch-decomposer'
 export { getKeyProps } from './patch-types'
 
 // Types
+export type { FlatOf } from '@atscript/typescript/utils'
 export type {
   TDbFilter, TDbFindOptions,
   TDbInsertResult, TDbInsertManyResult, TDbUpdateResult, TDbDeleteResult,

package/dist/index.cjs

@@ -156,6 +156,14 @@ var AtscriptDbTable = class {
 		this._flatten();
 		return this._uniqueProps;
 	}
+	/** Precomputed logical dot-path → physical column name map. */ get pathToPhysical() {
+		this._flatten();
+		return this._pathToPhysical;
+	}
+	/** Precomputed physical column name → logical dot-path map (inverse). */ get physicalToPath() {
+		this._flatten();
+		return this._physicalToPath;
+	}
 	/** Descriptor for the primary ID field(s). */ getIdDescriptor() {
 		this._flatten();
 		return {
@@ -171,17 +179,31 @@ var AtscriptDbTable = class {
 		this._flatten();
 		if (!this._fieldDescriptors) {
 			this._fieldDescriptors = [];
+			const skipFlattening = this.adapter.supportsNestedObjects();
 			for (const [path, type] of this._flatMap.entries()) {
 				if (!path) continue;
+				if (!skipFlattening && this._flattenedParents.has(path)) continue;
+				if (!skipFlattening && this._findJsonParent(path) !== undefined) continue;
+				const isJson = this._jsonFields.has(path);
+				const isFlattened = !skipFlattening && this._findFlattenedParent(path) !== undefined;
+				const designType = isJson ? "json" : resolveDesignType(type);
+				let storage;
+				if (skipFlattening) storage = "column";
+else if (isJson) storage = "json";
+else if (isFlattened) storage = "flattened";
+else storage = "column";
+				const physicalName = skipFlattening ? this._columnMap.get(path) ?? path : this._pathToPhysical.get(path) ?? this._columnMap.get(path) ?? path;
 				this._fieldDescriptors.push({
 					path,
 					type,
-					physicalName: this._columnMap.get(path) ?? path,
-					designType: resolveDesignType(type),
+					physicalName,
+					designType,
 					optional: type.optional === true,
 					isPrimaryKey: this._primaryKeys.includes(path),
 					ignored: this._ignoredFields.has(path),
-					defaultValue: this._defaults.get(path)
+					defaultValue: this._defaults.get(path),
+					storage,
+					flattenedFrom: isFlattened ? path : undefined
 				});
 			}
 		}
@@ -196,12 +218,19 @@ var AtscriptDbTable = class {
 	*/ resolveProjection(select) {
 		if (!select) return undefined;
 		if (Array.isArray(select)) return select.length > 0 ? select : undefined;
-		const entries = Object.entries(select);
-		if (entries.length === 0) return undefined;
-		const firstVal = entries[0][1];
-		if (firstVal === 1) return entries.filter(([, v]) => v === 1).map(([k]) => k);
-		const excluded = new Set(entries.filter(([, v]) => v === 0).map(([k]) => k));
-		return this.fieldDescriptors.filter((f) => !f.ignored && !excluded.has(f.path)).map((f) => f.path);
+		const selectObj = select;
+		const keys = Object.keys(selectObj);
+		if (keys.length === 0) return undefined;
+		if (selectObj[keys[0]] === 1) {
+			const result$1 = [];
+			for (const k of keys) if (selectObj[k] === 1) result$1.push(k);
+			return result$1;
+		}
+		const excluded = new Set();
+		for (const k of keys) if (selectObj[k] === 0) excluded.add(k);
+		const result = [];
+		for (const f of this.fieldDescriptors) if (!f.ignored && !excluded.has(f.path)) result.push(f.path);
+		return result;
 	}
 	/**
 	* Creates a new validator with custom options.
@@ -266,9 +295,9 @@ var AtscriptDbTable = class {
 		const validator = this.getValidator("patch");
 		if (!validator.validate(payload)) throw new Error("Validation failed for update");
 		const filter = this._extractPrimaryKeyFilter(payload);
-		if (this.adapter.supportsNativePatch()) return this.adapter.nativePatch(filter, payload);
+		if (this.adapter.supportsNativePatch()) return this.adapter.nativePatch(this._translateFilter(filter), payload);
 		const update = decomposePatch(payload, this);
-		return this.adapter.updateOne(filter, update);
+		return this.adapter.updateOne(this._translateFilter(filter), this._translatePatchKeys(update));
 	}
 	/**
 	* Deletes a single record by primary key value.
@@ -288,35 +317,45 @@ var AtscriptDbTable = class {
 				filter[field] = fieldType ? this.adapter.prepareId(idObj[field], fieldType) : idObj[field];
 			}
 		}
-		return this.adapter.deleteOne(filter);
+		return this.adapter.deleteOne(this._translateFilter(filter));
 	}
 	/**
 	* Finds a single record matching the query.
 	*/ async findOne(query) {
-		return this.adapter.findOne(query);
+		this._flatten();
+		const translatedQuery = this._translateQuery(query);
+		const result = await this.adapter.findOne(translatedQuery);
+		return result ? this._reconstructFromRead(result) : null;
 	}
 	/**
 	* Finds all records matching the query.
 	*/ async findMany(query) {
-		return this.adapter.findMany(query);
+		this._flatten();
+		const translatedQuery = this._translateQuery(query);
+		const results = await this.adapter.findMany(translatedQuery);
+		return results.map((row) => this._reconstructFromRead(row));
 	}
 	/**
 	* Counts records matching the query.
 	*/ async count(query) {
+		this._flatten();
 		query ?? (query = {
 			filter: {},
 			controls: {}
 		});
-		return this.adapter.count(query);
+		return this.adapter.count(this._translateQuery(query));
 	}
 	async updateMany(filter, data) {
-		return this.adapter.updateMany(filter, data);
+		this._flatten();
+		return this.adapter.updateMany(this._translateFilter(filter), this._prepareForWrite({ ...data }));
 	}
 	async replaceMany(filter, data) {
-		return this.adapter.replaceMany(filter, data);
+		this._flatten();
+		return this.adapter.replaceMany(this._translateFilter(filter), this._prepareForWrite({ ...data }));
 	}
 	async deleteMany(filter) {
-		return this.adapter.deleteMany(filter);
+		this._flatten();
+		return this.adapter.deleteMany(this._translateFilter(filter));
 	}
 	/**
 	* Synchronizes indexes between Atscript definitions and the database.
@@ -342,6 +381,7 @@ var AtscriptDbTable = class {
 				this.adapter.onFieldScanned?.(path, type, metadata);
 			}
 		});
+		if (!this.adapter.supportsNestedObjects()) this._classifyFields();
 		this._finalizeIndexes();
 		this.adapter.onAfterFlatten?.();
 	}
@@ -375,6 +415,11 @@ else if (defaultFn !== undefined) this._defaults.set(fieldName, {
 			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
 			this._addIndexField("fulltext", name, fieldName);
 		}
+		if (metadata.has("db.json")) {
+			this._jsonFields.add(fieldName);
+			const hasIndex = metadata.has("db.index.plain") || metadata.has("db.index.unique") || metadata.has("db.index.fulltext");
+			if (hasIndex) this.logger.warn(`@db.index on a @db.json field "${fieldName}" — most databases cannot index into JSON columns`);
+		}
 	}
 	_addIndexField(type, name, field, sort = "asc") {
 		const key = indexKey(type, name);
@@ -391,7 +436,66 @@ else this._indexes.set(key, {
 			fields: [indexField]
 		});
 	}
+	/**
+	* Classifies each field as column, flattened, json, or parent-object.
+	* Builds the bidirectional _pathToPhysical / _physicalToPath maps.
+	* Only called when the adapter does NOT support nested objects natively.
+	*/ _classifyFields() {
+		for (const [path, type] of this._flatMap.entries()) {
+			if (!path) continue;
+			const designType = resolveDesignType(type);
+			const isJson = this._jsonFields.has(path);
+			const isArray = designType === "array";
+			const isObject = designType === "object";
+			if (isArray) this._jsonFields.add(path);
+else if (isObject && isJson) {} else if (isObject && !isJson) this._flattenedParents.add(path);
+		}
+		for (const ignoredField of this._ignoredFields) if (this._flattenedParents.has(ignoredField)) {
+			const prefix = `${ignoredField}.`;
+			for (const path of this._flatMap.keys()) if (path.startsWith(prefix)) this._ignoredFields.add(path);
+		}
+		for (const parentPath of this._flattenedParents) if (this._columnMap.has(parentPath)) throw new Error(`@db.column cannot rename a flattened object field "${parentPath}" — ` + `apply @db.column to individual nested fields, or use @db.json to store as a single column`);
+		for (const [path] of this._flatMap.entries()) {
+			if (!path) continue;
+			if (this._flattenedParents.has(path)) continue;
+			if (this._findJsonParent(path) !== undefined) continue;
+			const isFlattened = this._findFlattenedParent(path) !== undefined;
+			const physicalName = this._columnMap.get(path) ?? (isFlattened ? path.replace(/\./g, "__") : path);
+			this._pathToPhysical.set(path, physicalName);
+			this._physicalToPath.set(physicalName, path);
+		}
+		for (const parentPath of this._flattenedParents) {
+			const prefix = `${parentPath}.`;
+			const leaves = [];
+			for (const [path, physical] of this._pathToPhysical) if (path.startsWith(prefix)) leaves.push(physical);
+			if (leaves.length > 0) this._selectExpansion.set(parentPath, leaves);
+		}
+		this._requiresMappings = this._flattenedParents.size > 0 || this._jsonFields.size > 0;
+	}
+	/**
+	* Finds the nearest ancestor that is a flattened parent object.
+	* Returns the parent path, or undefined if no ancestor is being flattened.
+	*/ _findFlattenedParent(path) {
+		let pos = path.length;
+		while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+			const ancestor = path.slice(0, pos);
+			if (this._flattenedParents.has(ancestor)) return ancestor;
+		}
+		return undefined;
+	}
+	/**
+	* Finds the nearest ancestor that is a @db.json field.
+	* Children of JSON fields don't get their own columns.
+	*/ _findJsonParent(path) {
+		let pos = path.length;
+		while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+			const ancestor = path.slice(0, pos);
+			if (this._jsonFields.has(ancestor)) return ancestor;
+		}
+		return undefined;
+	}
 	_finalizeIndexes() {
+		for (const index of this._indexes.values()) for (const field of index.fields) field.name = this._pathToPhysical.get(field.name) ?? this._columnMap.get(field.name) ?? field.name;
 		for (const index of this._indexes.values()) if (index.type === "unique" && index.fields.length === 1) this._uniqueProps.add(index.fields[0].name);
 	}
 	/**
@@ -405,7 +509,7 @@ else this._indexes.set(key, {
 	}
 	/**
 	* Prepares a payload for writing to the database:
-	* prepares IDs, strips ignored fields, maps column names.
+	* prepares IDs, strips ignored fields, flattens nested objects, maps column names.
 	* Defaults should be applied before this via `_applyDefaults`.
 	*/ _prepareForWrite(payload) {
 		const data = { ...payload };
@@ -413,12 +517,213 @@ else this._indexes.set(key, {
 			const fieldType = this._flatMap?.get(pk);
 			if (fieldType) data[pk] = this.adapter.prepareId(data[pk], fieldType);
 		}
-		for (const field of this._ignoredFields) delete data[field];
-		for (const [logical, physical] of this._columnMap.entries()) if (logical in data) {
-			data[physical] = data[logical];
-			delete data[logical];
+		for (const field of this._ignoredFields) if (!field.includes(".")) delete data[field];
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) {
+			for (const [logical, physical] of this._columnMap.entries()) if (logical in data) {
+				data[physical] = data[logical];
+				delete data[logical];
+			}
+			return data;
 		}
-		return data;
+		return this._flattenPayload(data);
+	}
+	/**
+	* Flattens nested object fields into __-separated keys and
+	* JSON-stringifies @db.json / array fields.
+	* Uses _pathToPhysical for final key names.
+	*/ _flattenPayload(data) {
+		const result = {};
+		const dataKeys = Object.keys(data);
+		for (const key of dataKeys) {
+			const value = data[key];
+			if (this._flattenedParents.has(key)) {
+				if (value === null || value === undefined) this._setFlattenedChildrenNull(key, result);
+else if (typeof value === "object" && !Array.isArray(value)) this._flattenObject(key, value, result);
+			} else if (this._jsonFields.has(key)) {
+				const physical = this._pathToPhysical.get(key) ?? key;
+				result[physical] = value !== undefined && value !== null ? JSON.stringify(value) : value;
+			} else {
+				const physical = this._pathToPhysical.get(key) ?? key;
+				result[physical] = value;
+			}
+		}
+		return result;
+	}
+	/**
+	* Recursively flattens a nested object, writing physical keys to result.
+	*/ _flattenObject(prefix, obj, result) {
+		const objKeys = Object.keys(obj);
+		for (const key of objKeys) {
+			const value = obj[key];
+			const dotPath = `${prefix}.${key}`;
+			if (this._ignoredFields.has(dotPath)) continue;
+			if (this._flattenedParents.has(dotPath)) {
+				if (value === null || value === undefined) this._setFlattenedChildrenNull(dotPath, result);
+else if (typeof value === "object" && !Array.isArray(value)) this._flattenObject(dotPath, value, result);
+			} else if (this._jsonFields.has(dotPath)) {
+				const physical = this._pathToPhysical.get(dotPath) ?? dotPath.replace(/\./g, "__");
+				result[physical] = value !== undefined && value !== null ? JSON.stringify(value) : value;
+			} else {
+				const physical = this._pathToPhysical.get(dotPath) ?? dotPath.replace(/\./g, "__");
+				result[physical] = value;
+			}
+		}
+	}
+	/**
+	* When a parent object is null/undefined, set all its flattened children to null.
+	*/ _setFlattenedChildrenNull(parentPath, result) {
+		const prefix = `${parentPath}.`;
+		for (const [path, physical] of this._pathToPhysical.entries()) if (path.startsWith(prefix)) result[physical] = null;
+	}
+	/**
+	* Reconstructs nested objects from flat __-separated column values.
+	* JSON fields are parsed from strings back to objects/arrays.
+	*/ _reconstructFromRead(row) {
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) return row;
+		const result = {};
+		const rowKeys = Object.keys(row);
+		for (const physical of rowKeys) {
+			const value = row[physical];
+			const logicalPath = this._physicalToPath.get(physical);
+			if (!logicalPath) {
+				result[physical] = value;
+				continue;
+			}
+			if (this._jsonFields.has(logicalPath)) {
+				const parsed = typeof value === "string" ? JSON.parse(value) : value;
+				this._setNestedValue(result, logicalPath, parsed);
+			} else if (logicalPath.includes(".")) this._setNestedValue(result, logicalPath, value);
+else result[logicalPath] = value;
+		}
+		for (const parentPath of this._flattenedParents) this._reconstructNullParent(result, parentPath);
+		return result;
+	}
+	/**
+	* Sets a value at a dot-notation path, creating intermediate objects as needed.
+	*/ _setNestedValue(obj, dotPath, value) {
+		const parts = dotPath.split(".");
+		let current = obj;
+		for (let i = 0; i < parts.length - 1; i++) {
+			const part = parts[i];
+			if (current[part] === undefined || current[part] === null) current[part] = {};
+			current = current[part];
+		}
+		current[parts[parts.length - 1]] = value;
+	}
+	/**
+	* If all children of a flattened parent are null, collapse the parent to null.
+	*/ _reconstructNullParent(obj, parentPath) {
+		const parts = parentPath.split(".");
+		let current = obj;
+		for (let i = 0; i < parts.length - 1; i++) {
+			if (current[parts[i]] === undefined) return;
+			current = current[parts[i]];
+		}
+		const lastPart = parts[parts.length - 1];
+		const parentObj = current[lastPart];
+		if (typeof parentObj !== "object" || parentObj === null) return;
+		let allNull = true;
+		const parentKeys = Object.keys(parentObj);
+		for (const k of parentKeys) {
+			const v = parentObj[k];
+			if (v !== null && v !== undefined) {
+				allNull = false;
+				break;
+			}
+		}
+		if (allNull) {
+			const parentType = this._flatMap?.get(parentPath);
+			current[lastPart] = parentType?.optional ? null : {};
+		}
+	}
+	/**
+	* Translates a Uniquery's filter, sort, and projection from logical
+	* dot-notation paths to physical column names.
+	*/ _translateQuery(query) {
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) return query;
+		return {
+			filter: this._translateFilter(query.filter),
+			controls: query.controls ? this._translateControls(query.controls) : query.controls,
+			insights: query.insights
+		};
+	}
+	/**
+	* Recursively translates field names in a filter expression.
+	*/ _translateFilter(filter) {
+		if (!filter || typeof filter !== "object") return filter;
+		if (!this._requiresMappings) return filter;
+		const result = {};
+		const filterKeys = Object.keys(filter);
+		for (const key of filterKeys) {
+			const value = filter[key];
+			if (key === "$and" || key === "$or") result[key] = value.map((f) => this._translateFilter(f));
+else if (key === "$not") result[key] = this._translateFilter(value);
+else if (key.startsWith("$")) result[key] = value;
+else {
+				const physical = this._pathToPhysical.get(key) ?? key;
+				result[physical] = value;
+			}
+		}
+		return result;
+	}
+	/**
+	* Translates field names in sort and projection controls.
+	*/ _translateControls(controls) {
+		if (!controls) return controls;
+		const result = { ...controls };
+		if (controls.$sort) {
+			const translated = {};
+			const sortObj = controls.$sort;
+			const sortKeys = Object.keys(sortObj);
+			for (const key of sortKeys) {
+				if (this._flattenedParents.has(key)) continue;
+				const physical = this._pathToPhysical.get(key) ?? key;
+				translated[physical] = sortObj[key];
+			}
+			result.$sort = translated;
+		}
+		if (controls.$select) if (Array.isArray(controls.$select)) {
+			const expanded = [];
+			for (const key of controls.$select) {
+				const expansion = this._selectExpansion.get(key);
+				if (expansion) expanded.push(...expansion);
+else expanded.push(this._pathToPhysical.get(key) ?? key);
+			}
+			result.$select = expanded;
+		} else {
+			const translated = {};
+			const selectObj = controls.$select;
+			const selectKeys = Object.keys(selectObj);
+			for (const key of selectKeys) {
+				const val = selectObj[key];
+				const expansion = this._selectExpansion.get(key);
+				if (expansion) for (const leaf of expansion) translated[leaf] = val;
+else {
+					const physical = this._pathToPhysical.get(key) ?? key;
+					translated[physical] = val;
+				}
+			}
+			result.$select = translated;
+		}
+		return result;
+	}
+	/**
+	* Translates dot-notation keys in a decomposed patch to physical column names.
+	*/ _translatePatchKeys(update) {
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) return update;
+		const result = {};
+		const updateKeys = Object.keys(update);
+		for (const key of updateKeys) {
+			const value = update[key];
+			const operatorMatch = key.match(/^(.+?)(\.__\$.+)$/);
+			const basePath = operatorMatch ? operatorMatch[1] : key;
+			const suffix = operatorMatch ? operatorMatch[2] : "";
+			const physical = this._pathToPhysical.get(basePath) ?? basePath;
+			const finalKey = physical + suffix;
+			if (this._jsonFields.has(basePath) && typeof value === "object" && value !== null && !suffix) result[finalKey] = JSON.stringify(value);
+else result[finalKey] = value;
+		}
+		return result;
 	}
 	/**
 	* Extracts primary key field(s) from a payload to build a filter.
@@ -470,6 +775,12 @@ else this._indexes.set(key, {
 		_define_property$1(this, "_defaults", void 0);
 		_define_property$1(this, "_ignoredFields", void 0);
 		_define_property$1(this, "_uniqueProps", void 0);
+		/** Logical dot-path → physical column name. */ _define_property$1(this, "_pathToPhysical", void 0);
+		/** Physical column name → logical dot-path (inverse). */ _define_property$1(this, "_physicalToPath", void 0);
+		/** Object paths being flattened into __-separated columns (no column themselves). */ _define_property$1(this, "_flattenedParents", void 0);
+		/** Fields stored as JSON (@db.json + array fields). */ _define_property$1(this, "_jsonFields", void 0);
+		/** Intermediate paths → their leaf physical column names (for $select expansion in relational DBs). */ _define_property$1(this, "_selectExpansion", void 0);
+		/** Fast-path flag: skip all mapping when no nested/json fields exist. */ _define_property$1(this, "_requiresMappings", void 0);
 		_define_property$1(this, "validators", void 0);
 		this._type = _type;
 		this.adapter = adapter;
@@ -480,6 +791,12 @@ else this._indexes.set(key, {
 		this._defaults = new Map();
 		this._ignoredFields = new Set();
 		this._uniqueProps = new Set();
+		this._pathToPhysical = new Map();
+		this._physicalToPath = new Map();
+		this._flattenedParents = new Set();
+		this._jsonFields = new Set();
+		this._selectExpansion = new Map();
+		this._requiresMappings = false;
 		this.validators = new Map();
 		if (!(0, __atscript_typescript_utils.isAnnotatedType)(_type)) throw new Error("Atscript Annotated Type expected");
 		if (_type.type.kind !== "object") throw new Error("Database table type must be an object type");
@@ -539,6 +856,14 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Whether this adapter handles nested objects natively.
+	* When `true`, the generic layer skips flattening and
+	* passes nested objects as-is to the adapter.
+	* MongoDB returns `true`; relational adapters return `false` (default).
+	*/ supportsNestedObjects() {
+		return false;
+	}
+	/**
 	* Applies a patch payload using native database operations.
 	* Only called when {@link supportsNativePatch} returns `true`.
 	*

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TAtscriptAnnotatedType, TValidatorPlugin, TMetadataMap, TAtscriptDataType, Validator, TAtscriptTypeObject, TValidatorOptions, TAtscriptTypeArray } from '@atscript/typescript/utils';
+import { TAtscriptAnnotatedType, TValidatorPlugin, TMetadataMap, TAtscriptDataType, FlatOf, Validator, TAtscriptTypeObject, TValidatorOptions, TAtscriptTypeArray } from '@atscript/typescript/utils';
 import { FilterExpr, Uniquery, UniqueryControls } from '@uniqu/core';
 export { FieldOpsFor, FilterExpr, FilterVisitor, Uniquery, UniqueryControls, isPrimitive, walkFilter } from '@uniqu/core';
 
@@ -48,9 +48,9 @@ interface TDbFieldMeta {
     path: string;
     /** The annotated type for this field. */
     type: TAtscriptAnnotatedType;
-    /** Physical column/field name (from @db.column, or same as path). */
+    /** Physical column/field name (from @db.column, __-separated for flattened, or same as path). */
     physicalName: string;
-    /** Resolved design type: 'string', 'number', 'boolean', 'object', etc. */
+    /** Resolved design type: 'string', 'number', 'boolean', 'object', 'json', etc. */
     designType: string;
     /** Whether the field is optional. */
     optional: boolean;
@@ -60,6 +60,19 @@ interface TDbFieldMeta {
     ignored: boolean;
     /** Default value from @db.default.* */
     defaultValue?: TDbDefaultValue;
+    /**
+     * How this field is stored in the database.
+     * - 'column': a standard scalar column (default for primitives)
+     * - 'flattened': a leaf scalar from a flattened nested object
+     * - 'json': stored as a single JSON column (arrays, @db.json fields)
+     */
+    storage: 'column' | 'flattened' | 'json';
+    /**
+     * For flattened fields: the dot-notation path (same as `path`).
+     * E.g., for physicalName 'contact__email', this is 'contact.email'.
+     * Undefined for non-flattened fields.
+     */
+    flattenedFrom?: string;
 }
 
 /**
@@ -114,6 +127,13 @@ declare abstract class BaseDbAdapter {
      * {@link nativePatch} instead of using the generic decomposition.
      */
     supportsNativePatch(): boolean;
+    /**
+     * Whether this adapter handles nested objects natively.
+     * When `true`, the generic layer skips flattening and
+     * passes nested objects as-is to the adapter.
+     * MongoDB returns `true`; relational adapters return `false` (default).
+     */
+    supportsNestedObjects(): boolean;
     /**
      * Applies a patch payload using native database operations.
      * Only called when {@link supportsNativePatch} returns `true`.
@@ -247,7 +267,7 @@ declare function resolveDesignType(fieldType: TAtscriptAnnotatedType): string;
  * @typeParam T - The Atscript annotated type for this table.
  * @typeParam DataType - The inferred data shape from the annotated type.
  */
-declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, FlatType = FlatOf<T>> {
     protected readonly _type: T;
     protected readonly adapter: BaseDbAdapter;
     protected readonly logger: TGenericLogger;
@@ -263,6 +283,18 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     protected _defaults: Map<string, TDbDefaultValue>;
     protected _ignoredFields: Set<string>;
     protected _uniqueProps: Set<string>;
+    /** Logical dot-path → physical column name. */
+    protected _pathToPhysical: Map<string, string>;
+    /** Physical column name → logical dot-path (inverse). */
+    protected _physicalToPath: Map<string, string>;
+    /** Object paths being flattened into __-separated columns (no column themselves). */
+    protected _flattenedParents: Set<string>;
+    /** Fields stored as JSON (@db.json + array fields). */
+    protected _jsonFields: Set<string>;
+    /** Intermediate paths → their leaf physical column names (for $select expansion in relational DBs). */
+    protected _selectExpansion: Map<string, string[]>;
+    /** Fast-path flag: skip all mapping when no nested/json fields exist. */
+    protected _requiresMappings: boolean;
     protected readonly validators: Map<string, Validator<T, DataType>>;
     constructor(_type: T, adapter: BaseDbAdapter, logger?: TGenericLogger);
     /** The raw annotated type. */
@@ -281,6 +313,10 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     get ignoredFields(): ReadonlySet<string>;
     /** Single-field unique index properties. */
     get uniqueProps(): ReadonlySet<string>;
+    /** Precomputed logical dot-path → physical column name map. */
+    get pathToPhysical(): ReadonlyMap<string, string>;
+    /** Precomputed physical column name → logical dot-path map (inverse). */
+    get physicalToPath(): ReadonlyMap<string, string>;
     /** Descriptor for the primary ID field(s). */
     getIdDescriptor(): TIdDescriptor;
     /**
@@ -338,18 +374,18 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     /**
      * Finds a single record matching the query.
      */
-    findOne(query: Uniquery<DataType>): Promise<DataType | null>;
+    findOne(query: Uniquery<FlatType>): Promise<DataType | null>;
     /**
      * Finds all records matching the query.
      */
-    findMany(query: Uniquery<DataType>): Promise<DataType[]>;
+    findMany(query: Uniquery<FlatType>): Promise<DataType[]>;
     /**
      * Counts records matching the query.
      */
-    count(query?: Uniquery<DataType>): Promise<number>;
-    updateMany(filter: FilterExpr<DataType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
-    replaceMany(filter: FilterExpr<DataType>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-    deleteMany(filter: FilterExpr<DataType>): Promise<TDbDeleteResult>;
+    count(query?: Uniquery<FlatType>): Promise<number>;
+    updateMany(filter: FilterExpr<FlatType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
+    replaceMany(filter: FilterExpr<FlatType>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    deleteMany(filter: FilterExpr<FlatType>): Promise<TDbDeleteResult>;
     /**
      * Synchronizes indexes between Atscript definitions and the database.
      * Delegates to the adapter, which uses `this._table.indexes`.
@@ -365,6 +401,22 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
      */
     private _scanGenericAnnotations;
     protected _addIndexField(type: TDbIndex['type'], name: string, field: string, sort?: 'asc' | 'desc'): void;
+    /**
+     * Classifies each field as column, flattened, json, or parent-object.
+     * Builds the bidirectional _pathToPhysical / _physicalToPath maps.
+     * Only called when the adapter does NOT support nested objects natively.
+     */
+    private _classifyFields;
+    /**
+     * Finds the nearest ancestor that is a flattened parent object.
+     * Returns the parent path, or undefined if no ancestor is being flattened.
+     */
+    private _findFlattenedParent;
+    /**
+     * Finds the nearest ancestor that is a @db.json field.
+     * Children of JSON fields don't get their own columns.
+     */
+    private _findJsonParent;
     private _finalizeIndexes;
     /**
      * Applies default values for fields that are missing from the payload.
@@ -373,10 +425,54 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
     /**
      * Prepares a payload for writing to the database:
-     * prepares IDs, strips ignored fields, maps column names.
+     * prepares IDs, strips ignored fields, flattens nested objects, maps column names.
      * Defaults should be applied before this via `_applyDefaults`.
      */
     protected _prepareForWrite(payload: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Flattens nested object fields into __-separated keys and
+     * JSON-stringifies @db.json / array fields.
+     * Uses _pathToPhysical for final key names.
+     */
+    private _flattenPayload;
+    /**
+     * Recursively flattens a nested object, writing physical keys to result.
+     */
+    private _flattenObject;
+    /**
+     * When a parent object is null/undefined, set all its flattened children to null.
+     */
+    private _setFlattenedChildrenNull;
+    /**
+     * Reconstructs nested objects from flat __-separated column values.
+     * JSON fields are parsed from strings back to objects/arrays.
+     */
+    protected _reconstructFromRead(row: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Sets a value at a dot-notation path, creating intermediate objects as needed.
+     */
+    private _setNestedValue;
+    /**
+     * If all children of a flattened parent are null, collapse the parent to null.
+     */
+    private _reconstructNullParent;
+    /**
+     * Translates a Uniquery's filter, sort, and projection from logical
+     * dot-notation paths to physical column names.
+     */
+    private _translateQuery;
+    /**
+     * Recursively translates field names in a filter expression.
+     */
+    private _translateFilter;
+    /**
+     * Translates field names in sort and projection controls.
+     */
+    private _translateControls;
+    /**
+     * Translates dot-notation keys in a decomposed patch to physical column names.
+     */
+    private _translatePatchKeys;
     /**
      * Extracts primary key field(s) from a payload to build a filter.
      */

package/dist/index.mjs

@@ -132,6 +132,14 @@ var AtscriptDbTable = class {
 		this._flatten();
 		return this._uniqueProps;
 	}
+	/** Precomputed logical dot-path → physical column name map. */ get pathToPhysical() {
+		this._flatten();
+		return this._pathToPhysical;
+	}
+	/** Precomputed physical column name → logical dot-path map (inverse). */ get physicalToPath() {
+		this._flatten();
+		return this._physicalToPath;
+	}
 	/** Descriptor for the primary ID field(s). */ getIdDescriptor() {
 		this._flatten();
 		return {
@@ -147,17 +155,31 @@ var AtscriptDbTable = class {
 		this._flatten();
 		if (!this._fieldDescriptors) {
 			this._fieldDescriptors = [];
+			const skipFlattening = this.adapter.supportsNestedObjects();
 			for (const [path, type] of this._flatMap.entries()) {
 				if (!path) continue;
+				if (!skipFlattening && this._flattenedParents.has(path)) continue;
+				if (!skipFlattening && this._findJsonParent(path) !== undefined) continue;
+				const isJson = this._jsonFields.has(path);
+				const isFlattened = !skipFlattening && this._findFlattenedParent(path) !== undefined;
+				const designType = isJson ? "json" : resolveDesignType(type);
+				let storage;
+				if (skipFlattening) storage = "column";
+else if (isJson) storage = "json";
+else if (isFlattened) storage = "flattened";
+else storage = "column";
+				const physicalName = skipFlattening ? this._columnMap.get(path) ?? path : this._pathToPhysical.get(path) ?? this._columnMap.get(path) ?? path;
 				this._fieldDescriptors.push({
 					path,
 					type,
-					physicalName: this._columnMap.get(path) ?? path,
-					designType: resolveDesignType(type),
+					physicalName,
+					designType,
 					optional: type.optional === true,
 					isPrimaryKey: this._primaryKeys.includes(path),
 					ignored: this._ignoredFields.has(path),
-					defaultValue: this._defaults.get(path)
+					defaultValue: this._defaults.get(path),
+					storage,
+					flattenedFrom: isFlattened ? path : undefined
 				});
 			}
 		}
@@ -172,12 +194,19 @@ var AtscriptDbTable = class {
 	*/ resolveProjection(select) {
 		if (!select) return undefined;
 		if (Array.isArray(select)) return select.length > 0 ? select : undefined;
-		const entries = Object.entries(select);
-		if (entries.length === 0) return undefined;
-		const firstVal = entries[0][1];
-		if (firstVal === 1) return entries.filter(([, v]) => v === 1).map(([k]) => k);
-		const excluded = new Set(entries.filter(([, v]) => v === 0).map(([k]) => k));
-		return this.fieldDescriptors.filter((f) => !f.ignored && !excluded.has(f.path)).map((f) => f.path);
+		const selectObj = select;
+		const keys = Object.keys(selectObj);
+		if (keys.length === 0) return undefined;
+		if (selectObj[keys[0]] === 1) {
+			const result$1 = [];
+			for (const k of keys) if (selectObj[k] === 1) result$1.push(k);
+			return result$1;
+		}
+		const excluded = new Set();
+		for (const k of keys) if (selectObj[k] === 0) excluded.add(k);
+		const result = [];
+		for (const f of this.fieldDescriptors) if (!f.ignored && !excluded.has(f.path)) result.push(f.path);
+		return result;
 	}
 	/**
 	* Creates a new validator with custom options.
@@ -242,9 +271,9 @@ var AtscriptDbTable = class {
 		const validator = this.getValidator("patch");
 		if (!validator.validate(payload)) throw new Error("Validation failed for update");
 		const filter = this._extractPrimaryKeyFilter(payload);
-		if (this.adapter.supportsNativePatch()) return this.adapter.nativePatch(filter, payload);
+		if (this.adapter.supportsNativePatch()) return this.adapter.nativePatch(this._translateFilter(filter), payload);
 		const update = decomposePatch(payload, this);
-		return this.adapter.updateOne(filter, update);
+		return this.adapter.updateOne(this._translateFilter(filter), this._translatePatchKeys(update));
 	}
 	/**
 	* Deletes a single record by primary key value.
@@ -264,35 +293,45 @@ var AtscriptDbTable = class {
 				filter[field] = fieldType ? this.adapter.prepareId(idObj[field], fieldType) : idObj[field];
 			}
 		}
-		return this.adapter.deleteOne(filter);
+		return this.adapter.deleteOne(this._translateFilter(filter));
 	}
 	/**
 	* Finds a single record matching the query.
 	*/ async findOne(query) {
-		return this.adapter.findOne(query);
+		this._flatten();
+		const translatedQuery = this._translateQuery(query);
+		const result = await this.adapter.findOne(translatedQuery);
+		return result ? this._reconstructFromRead(result) : null;
 	}
 	/**
 	* Finds all records matching the query.
 	*/ async findMany(query) {
-		return this.adapter.findMany(query);
+		this._flatten();
+		const translatedQuery = this._translateQuery(query);
+		const results = await this.adapter.findMany(translatedQuery);
+		return results.map((row) => this._reconstructFromRead(row));
 	}
 	/**
 	* Counts records matching the query.
 	*/ async count(query) {
+		this._flatten();
 		query ?? (query = {
 			filter: {},
 			controls: {}
 		});
-		return this.adapter.count(query);
+		return this.adapter.count(this._translateQuery(query));
 	}
 	async updateMany(filter, data) {
-		return this.adapter.updateMany(filter, data);
+		this._flatten();
+		return this.adapter.updateMany(this._translateFilter(filter), this._prepareForWrite({ ...data }));
 	}
 	async replaceMany(filter, data) {
-		return this.adapter.replaceMany(filter, data);
+		this._flatten();
+		return this.adapter.replaceMany(this._translateFilter(filter), this._prepareForWrite({ ...data }));
 	}
 	async deleteMany(filter) {
-		return this.adapter.deleteMany(filter);
+		this._flatten();
+		return this.adapter.deleteMany(this._translateFilter(filter));
 	}
 	/**
 	* Synchronizes indexes between Atscript definitions and the database.
@@ -318,6 +357,7 @@ var AtscriptDbTable = class {
 				this.adapter.onFieldScanned?.(path, type, metadata);
 			}
 		});
+		if (!this.adapter.supportsNestedObjects()) this._classifyFields();
 		this._finalizeIndexes();
 		this.adapter.onAfterFlatten?.();
 	}
@@ -351,6 +391,11 @@ else if (defaultFn !== undefined) this._defaults.set(fieldName, {
 			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
 			this._addIndexField("fulltext", name, fieldName);
 		}
+		if (metadata.has("db.json")) {
+			this._jsonFields.add(fieldName);
+			const hasIndex = metadata.has("db.index.plain") || metadata.has("db.index.unique") || metadata.has("db.index.fulltext");
+			if (hasIndex) this.logger.warn(`@db.index on a @db.json field "${fieldName}" — most databases cannot index into JSON columns`);
+		}
 	}
 	_addIndexField(type, name, field, sort = "asc") {
 		const key = indexKey(type, name);
@@ -367,7 +412,66 @@ else this._indexes.set(key, {
 			fields: [indexField]
 		});
 	}
+	/**
+	* Classifies each field as column, flattened, json, or parent-object.
+	* Builds the bidirectional _pathToPhysical / _physicalToPath maps.
+	* Only called when the adapter does NOT support nested objects natively.
+	*/ _classifyFields() {
+		for (const [path, type] of this._flatMap.entries()) {
+			if (!path) continue;
+			const designType = resolveDesignType(type);
+			const isJson = this._jsonFields.has(path);
+			const isArray = designType === "array";
+			const isObject = designType === "object";
+			if (isArray) this._jsonFields.add(path);
+else if (isObject && isJson) {} else if (isObject && !isJson) this._flattenedParents.add(path);
+		}
+		for (const ignoredField of this._ignoredFields) if (this._flattenedParents.has(ignoredField)) {
+			const prefix = `${ignoredField}.`;
+			for (const path of this._flatMap.keys()) if (path.startsWith(prefix)) this._ignoredFields.add(path);
+		}
+		for (const parentPath of this._flattenedParents) if (this._columnMap.has(parentPath)) throw new Error(`@db.column cannot rename a flattened object field "${parentPath}" — ` + `apply @db.column to individual nested fields, or use @db.json to store as a single column`);
+		for (const [path] of this._flatMap.entries()) {
+			if (!path) continue;
+			if (this._flattenedParents.has(path)) continue;
+			if (this._findJsonParent(path) !== undefined) continue;
+			const isFlattened = this._findFlattenedParent(path) !== undefined;
+			const physicalName = this._columnMap.get(path) ?? (isFlattened ? path.replace(/\./g, "__") : path);
+			this._pathToPhysical.set(path, physicalName);
+			this._physicalToPath.set(physicalName, path);
+		}
+		for (const parentPath of this._flattenedParents) {
+			const prefix = `${parentPath}.`;
+			const leaves = [];
+			for (const [path, physical] of this._pathToPhysical) if (path.startsWith(prefix)) leaves.push(physical);
+			if (leaves.length > 0) this._selectExpansion.set(parentPath, leaves);
+		}
+		this._requiresMappings = this._flattenedParents.size > 0 || this._jsonFields.size > 0;
+	}
+	/**
+	* Finds the nearest ancestor that is a flattened parent object.
+	* Returns the parent path, or undefined if no ancestor is being flattened.
+	*/ _findFlattenedParent(path) {
+		let pos = path.length;
+		while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+			const ancestor = path.slice(0, pos);
+			if (this._flattenedParents.has(ancestor)) return ancestor;
+		}
+		return undefined;
+	}
+	/**
+	* Finds the nearest ancestor that is a @db.json field.
+	* Children of JSON fields don't get their own columns.
+	*/ _findJsonParent(path) {
+		let pos = path.length;
+		while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+			const ancestor = path.slice(0, pos);
+			if (this._jsonFields.has(ancestor)) return ancestor;
+		}
+		return undefined;
+	}
 	_finalizeIndexes() {
+		for (const index of this._indexes.values()) for (const field of index.fields) field.name = this._pathToPhysical.get(field.name) ?? this._columnMap.get(field.name) ?? field.name;
 		for (const index of this._indexes.values()) if (index.type === "unique" && index.fields.length === 1) this._uniqueProps.add(index.fields[0].name);
 	}
 	/**
@@ -381,7 +485,7 @@ else this._indexes.set(key, {
 	}
 	/**
 	* Prepares a payload for writing to the database:
-	* prepares IDs, strips ignored fields, maps column names.
+	* prepares IDs, strips ignored fields, flattens nested objects, maps column names.
 	* Defaults should be applied before this via `_applyDefaults`.
 	*/ _prepareForWrite(payload) {
 		const data = { ...payload };
@@ -389,12 +493,213 @@ else this._indexes.set(key, {
 			const fieldType = this._flatMap?.get(pk);
 			if (fieldType) data[pk] = this.adapter.prepareId(data[pk], fieldType);
 		}
-		for (const field of this._ignoredFields) delete data[field];
-		for (const [logical, physical] of this._columnMap.entries()) if (logical in data) {
-			data[physical] = data[logical];
-			delete data[logical];
+		for (const field of this._ignoredFields) if (!field.includes(".")) delete data[field];
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) {
+			for (const [logical, physical] of this._columnMap.entries()) if (logical in data) {
+				data[physical] = data[logical];
+				delete data[logical];
+			}
+			return data;
 		}
-		return data;
+		return this._flattenPayload(data);
+	}
+	/**
+	* Flattens nested object fields into __-separated keys and
+	* JSON-stringifies @db.json / array fields.
+	* Uses _pathToPhysical for final key names.
+	*/ _flattenPayload(data) {
+		const result = {};
+		const dataKeys = Object.keys(data);
+		for (const key of dataKeys) {
+			const value = data[key];
+			if (this._flattenedParents.has(key)) {
+				if (value === null || value === undefined) this._setFlattenedChildrenNull(key, result);
+else if (typeof value === "object" && !Array.isArray(value)) this._flattenObject(key, value, result);
+			} else if (this._jsonFields.has(key)) {
+				const physical = this._pathToPhysical.get(key) ?? key;
+				result[physical] = value !== undefined && value !== null ? JSON.stringify(value) : value;
+			} else {
+				const physical = this._pathToPhysical.get(key) ?? key;
+				result[physical] = value;
+			}
+		}
+		return result;
+	}
+	/**
+	* Recursively flattens a nested object, writing physical keys to result.
+	*/ _flattenObject(prefix, obj, result) {
+		const objKeys = Object.keys(obj);
+		for (const key of objKeys) {
+			const value = obj[key];
+			const dotPath = `${prefix}.${key}`;
+			if (this._ignoredFields.has(dotPath)) continue;
+			if (this._flattenedParents.has(dotPath)) {
+				if (value === null || value === undefined) this._setFlattenedChildrenNull(dotPath, result);
+else if (typeof value === "object" && !Array.isArray(value)) this._flattenObject(dotPath, value, result);
+			} else if (this._jsonFields.has(dotPath)) {
+				const physical = this._pathToPhysical.get(dotPath) ?? dotPath.replace(/\./g, "__");
+				result[physical] = value !== undefined && value !== null ? JSON.stringify(value) : value;
+			} else {
+				const physical = this._pathToPhysical.get(dotPath) ?? dotPath.replace(/\./g, "__");
+				result[physical] = value;
+			}
+		}
+	}
+	/**
+	* When a parent object is null/undefined, set all its flattened children to null.
+	*/ _setFlattenedChildrenNull(parentPath, result) {
+		const prefix = `${parentPath}.`;
+		for (const [path, physical] of this._pathToPhysical.entries()) if (path.startsWith(prefix)) result[physical] = null;
+	}
+	/**
+	* Reconstructs nested objects from flat __-separated column values.
+	* JSON fields are parsed from strings back to objects/arrays.
+	*/ _reconstructFromRead(row) {
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) return row;
+		const result = {};
+		const rowKeys = Object.keys(row);
+		for (const physical of rowKeys) {
+			const value = row[physical];
+			const logicalPath = this._physicalToPath.get(physical);
+			if (!logicalPath) {
+				result[physical] = value;
+				continue;
+			}
+			if (this._jsonFields.has(logicalPath)) {
+				const parsed = typeof value === "string" ? JSON.parse(value) : value;
+				this._setNestedValue(result, logicalPath, parsed);
+			} else if (logicalPath.includes(".")) this._setNestedValue(result, logicalPath, value);
+else result[logicalPath] = value;
+		}
+		for (const parentPath of this._flattenedParents) this._reconstructNullParent(result, parentPath);
+		return result;
+	}
+	/**
+	* Sets a value at a dot-notation path, creating intermediate objects as needed.
+	*/ _setNestedValue(obj, dotPath, value) {
+		const parts = dotPath.split(".");
+		let current = obj;
+		for (let i = 0; i < parts.length - 1; i++) {
+			const part = parts[i];
+			if (current[part] === undefined || current[part] === null) current[part] = {};
+			current = current[part];
+		}
+		current[parts[parts.length - 1]] = value;
+	}
+	/**
+	* If all children of a flattened parent are null, collapse the parent to null.
+	*/ _reconstructNullParent(obj, parentPath) {
+		const parts = parentPath.split(".");
+		let current = obj;
+		for (let i = 0; i < parts.length - 1; i++) {
+			if (current[parts[i]] === undefined) return;
+			current = current[parts[i]];
+		}
+		const lastPart = parts[parts.length - 1];
+		const parentObj = current[lastPart];
+		if (typeof parentObj !== "object" || parentObj === null) return;
+		let allNull = true;
+		const parentKeys = Object.keys(parentObj);
+		for (const k of parentKeys) {
+			const v = parentObj[k];
+			if (v !== null && v !== undefined) {
+				allNull = false;
+				break;
+			}
+		}
+		if (allNull) {
+			const parentType = this._flatMap?.get(parentPath);
+			current[lastPart] = parentType?.optional ? null : {};
+		}
+	}
+	/**
+	* Translates a Uniquery's filter, sort, and projection from logical
+	* dot-notation paths to physical column names.
+	*/ _translateQuery(query) {
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) return query;
+		return {
+			filter: this._translateFilter(query.filter),
+			controls: query.controls ? this._translateControls(query.controls) : query.controls,
+			insights: query.insights
+		};
+	}
+	/**
+	* Recursively translates field names in a filter expression.
+	*/ _translateFilter(filter) {
+		if (!filter || typeof filter !== "object") return filter;
+		if (!this._requiresMappings) return filter;
+		const result = {};
+		const filterKeys = Object.keys(filter);
+		for (const key of filterKeys) {
+			const value = filter[key];
+			if (key === "$and" || key === "$or") result[key] = value.map((f) => this._translateFilter(f));
+else if (key === "$not") result[key] = this._translateFilter(value);
+else if (key.startsWith("$")) result[key] = value;
+else {
+				const physical = this._pathToPhysical.get(key) ?? key;
+				result[physical] = value;
+			}
+		}
+		return result;
+	}
+	/**
+	* Translates field names in sort and projection controls.
+	*/ _translateControls(controls) {
+		if (!controls) return controls;
+		const result = { ...controls };
+		if (controls.$sort) {
+			const translated = {};
+			const sortObj = controls.$sort;
+			const sortKeys = Object.keys(sortObj);
+			for (const key of sortKeys) {
+				if (this._flattenedParents.has(key)) continue;
+				const physical = this._pathToPhysical.get(key) ?? key;
+				translated[physical] = sortObj[key];
+			}
+			result.$sort = translated;
+		}
+		if (controls.$select) if (Array.isArray(controls.$select)) {
+			const expanded = [];
+			for (const key of controls.$select) {
+				const expansion = this._selectExpansion.get(key);
+				if (expansion) expanded.push(...expansion);
+else expanded.push(this._pathToPhysical.get(key) ?? key);
+			}
+			result.$select = expanded;
+		} else {
+			const translated = {};
+			const selectObj = controls.$select;
+			const selectKeys = Object.keys(selectObj);
+			for (const key of selectKeys) {
+				const val = selectObj[key];
+				const expansion = this._selectExpansion.get(key);
+				if (expansion) for (const leaf of expansion) translated[leaf] = val;
+else {
+					const physical = this._pathToPhysical.get(key) ?? key;
+					translated[physical] = val;
+				}
+			}
+			result.$select = translated;
+		}
+		return result;
+	}
+	/**
+	* Translates dot-notation keys in a decomposed patch to physical column names.
+	*/ _translatePatchKeys(update) {
+		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) return update;
+		const result = {};
+		const updateKeys = Object.keys(update);
+		for (const key of updateKeys) {
+			const value = update[key];
+			const operatorMatch = key.match(/^(.+?)(\.__\$.+)$/);
+			const basePath = operatorMatch ? operatorMatch[1] : key;
+			const suffix = operatorMatch ? operatorMatch[2] : "";
+			const physical = this._pathToPhysical.get(basePath) ?? basePath;
+			const finalKey = physical + suffix;
+			if (this._jsonFields.has(basePath) && typeof value === "object" && value !== null && !suffix) result[finalKey] = JSON.stringify(value);
+else result[finalKey] = value;
+		}
+		return result;
 	}
 	/**
 	* Extracts primary key field(s) from a payload to build a filter.
@@ -446,6 +751,12 @@ else this._indexes.set(key, {
 		_define_property$1(this, "_defaults", void 0);
 		_define_property$1(this, "_ignoredFields", void 0);
 		_define_property$1(this, "_uniqueProps", void 0);
+		/** Logical dot-path → physical column name. */ _define_property$1(this, "_pathToPhysical", void 0);
+		/** Physical column name → logical dot-path (inverse). */ _define_property$1(this, "_physicalToPath", void 0);
+		/** Object paths being flattened into __-separated columns (no column themselves). */ _define_property$1(this, "_flattenedParents", void 0);
+		/** Fields stored as JSON (@db.json + array fields). */ _define_property$1(this, "_jsonFields", void 0);
+		/** Intermediate paths → their leaf physical column names (for $select expansion in relational DBs). */ _define_property$1(this, "_selectExpansion", void 0);
+		/** Fast-path flag: skip all mapping when no nested/json fields exist. */ _define_property$1(this, "_requiresMappings", void 0);
 		_define_property$1(this, "validators", void 0);
 		this._type = _type;
 		this.adapter = adapter;
@@ -456,6 +767,12 @@ else this._indexes.set(key, {
 		this._defaults = new Map();
 		this._ignoredFields = new Set();
 		this._uniqueProps = new Set();
+		this._pathToPhysical = new Map();
+		this._physicalToPath = new Map();
+		this._flattenedParents = new Set();
+		this._jsonFields = new Set();
+		this._selectExpansion = new Map();
+		this._requiresMappings = false;
 		this.validators = new Map();
 		if (!isAnnotatedType(_type)) throw new Error("Atscript Annotated Type expected");
 		if (_type.type.kind !== "object") throw new Error("Database table type must be an object type");
@@ -515,6 +832,14 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Whether this adapter handles nested objects natively.
+	* When `true`, the generic layer skips flattening and
+	* passes nested objects as-is to the adapter.
+	* MongoDB returns `true`; relational adapters return `false` (default).
+	*/ supportsNestedObjects() {
+		return false;
+	}
+	/**
 	* Applies a patch payload using native database operations.
 	* Only called when {@link supportsNativePatch} returns `true`.
 	*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/utils-db",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Database adapter utilities for atscript.",
   "keywords": [
     "atscript",
@@ -37,8 +37,8 @@
   },
   "peerDependencies": {
     "@uniqu/core": "^0.0.1",
-    "@atscript/core": "^0.1.30",
-    "@atscript/typescript": "^0.1.30"
+    "@atscript/core": "^0.1.31",
+    "@atscript/typescript": "^0.1.31"
   },
   "scripts": {
     "pub": "pnpm publish --access public",