velocious 1.0.430 → 1.0.431

package/src/configuration-types.js

@@ -0,0 +1,429 @@
+// @ts-check
+
+/**
+ * @module types
+ */
+
+/**
+ * @typedef {function({request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, response: import("./http-server/client/response.js").default}): Promise<void>} CorsType
+ */
+
+/**
+ * @typedef {function({request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined, subscription?: {channel: string, params?: Record<string, ?>}, client: import("./http-server/client/index.js").default, websocketSession: import("./http-server/client/websocket-session.js").default, configuration: import("./configuration.js").default}): typeof import("./http-server/websocket-channel.js").default | import("./http-server/websocket-channel.js").default | void | Promise<typeof import("./http-server/websocket-channel.js").default | import("./http-server/websocket-channel.js").default | void>} WebsocketChannelResolverType
+ */
+
+/**
+ * @typedef {object} WebsocketMessageHandler
+ * @property {function({message: ?, session: import("./http-server/client/websocket-session.js").default}) : Promise<void> | void} [onMessage] - Handler for incoming websocket messages.
+ * @property {function({session: import("./http-server/client/websocket-session.js").default}) : Promise<void> | void} [onOpen] - Handler when the websocket session opens.
+ * @property {function({session: import("./http-server/client/websocket-session.js").default}) : Promise<void> | void} [onClose] - Handler when the websocket session closes.
+ * @property {function({error: Error, session: import("./http-server/client/websocket-session.js").default}) : Promise<void> | void} [onError] - Handler when a websocket message errors.
+ */
+
+/**
+ * @typedef {function({request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined, client: import("./http-server/client/index.js").default, configuration: import("./configuration.js").default}): WebsocketMessageHandler | void | Promise<WebsocketMessageHandler | void>} WebsocketMessageHandlerResolverType
+ */
+
+/**
+ * @typedef {(id: string) => {default: typeof import("./initializer.js").default}} InitializersRequireContextType
+ * @typedef {InitializersRequireContextType & {
+ *   keys: () => string[],
+ *   id: string
+ * }} WebpackRequireContext
+ * @typedef {{requireContext: WebpackRequireContext}} InitializersExportType
+ * @typedef {function({configuration: import("./configuration.js").default}) : Promise<InitializersExportType>} InitializersType
+ */
+
+/**
+ * @typedef {object} SqlConfig
+ * @property {string} [database] - Database name for the SQL driver.
+ * @property {object} [options] - Driver-specific connection options.
+ * @property {boolean} [options.encrypt] - Whether to encrypt the connection (MSSQL).
+ * @property {string} [options.schema] - Default schema for unqualified table lookups (MSSQL).
+ * @property {string} [options.serverName] - TLS SNI server name override for MSSQL (empty string disables SNI).
+ * @property {boolean} [options.trustServerCertificate] - Whether to trust the server certificate (MSSQL).
+ * @property {string} [password] - Password for the SQL user.
+ * @property {object} [pool] - Connection pool configuration.
+ * @property {number} [pool.max] - Maximum number of connections.
+ * @property {number} [pool.min] - Minimum number of connections.
+ * @property {number} [pool.idleTimeoutMillis] - Idle timeout before releasing a connection.
+ * @property {string} [server] - SQL server hostname.
+ * @property {string} [user] - SQL username.
+ */
+
+/**
+ * @typedef {object} DatabasePoolConfiguration
+ * @property {number | null} [idleTimeoutMillis] - Idle timeout before closing a checked-in async-tracked connection. Set null to disable idle reaping. Default: 5000.
+ * @property {number} [max] - Maximum live async-tracked connections for this pool. Extra checkouts wait until a matching connection is checked in or capacity is freed.
+ */
+
+/**
+ * @typedef {object} DatabaseConfigurationType
+ * @property {string} [databaseCharset] - Default character set applied by `db:create` via mysql/mariadb `CREATE DATABASE ... CHARACTER SET`. Distinct from `charset`, which is the client connection charset forwarded to the mysql2 driver.
+ * @property {string} [databaseCollation] - Default collation applied by `db:create` via mysql/mariadb `CREATE DATABASE ... COLLATE`.
+ * @property {string} [database] - Database name for this connection.
+ * @property {typeof import("./database/drivers/base.js").default} [driver] - Driver class to use for this database.
+ * @property {typeof import("./database/pool/base.js").default} [poolType] - Pool class to use for this database.
+ * @property {function() : ?} [getConnection] - Custom connection factory override.
+ * @property {string} [host] - Database host.
+ * @property {boolean} [migrations] - Whether migrations are enabled for this database.
+ * @property {string} [password] - Password for the database user.
+ * @property {number} [port] - Database port.
+ * @property {DatabasePoolConfiguration} [pool] - Velocious database pool lifecycle configuration.
+ * @property {string} [name] - Friendly name for the configuration.
+ * @property {(file: string) => string} [locateFile] - Optional sqlite-web sql.js wasm resolver (`initSqlJs({locateFile})`).
+ * @property {boolean} [readOnly] - Whether writes should be blocked for this database.
+ * @property {string} [schema] - Default schema for unqualified table lookups (MSSQL).
+ * @property {boolean} [schemaCache] - Whether schema metadata should be cached on the driver. Defaults to true.
+ * @property {object} [record] - Record-level configuration.
+ * @property {boolean} [record.transactions] - Whether record operations should use transactions.
+ * @property {boolean} [reset] - Whether to reset the database on startup.
+ * @property {SqlConfig} [sqlConfig] - Driver-specific SQL config.
+ * @property {boolean} [tenantOnly] - Whether this database identifier is only active inside a resolved tenant context.
+ * @property {"mssql" | "mysql" | "pgsql" | "sqlite"} [type] - Database type identifier.
+ * @property {string} [useDatabase] - Database to switch to after connecting.
+ * @property {string} [username] - Username for database authentication.
+ */
+
+/**
+ * @typedef {"debug-low-level" | "debug" | "info" | "warn" | "error"} LogLevel
+ */
+
+/**
+ * @typedef {object} LoggingOutputPayload
+ * @property {LogLevel} level - Log level.
+ * @property {string} message - Formatted message.
+ * @property {string} subject - Log subject.
+ * @property {Date} timestamp - Timestamp.
+ */
+
+/**
+ * @typedef {object} LoggingOutput
+ * @property {function(LoggingOutputPayload): Promise<void> | void} write - Write a log entry.
+ * @property {LogLevel[]} [levels] - Default levels for this output.
+ */
+
+/**
+ * @typedef {object} LoggingOutputConfig
+ * @property {LoggingOutput} output - Output instance.
+ * @property {Array<LogLevel>} [levels] - Levels enabled for this output.
+ */
+
+/**
+ * @typedef {LoggingOutputConfig | LoggingOutput | import("./logger/base-logger.js").default} LoggerConfig
+ */
+
+/**
+ * @typedef {object} LoggingConfiguration
+ * @property {boolean} [console] - Enable/disable console logging for request logging. Defaults to true outside of "test" and for HTTP server logs.
+ * @property {boolean} [file] - Enable/disable writing logs to a file. Defaults to true.
+ * @property {string} [directory] - Directory where log files are stored. Defaults to "<project>/log".
+ * @property {string} [filePath] - Explicit path for the log file. Defaults to "<directory>/<environment>.log".
+ * @property {Array<"debug-low-level" | "debug" | "info" | "warn" | "error">} [levels] - Override which log levels are emitted.
+ * @property {boolean} [debugLowLevel] - Convenience flag to include very low-level debug logs.
+ * @property {boolean} [queryLogging] - Enable/disable database query logging. Defaults to true outside test and false in test.
+ * @property {LoggerConfig[]} [loggers] - Logger instances (converted to outputs when configured).
+ * @property {LoggingOutputConfig[]} [outputs] - Explicit logger outputs (overrides console/file defaults when provided).
+ */
+
+/**
+ * @typedef {object} StructureSqlConfiguration
+ * @property {string[]} [enabledEnvironments] - Environments allowed to write structure sql files during automatic migration dumps.
+ * @property {string[]} [disabledEnvironments] - Environments that should skip writing structure sql files.
+ */
+
+/**
+ * @typedef {"beacon" | "polling"} BackgroundJobsDispatchStrategy
+ *
+ * - `"beacon"` (default): event-driven dispatch. The
+ *   `background-jobs-main` process drains the queue on enqueue, on
+ *   worker readiness, on Beacon broadcasts (so cross-process enqueues
+ *   wake it), and arms a `setTimeout` for the soonest future-scheduled
+ *   job. Falls back gracefully to direct in-process triggering when
+ *   Beacon is not configured.
+ * - `"polling"`: legacy mode, runs a fixed-interval poll over the
+ *   `background_jobs` table (see `pollIntervalMs`).
+ */
+
+/**
+ * @typedef {object} BackgroundJobsConfiguration
+ * @property {string} [host] - Hostname for the background jobs main process.
+ * @property {number} [port] - Port for the background jobs main process.
+ * @property {string} [databaseIdentifier] - Database identifier used to store background jobs.
+ * @property {number} [maxConcurrentInlineJobs] - How many `forked: false` jobs a single
+ *   `background-jobs-worker` process is allowed to run in parallel. Concurrency
+ *   is at the JS event-loop level: every concurrent job shares the worker's
+ *   process and DB connection pool, so this should fit the pool size, not the
+ *   CPU count. Forking remains the right tool for memory isolation across
+ *   long-running jobs and for using more cores. Default: `4`.
+ * @property {number} [maxConcurrentForkedJobs] - How many out-of-process
+ *   `"forked"` or `"spawned"` jobs a single `background-jobs-worker` is
+ *   allowed to keep in flight. Default: `4`.
+ * @property {BackgroundJobsDispatchStrategy} [dispatchStrategy] - How the main process
+ *   detects new work. Defaults to `"beacon"` (event-driven). Set to `"polling"`
+ *   to restore the legacy fixed-interval poll.
+ * @property {number} [pollIntervalMs] - Poll interval in milliseconds. Only used
+ *   when `dispatchStrategy === "polling"`. Default: `1000`.
+ */
+
+/**
+ * @typedef {object} BeaconConfiguration
+ * @property {boolean} [enabled] - Whether to connect to a Beacon broker. Defaults to false unless `host`/`port` or `inProcess: true` are set, or env vars are present. Explicit `false` disables Beacon even when env vars are set.
+ * @property {boolean} [inProcess] - When true, use a module-level in-process broker singleton instead of connecting over TCP. Mutually exclusive with `host`/`port`. Useful for tests and single-process deployments.
+ * @property {string} [host] - Hostname of the Beacon broker daemon.
+ * @property {number} [port] - Port of the Beacon broker daemon.
+ * @property {string} [peerType] - Optional human-readable label for this peer (e.g. "server", "background-jobs-worker").
+ * @property {number} [unreachableReportMs] - Grace window (ms) a beacon connect/disconnect blip must persist before it is reported as a framework-error. Transient outages that recover within this window (e.g. a deploy restarting the broker) are not reported. Defaults to 30000.
+ */
+
+/**
+ * @typedef {object} HttpServerConfiguration
+ * @property {string} [host] - Hostname to bind the HTTP server to.
+ * @property {boolean} [inProcess] - Run HTTP handlers in the main thread instead of worker threads.
+ * @property {number} [maxWorkers] - Backward-compatible alias for workers.
+ * @property {number} [port] - Port to bind the HTTP server to.
+ * @property {number} [workers] - Worker handlers to start for the HTTP server.
+ */
+
+/**
+ * @typedef {object} ScheduledBackgroundJobEveryOptions
+ * @property {number | string} [firstIn] - Delay before the first enqueue.
+ * @property {number | string} [first_in] - Sidekiq-style alias for `firstIn`.
+ */
+
+/**
+ * @typedef {object} ScheduledBackgroundJobConfiguration
+ * @property {Array<?>} [args] - Arguments passed to the job when enqueued.
+ * @property {typeof import("./background-jobs/job.js").default} class - Job class to enqueue.
+ * @property {string} [cron] - Crontab expression (5-field POSIX, plus `@hourly`/`@daily`/`@weekly`/`@monthly`/`@yearly`/`@midnight`). Mutually exclusive with `every`.
+ * @property {boolean} [enabled] - Whether the schedule is enabled.
+ * @property {number | string | [number | string, ScheduledBackgroundJobEveryOptions]} [every] - Repeat interval. Either `every` or `cron` must be set.
+ * @property {import("./background-jobs/types.js").BackgroundJobOptions} [options] - Job options.
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {configuration?: import("./configuration.js").default, currentUser?: Record<string, unknown> | null, params?: Record<string, unknown>, request?: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default}} VelociousLooseObject
+ */
+
+/**
+ * @typedef {new (args: {attachmentName?: string, configuration: import("./configuration.js").default, modelClass?: typeof import("./database/record/index.js").default, name?: string, options?: Record<string, ?>}) => object} AttachmentDriverConstructor
+ */
+
+/**
+ * @typedef {object} ScheduledBackgroundJobsConfiguration
+ * @property {Record<string, ScheduledBackgroundJobConfiguration>} jobs - Scheduled jobs keyed by name.
+ */
+
+/**
+ * @typedef {function({configuration: import("./configuration.js").default}) : ScheduledBackgroundJobsConfiguration | Promise<ScheduledBackgroundJobsConfiguration>} ScheduledBackgroundJobsLoaderType
+ */
+
+/**
+ * @typedef {object} AttachmentDriverConfiguration
+ * @property {function({configuration: import("./configuration.js").default, name: string, options: Record<string, ?>}) : Record<string, ?>} [create] - Optional factory for a custom attachment driver instance.
+ * @property {AttachmentDriverConstructor} [driverClass] - Optional custom attachment driver class.
+ * @property {Record<string, ?>} [instance] - Optional custom attachment driver instance.
+ */
+
+/**
+ * @typedef {object} AttachmentsConfiguration
+ * @property {string} [defaultDriver] - Default attachment storage driver name.
+ * @property {Record<string, AttachmentDriverConfiguration & Record<string, ?>>} [drivers] - Named attachment driver configurations.
+ * @property {boolean} [allowPathInput] - Whether `{path: ...}` attachment input is allowed.
+ * @property {string[]} [allowedPathPrefixes] - Optional allowlist of directories for `{path: ...}` input.
+ */
+
+/**
+ * @typedef {object} MailerBackend
+ * @property {function({payload: import("./mailer.js").MailerDeliveryPayload, configuration: import("./configuration.js").default}) : Promise<?> | ?} deliver - Deliver a mailer payload.
+ */
+
+
+/**
+ * @typedef {Record<string, string[]>} LocaleFallbacksType
+ */
+
+/**
+ * @typedef {object} FrontendModelRelationshipConfiguration
+ * @property {"belongsTo" | "hasOne" | "hasMany"} type - Relationship type.
+ * @property {string} [model] - Target model class name.
+ * @property {string} [className] - Alias of target model class name.
+ * @property {string} [modelClassName] - Explicit target model class name.
+ */
+
+/**
+ * @typedef {object} FrontendModelAttributeConfiguration
+ * @property {string} [type] - Column type name.
+ * @property {string} [columnType] - Alias for column type name.
+ * @property {string} [sqlType] - Alias for column type name.
+ * @property {string} [dataType] - Alias for column type name.
+ * @property {boolean} [null] - Whether value can be null.
+ * @property {boolean} [selectedByDefault] - Whether included in default serialization. Defaults to true.
+ */
+
+/**
+ * @typedef {object} FrontendModelAttachmentConfiguration
+ * @property {"hasOne" | "hasMany"} type - Attachment cardinality.
+ */
+
+/**
+ * @typedef {object} FrontendModelResourceConfiguration
+ * @property {string[] | Record<string, FrontendModelAttributeConfiguration | import("./database/drivers/base-column.js").default | boolean>} attributes - Attributes to expose on the frontend model.
+ * @property {string[]} [abilities] - Ability action list (camelCase action names). Defaults to `["read"]` for `find` and `index` when omitted.
+ * @property {Record<string, FrontendModelAttachmentConfiguration>} [attachments] - Attachment helpers keyed by attachment name.
+ * @property {string[]} [commands] - Legacy built-in command names (`index`, `find`, `create`, `update`, `destroy`, `attach`, `download`, `url`).
+ * @property {string[]} [collectionCommands] - Custom collection commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
+ * @property {string[]} [memberCommands] - Custom member commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
+ * @property {string[]} [builtInCollectionCommands] - Built-in collection command names (`index`, `create`).
+ * @property {string[]} [builtInMemberCommands] - Built-in member command names (`find`, `update`, `destroy`, `attach`, `download`, `url`).
+ * @property {string[]} [relationships] - Relationship names to expose in frontend models. Type and target model are inferred from the backend model's registered relationships.
+ * @property {string} [primaryKey] - Primary key attribute name.
+ * @property {FrontendModelResourceServerConfiguration} [server] - Optional legacy backend behavior overrides for built-in frontend actions.
+ */
+
+/**
+ * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands"> & {
+ *   abilities: FrontendModelResourceAbilitiesConfiguration
+ *   builtInCollectionCommands: Record<string, string>
+ *   builtInMemberCommands: Record<string, string>
+ *   collectionCommands: Record<string, string>
+ *   memberCommands: Record<string, string>
+ * }} NormalizedFrontendModelResourceConfiguration
+ */
+
+/**
+ * @typedef {typeof import("./frontend-model-resource/base-resource.js").default} FrontendModelResourceClassType
+ */
+
+/**
+ * @typedef {FrontendModelResourceClassType} FrontendModelResourceDefinition
+ */
+
+/**
+ * @typedef {object} FrontendModelResourceAbilitiesConfiguration
+ * @property {string} [index] - Ability action for frontend index.
+ * @property {string} [find] - Ability action for frontend find.
+ * @property {string} [create] - Ability action for frontend create.
+ * @property {string} [update] - Ability action for frontend update.
+ * @property {string} [destroy] - Ability action for frontend destroy.
+ */
+
+/**
+ * @typedef {object} FrontendModelResourceServerConfiguration
+ * @property {function({action: "index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default}) : (boolean | void | Promise<boolean | void>)} [beforeAction] - Optional callback run before built-in frontend actions.
+ * @property {function({action: "index", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default}) : Promise<import("./database/record/index.js").default[]>} [records] - Records loader for frontendIndex.
+ * @property {function({action: "index" | "find" | "create" | "update", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, model: import("./database/record/index.js").default}) : Record<string, ?> | Promise<Record<string, ?>>} [serialize] - Record serializer for response payloads.
+ * @property {function({action: "find" | "update" | "destroy" | "attach" | "download" | "url", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, id: string | number}) : Promise<import("./database/record/index.js").default | null>} [find] - Record loader for find/update/destroy/attach/download/url actions.
+ * @property {function({action: "create", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, attributes: Record<string, ?>}) : Promise<import("./database/record/index.js").default>} [create] - Custom create callback.
+ * @property {function({action: "update", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, model: import("./database/record/index.js").default, attributes: Record<string, ?>}) : Promise<import("./database/record/index.js").default | void>} [update] - Custom update callback.
+ * @property {function({action: "destroy", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, model: import("./database/record/index.js").default}) : Promise<void>} [destroy] - Custom destroy callback.
+ */
+
+/**
+ * @typedef {object} BackendProjectConfiguration
+ * @property {string} path - Path to the backend project.
+ * @property {string} [frontendModelsOutputPath] - Optional output project path where `src/frontend-models` should be generated.
+ * @property {Record<string, FrontendModelResourceDefinition>} [frontendModels] - Auto-discovered frontend model definitions keyed by model class name. Set internally by the environment handler — do not set manually.
+ */
+
+/**
+ * @typedef {object} RouteResolverHookArgs
+ * @property {import("./configuration.js").default} configuration - Configuration instance.
+ * @property {Record<string, ?>} params - Mutable request params object.
+ * @property {string} currentPath - Request path without query.
+ * @property {boolean} [hasMatchingCustomRoute] - True when matching a configured custom route.
+ * @property {import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default} request - Request object.
+ * @property {import("./http-server/client/response.js").default} response - Response object.
+ * @property {import("./routes/resolver.js").default} resolver - Resolver instance.
+ */
+
+/**
+ * @typedef {object} RouteResolverHookResult
+ * @property {string} action - Dasherized action name (for example `frontend-index`).
+ * @property {string} controller - Controller path (for example `accounts`).
+ * @property {typeof import("./controller.js").default} [controllerClass] - Optional controller class override.
+ * @property {string} [controllerPath] - Optional absolute/relative controller file path override.
+ * @property {Record<string, ?>} [params] - Extra params to merge for controller/action.
+ * @property {boolean} [skipAbilityResolution] - Whether to run the controller action without resolving request ability.
+ * @property {boolean} [skipControllerConnections] - Whether to run the controller action without the automatic database checkout wrapper.
+ * @property {boolean} [skipTenantResolution] - Whether to run the controller action without resolving request tenant.
+ * @property {string} [viewPath] - Optional view path override used by controller render lookups.
+ */
+
+/**
+ * @typedef {function(RouteResolverHookArgs) : RouteResolverHookResult | null | Promise<RouteResolverHookResult | null>} RouteResolverHookType
+ */
+
+/**
+ * @typedef {typeof import("./authorization/base-resource.js").default} AbilityResourceClassType
+ */
+
+/**
+ * @typedef {function({configuration: import("./configuration.js").default, params: Record<string, ?>, request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, response: import("./http-server/client/response.js").default}) : import("./authorization/ability.js").default | void | Promise<import("./authorization/ability.js").default | void>} AbilityResolverType
+ */
+
+/**
+ * @typedef {function({configuration: import("./configuration.js").default, params: Record<string, ?>, request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined, response: import("./http-server/client/response.js").default | undefined, subscription?: {channel: string, params?: Record<string, ?>}}) : ? | void | Promise<? | void>} TenantResolverType
+ */
+
+/**
+ * @typedef {function({configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ?}) : DatabaseConfigurationType | Partial<DatabaseConfigurationType> | void} TenantDatabaseResolverType
+ */
+
+/**
+ * @typedef {object} DebugEndpointConfiguration
+ * @property {string} [path] - HTTP path for the built-in debug endpoint. Defaults to `/velocious/debug`.
+ * @property {string} [token] - Bearer token required in the `Authorization: Bearer <token>` header. When set, requests without a matching token are not routed (404), so the endpoint stays hidden.
+ */
+
+/**
+ * @typedef {object} TenantDatabaseProviderType
+ * @property {function({configuration: import("./configuration.js").default, identifier: string}) : Array<?> | Promise<Array<?>>} listTenants - Lists tenants that should be created, checked, or migrated for this database identifier.
+ * @property {function({configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ?}) : void | Promise<void>} [createDatabase] - Creates the tenant database/schema for one tenant.
+ * @property {function({configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ?}) : void | Promise<void>} [dropDatabase] - Drops the tenant database/schema for one tenant.
+ * @property {function({configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ?}) : void | Promise<void>} [checkTenant] - Checks one tenant database before generic connection validation.
+ * @property {function({configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, migrationsApplied: number, tenant: ?}) : void | Promise<void>} [afterMigrateTenant] - Runs app-owned tenant work after generic migrations for one tenant. `migrationsApplied` is how many migrations actually ran (0 when the tenant was already up to date), so the app can skip expensive per-tenant work on no-op deploys.
+ */
+
+/**
+ * @typedef {object} ConfigurationArgsType
+ * @property {boolean} [autoload] - Globally enable auto-batch-preload of relationships on lazy access. Default true.
+ * @property {CorsType} [cors] - CORS configuration for the HTTP server.
+ * @property {string} [cookieSecret] - Secret for encrypting cookies.
+ * @property {AbilityResourceClassType[]} [abilityResources] - Resource classes used to define abilities per model.
+ * @property {AbilityResolverType} [abilityResolver] - Resolver for creating request-scoped ability instances.
+ * @property {AttachmentsConfiguration} [attachments] - Attachment storage configuration.
+ * @property {BackendProjectConfiguration[]} [backendProjects] - Backend project definitions used for frontend model generation.
+ * @property {{[key: string]: {[key: string]: DatabaseConfigurationType}}} database - Database configurations keyed by environment and identifier.
+ * @property {boolean} [debug] - Enable debug logging.
+ * @property {boolean | DebugEndpointConfiguration} [debugEndpoint] - Enable the built-in debug endpoint. Defaults to false.
+ * @property {string} [directory] - Base directory for the project.
+ * @property {boolean} [enforceTenantDatabaseScopes] - Require tenant-switched model queries to resolve a tenant database identifier. Defaults to true.
+ * @property {string} [environment] - Current environment name.
+ * @property {import("./environment-handlers/base.js").default} environmentHandler - Environment handler instance.
+ * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error details in client API payloads outside production. Defaults to false.
+ * @property {HttpServerConfiguration} [httpServer] - Default HTTP server configuration for applications started from this configuration.
+ * @property {LoggingConfiguration} [logging] - Logging configuration.
+ * @property {BackgroundJobsConfiguration} [backgroundJobs] - Background jobs configuration.
+ * @property {BeaconConfiguration} [beacon] - Beacon broadcast bus configuration.
+ * @property {ScheduledBackgroundJobsConfiguration | ScheduledBackgroundJobsLoaderType} [scheduledBackgroundJobs] - Scheduled background jobs configuration.
+ * @property {MailerBackend} [mailerBackend] - Mail delivery backend.
+ * @property {function({configuration: import("./configuration.js").default, type: string}) : void} initializeModels - Hook to register models for a given initialization type.
+ * @property {InitializersType} [initializers] - Initializer loader for environment bootstrapping.
+ * @property {string | function() : string} locale - Default locale or locale resolver.
+ * @property {string[]} locales - Supported locales.
+ * @property {LocaleFallbacksType} localeFallbacks - Locale fallback map.
+ * @property {StructureSqlConfiguration} [structureSql] - Structure SQL generation configuration.
+ * @property {TenantResolverType} [tenantResolver] - Resolver for creating request-scoped tenant context objects.
+ * @property {TenantDatabaseResolverType} [tenantDatabaseResolver] - Resolver for deriving tenant-specific database config overrides.
+ * @property {Record<string, TenantDatabaseProviderType>} [tenantDatabaseProviders] - Tenant database lifecycle providers keyed by database identifier.
+ * @property {string} [testing] - Path to the testing configuration file.
+ * @property {number | (() => number)} [timezoneOffsetMinutes] - Default timezone offset in minutes.
+ * @property {string | string[]} [trustedProxies] - Trusted reverse proxy address ranges used to resolve request remote addresses from forwarding headers.
+ * @property {number | (() => number)} [requestTimeoutMs] - Timeout in seconds for completing a HTTP request.
+ * @property {RouteResolverHookType[]} [routeResolverHooks] - Hook callbacks that can hijack unresolved routes.
+ * @property {WebsocketChannelResolverType} [websocketChannelResolver] - Resolve a websocket channel class/instance for each connection.
+ * @property {WebsocketMessageHandlerResolverType} [websocketMessageHandlerResolver] - Resolve a raw websocket message handler for each connection.
+ */
+
+export const nothing = {}