@bull-js/runtime 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bull contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @bull-js/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MVVM runtime of [Bull](https://github.com/nicolasandradedesarrollosit/bull.js): observable state,
+ViewModels, commands, a dependency-injection container and the React bindings.
+
+```bash
+npm install @bull-js/runtime react react-dom
+```
+
+```ts
+import { ViewModel } from "@bull-js/runtime";
+
+export class CounterViewModel extends ViewModel {
+  readonly #count = this.state(0);
+  readonly count = this.#count.readonly;
+  readonly double = this.computed(() => this.#count.value * 2);
+  readonly increment = this.command(() => this.#count.update((n) => n + 1));
+}
+```
+
+```tsx
+import { useBinding, useViewModel } from "@bull-js/runtime/react";
+
+export function CounterView() {
+  const vm = useViewModel(CounterViewModel);
+  const count = useBinding(vm.count);
+  return <button onClick={vm.increment.execute}>{count}</button>;
+}
+```
+
+| Entry | Exports |
+|---|---|
+| `@bull-js/runtime` | `ViewModel`, `Command`, `Container`, `Token`, `state`, `computed`, `effect`, `batch`, `untracked` |
+| `@bull-js/runtime/react` | `createBullApp`, `BullProvider`, `useViewModel`, `useChildViewModel`, `useBinding` |
+
+The runtime works on its own, but Bull is meant to be used with [`@bull-js/cli`](https://www.npmjs.com/package/@bull-js/cli),
+which refuses to build when the code breaks MVVM.
+
+## License
+
+MIT

package/dist/chunk-QTHQ6FIG.js

@@ -0,0 +1,54 @@
+// src/container.ts
+var Container = class {
+  #models = /* @__PURE__ */ new Map();
+  #viewModels = /* @__PURE__ */ new Map();
+  /** Registers a Model (repository, service or shared entity). */
+  model(token, factory) {
+    this.#models.set(token, { factory });
+    return this;
+  }
+  /** Registers how to build a ViewModel and inject its dependencies. */
+  viewModel(token, factory) {
+    this.#viewModels.set(token, factory);
+    return this;
+  }
+  /** Gets a registered Model. */
+  get(token) {
+    const entry = this.#models.get(token);
+    if (!entry) {
+      if (this.#viewModels.has(token)) {
+        throw new Error(
+          `[bull] ${token.name} is a ViewModel. ViewModels are not requested from the container: the View creates them with useViewModel(${token.name}).`
+        );
+      }
+      throw new Error(
+        `[bull] No Model is registered as ${token.name}.
+Register it in the composition root (src/main.tsx):
+  c.model(${token.name}, () => new ${token.name}())`
+      );
+    }
+    if (!("instance" in entry)) entry.instance = entry.factory(this);
+    return entry.instance;
+  }
+  /** Creates a new ViewModel instance. Used by `useViewModel`. */
+  createViewModel(token) {
+    const factory = this.#viewModels.get(token);
+    if (factory) return factory(this);
+    if (token.length === 0) return new token();
+    throw new Error(
+      `[bull] ${token.name} needs dependencies, but no factory is registered.
+Register it in the composition root (src/main.tsx):
+  c.viewModel(${token.name}, (c) => new ${token.name}(c.get(MyRepository)))`
+    );
+  }
+};
+
+// src/lifecycle.ts
+var ACTIVATE = /* @__PURE__ */ Symbol.for("bull.viewmodel.activate");
+var DEACTIVATE = /* @__PURE__ */ Symbol.for("bull.viewmodel.deactivate");
+
+export {
+  Container,
+  ACTIVATE,
+  DEACTIVATE
+};

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Minimal signals-based reactivity.
+ *
+ * - `State`    mutable source of truth (only the ViewModel writes it).
+ * - `Computed` derived value, lazy and cached.
+ * - `effect`   reaction that re-runs when its dependencies change.
+ *
+ * Push-pull propagation: sources mark their observers as "dirty" and values
+ * are only recomputed when someone reads them. Reactions (effects and
+ * subscribers) are queued and run at the end of the batch, so they never see
+ * an intermediate state.
+ */
+/** Something that can be read and observed. It is all the View ever sees. */
+interface Readable<T> {
+    /** Reads the value and tracks the dependency if there is an active observer. */
+    readonly value: T;
+    /** Reads the value without tracking. */
+    peek(): T;
+    /** Subscribes to changes. Returns the unsubscribe function. */
+    readonly subscribe: (listener: () => void) => () => void;
+}
+/** Read-only view of a `State`. It is what a ViewModel exposes. */
+type ReadonlyState<T> = Readable<T>;
+interface Source {
+    observers: Set<Observer>;
+}
+interface Observer {
+    sources: Set<Source>;
+    /** Called by a source when it changes. */
+    invalidate(): void;
+}
+/** Groups several writes: reactions run only once, at the end. */
+declare function batch<T>(fn: () => T): T;
+/** Runs `fn` without tracking dependencies. */
+declare function untracked<T>(fn: () => T): T;
+declare class State<T> implements Readable<T>, Source {
+    #private;
+    readonly observers: Set<Observer>;
+    constructor(initial: T);
+    get value(): T;
+    peek(): T;
+    set(next: T): void;
+    update(fn: (current: T) => T): void;
+    readonly subscribe: (listener: () => void) => (() => void);
+    /** Read-only view: what the ViewModel should expose to the View. */
+    get readonly(): ReadonlyState<T>;
+}
+declare class Computed<T> implements Readable<T>, Source, Observer {
+    #private;
+    readonly observers: Set<Observer>;
+    readonly sources: Set<Source>;
+    constructor(fn: () => T);
+    invalidate(): void;
+    get value(): T;
+    peek(): T;
+    readonly subscribe: (listener: () => void) => (() => void);
+}
+/**
+ * Runs `fn` now and every time something it reads changes.
+ * `fn` may return a cleanup function. Returns the function that stops the effect.
+ */
+declare function effect(fn: () => void | (() => void)): () => void;
+declare function state<T>(initial: T): State<T>;
+declare function computed<T>(fn: () => T): Computed<T>;
+
+interface CommandOptions {
+    /** Extra condition to be able to execute (for example, a valid form). It is reactive. */
+    canExecute?: () => boolean;
+}
+/** What `execute` returns: `undefined` if the command could not run or failed. */
+type CommandResult<R> = R extends PromiseLike<infer U> ? Promise<U | undefined> : R | undefined;
+/**
+ * An action the ViewModel exposes to the View.
+ *
+ * The View never changes state: it calls `vm.something.execute(...)`. The
+ * command publishes its own observable state (`isRunning`, `error`,
+ * `canExecute`) so the View can disable buttons or show errors without logic.
+ */
+declare class Command<A extends unknown[] = [], R = void> {
+    #private;
+    /** `true` while an async command is running. */
+    readonly isRunning: ReadonlyState<boolean>;
+    /** The last error, or `undefined`. Cleared on the next execution. */
+    readonly error: ReadonlyState<unknown>;
+    /** `false` while running or when `options.canExecute` returns `false`. */
+    readonly canExecute: ReadonlyState<boolean>;
+    constructor(fn: (...args: A) => R, options?: CommandOptions);
+    /** Runs the action. It is bound, so it can be passed straight to an `onClick`. */
+    readonly execute: (...args: A) => CommandResult<R>;
+}
+
+/** Internal lifecycle keys. Used by `useViewModel`; not part of the public API. */
+declare const ACTIVATE: unique symbol;
+declare const DEACTIVATE: unique symbol;
+
+type EffectFn = () => void | (() => void);
+/**
+ * Base class of every ViewModel.
+ *
+ * A ViewModel:
+ *  - receives its Model dependencies through the constructor,
+ *  - keeps state with `this.state()` and exposes it with `.readonly`,
+ *  - derives data with `this.computed()`,
+ *  - exposes actions with `this.command()`,
+ *  - knows nothing about React, the DOM or how it is drawn.
+ *
+ * @example
+ * export class CounterViewModel extends ViewModel {
+ *   readonly #count = this.state(0);
+ *   readonly count = this.#count.readonly;
+ *   readonly increment = this.command(() => this.#count.update((n) => n + 1));
+ * }
+ */
+declare abstract class ViewModel {
+    #private;
+    protected state<T>(initial: T): State<T>;
+    protected computed<T>(fn: () => T): Computed<T>;
+    protected command<A extends unknown[] = [], R = void>(fn: (...args: A) => R, options?: CommandOptions): Command<A, R>;
+    /** Registers a reaction that runs while the associated View is mounted. */
+    protected effect(fn: EffectFn): void;
+    /**
+     * Called when the View that uses this ViewModel mounts. It is the place to
+     * load initial data. It may return a cleanup function.
+     */
+    protected onActivate(): void | (() => void);
+    get isActive(): boolean;
+    [ACTIVATE](): void;
+    [DEACTIVATE](): void;
+}
+
+type Token<T> = abstract new (...args: any[]) => T;
+type Factory<T> = (container: Container) => T;
+/**
+ * Dependency registry of the composition root (`src/main.tsx`).
+ *
+ * - Models are singletons: created once and shared.
+ * - ViewModels are created once per View that uses them.
+ */
+declare class Container {
+    #private;
+    /** Registers a Model (repository, service or shared entity). */
+    model<T>(token: Token<T>, factory: Factory<T>): this;
+    /** Registers how to build a ViewModel and inject its dependencies. */
+    viewModel<T extends ViewModel>(token: Token<T>, factory: Factory<T>): this;
+    /** Gets a registered Model. */
+    get<T>(token: Token<T>): T;
+    /** Creates a new ViewModel instance. Used by `useViewModel`. */
+    createViewModel<T extends ViewModel>(token: Token<T>): T;
+}
+
+export { Command, type CommandOptions, type CommandResult, Computed, Container, type Readable, type ReadonlyState, State, type Token, ViewModel, batch, computed, effect, state, untracked };

package/dist/index.js

@@ -0,0 +1,275 @@
+import {
+  ACTIVATE,
+  Container,
+  DEACTIVATE
+} from "./chunk-QTHQ6FIG.js";
+
+// src/reactive.ts
+var activeObserver = null;
+var batchDepth = 0;
+var pendingReactions = /* @__PURE__ */ new Set();
+function track(source) {
+  if (!activeObserver) return;
+  source.observers.add(activeObserver);
+  activeObserver.sources.add(source);
+}
+function untrackAll(observer) {
+  for (const source of observer.sources) source.observers.delete(observer);
+  observer.sources.clear();
+}
+function runTracked(observer, fn) {
+  untrackAll(observer);
+  const previous = activeObserver;
+  activeObserver = observer;
+  try {
+    return fn();
+  } finally {
+    activeObserver = previous;
+  }
+}
+function invalidateObservers(source) {
+  for (const observer of [...source.observers]) observer.invalidate();
+}
+function flush() {
+  while (pendingReactions.size > 0) {
+    const reactions = [...pendingReactions];
+    pendingReactions.clear();
+    for (const reaction of reactions) reaction();
+  }
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flush();
+  }
+}
+function untracked(fn) {
+  const previous = activeObserver;
+  activeObserver = null;
+  try {
+    return fn();
+  } finally {
+    activeObserver = previous;
+  }
+}
+function subscribeTo(source, listener) {
+  const reaction = () => {
+    source.peek();
+    listener();
+  };
+  const observer = {
+    sources: /* @__PURE__ */ new Set(),
+    invalidate: () => {
+      pendingReactions.add(reaction);
+      if (batchDepth === 0) flush();
+    }
+  };
+  runTracked(observer, () => {
+    track(source);
+    source.peek();
+  });
+  return () => {
+    untrackAll(observer);
+    pendingReactions.delete(reaction);
+  };
+}
+var State = class {
+  observers = /* @__PURE__ */ new Set();
+  #value;
+  #readonly;
+  constructor(initial) {
+    this.#value = initial;
+  }
+  get value() {
+    track(this);
+    return this.#value;
+  }
+  peek() {
+    return this.#value;
+  }
+  set(next) {
+    if (Object.is(next, this.#value)) return;
+    this.#value = next;
+    batch(() => invalidateObservers(this));
+  }
+  update(fn) {
+    this.set(fn(this.#value));
+  }
+  subscribe = (listener) => subscribeTo(this, listener);
+  /** Read-only view: what the ViewModel should expose to the View. */
+  get readonly() {
+    if (!this.#readonly) {
+      const self = this;
+      this.#readonly = Object.freeze({
+        get value() {
+          return self.value;
+        },
+        peek: () => self.peek(),
+        subscribe: self.subscribe
+      });
+    }
+    return this.#readonly;
+  }
+};
+var Computed = class {
+  observers = /* @__PURE__ */ new Set();
+  sources = /* @__PURE__ */ new Set();
+  #dirty = true;
+  #value;
+  #fn;
+  constructor(fn) {
+    this.#fn = fn;
+  }
+  invalidate() {
+    if (this.#dirty) return;
+    this.#dirty = true;
+    invalidateObservers(this);
+  }
+  get value() {
+    track(this);
+    return this.peek();
+  }
+  peek() {
+    if (this.#dirty) {
+      this.#value = runTracked(this, this.#fn);
+      this.#dirty = false;
+    }
+    return this.#value;
+  }
+  subscribe = (listener) => subscribeTo(this, listener);
+};
+function effect(fn) {
+  let cleanup;
+  let disposed = false;
+  const observer = {
+    sources: /* @__PURE__ */ new Set(),
+    invalidate: () => {
+      if (disposed) return;
+      pendingReactions.add(run);
+      if (batchDepth === 0) flush();
+    }
+  };
+  function run() {
+    if (disposed) return;
+    if (typeof cleanup === "function") cleanup();
+    cleanup = runTracked(observer, fn);
+  }
+  run();
+  return () => {
+    disposed = true;
+    untrackAll(observer);
+    pendingReactions.delete(run);
+    if (typeof cleanup === "function") cleanup();
+  };
+}
+function state(initial) {
+  return new State(initial);
+}
+function computed(fn) {
+  return new Computed(fn);
+}
+
+// src/command.ts
+var Command = class {
+  #running = new State(false);
+  #error = new State(void 0);
+  #fn;
+  /** `true` while an async command is running. */
+  isRunning = this.#running.readonly;
+  /** The last error, or `undefined`. Cleared on the next execution. */
+  error = this.#error.readonly;
+  /** `false` while running or when `options.canExecute` returns `false`. */
+  canExecute;
+  constructor(fn, options = {}) {
+    this.#fn = fn;
+    const extra = options.canExecute;
+    this.canExecute = new Computed(() => !this.#running.value && (extra ? extra() : true));
+  }
+  /** Runs the action. It is bound, so it can be passed straight to an `onClick`. */
+  execute = (...args) => {
+    if (!this.canExecute.peek()) return void 0;
+    this.#error.set(void 0);
+    let result;
+    try {
+      result = this.#fn(...args);
+    } catch (error) {
+      this.#fail(error);
+      return void 0;
+    }
+    if (!isThenable(result)) return result;
+    this.#running.set(true);
+    return Promise.resolve(result).then(
+      (value) => {
+        this.#running.set(false);
+        return value;
+      },
+      (error) => {
+        this.#running.set(false);
+        this.#fail(error);
+        return void 0;
+      }
+    );
+  };
+  #fail(error) {
+    this.#error.set(error);
+    console.error("[bull] A command failed:", error);
+  }
+};
+function isThenable(value) {
+  return typeof value?.then === "function";
+}
+
+// src/ViewModel.ts
+var ViewModel = class {
+  #effects = [];
+  #running = [];
+  #activations = 0;
+  state(initial) {
+    return new State(initial);
+  }
+  computed(fn) {
+    return new Computed(fn);
+  }
+  command(fn, options) {
+    return new Command(fn, options);
+  }
+  /** Registers a reaction that runs while the associated View is mounted. */
+  effect(fn) {
+    this.#effects.push(fn);
+    if (this.#activations > 0) this.#running.push(effect(fn));
+  }
+  /**
+   * Called when the View that uses this ViewModel mounts. It is the place to
+   * load initial data. It may return a cleanup function.
+   */
+  onActivate() {
+  }
+  get isActive() {
+    return this.#activations > 0;
+  }
+  [ACTIVATE]() {
+    if (this.#activations++ > 0) return;
+    this.#running = this.#effects.map((fn) => effect(fn));
+    const cleanup = this.onActivate();
+    if (typeof cleanup === "function") this.#running.push(cleanup);
+  }
+  [DEACTIVATE]() {
+    if (this.#activations === 0 || --this.#activations > 0) return;
+    for (const stop of this.#running.splice(0)) stop();
+  }
+};
+export {
+  Command,
+  Computed,
+  Container,
+  State,
+  ViewModel,
+  batch,
+  computed,
+  effect,
+  state,
+  untracked
+};

package/dist/react.d.ts

@@ -0,0 +1,38 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { Container, Readable, ViewModel, Token } from './index.js';
+
+declare function BullProvider(props: {
+    container: Container;
+    children?: ReactNode;
+}): react.JSX.Element;
+/**
+ * Connects a View with its ViewModel. Creates one instance per component,
+ * activates it on mount and deactivates it on unmount.
+ */
+declare function useViewModel<T extends ViewModel>(token: Token<T>): T;
+/**
+ * Activates a child ViewModel that a parent passed to a View through props
+ * (for example, a `TodoItemViewModel` inside a list).
+ */
+declare function useChildViewModel<T extends ViewModel>(vm: T): T;
+/** Reads an observable ViewModel value and re-renders when it changes. */
+declare function useBinding<T>(source: Readable<T>): T;
+interface BullAppOptions {
+    /** The root View of the application. */
+    root: ComponentType;
+    /** Registers the Models and ViewModels. It is the app's dependency injection. */
+    register?: (container: Container) => void;
+    /** Element or selector where the app is mounted. Defaults to `#root`. */
+    element?: Element | string;
+    /** Wraps the app in `<StrictMode>`. Defaults to `true`. */
+    strict?: boolean;
+}
+interface BullApp {
+    container: Container;
+    unmount(): void;
+}
+/** Mounts the application. Called once, from the composition root. */
+declare function createBullApp(options: BullAppOptions): BullApp;
+
+export { type BullApp, type BullAppOptions, BullProvider, Container, createBullApp, useBinding, useChildViewModel, useViewModel };

package/dist/react.js

@@ -0,0 +1,66 @@
+import {
+  ACTIVATE,
+  Container,
+  DEACTIVATE
+} from "./chunk-QTHQ6FIG.js";
+
+// src/react.tsx
+import {
+  createContext,
+  StrictMode,
+  useContext,
+  useEffect,
+  useState,
+  useSyncExternalStore
+} from "react";
+import { createRoot } from "react-dom/client";
+import { jsx } from "react/jsx-runtime";
+var ContainerContext = createContext(null);
+function BullProvider(props) {
+  return /* @__PURE__ */ jsx(ContainerContext.Provider, { value: props.container, children: props.children });
+}
+function useViewModel(token) {
+  const container = useContext(ContainerContext);
+  if (!container) {
+    throw new Error(
+      `[bull] useViewModel(${token.name}) was called outside a Bull app. Mount the app with createBullApp() in src/main.tsx.`
+    );
+  }
+  const [vm] = useState(() => container.createViewModel(token));
+  useLifecycle(vm);
+  return vm;
+}
+function useChildViewModel(vm) {
+  useLifecycle(vm);
+  return vm;
+}
+function useLifecycle(vm) {
+  useEffect(() => {
+    vm[ACTIVATE]();
+    return () => vm[DEACTIVATE]();
+  }, [vm]);
+}
+function useBinding(source) {
+  const snapshot = () => source.peek();
+  return useSyncExternalStore(source.subscribe, snapshot, snapshot);
+}
+function createBullApp(options) {
+  const container = new Container();
+  options.register?.(container);
+  const target = options.element ?? "#root";
+  const element = typeof target === "string" ? document.querySelector(target) : target;
+  if (!element) throw new Error(`[bull] Element "${String(target)}" was not found in index.html.`);
+  const Root = options.root;
+  const tree = /* @__PURE__ */ jsx(BullProvider, { container, children: /* @__PURE__ */ jsx(Root, {}) });
+  const root = createRoot(element);
+  root.render(options.strict === false ? tree : /* @__PURE__ */ jsx(StrictMode, { children: tree }));
+  return { container, unmount: () => root.unmount() };
+}
+export {
+  BullProvider,
+  Container,
+  createBullApp,
+  useBinding,
+  useChildViewModel,
+  useViewModel
+};

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@bull-js/runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Bull's MVVM runtime: observable state, ViewModels, commands and React bindings.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/nicolasandradedesarrollosit/bull.js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicolasandradedesarrollosit/bull.js.git",
+    "directory": "packages/runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/nicolasandradedesarrollosit/bull.js/issues"
+  },
+  "keywords": [
+    "react",
+    "mvvm",
+    "viewmodel",
+    "signals",
+    "reactive",
+    "state-management",
+    "dependency-injection"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/react.tsx --format esm --dts --clean --external react --external react-dom"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  }
+}