joist-core 2.4.0-next.2 → 2.4.0-next.21

package/build/relations/RecursiveCollection.js

@@ -1,13 +1,13 @@
 import { isCollection, isLoadedCollection } from "./Collection.js";
 import { AbstractRelationImpl } from "./AbstractRelationImpl.js";
 import { RelationT, RelationU } from "./RelationSymbols.js";
+import { RecursiveCycleError } from "./RecursiveCycleError.js";
+import { isLoadedReference, isReference } from "./Reference.js";
+import { isLoadedOneToOneReference, isOneToOneReference } from "./OneToOneReference.js";
 import { recursiveChildrenBatchLoader } from "../batchloaders/recursiveChildrenBatchLoader.js";
 import { recursiveM2mBatchLoader } from "../batchloaders/recursiveM2mBatchLoader.js";
 import { recursiveParentsBatchLoader } from "../batchloaders/recursiveParentsBatchLoader.js";
 import "./ReadOnlyCollection.js";
-import { RecursiveCycleError } from "./RecursiveCycleError.js";
-import { isLoadedReference, isReference } from "./Reference.js";
-import { isLoadedOneToOneReference, isOneToOneReference } from "./OneToOneReference.js";
 import { fail } from "../utils.js";
 import { lazyField } from "../newEntity.js";
 import { getMetadata } from "../EntityMetadata.js";

package/build/relations/hasProperty.cjs

@@ -1,10 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_loading_loadHints = require("../loading/loadHints.cjs");
 const require_relations_PropertySymbols = require("./PropertySymbols.cjs");
 const require_relations_RecursiveCycleError = require("./RecursiveCycleError.cjs");
-const require_reactivity_reactiveHints = require("../reactivity/reactiveHints.cjs");
-const require_loading_loadHints = require("../loading/loadHints.cjs");
 const require_utils = require("../utils.cjs");
 const require_newEntity = require("../newEntity.cjs");
+const require_reactivity_reactiveHints = require("../reactivity/reactiveHints.cjs");
 const require_EntityMetadata = require("../EntityMetadata.cjs");
 require("../Entity.cjs");
 //#region src/relations/hasProperty.ts

package/build/relations/hasProperty.js

@@ -1,9 +1,9 @@
+import { isLoaded } from "../loading/loadHints.js";
 import { PropertyT } from "./PropertySymbols.js";
 import { RecursiveCycleError } from "./RecursiveCycleError.js";
-import { convertToLoadHint } from "../reactivity/reactiveHints.js";
-import { isLoaded } from "../loading/loadHints.js";
 import { tryResolve } from "../utils.js";
 import { lazyField } from "../newEntity.js";
+import { convertToLoadHint } from "../reactivity/reactiveHints.js";
 import { getMetadata } from "../EntityMetadata.js";
 import "../Entity.js";
 //#region src/relations/hasProperty.ts

package/build/relations/index.cjs

@@ -3,12 +3,8 @@ const require_relations_Collection = require("./Collection.cjs");
 const require_relations_CustomCollection = require("./CustomCollection.cjs");
 const require_relations_EnumCollection = require("./EnumCollection.cjs");
 const require_relations_CustomReference = require("./CustomReference.cjs");
-const require_relations_ReactiveGetter = require("./ReactiveGetter.cjs");
-const require_relations_Relation = require("./Relation.cjs");
-const require_relations_ReadOnlyCollection = require("./ReadOnlyCollection.cjs");
-const require_relations_RecursiveCycleError = require("./RecursiveCycleError.cjs");
-const require_relations_RecursiveCollection = require("./RecursiveCollection.cjs");
 const require_relations_hasAsyncMethod = require("./hasAsyncMethod.cjs");
+const require_relations_RecursiveCycleError = require("./RecursiveCycleError.cjs");
 const require_relations_hasProperty = require("./hasProperty.cjs");
 const require_relations_AsyncProperty = require("./AsyncProperty.cjs");
 const require_relations_LazyField = require("./LazyField.cjs");
@@ -18,6 +14,7 @@ const require_relations_Reference = require("./Reference.cjs");
 const require_relations_hasOneDerived = require("./hasOneDerived.cjs");
 const require_relations_hasOneThrough = require("./hasOneThrough.cjs");
 const require_relations_ManyToManyCollection = require("./ManyToManyCollection.cjs");
+const require_relations_Relation = require("./Relation.cjs");
 const require_relations_ManyToManyLargeCollection = require("./ManyToManyLargeCollection.cjs");
 const require_relations_OneToManyCollection = require("./OneToManyCollection.cjs");
 const require_relations_ManyToOneReference = require("./ManyToOneReference.cjs");
@@ -26,9 +23,12 @@ const require_relations_ReactiveReference = require("./ReactiveReference.cjs");
 const require_relations_OneToOneReference = require("./OneToOneReference.cjs");
 const require_relations_PolymorphicReference = require("./PolymorphicReference.cjs");
 const require_relations_ReactiveField = require("./ReactiveField.cjs");
+const require_relations_ReactiveGetter = require("./ReactiveGetter.cjs");
 const require_relations_ReactiveManyToMany = require("./ReactiveManyToMany.cjs");
 const require_relations_ReactiveManyToManyOtherSide = require("./ReactiveManyToManyOtherSide.cjs");
 const require_relations_AsyncReactiveField = require("./AsyncReactiveField.cjs");
+const require_relations_RecursiveCollection = require("./RecursiveCollection.cjs");
+const require_relations_ReadOnlyCollection = require("./ReadOnlyCollection.cjs");
 exports.AsyncPropertyImpl = require_relations_AsyncProperty.AsyncPropertyImpl;
 exports.CustomCollection = require_relations_CustomCollection.CustomCollection;
 exports.CustomReference = require_relations_CustomReference.CustomReference;

package/build/relations/index.js

@@ -2,12 +2,8 @@ import { isCollection, isLoadedCollection } from "./Collection.js";
 import { CustomCollection, hasCustomCollection } from "./CustomCollection.js";
 import { EnumCollectionImpl, hasEnumCollection } from "./EnumCollection.js";
 import { CustomReference, hasCustomReference } from "./CustomReference.js";
-import { hasReactiveGetter, isReactiveGetter } from "./ReactiveGetter.js";
-import { isRelation } from "./Relation.js";
-import { isLoadedReadOnlyCollection, isReadOnlyCollection } from "./ReadOnlyCollection.js";
-import { RecursiveCycleError } from "./RecursiveCycleError.js";
-import { hasRecursiveChildren, hasRecursiveM2m, hasRecursiveParents } from "./RecursiveCollection.js";
 import { hasAsyncMethod } from "./hasAsyncMethod.js";
+import { RecursiveCycleError } from "./RecursiveCycleError.js";
 import { PropertyImpl, hasProperty, hasReactiveProperty, isLoadedProperty, isProperty } from "./hasProperty.js";
 import { AsyncPropertyImpl, hasAsyncProperty, isAsyncProperty, isLoadedAsyncProperty } from "./AsyncProperty.js";
 import { LazyFieldImpl, hasLazyField, isLazyField, isLoadedLazyField } from "./LazyField.js";
@@ -17,6 +13,7 @@ import { isLoadedReference, isReference } from "./Reference.js";
 import { hasOneDerived } from "./hasOneDerived.js";
 import { hasOneThrough } from "./hasOneThrough.js";
 import { ManyToManyCollection, hasManyToMany } from "./ManyToManyCollection.js";
+import { isRelation } from "./Relation.js";
 import { ManyToManyLargeCollection, hasLargeManyToMany } from "./ManyToManyLargeCollection.js";
 import { OneToManyCollection, hasMany } from "./OneToManyCollection.js";
 import { ManyToOneReferenceImpl, hasOne, isManyToOneReference } from "./ManyToOneReference.js";
@@ -25,7 +22,10 @@ import { ReactiveReferenceImpl, hasReactiveReference, isReactiveReference } from
 import { OneToOneReferenceImpl, hasOneToOne, isLoadedOneToOneReference, isOneToOneReference } from "./OneToOneReference.js";
 import { PolymorphicReferenceImpl, hasOnePolymorphic, isPolymorphicReference } from "./PolymorphicReference.js";
 import { hasReactiveField, isReactiveField } from "./ReactiveField.js";
+import { hasReactiveGetter, isReactiveGetter } from "./ReactiveGetter.js";
 import { ReactiveManyToManyImpl, hasReactiveManyToMany, isReactiveManyToMany } from "./ReactiveManyToMany.js";
 import { ReactiveManyToManyOtherSideImpl, hasReactiveManyToManyOtherSide, isReactiveManyToManyOtherSide } from "./ReactiveManyToManyOtherSide.js";
 import { hasAsyncReactiveField, isAsyncReactiveField } from "./AsyncReactiveField.js";
+import { hasRecursiveChildren, hasRecursiveM2m, hasRecursiveParents } from "./RecursiveCollection.js";
+import { isLoadedReadOnlyCollection, isReadOnlyCollection } from "./ReadOnlyCollection.js";
 export { AsyncPropertyImpl, CustomCollection, CustomReference, EnumCollectionImpl, LazyFieldImpl, ManyToManyCollection, ManyToManyLargeCollection, ManyToOneReferenceImpl, OneToManyCollection, OneToManyLargeCollection, OneToOneReferenceImpl, PolymorphicReferenceImpl, PropertyImpl, ReactiveManyToManyImpl, ReactiveManyToManyOtherSideImpl, ReactiveReferenceImpl, RecursiveCycleError, hasAsyncMethod, hasAsyncProperty, hasAsyncReactiveField, hasCustomCollection, hasCustomReference, hasEnumCollection, hasLargeMany, hasLargeManyToMany, hasLazyField, hasMany, hasManyDerived, hasManyThrough, hasManyToMany, hasOne, hasOneDerived, hasOnePolymorphic, hasOneThrough, hasOneToOne, hasProperty, hasReactiveField, hasReactiveGetter, hasReactiveManyToMany, hasReactiveManyToManyOtherSide, hasReactiveProperty, hasReactiveReference, hasRecursiveChildren, hasRecursiveM2m, hasRecursiveParents, isAsyncProperty, isAsyncReactiveField, isCollection, isLazyField, isLoadedAsyncProperty, isLoadedCollection, isLoadedLazyField, isLoadedOneToOneReference, isLoadedProperty, isLoadedReadOnlyCollection, isLoadedReference, isManyToOneReference, isOneToOneReference, isPolymorphicReference, isProperty, isReactiveField, isReactiveGetter, isReactiveManyToMany, isReactiveManyToManyOtherSide, isReactiveReference, isReadOnlyCollection, isReference, isRelation };

package/build/resurrection.cjs

@@ -24,7 +24,7 @@ async function findExistingIfUniqueBy(em, constructor, input) {
 			return inMemory[0];
 		}
 		if (Object.values(where).some((value) => require_Entity.isEntity(value) && value.isNewEntity)) continue;
-		const entities = onlySoftDeleted(await em.find(constructor, where, { softDeletes: "include" }));
+		const entities = onlySoftDeleted(await em.find(constructor, newWhereEqual(meta, where), { softDeletes: "include" }));
 		if (entities.length > 1) throw new require_EntityManager.TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);
 		else if (entities.length === 1) {
 			resurrectIfSoftDeleted(entities[0]);
@@ -67,8 +67,18 @@ function isQueryableIdentityField(field) {
 function whereAsString(where) {
 	return Object.entries(where).map(([key, value]) => `${key}=${value}`).join(", ");
 }
+/** Builds exact identity filters for primitives and relations. */
+function newWhereEqual(meta, input) {
+	const where = {};
+	for (const name of Object.keys(input)) {
+		const value = input[name] ?? null;
+		where[name] = meta.allFields[name]?.kind === "primitive" ? { eq: value } : value;
+	}
+	return where;
+}
 //#endregion
 exports.findExistingIfUniqueBy = findExistingIfUniqueBy;
+exports.newWhereEqual = newWhereEqual;
 exports.resurrectIfSoftDeleted = resurrectIfSoftDeleted;
 
 //# sourceMappingURL=resurrection.cjs.map

package/build/resurrection.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"resurrection.cjs","names":["getBaseMeta","getMetadata","TooManyError","isEntity"],"sources":["../src/resurrection.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type EntityManager, type MaybeAbstractEntityConstructor, TooManyError } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, type Field, getBaseMeta, getMetadata } from \"src/EntityMetadata.ts\";\nimport { setField } from \"src/fields.ts\";\n\n/** Clears the soft-delete marker so a matched entity is updated instead of recreated. */\nexport function resurrectIfSoftDeleted(entity: Entity): void {\n  const deletedAt = getBaseMeta(getMetadata(entity)).timestampFields?.deletedAt;\n  if (deletedAt && (entity as any).isSoftDeletedEntity) {\n    setField(entity, deletedAt, undefined);\n  }\n}\n\n/**\n * Finds an existing entity when the input fully covers one configured `uniqueBy` candidate.\n * I.e. with `uniqueBy = [[\"email\"], [\"author\", \"title\"]]`, `{ email }` or `{ authorId, title }` can lookup an existing row.\n */\nexport async function findExistingIfUniqueBy<T extends Entity>(\n  em: EntityManager<any, any, any>,\n  constructor: MaybeAbstractEntityConstructor<T>,\n  input: object,\n): Promise<T | undefined> {\n  const meta = getMetadata(constructor);\n  const candidates = getUniqueByCandidates(meta, input);\n  for (const where of candidates) {\n    const inMemory = onlySoftDeleted(em.filterEntities(constructor as any, where as any) as T[]);\n    if (inMemory.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (inMemory.length === 1) {\n      resurrectIfSoftDeleted(inMemory[0]);\n      return inMemory[0];\n    }\n\n    // I.e. `{ publisher: newPublisherEntity }` cannot already exist in the database, so skip the `em.find`.\n    const hasNewEntityParam = Object.values(where).some((value) => isEntity(value) && value.isNewEntity);\n    if (hasNewEntityParam) continue;\n\n    const entities = onlySoftDeleted(await (em as any).find(constructor, where, { softDeletes: \"include\" })) as T[];\n    if (entities.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (entities.length === 1) {\n      resurrectIfSoftDeleted(entities[0]);\n      return entities[0];\n    }\n  }\n  return undefined;\n}\n\n/** Returns soft-deleted entities that are safe for upsert to resurrect. */\nfunction onlySoftDeleted<T extends Entity>(entities: T[]): T[] {\n  return entities.filter(\n    (entity) => !entity.isDeletedEntity && (entity as T & { isSoftDeletedEntity?: boolean }).isSoftDeletedEntity,\n  );\n}\n\n/** Builds pushdown-safe where clauses from configured identity fields. */\nfunction getUniqueByCandidates(meta: EntityMetadata, input: object): object[] {\n  return (meta.uniqueBy ?? getBaseMeta(meta).uniqueBy ?? []).flatMap((fields) => {\n    const where: Record<string, unknown> = {};\n    for (const fieldName of fields) {\n      const field = meta.allFields[fieldName];\n      if (!field || !isQueryableIdentityField(field)) return [];\n      const value = getIdentityValue(field, input);\n      if (value === undefined || value === null) return [];\n      where[field.fieldName] = value;\n    }\n    return [where];\n  });\n}\n\n/** Returns the identity value from the input. */\nfunction getIdentityValue(field: Field, input: object): unknown {\n  if (Object.hasOwn(input, field.fieldName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldName]);\n  }\n  if (field.fieldIdName && Object.hasOwn(input, field.fieldIdName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldIdName]);\n  }\n  return undefined;\n}\n\n/** Returns raw ids from relation inputs, i.e. `{ publisher: { id: \"p:1\" } }` becomes `{ publisher: \"p:1\" }`. */\nfunction normalizeIdentityValue(value: unknown): unknown {\n  if (!isEntity(value) && value && typeof value === \"object\" && Object.hasOwn(value, \"id\")) {\n    return (value as { id?: unknown }).id;\n  }\n  return value;\n}\n\n/** Returns true if Joist can push this identity field into a flat find clause. */\nfunction isQueryableIdentityField(field: Field): boolean {\n  return field.kind === \"primitive\" || field.kind === \"enum\" || field.kind === \"m2o\" || field.kind === \"poly\";\n}\n\nfunction whereAsString(where: object): string {\n  return Object.entries(where)\n    .map(([key, value]) => `${key}=${value}`)\n    .join(\", \");\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,uBAAuB,QAAsB;CAC3D,MAAM,YAAYA,uBAAAA,YAAYC,uBAAAA,YAAY,MAAM,CAAC,CAAC,CAAC,iBAAiB;CACpE,IAAI,aAAc,OAAe,qBAC/B,eAAA,SAAS,QAAQ,WAAW,KAAA,CAAS;AAEzC;;;;;AAMA,eAAsB,uBACpB,IACA,aACA,OACwB;CACxB,MAAM,OAAOA,uBAAAA,YAAY,WAAW;CACpC,MAAM,aAAa,sBAAsB,MAAM,KAAK;CACpD,KAAK,MAAM,SAAS,YAAY;EAC9B,MAAM,WAAW,gBAAgB,GAAG,eAAe,aAAoB,KAAY,CAAQ;EAC3F,IAAI,SAAS,SAAS,GACpB,MAAM,IAAIC,sBAAAA,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;EAIA,IAD0B,OAAO,OAAO,KAAK,CAAC,CAAC,MAAM,UAAUC,eAAAA,SAAS,KAAK,KAAK,MAAM,WACpE,GAAG;EAEvB,MAAM,WAAW,gBAAgB,MAAO,GAAW,KAAK,aAAa,OAAO,EAAE,aAAa,UAAU,CAAC,CAAC;EACvG,IAAI,SAAS,SAAS,GACpB,MAAM,IAAID,sBAAAA,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;CACF;AAEF;;AAGA,SAAS,gBAAkC,UAAoB;CAC7D,OAAO,SAAS,QACb,WAAW,CAAC,OAAO,mBAAoB,OAAiD,mBAC3F;AACF;;AAGA,SAAS,sBAAsB,MAAsB,OAAyB;CAC5E,QAAQ,KAAK,YAAYF,uBAAAA,YAAY,IAAI,CAAC,CAAC,YAAY,CAAC,EAAA,CAAG,SAAS,WAAW;EAC7E,MAAM,QAAiC,CAAC;EACxC,KAAK,MAAM,aAAa,QAAQ;GAC9B,MAAM,QAAQ,KAAK,UAAU;GAC7B,IAAI,CAAC,SAAS,CAAC,yBAAyB,KAAK,GAAG,OAAO,CAAC;GACxD,MAAM,QAAQ,iBAAiB,OAAO,KAAK;GAC3C,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,OAAO,CAAC;GACnD,MAAM,MAAM,aAAa;EAC3B;EACA,OAAO,CAAC,KAAK;CACf,CAAC;AACH;;AAGA,SAAS,iBAAiB,OAAc,OAAwB;CAC9D,IAAI,OAAO,OAAO,OAAO,MAAM,SAAS,GACtC,OAAO,uBAAwB,MAAkC,MAAM,UAAU;CAEnF,IAAI,MAAM,eAAe,OAAO,OAAO,OAAO,MAAM,WAAW,GAC7D,OAAO,uBAAwB,MAAkC,MAAM,YAAY;AAGvF;;AAGA,SAAS,uBAAuB,OAAyB;CACvD,IAAI,CAACG,eAAAA,SAAS,KAAK,KAAK,SAAS,OAAO,UAAU,YAAY,OAAO,OAAO,OAAO,IAAI,GACrF,OAAQ,MAA2B;CAErC,OAAO;AACT;;AAGA,SAAS,yBAAyB,OAAuB;CACvD,OAAO,MAAM,SAAS,eAAe,MAAM,SAAS,UAAU,MAAM,SAAS,SAAS,MAAM,SAAS;AACvG;AAEA,SAAS,cAAc,OAAuB;CAC5C,OAAO,OAAO,QAAQ,KAAK,CAAC,CACzB,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,CACxC,KAAK,IAAI;AACd"}
+{"version":3,"file":"resurrection.cjs","names":["getBaseMeta","getMetadata","TooManyError","isEntity"],"sources":["../src/resurrection.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type EntityManager, type MaybeAbstractEntityConstructor, TooManyError } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, type Field, getBaseMeta, getMetadata } from \"src/EntityMetadata.ts\";\nimport { setField } from \"src/fields.ts\";\n\n/** Clears the soft-delete marker so a matched entity is updated instead of recreated. */\nexport function resurrectIfSoftDeleted(entity: Entity): void {\n  const deletedAt = getBaseMeta(getMetadata(entity)).timestampFields?.deletedAt;\n  if (deletedAt && (entity as any).isSoftDeletedEntity) {\n    setField(entity, deletedAt, undefined);\n  }\n}\n\n/**\n * Finds an existing entity when the input fully covers one configured `uniqueBy` candidate.\n * I.e. with `uniqueBy = [[\"email\"], [\"author\", \"title\"]]`, `{ email }` or `{ authorId, title }` can lookup an existing row.\n */\nexport async function findExistingIfUniqueBy<T extends Entity>(\n  em: EntityManager<any, any, any>,\n  constructor: MaybeAbstractEntityConstructor<T>,\n  input: object,\n): Promise<T | undefined> {\n  const meta = getMetadata(constructor);\n  const candidates = getUniqueByCandidates(meta, input);\n  for (const where of candidates) {\n    const inMemory = onlySoftDeleted(em.filterEntities(constructor as any, where as any) as T[]);\n    if (inMemory.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (inMemory.length === 1) {\n      resurrectIfSoftDeleted(inMemory[0]);\n      return inMemory[0];\n    }\n\n    // I.e. `{ publisher: newPublisherEntity }` cannot already exist in the database, so skip the `em.find`.\n    const hasNewEntityParam = Object.values(where).some((value) => isEntity(value) && value.isNewEntity);\n    if (hasNewEntityParam) continue;\n\n    const entities = onlySoftDeleted(\n      await (em as any).find(constructor, newWhereEqual(meta, where), { softDeletes: \"include\" }),\n    ) as T[];\n    if (entities.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (entities.length === 1) {\n      resurrectIfSoftDeleted(entities[0]);\n      return entities[0];\n    }\n  }\n  return undefined;\n}\n\n/** Returns soft-deleted entities that are safe for upsert to resurrect. */\nfunction onlySoftDeleted<T extends Entity>(entities: T[]): T[] {\n  return entities.filter(\n    (entity) => !entity.isDeletedEntity && (entity as T & { isSoftDeletedEntity?: boolean }).isSoftDeletedEntity,\n  );\n}\n\n/** Builds pushdown-safe where clauses from configured identity fields. */\nfunction getUniqueByCandidates(meta: EntityMetadata, input: object): object[] {\n  return (meta.uniqueBy ?? getBaseMeta(meta).uniqueBy ?? []).flatMap((fields) => {\n    const where: Record<string, unknown> = {};\n    for (const fieldName of fields) {\n      const field = meta.allFields[fieldName];\n      if (!field || !isQueryableIdentityField(field)) return [];\n      const value = getIdentityValue(field, input);\n      if (value === undefined || value === null) return [];\n      where[field.fieldName] = value;\n    }\n    return [where];\n  });\n}\n\n/** Returns the identity value from the input. */\nfunction getIdentityValue(field: Field, input: object): unknown {\n  if (Object.hasOwn(input, field.fieldName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldName]);\n  }\n  if (field.fieldIdName && Object.hasOwn(input, field.fieldIdName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldIdName]);\n  }\n  return undefined;\n}\n\n/** Returns raw ids from relation inputs, i.e. `{ publisher: { id: \"p:1\" } }` becomes `{ publisher: \"p:1\" }`. */\nfunction normalizeIdentityValue(value: unknown): unknown {\n  if (!isEntity(value) && value && typeof value === \"object\" && Object.hasOwn(value, \"id\")) {\n    return (value as { id?: unknown }).id;\n  }\n  return value;\n}\n\n/** Returns true if Joist can push this identity field into a flat find clause. */\nfunction isQueryableIdentityField(field: Field): boolean {\n  return field.kind === \"primitive\" || field.kind === \"enum\" || field.kind === \"m2o\" || field.kind === \"poly\";\n}\n\nfunction whereAsString(where: object): string {\n  return Object.entries(where)\n    .map(([key, value]) => `${key}=${value}`)\n    .join(\", \");\n}\n\n/** Builds exact identity filters for primitives and relations. */\nexport function newWhereEqual(meta: EntityMetadata, input: object): object {\n  const where: Record<string, unknown> = {};\n\n  // Arrays need eq for exact equality; relations must stay as-is because eq would be a nested entity filter.\n  // Unset values must match SQL NULL, e.g. publisher: undefined must not omit the publisher filter.\n  for (const name of Object.keys(input)) {\n    const value = (input as Record<string, unknown>)[name] ?? null;\n    where[name] = meta.allFields[name]?.kind === \"primitive\" ? { eq: value } : value;\n  }\n\n  return where;\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,uBAAuB,QAAsB;CAC3D,MAAM,YAAYA,uBAAAA,YAAYC,uBAAAA,YAAY,MAAM,CAAC,CAAC,CAAC,iBAAiB;CACpE,IAAI,aAAc,OAAe,qBAC/B,eAAA,SAAS,QAAQ,WAAW,KAAA,CAAS;AAEzC;;;;;AAMA,eAAsB,uBACpB,IACA,aACA,OACwB;CACxB,MAAM,OAAOA,uBAAAA,YAAY,WAAW;CACpC,MAAM,aAAa,sBAAsB,MAAM,KAAK;CACpD,KAAK,MAAM,SAAS,YAAY;EAC9B,MAAM,WAAW,gBAAgB,GAAG,eAAe,aAAoB,KAAY,CAAQ;EAC3F,IAAI,SAAS,SAAS,GACpB,MAAM,IAAIC,sBAAAA,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;EAIA,IAD0B,OAAO,OAAO,KAAK,CAAC,CAAC,MAAM,UAAUC,eAAAA,SAAS,KAAK,KAAK,MAAM,WACpE,GAAG;EAEvB,MAAM,WAAW,gBACf,MAAO,GAAW,KAAK,aAAa,cAAc,MAAM,KAAK,GAAG,EAAE,aAAa,UAAU,CAAC,CAC5F;EACA,IAAI,SAAS,SAAS,GACpB,MAAM,IAAID,sBAAAA,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;CACF;AAEF;;AAGA,SAAS,gBAAkC,UAAoB;CAC7D,OAAO,SAAS,QACb,WAAW,CAAC,OAAO,mBAAoB,OAAiD,mBAC3F;AACF;;AAGA,SAAS,sBAAsB,MAAsB,OAAyB;CAC5E,QAAQ,KAAK,YAAYF,uBAAAA,YAAY,IAAI,CAAC,CAAC,YAAY,CAAC,EAAA,CAAG,SAAS,WAAW;EAC7E,MAAM,QAAiC,CAAC;EACxC,KAAK,MAAM,aAAa,QAAQ;GAC9B,MAAM,QAAQ,KAAK,UAAU;GAC7B,IAAI,CAAC,SAAS,CAAC,yBAAyB,KAAK,GAAG,OAAO,CAAC;GACxD,MAAM,QAAQ,iBAAiB,OAAO,KAAK;GAC3C,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,OAAO,CAAC;GACnD,MAAM,MAAM,aAAa;EAC3B;EACA,OAAO,CAAC,KAAK;CACf,CAAC;AACH;;AAGA,SAAS,iBAAiB,OAAc,OAAwB;CAC9D,IAAI,OAAO,OAAO,OAAO,MAAM,SAAS,GACtC,OAAO,uBAAwB,MAAkC,MAAM,UAAU;CAEnF,IAAI,MAAM,eAAe,OAAO,OAAO,OAAO,MAAM,WAAW,GAC7D,OAAO,uBAAwB,MAAkC,MAAM,YAAY;AAGvF;;AAGA,SAAS,uBAAuB,OAAyB;CACvD,IAAI,CAACG,eAAAA,SAAS,KAAK,KAAK,SAAS,OAAO,UAAU,YAAY,OAAO,OAAO,OAAO,IAAI,GACrF,OAAQ,MAA2B;CAErC,OAAO;AACT;;AAGA,SAAS,yBAAyB,OAAuB;CACvD,OAAO,MAAM,SAAS,eAAe,MAAM,SAAS,UAAU,MAAM,SAAS,SAAS,MAAM,SAAS;AACvG;AAEA,SAAS,cAAc,OAAuB;CAC5C,OAAO,OAAO,QAAQ,KAAK,CAAC,CACzB,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,CACxC,KAAK,IAAI;AACd;;AAGA,SAAgB,cAAc,MAAsB,OAAuB;CACzE,MAAM,QAAiC,CAAC;CAIxC,KAAK,MAAM,QAAQ,OAAO,KAAK,KAAK,GAAG;EACrC,MAAM,QAAS,MAAkC,SAAS;EAC1D,MAAM,QAAQ,KAAK,UAAU,KAAK,EAAE,SAAS,cAAc,EAAE,IAAI,MAAM,IAAI;CAC7E;CAEA,OAAO;AACT"}

package/build/resurrection.d.cts

@@ -1,3 +1,4 @@
+import { EntityMetadata } from "./EntityMetadata.cjs";
 import { EntityManager, MaybeAbstractEntityConstructor } from "./EntityManager.cjs";
 import { Entity } from "./Entity.cjs";
 //#region src/resurrection.d.ts
@@ -8,6 +9,8 @@ declare function resurrectIfSoftDeleted(entity: Entity): void;
  * I.e. with `uniqueBy = [["email"], ["author", "title"]]`, `{ email }` or `{ authorId, title }` can lookup an existing row.
  */
 declare function findExistingIfUniqueBy<T extends Entity>(em: EntityManager<any, any, any>, constructor: MaybeAbstractEntityConstructor<T>, input: object): Promise<T | undefined>;
+/** Builds exact identity filters for primitives and relations. */
+declare function newWhereEqual(meta: EntityMetadata, input: object): object;
 //#endregion
-export { findExistingIfUniqueBy, resurrectIfSoftDeleted };
+export { findExistingIfUniqueBy, newWhereEqual, resurrectIfSoftDeleted };
 //# sourceMappingURL=resurrection.d.cts.map

package/build/resurrection.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"resurrection.d.cts","names":[],"sources":["../src/resurrection.ts"],"mappings":";;;;iBAMgB,uBAAuB,QAAQ;;;;;iBAWzB,uBAAuB,UAAU,QACrD,IAAI,8BACJ,aAAa,+BAA+B,IAC5C,gBACC,QAAQ"}
+{"version":3,"file":"resurrection.d.cts","names":[],"sources":["../src/resurrection.ts"],"mappings":";;;;;iBAMgB,uBAAuB,QAAQ;;;;;iBAWzB,uBAAuB,UAAU,QACrD,IAAI,8BACJ,aAAa,+BAA+B,IAC5C,gBACC,QAAQ;;iBAkFK,cAAc,MAAM,gBAAgB"}

package/build/resurrection.d.mts

@@ -1,3 +1,4 @@
+import { EntityMetadata } from "./EntityMetadata.mjs";
 import { EntityManager, MaybeAbstractEntityConstructor } from "./EntityManager.mjs";
 import { Entity } from "./Entity.mjs";
 //#region src/resurrection.d.ts
@@ -8,6 +9,8 @@ declare function resurrectIfSoftDeleted(entity: Entity): void;
  * I.e. with `uniqueBy = [["email"], ["author", "title"]]`, `{ email }` or `{ authorId, title }` can lookup an existing row.
  */
 declare function findExistingIfUniqueBy<T extends Entity>(em: EntityManager<any, any, any>, constructor: MaybeAbstractEntityConstructor<T>, input: object): Promise<T | undefined>;
+/** Builds exact identity filters for primitives and relations. */
+declare function newWhereEqual(meta: EntityMetadata, input: object): object;
 //#endregion
-export { findExistingIfUniqueBy, resurrectIfSoftDeleted };
+export { findExistingIfUniqueBy, newWhereEqual, resurrectIfSoftDeleted };
 //# sourceMappingURL=resurrection.d.mts.map

package/build/resurrection.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"resurrection.d.mts","names":[],"sources":["../src/resurrection.ts"],"mappings":";;;;iBAMgB,uBAAuB,QAAQ;;;;;iBAWzB,uBAAuB,UAAU,QACrD,IAAI,8BACJ,aAAa,+BAA+B,IAC5C,gBACC,QAAQ"}
+{"version":3,"file":"resurrection.d.mts","names":[],"sources":["../src/resurrection.ts"],"mappings":";;;;;iBAMgB,uBAAuB,QAAQ;;;;;iBAWzB,uBAAuB,UAAU,QACrD,IAAI,8BACJ,aAAa,+BAA+B,IAC5C,gBACC,QAAQ;;iBAkFK,cAAc,MAAM,gBAAgB"}

package/build/resurrection.js

@@ -23,7 +23,7 @@ async function findExistingIfUniqueBy(em, constructor, input) {
 			return inMemory[0];
 		}
 		if (Object.values(where).some((value) => isEntity(value) && value.isNewEntity)) continue;
-		const entities = onlySoftDeleted(await em.find(constructor, where, { softDeletes: "include" }));
+		const entities = onlySoftDeleted(await em.find(constructor, newWhereEqual(meta, where), { softDeletes: "include" }));
 		if (entities.length > 1) throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);
 		else if (entities.length === 1) {
 			resurrectIfSoftDeleted(entities[0]);
@@ -66,7 +66,16 @@ function isQueryableIdentityField(field) {
 function whereAsString(where) {
 	return Object.entries(where).map(([key, value]) => `${key}=${value}`).join(", ");
 }
+/** Builds exact identity filters for primitives and relations. */
+function newWhereEqual(meta, input) {
+	const where = {};
+	for (const name of Object.keys(input)) {
+		const value = input[name] ?? null;
+		where[name] = meta.allFields[name]?.kind === "primitive" ? { eq: value } : value;
+	}
+	return where;
+}
 //#endregion
-export { findExistingIfUniqueBy, resurrectIfSoftDeleted };
+export { findExistingIfUniqueBy, newWhereEqual, resurrectIfSoftDeleted };
 
 //# sourceMappingURL=resurrection.js.map

package/build/resurrection.js.map

@@ -1 +1 @@
-{"version":3,"file":"resurrection.js","names":[],"sources":["../src/resurrection.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type EntityManager, type MaybeAbstractEntityConstructor, TooManyError } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, type Field, getBaseMeta, getMetadata } from \"src/EntityMetadata.ts\";\nimport { setField } from \"src/fields.ts\";\n\n/** Clears the soft-delete marker so a matched entity is updated instead of recreated. */\nexport function resurrectIfSoftDeleted(entity: Entity): void {\n  const deletedAt = getBaseMeta(getMetadata(entity)).timestampFields?.deletedAt;\n  if (deletedAt && (entity as any).isSoftDeletedEntity) {\n    setField(entity, deletedAt, undefined);\n  }\n}\n\n/**\n * Finds an existing entity when the input fully covers one configured `uniqueBy` candidate.\n * I.e. with `uniqueBy = [[\"email\"], [\"author\", \"title\"]]`, `{ email }` or `{ authorId, title }` can lookup an existing row.\n */\nexport async function findExistingIfUniqueBy<T extends Entity>(\n  em: EntityManager<any, any, any>,\n  constructor: MaybeAbstractEntityConstructor<T>,\n  input: object,\n): Promise<T | undefined> {\n  const meta = getMetadata(constructor);\n  const candidates = getUniqueByCandidates(meta, input);\n  for (const where of candidates) {\n    const inMemory = onlySoftDeleted(em.filterEntities(constructor as any, where as any) as T[]);\n    if (inMemory.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (inMemory.length === 1) {\n      resurrectIfSoftDeleted(inMemory[0]);\n      return inMemory[0];\n    }\n\n    // I.e. `{ publisher: newPublisherEntity }` cannot already exist in the database, so skip the `em.find`.\n    const hasNewEntityParam = Object.values(where).some((value) => isEntity(value) && value.isNewEntity);\n    if (hasNewEntityParam) continue;\n\n    const entities = onlySoftDeleted(await (em as any).find(constructor, where, { softDeletes: \"include\" })) as T[];\n    if (entities.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (entities.length === 1) {\n      resurrectIfSoftDeleted(entities[0]);\n      return entities[0];\n    }\n  }\n  return undefined;\n}\n\n/** Returns soft-deleted entities that are safe for upsert to resurrect. */\nfunction onlySoftDeleted<T extends Entity>(entities: T[]): T[] {\n  return entities.filter(\n    (entity) => !entity.isDeletedEntity && (entity as T & { isSoftDeletedEntity?: boolean }).isSoftDeletedEntity,\n  );\n}\n\n/** Builds pushdown-safe where clauses from configured identity fields. */\nfunction getUniqueByCandidates(meta: EntityMetadata, input: object): object[] {\n  return (meta.uniqueBy ?? getBaseMeta(meta).uniqueBy ?? []).flatMap((fields) => {\n    const where: Record<string, unknown> = {};\n    for (const fieldName of fields) {\n      const field = meta.allFields[fieldName];\n      if (!field || !isQueryableIdentityField(field)) return [];\n      const value = getIdentityValue(field, input);\n      if (value === undefined || value === null) return [];\n      where[field.fieldName] = value;\n    }\n    return [where];\n  });\n}\n\n/** Returns the identity value from the input. */\nfunction getIdentityValue(field: Field, input: object): unknown {\n  if (Object.hasOwn(input, field.fieldName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldName]);\n  }\n  if (field.fieldIdName && Object.hasOwn(input, field.fieldIdName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldIdName]);\n  }\n  return undefined;\n}\n\n/** Returns raw ids from relation inputs, i.e. `{ publisher: { id: \"p:1\" } }` becomes `{ publisher: \"p:1\" }`. */\nfunction normalizeIdentityValue(value: unknown): unknown {\n  if (!isEntity(value) && value && typeof value === \"object\" && Object.hasOwn(value, \"id\")) {\n    return (value as { id?: unknown }).id;\n  }\n  return value;\n}\n\n/** Returns true if Joist can push this identity field into a flat find clause. */\nfunction isQueryableIdentityField(field: Field): boolean {\n  return field.kind === \"primitive\" || field.kind === \"enum\" || field.kind === \"m2o\" || field.kind === \"poly\";\n}\n\nfunction whereAsString(where: object): string {\n  return Object.entries(where)\n    .map(([key, value]) => `${key}=${value}`)\n    .join(\", \");\n}\n"],"mappings":";;;;;;AAMA,SAAgB,uBAAuB,QAAsB;CAC3D,MAAM,YAAY,YAAY,YAAY,MAAM,CAAC,CAAC,CAAC,iBAAiB;CACpE,IAAI,aAAc,OAAe,qBAC/B,SAAS,QAAQ,WAAW,KAAA,CAAS;AAEzC;;;;;AAMA,eAAsB,uBACpB,IACA,aACA,OACwB;CACxB,MAAM,OAAO,YAAY,WAAW;CACpC,MAAM,aAAa,sBAAsB,MAAM,KAAK;CACpD,KAAK,MAAM,SAAS,YAAY;EAC9B,MAAM,WAAW,gBAAgB,GAAG,eAAe,aAAoB,KAAY,CAAQ;EAC3F,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;EAIA,IAD0B,OAAO,OAAO,KAAK,CAAC,CAAC,MAAM,UAAU,SAAS,KAAK,KAAK,MAAM,WACpE,GAAG;EAEvB,MAAM,WAAW,gBAAgB,MAAO,GAAW,KAAK,aAAa,OAAO,EAAE,aAAa,UAAU,CAAC,CAAC;EACvG,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;CACF;AAEF;;AAGA,SAAS,gBAAkC,UAAoB;CAC7D,OAAO,SAAS,QACb,WAAW,CAAC,OAAO,mBAAoB,OAAiD,mBAC3F;AACF;;AAGA,SAAS,sBAAsB,MAAsB,OAAyB;CAC5E,QAAQ,KAAK,YAAY,YAAY,IAAI,CAAC,CAAC,YAAY,CAAC,EAAA,CAAG,SAAS,WAAW;EAC7E,MAAM,QAAiC,CAAC;EACxC,KAAK,MAAM,aAAa,QAAQ;GAC9B,MAAM,QAAQ,KAAK,UAAU;GAC7B,IAAI,CAAC,SAAS,CAAC,yBAAyB,KAAK,GAAG,OAAO,CAAC;GACxD,MAAM,QAAQ,iBAAiB,OAAO,KAAK;GAC3C,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,OAAO,CAAC;GACnD,MAAM,MAAM,aAAa;EAC3B;EACA,OAAO,CAAC,KAAK;CACf,CAAC;AACH;;AAGA,SAAS,iBAAiB,OAAc,OAAwB;CAC9D,IAAI,OAAO,OAAO,OAAO,MAAM,SAAS,GACtC,OAAO,uBAAwB,MAAkC,MAAM,UAAU;CAEnF,IAAI,MAAM,eAAe,OAAO,OAAO,OAAO,MAAM,WAAW,GAC7D,OAAO,uBAAwB,MAAkC,MAAM,YAAY;AAGvF;;AAGA,SAAS,uBAAuB,OAAyB;CACvD,IAAI,CAAC,SAAS,KAAK,KAAK,SAAS,OAAO,UAAU,YAAY,OAAO,OAAO,OAAO,IAAI,GACrF,OAAQ,MAA2B;CAErC,OAAO;AACT;;AAGA,SAAS,yBAAyB,OAAuB;CACvD,OAAO,MAAM,SAAS,eAAe,MAAM,SAAS,UAAU,MAAM,SAAS,SAAS,MAAM,SAAS;AACvG;AAEA,SAAS,cAAc,OAAuB;CAC5C,OAAO,OAAO,QAAQ,KAAK,CAAC,CACzB,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,CACxC,KAAK,IAAI;AACd"}
+{"version":3,"file":"resurrection.js","names":[],"sources":["../src/resurrection.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type EntityManager, type MaybeAbstractEntityConstructor, TooManyError } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, type Field, getBaseMeta, getMetadata } from \"src/EntityMetadata.ts\";\nimport { setField } from \"src/fields.ts\";\n\n/** Clears the soft-delete marker so a matched entity is updated instead of recreated. */\nexport function resurrectIfSoftDeleted(entity: Entity): void {\n  const deletedAt = getBaseMeta(getMetadata(entity)).timestampFields?.deletedAt;\n  if (deletedAt && (entity as any).isSoftDeletedEntity) {\n    setField(entity, deletedAt, undefined);\n  }\n}\n\n/**\n * Finds an existing entity when the input fully covers one configured `uniqueBy` candidate.\n * I.e. with `uniqueBy = [[\"email\"], [\"author\", \"title\"]]`, `{ email }` or `{ authorId, title }` can lookup an existing row.\n */\nexport async function findExistingIfUniqueBy<T extends Entity>(\n  em: EntityManager<any, any, any>,\n  constructor: MaybeAbstractEntityConstructor<T>,\n  input: object,\n): Promise<T | undefined> {\n  const meta = getMetadata(constructor);\n  const candidates = getUniqueByCandidates(meta, input);\n  for (const where of candidates) {\n    const inMemory = onlySoftDeleted(em.filterEntities(constructor as any, where as any) as T[]);\n    if (inMemory.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (inMemory.length === 1) {\n      resurrectIfSoftDeleted(inMemory[0]);\n      return inMemory[0];\n    }\n\n    // I.e. `{ publisher: newPublisherEntity }` cannot already exist in the database, so skip the `em.find`.\n    const hasNewEntityParam = Object.values(where).some((value) => isEntity(value) && value.isNewEntity);\n    if (hasNewEntityParam) continue;\n\n    const entities = onlySoftDeleted(\n      await (em as any).find(constructor, newWhereEqual(meta, where), { softDeletes: \"include\" }),\n    ) as T[];\n    if (entities.length > 1) {\n      throw new TooManyError(`Found more than one existing ${meta.type} with ${whereAsString(where)}`);\n    } else if (entities.length === 1) {\n      resurrectIfSoftDeleted(entities[0]);\n      return entities[0];\n    }\n  }\n  return undefined;\n}\n\n/** Returns soft-deleted entities that are safe for upsert to resurrect. */\nfunction onlySoftDeleted<T extends Entity>(entities: T[]): T[] {\n  return entities.filter(\n    (entity) => !entity.isDeletedEntity && (entity as T & { isSoftDeletedEntity?: boolean }).isSoftDeletedEntity,\n  );\n}\n\n/** Builds pushdown-safe where clauses from configured identity fields. */\nfunction getUniqueByCandidates(meta: EntityMetadata, input: object): object[] {\n  return (meta.uniqueBy ?? getBaseMeta(meta).uniqueBy ?? []).flatMap((fields) => {\n    const where: Record<string, unknown> = {};\n    for (const fieldName of fields) {\n      const field = meta.allFields[fieldName];\n      if (!field || !isQueryableIdentityField(field)) return [];\n      const value = getIdentityValue(field, input);\n      if (value === undefined || value === null) return [];\n      where[field.fieldName] = value;\n    }\n    return [where];\n  });\n}\n\n/** Returns the identity value from the input. */\nfunction getIdentityValue(field: Field, input: object): unknown {\n  if (Object.hasOwn(input, field.fieldName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldName]);\n  }\n  if (field.fieldIdName && Object.hasOwn(input, field.fieldIdName)) {\n    return normalizeIdentityValue((input as Record<string, unknown>)[field.fieldIdName]);\n  }\n  return undefined;\n}\n\n/** Returns raw ids from relation inputs, i.e. `{ publisher: { id: \"p:1\" } }` becomes `{ publisher: \"p:1\" }`. */\nfunction normalizeIdentityValue(value: unknown): unknown {\n  if (!isEntity(value) && value && typeof value === \"object\" && Object.hasOwn(value, \"id\")) {\n    return (value as { id?: unknown }).id;\n  }\n  return value;\n}\n\n/** Returns true if Joist can push this identity field into a flat find clause. */\nfunction isQueryableIdentityField(field: Field): boolean {\n  return field.kind === \"primitive\" || field.kind === \"enum\" || field.kind === \"m2o\" || field.kind === \"poly\";\n}\n\nfunction whereAsString(where: object): string {\n  return Object.entries(where)\n    .map(([key, value]) => `${key}=${value}`)\n    .join(\", \");\n}\n\n/** Builds exact identity filters for primitives and relations. */\nexport function newWhereEqual(meta: EntityMetadata, input: object): object {\n  const where: Record<string, unknown> = {};\n\n  // Arrays need eq for exact equality; relations must stay as-is because eq would be a nested entity filter.\n  // Unset values must match SQL NULL, e.g. publisher: undefined must not omit the publisher filter.\n  for (const name of Object.keys(input)) {\n    const value = (input as Record<string, unknown>)[name] ?? null;\n    where[name] = meta.allFields[name]?.kind === \"primitive\" ? { eq: value } : value;\n  }\n\n  return where;\n}\n"],"mappings":";;;;;;AAMA,SAAgB,uBAAuB,QAAsB;CAC3D,MAAM,YAAY,YAAY,YAAY,MAAM,CAAC,CAAC,CAAC,iBAAiB;CACpE,IAAI,aAAc,OAAe,qBAC/B,SAAS,QAAQ,WAAW,KAAA,CAAS;AAEzC;;;;;AAMA,eAAsB,uBACpB,IACA,aACA,OACwB;CACxB,MAAM,OAAO,YAAY,WAAW;CACpC,MAAM,aAAa,sBAAsB,MAAM,KAAK;CACpD,KAAK,MAAM,SAAS,YAAY;EAC9B,MAAM,WAAW,gBAAgB,GAAG,eAAe,aAAoB,KAAY,CAAQ;EAC3F,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;EAIA,IAD0B,OAAO,OAAO,KAAK,CAAC,CAAC,MAAM,UAAU,SAAS,KAAK,KAAK,MAAM,WACpE,GAAG;EAEvB,MAAM,WAAW,gBACf,MAAO,GAAW,KAAK,aAAa,cAAc,MAAM,KAAK,GAAG,EAAE,aAAa,UAAU,CAAC,CAC5F;EACA,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,aAAa,gCAAgC,KAAK,KAAK,QAAQ,cAAc,KAAK,GAAG;OAC1F,IAAI,SAAS,WAAW,GAAG;GAChC,uBAAuB,SAAS,EAAE;GAClC,OAAO,SAAS;EAClB;CACF;AAEF;;AAGA,SAAS,gBAAkC,UAAoB;CAC7D,OAAO,SAAS,QACb,WAAW,CAAC,OAAO,mBAAoB,OAAiD,mBAC3F;AACF;;AAGA,SAAS,sBAAsB,MAAsB,OAAyB;CAC5E,QAAQ,KAAK,YAAY,YAAY,IAAI,CAAC,CAAC,YAAY,CAAC,EAAA,CAAG,SAAS,WAAW;EAC7E,MAAM,QAAiC,CAAC;EACxC,KAAK,MAAM,aAAa,QAAQ;GAC9B,MAAM,QAAQ,KAAK,UAAU;GAC7B,IAAI,CAAC,SAAS,CAAC,yBAAyB,KAAK,GAAG,OAAO,CAAC;GACxD,MAAM,QAAQ,iBAAiB,OAAO,KAAK;GAC3C,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,OAAO,CAAC;GACnD,MAAM,MAAM,aAAa;EAC3B;EACA,OAAO,CAAC,KAAK;CACf,CAAC;AACH;;AAGA,SAAS,iBAAiB,OAAc,OAAwB;CAC9D,IAAI,OAAO,OAAO,OAAO,MAAM,SAAS,GACtC,OAAO,uBAAwB,MAAkC,MAAM,UAAU;CAEnF,IAAI,MAAM,eAAe,OAAO,OAAO,OAAO,MAAM,WAAW,GAC7D,OAAO,uBAAwB,MAAkC,MAAM,YAAY;AAGvF;;AAGA,SAAS,uBAAuB,OAAyB;CACvD,IAAI,CAAC,SAAS,KAAK,KAAK,SAAS,OAAO,UAAU,YAAY,OAAO,OAAO,OAAO,IAAI,GACrF,OAAQ,MAA2B;CAErC,OAAO;AACT;;AAGA,SAAS,yBAAyB,OAAuB;CACvD,OAAO,MAAM,SAAS,eAAe,MAAM,SAAS,UAAU,MAAM,SAAS,SAAS,MAAM,SAAS;AACvG;AAEA,SAAS,cAAc,OAAuB;CAC5C,OAAO,OAAO,QAAQ,KAAK,CAAC,CACzB,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,CACxC,KAAK,IAAI;AACd;;AAGA,SAAgB,cAAc,MAAsB,OAAuB;CACzE,MAAM,QAAiC,CAAC;CAIxC,KAAK,MAAM,QAAQ,OAAO,KAAK,KAAK,GAAG;EACrC,MAAM,QAAS,MAAkC,SAAS;EAC1D,MAAM,QAAQ,KAAK,UAAU,KAAK,EAAE,SAAS,cAAc,EAAE,IAAI,MAAM,IAAI;CAC7E;CAEA,OAAO;AACT"}

package/build/transitions.cjs

@@ -0,0 +1,89 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_utils = require("./utils.cjs");
+const require_EntityMetadata = require("./EntityMetadata.cjs");
+//#region src/transitions.ts
+/** The "from" state of a just-created entity, because `undefined` can be a real field value. */
+const created = Symbol("created");
+/** Converts an internal step to the `Transition` that guards and reactions receive. */
+function toTransition(step) {
+	return {
+		from: step.from === created ? void 0 : step.from,
+		to: step.to
+	};
+}
+/**
+* Merges the transition config of `meta` and its base types by field, converting accessors to codes.
+*
+* This runs after boot, because the config is written before the enum metadata exists.
+*/
+function buildFieldTransitions(meta) {
+	const byField = /* @__PURE__ */ new Map();
+	for (const m of require_EntityMetadata.getBaseAndSelfMetas(meta)) for (const [fieldName, config] of Object.entries(m.config.__data.transitions)) {
+		let merged = byField.get(fieldName);
+		if (!merged) byField.set(fieldName, merged = {
+			tables: [],
+			guards: [],
+			callbacks: []
+		});
+		if (config.table) merged.tables.push(toCodesTable(meta, fieldName, config.table));
+		for (const { match, run } of config.guards) merged.guards.push({
+			matcher: toMatcher(meta, fieldName, match),
+			run
+		});
+		for (const { name, match, run } of config.callbacks) {
+			const matcher = toMatcher(meta, fieldName, match);
+			merged.callbacks.push({
+				name,
+				phase: match.phase ?? "flush",
+				matcher,
+				run
+			});
+		}
+	}
+	return byField;
+}
+/** Returns whether `step` matches `matcher`'s `from`, `to`, and `onCreate` settings. */
+function matchesTransition(matcher, step) {
+	if (step.from === created) {
+		if (!matcher.onCreate) return false;
+	} else if (matcher.from && !matcher.from.includes(step.from)) return false;
+	return !matcher.to || matcher.to.includes(step.to);
+}
+/** Uses the enum's display name in error messages when there is one, i.e. `Approved` instead of `APPROVED`. */
+function describeValue(meta, fieldName, value) {
+	if (value === void 0) return "unset";
+	const field = meta.allFields[fieldName];
+	return field?.kind === "enum" ? field.enumDetailType.getByCode(value)?.name ?? String(value) : String(value);
+}
+/** Converts a `transitions` table's keys and values to codes, so it can be compared to field values. */
+function toCodesTable(meta, fieldName, table) {
+	return new Map(Object.entries(table).map(([from, tos]) => [accessorToCode(meta, fieldName, from), toCodes(meta, fieldName, tos ?? [])]));
+}
+/** Converts a `match`'s accessors to codes. */
+function toMatcher(meta, fieldName, match) {
+	return {
+		from: toCodes(meta, fieldName, match.from),
+		to: toCodes(meta, fieldName, match.to),
+		onCreate: match.onCreate !== false && match.from === void 0
+	};
+}
+/** Converts an enum accessor, i.e. `Rejected`, to its code, i.e. `REJECTED`, and fails on anything else. */
+function accessorToCode(meta, fieldName, value) {
+	const field = meta.allFields[fieldName];
+	if (field?.kind !== "enum") require_utils.fail(`${meta.type}.${fieldName} is not an enum field, so it can't have transitions`);
+	if (typeof value !== "string" || !Object.hasOwn(field.enumType, value)) require_utils.fail(`Unknown ${meta.type}.${fieldName} accessor ${String(value)}, i.e. use "Draft" for AuthorStatus.Draft`);
+	return field.enumType[value];
+}
+/** Converts one or more enum accessors to an array of codes, preserving an omitted match. */
+function toCodes(meta, fieldName, values) {
+	if (values === void 0) return void 0;
+	return typeof values === "string" ? [accessorToCode(meta, fieldName, values)] : values.map((v) => accessorToCode(meta, fieldName, v));
+}
+//#endregion
+exports.buildFieldTransitions = buildFieldTransitions;
+exports.created = created;
+exports.describeValue = describeValue;
+exports.matchesTransition = matchesTransition;
+exports.toTransition = toTransition;
+
+//# sourceMappingURL=transitions.cjs.map

package/build/transitions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.cjs","names":["getBaseAndSelfMetas"],"sources":["../src/transitions.ts"],"sourcesContent":["import type { Entity } from \"src/Entity.ts\";\nimport { type EntityMetadata, getBaseAndSelfMetas } from \"src/EntityMetadata.ts\";\nimport type { ValidationRuleResult } from \"src/rules.ts\";\nimport { type MaybePromise, fail } from \"src/utils.ts\";\n\n/**\n * Which state transitions of an enum field a `guardTransition` cares about.\n *\n * Omitting `from` or `to` matches any state. Guards never run on creation.\n */\nexport interface GuardTransitionMatch<V> {\n  from?: V | readonly V[];\n  to?: V | readonly V[];\n}\n\n/**\n * Which state transitions of an enum field an `onTransition` callback handles.\n *\n * Creating an entity with a matching `to` state also matches, unless `from` is set or `onCreate` is `false`.\n */\nexport interface OnTransitionMatch<V> extends GuardTransitionMatch<V> {\n  /**\n   * Whether `onTransition` fires when an entity is created with a matching `to` state, defaults to `true`.\n   *\n   * Entering a state by creation usually needs the same side effects as entering it by a transition, and\n   * forgetting them is easy to miss. Set `false` for reactions that only make sense for a transition.\n   */\n  onCreate?: boolean;\n  /** `commit` runs in `beforeCommit`, i.e. to enqueue jobs; `flush` (the default) runs as a reaction. */\n  phase?: \"flush\" | \"commit\";\n}\n\n/** Maps each state to the states it may transition to, i.e. `{ Draft: [\"Open\"], Open: [\"Closed\"] }`. */\nexport type TransitionTable<V extends PropertyKey> = Partial<Record<V, readonly V[]>>;\n\n/**\n * The transition a guard or reaction is handling, i.e. `{ from: \"DRAFT\", to: \"OPEN\" }`.\n *\n * Guards and callbacks run during reaction passes, after the assignment, so the entity may already be in a\n * later state. This tells them which transition they're handling. `from` is `undefined` for creation.\n */\nexport interface Transition<V> {\n  from: V | undefined;\n  to: V;\n}\n\n/** The \"from\" state of a just-created entity, because `undefined` can be a real field value. */\nexport const created: unique symbol = Symbol(\"created\");\n\n/** A single recorded transition of a field, with `from` as `created` for creation. */\nexport interface TransitionStep {\n  from: unknown;\n  to: unknown;\n}\n\n/** A `guardTransition` as registered in config, with its `match` still using accessors. */\nexport interface TransitionGuardConfig<T extends Entity = Entity> {\n  match: GuardTransitionMatch<string>;\n  run(entity: T, step: TransitionStep): MaybePromise<ValidationRuleResult>;\n}\n\n/** An `onTransition` as registered in config, with its `match` still using accessors. */\nexport interface TransitionCallbackConfig<T extends Entity = Entity, C = unknown> {\n  name: string;\n  match: OnTransitionMatch<string>;\n  run(entity: T, ctx: C, step: TransitionStep): MaybePromise<unknown>;\n}\n\n/** One field's `transitions`, `guardTransition`, and `onTransition` config on a single entity type. */\nexport interface FieldTransitionsConfig<T extends Entity = Entity, C = unknown> {\n  /** The `transitions` table, if any; subtypes add their own tables on their own configs. */\n  table?: TransitionTable<string>;\n  guards: TransitionGuardConfig<T>[];\n  callbacks: TransitionCallbackConfig<T, C>[];\n}\n\n/** A `match` with accessors converted to codes, so it can be compared to recorded steps. */\nexport interface TransitionMatcher {\n  /** The allowed previous states, or `undefined` for any state. */\n  from: readonly unknown[] | undefined;\n  /** The allowed new states, or `undefined` for any state. */\n  to: readonly unknown[] | undefined;\n  /** Whether creation matches, which is never true when `from` is set. */\n  onCreate: boolean;\n}\n\n/** A guard with its `match` converted to codes. */\nexport interface TransitionGuard {\n  matcher: TransitionMatcher;\n  run(entity: Entity, step: TransitionStep): MaybePromise<ValidationRuleResult>;\n}\n\n/** A callback with its `match` converted to codes, dispatched only after its transition's guards pass. */\nexport interface TransitionCallback {\n  name: string;\n  phase: \"flush\" | \"commit\";\n  matcher: TransitionMatcher;\n  run(entity: Entity, ctx: unknown, step: TransitionStep): MaybePromise<unknown>;\n}\n\n/** One field's transition config from an entity type and its base types, with accessors converted to codes. */\nexport interface FieldTransitions {\n  /** Each table maps a `from` code to its allowed `to` codes; every table must allow a change. */\n  tables: ReadonlyMap<unknown, readonly unknown[]>[];\n  guards: TransitionGuard[];\n  callbacks: TransitionCallback[];\n}\n\n/** Converts an internal step to the `Transition` that guards and reactions receive. */\nexport function toTransition(step: TransitionStep): Transition<any> {\n  return { from: step.from === created ? undefined : step.from, to: step.to };\n}\n\n/**\n * Merges the transition config of `meta` and its base types by field, converting accessors to codes.\n *\n * This runs after boot, because the config is written before the enum metadata exists.\n */\nexport function buildFieldTransitions(meta: EntityMetadata): Map<string, FieldTransitions> {\n  const byField = new Map<string, FieldTransitions>();\n  for (const m of getBaseAndSelfMetas(meta)) {\n    for (const [fieldName, config] of Object.entries(m.config.__data.transitions)) {\n      let merged = byField.get(fieldName);\n      if (!merged) byField.set(fieldName, (merged = { tables: [], guards: [], callbacks: [] }));\n      if (config.table) merged.tables.push(toCodesTable(meta, fieldName, config.table));\n      for (const { match, run } of config.guards) {\n        merged.guards.push({ matcher: toMatcher(meta, fieldName, match), run });\n      }\n      for (const { name, match, run } of config.callbacks) {\n        const matcher = toMatcher(meta, fieldName, match);\n        merged.callbacks.push({ name, phase: match.phase ?? \"flush\", matcher, run });\n      }\n    }\n  }\n  return byField;\n}\n\n/** Returns whether `step` matches `matcher`'s `from`, `to`, and `onCreate` settings. */\nexport function matchesTransition(matcher: TransitionMatcher, step: TransitionStep): boolean {\n  if (step.from === created) {\n    if (!matcher.onCreate) return false;\n  } else if (matcher.from && !matcher.from.includes(step.from)) {\n    return false;\n  }\n  return !matcher.to || matcher.to.includes(step.to);\n}\n\n/** Uses the enum's display name in error messages when there is one, i.e. `Approved` instead of `APPROVED`. */\nexport function describeValue(meta: EntityMetadata, fieldName: string, value: unknown): string {\n  if (value === undefined) return \"unset\";\n  const field = meta.allFields[fieldName];\n  return field?.kind === \"enum\" ? (field.enumDetailType.getByCode(value)?.name ?? String(value)) : String(value);\n}\n\n/** Converts a `transitions` table's keys and values to codes, so it can be compared to field values. */\nfunction toCodesTable(\n  meta: EntityMetadata,\n  fieldName: string,\n  table: TransitionTable<string>,\n): Map<unknown, readonly unknown[]> {\n  return new Map(\n    Object.entries(table).map(([from, tos]) => [\n      accessorToCode(meta, fieldName, from),\n      toCodes(meta, fieldName, tos ?? [])!,\n    ]),\n  );\n}\n\n/** Converts a `match`'s accessors to codes. */\nfunction toMatcher(meta: EntityMetadata, fieldName: string, match: OnTransitionMatch<string>): TransitionMatcher {\n  return {\n    from: toCodes(meta, fieldName, match.from),\n    to: toCodes(meta, fieldName, match.to),\n    // `from` describes a previous state, which a new entity doesn't have\n    onCreate: match.onCreate !== false && match.from === undefined,\n  };\n}\n\n/** Converts an enum accessor, i.e. `Rejected`, to its code, i.e. `REJECTED`, and fails on anything else. */\nfunction accessorToCode(meta: EntityMetadata, fieldName: string, value: unknown): unknown {\n  const field = meta.allFields[fieldName];\n  if (field?.kind !== \"enum\") fail(`${meta.type}.${fieldName} is not an enum field, so it can't have transitions`);\n  // Only accessors are accepted, even from untyped callers, so every table reads the same way\n  if (typeof value !== \"string\" || !Object.hasOwn(field.enumType, value)) {\n    fail(`Unknown ${meta.type}.${fieldName} accessor ${String(value)}, i.e. use \"Draft\" for AuthorStatus.Draft`);\n  }\n  return field.enumType[value];\n}\n\n/** Converts one or more enum accessors to an array of codes, preserving an omitted match. */\nfunction toCodes(\n  meta: EntityMetadata,\n  fieldName: string,\n  values: string | readonly string[] | undefined,\n): unknown[] | undefined {\n  if (values === undefined) return undefined;\n  return typeof values === \"string\"\n    ? [accessorToCode(meta, fieldName, values)]\n    : values.map((v) => accessorToCode(meta, fieldName, v));\n}\n"],"mappings":";;;;;AA+CA,MAAa,UAAyB,OAAO,SAAS;;AA8DtD,SAAgB,aAAa,MAAuC;CAClE,OAAO;EAAE,MAAM,KAAK,SAAS,UAAU,KAAA,IAAY,KAAK;EAAM,IAAI,KAAK;CAAG;AAC5E;;;;;;AAOA,SAAgB,sBAAsB,MAAqD;CACzF,MAAM,0BAAU,IAAI,IAA8B;CAClD,KAAK,MAAM,KAAKA,uBAAAA,oBAAoB,IAAI,GACtC,KAAK,MAAM,CAAC,WAAW,WAAW,OAAO,QAAQ,EAAE,OAAO,OAAO,WAAW,GAAG;EAC7E,IAAI,SAAS,QAAQ,IAAI,SAAS;EAClC,IAAI,CAAC,QAAQ,QAAQ,IAAI,WAAY,SAAS;GAAE,QAAQ,CAAC;GAAG,QAAQ,CAAC;GAAG,WAAW,CAAC;EAAE,CAAE;EACxF,IAAI,OAAO,OAAO,OAAO,OAAO,KAAK,aAAa,MAAM,WAAW,OAAO,KAAK,CAAC;EAChF,KAAK,MAAM,EAAE,OAAO,SAAS,OAAO,QAClC,OAAO,OAAO,KAAK;GAAE,SAAS,UAAU,MAAM,WAAW,KAAK;GAAG;EAAI,CAAC;EAExE,KAAK,MAAM,EAAE,MAAM,OAAO,SAAS,OAAO,WAAW;GACnD,MAAM,UAAU,UAAU,MAAM,WAAW,KAAK;GAChD,OAAO,UAAU,KAAK;IAAE;IAAM,OAAO,MAAM,SAAS;IAAS;IAAS;GAAI,CAAC;EAC7E;CACF;CAEF,OAAO;AACT;;AAGA,SAAgB,kBAAkB,SAA4B,MAA+B;CAC3F,IAAI,KAAK,SAAS,SACZ;MAAA,CAAC,QAAQ,UAAU,OAAO;CAAA,OACzB,IAAI,QAAQ,QAAQ,CAAC,QAAQ,KAAK,SAAS,KAAK,IAAI,GACzD,OAAO;CAET,OAAO,CAAC,QAAQ,MAAM,QAAQ,GAAG,SAAS,KAAK,EAAE;AACnD;;AAGA,SAAgB,cAAc,MAAsB,WAAmB,OAAwB;CAC7F,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,MAAM,QAAQ,KAAK,UAAU;CAC7B,OAAO,OAAO,SAAS,SAAU,MAAM,eAAe,UAAU,KAAK,CAAC,EAAE,QAAQ,OAAO,KAAK,IAAK,OAAO,KAAK;AAC/G;;AAGA,SAAS,aACP,MACA,WACA,OACkC;CAClC,OAAO,IAAI,IACT,OAAO,QAAQ,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,SAAS,CACzC,eAAe,MAAM,WAAW,IAAI,GACpC,QAAQ,MAAM,WAAW,OAAO,CAAC,CAAC,CACpC,CAAC,CACH;AACF;;AAGA,SAAS,UAAU,MAAsB,WAAmB,OAAqD;CAC/G,OAAO;EACL,MAAM,QAAQ,MAAM,WAAW,MAAM,IAAI;EACzC,IAAI,QAAQ,MAAM,WAAW,MAAM,EAAE;EAErC,UAAU,MAAM,aAAa,SAAS,MAAM,SAAS,KAAA;CACvD;AACF;;AAGA,SAAS,eAAe,MAAsB,WAAmB,OAAyB;CACxF,MAAM,QAAQ,KAAK,UAAU;CAC7B,IAAI,OAAO,SAAS,QAAQ,cAAA,KAAK,GAAG,KAAK,KAAK,GAAG,UAAU,oDAAoD;CAE/G,IAAI,OAAO,UAAU,YAAY,CAAC,OAAO,OAAO,MAAM,UAAU,KAAK,GACnE,cAAA,KAAK,WAAW,KAAK,KAAK,GAAG,UAAU,YAAY,OAAO,KAAK,EAAE,0CAA0C;CAE7G,OAAO,MAAM,SAAS;AACxB;;AAGA,SAAS,QACP,MACA,WACA,QACuB;CACvB,IAAI,WAAW,KAAA,GAAW,OAAO,KAAA;CACjC,OAAO,OAAO,WAAW,WACrB,CAAC,eAAe,MAAM,WAAW,MAAM,CAAC,IACxC,OAAO,KAAK,MAAM,eAAe,MAAM,WAAW,CAAC,CAAC;AAC1D"}

package/build/transitions.d.cts

@@ -0,0 +1,110 @@
+import { MaybePromise } from "./utils.cjs";
+import { ValidationRuleResult } from "./rules.cjs";
+import { EntityMetadata } from "./EntityMetadata.cjs";
+import { Entity } from "./Entity.cjs";
+//#region src/transitions.d.ts
+/**
+ * Which state transitions of an enum field a `guardTransition` cares about.
+ *
+ * Omitting `from` or `to` matches any state. Guards never run on creation.
+ */
+interface GuardTransitionMatch<V> {
+  from?: V | readonly V[];
+  to?: V | readonly V[];
+}
+/**
+ * Which state transitions of an enum field an `onTransition` callback handles.
+ *
+ * Creating an entity with a matching `to` state also matches, unless `from` is set or `onCreate` is `false`.
+ */
+interface OnTransitionMatch<V> extends GuardTransitionMatch<V> {
+  /**
+   * Whether `onTransition` fires when an entity is created with a matching `to` state, defaults to `true`.
+   *
+   * Entering a state by creation usually needs the same side effects as entering it by a transition, and
+   * forgetting them is easy to miss. Set `false` for reactions that only make sense for a transition.
+   */
+  onCreate?: boolean;
+  /** `commit` runs in `beforeCommit`, i.e. to enqueue jobs; `flush` (the default) runs as a reaction. */
+  phase?: "flush" | "commit";
+}
+/** Maps each state to the states it may transition to, i.e. `{ Draft: ["Open"], Open: ["Closed"] }`. */
+type TransitionTable<V extends PropertyKey> = Partial<Record<V, readonly V[]>>;
+/**
+ * The transition a guard or reaction is handling, i.e. `{ from: "DRAFT", to: "OPEN" }`.
+ *
+ * Guards and callbacks run during reaction passes, after the assignment, so the entity may already be in a
+ * later state. This tells them which transition they're handling. `from` is `undefined` for creation.
+ */
+interface Transition<V> {
+  from: V | undefined;
+  to: V;
+}
+/** The "from" state of a just-created entity, because `undefined` can be a real field value. */
+declare const created: unique symbol;
+/** A single recorded transition of a field, with `from` as `created` for creation. */
+interface TransitionStep {
+  from: unknown;
+  to: unknown;
+}
+/** A `guardTransition` as registered in config, with its `match` still using accessors. */
+interface TransitionGuardConfig<T extends Entity = Entity> {
+  match: GuardTransitionMatch<string>;
+  run(entity: T, step: TransitionStep): MaybePromise<ValidationRuleResult>;
+}
+/** An `onTransition` as registered in config, with its `match` still using accessors. */
+interface TransitionCallbackConfig<T extends Entity = Entity, C = unknown> {
+  name: string;
+  match: OnTransitionMatch<string>;
+  run(entity: T, ctx: C, step: TransitionStep): MaybePromise<unknown>;
+}
+/** One field's `transitions`, `guardTransition`, and `onTransition` config on a single entity type. */
+interface FieldTransitionsConfig<T extends Entity = Entity, C = unknown> {
+  /** The `transitions` table, if any; subtypes add their own tables on their own configs. */
+  table?: TransitionTable<string>;
+  guards: TransitionGuardConfig<T>[];
+  callbacks: TransitionCallbackConfig<T, C>[];
+}
+/** A `match` with accessors converted to codes, so it can be compared to recorded steps. */
+interface TransitionMatcher {
+  /** The allowed previous states, or `undefined` for any state. */
+  from: readonly unknown[] | undefined;
+  /** The allowed new states, or `undefined` for any state. */
+  to: readonly unknown[] | undefined;
+  /** Whether creation matches, which is never true when `from` is set. */
+  onCreate: boolean;
+}
+/** A guard with its `match` converted to codes. */
+interface TransitionGuard {
+  matcher: TransitionMatcher;
+  run(entity: Entity, step: TransitionStep): MaybePromise<ValidationRuleResult>;
+}
+/** A callback with its `match` converted to codes, dispatched only after its transition's guards pass. */
+interface TransitionCallback {
+  name: string;
+  phase: "flush" | "commit";
+  matcher: TransitionMatcher;
+  run(entity: Entity, ctx: unknown, step: TransitionStep): MaybePromise<unknown>;
+}
+/** One field's transition config from an entity type and its base types, with accessors converted to codes. */
+interface FieldTransitions {
+  /** Each table maps a `from` code to its allowed `to` codes; every table must allow a change. */
+  tables: ReadonlyMap<unknown, readonly unknown[]>[];
+  guards: TransitionGuard[];
+  callbacks: TransitionCallback[];
+}
+/** Converts an internal step to the `Transition` that guards and reactions receive. */
+declare function toTransition(step: TransitionStep): Transition<any>;
+/**
+ * Merges the transition config of `meta` and its base types by field, converting accessors to codes.
+ *
+ * This runs after boot, because the config is written before the enum metadata exists.
+ */
+declare function buildFieldTransitions(meta: EntityMetadata): Map<string, FieldTransitions>;
+/** Returns whether `step` matches `matcher`'s `from`, `to`, and `onCreate` settings. */
+declare function matchesTransition(matcher: TransitionMatcher, step: TransitionStep): boolean;
+/** Uses the enum's display name in error messages when there is one, i.e. `Approved` instead of `APPROVED`. */
+declare function describeValue(meta: EntityMetadata, fieldName: string, value: unknown): string;
+//#endregion
+export { FieldTransitions, FieldTransitionsConfig, GuardTransitionMatch, OnTransitionMatch, Transition, TransitionCallback, TransitionCallbackConfig, TransitionGuard, TransitionGuardConfig, TransitionMatcher, TransitionStep, TransitionTable, buildFieldTransitions, created, describeValue, matchesTransition, toTransition };
+//# sourceMappingURL=transitions.d.cts.map

package/build/transitions.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.cts","names":[],"sources":["../src/transitions.ts"],"mappings":";;;;;;;;;;UAUiB,qBAAqB;EACpC,OAAO,aAAa;EACpB,KAAK,aAAa;;;;;;;UAQH,kBAAkB,WAAW,qBAAqB;;;;;;;EAOjE;;EAEA;;;KAIU,gBAAgB,UAAU,eAAe,QAAQ,OAAO,YAAY;;;;;;;UAQ/D,WAAW;EAC1B,MAAM;EACN,IAAI;;;cAIO;;UAGI;EACf;EACA;;;UAIe,sBAAsB,UAAU,SAAS;EACxD,OAAO;EACP,IAAI,QAAQ,GAAG,MAAM,iBAAiB,aAAa;;;UAIpC,yBAAyB,UAAU,SAAS,QAAQ;EACnE;EACA,OAAO;EACP,IAAI,QAAQ,GAAG,KAAK,GAAG,MAAM,iBAAiB;;;UAI/B,uBAAuB,UAAU,SAAS,QAAQ;;EAEjE,QAAQ;EACR,QAAQ,sBAAsB;EAC9B,WAAW,yBAAyB,GAAG;;;UAIxB;;EAEf;;EAEA;;EAEA;;;UAIe;EACf,SAAS;EACT,IAAI,QAAQ,QAAQ,MAAM,iBAAiB,aAAa;;;UAIzC;EACf;EACA;EACA,SAAS;EACT,IAAI,QAAQ,QAAQ,cAAc,MAAM,iBAAiB;;;UAI1C;;EAEf,QAAQ;EACR,QAAQ;EACR,WAAW;;;iBAIG,aAAa,MAAM,iBAAiB;;;;;;iBASpC,sBAAsB,MAAM,iBAAiB,YAAY;;iBAoBzD,kBAAkB,SAAS,mBAAmB,MAAM;;iBAUpD,cAAc,MAAM,gBAAgB,mBAAmB"}

package/build/transitions.d.mts

@@ -0,0 +1,110 @@
+import { MaybePromise } from "./utils.mjs";
+import { ValidationRuleResult } from "./rules.mjs";
+import { EntityMetadata } from "./EntityMetadata.mjs";
+import { Entity } from "./Entity.mjs";
+//#region src/transitions.d.ts
+/**
+ * Which state transitions of an enum field a `guardTransition` cares about.
+ *
+ * Omitting `from` or `to` matches any state. Guards never run on creation.
+ */
+interface GuardTransitionMatch<V> {
+  from?: V | readonly V[];
+  to?: V | readonly V[];
+}
+/**
+ * Which state transitions of an enum field an `onTransition` callback handles.
+ *
+ * Creating an entity with a matching `to` state also matches, unless `from` is set or `onCreate` is `false`.
+ */
+interface OnTransitionMatch<V> extends GuardTransitionMatch<V> {
+  /**
+   * Whether `onTransition` fires when an entity is created with a matching `to` state, defaults to `true`.
+   *
+   * Entering a state by creation usually needs the same side effects as entering it by a transition, and
+   * forgetting them is easy to miss. Set `false` for reactions that only make sense for a transition.
+   */
+  onCreate?: boolean;
+  /** `commit` runs in `beforeCommit`, i.e. to enqueue jobs; `flush` (the default) runs as a reaction. */
+  phase?: "flush" | "commit";
+}
+/** Maps each state to the states it may transition to, i.e. `{ Draft: ["Open"], Open: ["Closed"] }`. */
+type TransitionTable<V extends PropertyKey> = Partial<Record<V, readonly V[]>>;
+/**
+ * The transition a guard or reaction is handling, i.e. `{ from: "DRAFT", to: "OPEN" }`.
+ *
+ * Guards and callbacks run during reaction passes, after the assignment, so the entity may already be in a
+ * later state. This tells them which transition they're handling. `from` is `undefined` for creation.
+ */
+interface Transition<V> {
+  from: V | undefined;
+  to: V;
+}
+/** The "from" state of a just-created entity, because `undefined` can be a real field value. */
+declare const created: unique symbol;
+/** A single recorded transition of a field, with `from` as `created` for creation. */
+interface TransitionStep {
+  from: unknown;
+  to: unknown;
+}
+/** A `guardTransition` as registered in config, with its `match` still using accessors. */
+interface TransitionGuardConfig<T extends Entity = Entity> {
+  match: GuardTransitionMatch<string>;
+  run(entity: T, step: TransitionStep): MaybePromise<ValidationRuleResult>;
+}
+/** An `onTransition` as registered in config, with its `match` still using accessors. */
+interface TransitionCallbackConfig<T extends Entity = Entity, C = unknown> {
+  name: string;
+  match: OnTransitionMatch<string>;
+  run(entity: T, ctx: C, step: TransitionStep): MaybePromise<unknown>;
+}
+/** One field's `transitions`, `guardTransition`, and `onTransition` config on a single entity type. */
+interface FieldTransitionsConfig<T extends Entity = Entity, C = unknown> {
+  /** The `transitions` table, if any; subtypes add their own tables on their own configs. */
+  table?: TransitionTable<string>;
+  guards: TransitionGuardConfig<T>[];
+  callbacks: TransitionCallbackConfig<T, C>[];
+}
+/** A `match` with accessors converted to codes, so it can be compared to recorded steps. */
+interface TransitionMatcher {
+  /** The allowed previous states, or `undefined` for any state. */
+  from: readonly unknown[] | undefined;
+  /** The allowed new states, or `undefined` for any state. */
+  to: readonly unknown[] | undefined;
+  /** Whether creation matches, which is never true when `from` is set. */
+  onCreate: boolean;
+}
+/** A guard with its `match` converted to codes. */
+interface TransitionGuard {
+  matcher: TransitionMatcher;
+  run(entity: Entity, step: TransitionStep): MaybePromise<ValidationRuleResult>;
+}
+/** A callback with its `match` converted to codes, dispatched only after its transition's guards pass. */
+interface TransitionCallback {
+  name: string;
+  phase: "flush" | "commit";
+  matcher: TransitionMatcher;
+  run(entity: Entity, ctx: unknown, step: TransitionStep): MaybePromise<unknown>;
+}
+/** One field's transition config from an entity type and its base types, with accessors converted to codes. */
+interface FieldTransitions {
+  /** Each table maps a `from` code to its allowed `to` codes; every table must allow a change. */
+  tables: ReadonlyMap<unknown, readonly unknown[]>[];
+  guards: TransitionGuard[];
+  callbacks: TransitionCallback[];
+}
+/** Converts an internal step to the `Transition` that guards and reactions receive. */
+declare function toTransition(step: TransitionStep): Transition<any>;
+/**
+ * Merges the transition config of `meta` and its base types by field, converting accessors to codes.
+ *
+ * This runs after boot, because the config is written before the enum metadata exists.
+ */
+declare function buildFieldTransitions(meta: EntityMetadata): Map<string, FieldTransitions>;
+/** Returns whether `step` matches `matcher`'s `from`, `to`, and `onCreate` settings. */
+declare function matchesTransition(matcher: TransitionMatcher, step: TransitionStep): boolean;
+/** Uses the enum's display name in error messages when there is one, i.e. `Approved` instead of `APPROVED`. */
+declare function describeValue(meta: EntityMetadata, fieldName: string, value: unknown): string;
+//#endregion
+export { FieldTransitions, FieldTransitionsConfig, GuardTransitionMatch, OnTransitionMatch, Transition, TransitionCallback, TransitionCallbackConfig, TransitionGuard, TransitionGuardConfig, TransitionMatcher, TransitionStep, TransitionTable, buildFieldTransitions, created, describeValue, matchesTransition, toTransition };
+//# sourceMappingURL=transitions.d.mts.map