@atscript/utils-db 0.1.31 → 0.1.32

package/dist/index.d.ts

@@ -1,7 +1,53 @@
-import { TAtscriptAnnotatedType, TValidatorPlugin, TMetadataMap, TAtscriptDataType, FlatOf, 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,6 +92,7 @@ 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;
@@ -66,7 +116,7 @@ interface TDbFieldMeta {
      * - 'flattened': a leaf scalar from a flattened nested object
      * - 'json': stored as a single JSON column (arrays, @db.json fields)
      */
-    storage: 'column' | 'flattened' | 'json';
+    storage: TDbStorageType;
     /**
      * For flattened fields: the dot-notation path (same as `path`).
      * E.g., for physicalName 'contact__email', this is 'contact.email'.
@@ -143,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.
@@ -154,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;
     /**
@@ -209,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>;
@@ -267,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>, FlatType = FlatOf<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;
@@ -293,10 +398,18 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     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). */
@@ -305,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.*`. */
@@ -325,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}
@@ -370,7 +494,7 @@ 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.
      */
@@ -383,6 +507,47 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
      * Counts records matching the query.
      */
     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>;
@@ -400,7 +565,10 @@ 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.
@@ -408,15 +576,10 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
      */
     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.
+     * Finds the nearest ancestor of `path` that belongs to `set`.
+     * Used to locate flattened parents and @db.json ancestors.
      */
-    private _findJsonParent;
+    private _findAncestorInSet;
     private _finalizeIndexes;
     /**
      * Applies default values for fields that are missing from the payload.
@@ -436,9 +599,10 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
      */
     private _flattenPayload;
     /**
-     * Recursively flattens a nested object, writing physical keys to result.
+     * Classifies and writes a single field to the result object.
+     * Recurses into nested objects that should be flattened.
      */
-    private _flattenObject;
+    private _writeFlattenedField;
     /**
      * When a parent object is null/undefined, set all its flattened children to null.
      */
@@ -448,6 +612,11 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
      * 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.
      */
@@ -459,6 +628,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     /**
      * 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;
     /**
@@ -467,6 +637,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
     private _translateFilter;
     /**
      * Translates field names in sort and projection controls.
+     * Wraps `$select` in {@link UniquSelect} after path translation.
      */
     private _translateControls;
     /**
@@ -527,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 };