@atscript/utils-db 0.1.30 → 0.1.32

package/dist/index.cjs

@@ -101,6 +101,78 @@ else update[key] = value;
 	}
 }
 
+//#endregion
+//#region packages/utils-db/src/uniqu-select.ts
+function _define_property$2(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+else obj[key] = value;
+	return obj;
+}
+var UniquSelect = class {
+	/**
+	* Resolved inclusion array of field names.
+	* For exclusion form, inverts using `allFields` from constructor.
+	*/ get asArray() {
+		if (this._arrayResolved) return this._array;
+		this._arrayResolved = true;
+		if (Array.isArray(this._raw)) {
+			this._array = this._raw;
+			return this._array;
+		}
+		const raw = this._raw;
+		const entries = Object.entries(raw);
+		if (entries.length === 0) return undefined;
+		if (entries[0][1] === 1) {
+			const result = [];
+			for (const entry of entries) if (entry[1] === 1) result.push(entry[0]);
+			this._array = result;
+		} else {
+			if (!this._allFields) return undefined;
+			const excluded = new Set();
+			for (const entry of entries) if (entry[1] === 0) excluded.add(entry[0]);
+			const result = [];
+			for (const field of this._allFields) if (!excluded.has(field)) result.push(field);
+			this._array = result;
+		}
+		return this._array;
+	}
+	/**
+	* Record projection preserving original semantics.
+	* Returns original object as-is if raw was object.
+	* Converts `string[]` to `{field: 1}` inclusion object.
+	*/ get asProjection() {
+		if (this._projectionResolved) return this._projection;
+		this._projectionResolved = true;
+		if (!Array.isArray(this._raw)) {
+			const raw = this._raw;
+			if (Object.keys(raw).length === 0) return undefined;
+			this._projection = raw;
+			return this._projection;
+		}
+		const arr = this._raw;
+		if (arr.length === 0) return undefined;
+		const result = {};
+		for (const item of arr) result[item] = 1;
+		this._projection = result;
+		return this._projection;
+	}
+	constructor(raw, allFields) {
+		_define_property$2(this, "_raw", void 0);
+		_define_property$2(this, "_allFields", void 0);
+		_define_property$2(this, "_arrayResolved", false);
+		_define_property$2(this, "_array", void 0);
+		_define_property$2(this, "_projectionResolved", false);
+		_define_property$2(this, "_projection", void 0);
+		this._raw = raw;
+		this._allFields = allFields;
+	}
+};
+
 //#endregion
 //#region packages/utils-db/src/db-table.ts
 function _define_property$1(obj, key, value) {
@@ -120,11 +192,18 @@ function resolveDesignType(fieldType) {
 	if (fieldType.type.kind === "array") return "array";
 	return "string";
 }
+/** Coerces a storage value (0/1/null) back to a JS boolean. */ function toBool(value) {
+	if (value === null || value === undefined) return value;
+	return !!value;
+}
 function indexKey(type, name) {
 	const cleanName = name.replace(/[^a-z0-9_.-]/gi, "_").replace(/_+/g, "_").slice(0, 127 - INDEX_PREFIX.length - type.length - 2);
 	return `${INDEX_PREFIX}${type}__${cleanName}`;
 }
 var AtscriptDbTable = class {
+	/** Returns the underlying adapter with its concrete type preserved. */ getAdapter() {
+		return this.adapter;
+	}
 	/** The raw annotated type. */ get type() {
 		return this._type;
 	}
@@ -140,6 +219,29 @@ var AtscriptDbTable = class {
 		this._flatten();
 		return this._primaryKeys;
 	}
+	/**
+	* Registers an additional primary key field.
+	* Useful for adapters (e.g., MongoDB) where `_id` is always the primary key
+	* even without an explicit `@meta.id` annotation.
+	*
+	* Typically called from {@link BaseDbAdapter.onFieldScanned}.
+	*/ addPrimaryKey(field) {
+		if (!this._primaryKeys.includes(field)) this._primaryKeys.push(field);
+	}
+	/**
+	* Removes a field from the primary key list.
+	* Useful for adapters (e.g., MongoDB) where `@meta.id` fields should be
+	* unique indexes rather than part of the primary key.
+	*/ removePrimaryKey(field) {
+		const idx = this._primaryKeys.indexOf(field);
+		if (idx >= 0) this._primaryKeys.splice(idx, 1);
+	}
+	/**
+	* Registers a field as having a unique constraint.
+	* Used by adapters to ensure `findById` falls back to this field.
+	*/ addUniqueField(field) {
+		this._uniqueProps.add(field);
+	}
 	/** Logical → physical column name mapping from `@db.column`. */ get columnMap() {
 		this._flatten();
 		return this._columnMap;
@@ -156,6 +258,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,39 +281,38 @@ var AtscriptDbTable = class {
 		this._flatten();
 		if (!this._fieldDescriptors) {
 			this._fieldDescriptors = [];
+			const skipFlattening = this._nestedObjects;
 			for (const [path, type] of this._flatMap.entries()) {
 				if (!path) continue;
+				if (!skipFlattening && this._flattenedParents.has(path)) continue;
+				if (!skipFlattening && this._findAncestorInSet(path, this._jsonFields) !== undefined) continue;
+				const isJson = this._jsonFields.has(path);
+				const isFlattened = !skipFlattening && this._findAncestorInSet(path, this._flattenedParents) !== 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
 				});
 			}
+			Object.freeze(this._fieldDescriptors);
 		}
 		return this._fieldDescriptors;
 	}
 	/**
-	* Resolves `$select` from {@link UniqueryControls} to a list of field names.
-	* - `undefined` → `undefined` (all fields)
-	* - `string[]` → pass through
-	* - `Record<K, 1>` → extract included keys
-	* - `Record<K, 0>` → invert using known field names
-	*/ 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);
-	}
-	/**
 	* Creates a new validator with custom options.
 	* Adapter plugins are NOT automatically included — use {@link getValidator}
 	* for the standard validator with adapter plugins.
@@ -266,9 +375,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 +397,145 @@ 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));
+	}
+	/**
+	* Finds records and total count in a single logical call.
+	* Adapters may optimize into a single query (e.g., MongoDB `$facet`).
+	*/ async findManyWithCount(query) {
+		this._flatten();
+		const translated = this._translateQuery(query);
+		const result = await this.adapter.findManyWithCount(translated);
+		return {
+			data: result.data.map((row) => this._reconstructFromRead(row)),
+			count: result.count
+		};
+	}
+	/** Whether the underlying adapter supports text search. */ isSearchable() {
+		return this.adapter.isSearchable();
+	}
+	/** Returns available search indexes from the adapter. */ getSearchIndexes() {
+		return this.adapter.getSearchIndexes();
+	}
+	/**
+	* Full-text search with query translation and result reconstruction.
+	*
+	* @param text - Search text.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional search index to target.
+	*/ async search(text, query, indexName) {
+		this._flatten();
+		const translated = this._translateQuery(query);
+		const results = await this.adapter.search(text, translated, indexName);
+		return results.map((row) => this._reconstructFromRead(row));
+	}
+	/**
+	* Full-text search with count for paginated search results.
+	*
+	* @param text - Search text.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional search index to target.
+	*/ async searchWithCount(text, query, indexName) {
+		this._flatten();
+		const translated = this._translateQuery(query);
+		const result = await this.adapter.searchWithCount(text, translated, indexName);
+		return {
+			data: result.data.map((row) => this._reconstructFromRead(row)),
+			count: result.count
+		};
+	}
+	/**
+	* Finds a single record by primary key or unique property.
+	*
+	* 1. Tries primary key lookup (single or composite).
+	* 2. Falls back to unique properties if PK validation fails.
+	*
+	* @param id - Primary key value (scalar for single PK, object for composite).
+	* @param controls - Optional query controls ($select, etc.).
+	*/ async findById(id, controls) {
+		this._flatten();
+		const pkFields = this.primaryKeys;
+		if (pkFields.length === 0) throw new Error("No primary key defined — cannot find by ID");
+		const filter = {};
+		let pkValid = true;
+		if (pkFields.length === 1) {
+			const field = pkFields[0];
+			const fieldType = this.flatMap.get(field);
+			try {
+				filter[field] = fieldType ? this.adapter.prepareId(id, fieldType) : id;
+			} catch {
+				pkValid = false;
+			}
+		} else if (typeof id !== "object" || id === null) pkValid = false;
+else {
+			const idObj = id;
+			for (const field of pkFields) {
+				const fieldType = this.flatMap.get(field);
+				try {
+					filter[field] = fieldType ? this.adapter.prepareId(idObj[field], fieldType) : idObj[field];
+				} catch {
+					pkValid = false;
+					break;
+				}
+			}
+		}
+		if (pkValid) return await this.findOne({
+			filter,
+			controls: controls || {}
+		});
+		if (this.uniqueProps.size > 0) {
+			const orFilters = [];
+			for (const prop of this.uniqueProps) {
+				const fieldType = this.flatMap.get(prop);
+				try {
+					const prepared = fieldType ? this.adapter.prepareId(id, fieldType) : id;
+					orFilters.push({ [prop]: prepared });
+				} catch {}
+			}
+			return await this.findOne({
+				filter: { $or: orFilters },
+				controls: controls || {}
+			});
+		}
+		return null;
 	}
 	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,8 +561,12 @@ var AtscriptDbTable = class {
 				this.adapter.onFieldScanned?.(path, type, metadata);
 			}
 		});
+		if (!this._nestedObjects) this._classifyFields();
 		this._finalizeIndexes();
 		this.adapter.onAfterFlatten?.();
+		if (this._nestedObjects && this._flatMap) {
+			for (const path of this._flatMap.keys()) if (path && !this._ignoredFields.has(path)) this._allPhysicalFields.push(path);
+		} else for (const physical of this._pathToPhysical.values()) this._allPhysicalFields.push(physical);
 	}
 	/**
 	* Scans `@db.*` and `@meta.id` annotations on a field during flattening.
@@ -365,7 +588,7 @@ else if (defaultFn !== undefined) this._defaults.set(fieldName, {
 		for (const index of metadata.get("db.index.plain") || []) {
 			const name = index === true ? fieldName : index?.name || fieldName;
 			const sort = (index === true ? undefined : index?.sort) || "asc";
-			this._addIndexField("plain", name, fieldName, sort);
+			this._addIndexField("plain", name, fieldName, { sort });
 		}
 		for (const index of metadata.get("db.index.unique") || []) {
 			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
@@ -373,16 +596,23 @@ else if (defaultFn !== undefined) this._defaults.set(fieldName, {
 		}
 		for (const index of metadata.get("db.index.fulltext") || []) {
 			const name = index === true ? fieldName : typeof index === "string" ? index : index?.name || fieldName;
-			this._addIndexField("fulltext", name, fieldName);
+			const weight = index !== true && typeof index === "object" ? index?.weight : undefined;
+			this._addIndexField("fulltext", name, fieldName, { weight });
+		}
+		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") {
+	_addIndexField(type, name, field, opts) {
 		const key = indexKey(type, name);
 		const index = this._indexes.get(key);
 		const indexField = {
 			name: field,
-			sort
+			sort: opts?.sort ?? "asc"
 		};
+		if (opts?.weight !== undefined) indexField.weight = opts.weight;
 		if (index) index.fields.push(indexField);
 else this._indexes.set(key, {
 			key,
@@ -391,7 +621,57 @@ 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._findAncestorInSet(path, this._jsonFields) !== undefined) continue;
+			const isFlattened = this._findAncestorInSet(path, this._flattenedParents) !== undefined;
+			const physicalName = this._columnMap.get(path) ?? (isFlattened ? path.replace(/\./g, "__") : path);
+			this._pathToPhysical.set(path, physicalName);
+			this._physicalToPath.set(physicalName, path);
+			const fieldType = this._flatMap?.get(path);
+			if (fieldType && resolveDesignType(fieldType) === "boolean") this._booleanFields.add(physicalName);
+		}
+		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 of `path` that belongs to `set`.
+	* Used to locate flattened parents and @db.json ancestors.
+	*/ _findAncestorInSet(path, set) {
+		let pos = path.length;
+		while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+			const ancestor = path.slice(0, pos);
+			if (set.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);
 	}
 	/**
@@ -399,13 +679,26 @@ else this._indexes.set(key, {
 	* Called before validation so that defaults satisfy required field constraints.
 	*/ _applyDefaults(data) {
 		for (const [field, def] of this._defaults.entries()) if (data[field] === undefined) {
-			if (def.kind === "value") data[field] = def.value;
+			if (def.kind === "value") {
+				const fieldType = this._flatMap?.get(field);
+				const designType = fieldType?.type.kind === "" && fieldType.type.designType;
+				data[field] = designType === "string" ? def.value : JSON.parse(def.value);
+			} else if (def.kind === "fn") switch (def.fn) {
+				case "now": {
+					data[field] = Date.now();
+					break;
+				}
+				case "uuid": {
+					data[field] = crypto.randomUUID();
+					break;
+				}
+			}
 		}
 		return data;
 	}
 	/**
 	* 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 +706,224 @@ 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._nestedObjects) {
+			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 = {};
+		for (const key of Object.keys(data)) this._writeFlattenedField(key, data[key], result);
+		return result;
+	}
+	/**
+	* Classifies and writes a single field to the result object.
+	* Recurses into nested objects that should be flattened.
+	*/ _writeFlattenedField(path, value, result) {
+		if (this._ignoredFields.has(path)) return;
+		if (this._flattenedParents.has(path)) {
+			if (value === null || value === undefined) this._setFlattenedChildrenNull(path, result);
+else if (typeof value === "object" && !Array.isArray(value)) {
+				const obj = value;
+				for (const key of Object.keys(obj)) this._writeFlattenedField(`${path}.${key}`, obj[key], result);
+			}
+		} else if (this._jsonFields.has(path)) {
+			const physical = this._pathToPhysical.get(path) ?? path.replace(/\./g, "__");
+			result[physical] = value !== undefined && value !== null ? JSON.stringify(value) : value;
+		} else {
+			const physical = this._pathToPhysical.get(path) ?? path.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._nestedObjects) return this._coerceBooleans(row);
+		const result = {};
+		const rowKeys = Object.keys(row);
+		for (const physical of rowKeys) {
+			const value = this._booleanFields.has(physical) ? toBool(row[physical]) : 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;
+	}
+	/**
+	* Coerces boolean fields from storage representation (0/1) to JS booleans.
+	* Used on the fast-path when no column mapping is needed.
+	*/ _coerceBooleans(row) {
+		if (this._booleanFields.size === 0) return row;
+		for (const field of this._booleanFields) if (field in row) row[field] = toBool(row[field]);
+		return row;
+	}
+	/**
+	* 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.
+	* Always wraps `$select` in {@link UniquSelect}.
+	*/ _translateQuery(query) {
+		if (!this._requiresMappings || this._nestedObjects) {
+			const controls = query.controls;
+			return {
+				filter: query.filter,
+				controls: {
+					...controls,
+					$select: controls?.$select ? new UniquSelect(controls.$select, this._allPhysicalFields) : undefined
+				}
+			};
+		}
+		return {
+			filter: this._translateFilter(query.filter),
+			controls: query.controls ? this._translateControls(query.controls) : {}
+		};
+	}
+	/**
+	* 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.
+	* Wraps `$select` in {@link UniquSelect} after path translation.
+	*/ _translateControls(controls) {
+		if (!controls) return {};
+		const result = {
+			...controls,
+			$select: undefined
+		};
+		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) {
+			let translatedRaw;
+			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);
+				}
+				translatedRaw = 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;
+					}
+				}
+				translatedRaw = translated;
+			}
+			result.$select = new UniquSelect(translatedRaw, this._allPhysicalFields);
+		}
+		return result;
+	}
+	/**
+	* Translates dot-notation keys in a decomposed patch to physical column names.
+	*/ _translatePatchKeys(update) {
+		if (!this._requiresMappings || this._nestedObjects) 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.
@@ -438,21 +943,26 @@ else this._indexes.set(key, {
 	*/ _buildValidator(purpose) {
 		const plugins = this.adapter.getValidatorPlugins();
 		switch (purpose) {
-			case "insert": return this.createValidator({
-				plugins,
-				replace: (type, path) => {
-					if (this._primaryKeys.includes(path)) return {
-						...type,
-						optional: true
-					};
-					return type;
-				}
-			});
-			case "update": return this.createValidator({ plugins });
-			case "patch": return this.createValidator({
-				plugins,
-				partial: true
-			});
+			case "insert": {
+				if (this.adapter.buildInsertValidator) return this.adapter.buildInsertValidator(this);
+				return this.createValidator({
+					plugins,
+					replace: (type, path) => {
+						if (this._primaryKeys.includes(path) || this._defaults.has(path)) return {
+							...type,
+							optional: true
+						};
+						return type;
+					}
+				});
+			}
+			case "patch": {
+				if (this.adapter.buildPatchValidator) return this.adapter.buildPatchValidator(this);
+				return this.createValidator({
+					plugins,
+					partial: true
+				});
+			}
 			default: return this.createValidator({ plugins });
 		}
 	}
@@ -470,6 +980,15 @@ 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);
+		/** Physical column names of boolean fields (for storage coercion on read). */ _define_property$1(this, "_booleanFields", void 0);
+		/** Fast-path flag: skip all mapping when no nested/json fields exist. */ _define_property$1(this, "_requiresMappings", void 0);
+		/** All non-ignored physical field names (for UniquSelect exclusion inversion). */ _define_property$1(this, "_allPhysicalFields", void 0);
+		/** Cached result of adapter.supportsNestedObjects(). */ _define_property$1(this, "_nestedObjects", void 0);
 		_define_property$1(this, "validators", void 0);
 		this._type = _type;
 		this.adapter = adapter;
@@ -480,6 +999,14 @@ 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._booleanFields = new Set();
+		this._requiresMappings = false;
+		this._allPhysicalFields = [];
 		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");
@@ -489,6 +1016,7 @@ else this._indexes.set(key, {
 		this.tableName = adapterName || dbTable || fallbackName;
 		if (!this.tableName) throw new Error("@db.table annotation or adapter-specific table name expected");
 		this.schema = _type.metadata.get("db.schema");
+		this._nestedObjects = adapter.supportsNestedObjects();
 		adapter.registerTable(this);
 	}
 };
@@ -539,6 +1067,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`.
 	*
@@ -586,6 +1122,46 @@ var BaseDbAdapter = class {
 		}
 		for (const name of existingNames) if (!desiredNames.has(name)) await opts.dropIndex(name);
 	}
+	/**
+	* Returns available search indexes for this adapter.
+	* UI uses this to show index picker. Override in adapters that support search.
+	*/ getSearchIndexes() {
+		return [];
+	}
+	/**
+	* Whether this adapter supports text search.
+	* Default: `true` when {@link getSearchIndexes} returns any entries.
+	*/ isSearchable() {
+		return this.getSearchIndexes().length > 0;
+	}
+	/**
+	* Full-text search. Override in adapters that support search.
+	*
+	* @param text - Search text.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional search index to target.
+	*/ async search(text, query, indexName) {
+		throw new Error("Search not supported by this adapter");
+	}
+	/**
+	* Full-text search with count (for paginated search results).
+	*
+	* @param text - Search text.
+	* @param query - Filter, sort, limit, etc.
+	* @param indexName - Optional search index to target.
+	*/ async searchWithCount(text, query, indexName) {
+		throw new Error("Search not supported by this adapter");
+	}
+	/**
+	* Fetches records and total count in one call.
+	* Default: two parallel calls. Adapters may override for single-query optimization.
+	*/ async findManyWithCount(query) {
+		const [data, count] = await Promise.all([this.findMany(query), this.count(query)]);
+		return {
+			data,
+			count
+		};
+	}
 	constructor() {
 		_define_property(this, "_table", void 0);
 	}
@@ -595,6 +1171,7 @@ var BaseDbAdapter = class {
 exports.AtscriptDbTable = AtscriptDbTable
 exports.BaseDbAdapter = BaseDbAdapter
 exports.NoopLogger = NoopLogger
+exports.UniquSelect = UniquSelect
 exports.decomposePatch = decomposePatch
 exports.getKeyProps = getKeyProps
 Object.defineProperty(exports, 'isPrimitive', {