joist-core 2.3.0 → 2.4.0

package/build/upsert.cjs

@@ -0,0 +1,175 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_utils = require("./utils.cjs");
+const require_getProperties = require("./getProperties.cjs");
+require("./typeMap.cjs");
+const require_configure = require("./configure.cjs");
+const require_EntityMetadata = require("./EntityMetadata.cjs");
+const require_defaults = require("./defaults.cjs");
+const require_resurrection = require("./resurrection.cjs");
+const require_index = require("./index.cjs");
+const require_EntityManager = require("./EntityManager.cjs");
+const require_Entity = require("./Entity.cjs");
+let joist_utils = require("joist-utils");
+//#region src/upsert.ts
+/**
+* A utility function to do partial-update style updates.
+*
+* The difference between this and `Entity.setPartial` is that we accept `DeepPartialOrNull`
+* updates, similar to `createOrUpdateUnsafe`, instead of just a flat/shallow list of opts.
+*/
+async function updatePartial(entity, input) {
+	if (Object.keys(input).length === 0) return;
+	const meta = require_EntityMetadata.getMetadata(entity);
+	const { em } = entity;
+	await Promise.all(Object.entries(input).map(async ([key, value]) => {
+		if (value === void 0) return;
+		const field = meta.allFields[key] || Object.values(meta.allFields).find((f) => f.fieldIdName === key);
+		if (!field) {
+			if (key === "delete" || key === "remove" || key === "op") return;
+			if (require_getProperties.getProperties(meta)[key]) {
+				require_index.setOpt(meta, entity, key, value);
+				return;
+			} else throw new Error(`Unknown field ${key}`);
+		}
+		const name = field.fieldName;
+		if (field.kind === "poly" && value && !require_Entity.isEntity(value)) {
+			if (require_EntityManager.isKey(value)) require_index.setOpt(meta, entity, name, await em.load(require_configure.getConstructorFromTaggedId(value), value));
+			else throw new Error(`Cannot use partial value for polymorphic field `);
+		} else if (field.kind === "m2o" && value && !require_Entity.isEntity(value)) {
+			if (require_EntityManager.isKey(value)) require_index.setOpt(meta, entity, name, await em.load(field.otherMetadata().cstr, value));
+			else if (typeof value === "object" && value) {
+				let other;
+				if ("id" in value) other = await upsert(em, field.otherMetadata().cstr, value);
+				else if (entity.isNewEntity) other = await upsert(em, field.otherMetadata().cstr, value);
+				else {
+					other = await entity[name].load();
+					if (other) await updatePartial(other, value);
+					else other = await upsert(em, field.otherMetadata().cstr, value);
+				}
+				if (getDeleteMarker(field, value)) {
+					em.delete(other);
+					other = void 0;
+				}
+				require_index.setOpt(meta, entity, name, other);
+			}
+		} else if (field.kind === "o2o") {
+			if (value === null || require_Entity.isEntity(value)) {
+				await entity[name].load();
+				require_index.setOpt(meta, entity, name, value);
+			} else if (require_EntityManager.isKey(value)) {
+				const [, other] = await Promise.all([entity[name].load(), em.load(field.otherMetadata().cstr, value)]);
+				require_index.setOpt(meta, entity, name, other);
+			} else if (typeof value === "object" && (0, joist_utils.isPlainObject)(value)) {
+				const deleteMarker = getDeleteMarker(field, value);
+				const current = await entity[name].load();
+				let other;
+				if ("id" in value) other = await upsert(em, field.otherMetadata().cstr, value);
+				else {
+					other = current;
+					if (other) await updatePartial(other, value);
+					else other = await upsert(em, field.otherMetadata().cstr, value);
+				}
+				if (deleteMarker) em.delete(other);
+				else require_index.setOpt(meta, entity, name, other);
+			} else throw new Error(`Invalid value ${value}`);
+		} else if (field.kind === "o2m" || field.kind === "m2m") {
+			const values = require_utils.toArray(value);
+			const otherMeta = field.otherMetadata();
+			const maybeSoftDelete = otherMeta.timestampFields?.deletedAt;
+			if (values.some((v) => v && typeof v === "object" && !require_Entity.isEntity(v) && v.op != null)) {
+				let anyValueMissingOp = false;
+				const current = entity[name];
+				await Promise.all(values.map(async (value) => {
+					const [, , op] = getCollectionMarkers(field, value);
+					if (op === "delete") {
+						const other = await upsert(em, otherMeta.cstr, withOwnerField(field, value, entity));
+						if (maybeSoftDelete) {
+							const serde = otherMeta.fields[maybeSoftDelete].serde;
+							const now = /* @__PURE__ */ new Date();
+							other.set({ [maybeSoftDelete]: serde.mapFromNow(now) });
+						} else entity.em.delete(other);
+					} else if (op === "remove") {
+						const other = await upsert(em, otherMeta.cstr, withOwnerField(field, value, entity));
+						current.remove(other);
+					} else if (op === "include") {
+						const other = await upsert(em, otherMeta.cstr, withOwnerField(field, value, entity));
+						current.add(other);
+					} else if (op === "incremental") {} else anyValueMissingOp = true;
+				}));
+				if (anyValueMissingOp) throw new Error("If any child sets the `op` key, then all children must have the `op` key.");
+				return;
+			}
+			const others = await Promise.all(values.map(async (value) => {
+				if (require_Entity.isEntity(value)) return value;
+				else if (require_EntityManager.isKey(value)) return em.load(field.otherMetadata().cstr, value);
+				else if (value === null || value === void 0) return;
+				else if (!(0, joist_utils.isPlainObject)(value)) throw new Error(`Invalid value ${value}`);
+				else {
+					const [deleteMarker, removeMarker] = getCollectionMarkers(field, value);
+					const other = await upsert(em, field.otherMetadata().cstr, withOwnerField(field, value, entity));
+					if (deleteMarker) {
+						em.delete(other);
+						return other;
+					} else if (removeMarker) return;
+					else return other;
+				}
+			}));
+			await entity[name].load();
+			require_index.setOpt(meta, entity, name, others.filter((v) => v !== void 0));
+		} else require_index.setOpt(meta, entity, name, value);
+	}));
+}
+/**
+* A utility function to create-or-update/upsert entities coming from a partial-update style API.
+*/
+async function upsert(em, constructor, input) {
+	const { id, ...rest } = input;
+	const entity = id !== null && id !== void 0 ? await em.load(constructor, id) : (id === void 0 ? await require_resurrection.findExistingIfUniqueBy(em, constructor, rest) : void 0) ?? em.createPartial(require_index.asConcreteCstr(constructor), {});
+	await updatePartial(entity, rest);
+	if (entity.isNewEntity) require_defaults.setSyncDefaults(entity);
+	return entity;
+}
+/**
+* Adds the o2m owner field so child resurrection can find rows whose `uniqueBy` includes their parent.
+* I.e. upserting `Author.books: [{ title: "b1" }]` should lookup `Book.uniqueBy = [["author", "title"]]`.
+*/
+function withOwnerField(field, value, owner) {
+	if (field.kind !== "o2m" || !(0, joist_utils.isPlainObject)(value)) return value;
+	const ownerField = field.otherFieldName;
+	const ownerFieldId = field.otherMetadata().allFields[ownerField]?.fieldIdName;
+	if (Object.hasOwn(value, ownerField) || ownerFieldId && Object.hasOwn(value, ownerFieldId)) return value;
+	if (ownerFieldId && !owner.isNewEntity) return {
+		...value,
+		[ownerFieldId]: owner.id
+	};
+	return {
+		...value,
+		[ownerField]: owner
+	};
+}
+function getCollectionMarkers(field, value) {
+	const allowDelete = !field.otherMetadata().fields["delete"];
+	const allowRemove = !field.otherMetadata().fields["remove"];
+	const allowOp = !field.otherMetadata().fields["op"];
+	const deleteMarker = allowDelete && value["delete"];
+	const removeMarker = allowRemove && value["remove"];
+	const opMarker = allowOp && value["op"];
+	if (deleteMarker !== void 0) delete value.delete;
+	if (removeMarker !== void 0) delete value.remove;
+	if (opMarker !== void 0) delete value.op;
+	return [
+		deleteMarker,
+		removeMarker,
+		opMarker
+	];
+}
+function getDeleteMarker(field, value) {
+	const deleteMarker = !field.otherMetadata().fields["delete"] && value["delete"];
+	if (deleteMarker !== void 0) delete value.delete;
+	return deleteMarker;
+}
+//#endregion
+exports.updatePartial = updatePartial;
+exports.upsert = upsert;
+
+//# sourceMappingURL=upsert.cjs.map

package/build/upsert.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.cjs","names":["getMetadata","getProperties","isEntity","isKey","getConstructorFromTaggedId","isPlainObject","toArray","findExistingIfUniqueBy","asConcreteCstr"],"sources":["../src/upsert.ts"],"sourcesContent":["import { isPlainObject } from \"joist-utils\";\nimport { setSyncDefaults } from \"src/defaults.ts\";\nimport { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type EntityManager, type IdOf, type MaybeAbstractEntityConstructor, isKey } from \"src/EntityManager.ts\";\nimport {\n  type ManyToManyField,\n  type ManyToOneField,\n  type OneToManyField,\n  type OneToOneField,\n  getMetadata,\n} from \"src/EntityMetadata.ts\";\nimport {\n  type PartialOrNull,\n  type TimestampSerde,\n  asConcreteCstr,\n  getConstructorFromTaggedId,\n  getProperties,\n  setOpt,\n} from \"src/index.ts\";\nimport { findExistingIfUniqueBy } from \"src/resurrection.ts\";\nimport { type OptIdsOf, type OptsOf } from \"src/typeMap.ts\";\nimport { type NullOrDefinedOr, toArray } from \"src/utils.ts\";\n\n/**\n * The type for `EntityManager.createOrUpdateUnsafe` that allows \"upsert\"-ish behavior.\n *\n * I.e. `T` is an entity with an optional id (create if unset, update if set), and we recurse\n * into any relations (references or collections) to allow those relations themselves to be\n * any combination of 1) ids to existing entities, 2) entities directly, 3) null/undefined\n * with the appropriate partial-update behavior, or 4) partials.\n */\nexport type DeepPartialOrNull<T extends Entity> = { id?: IdOf<T> | null } & AllowRelationsToBeIdsOrEntitiesOrPartials<\n  PartialOrNull<OptsOf<T> & OptIdsOf<T>>\n> &\n  OptIdsOf<T>;\n\n/** Flags that allow `upsert` to delete or remove entities. */\ntype CollectionFlags = {\n  delete?: boolean | null;\n  remove?: boolean | null;\n  op?: \"remove\" | \"delete\" | \"include\" | \"incremental\";\n};\n\n/** Flag that allows `upsert` to delete. */\ntype DeleteFlag = {\n  delete?: boolean | null;\n};\n\ntype AllowRelationsToBeIdsOrEntitiesOrPartials<T> = {\n  [P in keyof T]: T[P] extends NullOrDefinedOr<infer U>\n    ? U extends Array<infer V>\n      ? V extends Entity\n        ? Array<V | (DeepPartialOrNull<V> & CollectionFlags) | IdOf<V>> | null\n        : T[P]\n      : U extends Entity\n        ? U | (DeepPartialOrNull<U> & DeleteFlag) | IdOf<U> | null\n        : T[P]\n    : T[P];\n};\n\n/**\n * A utility function to do partial-update style updates.\n *\n * The difference between this and `Entity.setPartial` is that we accept `DeepPartialOrNull`\n * updates, similar to `createOrUpdateUnsafe`, instead of just a flat/shallow list of opts.\n */\nexport async function updatePartial<T extends Entity>(entity: T, input: DeepPartialOrNull<T>): Promise<void> {\n  if (Object.keys(input).length === 0) return;\n  const meta = getMetadata(entity);\n  const { em } = entity;\n  // Do a Promise.all so we .load() relations in parallel\n  await Promise.all(\n    Object.entries(input).map(async ([key, value]) => {\n      // setPartial ==> `undefined` is a noop\n      if (value === undefined) return;\n\n      // Watch for the `bookId` / `bookIds` aliases\n      const field = meta.allFields[key] || Object.values(meta.allFields).find((f) => f.fieldIdName === key);\n\n      if (!field) {\n        // Allow (ignore here) delete/remove flags that we assume the API layer (i.e. GraphQL) will have specifically\n        // allowed, i.e. this isn't the Rails form bug where users can POST in any random field they want.\n        const flagField = key === \"delete\" || key === \"remove\" || key === \"op\";\n        if (flagField) return;\n        // Look for non-field properties like a fullName setter\n        const prop = getProperties(meta)[key];\n        if (prop) {\n          setOpt(meta, entity, key, value);\n          return;\n        } else {\n          throw new Error(`Unknown field ${key}`);\n        }\n      }\n\n      // Don't use key b/c it might be the bookId alias\n      const name = field.fieldName;\n\n      if (field.kind === \"poly\" && value && !isEntity(value)) {\n        // Resolve non-entity poly values\n        if (isKey(value)) {\n          setOpt(meta, entity, name, await em.load(getConstructorFromTaggedId(value), value));\n        } else {\n          throw new Error(`Cannot use partial value for polymorphic field `);\n        }\n      } else if (field.kind === \"m2o\" && value && !isEntity(value)) {\n        // This is a many-to-one reference\n        if (isKey(value)) {\n          setOpt(meta, entity, name, await em.load(field.otherMetadata().cstr, value));\n        } else if (typeof value === \"object\" && value) {\n          let other: any;\n          if (\"id\" in value) {\n            // This is a many-to-one partial update to an existing entity (they passed an id)\n            other = await upsert(em, field.otherMetadata().cstr, value as any);\n          } else {\n            // This is a many-to-one partial w/o passing an id, i.e. `upsert(Author, { id: \"a:1\", publisher: { name: \"p1\" } })`\n            if (entity.isNewEntity) {\n              // If we're brand new, our child/other has to be brand new as well\n              other = await upsert(em, field.otherMetadata().cstr, value);\n            } else {\n              // the o2o upsert hash didn't have an id, so find-or-create it\n              other = await (entity as any)[name].load();\n              if (other) {\n                await updatePartial(other, value);\n              } else {\n                other = await upsert(em, field.otherMetadata().cstr, value);\n              }\n            }\n          }\n          const deleteMarker = getDeleteMarker(field, value);\n          if (deleteMarker) {\n            em.delete(other);\n            other = undefined;\n          }\n          setOpt(meta, entity, name, other);\n        }\n      } else if (field.kind === \"o2o\") {\n        // ^-- o2o always need loaded to be set, so don't fall through\n        if (value === null || isEntity(value)) {\n          await (entity as any)[name].load();\n          setOpt(meta, entity, name, value);\n        } else if (isKey(value)) {\n          const [, other] = await Promise.all([\n            (entity as any)[name].load(),\n            em.load(field.otherMetadata().cstr, value),\n          ]);\n          setOpt(meta, entity, name, other);\n        } else if (typeof value === \"object\" && isPlainObject(value)) {\n          const deleteMarker = getDeleteMarker(field, value);\n          // Always load the o2o so we can set it\n          const current = await (entity as any)[name].load();\n          let other: any;\n          if (\"id\" in value) {\n            // The o2o upsert hash was passed an id, so load it\n            other = await upsert(em, field.otherMetadata().cstr, value as any);\n          } else {\n            // the o2o upsert hash didn't have an id, so find-or-create it\n            other = current;\n            if (other) {\n              await updatePartial(other, value);\n            } else {\n              other = await upsert(em, field.otherMetadata().cstr, value);\n            }\n          }\n          if (deleteMarker) {\n            em.delete(other);\n          } else {\n            setOpt(meta, entity, name, other);\n          }\n        } else {\n          throw new Error(`Invalid value ${value}`);\n        }\n      } else if (field.kind === \"o2m\" || field.kind === \"m2m\") {\n        // Look for one-to-many/many-to-many partials\n        // `null` is handled later, and treated as `[]`, which needs the collection loaded\n\n        const values = toArray(value);\n        const otherMeta = field.otherMetadata();\n        const maybeSoftDelete = otherMeta.timestampFields?.deletedAt;\n\n        // Incremental handling. Detect incremental mode by a meaningful `op` value--`op: undefined`/`op: null`\n        // is the natural shape of an optional field and must behave like \"no op\", consistent with how\n        // updatePartial treats `value === undefined` and how delete/remove are read by truthiness.\n        const anyValueHasOp = values.some((v: any) => v && typeof v === \"object\" && !isEntity(v) && v.op != null);\n        if (anyValueHasOp) {\n          let anyValueMissingOp = false;\n          const current = (entity as any)[name];\n          // The `op` behavior means incremental and wants to do this:\n          await Promise.all(\n            values.map(async (value: any) => {\n              const [, , op] = getCollectionMarkers(field, value);\n              if (op === \"delete\") {\n                const other = await upsert(em, otherMeta.cstr, withOwnerField(field, value, entity));\n                // We need to check if this is a soft-deletable entity, and if so, we will soft-delete it.\n                if (maybeSoftDelete) {\n                  const serde = otherMeta.fields[maybeSoftDelete].serde as TimestampSerde<unknown>;\n                  const now = new Date();\n                  other.set({ [maybeSoftDelete]: serde.mapFromNow(now) });\n                } else {\n                  entity.em.delete(other);\n                }\n              } else if (op === \"remove\") {\n                const other = await upsert(em, otherMeta.cstr, withOwnerField(field, value, entity));\n                current.remove(other);\n              } else if (op === \"include\") {\n                const other = await upsert(em, otherMeta.cstr, withOwnerField(field, value, entity));\n                current.add(other);\n              } else if (op === \"incremental\") {\n                // This is a marker entry, just ignore it\n              } else {\n                // A child entered incremental mode (a sibling had a real op) but has no op of its own;\n                // never silently skip it--flag it so the guard below throws instead of dropping the row.\n                anyValueMissingOp = true;\n              }\n            }),\n          );\n          if (anyValueMissingOp) {\n            throw new Error(\"If any child sets the `op` key, then all children must have the `op` key.\");\n          }\n          return; // return from the op-based incremental behavior\n        }\n\n        // Otherwise we do exhaustive sets, will still looking for `delete`/`remove` markers\n        const others = await Promise.all(\n          values.map(async (value: any) => {\n            if (isEntity(value)) {\n              return value;\n            } else if (isKey(value)) {\n              return em.load(field.otherMetadata().cstr, value);\n            } else if (value === null || value === undefined) {\n              return undefined;\n            } else if (!isPlainObject(value)) {\n              throw new Error(`Invalid value ${value}`);\n            } else {\n              // Look for `delete: true/false` and `remove: true/false` markers\n              const [deleteMarker, removeMarker] = getCollectionMarkers(field, value);\n              const other = await upsert(em, field.otherMetadata().cstr, withOwnerField(field, value, entity));\n              if (deleteMarker) {\n                // if (maybeSoftDelete) {\n                //   const serde = meta.fields[maybeSoftDelete].serde as TimestampSerde<unknown>;\n                //   const now = new Date();\n                //   other.set({ [maybeSoftDelete]: serde.mapFromNow(now) });\n                // } else {\n                // }\n                em.delete(other);\n                return other;\n              } else if (removeMarker) {\n                return undefined;\n              } else {\n                return other;\n              }\n            }\n          }),\n        );\n\n        await (entity as any)[name].load();\n        setOpt(\n          meta,\n          entity,\n          name,\n          others.filter((v) => v !== undefined),\n        );\n      } else {\n        // If we get here, value should be a vanilla value that `setOpt` can handle/pass through as-is\n        setOpt(meta, entity, name, value);\n      }\n    }),\n  );\n}\n\n/**\n * A utility function to create-or-update/upsert entities coming from a partial-update style API.\n */\nexport async function upsert<T extends Entity>(\n  em: EntityManager<any, any, any>,\n  constructor: MaybeAbstractEntityConstructor<T>,\n  input: DeepPartialOrNull<T>,\n): Promise<T> {\n  const { id, ...rest } = input;\n  const entity =\n    id !== null && id !== undefined\n      ? await em.load(constructor, id)\n      : // Look for an existing entity we could resurrect\n        ((id === undefined ? await findExistingIfUniqueBy(em, constructor, rest) : undefined) ??\n        em.createPartial(asConcreteCstr(constructor), {}));\n  await updatePartial(entity, rest as any);\n  // Do this manually since we're not going through setOpts anymore\n  if (entity.isNewEntity) {\n    setSyncDefaults(entity);\n  }\n  return entity;\n}\n\n/**\n * Adds the o2m owner field so child resurrection can find rows whose `uniqueBy` includes their parent.\n * I.e. upserting `Author.books: [{ title: \"b1\" }]` should lookup `Book.uniqueBy = [[\"author\", \"title\"]]`.\n */\nfunction withOwnerField(field: OneToManyField | ManyToManyField, value: any, owner: Entity): any {\n  if (field.kind !== \"o2m\" || !isPlainObject(value)) return value;\n  const ownerField = field.otherFieldName;\n  const ownerFieldId = field.otherMetadata().allFields[ownerField]?.fieldIdName;\n  if (Object.hasOwn(value, ownerField) || (ownerFieldId && Object.hasOwn(value, ownerFieldId))) return value;\n  if (ownerFieldId && !owner.isNewEntity) return { ...value, [ownerFieldId]: owner.id };\n  return { ...value, [ownerField]: owner };\n}\n\nfunction getCollectionMarkers(field: OneToManyField | ManyToManyField, value: any): [any, any, any] {\n  const allowDelete = !field.otherMetadata().fields[\"delete\"];\n  const allowRemove = !field.otherMetadata().fields[\"remove\"];\n  const allowOp = !field.otherMetadata().fields[\"op\"];\n\n  // Look for `delete: true/false` and `remove: true/false` markers\n  const deleteMarker: any = allowDelete && value[\"delete\"];\n  const removeMarker: any = allowRemove && value[\"remove\"];\n  const opMarker: any = allowOp && value[\"op\"];\n\n  // Remove the markers, regardless of true/false, before recursing into upsert to avoid unknown fields\n  if (deleteMarker !== undefined) delete value.delete;\n  if (removeMarker !== undefined) delete value.remove;\n  if (opMarker !== undefined) delete value.op;\n\n  return [deleteMarker, removeMarker, opMarker];\n}\nfunction getDeleteMarker(field: OneToOneField | ManyToOneField, value: any): boolean {\n  const allowDelete = !field.otherMetadata().fields[\"delete\"];\n  const deleteMarker: any = allowDelete && value[\"delete\"];\n  if (deleteMarker !== undefined) delete value.delete;\n  return deleteMarker;\n}\n"],"mappings":"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"}

package/build/upsert.d.cts

@@ -0,0 +1,42 @@
+import { OptIdsOf, OptsOf } from "./typeMap.cjs";
+import { NullOrDefinedOr } from "./utils.cjs";
+import { PartialOrNull } from "./index.cjs";
+import { EntityManager, IdOf, MaybeAbstractEntityConstructor } from "./EntityManager.cjs";
+import { Entity } from "./Entity.cjs";
+//#region src/upsert.d.ts
+/**
+ * The type for `EntityManager.createOrUpdateUnsafe` that allows "upsert"-ish behavior.
+ *
+ * I.e. `T` is an entity with an optional id (create if unset, update if set), and we recurse
+ * into any relations (references or collections) to allow those relations themselves to be
+ * any combination of 1) ids to existing entities, 2) entities directly, 3) null/undefined
+ * with the appropriate partial-update behavior, or 4) partials.
+ */
+type DeepPartialOrNull<T extends Entity> = {
+  id?: IdOf<T> | null;
+} & AllowRelationsToBeIdsOrEntitiesOrPartials<PartialOrNull<OptsOf<T> & OptIdsOf<T>>> & OptIdsOf<T>;
+/** Flags that allow `upsert` to delete or remove entities. */
+type CollectionFlags = {
+  delete?: boolean | null;
+  remove?: boolean | null;
+  op?: "remove" | "delete" | "include" | "incremental";
+};
+/** Flag that allows `upsert` to delete. */
+type DeleteFlag = {
+  delete?: boolean | null;
+};
+type AllowRelationsToBeIdsOrEntitiesOrPartials<T> = { [P in keyof T]: T[P] extends NullOrDefinedOr<infer U> ? U extends Array<infer V> ? V extends Entity ? Array<V | (DeepPartialOrNull<V> & CollectionFlags) | IdOf<V>> | null : T[P] : U extends Entity ? U | (DeepPartialOrNull<U> & DeleteFlag) | IdOf<U> | null : T[P] : T[P]; };
+/**
+ * A utility function to do partial-update style updates.
+ *
+ * The difference between this and `Entity.setPartial` is that we accept `DeepPartialOrNull`
+ * updates, similar to `createOrUpdateUnsafe`, instead of just a flat/shallow list of opts.
+ */
+declare function updatePartial<T extends Entity>(entity: T, input: DeepPartialOrNull<T>): Promise<void>;
+/**
+ * A utility function to create-or-update/upsert entities coming from a partial-update style API.
+ */
+declare function upsert<T extends Entity>(em: EntityManager<any, any, any>, constructor: MaybeAbstractEntityConstructor<T>, input: DeepPartialOrNull<T>): Promise<T>;
+//#endregion
+export { DeepPartialOrNull, updatePartial, upsert };
+//# sourceMappingURL=upsert.d.cts.map

package/build/upsert.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.d.cts","names":[],"sources":["../src/upsert.ts"],"mappings":";;;;;;;;;;;;;;KA+BY,kBAAkB,UAAU;EAAY,KAAK,KAAK;IAAc,0CAC1E,cAAc,OAAO,KAAK,SAAS,OAEnC,SAAS;;KAGN;EACH;EACA;EACA;;;KAIG;EACH;;KAGG,0CAA0C,QAC5C,WAAW,IAAI,EAAE,WAAW,sBAAsB,KAC/C,UAAU,YAAY,KACpB,UAAU,SACR,MAAM,KAAK,kBAAkB,KAAK,mBAAmB,KAAK,aAC1D,EAAE,KACJ,UAAU,SACR,KAAK,kBAAkB,KAAK,cAAc,KAAK,YAC/C,EAAE,KACN,EAAE;;;;;;;iBASc,cAAc,UAAU,QAAQ,QAAQ,GAAG,OAAO,kBAAkB,KAAK;;;;iBA8MzE,OAAO,UAAU,QACrC,IAAI,8BACJ,aAAa,+BAA+B,IAC5C,OAAO,kBAAkB,KACxB,QAAQ"}

package/build/upsert.d.mts

@@ -0,0 +1,42 @@
+import { OptIdsOf, OptsOf } from "./typeMap.mjs";
+import { NullOrDefinedOr } from "./utils.mjs";
+import { PartialOrNull } from "./index.mjs";
+import { EntityManager, IdOf, MaybeAbstractEntityConstructor } from "./EntityManager.mjs";
+import { Entity } from "./Entity.mjs";
+//#region src/upsert.d.ts
+/**
+ * The type for `EntityManager.createOrUpdateUnsafe` that allows "upsert"-ish behavior.
+ *
+ * I.e. `T` is an entity with an optional id (create if unset, update if set), and we recurse
+ * into any relations (references or collections) to allow those relations themselves to be
+ * any combination of 1) ids to existing entities, 2) entities directly, 3) null/undefined
+ * with the appropriate partial-update behavior, or 4) partials.
+ */
+type DeepPartialOrNull<T extends Entity> = {
+  id?: IdOf<T> | null;
+} & AllowRelationsToBeIdsOrEntitiesOrPartials<PartialOrNull<OptsOf<T> & OptIdsOf<T>>> & OptIdsOf<T>;
+/** Flags that allow `upsert` to delete or remove entities. */
+type CollectionFlags = {
+  delete?: boolean | null;
+  remove?: boolean | null;
+  op?: "remove" | "delete" | "include" | "incremental";
+};
+/** Flag that allows `upsert` to delete. */
+type DeleteFlag = {
+  delete?: boolean | null;
+};
+type AllowRelationsToBeIdsOrEntitiesOrPartials<T> = { [P in keyof T]: T[P] extends NullOrDefinedOr<infer U> ? U extends Array<infer V> ? V extends Entity ? Array<V | (DeepPartialOrNull<V> & CollectionFlags) | IdOf<V>> | null : T[P] : U extends Entity ? U | (DeepPartialOrNull<U> & DeleteFlag) | IdOf<U> | null : T[P] : T[P]; };
+/**
+ * A utility function to do partial-update style updates.
+ *
+ * The difference between this and `Entity.setPartial` is that we accept `DeepPartialOrNull`
+ * updates, similar to `createOrUpdateUnsafe`, instead of just a flat/shallow list of opts.
+ */
+declare function updatePartial<T extends Entity>(entity: T, input: DeepPartialOrNull<T>): Promise<void>;
+/**
+ * A utility function to create-or-update/upsert entities coming from a partial-update style API.
+ */
+declare function upsert<T extends Entity>(em: EntityManager<any, any, any>, constructor: MaybeAbstractEntityConstructor<T>, input: DeepPartialOrNull<T>): Promise<T>;
+//#endregion
+export { DeepPartialOrNull, updatePartial, upsert };
+//# sourceMappingURL=upsert.d.mts.map

package/build/upsert.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsert.d.mts","names":[],"sources":["../src/upsert.ts"],"mappings":";;;;;;;;;;;;;;KA+BY,kBAAkB,UAAU;EAAY,KAAK,KAAK;IAAc,0CAC1E,cAAc,OAAO,KAAK,SAAS,OAEnC,SAAS;;KAGN;EACH;EACA;EACA;;;KAIG;EACH;;KAGG,0CAA0C,QAC5C,WAAW,IAAI,EAAE,WAAW,sBAAsB,KAC/C,UAAU,YAAY,KACpB,UAAU,SACR,MAAM,KAAK,kBAAkB,KAAK,mBAAmB,KAAK,aAC1D,EAAE,KACJ,UAAU,SACR,KAAK,kBAAkB,KAAK,cAAc,KAAK,YAC/C,EAAE,KACN,EAAE;;;;;;;iBASc,cAAc,UAAU,QAAQ,QAAQ,GAAG,OAAO,kBAAkB,KAAK;;;;iBA8MzE,OAAO,UAAU,QACrC,IAAI,8BACJ,aAAa,+BAA+B,IAC5C,OAAO,kBAAkB,KACxB,QAAQ"}