velocious 1.0.552 → 1.0.555

package/src/testing/factory/strategies/base.js

@@ -0,0 +1,209 @@
+// @ts-check
+
+import * as inflection from "inflection"
+import {assertModelClass} from "../model-contract.js"
+import {ModelContractError} from "../errors.js"
+import EvaluationContext from "../evaluation-context.js"
+
+/**
+ * Shared behaviour for the build/create/attributesFor strategies: evaluation
+ * context creation, deterministic callback execution, guaranteed `afterAll`
+ * cleanup, record construction (default and `initializeWith`), and association
+ * wiring through public relationship reflection.
+ */
+export default class BaseStrategy {
+  /**
+   * Creates an evaluation context for a plan.
+   * @param {import("../factory-registry.js").default} registry - Owning registry.
+   * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
+   * @param {"attributesFor" | "build" | "create"} strategyName - Strategy name.
+   * @returns {EvaluationContext} - The context.
+   */
+  _newContext(registry, plan, strategyName) {
+    return new EvaluationContext({registry, plan, strategy: strategyName})
+  }
+
+  /**
+   * Builds the callback `context` object: evaluated transients exposed as plain
+   * properties (no Proxy) plus the named evaluator methods.
+   * @param {EvaluationContext} context - Evaluation context.
+   * @param {Record<string, ?>} transients - Evaluated transient values.
+   * @returns {Record<string, ?>} - The callback context.
+   */
+  _callbackContext(context, transients) {
+    return Object.assign({}, transients, context.contextFor([]))
+  }
+
+  /**
+   * Runs every deduped callback for an event in declaration order.
+   * @param {EvaluationContext} context - Evaluation context.
+   * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
+   * @param {string} event - Event name (e.g. "afterCreate").
+   * @param {{record: ?, transients: Record<string, ?>, strategy: string}} state - Current record/transients/strategy.
+   * @returns {Promise<void>} - Resolves when all callbacks complete.
+   */
+  async _runCallbacks(context, plan, event, state) {
+    const callbacks = plan.callbacks.get(event)
+
+    if (!callbacks) return
+
+    const callbackContext = this._callbackContext(context, state.transients)
+
+    for (const callback of callbacks) {
+      await callback.fn({record: state.record, context: callbackContext, strategy: state.strategy})
+    }
+  }
+
+  /**
+   * Runs `body`, then guarantees `afterAll` runs in `finally`. When both the body
+   * and cleanup fail, the body's primary error is preserved and the cleanup error
+   * is attached as a detail rather than masking it.
+   * @param {EvaluationContext} context - Evaluation context.
+   * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
+   * @param {() => {record: ?, transients: Record<string, ?>, strategy: string}} state - Late-bound state accessor.
+   * @param {() => Promise<?>} body - The strategy body.
+   * @returns {Promise<?>} - The body's result.
+   */
+  async _runWithAfterAll(context, plan, state, body) {
+    /** @type {?} */
+    let result
+    /** @type {?} */
+    let primaryError
+    let hasPrimaryError = false
+
+    try {
+      result = await body()
+    } catch (error) {
+      primaryError = error
+      hasPrimaryError = true
+    }
+
+    /** @type {?} */
+    let cleanupError
+    let hasCleanupError = false
+
+    try {
+      await this._runCallbacks(context, plan, "afterAll", state())
+    } catch (error) {
+      cleanupError = error
+      hasCleanupError = true
+    }
+
+    if (hasPrimaryError) {
+      if (hasCleanupError) this._attachCleanupFailure(primaryError, cleanupError)
+
+      throw primaryError
+    }
+
+    if (hasCleanupError) throw cleanupError
+
+    return result
+  }
+
+  /**
+   * Attaches an afterAll cleanup failure to the primary error without masking it.
+   * @param {?} primaryError - The original error that will propagate.
+   * @param {?} cleanupError - The afterAll cleanup failure.
+   * @returns {void}
+   */
+  _attachCleanupFailure(primaryError, cleanupError) {
+    if (!primaryError || typeof primaryError !== "object" || !Object.isExtensible(primaryError)) return
+
+    if (!Array.isArray(primaryError.factoryCleanupErrors)) primaryError.factoryCleanupErrors = []
+    primaryError.factoryCleanupErrors.push(cleanupError)
+  }
+
+  /**
+   * Constructs a record from evaluated public attributes, honouring a custom
+   * `initializeWith` constructor and never assigning constructor-consumed
+   * attributes twice.
+   * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
+   * @param {Record<string, ?>} publicAttributes - Evaluated public attributes.
+   * @param {EvaluationContext} context - Evaluation context.
+   * @param {Record<string, ?>} transients - Evaluated transients.
+   * @returns {Promise<?>} - The constructed record.
+   */
+  async _constructRecord(plan, publicAttributes, context, transients) {
+    const ModelClass = assertModelClass(plan.modelClass, plan.factoryName)
+
+    if (plan.initializeWith) {
+      return await this._constructWithInitializer(plan, ModelClass, publicAttributes, context, transients)
+    }
+
+    return new ModelClass(publicAttributes)
+  }
+
+  /**
+   * Constructs a record via a custom `initializeWith`, tracking which attributes
+   * the constructor consumed through its `get(name)` accessor and assigning only
+   * the remaining public attributes afterwards.
+   * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
+   * @param {new (attributes?: Record<string, ?>) => import("../../../database/record/index.js").default} ModelClass - Validated declared model class.
+   * @param {Record<string, ?>} publicAttributes - Evaluated public attributes.
+   * @param {EvaluationContext} context - Evaluation context.
+   * @param {Record<string, ?>} transients - Evaluated transients.
+   * @returns {Promise<?>} - The constructed record.
+   */
+  async _constructWithInitializer(plan, ModelClass, publicAttributes, context, transients) {
+    /** @type {Set<string>} */
+    const consumed = new Set()
+    const get = (/** @type {string} */ name) => {
+      consumed.add(name)
+
+      return publicAttributes[name]
+    }
+    const initializeWith = /** @type {import("../declarations.js").InitializeWithDeclaration["fn"]} */ (plan.initializeWith)
+    const record = await initializeWith({attributes: {...publicAttributes}, get, context: this._callbackContext(context, transients)})
+
+    if (!(record instanceof ModelClass)) {
+      throw new ModelContractError(`Factory "${plan.factoryName}" initializeWith must return an instance of ${ModelClass.name}, got: ${String(record)}`)
+    }
+
+    /** @type {Record<string, ?>} */
+    const remaining = {}
+
+    for (const key of Object.keys(publicAttributes)) {
+      if (!consumed.has(key)) remaining[key] = publicAttributes[key]
+    }
+
+    if (Object.keys(remaining).length > 0) {
+      /** @type {?} */ (record).assign(remaining)
+    }
+
+    return record
+  }
+
+  /**
+   * Wires evaluated associations onto a record through public relationship
+   * reflection and generated setters (never private caches or guessed keys).
+   * @param {?} record - The owning record.
+   * @param {Array<{name: string, record: ?}>} associations - Evaluated associations.
+   * @returns {void}
+   */
+  _assignAssociations(record, associations) {
+    for (const {name, record: associatedRecord} of associations) {
+      const instanceRelationship = record.getRelationshipByName(name)
+      const relationshipType = instanceRelationship.getType()
+
+      if (relationshipType === "belongsTo") {
+        record[`set${inflection.camelize(name)}`](associatedRecord || null)
+      } else if (relationshipType === "hasOne") {
+        instanceRelationship.setLoaded(associatedRecord || undefined)
+      } else if (relationshipType === "hasMany") {
+        instanceRelationship.setLoaded(this._toRecordArray(associatedRecord))
+      }
+    }
+  }
+
+  /**
+   * Normalizes a has-many association value into an array of records.
+   * @param {?} value - Association value (record, array, or null).
+   * @returns {Array<?>} - The normalized record array.
+   */
+  _toRecordArray(value) {
+    if (value == null) return []
+    if (Array.isArray(value)) return value
+
+    return [value]
+  }
+}

package/src/testing/factory/strategies/build.js

@@ -0,0 +1,42 @@
+// @ts-check
+
+import BaseStrategy from "./base.js"
+
+/**
+ * The `build` strategy. It recursively builds associated models (using the parent
+ * strategy) and constructs the root record without persisting anything. Runs the
+ * beforeAll/beforeBuild/afterBuild callbacks and guarantees afterAll cleanup.
+ */
+export default class BuildStrategy extends BaseStrategy {
+  /**
+   * Runs the strategy.
+   * @param {object} args - Options.
+   * @param {import("../factory-registry.js").default} args.registry - Owning registry.
+   * @param {import("../factory-runner.js").CompiledPlan} args.plan - Compiled plan.
+   * @returns {Promise<?>} - The built (unsaved) record.
+   */
+  async run({registry, plan}) {
+    const context = this._newContext(registry, plan, "build")
+    /** @type {{record: ?, transients: Record<string, ?>}} */
+    const runState = {record: undefined, transients: {}}
+    const state = () => ({record: runState.record, transients: runState.transients, strategy: "build"})
+
+    return await this._runWithAfterAll(context, plan, state, async () => {
+      runState.transients = await context.resolveTransients()
+
+      await this._runCallbacks(context, plan, "beforeAll", state())
+      await this._runCallbacks(context, plan, "beforeBuild", state())
+
+      const {publicAttributes, transients, associations} = await context.resolveForConstruction()
+
+      const record = await this._constructRecord(plan, publicAttributes, context, transients)
+
+      this._assignAssociations(record, associations)
+      runState.record = record
+
+      await this._runCallbacks(context, plan, "afterBuild", state())
+
+      return record
+    })
+  }
+}

package/src/testing/factory/strategies/create.js

@@ -0,0 +1,68 @@
+// @ts-check
+
+import BaseStrategy from "./base.js"
+
+/**
+ * The `create` strategy. It builds the object graph (associations use the parent
+ * create strategy by default), runs beforeAll/beforeBuild/afterBuild, persists the
+ * root record through its native `save()` (letting Velocious own association
+ * autosave order and validation) or a custom `toCreate`, then runs
+ * beforeCreate/afterCreate and guarantees afterAll cleanup.
+ */
+export default class CreateStrategy extends BaseStrategy {
+  /**
+   * Runs the strategy.
+   * @param {object} args - Options.
+   * @param {import("../factory-registry.js").default} args.registry - Owning registry.
+   * @param {import("../factory-runner.js").CompiledPlan} args.plan - Compiled plan.
+   * @returns {Promise<?>} - The persisted record.
+   */
+  async run({registry, plan}) {
+    const context = this._newContext(registry, plan, "create")
+    /** @type {{record: ?, transients: Record<string, ?>}} */
+    const runState = {record: undefined, transients: {}}
+    const state = () => ({record: runState.record, transients: runState.transients, strategy: "create"})
+
+    return await this._runWithAfterAll(context, plan, state, async () => {
+      runState.transients = await context.resolveTransients()
+
+      await this._runCallbacks(context, plan, "beforeAll", state())
+      await this._runCallbacks(context, plan, "beforeBuild", state())
+
+      const {publicAttributes, transients, associations} = await context.resolveForConstruction()
+
+      const record = await this._constructRecord(plan, publicAttributes, context, transients)
+
+      this._assignAssociations(record, associations)
+      runState.record = record
+
+      await this._runCallbacks(context, plan, "afterBuild", state())
+      await this._runCallbacks(context, plan, "beforeCreate", state())
+      await this._persist(plan, record, context, transients)
+      await this._runCallbacks(context, plan, "afterCreate", state())
+
+      return record
+    })
+  }
+
+  /**
+   * Persists the record via a custom `toCreate`, native `save()`, or not at all
+   * when `skipCreate` is declared.
+   * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
+   * @param {?} record - The record to persist.
+   * @param {import("../evaluation-context.js").default} context - Evaluation context.
+   * @param {Record<string, ?>} transients - Evaluated transients.
+   * @returns {Promise<void>} - Resolves when persistence completes.
+   */
+  async _persist(plan, record, context, transients) {
+    if (plan.skipCreate) return
+
+    if (plan.toCreate) {
+      await plan.toCreate({record, context: this._callbackContext(context, transients)})
+
+      return
+    }
+
+    await record.save()
+  }
+}

package/src/testing/factory/trait-definition.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+/**
+ * An immutable compiled trait. A trait carries an ordered list of declarations
+ * (attributes, transients, associations, callbacks, custom construction, and
+ * base-trait inclusions) that are mixed into a factory run.
+ */
+export default class TraitDefinition {
+  /**
+   * Builds a trait definition.
+   * @param {object} args - Options.
+   * @param {string} args.name - Trait name.
+   * @param {import("./declarations.js").Declaration[]} args.declarations - Ordered declarations.
+   */
+  constructor({name, declarations}) {
+    /** @type {string} - Trait name. */
+    this.name = name
+
+    /** @type {Array<import("./declarations.js").Declaration>} - Ordered declarations. */
+    this.declarations = /** @type {Array<import("./declarations.js").Declaration>} */ (Object.freeze([...declarations]))
+
+    Object.freeze(this)
+  }
+}