joist-orm 0.1.536 → 1.0.0

package/src/keys.ts

@@ -1,75 +0,0 @@
-import { getMetadata, Entity } from "./EntityManager";
-import { BaseEntity } from "./BaseEntity";
-
-const tagDelimiter = ":";
-
-// I'm not entirely sure this is still necessary, but use a small subset of EntityMetadata so
-// that this file doesn't have to import the type and potentially create import cycles.
-type HasTagName = { tagName: string };
-
-// Before a referred-to object is saved, we keep its instance in our data
-// map, and then assume it will be persisted before we're asked to persist
-export function maybeResolveReferenceToId(value: any): string | undefined {
-  return typeof value === "number" || typeof value === "string" ? value : value?.id;
-}
-
-/** Converts `value` to a number, i.e. for string ids, unless its undefined. */
-export function keyToNumber(meta: HasTagName, value: string): number;
-export function keyToNumber(meta: HasTagName, value: any): number | undefined;
-export function keyToNumber(meta: HasTagName, value: any): number | undefined {
-  if (value === undefined || value === null) {
-    return undefined;
-  } else if (typeof value === "number") {
-    return value;
-  } else if (typeof value === "string") {
-    const [tag, id] = value.split(tagDelimiter);
-    if (id === undefined) {
-      return Number(value);
-    }
-    if (tag !== meta.tagName) {
-      throw new Error(`Invalid tagged id, expected tag ${meta.tagName}, got ${value}`);
-    }
-    return Number(id);
-  } else {
-    throw new Error(`Invalid key ${value}`);
-  }
-}
-
-/** Converts `value` to a number, i.e. for string ids, unles its undefined. */
-export function keyToString(meta: HasTagName, value: any): string | undefined {
-  return value === undefined || value === null ? undefined : `${meta.tagName}:${value}`;
-}
-
-/** Fails if any keys are tagged; used by internal functions b/c we still allow most direct API input to be untagged. */
-export function assertIdsAreTagged(keys: readonly string[]): void {
-  const invalidKeys = keys.filter((k) => k.indexOf(tagDelimiter) === -1);
-  if (invalidKeys.length > 0) {
-    throw new Error(`Some keys are missing tags ${invalidKeys}`);
-  }
-}
-
-/** Tags a potentially untagged id, while our API inputs still accept either tagged or untagged ids. */
-export function tagIfNeeded(meta: HasTagName, id: string): string {
-  if (id.includes(tagDelimiter)) {
-    return id;
-  }
-  return `${meta.tagName}${tagDelimiter}${id}`;
-}
-
-/** Removes the tag prefixes so we can use the keys for SQL operations. */
-export function deTagIds(meta: HasTagName, keys: readonly string[]): readonly string[] {
-  return keys.map((k) => deTagId(meta, k));
-}
-
-export function deTagId(meta: HasTagName, id: string): string;
-export function deTagId(entity: Entity): string;
-export function deTagId(entityOrMeta: Entity | HasTagName, id?: string): string {
-  const meta = entityOrMeta instanceof BaseEntity ? getMetadata(entityOrMeta) : (entityOrMeta as HasTagName);
-  id = id ?? (entityOrMeta as Entity).id;
-  return keyToNumber(meta, id!).toString();
-}
-
-/** Removes the tag prefixes so we can use the keys for SQL operations. */
-export function unsafeDeTagIds(keys: readonly string[]): readonly string[] {
-  return keys.map((k) => k.split(tagDelimiter)).map((t) => (t.length === 0 ? t[0] : t[1]));
-}

package/src/loadLens.ts

@@ -1,126 +0,0 @@
-/** Generically matches on a Reference/Collection's load method. */
-type LoadLike<U> = { load(): Promise<U> };
-
-/** Generically matches a property or zero-arg method that returns a promise. */
-type PromiseFnLike<U> = () => PromiseLike<U>;
-
-/** Given a parent type U, and a new type V, returns V[] if U is already an array, i.e. we're in flatMap mode. */
-type MaybeArray<U, V> = U extends ReadonlyArray<any> ? (V extends ReadonlyArray<any> ? V : V[]) : V;
-
-/** Given a type T that we come across in the path, de-array it to continue our flatMap-ish semantics. */
-type MaybeDropArray<T> = T extends ReadonlyArray<infer U> ? U : T;
-
-type DropUndefined<T> = Exclude<T, undefined>;
-
-/**
- * A type for declaratively walking the object graph.
- *
- * This is not technically a Lens that can `get/set`, but the idea is generally the same.
- *
- * `T` is the type we're on, i.e. when `T = Author` we can do `.firstName` or `.lastName.
- * `R` is either a `T` or `T[]` or `T | undefined` and just captures whether we've hit a
- * list at any point in the lens navigation path.
- */
-export type Lens<T, R = T> = {
-  [P in keyof T]: T[P] extends LoadLike<infer U>
-    ? Lens<MaybeDropArray<DropUndefined<U>>, MaybeArray<R, U>>
-    : T[P] extends PromiseFnLike<infer U>
-    ? Lens<MaybeDropArray<DropUndefined<U>>, MaybeArray<R, U>>
-    : Lens<MaybeDropArray<DropUndefined<T[P]>>, MaybeArray<R, T[P]>>;
-};
-
-/**
- * Allows declaratively loading/traversing several layers of references at once.
- *
- * I.e.:
- *
- * ```typescript
- * const publisher = await book.load(b => b.author.publisher);
- * ```
- */
-// For some reason accepting Lens<this, this> does not work when called from within the entity
-// subclass itself, so we use the codegen hammer in our subclass to force the right Lens type
-// in a .load stub that just calls us for the implementation.
-export async function loadLens<T, U, V>(start: T, fn: (lens: Lens<T>) => Lens<U, V>): Promise<V> {
-  const paths = collectPaths(fn);
-  let current: any = start;
-  // Now evaluate each step of the path
-  for await (const path of paths) {
-    if (Array.isArray(current)) {
-      current = (await Promise.all(current.map((c) => maybeLoad(c, path)))).flat();
-      current = [...new Set(current)];
-    } else {
-      current = await maybeLoad(current, path);
-    }
-  }
-  return current!;
-}
-
-function maybeLoad(object: any, path: string): unknown {
-  if (object === undefined || object === null) {
-    return undefined;
-  }
-  const value = object[path];
-  if (value && typeof value === "object" && "load" in value) {
-    return value.load();
-  } else if (value && typeof value === "function") {
-    return value.apply(object);
-  } else {
-    return value;
-  }
-}
-
-/**
- * The synchronous version of `loadLens`.
- *
- * This assumes you've first evaluated the lens with `loadLens` and now can access it synchronously.
- */
-export function getLens<T, U, V>(start: T, fn: (lens: Lens<T>) => Lens<U, V>): V {
-  const paths = collectPaths(fn);
-  let current: any = start;
-  // Now evaluate each step of the path
-  for (const path of paths) {
-    if (Array.isArray(current)) {
-      current = current.map((c) => maybeGet(c, path)).flat();
-      current = [...new Set(current)];
-    } else {
-      current = maybeGet(current, path);
-    }
-  }
-  return current!;
-}
-
-function maybeGet(object: any, path: string): unknown {
-  if (object === undefined || object === null) {
-    return undefined;
-  }
-  const value = object[path];
-  if (value && typeof value === "object" && "get" in value) {
-    if (typeof value.get === "function") {
-      return value.get();
-    } else {
-      return value.get;
-    }
-  } else if (value && typeof value === "function") {
-    return value.apply(object);
-  } else {
-    return value;
-  }
-}
-
-function collectPaths(fn: Function): string[] {
-  const paths: string[] = [];
-  // The proxy collects the path navigations that the user's `fn` lambda invokes.
-  const proxy = new Proxy(
-    {},
-    {
-      get(object, property, receiver) {
-        paths.push(String(property));
-        return receiver;
-      },
-    },
-  );
-  // Invoke the lens function to record the navigation path on our proxy
-  fn(proxy as any);
-  return paths;
-}

package/src/newTestInstance.ts

@@ -1,205 +0,0 @@
-import isPlainObject from "is-plain-object";
-import {
-  ActualFactoryOpts,
-  Entity,
-  EntityConstructor,
-  EntityManager,
-  getMetadata,
-  IdOf,
-  isEntity,
-  New,
-  OptsOf,
-  PrimitiveField,
-} from "./EntityManager";
-import { tagIfNeeded } from "./keys";
-import { fail } from "./utils";
-
-/**
- * DeepPartial-esque type specific to our `newTestInstance` factory.
- *
- * Specifically (vs using DeepPartial directly) this:
- *
- * 1. Adds a `use` tag of `Entity | Entity[]` that will be checked for existing
- * entities before creating new ones (i.e. "if `newTestInstance` needs a `Book`,
- * use the one in `use` instead of making a new one).
- *
- * 2. Works specifically against the constructor/entity opts fields.
- */
-export type FactoryOpts<T extends Entity> = DeepPartialOpts<T> & { use?: Entity | Entity[] };
-
-// Chosen b/c it's a monday https://www.timeanddate.com/calendar/monthly.html?year=2018&month=1&country=1
-export const jan1 = new Date(2018, 0, 1);
-export let testDate = jan1;
-
-/** Creates a test instance of `T`. */
-export function newTestInstance<T extends Entity>(
-  em: EntityManager,
-  cstr: EntityConstructor<T>,
-  opts: FactoryOpts<T> = {},
-): New<T> {
-  const meta = getMetadata(cstr);
-
-  // fullOpts will end up being a full/type-safe opts with every required field
-  // filled in, either driven by the passed-in opts or by making new entities as-needed
-  const fullOpts = Object.fromEntries(
-    meta.fields
-      .map((field) => {
-        const { fieldName } = field;
-
-        // Use the opts value if they passed one in
-        if (fieldName in opts) {
-          const optValue = (opts as any)[fieldName];
-
-          // Watch for our "the parent is not yet created" null marker
-          if (optValue === null) {
-            return [];
-          }
-
-          // If this is a partial with defaults for the entity, call newTestInstance to get it created
-          if (field.kind === "m2o") {
-            if (isEntity(optValue)) {
-              return [fieldName, optValue];
-            } else if (optValue && typeof optValue === "string") {
-              return [
-                fieldName,
-                em.entities.find((e) => e.id === optValue || getTestId(em, e) === optValue) ||
-                  fail(`Did not find tagged id ${optValue}`),
-              ];
-            } else if (optValue && !isPlainObject(optValue)) {
-              return field.otherMetadata().factory(em, opts);
-            }
-            return [fieldName, field.otherMetadata().factory(em, { ...optValue, use: opts.use })];
-          }
-
-          // If this is a list of children, watch for partials that should be newTestInstance'd
-          if (field.kind === "o2m" || field.kind == "m2m") {
-            const values = (optValue as Array<any>).map((optValue) => {
-              if (isEntity(optValue)) {
-                return optValue;
-              } else if (optValue && typeof optValue === "string") {
-                return (
-                  em.entities.find((e) => e.id === optValue || getTestId(em, e) === optValue) ||
-                  fail(`Did not find tagged id ${optValue}`)
-                );
-              } else if (optValue && !isPlainObject(optValue)) {
-                return field.otherMetadata().factory(em, optValue);
-              }
-              return field.otherMetadata().factory(em, {
-                ...optValue,
-                // We include null as a marker for "don't create the parent"; even if it's required,
-                // once the child has been created, the act of adding it to our collection will get the
-                // parent set. It might be better to do o2ms as a 2nd-pass, after we've done the em.create
-                // call and could directly pass this entity instead of null.
-                [field.otherFieldName]: null,
-                use: opts.use,
-              });
-            });
-            return [fieldName, values];
-          }
-
-          // Look for strings that want to use the test index
-          if (typeof optValue === "string" && optValue.includes(testIndex)) {
-            const actualIndex = getTestIndex(em, meta.cstr);
-            return [fieldName, optValue.replace(testIndex, String(actualIndex))];
-          }
-
-          // Otherwise just use the user's opt value as-is
-          return [fieldName, optValue];
-        }
-
-        if (field.kind === "primitive" && field.required && !field.derived && !field.protected) {
-          return [fieldName, defaultValue(field)];
-        } else if (field.kind === "m2o") {
-          const otherMeta = field.otherMetadata();
-
-          // If there is a single existing instance of this type, assume the caller is fine with that,
-          // even if the field is not required.
-          const existing = em.entities.filter((e) => e instanceof otherMeta.cstr);
-          if (existing.length === 1) {
-            return [fieldName, existing[0]];
-          }
-
-          // If there is a use type, assume the caller is fine with that, even if the field is not required
-          const useEntity = maybeArray(opts.use)?.find((e) => e instanceof otherMeta.cstr);
-          if (useEntity) {
-            return [fieldName, useEntity];
-          }
-
-          // Otherwise only make a new entity only if the field is required
-          if (field.required) {
-            return [fieldName, otherMeta.factory(em, { use: opts.use })];
-          }
-        } else if (field.kind === "enum" && field.required) {
-          return [fieldName, field.enumDetailType.getValues()[0]];
-        }
-        return [];
-      })
-      .filter((t) => t.length > 0),
-  );
-
-  return em.create(meta.cstr, fullOpts as any) as New<T>;
-}
-
-/**
- * A marker value for later replacement with the test instance's "unique-ish" index.
- *
- * This is meant to just be a helpful identifier in fields like entity names/descriptions for
- * debugging purposes.
- */
-export const testIndex = "TEST_INDEX";
-
-/**
- * Returns a unique-ish test index for putting in `name` fields.
- *
- * Note that `testIndex` is easier to just include in a string, because it doesn't require passing
- * the `EntityManger` and `type`. But if a factory really wants the test index as a number, they can
- * call this method.
- *
- * Despite the name, these are 1-based, i.e. the first `Author` is `a1`.
- */
-export function getTestIndex<T extends Entity>(em: EntityManager, type: EntityConstructor<T>): number {
-  const existing = em.entities.filter((e) => e instanceof type);
-  return existing.length + 1;
-}
-
-/** Fakes a probably-right id for un-persisted entities. Solely used for quick lookups in tests/factories. */
-function getTestId<T extends Entity>(em: EntityManager, entity: T): string {
-  const meta = getMetadata(entity);
-  const sameType = em.entities.filter((e) => e instanceof meta.cstr);
-  return tagIfNeeded(meta, String(sameType.indexOf(entity) + 1));
-}
-
-function defaultValue(field: PrimitiveField): unknown {
-  switch (field.type) {
-    case "string":
-      return field.fieldName;
-    case "number":
-      return 0;
-    case "Date":
-      return testDate;
-    case "boolean":
-      return false;
-  }
-  return null;
-}
-
-// Utility type to destructure T out of T | undefined
-type DefinedOr<T> = T | undefined;
-
-type DeepPartialOpts<T extends Entity> = AllowRelationsOrPartials<OptsOf<T>>;
-
-type AllowRelationsOrPartials<T> = {
-  [P in keyof T]?: T[P] extends DefinedOr<infer U>
-    ? U extends Array<infer V>
-      ? V extends Entity
-        ? Array<V | IdOf<V> | ActualFactoryOpts<V>>
-        : T[P]
-      : U extends Entity
-      ? U | IdOf<U> | ActualFactoryOpts<U>
-      : T[P]
-    : T[P];
-};
-
-function maybeArray<T>(array: T | T[] | undefined): T[] | undefined {
-  return array ? (Array.isArray(array) ? array : [array]) : undefined;
-}

package/src/reverseHint.ts

@@ -1,43 +0,0 @@
-import { Entity, EntityConstructor, getMetadata, LoadHint } from "./EntityManager";
-import { fail } from "./utils";
-
-/**
- * Given a load hint of "given an entity, load these N things", return an array
- * of what those N things are, and reversed load hints to "come back" to the
- * original entity.
- */
-export function reverseHint<T extends Entity>(
-  entityType: EntityConstructor<T>,
-  hint: LoadHint<T>,
-): [EntityConstructor<any>, string[]][] {
-  if (typeof hint === "string") {
-    // For a simple string hint, i.e. Book "author", find the Book.author field,
-    // and use the metdata to find the otherFieldName, i.e. Author "books"
-    const meta = getMetadata(entityType);
-    const field = meta.fields.find((f) => f.fieldName === hint) || fail(`Invalid hint ${JSON.stringify(hint)}`);
-    if (field.kind !== "m2m" && field.kind !== "m2o" && field.kind !== "o2m") {
-      throw new Error("Invalid hint");
-    }
-    const otherMeta = field.otherMetadata();
-    return [[otherMeta.cstr, [field.otherFieldName]]];
-  } else if (Array.isArray(hint)) {
-    // For an array of string hints, i.e. Author "authors" "books", recurse
-    // into each individual hint (i.e. the logic right above this) and then
-    // combine/flatten them.
-    return (hint as string[]).map((hint) => reverseHint(entityType, hint as any)).flat();
-  } else {
-    // For a hash of hints, i.e. Author { books: reviews }, recurse for each
-    // key in the hash, and then combine
-    return Object.entries(hint).flatMap(([key, hint]) => {
-      const meta = getMetadata(entityType);
-      const field = meta.fields.find((f) => f.fieldName === key) || fail(`Invalid hint ${JSON.stringify(hint)}`);
-      if (field.kind !== "m2m" && field.kind !== "m2o" && field.kind !== "o2m") {
-        throw new Error("Invalid hint");
-      }
-      const otherMeta = field.otherMetadata();
-      return reverseHint(otherMeta.cstr, hint).map(([e, hint]) => {
-        return [e, [...hint, field.otherFieldName]] as [EntityConstructor<any>, string[]];
-      });
-    });
-  }
-}

package/src/serde.ts

@@ -1,97 +0,0 @@
-import { EntityMetadata, keyToNumber, keyToString, maybeResolveReferenceToId } from "./index";
-
-export interface ColumnSerde {
-  setOnEntity(data: any, row: any): void;
-
-  setOnRow(data: any, row: any): void;
-
-  getFromEntity(data: any): any;
-
-  mapToDb(value: any): any;
-}
-
-export class SimpleSerde implements ColumnSerde {
-  constructor(private fieldName: string, private columnName: string) {}
-
-  setOnEntity(data: any, row: any): void {
-    data[this.fieldName] = maybeNullToUndefined(row[this.columnName]);
-  }
-
-  setOnRow(data: any, row: any): void {
-    row[this.columnName] = data[this.fieldName];
-  }
-
-  getFromEntity(data: any) {
-    return data[this.fieldName];
-  }
-
-  mapToDb(value: any) {
-    return value;
-  }
-}
-
-/** Maps integer primary keys ot strings "because GraphQL". */
-export class PrimaryKeySerde implements ColumnSerde {
-  constructor(private meta: () => EntityMetadata<any>, private fieldName: string, private columnName: string) {}
-
-  setOnEntity(data: any, row: any): void {
-    data[this.fieldName] = keyToString(this.meta(), row[this.columnName]);
-  }
-
-  setOnRow(data: any, row: any): void {
-    row[this.columnName] = keyToNumber(this.meta(), data[this.fieldName]);
-  }
-
-  getFromEntity(data: any) {
-    return keyToNumber(this.meta(), data[this.fieldName]);
-  }
-
-  mapToDb(value: any) {
-    return keyToNumber(this.meta(), value);
-  }
-}
-
-export class ForeignKeySerde implements ColumnSerde {
-  // TODO EntityMetadata being in here is weird.
-  constructor(private fieldName: string, private columnName: string, public otherMeta: () => EntityMetadata<any>) {}
-
-  setOnEntity(data: any, row: any): void {
-    data[this.fieldName] = keyToString(this.otherMeta(), row[this.columnName]);
-  }
-
-  setOnRow(data: any, row: any): void {
-    row[this.columnName] = keyToNumber(this.otherMeta(), maybeResolveReferenceToId(data[this.fieldName]));
-  }
-
-  getFromEntity(data: any) {
-    return keyToNumber(this.otherMeta(), maybeResolveReferenceToId(data[this.fieldName]));
-  }
-
-  mapToDb(value: any): any {
-    return keyToNumber(this.otherMeta(), maybeResolveReferenceToId(value));
-  }
-}
-
-export class EnumFieldSerde implements ColumnSerde {
-  constructor(private fieldName: string, private columnName: string, private enumObject: any) {}
-
-  setOnEntity(data: any, row: any): void {
-    data[this.fieldName] = this.enumObject.findById(row[this.columnName])?.code;
-  }
-
-  setOnRow(data: any, row: any): void {
-    row[this.columnName] = this.enumObject.findByCode(data[this.fieldName])?.id;
-  }
-
-  getFromEntity(data: any) {
-    return this.enumObject.findByCode(data[this.fieldName])?.id;
-  }
-
-  mapToDb(value: any) {
-    return this.enumObject.findByCode(value)?.id;
-  }
-}
-
-function maybeNullToUndefined(value: any): any {
-  return value === null ? undefined : value;
-}

package/src/utils.ts

@@ -1,63 +0,0 @@
-export function getOrSet<T extends Record<keyof unknown, unknown>>(
-  record: T,
-  key: keyof T,
-  defaultValue: T[keyof T] | (() => T[keyof T]),
-): T[keyof T] {
-  if (record[key] === undefined) {
-    record[key] = defaultValue instanceof Function ? defaultValue() : defaultValue;
-  }
-  return record[key];
-}
-
-export function fail(message?: string): never {
-  throw new Error(message || "Failed");
-}
-
-export function remove<T>(array: T[], t: T): void {
-  const index = array.indexOf(t);
-  if (index > -1) {
-    array.splice(index, 1);
-  }
-}
-
-/** Returns 0 inclusive to n exclusive. */
-export function zeroTo(n: number): number[] {
-  return [...Array(n).keys()];
-}
-
-export function groupBy<T, Y = T>(list: T[], fn: (x: T) => string, valueFn?: (x: T) => Y): Map<string, Y[]> {
-  const result = new Map<string, Y[]>();
-  list.forEach((o) => {
-    const group = fn(o);
-    if (!result.has(group)) {
-      result.set(group, []);
-    }
-    result.get(group)!.push(valueFn === undefined ? ((o as any) as Y) : valueFn(o));
-  });
-  return result;
-}
-
-export function indexBy<T, Y = T>(list: T[], fn: (x: T) => string, valueFn?: (x: T) => Y): Map<string, Y> {
-  const result = new Map<string, Y>();
-  list.forEach((o) => {
-    const group = fn(o);
-    result.set(group, valueFn === undefined ? ((o as any) as Y) : valueFn(o));
-  });
-  return result;
-}
-
-export function partition<T>(array: ReadonlyArray<T>, f: (el: T) => boolean): [T[], T[]] {
-  const trueElements: T[] = [];
-  const falseElements: T[] = [];
-  array.forEach((el) => {
-    if (f(el)) {
-      trueElements.push(el);
-    } else {
-      falseElements.push(el);
-    }
-  });
-  return [trueElements, falseElements];
-}
-
-// Utility type to strip off null and defined and infer only T.
-export type NullOrDefinedOr<T> = T | null | undefined;

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "es2019",
-    "module": "commonjs",
-    "lib": ["es2019"],
-    "strict": true,
-    "noImplicitReturns": true,
-    "types": ["jest", "node"],
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "composite": true,
-    "sourceMap": true,
-    "outDir": "./build",
-    "rootDir": "./src",
-    "baseUrl": "./src",
-    "paths": {
-      "joist-utils": ["../../utils/src"]
-    }
-  },
-  "references": [{ "path": "../utils" }]
-}