native-document 1.0.169 → 1.0.173

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

package/vitest.config.js

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        environment: 'happy-dom',
+        globals:     true,
+        include:     ['tests/**/*.test.js'],
+        coverage: {
+            provider: 'v8',
+            reporter: ['text', 'html'],
+            include:  ['src/**/*.js'],
+            exclude:  ['src/**/*.d.ts', 'src/ui/**/*.css'],
+        },
+    },
+});