@nuxodin/item 0.6.4

package/src/AsyncDataPoint.d.ts

@@ -0,0 +1,52 @@
+export interface AsyncDataPointOptions {
+    optimistic?: boolean;
+    ttl?: number;
+    debounceMs?: number;
+    getRetry?: number;
+    getRetryDelay?: number;
+    setRetry?: number;
+    setRetryDelay?: number;
+    [key: string]: any;
+}
+
+export interface AsyncDataPointConfig<T = any> {
+    get: (signal?: AbortSignal) => Promise<T>;
+    set?: (value: T, signal?: AbortSignal) => Promise<T>;
+}
+
+export interface AsyncDataPointChangeEvent<T = any> {
+    value?: T;
+    oldValue?: T;
+    error?: Error;
+}
+
+export interface ResolvedAsyncDataPointOptions extends Required<AsyncDataPointOptions> {}
+
+export class AsyncDataPoint<T = any> {
+    options: ResolvedAsyncDataPointOptions;
+
+    createGetter: (signal?: AbortSignal) => Promise<T>;
+    createSetter: ((value: T, signal?: AbortSignal) => Promise<T>) | undefined;
+
+    onpending: (() => void) | null;
+    onchange: ((event: AsyncDataPointChangeEvent<T>) => void) | null;
+
+    constructor(config: AsyncDataPointConfig<T> & AsyncDataPointOptions);
+
+    get isPending(): boolean;
+    /** True once a full value has arrived — via getter, setLocal, setFromPromise or a landed write. Expires with ttl. */
+    get isLoaded(): boolean;
+    get lastError(): Error | undefined;
+    get recentValue(): T | undefined;
+
+    get(): Promise<T>;
+    set(value: T): Promise<T> | undefined;
+    setLocal(value: T): void;
+    setFromPromise(promise: Promise<T>): void;
+    dispose(): void;
+    getDebugState(): {
+        getter: Promise<T> | null;
+        setter: Promise<T> | null;
+        expectedValue: T | null;
+    };
+}

package/src/AsyncDataPoint.js

@@ -0,0 +1,280 @@
+    /*
+    // Usage:
+    const datapoint = new AsyncDataPoint({
+        get: () => fetch('https://example.com/todos/1').then(res => res.json()),
+        set: value => fetch('https://example.com/todos/1', {method: 'PUT', body: JSON.stringify(value)}).then(res => res.json())
+    });
+    datapoint.set({title: 'foo', completed: true}); // Returns promise - or undefined if value is already the same - do not rely on return value
+    datapoint.get().then(value => console.log(value));
+
+    // API
+    datapoint.onchange = ({value}) => console.log('value changed', value);
+    datapoint.ttl = 1000; // cache for 1 second
+    datapoint.optimistic = true; // trust sending value: until the sending is done, the value is the new value, despite the uncertainty that the server will fail
+    datapoint.debounceMs = 5; // debounce period for setter in ms, default 5
+    datapoint.setLocal({title: 'foo', completed: true}); // set value without saving it to the master (the value comes from the master through an other channel / trusted source)
+    */
+
+    export class AsyncDataPoint {
+
+        createGetter;
+        createSetter;
+        #expectedValue = null; // value while saving
+        #setter = null; // current setter promise
+        #getter = null; // current/cached getter promise
+        #getterExpiry = Infinity; // ttl is checked lazily on access — no timer per cache entry
+        // expired getters count as gone (lazy ttl)
+        get #cachedGetter() { return Date.now() < this.#getterExpiry ? this.#getter : null; }
+        onpending = null;
+        onchange = null;
+        
+        constructor({get, set, ...options}) {
+            this.options = {
+                optimistic: true,
+                ttl: 5000,
+                debounceMs: 5,
+                getRetry: 1,
+                getRetryDelay: 500,
+                setRetry: 0,
+                setRetryDelay: 500,
+                ...options
+            };
+            this.createGetter = get;
+            this.createSetter = set;
+        }
+
+        #createGetter() {
+            const {getRetry, getRetryDelay} = this.options;
+            const controller = new AbortController();
+            const promise = retryAsync(
+                () => this.createGetter(controller.signal),
+                getRetry, 
+                getRetryDelay
+            );
+            promise.controller = controller;
+            makePromiseTransparent(promise);
+            return promise;
+        }
+
+        #createSetter(value) {
+            const {setRetry, setRetryDelay, debounceMs} = this.options;        
+            const promise = abortablePromise((resolve, reject) => {
+                retryAsync(
+                    () => this.createSetter(value, promise.controller.signal),
+                    setRetry,
+                    setRetryDelay
+                ).then(resolve, reject);
+            }, debounceMs);
+            
+            makePromiseTransparent(promise);
+            return promise;
+        }
+
+        #cacheGetter(promise){
+            // trigger onchange if the value changes
+            // note: triggers also if the getter is no more cached as we dont know if the value has changed
+
+            if (promise.state === 'pending') this.onpending?.();
+
+            const oldValue = this.#getter?.value;
+            promise.then(
+                value => {
+                    if (this.#getter !== promise) return;
+                    if (!isEqual(oldValue, value)) {
+                        try {
+                            this.onchange?.({value, oldValue});
+                        } catch (err) {
+                            console.error('[item.js] AsyncDataPoint onchange error:', err);
+                        }
+                    }
+                },
+                error => {
+                    if (this.#getter !== promise) return;
+                    if (error?.name === 'AbortError') return;
+                    this.onchange?.({error, oldValue});
+                }
+            );
+
+            this.#getter = promise;
+            const duration = this.options.ttl;
+            this.#getterExpiry = duration > 0 ? Date.now() + duration : Infinity;
+        }
+
+        setLocal(value) { this.#cacheGetter(transparentPromiseResolve(value)); }
+        setFromPromise(promise) { this.#cacheGetter(makePromiseTransparent(promise)); }
+        get isPending() { return this.#cachedGetter?.state === 'pending' || this.#setter?.state === 'pending'; }
+        /** True once a full value has arrived — via getter, setLocal, setFromPromise or a landed write. */
+        get isLoaded() { return this.#cachedGetter?.state === 'fulfilled'; }
+        get lastError() { return this.#cachedGetter?.reason ?? this.#setter?.reason ?? undefined; }
+        get recentValue() { return this.#cachedGetter?.value; }
+
+        get() {
+            if (this.#setter?.state === 'pending') {
+                if (this.options.optimistic) {
+                    return Promise.resolve(this.#expectedValue); // trust sending value
+                } else {
+                    return this.#setter.then(() => this.get()); // wait for setter to be done
+                }
+            }
+            if (!this.#cachedGetter) this.#cacheGetter(this.#createGetter());
+            return this.#getter;
+        }
+
+        set(value) {
+            // Already setting this value
+            if (this.#setter?.state === 'pending' && isEqual(this.#expectedValue, value)) return this.#setter;
+
+            this.#setter?.controller.abort(); // abort previous setter
+
+            // ignore if latest getter value is the same
+            // Value already set (no-op). Returns undefined to avoid falsy issues (value could be 0, false, etc.)
+            if (this.#cachedGetter?.state === 'fulfilled' && isEqual(this.#cachedGetter.value, value)) return;
+            
+            this.#expectedValue = value;
+            const promise = this.#createSetter(value);
+            
+            this.onpending?.();
+
+            promise.then(
+                data  => {
+                    if (this.#setter !== promise) return;
+                    this.setLocal(value);
+                    this.#setter = null;
+                    this.#expectedValue = null;
+                },
+                error => {
+                    if (this.#setter !== promise) return;
+                    if (error?.name === 'AbortError') return;
+                    this.#getter = null;
+                    this.#setter = null;
+                    this.#expectedValue = null;
+                    this.onchange?.({ error }); }
+            );
+
+            return this.#setter = promise;
+        }
+
+        dispose() {
+            this.#setter?.controller.abort();
+            this.#getter?.controller?.abort();
+            this.#setter = null;
+            this.#getter = null;
+            this.#expectedValue = null;
+            this.#getterExpiry = Infinity;
+            this.onchange = null;
+        }
+        getDebugState() {
+            return {
+                getter: this.#getter,
+                setter: this.#setter,
+                expectedValue: this.#expectedValue
+            };
+        }
+
+    }
+
+
+
+    /**
+     * Adds state and value properties to a Promise, making it transparent.
+     * @param {Promise<any>|TransparentPromise} promise - The Promise to make transparent.
+     * @returns {TransparentPromise} - The transparent Promise.
+     * @example
+     * const promise = makePromiseTransparent(new Promise(resolve => resolve('foo')));
+     * promise.state; // 'pending'
+     * promise.value; // undefined
+     * promise.then(value => {
+     *      console.log(promise.state); // 'fulfilled'
+     *      console.log(promise.value); // 'foo'
+     * });
+     */
+    function makePromiseTransparent(promise) {
+        if (promise.state) console.warn('[item.js] already transparent');
+        promise.state = 'pending'; // or 'unknown' ?
+        promise.value = undefined;
+        promise.then(
+            value => {
+                promise.state = 'fulfilled';
+                promise.value = value;
+            },
+            reason => {
+                promise.state = 'rejected';
+                promise.reason = reason;
+            }
+        );
+        return promise;
+    }
+
+
+    /**
+     * Returns a transparent Promise (see makePromiseTransparent) that is resolved with the specified value.
+     * @param {any} value - The value to resolve the Promise with.
+     * @returns {TransparentPromise} - A transparent Promise.
+     */
+    function transparentPromiseResolve(value) {
+        const promise = makePromiseTransparent(Promise.resolve(value));
+        promise.state = 'fulfilled';
+        promise.value = value;
+        return promise;
+    }
+
+    /**
+     * Returns a delayed Promise that can be aborted within the specified time (ms).
+     * @param {Promise<any>} fn - A function that returns a Promise.
+     * @param {Number} [ms=1] - The time in milliseconds to delay before resolving the Promise.
+     * @returns {Promise<any>} - A delayed Promise that can be aborted.
+     */
+    function abortablePromise(fn, ms=1) { // delayed and therfore abortable within ms
+        const controller = new AbortController();
+        const promise = new Promise((resolve, reject) => {
+            setTimeout(() => {
+                if (controller.signal.aborted) return reject(new DOMException('aborted', 'AbortError'));
+                fn(resolve, reject);
+            }, ms);
+        });
+        promise.controller = controller;
+        return promise;
+    }
+
+    /**
+     * Retries an async operation with exponential backoff.
+     * @param {Function} fn - The async function to retry.
+     * @param {Number} retries - Number of retries (0 = no retry, just one attempt).
+     * @param {Number} baseDelay - Base delay in milliseconds for exponential backoff.
+     * @returns {Promise<any>} - The result of the operation.
+     */
+    async function retryAsync(fn, retries = 2, baseDelay = 1000) {
+        let lastError;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                return await fn();
+            } catch (error) {
+                if (error?.name === 'AbortError') return;
+                lastError = error;
+                if (attempt < retries) {
+                    const delay = baseDelay * Math.pow(2, attempt);
+                    console.warn(`[item.js] Attempt ${attempt + 1}/${retries + 1} failed, retrying in ${delay}ms...`, error);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw lastError;
+    }
+
+
+    /**
+     * Compares two values for equality.
+     * @param {any} a - The first value to compare.
+     * @param {any} b - The second value to compare.
+     * @returns {boolean} - True if the values are equal, false otherwise.
+     */
+    function isEqual(a, b) {
+        if (a === b) return true;
+        if (a == null || b == null || typeof a !== 'object' || typeof b !== 'object') return false;
+        if (a.constructor !== b.constructor) return false;
+
+        const keysA = Object.keys(a), keysB = Object.keys(b);
+        if (keysA.length !== keysB.length) return false;
+
+        return keysA.every(k => Object.hasOwn(b, k) && isEqual(a[k], b[k]));
+    }

package/src/Collection.experiment.js

@@ -0,0 +1,63 @@
+import { Emitter, ItemEvent } from './Emitter.js';
+import { evaluate } from '../tools/condition.js';
+
+export class Collection extends Emitter {
+    #source;
+    #filter;
+    #items = new Map();
+    #onChange;
+
+    constructor(source, filter = {}) {
+        super();
+        this.#source = source;
+        this.#filter = filter;
+        for (const item of source.items()) this.#evaluate(item);
+        this.#onChange = ({ target, add, remove }) => {
+            if (target === this.#source) {
+                if (remove) {
+                    if (this.#items.has(remove.key)) {
+                        this.#items.delete(remove.key);
+                        this.dispatchEvent(new ItemEvent('change', { remove }));
+                    }
+                    return;
+                }
+                if (add) {
+                    this.#evaluate(add);
+                    return;
+                }
+            }
+            const key = target.path[this.#source.path.length];
+            const direct = key ? this.#source.has(key) : target;
+            if (direct) this.#evaluate(direct);
+        };
+        source.addEventListener('changeIn', this.#onChange);
+        // source.addEventListener('destroy', () => this.destroy()); todo?
+    }
+
+    async read() {
+        if (!this.#source.reader) throw new Error('[item.js] no reader on source');
+        await this.#source.reader(this.#filter);
+        return this;
+    }
+
+    #evaluate(item) {
+        const has   = this.#items.has(item.key);
+        const match = evaluate(this.#filter, item.get());
+        if (match && !has) {
+            this.#items.set(item.key, item);
+            this.dispatchEvent(new ItemEvent('change', { add: item }));
+        } else if (!match && has) {
+            this.#items.delete(item.key);
+            this.dispatchEvent(new ItemEvent('change', { remove: item }));
+        }
+    }
+
+    get items() { return [...this.#items.values()]; }
+    get keys()  { return [...this.#items.keys()]; }
+    [Symbol.iterator]() { return this.#items.values(); }
+
+    destroy() {
+        this.#source.removeEventListener('changeIn', this.#onChange);
+        this.#items.clear();
+    }
+}

package/src/Emitter.js

@@ -0,0 +1,103 @@
+
+export class Emitter {
+    
+    #listeners = null;
+
+    addEventListener(type, fn, opts) {
+        if (opts?.signal?.aborted) return;
+        (this.#listeners ??= new Map()).has(type)
+            ? this.#listeners.get(type).add(fn)
+            : this.#listeners.set(type, new Set([fn]));
+        if (opts?.signal) opts.signal.addEventListener('abort', () => this.removeEventListener(type, fn), { once: true });
+    }
+
+    removeEventListener(type, fn) {
+        this.#listeners?.get(type)?.delete(fn);
+    }
+
+    dispatchEvent(e) {
+        e.target ??= this;
+        const fns = this.#listeners?.get(e.type);
+        if (fns) {
+            e.currentTarget = this;
+            for (const fn of fns) fn(e);
+        }
+        return !e.defaultPrevented;
+    }
+
+    removeAllListeners() {
+        this.#listeners?.clear();
+    }
+}
+
+
+export class ItemEvent {
+    type;
+    target;
+    currentTarget;
+    defaultPrevented = false;
+
+    constructor(type, options) {
+        this.type = type;
+        Object.assign(this, options);
+    }
+    preventDefault() { this.defaultPrevented = true; }
+    toJSON() {
+        return {
+            path: this.target.path,
+            add: this.add?.key,
+            remove: this.remove?.key,
+            pending: this.pending,
+            error: this.error?.message,
+            value: this.value,
+        }
+    }
+}
+
+
+/**
+ * Creates a async iterator from an event target.
+ * @param {EventTarget|Emitter} eventTarget - The event target.
+ * @param {string} eventName - The name of the event.
+ * @param {Object} [options] - The event listener options.
+ * @return {AsyncGenerator} A generator that yields events.
+ * @example
+ * const abortCtrl = new AbortController();
+ * for await (const event of asyncIteratorFromEventTarget(document, 'click', {signal: abortCtrl.signal})) {
+ *    console.log(event);
+ * }
+ * setTimeout(() => abortCtrl.abort(), 1000);
+ */
+export async function* asyncIteratorFromEventTarget(eventTarget, eventName, options) {
+    const queue = [];
+    let stopAfterQueue = false;
+    let resolve;
+    const eventHandler = event => {
+        queue.push(event);
+        if (resolve) {
+            resolve();
+            resolve = null;
+        }
+    };
+    eventTarget.addEventListener(eventName, eventHandler, options);
+    options?.signal?.addEventListener('abort', () => {
+        stopAfterQueue = true;
+        if (resolve) {
+            resolve();
+            resolve = null;
+        }
+    });
+    try {
+        while (true) {
+            if (queue.length) {
+                yield queue.shift();
+            } else if (stopAfterQueue) {
+                return;
+            } else {
+                await new Promise(res => resolve = res);
+            }
+        }
+    } finally {
+        eventTarget.removeEventListener(eventName, eventHandler, options);
+    }
+}

package/src/proxy.js

@@ -0,0 +1,77 @@
+
+export const $item = Symbol('item.js [proxy target]');
+
+const proxyHandler = {
+
+    get: function (target, property) {
+        const targetItem = target.item;
+        if (property === $item) return targetItem;
+        if (property === Symbol.iterator) {
+            !targetItem.filled && targetItem.read(); // read?
+            return function* () {
+                for (const childItem of targetItem) yield toProxy(childItem);
+            };
+        }
+        if (typeof property === 'symbol') {
+            if (typeof targetItem[property] === 'function') return targetItem[property].bind(targetItem);
+            return targetItem[property];
+        }
+
+        if (property === 'then') {
+            return (resolve, reject) => {
+                targetItem.read()
+                    .then(() => resolve(targetItem.get())) 
+                    .catch(reject);
+            };
+        }
+
+        const childItem = targetItem.item(property);
+
+        // toJSON is allowed
+        if (property === 'toJSON') console.warn('[item.js] toJSON accessed on proxy. Use `JSON.stringify(proxy())` instead of `JSON.stringify(proxy)`', Error().stack);
+
+        return toProxy(childItem);
+    },
+
+    set: function (target, property, value) {
+        target.item.item(property).set(value);
+        return true;
+    },
+
+    apply: function (target, thisArg, args) {
+        const targetItem = target.item;
+        if (args.length === 0) return targetItem.get();
+        if (args.length === 1) return targetItem.set(args[0]);
+        throw new Error('[item.js] apply called with too many arguments');
+    },
+
+    has: (target, property) => typeof property === 'string' && !!target.item.has(property),
+
+    ownKeys: (target) => {
+        if (!target.item.filled) target.item.read();
+        return target.item.keys;
+    },
+
+    getOwnPropertyDescriptor(target, property) {
+        if (typeof property === 'symbol') return Reflect.getOwnPropertyDescriptor(target.item, property);
+        if (target.item.has(property)) return { configurable: true, enumerable: true, writable: false };
+    },
+
+    deleteProperty: function (target, property) {
+        target.item.has(property)?.remove();
+        return true;
+    },
+};
+
+const cachedProxies = new WeakMap();
+
+export const toProxy = (itm) => {
+    let p = cachedProxies.get(itm);
+    if (!p) {
+        const fn = ()=>{};
+        fn.item = itm;
+        p = new Proxy(fn, proxyHandler);
+        cachedProxies.set(itm, p);
+    }
+    return p;
+};

package/src/signal.js

@@ -0,0 +1,95 @@
+
+// signal / effect
+const relatedEffects = new WeakMap();
+
+let activeEffect = null;
+let queue = null;
+
+/**
+ * Execute the provided function and re-execute it when dependencies change.
+ * @param {EffectFn} fn - A function that executes immediately and collects the containing items.
+ * @return {function} A function to dispose the effect.
+ */
+export function effect(fn) { // async?
+    const parent = activeEffect;
+    if (parent) {
+        (parent.nested ??= new Set()).add(fn);
+        if (fn.parent && fn.parent !== parent) throw new Error("[item.js] effect(cb) callbacks should not be reused for other effects");
+        fn.parent = parent;
+    }
+    activeEffect = fn;
+    cleanup(fn);
+    try { fn({ self: fn }); }
+    finally { activeEffect = parent; }
+    return () => dispose(fn);
+}
+
+/**
+ * Notify all effects that depend on the given signal.
+ * @param {Item} signal - The signal to notify.
+ */
+export function notify(signal) {
+    const effects = relatedEffects.get(signal);
+    if (!effects) return;
+    for (const fn of effects) {
+        fn.nested?.forEach(dispose);
+        if (fn.disposed) effects.delete(fn);
+        else batch(fn);
+    }
+}
+
+/**
+ * Register the active effect as a dependency of the given signal.
+ * @param {Item} signal - The signal to track.
+ */
+export function track(signal) {
+    if (!activeEffect || activeEffect.disposed) return;
+    let effects = relatedEffects.get(signal);
+    if (!effects) {
+        effects = new Set();
+        relatedEffects.set(signal, effects);
+    }
+    effects.add(activeEffect);
+    
+    (activeEffect.deps ??= new Set()).add(signal);
+}
+
+function batch(effect) {
+    if (queue) return queue.add(effect); // currently collecting
+    queue = new Set([effect]);
+    const schedule = globalThis.requestAnimationFrame ?? queueMicrotask;
+    schedule(() => {
+        const effects = queue;
+        queue = null;
+        for (const fn of effects) {
+            if (fn.disposed) continue;
+            if (effects.has(fn?.parent)) continue; // skip if parent already runs. needed as nested effects are disposed anyway
+            
+            cleanup(fn);
+
+            activeEffect = fn; // effect() called inside fn(callback) has to know his parent effect
+            try { fn({ self: fn }); }
+            catch (err) { console.error('[item.js]', err); }
+        }
+        activeEffect = null;
+//        queue = null; // restart collecting, todo? we could also keep collecting while running, but it can cause infinite loops if not careful
+    });
+}
+
+function cleanup(effect) {
+    if (!effect.deps) return;
+    for (const signal of effect.deps) {
+        relatedEffects.get(signal)?.delete(effect);
+    }
+    effect.deps.clear();
+}
+
+function dispose(effect) {
+    if (effect.disposed) return;
+    effect.disposed = true;
+    effect.nested?.forEach(dispose);
+    effect.nested?.clear();
+    effect.parent?.nested?.delete(effect); // remove from parent's nested set
+    effect.parent = undefined;
+}
+