Upgrade from Monster 4 to 5

Monster 5 makes the CustomElement option lifecycle explicit. Code that reads or writes options while those options are still being defined now fails immediately instead of silently using a fallback or losing a write.

The breaking contract

• The option API is unavailable while defaults and customization are evaluated.
• Early access throws the exported OptionsNotInitializedError. Its method and component properties identify the operation and class.
• Monster 5 has no compatibility flag, injected legacy strategy, early-read fallback or queue for early writes.
• Normal fallbacks still work after initialization. Valid values such as false, 0, an empty string and null remain valid.

Choose the phase that owns the data

Replace circular defaults

This Monster 4 pattern asks the option tree for a value while that same tree is being built. It always depended on fallback behavior and throws in Monster 5.

// Before: unsupported in Monster 5
get defaults() {
    return {
        ...super.defaults,
        title: this.getOption("labels.title", "Details"),
    };
}

Declare the state directly and let updater-bound markup read it after assembly.

// After: declarative defaults
get defaults() {
    return {
        ...super.defaults,
        labels: {
            title: "Details",
        },
        templates: {
            main: "<h2 data-monster-replace='path:labels.title'></h2>",
        },
    };
}

Move derived work to the right hook

Use initMethodSymbol only when constructor-time configuration is sufficient. Always keep the parent call.

import {
    CustomElement,
    initMethodSymbol,
} from "@schukai/monster/source/dom/customelement.mjs";

class ReportPanel extends CustomElement {
    [initMethodSymbol]() {
        super[initMethodSymbol]();
        this.initialReportType = this.getOption("report.type", "summary");
        return this;
    }
}

Use assembleMethodSymbol when values may come from late attributes or script configuration, or when the work needs rendered DOM. Call super first.

import {
    CustomElement,
    assembleMethodSymbol,
} from "@schukai/monster/source/dom/customelement.mjs";

class ReportPanel extends CustomElement {
    [assembleMethodSymbol]() {
        super[assembleMethodSymbol]();
        this.configureResource(this.getOption("resourceConfig"));
        return this;
    }
}

document.createElement() and late configuration

document.createElement() completes construction synchronously. The returned upgraded element can use the option API immediately, but attributes the caller adds later could not have influenced initMethodSymbol.

await customElements.whenDefined("report-panel");
const panel = document.createElement("report-panel");

// Safe: construction and option initialization have completed.
panel.setOption("report.type", "detailed");

// Also applied during connection, but it was not visible to initMethodSymbol.
panel.setAttribute("data-monster-option-report-scope", "quarter");
document.body.append(panel);

On first connection, Monster reads option attributes again, merges data-monster-options and selected script configuration, then renders and binds updaters. Reconnection reuses the assembled state; it does not reload those configuration sources.

Migration checklist

1. Search both getters and every helper they call for all three option methods.
2. Replace option-derived defaults with literal, static or class-level declarations.
3. Move constructor-only derived state to initMethodSymbol.
4. Move DOM and connection-time configuration work to assembleMethodSymbol.
5. Call the matching parent hook before relying on Monster state.
6. Test parsed HTML, document.createElement(), first connection and reconnection.
7. Remove compatibility guards that catch OptionsNotInitializedError.

Related documentation