5.0.0-beta.2 · Published beta · 13f4954c. Published on npm. Match your installed version.

Compact framework reference#

Generated from the reviewed public contract inventory by npm run check:api-contracts -- --write. Read this with the documentation shipped by the installed package. Source-only additions may be absent from the published beta. The linked guides own complete examples and argument details.

Choose an owner#

Use plain functions or classes when you do not need Marionette lifecycle, events, or ownership. MnObject is an optional evented, destroyable convenience; Application adds an active asynchronous lifecycle. Application is never a Region-renderable object.

Lifecycle and cancellation#

A synchronous callback/adapter exception escapes; no successful result or rollback is promised. Synchronous; callback or adapter exceptions abort the operation without rollback or attempt-all cleanup. Accepted idempotence guards remain; Application asynchronous cancellation is a distinct contract. Synchronous failures.

Operations resolve true at the requested target, false when superseded, and compatible calls share in-flight promises. Current readiness failure rejects the operation promise. Readiness is awaited; superseded signals abort before replacement readiness; adopted stop retains its original context/options without abort. Destruction blocks owner and descendant start/restart; successful destruction destroys owned children. Readiness rejection preserves the documented retry and partial-child boundaries. Application Lifecycle.

Construction and addChildApp/showView return their public instance; removeChildApp returns a Promise of the removed child or undefined; queries return the declared state or optional owner member. Construction, registration, root-view display and queries are synchronous; removeChildApp awaits child destruction before releasing ownership. Destroy tears down owned children and a constructed root Region; it empties but preserves a supplied borrowed Region. Application Lifecycle.

Application readiness cancellation prevents stale framework completion. Application code must also respect the readiness signal before committing its own asynchronous side effects. Completion hooks are synchronous notifications. Use the routing recipe for cooperative cancellation and late-result checks.

Rendering, lookup, and child identity#

render replaces template contents and refreshes UI bindings; renderAttributes explicitly refreshes root attributes. Named Region lookup does not render; getChildView renders an unrendered parent before reading its child. render may repeat while live; rendering after destruction is a no-op. Method results and side effects.

hasRegion/getRegion/getRegions inspect registrations without rendering. getChildView/showChildView/detachChildView and emptyRegions render an unrendered parent first; removal destroys the Region. Region registration reads are side-effect free; child operations skip parent rendering once it is rendered and retain their own show/detach effects. Method results and side effects.

Structural updates add/remove affected children and reorder survivor elements; reset destructively replaces the list. Filters affect presentation. Explicit live render destroys all existing children and reconstructs collection-derived children; structural source updates reconcile survivors without an explicit render. Comparator ties preserve documented order. Managing Children.

Manual child order is preserved during managed replacement; swap moves existing child elements and keeps identity. Swapping a child with itself leaves it in place; ownership conflicts are rejected before adoption. Self-Managed children.

Applies current root attributes without rendering templates, emitting render lifecycle, rebinding composition or changing child identity. Operates on the current configuration; repeated reads are side-effect free. Refreshing Root Attributes.

State sources and domain data#

StateApi governs an owner’s state-source observation and disposal. DataApi governs model reads, serialization, ordered collection snapshots, and structural observation. Configure each capability explicitly before constructing its consumers. getState() returns the exact source; call that source’s own mutation API.

Plain objects and array snapshots remain exact borrowed sources; array order is read on explicit render. Destroying a consumer does not dispose borrowed models or arrays. Consumer destruction releases its Views without mutating the source. Adapter contract.

Native Model identity survives key/id changes and reorder; Collection structural mutations notify all live consumers. Supplied data/state sources are borrowed; factory-created state is disposed through StateApi. Removed consumers receive no later render notification; owned state subscriptions are released before disposal. Optional @mnjs/data sources.

Backbone models retain reference identity; Backbone event names and callback arguments remain native. Backbone sources remain borrowed for data consumers; StateApi disposal releases subscriptions without calling Model.destroy. Survivors continue rendering after another consumer is destroyed; borrowed source remains usable. Backbone.

Actor reference is model identity; selection returns ordered distinct stable actor references. A respawned actor with the same id has new identity. Borrowed actors stay active after consumer destruction; only factory-owned state actors stop. Owned actor subscriptions release before actor.stop; data consumers do not stop borrowed actors. XState actors.

Custom provider state/data retains opaque source identity and provider-owned event vocabulary. Multiple owners may borrow a state source; factory state alone is owned. Successful cleanup removes externally tracked subscriptions and precedes owned-source disposal; synchronous failures abort without rollback or attempt-all cleanup. Adapter contract.

Events, communication, and cleanup#

Returns the View. Does not transfer ownership; the owner keeps its existing composition. EventDelegator Adapter.

on/off/once/listenTo/listenToOnce/stopListening/trigger return their receiver; triggerMethod has its own result contract. listenTo subscriptions belong to the listener; off removes source registrations. Events API.

Returns the matching onEventName method result; undefined when absent. No ownership transfer. triggerMethod.

channel returns a named channel; direct Channel construction is independent; messaging forwards Events/Requests results. Each Radio registry owns its channel references; owner bindings are scoped by context. Channel Lifecycle.

request returns the handler result, undefined when no applicable reply exists, or mapped results for request maps. Replies use configured context; stopReplying supports selective removal. Requests and Replies.

Own external timers, DOM listeners, and widgets in the lifecycle that actually contains their use. Release render-scoped work before replacement and owner-scoped work on destruction. See resource lifetimes, Behavior composition, and safe rendering. No resource registry or extension-hook API is implied.

Runtime imports and optional integrations#

Runtime configuration and Radio channels are isolated; class setters affect that class and descendants. Configure before constructing or registering consumers; new event registrations use current adapters and existing registrations retain their cleanup. Configuration method contract.

Type-only exports live in the same package declarations. Core, utils, Radio, data, and adapters release together; keep their versions aligned. ESM is the canonical application path. See installation, TypeScript, and the migration procedure.

Development tooling is separate: marionette/eslint. The consumer lint guide states availability and supported analysis. No validator, hierarchy inspector, or test-helper package is currently promised.

Diagnostics and verification#

Match a framework invariant by its stable diagnostic code, not message prose. The diagnostic catalog defines the active codes and supported remedies.

Use public return values, DOM state, child identity, events, and externally counted subscriptions to prove behavior. Test focus and editable state in a real browser; test cancellation with held readiness and late results. A generated contract record proves consistency, not behavior or agent effectiveness.

Canonical examples and counterexamples: class choice, integration choice, Region composition, state ownership, forms, and routing. The consumer guide explains the workflow; the API index locates detailed references.