joist-orm 0.1.538 → 1.0.0

package/build/src/index.js

@@ -0,0 +1,263 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCollectionField = exports.isReferenceField = exports.isPolymorphicField = exports.isOneToOneField = exports.isManyToManyField = exports.isManyToOneField = exports.isOneToManyField = exports.maybeGetConstructorFromReference = exports.getConstructorFromTaggedId = exports.getRelations = exports.getEm = exports.configureMetadata = exports.getRequiredKeys = exports.ensureNotDeleted = exports.setOpts = exports.setField = exports.fail = exports.ValidationErrors = exports.newRequiredRule = exports.isNew = exports.ConfigApi = exports.BaseEntity = exports.newPgConnectionConfig = void 0;
+const EntityManager_1 = require("./EntityManager");
+const keys_1 = require("./keys");
+const AbstractRelationImpl_1 = require("./relations/AbstractRelationImpl");
+const reverseHint_1 = require("./reverseHint");
+const utils_1 = require("./utils");
+var joist_utils_1 = require("joist-utils");
+Object.defineProperty(exports, "newPgConnectionConfig", { enumerable: true, get: function () { return joist_utils_1.newPgConnectionConfig; } });
+var BaseEntity_1 = require("./BaseEntity");
+Object.defineProperty(exports, "BaseEntity", { enumerable: true, get: function () { return BaseEntity_1.BaseEntity; } });
+__exportStar(require("./changes"), exports);
+var config_1 = require("./config");
+Object.defineProperty(exports, "ConfigApi", { enumerable: true, get: function () { return config_1.ConfigApi; } });
+__exportStar(require("./drivers"), exports);
+__exportStar(require("./EntityManager"), exports);
+__exportStar(require("./getProperties"), exports);
+__exportStar(require("./keys"), exports);
+var loaded_1 = require("./loaded");
+Object.defineProperty(exports, "isNew", { enumerable: true, get: function () { return loaded_1.isNew; } });
+__exportStar(require("./loadLens"), exports);
+__exportStar(require("./newTestInstance"), exports);
+__exportStar(require("./QueryBuilder"), exports);
+__exportStar(require("./relations"), exports);
+__exportStar(require("./reverseHint"), exports);
+var rules_1 = require("./rules");
+Object.defineProperty(exports, "newRequiredRule", { enumerable: true, get: function () { return rules_1.newRequiredRule; } });
+Object.defineProperty(exports, "ValidationErrors", { enumerable: true, get: function () { return rules_1.ValidationErrors; } });
+__exportStar(require("./serde"), exports);
+var utils_2 = require("./utils");
+Object.defineProperty(exports, "fail", { enumerable: true, get: function () { return utils_2.fail; } });
+function setField(entity, fieldName, newValue) {
+    ensureNotDeleted(entity, { ignore: "pending" });
+    const { em } = entity;
+    if (em.isFlushing) {
+        const { flushSecret } = EntityManager_1.currentFlushSecret.getStore() || {};
+        if (flushSecret === undefined) {
+            throw new Error(`Cannot set '${fieldName}' on ${entity} during a flush outside of a entity hook or from afterCommit`);
+        }
+        if (flushSecret !== em["flushSecret"]) {
+            throw new Error(`Attempting to reuse a hook context outside its flush loop`);
+        }
+    }
+    const { data, originalData } = entity.__orm;
+    // "Un-dirty" our originalData if newValue is reverting to originalData
+    if (fieldName in originalData) {
+        if (equal(originalData[fieldName], newValue)) {
+            data[fieldName] = newValue;
+            delete originalData[fieldName];
+            return true;
+        }
+    }
+    // Push this logic into a field serde type abstraction?
+    const currentValue = data[fieldName];
+    if (equal(currentValue, newValue)) {
+        return false;
+    }
+    // Only save the currentValue on the 1st change of this field
+    if (!(fieldName in originalData)) {
+        originalData[fieldName] = currentValue;
+    }
+    data[fieldName] = newValue;
+    return true;
+}
+exports.setField = setField;
+/**
+ * Sets each value in `values` on the current entity.
+ *
+ * The default behavior is that passing a value as either `null` or `undefined` will set
+ * the field as `undefined`, i.e. automatic `null` to `undefined` conversion.
+ *
+ * However, if you pass `ignoreUndefined: true`, then any opt that is `undefined` will be treated
+ * as "do not set", and `null` will still mean "set to `undefined`". This is useful for implementing
+ * APIs were an input of `undefined` means "do not set / noop" and `null` means "unset".
+ */
+function setOpts(entity, values, opts) {
+    // If `values` is a string (i.e. the id), this instance is being hydrated from a database row, so skip all this.
+    // If `values` is undefined, we're being called by `createPartial` that will do its own opt handling.
+    if (values === undefined || typeof values === "string") {
+        return;
+    }
+    const { calledFromConstructor, partial } = opts || {};
+    const meta = (0, EntityManager_1.getMetadata)(entity);
+    Object.entries(values).forEach(([key, _value]) => {
+        const field = meta.fields[key];
+        if (!field) {
+            throw new Error(`Unknown field ${key}`);
+        }
+        // If ignoreUndefined is set, we treat undefined as a noop
+        if (partial && _value === undefined) {
+            return;
+        }
+        // We let optional opts fields be `| null` for convenience, and convert to undefined.
+        const value = _value === null || (typeof _value === "string" && _value.trim() === "") ? undefined : _value;
+        const current = entity[key];
+        if (current instanceof AbstractRelationImpl_1.AbstractRelationImpl) {
+            if (calledFromConstructor) {
+                current.setFromOpts(value);
+            }
+            else if (partial && (field.kind === "o2m" || field.kind === "m2m")) {
+                const values = value;
+                // For setPartial collections, we used to individually add/remove instead of set, but this
+                // incremental behavior was unintuitive for mutations, i.e. `parent.children = [b, c]` and
+                // you'd still have `[a]` around. Note that we still support `delete: true` command to go
+                // further than "remove from collection" to "actually delete the entity".
+                const allowDelete = !field.otherMetadata().fields["delete"];
+                const allowRemove = !field.otherMetadata().fields["remove"];
+                // We're replacing the old `delete: true` / `remove: true` behavior with `op` (i.e. operation).
+                // When passed in, all values must have it, and we kick into incremental mode, i.e. we
+                // individually add/remove/delete entities.
+                //
+                // The old `delete: true / remove: true` behavior is deprecated, and should eventually blow up.
+                const allowOp = !field.otherMetadata().fields["op"];
+                const anyValueHasOp = allowOp && values.some((v) => !!v.op);
+                if (anyValueHasOp) {
+                    const anyValueMissingOp = values.some((v) => !v.op);
+                    if (anyValueMissingOp) {
+                        throw new Error("If any child sets the `op` key, then all children must have the `op` key.");
+                    }
+                    values.forEach((v) => {
+                        if (v.op === "delete") {
+                            entity.em.delete(v);
+                        }
+                        else if (v.op === "remove") {
+                            current.remove(v);
+                        }
+                        else if (v.op === "include") {
+                            current.add(v);
+                        }
+                        else if (v.op === "incremental") {
+                            // This is a marker entry to opt-in to incremental behavior, just drop it
+                        }
+                    });
+                    return; // return from the op-based incremental behavior
+                }
+                const toSet = [];
+                values.forEach((e) => {
+                    if (allowDelete && e.delete === true) {
+                        entity.em.delete(e);
+                    }
+                    else if (allowRemove && e.remove === true) {
+                        // Just leave out of `toSet`
+                    }
+                    else {
+                        toSet.push(e);
+                    }
+                });
+                current.set(toSet);
+            }
+            else {
+                current.set(value);
+            }
+        }
+        else {
+            entity[key] = value;
+        }
+    });
+    if (calledFromConstructor) {
+        getRelations(entity).forEach((v) => v.initializeForNewEntity());
+    }
+}
+exports.setOpts = setOpts;
+function ensureNotDeleted(entity, opts = {}) {
+    if (entity.isDeletedEntity && (opts.ignore === undefined || entity.__orm.deleted !== opts.ignore)) {
+        (0, utils_1.fail)(`${entity} is marked as deleted`);
+    }
+}
+exports.ensureNotDeleted = ensureNotDeleted;
+function getRequiredKeys(entityOrType) {
+    return Object.values((0, EntityManager_1.getMetadata)(entityOrType).fields)
+        .filter((f) => f.required)
+        .map((f) => f.fieldName);
+}
+exports.getRequiredKeys = getRequiredKeys;
+const tagToConstructorMap = new Map();
+/** Processes the metas based on any custom calls to the `configApi` hooks. */
+function configureMetadata(metas) {
+    metas.forEach((meta) => {
+        // Add each constructor into our tag -> constructor map for future lookups
+        tagToConstructorMap.set(meta.tagName, meta.cstr);
+        // Look for reactive validation rules to reverse
+        meta.config.__data.rules.forEach((rule) => {
+            if (rule.hint) {
+                const reversals = (0, reverseHint_1.reverseHint)(meta.cstr, rule.hint);
+                // For each reversal, tell its config about the reverse hint to force-re-validate
+                // the original rule's instance any time it changes.
+                reversals.forEach(([otherEntity, reverseHint]) => {
+                    (0, EntityManager_1.getMetadata)(otherEntity).config.__data.reactiveRules.push(reverseHint);
+                });
+            }
+        });
+        // Look for reactive async derived values rules to reverse
+        Object.entries(meta.config.__data.asyncDerivedFields).forEach(([, entry]) => {
+            const hint = entry[0];
+            const reversals = (0, reverseHint_1.reverseHint)(meta.cstr, hint);
+            reversals.forEach(([otherEntity, reverseHint]) => {
+                (0, EntityManager_1.getMetadata)(otherEntity).config.__data.reactiveDerivedValues.push(reverseHint);
+            });
+        });
+    });
+}
+exports.configureMetadata = configureMetadata;
+function getEm(entity) {
+    return entity.em;
+}
+exports.getEm = getEm;
+function getRelations(entity) {
+    return Object.values(entity).filter((v) => v instanceof AbstractRelationImpl_1.AbstractRelationImpl);
+}
+exports.getRelations = getRelations;
+function getConstructorFromTaggedId(id) {
+    const tag = (0, keys_1.tagFromId)(id);
+    return tagToConstructorMap.get(tag) ?? (0, utils_1.fail)(`Unknown tag: "${tag}" `);
+}
+exports.getConstructorFromTaggedId = getConstructorFromTaggedId;
+function maybeGetConstructorFromReference(value) {
+    const id = (0, keys_1.maybeResolveReferenceToId)(value);
+    return id ? getConstructorFromTaggedId(id) : undefined;
+}
+exports.maybeGetConstructorFromReference = maybeGetConstructorFromReference;
+function equal(a, b) {
+    return a === b || (a instanceof Date && b instanceof Date && a.getTime() == b.getTime());
+}
+function isOneToManyField(ormField) {
+    return ormField.kind === "o2m";
+}
+exports.isOneToManyField = isOneToManyField;
+function isManyToOneField(ormField) {
+    return ormField.kind === "m2o";
+}
+exports.isManyToOneField = isManyToOneField;
+function isManyToManyField(ormField) {
+    return ormField.kind === "m2m";
+}
+exports.isManyToManyField = isManyToManyField;
+function isOneToOneField(ormField) {
+    return ormField.kind === "o2o";
+}
+exports.isOneToOneField = isOneToOneField;
+function isPolymorphicField(ormField) {
+    return ormField.kind === "poly";
+}
+exports.isPolymorphicField = isPolymorphicField;
+function isReferenceField(ormField) {
+    return ormField.kind === "m2o" || ormField.kind === "o2o" || ormField.kind === "poly";
+}
+exports.isReferenceField = isReferenceField;
+function isCollectionField(ormField) {
+    return ormField.kind === "o2m" || ormField.kind === "m2m";
+}
+exports.isCollectionField = isCollectionField;
+//# sourceMappingURL=index.js.map

package/build/src/index.js.map

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

package/build/src/keys.d.ts

@@ -0,0 +1,30 @@
+import { Entity, EntityConstructor } from "./EntityManager";
+declare type HasTagName = {
+    tagName: string;
+    idType: "int" | "uuid";
+};
+export declare function maybeResolveReferenceToId(value: any): string | undefined;
+/** Converts `value` to a number, i.e. for string ids, unless its undefined. */
+export declare function keyToNumber(meta: HasTagName, value: string | number): number;
+export declare function keyToNumber(meta: HasTagName, value: string | number | undefined): number | undefined;
+/** Converts `value` to a tagged string, i.e. for string ids, unless its undefined. */
+export declare function keyToString(meta: HasTagName, value: any): string | undefined;
+/** Fails if any keys are tagged; used by internal functions b/c we still allow most direct API input to be untagged. */
+export declare function assertIdsAreTagged(keys: readonly string[]): void;
+/** Tags a potentially untagged id, while our API inputs still accept either tagged or untagged ids. */
+export declare function tagId(meta: HasTagName, id: string | number): string;
+export declare function tagId(cstr: EntityConstructor<any>, id: string | number): string;
+export declare function tagId(meta: HasTagName, id: string | number | null | undefined): string | undefined;
+export declare function tagId(cstr: EntityConstructor<any>, id: string | number | null | undefined): string | undefined;
+/** Adds the tag prefixes. */
+export declare function tagIds(meta: HasTagName, keys: readonly (string | number)[]): readonly string[];
+export declare function tagIds(cstr: EntityConstructor<any>, keys: readonly (string | number)[]): readonly string[];
+export declare function deTagId(meta: HasTagName, id: string | number): string;
+export declare function deTagId(entity: Entity): string;
+/** Removes the tag prefixes so we can use the keys for SQL operations. */
+export declare function deTagIds(meta: HasTagName, keys: readonly string[]): readonly string[];
+/** Removes the tag prefixes so we can use the keys for SQL operations. */
+export declare function unsafeDeTagIds(keys: readonly string[]): readonly string[];
+/** Given a tagged id, returns its tag. */
+export declare function tagFromId(key: string): string;
+export {};

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

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.unsafeDeTagIds = exports.deTagId = exports.deTagIds = exports.tagIfNeeded = exports.assertIdsAreTagged = exports.keyToString = exports.keyToNumber = exports.maybeResolveReferenceToId = void 0;
-const EntityManager_1 = require("./EntityManager");
+exports.tagFromId = exports.unsafeDeTagIds = exports.deTagIds = exports.deTagId = exports.tagIds = exports.tagId = exports.assertIdsAreTagged = exports.keyToString = exports.keyToNumber = exports.maybeResolveReferenceToId = void 0;
 const BaseEntity_1 = require("./BaseEntity");
+const EntityManager_1 = require("./EntityManager");
 const tagDelimiter = ":";
 // 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
 function maybeResolveReferenceToId(value) {
-    return typeof value === "number" || typeof value === "string" ? value : value === null || value === void 0 ? void 0 : value.id;
+    return typeof value === "number" || typeof value === "string" ? value : value?.id;
 }
 exports.maybeResolveReferenceToId = maybeResolveReferenceToId;
 function keyToNumber(meta, value) {
@@ -20,19 +20,26 @@ function keyToNumber(meta, value) {
     else if (typeof value === "string") {
         const [tag, id] = value.split(tagDelimiter);
         if (id === undefined) {
-            return Number(value);
+            return maybeNumberUnlessUuid(meta, value);
         }
         if (tag !== meta.tagName) {
             throw new Error(`Invalid tagged id, expected tag ${meta.tagName}, got ${value}`);
         }
-        return Number(id);
+        return maybeNumberUnlessUuid(meta, id);
     }
     else {
         throw new Error(`Invalid key ${value}`);
     }
 }
 exports.keyToNumber = keyToNumber;
-/** Converts `value` to a number, i.e. for string ids, unles its undefined. */
+// If we're using UUIDs, just lie to the type system and pretend they're numbers.
+function maybeNumberUnlessUuid(meta, key) {
+    if (meta.idType === "uuid") {
+        return key;
+    }
+    return Number(key);
+}
+/** Converts `value` to a tagged string, i.e. for string ids, unless its undefined. */
 function keyToString(meta, value) {
     return value === undefined || value === null ? undefined : `${meta.tagName}:${value}`;
 }
@@ -45,28 +52,53 @@ function assertIdsAreTagged(keys) {
     }
 }
 exports.assertIdsAreTagged = assertIdsAreTagged;
-/** Tags a potentially untagged id, while our API inputs still accept either tagged or untagged ids. */
-function tagIfNeeded(meta, id) {
+function tagId(metaOrCstr, id) {
+    if (typeof id === "number") {
+        return `${tagName(metaOrCstr)}${tagDelimiter}${id}`;
+    }
+    if (id === null || id === undefined) {
+        return undefined;
+    }
     if (id.includes(tagDelimiter)) {
+        const [tag] = id.split(tagDelimiter);
+        if (tag !== tagName(metaOrCstr)) {
+            throw new Error(`Invalid tagged id, expected tag ${tagName(metaOrCstr)}, got ${id}`);
+        }
         return id;
     }
-    return `${meta.tagName}${tagDelimiter}${id}`;
+    return `${tagName(metaOrCstr)}${tagDelimiter}${id}`;
 }
-exports.tagIfNeeded = tagIfNeeded;
-/** Removes the tag prefixes so we can use the keys for SQL operations. */
-function deTagIds(meta, keys) {
-    return keys.map((k) => deTagId(meta, k));
+exports.tagId = tagId;
+function tagIds(metaOrCstr, keys) {
+    return keys.map((k) => tagId(metaOrCstr, k));
 }
-exports.deTagIds = deTagIds;
+exports.tagIds = tagIds;
 function deTagId(entityOrMeta, id) {
-    const meta = entityOrMeta instanceof BaseEntity_1.BaseEntity ? EntityManager_1.getMetadata(entityOrMeta) : entityOrMeta;
-    id = id !== null && id !== void 0 ? id : entityOrMeta.id;
+    const meta = entityOrMeta instanceof BaseEntity_1.BaseEntity ? (0, EntityManager_1.getMetadata)(entityOrMeta) : entityOrMeta;
+    id = id ?? entityOrMeta.id;
     return keyToNumber(meta, id).toString();
 }
 exports.deTagId = deTagId;
 /** Removes the tag prefixes so we can use the keys for SQL operations. */
+function deTagIds(meta, keys) {
+    return keys.map((k) => deTagId(meta, k));
+}
+exports.deTagIds = deTagIds;
+/** Removes the tag prefixes so we can use the keys for SQL operations. */
 function unsafeDeTagIds(keys) {
     return keys.map((k) => k.split(tagDelimiter)).map((t) => (t.length === 0 ? t[0] : t[1]));
 }
 exports.unsafeDeTagIds = unsafeDeTagIds;
+/** Given a tagged id, returns its tag. */
+function tagFromId(key) {
+    const parts = key.split(tagDelimiter);
+    if (parts.length !== 2) {
+        fail(`Unknown tagged id format: "${key}"`);
+    }
+    return parts[0];
+}
+exports.tagFromId = tagFromId;
+function tagName(metaOrCstr) {
+    return typeof metaOrCstr === "function" ? (0, EntityManager_1.getMetadata)(metaOrCstr).tagName : metaOrCstr.tagName;
+}
 //# sourceMappingURL=keys.js.map

package/build/src/keys.js.map

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

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

@@ -4,8 +4,8 @@ declare type LoadLike<U> = {
 };
 /** Generically matches a property or zero-arg method that returns a promise. */
 declare 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. */
-declare type MaybeArray<U, V> = U extends ReadonlyArray<any> ? (V extends ReadonlyArray<any> ? V : V[]) : V;
+/** Given a parent type P, and a new type V, returns V[] if P is already an array, i.e. we're in flatMap mode. */
+declare type MaybeArray<P, V> = P extends ReadonlyArray<any> ? [V] extends [ReadonlyArray<infer U>] ? DropUndefined<U>[] : DropUndefined<V>[] : V;
 /** Given a type T that we come across in the path, de-array it to continue our flatMap-ish semantics. */
 declare type MaybeDropArray<T> = T extends ReadonlyArray<infer U> ? U : T;
 declare type DropUndefined<T> = Exclude<T, undefined>;

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

@@ -20,7 +20,7 @@ async function loadLens(start, fn) {
     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)];
+            current = [...new Set(current.filter((c) => c !== undefined))];
         }
         else {
             current = await maybeLoad(current, path);

package/build/src/loadLens.js.map

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

package/build/src/loaded.d.ts

@@ -0,0 +1,49 @@
+/** Marks a given `T[P]` as the loaded/synchronous version of the collection. */
+import { Entity, OptsOf } from "./EntityManager";
+import { AsyncProperty, Collection, LoadedCollection, LoadedProperty, LoadedReference, OneToOneReference, Reference, Relation } from "./relations";
+import { LoadedOneToOneReference } from "./relations/OneToOneReference";
+import { NullOrDefinedOr } from "./utils";
+declare type MarkLoaded<T extends Entity, P, H = {}> = P extends OneToOneReference<T, infer U> ? LoadedOneToOneReference<T, Loaded<U, 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>> : P extends AsyncProperty<T, infer V> ? LoadedProperty<T, V> : unknown;
+/**
+ * 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.
+ *
+ * This means things like `entity.parent.get.grandParent.get` will work on the resulting
+ * type.
+ *
+ * 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 OneToOneReference<T, infer U> ? LoadedOneToOneReference<T, U> : 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 : T[K] : 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.
+ *
+ * `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.
+ */
+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]>;
+};
+/** Detects whether an entity is newly created, and so we can treat all of the relations as loaded. */
+export declare function isNew<T extends Entity>(e: T): e is New<T>;
+/** 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 `Relations` field in `T`, i.e. for loader hints. */
+export declare type RelationsIn<T extends Entity> = SubType<T, Relation<any, any>>;
+export declare type Loadable<T extends Entity> = SubType<T, AsyncProperty<any, any> | 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 Loadable<T> | ReadonlyArray<keyof Loadable<T>> | NestedLoadHint<T>;
+export declare type NestedLoadHint<T extends Entity> = {
+    [K in keyof Loadable<T>]?: T[K] extends Relation<any, infer U> ? LoadHint<U> : T[K] extends AsyncProperty<any, any> ? {} : never;
+};
+export {};

package/build/src/loaded.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNew = void 0;
+/** Detects whether an entity is newly created, and so we can treat all of the relations as loaded. */
+function isNew(e) {
+    return e.id === undefined;
+}
+exports.isNew = isNew;
+//# sourceMappingURL=loaded.js.map

package/build/src/loaded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaded.js","sourceRoot":"","sources":["../../src/loaded.ts"],"names":[],"mappings":";;;AAyEA,sGAAsG;AACtG,SAAgB,KAAK,CAAmB,CAAI;IAC1C,OAAO,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC;AAC5B,CAAC;AAFD,sBAEC"}

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

@@ -1,4 +1,5 @@
-import { ActualFactoryOpts, Entity, EntityConstructor, EntityManager, IdOf, New, OptsOf } from "./EntityManager";
+import { ActualFactoryOpts, Entity, EntityConstructor, EntityManager, IdOf, OptsOf } from "./EntityManager";
+import { New } from "./index";
 /**
  * DeepPartial-esque type specific to our `newTestInstance` factory.
  *
@@ -24,6 +25,37 @@ export declare function newTestInstance<T extends Entity>(em: EntityManager, cst
  * debugging purposes.
  */
 export declare const testIndex = "TEST_INDEX";
+/**
+ * A marker value for the default `newTestInstance` behavior.
+ *
+ * Useful for passing arguments to `newTestInstance` where you sometimes want to
+ * provide a specific value, and other times ask for the "pick a default" behavior
+ * (i.e. you don't want to pass `undefined` b/c that means explicitly "leave this
+ * key unset").
+ *
+ * Note that this is a function so that we can infer the return type as basically
+ * `any` without really using `any` (which would disable type-checking in the rest
+ * of the expression).
+ */
+export declare function defaultValue<T>(): T;
+/**
+ * Allows a factory to provide a default, i.e. for a field that would otherwise
+ * be optional, but still have that field be override by opts & use, without
+ * accidentally creating an extra entity as a side-effect.
+ *
+ * I.e.:
+ *
+ * ```typescript
+ * export function newAuthor(em: Entity, opts: FactoryOpts<Author>) {
+ *   return newTestInstance(em, Author, {
+ *     // publisher is not technically required, but make one
+ *     publisher: maybeNew<Publisher>({}),
+ *     ...opts,
+ *   });
+ * }
+ * ```
+ */
+export declare function maybeNew<T extends Entity>(opts?: ActualFactoryOpts<T>): FactoryEntityOpt<T>;
 /**
  * Returns a unique-ish test index for putting in `name` fields.
  *
@@ -34,9 +66,11 @@ export declare const testIndex = "TEST_INDEX";
  * Despite the name, these are 1-based, i.e. the first `Author` is `a1`.
  */
 export declare function getTestIndex<T extends Entity>(em: EntityManager, type: EntityConstructor<T>): number;
-declare type DefinedOr<T> = T | undefined;
+declare type DefinedOr<T> = T | undefined | null;
 declare type DeepPartialOpts<T extends Entity> = AllowRelationsOrPartials<OptsOf<T>>;
+/** What a factory can accept for a given entity. */
+export declare type FactoryEntityOpt<T extends Entity> = T | IdOf<T> | ActualFactoryOpts<T>;
 declare 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];
+    [P in keyof T]?: T[P] extends DefinedOr<infer U> ? U extends Array<infer V> ? V extends Entity ? Array<FactoryEntityOpt<V>> : T[P] : U extends Entity ? FactoryEntityOpt<U> : T[P] : T[P];
 };
 export {};