@atscript/db 0.1.39 → 0.1.40

package/dist/index.d.cts

@@ -0,0 +1,137 @@
+import { $ as Uniquery, A as TDbForeignKey, B as TExistingColumn, C as TCascadeTarget, D as TDbDefaultValue, E as TDbDefaultFn, F as TDbInsertResult, G as TMetadataOverrides, H as TFkLookupResolver, I as TDbReferentialAction, J as TTableOptionDiff, K as TSearchIndexInfo, L as TDbRelation, M as TDbIndexField, N as TDbIndexType, O as TDbDeleteResult, P as TDbInsertManyResult, Q as TypedWithRelation, R as TDbStorageType, S as TCascadeResolver, T as TDbCollation, U as TFkLookupTarget, V as TExistingTableOption, W as TIdDescriptor, X as TValueFormatterPair, Y as TTableResolver, Z as TWriteTableResolver, _ as DbQuery, a as FieldMappingStrategy, b as NavPropsOf, c as NoopLogger, d as AggregateExpr, et as UniqueryControls, f as AggregateFn, g as DbControls, h as AtscriptDbWritable, i as DocumentFieldMapper, j as TDbIndex, k as TDbFieldMeta, l as TGenericLogger, m as AggregateResult, n as DbResponse, nt as UniquSelect, o as BaseDbAdapter, p as AggregateQuery, q as TSyncColumnResult, r as resolveDesignType, s as TableMetadata, t as AtscriptDbReadable, tt as WithRelation, u as AggregateControls, v as FieldOpsFor, w as TColumnDiff, x as OwnPropsOf, y as FilterExpr, z as TDbUpdateResult } from "./db-readable-BQQzfguJ.cjs";
+import { d as getDbFieldOp, f as isDbFieldOp, l as TDbFieldOp, p as separateFieldOps, u as TFieldOps } from "./ops-DXJ4Zw0P.cjs";
+import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-Vxpcnyt5.cjs";
+import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-07kDiis2.cjs";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+import { TAtscriptAnnotatedType, TAtscriptTypeArray } from "@atscript/typescript/utils";
+
+//#region src/strategies/relational-field-mapper.d.ts
+/**
+ * Field mapper for relational adapters (e.g. SQLite, MySQL).
+ * Flattens nested objects to `__`-separated column names and
+ * reconstructs them on read. Applies full physical-name translation
+ * for queries, filters, and controls.
+ */
+declare class RelationalFieldMapper extends FieldMappingStrategy {
+  reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  translateQuery(query: Uniquery$1, meta: TableMetadata): DbQuery;
+  translateAggregateQuery(query: AggregateQuery$1, meta: TableMetadata): DbQuery;
+  /**
+   * Translates filter with key renaming from logical to physical names.
+   * Used by the relational query path where field paths must be mapped
+   * to `__`-separated column names.
+   */
+  translateFilterWithRename(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
+  prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
+  translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  /**
+   * Translates field names in sort and projection controls from
+   * logical dot-paths to physical column names.
+   */
+  private translateControls;
+  /**
+   * Flattens nested object fields into __-separated keys and
+   * JSON-stringifies @db.json / array fields.
+   */
+  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;
+}
+//#endregion
+//#region src/strategies/application-integrity.d.ts
+/**
+ * Integrity strategy for adapters without native FK support (e.g. MongoDB).
+ * Validates FK constraints and executes cascade/setNull actions at
+ * the application level.
+ */
+declare class ApplicationIntegrity extends IntegrityStrategy {
+  /**
+   * Validates FK constraints by querying target tables for referenced records.
+   * Collects unique FK values across items, batches them into target-table
+   * lookups, and throws FK_VIOLATION if any references are missing.
+   */
+  validateForeignKeys(items: Array<Record<string, unknown>>, meta: TableMetadata, fkLookupResolver: TFkLookupResolver | undefined, writeTableResolver: TWriteTableResolver | undefined, partial?: boolean, excludeTargetTable?: string): Promise<void>;
+  /**
+   * Applies cascade/setNull actions on child tables before deleting parent records.
+   * Finds all records matching `filter`, extracts their PK values, then for each
+   * child table with a FK pointing to this table:
+   * - `restrict`: throws if any children exist
+   * - `cascade`: recursively deletes child records
+   * - `setNull`: sets FK fields to null
+   */
+  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<void>;
+  needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
+  private recordKey;
+  /**
+   * Builds a filter for child records whose FK matches the deleted parent's PK values.
+   */
+  private buildCascadeChildFilter;
+}
+//#endregion
+//#region src/db-error.d.ts
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY";
+declare class DbError extends Error {
+  readonly code: DbErrorCode;
+  readonly errors: Array<{
+    path: string;
+    message: string;
+  }>;
+  name: string;
+  constructor(code: DbErrorCode, errors: Array<{
+    path: string;
+    message: string;
+  }>, message?: string);
+}
+//#endregion
+//#region src/patch/patch-decomposer.d.ts
+/**
+ * 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>;
+//#endregion
+//#region src/patch/patch-types.d.ts
+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>;
+//#endregion
+export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TMetadataOverrides, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type WithRelation, computeInsights, createDbValidatorPlugin, decomposePatch, getDbFieldOp, getKeyProps, isDbFieldOp, isPrimitive, resolveDesignType, separateFieldOps, translateQueryTree, walkFilter };

package/dist/index.d.mts

@@ -0,0 +1,137 @@
+import { $ as Uniquery, A as TDbForeignKey, B as TExistingColumn, C as TCascadeTarget, D as TDbDefaultValue, E as TDbDefaultFn, F as TDbInsertResult, G as TMetadataOverrides, H as TFkLookupResolver, I as TDbReferentialAction, J as TTableOptionDiff, K as TSearchIndexInfo, L as TDbRelation, M as TDbIndexField, N as TDbIndexType, O as TDbDeleteResult, P as TDbInsertManyResult, Q as TypedWithRelation, R as TDbStorageType, S as TCascadeResolver, T as TDbCollation, U as TFkLookupTarget, V as TExistingTableOption, W as TIdDescriptor, X as TValueFormatterPair, Y as TTableResolver, Z as TWriteTableResolver, _ as DbQuery, a as FieldMappingStrategy, b as NavPropsOf, c as NoopLogger, d as AggregateExpr, et as UniqueryControls, f as AggregateFn, g as DbControls, h as AtscriptDbWritable, i as DocumentFieldMapper, j as TDbIndex, k as TDbFieldMeta, l as TGenericLogger, m as AggregateResult, n as DbResponse, nt as UniquSelect, o as BaseDbAdapter, p as AggregateQuery, q as TSyncColumnResult, r as resolveDesignType, s as TableMetadata, t as AtscriptDbReadable, tt as WithRelation, u as AggregateControls, v as FieldOpsFor, w as TColumnDiff, x as OwnPropsOf, y as FilterExpr, z as TDbUpdateResult } from "./db-readable-Bbr4CjMb.mjs";
+import { d as getDbFieldOp, f as isDbFieldOp, l as TDbFieldOp, p as separateFieldOps, u as TFieldOps } from "./ops-BdRAFLKY.mjs";
+import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-BUrQ5BFm.mjs";
+import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-CiqsHTI_.mjs";
+import { TAtscriptAnnotatedType, TAtscriptTypeArray } from "@atscript/typescript/utils";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
+
+//#region src/strategies/relational-field-mapper.d.ts
+/**
+ * Field mapper for relational adapters (e.g. SQLite, MySQL).
+ * Flattens nested objects to `__`-separated column names and
+ * reconstructs them on read. Applies full physical-name translation
+ * for queries, filters, and controls.
+ */
+declare class RelationalFieldMapper extends FieldMappingStrategy {
+  reconstructFromRead(row: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  translateQuery(query: Uniquery$1, meta: TableMetadata): DbQuery;
+  translateAggregateQuery(query: AggregateQuery$1, meta: TableMetadata): DbQuery;
+  /**
+   * Translates filter with key renaming from logical to physical names.
+   * Used by the relational query path where field paths must be mapped
+   * to `__`-separated column names.
+   */
+  translateFilterWithRename(filter: FilterExpr$1, meta: TableMetadata): FilterExpr$1;
+  prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
+  translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  /**
+   * Translates field names in sort and projection controls from
+   * logical dot-paths to physical column names.
+   */
+  private translateControls;
+  /**
+   * Flattens nested object fields into __-separated keys and
+   * JSON-stringifies @db.json / array fields.
+   */
+  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;
+}
+//#endregion
+//#region src/strategies/application-integrity.d.ts
+/**
+ * Integrity strategy for adapters without native FK support (e.g. MongoDB).
+ * Validates FK constraints and executes cascade/setNull actions at
+ * the application level.
+ */
+declare class ApplicationIntegrity extends IntegrityStrategy {
+  /**
+   * Validates FK constraints by querying target tables for referenced records.
+   * Collects unique FK values across items, batches them into target-table
+   * lookups, and throws FK_VIOLATION if any references are missing.
+   */
+  validateForeignKeys(items: Array<Record<string, unknown>>, meta: TableMetadata, fkLookupResolver: TFkLookupResolver | undefined, writeTableResolver: TWriteTableResolver | undefined, partial?: boolean, excludeTargetTable?: string): Promise<void>;
+  /**
+   * Applies cascade/setNull actions on child tables before deleting parent records.
+   * Finds all records matching `filter`, extracts their PK values, then for each
+   * child table with a FK pointing to this table:
+   * - `restrict`: throws if any children exist
+   * - `cascade`: recursively deletes child records
+   * - `setNull`: sets FK fields to null
+   */
+  cascadeBeforeDelete(filter: FilterExpr$1, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr$1) => FilterExpr$1, adapter: BaseDbAdapter): Promise<void>;
+  needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
+  private recordKey;
+  /**
+   * Builds a filter for child records whose FK matches the deleted parent's PK values.
+   */
+  private buildCascadeChildFilter;
+}
+//#endregion
+//#region src/db-error.d.ts
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY";
+declare class DbError extends Error {
+  readonly code: DbErrorCode;
+  readonly errors: Array<{
+    path: string;
+    message: string;
+  }>;
+  name: string;
+  constructor(code: DbErrorCode, errors: Array<{
+    path: string;
+    message: string;
+  }>, message?: string);
+}
+//#endregion
+//#region src/patch/patch-decomposer.d.ts
+/**
+ * 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>;
+//#endregion
+//#region src/patch/patch-types.d.ts
+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>;
+//#endregion
+export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TMetadataOverrides, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type WithRelation, computeInsights, createDbValidatorPlugin, decomposePatch, getDbFieldOp, getKeyProps, isDbFieldOp, isPrimitive, resolveDesignType, separateFieldOps, translateQueryTree, walkFilter };