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

package/build/transitions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.mts","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.js

@@ -0,0 +1,84 @@
+import { fail } from "./utils.js";
+import { getBaseAndSelfMetas } from "./EntityMetadata.js";
+//#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 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") fail(`${meta.type}.${fieldName} is not an enum field, so it can't have transitions`);
+	if (typeof value !== "string" || !Object.hasOwn(field.enumType, value)) 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
+export { buildFieldTransitions, created, describeValue, matchesTransition, toTransition };
+
+//# sourceMappingURL=transitions.js.map

package/build/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","names":[],"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,KAAK,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,KAAK,GAAG,KAAK,KAAK,GAAG,UAAU,oDAAoD;CAE/G,IAAI,OAAO,UAAU,YAAY,CAAC,OAAO,OAAO,MAAM,UAAU,KAAK,GACnE,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joist-core",
-  "version": "2.4.0-next.2",
+  "version": "2.4.0-next.21",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -42,7 +42,7 @@
     "build"
   ],
   "peerDependencies": {
-    "joist-utils": "2.4.0-next.2"
+    "joist-utils": "2.4.0-next.21"
   },
   "dependencies": {
     "ansis": "^4.3.1",