velocious 1.0.461 → 1.0.462

package/build/database/record/instance-relationships/has-one.js

@@ -28,15 +28,11 @@ export default class VelociousDatabaseRecordHasOneInstanceRelationship extends B
    * @returns {InstanceType<TMC>} - The build.
    */
   build(data) {
-    const TargetModelClass = /**
-                              * Narrows the runtime value to the documented type.
-                              * @type {TMC} */ (this.getTargetModelClass())
+    const TargetModelClass = /** @type {TMC} */ (this.getTargetModelClass())
 
     if (!TargetModelClass) throw new Error("Can't build a new record without a target model class")
 
-    const newInstance = /**
-                         * Narrows the runtime value to the documented type.
-                         * @type {InstanceType<TMC>} */ (new TargetModelClass(data))
+    const newInstance = /** @type {InstanceType<TMC>} */ (new TargetModelClass(data))
 
     this._loaded = newInstance
 
@@ -56,12 +52,8 @@ export default class VelociousDatabaseRecordHasOneInstanceRelationship extends B
 
     const foreignKey = this.getForeignKey()
     const primaryKey = this.getPrimaryKey()
-    const primaryModelID = /**
-                            * Narrows the runtime value to the documented type.
-                            * @type {string | number} */ (this.getModel().readColumn(primaryKey))
-    const TargetModelClass = /**
-                              * Narrows the runtime value to the documented type.
-                              * @type {TMC} */ (this.getTargetModelClass())
+    const primaryModelID = /** @type {string | number} */ (this.getModel().readColumn(primaryKey))
+    const TargetModelClass = /** @type {TMC} */ (this.getTargetModelClass())
 
     if (!TargetModelClass) throw new Error("Can't load without a target model class")
 

package/build/database/record/relationships/base.js

@@ -133,11 +133,7 @@ export default class VelociousDatabaseRecordBaseRelationship {
 
     if (!scope) return query
 
-    const scopedQuery = /**
-                         * Narrows the runtime value to the documented type.
-                         * @type {T | void} */ (scope.call(query, /**
-                                                                  * Narrows the runtime value to the documented type.
-                                                                  * @type {import("../../query/model-class-query.js").default<typeof import("../index.js").default>} */ (query)))
+    const scopedQuery = /** @type {T | void} */ (scope.call(query, /** @type {import("../../query/model-class-query.js").default<typeof import("../index.js").default>} */ (query)))
 
     return scopedQuery || query
   }

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

@@ -10,9 +10,7 @@ export default class VelociousDatabaseRecordValidatorsPresence extends Base {
    * @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 rawValue = /** @type {string | undefined} */ (model.readAttribute(attributeName))
     const attributeValue = rawValue?.trim()
 
     if (!attributeValue) {

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

@@ -12,15 +12,11 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
    * @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 modelClass = /** @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 attributeValue = /** @type {string | number} */ (model.readAttribute(attributeName))
     const attributeNameUnderscore = inflection.underscore(attributeName)
 
     /**
@@ -49,9 +45,7 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
 
       if (scopeValue == null) return
 
-      whereArgs[scopeUnderscore] = /**
-                                    * Narrows the runtime value to the documented type.
-                                    * @type {string | number} */ (scopeValue)
+      whereArgs[scopeUnderscore] = /** @type {string | number} */ (scopeValue)
     }
 
     let existingRecordQuery = modelClass
@@ -82,9 +76,7 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
    * @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 modelClass = /** @type {typeof import("../index.js").default} */ (model.constructor)
     const relationships = modelClass.getRelationshipsMap()
 
     for (const relationshipName in relationships) {

package/build/environment-handlers/browser.js

@@ -229,9 +229,7 @@ export default class VelociousEnvironmentsHandlerBrowser extends Base {
     /**
      * Files.
      * @type {import("./base.js").MigrationObjectType[]} */
-    const files = /**
-                   * Narrows the runtime value to the documented type.
-                   * @type {import("./base.js").MigrationObjectType[]} */ (migrations)
+    const files = /** @type {import("./base.js").MigrationObjectType[]} */ (migrations)
 
     files.sort((migration1, migration2) => migration1.date - migration2.date)
 

package/build/environment-handlers/node/cli/commands/console.js

@@ -22,9 +22,7 @@ function buildConsoleContext({application, configuration}) {
     if (dbs[identifier]) continue
 
     const pool = configuration.getDatabasePool(identifier)
-    const poolWithGlobal = /**
-                            * Narrows the runtime value to the documented type.
-                            * @type {{getGlobalConnection?: () => import("../../../../database/drivers/base.js").default | undefined}} */ (pool)
+    const poolWithGlobal = /** @type {{getGlobalConnection?: () => import("../../../../database/drivers/base.js").default | undefined}} */ (pool)
     const globalConnection = poolWithGlobal.getGlobalConnection?.()
 
     if (globalConnection) {
@@ -65,9 +63,7 @@ function buildConsoleContext({application, configuration}) {
 function assignConsoleContext({context, replServer}) {
   Object.assign(replServer.context, context)
 
-  const modelClasses = /**
-                        * Narrows the runtime value to the documented type.
-                        * @type {Record<string, typeof import("../../../../database/record/index.js").default>} */ (
+  const modelClasses = /** @type {Record<string, typeof import("../../../../database/record/index.js").default>} */ (
     context.models || {}
   )
 

package/build/environment-handlers/node/cli/commands/db/schema/load.js

@@ -57,9 +57,7 @@ export default class DbSchemaLoad extends BaseCommand {
    * @returns {{exec: (sql: string) => Promise<?>} | undefined} - Connection with exec support.
    */
   executableConnection(db) {
-    const dbWithConnection = /**
-                              * Narrows the runtime value to the documented type.
-                              * @type {import("../../../../../../database/drivers/base.js").default & {connection?: ?}} */ (db)
+    const dbWithConnection = /** @type {import("../../../../../../database/drivers/base.js").default & {connection?: ?}} */ (db)
     const connection = dbWithConnection.connection
 
     if (connection && typeof connection == "object" && "exec" in connection && typeof connection.exec == "function") {

package/build/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -397,8 +397,10 @@ export default class DbGenerateFrontendModels extends BaseCommand {
         values: memberCommands
       })
     }
-    if (modelClass && modelClass.primaryKey() !== "id") {
-      fileContent += `      primaryKey: ${JSON.stringify(modelClass.primaryKey())},\n`
+    const primaryKey = this.frontendModelPrimaryKeyForResource({attributeNames, modelClass, modelConfig})
+
+    if (primaryKey !== "id") {
+      fileContent += `      primaryKey: ${JSON.stringify(primaryKey)},\n`
     }
     const nestedRelationshipNames = this.nestedRelationshipNamesForGenerator(resourceClass || null)
     if (nestedRelationshipNames.length > 0) {
@@ -840,10 +842,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
         modelClass,
         modelName: modelClass.getModelName(),
         params: {},
-        resourceConfiguration: /**
-                                * Resource configuration.
-                                * @type {import("../../../../../configuration-types.js").FrontendModelResourceConfiguration}
-                                */ ({attributes: []})
+        resourceConfiguration: /** @type {import("../../../../../configuration-types.js").FrontendModelResourceConfiguration} */ ({attributes: []})
       })
       const spec = instance.permittedParams({action, ability: undefined, locals: {}, params: {}})
 
@@ -880,10 +879,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
         modelClass,
         modelName: modelClass.getModelName(),
         params: {},
-        resourceConfiguration: /**
-                                * Resource configuration.
-                                * @type {import("../../../../../configuration-types.js").FrontendModelResourceConfiguration}
-                                */ ({attributes: []})
+        resourceConfiguration: /** @type {import("../../../../../configuration-types.js").FrontendModelResourceConfiguration} */ ({attributes: []})
       })
       spec = instance.permittedParams()
     } catch (error) {
@@ -1095,6 +1091,66 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     return modelClass.resolveAttributeName(primaryKey) === attributeName
   }
 
+  /**
+   * Resolves the primary key from explicit resource config or the backend model.
+   * @param {{attributeNames: Array<string>, modelClass: typeof import("../../../../../database/record/index.js").default | undefined, modelConfig: import("../../../../../configuration-types.js").NormalizedFrontendModelResourceConfiguration}} args - Primary key resolution args.
+   * @returns {string | Array<string>} - Frontend-model primary key attribute name.
+   */
+  frontendModelPrimaryKeyForResource({attributeNames, modelClass, modelConfig}) {
+    if (modelConfig.primaryKey) {
+      return this.validatedConfiguredPrimaryKey({attributeNames, primaryKey: modelConfig.primaryKey})
+    }
+
+    if (!modelClass) return "id"
+
+    return this.frontendModelPrimaryKeyForModelClass({attributeNames, modelClass})
+  }
+
+  /**
+   * Validates an explicitly configured frontend-model primary key.
+   * @param {{attributeNames: Array<string>, primaryKey: string}} args - Configured primary key args.
+   * @returns {string} - Configured primary key.
+   */
+  validatedConfiguredPrimaryKey({attributeNames, primaryKey}) {
+    if (attributeNames.includes(primaryKey)) return primaryKey
+
+    throw new Error(`Configured frontend model primary key "${primaryKey}" is not a generated frontend model attribute.`)
+  }
+
+  /**
+   * Resolves the backend primary key to generated frontend-model attribute names.
+   * @param {{attributeNames: Array<string>, modelClass: typeof import("../../../../../database/record/index.js").default}} args - Primary key resolution args.
+   * @returns {string | Array<string>} - Frontend-model primary key attribute name.
+   */
+  frontendModelPrimaryKeyForModelClass({attributeNames, modelClass}) {
+    const primaryKey = modelClass.primaryKey()
+
+    if (primaryKey === "id") return "id"
+
+    if (Array.isArray(primaryKey)) {
+      return primaryKey.map((columnName) => this.frontendModelPrimaryKeyAttributeName({attributeNames, columnName, modelClass}))
+    }
+
+    return this.frontendModelPrimaryKeyAttributeName({attributeNames, columnName: primaryKey, modelClass})
+  }
+
+  /**
+   * Resolves one backend primary key column to a generated frontend-model attribute name.
+   * @param {{attributeNames: Array<string>, columnName: string, modelClass: typeof import("../../../../../database/record/index.js").default}} args - Primary key args.
+   * @returns {string} - Frontend-model primary key attribute name.
+   */
+  frontendModelPrimaryKeyAttributeName({attributeNames, columnName, modelClass}) {
+    if (attributeNames.includes(columnName)) return columnName
+
+    const attributeName = modelClass.resolveAttributeName(columnName)
+
+    if (attributeName && attributeNames.includes(attributeName)) {
+      return attributeName
+    }
+
+    throw new Error(`${modelClass.name}.primaryKey() column "${columnName}" does not resolve to a generated frontend model attribute.`)
+  }
+
   /**
    * Resolves frontend attribute config from explicit metadata, resource methods, model columns, translated columns, or model accessor JSDoc.
    * @param {object} args - Arguments.
@@ -1376,7 +1432,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
    */
   customCommandMethodSignature({commandMetadata, methodName}) {
     const metadata = commandMetadata[methodName] || {args: [], returnType: null}
-    const returnType = metadata.returnType || "Record<string, ?>"
+    const returnType = metadata.returnType || "Record<string, FrontendModelAttributeValue>"
 
     if (metadata.args.length > 0) {
       const parameterNames = metadata.args.map((arg) => arg.name)

package/build/environment-handlers/node.js

@@ -125,13 +125,14 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         const ResourceClass = imported.default
 
         if (!frontendModelResourceDefinitionIsClass(ResourceClass)) continue
+        // Skip abstract/common base resources that declare no `ModelClass` — they are
+        // not models, so they must not be recorded as discovered frontend models.
+        if (!ResourceClass.ModelClass) continue
 
         const baseName = file.replace(/\.(js|mjs)$/, "")
         const modelName = baseName.replace(/-resource$/, "")
           .split("-")
-          .map((/**
-                 * Narrows the runtime value to the documented type.
-                 * @type {string} */ part) => part.charAt(0).toUpperCase() + part.slice(1))
+          .map((/** @type {string} */ part) => part.charAt(0).toUpperCase() + part.slice(1))
           .join("")
 
         discovered[modelName] = ResourceClass
@@ -861,9 +862,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @returns {Promise<Record<string, string>>} - Resolves with SQL string.
    */
   async _structureSqlByIdentifier({dbs}) {
-    const sqlByIdentifier = /**
-                             * Narrows the runtime value to the documented type.
-                             * @type {Record<string, string>} */ ({})
+    const sqlByIdentifier = /** @type {Record<string, string>} */ ({})
 
     for (const identifier of Object.keys(dbs)) {
       const db = dbs[identifier]
@@ -890,6 +889,16 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @returns {Promise<void>} - Resolves when complete.
    */
   async initializeFrontendModelWebsocketPublishers(configuration) {
+    // Discover each backend project's resources before registering publishers. The publishers are
+    // derived from `backendProject.frontendModels`, which `autoDiscoverResources` populates. Without
+    // this, registration runs against an empty/partial resource set (only built-ins), so apps that
+    // resolve resources through an `abilityResolver` rather than a static ability-resource list never
+    // register lifecycle publishers and their realtime frontend-model updates silently stop. The
+    // lifecycle hooks are deduped per model class via a process-global set, so a later, fully
+    // discovered pass cannot retroactively add the missing publishers. `autoDiscoverResources` is
+    // idempotent (it skips backend projects whose `frontendModels` are already set).
+    await this.autoDiscoverResources(configuration)
+
     const {ensureFrontendModelWebsocketPublishersRegistered} = await import("../frontend-models/websocket-publishers.js")
 
     await ensureFrontendModelWebsocketPublishersRegistered(configuration)