@atscript/utils-db 0.1.30 → 0.1.32

package/dist/index.d.ts

@@ -1,7 +1,53 @@
-import { TAtscriptAnnotatedType, TValidatorPlugin, TMetadataMap, TAtscriptDataType, Validator, TAtscriptTypeObject, TValidatorOptions, TAtscriptTypeArray } from '@atscript/typescript/utils';
-import { FilterExpr, Uniquery, UniqueryControls } from '@uniqu/core';
+import { TAtscriptAnnotatedType, TValidatorPlugin, TMetadataMap, TAtscriptDataType, FlatOf, PrimaryKeyOf, Validator, TAtscriptTypeObject, TValidatorOptions, TAtscriptTypeArray } from '@atscript/typescript/utils';
+import { UniqueryControls, FilterExpr, Uniquery } from '@uniqu/core';
 export { FieldOpsFor, FilterExpr, FilterVisitor, Uniquery, UniqueryControls, isPrimitive, walkFilter } from '@uniqu/core';
 
+/**
+ * Wraps a raw `$select` value and provides lazy-cached conversions
+ * to the forms different adapters need.
+ *
+ * Only instantiated when `$select` is actually provided —
+ * `controls.$select` is `UniquSelect | undefined`.
+ *
+ * For exclusion → inclusion inversion, pass `allFields` (physical field names).
+ */
+declare class UniquSelect {
+    private _raw;
+    private _allFields?;
+    private _arrayResolved;
+    private _array?;
+    private _projectionResolved;
+    private _projection?;
+    constructor(raw: UniqueryControls['$select'], allFields?: string[]);
+    /**
+     * Resolved inclusion array of field names.
+     * For exclusion form, inverts using `allFields` from constructor.
+     */
+    get asArray(): string[] | undefined;
+    /**
+     * Record projection preserving original semantics.
+     * Returns original object as-is if raw was object.
+     * Converts `string[]` to `{field: 1}` inclusion object.
+     */
+    get asProjection(): Record<string, 0 | 1> | undefined;
+}
+
+/** Controls with resolved projection. Used in the adapter interface. */
+interface DbControls extends Omit<UniqueryControls, '$select'> {
+    $select?: UniquSelect;
+}
+/** Query object with resolved projection. Passed to adapter methods. */
+interface DbQuery {
+    filter: FilterExpr;
+    controls: DbControls;
+}
+/** Describes an available search index exposed by a database adapter. */
+interface TSearchIndexInfo {
+    /** Index name. Empty string or 'DEFAULT' for the default index. */
+    name: string;
+    /** Human-readable label for UI display. */
+    description?: string;
+}
 interface TDbInsertResult {
     insertedId: unknown;
 }
@@ -16,9 +62,11 @@ interface TDbUpdateResult {
 interface TDbDeleteResult {
     deletedCount: number;
 }
+type TDbIndexType = 'plain' | 'unique' | 'fulltext';
 interface TDbIndexField {
     name: string;
     sort: 'asc' | 'desc';
+    weight?: number;
 }
 interface TDbIndex {
     /** Unique key used for identity/diffing (e.g., "atscript__plain__email") */
@@ -26,16 +74,17 @@ interface TDbIndex {
     /** Human-readable index name. */
     name: string;
     /** Index type. */
-    type: 'plain' | 'unique' | 'fulltext';
+    type: TDbIndexType;
     /** Ordered list of fields in the index. */
     fields: TDbIndexField[];
 }
+type TDbDefaultFn = 'increment' | 'uuid' | 'now';
 type TDbDefaultValue = {
     kind: 'value';
     value: string;
 } | {
     kind: 'fn';
-    fn: 'increment' | 'uuid' | 'now';
+    fn: TDbDefaultFn;
 };
 interface TIdDescriptor {
     /** Field names that form the primary key. */
@@ -43,14 +92,15 @@ interface TIdDescriptor {
     /** Whether this is a composite key (multiple fields). */
     isComposite: boolean;
 }
+type TDbStorageType = 'column' | 'flattened' | 'json';
 interface TDbFieldMeta {
     /** The dot-notation path to this field (logical name). */
     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 +110,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: TDbStorageType;
+    /**
+     * 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 +177,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`.
@@ -123,6 +193,24 @@ declare abstract class BaseDbAdapter {
      * @returns Update result.
      */
     nativePatch(filter: FilterExpr, patch: unknown): Promise<TDbUpdateResult>;
+    /**
+     * Builds a custom insert validator for this adapter.
+     * When defined, {@link AtscriptDbTable} uses this instead of the default
+     * insert validator (which makes all primary keys optional).
+     *
+     * Example: MongoDB only makes ObjectId primary keys optional (auto-generated),
+     * but string/number IDs remain required.
+     */
+    buildInsertValidator?(table: AtscriptDbTable): any;
+    /**
+     * Builds a custom patch validator for this adapter.
+     * When defined, {@link AtscriptDbTable} uses this instead of the default
+     * partial validator for the `'patch'` purpose.
+     *
+     * Example: MongoDB wraps top-level array fields with `$replace`/`$insert`/…
+     * patch operators that the default validator doesn't understand.
+     */
+    buildPatchValidator?(table: AtscriptDbTable): any;
     /**
      * Called before field flattening begins.
      * Use to extract table-level adapter-specific annotations.
@@ -134,7 +222,7 @@ declare abstract class BaseDbAdapter {
      * Called for each field during flattening.
      * Use to extract field-level adapter-specific annotations.
      *
-     * Example: MongoDB adapter extracts `@db.mongo.index.text`, `@db.mongo.search.vector`.
+     * Example: MongoDB adapter extracts `@db.mongo.search.vector`, `@db.mongo.search.text`.
      */
     onFieldScanned?(field: string, type: TAtscriptAnnotatedType, metadata: TMetadataMap<AtscriptMetadata>): void;
     /**
@@ -189,14 +277,51 @@ declare abstract class BaseDbAdapter {
         prefix?: string;
         shouldSkipType?(type: TDbIndex['type']): boolean;
     }): Promise<void>;
+    /**
+     * Returns available search indexes for this adapter.
+     * UI uses this to show index picker. Override in adapters that support search.
+     */
+    getSearchIndexes(): TSearchIndexInfo[];
+    /**
+     * Whether this adapter supports text search.
+     * Default: `true` when {@link getSearchIndexes} returns any entries.
+     */
+    isSearchable(): boolean;
+    /**
+     * 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.
+     */
+    search(text: string, query: DbQuery, indexName?: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * 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.
+     */
+    searchWithCount(text: string, query: DbQuery, indexName?: string): Promise<{
+        data: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    /**
+     * Fetches records and total count in one call.
+     * Default: two parallel calls. Adapters may override for single-query optimization.
+     */
+    findManyWithCount(query: DbQuery): Promise<{
+        data: Array<Record<string, unknown>>;
+        count: number;
+    }>;
     abstract insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
     abstract insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
     abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
     abstract updateOne(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
     abstract deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
-    abstract findOne(query: Uniquery): Promise<Record<string, unknown> | null>;
-    abstract findMany(query: Uniquery): Promise<Array<Record<string, unknown>>>;
-    abstract count(query: Uniquery): Promise<number>;
+    abstract findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
+    abstract findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+    abstract count(query: DbQuery): Promise<number>;
     abstract updateMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
     abstract replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
     abstract deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
@@ -247,9 +372,9 @@ 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>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>> {
     protected readonly _type: T;
-    protected readonly adapter: BaseDbAdapter;
+    protected readonly adapter: A;
     protected readonly logger: TGenericLogger;
     /** Resolved table/collection name. */
     readonly tableName: string;
@@ -263,8 +388,28 @@ 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[]>;
+    /** Physical column names of boolean fields (for storage coercion on read). */
+    protected _booleanFields: Set<string>;
+    /** Fast-path flag: skip all mapping when no nested/json fields exist. */
+    protected _requiresMappings: boolean;
+    /** All non-ignored physical field names (for UniquSelect exclusion inversion). */
+    protected _allPhysicalFields: string[];
+    /** Cached result of adapter.supportsNestedObjects(). */
+    protected readonly _nestedObjects: boolean;
     protected readonly validators: Map<string, Validator<T, DataType>>;
-    constructor(_type: T, adapter: BaseDbAdapter, logger?: TGenericLogger);
+    constructor(_type: T, adapter: A, logger?: TGenericLogger);
+    /** Returns the underlying adapter with its concrete type preserved. */
+    getAdapter(): A;
     /** The raw annotated type. */
     get type(): TAtscriptAnnotatedType<TAtscriptTypeObject>;
     /** Lazily-built flat map of all fields (dot-notation paths → annotated types). */
@@ -273,6 +418,25 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     get indexes(): Map<string, TDbIndex>;
     /** Primary key field names from `@meta.id`. */
     get primaryKeys(): readonly string[];
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * Registers a field as having a unique constraint.
+     * Used by adapters to ensure `findById` falls back to this field.
+     */
+    addUniqueField(field: string): void;
     /** Logical → physical column name mapping from `@db.column`. */
     get columnMap(): ReadonlyMap<string, string>;
     /** Default values from `@db.default.*`. */
@@ -281,6 +445,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;
     /**
@@ -289,14 +457,6 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
      * encapsulating all the type introspection gotchas.
      */
     get fieldDescriptors(): readonly TDbFieldMeta[];
-    /**
-     * 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?: UniqueryControls['$select']): string[] | undefined;
     /**
      * Creates a new validator with custom options.
      * Adapter plugins are NOT automatically included — use {@link getValidator}
@@ -334,22 +494,63 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     /**
      * Deletes a single record by primary key value.
      */
-    deleteOne(id: unknown): Promise<TDbDeleteResult>;
+    deleteOne(id: IdType): Promise<TDbDeleteResult>;
     /**
      * 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>;
+    /**
+     * Finds records and total count in a single logical call.
+     * Adapters may optimize into a single query (e.g., MongoDB `$facet`).
+     */
+    findManyWithCount(query: Uniquery<FlatType>): Promise<{
+        data: DataType[];
+        count: number;
+    }>;
+    /** Whether the underlying adapter supports text search. */
+    isSearchable(): boolean;
+    /** Returns available search indexes from the adapter. */
+    getSearchIndexes(): TSearchIndexInfo[];
+    /**
+     * 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.
+     */
+    search(text: string, query: Uniquery<FlatType>, indexName?: string): Promise<DataType[]>;
+    /**
+     * 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.
+     */
+    searchWithCount(text: string, query: Uniquery<FlatType>, indexName?: string): Promise<{
+        data: DataType[];
+        count: number;
+    }>;
+    /**
+     * 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.).
+     */
+    findById(id: unknown, controls?: UniqueryControls<FlatType>): Promise<DataType | null>;
+    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`.
@@ -364,7 +565,21 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
      * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
      */
     private _scanGenericAnnotations;
-    protected _addIndexField(type: TDbIndex['type'], name: string, field: string, sort?: 'asc' | 'desc'): void;
+    protected _addIndexField(type: TDbIndex['type'], name: string, field: string, opts?: {
+        sort?: 'asc' | 'desc';
+        weight?: number;
+    }): 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 of `path` that belongs to `set`.
+     * Used to locate flattened parents and @db.json ancestors.
+     */
+    private _findAncestorInSet;
     private _finalizeIndexes;
     /**
      * Applies default values for fields that are missing from the payload.
@@ -373,10 +588,62 @@ 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;
+    /**
+     * Classifies and writes a single field to the result object.
+     * Recurses into nested objects that should be flattened.
+     */
+    private _writeFlattenedField;
+    /**
+     * 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>;
+    /**
+     * Coerces boolean fields from storage representation (0/1) to JS booleans.
+     * Used on the fast-path when no column mapping is needed.
+     */
+    private _coerceBooleans;
+    /**
+     * 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.
+     * Always wraps `$select` in {@link UniquSelect}.
+     */
+    private _translateQuery;
+    /**
+     * Recursively translates field names in a filter expression.
+     */
+    private _translateFilter;
+    /**
+     * Translates field names in sort and projection controls.
+     * Wraps `$select` in {@link UniquSelect} after path translation.
+     */
+    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.
      */
@@ -431,5 +698,5 @@ type TDbPatch<T> = {
  */
 declare function getKeyProps(def: TAtscriptAnnotatedType<TAtscriptTypeArray>): Set<string>;
 
-export { AtscriptDbTable, BaseDbAdapter, NoopLogger, decomposePatch, getKeyProps, resolveDesignType };
-export type { TArrayPatch, TDbDefaultValue, TDbDeleteResult, TDbFieldMeta, TDbIndex, TDbIndexField, TDbInsertManyResult, TDbInsertResult, TDbPatch, TDbUpdateResult, TGenericLogger, TIdDescriptor };
+export { AtscriptDbTable, BaseDbAdapter, NoopLogger, UniquSelect, decomposePatch, getKeyProps, resolveDesignType };
+export type { DbControls, DbQuery, TArrayPatch, TDbDefaultFn, TDbDefaultValue, TDbDeleteResult, TDbFieldMeta, TDbIndex, TDbIndexField, TDbIndexType, TDbInsertManyResult, TDbInsertResult, TDbPatch, TDbStorageType, TDbUpdateResult, TGenericLogger, TIdDescriptor, TSearchIndexInfo };