Interfaces

@system-inc/base-foundation · 515c140 · 16 symbols

BaseModuleCreateBaseModuleOptionsBaseModuleSettingsBaseSettingsBaseWorkerDelegateBaseWorkerPlatformDelegateEnvironmentVariablesEventBusConfigurationLoggingConfigurationRouterConfigurationScheduledConfigurationVersionInfoWorkerBindingReferenceWorkerBindingsWorkerConfigValidationContextWorkerQueueConfiguration

BaseModuleCreate

interface

Specification for creating a Base module.

Members

  • key: BaseModuleKey<ModuleSpecificSettings>

    The module's identity key — the same BaseModuleKey consumers use with uses, configuration.getModuleSettings(key), and declared module membership (@Injectable(key)). Passing the key (not a string) makes it the single source of the module's name AND binds the key's phantom settings type to this module's settings, so a key declared as BaseModuleKey.create<StripeModuleSettings>('Stripe') only accepts settings of that shape.

  • settings: ModuleSettings<ModuleSpecificSettings>

    Settings for this module.

  • uses?: readonly ModuleUse[]

    A list of modules that this module uses. Entries may be feature-scoped ({ module, when }).

  • onCreate(settings: ModuleSettings<ModuleSpecificSettings>): void

    Called when the module is created.

  • onInitialize(settings: ModuleSettings<ModuleSpecificSettings>, configuration: BaseConfiguration): Promise<void>

    Called when the module is initialized.

View source ↗

BaseModuleOptions

interface

Registration modifiers a worker applies when adding a module — the single, uniform way to change how a module participates in this worker. Apply them with BaseModule.with (or pass to BaseModule.create); they are applied once, when the app manifest is flattened.

  • Feature toggles (orm/eventBus/graphql/queue/router/rpc/ scheduled/middleware/webSocket): set to false to strip that feature's wiring for this registration — e.g. middleware: false keeps a module's services but drops its global/handler middleware (which otherwise runs on every request, even where you only wanted the services). A { module, when } entry in uses whose when names a stripped feature is dropped too. Toggles control wiring, not the bundle: the stripped code is still imported and shipped (only its registration is skipped). To drop the code itself, import a smaller module/layer instead.
  • externalSchema: register the module's entities for queries but do NOT own/migrate their schema here — another worker (or an inheritSchema source) owns it. The entities still build into the runtime query schema; they're excluded from migration generation and the schema:sync table scope.
  • database: route this module to a named database in this worker. It overrides the module's own settings.orm.databaseName, so a module reused across workers can live in different databases per deployment (e.g. the default database in the main worker, but an external connected database inside a Durable Object whose default database is local SQLite). It governs both where the module's entities are registered AND where the module's services' token-less @InjectRepository/@InjectDatabase resolve to — see module-aware resolution in BaseModuleSettings.orm / the orm doc. Typically paired with externalSchema: true.

See BaseModuleSettings for the features these map to.

Members

  • database?: string

  • eventBus?: boolean

  • externalSchema?: boolean

  • graphql?: boolean

  • middleware?: boolean

  • orm?: boolean

  • queue?: boolean

  • router?: boolean

  • rpc?: boolean

  • scheduled?: boolean

  • webSocket?: boolean

View source ↗

BaseModuleSettings

interface

An interface for defining all modules settings in Base.

Modules are self-contained pieces of functionality that can be used in multiple places. You can combine the functionality of multiple modules by using them together in your Workers.

Members

  • accessControl?: AccessControlSettings

    Access-control settings for this module. A module that implements the worker's identity system contributes its import('../access-control/SessionContextProvider').SessionContextProvider here; exactly one provider may be registered across the worker and all its modules.

  • cli?: { configValidators?: WorkerConfigValidator[] }

    CLI-time extension points for the module.

  • graphql?: { directives?: GraphQLDirective[] }

    GraphQL settings for this module. Resolvers are contributed through the unified services array (sorted in by their @GqlResolver decorator); this slot carries what can't be a class list.

  • middleware?: { global?: BaseMiddlewareRegistration[]; handler?: HandlerMiddlewareRegistration[] }

    Middleware settings for this module.

  • orm?: { databaseName?: string; entities?: OrmEntityClass[]; externalEntities?: OrmEntityClass[] }

    Orm settings for this module.

  • services?: (Constructor<object>)[]

    The classes this module provides to the system — the single class slot. Each class's decorators declare what it is: dispatch decorators (@GqlResolver, @HttpService, @RpcService, @WorkerQueueProcessor, @ScheduledExecutable, @EventBusListener) sort it into the matching dispatch surface(s) at boot, honoring this registration's feature toggles; @Provider hosts and injectable-family classes are loaded so their registrations run. A class with no recognized base decorator is a boot error — it can't do anything, so listing it is a mistake (usually a forgotten decorator). Configuration-carrying settings (directives, webSocket delegates, middleware) stay in their subsystem slots; entities go in orm.entities.

  • webSocket?: { delegates?: WebSocketDelegateSettings[]; mappings?: (WebSocketContextMapping<Json>)[] }

View source ↗

BaseSettings

interface

The BaseSettings interface provides configuration for your Base Worker. Each of these fields can be optionally set by implementing this interface.

Members

  • accessControl?: AccessControlSettings

    The access-control settings for the Base Worker — registers the worker's SessionContextProvider (apps whose identity system lives in a module register it through that module's settings instead).

  • cli?: { configValidators?: WorkerConfigValidator[] }

    CLI-time extension points for the worker.

  • containers?: CfDurableObjectSettings[]

    The settings for Cloudflare Containers.

  • delegate?: Constructor<BaseWorkerDelegate>

    A delegate for receiving events from the Base Worker.

  • deployEnvironment?: string | string[]

    The environment or list of environments that this worker should be deployed to.

  • durableObjects?: CfDurableObjectSettings[]

    The settings for Cloudflare Durable Objects.

  • graphql?: GqlSettings

    The GraphQL settings for the Base Worker (provider type, route, directives, graphiql/introspection). Resolver classes go in services.

  • keyValueStorage?: KeyValueStorageSettings

    The settings for the key value storage this Base Worker can access.

  • logging?: LoggingSettings

    Logging settings — the default and per-category log thresholds and the request-log switch. The LOG_LEVEL environment variable overrides the thresholds at deploy time.

  • middleware?: { global?: BaseMiddlewareRegistration[]; handler?: HandlerMiddlewareRegistration[] }

    Middleware settings for this module.

  • modules?: (BaseModule<any>)[]

    The list of modules to load for the Base Worker.

  • moduleTest?: boolean | string[]

    Opt-in for running module integration tests with this worker.

    • true: run integration tests for ALL modules this worker registers
    • string[]: run integration tests only for the listed module names
    • undefined (default): no module integration tests

  • name: string

    The name of the Base Worker.

  • objectStore?: ObjectStoreSettings

    The settings for object storage (R2 / S3-compatible buckets) this Base Worker can access. Buckets declared here can be injected via @InjectObjectStore(...) without requiring the FileStorage module.

  • orm?: NamedConfiguration<OrmSettings<"drizzle">>

    The settings for the ORM this Base Worker can access.

  • queue?: WorkerQueueSettings

    The queue settings for the Base Worker.

  • router?: RouterSettings

    The router settings for the Base Worker (CORS, rewrites). Route handler classes go in services.

  • rpc?: RpcSettings

    The RPC settings for the Base Worker.

  • scheduled?: ScheduledSettings

    The cron settings for the Base Worker.

  • server?: NamedConfiguration<BaseServerSettings>

    Settings for the local development server.

  • services?: (Constructor<object>)[]

    The classes this worker contributes — the single class slot. Each class's decorators declare what it is: dispatch decorators (@GqlResolver, @HttpService, @RpcService, @WorkerQueueProcessor, @ScheduledExecutable, @EventBusListener) sort it into the matching dispatch surface(s) at boot; @Provider hosts and injectable-family classes are loaded so their registrations run. A class with no recognized base decorator is a boot error. Configuration-carrying settings (cors, rpc visibility, webSocket delegates, middleware, directives) stay in their subsystem slots; entities go in orm.

  • title: string

    The title of the project.

  • version: string

    The version of the Base Worker.

  • webSocket?: WebSocketSettings

    The WebSocket settings for the Base Worker.

View source ↗

BaseWorkerDelegate

interface

Delegate in charge of configuring the Base application and optionally responding to lifecycle events.

Members

  • onInitialize(base: Base): Promise<void>

    Optional hook to run after Base has been initialized. This is where you can add routes, middleware, etc. that are specific to your application, but also not configurable in the BaseSettings.

  • onStart(): Promise<void>

    Called when the worker starts listening for requests. Not called on all platforms.

  • onStop(): Promise<number | void>

    Called when the worker stops listening for requests. Not called on all platforms.

View source ↗

BaseWorkerPlatformDelegate

interface

Delegate for platform-specific worker functionality.

Members

  • getPlatformRequestProperties(request: Request): PlatformRequestProperties | undefined

    Gets properties that have been added to the request that are specific to the platform. For example, Cloudflare adds additional headers to the request that can be used to determine the country of the request.

  • getRequestIpAddress(request: Request): string | undefined

    Gets the IP address from the request.

  • initializePlatform(configuration: BaseConfiguration): void | Promise<void>

    Perform any platform-specific initialization.

View source ↗

EnvironmentVariables

interface

A default set of environment variables for Base.

You can extend this interface to add your own variables specific to your Worker.

These variables will be available to your worker at runtime, and should match the variables you have set in your env.toml file.

extends Dictionary<unknown>

Members

  • BUILD_TIMESTAMP?: string

    The build timestamp of the build.

  • CF_VERSION_METADATA?: any

    Cloudflare Worker version metadata.

  • COMMIT_SHA?: string

    The commit SHA of the build.

  • DATABASES?: string | DatabaseEnvironmentVariables[]

    A list of databases to connect to. Each database should have a name and a URL. The URL should be formatted as a MySQL connection string.

  • DEPLOYED_BY?: string

    The user who deployed the build.

  • ENCRYPTION_KEYS?: string | ExportedEncryptionKey[]

    The encryption keys to use for the server.

  • ENVIRONMENT?: string

    The type of environment you are running in. This should map to one of the possible types in EnivronmentType in base/source/core/Environment.ts

  • EXECUTION_MODE?: ExecutionModeType

    The execution mode of the worker.

  • PLATFORM?: PlatformType

    The type of platform the worker is running on.

  • PORT?: string

    The port the worker should run on.

  • RUN_CONFIG?: string

    The configuration name to use when running the worker.

View source ↗

EventBusConfiguration

interface

Runtime event-bus configuration: the @EventBusListener classes the manifest aggregated.

Members

View source ↗

LoggingConfiguration

interface

Runtime logging configuration: the settings-level defaults (level + per-category overrides), the LOG_LEVEL environment directive (which wins where both are set — the engine applies it last at boot), and the request-log switch with its default applied.

extends LoggingSettings

Members

  • categories?: Record<string, LogLevel>

    Per-category thresholds overriding level, keyed by the category name passed to Logger.create (e.g. { rpc: LogLevel.Debug }). The framework's own categories include base, http, rpc, gql, orm, queue, scheduled, ws, event, kv, durable, common.

  • directive?: string

  • level?: LogLevel

    The default log threshold. Defaults to LogLevel.Info.

  • requestLog: boolean

    Whether to emit the per-request log line (GET /notes 200 OK (12ms)). Defaults to true. This is a request log, not an application log — it is the single most expensive log line on the hot path, so it has its own switch: turn it off for maximum throughput while keeping info elsewhere.

View source ↗

RouterConfiguration

interface

Router settings for Base applications.

extends RouterSettings

Members

  • cors?: RouterCorsSettings

    Cors settings for the router.

  • disableAccessLog?: boolean | string[]

    A map of routes that should not be logged or true to disable for all routes.

  • rewrite?: Record<string, string>

    A map of paths to rewrite to other paths.

  • services: (Constructor<object>)[]

View source ↗

ScheduledConfiguration

interface

Scheduled executor settings. These are settings for Executables that can be run as as a result of a schedule() call (Cloudflare Cron Job) or a DurableObject alarm() call.

extends ScheduledSettings

Members

  • concurrency?: number

    The number of Executables that can be run concurrently. Default is 1 (no concurrency).

  • executables: (Constructor<ScheduledExecutableInterface>)[]

View source ↗

VersionInfo

interface

Build and deployment identity for a worker: its name and version plus the commit, build timestamp, and deployment metadata stamped by the build.

Members

  • builtAt?: string

  • commit?: string

  • deployedAt?: string

  • environment: string

  • id?: string

  • name: string

  • version: string

View source ↗

WorkerBindingReference

interface

A reference to a platform binding (R2 bucket, queue producer, KV namespace, service binding, etc.) by its binding name.

Members

  • binding: string

View source ↗

WorkerBindings

interface

Platform-agnostic view of the bindings declared for the worker in its deployment configuration (e.g. Cloudflare's wrangler.toml).

CLI tooling adapts the raw platform configuration into this shape before handing it to module-contributed validators.

Members

View source ↗

WorkerConfigValidationContext

interface

Context passed to a WorkerConfigValidator.

Contains everything a module needs to assert that its deployment configuration matches its runtime requirements.

Members

View source ↗

WorkerQueueConfiguration

interface

Settings related to queues for the Base Worker.

extends WorkerQueueSettings

Members

  • bindings?: string[]

    Queue bindings that the Base Worker will have access to. These are the queues that the Base Worker will produce messages to.

  • processors: (Constructor<WorkerQueueProcessorInterface<unknown>>)[]

View source ↗