velocious 1.0.450 → 1.0.452

package/README.md

@@ -392,7 +392,7 @@ Generate classes:
 npx velocious g:frontend-models
 ```
 
-When `frontendModels.*.attributes` is an object, the generator can infer JSDoc typedefs from attribute metadata (`type`/`columnType`/`sqlType`/`dataType` and `null`). If metadata is absent, the generated attribute type falls back to `any`.
+Frontend-model attributes can usually be declared by name. The generator infers JSDoc typedefs and nullability from backend model columns and translated attribute columns. When an attribute entry needs resource-specific options such as `selectedByDefault: false`, keep only that option in the resource config, for example `{name: "archivedAt", selectedByDefault: false}`; the column type and nullability are still inferred. For computed resource attributes, add a typed `${attributeName}Attribute(model)` method with an `@returns` tag in the backend project's `src` tree. Resource attribute return types take precedence over column types because the resource method controls the serialized value. If Velocious cannot infer a read attribute from a column, generated model accessor, resource method JSDoc, or explicit metadata, generation fails with a clear error instead of emitting a broad fallback type.
 
 This creates `src/frontend-models/user.js` (and one file per configured resource). Generated classes support:
 
@@ -583,7 +583,7 @@ const configuration = new Configuration({
 
 This opt-in is ignored in `production`; production frontend-model responses never include internal exception details.
 
-Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, and a small `context` object, and should only return fields that are safe for clients to see. This is useful for attaching an error-reporting URL while keeping the normal production error message generic:
+Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. This is useful for attaching an error-reporting URL while keeping the normal production error message generic:
 
 ```js
 configuration.addClientErrorPayloadReporter(async ({error, request, context}) => {
@@ -1597,7 +1597,7 @@ configuration.getErrorEvents().on("all-error", ({error, errorType}) => {
 })
 ```
 
-Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return a client-safe `Request failed.` response, but it also emits them as `framework-error`/`all-error` (with `context.frontendModelEndpoint === true`) so they are reported instead of being silently swallowed. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`) rather than the generic one, and `error.velocious`-annotated / `safeToExpose` errors keep their own message — none of these reach the error bus.
+Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return a client-safe `Request failed.` response, but it also emits them as `framework-error`/`all-error` (with `context.frontendModelEndpoint === true`) so they are reported instead of being silently swallowed. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`) rather than the generic one, and `error.velocious`-annotated / `safeToExpose` / `errorType`-marked errors keep their expected-error status — none of these reach the error bus.
 
 ## Use the Websocket client API (HTTP-like)
 

package/build/configuration-types.js

@@ -207,6 +207,29 @@
  * @typedef {Record<string, string>} VelociousParams
  */
 
+/**
+ * @typedef {Record<string, import("./frontend-models/query.js").FrontendModelTransportValue>} ClientErrorPayloadReporterPayload
+ */
+
+/**
+ * @typedef {object} ClientErrorPayloadContext
+ * @property {string} controller - Controller class name.
+ * @property {string} [action] - Controller action or endpoint label.
+ * @property {"index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url" | "custom-command"} [commandType] - Frontend-model command type.
+ * @property {boolean} [expectedError] - Whether the error is an expected user-flow failure.
+ * @property {boolean} [frontendModelEndpoint] - Whether the error came from the frontend-model endpoint.
+ * @property {string} [model] - Frontend-model name from the failed request.
+ * @property {string} [requestId] - Shared frontend-model request id.
+ */
+
+/**
+ * @typedef {function({
+ *   context: ClientErrorPayloadContext,
+ *   error: Error,
+ *   request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined
+ * }): Promise<ClientErrorPayloadReporterPayload | void> | ClientErrorPayloadReporterPayload | void} ClientErrorPayloadReporterType
+ */
+
 /**
  * @typedef {Record<string, unknown> & {configuration?: import("./configuration.js").default, currentUser?: unknown, params?: VelociousParams, request?: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default}} VelociousLooseObject
  */
@@ -263,6 +286,8 @@
  * @property {string} [columnType] - Alias for column type name.
  * @property {string} [sqlType] - Alias for column type name.
  * @property {string} [dataType] - Alias for column type name.
+ * @property {string} [jsDocType] - Exact generated JSDoc type for non-column attributes.
+ * @property {string} [name] - Attribute name when configured as an array entry.
  * @property {boolean} [null] - Whether value can be null.
  * @property {boolean} [selectedByDefault] - Whether included in default serialization. Defaults to true.
  */
@@ -274,7 +299,7 @@
 
 /**
  * @typedef {object} FrontendModelResourceConfiguration
- * @property {string[] | Record<string, FrontendModelAttributeConfiguration | import("./database/drivers/base-column.js").default | boolean>} attributes - Attributes to expose on the frontend model.
+ * @property {Array<string | FrontendModelAttributeConfiguration> | Record<string, FrontendModelAttributeConfiguration | import("./database/drivers/base-column.js").default | boolean>} attributes - Attributes to expose on the frontend model.
  * @property {string[]} [abilities] - Ability action list (camelCase action names). Defaults to `["read"]` for `find` and `index` when omitted.
  * @property {Record<string, FrontendModelAttachmentConfiguration>} [attachments] - Attachment helpers keyed by attachment name.
  * @property {string[]} [commands] - Legacy built-in command names (`index`, `find`, `create`, `update`, `destroy`, `attach`, `download`, `url`).

package/build/configuration.js

@@ -143,7 +143,7 @@ export default class VelociousConfiguration {
     this._scheduledBackgroundJobs = scheduledBackgroundJobs
     this._attachments = attachments || {}
     this._backendProjects = backendProjects || []
-    /** @type {Array<(args: {context: ?, error: Error, request: ?}) => Promise<Record<string, ?> | void> | Record<string, ?> | void>} */
+    /** @type {import("./configuration-types.js").ClientErrorPayloadReporterType[]} */
     this._clientErrorPayloadReporters = []
     this.cors = cors
     this._cookieSecret = cookieSecret
@@ -2386,7 +2386,7 @@ export default class VelociousConfiguration {
 
   /**
    * Registers a reporter that can add client-safe metadata to frontend-model error payloads.
-   * @param {(args: {context: ?, error: Error, request: ?}) => Promise<Record<string, ?> | void> | Record<string, ?> | void} reporter - Reporter callback.
+   * @param {import("./configuration-types.js").ClientErrorPayloadReporterType} reporter - Reporter callback.
    * @returns {void}
    */
   addClientErrorPayloadReporter(reporter) {
@@ -2395,11 +2395,11 @@ export default class VelociousConfiguration {
 
   /**
    * Runs registered client error payload reporters.
-   * @param {{context: ?, error: Error, request: ?}} args - Reporter args.
-   * @returns {Promise<Record<string, ?>>} - Merged client-safe reporter payload.
+   * @param {{context: import("./configuration-types.js").ClientErrorPayloadContext, error: Error, request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined}} args - Reporter args.
+   * @returns {Promise<import("./configuration-types.js").ClientErrorPayloadReporterPayload>} - Merged client-safe reporter payload.
    */
   async clientErrorPayloadForError(args) {
-    /** @type {Record<string, ?>} */
+    /** @type {import("./configuration-types.js").ClientErrorPayloadReporterPayload} */
     const payload = {}
 
     for (const reporter of this._clientErrorPayloadReporters) {