velocious 1.0.430 → 1.0.432

package/src/database/record/state-machine.js

@@ -0,0 +1,278 @@
+// @ts-check
+
+/**
+ * Defines this typedef.
+ * @typedef {{
+ *   column?: string,
+ *   initial: string,
+ *   states: Record<string, StateDefinition>,
+ *   events: Record<string, EventDefinition>
+ * }} StateMachineDefinition
+ * @typedef {{
+ *   beforeEnter?: (model: import("./index.js").default) => void | Promise<void>,
+ *   afterEnter?: (model: import("./index.js").default) => void | Promise<void>
+ * }} StateDefinition
+ * @typedef {{
+ *   from: string | string[],
+ *   to: string,
+ *   guard?: (model: import("./index.js").default) => boolean | Promise<boolean>,
+ *   before?: (model: import("./index.js").default) => void | Promise<void>,
+ *   after?: (model: import("./index.js").default) => void | Promise<void>
+ * }} EventDefinition
+ */
+
+/**
+ * Pending transition key.
+  @type {string} */
+const PENDING_TRANSITION_KEY = "_stateMachinePendingTransition"
+
+/**
+ * Registers a state machine on a Velocious model class.
+ *
+ * Usage:
+ * ```js
+ * import {stateMachine} from "velocious/build/src/database/record/state-machine.js"
+ *
+ * class Build extends BuildBase {}
+ *
+ * stateMachine(Build, {
+ *   column: "status",
+ *   initial: "new",
+ *   states: {
+ *     new: {},
+ *     queued: {beforeEnter: (build) => { build.setQueuedAt(new Date()) }},
+ *     running: {beforeEnter: (build) => { build.setStartedAt(new Date()) }},
+ *     failed: {beforeEnter: (build) => { build.setEndedAt(new Date()) }},
+ *     succeeded: {beforeEnter: (build) => { build.setEndedAt(new Date()) }}
+ *   },
+ *   events: {
+ *     queue: {from: "new", to: "queued"},
+ *     run: {from: ["new", "queued", "crashed"], to: "running"},
+ *     fail: {from: ["new", "queued", "running"], to: "failed"},
+ *     succeed: {from: "running", to: "succeeded"},
+ *     cancel: {from: ["new", "queued", "running"], to: "cancelled", guard: (build) => !build.isNewRecord()}
+ *   }
+ * })
+ * ```
+ * @param {typeof import("./index.js").default} ModelClass - The model class to add state machine behavior to.
+ * @param {StateMachineDefinition} definition - The state machine definition.
+ * @returns {void}
+ */
+export function stateMachine(ModelClass, definition) {
+  const column = definition.column || "state"
+  const stateNames = Object.keys(definition.states)
+
+  // Store definition on the model class for introspection
+  /**
+   * Dynamic class.
+    @type {?} */
+  const dynamicClass = ModelClass
+
+  dynamicClass._stateMachineDefinition = definition
+  dynamicClass._stateMachineColumn = column
+
+  /**
+   * Returns the registered state machine definition.
+   * @returns {StateMachineDefinition} - The registered state machine definition.
+   */
+  dynamicClass.getStateMachineDefinition = function () {
+    return dynamicClass._stateMachineDefinition
+  }
+
+  /**
+   * Returns the state column name.
+   * @returns {string} - The column name used for state storage.
+   */
+  dynamicClass.getStateMachineColumn = function () {
+    return dynamicClass._stateMachineColumn
+  }
+
+  /**
+   * Returns all declared state names.
+   * @returns {string[]} - All declared state names.
+   */
+  dynamicClass.getStateMachineStateNames = function () {
+    return stateNames
+  }
+
+  // Register event methods and guard methods on the prototype
+  /**
+   * Proto.
+    @type {?} */
+  const proto = ModelClass.prototype
+
+  for (const [eventName, eventDef] of Object.entries(definition.events)) {
+    const fromStates = Array.isArray(eventDef.from) ? eventDef.from : [eventDef.from]
+    const capitalizedEvent = eventName.charAt(0).toUpperCase() + eventName.slice(1)
+    const canMethodName = `can${capitalizedEvent}`
+    const setterName = columnSetterName(column)
+
+    // Guard method: canQueue(), canRun(), etc.
+    proto[canMethodName] = function () {
+      const currentState = this.readAttribute(column)
+
+      if (!fromStates.includes(currentState)) {
+        return false
+      }
+
+      if (eventDef.guard) {
+        const guardResult = eventDef.guard(this)
+
+        if (guardResult instanceof Promise) {
+          throw new Error(`Guard for event "${eventName}" returned a Promise. Use await model.can${capitalizedEvent}Async() instead.`)
+        }
+
+        return guardResult
+      }
+
+      return true
+    }
+
+    // Async guard method: canQueueAsync(), canRunAsync(), etc.
+    proto[`${canMethodName}Async`] = async function () {
+      const currentState = this.readAttribute(column)
+
+      if (!fromStates.includes(currentState)) {
+        return false
+      }
+
+      if (eventDef.guard) {
+        return await eventDef.guard(this)
+      }
+
+      return true
+    }
+
+    // Transition method: queue(), run(), etc. — checks guard, sets the state, stashes event name
+    proto[eventName] = function () {
+      /**
+       * Self.
+        @type {?} */
+      const self = this
+      const currentState = self.readAttribute(column)
+
+      if (!fromStates.includes(currentState)) {
+        throw new Error(
+          `Cannot transition "${eventName}" from "${currentState}" on ${self.getModelClass().name}. ` +
+          `Allowed source states: ${fromStates.join(", ")}`
+        )
+      }
+
+      // Enforce synchronous guard before mutating state
+      if (eventDef.guard) {
+        const guardResult = eventDef.guard(self)
+
+        if (guardResult instanceof Promise) {
+          throw new Error(`Guard for event "${eventName}" returned a Promise. Use await model.${eventName}AndSave() for async guards.`)
+        }
+
+        if (!guardResult) {
+          throw new Error(
+            `Guard rejected transition "${eventName}" from "${currentState}" on ${self.getModelClass().name}.`
+          )
+        }
+      }
+
+      // Stash the transition so beforeSave/afterSave know which event was invoked
+      self[PENDING_TRANSITION_KEY] = {eventName, from: currentState, to: eventDef.to}
+      self[setterName](eventDef.to)
+    }
+
+    // Bang method: queueAndSave(), runAndSave(), etc. — transitions AND saves (supports async guards)
+    proto[`${eventName}AndSave`] = async function () {
+      /**
+       * Self.
+        @type {?} */
+      const self = this
+      const currentState = self.readAttribute(column)
+
+      if (!fromStates.includes(currentState)) {
+        throw new Error(
+          `Cannot transition "${eventName}" from "${currentState}" on ${self.getModelClass().name}. ` +
+          `Allowed source states: ${fromStates.join(", ")}`
+        )
+      }
+
+      // Enforce async guard before mutating state
+      if (eventDef.guard) {
+        const allowed = await eventDef.guard(self)
+
+        if (!allowed) {
+          throw new Error(
+            `Guard rejected transition "${eventName}" from "${currentState}" on ${self.getModelClass().name}.`
+          )
+        }
+      }
+
+      self[PENDING_TRANSITION_KEY] = {eventName, from: currentState, to: eventDef.to}
+      self[setterName](eventDef.to)
+      await self.save()
+    }
+  }
+
+  // Register a beforeSave callback that fires state-enter hooks
+  ModelClass.beforeSave(async function (model) {
+    /**
+     * Dynamic model.
+      @type {?} */
+    const dynamicModel = model
+    const pending = dynamicModel[PENDING_TRANSITION_KEY]
+
+    if (!pending) {
+      return
+    }
+
+    const eventDef = definition.events[pending.eventName]
+
+    // Run event-level before callback
+    if (eventDef?.before) {
+      await eventDef.before(model)
+    }
+
+    // Run state-level beforeEnter callback
+    const stateDefinition = definition.states[pending.to]
+
+    if (stateDefinition?.beforeEnter) {
+      await stateDefinition.beforeEnter(model)
+    }
+  })
+
+  // Register an afterSave callback for afterEnter hooks
+  ModelClass.afterSave(async function (model) {
+    /**
+     * Dynamic model.
+      @type {?} */
+    const dynamicModel = model
+    const pending = dynamicModel[PENDING_TRANSITION_KEY]
+
+    if (!pending) {
+      return
+    }
+
+    // Clear the pending transition now that save is complete
+    dynamicModel[PENDING_TRANSITION_KEY] = null
+
+    // Run state-level afterEnter callback
+    const stateDefinition = definition.states[pending.to]
+
+    if (stateDefinition?.afterEnter) {
+      await stateDefinition.afterEnter(model)
+    }
+
+    // Run event-level after callback
+    const eventDef = definition.events[pending.eventName]
+
+    if (eventDef?.after) {
+      await eventDef.after(model)
+    }
+  })
+}
+
+/**
+ * Returns the setter method name for a column (e.g., "status" → "setStatus", "state" → "setState").
+ * @param {string} column - The column name.
+ * @returns {string} - The setter method name.
+ */
+function columnSetterName(column) {
+  return `set${column.charAt(0).toUpperCase()}${column.slice(1)}`
+}

package/src/database/record/user-module.js

@@ -0,0 +1,43 @@
+// @ts-check
+
+import bcryptjs from "bcryptjs"
+import restArgsError from "../../utils/rest-args-error.js"
+
+export default class UserModule {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} args.secretKey - Secret key.
+   */
+  constructor({secretKey, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!secretKey) throw new Error(`Invalid secret key given: ${secretKey}`)
+
+    this.secretKey = secretKey
+  }
+
+  /**
+   * Runs attach to.
+   * @param {typeof import("./index.js").default} UserClass - User class.
+   */
+  attachTo(UserClass) {
+    // @ts-expect-error
+    UserClass.prototype.setPassword = function(newPassword) {
+      const salt = bcryptjs.genSaltSync(10)
+      const encryptedPassword = bcryptjs.hashSync(newPassword, salt)
+
+      // @ts-expect-error
+      this.setEncryptedPassword(encryptedPassword)
+    }
+
+    // @ts-expect-error
+    UserClass.prototype.setPasswordConfirmation = function(newPasswordConfirmation) {
+      const salt = bcryptjs.genSaltSync(10)
+      const encryptedPassword = bcryptjs.hashSync(newPasswordConfirmation, salt)
+
+      // @ts-expect-error
+      this._encryptedPasswordConfirmation = encryptedPassword
+    }
+  }
+}

package/src/database/record/validators/base.js

@@ -0,0 +1,27 @@
+// @ts-check
+
+export default class VelociousDatabaseRecordValidatorsBase {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {string} args.attributeName - Attribute name.
+   * @param {Record<string, ?>} args.args - Options object.
+   */
+  constructor({attributeName, args}) {
+    this.attributeName = attributeName
+    this.args = args
+  }
+
+  /**
+   * Runs validate.
+   * @abstract
+   * @param {object} args - Options object.
+   * @param {import("../index.js").default} args.model - Model instance.
+   * @param {string} args.attributeName - Attribute name.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async validate({model, attributeName}) { // eslint-disable-line no-unused-vars
+    throw new Error("validate not implemented")
+  }
+}
+

package/src/database/record/validators/format.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+import Base from "./base.js"
+
+export default class VelociousDatabaseRecordValidatorsFormat extends Base {
+  /**
+   * Runs validate.
+   * @param {object} args - Options object.
+   * @param {import("../index.js").default} args.model - Model instance.
+   * @param {string} args.attributeName - Attribute name.
+   * @returns {Promise<void>}
+   */
+  async validate({model, attributeName}) {
+    const value = model.readAttribute(attributeName)
+
+    // Rails parity: `allow_blank: true` skips the format check for
+    // blank/null/undefined values. Default to false (same as Rails).
+    const allowBlank = this.args?.allowBlank === true
+
+    if (value == null || (typeof value === "string" && value.trim() === "")) {
+      if (allowBlank) return
+
+      if (!(attributeName in model._validationErrors)) model._validationErrors[attributeName] = []
+
+      model._validationErrors[attributeName].push({type: "format", message: "is invalid"})
+
+      return
+    }
+
+    const pattern = this.args?.with
+
+    if (!(pattern instanceof RegExp)) {
+      throw new Error(`validates format requires a 'with' option that is a RegExp, got: ${typeof pattern}`)
+    }
+
+    const stringValue = String(value)
+
+    // Reset lastIndex so stateful flags (g, y) on a shared RegExp
+    // instance don't cause nondeterministic pass/fail across calls.
+    pattern.lastIndex = 0
+
+    if (!pattern.test(stringValue)) {
+      const message = typeof this.args?.message === "string" ? this.args.message : "is invalid"
+
+      if (!(attributeName in model._validationErrors)) model._validationErrors[attributeName] = []
+
+      model._validationErrors[attributeName].push({type: "format", message})
+    }
+  }
+}

package/src/database/record/validators/presence.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+import Base from "./base.js"
+
+export default class VelociousDatabaseRecordValidatorsPresence extends Base {
+  /**
+   * Runs validate.
+   * @param {object} args - Options object.
+   * @param {import("../index.js").default} args.model - Model instance.
+   * @param {string} args.attributeName - Attribute name.
+   */
+  async validate({model, attributeName}) {
+    const rawValue = /**
+                      * Narrows the runtime value to the documented type.
+                       @type {string | undefined} */ (model.readAttribute(attributeName))
+    const attributeValue = rawValue?.trim()
+
+    if (!attributeValue) {
+      if (!(attributeName in model._validationErrors)) model._validationErrors[attributeName] = []
+
+      model._validationErrors[attributeName].push({type: "presence", message: "can't be blank"})
+    }
+  }
+}

package/src/database/record/validators/uniqueness.js

@@ -0,0 +1,124 @@
+// @ts-check
+
+import Base from "./base.js"
+import * as inflection from "inflection"
+
+export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
+  /**
+   * Runs validate.
+   * @param {object} args - Options object.
+   * @param {import("../index.js").default} args.model - Model instance.
+   * @param {string} args.attributeName - Attribute name.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async validate({model, attributeName}) {
+    const modelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof import("../index.js").default} */ (model.constructor)
+
+    const connection = modelClass.connection()
+    const tableName = modelClass._getTable().getName()
+    const attributeValue = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {string | number} */ (model.readAttribute(attributeName))
+    const attributeNameUnderscore = inflection.underscore(attributeName)
+
+    /**
+     * Where args.
+      @type {Record<string, string | number>} */
+    const whereArgs = {}
+
+    whereArgs[attributeNameUnderscore] = attributeValue
+
+    // Rails parity: `validates :attr, uniqueness: {scope: :other}` adds
+    // the scoped column(s) to the WHERE clause so uniqueness is checked
+    // within the given scope (e.g. `role` unique per `userId`).
+    const scopeColumns = this._normalizeScopeColumns()
+
+    for (const scopeColumn of scopeColumns) {
+      const scopeUnderscore = inflection.underscore(scopeColumn)
+      let scopeValue = model.readAttribute(scopeColumn)
+
+      // When the FK hasn't been flushed from the relationship object
+      // onto the attribute store yet (e.g. `new Task({project})` where
+      // `projectId` is still undefined), try resolving it from the
+      // loaded belongsTo relationship instead.
+      if (scopeValue == null) {
+        scopeValue = this._resolveScopeValueFromRelationship(model, scopeColumn)
+      }
+
+      if (scopeValue == null) return
+
+      whereArgs[scopeUnderscore] = /**
+                                    * Narrows the runtime value to the documented type.
+                                     @type {string | number} */ (scopeValue)
+    }
+
+    let existingRecordQuery = modelClass
+      .select(modelClass.primaryKey())
+      .where(whereArgs)
+
+    if (model.isPersisted()) {
+      existingRecordQuery.where(`${connection.quoteTable(tableName)}.${connection.quoteColumn(modelClass.primaryKey())} != ${connection.quote(model.id())}`)
+    }
+
+    const existingRecord = await existingRecordQuery.first()
+
+    if (existingRecord) {
+      if (!(attributeName in model._validationErrors)) model._validationErrors[attributeName] = []
+
+      model._validationErrors[attributeName].push({type: "uniqueness", message: "has already been taken"})
+    }
+  }
+
+  /**
+   * Try to resolve a scope column value from a loaded belongsTo
+   * relationship on the model. When a Task is created via
+   * `new Task({project})`, the FK (`projectId`) is only flushed onto
+   * the attribute store during save — but the relationship object is
+   * already loaded and carries the id we need for the WHERE clause.
+   * @param {import("../index.js").default} model
+   * @param {string} scopeColumn - camelCase attribute name (e.g. `"projectId"`).
+   * @returns {string | number | null}
+   */
+  _resolveScopeValueFromRelationship(model, scopeColumn) {
+    const modelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof import("../index.js").default} */ (model.constructor)
+    const relationships = modelClass.getRelationshipsMap()
+
+    for (const relationshipName in relationships) {
+      const relationship = relationships[relationshipName]
+
+      if (relationship.getType?.() !== "belongsTo") continue
+
+      const foreignKey = inflection.camelize(relationship.getForeignKey(), true)
+
+      if (foreignKey !== scopeColumn) continue
+
+      const instanceRelationship = model.getRelationshipByName(relationshipName)
+      const loaded = instanceRelationship.loaded()
+
+      if (loaded && !Array.isArray(loaded) && typeof loaded.id === "function") {
+        return loaded.id()
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Normalize the `scope` option into an array of attribute names.
+   * Supports string (`"userId"`), array of strings (`["userId", "projectId"]`),
+   * or absent (empty array — no scope, original single-column behavior).
+   * @returns {string[]}
+   */
+  _normalizeScopeColumns() {
+    const scope = this.args?.scope
+
+    if (!scope) return []
+    if (Array.isArray(scope)) return scope
+
+    return [String(scope)]
+  }
+}