joist-orm 0.1.536 → 1.0.0

package/src/collections/CustomCollection.ts

@@ -1,152 +0,0 @@
-import { Entity, IdOf } from "../EntityManager";
-import { Collection, ensureNotDeleted, fail } from "../index";
-import { AbstractRelationImpl } from "./AbstractRelationImpl";
-
-export type CustomCollectionOpts<T extends Entity, U extends Entity> = {
-  // We purposefully don't capture the return value of `load` b/c we want `get` to re-calc from `entity`
-  // each time it's invoked so that it reflects any changed values.
-  load: (entity: T) => Promise<any>;
-  get: (entity: T) => readonly U[];
-  set?: (entity: T, other: U[]) => void;
-  find?: (entity: T, id: IdOf<U>) => U | undefined;
-  add?: (entity: T, other: U) => void;
-  remove?: (entity: T, other: U) => void;
-};
-
-/**
- * Allows user-defined collections that will work in `populate` / preload hints.
- *
- * This works because Joist's `populate`/preloading is not based on creating giant SQL joins,
- * but instead by just walking "1 dataloader per level". Given this, we don't really care
- * what happens at each "level" of resolution, as long as: a) it's a promise, and b) the
- * caller uses dataloader to be batch friendly.
- *
- * This `CustomCollection` API is fairly low-level; users should more likely prefer higher-level
- * abstractions like `hasManyThrough`, which are built on `CustomCollection.
- */
-export class CustomCollection<T extends Entity, U extends Entity> extends AbstractRelationImpl<U[]>
-  implements Collection<T, U> {
-  // We keep both a promise+loaded flag and not an actual `this.loaded = await load` because
-  // the values can become stale; we want to each `.get` call to repeatedly evaluate the latest values.
-  private loadPromise: Promise<any> | undefined;
-  private _isLoaded = false;
-
-  constructor(public entity: T, private opts: CustomCollectionOpts<T, U>) {
-    super();
-  }
-
-  get get(): readonly U[] {
-    return this.doGet({ withDeleted: false });
-  }
-
-  get getWithDeleted(): readonly U[] {
-    return this.doGet({ withDeleted: true });
-  }
-
-  get isLoaded(): boolean {
-    return this._isLoaded;
-  }
-
-  async load(opts?: { withDeleted?: boolean }): Promise<readonly U[]> {
-    ensureNotDeleted(this.entity, { ignore: "pending" });
-    if (!this.isLoaded) {
-      if (this.loadPromise === undefined) {
-        this.loadPromise = this.opts.load(this.entity);
-        await this.loadPromise;
-        this.loadPromise = undefined;
-        this._isLoaded = true;
-      } else {
-        await this.loadPromise;
-      }
-    }
-
-    return this.doGet(opts);
-  }
-
-  initializeForNewEntity(): void {
-    // Normally we flag relations as loaded if created on a new entity, however CustomCollections
-    // might require crawling N-layers down from our initial opts, i.e. if creating a BookReview
-    // with a book, accessing review.author maybe not necessarily be safe to do immediately b/c
-    // we need to load book.author to successfully evaluated review -> book -> author synchronously.
-    // this._isLoaded = true;
-  }
-
-  set(values: U[]): void {
-    ensureNewOrLoaded(this);
-    const { set, add, remove } = this.opts;
-    if (set !== undefined) {
-      set(this.entity, values);
-    } else if (add !== undefined && remove !== undefined) {
-      const current = this.get;
-      current.filter((value) => !values.includes(value)).forEach((value) => this.remove(value));
-      values.filter((value) => !current.includes(value)).forEach((value) => this.add(value));
-    } else {
-      fail(`'set' not implemented and not inferrable from 'add'/'remove' on ${this}`);
-    }
-  }
-
-  setFromOpts(values: U[]): void {
-    this.set(values);
-  }
-
-  async find(id: IdOf<U>): Promise<U | undefined> {
-    if (!this.isLoaded) {
-      await this.load();
-    }
-    const { find } = this.opts;
-    if (find === undefined) {
-      return this.doGet().find((other) => other.id === id);
-    } else {
-      return find(this.entity, id);
-    }
-  }
-
-  add(other: U): void {
-    ensureNewOrLoaded(this);
-    const { add } = this.opts;
-    if (add === undefined) {
-      fail(`'add' not implemented on ${this}`);
-    }
-    add(this.entity, other);
-  }
-
-  remove(other: U): void {
-    ensureNewOrLoaded(this);
-    const { remove } = this.opts;
-    if (remove === undefined) {
-      fail(`'add' not implemented on ${this}`);
-    }
-    remove(this.entity, other);
-  }
-
-  // these callbacks should be no-ops as they ought to be handled by the underlying relations
-  async onEntityDeletedAndFlushing(): Promise<void> {}
-  onEntityDelete(): void {}
-  async refreshIfLoaded(): Promise<void> {}
-
-  /** Finds this CustomCollections field name by looking in the entity for the key that we're assigned to. */
-  get fieldName(): string {
-    return Object.entries(this.entity).filter((e) => e[1] === this)[0][0];
-  }
-
-  toString(): string {
-    return `CustomCollection(entity: ${this.entity}, fieldName: ${this.fieldName})`;
-  }
-
-  private doGet(opts?: { withDeleted?: boolean }): readonly U[] {
-    ensureNotDeleted(this.entity, { ignore: "pending" });
-    ensureNewOrLoaded(this);
-    return this.filterDeleted(this.opts.get(this.entity), opts);
-  }
-
-  private filterDeleted(entities: readonly U[], opts?: { withDeleted?: boolean }): readonly U[] {
-    return entities.filter((entity) => opts?.withDeleted === true || !entity.isDeletedEntity);
-  }
-}
-
-function ensureNewOrLoaded(reference: CustomCollection<any, any>) {
-  if (!(reference.isLoaded || reference.entity.isNewEntity)) {
-    // This should only be callable in the type system if we've already resolved this to an instance
-    fail(`${reference.entity}.${reference.fieldName} was not loaded`);
-  }
-}

package/src/collections/CustomReference.ts

@@ -1,138 +0,0 @@
-import { Entity, IdOf } from "../EntityManager";
-import { deTagIds, ensureNotDeleted, fail, Reference, unsafeDeTagIds } from "../index";
-import { AbstractRelationImpl } from "./AbstractRelationImpl";
-
-export type CustomReferenceOpts<T extends Entity, U extends Entity, N extends never | undefined> = {
-  // We purposefully don't capture the return value of `load` b/c we want `get` to re-calc from `entity`
-  // each time it's invoked so that it reflects any changed values.
-  load: (entity: T) => Promise<void>;
-  get: (entity: T) => U | N;
-  set?: (entity: T, other: U) => void;
-};
-
-/**
- * Allows user-defined references that will work in `populate` / preload hints.
- *
- * This works because Joist's `populate`/preloading is not based on creating giant SQL joins,
- * but instead by just walking "1 dataloader per level". Given this, we don't really care
- * what happens at each "level" of resolution, as long as: a) it's a promise, and b) the
- * caller uses dataloader to be batch friendly.
- *
- * This `CustomReference` API is fairly low-level; users should more likely prefer higher-level
- * abstractions like `hasOneThrough`, which are built on `CustomReference.
- */
-export class CustomReference<T extends Entity, U extends Entity, N extends never | undefined>
-  extends AbstractRelationImpl<U>
-  implements Reference<T, U, N> {
-  // We keep both a promise+loaded flag and not an actual `this.loaded = await load` because
-  // the value can become stale; we want to each `.get` call to repeatedly evaluate the latest value.
-  private loadPromise: Promise<void> | undefined;
-  private _isLoaded = false;
-
-  constructor(public entity: T, private opts: CustomReferenceOpts<T, U, N>) {
-    super();
-  }
-
-  get get(): U | N {
-    return this.doGet({ withDeleted: false });
-  }
-
-  get getWithDeleted(): U | N {
-    return this.doGet({ withDeleted: true });
-  }
-
-  get isLoaded(): boolean {
-    return this._isLoaded;
-  }
-
-  async load(opts?: { withDeleted?: boolean }): Promise<U | N> {
-    ensureNotDeleted(this.entity, { ignore: "pending" });
-    if (!this.isLoaded) {
-      if (this.loadPromise === undefined) {
-        this.loadPromise = this.opts.load(this.entity);
-        await this.loadPromise;
-        this.loadPromise = undefined;
-        this._isLoaded = true;
-      } else {
-        await this.loadPromise;
-      }
-    }
-
-    return this.doGet(opts);
-  }
-
-  initializeForNewEntity(): void {
-    // Normally we flag relations as loaded if created on a new entity, however CustomReferences
-    // might require crawling N-layers down from our initial opts, i.e. if creating a BookReview
-    // with a book, accessing review.author maybe not necessarily be safe to do immediately b/c
-    // we need to load book.author to successfully evaluated review -> book -> author synchronously.
-    // this._isLoaded = true;
-  }
-
-  get id(): IdOf<U> | undefined {
-    return fail(`CustomReference cannot resolve 'id'`);
-  }
-
-  get idOrFail(): IdOf<U> {
-    return fail(`CustomReference cannot resolve 'idOrFail'`);
-  }
-
-  get idUntagged(): string | undefined {
-    // We don't know the meta here but that is probably a feature in case this is polymorphic
-    return this.id && unsafeDeTagIds([this.id])[0];
-  }
-
-  get idUntaggedOrFail(): string {
-    return this.idUntagged || fail("Reference is unset or assigned to a new entity");
-  }
-
-  get isSet(): boolean {
-    ensureNewOrLoaded(this);
-    const { get } = this.opts;
-    return get(this.entity) !== undefined;
-  }
-
-  set(value: U): void {
-    ensureNewOrLoaded(this);
-    const { set } = this.opts;
-    if (set === undefined) {
-      throw new Error(`'set' not implemented on ${this}`);
-    }
-    set(this.entity, value);
-  }
-
-  setFromOpts(value: U): void {
-    this.set(value);
-  }
-
-  // these callbacks should be no-ops as they ought to be handled by the underlying relations
-  async onEntityDeletedAndFlushing(): Promise<void> {}
-  onEntityDelete(): void {}
-  async refreshIfLoaded(): Promise<void> {}
-
-  /** Finds this CustomReferences field name by looking in the entity for the key that we're assigned to. */
-  get fieldName(): string {
-    return Object.entries(this.entity).filter((e) => e[1] === this)[0][0];
-  }
-
-  toString(): string {
-    return `CustomReference(entity: ${this.entity}, fieldName: ${this.fieldName})`;
-  }
-
-  private doGet(opts?: { withDeleted?: boolean }): U | N {
-    ensureNotDeleted(this.entity, { ignore: "pending" });
-    ensureNewOrLoaded(this);
-    return this.filterDeleted(this.opts.get(this.entity), opts);
-  }
-
-  private filterDeleted(entity: U | N, opts?: { withDeleted?: boolean }): U | N {
-    return opts?.withDeleted === true || entity === undefined || !entity.isDeletedEntity ? entity : (undefined as N);
-  }
-}
-
-function ensureNewOrLoaded(reference: CustomReference<any, any, any>) {
-  if (!(reference.isLoaded || reference.entity.isNewEntity)) {
-    // This should only be callable in the type system if we've already resolved this to an instance
-    throw new Error(`${reference.entity}.${reference.fieldName} was not loaded`);
-  }
-}

package/src/collections/ManyToManyCollection.ts

@@ -1,346 +0,0 @@
-import DataLoader from "dataloader";
-import {
-  Collection,
-  ensureNotDeleted,
-  Entity,
-  EntityMetadata,
-  getEm,
-  getMetadata,
-  IdOf,
-  keyToNumber,
-  keyToString,
-} from "../";
-import { getOrSet, remove } from "../utils";
-import { AbstractRelationImpl } from "./AbstractRelationImpl";
-
-export class ManyToManyCollection<T extends Entity, U extends Entity> extends AbstractRelationImpl<U[]>
-  implements Collection<T, U> {
-  private loaded: U[] | undefined;
-  private addedBeforeLoaded: U[] = [];
-  private removedBeforeLoaded: U[] = [];
-  private isCascadeDelete: boolean;
-
-  constructor(
-    public joinTableName: string,
-    // I.e. when entity = Book:
-    // fieldName == tags, because it's our collection to tags
-    // columnName = book_id, what we use as the `where book_id = us` to find our join table rows
-    // otherFieldName = books, how tags points to us
-    // otherColumnName = tag_id, how the other side finds its join table rows
-    public entity: T,
-    public fieldName: keyof T,
-    public columnName: string,
-    public otherMeta: EntityMetadata<U>,
-    public otherFieldName: keyof U,
-    public otherColumnName: string,
-  ) {
-    super();
-    this.isCascadeDelete = otherMeta.config.__data.cascadeDeleteFields.includes(fieldName as any);
-  }
-
-  private filterDeleted(entities: U[], opts?: { withDeleted?: boolean }): U[] {
-    return opts?.withDeleted === true ? [...entities] : entities.filter((e) => !e.isDeletedEntity);
-  }
-
-  async load(opts?: { withDeleted?: boolean }): Promise<ReadonlyArray<U>> {
-    ensureNotDeleted(this.entity, { ignore: "pending" });
-    if (this.loaded === undefined) {
-      // TODO This key is basically a Reference, whenever we have that.
-      // TODO Unsaved entities should never get here
-      const key = `${this.columnName}=${this.entity.id}`;
-      this.loaded = await loaderForJoinTable(this).load(key);
-      this.maybeApplyAddedAndRemovedBeforeLoaded();
-    }
-    return this.filterDeleted(this.loaded!, opts) as ReadonlyArray<U>;
-  }
-
-  async find(id: IdOf<U>): Promise<U | undefined> {
-    return (await this.load()).find((u) => u.id === id);
-  }
-
-  add(other: U, percolated = false): void {
-    ensureNotDeleted(this.entity);
-
-    if (this.loaded !== undefined) {
-      if (this.loaded.includes(other)) {
-        return;
-      }
-      this.loaded.push(other);
-    } else {
-      if (this.addedBeforeLoaded.includes(other)) {
-        return;
-      }
-      this.addedBeforeLoaded.push(other);
-    }
-
-    if (!percolated) {
-      const joinRow: JoinRow = {
-        id: undefined,
-        m2m: this,
-        [this.columnName]: this.entity,
-        [this.otherColumnName]: other,
-      };
-      getOrSet(getEm(this.entity).__data.joinRows, this.joinTableName, []).push(joinRow);
-      ((other[this.otherFieldName] as any) as ManyToManyCollection<U, T>).add(this.entity, true);
-    }
-  }
-
-  remove(other: U, percolated = false): void {
-    ensureNotDeleted(this.entity, { ignore: "pending" });
-
-    if (!percolated) {
-      const joinRows = getOrSet(getEm(this.entity).__data.joinRows, this.joinTableName, []);
-      const row = joinRows.find((r) => r[this.columnName] === this.entity && r[this.otherColumnName] === other);
-      if (row) {
-        row.deleted = true;
-      } else {
-        const joinRow: JoinRow = {
-          // Use -1 to force the sortJoinRows to notice us as dirty ("delete: true but id is set")
-          id: -1,
-          m2m: this,
-          [this.columnName]: this.entity,
-          [this.otherColumnName]: other,
-          deleted: true,
-        };
-        getOrSet(getEm(this.entity).__data.joinRows, this.joinTableName, []).push(joinRow);
-      }
-      ((other[this.otherFieldName] as any) as ManyToManyCollection<U, T>).remove(this.entity, true);
-    }
-
-    if (this.loaded !== undefined) {
-      remove(this.loaded, other);
-    } else {
-      remove(this.addedBeforeLoaded, other);
-      this.removedBeforeLoaded.push(other);
-    }
-  }
-
-  private doGet(): U[] {
-    ensureNotDeleted(this.entity);
-    if (this.loaded === undefined) {
-      if (this.entity.id === undefined) {
-        return this.addedBeforeLoaded;
-      } else {
-        // This should only be callable in the type system if we've already resolved this to an instance
-        throw new Error("get was called when not loaded");
-      }
-    }
-    return this.loaded;
-  }
-
-  get getWithDeleted(): U[] {
-    return this.filterDeleted(this.doGet(), { withDeleted: true });
-  }
-
-  get get(): U[] {
-    return this.filterDeleted(this.doGet(), { withDeleted: false });
-  }
-
-  set(values: U[]): void {
-    ensureNotDeleted(this.entity);
-    if (this.loaded === undefined) {
-      throw new Error("set was called when not loaded");
-    }
-    // Make a copy for safe iteration
-    const loaded = [...this.loaded];
-    // Remove old values
-    for (const other of loaded) {
-      if (!values.includes(other)) {
-        this.remove(other);
-      }
-    }
-    for (const other of values) {
-      if (!loaded.includes(other)) {
-        this.add(other);
-      }
-    }
-  }
-
-  removeAll(): void {
-    ensureNotDeleted(this.entity);
-    if (this.loaded === undefined) {
-      throw new Error("removeAll was called when not loaded");
-    }
-    for (const other of [...this.loaded]) {
-      this.remove(other);
-    }
-  }
-
-  // impl details
-
-  setFromOpts(others: U[]): void {
-    this.loaded = [];
-    others.forEach((o) => this.add(o));
-  }
-
-  initializeForNewEntity(): void {
-    // Don't overwrite any opts values
-    if (this.loaded === undefined) {
-      this.loaded = [];
-    }
-  }
-
-  async refreshIfLoaded(): Promise<void> {
-    ensureNotDeleted(this.entity);
-    // TODO We should remember what load hints have been applied to this collection and re-apply them.
-    if (this.loaded !== undefined && this.entity.id !== undefined) {
-      const key = `${this.columnName}=${this.entity.id}`;
-      const loader = loaderForJoinTable(this);
-      loader.clear(key);
-      this.loaded = await loader.load(key);
-    }
-  }
-
-  onEntityDelete() {
-    if (this.isCascadeDelete) {
-      this.current({ withDeleted: true }).forEach(getEm(this.entity).delete);
-    }
-  }
-
-  async onEntityDeletedAndFlushing(): Promise<void> {
-    const entities = await this.load({ withDeleted: true });
-    entities.forEach((other) => {
-      const m2m = (other[this.otherFieldName] as any) as ManyToManyCollection<U, T>;
-      m2m.remove(this.entity);
-    });
-    this.loaded = [];
-  }
-
-  private maybeApplyAddedAndRemovedBeforeLoaded(): void {
-    if (this.loaded) {
-      // this.loaded.unshift(...this.addedBeforeLoaded);
-      // this.addedBeforeLoaded = [];
-      this.removedBeforeLoaded.forEach((e) => {
-        remove(this.loaded!, e);
-        const em = getEm(this.entity);
-        const row = em.__data.joinRows[this.joinTableName].find(
-          (r) => r[this.columnName] === this.entity && r[this.otherColumnName] === e,
-        );
-        if (row) {
-          row.deleted = true;
-        }
-      });
-      this.removedBeforeLoaded = [];
-    }
-  }
-
-  current(opts?: { withDeleted?: boolean }): U[] {
-    return this.filterDeleted(this.loaded || this.addedBeforeLoaded, opts);
-  }
-
-  public get meta(): EntityMetadata<T> {
-    return getMetadata(this.entity);
-  }
-
-  public toString(): string {
-    return `OneToManyCollection(entity: ${this.entity}, fieldName: ${this.fieldName}, otherType: ${this.otherMeta.type}, otherFieldName: ${this.otherFieldName})`;
-  }
-}
-
-export type JoinRow = {
-  id: number | undefined;
-  m2m: ManyToManyCollection<any, any>;
-  created_at?: Date;
-  [column: string]: number | Entity | undefined | boolean | Date | ManyToManyCollection<any, any>;
-  deleted?: boolean;
-};
-
-function loaderForJoinTable<T extends Entity, U extends Entity>(collection: ManyToManyCollection<T, U>) {
-  const { joinTableName } = collection;
-  const em = getEm(collection.entity);
-  return getOrSet(em.__data.loaders, joinTableName, () => {
-    return new DataLoader<string, Entity[]>(async (keys) => loadFromJoinTable(collection, keys));
-  });
-}
-
-/**
- * Loads join rows (batched).
- *
- * I.e. we can load the `books_to_tags` join rows for multiple `Book`s at a time, or even
- * load `books_to_tags` for several `Book`s and several `Tag`s in a single SQL query.
- */
-async function loadFromJoinTable<T extends Entity, U extends Entity>(
-  collection: ManyToManyCollection<T, U>,
-  keys: ReadonlyArray<string>,
-): Promise<Entity[][]> {
-  const { joinTableName } = collection;
-  const em = getEm(collection.entity);
-
-  // Break out `column_id=string` keys out
-  const columns: Record<string, string[]> = {};
-  keys.forEach((key) => {
-    const [columnId, id] = key.split("=");
-    getOrSet(columns, columnId, []).push(id);
-  });
-
-  // Or together `where tag_id in (...)` and `book_id in (...)`
-  let query = em.knex.select("*").from(joinTableName);
-  Object.entries(columns).forEach(([columnId, values]) => {
-    // Pick the right meta i.e. tag_id --> TagMeta or book_id --> BookMeta
-    const meta = collection.columnName == columnId ? getMetadata(collection.entity) : collection.otherMeta;
-    query = query.orWhereIn(
-      columnId,
-      values.map((id) => keyToNumber(meta, id)!),
-    );
-  });
-
-  const rows: JoinRow[] = await query.orderBy("id");
-
-  // Make a map that will be both `tag_id=2 -> [...]` and `book_id=3 -> [...]`
-  const rowsByKey: Record<string, JoinRow[]> = {};
-
-  // Keep a reference to our row to track updates/deletes
-  const emJoinRows = getOrSet(em.__data.joinRows, joinTableName, []);
-
-  // The order of column1/column2 doesn't really matter, i.e. if the opposite-side collection is later used
-  const column1 = collection.columnName;
-  const meta1 = collection.entity.__orm.metadata;
-  const column2 = collection.otherColumnName;
-  const meta2 = collection.otherMeta;
-
-  // For each join table row, we use `EntityManager.load` to get both entities loaded.
-  // This will be another 1 or 2 queries (depending on whether we're loading just
-  // `book.getTags` (1 query to load new tags) or both `book.getTags` and `tag.getBooks
-  // (1 query to load the new tags and 1 query to look the new books)).
-  //
-  // Eventually we could have this query join into the entity tables themselves, i.e.
-  // `books` and `tags`, and use those results to hydrate the newly-found entities.
-  await Promise.all(
-    rows.map(async (dbRow) => {
-      // We may have already loaded this join row in a prior load of the opposite side of this m2m.
-      let emRow = emJoinRows.find((jr) => {
-        return (
-          (jr[column1] as Entity).id === keyToString(meta1, dbRow[column1]) &&
-          (jr[column2] as Entity).id === keyToString(meta2, dbRow[column2])
-        );
-      });
-
-      if (!emRow) {
-        // For this join table row, load the entities of both foreign keys. Because we are `EntityManager.load`,
-        // this is N+1 safe (and will check the Unit of Work for already-loaded entities), but per ^ comment
-        // we chould pull these from the row itself if we did a fancier join.
-        const p1 = em.load(meta1.cstr, keyToString(meta1, dbRow[column1])!);
-        const p2 = em.load(meta2.cstr, keyToString(meta2, dbRow[column2])!);
-        const [e1, e2] = await Promise.all([p1, p2]);
-        emRow = { id: dbRow.id, m2m: collection, [column1]: e1, [column2]: e2, created_at: dbRow.created_at };
-        emJoinRows.push(emRow);
-      } else {
-        // If a placeholder row was created while a ManyToManyCollection was unloaded, and we find it during
-        // a subsequent load/query, update its id to be what is in the database.
-        emRow.id = dbRow.id;
-      }
-
-      // Put this row into the map for both join table columns, i.e. `book_id=2` and `tag_id=3`
-      getOrSet(rowsByKey, `${column1}=${(emRow[column1] as Entity).id}`, []).push(emRow);
-      getOrSet(rowsByKey, `${column2}=${(emRow[column2] as Entity).id}`, []).push(emRow);
-    }),
-  );
-
-  // Map the requested keys, i.e. book_id=2 back to "the tags for book 2".
-  return keys.map((key) => {
-    const [column] = key.split("=");
-    const joinRows = rowsByKey[key] || [];
-    const otherColumn = column === collection.columnName ? collection.otherColumnName : collection.columnName;
-    return joinRows.map((joinRow) => joinRow[otherColumn] as Entity);
-  });
-}