Core Concepts

Modules

Modules are the primary organizational units within the Platform SDK. They encapsulate related functionalities and resources, providing a clear separation of concerns. Each module exposes a well-defined API for interaction.

Key characteristics of modules:

• Encapsulation: Hides internal implementation details.
• Reusability: Can be independently developed, tested, and deployed.
• Dependency Management: Explicitly declare dependencies on other modules.

For example, the Networking module handles all network-related operations, while the Storage module manages data persistence.

// Example of loading a module
import { Networking } from '@platform/sdk/networking';

const networkManager = new Networking();
networkManager.fetch('https://api.example.com/data')
    .then(response => console.log('Data received:', response))
    .catch(error => console.error('Network error:', error));
            

Components

Components are reusable, self-contained units of functionality that can be assembled to build applications. They often represent UI elements, business logic, or data services.

Components interact with each other through well-defined inputs (props) and outputs (events).

Component Lifecycle

Components typically follow a lifecycle with distinct phases:

• Initialization: Component is created and its initial state is set.
• Rendering: Component's UI is generated and displayed.
• Update: Component's state or props change, triggering a re-render.
• Destruction: Component is removed from the UI and its resources are cleaned up.

// Example of a simple component definition
class Button {
    constructor(label, onClick) {
        this.label = label;
        this.onClick = onClick;
    }

    render() {
        const buttonElement = document.createElement('button');
        buttonElement.textContent = this.label;
        buttonElement.addEventListener('click', this.onClick);
        return buttonElement;
    }
}

const myButton = new Button('Click Me', () => alert('Button clicked!'));
document.body.appendChild(myButton.render());
            

Interfaces

Interfaces define contracts that classes must adhere to. They specify the methods, properties, and events that a particular type of object should expose, without providing the implementation details.

Interfaces are crucial for ensuring type safety and promoting loose coupling between different parts of the SDK.

Example Interface

Consider an interface for a data source:

interface DataSource {
    getData(id: string): Promise<any>;
    saveData(data: any): Promise<void>;
    subscribe(callback: (data: any) => void): UnsubscribeFunction;
}

type UnsubscribeFunction = () => void;
            

Any class implementing the DataSource interface must provide implementations for getData, saveData, and subscribe.

Events

Events are a mechanism for components and modules to signal that something has happened. Other parts of the system can listen for these events and react accordingly, enabling asynchronous communication and loose coupling.

The SDK utilizes an event-driven architecture, allowing for flexible and scalable solutions.

Event Types

• User Interaction Events: e.g., click, input, keypress.
• System Events: e.g., dataLoaded, connectionEstablished, errorOccurred.
• Custom Events: Developers can define and dispatch their own custom events.

// Example of event emission and handling
class EventEmitter {
    constructor() {
        this.listeners = {};
    }

    on(event, callback) {
        if (!this.listeners[event]) {
            this.listeners[event] = [];
        }
        this.listeners[event].push(callback);
    }

    emit(event, ...args) {
        if (this.listeners[event]) {
            this.listeners[event].forEach(callback => callback(...args));
        }
    }
}

const emitter = new EventEmitter();

emitter.on('message', (text) => {
    console.log('Received message:', text);
});

emitter.emit('message', 'Hello, SDK!');
            

Context

Context provides a way to pass data through the component tree without having to pass props down manually at every level. It's particularly useful for global data such as themes, user authentication, or configuration settings.

The SDK provides mechanisms for creating and consuming context.

Using Context

A typical pattern involves a Provider component that wraps a part of the component tree and makes the context value available to any descendant component that consumes it.

// Simplified conceptual example (actual implementation may vary)

// 1. Define context
const ThemeContext = createContext({ theme: 'light' });

// 2. Provider component
function AppThemeProvider({ children }) {
    const [theme, setTheme] = useState('light');
    
    const toggleTheme = () => setTheme(prevTheme => (prevTheme === 'light' ? 'dark' : 'light'));

    return (
        <ThemeContext.Provider value={{ theme, toggleTheme }}>
            {children}
        </ThemeContext.Provider>
    );
}

// 3. Consumer component
function ThemedComponent() {
    const { theme, toggleTheme } = useContext(ThemeContext);

    return (
        <div style={{ backgroundColor: theme === 'light' ? '#fff' : '#333', color: theme === 'light' ? '#333' : '#fff' }}>
            <p>Current theme: {theme}</p>
            <button onClick={toggleTheme}>Toggle Theme</button>
        </div>
    );
}

// Usage:
// <AppThemeProvider>
//     <ThemedComponent />
// </AppThemeProvider>