mostlyright/experimental

Classes

ContributorFirewallError

Raised at compose time when a contributor emits a column that violates the labels-only firewall — a non-prefixed column, or a forbidden label/obs_*/cli_* column. Mirrors Python _assert_columns_clean in _contributors.py: a firewall breach is a correctness bug, so it throws immediately and is never downgraded to the NaN/null failure block. That block is reserved for a contributor’s own runtime exception.

Extends

ContractError

Constructors

new ContributorFirewallError()

new ContributorFirewallError(message): ContributorFirewallError

Parameters

message

string

Returns

ContributorFirewallError

Overrides

ContractError.constructor

ContributorRegistrationError

Raised when a contributor spec violates a registration guard (bad prefix, missing or out-of-namespace columns, duplicate name, built-in-prefix claim). A loud, typed error — never a silent no-op.

Extends

ContractError

Constructors

new ContributorRegistrationError()

new ContributorRegistrationError(message): ContributorRegistrationError

Parameters

message

string

Returns

ContributorRegistrationError

Overrides

ContractError.constructor

Interfaces

ContributorSpec

Properties

archiveClass?

readonly optional archiveClass: ArchiveClass

Archive class. Default "refetchable".

builtin?

readonly optional builtin: boolean

Built-ins are exempt from the experimental warning. Default false.

columns?

readonly optional columns: readonly string[]

The prefixed column set this contributor emits. Required for third-party (non-builtin) contributors, and every column must carry prefix — mirrors Python _contributors.py, which requires the set and seeds the all-null column universe from it. That is what makes the failure contract load-bearing: if contribute() throws or covers zero days, the declared columns still materialize as an all-null block instead of silently vanishing. Built-ins may omit it (they derive their columns from the composed output); a third-party registration without columns raises ContributorRegistrationError.

contribute

readonly contribute: ContributeFn

The contribute() implementation.

injectionPoint?

readonly optional injectionPoint: InjectionPoint

Injection point. Default "post_join", where third-party columns are appended.

key

readonly key: string

Unique registry key (the Python key tuple, flattened to a string).

nativeGrain?

readonly optional nativeGrain: "daily" | "observation"

Native grain the contributor computes at. Default "daily".

prefix

readonly prefix: string

The column prefix this contributor emits (e.g. "sat_"). Validated against the firewall at registration; every emitted column must start with it.

Type Aliases

ArchiveClass

ArchiveClass: "ledger" | "refetchable"

Archival durability class of the contributor’s underlying data. Closed enum (mirrors Python: ledger = capture-or-lose; refetchable = re-derivable).

ContributeFn()

ContributeFn: (args) => ReadonlyMap<string, Readonly<Record<string, unknown>>>

The contribute(entity, window, grain) protocol. Returns a map of prefixed_col -> value for the given key. Mirrors the neutralized Python contribute(entity, window, grain) -> {key: {prefixed_col: value}}. In TS we key the per-day contributions by the daily date string.

Parameters

args

entity

string

grain

"daily" | "observation"

window

{ fromDate: string; toDate: string; }

window.fromDate

string

window.toDate

string

Returns

ReadonlyMap<string, Readonly<Record<string, unknown>>>

InjectionPoint

InjectionPoint: "pre_aggregation" | "post_join"

Where a contributor injects its columns. Closed enum (mirrors Python).

Functions

_resetContributorFailureWarning()

_resetContributorFailureWarning(): void

Reset the one-time contributor-failure-warning latch — test use only.

Returns

void

_resetExperimentalWarning()

_resetExperimentalWarning(): void

Reset the one-time experimental-warning latch — test use only.

Returns

void

_resetRegistry()

_resetRegistry(): void

Reset the registry — test use only (mirrors the Python clean_registry fixture).

Returns

void

composePostJoinContributors()

composePostJoinContributors(rows, args): object

Compose post-join third-party contributors onto the daily rows. Runs strictly after the built-in composition, so built-in output stays byte-identical and only additive third-party columns are appended (mirrors _contributors.py’s compose_post_join_contributors).

Failure semantics, matching Python — the three kinds of contributor problem are treated differently:

A contributor whose contribute() throws an ordinary runtime error (a data or runtime failure) yields an all-null prefix block on every row plus an entry pushed to errors, and composition continues — the dataset() call succeeds, and a one-time console.warn (the equivalent of Python’s RuntimeWarning) reports it. A data failure is a null block plus a warning.
A contributor whose contribute() throws an availability or config error — SourceUnavailableError (a missing optional extra) or DataAvailabilityError (fetched, nothing usable) — is re-raised, never downgraded to the null block. Python re-raises SourceUnavailableError; TS splits that case across the two typed errors, so both propagate. A configuration error must fail loudly rather than silently null-fill.
A contributor that emits a firewall-violating column (a non-prefixed column, or a forbidden label/obs_*/cli_* column) throws a typed ContributorFirewallError immediately. That is a correctness bug, never converted to a null failure block: a contributor must not shadow a label, silently or otherwise.

Parameters

rows

readonly Record<string, unknown>[]

args

entity

string

grain

"daily" | "observation"

keyColumn?

string

The key column each row carries to join contributions by.

window

{ fromDate: string; toDate: string; }

window.fromDate

string

window.toDate

string

Returns

object

contributorErrors

contributorErrors: Readonly<Record<string, string>>

errors

errors: readonly string[]

rows

rows: readonly Record<string, unknown>[]

registerContributor()

registerContributor(spec): void

Register a contributor. The first non-builtin registration fires a one-time ExperimentalFeatureWarning. The declared prefix is checked against the labels-only firewall and throws on violation. Registration validation mirrors Python _contributors.py _validate_prefix + _register:

prefix non-empty, ends with _, and not a reserved label prefix/name — including after stripping the trailing _, so label_/date_/station_ reject, because they namespace into the label set;
archiveClass ∈ {refetchable, ledger} and injectionPoint ∈ {pre_aggregation, post_join} are runtime-validated before the duplicate, built-in-prefix, and columns guards, as in Python;
a third-party contributor may not claim a built-in prefix (fcst_/trade_/sat_/cwop_) — it would shadow a built-in’s columns;
a duplicate key (the contributor name) is rejected rather than overwritten. Names are unique; a re-registration is a programming error, not an update.

Parameters

spec

ContributorSpec

Returns

void

registeredContributorPrefixes()

registeredContributorPrefixes(): readonly string[]

The registered contributor prefixes — the union the BYO label collision guard checks.

Returns

readonly string[]

registeredContributors()

registeredContributors(): readonly string[]

The registered contributor keys (registration order not promised).

Returns

readonly string[]

unregisterContributor()

unregisterContributor(key): boolean

Remove a registered contributor by key. Returns true if one was removed.

Parameters

key

string

Returns

boolean