joist-core 2.3.0 → 2.4.0

package/build/EntityManager.d.ts

@@ -1,740 +0,0 @@
-import DataLoader, { BatchLoadFn, Options } from "dataloader";
-import { BatchLoader } from "./batchloaders/BatchLoader";
-import { enumCollectionLoadOperation } from "./batchloaders/enumCollectionBatchLoader";
-import { loadOperation } from "./batchloaders/loadBatchLoader";
-import { manyToManyLoadOperation } from "./batchloaders/manyToManyBatchLoader";
-import { oneToManyLoadOperation } from "./batchloaders/oneToManyBatchLoader";
-import { oneToOneLoadOperation } from "./batchloaders/oneToOneBatchLoader";
-import { IndexManager } from "./IndexManager";
-import { populateOperation } from "./batchloaders/populateBatchLoader";
-import { recursiveChildrenOperation } from "./batchloaders/recursiveChildrenBatchLoader";
-import { recursiveM2mOperation } from "./batchloaders/recursiveM2mBatchLoader";
-import { recursiveParentsOperation } from "./batchloaders/recursiveParentsBatchLoader";
-import { findByUniqueOperation } from "./dataloaders/findByUniqueDataLoader";
-import { findCountOperation } from "./dataloaders/findCountDataLoader";
-import { findOperation } from "./dataloaders/findDataLoader";
-import { findIdsOperation } from "./dataloaders/findIdsDataLoader";
-import { lensOperation } from "./dataloaders/lensDataLoader";
-import { manyToManyFindOperation } from "./dataloaders/manyToManyFindDataLoader";
-import { oneToManyFindOperation } from "./dataloaders/oneToManyFindDataLoader";
-import { Driver } from "./drivers";
-import { Entity, Entity as EntityW, IdType } from "./Entity";
-import { DeepPartialOrNull, EntityMetadata, ExpressionFilter, FieldLogger, FindFilter, GraphQLFilterWithAlias, InstanceData, Lens, OneToManyCollection, PartialOrNull, Plugin, ReactionLogger, ReactiveHint, Reference, UniqueFilter } from "./index";
-import { IsLoadedCache } from "./IsLoadedCache";
-import { JoinRows, ManyToManyLike } from "./JoinRows";
-import { Loaded, LoadHint, New } from "./loadHints";
-import { PendingChange } from "./PendingChanges";
-import { PluginManager } from "./PluginManager";
-import { PreloadPlugin } from "./plugins/PreloadPlugin";
-import { ReactionsManager } from "./ReactionsManager";
-import { Collection } from "./relations/Collection";
-import { OptsOf, OrderOf } from "./typeMap";
-import { MaybePromise } from "./utils";
-/**
- * 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.
- */
-export 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. */
-export 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;
-}
-export interface FindGqlFilterOptions<T extends Entity> extends Omit<FindFilterOptions<T>, "limit" | "offset"> {
-    limit?: number | null | undefined;
-    offset?: number | null | undefined;
-}
-/** Options for the `findCount`. */
-export 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".
- */
-export 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. */
-export type IdOf<T> = T extends {
-    id: infer I;
-} ? I : never;
-export type TaggedId = string;
-export declare function isId(value: any): value is IdOf<unknown>;
-export type EntityManagerHook = "beforeBegin" | "afterBegin" | "beforeCommit" | "afterCommit";
-type HookFn<TX> = (em: EntityManager, txn: TX) => MaybePromise<any>;
-export type LoaderCache = Record<string, DataLoader<any, any>>;
-export interface TimestampFields {
-    updatedAt: string | undefined;
-    createdAt: string | undefined;
-    deletedAt: string | undefined;
-}
-export type EntityManagerOpts<TX = unknown> = ({
-    driver: Driver<TX>;
-    em?: undefined;
-} | {
-    driver?: undefined;
-    em: EntityManager<any, any, any>;
-}) & {
-    preloadPlugin?: PreloadPlugin;
-};
-export 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
- */
-export type EntityManagerMode = "read-only" | "in-memory-writes" | "writes";
-export 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;
-/**
- * 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`
- */
-export declare class EntityManager<C = unknown, Entity extends EntityW = EntityW, 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>;
-    /** 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>(type: MaybeAbstractEntityConstructor<T>): ReadonlyArray<T>;
-    /** Looks up `id` in the list of already-loaded entities. */
-    getEntity<T extends Entity & {
-        id: string;
-    }>(id: IdOf<T>): T | undefined;
-    getEntity(id: TaggedId): Entity | 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 EntityW>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>): Promise<T[]>;
-    find<T extends EntityW, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>, options?: FindFilterOptions<T> & {
-        populate?: H;
-    }): Promise<Loaded<T, H>[]>;
-    /** Runs the post-parse find pipeline: plugins mutate the logical AST, then Joist optimizes/prunes before SQL. */
-    private executeFind;
-    /** Executes a query that has already had find hooks and optimizations applied. */
-    private executePreparedFind;
-    /**
-     * 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 EntityW>(type: MaybeAbstractEntityConstructor<T>, where: GraphQLFilterWithAlias<T>): Promise<T[]>;
-    findGql<T extends EntityW, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: GraphQLFilterWithAlias<T>, options?: FindGqlFilterOptions<T> & {
-        populate?: H;
-    }): Promise<Loaded<T, H>[]>;
-    findOne<T extends EntityW>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>): Promise<T | undefined>;
-    findOne<T extends EntityW, 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 EntityW>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>): Promise<T>;
-    findOneOrFail<T extends EntityW, const H extends LoadHint<T>>(type: MaybeAbstractEntityConstructor<T>, where: FindFilter<T>, options: FindFilterOptions<T> & {
-        populate?: H;
-    }): Promise<Loaded<T, H>>;
-    findByUnique<T extends EntityW>(type: MaybeAbstractEntityConstructor<T>, where: UniqueFilter<T>): Promise<T | undefined>;
-    findByUnique<T extends EntityW, 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 EntityW>(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 EntityW>(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, F extends Partial<OptsOf<T>>>(type: EntityConstructor<T>, where: F): Promise<T[]>;
-    findWithNewOrChanged<T extends Entity, 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 EntityW, 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 EntityW, 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 EntityW, 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 EntityW>(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 EntityW>(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, H extends LoadHint<T>, const K = ReactiveHint<T>>(entity: T, opts?: {
-        deep?: H;
-        skip?: K;
-        skipIf?: (entity: Entity) => boolean;
-        postClone?: (original: Entity, clone: Entity) => 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, H extends LoadHint<T>, const K = ReactiveHint<T>>(entities: readonly T[], opts?: {
-        deep?: H;
-        skip?: K;
-        skipIf?: (entity: Entity) => boolean;
-        postClone?: (original: Entity, clone: Entity) => 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>(target: T, sources: T[], opts?: {
-        autoDelete?: boolean;
-    }): Promise<Entity[]>;
-    /** Returns an instance of `type` for the given `id`, resolving to an existing instance if in our Unit of Work. */
-    load<T extends EntityW & {
-        id: string;
-    }>(id: IdOf<T>): Promise<T>;
-    load(id: TaggedId): Promise<Entity>;
-    load<T extends EntityW>(type: MaybeAbstractEntityConstructor<T>, id: IdOf<T> | TaggedId): Promise<T>;
-    load<T extends EntityW, 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 EntityW>(type: MaybeAbstractEntityConstructor<T>, ids: readonly string[]): Promise<T[]>;
-    loadAll<T extends EntityW, 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 EntityW>(type: EntityConstructor<T>, ids: readonly string[]): Promise<T[]>;
-    loadAllIfExists<T extends EntityW, 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 EntityW, U, V>(entities: readonly T[], fn: (lens: Lens<T>) => Lens<U, V>): Promise<U[]>;
-    loadLens<T extends EntityW, U extends EntityW, 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 EntityW>(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 EntityW>(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 EntityW, 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 EntityW, 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 EntityW>(type: MaybeAbstractEntityConstructor<T>, rows: unknown[]): Promise<T[]>;
-    loadFromRows<T extends EntityW, 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 EntityW, const H extends LoadHint<T>, V = Loaded<T, H>>(entity: T, hint: H, fn?: (entity: Loaded<T, H>) => V): Promise<V>;
-    populate<T extends EntityW, 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 EntityW, const H extends LoadHint<T>>(entities: ReadonlyArray<T>, hint: H): Promise<Loaded<T, H>[]>;
-    populate<T extends EntityW, 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): 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[]): 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[]): 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[]>;
-    /**
-     * 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: EntityW): Promise<void>;
-    refresh(entities: ReadonlyArray<EntityW>): Promise<void>;
-    get numberOfEntities(): number;
-    findExistingInstance<T extends EntityW>(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 EntityW>(type: MaybeAbstractEntityConstructor<T>, rows: readonly any[], 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: EntityW): void;
-    touch(entities: EntityW[]): void;
-    /**
-     * Recalculates the reactive fields for an entity, and any downstream reactive fields or reactions that depend on them.
-     *
-     * 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.
-     *
-     * 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: EntityW): Promise<void>;
-    recalc(entities: EntityW[]): 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>(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, 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>(original: T): T;
-    importEntity<T extends Entity, 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`. */
-export 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 | undefined;
-    get isLoadedCache(): IsLoadedCache;
-    pluginManager: PluginManager;
-    clearDataloaders(): void;
-    clearPreloadedRelations(): void;
-    markMaybePending(entity: EntityW): void;
-    unmarkMaybePending(entity: EntityW): void;
-    hasAnyDeletes(): boolean;
-    pendingDeleteIds(type: MaybeAbstractEntityConstructor<Entity>): readonly IdType[];
-    setIsRefreshing(isRefreshing: boolean): void;
-}
-export declare function getEmInternalApi(em: EntityManager): EntityManagerInternalApi;
-export declare function getDefaultEntityLimit(): number;
-export declare function setDefaultEntityLimit(limit: number): void;
-export declare function resetDefaultEntityLimit(): void;
-export declare function isKey(k: any): k is string;
-/** Compares `a` to `b`, where `b` might be an id. */
-export 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. */
-export 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. */
-export declare class NotFoundError extends Error {
-}
-/** Thrown by `findOne` and `findOneOrFail` if more than one entity is found. */
-export declare class TooManyError extends Error {
-    constructor(message: string);
-}
-export declare function driverBeforeBegin<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
-export declare function driverAfterBegin<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
-export declare function driverBeforeCommit<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
-export declare function driverAfterCommit<TXN>(em: EntityManager<any, any, TXN>, txn: TXN): Promise<unknown>;
-export declare function isDefined<T extends any>(param: T | undefined | null): param is T;
-export declare function setLastNow(now: Date | undefined): void;
-/** An error thrown when `em.mode === "read-only"` but entities are mutated/flushed. */
-export 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
- */
-export declare function appendStack(err: unknown, dummy: Error): unknown;
-export declare function createRowFromEntityData(e: Entity, opts?: {
-    preferOriginalData?: boolean;
-}): Record<string, any>;
-export {};
-//# sourceMappingURL=EntityManager.d.ts.map