@atscript/utils-db 0.1.31 → 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;
@@ -179,13 +281,13 @@ var AtscriptDbTable = class {
 		this._flatten();
 		if (!this._fieldDescriptors) {
 			this._fieldDescriptors = [];
-			const skipFlattening = this.adapter.supportsNestedObjects();
+			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._findJsonParent(path) !== undefined) continue;
+				if (!skipFlattening && this._findAncestorInSet(path, this._jsonFields) !== undefined) continue;
 				const isJson = this._jsonFields.has(path);
-				const isFlattened = !skipFlattening && this._findFlattenedParent(path) !== undefined;
+				const isFlattened = !skipFlattening && this._findAncestorInSet(path, this._flattenedParents) !== undefined;
 				const designType = isJson ? "json" : resolveDesignType(type);
 				let storage;
 				if (skipFlattening) storage = "column";
@@ -206,33 +308,11 @@ else storage = "column";
 					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 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.
 	* Adapter plugins are NOT automatically included — use {@link getValidator}
 	* for the standard validator with adapter plugins.
@@ -345,6 +425,106 @@ else storage = "column";
 		});
 		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) {
 		this._flatten();
 		return this.adapter.updateMany(this._translateFilter(filter), this._prepareForWrite({ ...data }));
@@ -381,9 +561,12 @@ else storage = "column";
 				this.adapter.onFieldScanned?.(path, type, metadata);
 			}
 		});
-		if (!this.adapter.supportsNestedObjects()) this._classifyFields();
+		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.
@@ -405,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;
@@ -413,7 +596,8 @@ 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);
@@ -421,13 +605,14 @@ else if (defaultFn !== undefined) this._defaults.set(fieldName, {
 			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,
@@ -458,11 +643,13 @@ else if (isObject && isJson) {} else if (isObject && !isJson) this._flattenedPar
 		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;
+			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}.`;
@@ -473,24 +660,13 @@ else if (isObject && isJson) {} else if (isObject && !isJson) this._flattenedPar
 		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) {
+	* 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 (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;
+			if (set.has(ancestor)) return ancestor;
 		}
 		return undefined;
 	}
@@ -503,7 +679,20 @@ else if (isObject && isJson) {} else if (isObject && !isJson) this._flattenedPar
 	* 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;
 	}
@@ -518,7 +707,7 @@ else if (isObject && isJson) {} else if (isObject && !isJson) this._flattenedPar
 			if (fieldType) data[pk] = this.adapter.prepareId(data[pk], fieldType);
 		}
 		for (const field of this._ignoredFields) if (!field.includes(".")) delete data[field];
-		if (!this._requiresMappings || this.adapter.supportsNestedObjects()) {
+		if (!this._requiresMappings || this._nestedObjects) {
 			for (const [logical, physical] of this._columnMap.entries()) if (logical in data) {
 				data[physical] = data[logical];
 				delete data[logical];
@@ -533,40 +722,26 @@ else if (isObject && isJson) {} else if (isObject && !isJson) this._flattenedPar
 	* 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;
-			}
-		}
+		for (const key of Object.keys(data)) this._writeFlattenedField(key, data[key], result);
 		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;
+	* 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;
 		}
 	}
 	/**
@@ -579,11 +754,11 @@ else if (typeof value === "object" && !Array.isArray(value)) this._flattenObject
 	* 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;
+		if (!this._requiresMappings || this._nestedObjects) return this._coerceBooleans(row);
 		const result = {};
 		const rowKeys = Object.keys(row);
 		for (const physical of rowKeys) {
-			const value = row[physical];
+			const value = this._booleanFields.has(physical) ? toBool(row[physical]) : row[physical];
 			const logicalPath = this._physicalToPath.get(physical);
 			if (!logicalPath) {
 				result[physical] = value;
@@ -599,6 +774,14 @@ else result[logicalPath] = value;
 		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(".");
@@ -639,12 +822,21 @@ else result[logicalPath] = value;
 	/**
 	* 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.adapter.supportsNestedObjects()) return 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) : query.controls,
-			insights: query.insights
+			controls: query.controls ? this._translateControls(query.controls) : {}
 		};
 	}
 	/**
@@ -668,9 +860,13 @@ else {
 	}
 	/**
 	* Translates field names in sort and projection controls.
+	* Wraps `$select` in {@link UniquSelect} after path translation.
 	*/ _translateControls(controls) {
-		if (!controls) return controls;
-		const result = { ...controls };
+		if (!controls) return {};
+		const result = {
+			...controls,
+			$select: undefined
+		};
 		if (controls.$sort) {
 			const translated = {};
 			const sortObj = controls.$sort;
@@ -682,35 +878,39 @@ else {
 			}
 			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);
+		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);
-			}
-			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;
+				}
+				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;
+						const physical = this._pathToPhysical.get(key) ?? key;
+						translated[physical] = val;
+					}
 				}
+				translatedRaw = translated;
 			}
-			result.$select = 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.adapter.supportsNestedObjects()) return update;
+		if (!this._requiresMappings || this._nestedObjects) return update;
 		const result = {};
 		const updateKeys = Object.keys(update);
 		for (const key of updateKeys) {
@@ -743,21 +943,26 @@ else result[finalKey] = value;
 	*/ _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 });
 		}
 	}
@@ -780,7 +985,10 @@ else result[finalKey] = value;
 		/** 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;
@@ -796,7 +1004,9 @@ else result[finalKey] = value;
 		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");
@@ -806,6 +1016,7 @@ else result[finalKey] = value;
 		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);
 	}
 };
@@ -911,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);
 	}
@@ -920,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', {