@atscript/utils-db 0.1.28

package/dist/index.d.ts

@@ -0,0 +1,488 @@
+import { TAtscriptAnnotatedType, TValidatorPlugin, TMetadataMap, TAtscriptDataType, Validator, TAtscriptTypeObject, TValidatorOptions, TAtscriptTypeArray } from '@atscript/typescript/utils';
+
+/**
+ * Comparison and set operators for a single field value.
+ * Used inside filter objects: `{ age: { $gt: 18, $lt: 65 } }`.
+ */
+type TFilterOperators<V = unknown> = {
+    $gt?: V;
+    $gte?: V;
+    $lt?: V;
+    $lte?: V;
+    $ne?: V | null;
+    $in?: V[];
+    $nin?: V[];
+    $exists?: boolean;
+    $regex?: string;
+};
+/**
+ * Typed filter for database queries. Root-level keys from `T` get
+ * autocompletion and value type checking. Arbitrary string keys
+ * (e.g. dot-notation paths like `"address.city"`) are allowed via
+ * index signature fallback.
+ *
+ * When used without a type parameter, behaves as `Record<string, unknown>`.
+ *
+ * @example
+ * ```typescript
+ * // Typed — autocompletion + value checking
+ * const filter: TDbFilter<User> = { name: 'John', age: { $gt: 18 } }
+ *
+ * // Dot-notation — accepted via string fallback
+ * const filter2: TDbFilter<User> = { 'address.city': 'NYC' }
+ * ```
+ */
+type TDbFilter<T = Record<string, unknown>> = {
+    [K in keyof T & string]?: T[K] | TFilterOperators<T[K]> | null;
+} & Record<string, unknown> & {
+    $and?: Array<TDbFilter<T>>;
+    $or?: Array<TDbFilter<T>>;
+    $not?: TDbFilter<T>;
+};
+/**
+ * Projection for selecting/excluding fields.
+ * Accepts either an object `{ name: 1, email: 1 }` or an array `['name', 'email']`.
+ * Root-level keys get autocompletion, arbitrary strings allowed for dot-notation.
+ */
+type TDbProjection<T = Record<string, unknown>> = (Partial<Record<keyof T & string, 0 | 1>> & Record<string, 0 | 1>) | (keyof T & string | string)[];
+/**
+ * Options for find operations: sort, pagination, projection.
+ * Root-level keys get autocompletion, arbitrary strings allowed for dot-notation.
+ */
+interface TDbFindOptions<T = Record<string, unknown>> {
+    sort?: Partial<Record<keyof T & string, 1 | -1>> & Record<string, 1 | -1>;
+    skip?: number;
+    limit?: number;
+    projection?: TDbProjection<T>;
+}
+interface TDbInsertResult {
+    insertedId: unknown;
+}
+interface TDbInsertManyResult {
+    insertedCount: number;
+    insertedIds: unknown[];
+}
+interface TDbUpdateResult {
+    matchedCount: number;
+    modifiedCount: number;
+}
+interface TDbDeleteResult {
+    deletedCount: number;
+}
+interface TDbIndexField {
+    name: string;
+    sort: 'asc' | 'desc';
+}
+interface TDbIndex {
+    /** Unique key used for identity/diffing (e.g., "atscript__plain__email") */
+    key: string;
+    /** Human-readable index name. */
+    name: string;
+    /** Index type. */
+    type: 'plain' | 'unique' | 'fulltext';
+    /** Ordered list of fields in the index. */
+    fields: TDbIndexField[];
+}
+type TDbDefaultValue = {
+    kind: 'value';
+    value: string;
+} | {
+    kind: 'fn';
+    fn: 'increment' | 'uuid' | 'now';
+};
+interface TIdDescriptor {
+    /** Field names that form the primary key. */
+    fields: string[];
+    /** Whether this is a composite key (multiple fields). */
+    isComposite: boolean;
+}
+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). */
+    physicalName: string;
+    /** Resolved design type: 'string', 'number', 'boolean', 'object', etc. */
+    designType: string;
+    /** Whether the field is optional. */
+    optional: boolean;
+    /** Whether this field is part of the primary key (@meta.id). */
+    isPrimaryKey: boolean;
+    /** Whether this field is excluded from the DB (@db.ignore). */
+    ignored: boolean;
+    /** Default value from @db.default.* */
+    defaultValue?: TDbDefaultValue;
+}
+
+/**
+ * Abstract base class for database adapters.
+ *
+ * Adapter instances are 1:1 with table instances. When an {@link AtscriptDbTable}
+ * is created with an adapter, it calls {@link registerTable} to establish a
+ * bidirectional relationship:
+ *
+ * ```
+ * AtscriptDbTable ──delegates CRUD──▶ BaseDbAdapter
+ *                 ◀──reads metadata── (via this._table)
+ * ```
+ *
+ * Adapter authors can access all computed metadata through `this._table`:
+ * - `this._table.tableName` — resolved table/collection name
+ * - `this._table.flatMap` — all fields as dot-notation paths
+ * - `this._table.indexes` — computed index definitions
+ * - `this._table.primaryKeys` — primary key field names
+ * - `this._table.columnMap` — logical → physical column mappings
+ * - `this._table.defaults` — default value configurations
+ * - `this._table.ignoredFields` — fields excluded from DB
+ * - `this._table.uniqueProps` — single-field unique index properties
+ */
+declare abstract class BaseDbAdapter {
+    protected _table: AtscriptDbTable;
+    /**
+     * Called by {@link AtscriptDbTable} constructor. Gives the adapter access to
+     * the table's computed metadata for internal use in query rendering, index
+     * sync, etc.
+     */
+    registerTable(table: AtscriptDbTable): void;
+    /**
+     * Returns additional validator plugins for this adapter.
+     * These are merged with the built-in Atscript validators.
+     *
+     * Example: MongoDB adapter returns ObjectId validation plugin.
+     */
+    getValidatorPlugins(): TValidatorPlugin[];
+    /**
+     * Transforms an ID value for the database.
+     * Override to convert string → ObjectId, parse numeric IDs, etc.
+     *
+     * @param id - The raw ID value.
+     * @param fieldType - The annotated type of the ID field.
+     * @returns The transformed ID value.
+     */
+    prepareId(id: unknown, fieldType: TAtscriptAnnotatedType): unknown;
+    /**
+     * Whether this adapter supports native patch operations.
+     * When `true`, {@link AtscriptDbTable} delegates patch payloads to
+     * {@link nativePatch} instead of using the generic decomposition.
+     */
+    supportsNativePatch(): boolean;
+    /**
+     * Applies a patch payload using native database operations.
+     * Only called when {@link supportsNativePatch} returns `true`.
+     *
+     * @param filter - Filter identifying the record to patch.
+     * @param patch - The patch payload with array operations.
+     * @returns Update result.
+     */
+    nativePatch(filter: TDbFilter, patch: unknown): Promise<TDbUpdateResult>;
+    /**
+     * Called before field flattening begins.
+     * Use to extract table-level adapter-specific annotations.
+     *
+     * Example: MongoDB adapter extracts `@db.mongo.search.dynamic`.
+     */
+    onBeforeFlatten?(type: TAtscriptAnnotatedType): void;
+    /**
+     * 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`.
+     */
+    onFieldScanned?(field: string, type: TAtscriptAnnotatedType, metadata: TMetadataMap<AtscriptMetadata>): void;
+    /**
+     * Called after all fields are scanned.
+     * Use to finalize adapter-specific computed state.
+     * Access table metadata via `this._table`.
+     */
+    onAfterFlatten?(): void;
+    /**
+     * Returns an adapter-specific table name.
+     * For example, MongoDB reads from `@db.mongo.collection`.
+     * Return `undefined` to fall back to `@db.table` or the interface name.
+     */
+    getAdapterTableName?(type: TAtscriptAnnotatedType): string | undefined;
+    /**
+     * Returns the metadata tag used to mark top-level arrays during flattening.
+     * Default: `'db.__topLevelArray'`
+     *
+     * Override to use adapter-specific tags (e.g., `'db.mongo.__topLevelArray'`).
+     */
+    getTopLevelArrayTag?(): string;
+    /**
+     * Resolves the full table name, optionally including the schema prefix.
+     * Override for databases that don't support schemas (e.g., SQLite).
+     *
+     * @param includeSchema - Whether to prepend `schema.` prefix (default: true).
+     */
+    resolveTableName(includeSchema?: boolean): string;
+    /**
+     * Template method for index synchronization.
+     * Implements the diff algorithm (list → compare → create/drop).
+     * Adapters provide the three DB-specific primitives.
+     *
+     * @example
+     * ```typescript
+     * async syncIndexes() {
+     *   await this.syncIndexesWithDiff({
+     *     listExisting: async () => this.driver.all('PRAGMA index_list(...)'),
+     *     createIndex: async (index) => this.driver.exec('CREATE INDEX ...'),
+     *     dropIndex: async (name) => this.driver.exec('DROP INDEX ...'),
+     *     shouldSkipType: (type) => type === 'fulltext',
+     *   })
+     * }
+     * ```
+     */
+    protected syncIndexesWithDiff(opts: {
+        listExisting(): Promise<Array<{
+            name: string;
+        }>>;
+        createIndex(index: TDbIndex): Promise<void>;
+        dropIndex(name: string): Promise<void>;
+        prefix?: string;
+        shouldSkipType?(type: TDbIndex['type']): boolean;
+    }): Promise<void>;
+    abstract insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
+    abstract insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+    abstract replaceOne(filter: TDbFilter, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    abstract updateOne(filter: TDbFilter, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    abstract deleteOne(filter: TDbFilter): Promise<TDbDeleteResult>;
+    abstract findOne(filter: TDbFilter, options?: TDbFindOptions): Promise<Record<string, unknown> | null>;
+    abstract findMany(filter: TDbFilter, options?: TDbFindOptions): Promise<Array<Record<string, unknown>>>;
+    abstract count(filter: TDbFilter): Promise<number>;
+    abstract updateMany(filter: TDbFilter, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    abstract replaceMany(filter: TDbFilter, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    abstract deleteMany(filter: TDbFilter): Promise<TDbDeleteResult>;
+    /**
+     * Synchronizes indexes between the Atscript definitions and the database.
+     * Uses `this._table.indexes` for the full index definitions.
+     */
+    abstract syncIndexes(): Promise<void>;
+    /**
+     * Ensures the table exists in the database, creating it if needed.
+     * Uses `this._table.tableName`, `this._table.schema`, etc.
+     */
+    abstract ensureTable(): Promise<void>;
+}
+
+interface TGenericLogger {
+    error(...messages: any[]): void;
+    warn(...messages: any[]): void;
+    log(...messages: any[]): void;
+    info(...messages: any[]): void;
+    debug(...messages: any[]): void;
+}
+declare const NoopLogger: TGenericLogger;
+
+/**
+ * Resolves the design type from an annotated type.
+ * Encapsulates the `kind === ''` check and fallback logic that
+ * otherwise trips up every adapter author.
+ */
+declare function resolveDesignType(fieldType: TAtscriptAnnotatedType): string;
+/**
+ * Generic database table abstraction driven by Atscript `@db.*` annotations.
+ *
+ * Accepts an annotated type marked with `@db.table` and a {@link BaseDbAdapter}
+ * instance. Pre-computes indexes, column mappings, defaults, and primary keys
+ * from annotations, then delegates actual database operations to the adapter.
+ *
+ * This class is **concrete** (not abstract) — extend it for cross-cutting
+ * concerns like field-level permissions, audit logging, etc. Extensions
+ * work with any adapter.
+ *
+ * ```typescript
+ * const adapter = new MongoAdapter(db)
+ * const users = new AtscriptDbTable(UsersType, adapter)
+ * await users.insertOne({ name: 'John', email: 'john@example.com' })
+ * ```
+ *
+ * @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>> {
+    protected readonly _type: T;
+    protected readonly adapter: BaseDbAdapter;
+    protected readonly logger: TGenericLogger;
+    /** Resolved table/collection name. */
+    readonly tableName: string;
+    /** Database schema/namespace from `@db.schema` (if set). */
+    readonly schema: string | undefined;
+    protected _flatMap?: Map<string, TAtscriptAnnotatedType>;
+    protected _fieldDescriptors?: TDbFieldMeta[];
+    protected _indexes: Map<string, TDbIndex>;
+    protected _primaryKeys: string[];
+    protected _columnMap: Map<string, string>;
+    protected _defaults: Map<string, TDbDefaultValue>;
+    protected _ignoredFields: Set<string>;
+    protected _uniqueProps: Set<string>;
+    protected readonly validators: Map<string, Validator<T, DataType>>;
+    constructor(_type: T, adapter: BaseDbAdapter, logger?: TGenericLogger);
+    /** The raw annotated type. */
+    get type(): TAtscriptAnnotatedType<TAtscriptTypeObject>;
+    /** Lazily-built flat map of all fields (dot-notation paths → annotated types). */
+    get flatMap(): Map<string, TAtscriptAnnotatedType>;
+    /** All computed indexes from `@db.index.*` annotations. */
+    get indexes(): Map<string, TDbIndex>;
+    /** Primary key field names from `@meta.id`. */
+    get primaryKeys(): readonly string[];
+    /** Logical → physical column name mapping from `@db.column`. */
+    get columnMap(): ReadonlyMap<string, string>;
+    /** Default values from `@db.default.*`. */
+    get defaults(): ReadonlyMap<string, TDbDefaultValue>;
+    /** Fields excluded from DB via `@db.ignore`. */
+    get ignoredFields(): ReadonlySet<string>;
+    /** Single-field unique index properties. */
+    get uniqueProps(): ReadonlySet<string>;
+    /** Descriptor for the primary ID field(s). */
+    getIdDescriptor(): TIdDescriptor;
+    /**
+     * Pre-computed field metadata for adapter use.
+     * Filters root entry, resolves designType, physicalName, optional —
+     * encapsulating all the type introspection gotchas.
+     */
+    get fieldDescriptors(): readonly TDbFieldMeta[];
+    /**
+     * Resolves a projection to a list of field names to include.
+     * - `undefined` → `undefined` (all fields)
+     * - `string[]` → pass through
+     * - `Record<K, 1>` → extract included keys
+     * - `Record<K, 0>` → invert using known field names
+     */
+    resolveProjection(projection?: TDbProjection<DataType>): string[] | undefined;
+    /**
+     * Creates a new validator with custom options.
+     * Adapter plugins are NOT automatically included — use {@link getValidator}
+     * for the standard validator with adapter plugins.
+     */
+    createValidator(opts?: Partial<TValidatorOptions>): Validator<T, DataType>;
+    /**
+     * Returns a cached validator for the given purpose.
+     * Built with adapter plugins from {@link BaseDbAdapter.getValidatorPlugins}.
+     *
+     * Standard purposes: `'insert'`, `'update'`, `'patch'`.
+     * Adapters may define additional purposes.
+     */
+    getValidator(purpose: string): Validator<T, DataType>;
+    /**
+     * Inserts a single record.
+     * Applies defaults, validates, prepares ID, maps columns, strips ignored fields.
+     */
+    insertOne(payload: Partial<DataType> & Record<string, unknown>): Promise<TDbInsertResult>;
+    /**
+     * Inserts multiple records.
+     */
+    insertMany(payloads: Array<Partial<DataType> & Record<string, unknown>>): Promise<TDbInsertManyResult>;
+    /**
+     * Replaces a single record identified by primary key(s).
+     * The payload must include primary key field(s).
+     */
+    replaceOne(payload: DataType & Record<string, unknown>): Promise<TDbUpdateResult>;
+    /**
+     * Partially updates a single record identified by primary key(s).
+     * Supports array patch operations (`$replace`, `$insert`, `$upsert`,
+     * `$update`, `$remove`) for top-level array fields.
+     */
+    updateOne(payload: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
+    /**
+     * Deletes a single record by primary key value.
+     */
+    deleteOne(id: unknown): Promise<TDbDeleteResult>;
+    /**
+     * Finds a single record matching the filter.
+     */
+    findOne(filter: TDbFilter<DataType>, options?: TDbFindOptions<DataType>): Promise<DataType | null>;
+    /**
+     * Finds all records matching the filter.
+     */
+    findMany(filter: TDbFilter<DataType>, options?: TDbFindOptions<DataType>): Promise<DataType[]>;
+    /**
+     * Counts records matching the filter.
+     */
+    count(filter?: TDbFilter<DataType>): Promise<number>;
+    updateMany(filter: TDbFilter<DataType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
+    replaceMany(filter: TDbFilter<DataType>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+    deleteMany(filter: TDbFilter<DataType>): Promise<TDbDeleteResult>;
+    /**
+     * Synchronizes indexes between Atscript definitions and the database.
+     * Delegates to the adapter, which uses `this._table.indexes`.
+     */
+    syncIndexes(): Promise<void>;
+    /**
+     * Ensures the table/collection exists in the database.
+     */
+    ensureTable(): Promise<void>;
+    protected _flatten(): void;
+    /**
+     * 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;
+    private _finalizeIndexes;
+    /**
+     * Applies default values for fields that are missing from the payload.
+     * Called before validation so that defaults satisfy required field constraints.
+     */
+    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.
+     * Defaults should be applied before this via `_applyDefaults`.
+     */
+    protected _prepareForWrite(payload: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Extracts primary key field(s) from a payload to build a filter.
+     */
+    protected _extractPrimaryKeyFilter(payload: Record<string, unknown>): TDbFilter;
+    /**
+     * Builds a validator for a given purpose with adapter plugins.
+     */
+    protected _buildValidator(purpose: string): Validator<T, DataType>;
+}
+
+/**
+ * Decomposes a patch payload into a flat update object for adapters
+ * that don't support native patch operations.
+ *
+ * Handles:
+ * - Top-level array patches (`$replace`, `$insert`, `$upsert`, `$update`, `$remove`)
+ * - Merge strategy for nested objects
+ * - Simple field sets
+ *
+ * For adapters with native patch support (e.g., MongoDB aggregation pipelines),
+ * use {@link BaseDbAdapter.nativePatch} instead.
+ *
+ * @param payload - The patch payload from the user.
+ * @param table - The AtscriptDbTable instance for metadata access.
+ * @returns A flat update object suitable for a basic `updateOne` call.
+ */
+declare function decomposePatch(payload: Record<string, unknown>, table: AtscriptDbTable): Record<string, unknown>;
+
+interface TArrayPatch<A extends readonly unknown[]> {
+    $replace?: A;
+    $insert?: A;
+    $upsert?: A;
+    $update?: Array<Partial<TArrayElement<A>>>;
+    $remove?: Array<Partial<TArrayElement<A>>>;
+}
+type TArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends ReadonlyArray<infer ElementType> ? ElementType : never;
+/**
+ * Maps each property of T into a patch payload:
+ * - Array properties become `TArrayPatch<T[K]>`
+ * - Non-array properties become `Partial<T[K]>`
+ */
+type TDbPatch<T> = {
+    [K in keyof T]?: T[K] extends Array<infer _> ? TArrayPatch<T[K]> : Partial<T[K]>;
+};
+/**
+ * Extracts `@expect.array.key` properties from an array-of-objects type.
+ * These keys uniquely identify an element inside the array and are used
+ * for `$update`, `$remove`, and `$upsert` operations.
+ *
+ * @param def - Atscript array type definition.
+ * @returns Set of property names marked as keys; empty set if none.
+ */
+declare function getKeyProps(def: TAtscriptAnnotatedType<TAtscriptTypeArray>): Set<string>;
+
+export { AtscriptDbTable, BaseDbAdapter, NoopLogger, decomposePatch, getKeyProps, resolveDesignType };
+export type { TArrayPatch, TDbDefaultValue, TDbDeleteResult, TDbFieldMeta, TDbFilter, TDbFindOptions, TDbIndex, TDbIndexField, TDbInsertManyResult, TDbInsertResult, TDbPatch, TDbProjection, TDbUpdateResult, TFilterOperators, TGenericLogger, TIdDescriptor };