@ditojs/server 1.12.0 → 1.13.1

package/types/index.d.ts

@@ -0,0 +1,2177 @@
+/// <reference types="node" />
+
+// Type definitions for Dito.js server
+// Project: <https://github.com/ditojs/dito/>
+
+// Export the entire Dito namespace.
+
+import { DateFormat } from '@dito/utils'
+import koaCors from '@koa/cors'
+import * as Ajv from 'ajv/dist/2020.js'
+import * as aws from 'aws-sdk'
+import * as dbErrors from 'db-errors'
+import * as EventEmitter2 from 'eventemitter2'
+import helmet from 'helmet'
+import * as Knex from 'knex'
+import * as Koa from 'koa'
+import koaBodyParser from 'koa-bodyparser'
+import koaCompress from 'koa-compress'
+import koaLogger from 'koa-logger'
+import mount from 'koa-mount'
+import koaPinoLogger from 'koa-pino-logger'
+import koaResponseTime from 'koa-response-time'
+import koaSession from 'koa-session'
+import * as objection from 'objection'
+import { KnexSnakeCaseMappersFactory } from 'objection'
+import {
+  Class,
+  ConditionalExcept,
+  ConditionalKeys,
+  Constructor, SetOptional, SetReturnType
+} from 'type-fest'
+import { UserConfig } from 'vite'
+
+export type Page<$Model extends Model> = {
+  total: number
+  results: $Model[]
+}
+
+export type ApplicationConfig = {
+  /** @defaultValue `production` */
+  env?: '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
+  }
+  /** Logging options */
+  log?: {
+    /**
+     * Enable logging requests to console by passing `true` or pick between
+     * 'console' for logging to console and 'file' for logging to file
+     *
+     * @defaultValue `false`
+     */
+    requests?: boolean | 'console' | 'file'
+    /**
+     * Whether to output route (Controller) logs
+     *
+     * @defaultValue `false`
+     */
+    routes?: boolean
+    /**
+     * Whether to log relation mappings
+     *
+     * @defaultValue `false`
+     */
+    relations?: boolean
+    /**
+     * Whether to log the json schema generated out of the model property
+     * definitions
+     *
+     * @defaultValue `false`
+     */
+    schema?: boolean
+    /**
+     * Whether to log sql queries
+     *
+     * @defaultValue `false`
+     */
+    sql?: boolean
+    /** Whether to turn off all logging */
+    silent?: boolean
+    errors?:
+      | boolean
+      | {
+          /** Whether to log sql errors */
+          sql?: boolean
+          /** Whether to log the error stack */
+          stack?: boolean
+          json?: boolean
+        }
+  }
+  api?: ApiConfig
+  app?: {
+    /**
+     * Whether to normalize paths from camel case to kebab case.
+     *
+     * @defaultValue `false`
+     * @see {@link https://github.com/ditojs/dito/blob/master/docs/controllers.md#path-normalization|Path Normalization}
+     */
+    normalizePaths?: boolean
+    /**
+     * Whether proxy header fields will be trusted.
+     *
+     * @defaultValue `false`
+     */
+    proxy?: Koa['proxy']
+    /**
+     * Whether to include X-Response-Time header in responses
+     *
+     * @defaultValue `true`
+     */
+    responseTime?: boolean | Parameters<typeof koaResponseTime>[0]
+    /**
+     * Whether to use koa-helmet middleware which provides important security
+     * headers to make your app more secure by default.
+     *
+     * @defaultValue `true`
+     * @see https://github.com/venables/koa-helmet
+     * @see https://github.com/helmetjs/helmet
+     */
+    helmet?: boolean | Parameters<typeof helmet>[0]
+    logger?:
+      | Parameters<typeof koaLogger>[0]
+      | Parameters<typeof koaPinoLogger>[0]
+    /**
+     * Configure body parser.
+     *
+     * @see https://github.com/koajs/bodyparser#options
+     */
+    bodyParser?: koaBodyParser.Options
+    /**
+     * Enable or configure Cross-Origin Resource Sharing (CORS)
+     *
+     * @defaultValue `true`
+     * @see https://github.com/koajs/cors#corsoptions
+     */
+    cors?: boolean | koaCors.Options
+    /**
+     * Enable or configure server response compression
+     *
+     * @defaultValue `true`
+     * @see https://github.com/koajs/compress#options
+     */
+    compress?: boolean | koaCompress.CompressOptions
+    /**
+     * Enable ETag headers in server responses
+     *
+     * @defaultValue `true`
+     */
+    etag?: boolean
+    /**
+     * @defaultValue `false`
+     * @see https://github.com/koajs/session
+     */
+    session?: boolean | (koaSession.opts & { modelClass: string })
+    /**
+     * Enable passport authentication middleware
+     *
+     * @defaultValue `false`
+     */
+    passport?: boolean
+    /**
+     * Set signed cookie keys.
+     *
+     * @see https://github.com/koajs/koa/blob/master/docs/api/index.md#appkeys
+     */
+    keys?: Koa['keys']
+  }
+  admin?: AdminConfig
+  knex?: Knex.Config<any> & {
+    /** @defaultValue `false` */
+    normalizeDbNames?: boolean | Parameters<KnexSnakeCaseMappersFactory>
+    // See https://github.com/brianc/node-pg-types/blob/master/index.d.ts#L67
+    typeParsers?: Record<number, <I extends string | Buffer>(value: I) => any>
+  }
+  /** Service configurations. Pass `false` as a value to disable a service. */
+  services?: Services
+  storages?: StorageConfigs
+  assets?: {
+    /**
+     * Threshold after which unused assets that haven't seen changes for given
+     * timeframe are removed.
+     *
+     * @example
+     *   '1 hr 20 mins'
+     *
+     * @default `0`
+     * @see https://www.npmjs.com/package/parse-duration
+     */
+    cleanupTimeThreshold?: string | number
+  }
+}
+
+export type MulterS3File = {
+  bucket: string
+  key: string
+  acl: string
+  contentType: string
+  contentDisposition: null
+  storageClass: string
+  serverSideEncryption: null
+  metadata: any
+  location: string
+  etag: string
+}
+
+export type StorageConfigs = { [key: string]: StorageConfig }
+
+export type StorageConfig =
+  | {
+      type: 's3'
+      /** The name of the destination bucket. */
+      bucket: aws.S3.BucketName
+      /** @default 'private'  */
+      acl: LiteralUnion<
+        | 'private'
+        | 'public-read'
+        | 'public-read-write'
+        | 'authenticated-read'
+        | 'aws-exec-read'
+        | 'bucket-owner-read'
+        | 'bucket-owner-full-control'
+      >
+      /**
+       * Can be used to specify caching behavior along the request/reply chain.
+       *
+       * @see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.
+       */
+      cacheControl?: aws.S3.CacheControl
+      /**
+       * The type of storage to use for the object.
+       *
+       * @default 'STANDARD'
+       */
+      storageClass?: LiteralUnion<
+        | 'STANDARD'
+        | 'REDUCED_REDUNDANCY'
+        | 'STANDARD_IA'
+        | 'ONEZONE_IA'
+        | 'INTELLIGENT_TIERING'
+        | 'GLACIER'
+        | 'DEEP_ARCHIVE'
+      >
+      /**
+       * The server-side encryption algorithm used when storing this object in
+       * Amazon S3 (for example, AES256, aws:kms).
+       */
+      serverSideEncryption?: aws.S3.ServerSideEncryption
+      /**
+       * If present, specifies the ID of the AWS Key Management Service (AWS
+       * KMS) symmetric customer managed customer master key (CMK)
+       */
+      sseKmsKeyId?: aws.S3.SSEKMSKeyId
+      s3: aws.S3.ClientConfiguration
+      url?: string
+    }
+  | {
+      type: 'disk'
+      path: string
+      url?: string
+      mount?: string
+      allowedImports?: string[]
+    }
+
+export interface AdminConfig {
+  api?: ApiConfig
+  /** Path to the admin's src directory. Mandatory when in development mode. */
+  root?: string
+  /**
+   * Path to the dist/src/admin directory. Mandatory when in production mode.
+   */
+  dist?: string
+  /** @default Application  */
+  mode?: 'production' | 'development'
+  /** Settings accessible on the browser side as `global.dito.settings`. */
+  settings?: Record<string, any>
+}
+
+export interface ApiResource {
+  type: string
+  path?: string
+  parent?: ApiResource
+}
+
+export interface ApiConfig {
+  /** The base url to use for api requests. */
+  url?: string
+  /** @defaultValue 'en-US'  */
+  locale?: string
+  dateFormat?: DateFormat
+  /**
+   * Whether to display admin notifications.
+   *
+   * @default `true`
+   */
+  notifications?:
+    | boolean
+    | {
+        /**
+         * The amount of milliseconds multiplied with the amount of characters
+         * displayed in the notification, plus 40 (40 + title + message).
+         *
+         * @defaultValue `20`
+         */
+        durationFactor: number
+      }
+  cors?: {
+    /**
+     * Whether cross-site `Access-Control` requests are made using credentials.
+     */
+    credentials: boolean
+  }
+  /**
+   * Setting normalizePaths to `true` sets `api.normalizePath` to hyphenate
+   * camelized strings and `api.denormalizePath` to do the opposite. If you
+   * prefer to use another path normalization algorithm, they can be defined the
+   * api settings passed to the DitoAdmin constructor.
+   *
+   * @default Defaults to Application.config.app.normalizePaths and then
+   */
+  normalizePaths?: boolean
+  /** Auth resources */
+  users?: {
+    path?: string
+    login?: {
+      /** @defaultValue `'login'` */
+      path?: string
+      /** @defaultValue `'post'` */
+      method?: HTTPMethod
+    }
+    logout?: {
+      /** @defaultValue `'logout'` */
+      path?: string
+      /** @defaultValue `'post'` */
+      method?: HTTPMethod
+    }
+    session?: {
+      /** @defaultValue `'session'` */
+      path?: string
+      /** @defaultValue `'get'` */
+      method?: HTTPMethod
+    }
+  }
+  /** Optionally override resource path handlers. */
+  resources?: Record<string, (resource: ApiResource | string) => string>
+
+  /**
+   * Optionally override / extend headers
+   *
+   * @defaultValue `
+   */
+  headers?: Record<string, string>
+}
+
+export interface ApplicationControllers {
+  [k: string]:
+    | Class<ModelController<Model>>
+    | Class<Controller>
+    | ApplicationControllers
+}
+
+export type Models = Record<string, Class<Model>>
+
+export class Application<$Models extends Models> {
+  constructor(options: {
+    config?: ApplicationConfig
+    validator?: Validator
+    // TODO: router types
+    router?: any
+    /**
+     * Subscribe to application events. Event names: `'before:start'`,
+     * `'after:start'`, `'before:stop'`, `'after:stop'`, `'error'`
+     */
+    events?: Record<string, (this: Application<$Models>, ...args: []) => void>
+    models: $Models
+    controllers?: ApplicationControllers
+    // TODO: services docs
+    services?: Services
+    middleware?: Koa.Middleware
+  })
+
+  models: $Models
+  start(): Promise<void>
+  stop(timeout?: number): Promise<void>
+  startOrExit(): Promise<void>
+  addServices(services: Services): void
+  addService(service: Service): void
+  addController(controllers: Controller, namespace?: string): void
+  addControllers(controllers: ApplicationControllers, namespace?: string): void
+  addStorages(storages: StorageConfigs): void
+  addStorage(storage: StorageConfig): void
+  addModels(models: Models): void
+  addModel(model: Class<Model>): void
+  getAdminViteConfig(config?: UserConfig): UserConfig
+}
+export interface Application
+  extends Omit<
+      Koa,
+      | 'setMaxListeners'
+      | 'removeListener'
+      | 'removeAllListeners'
+      | 'prependOnceListener'
+      | 'prependListener'
+      | 'once'
+      | 'on'
+      | 'off'
+      | 'listeners'
+      | 'addListener'
+      | 'listenerCount'
+      | 'emit'
+      | 'eventNames'
+    >,
+    EventEmitter {}
+
+export type SchemaType = LiteralUnion<
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+  | 'date'
+  | 'datetime'
+  | 'timestamp'
+>
+
+export interface ModelRelation {
+  /**
+   * The type of relation
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-relations.md#relation-types|Relation Types}
+   */
+  relation: LiteralUnion<
+    'belongsTo' | 'hasMany' | 'hasOne' | 'manyToMany' | 'hasOneThrough'
+  >
+  /**
+   * 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
+  /**
+   * 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
+  /**
+   * When set to true the join model class and table is to be built
+   * automatically, or allows to specify an existing one manually.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-relations.md#join-models-and-tables|Join Models and Tables}
+   */
+  through?:
+    | boolean
+    | {
+        /**
+         * The model and property name or table and column name of an existing
+         * join model class or join table from which the through relation is to
+         * be built, as a string with both identifiers separated by '.', e.g.:
+         * 'FromModelClass.fromPropertyName'
+         */
+        from: string
+        /**
+         * 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
+        /**
+         * List additional columns to be added to the related model.
+         *
+         * When working with a join model class or table, extra columns from it
+         * can be added to the related model, as if it was define on its own
+         * table. They then appear as additional properties on the related
+         * model.
+         */
+        extra?: string[]
+      }
+  /**
+   * Controls whether the relation is the inverse of another relation.
+   *
+   * This information is only required when working with through relations.
+   * Without it, Dito.js wouldn't be able to tell which side of the relation is
+   * on the left-hand side, and which is on the right-hand side when
+   * automatically creating the join model class and table.
+   */
+  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.
+   */
+  scope?: string
+  /**
+   * Controls whether the auto-inserted foreign key property should be marked as
+   * nullable. This only makes sense on a 'belongsTo' relation, where the model
+   * class holds the foreign key, and only when the foreign key isn't already
+   * explicitly defined in the Model Properties.
+   */
+  nullable?: boolean
+  /**
+   * Controls whether the relation owns the models that it holds, or whether it
+   * is simply relating to them, and a relation elsewhere is considered to be
+   * their owner.
+   */
+  owner?: boolean
+}
+
+export type ModelProperty<T = any> = Schema<T> & {
+  /** Marks the column as the primary key in the database. */
+  primary?: boolean
+  /**
+   * Defines if the property is a foreign key.
+   *
+   * Finds the information about the related model in the relations definition
+   * and adds a reference to the related model table in migrations, by calling
+   * the .references(columnName).inTable(tableName) method.
+   */
+  foreign?: boolean
+  /**
+   * Adds an index to the database column in the migrations, by calling the
+   * .index() method.
+   */
+  index?: boolean
+  /**
+   * Marks the column as nullable in the migrations, by calling the .nullable()
+   * method.
+   */
+  nullable?: boolean
+  /**
+   * Adds a unique constraint to the table for the given column in the
+   * migrations, by calling the .unique() method. If a string is provided, all
+   * columns with the same string value for unique are grouped together in one
+   * unique constraint, by calling .unique([column1, column2, …]).
+   */
+  unique?: boolean | string
+  /**
+   * Marks the column for a property of type 'integer' to be unsigned in the
+   * migrations, by calling the .index() method.calling the .unsigned() method.
+   */
+  unsigned?: boolean
+  /**
+   * Marks the property as computed.
+   *
+   * Computed properties are not present as columns in the database itself. They
+   * can be created either by an SQL statement (SELECT … AS), or by a getter
+   * accessor defined on the model. Computed properties are set when converting
+   * to JSON if not present already, and removed again before data is sent to
+   * the database.
+   */
+  computed?: boolean
+  /**
+   * Marks the property has hidden, so that it does not show up in data
+   * converted to JSON.
+   *
+   * This can be used for sensitive data.
+   */
+  hidden?: boolean
+}
+
+export type ModelScope<$Model extends Model> = (
+  this: $Model,
+  query: QueryBuilder<$Model>,
+  applyParentScope: (query: QueryBuilder<$Model>) => QueryBuilder<$Model>
+) => QueryBuilder<$Model, any> | void
+
+export type ModelScopes<$Model extends Model> = Record<
+  string,
+  ModelScope<$Model>
+>
+
+export type ModelFilterFunction<$Model extends Model> = (
+  queryBuilder: QueryBuilder<$Model>,
+  ...args: any[]
+) => void
+
+export type ModelFilter<$Model extends Model> =
+  | {
+      filter: 'text' | 'date-range'
+      properties?: string[]
+    }
+  | {
+      handler: ModelFilterFunction<$Model>
+      parameters?: { [key: string]: Schema }
+      // TODO: validate type
+      validate?: any
+    }
+  | ModelFilterFunction<$Model>
+
+export type ModelFilters<$Model extends Model> = Record<
+  string,
+  ModelFilter<$Model>
+>
+
+export interface ModelAsset {
+  storage: string
+  readImageSize?: boolean
+}
+
+export type ModelAssets = Record<string, ModelAsset>
+
+export interface ModelOptions extends objection.ModelOptions {
+  graph?: boolean
+  async?: boolean
+  mutable?: boolean
+}
+
+type ModelHookFunction<$Model extends Model> = (
+  args: objection.StaticHookArguments<$Model>
+) => void
+export type ModelHooks<$Model extends Model> = {
+  [key in `${'before' | 'after'}:${
+    | 'find'
+    | 'insert'
+    | 'update'
+    | 'delete'}`]?: ModelHookFunction<$Model>
+}
+
+export class Model extends objection.Model {
+  /** @see {@link https://github.com/ditojs/dito/blob/master/docs/model-properties.md|Model Properties} */
+  static properties: ModelProperties
+
+  /** @see {@link https://github.com/ditojs/dito/blob/master/docs/model-relations.md|Model Relations} */
+  static relations: ModelRelations
+
+  /** @see {@link https://github.com/ditojs/dito/blob/master/docs/model-scopes.md|Model Scopes} */
+  static scopes: ModelScopes<Model>
+
+  /** @see {@link https://github.com/ditojs/dito/blob/master/docs/model-filters.md|Model Filters} */
+  static filters: ModelFilters<Model>
+
+  static hooks: ModelHooks<Model>
+
+  static assets: ModelAssets
+
+  static getPropertyOrRelationAtDataPath: (dataPath: OrArrayOf<string>) => any
+
+  static count: {
+    (column?: objection.ColumnRef, options?: { as: string }): number
+    (aliasToColumnDict: Record<string, string | string[]>): number
+    (...columns: objection.ColumnRef[]): number
+  }
+
+  /**
+   * Dito automatically adds an `id` property if a model property with the
+   * `primary: true` setting is not already explicitly defined.
+   */
+  readonly id: Id
+
+  /**
+   * Dito 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[]>
+
+  // Todo: include application settings
+  $app: Application<Models>
+  $is(model: Model): boolean
+  $update(
+    attributes: Partial<ExtractModelProperties<this>>,
+    trx?: objection.Transaction
+  ): objection.SingleQueryBuilder<objection.QueryBuilderType<this>>
+
+  $patch(
+    attributes: Partial<ExtractModelProperties<this>>,
+    trx?: objection.Transaction
+  ): objection.SingleQueryBuilder<objection.QueryBuilderType<this>>
+
+  $validate<$JSON extends null | {}>(
+    json?: $JSON,
+    options?: ModelOptions & Record<string, any>
+  ): Promise<$JSON | this>
+
+  $validateGraph(options: ModelOptions & Record<string, any>): Promise<this>
+
+  /* -------------------- Start QueryBuilder.mixin(Model) ------------------- */
+  static first: StaticQueryBuilderMethod<'first'>
+  static find: StaticQueryBuilderMethod<'find'>
+  static findOne: StaticQueryBuilderMethod<'findOne'>
+  static findById: StaticQueryBuilderMethod<'findById'>
+
+  static withGraph: StaticQueryBuilderMethod<'withGraph'>
+  static withGraphFetched: StaticQueryBuilderMethod<'withGraphFetched'>
+  static withGraphJoined: StaticQueryBuilderMethod<'withGraphJoined'>
+  static clearWithGraph: StaticQueryBuilderMethod<'clearWithGraph'>
+
+  static withScope: StaticQueryBuilderMethod<'withScope'>
+  static applyScope: StaticQueryBuilderMethod<'applyScope'>
+  static clearWithScope: StaticQueryBuilderMethod<'clearWithScope'>
+
+  static clear: StaticQueryBuilderMethod<'clear'>
+  static pick: StaticQueryBuilderMethod<'pick'>
+  static omit: StaticQueryBuilderMethod<'omit'>
+  static select: StaticQueryBuilderMethod<'select'>
+
+  static insert: StaticQueryBuilderMethod<'insert'>
+  static upsert: StaticQueryBuilderMethod<'upsert'>
+  static update: StaticQueryBuilderMethod<'update'>
+  static relate: StaticQueryBuilderMethod<'relate'>
+  static patch: StaticQueryBuilderMethod<'patch'>
+
+  static truncate: StaticQueryBuilderMethod<'truncate'>
+  static delete: StaticQueryBuilderMethod<'delete'>
+  static deleteById: StaticQueryBuilderMethod<'deleteById'>
+
+  static insertAndFetch: StaticQueryBuilderMethod<'insertAndFetch'>
+  static upsertAndFetch: StaticQueryBuilderMethod<'upsertAndFetch'>
+  static updateAndFetch: StaticQueryBuilderMethod<'updateAndFetch'>
+  static patchAndFetch: StaticQueryBuilderMethod<'patchAndFetch'>
+  static patchAndFetchById: StaticQueryBuilderMethod<'patchAndFetchById'>
+  static updateAndFetchById: StaticQueryBuilderMethod<'updateAndFetchById'>
+
+  static insertGraph: StaticQueryBuilderMethod<'insertGraph'>
+  static upsertGraph: StaticQueryBuilderMethod<'upsertGraph'>
+  static insertGraphAndFetch: StaticQueryBuilderMethod<'insertGraphAndFetch'>
+  static upsertGraphAndFetch: StaticQueryBuilderMethod<'upsertGraphAndFetch'>
+
+  static insertDitoGraph: StaticQueryBuilderMethod<'insertDitoGraph'>
+  static upsertDitoGraph: StaticQueryBuilderMethod<'upsertDitoGraph'>
+  static updateDitoGraph: StaticQueryBuilderMethod<'updateDitoGraph'>
+  static patchDitoGraph: StaticQueryBuilderMethod<'patchDitoGraph'>
+  static insertDitoGraphAndFetch:
+    StaticQueryBuilderMethod<'insertDitoGraphAndFetch'>
+
+  static upsertDitoGraphAndFetch:
+    StaticQueryBuilderMethod<'upsertDitoGraphAndFetch'>
+
+  static updateDitoGraphAndFetch:
+    StaticQueryBuilderMethod<'updateDitoGraphAndFetch'>
+
+  static patchDitoGraphAndFetch:
+    StaticQueryBuilderMethod<'patchDitoGraphAndFetch'>
+
+  static upsertDitoGraphAndFetchById:
+    StaticQueryBuilderMethod<'upsertDitoGraphAndFetchById'>
+
+  static updateDitoGraphAndFetchById:
+    StaticQueryBuilderMethod<'updateDitoGraphAndFetchById'>
+
+  static patchDitoGraphAndFetchById:
+    StaticQueryBuilderMethod<'patchDitoGraphAndFetchById'>
+
+  static where: StaticQueryBuilderMethod<'where'>
+  static whereNot: StaticQueryBuilderMethod<'whereNot'>
+  static whereRaw: StaticQueryBuilderMethod<'whereRaw'>
+  static whereWrapped: StaticQueryBuilderMethod<'whereWrapped'>
+  static whereExists: StaticQueryBuilderMethod<'whereExists'>
+  static whereNotExists: StaticQueryBuilderMethod<'whereNotExists'>
+  static whereIn: StaticQueryBuilderMethod<'whereIn'>
+  static whereNotIn: StaticQueryBuilderMethod<'whereNotIn'>
+  static whereNull: StaticQueryBuilderMethod<'whereNull'>
+  static whereNotNull: StaticQueryBuilderMethod<'whereNotNull'>
+  static whereBetween: StaticQueryBuilderMethod<'whereBetween'>
+  static whereNotBetween: StaticQueryBuilderMethod<'whereNotBetween'>
+  static whereColumn: StaticQueryBuilderMethod<'whereColumn'>
+  static whereNotColumn: StaticQueryBuilderMethod<'whereNotColumn'>
+  static whereComposite: StaticQueryBuilderMethod<'whereComposite'>
+  static whereInComposite: StaticQueryBuilderMethod<'whereInComposite'>
+  // whereNotInComposite:  QueryBuilder<Model>['whereNotInComposite']
+  static whereJsonHasAny: StaticQueryBuilderMethod<'whereJsonHasAny'>
+  static whereJsonHasAll: StaticQueryBuilderMethod<'whereJsonHasAll'>
+  static whereJsonIsArray: StaticQueryBuilderMethod<'whereJsonIsArray'>
+  static whereJsonNotArray: StaticQueryBuilderMethod<'whereJsonNotArray'>
+  static whereJsonIsObject: StaticQueryBuilderMethod<'whereJsonIsObject'>
+  static whereJsonNotObject: StaticQueryBuilderMethod<'whereJsonNotObject'>
+  static whereJsonSubsetOf: StaticQueryBuilderMethod<'whereJsonSubsetOf'>
+  static whereJsonNotSubsetOf: StaticQueryBuilderMethod<'whereJsonNotSubsetOf'>
+  static whereJsonSupersetOf: StaticQueryBuilderMethod<'whereJsonSupersetOf'>
+  static whereJsonNotSupersetOf:
+    StaticQueryBuilderMethod<'whereJsonNotSupersetOf'>
+
+  static having: StaticQueryBuilderMethod<'having'>
+  static havingIn: StaticQueryBuilderMethod<'havingIn'>
+  static havingNotIn: StaticQueryBuilderMethod<'havingNotIn'>
+  static havingNull: StaticQueryBuilderMethod<'havingNull'>
+  static havingNotNull: StaticQueryBuilderMethod<'havingNotNull'>
+  static havingExists: StaticQueryBuilderMethod<'havingExists'>
+  static havingNotExists: StaticQueryBuilderMethod<'havingNotExists'>
+  static havingBetween: StaticQueryBuilderMethod<'havingBetween'>
+  static havingNotBetween: StaticQueryBuilderMethod<'havingNotBetween'>
+  static havingRaw: StaticQueryBuilderMethod<'havingRaw'>
+  static havingWrapped: StaticQueryBuilderMethod<'havingWrapped'>
+
+  // deprecated methods that are still supported at the moment.
+  // TODO: Remove once we move to Objection 3.0
+
+  static eager: StaticQueryBuilderMethod<'eager'>
+  static joinEager: StaticQueryBuilderMethod<'joinEager'>
+  static naiveEager: StaticQueryBuilderMethod<'naiveEager'>
+  static mergeEager: StaticQueryBuilderMethod<'mergeEager'>
+  static mergeJoinEager: StaticQueryBuilderMethod<'mergeJoinEager'>
+  static mergeNaiveEager: StaticQueryBuilderMethod<'mergeNaiveEager'>
+  static clearEager: StaticQueryBuilderMethod<'clearEager'>
+
+  // static scope:  QueryBuilder<Model>['scope']
+  // static mergeScope:  QueryBuilder<Model>['mergeScope']
+  // static clearScope:  QueryBuilder<Model>['clearScope']
+
+  /* --------------------- End QueryBuilder.mixin(Model) -------------------- */
+}
+
+type StaticQueryBuilderMethod<
+  K extends ConditionalKeys<QueryBuilder<Model>, (...a: any[]) => any>
+> = <$Model extends Class<Model>>(
+  ...args: Parameters<QueryBuilder<InstanceType<$Model>>[K]>
+) => ReturnType<QueryBuilder<InstanceType<$Model>>[K]>
+
+// @eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface Model extends EventEmitter {}
+export interface Model extends KnexHelper {}
+
+export type ModelClass = Class<Model>
+
+export type ModelRelations = Record<string, ModelRelation>
+
+export type ModelProperties = Record<string, ModelProperty>
+
+export type ControllerAction<$Controller extends Controller> =
+  | ControllerActionOptions<$Controller>
+  | ControllerActionHandler<$Controller>
+
+export class Controller {
+  app: Application
+  /**
+   * Optionally provide the controller path. A default is deducted from the
+   * normalized class name otherwise.
+   */
+  path?: string
+  /**
+   * The controller's name. If not provided, it is automatically deducted from
+   * the controller class name. If this name ends in 'Controller', that is
+   * stripped off the name, so 'GreetingsController' turns into 'Greetings'.
+   */
+  name?: string
+  /**
+   * The controller's namespace, which is prepended to path to generate the
+   * absolute controller route. Note that it is rare to provide this manually.
+   * Usually Dito.js determines the namespace automatically from the controller
+   * object passed to the Dito.js application's constructor and its
+   * sub-objects.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/controllers.md#namespaces Namespaces}
+   */
+  namespace?: string
+  /**
+   * 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.
+   */
+  allow?: OrReadOnly<ControllerActionName[]>
+
+  /** Authorization */
+  authorize?: Authorize
+  actions?: ControllerActions<this>
+
+  initialize(): void
+  setup(isRoot: boolean, setupActionsObject: boolean): void
+  // TODO: type reflectActionsObject
+  reflectActionsObject(): any
+  setupRoute<$ControllerAction extends ControllerAction<any>>(
+    method: HTTPMethod,
+    url: string,
+    transacted: boolean,
+    authorize: Authorize,
+    action: $ControllerAction,
+    handlers: ((ctx: KoaContext, next: Function) => void)[]
+  ): void
+
+  setupActions(type: string): string[]
+  setupActionRoute(type: any, action: any): void
+  setupAssets(): any
+  setupAssetRoute(
+    dataPath: OrArrayOf<string>,
+    config: any,
+    authorize: Authorize
+  ): void
+
+  compose(): Parameters<typeof mount>[1]
+  /** To be overridden by sub-classes. */
+  getPath(type: string, path: string): string
+  getUrl(type: string, path: string): string
+  inheritValues(type: string): any
+  processValues(values: any): {
+    // Create a filtered `values` object that only contains the allowed fields
+    values: any
+    allow: string[]
+    authorize: Authorize
+  }
+
+  emitHook(
+    type: string,
+    handleResult: any,
+    ctx: any,
+    ...args: any[]
+  ): Promise<any>
+
+  processAuthorize(authorize: any): any
+  describeAuthorize(authorize: any): string
+  handleAuthorization(): Promise<void>
+  /**
+   * @param str The string to log.
+   * @param [indent=0] The amount of levels to indent (in pairs of two spaces).
+   *   Default is `0`
+   */
+  log(str: string, indent?: number): void
+}
+
+export type ActionParameter = Schema & { name: string }
+
+export type ModelControllerActionHandler<
+  $ModelController extends ModelController<Model>
+> = (this: $ModelController, ctx: KoaContext, ...args: any[]) => any
+
+export type ControllerActionHandler<$Controller extends Controller> = (
+  this: $Controller,
+  ctx: KoaContext,
+  ...args: any[]
+) => any
+
+export type ExtractModelProperties<$Model> = {
+  [$Key in SelectModelPropertyKeys<$Model>]: $Model[$Key] extends Model
+    ? ExtractModelProperties<$Model[$Key]>
+    : $Model[$Key]
+}
+
+export type Extends<$A, $B> = $A extends $B ? 1 : 0
+
+export type SelectModelPropertyKeys<$Model extends Model> = {
+  [K in keyof $Model]-?: K extends
+    | 'QueryBuilderType'
+    | 'foreignKeyId'
+    | `$${string}`
+    ? never
+    : $Model[K] extends Function
+    ? never
+    : K
+}[keyof $Model]
+
+export type Authorize =
+  | boolean
+  | OrArrayOf<LiteralUnion<'$self' | '$owner'>>
+  | ((ctx: KoaContext) => OrPromiseOf<Authorize>)
+  | Record<HTTPMethod, string | string[]>
+
+export type BaseControllerActionOptions = {
+  /**
+   * The HTTP method (`'get'`, `'post'`, `'put'`, `'delete'` or `'patch'`) to
+   * which the action should listen. By default, the `'get'` method is assigned
+   * if none is provided.
+   */
+  method?: HTTPMethod
+  /**
+   * The path to which the action is mapped, defined in relation to the route
+   * path of its controller. By default, the normalized method name is used as
+   * the action's path.
+   */
+  path?: string
+  /**
+   * Determines whether or how the request is authorized. This value can either
+   * be one of the values as described below, an array of them or a function
+   * which returns one or more of them.
+   *
+   * - Boolean: `true` if the action should be authorized, `false` otherwise.
+   * - '$self': The requested member is checked against `ctx.state.user` and the
+   *   action is only authorized if it matches the member.
+   * - '$owner': The member is asked if it is owned by `ctx.state.user` through
+   *   the optional `Model.$hasOwner()` method.
+   * - Any string: `ctx.state.user` is checked for this role through the
+   *   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/master/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
+   * contains a `name` property.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-properties.md Model Properties}
+   */
+  returns?: Schema & { name?: string }
+  /**
+   * The scope(s) to be applied to every query executed through the action.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-scopes.md Model Scopes}
+   */
+  scope?: string[]
+  /**
+   * Determines whether queries in the action should be executed within a
+   * transaction. Any failure will mean the database will rollback any queries
+   * executed to the pre-transaction state.
+   */
+  transacted?: boolean
+}
+
+export type ControllerActionOptions<$Controller extends Controller> =
+  BaseControllerActionOptions & {
+    handler: ControllerActionHandler<$Controller>
+  }
+
+export type ModelControllerActionOptions<
+  $ModelController extends ModelController<Model>
+> = BaseControllerActionOptions & {
+  /** The function to be called when the action route is requested. */
+  handler: ModelControllerActionHandler<$ModelController>
+}
+
+export type MemberActionParameter<M extends Model> =
+  | Schema
+  | {
+      member: true
+
+      /** Sets ctx.query. */
+      query?: Record<string, any>
+      /**
+       * Adds a FOR UPDATE in PostgreSQL and MySQL during a select statement.
+       * FOR UPDATE causes the rows retrieved by the SELECT statement to be
+       * locked as though for update. This prevents them from being locked,
+       * modified or deleted by other transactions until the current transaction
+       * ends.
+       *
+       * @default `false`
+       * @see {@link http://knexjs.org/#Builder-forUpdate}
+       * @see {@link https://www.postgresql.org/docs/12/explicit-locking.html#LOCKING-ROWS}
+       */
+      forUpdate?: boolean
+      /** Modify the member query. */
+      modify?: (query: QueryBuilder<M>) => QueryBuilder<M>
+    }
+
+export type ModelControllerAction<
+  $ModelController extends ModelController<Model>
+> =
+  | ModelControllerActionOptions<$ModelController>
+  | ModelControllerActionHandler<$ModelController>
+
+export type ModelControllerActions<
+  $ModelController extends ModelController<Model> = ModelController<Model>
+> = {
+  [name: ControllerActionName]: ModelControllerAction<$ModelController>
+  allow?: OrReadOnly<ControllerActionName[]>
+  authorize?: Authorize
+}
+
+type ModelControllerMemberAction<
+  $ModelController extends ModelController<Model>
+> =
+  | (Omit<ModelControllerActionOptions<$ModelController>, 'parameters'> & {
+      parameters?: {
+        [key: string]: MemberActionParameter<
+          modelFromModelController<$ModelController>
+        >
+      }
+    })
+  | ModelControllerActionHandler<$ModelController>
+
+export type ModelControllerMemberActions<
+  $ModelController extends ModelController<Model>
+> = {
+  [name: ControllerActionName]: ModelControllerMemberAction<$ModelController>
+  allow?: OrReadOnly<ControllerActionName[]>
+  authorize?: Authorize
+}
+
+export type ControllerActionName = `${HTTPMethod}${string}`
+
+export type ControllerActions<$Controller extends Controller> = {
+  [name: ControllerActionName]: ControllerAction<$Controller>
+  allow?: OrReadOnly<ControllerActionName[]>
+  authorize?: Authorize
+}
+
+export class UsersController<M extends Model> extends ModelController<M> {}
+
+export class AdminController extends Controller {
+  config: AdminConfig
+  mode: 'production' | 'development'
+  closed: boolean
+  koa: Koa
+  getPath(name: string): string
+  getDitoObject(): {
+    base: string
+    api: AdminConfig['api']
+    settings: AdminConfig['settings']
+  }
+
+  sendDitoObject(ctx: Koa.Context): void
+  middleware(): Koa.Middleware
+  setupViteServer(): void
+  getViteConfig(config: UserConfig): UserConfig
+}
+type ModelControllerHookType = 'collection' | 'member'
+type ModelControllerHookKeys<
+  $Keys extends string,
+  $ModelControllerHookType extends string
+> = `${'before' | 'after' | '*'}:${$ModelControllerHookType | '*'}:${
+  | Exclude<$Keys, 'allow'>
+  | ControllerActionName
+  | '*'}`
+type ModelControllerHook<
+  $ModelController extends ModelController<Model> = ModelController<Model>
+> = (
+  ctx: KoaContext,
+  result: objection.Page<modelFromModelController<$ModelController>>
+) => any
+
+type HookHandler = () => void
+
+type HookKeysFromController<$ModelController extends ModelController<Model>> =
+  | 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<Model>,
+  $Key extends HookKeysFromController<$ModelController>
+> = $Key extends `${'before' | 'after' | '*'}:${
+  | 'collection'
+  | 'member'
+  | '*'}:${string}`
+  ? (this: $ModelController, ctx: KoaContext, ...args: any[]) => any
+  : never
+
+type ModelControllerHooks<
+  $ModelController extends ModelController<Model> = ModelController<Model>
+> = {
+  [$Key in HookKeysFromController<$ModelController>]?: HandlerFromHookKey<
+    $ModelController,
+    HookKeysFromController<$ModelController>
+  >
+}
+
+export type ModelControllerScope = OrArrayOf<string>
+
+export class ModelController<$Model extends Model = Model> extends Controller {
+  /**
+   * The model class that this controller represents. If none is provided, the
+   * singularized controller name is used to look up the model class in models
+   * registered with the application. As a convention, model controller names
+   * should always be provided in pluralized form.
+   */
+  modelClass?: Class<$Model>
+  /**
+   * The controller's collection actions. Instead of being provided on the
+   * instance level as in the controller base class, they are to be wrapped in a
+   * designated object in order to be assigned to the collection.
+   *
+   * To limit which collection actions will be mapped to routes, supply an array
+   * of action names under the `allow` key. Only the action names listed there
+   * will be mapped to routes, everything else will be omitted.
+   */
+  collection?: ModelControllerActions<ModelController<$Model>>
+  /**
+   * The controller's member actions. Instead of being provided on the instance
+   * level as in the controller base class, they are to be wrapped in a
+   * designated object in order to be assigned to the member.
+   *
+   * To limit which member actions will be mapped to routes, supply an array of
+   * action names under the `allow` key. Only the action names listed there will
+   * be mapped to routes, everything else will be omitted.
+   */
+  member?: ModelControllerMemberActions<ModelController<$Model>>
+  assets?:
+    | boolean
+    | {
+        allow?: OrArrayOf<string>
+        authorize: Record<string, OrArrayOf<string>>
+      }
+
+  /**
+   * When nothing is returned from a hook, the standard action result is used.
+   */
+  hooks?: ModelControllerHooks<ModelController<$Model>>
+  /**
+   * Controls whether normal database methods should be used, or their …Graph…
+   * counterparts.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-queries.md#graph-methods Model Queries – Graph Methods}
+   */
+  graph?: boolean
+  /**
+   * The query parameter(s) allowed to be passed to the default model actions,
+   * both on `collection` and `member` level. If none is provided, every
+   * supported parameter is allowed.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-queries.md#find-methods) Model Queries – Find Methods}
+   */
+  allowParam?: OrArrayOf<LiteralUnion<keyof QueryParameterOptions>>
+  /**
+   * The scope(s) allowed to be requested when passing the 'scope' query
+   * parameter to the default model actions. If none is provided, every
+   * supported scope is allowed.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-scopes.md Model Scopes}
+   */
+  allowScope?: boolean | OrArrayOf<string>
+  /**
+   * The filter(s) allowed to be requested when passing the 'filter' query
+   * parameter to the default model actions. If none is provided, every
+   * supported filter is allowed.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-filters.md Model Filters}
+   */
+  allowFilter?: boolean | OrArrayOf<string>
+  /**
+   * The scope(s) to be applied to every query executed through this controller.
+   *
+   * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-scopes.md Model Scopes}
+   */
+  scope?: ModelControllerScope
+  query(): QueryBuilder<$Model>
+}
+
+export class Validator extends objection.Validator {
+  constructor(schema?: {
+    options?: {
+      /** @defaultValue `false` */
+      async?: boolean
+      /** @defaultValue `false` */
+      patch?: boolean
+      /** @defaultValue `false` */
+      $data?: boolean
+      /** @defaultValue `false` */
+      $comment?: boolean
+      /** @defaultValue `false` */
+      coerceTypes?: boolean
+      /** @defaultValue `false` */
+      multipleOfPrecision?: boolean
+      /** @defaultValue `true` */
+      ownProperties?: boolean
+      /** @defaultValue `false` */
+      removeAdditional?: boolean
+      /** @defaultValue `true` */
+      uniqueItems?: boolean
+      /** @defaultValue `true` */
+      useDefaults?: boolean
+      /** @defaultValue `false` */
+      verbose?: boolean
+    }
+    keywords?: Record<string, Keyword>
+    formats?: Record<string, Format>
+  })
+}
+
+// NOTE: Because EventEmitter overrides a number of EventEmitter2 methods with
+// changed signatures, we are unable to extend it.
+export class EventEmitter {
+  static mixin: (target: any) => {}
+  constructor(options?: EventEmitter2.ConstructorOptions)
+  responds(event: EventEmitter2.event): boolean
+  emit(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    ...values: any[]
+  ): Promise<any[]>
+
+  on(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    listener: EventEmitter2.ListenerFn
+  ): this
+
+  off(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    listener: EventEmitter2.ListenerFn
+  ): this
+
+  once(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    listener: EventEmitter2.ListenerFn
+  ): this
+
+  setupEmitter(
+    events: Record<string, EventEmitter2.ListenerFn>,
+    options: EventEmitter2.ConstructorOptions
+  ): void
+
+  // From EventEmitter2:
+  emitAsync(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    ...values: any[]
+  ): Promise<any[]>
+
+  addListener(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    listener: EventEmitter2.ListenerFn
+  ): this | EventEmitter2.Listener
+
+  prependListener(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    listener: EventEmitter2.ListenerFn,
+    options?: boolean | EventEmitter2.OnOptions
+  ): this | EventEmitter2.Listener
+
+  prependOnceListener(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    listener: EventEmitter2.ListenerFn,
+    options?: boolean | EventEmitter2.OnOptions
+  ): this | EventEmitter2.Listener
+
+  many(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    timesToListen: number,
+    listener: EventEmitter2.ListenerFn,
+    options?: boolean | EventEmitter2.OnOptions
+  ): this | EventEmitter2.Listener
+
+  prependMany(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    timesToListen: number,
+    listener: EventEmitter2.ListenerFn,
+    options?: boolean | EventEmitter2.OnOptions
+  ): this | EventEmitter2.Listener
+
+  onAny(listener: EventEmitter2.EventAndListener): this
+  prependAny(listener: EventEmitter2.EventAndListener): this
+  offAny(listener: EventEmitter2.ListenerFn): this
+  removeListener(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    listener: EventEmitter2.ListenerFn
+  ): this
+
+  removeAllListeners(event?: EventEmitter2.event | EventEmitter2.eventNS): this
+  setMaxListeners(n: number): void
+  getMaxListeners(): number
+  eventNames(
+    nsAsArray?: boolean
+  ): (EventEmitter2.event | EventEmitter2.eventNS)[]
+
+  listenerCount(event?: EventEmitter2.event | EventEmitter2.eventNS): number
+  listeners(
+    event?: EventEmitter2.event | EventEmitter2.eventNS
+  ): EventEmitter2.ListenerFn[]
+
+  listenersAny(): EventEmitter2.ListenerFn[]
+  waitFor(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    timeout?: number
+  ): EventEmitter2.CancelablePromise<any[]>
+
+  waitFor(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    filter?: EventEmitter2.WaitForFilter
+  ): EventEmitter2.CancelablePromise<any[]>
+
+  waitFor(
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    options?: EventEmitter2.WaitForOptions
+  ): EventEmitter2.CancelablePromise<any[]>
+
+  listenTo(
+    target: EventEmitter2.GeneralEventEmitter,
+    events: EventEmitter2.event | EventEmitter2.eventNS,
+    options?: EventEmitter2.ListenToOptions
+  ): this
+
+  listenTo(
+    target: EventEmitter2.GeneralEventEmitter,
+    events: EventEmitter2.event[],
+    options?: EventEmitter2.ListenToOptions
+  ): this
+
+  listenTo(
+    target: EventEmitter2.GeneralEventEmitter,
+    events: Object,
+    options?: EventEmitter2.ListenToOptions
+  ): this
+
+  stopListeningTo(
+    target?: EventEmitter2.GeneralEventEmitter,
+    event?: EventEmitter2.event | EventEmitter2.eventNS
+  ): Boolean
+
+  hasListeners(event?: String): Boolean
+  static once(
+    emitter: EventEmitter2.EventEmitter2,
+    event: EventEmitter2.event | EventEmitter2.eventNS,
+    options?: EventEmitter2.OnceOptions
+  ): EventEmitter2.CancelablePromise<any[]>
+
+  static defaultMaxListeners: number
+}
+
+export interface DitoGraphOptions {
+  fetchStrategy?: 'OnlyNeeded' | 'OnlyIdentifiers' | 'Everything'
+  relate?: boolean
+  allowRefs?: boolean
+  insertMissing?: boolean
+  unrelate?: boolean
+  update?: boolean
+}
+
+export type QueryParameterOptions = {
+  scope?: OrArrayOf<string>
+  filter?: OrArrayOf<string>
+  /**
+   * A range between two numbers. When expressed as a string, the value is split
+   * at the ',' character ignoring any spaces on either side. i.e. `'1,2'` and
+   * `'1 , 2'`
+   */
+  range?: [number, number] | string
+  limit?: number
+  offset?: number
+  order?: 'asc' | 'desc'
+}
+export type QueryParameterOptionKey = keyof QueryParameterOptions
+
+export class Service {
+  constructor(app: Application<Models>, name?: string)
+
+  setup(config: any): void
+
+  initialize(): void
+
+  start(): Promise<void>
+
+  stop(): Promise<void>
+}
+export type Services = Record<string, Class<Service> | Service>
+
+export class QueryBuilder<
+  M extends Model,
+  R = M[]
+> extends objection.QueryBuilder<M, R> {
+  /**
+   * Returns true if the query defines normal selects: select(), column(),
+   * columns()
+   */
+  hasNormalSelects: () => boolean
+  /**
+   * Returns true if the query defines special selects: distinct(), count(),
+   * countDistinct(), min(), max(), sum(), sumDistinct(), avg(), avgDistinct()
+   */
+  hasSpecialSelects: () => boolean
+  withScope: (...scopes: string[]) => this
+  /**
+   * Clear all scopes defined with `withScope()` statements, preserving the
+   * default scope.
+   */
+  clearWithScope: () => this
+  ignoreScope: (...scopes: string[]) => this
+  applyScope: (...scopes: string[]) => this
+  allowScope: (...scopes: string[]) => void
+  clearAllowScope: () => void
+  applyFilter: (name: string, ...args: any[]) => this
+  allowFilter: (...filters: string[]) => void
+  withGraph: (
+    expr: objection.RelationExpression<M>,
+    options?: objection.GraphOptions & { algorithm: 'fetch' | 'join' }
+  ) => this
+
+  toSQL: () => string
+  raw: Knex.RawBuilder
+  selectRaw: SetReturnType<Knex.RawBuilder, this>
+  // TODO: add type for Dito's pluck method, which has a different method
+  // signature than the objection one:
+  // pluck: <K extends objection.ModelProps<M>>(
+  //   key: K
+  // ) => QueryBuilder<M, ReflectArrayType<R, M[K]>>
+  loadDataPath: (
+    dataPath: string[] | string,
+    options: objection.GraphOptions & { algorithm: 'fetch' | 'join' }
+  ) => this
+
+  upsert: (
+    data: PartialModelObject<M>,
+    options?: {
+      update: boolean
+      fetch: boolean
+    }
+  ) => this
+
+  find: (
+    query: QueryParameterOptions,
+    allowParam?:
+      | QueryParameterOptionKey[]
+      | { [key in keyof QueryParameterOptionKey]: boolean }
+  ) => this
+
+  patchById: (id: Id, data: PartialModelObject<M>) => this
+  updateById: (id: Id, data: PartialModelObject<M>) => this
+  upsertAndFetch: (data: PartialModelObject<M>) => this
+  insertDitoGraph: (
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => this
+
+  insertDitoGraphAndFetch: (
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => this
+
+  upsertDitoGraph: (
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => this
+
+  upsertDitoGraphAndFetch: (data: any, options?: DitoGraphOptions) => this
+  upsertDitoGraphAndFetchById: (
+    id: Id,
+    data: any,
+    options?: DitoGraphOptions
+  ) => QueryBuilder<M, M>
+
+  updateDitoGraph: (
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => Promise<any>
+
+  updateDitoGraphAndFetch: (
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => this
+
+  updateDitoGraphAndFetchById: (
+    id: Id,
+    data: any,
+    options?: DitoGraphOptions
+  ) => QueryBuilder<M, M>
+
+  patchDitoGraph: (
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => this
+
+  patchDitoGraphAndFetch: (
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => this
+
+  patchDitoGraphAndFetchById: (
+    id: Id,
+    data: PartialDitoModelGraph<M>,
+    options?: DitoGraphOptions
+  ) => QueryBuilder<M, M>
+  // TODO: static mixin(target)
+
+  ArrayQueryBuilderType: QueryBuilder<M, M[]>
+  SingleQueryBuilderType: QueryBuilder<M, M>
+  NumberQueryBuilderType: QueryBuilder<M, number>
+  PageQueryBuilderType: QueryBuilder<M, objection.Page<M>>
+}
+export interface QueryBuilder<M extends Model, R = M[]> extends KnexHelper {}
+
+export type PartialModelObject<T extends Model> = {
+  [K in objection.NonFunctionPropertyNames<T>]?: objection.Defined<
+    T[K]
+  > extends Model
+    ? T[K]
+    : objection.Defined<T[K]> extends Array<infer I>
+    ? I extends Model
+      ? I[]
+      : objection.Expression<T[K]>
+    : objection.Expression<T[K]>
+}
+
+export type PartialDitoModelGraph<M extends Partial<Model>> = {
+  [K in objection.NonFunctionPropertyNames<M>]?: objection.Defined<
+    M[K]
+  > extends Model
+    ? PartialDitoModelGraph<M[K]>
+    : objection.Defined<M[K]> extends Array<infer I>
+    ? I extends Partial<Model>
+      ? PartialDitoModelGraph<I>[]
+      : M[K]
+    : M[K]
+}
+
+/* ------------------------------ Start Errors ----------------------------- */
+export class ResponseError extends Error {
+  constructor()
+  constructor(
+    error:
+      | {
+          /** The http status code. */
+          status: number
+          /** The error message. */
+          message?: string
+          /**
+           * An optional code to be used to distinguish different error
+           * instances.
+           */
+          code?: string | number
+        }
+      | string,
+    defaults?: { message?: string; status?: number }
+  )
+
+  status: number
+  code?: string | number
+}
+export class AssetError extends ResponseError {}
+export class AuthenticationError extends ResponseError {}
+export class AuthorizationError extends ResponseError {}
+export class WrappedError extends ResponseError {}
+export class DatabaseError extends WrappedError {
+  constructor(
+    error:
+      | dbErrors.CheckViolationError
+      | dbErrors.NotNullViolationError
+      | dbErrors.ConstraintViolationError
+      | dbErrors.DataError
+      | dbErrors.DBError
+  )
+}
+export class GraphError extends ResponseError {}
+export class ModelError extends ResponseError {
+  constructor(model: Class<Model> | Model)
+}
+export class NotFoundError extends ResponseError {}
+export class NotImplementedError extends ResponseError {}
+export class QueryBuilderError extends ResponseError {}
+export class RelationError extends ResponseError {}
+export class ValidationError extends ResponseError {}
+export class ControllerError extends ResponseError {
+  constructor(controller: { name: string } | { constructor: { name: string } })
+}
+/* ------------------------------- End Errors ------------------------------ */
+
+/* ------------------------------ Start Mixins ----------------------------- */
+export type Mixin = (
+  target: Object,
+  propertyName: string,
+  propertyDescriptor: PropertyDescriptor
+) => void
+
+type AssetFileObject = {
+  // The unique key within the storage (uuid/v4 + file extension)
+  key: string
+  // The original filename
+  name: string
+  // The file's mime-type
+  type: string
+  // The amount of bytes consumed by the file
+  size: number
+  // The public url of the file
+  url: string
+  // The width of the image if the storage defines `config.readImageSize`
+  width: number
+  // The height of the image if the storage defines `config.readImageSize`
+  height: number
+}
+
+export class AssetModel extends TimeStampedModel {
+  key: string
+  file: AssetFileObject
+  storage: string
+  count: number
+}
+
+export const AssetMixin: <T extends Constructor>(
+  target: T
+) => Constructor<
+  InstanceType<T> & {
+    key: string
+    file: AssetFileObject
+    storage: string
+    count: number
+  }
+>
+
+export class TimeStampedModel extends Model {
+  createdAt: Date
+  updatedAt: Date
+}
+
+export const TimeStampedMixin: <T extends Constructor>(
+  target: T
+) => Constructor<InstanceType<T> & {
+  createdAt: Date
+  updatedAt: Date
+}>
+
+export class UserModel extends Model {
+  static options?: {
+    usernameProperty?: string
+    passwordProperty?: string
+    /**
+     * This option can be used to specify (eager) scopes to be applied when the
+     * user is deserialized from the session.
+     */
+    sessionScope?: OrArrayOf<string>
+  }
+
+  username: string
+  password: string
+  hash: string
+  lastLogin?: Date
+
+  $verifyPassword(password: string): Promise<boolean>
+
+  $hasRole(...roles: string[]): boolean
+
+  $hasOwner(owner: UserModel): boolean
+
+  $isLoggedIn(ctx: KoaContext): boolean
+
+  // TODO: type options
+  static login(ctx: KoaContext, options: any): Promise<void>
+
+  static sessionQuery(trx: Knex.Transaction): QueryBuilder<UserModel>
+}
+
+export class SessionModel extends Model {
+  id: string
+  value: { [key: string]: any }
+}
+
+export const SessionMixin: <T extends Constructor>(
+  target: T
+) => Constructor<InstanceType<T> & {
+  id: string
+  value: { [key: string]: any }
+}>
+
+export const UserMixin: <T extends Constructor>(
+  target: T
+) => Constructor<
+  InstanceType<T> & {
+    id: string
+    value: { [key: string]: any }
+  }
+>
+
+/**
+ * Apply the action mixin to a controller action, in order to determine which
+ * HTTP method (`'get'`, `'post'`, `'put'`, `'delete'` or `'patch'`) the action
+ * should listen to and optionally the path to which it is mapped, defined in
+ * relation to the route path of its controller. By default, the normalized
+ * method name is used as the action's path, and the `'get'` method is assigned
+ * if none is provided.
+ */
+export const action: (method: string, path: string) => Mixin
+
+/**
+ * Apply the authorize mixin to a controller action, in order to determines
+ * whether or how the request is authorized. This value can either be one of the
+ * values as described below, an array of them or a function which returns one
+ * or more of them.
+ *
+ * - Boolean: `true` if the action should be authorized, `false` otherwise.
+ * - '$self': The requested member is checked against `ctx.state.user` and the
+ *   action is only authorized if it matches the member.
+ * - '$owner': The member is asked if it is owned by `ctx.state.user` through
+ *   the optional `Model.$hasOwner()` method.
+ * - Any string: `ctx.state.user` is checked for this role through the
+ *   overridable `UserModel.hasRole()` method.
+ */
+export const authorize: (
+  authorize: (ctx: KoaContext) => void | boolean | OrArrayOf<string>
+) => Mixin
+
+/**
+ * Apply the parameters mixin to a controller action, in order to apply
+ * automatic mapping of Koa.js' `ctx.query` object to method parameters along
+ * with their automatic validation.
+ *
+ * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-properties.md Model Properties}
+ */
+export const parameters: (params: { [key: string]: Schema }) => Mixin
+
+/**
+ * Apply the returns mixin to a controller action, in order to provide a schema
+ * for the value returned from the action handler and optionally map the value
+ * to a key inside a returned object when it contains a `name` property.
+ */
+export const returns: (
+  returns: Schema & { name?: string },
+  options: any
+) => Mixin
+
+/**
+ * Apply the scope mixin to a controller action, in order to determine the
+ * scope(s) to be applied when loading the relation's models. The scope needs to
+ * be defined in the related model class' scopes definitions.
+ */
+export const scope: (...scopes: string[]) => Mixin
+
+/**
+ * Apply the transacted mixin to a controller action in order to determine
+ * whether queries in the action should be executed within a transaction. Any
+ * failure will mean the database will rollback any queries executed to the
+ * pre-transaction state.
+ */
+export const transacted: () => Mixin
+
+/* ------------------------------ End Mixins ----------------------------- */
+
+export type HTTPMethod =
+  | 'get'
+  | 'post'
+  | 'put'
+  | 'delete'
+  | 'patch'
+  | 'options'
+  | 'trace'
+  | 'connect'
+
+export interface KnexHelper {
+  getDialect(): string
+
+  isPostgreSQL(): boolean
+
+  isMySQL(): boolean
+
+  isSQLite(): boolean
+
+  isMsSQL(): boolean
+}
+
+export type Keyword =
+  | SetOptional<Ajv.MacroKeywordDefinition, 'keyword'>
+  | SetOptional<Ajv.CodeKeywordDefinition, 'keyword'>
+  | SetOptional<Ajv.FuncKeywordDefinition, 'keyword'>
+export type Format = Ajv.ValidateFunction | Ajv.FormatDefinition<string>
+export type Id = string | number
+export type KoaContext<$State = any> = Koa.ParameterizedContext<
+  $State,
+  {
+    transaction: objection.Transaction
+    session: koaSession.ContextSession & { state: { user: any } }
+  }
+>
+
+type LiteralUnion<T extends U, U = string> = T | (U & Record<never, never>)
+
+type ReflectArrayType<Source, Target> = Source extends any[] ? Target[] : Target
+
+type OrArrayOf<T> = T[] | T
+
+type OrReadOnly<T> = Readonly<T> | T
+
+type OrPromiseOf<T> = Promise<T> | T
+
+type modelFromModelController<$ModelController extends ModelController<Model>> =
+  InstanceType<Exclude<$ModelController['modelClass'], undefined>>
+
+export type SelectModelProperties<T> = {
+  [$Key in SelectModelKeys<T>]: T[$Key] extends Model
+    ? SelectModelProperties<T[$Key]>
+    : T[$Key]
+}
+
+// https://stackoverflow.com/questions/49927523/disallow-call-with-any/49928360#49928360
+type AnyGate<
+  $CheckType,
+  $TypeWhenNotAny,
+  $TypeWhenAny = $CheckType
+> = 0 extends 1 & $CheckType ? $TypeWhenAny : $TypeWhenNotAny
+
+export type SelectModelKeys<T> = AnyGate<
+  T,
+  Exclude<
+    keyof ConditionalExcept<T, Function>,
+    `$${string}` | 'QueryBuilderType' | 'foreignKeyId'
+  >,
+  string
+>
+
+/* ---------------------- Extended from Ajv JSON Schema --------------------- */
+
+export type Schema<T = any> = JSONSchemaType<T> & {
+  // keywords/_validate.js
+  validate?: (params: {
+    data: any
+    parentData: object | any[]
+    rootData: object | any[]
+    dataPath: string
+    parentIndex?: number
+    parentKey?: string
+    app: Application<Models>
+    validator: Validator
+    options: any
+  }) => boolean | void
+
+  // keywords/_validate.js
+  validateAsync?: (params: {
+    data: any
+    parentData: object | any[]
+    rootData: object | any[]
+    dataPath: string
+    parentIndex?: number
+    parentKey?: string
+    app: Application<Models>
+    validator: Validator
+    options: any
+  }) => Promise<boolean | void>
+
+  // keywords/_instanceof.js
+  /**
+   * Validates whether the value is an instance of at least one of the passed
+   * types.
+   */
+  instanceof?: OrArrayOf<
+    | LiteralUnion<
+        | 'Object'
+        | 'Array'
+        | 'Function'
+        | 'String'
+        | 'Number'
+        | 'Boolean'
+        | 'Date'
+        | 'RegExp'
+        | 'Buffer'
+      >
+    | Function
+    | typeof Object
+    | typeof Array
+    | typeof Function
+    | typeof String
+    | typeof Number
+    | typeof Boolean
+    | typeof Date
+    | typeof RegExp
+    | typeof Buffer
+  >
+}
+
+declare type StrictNullChecksWrapper<
+  Name extends string,
+  Type
+> = undefined extends null
+  ? `strictNullChecks must be true in tsconfig to use ${Name}`
+  : Type
+declare type UnionToIntersection<U> = (
+  U extends any ? (_: U) => void : never
+) extends (_: infer I) => void
+  ? I
+  : never
+declare type SomeJSONSchema = UncheckedJSONSchemaType<Known, true>
+declare type UncheckedPartialSchema<T> = Partial<
+  UncheckedJSONSchemaType<T, true>
+>
+declare type PartialSchema<T> = StrictNullChecksWrapper<
+  'PartialSchema',
+  UncheckedPartialSchema<T>
+>
+declare type JSONType<
+  T extends string,
+  IsPartial extends boolean
+> = IsPartial extends true ? T | undefined : T
+interface NumberKeywords {
+  minimum?: number
+  maximum?: number
+  exclusiveMinimum?: number
+  exclusiveMaximum?: number
+  multipleOf?: number
+  format?: string
+  range?: [number, number]
+}
+interface StringKeywords {
+  minLength?: number
+  maxLength?: number
+  pattern?: string
+  format?: LiteralUnion<
+    | 'date'
+    | 'time'
+    | 'uri'
+    | 'uri-reference'
+    | 'uri-template'
+    | 'email'
+    | 'hostname'
+    | 'ipv4'
+    | 'ipv6'
+    | 'uuid'
+    | 'json-pointer'
+    | 'relative-json-pointer'
+    | 'datetime'
+    | 'timestamp'
+  >
+}
+declare type UncheckedJSONSchemaType<
+  T,
+  IsPartial extends boolean
+> = // these two unions allow arbitrary unions of types
+(| {
+      anyOf: readonly UncheckedJSONSchemaType<T, IsPartial>[]
+    }
+  | {
+      oneOf: readonly UncheckedJSONSchemaType<T, IsPartial>[]
+    }
+  | ({
+      type: readonly (T extends number
+        ? JSONType<'number' | 'integer', IsPartial>
+        : T extends string
+        ? JSONType<'string', IsPartial>
+        : T extends boolean
+        ? JSONType<'boolean', IsPartial>
+        : never)[]
+    } & UnionToIntersection<
+      T extends number
+        ? NumberKeywords
+        : T extends string
+        ? StringKeywords
+        : T extends boolean
+        ? {}
+        : never
+    >)
+  | ((T extends number
+      ? {
+          type: JSONType<'number' | 'integer', IsPartial>
+        } & NumberKeywords
+      : T extends string
+      ? {
+          type: JSONType<
+            'string' | 'text' | 'date' | 'datetime' | 'timestamp',
+            IsPartial
+          >
+        } & StringKeywords
+      : T extends Date
+      ? {
+          type: JSONType<'date' | 'datetime' | 'timestamp', IsPartial>
+        }
+      : T extends boolean
+      ? {
+          type: JSONType<'boolean', IsPartial>
+        }
+      : T extends readonly [any, ...any[]]
+      ? {
+          type: JSONType<'array', IsPartial>
+          items: {
+            readonly [K in keyof T]-?: UncheckedJSONSchemaType<T[K], false> &
+              Nullable<T[K]>
+          } & {
+            length: T['length']
+          }
+          minItems: T['length']
+        } & (
+          | {
+              maxItems: T['length']
+            }
+          | {
+              additionalItems: false
+            }
+        )
+      : T extends readonly any[]
+      ? {
+          type: JSONType<'array', IsPartial>
+          items: UncheckedJSONSchemaType<T[0], false>
+          contains?: UncheckedPartialSchema<T[0]>
+          minItems?: number
+          maxItems?: number
+          minContains?: number
+          maxContains?: number
+          uniqueItems?: true
+          additionalItems?: never
+        }
+      : T extends Record<string, any>
+      ? {
+          type: JSONType<'object', IsPartial>
+          additionalProperties?:
+            | boolean
+            | UncheckedJSONSchemaType<T[string], false>
+          unevaluatedProperties?:
+            | boolean
+            | UncheckedJSONSchemaType<T[string], false>
+          properties?: IsPartial extends true
+            ? Partial<UncheckedPropertiesSchema<T>>
+            : UncheckedPropertiesSchema<T>
+          patternProperties?: Record<
+            string,
+            UncheckedJSONSchemaType<T[string], false>
+          >
+          propertyNames?: Omit<
+            UncheckedJSONSchemaType<string, false>,
+            'type'
+          > & {
+            type?: 'string'
+          }
+          dependencies?: {
+            [K in keyof T]?: Readonly<(keyof T)[]> | UncheckedPartialSchema<T>
+          }
+          dependentRequired?: {
+            [K in keyof T]?: Readonly<(keyof T)[]>
+          }
+          dependentSchemas?: {
+            [K in keyof T]?: UncheckedPartialSchema<T>
+          }
+          minProperties?: number
+          maxProperties?: number
+        } & (IsPartial extends true
+          ? {
+              required: Readonly<(keyof T)[] | boolean>
+            }
+          : [UncheckedRequiredMembers<T>] extends [never]
+          ? {
+              required?: Readonly<UncheckedRequiredMembers<T>[]> | boolean
+            }
+          : {
+              required: Readonly<UncheckedRequiredMembers<T>[]> | boolean
+            })
+      : T extends null
+      ? {
+          type: JSONType<'null', IsPartial>
+          nullable: true
+        }
+      : never) & {
+      allOf?: Readonly<UncheckedPartialSchema<T>[]>
+      anyOf?: Readonly<UncheckedPartialSchema<T>[]>
+      oneOf?: Readonly<UncheckedPartialSchema<T>[]>
+      if?: UncheckedPartialSchema<T>
+      then?: UncheckedPartialSchema<T>
+      else?: UncheckedPartialSchema<T>
+      not?: UncheckedPartialSchema<T>
+    })
+) & {
+  [keyword: string]: any
+  $id?: string
+  $ref?: string
+  $defs?: Record<string, UncheckedJSONSchemaType<Known, true>>
+  definitions?: Record<string, UncheckedJSONSchemaType<Known, true>>
+}
+declare type JSONSchemaType<T> = StrictNullChecksWrapper<
+  'JSONSchemaType',
+  UncheckedJSONSchemaType<T, false>
+>
+declare type Known =
+  | {
+      [key: string]: Known
+    }
+  | [Known, ...Known[]]
+  | Known[]
+  | number
+  | string
+  | boolean
+  | null
+declare type UncheckedPropertiesSchema<T> = {
+  [K in keyof T]-?:
+    | (UncheckedJSONSchemaType<T[K], false> & Nullable<T[K]>)
+    | {
+        $ref: string
+      }
+}
+declare type PropertiesSchema<T> = StrictNullChecksWrapper<
+  'PropertiesSchema',
+  UncheckedPropertiesSchema<T>
+>
+declare type UncheckedRequiredMembers<T> = {
+  [K in keyof T]-?: undefined extends T[K] ? never : K
+}[keyof T]
+declare type RequiredMembers<T> = StrictNullChecksWrapper<
+  'RequiredMembers',
+  UncheckedRequiredMembers<T>
+>
+declare type Nullable<T> = undefined extends T
+  ? {
+      nullable: true
+      const?: null
+      enum?: Readonly<(T | null)[]>
+      default?: T | null
+    }
+  : {
+      const?: T
+      enum?: Readonly<T[]>
+      default?: T
+    }