Package @nrgyjs/core

Package Purpose

The @nrgyjs/core package provides the fundamental reactive, scope, and MVC/MVVM primitives used by the Nrgy.js ecosystem.

Overview

The package combines several layers:

1. A reactive runtime based on atom(), compute(), and effect().
2. Scopes for lifecycle and resource ownership.
3. Utility helpers for atom composition and testing.
4. Controller, view, and view-model abstractions for MVC/MVVM patterns.

Most other Nrgy.js packages build on top of these APIs.

Package Installation

npm install @nrgyjs/core

yarn add @nrgyjs/core

pnpm add @nrgyjs/core

Conceptual Architecture

@nrgyjs/core is organized into several functional areas:

1. common/*: reusable equality and type helpers.
2. reactivity/*: atom types, runtime, schedulers, and effect execution.
3. scope/*: lifecycle boundaries that collect destroyable resources.
4. utils/*: helper functions built on top of atoms and effects.
5. mvc/*: controller declarations, view bindings, and view-model helpers.

Feature Documentation

• defaultEquals: Default equality strategy.
• objectEquals: Structural equality for plain objects.
• common types: Shared helper types such as ValueEqualityFn.
• reactivity: Main atom, compute, and effect API.
• reactivity types: Public types for atoms and effects.
• createScope: Scope lifecycle management.
• ScopeDestructionError: Aggregate destruction error.
• scope types: Shared scope contracts.
• createAtomSubject: Atom subject with value and error channels.
• batch: Batched reactive updates.
• mapAtom: Derived atom transformation.
• mergeAtoms: Combine several atoms into one.
• readonlyAtom: Read-only atom projection.
• runEffects: Manual scheduler flush helper.
• controller: Controller declarations and extensions.
• view: View binding contracts.
• viewModel: View-model declarations.
• viewProxy: Testable view binding implementation.
• withView: View extension for controllers.

Usage Examples

import { atom, compute, effect } from '@nrgyjs/core';

const count = atom(1);
const doubled = compute(() => count() * 2);

const subscription = effect(doubled, (value) => {
  console.log(value);
});

count.set(2);
subscription.destroy();

import { declareController } from '@nrgyjs/core';

const CounterController = declareController(({ scope }) => {
  const value = scope.atom(0);

  return {
    value,
    increase: () => value.update((prev) => prev + 1),
  };
});

const controller = new CounterController();
controller.increase();
controller.destroy();