velocious 1.0.441 → 1.0.443

package/src/environment-handlers/node/cli/commands/lint/relationships.js

@@ -0,0 +1,144 @@
+// @ts-check
+
+import BaseCommand from "../../../../../cli/base-command.js"
+import fs from "node:fs/promises"
+import path from "node:path"
+
+/**
+ * Lints model relationships: every non-polymorphic belongs-to relationship should have an inverse
+ * has-many or has-one relationship declared on its target model class. A missing inverse usually
+ * means the target model was never told about the association (e.g. an Event model missing
+ * `hasMany("priceCategorySettings")` while PriceCategorySetting declares `belongsTo("event")`).
+ *
+ * Specific relationships can be ignored through a JSON config file (default:
+ * `relationship-lint.json` in the project directory, overridable with `--config <path>`):
+ *
+ *   {"ignore": ["PriceCategorySetting#event"]}
+ *
+ * where each entry is `<model class name>#<belongs-to relationship name>`.
+ */
+export default class VelociousCliCommandsLintRelationships extends BaseCommand {
+  /**
+   * Runs execute.
+   * @returns {Promise<{offences: Array<{ignoreKey: string, message: string}>}>} - Resolves with the found offences (empty when the lint passes).
+   */
+  async execute() {
+    // Relationship target resolution (getTargetModelClass) looks model classes up through the
+    // current configuration, so make this command's configuration the current one.
+    this.getConfiguration().setCurrent()
+
+    await this.getConfiguration().initializeModels()
+
+    const ignoredRelationships = await this._loadIgnoredRelationships()
+    const offences = []
+    const modelClasses = Object.values(this.getConfiguration().getModelClasses())
+
+    for (const modelClass of modelClasses) {
+      for (const relationship of modelClass.getRelationships()) {
+        if (relationship.getType() != "belongsTo") continue
+        if (relationship.getPolymorphic()) continue
+
+        const ignoreKey = `${modelClass.name}#${relationship.getRelationshipName()}`
+
+        if (ignoredRelationships.has(ignoreKey)) continue
+
+        let targetModelClass
+
+        try {
+          targetModelClass = relationship.getTargetModelClass()
+        } catch (error) {
+          offences.push({
+            ignoreKey,
+            message: `${ignoreKey}: couldn't resolve the target model class: ${error instanceof Error ? error.message : error}`
+          })
+
+          continue
+        }
+
+        if (!targetModelClass) {
+          offences.push({ignoreKey, message: `${ignoreKey}: couldn't resolve the target model class`})
+
+          continue
+        }
+
+        const inverseRelationship = targetModelClass.getRelationships().find((candidate) => {
+          if (candidate.getType() != "hasMany" && candidate.getType() != "hasOne") return false
+          if (candidate.through) return false
+
+          try {
+            return candidate.getTargetModelClass() === modelClass
+          } catch {
+            // A has-many/has-one with an unresolvable target can't be the inverse of this belongs-to.
+            // It is reported separately when its own model's belongs-to relationships are linted.
+            return false
+          }
+        })
+
+        if (inverseRelationship) continue
+
+        offences.push({
+          ignoreKey,
+          message: `${targetModelClass.name} is missing an inverse hasMany/hasOne relationship for ${ignoreKey} (belongsTo). ` +
+            `Declare the inverse on ${targetModelClass.name} or add "${ignoreKey}" to the ignore config.`
+        })
+      }
+    }
+
+    for (const offence of offences) {
+      console.error(offence.message)
+    }
+
+    if (offences.length > 0) {
+      throw new Error(`Relationship lint failed with ${offences.length} offence(s):\n${offences.map((offence) => offence.message).join("\n")}`)
+    }
+
+    console.log(`Relationship lint passed for ${modelClasses.length} model(s).`)
+
+    return {offences}
+  }
+
+  /**
+   * Loads the ignored relationship keys from the lint config file. The file is optional; when the
+   * default path doesn't exist, no relationships are ignored. An explicitly passed `--config` path
+   * must exist.
+   * @returns {Promise<Set<string>>} - Ignored `<model>#<relationship>` keys.
+   */
+  async _loadIgnoredRelationships() {
+    const configArgIndex = this.processArgs?.indexOf("--config") ?? -1
+    const explicitConfigPath = configArgIndex >= 0 ? this.processArgs?.[configArgIndex + 1] : undefined
+
+    if (configArgIndex >= 0 && !explicitConfigPath) {
+      throw new Error("--config was given without a path argument")
+    }
+
+    const configPath = explicitConfigPath
+      ? path.resolve(this.directory(), explicitConfigPath)
+      : path.join(this.directory(), "relationship-lint.json")
+
+    let configContent
+
+    try {
+      configContent = await fs.readFile(configPath, "utf8")
+    } catch (error) {
+      if (!explicitConfigPath && /** @type {NodeJS.ErrnoException} */ (error).code == "ENOENT") {
+        return new Set()
+      }
+
+      throw error
+    }
+
+    const config = JSON.parse(configContent)
+
+    if (config === null || typeof config != "object" || Array.isArray(config)) {
+      throw new Error(`Relationship lint config must be a JSON object: ${configPath}`)
+    }
+
+    const ignore = config.ignore ?? []
+
+    if (!Array.isArray(ignore) || ignore.some((entry) => typeof entry != "string")) {
+      throw new Error(`Relationship lint config "ignore" must be an array of "<model>#<relationship>" strings: ${configPath}`)
+    }
+
+    return new Set(ignore)
+  }
+}

package/src/environment-handlers/node.js

@@ -8,6 +8,7 @@ import CliCommandsGenerateBaseModels from "./node/cli/commands/generate/base-mod
 import CliCommandsGenerateFrontendModels from "./node/cli/commands/generate/frontend-models.js"
 import CliCommandsGenerateMigration from "./node/cli/commands/generate/migration.js"
 import CliCommandsGenerateModel from "./node/cli/commands/generate/model.js"
+import CliCommandsLintRelationships from "./node/cli/commands/lint/relationships.js"
 import CliCommandsRoutes from "./node/cli/commands/routes.js"
 import CliCommandsServer from "./node/cli/commands/server.js"
 import CliCommandsTest from "./node/cli/commands/test.js"
@@ -509,6 +510,15 @@ export default class VelociousEnvironmentHandlerNode extends Base{
     return await this.forwardCommand(command, CliCommandsGenerateModel)
   }
 
+  /**
+   * Runs cli commands lint relationships.
+   * @param {import("../cli/base-command.js").default} command - Command.
+   * @returns {Promise<?>} - Resolves with the command result.
+   */
+  async cliCommandsLintRelationships(command) {
+    return await this.forwardCommand(command, CliCommandsLintRelationships)
+  }
+
   /**
    * Runs cli commands routes.
    * @param {import("../cli/base-command.js").default} command - Command.

package/src/frontend-model-resource/base-resource.js

@@ -9,7 +9,7 @@ import * as inflection from "inflection"
  * @property {import("../controller.js").default} controller - Frontend-model controller instance.
  * @property {typeof import("../database/record/index.js").default} modelClass - Backing model class.
  * @property {string} modelName - Model name.
- * @property {import("../configuration-types.js").VelociousLooseObject} params - Request params.
+ * @property {import("../configuration-types.js").VelociousParams} params - Request params.
  * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | import("../configuration-types.js").FrontendModelResourceConfiguration} resourceConfiguration - Normalized resource configuration (or raw input shape during early bootstrap).
  */
 
@@ -21,13 +21,13 @@ import * as inflection from "inflection"
  * @property {import("../configuration-types.js").VelociousLooseObject} [locals] - Ability locals.
  * @property {typeof import("../database/record/index.js").default} [modelClass] - Optional backing model class override.
  * @property {string} [modelName] - Optional model name override.
- * @property {import("../configuration-types.js").VelociousLooseObject} [params] - Optional params override.
+ * @property {import("../configuration-types.js").VelociousParams} [params] - Optional params override.
  * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | import("../configuration-types.js").FrontendModelResourceConfiguration} [resourceConfiguration] - Optional normalized resource configuration.
  */
 
 /**
  * Base class for backend frontend-model resources.
- * @template {typeof import("../database/record/index.js").default} [out TModelClass=typeof import("../database/record/index.js").default]
+ * @template {typeof import("../database/record/index.js").default} [TModelClass=typeof import("../database/record/index.js").default]
  */
 export default class FrontendModelBaseResource extends AuthorizationBaseResource {
   /**
@@ -99,10 +99,10 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Runs typed controller instance.
    * @returns {import("../controller.js").default & {
-   *   frontendModelAuthorizedQuery: (action: "index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url") => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
+   *   frontendModelAuthorizedQuery: (action: "index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url") => import("../database/query/model-class-query.js").default<TModelClass>,
    *   frontendModelAbilityAction: (action: string) => string,
    *   currentAbility: () => import("../authorization/ability.js").default | undefined,
-   *   frontendModelIndexQuery: () => import("../database/query/model-class-query.js").default<typeof import("../database/record/index.js").default>,
+   *   frontendModelIndexQuery: () => import("../database/query/model-class-query.js").default<TModelClass>,
    *   frontendModelPreload: () => import("../database/query/index.js").NestedPreloadRecord | null,
    *   serializeFrontendModel: (model: import("../database/record/index.js").default) => Promise<Record<string, unknown>>
    * }} - Controller instance with frontend-model helpers.
@@ -176,9 +176,9 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
 
   /**
    * Runs params.
-   * @returns {import("../configuration-types.js").VelociousLooseObject} - Params.
+   * @returns {import("../configuration-types.js").VelociousParams} - Params.
    */
-  params() { return this.paramsValue || super.params() || {} }
+  params() { return /** @type {import("../configuration-types.js").VelociousParams} */ (this.paramsValue || super.params() || {}) }
 
   /**
    * Runs resource configuration.
@@ -243,11 +243,10 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Runs authorized query.
    * @param {"index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url"} action - Ability action.
-   * @template {typeof import("../database/record/index.js").default} [MC=typeof import("../database/record/index.js").default]
-   * @returns {import("../database/query/model-class-query.js").default<MC>} - Authorized query.
+   * @returns {import("../database/query/model-class-query.js").default<TModelClass>} - Authorized query.
    */
   authorizedQuery(action) {
-    return /** Narrows the authorized query to the resource's model class. @type {import("../database/query/model-class-query.js").default<MC>} */ (this.typedControllerInstance().frontendModelAuthorizedQuery(action))
+    return this.typedControllerInstance().frontendModelAuthorizedQuery(action)
   }
 
 

package/src/frontend-models/base.js

@@ -2660,8 +2660,8 @@ export default class FrontendModelBase {
    * `openConnection`. Apps use this for per-session state/messaging
    * that doesn't fit the pub/sub Channel model (locale, presence).
    * @param {string} connectionType - Name the server registered the class under.
-   * @param {{params?: Record<string, ?>, onConnect?: () => void, onMessage?: (body: ?) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options and event handlers.
-   * @returns {?} - VelociousWebsocketClientConnection handle (typed loosely to avoid a cross-module import cycle).
+   * @param {{params?: Record<string, ?>, onConnect?: () => void, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options and event handlers.
+   * @returns {{ready: Promise<void>, close: () => void}} - Websocket connection handle.
    */
   static openWebsocketConnection(connectionType, options) {
     const client = /**
@@ -2679,8 +2679,8 @@ export default class FrontendModelBase {
    * Subscribes to a pub/sub `WebsocketChannel`. Thin wrapper around
    * the internal client's `subscribeChannel`.
    * @param {string} channelType - Channel class name registered on the server.
-   * @param {{params?: Record<string, ?>, onMessage?: (body: ?) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Channel subscription options and event handlers.
-   * @returns {?} - Websocket channel handle from the configured client.
+   * @param {{params?: Record<string, ?>, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Channel subscription options and event handlers.
+   * @returns {{ready: Promise<void>, close: () => void}} - Websocket channel handle from the configured client.
    */
   static subscribeWebsocketChannel(channelType, options) {
     const client = /**
@@ -3200,7 +3200,7 @@ export default class FrontendModelBase {
    * Runs sort.
    * @template {typeof FrontendModelBase} T
    * @this {T}
-   * @param {string | string[] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
+   * @param {string | string[] | string[][] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
    * @returns {FrontendModelQuery<T>} - Query builder with sort definitions.
    */
   static sort(sort) {
@@ -3211,7 +3211,7 @@ export default class FrontendModelBase {
    * Runs order.
    * @template {typeof FrontendModelBase} T
    * @this {T}
-   * @param {string | string[] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
+   * @param {string | string[] | string[][] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
    * @returns {FrontendModelQuery<T>} - Query builder with sort definitions.
    */
   static order(sort) {

package/src/frontend-models/query.js

@@ -1414,7 +1414,7 @@ export default class FrontendModelQuery {
 
   /**
    * Runs sort.
-   * @param {string | string[] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
+   * @param {string | string[] | string[][] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
    * @returns {this} - Query with appended sort definitions.
    */
   sort(sort) {
@@ -1425,7 +1425,7 @@ export default class FrontendModelQuery {
 
   /**
    * Runs order.
-   * @param {string | string[] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} order - Order definition(s).
+   * @param {string | string[] | string[][] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} order - Order definition(s).
    * @returns {this} - Query with appended sort definitions.
    */
   order(order) {

package/src/utils/is-date.js

@@ -0,0 +1,13 @@
+// @ts-check
+
+/**
+ * Whether the value is a Date, including Dates created in another JS realm (e.g. the velocious
+ * console REPL context or a node:vm context), where `instanceof Date` is false because the other
+ * realm has its own Date constructor. Without this, such a Date bypasses date normalization and SQL
+ * value conversion and ends up as an empty value in the generated SQL.
+ * @param {?} value - Value to test.
+ * @returns {value is Date} - Whether the value is a Date from any realm.
+ */
+export default function isDate(value) {
+  return value instanceof Date || Object.prototype.toString.call(value) === "[object Date]"
+}