@ditojs/server 2.93.0 → 2.94.1

package/types/index.d.ts

@@ -50,15 +50,31 @@ export type CompiledParametersValidator = {
   hasModelRefs: boolean
 }
 
-export type ApplicationConfig = {
+/**
+ * Application configuration passed to the Application constructor.
+ *
+ * Extend via module augmentation for project-specific config:
+ *
+ * ```ts
+ * declare module '@ditojs/server' {
+ *   interface ApplicationConfig {
+ *     externalUrls?: {
+ *       frontend: string
+ *       backend: string
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface ApplicationConfig {
   /** @defaultValue `production` */
-  env?: 'production' | 'development'
+  env?: LiteralUnion<'production' | 'development'>
   /** The server configuration */
   server?: {
     /** The ip address or hostname used to serve requests */
     host?: string
     /** The port to listen on for connections */
-    port?: string
+    port?: string | number
   }
   /** Logging options */
   log?: {
@@ -184,7 +200,9 @@ export type ApplicationConfig = {
     keys?: Koa['keys']
   }
   admin?: AdminConfig
-  knex?: Knex.Config<any> & {
+  knex?: Omit<Knex.Config<any>, 'connection'> & {
+    /** Knex connection config, or a custom adapter object (e.g. PGlite). */
+    connection?: Knex.Config<any>['connection'] | Record<string, unknown>
     /** @defaultValue `false` */
     normalizeDbNames?: boolean | Parameters<KnexSnakeCaseMappersFactory>
     // See https://github.com/brianc/node-pg-types/blob/master/index.d.ts#L67
@@ -268,6 +286,13 @@ export interface DiskStorageConfig extends CommonStorageConfig {
    * The path to the directory where assets are stored on.
    */
   path: string
+  /**
+   * Whether to store files in a two-level nested folder structure using the
+   * first two characters of the file key.
+   *
+   * @defaultValue true
+   */
+  nestedFolders?: boolean
 }
 
 export type StorageConfig = S3StorageConfig | DiskStorageConfig
@@ -384,14 +409,20 @@ export class Application<$Models extends Models = Models> {
       add(
         method: string,
         path: string,
-        handler: Function
+        handler: (
+          ctx: KoaContext,
+          next: () => Promise<void>
+        ) => OrPromiseOf<void>
       ): this
       find(
         method: string,
         path: string
       ): {
         status: number
-        handler?: Function
+        handler?: (
+          ctx: KoaContext,
+          next: () => Promise<void>
+        ) => OrPromiseOf<void>
         params?: Record<string, string>
         allowed: string[]
       }
@@ -429,9 +460,9 @@ export class Application<$Models extends Models = Models> {
   /** The schema validator instance. */
   validator: Validator
   /** Registered storage instances by name. */
-  storages: Record<string, Storage>
+  storages: ResolvedStorages
   /** Registered service instances by name. */
-  services: Record<string, Service>
+  services: ResolvedServices
   /** Registered controller instances by name. */
   controllers: Record<string, Controller>
   models: $Models
@@ -461,7 +492,11 @@ export class Application<$Models extends Models = Models> {
   addStorages(storages: StorageConfigs): void
   setupStorages(): Promise<void>
   /** Returns a storage by name, or `null` if not found. */
-  getStorage(name: string): Storage | null
+  getStorage<K extends string>(
+    name: K
+  ): K extends keyof ResolvedStorages
+    ? ResolvedStorages[K]
+    : Storage | null
 
   addService(
     service: Service | Class<Service>,
@@ -471,7 +506,12 @@ export class Application<$Models extends Models = Models> {
   addServices(services: Services): void
   setupServices(): Promise<void>
   /** Returns a service by name. */
-  getService(name: string): Service | null
+  getService<K extends string>(
+    name: K
+  ): K extends keyof ResolvedServices
+    ? ResolvedServices[K]
+    : Service | null
+
   /** Finds a service matching the given predicate. */
   findService(
     callback: (service: Service) => boolean
@@ -620,7 +660,11 @@ export class Application<$Models extends Models = Models> {
     method: HTTPMethod,
     path: string,
     transacted: boolean,
-    middlewares: OrArrayOf<(ctx: KoaContext, next: Function) => void>,
+    middlewares: OrArrayOf< (
+        ctx: KoaContext,
+        next: () => Promise<void>
+      ) => OrPromiseOf<void>
+    >,
     controller?: Controller | null,
     action?: any
   ): void
@@ -658,6 +702,7 @@ export interface Application
 
 export type SchemaType = LiteralUnion<
   | 'string'
+  | 'text'
   | 'number'
   | 'integer'
   | 'boolean'
@@ -669,27 +714,105 @@ export type SchemaType = LiteralUnion<
   | 'timestamp'
 >
 
-export interface ModelRelation {
+type RelatedModel<T> = T extends (infer U)[]
+  ? U extends Model
+    ? U
+    : never
+  : T extends Model
+    ? T
+    : never
+
+type ModelName<T extends Model, $Models, R = ResolveModels<$Models>> = {
+  [K in keyof R]: R[K] extends Class<T> ? K : never
+}[keyof R]
+
+type ResolveModels<$Models> = $Models extends Promise<infer M> ? M : $Models
+
+type OnlyModels<$Models, R = ResolveModels<$Models>> = {
+  [K in keyof R as R[K] extends ModelClass ? K : never]: R[K]
+}
+
+type HasModels<$Models> = keyof OnlyModels<$Models> extends never ? false : true
+
+type ModelRef<T extends Model, $Models> =
+  HasModels<$Models> extends true
+    ? `${ModelName<T, $Models> & string}.${keyof SerializedModel<T> & string}`
+    : string
+
+type AnyModelRef<$Models> =
+  HasModels<$Models> extends true
+    ? `${string}.${string}`
+    : string
+
+/**
+ * The supported relation types for model associations.
+ *
+ * - `'belongsTo'` — single model, foreign key on this table
+ * - `'hasOne'` — single model, foreign key on the other table
+ * - `'hasMany'` — array of models, foreign key on the other table
+ * - `'manyToMany'` — array of models, via a join table
+ * - `'hasOneThrough'` — single model, via a join table
+ *
+ * @see {@link https://github.com/ditojs/dito/blob/main/docs/model-relations.md#relation-types|Relation Types}
+ */
+export type RelationType =
+  | 'belongsTo'
+  | 'hasMany'
+  | 'hasOne'
+  | 'manyToMany'
+  | 'hasOneThrough'
+
+type RelationTypeForProperty<T> = T extends Model[]
+  ? 'hasMany' | 'manyToMany'
+  : T extends Model
+    ? 'belongsTo' | 'hasOne' | 'hasOneThrough'
+    : RelationType
+
+/**
+ * A model relation definition describing how two models are associated.
+ *
+ * When used with type arguments, provides type-safe `from`/`to` strings
+ * and narrows `relation` based on the property type (array vs single
+ * model).
+ *
+ * @example
+ * ```ts
+ * // Untyped — accepts any relation definition:
+ * const rel: ModelRelation = {
+ *   relation: 'hasMany',
+ *   from: 'Tag.id',
+ *   to: 'Task.tagId'
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/ditojs/dito/blob/main/docs/model-relations.md|Model Relations}
+ */
+export interface ModelRelation<
+  $Owner extends Model = Model,
+  $Related extends Model = Model,
+  $Models = unknown,
+  $PropertyType = unknown
+> {
   /**
    * The type of relation
    *
    * @see {@link https://github.com/ditojs/dito/blob/main/docs/model-relations.md#relation-types|Relation Types}
    */
-  relation: LiteralUnion<
-    'belongsTo' | 'hasMany' | 'hasOne' | 'manyToMany' | 'hasOneThrough'
-  >
+  relation: unknown extends $PropertyType
+    ? RelationType
+    : RelationTypeForProperty<$PropertyType>
   /**
    * The model and property name from which the relation is to be built, as a
    * string with both identifiers separated by '.', e.g.:
    * 'FromModelClass.fromPropertyName'
    */
-  from: string
+  from: ModelRef<$Owner, $Models>
   /**
    * The model and property name to which the relation is to be built, as a
    * string with both identifiers separated by '.', e.g.:
    * 'ToModelClass.toPropertyName'
    */
-  to: string
+  to: ModelRef<$Related, $Models>
   /**
    * When set to true the join model class and table is to be built
    * automatically, or allows to specify an existing one manually.
@@ -705,14 +828,14 @@ export interface ModelRelation {
          * be built, as a string with both identifiers separated by '.', e.g.:
          * 'FromModelClass.fromPropertyName'
          */
-        from: string
+        from: AnyModelRef<$Models>
         /**
          * The model and property name or table and column name of an existing
          * join model class or join table to which the through relation is to be
          * built, as a string with both identifiers separated by '.', e.g.:
          * 'toModelClass.toPropertyName'
          */
-        to: string
+        to: AnyModelRef<$Models>
         /**
          * List additional columns to be added to the related model.
          *
@@ -733,11 +856,17 @@ export interface ModelRelation {
    */
   inverse?: boolean
   /**
-   * Optionally, a scope can be defined to be applied when loading the
-   * relation's models. The scope needs to be defined in the related model
-   * class' scopes definitions.
+   * Optionally overrides the related model class derived from
+   * the `to` property. Can be specified as the name the model
+   * was registered with or the model class itself.
+   */
+  modelClass?: string | Class<$Related>
+  /**
+   * Optionally, one or more scopes can be defined to be applied when
+   * loading the relation's models. The scopes need to be defined in the
+   * related model class' scopes definitions.
    */
-  scope?: string
+  scope?: OrArrayOf<string>
   /**
    * Optionally, a filter to apply when loading the relation's models.
    * Accepts a Dito.js filter name/object (resolved via the related model's
@@ -818,7 +947,7 @@ export type ModelProperty<T = any> = Schema<T> & {
    */
   computed?: boolean
   /**
-   * Marks the property has hidden, so that it does not show up in data
+   * Marks the property as hidden, so that it does not show up in data
    * converted to JSON.
    *
    * This can be used for sensitive data.
@@ -850,6 +979,24 @@ export type ModelScopes<$Model extends Model = Model> = Record<
   ModelScope<$Model>
 >
 
+/**
+ * A query modifier function that transforms a query builder.
+ * Modifiers are reusable query fragments applied via
+ * `.modify('name')` on queries.
+ */
+export type ModelModifier<$Model extends Model = Model> = (
+  query: QueryBuilder<$Model>,
+  ...args: any[]
+) => void
+
+/**
+ * Map of modifier names to modifier functions.
+ */
+export type ModelModifiers<$Model extends Model = Model> = Record<
+  string,
+  ModelModifier<$Model>
+>
+
 /**
  * A filter handler function that modifies a query builder
  * based on external parameters (e.g. from URL query strings).
@@ -859,6 +1006,45 @@ export type ModelFilterFunction<$Model extends Model = Model> = (
   ...args: any[]
 ) => void
 
+/**
+ * Registry of known filter type names for use with
+ * `{ filter: '...', properties: [...] }` in model filter definitions.
+ *
+ * Filter types are reusable query filters registered via
+ * `QueryFilters.register()`. Dito.js ships with two built-in types:
+ * - `'text'` — text search with operators (contains, equals, etc.)
+ * - `'date-range'` — date range filtering with from/to parameters
+ *
+ * Register custom filter types at runtime with
+ * `QueryFilters.register()`, then declare them for type safety
+ * via module augmentation:
+ *
+ * ```ts
+ * // Register at runtime:
+ * QueryFilters.register({
+ *   'country': {
+ *     parameters: { code: { type: 'string' } },
+ *     handler(query, property, { code }) {
+ *       query.where(property, code)
+ *     }
+ *   }
+ * })
+ *
+ * // Declare for type safety:
+ * declare module '@ditojs/server' {
+ *   interface QueryFilterTypes {
+ *     'country': true
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/ditojs/dito/blob/main/docs/model-filters.md|Model Filters}
+ */
+export interface QueryFilterTypes {
+  'text': true
+  'date-range': true
+}
+
 /**
  * A model filter definition. Can be one of:
  *
@@ -873,7 +1059,7 @@ export type ModelFilterFunction<$Model extends Model = Model> = (
  */
 export type ModelFilter<$Model extends Model = Model> =
   | {
-      filter: LiteralUnion<'text' | 'date-range'>
+      filter: keyof QueryFilterTypes
       properties?: string[]
     }
   | {
@@ -949,6 +1135,11 @@ export type ModelHooks<$Model extends Model = Model> = {
 }
 
 export class Model extends objection.Model {
+  static query<M extends Model>(
+    this: Constructor<M>,
+    trxOrKnex?: objection.TransactionOrKnex
+  ): QueryBuilder<M, M[]>
+
   constructor(json?: Record<string, any>)
 
   /** @see {@link https://github.com/ditojs/dito/blob/main/docs/model-properties.md|Model Properties} */
@@ -963,6 +1154,47 @@ export class Model extends objection.Model {
   /** @see {@link https://github.com/ditojs/dito/blob/main/docs/model-filters.md|Model Filters} */
   static filters: ModelFilters<Model>
 
+  /**
+   * Reusable named query fragments applied via
+   * `.modify('name')` on query builders. Commonly used
+   * to define shared select sets or filter conditions.
+   *
+   * @example
+   * ```ts
+   * // Define modifiers on a model:
+   * static modifiers = {
+   *   sharedSelects: query =>
+   *     query.select('id', 'name', 'status'),
+   *   whereActive: query =>
+   *     query.where('active', true)
+   * }
+   *
+   * // Use them on queries via QueryBuilder.modify():
+   * query.modify('sharedSelects').modify('whereActive')
+   * ```
+   */
+  static modifiers: ModelModifiers<Model>
+
+  /**
+   * Additional JSON Schema properties that are deep-merged
+   * into the model's compiled schema (built from
+   * {@link Model.properties}). Used for example to add
+   * a custom `validate` function for cross-field validation.
+   *
+   * @example
+   * ```ts
+   * static schema: Schema = {
+   *   validate({ data, options }) {
+   *     if (!data.name) {
+   *       throw new Error('Name is required')
+   *     }
+   *     return true
+   *   }
+   * }
+   * ```
+   */
+  static schema: Schema
+
   static hooks: ModelHooks<Model>
 
   static assets: ModelAssets
@@ -976,15 +1208,8 @@ export class Model extends objection.Model {
     hooks: ModelHooks
     assets: ModelAssets
     options: Record<string, any>
-    modifiers: Record<
-      string,
-      (
-        builder: objection.QueryBuilder<any, any>,
-        ...args: any[]
-      ) => void
-    >
-    schema: Record<string, any>
-    [key: string]: any
+    modifiers: ModelModifiers
+    schema: Schema
   }
 
   /** Derived from class name (removes 'Model' suffix). */
@@ -1068,13 +1293,7 @@ export class Model extends objection.Model {
   /** Returns the named property definition, if found. */
   static getProperty(name: string): ModelProperty | null
   /** Returns the model's query modifiers. */
-  static getModifiers(): Record<
-    string,
-    (
-      builder: objection.QueryBuilder<any, any>,
-      ...args: any[]
-    ) => void
-  >
+  static getModifiers(): ModelModifiers
 
   /**
    * Returns property names matching the given filter
@@ -1268,20 +1487,6 @@ export class Model extends objection.Model {
     trx?: objection.Transaction
   ): Promise<Model | Model[]>
 
-  /**
-   * Dito.js automatically adds an `id` property if a model
-   * property with the `primary: true` setting is not
-   * already explicitly defined.
-   */
-  readonly id: Id
-
-  /**
-   * Dito.js automatically adds a `foreignKeyId` property
-   * if foreign keys occurring in relations definitions are
-   * not explicitly defined in the properties.
-   */
-  readonly foreignKeyId: Id
-
   QueryBuilderType: QueryBuilder<this, this[]>
 
   $app: Application<Models>
@@ -1506,20 +1711,112 @@ export interface Model extends KnexHelper {}
 
 export type ModelClass = Class<Model>
 
-export type ModelRelations = Record<string, ModelRelation>
+type ModelRelationKey<T, K extends keyof T> = K extends
+  | 'QueryBuilderType'
+  | `$${string}`
+  ? never
+  : T[K] extends (...args: any[]) => any
+    ? never
+    : T[K] extends Model | Model[] | undefined
+      ? K
+      : never
+
+/**
+ * A map of relation definitions for a model class.
+ *
+ * When used with a type argument, restricts keys to declared
+ * `Model` or `Model[]` properties on the class.
+ *
+ * @example
+ * ```ts
+ * // Type-safe keys only:
+ * class Tag extends Model {
+ *   declare tasks: Task[]
+ *
+ *   static override relations: ModelRelations<Tag> = {
+ *     tasks: {
+ *       relation: 'manyToMany',
+ *       from: 'Tag.id',
+ *       to: 'Task.id'
+ *     }
+ *   }
+ * }
+ *
+ * // With typed from/to via typeof import():
+ * class Tag extends Model {
+ *   declare tasks: Task[]
+ *
+ *   static override relations:
+ *     ModelRelations<Tag, typeof import('./models')> = {
+ *       tasks: {
+ *         relation: 'manyToMany',
+ *         from: 'Tag.id',    // validated against Tag props
+ *         to: 'Task.id'      // validated against Task props
+ *       }
+ *     }
+ * }
+ * ```
+ */
+export type ModelRelations<$Model extends Model = Model, $Models = unknown> = [
+  keyof SerializedModel<$Model>
+] extends [never]
+  ? Record<string, ModelRelation>
+  : {
+      [K in keyof $Model as ModelRelationKey<$Model, K>]?: ModelRelation<
+        $Model,
+        RelatedModel<$Model[K]>,
+        $Models,
+        $Model[K]
+      >
+    }
 
-export type ModelProperties = Record<string, ModelProperty>
+export type ModelProperties<$Model extends Model = Model> = [
+  keyof SerializedModel<$Model>
+] extends [never]
+  ? Record<string, ModelProperty>
+  : {
+      [K in keyof $Model as ModelDataKey<$Model, K>]?: ModelProperty<$Model[K]>
+    }
 
 /**
- * A controller action definition. Either an options object
- * with `handler`, `method`, `path`, `authorize`, etc., or a
- * bare handler function. The HTTP method and path are
- * derived from the action name key (e.g. `'postImport'`
- * maps to `POST /import`).
+ * A controller action definition. The HTTP method and route
+ * path are derived from the action name key (e.g.
+ * `'post import'` → `POST /import`, `'get'` → `GET /`).
+ *
+ * Can be either a bare handler function or an options
+ * object with `handler`, `authorize`, `parameters`, etc.
+ *
+ * @example
+ * ```ts
+ * // Bare handler function:
+ * actions = {
+ *   'post import'(ctx) {
+ *     return this.importData(ctx.request.body)
+ *   }
+ * }
+ *
+ * // Options object:
+ * actions = {
+ *   'post import': {
+ *     handler(ctx) { ... },
+ *     authorize: 'admin',
+ *     transacted: true
+ *   }
+ * }
+ *
+ * // With typed parameters:
+ * const action: ControllerAction<this, { query: string }> = {
+ *   parameters: { query: { type: 'string' } },
+ *   handler(ctx, { query }) { ... } // query: string
+ * }
+ * ```
  */
-export type ControllerAction<$Controller extends Controller = Controller> =
-  | ControllerActionOptions<$Controller>
-  | ControllerActionHandler<$Controller>
+export type ControllerAction<
+  $Controller extends Controller = Controller,
+  $Params = Record<string, any>
+> =
+  | ControllerActionOptions<$Controller, $Params>
+  | ControllerActionHandler<$Controller, $Params>
 
 export class Controller {
   app: Application
@@ -1562,9 +1859,12 @@ export class Controller {
   logRoutes: boolean
 
   /**
-   * A list of allowed actions. If provided, only the
-   * action names listed here as strings will be mapped to
-   * routes, everything else will be omitted.
+   * Which inherited actions to enable, e.g.
+   * `['get', 'post', 'get stats']`. Actions defined
+   * directly on the same object are always enabled.
+   * When set, it replaces any parent controller's
+   * `allow` list. When omitted, the parent's `allow`
+   * list is inherited.
    */
   allow?: OrReadOnly<ControllerActionName[]>
 
@@ -1620,15 +1920,25 @@ export class Controller {
     transacted: boolean,
     authorize: Authorize,
     action: $ControllerAction,
-    handlers: ((ctx: KoaContext, next: Function) => void)[]
+    handlers: ((
+      ctx: KoaContext,
+      next: () => Promise<void>
+    ) => OrPromiseOf<void>)[]
+  ): void
+
+  setupActions(
+    type: 'actions' | 'collection' | 'member'
+  ): Record<string, unknown> | undefined
+
+  setupActionRoute(
+    type: 'actions' | 'collection' | 'member',
+    action: ControllerAction
   ): void
 
-  setupActions(type: string): any
-  setupActionRoute(type: string, action: ControllerAction): void
-  setupAssets(): any
+  setupAssets(): Record<string, unknown> | undefined
   setupAssetRoute(
     dataPath: OrArrayOf<string>,
-    config: any,
+    config: Record<string, unknown>,
     authorize: Authorize
   ): void
 
@@ -1649,11 +1959,11 @@ export class Controller {
   }
 
   emitHook(
-    type: string,
+    type: `${'before' | 'after'}:${string}`,
     handleResult: boolean,
     ctx: KoaContext,
-    ...args: any[]
-  ): Promise<any>
+    ...args: unknown[]
+  ): Promise<unknown>
 
   processAuthorize(
     authorize: Authorize
@@ -1680,9 +1990,11 @@ export type ActionParameter = Schema & { name: string }
  * the Koa context and any resolved action parameters. `this`
  * is bound to the controller instance.
  */
-export type ModelControllerActionHandler<
-  $ModelController extends ModelController = ModelController
-> = (this: $ModelController, ctx: KoaContext, ...args: any[]) => any
+export type ModelControllerActionHandler<$ModelController = ModelController> = (
+  this: $ModelController,
+  ctx: KoaContext,
+  ...args: any[]
+) => any
 
 /**
  * Handler function for a controller action. Receives the Koa
@@ -1690,12 +2002,14 @@ export type ModelControllerActionHandler<
  * bound to the controller instance.
  */
 export type ControllerActionHandler<
-  $Controller extends Controller = Controller
-> = (this: $Controller, ctx: KoaContext, ...args: any[]) => any
+  $Controller extends Controller = Controller,
+  $Params = Record<string, any>
+> = keyof $Params extends never
+  ? (this: $Controller, ctx: KoaContext) => any
+  : (this: $Controller, ctx: KoaContext, params: $Params) => any
 
 type ModelDataKey<T, K extends keyof T> = K extends
   | 'QueryBuilderType'
-  | 'foreignKeyId'
   | `$${string}`
   ? never
   : T[K] extends (...args: any[]) => any
@@ -1720,14 +2034,14 @@ type ModelDataProperties<$Model extends Model = Model> = {
  * - Any other `string`: Checked as a role via
  *   `UserModel.$hasRole()`.
  * - `function`: Dynamically resolves to any of the above.
- * - `Record<HTTPMethod, string | string[]>`: Per-method
+ * - `Partial<Record<HTTPMethod, string | string[]>>`: Per-method
  *   role authorization.
  */
 export type Authorize =
   | boolean
   | OrArrayOf<LiteralUnion<'$self' | '$owner'>>
   | ((ctx: KoaContext) => OrPromiseOf<Authorize>)
-  | Record<HTTPMethod, string | string[]>
+  | Partial<Record<HTTPMethod, string | string[]>>
 
 export type BaseControllerActionOptions = {
   /**
@@ -1756,13 +2070,6 @@ export type BaseControllerActionOptions = {
    *   overridable `UserModel.hasRole()` method.
    */
   authorize?: Authorize
-  /**
-   * Validates action parameters and maps them to Koa's `ctx.query` object
-   * passed to the action handler.
-   *
-   * @see {@link https://github.com/ditojs/dito/blob/main/docs/model-properties.md Model Properties}
-   */
-  parameters?: { [key: string]: Schema }
   /**
    * Provides a schema for the value returned from the action handler and
    * optionally maps the value to a key inside a returned object when it
@@ -1786,17 +2093,41 @@ export type BaseControllerActionOptions = {
 }
 
 export type ControllerActionOptions<
-  $Controller extends Controller = Controller
+  $Controller extends Controller = Controller,
+  $Params = Record<string, any>
 > = BaseControllerActionOptions & {
-  handler: ControllerActionHandler<$Controller>
+  /**
+   * Defines validated parameters for the action handler.
+   * The handler receives a single parameter object with
+   * the same keys:
+   * ```ts
+   * parameters: { cart: { type: 'object' } },
+   * handler(ctx, { cart }) { ... }
+   * ```
+   *
+   * For strongly-typed parameters, pass a params map as
+   * the second type argument to {@link ControllerActions}:
+   * ```ts
+   * actions: ControllerActions<this, {
+   *   'get search': { query: string }
+   * }>
+   * ```
+   */
+  parameters?: { [K in keyof $Params]: Schema<$Params[K]> }
+  handler: ControllerActionHandler<$Controller, $Params>
 }
 
-export type ModelControllerActionOptions<
-  $ModelController extends ModelController = ModelController
-> = BaseControllerActionOptions & {
-  /** The function to be called when the action route is requested. */
-  handler: ModelControllerActionHandler<$ModelController>
-}
+export type ModelControllerActionOptions<$ModelController = ModelController> =
+  BaseControllerActionOptions & {
+    /**
+     * Defines validated parameters for the action handler.
+     * The handler receives a single parameter object with
+     * the same keys.
+     */
+    parameters?: { [key: string]: Schema }
+    /** The function to be called when the action route is requested. */
+    handler: ModelControllerActionHandler<$ModelController>
+  }
 
 export type MemberActionParameter<$Model extends Model = Model> =
   | Schema
@@ -1825,28 +2156,22 @@ export type MemberActionParameter<$Model extends Model = Model> =
  * A model controller action: either an options object with
  * `handler` or a bare handler function.
  */
-export type ModelControllerAction<
-  $ModelController extends ModelController = ModelController
-> =
+export type ModelControllerAction<$ModelController = ModelController> =
   | ModelControllerActionOptions<$ModelController>
   | ModelControllerActionHandler<$ModelController>
 
 /**
  * Map of action names to action definitions for a model
- * controller's collection-level actions (e.g. `getList`,
- * `postCreate`).
+ * controller's collection-level actions (e.g. `'get'`,
+ * `'post'`, `'post login'`).
  */
-export type ModelControllerActions<
-  $ModelController extends ModelController = ModelController
-> = {
+export type ModelControllerActions<$ModelController = ModelController> = {
   [name: ControllerActionName]: ModelControllerAction<$ModelController>
   allow?: OrReadOnly<ControllerActionName[]>
   authorize?: Authorize
 }
 
-type ModelControllerMemberAction<
-  $ModelController extends ModelController = ModelController
-> =
+type ModelControllerMemberAction<$ModelController = ModelController> =
   | (Omit<ModelControllerActionOptions<$ModelController>, 'parameters'> & {
       parameters?: {
         [key: string]: MemberActionParameter<
@@ -1862,28 +2187,66 @@ type ModelControllerMemberAction<
  * `delete`). Member actions can use `{ from: 'member' }`
  * parameters to receive the resolved member model.
  */
-export type ModelControllerMemberActions<
-  $ModelController extends ModelController = ModelController
-> = {
+export type ModelControllerMemberActions<$ModelController = ModelController> = {
   [name: ControllerActionName]: ModelControllerMemberAction<$ModelController>
   allow?: OrReadOnly<ControllerActionName[]>
   authorize?: Authorize
 }
 
 /**
- * Action name pattern: an HTTP method followed by an
- * optional suffix, e.g. `'getStats'`, `'postImport'`,
- * `'deleteAll'`.
+ * Action name: an HTTP method, optionally followed by a
+ * space and a name (e.g. `'get'`, `'post login'`,
+ * `'get session'`). The method and name are split on the
+ * first space to determine the HTTP method and route path.
+ * Bare names without an HTTP method prefix (e.g. `'login'`)
+ * are not supported and will throw at runtime.
  */
 export type ControllerActionName = `${HTTPMethod}${string}`
 
 /**
  * Map of action names to action definitions for a
- * controller. Supports `allow` to whitelist specific
- * actions and `authorize` for group-level authorization.
+ * controller. Action names follow the pattern
+ * `'{method} {path}'` (e.g. `'post import'`) or just
+ * `'{method}'` for default CRUD actions (e.g. `'get'`).
+ *
+ * Use `allow` to whitelist specific actions and
+ * `authorize` for group-level authorization.
+ *
+ * Pass a `$ParamsMap` as the second type argument to
+ * strongly type handler parameters per action:
+ *
+ * @example
+ * ```ts
+ * type Params = {
+ *   'get search': { query: string }
+ *   'post create': { name: string }
+ * }
+ *
+ * actions: ControllerActions<this, Params> = {
+ *   allow: ['get search', 'post create'],
+ *   'get search': {
+ *     parameters: { query: { type: 'string' } },
+ *     handler(ctx, { query }) { ... } // query: string
+ *   },
+ *   'post create': {
+ *     parameters: { name: { type: 'string' } },
+ *     handler(ctx, { name }) { ... } // name: string
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link ControllerAction}
  */
-export type ControllerActions<$Controller extends Controller = Controller> = {
-  [name: ControllerActionName]: ControllerAction<$Controller>
+export type ControllerActions<
+  $Controller extends Controller = Controller,
+  $ParamsMap extends Record<string, any> = {}
+> = {
+  [K in keyof $ParamsMap & ControllerActionName]?: ControllerAction<
+    $Controller,
+    $ParamsMap[K]
+  >
+} & {
+  [name: ControllerActionName]: ControllerAction<$Controller, any>
   allow?: OrReadOnly<ControllerActionName[]>
   authorize?: Authorize
 }
@@ -1916,66 +2279,65 @@ export class AdminController extends Controller {
   defineViteConfig(config?: UserConfig): UserConfig
 }
 type ModelControllerHookType = 'collection' | 'member'
-type ModelControllerHookKeys<
-  $Keys extends string,
-  $ModelControllerHookType extends string
-> = `${
+type ModelControllerHookKey = `${
   | 'before'
   | 'after'
   | '*'
 }:${
-  | $ModelControllerHookType
+  | ModelControllerHookType
   | '*'
 }:${
-  | Exclude<$Keys, 'allow'>
   | ControllerActionName
   | '*'
 }`
-type ModelControllerHook<
-  $ModelController extends ModelController = ModelController
-> = (
-  ctx: KoaContext,
-  result: objection.Page<ModelFromModelController<$ModelController>>
-) => any
-
-type HookKeysFromController<$ModelController extends ModelController> =
-  | ModelControllerHookKeys<
-      Exclude<
-        keyof Exclude<$ModelController['collection'], undefined>,
-        symbol | number
-      >,
-      'collection'
-    >
-  | ModelControllerHookKeys<
-      Exclude<
-        keyof Exclude<$ModelController['member'], undefined>,
-        symbol | number
-      >,
-      'member'
-    >
 
-type HandlerFromHookKey<
-  $ModelController extends ModelController,
-  K extends HookKeysFromController<$ModelController>
-> = K extends `${
-  | 'before'
-  | 'after'
-  | '*'
-}:${
-  | 'collection'
-  | 'member'
-  | '*'
-}:${string}`
-  ? (this: $ModelController, ctx: KoaContext, ...args: any[]) => any
-  : never
-
-type ModelControllerHooks<
-  $ModelController extends ModelController = ModelController
-> = {
-  [$Key in HookKeysFromController<$ModelController>]?: HandlerFromHookKey<
-    $ModelController,
-    $Key
-  >
+type CrudActionName = 'get' | 'post' | 'put' | 'patch' | 'delete'
+type NonDeleteCrudActionName = Exclude<CrudActionName, 'delete'>
+
+type BeforeHookKey =
+  `${'before' | '*'}:${ModelControllerHookType | '*'}:${ControllerActionName | '*'}`
+type AfterDeleteHookKey = `after:${ModelControllerHookType | '*'}:delete`
+type AfterItemHookKey =
+  | `after:member:${NonDeleteCrudActionName}`
+  | `after:collection:${'post' | 'put' | 'patch'}`
+type AfterCollectionGetHookKey = `after:collection:get`
+// Catch-all for custom actions and wildcard scopes;
+// CRUD hooks get strongly-typed results via the specific key types above.
+type AfterCustomHookKey =
+  `after:${ModelControllerHookType | '*'}:${ControllerActionName | '*'}`
+
+export type ModelControllerHooks<$ModelController = ModelController> = {
+  [$Key in BeforeHookKey]?: (
+    this: $ModelController,
+    ctx: KoaContext,
+    params?: Record<string, any>
+  ) => void
+} & {
+  [$Key in AfterDeleteHookKey]?: (
+    this: $ModelController,
+    ctx: KoaContext,
+    result: { count: number }
+  ) => any
+} & {
+  [$Key in AfterItemHookKey]?: (
+    this: $ModelController,
+    ctx: KoaContext,
+    item: ModelFromModelController<$ModelController>
+  ) => any
+} & {
+  [$Key in AfterCollectionGetHookKey]?: (
+    this: $ModelController,
+    ctx: KoaContext,
+    result:
+      | ModelFromModelController<$ModelController>[]
+      | Page<ModelFromModelController<$ModelController>>
+  ) => any
+} & {
+  [$Key in AfterCustomHookKey]?: (
+    this: $ModelController,
+    ctx: KoaContext,
+    result: any
+  ) => any
 }
 
 /**
@@ -2026,12 +2388,12 @@ export class CollectionController<
    * The controller's collection actions with built-in CRUD
    * defaults.
    */
-  collection?: ModelControllerActions<CollectionController<$Model>>
+  collection?: ModelControllerActions<this>
   /**
    * The controller's member actions with built-in CRUD
    * defaults.
    */
-  member?: ModelControllerMemberActions<CollectionController<$Model>>
+  member?: ModelControllerMemberActions<this>
 
   /** Creates a query builder for this controller's model. */
   query(trx?: objection.Transaction): QueryBuilder<$Model>
@@ -2071,13 +2433,13 @@ export class CollectionController<
    * Executes a controller action within a transaction
    * context.
    */
-  execute(
+  execute<R>(
     ctx: KoaContext,
     execute: (
       query: QueryBuilder<$Model>,
       trx?: objection.Transaction
-    ) => any
-  ): Promise<any>
+    ) => R
+  ): Promise<Awaited<R>>
 
   /**
    * Extracts model IDs from the request body collection,
@@ -2152,12 +2514,12 @@ export class ModelController<
    * The controller's collection actions. Wrap actions in
    * this object to assign them to the collection.
    */
-  collection?: ModelControllerActions<ModelController<$Model>>
+  collection?: ModelControllerActions<this>
   /**
    * The controller's member actions. Wrap actions in this
    * object to assign them to the member.
    */
-  member?: ModelControllerMemberActions<ModelController<$Model>>
+  member?: ModelControllerMemberActions<this>
   assets?:
     | boolean
     | {
@@ -2166,10 +2528,55 @@ export class ModelController<
       }
 
   /**
-   * When nothing is returned from a hook, the standard
-   * action result is used.
+   * Lifecycle hooks that run before or after controller
+   * actions. Keys follow the pattern
+   * `'{before|after|*}:{collection|member|*}:{actionName|*}'`.
+   * Use `'*'` in any segment to match all values.
+   *
+   * @example
+   * ```ts
+   * override hooks: ModelControllerHooks<MyController> = {
+   *   // Guard: prevent patching locked records
+   *   'before:member:patch'(ctx) {
+   *     if (ctx.request.body.locked) {
+   *       throw new ResponseError('Locked records cannot be modified', {
+   *         status: 403
+   *       })
+   *     }
+   *   },
+   *   // Enrich: attach computed data to the member
+   *   async 'after:member:get'(ctx, item) {
+   *     const isProcessing = await checkJobStatus(item.id)
+   *     item.$set({ isProcessing })
+   *     return item
+   *   },
+   *   // Side effect: log after a successful deletion
+   *   'after:member:delete'(ctx, result) {
+   *     const name = this.modelClass.name
+   *     logger.info(`Deleted ${result.count} ${name} record(s)`)
+   *   },
+   *   // Custom action: runs after a custom 'get export' action
+   *   'after:collection:get export'(ctx, items) {
+   *     analytics.track('export', { count: items.length })
+   *   },
+   *   // Custom action: receives the resolved parameters
+   *   'before:member:post import'(ctx, params) {
+   *     logger.info(`Importing ${params?.repoFamily?.name}`)
+   *   }
+   * }
+   * ```
+   *
+   * `before:` CRUD hooks receive only `(ctx)`. Custom
+   * action hooks also receive the resolved `params` object.
+   *
+   * `after:` hooks receive `(ctx, result)`. Returning a
+   * value from an `after:` hook replaces the action result.
+   *
+   * @see {@link ModelControllerActions}
+   * @see {@link ModelControllerMemberActions}
+   * @see {@link QueryParameterOptions} for pagination parameters
    */
-  hooks?: ModelControllerHooks<ModelController<$Model>>
+  hooks?: ModelControllerHooks<this>
   /** Map of relation name to RelationController instance. */
   relations?: Record<string, RelationController>
 }
@@ -2502,7 +2909,25 @@ export type QueryParameterOptions = {
 }
 export type QueryParameterOptionKey = keyof QueryParameterOptions
 
-export class Service {
+/**
+ * Base class for application services.
+ *
+ * @typeParam $Config - The shape of the service's configuration
+ *   object, accessed via `this.config` in service methods.
+ *
+ * ```ts
+ * class MailService extends Service<{
+ *   smtp: { host: string; port: number }
+ *   from: string
+ * }> {
+ *   async send(to: string, body: string) {
+ *     const { host, port } = this.config!.smtp
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export class Service<$Config extends object = Record<string, unknown>> {
   constructor(app: Application<Models>, name?: string)
 
   /** The application instance. */
@@ -2510,11 +2935,11 @@ export class Service {
   /** The camelized service name. */
   name: string
   /** The service configuration. */
-  config: Record<string, unknown> | null
+  config: $Config | null
   /** Whether this service has been initialized. */
   initialized: boolean
 
-  setup(config: Record<string, unknown>): void
+  setup(config: $Config): void
 
   /**
    * Override in sub-classes if the service needs async
@@ -2533,6 +2958,46 @@ export class Service {
 }
 export type Services = Record<string, Class<Service> | Service>
 
+/**
+ * Registry of application service instances by name.
+ *
+ * Extend via module augmentation for typed `app.services` access:
+ *
+ * ```ts
+ * declare module '@ditojs/server' {
+ *   interface ApplicationServices {
+ *     mail: MailService
+ *     jobs: JobService
+ *   }
+ * }
+ * ```
+ */
+export interface ApplicationServices {}
+
+type ResolvedServices = keyof ApplicationServices extends never
+  ? Record<string, Service>
+  : ApplicationServices
+
+/**
+ * Registry of application storage instances by name.
+ *
+ * Extend via module augmentation for typed `app.storages` access:
+ *
+ * ```ts
+ * declare module '@ditojs/server' {
+ *   interface ApplicationStorages {
+ *     s3: Storage
+ *     local: Storage
+ *   }
+ * }
+ * ```
+ */
+export interface ApplicationStorages {}
+
+type ResolvedStorages = keyof ApplicationStorages extends never
+  ? Record<string, Storage>
+  : ApplicationStorages
+
 export class QueryBuilder<
   M extends Model,
   R = M[]
@@ -2908,6 +3373,19 @@ export class Storage {
    */
   convertAssetFile(file: AssetFileObject): void
 
+  /**
+   * Signs an asset file by setting its `signature` property
+   * to an HMAC derived from its storage key.
+   */
+  signAssetFile(file: AssetFile): void
+
+  /**
+   * Verifies that an asset file's signature matches its
+   * storage key. Returns false if the signature is missing
+   * or invalid.
+   */
+  verifyAssetFile(file: AssetFile): boolean
+
   /** Registers a storage subclass by type name. */
   static register(storageClass: Class<Storage>): void
   /** Retrieves a registered storage class by type name. */
@@ -3140,11 +3618,22 @@ export function addRelationSchemas(
   properties: Record<string, ModelProperty>
 ): void
 
-export type Keyword =
+export type Keyword = (
   | SetOptional<Ajv.MacroKeywordDefinition, 'keyword'>
   | SetOptional<Ajv.CodeKeywordDefinition, 'keyword'>
   | SetOptional<Ajv.FuncKeywordDefinition, 'keyword'>
-export type Format = Ajv.ValidateFunction | Ajv.FormatDefinition<string>
+) & {
+  /** Custom error message shown when validation fails. */
+  message?: string
+  /** When true, validation errors for this keyword are suppressed. */
+  silent?: boolean
+}
+export type Format = (Ajv.ValidateFunction | Ajv.FormatDefinition<string>) & {
+  /** Custom error message shown when validation fails. */
+  message?: string
+  /** When true, validation errors for this format are suppressed. */
+  silent?: boolean
+}
 
 /** Built-in AJV keyword definitions. */
 export const keywords: {
@@ -3175,14 +3664,34 @@ export const types: {
   color: Record<string, any>
 }
 export type Id = string | number
-export type KoaContext<$State = any> = Koa.ParameterizedContext<
+/**
+ * Koa context state available as `ctx.state`.
+ *
+ * Extend via module augmentation for typed state access:
+ *
+ * ```ts
+ * declare module '@ditojs/server' {
+ *   interface KoaContextState {
+ *     foo: string
+ *   }
+ * }
+ * ```
+ */
+export interface KoaContextState {
+  user: InstanceType<typeof UserModel>
+  [key: string]: unknown
+}
+
+export type KoaContext<$State = KoaContextState> = Koa.ParameterizedContext<
   $State,
   {
     transaction: objection.Transaction
-    session: koaSession.ContextSession & { state: { user: any } }
+    session: koaSession.ContextSession
     logger: PinoLogger
   }
->
+> & {
+  app: Application
+}
 
 type LiteralUnion<T extends U, U = string> = T | (U & Record<never, never>)
 
@@ -3192,8 +3701,9 @@ type OrReadOnly<T> = Readonly<T> | T
 
 type OrPromiseOf<T> = Promise<T> | T
 
-type ModelFromModelController<$ModelController extends ModelController> =
-  InstanceType<Exclude<$ModelController['modelClass'], undefined>>
+type ModelFromModelController<
+  $ModelController extends { modelClass?: Class<any> }
+> = InstanceType<Exclude<$ModelController['modelClass'], undefined>>
 
 type SerializeModelPropertyValue<T> = T extends (infer U)[]
   ? SerializeModelPropertyValue<U>[]
@@ -3244,10 +3754,10 @@ export type SelectModelPropertyKeys<T extends Model> = keyof SerializedModel<T>
  * }
  * ```
  */
-export type Schema<T = any> = JSONSchemaType<T> & {
+export type Schema<$Value = any> = JSONSchemaType<$Value> & {
   // keywords/_validate.js
   validate?: (params: {
-    data: unknown
+    data: $Value
     parentData: object | unknown[]
     rootData: object | unknown[]
     dataPath: string
@@ -3260,7 +3770,7 @@ export type Schema<T = any> = JSONSchemaType<T> & {
 
   // keywords/_validate.js
   validateAsync?: (params: {
-    data: unknown
+    data: $Value
     parentData: object | unknown[]
     rootData: object | unknown[]
     dataPath: string