@stacksjs/defaults 0.72.57 → 0.72.60

package/ai/skills/stacks-events/SKILL.md

@@ -122,12 +122,57 @@ The `Record<EventType, unknown>` intersection allows arbitrary event names beyon
 
 ## Model Events
 
-Every model with `observe: true` trait (in defineModel) emits via `afterCreate`/`afterUpdate`/`afterDelete` hooks:
-- `'{model}:created'` -- after insert
-- `'{model}:updated'` -- after update
-- `'{model}:deleted'` -- after delete
+Every model with the `observe: true` trait emits **eight** events:
 
-Model name is lowercased: `'user:created'`, `'post:updated'`, `'order:deleted'`
+| Event | When | Payload |
+|---|---|---|
+| `{model}:saving` | before any write | the model object |
+| `{model}:creating` / `:updating` / `:deleting` | before that write | the model object |
+| `{model}:created` / `:updated` / `:deleted` | after that write | the row |
+| `{model}:saved` | after insert OR update | the row |
+
+Model name is lowercased: `'user:created'`, `'post:updated'`, `'teammember:saved'`.
+
+A **before** listener can cancel the write by returning `false`:
+
+```ts
+listen('user:deleting', (model) => {
+  if (model.attributes.email.endsWith('@example.com'))
+    return false   // the delete does not happen
+})
+```
+
+Before-events carry the model object (`.attributes` holds the row); after-events
+carry the row itself.
+
+### The payloads are typed, and nothing generates them
+
+`listen('user:created', user => user.emial)` is a compile error - the payload is
+the User row, with the columns your model declares.
+
+`storage/framework/types/model-events.d.ts` derives the whole map from the models
+barrel with a mapped type:
+
+```ts
+type ModelAfterEvents = {
+  [K in keyof Models & string as `${Lowercase<K>}:${AfterEvent}`]: ModelRow<Models[K]>
+}
+```
+
+So a model existing IS its events existing - there is no generated list to keep in
+agreement, and nothing to re-run after adding a model. (It replaced an 817-line
+generated file, and before that a hand-maintained one that listed three events per
+model and typed every payload `Record<string, any>`.)
+
+Declare your own events by augmenting `AppEvents`:
+
+```ts
+declare module '@stacksjs/events' {
+  interface AppEvents {
+    'invoice:overdue': { id: number, daysLate: number }
+  }
+}
+```
 
 Events are dispatched via lazy `import('@stacksjs/events').then(({ dispatch }) => dispatch(...))` to avoid circular dependencies. If the import fails (e.g., browser context), errors are silently caught.
 
@@ -136,8 +181,9 @@ The `observe` trait can be:
 - `['create', 'update']` -- emits only specified events
 - `false` / undefined -- no events
 
-Full model list (45+ with events defined in `storage/framework/types/events.ts`):
-Author, Page, Post, User, Activity, Campaign, Cart, CartItem, Category, Comment, Coupon, Customer, DeliveryRoute, DigitalDelivery, Driver, EmailList, GiftCard, LicenseKey, LoyaltyPoint, LoyaltyReward, Manufacturer, Notification, Order, OrderItem, Payment, PrintDevice, Product, ProductUnit, ProductVariant, Receipt, Review, ShippingMethod, ShippingRate, ShippingZone, SocialPost, Subscription, Tag, TaxRate, Transaction, WaitlistProduct, WaitlistRestaurant, Websocket
+There is no model list to keep here. Every model in `storage/framework/auto-imports/models.ts`
+has its eight events, and that barrel is generated from disk for the runtime, so the
+answer to "which models emit events" is "the ones that exist".
 
 ## Event-to-Listener Mapping (app/Events.ts)
 

package/app/Actions/AI/AskAction.ts

@@ -13,7 +13,7 @@ export default new Action({
 
   validations: {
     question: {
-      rule: schema.string().min(3).max(255),
+      rule: schema.string().min(3).max(255).required(),
       message: 'The question must be between 3 and 255 characters long.',
     },
   },

package/app/Actions/AI/SummaryAction.ts

@@ -13,7 +13,7 @@ export default new Action({
 
   validations: {
     text: {
-      rule: schema.string().min(3),
+      rule: schema.string().min(3).required(),
       message: 'The text must be at least 3 characters long.',
     },
   },

package/app/Actions/Auth/DisableTwoFactorAction.ts

@@ -10,7 +10,7 @@ export default new Action({
 
   validations: {
     password: {
-      rule: schema.string().min(1),
+      rule: schema.string().min(1).required(),
       message: 'Password is required to disable two-factor authentication.',
     },
   },

package/app/Actions/Auth/EnableTwoFactorAction.ts

@@ -10,7 +10,7 @@ export default new Action({
 
   validations: {
     code: {
-      rule: schema.string().min(6).max(6),
+      rule: schema.string().min(6).max(6).required(),
       message: 'Code must be a 6-digit TOTP code.',
     },
   },

package/app/Actions/Auth/LoginAction.ts

@@ -12,7 +12,7 @@ export default new Action({
 
   validations: {
     email: {
-      rule: schema.string().email(),
+      rule: schema.string().email().required(),
       message: 'Email must be a valid email address.',
     },
     // Presence only, NOT the creation policy. Enforcing a minimum length on
@@ -21,7 +21,7 @@ export default new Action({
     // credentials are ever checked. The policy belongs on the paths that SET a
     // password (#2226).
     password: {
-      rule: schema.string().min(1).max(PASSWORD_MAX_LENGTH),
+      rule: schema.string().min(1).max(PASSWORD_MAX_LENGTH).required(),
       message: PASSWORD_PRESENCE_MESSAGE,
     },
   },

package/app/Actions/Auth/MagicLinkConsumeAction.ts

@@ -11,7 +11,7 @@ export default new Action({
 
   validations: {
     token: {
-      rule: schema.string().min(16).max(255),
+      rule: schema.string().min(16).max(255).required(),
       message: 'Token is required.',
     },
   },

package/app/Actions/Auth/MagicLinkSendAction.ts

@@ -11,7 +11,7 @@ export default new Action({
 
   validations: {
     email: {
-      rule: schema.string().email(),
+      rule: schema.string().email().required(),
       message: 'Email must be a valid email address.',
     },
   },

package/app/Actions/Auth/RefreshTokenAction.ts

@@ -12,7 +12,7 @@ export default new Action({
 
     await request.validate({
       refresh_token: {
-        rule: schema.string().min(1),
+        rule: schema.string().min(1).required(),
         message: {
           min: 'Refresh token is required',
         },

package/app/Actions/Auth/RegisterAction.ts

@@ -12,15 +12,15 @@ export default new Action({
 
   validations: {
     email: {
-      rule: schema.string().email(),
+      rule: schema.string().email().required(),
       message: 'Email must be a valid email address.',
     },
     password: {
-      rule: schema.string().min(PASSWORD_MIN_LENGTH).max(PASSWORD_MAX_LENGTH),
+      rule: schema.string().min(PASSWORD_MIN_LENGTH).max(PASSWORD_MAX_LENGTH).required(),
       message: PASSWORD_POLICY_MESSAGE,
     },
     name: {
-      rule: schema.string().min(2).max(255),
+      rule: schema.string().min(2).max(255).required(),
       message: 'Name must be between 2 and 255 characters.',
     },
   },

package/app/Actions/Auth/VerifyTwoFactorLoginAction.ts

@@ -10,11 +10,11 @@ export default new Action({
 
   validations: {
     challenge_token: {
-      rule: schema.string().min(1),
+      rule: schema.string().min(1).required(),
       message: 'A challenge token is required.',
     },
     code: {
-      rule: schema.string().min(6).max(6),
+      rule: schema.string().min(6).max(6).required(),
       message: 'Code must be a 6-digit TOTP code.',
     },
   },

package/app/Actions/Cms/CategorizableStoreAction.ts

@@ -10,20 +10,20 @@ export default new Action({
   async handle(request: RequestInstance) {
     await request.validate({
       name: {
-        rule: schema.string(),
+        rule: schema.string().required(),
         message: {
           name: 'Name is required',
         },
       },
       description: {
-        rule: schema.string(),
+        rule: schema.string().required(),
         message: {
           description: 'Description is required',
         },
       },
 
       categorizable_type: {
-        rule: schema.string(),
+        rule: schema.string().required(),
         message: {
           categorizable_type: 'Categorizable type is required',
         },

package/app/Actions/Cms/CategorizableUpdateAction.ts

@@ -8,17 +8,23 @@ export default new Action({
   description: 'Category Update ORM Action',
   method: 'PATCH',
   async handle(request: RequestInstance) {
+    /*
+     * PATCH, so these are NOT required: a partial update sends the fields it
+     * means to change. The messages used to say "X is required", which fires on
+     * a type failure and never on absence - a message describing a rule the
+     * block does not have.
+     */
     await request.validate({
       name: {
         rule: schema.string(),
         message: {
-          name: 'Name is required',
+          name: 'Name must be a string.',
         },
       },
       description: {
         rule: schema.string(),
         message: {
-          description: 'Description is required',
+          description: 'Description must be a string.',
         },
       },
     })

package/app/Actions/Cms/CommentStoreAction.ts

@@ -10,13 +10,13 @@ export default new Action({
   async handle(request: RequestInstance) {
     await request.validate({
       title: {
-        rule: schema.string(),
+        rule: schema.string().required(),
         message: {
           title: 'Title is required',
         },
       },
       body: {
-        rule: schema.string(),
+        rule: schema.string().required(),
         message: {
           body: 'Body is required',
         },

package/app/Actions/Cms/CommentUpdateAction.ts

@@ -8,17 +8,23 @@ export default new Action({
   description: 'Comment Update ORM Action',
   method: 'PATCH',
   async handle(request: RequestInstance) {
+    /*
+     * PATCH, so these are NOT required: a partial update sends the fields it
+     * means to change. The messages used to say "X is required", which fires on
+     * a type failure and never on absence - a message describing a rule the
+     * block does not have.
+     */
     await request.validate({
       title: {
         rule: schema.string(),
         message: {
-          title: 'Title is required',
+          title: 'Title must be a string.',
         },
       },
       body: {
         rule: schema.string(),
         message: {
-          body: 'Body is required',
+          body: 'Body must be a string.',
         },
       },
     })

package/app/Actions/Cms/PostViewsUpdateAction.ts

@@ -8,11 +8,17 @@ export default new Action({
   description: 'Updates the view count for a post',
   method: 'PATCH',
   async handle(request: RequestInstance) {
+    /*
+     * PATCH, so these are NOT required: a partial update sends the fields it
+     * means to change. The messages used to say "X is required", which fires on
+     * a type failure and never on absence - a message describing a rule the
+     * block does not have.
+     */
     await request.validate({
       views: {
         rule: schema.number(),
         message: {
-          views: 'Views is required',
+          views: 'Views must be a number.',
         },
       },
     })

package/app/Actions/Cms/TaggableStoreAction.ts

@@ -10,13 +10,13 @@ export default new Action({
   async handle(request: RequestInstance) {
     await request.validate({
       name: {
-        rule: schema.string(),
+        rule: schema.string().required(),
         message: {
           name: 'Name is required',
         },
       },
       description: {
-        rule: schema.string(),
+        rule: schema.string().required(),
         message: {
           description: 'Description is required',
         },

package/app/Actions/Cms/TaggableUpdateAction.ts

@@ -8,17 +8,23 @@ export default new Action({
   description: 'Tag Update ORM Action',
   method: 'PATCH',
   async handle(request: RequestInstance) {
+    /*
+     * PATCH, so these are NOT required: a partial update sends the fields it
+     * means to change. The messages used to say "X is required", which fires on
+     * a type failure and never on absence - a message describing a rule the
+     * block does not have.
+     */
     await request.validate({
       name: {
         rule: schema.string(),
         message: {
-          name: 'Name is required',
+          name: 'Name must be a string.',
         },
       },
       description: {
         rule: schema.string(),
         message: {
-          description: 'Description is required',
+          description: 'Description must be a string.',
         },
       },
     })

package/app/Actions/Dashboard/Kanban/BoardsIndexAction.ts

@@ -1,7 +1,7 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
 import { modelBoolean } from './kanban-model'
-import { kanbanActionError, kanbanError } from './kanban-response'
+import { kanbanActionError } from './kanban-response'
 
 interface BoardRow {
   id: number

package/app/Actions/Dashboard/Kanban/UsersListAction.ts

@@ -1,6 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
-import { kanbanActionError, kanbanError } from './kanban-response'
+import { kanbanActionError } from './kanban-response'
 
 /**
  * `GET /api/dashboard/kanban/users`.

package/app/Actions/LogAction.ts

@@ -15,7 +15,7 @@ export default new Action({
   // the request object is optional, but if it is provided, it will be used for validation
   validations: {
     message: {
-      rule: schema.string().min(3).max(255),
+      rule: schema.string().min(3).max(255).required(),
       message: 'The message must be between 3 and 255 characters long.',
     },
 
@@ -25,7 +25,7 @@ export default new Action({
       // is not a function" at module evaluation. Use `schema.enum([...])`
       // — that's the working enum primitive used throughout the framework
       // defaults and in the typical project's models.
-      rule: schema.enum(['info', 'warn', 'error']),
+      rule: schema.enum(['info', 'warn', 'error']).required(),
       message: 'The log level must be one of "info", "warn", or "error".',
     },
   },

package/app/Actions/UploadTestAction.ts

@@ -1,5 +1,4 @@
 import { Action } from '@stacksjs/actions'
-import { Storage } from '@stacksjs/storage'
 
 interface Request {
   file: (key: string) => any

package/app/Middleware/Auth.ts

@@ -1,5 +1,4 @@
 import { Auth, authCookieName, sessionUser } from '@stacksjs/auth'
-import { config } from '@stacksjs/config'
 import { HttpError } from '@stacksjs/error-handling'
 import { Middleware } from '@stacksjs/router'
 

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.72.57",
+  "version": "0.72.60",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.72.57",
+  "version": "0.72.60",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.72.57",
+    "@stacksjs/mobile": "^0.72.60",
     "@stacksjs/sanitizer": "^0.2.113"
   },
   "scripts": {

package/routes/dashboard.ts

@@ -16,7 +16,7 @@
  */
 
 import process from 'node:process'
-import { response, route } from '@stacksjs/router'
+import { route } from '@stacksjs/router'
 
 // ============================================================================
 // Email