Pular para o conteúdo
Português (BR)

ActorSystemOptionsType

Este conteúdo não está disponível em sua língua ainda.

ActorSystemOptionsType = object

Defined in: src/ActorSystemOptions.ts:41

Plain options-object shape accepted by ActorSystem.create.

Four fields decide the system logger, and the first one set wins whole: logger > otelLogs > logSinks > the sinks actor-ts.logger.sinks.* enables > a ConsoleLogger. Nothing is merged across them, and setting two is not an error — the lower one is simply not built.

readonly optional config?: Config | ConfigObject

Defined in: src/ActorSystemOptions.ts:92

Application config. Accepts:

  • a prebuilt Config (highest precedence layered on top of reference);
  • a plain JS object of overrides (converted via Config.fromObject);
  • omitted — the files Config.load finds (see configFile and its siblings) over the bundled reference defaults are used. Constructor options (logger, logLevel, dispatcher) still win over anything in config — they are explicit code overrides.

readonly optional configFile?: string | false

Defined in: src/ActorSystemOptions.ts:97

Explicit path to application.conf; overrides ACTOR_TS_CONFIG + CWD lookup. false reads no application file.


readonly optional coordinatedStartup?: CoordinatedStartupOptions

Defined in: src/ActorSystemOptions.ts:220

The startup graph (#1473): tasks the system runs in phases as the last step of create, before whenReady() resolves and before the startup readiness check turns true — so a step that has to happen after a plugin is registered and before the node takes traffic needs no call in main.

A slot here rather than a call on the extension, because the graph is sealed when create returns: a task added afterwards could find its phase already over, so CoordinatedStartup.addTask refuses and names this.


readonly optional deadLetters?: DeadLetterQueueOptions

Defined in: src/ActorSystemOptions.ts:180

Dead-letter queue settings — the explicit layer over actor-ts.dead-letters.*.

Needed because system.deadLetterQueue is built by the constructor and is readonly: without a slot here the publicly exported DeadLetterQueueOptions family had no reachable consumer at all. A queue you construct yourself is never installed as the capture sink, so it is a correctly-configured object that receives nothing — which made HOCON the only way to configure the real queue, against the project’s explicit options > HOCON > built-in defaults rule.

Field-by-field, so setting one knob here does not blank the others out of the config file.


readonly optional diagnostics?: DiagnosticsOptions

Defined in: src/ActorSystemOptions.ts:195

Diagnostics settings — the explicit layer over actor-ts.diagnostics.*, which today is dead-letter logging and its throttle (#1000).

Here for the same reason deadLetters is: the settings are consumed by the constructor and handed straight to DeadLetterRef, so without a slot here the published DiagnosticsOptions family would have no reachable consumer and HOCON would be the only way to configure a default-ON log line — against the project’s explicit options > HOCON > built-in defaults rule.

Field-by-field, so setting one knob here does not blank the others out of the config file.


readonly optional dispatcher?: Dispatcher

Defined in: src/ActorSystemOptions.ts:80


readonly optional environmentFile?: string | false

Defined in: src/ActorSystemOptions.ts:115

Explicit path to the .env file whose variables answer substitutions behind the real environment (#1785). Overrides ACTOR_TS_ENV_FILE + CWD lookup; false reads none.


readonly optional logger?: Logger

Defined in: src/ActorSystemOptions.ts:43

The system logger, used as it is. Wins over every other logger field.


readonly optional logLevel?: LogLevel

Defined in: src/ActorSystemOptions.ts:79

Minimum level of the logger the system builds — the sinks, the console default, and the otelLogs logger unless its options set their own. Wins over actor-ts.logger.level; ignored when logger is set.


readonly optional logSinks?: readonly LogSink[]

Defined in: src/ActorSystemOptions.ts:73

Log destinations — the system wraps them in a MultiSinkLogger, attaches them to its scheduler, and flushes them on terminate().

The shorthand for the common case; logger and otelLogs still win when either is given. Setting this, or either of those, replaces the actor-ts.logger.sinks.* block wholesale rather than merging with it: a sink is configured in code or in HOCON, never half in each.


readonly optional messageBoundary?: MessageBoundaryOptions

Defined in: src/ActorSystemOptions.ts:202

What every local tell is held to before delivery, layered over actor-ts.diagnostics.message-boundary.* (#1386): the worker hop’s structured clone, the cluster wire’s serializer round trip. Off in production; TestKit turns the clone check to fail.


readonly optional otelLogs?: OtelLogsAdapterOptions

Defined in: src/ActorSystemOptions.ts:63

The system logger built by the framework from the OpenTelemetry Logs API: the system passes these options to otelLogger at construction, with actor-ts.tracing.logger-name and logger-version layered under them field by field, and uses the result as system.log. Its level is the options’ own level, else logLevel, else actor-ts.logger.level.

A slot rather than something the tracing extension installs later, because the logger cannot change once the constructor has run: system.log is read-only, and the event stream, the dead-letter reporting and every actor’s this.log capture it as they are built. withLogger(otelLogger(...)) stays the pure path — the same factory with your options alone, no config file.

logger wins over this; this wins over logSinks and the HOCON sinks. A mesh worker never receives it — a namespace object does not survive the structured clone into a worker — so a worker’s logger follows actor-ts.logger.sinks.* as before.


readonly optional parallelism?: ParallelismOptions

Defined in: src/ActorSystemOptions.ts:209

Actors on worker threads, layered over actor-ts.parallelism.* (#1563). The one thing only code can say here is the actor module — withModule — because a config file must not decide which code a worker runs; the worker count and everything else fall through to HOCON.


readonly optional persistence?: object

Defined in: src/ActorSystemOptions.ts:158

Persistence wired where the system is created, instead of by reaching into the extension after create (#1473).

plugins register backends. Each is handed the system’s PersistenceExtension and typically makes one register*Plugins call — (persistence) => registerPostgresPlugins(persistence) — while the configuration’s actor-ts.persistence.<axis>.plugin still decides which registered plug-in an axis uses. They run inside create, synchronously and in the order given, so a selected plug-in resolves on the line after create, before the startup graph starts. One that throws makes create throw; a promise one returns is awaited in the persistence-start phase, where a rejection fails the startup.

journal, snapshotStore and durableStateStore are instances, each the explicit layer over the plug-in its axis selects: applied after the plug-ins have run, and not replaced by a registration that comes later — as if set with setJournal / setSnapshotStore / setDurableStateStore on system.extension(PersistenceExtensionId). Every field is independent; an axis with no instance keeps the plug-in it selects.

behavior is the system-wide persistence behaviour, layered over actor-ts.persistence field by field: a field set here wins over the file, and one left unset still falls through to it. Its autoStart, on unless set false here, opens the selected stores as part of the startup: a selection nothing registered, or a store that cannot open, fails whenReady() and takes the system down. Off, the stores open on first use — the one way a plug-in registered after create still counts.

readonly optional behavior?: PersistenceBehaviorOptions

readonly optional durableStateStore?: DurableStateStore

readonly optional journal?: Journal

readonly optional plugins?: ReadonlyArray<PersistencePlugin>

readonly optional snapshotStore?: SnapshotStore


readonly optional profile?: string

Defined in: src/ActorSystemOptions.ts:128

The config profile — the profiles.<profile> block of each file the loader reads, the project reference.conf, application.conf and the secrets file, laid over each file’s root (#1546, #1785). Overrides ACTOR_TS_PROFILE; a name no file defines is refused at startup.

Reaches system.config only. The few components that read the configuration without a system — ClusterClient, InMemoryLease, KubernetesLease, WorkerCluster, and the read…OptionsFromConfig helpers called without a Config — load it themselves and see ACTOR_TS_PROFILE alone.


readonly optional referenceConfigFile?: string | false

Defined in: src/ActorSystemOptions.ts:103

Explicit path to the project’s own reference.conf — its defaults, over the bundled ones and under application.conf (#1785). Overrides ACTOR_TS_REFERENCE_CONFIG + CWD lookup; false reads none.


readonly optional scheduler?: Scheduler

Defined in: src/ActorSystemOptions.ts:82

Inject a custom scheduler — typically a ManualScheduler in tests.


readonly optional secretsFile?: string | false

Defined in: src/ActorSystemOptions.ts:109

Explicit path to the secrets file (#1769). Overrides ACTOR_TS_SECRETS_CONF + CWD lookup; its keys are attributed to secrets and withheld by the config dump and DevTools. false reads none.