//\ Tarp.observable - a lightweight observer pattern implementation

Tarp.observable is a simple implementation of the observer pattern licensed as open source under the LGPL v3. It follows the Tarp principle, which means to be as lightweight as possible while providing all essential features.

Features

• Reactive state management: Easily track changes to data and react to them automatically.
• Derived states: Automatically calculate values based on dependencies.
• Memory efficient: Designed with minimal memory and processing overhead in mind.
• Web component integration: Built-in support for lifecycle-aware DOM observers.
• Immutable-friendly: Built-in cloning for safe object and array updates.

Installation

You can install Tarp.observable using npm:

npm install @tarp/observable

Reference

Observable

The base class for storing data. When the value property is changed, all attached listener functions will be called.

• new Observable(initialValue): Initializes the observable with an optional starting value.
  • initialValue: The starting value of the observable.
• .value: Get or set the current value.
  • Returns: The current value.
  • Note: Setting an object or array creates a shallow clone to ensure data integrity.
• .addListener(listener): Registers a callback for when the value changes.
  • listener: The callback function to execute when a change occurs.
  • Returns: The result of addEventListener.
• .removeListener(listener): Removes a previously registered callback.
  • listener: The function to be removed.
  • Returns: The result of removeEventListener.

DerivedObservable

A specialized observable that calculates its value based on other observables. It updates itself when any of the base observables change.

• new DerivedObservable(...observables, composer): Initializes the derived observable with dependencies and a calculation function.
  • observables: The base observables that the derived value depends on.
  • composer: The callback function that returns the new derived value after a change.
• .addObservables(...observables): Adds new base observables that this derived value depends on.
  • observables: The Observable instances to start watching.
• .removeObservables(...observables): Removes old base observables that the derived value no longer depends on.
  • observables: The Observable instances to stop watching.

ObservingHTMLElement

A base class for web components that automates the management of observers based on the element's lifecycle. Use this class instead of HTMLElement as the parent class for web components that shall react to Observable changes.

• .addObserver(...observables, listener, [immediateExec = true]): Registers one or more observables to be observed by this element.
  • observables: One or more Observable instances to watch.
  • listener: The callback function to execute when a change occurs.
  • immediateExec: Whether the listener shall run immediately upon registration (default: true).
  • Returns: A unique observer ID used for manual removal.
• .removeObserver(id): Removes a previously registered observer.
  • id: The unique ID returned by addObserver.

Example

import Observable from "@tarp/observable";
import DerivedObservable from "@tarp/observable/DerivedObservable";
import ObservingHTMLElement from "@tarp/observable/ObservingHTMLElement";

// 1. Create some observable data containers.

const firstName = new Observable("John");
const lastName = new Observable("Doe");

const fullName = new DerivedObservable(firstName, lastName, () => `${firstName.value} ${lastName.value}`);

// 2. Create a web component that reacts to the data.

class UserProfile extends ObservingHTMLElement {
	constructor() {
		super();
		this.attachShadow({ mode: "open" });
		this.shadowRoot.innerHTML = `<p id="name-display"></p>`;

		// Observation automatically starts when element is connected and stops when disconnected.
		this.addObserver(fullName, () => {
			this.shadowRoot.getElementById("name-display").textContent = fullName.value;
		});
	}
}

customElements.define("user-profile", UserProfile);

// 3. Add the web component to your HTML.

// <user-profile></user-profile>

// 4. Modify an observed value and the web component updates automatically!

setTimeout(1000, () => (firstName.value = "Jane"));

Copyright 2024-2026 Torben Haase <https://letorbi.com>