velocious 1.0.552 → 1.0.555

package/src/testing/factory/factory-runner.js

@@ -0,0 +1,296 @@
+// @ts-check
+
+import DatabaseRecord from "../../database/record/index.js"
+import {FactoryCycleError, UndefinedFactoryError, UndefinedTraitError} from "./errors.js"
+
+/**
+ * A resolved attribute/transient/association slot in a compiled plan.
+ * @typedef {object} Slot
+ * @property {"attribute" | "transient" | "association"} slotKind - Slot nature.
+ * @property {?} value - Literal/lazy value, override value, or AssociationDeclaration.
+ * @property {boolean} isOverride - Whether the value came from a call-site override.
+ */
+
+/**
+ * The immutable result of compiling a factory invocation.
+ * @typedef {object} CompiledPlan
+ * @property {string} factoryName - Target factory name.
+ * @property {import("./factory-definition.js").default} factoryDefinition - Target definition.
+ * @property {(new (attributes?: Record<string, ?>) => ?) | null} modelClass - Resolved model class.
+ * @property {string[]} chainNames - Inheritance chain names (child last) for sequence scope.
+ * @property {Map<string, Slot>} resolved - Name→slot map (last declaration wins).
+ * @property {Map<string, import("./declarations.js").CallbackDeclaration[]>} callbacks - Deduped callbacks by event.
+ * @property {import("./declarations.js").InitializeWithDeclaration["fn"] | null} initializeWith - Custom constructor, or null.
+ * @property {import("./declarations.js").ToCreateDeclaration["fn"] | null} toCreate - Custom persistence, or null.
+ * @property {boolean} skipCreate - Whether persistence is skipped.
+ */
+
+/**
+ * Compiles factory invocations into immutable plans by resolving the inheritance
+ * chain, expanding base and requested traits, and folding declarations into a
+ * name→slot map plus a deduped, ordered callback set.
+ */
+export default class FactoryRunner {
+  /**
+   * Builds a runner.
+   * @param {import("./factory-registry.js").default} registry - Owning registry.
+   */
+  constructor(registry) {
+    /** @type {import("./factory-registry.js").default} - Owning registry. */
+    this.registry = registry
+  }
+
+  /**
+   * Compiles a factory invocation into a plan.
+   * @param {string} factoryName - Factory to run.
+   * @param {string[]} requestedTraits - Traits requested at the call site, in order.
+   * @param {Record<string, ?>} overrides - Call-site overrides (highest precedence).
+   * @returns {CompiledPlan} - The compiled plan.
+   */
+  compile(factoryName, requestedTraits, overrides) {
+    const chain = this._resolveChain(factoryName)
+    const target = chain[chain.length - 1]
+    const modelClass = this._resolveModelClass(chain)
+
+    /** @type {Array<{decl: import("./declarations.js").Declaration}>} */
+    const flattened = []
+
+    for (const declaration of this.registry._globalDeclarations) {
+      flattened.push({decl: declaration})
+    }
+
+    for (const factoryDefinition of chain) {
+      this._expandFactoryDeclarations(factoryDefinition, factoryDefinition, flattened)
+    }
+
+    for (const traitName of requestedTraits) {
+      this._expandTrait(traitName, target, flattened, [])
+    }
+
+    return this._buildPlan({flattened, overrides, modelClass, target, chainNames: chain.map((definition) => definition.name)})
+  }
+
+  /**
+   * Resolves the inheritance chain from the root parent down to the target.
+   * @param {string} factoryName - Target factory name.
+   * @returns {import("./factory-definition.js").default[]} - Chain (root first, target last).
+   */
+  _resolveChain(factoryName) {
+    /** @type {import("./factory-definition.js").default[]} */
+    const chain = []
+    /** @type {Set<string>} */
+    const seen = new Set()
+    /** @type {import("./factory-definition.js").default | null} */
+    let current = this._resolveFactory(factoryName)
+
+    while (current) {
+      if (seen.has(current.name)) {
+        throw new FactoryCycleError(`Factory inheritance cycle detected: ${[...seen, current.name].join(" -> ")}`)
+      }
+
+      seen.add(current.name)
+      chain.unshift(current)
+      current = current.parentName ? this._resolveFactory(current.parentName) : null
+    }
+
+    return chain
+  }
+
+  /**
+   * Resolves a factory definition by name (or alias).
+   * @param {string} factoryName - Factory name.
+   * @returns {import("./factory-definition.js").default} - The definition.
+   */
+  _resolveFactory(factoryName) {
+    const definition = this.registry._factories.get(factoryName)
+
+    if (!definition) {
+      throw new UndefinedFactoryError(`No factory registered called "${factoryName}". Registered: ${[...this.registry._factories.keys()].join(", ") || "(none)"}`)
+    }
+
+    return definition
+  }
+
+  /**
+   * Picks the nearest declared model class in the chain (child overrides parent).
+   * @param {import("./factory-definition.js").default[]} chain - Inheritance chain.
+   * @returns {(new (attributes?: Record<string, ?>) => ?) | null} - The model class, or null.
+   */
+  _resolveModelClass(chain) {
+    for (let index = chain.length - 1; index >= 0; index--) {
+      if (chain[index].modelClass) return chain[index].modelClass
+    }
+
+    return null
+  }
+
+  /**
+   * Expands one factory's own declarations, inlining base-trait inclusions.
+   * @param {import("./factory-definition.js").default} factoryDefinition - Factory whose declarations are expanded.
+   * @param {import("./factory-definition.js").default} scope - Target factory (for local-trait resolution).
+   * @param {Array<{decl: import("./declarations.js").Declaration}>} out - Flattened output sink.
+   * @returns {void}
+   */
+  _expandFactoryDeclarations(factoryDefinition, scope, out) {
+    for (const declaration of factoryDefinition.declarations) {
+      if (declaration.kind === "traitInclude") {
+        this._expandTrait(declaration.name, scope, out, [])
+      } else {
+        out.push({decl: declaration})
+      }
+    }
+  }
+
+  /**
+   * Expands a trait (resolving factory-local before global) and its inclusions.
+   * @param {string} traitName - Trait to expand.
+   * @param {import("./factory-definition.js").default} scope - Target factory (for local-trait resolution).
+   * @param {Array<{decl: import("./declarations.js").Declaration}>} out - Flattened output sink.
+   * @param {string[]} activePath - Trait inclusion path (for cycle detection).
+   * @returns {void}
+   */
+  _expandTrait(traitName, scope, out, activePath) {
+    if (activePath.includes(traitName)) {
+      throw new FactoryCycleError(`Trait inclusion cycle detected: ${[...activePath, traitName].join(" -> ")}`)
+    }
+
+    const localTrait = this._resolveLocalTrait(traitName, scope)
+    const trait = localTrait?.trait || this.registry._globalTraits.get(traitName)
+    const inclusionScope = localTrait?.scope || scope
+
+    if (!trait) {
+      throw new UndefinedTraitError(`No trait registered called "${traitName}" for factory "${scope.name}"`)
+    }
+
+    for (const declaration of trait.declarations) {
+      if (declaration.kind === "traitInclude") {
+        this._expandTrait(declaration.name, inclusionScope, out, [...activePath, traitName])
+      } else {
+        out.push({decl: declaration})
+      }
+    }
+  }
+
+  /**
+   * Resolves a local trait from the current factory upward through its parents.
+   * @param {string} traitName - Trait name to resolve.
+   * @param {import("./factory-definition.js").default} scope - Declaring/requesting factory scope.
+   * @returns {{trait: import("./trait-definition.js").default, scope: import("./factory-definition.js").default} | undefined} - Nearest local trait and its declaring scope, if any.
+   */
+  _resolveLocalTrait(traitName, scope) {
+    /** @type {import("./factory-definition.js").default | undefined} */
+    let current = scope
+
+    while (current) {
+      const trait = current.localTraits.get(traitName)
+
+      if (trait) return {trait, scope: current}
+
+      current = current.parentName ? this._resolveFactory(current.parentName) : undefined
+    }
+
+    return undefined
+  }
+
+  /**
+   * Folds flattened declarations plus overrides into a compiled plan.
+   * @param {object} args - Options.
+   * @param {Array<{decl: import("./declarations.js").Declaration}>} args.flattened - Flattened declarations.
+   * @param {Record<string, ?>} args.overrides - Call-site overrides.
+   * @param {(new (attributes?: Record<string, ?>) => ?) | null} args.modelClass - Resolved model class.
+   * @param {import("./factory-definition.js").default} args.target - Target factory definition.
+   * @param {string[]} args.chainNames - Inheritance chain names.
+   * @returns {CompiledPlan} - The compiled plan.
+   */
+  _buildPlan({flattened, overrides, modelClass, target, chainNames}) {
+    /** @type {Map<string, Slot>} */
+    const resolved = new Map()
+    /** @type {Map<string, import("./declarations.js").CallbackDeclaration[]>} */
+    const callbacks = new Map()
+    /** @type {Set<import("./declarations.js").CallbackDeclaration>} */
+    const seenCallbacks = new Set()
+    /** @type {import("./declarations.js").InitializeWithDeclaration["fn"] | null} */
+    let initializeWith = null
+    /** @type {import("./declarations.js").ToCreateDeclaration["fn"] | null} */
+    let toCreate = null
+    let skipCreate = false
+
+    for (const {decl} of flattened) {
+      if (decl.kind === "attribute") {
+        resolved.set(decl.name, {slotKind: decl.isTransient ? "transient" : "attribute", value: decl.value, isOverride: false})
+      } else if (decl.kind === "association") {
+        resolved.set(decl.name, {slotKind: "association", value: decl, isOverride: false})
+      } else if (decl.kind === "callback") {
+        if (!seenCallbacks.has(decl)) {
+          seenCallbacks.add(decl)
+
+          const eventCallbacks = callbacks.get(decl.event) || []
+
+          eventCallbacks.push(decl)
+          callbacks.set(decl.event, eventCallbacks)
+        }
+      } else if (decl.kind === "initializeWith") {
+        initializeWith = decl.fn
+      } else if (decl.kind === "toCreate") {
+        toCreate = decl.fn
+      } else if (decl.kind === "skipCreate") {
+        skipCreate = true
+      }
+    }
+
+    for (const key of Object.keys(overrides)) {
+      const prior = resolved.get(key)
+
+      resolved.set(key, {slotKind: prior ? prior.slotKind : "attribute", value: overrides[key], isOverride: true})
+    }
+
+    this._arbitrateAssociationOverrides(resolved, overrides, modelClass)
+
+    return {
+      factoryName: target.name,
+      factoryDefinition: target,
+      modelClass,
+      chainNames,
+      resolved,
+      callbacks,
+      initializeWith,
+      toCreate,
+      skipCreate
+    }
+  }
+
+  /**
+   * Applies belongs-to override precedence using the declared model relationship's
+   * real foreign-key metadata. An explicit association object wins over its key;
+   * otherwise an explicit key suppresses the factory-declared association.
+   * @param {Map<string, Slot>} resolved - Folded slots.
+   * @param {Record<string, ?>} overrides - Call-site overrides.
+   * @param {(new (attributes?: Record<string, ?>) => ?) | null} modelClass - Resolved model class.
+   * @returns {void}
+   */
+  _arbitrateAssociationOverrides(resolved, overrides, modelClass) {
+    if (typeof modelClass !== "function" || !(modelClass.prototype instanceof DatabaseRecord)) return
+
+    const backendModelClass = /** @type {typeof DatabaseRecord} */ (modelClass)
+    const columnToAttribute = backendModelClass.getColumnNameToAttributeNameMap()
+
+    for (const [name, slot] of [...resolved]) {
+      if (slot.slotKind !== "association") continue
+
+      const relationship = backendModelClass.getRelationshipByName(name)
+
+      if (relationship.getType() !== "belongsTo") continue
+
+      const foreignKeyColumn = relationship.getForeignKey()
+      const foreignKeyAttribute = columnToAttribute[foreignKeyColumn] || foreignKeyColumn
+
+      if (!Object.hasOwn(overrides, foreignKeyAttribute)) continue
+
+      if (slot.isOverride) {
+        resolved.delete(foreignKeyAttribute)
+      } else {
+        resolved.delete(name)
+      }
+    }
+  }
+}

package/src/testing/factory/index.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+import FactoryRegistry from "./factory-registry.js"
+
+/**
+ * The default, convenient factory registry singleton. Import it as `Factory` and
+ * call `Factory.define(...)`, `Factory.build(...)`, `Factory.create(...)`,
+ * `Factory.attributesFor(...)` and the list/pair helpers. This module is
+ * browser/Metro-safe: it contains no Node built-ins, filesystem discovery, or
+ * raw `import.meta`. Node-only definition loading lives in `./node/load-definitions.js`.
+ * @type {FactoryRegistry}
+ */
+const Factory = new FactoryRegistry()
+
+/**
+ * Creates a fresh, isolated factory registry independent of the default singleton
+ * (for libraries or spec groups that must not share global factory state).
+ * @returns {FactoryRegistry} - A new registry.
+ */
+export function createFactoryRegistry() {
+  return new FactoryRegistry()
+}
+
+export default Factory

package/src/testing/factory/linter.js

@@ -0,0 +1,119 @@
+// @ts-check
+
+import {FactoryError} from "./errors.js"
+
+/** Internal sentinel thrown to force a per-case transaction rollback. */
+class LintRollbackSignal extends Error {}
+
+/**
+ * Aggregated lint failure raised when one or more linted factories/traits error.
+ */
+class FactoryLintError extends FactoryError {}
+
+/**
+ * Executes registered factories (and optionally their traits) to prove they build
+ * and persist, aggregating every failure by case. For the create strategy each
+ * case runs inside the model's ambient transaction and is rolled back, so no rows
+ * remain in the supported single-connection case. External callback side effects
+ * are not reversible and cross-database writes are not globally atomic.
+ */
+export default class FactoryLinter {
+  /**
+   * Builds a linter.
+   * @param {import("./factory-registry.js").default} registry - Registry to lint.
+   */
+  constructor(registry) {
+    /** @type {import("./factory-registry.js").default} - Registry to lint. */
+    this.registry = registry
+  }
+
+  /**
+   * Lints selected factories and reports every failure together.
+   * @param {object} [options] - Options.
+   * @param {string[]} [options.factories] - Factory names to lint. Defaults to all.
+   * @param {boolean} [options.traits] - Whether to also lint each factory's local traits.
+   * @param {"attributesFor" | "build" | "create"} [options.strategy] - Strategy to lint with. Defaults to create.
+   * @returns {Promise<void>} - Resolves when every case passed; rejects with an aggregate otherwise.
+   */
+  async lint({factories, traits = false, strategy = "create"} = {}) {
+    const definitions = this._selectDefinitions(factories)
+    /** @type {Array<{label: string, error: ?}>} */
+    const failures = []
+
+    for (const definition of definitions) {
+      await this._lintCase(definition, [], strategy, failures)
+
+      if (traits) {
+        for (const traitName of definition.localTraits.keys()) {
+          await this._lintCase(definition, [traitName], strategy, failures)
+        }
+      }
+    }
+
+    if (failures.length > 0) {
+      const details = failures.map((failure) => `  ${failure.label}: ${failure.error && failure.error.message}`).join("\n")
+
+      throw new FactoryLintError(`Factory lint found ${failures.length} error(s):\n${details}`)
+    }
+  }
+
+  /**
+   * Resolves the unique set of factory definitions to lint.
+   * @param {string[] | undefined} factories - Explicit names, or undefined for all.
+   * @returns {import("./factory-definition.js").default[]} - Unique definitions.
+   */
+  _selectDefinitions(factories) {
+    if (factories) {
+      return factories.map((name) => this.registry._runner._resolveFactory(name))
+    }
+
+    return [...new Set(this.registry._factories.values())]
+  }
+
+  /**
+   * Lints one factory/trait case, rolling back create-strategy persistence.
+   * @param {import("./factory-definition.js").default} definition - Factory definition.
+   * @param {string[]} traits - Traits to apply for this case.
+   * @param {"attributesFor" | "build" | "create"} strategy - Strategy to run.
+   * @param {Array<{label: string, error: ?}>} failures - Failure sink.
+   * @returns {Promise<void>} - Resolves when the case has been evaluated.
+   */
+  async _lintCase(definition, traits, strategy, failures) {
+    const label = traits.length > 0 ? `${definition.name} + ${traits.join(", ")}` : definition.name
+
+    try {
+      if (strategy === "create") {
+        await this._lintCreateCase(definition, traits)
+      } else {
+        await this.registry[strategy](definition.name, ...traits)
+      }
+    } catch (error) {
+      if (error instanceof LintRollbackSignal) return
+
+      failures.push({label, error})
+    }
+  }
+
+  /**
+   * Runs a create-strategy case inside a transaction and forces a rollback.
+   * @param {import("./factory-definition.js").default} definition - Factory definition.
+   * @param {string[]} traits - Traits to apply.
+   * @returns {Promise<void>} - Resolves (or rejects) once the rollback completes.
+   */
+  async _lintCreateCase(definition, traits) {
+    const chain = this.registry._runner._resolveChain(definition.name)
+    const modelClass = this.registry._runner._resolveModelClass(chain)
+
+    if (!modelClass) {
+      await this.registry.create(definition.name, ...traits)
+
+      return
+    }
+
+    await /** @type {typeof import("../../database/record/index.js").default} */ (modelClass).transaction(async () => {
+      await this.registry.create(definition.name, ...traits)
+
+      throw new LintRollbackSignal()
+    })
+  }
+}

package/src/testing/factory/model-contract.js

@@ -0,0 +1,31 @@
+// @ts-check
+
+import DatabaseRecord from "../../database/record/index.js"
+import {ModelContractError} from "./errors.js"
+
+/**
+ * Asserts a class satisfies the V1 factory model contract: it must be an
+ * initialized backend Velocious `DatabaseRecord` subclass. Uninitialized backend
+ * classes and non-backend classes (e.g. generated frontend models) are rejected
+ * with a named, actionable error rather than failing deep inside construction.
+ * @param {?} modelClass - The candidate model class.
+ * @param {string} factoryName - Factory name, for the error message.
+ * @returns {new (attributes?: Record<string, ?>) => import("../../database/record/index.js").default} - The validated model class.
+ */
+export function assertModelClass(modelClass, factoryName) {
+  if (typeof modelClass !== "function") {
+    throw new ModelContractError(`Factory "${factoryName}" has no model class to construct. Declare one with factory("${factoryName}", ModelClass, ...).`)
+  }
+
+  if (!(modelClass.prototype instanceof DatabaseRecord)) {
+    throw new ModelContractError(`Factory "${factoryName}" model ${modelClass.name || "class"} is not a supported Velocious backend record. build/create require an initialized DatabaseRecord subclass; generated frontend models are not supported in V1.`)
+  }
+
+  const backendModelClass = /** @type {typeof import("../../database/record/index.js").default} */ (modelClass)
+
+  if (!backendModelClass.isInitialized()) {
+    throw new ModelContractError(`Factory "${factoryName}" model ${backendModelClass.name} has not been initialized. Ensure the model class is initialized (e.g. via configuration.initialize()/ensureInitialized) before build/create.`)
+  }
+
+  return /** @type {new (attributes?: Record<string, ?>) => import("../../database/record/index.js").default} */ (modelClass)
+}

package/src/testing/factory/node/load-definitions.js

@@ -0,0 +1,103 @@
+// @ts-check
+
+import {pathToFileURL} from "node:url"
+import {readdir, stat} from "node:fs/promises"
+import path from "node:path"
+
+/**
+ * Monotonic cache-busting counter shared by reloads. Kept module-local so a reload
+ * imports a fresh module instance rather than the cached one.
+ * @type {number}
+ */
+let reloadCounter = 0
+
+/**
+ * Recursively collects `.js` files under a directory in a deterministic
+ * (lexicographically sorted) order.
+ * @param {string} directory - Directory to scan.
+ * @returns {Promise<string[]>} - Sorted absolute file paths.
+ */
+async function collectDirectoryFiles(directory) {
+  const entries = await readdir(directory, {withFileTypes: true})
+  /** @type {string[]} */
+  const files = []
+
+  for (const entry of [...entries].sort((left, right) => (left.name < right.name ? -1 : 1))) {
+    const fullPath = path.join(directory, entry.name)
+
+    if (entry.isDirectory()) {
+      files.push(...await collectDirectoryFiles(fullPath))
+    } else if (entry.name.endsWith(".js")) {
+      files.push(fullPath)
+    }
+  }
+
+  return files
+}
+
+/**
+ * Resolves a load target (a single file, a directory, or an explicit list) into a
+ * deterministic, de-duplicated list of absolute definition file paths.
+ * @param {string | string[]} target - File path, directory, or list of paths.
+ * @returns {Promise<string[]>} - Sorted, de-duplicated absolute file paths.
+ */
+async function resolveFiles(target) {
+  if (Array.isArray(target)) {
+    return [...new Set(target.map((entry) => path.resolve(entry)))].sort()
+  }
+
+  const resolved = path.resolve(target)
+  const stats = await stat(resolved)
+
+  if (stats.isDirectory()) return await collectDirectoryFiles(resolved)
+
+  return [resolved]
+}
+
+/**
+ * Loads Velocious factory definition files (Node only). Each file must
+ * default-export a `(registry) => void` function that defines into the registry.
+ * Files load in deterministic path order. This module is intentionally Node-only
+ * (filesystem + dynamic import) and must never be imported from browser/Metro
+ * bundles; import the browser-safe core from `../index.js` there instead.
+ * @param {import("../factory-registry.js").default} registry - Registry to define into.
+ * @param {string | string[]} target - File path, directory, or list of paths.
+ * @param {{reload?: boolean}} [options] - Options.
+ * @returns {Promise<string[]>} - The loaded file paths, in load order.
+ */
+export async function loadDefinitions(registry, target, {reload = false} = {}) {
+  const files = await resolveFiles(target)
+
+  for (const file of files) {
+    let href = pathToFileURL(file).href
+
+    if (reload) {
+      reloadCounter += 1
+      href += `?factoryReload=${reloadCounter}`
+    }
+
+    const module = await import(href)
+
+    if (typeof module.default !== "function") {
+      throw new Error(`Factory definition file ${file} must default-export a (registry) => void function`)
+    }
+
+    module.default(registry)
+  }
+
+  return files
+}
+
+/**
+ * Fully reloads definitions: resets the registry (dropping every factory, trait,
+ * sequence, callback and default) and re-imports the target files with cache
+ * busting so edited definitions take effect.
+ * @param {import("../factory-registry.js").default} registry - Registry to reload.
+ * @param {string | string[]} target - File path, directory, or list of paths.
+ * @returns {Promise<string[]>} - The reloaded file paths, in load order.
+ */
+export async function reloadDefinitions(registry, target) {
+  registry.reset()
+
+  return await loadDefinitions(registry, target, {reload: true})
+}

package/src/testing/factory/sequence.js

@@ -0,0 +1,91 @@
+// @ts-check
+
+/**
+ * SequenceFormatter type. Receives the synchronously-allocated numeric value and
+ * returns the formatted value (optionally asynchronously).
+ * @typedef {(args: {value: number}) => (? | Promise<?>)} SequenceFormatter
+ */
+
+/**
+ * A numeric counter sequence. Values are allocated and consumed synchronously
+ * before the (possibly async) formatter runs, so a rejected formatter still
+ * advances the counter and concurrent `Promise.all` allocation never collides —
+ * matching FactoryBot's failed-value-consumption behaviour.
+ */
+export default class Sequence {
+  /**
+   * Builds a sequence.
+   * @param {object} args - Options.
+   * @param {string} args.name - Primary sequence name.
+   * @param {number} [args.initial] - First value the sequence yields. Defaults to 1.
+   * @param {SequenceFormatter} [args.formatter] - Optional formatter for the value.
+   * @param {string[]} [args.aliases] - Additional names that share this sequence's state.
+   */
+  constructor({name, initial = 1, formatter, aliases = []}) {
+    /** @type {string} - Primary sequence name. */
+    this.name = name
+
+    /** @type {number} - First value the sequence yields. */
+    this.initial = initial
+
+    /** @type {SequenceFormatter | undefined} - Optional value formatter. */
+    this.formatter = formatter
+
+    /** @type {string[]} - Names that share this sequence's counter. */
+    this.aliases = aliases
+
+    /** @type {number} - Next value to allocate. */
+    this._next = initial
+  }
+
+  /**
+   * Allocates and consumes the next numeric value synchronously.
+   * @returns {number} - The allocated raw value.
+   */
+  _allocate() {
+    const value = this._next
+
+    this._next += 1
+
+    return value
+  }
+
+  /**
+   * Advances the sequence and returns the formatted value. The numeric value is
+   * consumed synchronously before awaiting the formatter, so a rejected formatter
+   * still advances the counter.
+   * @returns {Promise<?>} - The formatted value.
+   */
+  async next() {
+    const value = this._allocate()
+
+    if (!this.formatter) return value
+
+    return await this.formatter({value})
+  }
+
+  /**
+   * Returns the value the next `next()` call will allocate without consuming it.
+   * @returns {number} - The upcoming raw value.
+   */
+  peek() {
+    return this._next
+  }
+
+  /**
+   * Sets the next value the sequence will allocate.
+   * @param {number} value - Next raw value.
+   * @returns {void}
+   */
+  set(value) {
+    this._next = value
+  }
+
+  /**
+   * Resets the counter back to its initial value.
+   * @returns {void}
+   */
+  rewind() {
+    this._next = this.initial
+  }
+}

package/src/testing/factory/strategies/attributes-for.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+import BaseStrategy from "./base.js"
+
+/**
+ * The `attributesFor` strategy. It resolves scalar/lazy attributes (and any
+ * transients they depend on) but never initializes the model, runs lifecycle
+ * callbacks, or evaluates/builds declared associations. Transients and
+ * associations are omitted from the returned plain object.
+ */
+export default class AttributesForStrategy 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<Record<string, ?>>} - The resolved attributes.
+   */
+  async run({registry, plan}) {
+    const context = this._newContext(registry, plan, "attributesFor")
+
+    return await context.resolveAttributes()
+  }
+}