zerotal 1.9.0 → 1.10.0

package/README.md

@@ -27,7 +27,7 @@ import { Auth } from "zerotal/auth";
 | `zerotal/testing`   | `@zerotal/testing`   |
 | `zerotal/validator` | `@zerotal/validator` |
 
-Core's own subpaths are mirrored 1:1, so `zerotal` is a full drop-in for `@zerotal/core`: `zerotal/logger`, `zerotal/lock`, `zerotal/storage`, `zerotal/config`, `zerotal/view`, `zerotal/helpers`, `zerotal/facades`, `zerotal/http`, `zerotal/env`, `zerotal/carbon`, `zerotal/contracts`, `zerotal/commands`, `zerotal/assets`, `zerotal/security`, `zerotal/health`, `zerotal/metrics`, `zerotal/dev`, `zerotal/build` — and `jsx-runtime`, so `"jsxImportSource": "zerotal"` works for server JSX views. The one exception is `@zerotal/core/macros/config` (a Bun macro): import it from core directly.
+Core's own subpaths are mirrored 1:1, so `zerotal` is a full drop-in for `@zerotal/core`: `zerotal/logger`, `zerotal/lock`, `zerotal/storage`, `zerotal/config`, `zerotal/view`, `zerotal/helpers`, `zerotal/facades`, `zerotal/http`, `zerotal/env`, `zerotal/carbon`, `zerotal/contracts`, `zerotal/commands`, `zerotal/assets`, `zerotal/security`, `zerotal/health`, `zerotal/metrics`, `zerotal/dev`, `zerotal/build`, `zerotal/runtime` — and `jsx-runtime`, so `"jsxImportSource": "zerotal"` works for server JSX views. The one exception is `@zerotal/core/macros/config` (a Bun macro): import it from core directly.
 
 There is no behaviour here and no version skew: the meta package pins the same monorepo version as every `@zerotal/*` package it re-exports. Installing a scoped package directly is always equivalent — this package exists so a new app needs exactly one dependency to start.
 

package/api-surface.md

@@ -394,6 +394,7 @@ class LimiterDefinition = {
   register: () => LimiterDefinition
   toMiddleware: () => ThrottleMiddleware
   toMiddlewareClass: () => new () => ThrottleMiddleware
+  trustedProxies: (count: number) => LimiterDefinition
 }
 
 class MarkdownBuilder = {
@@ -808,23 +809,23 @@ interface ContainerBindings = {
 }
 
 interface CookieOptions = {
-  domain?: string
-  httpOnly?: boolean
-  maxAge?: number
+  domain?: string | undefined
+  httpOnly?: boolean | undefined
+  maxAge?: number | undefined
   name: string
-  path?: string
-  sameSite?: SameSite
-  secure?: boolean
+  path?: string | undefined
+  sameSite?: SameSite | undefined
+  secure?: boolean | undefined
   value: string
 }
 
 interface CorsOptions = {
-  allowedHeaders?: string[]
-  credentials?: boolean
-  exposedHeaders?: string[]
-  maxAge?: number
-  methods?: string[]
-  origin?: string | string[] | ((origin: string) => boolean)
+  allowedHeaders?: string[] | undefined
+  credentials?: boolean | undefined
+  exposedHeaders?: string[] | undefined
+  maxAge?: number | undefined
+  methods?: string[] | undefined
+  origin?: string | string[] | ((origin: string) => boolean) | undefined
 }
 
 interface DevProcessDefinition = {
@@ -870,9 +871,9 @@ interface ErrorDiagnosis = {
 }
 
 interface GroupOptions = {
-  domain?: string
-  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[]
-  prefix?: string
+  domain?: string | undefined
+  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[] | undefined
+  prefix?: string | undefined
 }
 
 interface ModelClass = {
@@ -925,25 +926,25 @@ interface RouterMacros = {
 }
 
 interface SecureHeadersOptions = {
-  contentSecurityPolicy?: string
-  frameOptions?: false | 'DENY' | 'SAMEORIGIN'
-  hstsIncludeSubDomains?: boolean
-  hstsMaxAge?: number
-  hstsPreload?: boolean
-  permissionsPolicy?: string | false
-  referrerPolicy?: string
-  secure?: boolean
+  contentSecurityPolicy?: string | undefined
+  frameOptions?: false | 'DENY' | 'SAMEORIGIN' | undefined
+  hstsIncludeSubDomains?: boolean | undefined
+  hstsMaxAge?: number | undefined
+  hstsPreload?: boolean | undefined
+  permissionsPolicy?: string | false | undefined
+  referrerPolicy?: string | undefined
+  secure?: boolean | undefined
 }
 
 interface StartZerotalOptions = {
-  configDir?: string
+  configDir?: string | undefined
 }
 
 interface ThrottleOptions = {
-  keyResolver?: (ctx: HttpContext) => string
+  keyResolver?: ((ctx: HttpContext) => string) | undefined
   maxAttempts: number
-  trustedProxies?: number
-  windowSeconds?: number
+  trustedProxies?: number | undefined
+  windowSeconds?: number | undefined
 }
 
 interface ViewRegistration = {
@@ -952,14 +953,14 @@ interface ViewRegistration = {
 }
 
 interface WebhookOptions = {
-  algorithm?: 'sha256' | 'sha1' | 'sha512'
-  format?: 'raw' | 'stripe'
-  header?: string
-  prefix?: string
+  algorithm?: 'sha256' | 'sha1' | 'sha512' | undefined
+  format?: 'raw' | 'stripe' | undefined
+  header?: string | undefined
+  prefix?: string | undefined
   secret: string
-  timestampHeader?: string
-  timestampSeparator?: string
-  tolerance?: number
+  timestampHeader?: string | undefined
+  timestampSeparator?: string | undefined
+  tolerance?: number | undefined
 }
 
 interface WebSocketHandlers = {
@@ -998,6 +999,8 @@ type NextFn = () => Promise<Response | void>
 
 type ParamsOf = P extends `${string}:${infer Name}/${infer Rest}` ? { [K in Name]: RouteParamValue; } & ParamsOf<`/${Rest}`> : P extends `${string}:${infer Name}` ? { [K in Name]: RouteParamValue; } : P extends `${string}*${string}` ? {    "*": RouteParamValue | readonly RouteParamValue[];} : Record<never, never>
 
+type Resolved = { [K in keyof T]-?: Exclude<T[K], undefined>; }
+
 type RouteArgs = [params?: RouteParamValues, query?: RouteQuery]
 
 type RouteMiddleware = MiddlewareClass[] | RouteMethodMiddleware
@@ -1925,50 +1928,50 @@ function tokenCan = (row: TokenRow, ability: string) => boolean
 
 interface AppleOAuth2Config = {
   clientId: string
-  clientSecret?: string
-  keyId?: string
-  privateKey?: string
+  clientSecret?: string | undefined
+  keyId?: string | undefined
+  privateKey?: string | undefined
   redirectUrl: string
-  scopes?: string[]
-  teamId?: string
+  scopes?: string[] | undefined
+  teamId?: string | undefined
 }
 
 interface AuthConfigShape = {
   algorithm: 'bcrypt' | 'argon2id'
-  twoFactor?: TwoFactorOptions
+  twoFactor?: TwoFactorOptions | undefined
 }
 
 interface AuthenticateSessionOptions = {
-  redirectTo?: string
+  redirectTo?: string | undefined
 }
 
 interface AuthOptions = {
-  mustVerifyEmail?: boolean
-  redirectTo?: string
-  verifyRedirectTo?: string
+  mustVerifyEmail?: boolean | undefined
+  redirectTo?: string | undefined
+  verifyRedirectTo?: string | undefined
 }
 
 interface BasicAuthOptions = {
-  field?: string
-  realm?: string
+  field?: string | undefined
+  realm?: string | undefined
 }
 
 interface CompromisedCheckOptions = {
-  endpoint?: string
-  threshold?: number
+  endpoint?: string | undefined
+  threshold?: number | undefined
 }
 
 interface ConfirmPasswordOptions = {
-  redirectTo?: string
-  timeoutSeconds?: number
+  redirectTo?: string | undefined
+  timeoutSeconds?: number | undefined
 }
 
 interface EmailOtpOptions = {
   deleteCode: (email: string) => Promise<void>
-  expireMinutes?: number
+  expireMinutes?: number | undefined
   findCode: (email: string) => Promise<{    code: string;    createdAt: Date;} | null>
-  length?: number
-  maxAttempts?: number
+  length?: number | undefined
+  maxAttempts?: number | undefined
   sendCode: (email: string, code: string) => Promise<void>
   storeCode: (email: string, hash: string, expiresAt: Date) => Promise<void>
 }
@@ -1982,31 +1985,31 @@ interface Guard = {
 }
 
 interface GuestOptions = {
-  redirectTo?: string
+  redirectTo?: string | undefined
 }
 
 interface JwtGuardOptions = {
-  header?: string
-  resolve?: (claims: JwtPayload) => Promise<unknown> | unknown
-  secret?: string
+  header?: string | undefined
+  resolve?: ((claims: JwtPayload) => Promise<unknown> | unknown) | undefined
+  secret?: string | undefined
 }
 
 interface JwtSignOptions = {
-  expiresIn?: number
-  issuedAt?: number
+  expiresIn?: number | undefined
+  issuedAt?: number | undefined
 }
 
 interface LoginOptions = {
-  remember?: boolean
+  remember?: boolean | undefined
 }
 
 interface LoginThrottleOptions = {
-  decaySeconds?: number
-  maxAttempts?: number
+  decaySeconds?: number | undefined
+  maxAttempts?: number | undefined
 }
 
 interface MagicLinkBrokerOptions = {
-  expiresInMinutes?: number
+  expiresInMinutes?: number | undefined
   findUser: (email: string) => Promise<U | null | undefined>
   secret: string
   sendLink: (email: string, signedUrl: string) => Promise<void>
@@ -2024,9 +2027,9 @@ interface NewToken = {
 
 interface OAuth2Config = {
   clientId: string
-  clientSecret?: string
+  clientSecret?: string | undefined
   redirectUrl: string
-  scopes?: string[]
+  scopes?: string[] | undefined
 }
 
 interface PasskeyCredential = {
@@ -2045,11 +2048,11 @@ interface PasskeysOptions = {
   findCredential: (credentialId: string) => Promise<PasskeyCredential | null | undefined>
   findUserCredentials: (userId: number) => Promise<PasskeyCredential[]>
   origin: string | string[]
-  requireUserVerification?: boolean
+  requireUserVerification?: boolean | undefined
   rpId: string
   rpName: string
   saveCredential: (credential: Omit<PasskeyCredential, 'id'>) => Promise<void>
-  timeoutSeconds?: number
+  timeoutSeconds?: number | undefined
   updateCounter: (id: number, newCounter: number) => Promise<void>
 }
 
@@ -2061,7 +2064,7 @@ interface PasskeyUser = {
 
 interface PasswordBrokerOptions = {
   deleteToken: (email: string) => Promise<void>
-  expireMinutes?: number
+  expireMinutes?: number | undefined
   findToken: (email: string) => Promise<{    token: string;    createdAt: Date;} | null>
   pruneTokens: (cutoff: Date) => Promise<void>
   resetPassword: (email: string, newPassword: string) => Promise<void>
@@ -2078,16 +2081,16 @@ interface QrMatrix = {
 }
 
 interface QrSvgOptions = {
-  alt?: string
-  class?: string
-  dark?: string
-  light?: string | null
-  quietZone?: number
-  size?: number
+  alt?: string | undefined
+  class?: string | undefined
+  dark?: string | undefined
+  light?: string | null | undefined
+  quietZone?: number | undefined
+  size?: number | undefined
 }
 
 interface RememberMeOptions = {
-  secure?: boolean
+  secure?: boolean | undefined
 }
 
 interface SocialSession = {
@@ -2129,19 +2132,19 @@ interface TokenRow = {
 }
 
 interface TwoFactorOptions = {
-  issuer?: string
-  recoveryCodeCount?: number
-  window?: number
+  issuer?: string | undefined
+  recoveryCodeCount?: number | undefined
+  window?: number | undefined
 }
 
 interface TwoFactorQrOptions = {
-  alt?: string
-  class?: string
-  dark?: string
-  issuer?: string
-  light?: string | null
-  quietZone?: number
-  size?: number
+  alt?: string | undefined
+  class?: string | undefined
+  dark?: string | undefined
+  issuer?: string | undefined
+  light?: string | null | undefined
+  quietZone?: number | undefined
+  size?: number | undefined
 }
 
 interface UserModel = {
@@ -2192,7 +2195,7 @@ type MagicLinkBrokerResult = 'magic.sent' | 'magic.user_not_found' | 'magic.ok'
 
 type PasswordBrokerResult = 'passwords.sent' | 'passwords.token' | 'passwords.reset'
 
-type SocialConfigShape = {    [driver: string]: (OAuth2Config & Record<string, unknown>) | undefined;    github?: OAuth2Config & Record<string, unknown>;    google?: OAuth2Config & Record<string, unknown>;    apple?: AppleOAuth2Config & Record<string, unknown>;    discord?: (OAuth2Config & Record<string, unknown>) | undefined;    microsoft?: (OAuth2Config & Record<string, unknown>) | undefined;    facebook?: (OAuth2Config & Record<string, unknown>) | undefined;    twitter?: (OAuth2Config & Record<string, unknown>) | undefined;    linkedin?: (OAuth2Config & Record<string, unknown>) | undefined;    gitlab?: (OAuth2Config & Record<string, unknown>) | undefined;}
+type SocialConfigShape = {    [driver: string]: (OAuth2Config & Record<string, unknown>) | undefined;    github?: (OAuth2Config & Record<string, unknown>) | undefined;    google?: (OAuth2Config & Record<string, unknown>) | undefined;    apple?: (AppleOAuth2Config & Record<string, unknown>) | undefined;    discord?: (OAuth2Config & Record<string, unknown>) | undefined;    microsoft?: (OAuth2Config & Record<string, unknown>) | undefined;    facebook?: (OAuth2Config & Record<string, unknown>) | undefined;    twitter?: (OAuth2Config & Record<string, unknown>) | undefined;    linkedin?: (OAuth2Config & Record<string, unknown>) | undefined;    gitlab?: (OAuth2Config & Record<string, unknown>) | undefined;}
 
 ## ./build  `(./src/build.ts)`
 
@@ -2203,7 +2206,7 @@ function addToDefaultArrayExport = (source: string, identifier: string) => strin
 function registerProvider = (options: RegisterProviderOptions) => Promise<RegisterResult>
 
 interface RegisterProviderOptions = {
-  bootstrapPath?: string
+  bootstrapPath?: string | undefined
   className: string
   importPath: string
 }
@@ -2357,7 +2360,7 @@ interface CacheDriver = {
 interface IdempotencyOptions = {
   cache: CacheManager | undefined
   header: string
-  lock?: LockManager
+  lock?: LockManager | undefined
   methods: string[]
   ttl: number
   useLock: boolean
@@ -2718,64 +2721,64 @@ function ClientConfig = (options?: Partial<ClientConfigShape>) => Partial<Client
 function createApiClient = <Routes extends ApiRouteMap>(config?: ApiClientConfig) => ApiClient<Routes>
 
 interface ApiClientConfig = {
-  baseUrl?: string
-  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions
-  csrf?: boolean | {    cookie?: string;    header?: string;}
-  headers?: Record<string, string>
-  onError?: (error: ApiClientError) => void | Promise<void>
-  onForbidden?: (error: ApiClientError) => void | Promise<void>
-  onRequest?: RequestInterceptor | RequestInterceptor[]
-  onResponse?: ResponseInterceptor | ResponseInterceptor[]
-  onUnauthorized?: (error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void
-  retry?: number | RetryOptions
-  timeout?: number
-  token?: TokenSource
-  withCredentials?: boolean
+  baseUrl?: string | undefined
+  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions | undefined
+  csrf?: boolean | {    cookie?: string;    header?: string;} | undefined
+  headers?: Record<string, string> | undefined
+  onError?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onForbidden?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onRequest?: RequestInterceptor | RequestInterceptor[] | undefined
+  onResponse?: ResponseInterceptor | ResponseInterceptor[] | undefined
+  onUnauthorized?: ((error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void) | undefined
+  retry?: number | RetryOptions | undefined
+  timeout?: number | undefined
+  token?: TokenSource | undefined
+  withCredentials?: boolean | undefined
 }
 
 interface CircuitBreakerOptions = {
-  isFailure?: (error: unknown) => boolean
-  resetTimeout?: number
-  threshold?: number
+  isFailure?: ((error: unknown) => boolean) | undefined
+  resetTimeout?: number | undefined
+  threshold?: number | undefined
 }
 
 interface ClientConfigShape = {
-  baseUrl?: string
-  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions
-  csrf?: boolean | {    cookie?: string;    header?: string;}
-  headers?: Record<string, string>
-  onError?: (error: ApiClientError) => void | Promise<void>
-  onForbidden?: (error: ApiClientError) => void | Promise<void>
-  onRequest?: RequestInterceptor | RequestInterceptor[]
-  onResponse?: ResponseInterceptor | ResponseInterceptor[]
-  onUnauthorized?: (error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void
-  retry?: number | RetryOptions
-  timeout?: number
-  token?: TokenSource
-  withCredentials?: boolean
+  baseUrl?: string | undefined
+  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions | undefined
+  csrf?: boolean | {    cookie?: string;    header?: string;} | undefined
+  headers?: Record<string, string> | undefined
+  onError?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onForbidden?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onRequest?: RequestInterceptor | RequestInterceptor[] | undefined
+  onResponse?: ResponseInterceptor | ResponseInterceptor[] | undefined
+  onUnauthorized?: ((error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void) | undefined
+  retry?: number | RetryOptions | undefined
+  timeout?: number | undefined
+  token?: TokenSource | undefined
+  withCredentials?: boolean | undefined
 }
 
 interface GetOptions = {
-  headers?: Record<string, string>
-  init?: Omit<RequestInit, 'method' | 'headers' | 'body'>
-  meta?: (meta: ResponseMeta) => void
-  query?: Q
-  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer'
-  retry?: number | false | RetryOptions
-  signal?: AbortSignal
-  timeout?: number
+  headers?: Record<string, string> | undefined
+  init?: Omit<RequestInit, 'method' | 'headers' | 'body'> | undefined
+  meta?: ((meta: ResponseMeta) => void) | undefined
+  query?: Q | undefined
+  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer' | undefined
+  retry?: number | false | RetryOptions | undefined
+  signal?: AbortSignal | undefined
+  timeout?: number | undefined
 }
 
 interface MutationOptions = {
-  headers?: Record<string, string>
-  init?: Omit<RequestInit, 'method' | 'headers' | 'body'>
-  meta?: (meta: ResponseMeta) => void
-  params?: Record<string, string | number>
-  query?: Q
-  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer'
-  retry?: number | false | RetryOptions
-  signal?: AbortSignal
-  timeout?: number
+  headers?: Record<string, string> | undefined
+  init?: Omit<RequestInit, 'method' | 'headers' | 'body'> | undefined
+  meta?: ((meta: ResponseMeta) => void) | undefined
+  params?: Record<string, string | number> | undefined
+  query?: Q | undefined
+  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer' | undefined
+  retry?: number | false | RetryOptions | undefined
+  signal?: AbortSignal | undefined
+  timeout?: number | undefined
 }
 
 interface PresenceMember = {
@@ -2791,13 +2794,13 @@ interface RequestConfig = {
 }
 
 interface RequestOptions = {
-  headers?: Record<string, string>
-  init?: Omit<RequestInit, 'method' | 'headers' | 'body'>
-  meta?: (meta: ResponseMeta) => void
-  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer'
-  retry?: number | false | RetryOptions
-  signal?: AbortSignal
-  timeout?: number
+  headers?: Record<string, string> | undefined
+  init?: Omit<RequestInit, 'method' | 'headers' | 'body'> | undefined
+  meta?: ((meta: ResponseMeta) => void) | undefined
+  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer' | undefined
+  retry?: number | false | RetryOptions | undefined
+  signal?: AbortSignal | undefined
+  timeout?: number | undefined
 }
 
 interface ResponseContext = {
@@ -2813,11 +2816,11 @@ interface ResponseMeta = {
 }
 
 interface RetryOptions = {
-  attempts?: number
-  backoff?: (attempt: number, retryAfterMs: number | null) => number
-  methods?: string[]
-  respectRetryAfter?: boolean
-  statuses?: number[]
+  attempts?: number | undefined
+  backoff?: ((attempt: number, retryAfterMs: number | null) => number) | undefined
+  methods?: string[] | undefined
+  respectRetryAfter?: boolean | undefined
+  statuses?: number[] | undefined
 }
 
 interface RouteShape = {
@@ -2838,20 +2841,20 @@ interface SocketLike = {
 }
 
 interface SocketOptions = {
-  WebSocket?: new (url: string) => SocketLike
-  auth?: {    params?: Record<string, string>;    headers?: Record<string, string>;}
-  authEndpoint?: string | false
-  autoConnect?: boolean
-  fetch?: typeof fetch
-  host?: string
-  maxReconnectDelay?: number
-  path?: string
-  pingInterval?: number
-  port?: string | number
-  reconnect?: boolean
-  reconnectDelay?: number
-  scheme?: 'ws' | 'wss'
-  url?: string
+  WebSocket?: (new (url: string) => SocketLike) | undefined
+  auth?: {    params?: Record<string, string>;    headers?: Record<string, string>;} | undefined
+  authEndpoint?: string | false | undefined
+  autoConnect?: boolean | undefined
+  fetch?: typeof fetch | undefined
+  host?: string | undefined
+  maxReconnectDelay?: number | undefined
+  path?: string | undefined
+  pingInterval?: number | undefined
+  port?: string | number | undefined
+  reconnect?: boolean | undefined
+  reconnectDelay?: number | undefined
+  scheme?: 'ws' | 'wss' | undefined
+  url?: string | undefined
 }
 
 type ApiRouteMap = {    [x: `GET ${string}`]: RouteShape | undefined;    [x: `POST ${string}`]: RouteShape | undefined;    [x: `PUT ${string}`]: RouteShape | undefined;    [x: `PATCH ${string}`]: RouteShape | undefined;    [x: `DELETE ${string}`]: RouteShape | undefined;}
@@ -2910,6 +2913,34 @@ class AssetsBuildCommand = {
   write: (msg: string) => void
 }
 
+class AssetsPruneCommand = {
+  new (): AssetsPruneCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    type: 'string';    description: string;    default?: never;} | {    name: string;    type: 'boolean';    description: string;    default: boolean;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
 class CompileCommand = {
   new (): CompileCommand
   static args: ArgDef[]
@@ -3797,7 +3828,7 @@ function DeployConfig = (options?: Partial<DeployConfigShape>) => DeployConfigSh
 
 interface AppAssetsConfig = {
   entrypoint: string | string[]
-  loader?: Record<string, AssetLoaderKind>
+  loader?: Record<string, AssetLoaderKind> | undefined
   minify: boolean
   outDir: string
   prefix: string
@@ -3805,11 +3836,11 @@ interface AppAssetsConfig = {
 
 interface AppConfigShape = {
   allowedOrigins: string[]
-  assets?: AppAssetsConfig
+  assets?: AppAssetsConfig | undefined
   conventions: ConventionsConfig
   cors: AppCorsConfig
   debug: boolean
-  dev?: DevConfigShape
+  dev?: DevConfigShape | undefined
   env: string
   health: boolean | HealthConfigShape
   http3: boolean
@@ -3821,7 +3852,7 @@ interface AppConfigShape = {
   secureHeaders: AppSecureHeadersConfig
   throttle: AppThrottleConfig
   timezone: string
-  tls?: AppTlsConfig
+  tls?: AppTlsConfig | undefined
   url: string
 }
 
@@ -3976,10 +4007,10 @@ interface HealthCheckReport = {
 }
 
 interface HealthConfigShape = {
-  enabled?: boolean
-  path?: string
-  secret?: string
-  showDetails?: boolean
+  enabled?: boolean | undefined
+  path?: string | undefined
+  secret?: string | undefined
+  showDetails?: boolean | undefined
 }
 
 interface HealthReport = {
@@ -3999,7 +4030,7 @@ interface HealthResult = {
 interface ResolvedHealthConfig = {
   enabled: boolean
   path: string
-  secret?: string
+  secret?: string | undefined
   showDetails: boolean
 }
 
@@ -4017,6 +4048,8 @@ function data_get = (target: unknown, key: string, defaultValue?: unknown) => un
 
 function deepMerge = <T extends object>(base: T, override: DeepPartial<T>) => T
 
+function definedOnly = <T extends object>(value: T) => { [K in keyof T]?: Exclude<T[K], undefined>; }
+
 function env = {    (key: string): string | undefined;    (key: string, fallback: string): string;    (key: string, fallback: boolean): boolean;    (key: string, fallback: number): number;}
 
 function pipe = <T, R>(value: T, fn: (val: T) => R) => R
@@ -4041,6 +4074,8 @@ function tap = <T>(value: T, callback: (val: T) => void) => T
 
 function tapAsync = <T>(value: T, callback: (val: T) => Promise<void>) => Promise<T>
 
+type Resolved = { [K in keyof T]-?: Exclude<T[K], undefined>; }
+
 ## ./http  `(./src/http.ts)`
 
 class Http = {
@@ -4199,8 +4234,8 @@ interface CliContext = {
 }
 
 interface FileValidationOptions = {
-  maxSize?: number
-  mimes?: string[]
+  maxSize?: number | undefined
+  mimes?: string[] | undefined
 }
 
 interface NegotiateMap = {
@@ -4352,10 +4387,10 @@ class SqliteLockDriver = {
 function LockConfig = (options?: Partial<LockConfigShape>) => LockConfigShape
 
 interface BlockOptions = {
-  refresh?: boolean
-  refreshEvery?: number
-  retryDelay?: number
-  timeout?: number
+  refresh?: boolean | undefined
+  refreshEvery?: number | undefined
+  retryDelay?: number | undefined
+  timeout?: number | undefined
 }
 
 interface LockConfigShape = {
@@ -4374,8 +4409,8 @@ interface LockDriver = {
 }
 
 interface RefreshOptions = {
-  refresh?: boolean
-  refreshEvery?: number
+  refresh?: boolean | undefined
+  refreshEvery?: number | undefined
 }
 
 type LockedCallback = (lock: ManagedLock, signal: AbortSignal) => Promise<T> | T
@@ -4490,16 +4525,16 @@ interface LogEntry = {
 }
 
 interface LoggerOptions = {
-  format?: 'text' | 'json'
+  format?: 'text' | 'json' | undefined
 }
 
 interface LoggingConfigShape = {
   channels: Record<string, ChannelConfig>
-  console?: ConsoleSinkConfig
+  console?: ConsoleSinkConfig | undefined
   default: string
-  file?: FileSinkConfig
-  requests?: boolean
-  slowQueryMs?: number
+  file?: FileSinkConfig | undefined
+  requests?: boolean | undefined
+  slowQueryMs?: number | undefined
 }
 
 type ChannelConfig = { driver: 'console'; level?: LogLevel; format?: 'json' | 'pretty' } | { driver: 'single'; level?: LogLevel; path: string } | { driver: 'daily'; level?: LogLevel; path: string; days?: number } | { driver: 'stack'; level?: LogLevel; channels: string[] } | { driver: 'null' }
@@ -5743,14 +5778,14 @@ interface CastField = {
 }
 
 interface ColumnOptions = {
-  cast?: 'boolean' | 'date' | 'datetime' | 'array' | 'integer' | 'json' | 'float' | 'enum' | 'immutable_datetime' | 'encrypted' | 'encrypted:json' | `decimal:${number}` | {    get?: (dbValue: unknown) => unknown;    set?: (jsValue: unknown) => unknown;} | CastContract<unknown>
+  cast?: 'boolean' | 'date' | 'datetime' | 'array' | 'integer' | 'json' | 'float' | 'enum' | 'immutable_datetime' | 'encrypted' | 'encrypted:json' | `decimal:${number}` | {    get?: (dbValue: unknown) => unknown;    set?: (jsValue: unknown) => unknown;} | CastContract<unknown> | undefined
   default?: unknown
-  enumValues?: Record<string, string | number>
-  index?: boolean
-  nullable?: boolean
-  primary?: boolean
-  type?: 'string' | 'number' | 'boolean' | 'text' | 'datetime' | 'json'
-  unique?: boolean
+  enumValues?: Record<string, string | number> | undefined
+  index?: boolean | undefined
+  nullable?: boolean | undefined
+  primary?: boolean | undefined
+  type?: 'string' | 'number' | 'boolean' | 'text' | 'datetime' | 'json' | undefined
+  unique?: boolean | undefined
 }
 
 interface Compose = {
@@ -5773,10 +5808,10 @@ interface CursorPaginateResult = {
 
 interface DatabaseConfigShape = {
   driver: 'sqlite' | 'postgres' | 'mysql'
-  pool?: {    max?: number;    idleTimeout?: number;}
-  replicas?: string[]
+  pool?: {    max?: number;    idleTimeout?: number;} | undefined
+  replicas?: string[] | undefined
   sqlite: {    path: string;}
-  synchronize?: boolean | {    enabled: boolean;    disruptive?: boolean;}
+  synchronize?: boolean | {    enabled: boolean;    disruptive?: boolean;} | undefined
   url: string
 }
 
@@ -5787,9 +5822,9 @@ interface HasMany = {
 
 interface HasManyThroughOptions = {
   firstKey: string
-  localKey?: string
+  localKey?: string | undefined
   secondKey: string
-  throughLocalKey?: string
+  throughLocalKey?: string | undefined
 }
 
 interface HasOne = {
@@ -5798,10 +5833,10 @@ interface HasOne = {
 }
 
 interface KeysetOptions = {
-  column?: string
-  cursor?: string | null
-  direction?: 'asc' | 'desc'
-  limit?: number
+  column?: string | undefined
+  cursor?: string | null | undefined
+  direction?: 'asc' | 'desc' | undefined
+  limit?: number | undefined
 }
 
 interface KeysetPaginateResult = {
@@ -5827,13 +5862,13 @@ interface ManyToMany = {
 }
 
 interface ManyToManyOptions = {
-  localKey?: string
+  localKey?: string | undefined
   pivotForeignKey: string
   pivotRelatedKey: string
   pivotTable: string
-  relatedKey?: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  relatedKey?: string | undefined
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MigrationEntry = {
@@ -5868,9 +5903,9 @@ interface ModelObserver = {
 interface MorphedByManyOptions = {
   morphName: string
   parentPivotKey: string
-  pivotTable?: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  pivotTable?: string | undefined
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MorphMany = {
@@ -5879,7 +5914,7 @@ interface MorphMany = {
 }
 
 interface MorphManyOptions = {
-  localKey?: string
+  localKey?: string | undefined
   morphName: string
 }
 
@@ -5889,7 +5924,7 @@ interface MorphOne = {
 }
 
 interface MorphOneOptions = {
-  localKey?: string
+  localKey?: string | undefined
   morphName: string
 }
 
@@ -5900,21 +5935,21 @@ interface MorphTo = {
 
 interface MorphToManyOptions = {
   morphName: string
-  pivotTable?: string
+  pivotTable?: string | undefined
   relatedPivotKey: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MorphToOptions = {
-  morphForeignKey?: string
+  morphForeignKey?: string | undefined
   morphMap: Record<string, () => unknown>
-  morphTypeColumn?: string
+  morphTypeColumn?: string | undefined
 }
 
 interface NPlusOneOptions = {
-  mode?: 'warn' | 'throw'
-  threshold?: number
+  mode?: 'warn' | 'throw' | undefined
+  threshold?: number | undefined
 }
 
 interface PaginateMeta = {
@@ -6004,8 +6039,8 @@ interface TableDecoratorBuilder = {
 }
 
 interface TableOptions = {
-  primaryKey?: string
-  timestamps?: boolean
+  primaryKey?: string | undefined
+  timestamps?: boolean | undefined
 }
 
 interface TransitionContext = {
@@ -6317,7 +6352,7 @@ interface QueueConfigShape = {
   driver: 'sqlite' | 'redis' | 'sync'
   pollInterval: number
   queues: string[]
-  workerBootstrap?: string
+  workerBootstrap?: string | undefined
   workers: number
 }
 
@@ -6392,6 +6427,38 @@ type RouteTable = Readonly<Record<string, string>> | ReadonlyMap<string, string>
 
 type RouteTarget = string
 
+## ./runtime  `(./src/runtime.ts)`
+
+const RUNTIME_MISMATCH_ESCAPE = 'ZT_ALLOW_RUNTIME_MISMATCH'
+
+function bunBinary = () => string
+
+function declaredBunFloor = (cwd: string) => {    range: string;    manifest: string;} | null
+
+function installedBunVersion = (cwd: string) => {    version: string;    manifest: string;} | null
+
+function runtimeBelowFloor = (cwd?: string) => RuntimeFloor | null
+
+function runtimeBelowFloorMessage = (floor: RuntimeFloor) => string
+
+function runtimeMismatch = (cwd?: string) => RuntimeMismatch | null
+
+function runtimeMismatchAllowed = () => boolean
+
+function runtimeMismatchMessage = (mismatch: RuntimeMismatch) => string
+
+interface RuntimeFloor = {
+  manifest: string
+  required: string
+  running: string
+}
+
+interface RuntimeMismatch = {
+  installed: string
+  manifest: string
+  running: string
+}
+
 ## ./scheduler  `(./src/scheduler.ts)`
 
 class CronExpression = {
@@ -6399,10 +6466,12 @@ class CronExpression = {
   static describe: (expression: string) => string
   static isValid: (expression: string) => boolean
   static nextRunAfter: (expression: string, from?: Date) => Date | null
+  static nextRunAfterIn: (expression: string, from: Date, timeZone: string) => Date | null
   static readonly SEARCH_HORIZON_DAYS: number
   dayOfMonth: (v: number | string) => CronExpression
   hour: (v: number | string) => CronExpression
   matches: (date?: Date) => boolean
+  matchesIn: (date: Date, timeZone: string) => boolean
   minute: (v: number | string) => CronExpression
   month: (v: number | string) => CronExpression
   nextRun: (from?: Date) => Date | null
@@ -6510,6 +6579,13 @@ class SchedulerBuilder = {
   yearlyOn: (month?: number, dayOfMonth?: number, time?: string) => ScheduledTask
 }
 
+class SchedulerError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): SchedulerError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
 class SchedulerManager = {
   new (): SchedulerManager
   add: (name: string, cronExpression: string, callback: TaskCallback) => ScheduledTask
@@ -6561,14 +6637,25 @@ class TaskSkipped = {
   readonly reason: 'lock' | 'window' | 'env' | 'when' | 'skip' | 'overlap'
 }
 
+class UnknownTimeZoneError = {
+  new (task: string, timezone: string): UnknownTimeZoneError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
 const Scheduler = SchedulerManager
 
+function isValidTimeZone = (timeZone: string) => boolean
+
 function SchedulerConfig = (options?: Partial<SchedulerConfigShape>) => SchedulerConfigShape
 
+function wallClockIn = (date: Date, timeZone: string) => Date
+
 interface OverlapLockOptions = {
-  crossProcess?: boolean
-  expiresAfterMinutes?: number
-  refresh?: boolean
+  crossProcess?: boolean | undefined
+  expiresAfterMinutes?: number | undefined
+  refresh?: boolean | undefined
 }
 
 interface RunLogConfig = {
@@ -6635,7 +6722,7 @@ function redactGraph = (value: unknown, options: RedactGraphOptions) => unknown
 
 interface RedactGraphOptions = {
   circular: string
-  flatten?: (value: unknown) => string | undefined
+  flatten?: ((value: unknown) => string | undefined) | undefined
   mask: string
   maxDepth: number
   sensitive: (key: string) => boolean
@@ -6774,7 +6861,7 @@ const Session = SessionAccessor
 function SessionConfig = (options?: Partial<SessionConfigShape>) => SessionConfigShape
 
 interface CsrfOptions = {
-  secure?: boolean
+  secure?: boolean | undefined
 }
 
 interface SessionConfigShape = {
@@ -6794,7 +6881,7 @@ interface SessionDriver = {
 }
 
 interface SessionOptions = {
-  driver?: SessionDriver
+  driver?: SessionDriver | undefined
 }
 
 interface SessionPayload = {
@@ -6823,27 +6910,27 @@ function snakeCase = (value: string) => string
 function tableNameFor = (className: string) => string
 
 interface DateOptions = {
-  dateStyle?: 'medium' | 'short' | 'full' | 'long'
-  locale?: string
-  timeStyle?: 'medium' | 'short' | 'full' | 'long'
-  timeZone?: string
+  dateStyle?: 'medium' | 'short' | 'full' | 'long' | undefined
+  locale?: string | undefined
+  timeStyle?: 'medium' | 'short' | 'full' | 'long' | undefined
+  timeZone?: string | undefined
 }
 
 interface FormatOptions = {
-  locale?: string
+  locale?: string | undefined
 }
 
 interface MoneyOptions = {
   currency: string
-  fractionDigits?: number
-  locale?: string
-  minorUnits?: boolean
+  fractionDigits?: number | undefined
+  locale?: string | undefined
+  minorUnits?: boolean | undefined
 }
 
 interface NumberOptions = {
-  locale?: string
-  maximumFractionDigits?: number
-  minimumFractionDigits?: number
+  locale?: string | undefined
+  maximumFractionDigits?: number | undefined
+  minimumFractionDigits?: number | undefined
 }
 
 ## ./storage  `(./src/storage.ts)`
@@ -7010,10 +7097,10 @@ const Storage = StorageManager
 function StorageConfig = (options?: Partial<StorageConfigShape>) => StorageConfigShape
 
 interface DiskServeConfig = {
-  expiresIn?: number
-  headers?: Record<string, string>
+  expiresIn?: number | undefined
+  headers?: Record<string, string> | undefined
   path: string
-  signed?: boolean
+  signed?: boolean | undefined
 }
 
 interface FakeStoredFile = {
@@ -7027,24 +7114,24 @@ interface FakeStoredFile = {
 interface LocalDiskConfig = {
   driver: 'local'
   root: string
-  serve?: DiskServeConfig
-  url?: string
+  serve?: DiskServeConfig | undefined
+  url?: string | undefined
 }
 
 interface PutOptions = {
-  contentType?: string
-  visibility?: 'public' | 'private'
+  contentType?: string | undefined
+  visibility?: 'public' | 'private' | undefined
 }
 
 interface S3DiskConfig = {
   bucket: string
   driver: 's3'
-  endpoint?: string
+  endpoint?: string | undefined
   key: string
   region: string
   secret: string
-  serve?: DiskServeConfig
-  url?: string
+  serve?: DiskServeConfig | undefined
+  url?: string | undefined
 }
 
 interface StorageConfigShape = {
@@ -7069,8 +7156,8 @@ interface StorageDriver = {
 }
 
 interface StorageFilesOptions = {
-  mounts?: Mount[]
-  storage?: StorageManager
+  mounts?: Mount[] | undefined
+  storage?: StorageManager | undefined
 }
 
 type DiskConfig = LocalDiskConfig | S3DiskConfig
@@ -7259,6 +7346,7 @@ class TestResponse = {
   assertHeaderMissing: (name: string) => TestResponse
   assertInertia: (component?: string, props?: Record<string, unknown>) => TestResponse
   assertInertiaProp: (key: string, value?: unknown) => TestResponse
+  assertInertiaRedirect: (url: string, status?: number) => TestResponse
   assertInvalid: (fields?: string | string[] | Record<string, string>) => TestResponse
   assertJson: (expected: Record<string, unknown>) => TestResponse
   assertJsonCount: (count: number, key?: string) => TestResponse
@@ -7333,16 +7421,16 @@ interface InertiaPage = {
 }
 
 interface MigrateDatabaseOptions = {
-  connection?: SQLInstance
-  path?: string
-  table?: string
+  connection?: SQLInstance | undefined
+  path?: string | undefined
+  table?: string | undefined
 }
 
 interface RefreshDatabaseOptions = {
-  connection?: SQLInstance
-  migrate?: string | boolean
-  setup?: (db: SQLInstance) => void | Promise<void>
-  teardown?: (db: SQLInstance) => void | Promise<void>
+  connection?: SQLInstance | undefined
+  migrate?: string | boolean | undefined
+  setup?: ((db: SQLInstance) => void | Promise<void>) | undefined
+  teardown?: ((db: SQLInstance) => void | Promise<void>) | undefined
 }
 
 interface TestFileInput = {
@@ -7702,7 +7790,7 @@ interface FieldRuleDefinition = {
 }
 
 interface UniqueOptions = {
-  ignoreId?: string | number
+  ignoreId?: string | number | undefined
 }
 
 interface ValidatorConfigShape = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zerotal",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -33,6 +33,7 @@
     "./orm": "./src/orm.ts",
     "./queue": "./src/queue.ts",
     "./routes": "./src/routes.ts",
+    "./runtime": "./src/runtime.ts",
     "./scheduler": "./src/scheduler.ts",
     "./security": "./src/security.ts",
     "./session": "./src/session.ts",
@@ -62,17 +63,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/auth": "1.9.0",
-    "@zerotal/cache": "1.9.0",
-    "@zerotal/client": "1.9.0",
-    "@zerotal/core": "1.9.0",
-    "@zerotal/media": "1.9.0",
-    "@zerotal/orm": "1.9.0",
-    "@zerotal/queue": "1.9.0",
-    "@zerotal/scheduler": "1.9.0",
-    "@zerotal/session": "1.9.0",
-    "@zerotal/testing": "1.9.0",
-    "@zerotal/validator": "1.9.0"
+    "@zerotal/auth": "1.10.0",
+    "@zerotal/cache": "1.10.0",
+    "@zerotal/client": "1.10.0",
+    "@zerotal/core": "1.10.0",
+    "@zerotal/media": "1.10.0",
+    "@zerotal/orm": "1.10.0",
+    "@zerotal/queue": "1.10.0",
+    "@zerotal/scheduler": "1.10.0",
+    "@zerotal/session": "1.10.0",
+    "@zerotal/testing": "1.10.0",
+    "@zerotal/validator": "1.10.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/runtime.ts

@@ -0,0 +1 @@
+export * from "@zerotal/core/runtime";