nabd 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# 🚀 Nabd Core
+
+A lightweight, high-performance reactivity engine designed for Fintech applications. Built for precision, speed, and safety.
+
+# ✨ Features
+
+1.  Fine-Grained Reactivity: Updates only what changes—no more unnecessary re-renders.
+2.  Atomic Transactions: Native action and batch support for consistent state.
+3.  Bank-Grade Safety: Integrated withReversion for atomic optimistic UI rollbacks.
+4.  React Ready: Seamless integration with useSignal and useSyncExternalStore.
+5.  Type Safe: 100% TypeScript with first-class IDE support.
+
+# 📦 Installation
+
+```Bash
+
+npm install nabd
+# or
+yarn add nabd
+```
+
+# Quick Start Guide
+
+1. Create your first "Store"
+
+Instead of putting state inside components, create a dedicated file for your domain logic. This makes the state shareable and easy to test.
+
+```typescript
+// stores/counterStore.ts
+import { signal, computed, action, asReadonly } from "nabd";
+
+// 1. Private state (cannot be modified outside this file)
+const _count = signal(0);
+
+// 2. Public Read-only view
+export const count = asReadonly(_count);
+
+// 3. Derived state (Automatic)
+export const doubleCount = computed(() => _count.get() * 2);
+
+// 4. Actions (Logic with automatic batching)
+export const increment = action(() => {
+  _count.update((n) => n + 1);
+});
+
+export const reset = action(() => {
+  _count.set(0);
+});
+```
+
+2. Connect to a React Component
+   Use the useSignal hook to "peek" into the store. React will handle the subscription and unsubscription automatically.
+
+```typescript
+// components/Counter.tsx
+"use client"; // Required for Next.js App Router
+
+import { useSignal } from "nabd/react";
+import { count, doubleCount, increment } from "../stores/counterStore";
+
+export default function Counter() {
+  // Component re-renders ONLY when count changes
+  const c = useSignal(count);
+  const dc = useSignal(doubleCount);
+
+  return (
+    <div className="card">
+      <h1>Count: {c}</h1>
+      <h2>Double: {dc}</h2>
+      <button onClick={increment}>Add +1</button>
+    </div>
+  );
+}
+```
+
+3. Handle Async Data (The Resource Pattern)
+   For fetching data, use the resource handler. It tracks loading states so you don't have to create three separate signals manually.
+
+```typescript
+// stores/userStore.ts
+import { resource, signal } from "nabd";
+
+const userId = signal(1);
+
+export const userResource = resource(async () => {
+  const response = await fetch(`https://api.example.com/user/${userId.get()}`);
+  return response.json();
+});
+
+export const nextUser = () => userId.update((id) => id + 1);
+```
+
+# Fintech Patterns: Optimistic Updates
+
+Nabd makes handling failed transactions easy with withReversion.
+
+```typeScript
+
+import { withReversion, action } from 'nabd';
+
+export const sendMoney = action(async (amount: number) => {
+  balance.update(n => n - amount); // Update UI immediately
+
+  try {
+    await withReversion([balance], async () => {
+      await api.post('/transfer', { amount }); // If this fails, balance rolls back!
+    });
+  } catch (e) {
+    showNotification("Transfer failed, balance restored.");
+  }
+});
+```
+
+# Pro-Tips for the Team
+
+🟢 DO: Use asReadonly
+Always export the readonly version of your signals. This prevents components from doing count.set(999) directly, forcing all state changes to happen through defined Actions.
+
+🔴 DON'T: Use Signals for EVERYTHING
+If a piece of state is only used inside one small component and never shared (like a "isDropdownOpen" toggle), standard useState is perfectly fine. Use Signals for shared state or high-frequency updates.
+
+🟡 WATCH OUT: Destructuring
+Do not destructure signals in your component body.
+
+```typescript
+❌ const { get } = count; (Tracking might break)
+
+✅ const value = useSignal(count);
+```
+
+🛠️ Debugging with "Effects"
+If you're wondering why a value isn't updating, add a temporary effect in your store file. It will log every change to the console:
+
+```typeScript
+
+effect(() => {
+  console.log("[DEBUG] Count changed to:", count.get());
+});
+```
+
+# License
+
+MIT © akinnez/Nabd

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+type Subscriber = {
+    notify: () => void;
+    dependencies: Set<any>;
+};
+declare class Signal<T> {
+    private value;
+    private subscribers;
+    constructor(value: T);
+    get(): T;
+    peek(): T;
+    set(newValue: T): void;
+    update(fn: (val: T) => T): void;
+    subscribe(cb: () => void): () => void;
+    _unsubscribe(sub: Subscriber): void;
+}
+declare class Computed<T> {
+    private getter;
+    private cachedValue;
+    private dirty;
+    private signal;
+    private subscriber;
+    constructor(getter: () => T);
+    get(): T;
+    peek(): T;
+    subscribe(cb: () => void): () => void;
+}
+declare class Effect {
+    private fn;
+    private subscriber;
+    private cleanup?;
+    constructor(fn: () => void | (() => void));
+    private run;
+    dispose(): void;
+}
+declare const signal: <T>(v: T) => Signal<T>;
+declare const computed: <T>(fn: () => T) => Computed<T>;
+declare const effect: (fn: () => void | (() => void)) => Effect;
+declare const batch: (fn: () => void) => void;
+
+/**
+ * Executes an async task. If it fails, reverts signals to their previous state.
+ */
+declare function withReversion(signals: Signal<any>[], task: () => Promise<void>): Promise<void>;
+
+declare class ReadOnlySignal<T> {
+    protected ref: Signal<T> | Computed<T>;
+    constructor(ref: Signal<T> | Computed<T>);
+    get(): T;
+    peek(): T;
+    subscribe(cb: () => void): () => void;
+}
+declare const asReadonly: <T>(s: Signal<T> | Computed<T>) => ReadOnlySignal<T>;
+declare function action<T extends (...args: any[]) => any>(fn: T): T;
+declare function untracked<T>(fn: () => T): T;
+
+declare function resource<T>(fetcher: () => Promise<T>): {
+    data: Signal<T | undefined>;
+    loading: Signal<boolean>;
+    error: Signal<any>;
+    refetch: () => Promise<void>;
+};
+
+declare function debounceSignal<T>(source: Signal<T> | Computed<T>, delay: number): Signal<T>;
+
+type AnySignal<T> = Signal<T> | Computed<T> | ReadOnlySignal<T>;
+declare function useSignal<T>(source: AnySignal<T>): T;
+declare function useSignalEffect(fn: () => void | (() => void)): void;
+
+export { Computed, Effect, ReadOnlySignal, Signal, action, asReadonly, batch, computed, debounceSignal, effect, resource, signal, untracked, useSignal, useSignalEffect, withReversion };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+type Subscriber = {
+    notify: () => void;
+    dependencies: Set<any>;
+};
+declare class Signal<T> {
+    private value;
+    private subscribers;
+    constructor(value: T);
+    get(): T;
+    peek(): T;
+    set(newValue: T): void;
+    update(fn: (val: T) => T): void;
+    subscribe(cb: () => void): () => void;
+    _unsubscribe(sub: Subscriber): void;
+}
+declare class Computed<T> {
+    private getter;
+    private cachedValue;
+    private dirty;
+    private signal;
+    private subscriber;
+    constructor(getter: () => T);
+    get(): T;
+    peek(): T;
+    subscribe(cb: () => void): () => void;
+}
+declare class Effect {
+    private fn;
+    private subscriber;
+    private cleanup?;
+    constructor(fn: () => void | (() => void));
+    private run;
+    dispose(): void;
+}
+declare const signal: <T>(v: T) => Signal<T>;
+declare const computed: <T>(fn: () => T) => Computed<T>;
+declare const effect: (fn: () => void | (() => void)) => Effect;
+declare const batch: (fn: () => void) => void;
+
+/**
+ * Executes an async task. If it fails, reverts signals to their previous state.
+ */
+declare function withReversion(signals: Signal<any>[], task: () => Promise<void>): Promise<void>;
+
+declare class ReadOnlySignal<T> {
+    protected ref: Signal<T> | Computed<T>;
+    constructor(ref: Signal<T> | Computed<T>);
+    get(): T;
+    peek(): T;
+    subscribe(cb: () => void): () => void;
+}
+declare const asReadonly: <T>(s: Signal<T> | Computed<T>) => ReadOnlySignal<T>;
+declare function action<T extends (...args: any[]) => any>(fn: T): T;
+declare function untracked<T>(fn: () => T): T;
+
+declare function resource<T>(fetcher: () => Promise<T>): {
+    data: Signal<T | undefined>;
+    loading: Signal<boolean>;
+    error: Signal<any>;
+    refetch: () => Promise<void>;
+};
+
+declare function debounceSignal<T>(source: Signal<T> | Computed<T>, delay: number): Signal<T>;
+
+type AnySignal<T> = Signal<T> | Computed<T> | ReadOnlySignal<T>;
+declare function useSignal<T>(source: AnySignal<T>): T;
+declare function useSignalEffect(fn: () => void | (() => void)): void;
+
+export { Computed, Effect, ReadOnlySignal, Signal, action, asReadonly, batch, computed, debounceSignal, effect, resource, signal, untracked, useSignal, useSignalEffect, withReversion };

package/dist/index.js

@@ -0,0 +1,268 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Computed: () => Computed,
+  Effect: () => Effect,
+  ReadOnlySignal: () => ReadOnlySignal,
+  Signal: () => Signal,
+  action: () => action,
+  asReadonly: () => asReadonly,
+  batch: () => batch,
+  computed: () => computed,
+  debounceSignal: () => debounceSignal,
+  effect: () => effect,
+  resource: () => resource,
+  signal: () => signal,
+  untracked: () => untracked,
+  useSignal: () => useSignal,
+  useSignalEffect: () => useSignalEffect,
+  withReversion: () => withReversion
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/signals.ts
+var activeConsumer = null;
+var isBatching = false;
+var pendingNotifications = /* @__PURE__ */ new Set();
+var Signal = class {
+  constructor(value) {
+    this.value = value;
+  }
+  subscribers = /* @__PURE__ */ new Set();
+  get() {
+    if (activeConsumer) {
+      activeConsumer.dependencies.add(this);
+      this.subscribers.add(activeConsumer);
+    }
+    return this.value;
+  }
+  peek() {
+    return this.value;
+  }
+  set(newValue) {
+    if (Object.is(this.value, newValue)) return;
+    this.value = newValue;
+    if (isBatching) this.subscribers.forEach((sub) => pendingNotifications.add(sub));
+    else [...this.subscribers].forEach((sub) => sub.notify());
+  }
+  update(fn) {
+    this.set(fn(this.value));
+  }
+  subscribe(cb) {
+    const sub = { notify: cb, dependencies: /* @__PURE__ */ new Set([this]) };
+    this.subscribers.add(sub);
+    return () => this.subscribers.delete(sub);
+  }
+  _unsubscribe(sub) {
+    this.subscribers.delete(sub);
+  }
+};
+var Computed = class {
+  constructor(getter) {
+    this.getter = getter;
+    this.signal = new Signal(void 0);
+    this.subscriber = {
+      dependencies: /* @__PURE__ */ new Set(),
+      notify: () => {
+        this.dirty = true;
+        this.signal.set(this.get());
+      }
+    };
+  }
+  cachedValue;
+  dirty = true;
+  signal;
+  subscriber;
+  get() {
+    if (this.dirty) {
+      this.subscriber.dependencies.forEach((dep) => dep._unsubscribe(this.subscriber));
+      this.subscriber.dependencies.clear();
+      const prev = activeConsumer;
+      activeConsumer = this.subscriber;
+      try {
+        this.cachedValue = this.getter();
+        this.signal.value = this.cachedValue;
+      } finally {
+        activeConsumer = prev;
+      }
+      this.dirty = false;
+    }
+    return this.signal.get();
+  }
+  peek() {
+    return this.get();
+  }
+  subscribe(cb) {
+    return this.signal.subscribe(cb);
+  }
+};
+var Effect = class {
+  constructor(fn) {
+    this.fn = fn;
+    this.subscriber = { dependencies: /* @__PURE__ */ new Set(), notify: () => this.run() };
+    this.run();
+  }
+  subscriber;
+  cleanup;
+  run() {
+    this.dispose();
+    const prev = activeConsumer;
+    activeConsumer = this.subscriber;
+    try {
+      this.cleanup = this.fn() || void 0;
+    } finally {
+      activeConsumer = prev;
+    }
+  }
+  dispose() {
+    if (this.cleanup) this.cleanup();
+    this.subscriber.dependencies.forEach((s) => s._unsubscribe(this.subscriber));
+    this.subscriber.dependencies.clear();
+  }
+};
+var signal = (v) => new Signal(v);
+var computed = (fn) => new Computed(fn);
+var effect = (fn) => new Effect(fn);
+var batch = (fn) => {
+  isBatching = true;
+  try {
+    fn();
+  } finally {
+    isBatching = false;
+    pendingNotifications.forEach((s) => s.notify());
+    pendingNotifications.clear();
+  }
+};
+
+// src/core/reversion.ts
+async function withReversion(signals, task) {
+  const snapshots = signals.map((s) => s.peek());
+  try {
+    await task();
+  } catch (error) {
+    batch(() => {
+      signals.forEach((s, i) => s.set(snapshots[i]));
+    });
+    console.error("[Pulse] Operation failed. State reverted.", error);
+    throw error;
+  }
+}
+
+// src/core/action.ts
+var ReadOnlySignal = class {
+  constructor(ref) {
+    this.ref = ref;
+  }
+  get() {
+    return this.ref.get();
+  }
+  peek() {
+    return this.ref.peek();
+  }
+  subscribe(cb) {
+    return this.ref.subscribe(cb);
+  }
+};
+var asReadonly = (s) => new ReadOnlySignal(s);
+function action(fn) {
+  return ((...args) => {
+    let res;
+    batch(() => {
+      res = fn(...args);
+    });
+    return res;
+  });
+}
+function untracked(fn) {
+  const prev = globalThis.__activeConsumer;
+  globalThis.__activeConsumer = null;
+  const res = fn();
+  globalThis.__activeConsumer = prev;
+  return res;
+}
+
+// src/handlers/resources.ts
+function resource(fetcher) {
+  const data = signal(void 0);
+  const loading = signal(true);
+  const error = signal(null);
+  const exec = async () => {
+    loading.set(true);
+    try {
+      data.set(await fetcher());
+      error.set(null);
+    } catch (e) {
+      error.set(e);
+    } finally {
+      loading.set(false);
+    }
+  };
+  exec();
+  return { data, loading, error, refetch: exec };
+}
+
+// src/handlers/debounce.ts
+function debounceSignal(source, delay) {
+  const debounced = signal(source.peek());
+  let timeout;
+  effect(() => {
+    const val = source.get();
+    clearTimeout(timeout);
+    timeout = setTimeout(() => debounced.set(val), delay);
+  });
+  return debounced;
+}
+
+// src/react/hook.tsx
+var import_react = require("react");
+function useSignal(source) {
+  return (0, import_react.useSyncExternalStore)(
+    (cb) => source.subscribe(cb),
+    () => source.peek(),
+    () => source.peek()
+  );
+}
+function useSignalEffect(fn) {
+  (0, import_react.useEffect)(() => {
+    const eff = new Effect(fn);
+    return () => eff.dispose();
+  }, []);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Computed,
+  Effect,
+  ReadOnlySignal,
+  Signal,
+  action,
+  asReadonly,
+  batch,
+  computed,
+  debounceSignal,
+  effect,
+  resource,
+  signal,
+  untracked,
+  useSignal,
+  useSignalEffect,
+  withReversion
+});

package/dist/index.mjs

@@ -0,0 +1,226 @@
+// src/core/signals.ts
+var activeConsumer = null;
+var isBatching = false;
+var pendingNotifications = /* @__PURE__ */ new Set();
+var Signal = class {
+  constructor(value) {
+    this.value = value;
+  }
+  subscribers = /* @__PURE__ */ new Set();
+  get() {
+    if (activeConsumer) {
+      activeConsumer.dependencies.add(this);
+      this.subscribers.add(activeConsumer);
+    }
+    return this.value;
+  }
+  peek() {
+    return this.value;
+  }
+  set(newValue) {
+    if (Object.is(this.value, newValue)) return;
+    this.value = newValue;
+    if (isBatching) this.subscribers.forEach((sub) => pendingNotifications.add(sub));
+    else [...this.subscribers].forEach((sub) => sub.notify());
+  }
+  update(fn) {
+    this.set(fn(this.value));
+  }
+  subscribe(cb) {
+    const sub = { notify: cb, dependencies: /* @__PURE__ */ new Set([this]) };
+    this.subscribers.add(sub);
+    return () => this.subscribers.delete(sub);
+  }
+  _unsubscribe(sub) {
+    this.subscribers.delete(sub);
+  }
+};
+var Computed = class {
+  constructor(getter) {
+    this.getter = getter;
+    this.signal = new Signal(void 0);
+    this.subscriber = {
+      dependencies: /* @__PURE__ */ new Set(),
+      notify: () => {
+        this.dirty = true;
+        this.signal.set(this.get());
+      }
+    };
+  }
+  cachedValue;
+  dirty = true;
+  signal;
+  subscriber;
+  get() {
+    if (this.dirty) {
+      this.subscriber.dependencies.forEach((dep) => dep._unsubscribe(this.subscriber));
+      this.subscriber.dependencies.clear();
+      const prev = activeConsumer;
+      activeConsumer = this.subscriber;
+      try {
+        this.cachedValue = this.getter();
+        this.signal.value = this.cachedValue;
+      } finally {
+        activeConsumer = prev;
+      }
+      this.dirty = false;
+    }
+    return this.signal.get();
+  }
+  peek() {
+    return this.get();
+  }
+  subscribe(cb) {
+    return this.signal.subscribe(cb);
+  }
+};
+var Effect = class {
+  constructor(fn) {
+    this.fn = fn;
+    this.subscriber = { dependencies: /* @__PURE__ */ new Set(), notify: () => this.run() };
+    this.run();
+  }
+  subscriber;
+  cleanup;
+  run() {
+    this.dispose();
+    const prev = activeConsumer;
+    activeConsumer = this.subscriber;
+    try {
+      this.cleanup = this.fn() || void 0;
+    } finally {
+      activeConsumer = prev;
+    }
+  }
+  dispose() {
+    if (this.cleanup) this.cleanup();
+    this.subscriber.dependencies.forEach((s) => s._unsubscribe(this.subscriber));
+    this.subscriber.dependencies.clear();
+  }
+};
+var signal = (v) => new Signal(v);
+var computed = (fn) => new Computed(fn);
+var effect = (fn) => new Effect(fn);
+var batch = (fn) => {
+  isBatching = true;
+  try {
+    fn();
+  } finally {
+    isBatching = false;
+    pendingNotifications.forEach((s) => s.notify());
+    pendingNotifications.clear();
+  }
+};
+
+// src/core/reversion.ts
+async function withReversion(signals, task) {
+  const snapshots = signals.map((s) => s.peek());
+  try {
+    await task();
+  } catch (error) {
+    batch(() => {
+      signals.forEach((s, i) => s.set(snapshots[i]));
+    });
+    console.error("[Pulse] Operation failed. State reverted.", error);
+    throw error;
+  }
+}
+
+// src/core/action.ts
+var ReadOnlySignal = class {
+  constructor(ref) {
+    this.ref = ref;
+  }
+  get() {
+    return this.ref.get();
+  }
+  peek() {
+    return this.ref.peek();
+  }
+  subscribe(cb) {
+    return this.ref.subscribe(cb);
+  }
+};
+var asReadonly = (s) => new ReadOnlySignal(s);
+function action(fn) {
+  return ((...args) => {
+    let res;
+    batch(() => {
+      res = fn(...args);
+    });
+    return res;
+  });
+}
+function untracked(fn) {
+  const prev = globalThis.__activeConsumer;
+  globalThis.__activeConsumer = null;
+  const res = fn();
+  globalThis.__activeConsumer = prev;
+  return res;
+}
+
+// src/handlers/resources.ts
+function resource(fetcher) {
+  const data = signal(void 0);
+  const loading = signal(true);
+  const error = signal(null);
+  const exec = async () => {
+    loading.set(true);
+    try {
+      data.set(await fetcher());
+      error.set(null);
+    } catch (e) {
+      error.set(e);
+    } finally {
+      loading.set(false);
+    }
+  };
+  exec();
+  return { data, loading, error, refetch: exec };
+}
+
+// src/handlers/debounce.ts
+function debounceSignal(source, delay) {
+  const debounced = signal(source.peek());
+  let timeout;
+  effect(() => {
+    const val = source.get();
+    clearTimeout(timeout);
+    timeout = setTimeout(() => debounced.set(val), delay);
+  });
+  return debounced;
+}
+
+// src/react/hook.tsx
+import { useSyncExternalStore, useEffect } from "react";
+function useSignal(source) {
+  return useSyncExternalStore(
+    (cb) => source.subscribe(cb),
+    () => source.peek(),
+    () => source.peek()
+  );
+}
+function useSignalEffect(fn) {
+  useEffect(() => {
+    const eff = new Effect(fn);
+    return () => eff.dispose();
+  }, []);
+}
+export {
+  Computed,
+  Effect,
+  ReadOnlySignal,
+  Signal,
+  action,
+  asReadonly,
+  batch,
+  computed,
+  debounceSignal,
+  effect,
+  resource,
+  signal,
+  untracked,
+  useSignal,
+  useSignalEffect,
+  withReversion
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "nabd",
+  "version": "1.0.0",
+  "description": "A lightweight, high-performance reactivity engine designed mostly for Fintech applications. Built for precision, speed, and safety.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "bench": "tsx bench/signals.bench.ts"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "@types/react": "^19.2.8",
+    "mitata": "^0.1.14",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  },
+
+  "keywords": [
+    "react",
+    "reactivity",
+    "rx",
+    "web",
+    "signals",
+    "nabd",
+    "reversion",
+    "debounce",
+    "debounceSignal",
+    "resources",
+    "useSignal",
+    "useSignalEffect"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akinnez/nabd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/akinnez/nabd/issues"
+  },
+  "homepage": "https://github.com/akinnez/nabd#readme",
+
+  "author": "Oladejo Akinola Idris",
+  "contributors": [
+    "Oladejo Akinola Idris (https://github.com/akinnez)"
+  ]
+}
+