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 (_contributors.py:375): a firewall breach is a CORRECTNESS bug, so it fails LOUD and immediately — it is NEVER downgraded to the NaN/null failure block (that path is reserved for a contributor’s runtime exception only). “firewall = correctness bug = loud; data failure = null + warning.”

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/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:307 (require) + :478 (seed the all-null universe from the declared set). It 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 is a loud ContributorRegistrationError.

contribute

readonly contribute: ContributeFn

The contribute() implementation.

injectionPoint?

readonly optional injectionPoint: InjectionPoint

Injection point. Default "post_join" (the additive third-party seam).

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 append (mirrors _contributors.py’s compose_post_join_contributors).

Failure semantics (Python parity — _contributors.py:383 vs :561): the two kinds of contributor problem are treated OPPOSITELY:

A contributor whose contribute() THROWS an ORDINARY runtime error (a data/runtime failure) yields an all-null prefix block on every row + an entry pushed to errors, and composition CONTINUES — the dataset() call SUCCEEDS (a one-time RuntimeWarning-equivalent console.warn surfaces it). This is the FIX-B semantics: “data failure = null + warning.”
A contributor whose contribute() throws an AVAILABILITY/CONFIG error — SourceUnavailableError (a missing optional extra) or DataAvailabilityError (fetched-but-nothing-usable) — is RE-RAISED LOUDLY, never downgraded to the null block (mirrors Python re-raising SourceUnavailableError, _contributors.py:558; the TS availability axis is split across the two typed errors, so both propagate). A configuration error must fail loud, not 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 — it is a CORRECTNESS bug, so it fails LOUD and is NEVER converted to a null failure block. “firewall = correctness bug = loud.” A contributor must never be allowed to shadow a label, even silently.

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. PUBLIC-experimental: the first NON-builtin registration fires a one-time ExperimentalFeatureWarning. The declared prefix is checked against the labels-only firewall (loud throw on violation). Registration validation is Python-parity (mirrors _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 — they namespace INTO the label set);
archiveClass ∈ {refetchable, ledger} and injectionPoint ∈ {pre_aggregation, post_join} are runtime-validated BEFORE the duplicate / built-in-prefix / columns guards (Python _contributors.py:283/:288);
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 (contributor NAME) is REJECTED LOUDLY — there is no silent last-wins overwrite (Python _contributors.py:293). 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 BYO/label collision-guard union.

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