joist-core 2.3.0 → 2.4.0-next.10

package/build/EntityManager.d.mts

@@ -0,0 +1,835 @@
+import { BatchLoader } from "./batchloaders/BatchLoader.mjs";
+import { OptsOf, OrderOf } from "./typeMap.mjs";
+import { Collection } from "./relations/Collection.mjs";
+import { lazyColumnLoadOperation } from "./relations/LazyField.mjs";
+import { Reference } from "./relations/Reference.mjs";
+import { IsLoadedCache } from "./loading/IsLoadedCache.mjs";
+import { OneToManyCollection } from "./relations/OneToManyCollection.mjs";
+import { ReactionLogger } from "./logging/ReactionLogger.mjs";
+import { ReactionsManager } from "./reactivity/ReactionsManager.mjs";
+import { JoinRows, ManyToManyLike } from "./flush/JoinRows.mjs";
+import { GraphQLFilterWithAlias } from "./queries/find/EntityGraphQLFilter.mjs";
+import { ExpressionFilter, FindFilter, UniqueFilter } from "./queries/find/EntityFilter.mjs";
+import { MaybePromise } from "./utils.mjs";
+import { LoadHint, Loaded, New } from "./loading/loadHints.mjs";
+import { ReactiveHint } from "./reactivity/reactiveHints.mjs";
+import { RowData } from "./RowData.mjs";
+import { EntityMetadata } from "./EntityMetadata.mjs";
+import { Lens } from "./loading/loadLens.mjs";
+import { CheckSetQuery, EntityQuery, QueryArg, QueryJoinInput, QueryRow, QuerySelect, QuerySource, QueryTable, ResolvedJoins, SetOperand, SetQuery, SetQueryRow } from "./queries/sql/query.mjs";
+import { PreloadPlugin } from "./plugins/PreloadPlugin.mjs";
+import { Driver } from "./drivers/Driver.mjs";
+import { CheckMutation, ExecuteResult, MutationInput, MutationRow } from "./queries/sql/execute.mjs";
+import { InstanceData } from "./InstanceData.mjs";
+import { PendingChange } from "./flush/PendingChanges.mjs";
+import { Plugin, PluginManager } from "./PluginManager.mjs";
+import { findOperation } from "./dataloaders/findDataLoader.mjs";
+import "./drivers/index.mjs";
+import { FieldLogger } from "./logging/FieldLogger.mjs";
+import { DeepPartialOrNull } from "./upsert.mjs";
+import { PartialOrNull } from "./index.mjs";
+import { enumCollectionLoadOperation } from "./batchloaders/enumCollectionBatchLoader.mjs";
+import { loadOperation } from "./batchloaders/loadBatchLoader.mjs";
+import { manyToManyLoadOperation } from "./batchloaders/manyToManyBatchLoader.mjs";
+import { oneToManyLoadOperation } from "./batchloaders/oneToManyBatchLoader.mjs";
+import { oneToOneLoadOperation } from "./batchloaders/oneToOneBatchLoader.mjs";
+import { populateOperation } from "./batchloaders/populateBatchLoader.mjs";
+import { recursiveChildrenOperation } from "./batchloaders/recursiveChildrenBatchLoader.mjs";
+import { recursiveM2mOperation } from "./batchloaders/recursiveM2mBatchLoader.mjs";
+import { recursiveParentsOperation } from "./batchloaders/recursiveParentsBatchLoader.mjs";
+import { findByUniqueOperation } from "./dataloaders/findByUniqueDataLoader.mjs";
+import { findCountOperation } from "./dataloaders/findCountDataLoader.mjs";
+import { findIdsOperation } from "./dataloaders/findIdsDataLoader.mjs";
+import { lensOperation } from "./dataloaders/lensDataLoader.mjs";
+import { manyToManyFindOperation } from "./dataloaders/manyToManyFindDataLoader.mjs";
+import { oneToManyFindOperation } from "./dataloaders/oneToManyFindDataLoader.mjs";
+import { IndexManager } from "./IndexManager.mjs";
+import { Entity, IdType } from "./Entity.mjs";
+import DataLoader, { BatchLoadFn, Options } from "dataloader";
+//#region src/EntityManager.d.ts
+/**
+ * The constructor for concrete entity types.
+ *
+ * Abstract entity types, like a base `Publisher` class that is marked `abstract`, cannot
+ * implement this and instead only have the `AbsEntityConstructor` type.
+ */
+interface EntityConstructor<T> {
+  /** The pseudo-public constructor for entities; only the `EntityManager` should actually instantiate entities. */
+  new (em: EntityManager<any, any, any>): T;
+  tagName: any;
+  metadata: EntityMetadata;
+  /** Returns the private `InstanceData` for the given entity. */
+  getInstanceData(entity: Entity): InstanceData;
+}
+/** Options for the auto-batchable `em.find` queries. */
+interface FindFilterOptions<T extends Entity> {
+  conditions?: ExpressionFilter;
+  orderBy?: OrderOf<T> | OrderOf<T>[];
+  limit?: number | undefined;
+  offset?: number | undefined;
+  softDeletes?: "include" | "exclude";
+  allowMultipleLeftJoins?: boolean;
+  optimizeJoinsToExists?: boolean;
+}
+interface FindGqlFilterOptions<T extends Entity> extends Omit<FindFilterOptions<T>, "limit" | "offset"> {
+  limit?: number | null | undefined;
+  offset?: number | null | undefined;
+}
+/** Options for the `findCount`. */
+interface FindCountFilterOptions<T extends Entity> {
+  conditions?: ExpressionFilter;
+  softDeletes?: "include" | "exclude";
+  allowMultipleLeftJoins?: boolean;
+  optimizeJoinsToExists?: boolean;
+}
+/**
+ * Constructors for either concrete or abstract entity types.
+ *
+ * I.e. this is more like "MaybeAbstractEntityConstructor".
+ */
+type MaybeAbstractEntityConstructor<T> = abstract new (em: EntityManager<any, any, any>, opts: any) => T;
+/** Pulls the entity's id type out of a given entity type T. */
+type IdOf<T> = T extends {
+  id: infer I;
+} ? I : never;
+type TaggedId = string;
+declare function isId(value: any): value is IdOf<unknown>;
+type EntityManagerHook = "beforeBegin" | "afterBegin" | "beforeCommit" | "afterCommit";
+type HookFn<TX> = (em: EntityManager, txn: TX) => MaybePromise<any>;
+type LoaderCache = Record<string, DataLoader<any, any>>;
+interface TimestampFields {
+  updatedAt: string | undefined;
+  createdAt: string | undefined;
+  deletedAt: string | undefined;
+}
+type EntityManagerOpts<TX = unknown> = ({
+  driver: Driver<TX>;
+  em?: undefined;
+} | {
+  driver?: undefined;
+  em: EntityManager<any, any, any>;
+}) & {
+  preloadPlugin?: PreloadPlugin;
+};
+interface FlushOptions {
+  /** Skip all validations, including reactive validations, when flushing */
+  skipValidation?: boolean;
+}
+/**
+ * Describes the EntityManager read/write mode.
+ *
+ * - `read-only` -- any entity mutations or `em.flush` calls will fail fast
+ * - `in-memory-writes` -- allows entity mutations and `em.flush` w/o a `COMMIT`
+ * - `writes` -- allows entity mutations and `em.flush` will `COMMIT` writes
+ */
+type EntityManagerMode = "read-only" | "in-memory-writes" | "writes";
+type FindOperation = typeof findOperation | typeof findByUniqueOperation | typeof findCountOperation | typeof findIdsOperation | typeof lensOperation | typeof loadOperation | typeof manyToManyLoadOperation | typeof manyToManyFindOperation | typeof enumCollectionLoadOperation | typeof oneToManyLoadOperation | typeof oneToManyFindOperation | typeof oneToOneLoadOperation | typeof populateOperation | typeof recursiveChildrenOperation | typeof recursiveM2mOperation | typeof recursiveParentsOperation | typeof lazyColumnLoadOperation;
+/**
+ * The EntityManager is the primary way nearly all code, i.e. anything that finds/creates/updates/deletes entities,
+ * will interact with the database.
+ *
+ * It acts both an Identity Cache (preventing loading the same row twice into memory as separate entities, and then
+ * having drift between the two instances) and as a Unit of Work (tracking all changes to entities and then batch
+ * flushing only the entities that have changed).
+ *
+ * Note that the type parameters (C, I, and Entity) will be filled in by codegen with the values specific to your
+ * application, so you can import your app-specific EntityManager like:
+ *
+ * ```ts
+ * import { EntityManager } from "src/entities";
+ * ```
+ *
+ * @param C The type of your application-specific app-wide/request-wide Context object that will be passed to hooks
+ * @typeParam C - the application-specific context (typically the request-level context)
+ * @typeParam Entity - the application's based entity type (i.e. with number ids or string ids)
+ * @typeParamTX - the application's Transaction type, i.e. `Knex`
+ */
+declare class EntityManager<C = unknown, Entity$1 extends Entity = Entity, TX extends unknown = unknown> {
+  #private;
+  readonly ctx: C;
+  driver: Driver<TX>;
+  /** When we're flushing, the connection/transaction. */
+  txn: TX | undefined;
+  entityLimit: number;
+  private __api;
+  mode: EntityManagerMode;
+  constructor(ctx: C, opts: EntityManagerOpts<TX>);
+  constructor(ctx: C, driver: Driver<TX>);
+  /** Returns a read-only shallow copy of the currently-loaded entities. */
+  get entities(): ReadonlyArray<Entity$1>;
+  /** Returns a list of all pending creates, updates, deletes, and m2m changes that would be flushed. */
+  get pendingChanges(): PendingChange[];
+  /** Returns a read-only list of the currently-loaded entities of `type`. */
+  getEntities<T extends Entity$1>(type: MaybeAbstractEntityConstructor<T>): ReadonlyArray<T>;
+  /** Looks up `id` in the list of already-loaded entities. */
+  getEntity<T extends Entity$1 & {
+    id: string;
+  }>(id: IdOf<T>): T | undefined;
+  getEntity(id: TaggedId): Entity$1 | undefined;
+  /**
+   * Finds entities of `type` with the `where` filter, with auto-batching, so this method
+   * will not cause N+1s if called in a loop.
+   *
+   * The `where` filter is one of Joist's "join literals", which can combine both joining into
+   * related entities and simple column conditions in a single literal. All conditions are ANDed.
+   * For more complex conditions, use the `find` overload that has a `conditions` option.
+   *
+   * This method is batch-friendly, i.e. if called in a loop, it will be automatically batched
+   * to avoid N+1s, including queries that use `LIMIT` or `OFFSET`.
+   */
+  find<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>): Promise<T[]>;
+  find<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>, options?: FindFilterOptions<T> & {
+    populate?: H;
+  }): Promise<Loaded<T, H>[]>;
+  /**
+   * Runs a SQL-shaped query written as an object literal, and returns typed rows.
+   *
+   * ```ts
+   * const [a, b] = tables(Author, Book);
+   * const rows = await em.query({
+   *   from: a,
+   *   join: [{ left: b, on: b.author_id.eq(a.id) }],
+   *   where: { and: [a.age.gte(minAge)] },
+   *   groupBy: [a.first_name],
+   *   select: { name: a.first_name, bookCount: b.id.count() },
+   *   orderBy: { bookCount: "DESC" },
+   * });
+   * // → { name: string; bookCount: number }[]
+   * ```
+   *
+   * `select` decides the row type: a bare table (`select: a`) returns entities through the identity
+   * map, an array of columns or a `{ key: expr }` object returns typed POJOs, and a `query(...)` value
+   * returns its rows. Joins are pruned like `em.find`: an `undefined` condition drops out, and a join
+   * nothing references anymore drops with it. See `query.ts` for the full DSL, and `query()` for
+   * composing subqueries.
+   *
+   * Entity selections accept a second argument, `{ populate: hint }`, and return `Loaded` entities.
+   * Population runs after the query, using the same relation loaders as `em.populate`.
+   * This method is not batched: these are custom queries, too unique to batch.
+   */
+  query<R>(q: QueryTable<R, any>): Promise<R[]>;
+  query<T extends Entity$1>(q: EntityQuery<T>): Promise<T[]>;
+  query<T extends Entity$1, const H extends LoadHint<T>>(q: EntityQuery<T>, options: {
+    populate: H;
+  }): Promise<Loaded<T, H>[]>;
+  query<const Q extends SetQuery<readonly SetOperand[]>>(q: Q & CheckSetQuery<Q>): Promise<SetQueryRow<Q>[]>;
+  query<F extends QuerySource, const S extends QuerySelect = never, J extends QueryJoinInput = []>(q: QueryArg<F, S, J, never>): Promise<QueryRow<S, ResolvedJoins<F, J>>[]>;
+  query<F extends QuerySource, const S extends QuerySelect, const H extends LoadHint<Extract<QueryRow<S, ResolvedJoins<F, J>>, Entity>>, J extends QueryJoinInput = []>(q: QueryArg<F, S, J, never>, options: QueryRow<S, ResolvedJoins<F, J>> extends Entity ? {
+    populate: H;
+  } : never): Promise<Loaded<Extract<QueryRow<S, ResolvedJoins<F, J>>, Entity>, H>[]>;
+  /**
+   * Executes immediate SQL with a native command count. Mutations bypass the entity unit of work;
+   * reads retain query's decoding and permissions. Neither path flushes or repairs cached entities.
+   */
+  execute<const M extends MutationInput>(statement: M & CheckMutation<M>): Promise<ExecuteResult<MutationRow<M>>>;
+  execute<R>(statement: QueryTable<R, any>): Promise<ExecuteResult<R>>;
+  execute<T extends Entity$1>(statement: EntityQuery<T>): Promise<ExecuteResult<T>>;
+  execute<const Q extends SetQuery<readonly SetOperand[]>>(statement: Q & CheckSetQuery<Q>): Promise<ExecuteResult<SetQueryRow<Q>>>;
+  execute<F extends QuerySource, const S extends QuerySelect = never, J extends QueryJoinInput = []>(statement: QueryArg<F, S, J, never>): Promise<ExecuteResult<QueryRow<S, ResolvedJoins<F, J>>>>;
+  /** Runs the post-parse find pipeline: plugins mutate the logical AST, then Joist optimizes/prunes before SQL. */
+  private executeFind;
+  /** Like {@link executeFind}, but returns a {@link RowData}; see {@link executePreparedFindRowData}. */
+  private executeFindRowData;
+  /** Executes a query that has already had find hooks and optimizations applied. */
+  private executePreparedFind;
+  /**
+   * Like {@link executePreparedFind}, but returns a {@link RowData}: lazy wire rows when the
+   * driver has `lazyRows` enabled, else classic POJO rows wrapped in a `PojoRowData` — so
+   * loaders can hydrate from one shape without caring which the driver provides.
+   */
+  private executePreparedFindRowData;
+  /**
+   * Runs pre-SQL find hooks and optimizations against a parsed query.
+   *
+   * This allows plugins to see "pre-batched" / "logical" query ASTs, instead of our
+   * more complicated `_find` batched queries. The flow would be:
+   *
+   * - A loader calls `prepareFind(originalQuery)`
+   * - Plugins inspect/modify the query as/if needed
+   * - The loader crafts a new, more complicated query that embeds the originalQuery
+   * - The loader calls `executePreparedFind` with the 2nd query
+   */
+  private prepareFind;
+  /**
+   * Works exactly like `find` but accepts "less than greatly typed" GraphQL filters.
+   *
+   * I.e. filtering by `null` on fields that are non-`nullable`.
+   */
+  findGql<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, where: GraphQLFilterWithAlias<T>): Promise<T[]>;
+  findGql<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: GraphQLFilterWithAlias<T>, options?: FindGqlFilterOptions<T> & {
+    populate?: H;
+  }): Promise<Loaded<T, H>[]>;
+  findOne<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>): Promise<T | undefined>;
+  findOne<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>, options?: FindFilterOptions<T> & {
+    populate?: H;
+  }): Promise<Loaded<T, H> | undefined>;
+  /** Executes a given query filter and returns exactly one result, otherwise throws `NotFoundError` or `TooManyError`. */
+  findOneOrFail<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>): Promise<T>;
+  findOneOrFail<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>, options: FindFilterOptions<T> & {
+    populate?: H;
+  }): Promise<Loaded<T, H>>;
+  findByUnique<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, where: UniqueFilter<T>): Promise<T | undefined>;
+  findByUnique<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: UniqueFilter<T>, options?: {
+    populate?: H;
+    softDeletes?: "include" | "exclude";
+  }): Promise<Loaded<T, H> | undefined>;
+  /**
+   * Returns the count of entities that match the `where` clause.
+   *
+   * The `where` clause, and any options.conditions, matches the same syntax
+   * as `em.find`.
+   *
+   * Note: this method is not currently auto-batched, so it will cause N+1s if called in a loop.
+   */
+  findCount<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T> | GraphQLFilterWithAlias<T>, options?: FindCountFilterOptions<T>): Promise<number>;
+  /**
+   * Returns the IDs of entities that match the `where` clause.
+   *
+   * The `where` clause, and any options.conditions, matches the same syntax
+   * as `em.find`.
+   */
+  findIds<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>, options?: FindCountFilterOptions<T>): Promise<string[]>;
+  /**
+   * Looks for entities that match `where`, both in the database and any just-created or just-changed entities.
+   *
+   * Because we evaluate this `where` clause in memory (against any WIP changes made to entities
+   * that have not yet been `em.flush`ed to the database), the `where` clause is limited to fields
+   * immediately available on the entity, i.e. primitives, enums, and many-to-ones, without any
+   * nested, cross-table joins/conditions.
+   *
+   * For `m2o` fields, `undefined` will be pruned, just like `em.find`s. I.e. `{ publisher: undefined }` will
+   * be pruned and not filter on `publisher` at all, where as `{ publisher: null }` will filter for `publisher`
+   * is unset.
+   *
+   * @param type the entity type to find
+   * @param where the fields to look up the existing entity by
+   */
+  findWithNewOrChanged<T extends Entity$1, F extends Partial<OptsOf<T>>>(type: EntityConstructor<T>, where: F): Promise<T[]>;
+  findWithNewOrChanged<T extends Entity$1, F extends Partial<OptsOf<T>>, const H extends LoadHint<T>>(type: EntityConstructor<T>, where: F, options?: {
+    populate?: H;
+    softDeletes?: "include" | "exclude";
+  }): Promise<Loaded<T, H>[]>;
+  /**
+   * Conditionally finds or creates (or upserts) an Entity.
+   *
+   * The `where` param is used to find the existing/if any entity; if not found,
+   * then one will be created.
+   *
+   * The `ifNew` param will be used, if no entity is found, for the `em.create` call;
+   * it is typed such that it will require all opts necessary for the `em.create` to
+   * be valid, _unless_ those opts are already included in either the `where` or
+   * `upsert` params.
+   *
+   * The optional `upsert` param are fields to always set/update, regardless of whether
+   * the entity is created or not.
+   *
+   * @param type the entity type to find/create
+   * @param where the fields to look up the existing entity by
+   * @param ifNew the fields to set if the entity is new
+   * @param upsert the fields to update if the entity is either existing or new
+   */
+  findOrCreate<T extends Entity, F extends Partial<OptsOf<T>>, U extends Partial<OptsOf<T>> | {}, N extends Omit<OptsOf<T>, keyof F | keyof U>>(type: EntityConstructor<T>, where: F, ifNew: N, upsert?: U): Promise<T>;
+  findOrCreate<T extends Entity, F extends Partial<OptsOf<T>>, U extends Partial<OptsOf<T>> | {}, N extends Omit<OptsOf<T>, keyof F | keyof U>, const H extends LoadHint<T>>(type: EntityConstructor<T>, where: F, ifNew: N, upsert?: U, options?: {
+    populate?: H;
+    softDeletes?: "include" | "exclude";
+  }): Promise<Loaded<T, H>>;
+  /** Creates a new `type` and marks it as loaded, i.e. we know its collections are all safe to access in memory. */
+  create<T extends Entity, O extends OptsOf<T>>(type: EntityConstructor<T>, opts: O): New<T, O>;
+  /**
+   * Creates a new `type` but with `opts` that are nullable, to accept partial-update-style input.
+   *
+   * Note that `createPartial` doesn't support the full upsert behavior, i.e. this method:
+   *
+   * - always creates,
+   * - does not support relation markers like `op`, `delete`, and `remove`,
+   * - does not accept deep input, but
+   * - fields set to `undefined` will be skipped instead of unset
+   *
+   * See `upsert` for the upsert/deep upsert behavior.
+   */
+  createPartial<T extends Entity>(type: EntityConstructor<T>, opts: PartialOrNull<OptsOf<T>>): T;
+  /**
+   * Create or updates `type` based on partial-update-style `input`.
+   *
+   * This supports upsert behavior, i.e.:
+   *
+   * - findOrCreate the primary entity being updated (based on the `id` key being provided),
+   * - upsert relation markers like `op`, `delete`, and `remove` are supported,
+   * - deep input is supported, i.e. `{ firstName: "Bob", books: [{ title: "b1" } ] }`, and
+   * - fields set to `undefined` will be skipped instead of unset
+   */
+  upsert<T extends Entity>(type: EntityConstructor<T>, input: DeepPartialOrNull<T>): Promise<T>;
+  /**
+   * Utility to clone an entity and its nested relations, as determined by a populate hint
+   *
+   * @param entity - Any entity
+   * @param opts - Options to control the clone behaviour
+   *   @param deep - Populate hint of the nested tree of objects to clone
+   *   @param skip - Keys that will be skipped in the clone
+   *   @param skipIf - Predicate for determining if a specific entity should be skipped (and any entities beneath it
+   *   @param postClone - Function to be called for each original/clone entity for any post-processing needed
+   * @returns The `Loaded` cloned entity or fails if the clone could not be made
+   *
+   * @example
+   * // This will duplicate the author
+   * const duplicatedAuthor = await em.clone(author)
+   *
+   * @example
+   * // This will duplicate the author and all their related book entities
+   * const duplicatedAuthorAndBooks = await em.clone(author, { deep: "books" })
+   *
+   * @example
+   * // This will duplicate the author, all their books, and the images for those books
+   * const duplicatedAuthorAndBooksAndImages = await em.clone(author, { deep: { books: "image" } })
+   *
+   * @example
+   * // This will duplicate the author, and rename
+   * const duplicatedAuthor = await em.clone(author, { postClone: (_original, clone) => clone.firstName = clone.firstName + " COPY" })
+   *
+   * @example
+   * // This will duplicate the author, but skip any book where the title includes `sea`
+   * const duplicatedAuthor = await em.clone(author, { skipIf: (original) => original.title?.includes("sea") })
+   */
+  clone<T extends Entity$1, H extends LoadHint<T>, const K = ReactiveHint<T>>(entity: T, opts?: {
+    deep?: H;
+    skip?: K;
+    skipIf?: (entity: Entity$1) => boolean;
+    postClone?: (original: Entity$1, clone: Entity$1) => void;
+  }): Promise<Loaded<T, H>>;
+  /**
+   * Utility to clone an entity and its nested relations, as determined by a populate hint.
+   *
+   * @param entities - Any homogeneous list of entities
+   * @param opts - Options to control the clone behaviour
+   *   @param deep - Populate hint of the nested tree of objects to clone
+   *   @param skip - Keys that will be skipped in the clone
+   *   @param skipIf - Predicate for determining if a specific entity should be skipped (and any entities beneath it
+   *   @param postClone - Function to be called for each original/clone entity for any post-processing needed
+   * @returns Array of `Loaded` cloned entities from the provided list or empty array if all are skipped
+   *
+   * @example
+   * // This will duplicate the author's books
+   * const duplicatedBooks = await em.clone(author.books.get)
+   *
+   * @example
+   * // This will duplicate the author's books, all their books, and the images for those books
+   * const duplicatedBooksAndImages = await em.clone(author.books.get, { deep: { books: "image" } })
+   *
+   * @example
+   * // This will duplicate the author's books, and assign them to a different author
+   * const duplicatedBooks = await em.clone(author.books.get, { postClone: (_original, clone) => clone.author.set(author2) })
+   *
+   * @example
+   * // This will duplicate the author's books, but skip any book where the title includes `sea`
+   * const duplicatedBooks = await em.clone(author.books.get, { skipIf: (original) => original.title.includes("sea") })
+   */
+  clone<T extends Entity$1, H extends LoadHint<T>, const K = ReactiveHint<T>>(entities: readonly T[], opts?: {
+    deep?: H;
+    skip?: K;
+    skipIf?: (entity: Entity$1) => boolean;
+    postClone?: (original: Entity$1, clone: Entity$1) => void;
+  }): Promise<Loaded<T, H>[]>;
+  /**
+   * Merges multiple source entities into a target entity by updating all references that point
+   * to the source entities to instead point to the target entity.
+   *
+   * This method loads all relations from the source entities, updates any entity that
+   * references a source entity to reference the target entity instead, and then automatically
+   * deletes the source entities.
+   *
+   * @param target - The entity that will become the target of all merged references
+   * @param sources - Array of entities whose references will be redirected to the target
+   * @param opts - Options to control merge behavior
+   *   @param autoDelete - Whether to automatically delete source entities (default: true)
+   * @returns Promise that resolves when all references have been updated and sources deleted
+   *
+   * @example
+   * // Merge duplicate authors - all books pointing to author2 will now point to author1
+   * // author2 will be automatically deleted
+   * await em.merge(author1, [author2]);
+   *
+   * @example
+   * // Merge multiple duplicate publishers into one
+   * // publisher2 and publisher3 will be automatically deleted
+   * await em.merge(publisher1, [publisher2, publisher3]);
+   *
+   * @example
+   * // Merge without auto-deleting sources (for custom cleanup logic)
+   * await em.merge(author1, [author2], { autoDelete: false });
+   * // Custom logic here...
+   * em.delete(author2);
+   */
+  merge<T extends Entity$1>(target: T, sources: T[], opts?: {
+    autoDelete?: boolean;
+  }): Promise<Entity$1[]>;
+  /** Returns an instance of `type` for the given `id`, resolving to an existing instance if in our Unit of Work. */
+  load<T extends Entity & {
+    id: string;
+  }>(id: IdOf<T>): Promise<T>;
+  load(id: TaggedId): Promise<Entity$1>;
+  load<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, id: IdOf<T> | TaggedId): Promise<T>;
+  load<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, id: IdOf<T> | TaggedId, populate: H): Promise<Loaded<T, H>>;
+  /** Returns instances of `type` for the given `ids`, resolving to an existing instance if in our Unit of Work. */
+  loadAll<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, ids: readonly string[]): Promise<T[]>;
+  loadAll<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, ids: readonly string[], populate: H): Promise<Loaded<T, H>[]>;
+  /**
+   * Returns instances of `type` for the given `ids`, resolving to an existing instance if in our Unit of Work. Ignores
+   * IDs that are not found.
+   */
+  loadAllIfExists<T extends Entity>(type: EntityConstructor<T>, ids: readonly string[]): Promise<T[]>;
+  loadAllIfExists<T extends Entity, const H extends LoadHint<T>>(type: EntityConstructor<T>, ids: readonly string[], populate: H): Promise<Loaded<T, H>[]>;
+  /**
+   * Loads entities found, when starting at `entities`, via the "path" given by the `fn` lens function.
+   *
+   * Results are unique, i.e. if doing `em.loadLens([b1, b2], b => b.author.publisher)` point to the
+   * same `Publisher`, it will only be returned as a single value.
+   */
+  loadLens<T extends Entity, U, V>(entities: readonly T[], fn: (lens: Lens<T>) => Lens<U, V>): Promise<U[]>;
+  loadLens<T extends Entity, U extends Entity, V, const H extends LoadHint<U>>(entities: readonly T[], fn: (lens: Lens<T>) => Lens<U, V>, populate: H): Promise<Loaded<U, H>[]>;
+  /**
+   * Loads entities from database rows that were queried directly using a query builder.
+   *
+   * This overload is synchronous since there is no population/querying to do.
+   */
+  loadFromQuery<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, rows: readonly unknown[]): T[];
+  /**
+   * Loads entities from database rows from a Knex-ish query builder that needs an `await`.
+   *
+   * This overload is async because it triggers the `rows` query.
+   */
+  loadFromQuery<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, rows: PromiseLike<readonly unknown[]>): Promise<T[]>;
+  /**
+   * Loads & populates entities from database rows that were queried directly using a query builder.
+   */
+  loadFromQuery<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, rows: readonly unknown[], populate: H): Promise<Loaded<T, H>[]>;
+  /**
+   * Loads & populates entities from database rows from a Knex-ish query builder that needs an `await`.
+   */
+  loadFromQuery<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, rows: PromiseLike<readonly unknown[]>, populate: H): Promise<Loaded<T, H>[]>;
+  /** Loads entities from rows. */
+  loadFromRows<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, rows: unknown[]): Promise<T[]>;
+  loadFromRows<T extends Entity, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, rows: unknown[], populate: H): Promise<Loaded<T, H>[]>;
+  /** Given a hint `H` (a field, array of fields, or nested hash), pre-load that data into `entity` for sync access. */
+  populate<T extends Entity, const H extends LoadHint<T>, V = Loaded<T, H>>(entity: T, hint: H, fn?: (entity: Loaded<T, H>) => V): Promise<V>;
+  populate<T extends Entity, const H extends LoadHint<T>, V = Loaded<T, H>>(entity: T, opts: {
+    hint: H;
+    forceReload?: boolean;
+  }, fn?: (entity: Loaded<T, H>) => V): Promise<V>;
+  populate<T extends Entity, const H extends LoadHint<T>>(entities: ReadonlyArray<T>, hint: H): Promise<Loaded<T, H>[]>;
+  populate<T extends Entity, const H extends LoadHint<T>>(entities: ReadonlyArray<T>, opts: {
+    hint: H;
+    forceReload?: boolean;
+  }): Promise<Loaded<T, H>[]>;
+  /**
+   * Executes `fn` with a transaction, and automatically calls `flush`/`commit` at the end.
+   *
+   * This ensures both any `.find` and `.flush` operations happen within the same
+   * transaction, which is useful for enforcing cross-table/application-level invariants that
+   * cannot be enforced with database-level constraints.
+   */
+  transaction<T>(fn: (txn: TX) => Promise<T>): Promise<T>;
+  /**
+   * Marks an instance to be deleted.
+   *
+   * Any loaded collections that are currently "pointing to" this entity will be updated to
+   * no longer include this entity, i.e. if you `em.delete(b1)`, then `author.books` will have
+   * `b1` removed (if needed).
+   *
+   * This is done for all currently-loaded collections; i.e. technically unloaded collections
+   * may still point to this entity. We defer unsetting these not-currently-loaded references
+   * until `EntityManager.flush`, when we can make the async calls to load-and-unset them.
+   */
+  delete(entity: Entity$1): void;
+  /**
+   * Marks entities to be deleted.
+   *
+   * Any loaded collections that are currently "pointing to" this entity will be updated to
+   * no longer include this entity, i.e. if you `em.delete(b1)`, then `author.books` will have
+   * `b1` removed (if needed).
+   *
+   * This is done for all currently-loaded collections; i.e. technically unloaded collections
+   * may still point to this entity. We defer unsetting these not-currently-loaded references
+   * until `EntityManager.flush`, when we can make the async calls to load-and-unset them.
+   */
+  delete(entities: Entity$1[]): void;
+  assignNewIds(): Promise<void>;
+  /**
+   * Immediately assigns async defaults to `entities`.
+   *
+   * Normally async defaults wait until `em.flush` to run, because their async nature requires
+   * an `await` / `Promise` to be evaluated, and `em.create` is synchronous.
+   *
+   * This `assignDefaults` methods like you move that up, and immediately invoke
+   * any default logic against the `entities`.
+   */
+  setDefaults(entities: Entity$1[]): Promise<void>;
+  /**
+   * Flushes the SQL for any changed entities to the database.
+   *
+   * If this is run outside of an existing transaction, it will `BEGIN` and `COMMIT`
+   * a new transaction on every `.flush()` call so that all of the `INSERT`s/etc.
+   * happen atomically.
+   *
+   * If this is run within an existing transaction, i.e. `EntityManager.transaction`,
+   * then it will only issue `INSERT`s/etc. and defer to the caller to `COMMIT`
+   * the transaction.
+   *
+   * It returns entities that have changed (an entity is considered changed if it has been deleted, inserted, or updated)
+   */
+  flush(flushOptions?: FlushOptions): Promise<Entity$1[]>;
+  /**
+   * A very simple toJSON.
+   *
+   * This is not really meant to be useful, it's to prevent huge/circular output if
+   * an EntityManager accidentally ends up getting logged to something like pino that
+   * over-zealous toJSONs anything it touches.
+   */
+  toJSON(): string;
+  /**
+   * For all entities in the current `EntityManager`, load their latest data from the database.
+   *
+   * This is primarily useful in tests, i.e. having 1 `EntityManager` with some test data, running business
+   * logic in a dedicated `EntityManager`, and then `refresh`-ing the test data `EntityManager` to assert
+   * against the latest values.
+   *
+   * This works with primitive fields as well as references and collections.
+   *
+   * TODO Newly-found collection entries will not have prior load hints applied to this, unless using
+   * `deepLoad` which should only be used by tests to avoid loading your entire database in memory.
+   */
+  refresh(opts?: {
+    deepLoad?: boolean;
+  }): Promise<void>;
+  refresh(entity: Entity): Promise<void>;
+  refresh(entities: ReadonlyArray<Entity>): Promise<void>;
+  get numberOfEntities(): number;
+  findExistingInstance<T extends Entity>(id: string): T | undefined;
+  /**
+   * Takes a result `row` from a custom query and maps the db values into a new-or-existing domain object for that row.
+   *
+   * The `overwriteExisting` controls whether `row`'s values should overwrite the existing fields on
+   * an entity. By default this is true, as we assume the user calling this means they know the DB has
+   * updated values that should be put into the entities. A few internal callers set this to false,
+   * i.e. when we're loading collections and have db results that are potentially stale compared to
+   * the WIP entity state.
+   */
+  hydrate<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, rows: readonly any[], options?: {
+    overwriteExisting?: boolean;
+  }): T[];
+  /**
+   * Hydrates a query's `RowData`, running any sidecar reads, and always `finalize`s the result.
+   *
+   * This is the internal API for Joist's find/load loaders: `sidecars` is where reads of
+   * non-entity columns (preload aggregates, `_tags`, found-id checks) belong — they must run
+   * before `finalize`, because compaction drops unretained rows — and the `try/finally`
+   * guarantees a failed hydration or sidecar read still releases the result's unretained
+   * buffers instead of pinning them.
+   */
+  private hydrateAndFinalize;
+  /**
+   * Like {@link hydrate}, but reads rows from a {@link RowData}, i.e. a driver-produced
+   * lazy query result, instead of an array of POJO rows.
+   *
+   * This is an internal API used by Joist's own find loaders (usually via
+   * {@link hydrateAndFinalize}); rows whose entities are kept (newly created or
+   * overwrite-refreshed) are `retain`-ed on the `RowData` so the caller can later `finalize`
+   * (trim/compact) the result.
+   */
+  hydrateFromRowData<T extends Entity>(type: MaybeAbstractEntityConstructor<T>, rowData: RowData, options?: {
+    overwriteExisting?: boolean;
+  }): T[];
+  /**
+   * Mark an entity as needing to be flushed regardless of its state.
+   *
+   * This will:
+   *
+   * - Bump the entity's `updated_at` timestamp (if available),
+   * - Run `beforeUpdate` and `beforeFlush` hooks.
+   */
+  touch(entity: Entity): void;
+  touch(entities: Entity[]): void;
+  /**
+   * Recalculates an entity's reactive fields or explicitly runs a named reaction.
+   *
+   * You shouldn't need to call this unless the derived fields have drifted from the underlying data, which
+   * should only happen if:
+   *
+   * - The underlying data was changed by a raw SQL query, or
+   * - You've changed the field's business logic and want to update the database to the latest value.
+   *
+   * Pass `reactionName` to run only that named reaction on each entity. You can also trigger a recalc for
+   * specific fields by calling `.load()` on the property, i.e.
+   * `author.numberOfBooks.load()`. This `recalc` method is just a helper method to call `load` for
+   * all derived fields on the given entity/entities.
+   */
+  recalc(entity: Entity): Promise<void>;
+  recalc(entities: Entity[]): Promise<void>;
+  recalc(entity: Entity, reactionName: string): Promise<void>;
+  recalc(entities: Entity[], reactionName: string): Promise<void>;
+  beforeBegin(fn: HookFn<TX>): void;
+  afterBegin(fn: HookFn<TX>): void;
+  beforeCommit(fn: HookFn<TX>): void;
+  afterCommit(fn: HookFn<TX>): void;
+  /**
+   * Returns an EntityManager-scoped (i.e. request scoped) data loader.
+   *
+   * @param operation the operation being batched, i.e. `load` or `o2m-load`, to avoid clashing batch keys
+   *   across fundamentally different operations
+   * @param batchKey for a given operation, i.e. `load`, a batch key `Author` to batch all Author loads together
+   * @param fn the batch load function, i.e. that will accept all `.load(...)`-d Author ids to load as a single db call
+   * @param opts optional DataLoader options
+   * @returns a DataLoader scoped to the `operation` + `batchKey` combination
+   */
+  getLoader<K, V>(operation: string, batchKey: string, fn: BatchLoadFn<K, V>, opts?: Options<K, V>): DataLoader<K, V>;
+  /**
+   * Like `getLoader`, but returns a `BatchLoader` where all callers in the same tick
+   * share a single `Promise<void>` instead of getting per-key promises.
+   *
+   * The batch function should write results via side channels (e.g. `setPreloadedRelation`).
+   */
+  getBatchLoader<K>(operation: string, batchKey: string, fn: (keys: K[]) => Promise<void>): BatchLoader<K>;
+  toString(): string;
+  /** Recursively cascades any pending deletions. */
+  private flushDeletes;
+  setReactionLogging(logger: ReactionLogger): void;
+  setReactionLogging(enabled: boolean): void;
+  /** Accepts `Author` or `Author.firstName,lastName` or `Author.lastName!`. */
+  setFieldLogging(spec: string): void;
+  /** Accepts `["Author.firstName,lastName", "Book.title"]`. */
+  setFieldLogging(spec: string[]): void;
+  /** Sets this EntityManager's field logger. */
+  setFieldLogging(logger: FieldLogger): void;
+  /** Enables/disables field logging for all fields. */
+  setFieldLogging(enabled: boolean): void;
+  [Symbol.asyncDispose](): Promise<void>;
+  /** Returns entities matching the filter using indexed search when available. */
+  filterEntities<T extends Entity$1>(cstr: EntityConstructor<T>, where: Partial<OptsOf<T>>): T[];
+  /**
+   * Creates a new EntityManager that shares the same entities as the current one but allows independent changes.
+   *
+   * This is useful for scenarios where you want to:
+   *
+   * - Preload data for use as a cache
+   * - Make speculative changes that may or may not be committed
+   * - Escape a transaction scope
+   *
+   * The fork will:
+   *
+   * - Copy all currently loaded entities to the new EntityManager
+   * - Copy any loaded relation data to keep `.isLoaded` / `.get` state consistent
+   * - Copy and update references to the EntityManager and its entities in the context, which is itself shallowly copied
+   *
+   * The fork will NOT:
+   *
+   * - Copy any pending changes (must call .flush() first)
+   * - Share any changes made in either EntityManager with the other
+   *
+   * @param opts options to control the fork behavior
+   *  - allowPendingChanges - allows the em being forked to have pending changes and forces the resulting em to have
+   *  `mode` set to "in-memory-writes".  Changes to entities in the original em will be copied to the resulting em.
+   *  Optional. default: false
+   *
+   * @throws {Error} If called on an EntityManager with pending changes
+   * @returns A new EntityManager with copied entity state
+   */
+  fork(opts?: {
+    allowPendingChanges?: boolean;
+  }): EntityManager<C, Entity$1, TX>;
+  /**
+   * Copies an entity from one EntityManager to another, ensuring all relations specified in the hint are
+   * also copied.
+   *
+   * This method is primarily used when you need to move entities between different EntityManager instances
+   * while preserving their loaded state and relationships. This is useful for scenarios like:
+   *
+   * - Moving entities between transaction boundaries
+   * - Creating test fixtures that reference entities from a different EntityManager
+   * - Sharing entities between different parts of your application
+   *
+   * The migration process:
+   * 1. If the entity already exists in this EntityManager, returns it
+   * 2. Otherwise, creates a new instance with the same data
+   * 3. Recursively migrates any loaded relations specified in the hint
+   *
+   * @param source - The entity to migrate from another EntityManager
+   * @param hint - The load hint specifying which relations to migrate
+   * @returns The migrated entity with all specified relations loaded
+   */
+  importEntity<T extends Entity$1>(original: T): T;
+  importEntity<T extends Entity$1, H extends LoadHint<T>, L extends Loaded<T, H>>(original: L, hint: H): L;
+  addPlugin(plugin: Plugin): void;
+  getPlugins(): readonly Plugin[];
+  get isRefreshing(): boolean;
+  get isFlushing(): boolean;
+}
+/** Provides an internal API to the `EntityManager`. */
+interface EntityManagerInternalApi {
+  joinRows: (m2m: ManyToManyLike) => JoinRows;
+  /** Map of taggedId -> fieldName -> pending children, i.e. when `a1.books` later loads, add/remove b1. */
+  pendingPercolate: Map<string, Map<string, {
+    adds: Entity[];
+    removes: Entity[];
+  }>>;
+  /** List of mutated o2m collections to reset added/removed post-flush. */
+  mutatedCollections: Set<OneToManyCollection<any, any>>;
+  /** O2M/M2M collections with pending set() calls that need resolution before flush. */
+  pendingLoads: Set<Collection<any, any>>;
+  /** Map of taggedId -> fieldName -> join-loaded data. */
+  getPreloadedRelation<U>(taggedId: string, fieldName: string): U[] | undefined;
+  setPreloadedRelation<U>(taggedId: string, fieldName: string, children: U[]): void;
+  hooks: Record<EntityManagerHook, HookFn<any>[]>;
+  rm: ReactionsManager;
+  indexManager: IndexManager;
+  preloader: PreloadPlugin | undefined;
+  isValidating: boolean;
+  checkWritesAllowed: () => void;
+  isMerging: (entity: Entity) => boolean;
+  get fieldLogger(): FieldLogger;
+  get isLoadedCache(): IsLoadedCache;
+  pluginManager: PluginManager;
+  clearDataloaders(): void;
+  clearPreloadedRelations(): void;
+  markMaybePending(entity: Entity): void;
+  unmarkMaybePending(entity: Entity): void;
+  hasAnyDeletes(): boolean;
+  pendingDeleteIds(type: MaybeAbstractEntityConstructor<Entity>): readonly IdType[];
+  setIsRefreshing(isRefreshing: boolean): void;
+}
+declare function getEmInternalApi(em: EntityManager): EntityManagerInternalApi;
+declare function getDefaultEntityLimit(): number;
+declare function setDefaultEntityLimit(limit: number): void;
+declare function resetDefaultEntityLimit(): void;
+declare function isKey(k: any): k is string;
+/** Compares `a` to `b`, where `b` might be an id. */
+declare function sameEntity(a: Entity | string | number | undefined, b: Entity | string | number | undefined): boolean;
+/** Compares the value `a` to `b`, with handling of new entities w/o ids assigned yet. */
+declare function sameReference<T extends Entity>(a: Reference<any, T, any>, b: Reference<any, T, any>): boolean;
+/** Thrown by `findOneOrFail`, 'load' & 'loadAll' if an entity is not found. */
+declare class NotFoundError extends Error {}
+/** Thrown by `findOne` and `findOneOrFail` if more than one entity is found. */
+declare class TooManyError extends Error {
+  constructor(message: string);
+}
+declare function driverBeforeBegin<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
+declare function driverAfterBegin<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
+declare function driverBeforeCommit<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
+declare function driverAfterCommit<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
+declare function isDefined<T extends any>(param: T | undefined | null): param is T;
+declare function setLastNow(now: Date | undefined): void;
+/** An error thrown when `em.mode === "read-only"` but entities are mutated/flushed. */
+declare class ReadOnlyError extends Error {
+  constructor();
+}
+/**
+ * Given an `err` thrown in "a different context", i.e. a database error or dataloader error
+ * that doesn't include our stack trace, append our stack for better debugging.
+ *
+ * See https://github.com/brianc/node-postgres/pull/2983
+ */
+declare function appendStack(err: unknown, dummy: Error): unknown;
+declare function createRowFromEntityData(e: Entity, opts?: {
+  preferOriginalData?: boolean;
+}): Record<string, any>;
+//#endregion
+export { EntityConstructor, EntityManager, EntityManagerHook, EntityManagerInternalApi, EntityManagerMode, EntityManagerOpts, FindCountFilterOptions, FindFilterOptions, FindGqlFilterOptions, FindOperation, FlushOptions, IdOf, LoaderCache, MaybeAbstractEntityConstructor, NotFoundError, ReadOnlyError, TaggedId, TimestampFields, TooManyError, appendStack, createRowFromEntityData, driverAfterBegin, driverAfterCommit, driverBeforeBegin, driverBeforeCommit, getDefaultEntityLimit, getEmInternalApi, isDefined, isId, isKey, resetDefaultEntityLimit, sameEntity, sameReference, setDefaultEntityLimit, setLastNow };
+//# sourceMappingURL=EntityManager.d.mts.map