native-document 1.0.172 → 1.0.174

package/CHANGELOG.md

@@ -11,27 +11,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.0.173] - 2026-06-18
+
+### Fixed
+
+- `ObservableItem` TypeScript definitions - `subscribe()` and `on()` no longer
+  typed as returning `Unsubscribe`; they return nothing in the actual
+  implementation. Use `.unsubscribe(callback)` / `.off(value, callback)` with
+  the same reference to remove a subscription.
+
+### Added
+
+- `ObservableItem` type definitions - `interceptMutations`, `clone`, `valueOf`
+- `ObservableItem` comparison helpers typed: `isEqualTo`, `isNotEqualTo`,
+  `isGreaterThan`, `isGreaterThanOrEqualTo`, `isLessThan`,
+  `isLessThanOrEqualTo`, `isBetween`, `isNull`, `isTruthy`, `isFalsy`,
+  `isStartingWith`, `isEndingWith`, `isMatchingPattern`, `isEmpty`,
+  `isNotEmpty`, `isIncludes`, `isIncludedIn`, `isOneOf`, `isHaving`
+- `ObservableItem` transform helpers typed: `toUpperCase`, `toLowerCase`,
+  `toTrimmed`, `toBoolean`, `toLiteral`, `toFormatted`, `toProperty`,
+  `toLength`, `toClamped`, `toPercent`
+- `ObservableArray` type definitions - `swapItems`, `insertAfter`, `sync`,
+  `clone`, `isNotEmpty`, `indexOf`, `includes`; `deepSubscribe` and `sync`
+  correctly typed to return `Unsubscribe`
+- `ObservableObject` type definitions - `$observables()` and `configs()` typed
+  as callable methods; `subscribe()` documented as deep-subscribing nested
+  observables and observable arrays
+- `ObservableResource` type definitions (previously entirely missing) -
+  `ResourceState`, `ObservableResourceConfig`, `data`, `error`, `state`,
+  `loading`, `fetch`, `refetch`, `mutate`, `into`, `apply`, `destroy`,
+  `isReady`, `isPending`, `isRefreshing`, `isErrored`, `isUnresolved`,
+  `onSuccess`, `onError`
+- `ObservableStatic` type definitions - `resource()`, `setLocale()`,
+  `useValueProperty()`
+
+---
+
 ## [1.0.172] - 2026-06-15
 
 ### Added
 
-- `Text(string)` — shorthand for `string.toNdChildren()`, parses Observable placeholders in template strings
-- `String.prototype.toNdChildren()` — splits a string containing `{{obs:N}}` placeholders into a mixed array of strings and resolved Observables
-- `ObservableItem.prototype.toString()` — auto-registers the Observable in MemoryManager and returns `{{obs:id}}`, enabling reactive interpolation via standard template literals
-- `NDElement.prototype.className(classes)` — adds static classes, bypasses AttributesWrapper
-- `NDElement.prototype.class(className, value)` — adds a reactive class binding, bypasses AttributesWrapper
-- `__$isNativeNode` flag on DOM prototypes (`Element`, `Text`, `Comment`, `Document`, `DocumentFragment`) — faster alternative to `instanceof Node`
-- `__$isValidNdChild` flag on all valid NdChild prototypes — single property check replaces multiple type guards
-- `defineToNdElement`, `defineValidNdChild`, `defineNativeNode` — non-enumerable prototype helpers in `nd-element-extensions`
-- camelCase variants added to `BOOLEAN_ATTRIBUTES` — removes `toLowerCase()` call on each attribute in the hot path
+- `Text(string)` - shorthand for `string.toNdChildren()`, parses Observable placeholders in template strings
+- `String.prototype.toNdChildren()` - splits a string containing `{{obs:N}}` placeholders into a mixed array of strings and resolved Observables
+- `ObservableItem.prototype.toString()` - auto-registers the Observable in MemoryManager and returns `{{obs:id}}`, enabling reactive interpolation via standard template literals
+- `NDElement.prototype.className(classes)` - adds static classes, bypasses AttributesWrapper
+- `NDElement.prototype.class(className, value)` - adds a reactive class binding, bypasses AttributesWrapper
+- `__$isNativeNode` flag on DOM prototypes (`Element`, `Text`, `Comment`, `Document`, `DocumentFragment`) - faster alternative to `instanceof Node`
+- `__$isValidNdChild` flag on all valid NdChild prototypes - single property check replaces multiple type guards
+- `defineToNdElement`, `defineValidNdChild`, `defineNativeNode` - non-enumerable prototype helpers in `nd-element-extensions`
+- camelCase variants added to `BOOLEAN_ATTRIBUTES` - removes `toLowerCase()` call on each attribute in the hot path
 
 ### Changed
 
-- `ElementCreator.processChildren` and `getChild` — refactored for better performance
-- `nd-element-extensions` — all prototype extensions converted to non-enumerable `defineProperty`
-- `AttributesWrapper` — `options` defaults to `null` instead of `{}`, fixes truthy check issue
-- NDElement events — inline handler (`on*`) used when no existing handler and no options; falls back to `addEventListener` for subsequent handlers or when options are provided
-- `_prevent`, `_stop`, `_preventStop` — updated with same inline handler strategy
+- `ElementCreator.processChildren` and `getChild` - refactored for better performance
+- `nd-element-extensions` - all prototype extensions converted to non-enumerable `defineProperty`
+- `AttributesWrapper` - `options` defaults to `null` instead of `{}`, fixes truthy check issue
+- NDElement events - inline handler (`on*`) used when no existing handler and no options; falls back to `addEventListener` for subsequent handlers or when options are provided
+- `_prevent`, `_stop`, `_preventStop` - updated with same inline handler strategy
 
 ---
 
@@ -39,34 +75,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Vitest test suite — `vitest.config.js`, happy-dom environment, scripts `test`, `test:watch`, `test:ui`, `test:coverage`
-- 372 tests passing across 13 files — 0 failures, 0 todo
+- Vitest test suite - `vitest.config.js`, happy-dom environment, scripts `test`, `test:watch`, `test:ui`, `test:coverage`
+- 372 tests passing across 13 files - 0 failures, 0 todo
 
-#### Unit tests — core
-- `observable-item` — 48 cases: set, val, subscribe, on/off, once, toggle, reset, transform, equals, clone, cleanup, intercept, assocTrigger
-- `observable-array` — 48 cases: push, remove, clear, merge, swap, insertAfter, isIncludes, where, sync, clone, reset, deepSubscribe
-- `observable-object` — 30 cases: constructor, val, get, set, subscribe, keys, observables, reset, clone
-- `observable-resource` — 29 cases: states, fetch, refetch, mutate, abort, race condition, deps, onSuccess, onError, into, apply, destroy
-- `store` — 43 cases: create, createResettable, createComposed, use, follow, reset, delete, group, protected, createPersistent
+#### Unit tests - core
+- `observable-item` - 48 cases: set, val, subscribe, on/off, once, toggle, reset, transform, equals, clone, cleanup, intercept, assocTrigger
+- `observable-array` - 48 cases: push, remove, clear, merge, swap, insertAfter, isIncludes, where, sync, clone, reset, deepSubscribe
+- `observable-object` - 30 cases: constructor, val, get, set, subscribe, keys, observables, reset, clone
+- `observable-resource` - 29 cases: states, fetch, refetch, mutate, abort, race condition, deps, onSuccess, onError, into, apply, destroy
+- `store` - 43 cases: create, createResettable, createComposed, use, follow, reset, delete, group, protected, createPersistent
 
-#### Unit tests — router
-- `route-matching` — 26 cases: exact path, params, typed params, custom validators, url(), metadata
-- `router-guards` — 14 cases: middleware execution, group middlewares, subscribe, resolve, currentState
+#### Unit tests - router
+- `route-matching` - 26 cases: exact path, params, typed params, custom validators, url(), metadata
+- `router-guards` - 14 cases: middleware execution, group middlewares, subscribe, resolve, currentState
 
-#### Unit tests — utils
-- `cache` — 12 cases: singleton, once, memoize
-- `filters` — 60 cases: equals, comparison, inArray, isEmpty, match, and/or/not, custom, string filters, date/time filters
+#### Unit tests - utils
+- `cache` - 12 cases: singleton, once, memoize
+- `filters` - 60 cases: equals, comparison, inArray, isEmpty, match, and/or/not, custom, string filters, date/time filters
 
-#### Integration tests — UI
-- `attributes-wrapper` — 22 cases: string, class map, style, Observable, boolean, aria attributes
-- `show-if` — 16 cases: static boolean, observable, factory child, HideIf, HideIfNot
-- `for-each-array` — 13 cases: static array, push, removeItem, clear, set, swap, index observable, order preservation
-- `lifecycle` — 11 cases: mounted, unmounted, destroy, destroyOnUnmount
+#### Integration tests - UI
+- `attributes-wrapper` - 22 cases: string, class map, style, Observable, boolean, aria attributes
+- `show-if` - 16 cases: static boolean, observable, factory child, HideIf, HideIfNot
+- `for-each-array` - 13 cases: static array, push, removeItem, clear, set, swap, index observable, order preservation
+- `lifecycle` - 11 cases: mounted, unmounted, destroy, destroyOnUnmount
 
 ### Fixed
 
-- `NDElement.prototype.destroy()` — guard against double call when `$element` is already null
-- `NDElement.prototype.destroy()` — disconnect lifecycle observer to prevent callbacks from firing after destroy
+- `NDElement.prototype.destroy()` - guard against double call when `$element` is already null
+- `NDElement.prototype.destroy()` - disconnect lifecycle observer to prevent callbacks from firing after destroy
 
 ---
 
@@ -98,7 +134,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### UI (renders)
 - `CardRender` + `card.css` - Card renderer with 5 build slots and `layout(slots)` support
-- `ListRender` + `list.css` - `ForEachArray($desc.items)` — items self-render
+- `ListRender` + `list.css` - `ForEachArray($desc.items)` - items self-render
 - `ListItemRender` + `list-item.css` - reactive checkbox, select indicator, swipe gesture with pointer events, auto-close and stopPropagation
 - `ListGroupRender` + `list-group.css` - collapsible group with reactive chevron via `Switch`
 - `ListDividerRender` + `list-divider.css`
@@ -240,7 +276,8 @@ Entries use the following categories:
 
 ---
 
-[Unreleased]: https://github.com/afrocodeur/native-document/compare/v1.0.172...HEAD
+[Unreleased]: https://github.com/afrocodeur/native-document/compare/v1.0.173...HEAD
+[1.0.173]: https://github.com/afrocodeur/native-document/compare/v1.0.172...v1.0.173
 [1.0.172]: https://github.com/afrocodeur/native-document/compare/v1.0.170...v1.0.172
 [1.0.170]: https://github.com/afrocodeur/native-document/compare/v1.0.169...v1.0.170
 [1.0.169]: https://github.com/afrocodeur/native-document/compare/v1.0.167...v1.0.169

package/index.d.ts

@@ -18,4 +18,4 @@ export declare const Observable: ObservableStatic;
 export declare const $: ObservableStatic;
 export declare const obs: ObservableStatic;
 export declare const Store: StoreStatic;
-export declare const Router: RouterStatic;
+// export declare const Router: RouterStatic;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-document",
-  "version": "1.0.172",
+  "version": "1.0.174",
   "description": "A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features",
   "author": "AfroCodeur <https://github.com/afrocodeur>",
   "license": "MIT",

package/src/core/data/ObservableItem.js

@@ -18,10 +18,10 @@ import {$getFromStorage, $saveToStorage} from '../utils/localstorage';
  * @param {boolean} [configs.propagation] - Controls whether changes propagate to parent observables
  * @example
  * const count = new ObservableItem(0);
- * const name  = new ObservableItem('John', { reset: true });
+ * const name = new ObservableItem('John', { reset: true });
  */
 export default function ObservableItem(value, configs = null) {
-    value = Validator.isObservable(value) ? value.val() : value;
+    value = value?.__$Observable ? value.val() : value;
 
     this.$previousValue = null;
     this.$currentValue = value;
@@ -33,9 +33,9 @@ export default function ObservableItem(value, configs = null) {
     this.$listeners = null;
     this.$watchers = null;
 
-    this.$memoryId = null;
+    this.$id = null;
 
-    if(configs) {
+    if(configs !== null) {
         this.configs = configs;
         if(configs.reset) {
             this.$initialValue = Validator.isObject(value) ? deepClone(value) : value;
@@ -308,7 +308,7 @@ ObservableItem.prototype.cleanup = function() {
         }
         this.$cleanupListeners = null;
     }
-    MemoryManager.unregister(this.$memoryId);
+    MemoryManager.unregister(this.$id);
     this.disconnectAll();
     if(process.env.NODE_ENV === 'development') {
         this.$isCleanedUp = true;

package/src/core/data/ObservableObject.js

@@ -198,14 +198,13 @@ ObservableObject.prototype.$updateWith = ObservableObject.prototype.set;
 
 /**
  * Returns an array of all internal observable instances (one per property).
- * Alias: $observables()
  *
  * @returns {ObservableItem[]} Array of observable instances
  */
 ObservableObject.prototype.observables = function() {
     return Object.values(this.$observables);
 };
-ObservableObject.prototype.$observables = ObservableObject.prototype.observables;
+// ObservableObject.prototype.$observables = ObservableObject.prototype.observables;
 
 /**
  * Returns all property names of the observable object.

package/src/core/wrappers/HtmlElementWrapper.js

@@ -1,6 +1,5 @@
 import Anchor from '../elements/anchor/anchor';
 import {ElementCreator} from './ElementCreator';
-import {normalizeComponentArgs} from '../utils/args-types';
 import './NdPrototype';
 
 import '../../core/utils/prototypes.js';
@@ -19,7 +18,7 @@ import '../wrappers/prototypes/attributes-extensions';
  * @returns {Text} Text node, reactive if value is an ObservableItem
  */
 export const createTextNode = (value) => {
-    if(value) {
+    if(value != null) {
         return value.toNdElement();
     }
     return ElementCreator.createTextNode();
@@ -58,11 +57,12 @@ export const createHtmlElement = (element, _attributes, _children = null) => {
         attributes = _children;
         children = _attributes;
     }
+    element = element.cloneNode();
 
-    if(attributes) {
+    if(attributes != null) {
         ElementCreator.processAttributes(element, attributes);
     }
-    if(children) {
+    if(children != null) {
         ElementCreator.processChildren(children, element);
     }
     return element;
@@ -75,6 +75,7 @@ export const createHtmlElement = (element, _attributes, _children = null) => {
  *
  * @param {string} name - HTML tag name (e.g. 'div', 'button', 'input'). Pass empty string to create a Fragment.
  * @param {((element: HTMLElement) => HTMLElement)|null} [customWrapper=null] - Optional function to augment the element before returning
+ * @param {boolean} [isVoid=false] - If true, the element is a void element (no children allowed, e.g. input, img)
  * @returns {(attr?: Object, children?: ValidChild) => HTMLElement} Element factory function
  * @example
  * const Div = HtmlElementWrapper('div');
@@ -89,14 +90,12 @@ export const createHtmlElement = (element, _attributes, _children = null) => {
 export default function  HtmlElementWrapper(name, customWrapper = null, isVoid = false) {
     const elementCreator = isVoid ? createVoidHtmlElement : createHtmlElement;
     if(name) {
-        if(customWrapper) {
+        if(customWrapper == null) {
             let node = null;
             let createElement = (attr, children) => {
                 node = document.createElement(name);
-                createElement = (attr, children) => {
-                    return elementCreator(customWrapper(node.cloneNode()), attr, children);
-                };
-                return elementCreator(customWrapper(node.cloneNode()), attr, children);;
+                createElement = elementCreator.bind(null, node);
+                return elementCreator(node.cloneNode(), attr, children);
             };
 
             return (attr, children) => createElement(attr, children);
@@ -106,9 +105,9 @@ export default function  HtmlElementWrapper(name, customWrapper = null, isVoid =
         let createElement = (attr, children) => {
             node = document.createElement(name);
             createElement = (attr, children) => {
-                return elementCreator(node.cloneNode(), attr, children);
+                return elementCreator(customWrapper(node.cloneNode()), attr, children);
             };
-            return elementCreator(node.cloneNode(), attr, children);
+            return elementCreator(customWrapper(node.cloneNode()), attr, children);;
         };
 
         return (attr, children) => createElement(attr, children);

package/src/core/wrappers/NdPrototype.js

@@ -26,7 +26,8 @@ Object.defineProperty(NDElement.prototype, 'nd', {
 EVENTS.forEach(eventSourceName => {
     const eventName = eventSourceName.toLowerCase();
     const inlineHandler = 'on'+eventName;
-    NDElement.prototype['on'+eventSourceName] = function(callback = null, options = null) {
+    const fnName = 'on'+eventSourceName;
+    NDElement.prototype[fnName] = function(callback = null, options = null) {
         if(!this.$element[inlineHandler] && !options) {
             this.$element[inlineHandler] = callback;
             return this;
@@ -34,26 +35,58 @@ EVENTS.forEach(eventSourceName => {
         this.$element.addEventListener(eventName, callback, options);
         return this;
     };
+    if(!HTMLElement.prototype[fnName]) {
+        HTMLElement.prototype[fnName] = function(callback, options) {
+            if(!this[inlineHandler] && !options) {
+                this[inlineHandler] = callback;
+                return this;
+            }
+            this.addEventListener(eventName, callback, options);
+            return this;
+        }
+    }
 });
 
 EVENTS_WITH_STOP.forEach(eventSourceName => {
     const eventName = eventSourceName.toLowerCase();
-    NDElement.prototype['onStop'+eventSourceName] = function(callback = null, options = null) {
+    const stopFnName = 'onStop'+eventSourceName;
+    const preventStopFnName = 'onPreventStop'+eventSourceName;
+
+    NDElement.prototype[stopFnName] = function(callback = null, options = null) {
         _stop(this.$element, eventName, callback, options);
         return this;
     };
-    NDElement.prototype['onPreventStop'+eventSourceName] = function(callback = null, options = null) {
+    NDElement.prototype[preventStopFnName] = function(callback = null, options = null) {
         _preventStop(this.$element, eventName, callback, options);
         return this;
     };
+    if(HTMLElement.prototype[stopFnName]) {
+        HTMLElement.prototype[stopFnName] = function(callback = null, options = null) {
+            _stop(this, eventName, callback, options);
+            return this;
+        };
+    }
+    if(!HTMLElement.prototype[preventStopFnName]) {
+        HTMLElement.prototype[preventStopFnName] = function(callback = null, options = null) {
+            _preventStop(this, eventName, callback, options);
+            return this;
+        };
+    }
 });
 
 EVENTS_WITH_PREVENT.forEach(eventSourceName => {
     const eventName = eventSourceName.toLowerCase();
-    NDElement.prototype['onPrevent'+eventSourceName] = function(callback = null, options = null) {
+    const preventFnName = 'onPrevent'+eventSourceName;
+    NDElement.prototype[preventFnName] = function(callback = null, options = null) {
         _prevent(this.$element, eventName, callback, options);
         return this;
     };
+    if(HTMLElement.prototype[preventFnName]) {
+        HTMLElement.prototype[preventFnName] = function(callback = null, options = null) {
+            _prevent(this, eventName, callback, options);
+            return this;
+        };
+    }
 });
 
 

package/src/core/wrappers/template-cloner/NodeCloner.js

@@ -17,8 +17,12 @@ export default function NodeCloner($element) {
     this.$styles = null;
     this.$attrs = null;
     this.$ndMethods = null;
+    this.$content = null;
 }
 
+NodeCloner.prototype.shouldBeHydrate = function() {
+    return this.$attrs !== null || this.$classes !== null || this.$styles !== null || this.$ndMethods !== null || this.$content !== null;
+};
 
 /**
  * Attaches a template binding to the element by hydrating it with the specified method.
@@ -171,16 +175,16 @@ NodeCloner.prototype.attach = function(methodName, callback) {
  * Registers a reactive text content binding for the element.
  *
  * @internal
- * @param {Function} valueorProperty - Function receiving data and returning the text content
+ * @param {Function} valueOrProperty - Function receiving data and returning the text content
  * @returns {NodeCloner} this
  */
-NodeCloner.prototype.text = function(valueorProperty) {
-    this.$content = valueorProperty;
-    if(typeof valueorProperty === 'function') {
-        this.cloneNode = (data) => createTextNode(valueorProperty.apply(null, data));
+NodeCloner.prototype.text = function(valueOrProperty) {
+    this.$content = valueOrProperty;
+    if(typeof valueOrProperty === 'function') {
+        this.cloneNode = (data) => createTextNode(valueOrProperty.apply(null, data));
         return this;
     }
-    this.cloneNode = (data) => createTextNode(data[0][valueorProperty]);
+    this.cloneNode = (data) => createTextNode(data[0][valueOrProperty]);
     return this;
 };
 

package/src/core/wrappers/template-cloner/TemplateCloner.js

@@ -24,11 +24,11 @@ export function TemplateCloner($fn) {
 
     const assignClonerToNode = ($node) => {
         const childNodes = $node.childNodes;
-        let containDynamicNode = !!$node.nodeCloner;
+        let containDynamicNode = $node.nodeCloner?.shouldBeHydrate();
         const childNodesLength = childNodes.length;
         for(let i = 0; i < childNodesLength; i++) {
             const child = childNodes[i];
-            if(child.nodeCloner) {
+            if(child.nodeCloner && child.nodeCloner.shouldBeHydrate()) {
                 containDynamicNode = true;
             }
             const localContainDynamicNode = assignClonerToNode(child);
@@ -179,9 +179,12 @@ export function useCache(fn) {
         return node;
     };
 
+    if(fn.length === 0) {
+        return () => wrapper();
+    }
     if(fn.length < 2) {
-        return (...args) => {
-            return wrapper(args);
+        return (arg) => {
+            return wrapper([arg]);
         };
     }
     return (_, __, ...args) => {

package/src/fetch/NativeFetch.js

@@ -15,6 +15,7 @@ export default function NativeFetch($baseUrl) {
     };
 
     this.fetch = async function(method, endpoint, params = {}, options = {}) {
+        endpoint = endpoint || '';
         if(options.formData) {
             const formData = new FormData();
             for(const key in params) {

package/src/ui/components/form/fields/FieldRender.js

@@ -110,7 +110,7 @@ const buildErrors = ($desc) => {
         return ShowIf($desc.hasErrors,
             () => Div({class: 'field-errors', ...($desc.elementsProps.error || {})},
                 ForEachArray($desc.errors, (error) =>
-                    Span({class: 'field-error'}, error),
+                    Span({class: 'field-error'}, (typeof error === 'string' ? error.toNdChildren() : error)),
                 ),
             ),
         );

package/types/native-fetch.d.ts

@@ -32,7 +32,7 @@ interface Interceptors {
     response: (callback: ResponseInterceptor) => void;
 }
 
-declare class NativeFetch {
+export declare class NativeFetch {
     constructor(baseUrl: string);
 
     interceptors: Interceptors;

package/types/observable-resource.d.ts

@@ -1,3 +1,3 @@
-import { ObservableItem, ObservableChecker, ObservableResourceConfig, ObservableResource } from './observable';
+// import { ObservableResourceConfig, ObservableResource } from './observable';
 
-export type { ObservableResource, ObservableResourceConfig };
+// export type { ObservableResource, ObservableResourceConfig };

package/types/observable.d.ts

@@ -1,4 +1,4 @@
-import {FilterResult, PredicateMap} from "./filters";
+import { FilterResult, PredicateMap } from './filters';
 
 export type Unsubscribe = () => void;
 
@@ -41,45 +41,96 @@ export interface FormattersStatic {
 
 export declare const Formatters: FormattersStatic;
 
+// -- Observable system type definitions ---------------------------------------
 
-// Observable system type definitions
 export interface ObservableItem<T = any> {
     readonly $currentValue: T;
     readonly $previousValue: T;
     readonly $initialValue: T | null;
     readonly $isCleanedUp: boolean;
+    readonly $memoryId: number | null;
+    readonly __$Observable: true;
+    readonly __$isObservable: true;
 
     $value: T;
-    $memoryId: number | null;
 
     val(): T;
     set(value: T | ((prev: T) => T)): void;
     trigger(operations?: ObservableOperation): void;
     cleanup(): void;
+    clone(): ObservableItem<T>;
+    disconnectAll(): void;
 
-    subscribe(callback: (current: T, previous: T, operations?: ObservableOperation) => void): Unsubscribe;
+    /**
+     * Registers a subscriber. Does NOT return an unsubscribe function —
+     * call .unsubscribe(callback) with the same reference to remove it.
+     */
+    subscribe(callback: (current: T, previous: T, operations?: ObservableOperation) => void): void;
     unsubscribe(callback: Function): void;
-    on(value: T, callback: ObservableItem<boolean> | ((isActive: boolean) => void)): () => void;
+
+    /**
+     * Registers a watcher for a specific value. Does NOT return an unsubscribe
+     * function — call .off(value, callback) to remove it.
+     */
+    on(value: T, callback: ObservableItem<boolean> | ((isActive: boolean) => void)): void;
+    off(value: T, callback?: Function): void;
+    once(predicate: T | ((value: T) => boolean), callback: (value: T) => void): void;
+    onCleanup(callback: () => void): void;
+
+    intercept(callback: (newValue: T, currentValue: T) => T | undefined): this;
+    interceptMutations(callback: (operation: ObservableOperation) => void): this;
 
     check<U>(callback: (value: T) => U): ObservableChecker<U>;
     transform<U>(callback: (value: T) => U): ObservableChecker<U>;
     is<U>(callback: (value: T) => U): ObservableChecker<U>;
     select<U>(callback: (value: T) => U): ObservableChecker<U>;
-    pluck<U>(callback: (value: T) => U): ObservableChecker<U>;
+    pluck<U>(key: string): ObservableChecker<U>;
     format(type: FormatType | ((value: T) => string), options?: FormatOptions): ObservableItem<string>;
     get(key: string | number): any;
     when(value: T): ObservableWhen<T>;
-    off(value: T, callback?: Function): void;
-    once(predicate: T | ((value: T) => boolean), callback: (value: T) => void): void;
-    onCleanup(callback: () => void): void;
-    intercept(callback: (newValue: T, currentValue: T) => T | undefined): this;
+
     persist(key: string, options?: {
         get?: (value: any) => T;
         set?: (value: T) => any;
     }): this;
-    disconnectAll(): void;
+
+    // -- comparison helpers (is*) -----------------------------------------------
+
+    isEqualTo(value: T | ObservableItem<T>): ObservableChecker<boolean>;
+    isNotEqualTo(value: T | ObservableItem<T>): ObservableChecker<boolean>;
+    isGreaterThan(value: T | ObservableItem<T>): ObservableChecker<boolean>;
+    isGreaterThanOrEqualTo(value: T | ObservableItem<T>): ObservableChecker<boolean>;
+    isLessThan(value: T | ObservableItem<T>): ObservableChecker<boolean>;
+    isLessThanOrEqualTo(value: T | ObservableItem<T>): ObservableChecker<boolean>;
+    isBetween(min: T | ObservableItem<T>, max: T | ObservableItem<T>): ObservableChecker<boolean>;
+    isNull(): ObservableChecker<boolean>;
+    isTruthy(): ObservableChecker<boolean>;
+    isFalsy(): ObservableChecker<boolean>;
+    isStartingWith(value: string | ObservableItem<string>): ObservableChecker<boolean>;
+    isEndingWith(value: string | ObservableItem<string>): ObservableChecker<boolean>;
+    isMatchingPattern(pattern: RegExp | ObservableItem<RegExp>): ObservableChecker<boolean>;
+    isEmpty(): ObservableChecker<boolean>;
+    isNotEmpty(): ObservableChecker<boolean>;
+    isIncludes(value: any | ObservableItem<any>): ObservableChecker<boolean>;
+    isIncludedIn(collection: any[] | ObservableItem<any[]>): ObservableChecker<boolean>;
+    isOneOf(collection: any[] | ObservableItem<any[]>): ObservableChecker<boolean>;
+    isHaving(key: string | ObservableItem<string>): ObservableChecker<boolean>;
+
+    // -- transform helpers (to*) -------------------------------------------------
+
+    toUpperCase(): ObservableChecker<string>;
+    toLowerCase(): ObservableChecker<string>;
+    toTrimmed(): ObservableChecker<string>;
+    toBoolean(): ObservableChecker<boolean>;
+    toLiteral(template: string, placeholder?: string): ObservableChecker<string>;
+    toFormatted(template: string, placeholder?: string): ObservableChecker<string>;
+    toProperty<U = any>(path: string): ObservableChecker<U>;
+    toLength(): ObservableChecker<number>;
+    toClamped(min: number | ObservableItem<number>, max: number | ObservableItem<number>): ObservableChecker<number>;
+    toPercent(total: number | ObservableItem<number>): ObservableChecker<number>;
 
     toString(): string;
+    valueOf(): T;
     equals(value: any): boolean;
     toBool(): boolean;
     toggle(): void;
@@ -93,7 +144,8 @@ export class ObservableWhen<T = any> {
 
     constructor(observer: ObservableItem<T>, value: T);
 
-    subscribe(callback: (value: boolean) => void): Unsubscribe;
+    /** Does NOT return an unsubscribe function — use .off() on the underlying observer. */
+    subscribe(callback: (value: boolean) => void): void;
     val(): boolean;
     isMatch(): boolean;
     isActive(): boolean;
@@ -106,11 +158,14 @@ export interface ObservableOperation {
 }
 
 export interface ObservableChecker<T = any> {
+    readonly __$Observable: true;
     readonly __$isObservableChecker: true;
 
-    subscribe(callback: (value: T) => void): Unsubscribe;
+    /** Does NOT return an unsubscribe function. */
+    subscribe(callback: (value: T) => void): void;
     check<U>(callback: (value: T) => U): ObservableChecker<U>;
     val(): T;
+    toNdElement(): Text;
 
     set(value: any): void;
     trigger(): void;
@@ -119,6 +174,7 @@ export interface ObservableChecker<T = any> {
 
 export interface ObservableArray<T> extends ObservableItem<T[]> {
     readonly length: number;
+    readonly __$isObservableArray: true;
 
     push(...items: T[]): number;
     pop(): T | undefined;
@@ -128,16 +184,19 @@ export interface ObservableArray<T> extends ObservableItem<T[]> {
     sort(compareFn?: (a: T, b: T) => number): T[];
     splice(start: number, deleteCount?: number, ...items: T[]): T[];
 
-    isEmpty(): boolean;
+    empty(): boolean;
     clear(): boolean;
     merge(values: T[]): void;
     removeItem(item: T): T[];
     remove(index: number): T[];
     swap(indexA: number, indexB: number): boolean;
-    count(condition: (item:T, index?:number) => boolean): number;
-    populateAndRender(iteration: number, callback: (index: number) => T): void;
+    swapItems(itemA: T, itemB: T): boolean;
+    insertAfter(item: T, afterItem: T): T[];
+    count(condition: (item: T, index?: number) => boolean): number;
+    populateAndRender(items: T[], factory: any, options: any): void;
 
     map<U>(callback: (value: T, index: number, array: T[]) => U): U[];
+    forEach(callback: (value: T, index: number, array: T[]) => void): void;
     filter(callback: (value: T, index: number, array: T[]) => boolean): T[];
     reduce<U>(callback: (acc: U, value: T, index: number, array: T[]) => U, initial: U): U;
     some(callback: (value: T, index: number, array: T[]) => boolean): boolean;
@@ -146,12 +205,21 @@ export interface ObservableArray<T> extends ObservableItem<T[]> {
     at(index: number): T | undefined;
     findIndex(callback: (value: T, index: number, array: T[]) => boolean): number;
     concat(...items: (T | T[])[]): T[];
+    indexOf(item: T): number;
+    includes(item: T): boolean;
 
-    where(predicates: PredicateMap<T>): ObservableArray<T>;
+    where(predicates: PredicateMap<T> | ((item: T) => boolean)): ObservableArray<T>;
     whereSome<K extends keyof T>(fields: K[], filter: FilterResult<T[K]>): ObservableArray<T>;
     whereEvery<K extends keyof T>(fields: K[], filter: FilterResult<T[K]>): ObservableArray<T>;
 
-    deepSubscribe(callback: (value: T[]) => void): () => void;
+    /** Returns an unsubscribe function that stops all deep observation. */
+    deepSubscribe(callback: (value: T[]) => void): Unsubscribe;
+
+    /** One-way sync — pushes mutations from this array to the target. Returns unsubscribe. */
+    sync(target: ObservableArray<T>): Unsubscribe;
+
+    clone(): ObservableArray<T>;
+    isNotEmpty(): ObservableChecker<boolean>;
 }
 
 export type ObservableObject<T extends Record<string, any>> = ObservableItem<T> & {
@@ -175,6 +243,12 @@ export type ObservableObject<T extends Record<string, any>> = ObservableItem<T>
     keys(): string[];
     $keys(): string[];
     observables(): ObservableItem<any>[];
+
+    /**
+     * Subscribing to an ObservableObject also deep-subscribes to all nested
+     * observables and observable arrays — triggers on any nested change.
+     */
+    subscribe(callback: (current: T, previous: T, operations?: ObservableOperation) => void): void;
 } & {
     [K in keyof T]: T[K] extends (infer U)[]
         ? ObservableArray<U>
@@ -183,6 +257,40 @@ export type ObservableObject<T extends Record<string, any>> = ObservableItem<T>
             : ObservableItem<T[K]>;
 };
 
+// -- ObservableResource ---------------------------------------------------------
+
+export type ResourceState = 'unresolved' | 'pending' | 'ready' | 'refreshing' | 'errored';
+
+export interface ObservableResourceConfig<T = any> {
+    auto?: boolean;
+    lazy?: boolean;
+    debounce?: number;
+    into?: ObservableItem<T>;
+    apply?: (result: any, data: ObservableItem<T>) => void;
+}
+
+export interface ObservableResource<T = any> {
+    readonly data: ObservableItem<T>;
+    readonly error: ObservableItem<Error | null>;
+    readonly state: ObservableItem<ResourceState>;
+    readonly loading: ObservableItem<boolean>;
+
+    fetch(): this;
+    refetch(): this;
+    mutate(value: T): this;
+    into(target: ObservableItem<T>): this;
+    apply(callback: (result: any, data: ObservableItem<T>) => void): this;
+    destroy(): void;
+
+    isReady(): ObservableChecker<boolean>;
+    isPending(): ObservableChecker<boolean>;
+    isRefreshing(): ObservableChecker<boolean>;
+    isErrored(): ObservableChecker<boolean>;
+    isUnresolved(): ObservableChecker<boolean>;
+
+    onSuccess(callback: (data: T) => void): this;
+    onError(callback: (error: Error) => void): this;
+}
 
 export interface BatchFunction<TArgs extends any[] = any[], TReturn = any> {
     (...args: TArgs): TReturn;
@@ -210,8 +318,14 @@ export interface ObservableStatic {
     object<T extends Record<string, any>>(value: T, configs?: ObservableConfig | null): ObservableObject<T>;
     json<T extends Record<string, any>>(value: T, configs?: ObservableConfig | null): ObservableObject<T>;
 
-    computed<T>(callback: () => T, dependencies?: ValidComputedDependencies | BatchFunction): ObservableItem<T>;
-    computed<T>(callback: () => T, batchFunction?: BatchFunction): ObservableItem<T>;
+    resource<T = any>(
+        fn: (...args: any[]) => Promise<T>,
+        dependencies?: ValidComputedDependencies,
+        config?: ObservableResourceConfig<T> | boolean,
+    ): ObservableResource<T>;
+
+    computed<T>(callback: (...values: any[]) => T, dependencies?: ValidComputedDependencies | BatchFunction): ObservableItem<T>;
+    computed<T>(callback: (...values: any[]) => T, batchFunction?: BatchFunction): ObservableItem<T>;
 
     batch<TArgs extends any[], TReturn>(
         callback: (...args: TArgs) => TReturn
@@ -219,9 +333,11 @@ export interface ObservableStatic {
 
     value(data: any): any;
     update(target: any, data: any): void;
+    setLocale(locale: string | ObservableItem<string>): void;
+    useValueProperty(propertyName?: string): void;
 
     getById(id: number): ObservableItem | null;
     cleanup(observable: ObservableItem): void;
     autoCleanup(enable?: boolean, options?: AutoCleanupOptions): void;
     arrayOfObject<T extends Record<string, any>>(data: T[]): ObservableObject<T>[];
-}
+}

package/types/service.d.ts

@@ -20,4 +20,5 @@ interface ServiceStatic {
     ): MemoizeProxy<(...args: Args) => T>;
 }
 
-export const Service: ServiceStatic;
+export const Service: ServiceStatic;
+export const Cache: ServiceStatic;

package/utils.js

@@ -1,11 +1,14 @@
-import NativeFetch from "./src/fetch/NativeFetch";
-import * as Cache from "./src/core/utils/cache";
-import * as filters from "./src/core/utils/filters/index";
-import {classPropertyAccumulator, cssPropertyAccumulator} from "./src/core/utils/property-accumulator";
+import NativeFetch from './src/fetch/NativeFetch';
+import * as Cache from './src/core/utils/cache';
+import * as filters from './src/core/utils/filters/index';
+import {classPropertyAccumulator, cssPropertyAccumulator} from './src/core/utils/property-accumulator';
+
+const Service = Cache;
 
 export {
     NativeFetch,
     Cache,
+    Service,
     filters,
     classPropertyAccumulator,
     cssPropertyAccumulator