my-framework-almaz: A Learning Framework

Common errors

• TypeError: Cannot read properties of undefined (reading 'mountDOM')

  cause The `mountDOM` function was either not imported or the package was incorrectly installed/referenced, leading to `mountDOM` being `undefined`.
  fix Ensure `import { mountDOM } from 'my-framework-almaz';` is present at the top of your file and the `my-framework-almaz` package is correctly installed in your `node_modules`.

• ReferenceError: h is not defined

  cause The `h` function, used for creating virtual DOM nodes, was used without being imported.
  fix Add `import { h } from 'my-framework-almaz';` to the top of your JavaScript/TypeScript file where `h` is utilized.

• DOM element not found (when mounting app)

  cause The target DOM element specified for `mountDOM` (e.g., `document.getElementById('app-root')`) does not exist in the HTML document at the time `mountDOM` is called.
  fix Ensure your HTML includes the target element (e.g., `<div id="app-root"></div>`) and that `mountDOM` is called only after the DOM is fully loaded, typically within a `DOMContentLoaded` listener.

Warnings

• gotcha This framework is explicitly NOT intended for production use. It is a pedagogical tool for learning frontend framework internals and should not be deployed in live applications due to potential performance, security, and stability limitations.
  Fix: Always use a battle-tested, production-ready framework (e.g., React, Vue, Angular) for real-world applications. Consult `my-framework-almaz` only for educational purposes.
• breaking Version 1.0 of the framework (corresponding to Chapter 6 of the book) implements state changes by fully destroying and recreating the DOM on every update. Later versions introduce a 'reconciliation algorithm' to efficiently update only changed parts of the DOM, which implies significant internal architectural changes and potentially different patterns for component lifecycle and updates.
  Fix: When migrating between major versions, especially from v1.0, review the updated chapter and examples in the book for changes to the rendering pipeline, component structure, and state update mechanisms. Direct upgrades without code changes are unlikely to work.
• gotcha As an educational framework, `my-framework-almaz` may not prioritize security or performance optimizations typically found in production-grade libraries. Its code might be simplified to illustrate concepts rather than achieve maximum efficiency or robustness.
  Fix: Do not assume any inherent security features or performance guarantees. When adapting concepts for production, always consult best practices for your chosen production framework and perform thorough security audits and performance testing.

Install

• npm install my-framework-almaz npm
• yarn add my-framework-almaz yarn
• pnpm add my-framework-almaz pnpm

Imports

• createApp
  wrong:

  const createApp = require('my-framework-almaz').createApp

  correct:

  import { createApp } from 'my-framework-almaz'

  Primarily designed for modern ES Modules environments.
• h
  wrong:

  import h from 'my-framework-almaz'

  correct:

  import { h } from 'my-framework-almaz'

  The `h` function for creating Virtual DOM nodes is a named export, not a default.
• mountDOM
  wrong:

  const { mountDOM } = require('my-framework-almaz')

  correct:

  import { mountDOM } from 'my-framework-almaz'

  Used to render the Virtual DOM into the actual browser DOM.
• Dispatcher

  import { Dispatcher } from 'my-framework-almaz'

  The Dispatcher class is used for simple command-based state management, especially in earlier versions.

Quickstart

This example demonstrates how to create a simple interactive application using `createApp`, `h` for Virtual DOM creation, `mountDOM` for rendering, and the `Dispatcher` for state management. It illustrates an initial render and subsequent full re-renders (characteristic of v1.0) when state changes via dispatched commands.

import { createApp, h, mountDOM, Dispatcher } from 'my-framework-almaz';

interface State {
  message: string;
  count: number;
}

const initialState: State = {
  message: 'Hello, my-framework-almaz!',
  count: 0,
};

let appState = { ...initialState };
const dispatcher = new Dispatcher();

const UPDATE_MESSAGE = 'UPDATE_MESSAGE';
const INCREMENT_COUNT = 'INCREMENT_COUNT';

dispatcher.subscribe(UPDATE_MESSAGE, (payload: string) => {
  appState.message = payload;
});

dispatcher.subscribe(INCREMENT_COUNT, () => {
  appState.count++;
});

function renderApp() {
  return h('div', { id: 'my-app' }, [
    h('h1', {}, appState.message),
    h('p', {}, `Count: ${appState.count}`),
    h('button', {
      onclick: () => {
        dispatcher.dispatch(INCREMENT_COUNT);
        updateView();
      },
    }, 'Increment Count'),
    h('button', {
      onclick: () => {
        dispatcher.dispatch(UPDATE_MESSAGE, 'Updated message from command!');
        updateView();
      },
    }, 'Update Message'),
  ]);
}

const app = createApp(renderApp);

function updateView() {
  const rootElement = document.getElementById('app-root');
  if (rootElement) {
    while (rootElement.firstChild) {
      rootElement.removeChild(rootElement.firstChild);
    }
    mountDOM(app.render(), rootElement);
  }
}

document.addEventListener('DOMContentLoaded', () => {
  const root = document.createElement('div');
  root.id = 'app-root';
  document.body.appendChild(root);
  updateView();
});