joist-orm 0.1.538 → 1.0.0

package/build/{BaseEntity.d.ts → src/BaseEntity.d.ts}

@@ -4,7 +4,7 @@ import { Entity, EntityManager, EntityOrmField, IdOf, OptsOf, PartialOrNull } fr
  *
  * Currently this just adds the `.load(lensFn)` method for declarative reference traversal.
  */
-export declare abstract class BaseEntity implements Entity {
+export declare abstract class BaseEntity<EM extends EntityManager = EntityManager> implements Entity {
     abstract id: string | undefined;
     readonly __orm: EntityOrmField;
     protected constructor(em: EntityManager, metadata: any, defaultValues: object, opts: any);
@@ -23,6 +23,7 @@ export declare abstract class BaseEntity implements Entity {
     get isPendingFlush(): boolean;
     get isPendingDelete(): boolean;
     toString(): string;
+    get em(): EM;
     /**
      * A very simple toJSON.
      *

package/build/{BaseEntity.js → src/BaseEntity.js}

@@ -9,28 +9,29 @@ const index_1 = require("./index");
  */
 class BaseEntity {
     constructor(em, metadata, defaultValues, opts) {
-        this.__orm = { em, metadata, data: { ...defaultValues }, originalData: {} };
+        this.__orm = { em, metadata, data: { ...defaultValues }, originalData: {}, isNew: true, isTouched: false };
         // Ensure we have at least id set so the `EntityManager.register` works
         if (typeof opts === "string") {
             this.__orm.data["id"] = opts;
+            this.__orm.isNew = false;
         }
         em.register(metadata, this);
     }
     get idUntagged() {
         if (this.id) {
-            return index_1.deTagIds(index_1.getMetadata(this), [this.id])[0];
+            return (0, index_1.deTagIds)((0, index_1.getMetadata)(this), [this.id])[0];
         }
         return undefined;
     }
     get idUntaggedOrFail() {
-        return this.idUntagged || index_1.fail("Entity has no id yet");
+        return this.idUntagged || (0, index_1.fail)("Entity has no id yet");
     }
     /** @returns the current entity id or a runtime error if it's unassigned, i.e. it's not been assigned from the db yet. */
     get idOrFail() {
-        return this.__orm.data["id"] || index_1.fail("Entity has no id yet");
+        return this.__orm.data["id"] || (0, index_1.fail)("Entity has no id yet");
     }
     get isNewEntity() {
-        return this.id === undefined;
+        return this.__orm.isNew;
     }
     get isDeletedEntity() {
         return this.__orm.deleted !== undefined;
@@ -39,18 +40,21 @@ class BaseEntity {
         return Object.keys(this.__orm.originalData).length > 0;
     }
     get isPendingFlush() {
-        return this.isNewEntity || this.isDirtyEntity || this.isPendingDelete;
+        return this.isNewEntity || this.isDirtyEntity || this.isPendingDelete || this.__orm.isTouched;
     }
     get isPendingDelete() {
         return this.__orm.deleted === "pending";
     }
     toString() {
-        const meta = index_1.getMetadata(this);
+        const meta = (0, index_1.getMetadata)(this);
         // Strip the tag because we add back the entity prefix
-        const id = index_1.keyToNumber(meta, this.id) || "new";
+        const id = (0, index_1.keyToNumber)(meta, this.id) || "new";
         // Returns `Author:1` instead of `author:1` to differentiate the instance's toString from the tagged id itself
         return `${meta.type}:${id}`;
     }
+    get em() {
+        return this.__orm.em;
+    }
     /**
      * A very simple toJSON.
      *
@@ -62,7 +66,7 @@ class BaseEntity {
     toJSON() {
         return Object.fromEntries(Object.entries(this.__orm.data).map(([key, value]) => {
             // Don't recurse into new entities b/c the point is to stay shallow
-            return [key, index_1.isEntity(value) ? value.toString() : value];
+            return [key, (0, index_1.isEntity)(value) ? value.toString() : value];
         }));
     }
     [Symbol.toStringTag]() {

package/build/src/BaseEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseEntity.js","sourceRoot":"","sources":["../../src/BaseEntity.ts"],"names":[],"mappings":"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"}

package/build/{EntityManager.d.ts → src/EntityManager.d.ts}

@@ -1,21 +1,22 @@
 /// <reference types="node" />
 import { AsyncLocalStorage } from "async_hooks";
 import DataLoader from "dataloader";
-import Knex, { QueryBuilder } from "knex";
-import { JoinRow } from "./collections/ManyToManyCollection";
-import { Collection, ColumnSerde, ConfigApi, DeepPartialOrNull, LoadedCollection, LoadedReference, PartialOrNull, Reference, Relation } from "./index";
-import { NullOrDefinedOr } from "./utils";
+import { Knex } from "knex";
+import { Driver } from "./drivers/driver";
+import { ConfigApi, DeepPartialOrNull, FieldSerde, PartialOrNull, PolymorphicKeySerde } from "./index";
+import { Loaded, LoadHint, New } from "./loaded";
+import { JoinRow } from "./relations/ManyToManyCollection";
 export interface EntityConstructor<T> {
-    new (em: EntityManager, opts: any): T;
+    new (em: EntityManager<any>, opts: any): T;
 }
 /** Return the `FooOpts` type a given `Foo` entity constructor. */
 export declare type OptsOf<T> = T extends {
-    __types: {
+    __orm: {
         optsType: infer O;
     };
 } ? O : never;
 export declare type OptIdsOf<T> = T extends {
-    __types: {
+    __orm: {
         optIdsType: infer O;
     };
 } ? O : never;
@@ -23,19 +24,19 @@ export declare type OptIdsOf<T> = T extends {
 export declare type EntityOf<C> = C extends new (em: EntityManager, opts: any) => infer T ? T : never;
 /** Pulls the entity query type out of a given entity type T. */
 export declare type FilterOf<T> = T extends {
-    __types: {
+    __orm: {
         filterType: infer Q;
     };
 } ? Q : never;
 /** Pulls the entity GraphQL query type out of a given entity type T. */
 export declare type GraphQLFilterOf<T> = T extends {
-    __types: {
+    __orm: {
         gqlFilterType: infer Q;
     };
 } ? Q : never;
 /** Pulls the entity order type out of a given entity type T. */
 export declare type OrderOf<T> = T extends {
-    __types: {
+    __orm: {
         orderType: infer Q;
     };
 } ? Q : never;
@@ -45,7 +46,7 @@ export declare type OrderOf<T> = T extends {
  * This is because `FactoryOpts` is a set of defaults, but the user can customize it if they want.
  */
 export declare type ActualFactoryOpts<T> = T extends {
-    __types: {
+    __orm: {
         factoryOptsType: infer Q;
     };
 } ? Q : never;
@@ -53,6 +54,7 @@ export declare type ActualFactoryOpts<T> = T extends {
 export declare type IdOf<T> = T extends {
     id: infer I | undefined;
 } ? I : never;
+export declare function isId(value: any): value is IdOf<unknown>;
 /** The `__orm` metadata field we track on each instance. */
 export interface EntityOrmField {
     /** A point to our entity type's metadata. */
@@ -65,6 +67,10 @@ export interface EntityOrmField {
     deleted?: "pending" | "deleted";
     /** All entities must be associated to an `EntityManager` to handle lazy loading/etc. */
     em: EntityManager;
+    /** Whether our entity is new or not. */
+    isNew: boolean;
+    /** Whether our entity should flush regardless of any other changes. */
+    isTouched: boolean;
 }
 export declare let currentlyInstantiatingEntity: Entity | undefined;
 /** A marker/base interface for all of our entity types. */
@@ -72,6 +78,7 @@ export interface Entity {
     id: string | undefined;
     idOrFail: string;
     __orm: EntityOrmField;
+    readonly em: EntityManager<any>;
     readonly isNewEntity: boolean;
     readonly isDeletedEntity: boolean;
     readonly isDirtyEntity: boolean;
@@ -80,78 +87,54 @@ export interface Entity {
     set(opts: Partial<OptsOf<this>>): void;
     setPartial(values: PartialOrNull<OptsOf<this>>): void;
 }
-/** Marks a given `T[P]` as the loaded/synchronous version of the collection. */
-declare type MarkLoaded<T extends Entity, P, H = {}> = P extends Reference<T, infer U, infer N> ? LoadedReference<T, Loaded<U, H>, N> : P extends Collection<T, infer U> ? LoadedCollection<T, Loaded<U, H>> : unknown;
+declare type MaybePromise<T> = T | PromiseLike<T>;
+export declare type EntityManagerHook = "beforeTransaction" | "afterTransaction";
+declare type HookFn = (em: EntityManager, knex: Knex.Transaction) => MaybePromise<any>;
 /**
- * A helper type for `New` that marks every `Reference` and `LoadedCollection` in `T` as loaded.
- *
- * We also look in opts `O` for the "`U`" type, i.e. the next level up/down in the graph,
- * because the call site's opts may be using an also-marked loaded parent/child as an opt,
- * so this will infer the type of that parent/child and use that for the `U` type.
+ * A marker to prevent setter calls during `flush` calls.
  *
- * This means things like `entity.parent.get.grandParent.get` will work on the resulting
- * type.
+ * The `flush` process does a dirty check + SQL flush and generally doesn't want
+ * entities to re-dirtied after it's done the initial dirty check. So we'd like
+ * to prevent all setter calls while `flush` is running.
  *
- * Note that this is also purposefully broken out of `New` because of some weirdness
- * around type narrowing that wasn't working when inlined into `New`.
- */
-declare type MaybeUseOptsType<T extends Entity, O, K extends keyof T & keyof O> = O[K] extends NullOrDefinedOr<infer OK> ? OK extends Entity ? T[K] extends Reference<T, infer U, infer N> ? LoadedReference<T, OK, N> : never : OK extends Array<infer OU> ? OU extends Entity ? T[K] extends Collection<T, infer U> ? LoadedCollection<T, OU> : never : never : T[K] : never;
-/**
- * Marks all references/collections of `T` as loaded, i.e. for newly instantiated entities where
- * we know there are no already-existing rows with fk's to this new entity in the database.
+ * That said, lifecycle code like hooks actually can make setter calls b/c `flush`
+ * invokes them at a specific point in its process.
  *
- * `O` is the generic from the call site so that if the caller passes `{ author: SomeLoadedAuthor }`,
- * we'll prefer that type, as it might have more nested load hints that we can't otherwise assume.
+ * We solve this by using node's `AsyncLocalStorage` to mark certain callbacks (promise
+ * handlers) as blessed / invoked-from-`flush`-itself, and they are allowed to call setters,
+ * but any external callers (i.e. application code) will be rejected.
  */
-export declare type New<T extends Entity, O extends OptsOf<T> = OptsOf<T>> = T & {
-    [K in keyof T]: K extends keyof O ? MaybeUseOptsType<T, O, K> : MarkLoaded<T, T[K]>;
-};
-/** Given an entity `T` that is being populated with hints `H`, marks the `H` attributes as populated. */
-export declare type Loaded<T extends Entity, H extends LoadHint<T>> = T & {
-    [K in keyof T]: H extends NestedLoadHint<T> ? LoadedIfInNestedHint<T, K, H> : H extends ReadonlyArray<infer U> ? LoadedIfInKeyHint<T, K, U> : LoadedIfInKeyHint<T, K, H>;
-};
-declare type LoadedIfInNestedHint<T extends Entity, K extends keyof T, H> = K extends keyof H ? MarkLoaded<T, T[K], H[K]> : unknown;
-declare type LoadedIfInKeyHint<T extends Entity, K extends keyof T, H> = K extends H ? MarkLoaded<T, T[K]> : unknown;
-/** From any non-`Relations` field in `T`, i.e. for loader hints. */
-export declare type RelationsIn<T extends Entity> = SubType<T, Relation<any, any>>;
-declare type SubType<T, C> = Pick<T, {
-    [K in keyof T]: T[K] extends C ? K : never;
-}[keyof T]>;
-export declare type LoadHint<T extends Entity> = keyof RelationsIn<T> | ReadonlyArray<keyof RelationsIn<T>> | NestedLoadHint<T>;
-declare type NestedLoadHint<T extends Entity> = {
-    [K in keyof RelationsIn<T>]?: T[K] extends Relation<T, infer U> ? LoadHint<U> : never;
-};
-export declare type LoaderCache = Record<string, DataLoader<any, any>>;
-declare type MaybePromise<T> = T | PromiseLike<T>;
-export declare type EntityManagerHook = "beforeTransaction";
-declare type HookFn = (em: EntityManager, knex: Knex.Transaction) => MaybePromise<any>;
-export declare type HasKnex = {
-    knex: Knex;
-};
 export declare const currentFlushSecret: AsyncLocalStorage<{
     flushSecret: number;
 }>;
-export declare class EntityManager<C extends HasKnex = HasKnex> {
-    private readonly ctx;
-    knex: Knex;
-    constructor(em: EntityManager<C>);
-    constructor(ctx: C);
+export declare type LoaderCache = Record<string, DataLoader<any, any>>;
+export interface FlushOptions {
+    /** Skip all validations, including reactive validations, when flushing */
+    skipValidation?: boolean;
+}
+export declare class EntityManager<C = {}> {
+    readonly ctx: C;
+    driver: Driver;
+    currentTxnKnex: Knex | undefined;
     private _entities;
     private _entityIndex;
-    private findLoaders;
     private flushSecret;
     private _isFlushing;
+    loadLoaders: LoaderCache;
+    findLoaders: LoaderCache;
     __data: {
-        loaders: Record<string, DataLoader<any, any, any>>;
         joinRows: Record<string, JoinRow[]>;
     };
     private hooks;
+    constructor(em: EntityManager<C>);
+    constructor(ctx: C, driver: Driver);
+    /** Returns a read-only shallow copy of the currently-loaded entities. */
     get entities(): ReadonlyArray<Entity>;
+    /** Looks up `id` in the list of already-loaded entities. */
+    getEntity<T extends Entity>(id: IdOf<T>): T | undefined;
     find<T extends Entity>(type: EntityConstructor<T>, where: FilterOf<T>): Promise<T[]>;
-    find<T extends Entity, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(type: EntityConstructor<T>, where: FilterOf<T>, options?: {
-        populate?: H;
+    find<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, where: FilterOf<T>, options?: {
+        populate?: Const<H>;
         orderBy?: OrderOf<T>;
         limit?: number;
         offset?: number;
@@ -162,26 +145,20 @@ export declare class EntityManager<C extends HasKnex = HasKnex> {
      * I.e. filtering by `null` on fields that are non-`nullable`.
      */
     findGql<T extends Entity>(type: EntityConstructor<T>, where: GraphQLFilterOf<T>): Promise<T[]>;
-    findGql<T extends Entity, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(type: EntityConstructor<T>, where: GraphQLFilterOf<T>, options?: {
-        populate?: H;
+    findGql<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, where: GraphQLFilterOf<T>, options?: {
+        populate?: Const<H>;
         orderBy?: OrderOf<T>;
         limit?: number;
         offset?: number;
     }): Promise<Loaded<T, H>[]>;
     findOne<T extends Entity>(type: EntityConstructor<T>, where: FilterOf<T>): Promise<T | undefined>;
-    findOne<T extends Entity, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(type: EntityConstructor<T>, where: FilterOf<T>, options?: {
-        populate: H;
+    findOne<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, where: FilterOf<T>, options?: {
+        populate: Const<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: EntityConstructor<T>, where: FilterOf<T>): Promise<T>;
-    findOneOrFail<T extends Entity, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(type: EntityConstructor<T>, where: FilterOf<T>, options: {
-        populate: H;
+    findOneOrFail<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, where: FilterOf<T>, options: {
+        populate: Const<H>;
     }): Promise<Loaded<T, H>>;
     /**
      * Conditionally finds or creates an Entity.
@@ -196,36 +173,53 @@ export declare class EntityManager<C extends HasKnex = HasKnex> {
      * @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>> | {}, O extends Omit<OptsOf<T>, keyof F | keyof U>>(type: EntityConstructor<T>, where: F, ifNew: O, upsert?: U): Promise<T>;
-    findOrCreate<T extends Entity, F extends Partial<OptsOf<T>>, U extends Partial<OptsOf<T>> | {}, O extends Omit<OptsOf<T>, keyof F | keyof U>, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(type: EntityConstructor<T>, where: F, ifNew: O, upsert?: U, populate?: H): Promise<Loaded<T, H>>;
+    findOrCreate<T extends Entity, F extends Partial<OptsOf<T>>, U extends Partial<OptsOf<T>> | {}, O extends Omit<OptsOf<T>, keyof F | keyof U>, H extends LoadHint<T>>(type: EntityConstructor<T>, where: F, ifNew: O, upsert?: U, populate?: Const<H>): 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. */
     createPartial<T extends Entity>(type: EntityConstructor<T>, opts: PartialOrNull<OptsOf<T>>): T;
     /** Creates a new `type` but with `opts` that are nullable, to accept partial-update-style input. */
     createOrUpdatePartial<T extends Entity>(type: EntityConstructor<T>, opts: DeepPartialOrNull<T>): Promise<T>;
+    /**
+     * Utility to clone an entity and its nested relations, as determined by a populate hint
+     *
+     * @param entity - Any entity
+     * @param hint - A populate hint
+     *
+     * @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, "books")
+     *
+     * @exmaple
+     * // This will duplicate the author, all their books, and the images for those books
+     * const duplicatedAuthorAndBooksAndImages = await em.clone(author, {books: "image"})
+     */
+    clone<T extends Entity, H extends LoadHint<T>>(entity: T, hint?: H): Promise<Loaded<T, H>>;
     /** Returns an instance of `type` for the given `id`, resolving to an existing instance if in our Unit of Work. */
+    load<T>(id: IdOf<T>): Promise<T>;
+    load(id: string): Promise<Entity>;
     load<T extends Entity>(type: EntityConstructor<T>, id: string): Promise<T>;
-    load<T extends Entity, H extends LoadHint<T> & {
-        [k: string]: N | T | [];
-    }, N extends Narrowable>(type: EntityConstructor<T>, id: string, populate: H): Promise<Loaded<T, H>>;
-    load<T extends Entity, H extends LoadHint<T> & (N | N[]), N extends Narrowable>(type: EntityConstructor<T>, id: string, populate: H): Promise<Loaded<T, H>>;
+    load<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, id: string, populate: Const<H>): Promise<Loaded<T, H>>;
+    load<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, id: string, populate: Const<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: EntityConstructor<T>, ids: string[]): Promise<T[]>;
-    loadAll<T extends Entity, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(type: EntityConstructor<T>, ids: string[], populate: H): Promise<Loaded<T, H>[]>;
+    loadAll<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, ids: string[], populate: Const<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: string[]): Promise<T[]>;
+    loadAllIfExists<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, ids: string[], populate: Const<H>): Promise<Loaded<T, H>[]>;
     /** Loads entities from a knex QueryBuilder. */
-    loadFromQuery<T extends Entity>(type: EntityConstructor<T>, query: QueryBuilder): Promise<T[]>;
-    loadFromQuery<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, query: QueryBuilder, populate: H): Promise<Loaded<T, H>[]>;
+    loadFromQuery<T extends Entity>(type: EntityConstructor<T>, query: Knex.QueryBuilder): Promise<T[]>;
+    loadFromQuery<T extends Entity, H extends LoadHint<T>>(type: EntityConstructor<T>, query: Knex.QueryBuilder, 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, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(entity: T, hint: H): Promise<Loaded<T, H>>;
-    populate<T extends Entity, H extends LoadHint<T> & ({
-        [k: string]: N | H | [];
-    } | N | N[]), N extends Narrowable>(entities: ReadonlyArray<T>, hint: H): Promise<Loaded<T, H>[]>;
+    populate<T extends Entity, H extends LoadHint<T>>(entity: T, hint: Const<H>): Promise<Loaded<T, H>>;
+    populate<T extends Entity, H extends LoadHint<T>>(entities: ReadonlyArray<T>, hint: Const<H>): Promise<Loaded<T, H>[]>;
     /**
      * Executes `fn` with a transaction, and automatically calls `flush`/`commit` at the end.
      *
@@ -258,8 +252,10 @@ export declare class EntityManager<C extends HasKnex = HasKnex> {
      * 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(): Promise<void>;
+    flush(flushOptions?: FlushOptions): Promise<Entity[]>;
     get isFlushing(): boolean;
     /**
      * A very simple toJSON.
@@ -284,9 +280,7 @@ export declare class EntityManager<C extends HasKnex = HasKnex> {
     refresh(entity: Entity): Promise<void>;
     refresh(entities: ReadonlyArray<Entity>): Promise<void>;
     get numberOfEntities(): number;
-    private loaderForFind;
-    private loaderForEntity;
-    private findExistingInstance;
+    findExistingInstance<T>(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.
      *
@@ -299,7 +293,12 @@ export declare class EntityManager<C extends HasKnex = HasKnex> {
     hydrate<T extends Entity>(type: EntityConstructor<T>, row: any, options?: {
         overwriteExisting?: boolean;
     }): T;
+    /**
+     * Mark an entity as needing to be flushed regardless of its state
+     */
+    touch(entity: Entity): void;
     beforeTransaction(fn: HookFn): void;
+    afterTransaction(fn: HookFn): void;
     toString(): string;
 }
 export declare let entityLimit: number;
@@ -308,25 +307,21 @@ export declare function setDefaultEntityLimit(): void;
 export interface EntityMetadata<T extends Entity> {
     cstr: EntityConstructor<T>;
     type: string;
+    idType: "int" | "uuid";
     tableName: string;
     tagName: string;
-    columns: Array<ColumnMeta>;
-    fields: Array<Field>;
+    fields: Record<string, Field>;
     config: ConfigApi<T, any>;
     factory: (em: EntityManager, opts?: any) => New<T>;
 }
-export declare type ColumnMeta = {
-    fieldName: string;
-    columnName: string;
-    dbType: string;
-    serde: ColumnSerde;
-};
-export declare type Field = PrimaryKeyField | PrimitiveField | EnumField | OneToManyField | ManyToOneField | ManyToManyField | OneToOneField;
+export declare type Field = PrimaryKeyField | PrimitiveField | EnumField | OneToManyField | LargeOneToManyField | ManyToOneField | ManyToManyField | OneToOneField | PolymorphicField;
+export declare type SerdeField = PrimaryKeyField | PrimitiveField | EnumField | ManyToOneField | PolymorphicField;
 export declare type PrimaryKeyField = {
     kind: "primaryKey";
     fieldName: string;
     fieldIdName: undefined;
     required: true;
+    serde: FieldSerde;
 };
 export declare type PrimitiveField = {
     kind: "primitive";
@@ -336,6 +331,7 @@ export declare type PrimitiveField = {
     derived: "orm" | "sync" | "async" | false;
     protected: boolean;
     type: string | Function;
+    serde: FieldSerde;
 };
 export declare type EnumField = {
     kind: "enum";
@@ -345,6 +341,7 @@ export declare type EnumField = {
     enumDetailType: {
         getValues(): ReadonlyArray<unknown>;
     };
+    serde: FieldSerde;
 };
 export declare type OneToManyField = {
     kind: "o2m";
@@ -353,6 +350,16 @@ export declare type OneToManyField = {
     required: boolean;
     otherMetadata: () => EntityMetadata<any>;
     otherFieldName: string;
+    serde: undefined;
+};
+export declare type LargeOneToManyField = {
+    kind: "lo2m";
+    fieldName: string;
+    fieldIdName: string;
+    required: boolean;
+    otherMetadata: () => EntityMetadata<any>;
+    otherFieldName: string;
+    serde: undefined;
 };
 export declare type ManyToOneField = {
     kind: "m2o";
@@ -361,6 +368,7 @@ export declare type ManyToOneField = {
     required: boolean;
     otherMetadata: () => EntityMetadata<any>;
     otherFieldName: string;
+    serde: FieldSerde;
 };
 export declare type ManyToManyField = {
     kind: "m2m";
@@ -369,6 +377,7 @@ export declare type ManyToManyField = {
     required: boolean;
     otherMetadata: () => EntityMetadata<any>;
     otherFieldName: string;
+    serde: undefined;
 };
 export declare type OneToOneField = {
     kind: "o2o";
@@ -377,18 +386,38 @@ export declare type OneToOneField = {
     required: boolean;
     otherMetadata: () => EntityMetadata<any>;
     otherFieldName: string;
+    serde: undefined;
+};
+export declare type PolymorphicField = {
+    kind: "poly";
+    fieldName: string;
+    fieldIdName: string;
+    required: boolean;
+    components: PolymorphicFieldComponent[];
+    serde: PolymorphicKeySerde;
+};
+export declare type PolymorphicFieldComponent = {
+    otherMetadata: () => EntityMetadata<any>;
+    otherFieldName: string;
+    columnName: string;
 };
 export declare function isEntity(maybeEntity: any): maybeEntity is Entity;
 export declare function isKey(k: any): k is string;
 /** Compares `a` to `b`, where `b` might be an id. B/c ids can overlap, we need to know `b`'s metadata type. */
-export declare function sameEntity(a: Entity, bMeta: EntityMetadata<any>, bCurrent: Entity | string | undefined): boolean;
+export declare function sameEntity(a: Entity | undefined, meta: EntityMetadata<any>, b: Entity | string | undefined): boolean;
 export declare function getMetadata<T extends Entity>(entity: T): EntityMetadata<T>;
 export declare function getMetadata<T extends Entity>(type: EntityConstructor<T>): EntityMetadata<T>;
+export declare function getMetadata<T extends Entity>(meta: EntityMetadata<T>): EntityMetadata<T>;
 /** Thrown by `findOneOrFail` 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 {
 }
-declare type Narrowable = string | number | boolean | symbol | object | undefined | void | null | {};
+export declare function beforeTransaction(em: EntityManager, knex: Knex.Transaction): Promise<unknown>;
+export declare function afterTransaction(em: EntityManager, knex: Knex.Transaction): Promise<unknown>;
+declare type Narrowable = string | number | boolean | symbol | object | undefined | void | null | {} | [];
+declare type Const<N> = N | {
+    [K in keyof N]: N[K] extends Narrowable ? N[K] | Const<N[K]> : never;
+};
 export {};