joist-core 2.3.0 → 2.4.0

package/build/relations/ManyToOneReference.d.mts

@@ -0,0 +1,121 @@
+import { AbstractRelationImpl } from "./AbstractRelationImpl.mjs";
+import { RelationT, RelationU } from "./RelationSymbols.mjs";
+import { ReferenceN } from "./ReferenceSymbols.mjs";
+import { Reference } from "./Reference.mjs";
+import { EntityMetadata, ManyToOneField } from "../EntityMetadata.mjs";
+import "../index.mjs";
+import { IdOf, TaggedId } from "../EntityManager.mjs";
+import { Entity } from "../Entity.mjs";
+//#region src/relations/ManyToOneReference.d.ts
+/** An alias for creating `ManyToOneReference`s. */
+declare function hasOne<T extends Entity, U extends Entity, N extends never | undefined>(): ManyToOneReference<T, U, N>;
+/** Type guard utility for determining if an entity field is a ManyToOneReference. */
+declare function isManyToOneReference(maybeReference: any): maybeReference is ManyToOneReference<any, any, any>;
+interface ManyToOneReference<T extends Entity, U extends Entity, N extends never | undefined> extends Reference<T, U, N> {
+  /** Returns the id of the current assigned entity, or a runtime error if either 1) unset or 2) set to a new entity that doesn't have an `id` yet. */
+  id: IdOf<U>;
+  /** Returns the id of the current assigned entity, undefined if unset, or a runtime error if set to a new entity. */
+  idIfSet: IdOf<U> | undefined;
+  /** Returns the id of the current assigned entity, undefined if unset, or undefined if set to a new entity. */
+  idMaybe: IdOf<U> | undefined;
+  idUntagged: string;
+  idUntaggedIfSet: string | undefined;
+  /** Returns `true` if this relation is currently set (i.e. regardless of whether it's loaded, or if it is set but the assigned entity doesn't have an id saved. */
+  readonly isSet: boolean;
+}
+/**
+ * Manages a foreign key from one entity to another, i.e. `Book.author --> Author`.
+ *
+ * We keep the current `author` / `author_id` value in the `__orm.data` hash, where the
+ * current value could be either the (string) author id from the database, or an entity
+ * `Author` that the user has set.
+ *
+ * Note that if our `images.author_id` column is unique, this `ManyToOneReference` will essentially
+ * be half of a one-to-one relationship, but we'll keep using this `ManyToOneReference` on the "many"
+ * side, and the other side, i.e. `Author.image` will use a `OneToOneReference` to point back to us.
+ */
+declare class ManyToOneReferenceImpl<T extends Entity, U extends Entity, N extends never | undefined> extends AbstractRelationImpl<T, U> implements ManyToOneReference<T, U, N> {
+  #private;
+  constructor(entity: T, field: ManyToOneField);
+  load(opts?: {
+    withDeleted?: boolean;
+    forceReload?: boolean;
+  }): Promise<U | N>;
+  set(other: U | N): void;
+  get isSet(): boolean;
+  get isLoaded(): boolean;
+  get isPreloaded(): boolean;
+  preload(): void;
+  private unload;
+  /** Copy another em's `source` relation into our state. */
+  import(source: ManyToOneReferenceImpl<T, U, N>, findEntity: (e: U) => U): void;
+  private doGet;
+  get getWithDeleted(): U | N;
+  get get(): U | N;
+  /** Returns the id of the current value. */
+  get id(): IdOf<U>;
+  /** Sets the m2o to `id`, and allows accepting `undefined` (`N`) if this is a nullable relation. */
+  set id(id: IdOf<U> | N);
+  get idIfSet(): IdOf<U> | N | undefined;
+  get idUntagged(): string;
+  get idUntaggedIfSet(): string | undefined;
+  get idMaybe(): IdOf<U> | N | undefined;
+  /** Returns the tagged id of the current value, or undefined if unset or a new entity. */
+  get idTaggedMaybe(): TaggedId | undefined;
+  get fieldName(): string;
+  get otherFieldName(): keyof U & string;
+  private get idUntaggedMaybe();
+  setFromOpts(other: U | IdOf<U> | N): void;
+  maybeCascadeDelete(): void;
+  cleanupOnEntityDeleted(): Promise<void>;
+  current(opts?: {
+    withDeleted?: boolean;
+  }): U | TaggedId | N;
+  get otherMeta(): EntityMetadata<U>;
+  get hasBeenSet(): boolean;
+  toString(): string;
+  /**
+   * Removes pending-hard-delete (but not soft-deleted), unless explicitly asked for.
+   *
+   * Note that we leave soft-deleted entities b/c the call signature of a `book.author.get`
+   * very likely does not expect a soft-deleted entity to result in `undefined`.
+   *
+   * (Contrasted with `author.books.get` which is more intuitive to have soft-deleted
+   * entities filtered out, i.e. it doesn't fundamentally change the return type.)
+   */
+  private filterDeleted;
+  /** Returns the other relation that points back at us, i.e. we're `book.author_id` and this is `Author.books`. */
+  private getOtherRelation;
+  private get isCascadeDelete();
+  /**
+   * Looks for an entity in `EntityManager`, b/c we may have it in memory even if
+   * our reference is not specifically loaded.
+   */
+  maybeFindEntity(): U | undefined;
+  [RelationT]: T;
+  [RelationU]: U;
+  [ReferenceN]: N;
+}
+/**
+ * Fails when we can't return an `.id` for a reference, i.e. it's unset or a new entity.
+ *
+ * We strictly type `book.author.id` as `AuthorId`, even if `book.author` is nullable, to
+ * avoid users calling `.id` and getting back `undefined`, but not because "there is no
+ * author", but only because "the assigned author doesn't have an id assigned yet".
+ *
+ * To handle nullable references, set `.idIfSet`.
+ *
+ * Assumes being called like `return idMaybe ?? failNoId()`, i.e. if we're called we
+ * know the id is not available.
+ */
+declare function failNoId(entity: Entity, fieldName: string, current: string | Entity | undefined): never;
+/**
+ * Fails when we can't return an `.idIfSet` for a reference, i.e. it's a new entity.
+ *
+ * Assumes being called like `return idMaybe ?? failIfNewEntity()`, i.e. if we're called we
+ * know the id is not available.
+ */
+declare function failIfNewEntity(entity: Entity, fieldName: string, current: string | Entity | undefined): undefined;
+//#endregion
+export { ManyToOneReference, ManyToOneReferenceImpl, failIfNewEntity, failNoId, hasOne, isManyToOneReference };
+//# sourceMappingURL=ManyToOneReference.d.mts.map

package/build/relations/ManyToOneReference.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManyToOneReference.d.mts","names":[],"sources":["../../src/relations/ManyToOneReference.ts"],"mappings":";;;;;;;;;;iBA4BgB,OAAO,UAAU,QAAQ,UAAU,QAAQ,gCAAgC,mBAAmB,GAAG,GAAG;;iBAQpG,qBAAqB,sBAAsB,kBAAkB;UAI5D,mBAAmB,UAAU,QAAQ,UAAU,QAAQ,qCAAqC,UAC3G,GACA,GACA;;EAGA,IAAI,KAAK;;EAGT,SAAS,KAAK;;EAGd,SAAS,KAAK;EAEd;EAEA;;WAGS;;;;;;;;;;;;;cAcE,uBAAuB,UAAU,QAAQ,UAAU,QAAQ,qCAC9D,qBAAqB,GAAG,cACrB,mBAAmB,GAAG,GAAG;;EAOpC,YAAY,QAAQ,GAAG,OAAO;EAQxB,KAAK;IAAQ;IAAuB;MAA+B,QAAQ,IAAI;EAqBrF,IAAI,OAAO,IAAI;MAIX;MAIA;MAMA;EAIJ;UAIQ;;EAMR,OAAO,QAAQ,uBAAuB,GAAG,GAAG,IAAI,aAAa,GAAG,MAAM;UAI9D;MAMJ,kBAAkB,IAAI;MAItB,OAAO,IAAI;;MAKX,MAAM,KAAK;;MAKX,GAAG,IAAI,KAAK,KAAK;MAkBjB,WAAW,KAAK,KAAK;MAIrB;MAIA;MAIA,WAAW,KAAK,KAAK;;MAMrB,iBAAiB;MAMjB;MAIA,wBAAwB;cAIhB;EAiCZ,YAAY,OAAO,IAAI,KAAK,KAAK;EAIjC;EAgBM,0BAA0B;EAqFhC,QAAQ;IAAS;MAA0B,IAAI,WAAW;MAQtD,aAAa,eAAe;MAI5B;EAIG;;;;;;;;;;UAaC;;UAQA;cAMI;;;;;EAQZ,mBAAmB;GAQlB,YAAY;GACZ,YAAY;GACZ,aAAa;;;;;;;;;;;;;;iBAeA,SAAS,QAAQ,QAAQ,mBAAmB,kBAAkB;;;;;;;iBAc9D,gBAAgB,QAAQ,QAAQ,mBAAmB,kBAAkB"}