@k37z3r/jbase 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.1] - 2026-02-04
+
+* **ReadMe (`README.md`):** Updated ReadMe for better understanding 
+
+
+## [2.0.2] - 2026-02-08
+
+### 🚀 Added (SSR & Architecture)
+
+* **Server-Side Rendering (SSR):** Full support for Node.js environments via `jsdom`.
+* Added `src/server.ts` with `parseHTML` utility.
+* Added `bind(window)` factory in `src/index.ts` to create isolated jBase instances per request.
+
+
+* **Context Awareness:** The core `jBase` class now accepts an optional `context` (Window/Document) in the constructor to support isolated environments.
+* **Environment Detection:** Added `isBrowser()` utility in `src/utils.ts` to safely distinguish between browser and server environments.
+
+### ⚡ Performance
+
+* **Data Module (`objects.ts`):** Optimized search algorithms in `find.first`, `find.last`, `find.key`, and `find.value`. moved query normalization (`toLowerCase()`) outside of loops to significantly reduce CPU overhead.
+* **Effects Module:** Added server-guards (`if (!isBrowser())`) to `fade.ts`, `slide.ts`, and `vertical.ts`. Animation logic is now skipped on the server to save resources.
+
+### 🛡️ Fixed (Stability & Logic)
+
+* **Core (`core.ts`):** Added crash protection for invalid CSS selectors. `$(...)` now catches `DOMException` errors internally and logs a warning instead of crashing.
+* **DOM Manipulation (`manipulation.ts`):**
+* Rewrote `unwrap()` using a `Set` to safely handle parent removal without conflicts on sibling elements.
+* Replaced global `window.document` usage with a `getDoc(this)` helper to prevent `ReferenceError` crashes in Node.js.
+
+
+* **HTTP Module (`http/*.ts`):** Fixed potential crash when parsing JSON from `200 OK` responses that contain an empty body.
+* **CSS Module (`styles.ts`):** Updated `css()` getter to access `getComputedStyle` via `el.ownerDocument` instead of global `window`.
+
+### 🔧 Changed & Cleaned
+
+* **Documentation:** Removed localized German JSDoc comments to reduce source code size and maintain a consistent English-only documentation standard.
+* **Config:** Fixed invalid JSON syntax in `tsconfig.json`.
+* **Type Safety:** Upgraded `isObject` utility to a TypeScript Type Guard for better type inference.

package/README.md

@@ -1,26 +1,25 @@
 # jBase
 
-![Version](https://img.shields.io/badge/version-2.0.0-blue.svg?style=flat-square)
+![Version](https://img.shields.io/badge/version-2.0.2-blue.svg?style=flat-square)
 ![License](https://img.shields.io/badge/license-GPL--3.0-green.svg?style=flat-square)
 ![Size](https://img.shields.io/badge/size-lightweight-orange.svg?style=flat-square)
 ![Build](https://img.shields.io/badge/build-passing-brightgreen.svg?style=flat-square)
 
 **A modern, lightweight, and modular JavaScript framework for high-performance DOM manipulation, event handling, and data management.**
 
-jBase offers a familiar chainable API (similar to jQuery) but is built on modern ES6+ standards. It goes beyond UI logic by including a robust set of immutable data utilities for handling complex arrays and objects.
+jBase offers a familiar chainable API (similar to jQuery) but is built on modern ES6+ standards. It goes beyond UI logic by including a robust set of immutable data utilities and **full Server-Side Rendering (SSR) support**.
 
 ---
 
 ## 📥 Installation
 
 ### via NPM / Yarn
-Ideal for modern web apps using bundlers like Webpack, Vite, or Rollup.
+Ideal for modern web apps using bundlers (Vite, Webpack) or Node.js.
 
 ```bash
 npm install @k37z3r/jbase
 # or
 yarn add @k37z3r/jbase
-
 ```
 
 ### via Script Tag (CDN)
@@ -29,39 +28,75 @@ Simply download the minified file and include it in your HTML.
 
 ```html
 <script src="dist/jbase.min.js"></script>
+```
+
+---
+
+## 🖥️ Server-Side Rendering (SSR) & Node.js
+
+jBase is **isomorphic**. You can use the exact same code on the client and the server.
+To use DOM manipulation in Node.js, simply bind jBase to a `jsdom` window instance.
+
+### 1. Install JSDOM (Optional Peer Dependency)
+
+```bash
+npm install jsdom
+```
+
+### 2. Bind to a Virtual Window
+
+Use the `bind` factory to create a jBase instance scoped to a specific request or document.
+
+```javascript
+import { JSDOM } from 'jsdom';
+import { bind } from '@k37z3r/jbase'; // Adjust to your package name
 
+// 1. Create a virtual DOM environment
+const dom = new JSDOM('<!DOCTYPE html><div id="app"></div>');
+const window = dom.window;
+
+// 2. Create a scoped instance of jBase
+const $ = bind(window);
+
+// 3. Manipulate the DOM exactly like in the browser
+$('#app')
+    .addClass('ssr-rendered')
+    .html('<h1>Hello from Node.js!</h1>')
+    .append('<p>This HTML was generated on the server.</p>');
+
+// 4. Output the final HTML string
+console.log(dom.serialize());
 ```
 
+> [!NOTE]
+> Browser-only features like animations (`fadeIn`, `slideUp`) or Event Bindings (`click`) are **safely ignored** in Node.js environments to prevent crashes and save resources.
+
 ---
 
-## 🚀 Quick Start
+## 🚀 Client-Side Features
 
 jBase exposes itself globally as `jBase` and the shorthand `$`.
 
-### 1. DOM Manipulation & Events
+### 1. DOM & Effects
 
 ```javascript
-import { $ } from 'jbase';
-
 $(document).ready(() => {
-    // Select elements and modify CSS
-    $('.card').css({ 
-        'background-color': '#f8f9fa',
-        'border-radius': '8px' 
-    });
-
-    // Handle events
-    $('#save-btn').on('click', (e) => {
+    // Event Handling
+    $('button.save').on('click', (e) => {
         e.preventDefault();
-        $('.status').text('Saved successfully!').fadeIn(300);
+        
+        // Chained manipulation & Animation
+        $('.notification')
+            .addClass('success')
+            .text('Saved successfully!')
+            .fadeIn(300);
     });
 });
-
 ```
 
 ### 2. Powerful Data Utilities
 
-jBase includes a unique `$.data` module for **immutable** array and object manipulation.
+jBase includes a unique `$.data` module for **immutable** array and object manipulation. Optimized for high performance.
 
 ```javascript
 const users = [
@@ -69,49 +104,32 @@ const users = [
     { id: 2, name: 'Bob', role: 'user' }
 ];
 
-// Find specific data efficiently
+// Find specific data efficiently (Optimized Search)
 const admin = $.data.find.first(users, 'admin', 'exact', 'role');
 
 // Remove data immutably (returns a new array)
 const nonAdmins = $.data.remove.byMatch(users, 'admin', 'exact', 'role');
-
 ```
 
 ### 3. HTTP Requests
 
-Simple, Promise-based AJAX wrappers.
+Simple, robust AJAX wrappers that handle JSON automatically.
 
 ```javascript
 $.http.get('https://api.example.com/items')
     .then(data => console.log('Items loaded:', data))
     .catch(err => console.error('Error:', err));
-
 ```
 
 ---
 
 ## 📚 Documentation
 
-Detailed documentation for all methods is available in the **[GitHub Wiki](../../wiki)**.
-
+Detailed documentation for all methods is available in the **[GitHub Wiki](../../wiki)** or offline **[Documentation](./wiki)**.
 
 ---
 
-## 🛠 Usage in Node.js
-
-jBase can be used in Node.js environments. Note that DOM-related methods require a window context (like jsdom), but **Data** and **HTTP** utilities work natively.
-
-```javascript
-const { $ } = require('jbase');
-
-// Use Data Utils on the server side
-const merged = $.data.mergeObjects({ a: 1 }, { b: 2 });
-
-```
-
----
-
-## ©️ License & Author
+## 📄 License
 
 **jBase** is open-source software licensed under the **[GPL-3.0-or-later](LICENSE)**.
 
@@ -119,6 +137,4 @@ const merged = $.data.mergeObjects({ a: 1 }, { b: 2 });
 
 **Website:** [sven-minio.de](https://sven-minio.de)
 
-**Copyright:** © 2026 Sven Minio
-
-```
+**Copyright:** © 2026 Sven Minio

package/dist/browser.d.ts

@@ -1,19 +1,17 @@
 /**
  * @file src/browser.ts
- * @version 2.0.0
+ * @version 2.0.2
  * @since 2.0.0
  * @license GPL-3.0-or-later
  * @copyright Sven Minio 2026
  * @author Sven Minio <https://sven-minio.de>
  * @category Browser
  * @description
- * * 🇬🇧: Browser Entry Point. Attaches the jBase library and utilities to the global window object so they can be accessed via `$` or `jBase` in inline scripts.
- * * 🇩🇪: Browser-Einstiegspunkt. Hängt die jBase-Bibliothek und Utilities an das globale Window-Objekt an, damit sie über `$` oder `jBase` in Inline-Skripten verfügbar sind.
+ * * Browser Entry Point. Attaches the jBase library and utilities to the global window object so they can be accessed via `$` or `jBase` in inline scripts.
  */
-import { $, jBase, http, jB, _jB, __jB, _jBase, __jBase } from './index';
+import { $, jBase, http, jB, _jB, __jB, _jBase, __jBase, __ } from './index';
 /**
- * * 🇬🇧: TypeScript declaration merging to extend the global Window interface.
- * * 🇩🇪: TypeScript Declaration Merging zur Erweiterung des globalen Window-Interfaces.
+ * * TypeScript declaration merging to extend the global Window interface.
  */
 declare global {
     interface Window {
@@ -24,6 +22,7 @@ declare global {
         __jB: typeof __jB;
         _jBase: typeof _jBase;
         __jBase: typeof __jBase;
+        __: typeof __;
         http: typeof http;
     }
 }

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzE;;;GAGG;AACH,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,CAAC,EAAE,OAAO,CAAC,CAAC;QACZ,KAAK,EAAE,OAAO,KAAK,CAAC;QACpB,EAAE,EAAE,OAAO,EAAE,CAAC;QACd,GAAG,EAAE,OAAO,GAAG,CAAC;QAChB,IAAI,EAAE,OAAO,IAAI,CAAC;QAClB,MAAM,EAAE,OAAO,MAAM,CAAC;QACtB,OAAO,EAAE,OAAO,OAAO,CAAC;QACxB,IAAI,EAAE,OAAO,IAAI,CAAC;KACrB;CACJ"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7E;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,MAAM;QACZ,CAAC,EAAE,OAAO,CAAC,CAAC;QACZ,KAAK,EAAE,OAAO,KAAK,CAAC;QACpB,EAAE,EAAE,OAAO,EAAE,CAAC;QACd,GAAG,EAAE,OAAO,GAAG,CAAC;QAChB,IAAI,EAAE,OAAO,IAAI,CAAC;QAClB,MAAM,EAAE,OAAO,MAAM,CAAC;QACtB,OAAO,EAAE,OAAO,OAAO,CAAC;QACxB,EAAE,EAAE,OAAO,EAAE,CAAC;QACd,IAAI,EAAE,OAAO,IAAI,CAAC;KACrB;CACJ"}

package/dist/core.d.ts

@@ -1,36 +1,31 @@
 /**
  * @file src/core.ts
- * @version 2.0.0
+ * @version 2.0.2
  * @since 2.0.0
  * @license GPL-3.0-or-later
  * @copyright Sven Minio 2026
  * @author Sven Minio <https://sven-minio.de>
  * @category Core
  * @description
- * * 🇬🇧: The main jBase class. Handles the selection engine, initialization, and plugin architecture.
- * * 🇩🇪: Die Haupt-jBase-Klasse. Behandelt die Selektions-Engine, Initialisierung und Plugin-Architektur.
+ * * The main jBase class. Handles the selection engine, initialization, and plugin architecture.
  */
 import { JBaseElement, JBaseInput } from './types';
 /**
- * * 🇬🇧: The core class of the framework, inheriting from the native Array class. Acts as a wrapper around DOM elements and enables chainable methods (Fluent Interface).
- * * 🇩🇪: Die Kern-Klasse des Frameworks, die von der nativen Array-Klasse erbt. Dient als Wrapper um DOM-Elemente und ermöglicht verkettbare Methoden (Fluent Interface).
+ * * The core class of the framework, inheriting from the native Array class. Acts as a wrapper around DOM elements and enables chainable methods (Fluent Interface).
  */
 export declare class jBase extends Array<JBaseElement> {
     selectorSource: string;
+    doc: Document;
     /**
-     * * 🇬🇧: Initializes a new jBase instance. Analyzes the provided selector and populates the internal array with found or created DOM elements.
-     * * 🇩🇪: Initialisiert eine neue jBase-Instanz. Analysiert den übergebenen Selektor und füllt das interne Array mit den gefundenen oder erstellten DOM-Elementen.
+     * * Initializes a new jBase instance. Analyzes the provided selector and populates the internal array with found or created DOM elements.
      * @param selector
-     * * 🇬🇧: The input selector (CSS selector, HTML string, DOM element, or collection).
-     * * 🇩🇪: Der Eingabe-Selektor (CSS-Selektor, HTML-String, DOM-Element oder Sammlung).
+     * * The input selector (CSS selector, HTML string, DOM element, or collection).
      */
-    constructor(selector?: JBaseInput);
+    constructor(selector?: JBaseInput, context?: Document | Window);
     /**
-     * * 🇬🇧: Custom serializer for JSON.stringify. Prevents circular references and huge outputs by returning a simplified preview.
-     * * 🇩🇪: Benutzerdefinierte Serialisierung für JSON.stringify. Verhindert Zirkelbezüge und riesige Ausgaben durch Rückgabe einer vereinfachten Vorschau.
+     * * Custom serializer for JSON.stringify. Prevents circular references and huge outputs by returning a simplified preview.
      * @returns
-     * * 🇬🇧: A simplified object representation for debugging.
-     * * 🇩🇪: Eine vereinfachte Objektrepräsentation für das Debugging.
+     * * A simplified object representation for debugging.
      */
     toJSON(): {
         meta: string;

package/dist/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEnD;;;GAGG;AACH,qBAAa,KAAM,SAAQ,KAAK,CAAC,YAAY,CAAC;IACnC,cAAc,EAAE,MAAM,CAAM;IAEnC;;;;;;OAMG;gBACS,QAAQ,CAAC,EAAE,UAAU;IAgCjC;;;;;;OAMG;IACH,MAAM;;;;;;CAYT"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEnD;;GAEG;AACH,qBAAa,KAAM,SAAQ,KAAK,CAAC,YAAY,CAAC;IACnC,cAAc,EAAE,MAAM,CAAM;IAC5B,GAAG,EAAE,QAAQ,CAAC;IACrB;;;;OAIG;gBACS,QAAQ,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM;IA0D9D;;;;OAIG;IACH,MAAM;;;;;;CAYT"}