yummies 7.11.0 → 7.13.0

package/mobx.js

@@ -1,208 +1,455 @@
-import { makeObservable, createAtom, comparer, observable, runInAction, action, $mobx, onBecomeObserved, onBecomeUnobserved } from "mobx";
 import { typeGuard } from "yummies/type-guard";
-const applyObservable = (context, annotationsArray, useDecorators) => {
-  if (useDecorators) {
-    annotationsArray.forEach(([annotation, ...fields]) => {
-      fields.forEach((field) => {
-        annotation(context, field);
-      });
-    });
-    makeObservable(context);
-  } else {
-    const annotationsObject = {};
-    annotationsArray.forEach(([annotation, ...fields]) => {
-      fields.forEach((field) => {
-        annotationsObject[field] = annotation;
-      });
-    });
-    makeObservable(context, annotationsObject);
-  }
+import { $mobx, action, comparer, createAtom, makeObservable, observable, onBecomeObserved, onBecomeUnobserved, runInAction } from "mobx";
+//#region src/mobx/apply-observable.ts
+/**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* Compact **MobX `makeObservable`** wiring from tuple lists of annotations and keys. Reduces boilerplate
+* when many fields share `observable`, `action`, or `computed` decorators and you want one call site
+* instead of sprawling annotation maps across large stores.
+*
+* ## Usage
+*
+* ```ts
+* import { applyObservable } from "yummies/mobx";
+* ```
+*/
+/**
+* Applies a compact list of MobX annotations to an object using either
+* decorator-style invocation or the annotation map form accepted by `makeObservable`.
+*
+* @template T Target object type.
+* @param context Object that should become observable.
+* @param annotationsArray Tuples of annotation followed by annotated field names.
+* @param useDecorators Enables decorator-style application before calling `makeObservable`.
+*
+* @example
+* ```ts
+* applyObservable(store, [[observable, 'items'], [action, 'setItems']]);
+* ```
+*
+* @example
+* ```ts
+* applyObservable(viewModel, [[computed, 'fullName']], true);
+* ```
+*/
+var applyObservable = (context, annotationsArray, useDecorators) => {
+	if (useDecorators) {
+		annotationsArray.forEach(([annotation, ...fields]) => {
+			fields.forEach((field) => {
+				annotation(context, field);
+			});
+		});
+		makeObservable(context);
+	} else {
+		const annotationsObject = {};
+		annotationsArray.forEach(([annotation, ...fields]) => {
+			fields.forEach((field) => {
+				annotationsObject[field] = annotation;
+			});
+		});
+		makeObservable(context, annotationsObject);
+	}
 };
-const createEnhancedAtom = (name, onBecomeObservedHandler, onBecomeUnobservedHandler, meta) => {
-  const atom = createAtom(
-    name,
-    onBecomeObservedHandler && (() => onBecomeObservedHandler(atom)),
-    onBecomeUnobservedHandler && (() => onBecomeUnobservedHandler(atom))
-  );
-  atom.meta = meta ?? {};
-  atom.reportChanged = atom.reportChanged.bind(atom);
-  atom.reportObserved = atom.reportObserved.bind(atom);
-  return atom;
+//#endregion
+//#region src/mobx/create-enhanced-atom.ts
+/**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **`createAtom` wrapper** that attaches arbitrary metadata and keeps MobX’s observed/unobserved
+* hooks in one place. Useful for custom reactive primitives, async resources, or debugging atoms
+* where the stock API is too bare.
+*
+* ## Usage
+*
+* ```ts
+* import { createEnhancedAtom } from "yummies/mobx";
+* ```
+*/
+/**
+* Creates a MobX atom extended with metadata and bound reporting methods.
+*
+* @template TMeta Metadata object stored on the atom.
+* @param name Atom name used by MobX for debugging.
+* @param onBecomeObservedHandler Callback fired when the atom becomes observed.
+* @param onBecomeUnobservedHandler Callback fired when the atom is no longer observed.
+* @param meta Optional metadata attached to the atom.
+* @returns Atom instance with `meta`, `reportChanged` and `reportObserved`.
+*
+* @example
+* ```ts
+* const atom = createEnhancedAtom('user-status');
+* atom.reportChanged();
+* ```
+*
+* @example
+* ```ts
+* const atom = createEnhancedAtom('cache', undefined, undefined, { scope: 'users' });
+* atom.meta.scope;
+* ```
+*/
+var createEnhancedAtom = (name, onBecomeObservedHandler, onBecomeUnobservedHandler, meta) => {
+	const atom = createAtom(name, onBecomeObservedHandler && (() => onBecomeObservedHandler(atom)), onBecomeUnobservedHandler && (() => onBecomeUnobservedHandler(atom)));
+	atom.meta = meta ?? {};
+	atom.reportChanged = atom.reportChanged.bind(atom);
+	atom.reportObserved = atom.reportObserved.bind(atom);
+	return atom;
 };
-const createRef = (cfg) => {
-  let lastValue;
-  const comparer$1 = cfg?.comparer ?? comparer.default;
-  const setValue = (value) => {
-    const nextValue = value ?? null;
-    if (comparer$1(ref.current, nextValue)) {
-      return;
-    }
-    runInAction(() => {
-      const prevLastValue = lastValue;
-      lastValue = ref.current ?? void 0;
-      ref.current = nextValue;
-      let isNextValueIgnored = false;
-      ref.listeners.forEach((listener) => {
-        const listenerResult = listener(ref.current, lastValue);
-        if (listenerResult === false) {
-          isNextValueIgnored = true;
-        }
-      });
-      if (isNextValueIgnored) {
-        lastValue = prevLastValue;
-        ref.current = lastValue ?? null;
-      } else if (ref.current === null && lastValue !== void 0) {
-        lastValue = void 0;
-      }
-    });
-  };
-  const ref = setValue;
-  ref.set = setValue;
-  ref.listeners = new Set(cfg?.onChange ? [cfg.onChange] : []);
-  if (cfg?.onSet || cfg?.onUnset) {
-    ref.listeners.add((value, prevValue) => {
-      if (value) {
-        cfg.onSet?.(value, prevValue);
-      } else {
-        cfg.onUnset?.(prevValue);
-      }
-    });
-  }
-  ref.current = cfg?.initial ?? null;
-  ref.meta = cfg?.meta ?? {};
-  makeObservable(ref, {
-    current: observable.ref,
-    meta: observable
-  });
-  return ref;
+//#endregion
+//#region src/mobx/create-ref.ts
+/**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **Observable ref** pattern for MobX: boxed mutable references with change listeners, metadata,
+* and optional custom equality. Bridges React-style ref holders and MobX reactivity when a single
+* mutable cell must notify dependents without replacing the whole parent object graph.
+*
+* ## Usage
+*
+* ```ts
+* import { createRef } from "yummies/mobx";
+* ```
+*/
+/**
+* Creates a MobX-aware ref that behaves like a callback ref and exposes
+* observable `current` and `meta` fields.
+*
+* @template T Referenced value type.
+* @template TMeta Additional observable metadata stored on the ref.
+* @param cfg Optional callbacks, initial value and comparer configuration.
+* @returns Observable ref function object.
+*
+* @example
+* ```ts
+* const inputRef = createRef<HTMLInputElement>();
+* inputRef.set(document.createElement('input'));
+* ```
+*
+* @example
+* ```ts
+* const ref = createRef<number>();
+* ref(3);
+* ref.current; // 3
+* ```
+*
+* @example
+* ```ts
+* const nodeRef = createRef({
+*   onUnset: () => console.log('detached'),
+*   meta: { mounted: false },
+* });
+* ```
+*/
+var createRef = (cfg) => {
+	let lastValue;
+	const comparer$1 = cfg?.comparer ?? comparer.default;
+	const setValue = (value) => {
+		const nextValue = value ?? null;
+		if (comparer$1(ref.current, nextValue)) return;
+		runInAction(() => {
+			const prevLastValue = lastValue;
+			lastValue = ref.current ?? void 0;
+			ref.current = nextValue;
+			let isNextValueIgnored = false;
+			ref.listeners.forEach((listener) => {
+				if (listener(ref.current, lastValue) === false) isNextValueIgnored = true;
+			});
+			if (isNextValueIgnored) {
+				lastValue = prevLastValue;
+				ref.current = lastValue ?? null;
+			} else if (ref.current === null && lastValue !== void 0) lastValue = void 0;
+		});
+	};
+	const ref = setValue;
+	ref.set = setValue;
+	ref.listeners = new Set(cfg?.onChange ? [cfg.onChange] : []);
+	if (cfg?.onSet || cfg?.onUnset) ref.listeners.add((value, prevValue) => {
+		if (value) cfg.onSet?.(value, prevValue);
+		else cfg.onUnset?.(prevValue);
+	});
+	ref.current = cfg?.initial ?? null;
+	ref.meta = cfg?.meta ?? {};
+	makeObservable(ref, {
+		current: observable.ref,
+		meta: observable
+	});
+	return ref;
 };
-const isRef = (value) => {
-  return typeof value === "function" && "current" in value;
+/**
+* Checks whether the provided value is a ref created by `createRef`.
+*
+* @template T Referenced value type.
+* @template TMeta Ref metadata type.
+* @param value Value to inspect.
+* @returns `true` when the value is a ref-like function with `current`.
+*
+* @example
+* ```ts
+* const ref = createRef<number>();
+* isRef(ref); // true
+* ```
+*
+* @example
+* ```ts
+* isRef({ current: 1 }); // false
+* ```
+*/
+var isRef = (value) => {
+	return typeof value === "function" && "current" in value;
 };
-const toRef = (value, cfg) => {
-  return isRef(value) ? value : createRef({ initial: value, ...cfg });
+/**
+* Normalizes a plain value or an existing ref into a `Ref` instance.
+*
+* @template T Referenced value type.
+* @template TMeta Ref metadata type.
+* @param value Existing ref or initial plain value.
+* @param cfg Optional ref configuration applied when a new ref is created.
+* @returns Existing ref or a newly created ref initialized with `value`.
+*
+* @example
+* ```ts
+* const ref = toRef(document.body);
+* ref.current === document.body;
+* ```
+*
+* @example
+* ```ts
+* const existingRef = createRef<number>();
+* const sameRef = toRef(existingRef);
+* ```
+*/
+var toRef = (value, cfg) => {
+	return isRef(value) ? value : createRef({
+		initial: value,
+		...cfg
+	});
 };
-class DeepObservableStruct {
-  data;
-  constructor(data) {
-    this.data = data;
-    makeObservable(this, {
-      data: observable.deep,
-      set: action
-    });
-  }
-  set(newData) {
-    const stack = Object.keys(this.data).map((key) => [
-      key,
-      this.data,
-      newData
-    ]);
-    let currentIndex = 0;
-    let stackLength = stack.length;
-    while (currentIndex < stackLength) {
-      const [key, currObservableData, newData2] = stack[currentIndex];
-      const newValue = newData2[key];
-      const currValue = currObservableData[key];
-      currentIndex++;
-      if (key in newData2) {
-        if (typeGuard.isObject(newValue) && typeGuard.isObject(currValue)) {
-          const newValueKeys = Object.keys(newValue);
-          Object.keys(currValue).forEach((childKey) => {
-            if (!(childKey in newValue)) {
-              delete currObservableData[key][childKey];
-            }
-          });
-          newValueKeys.forEach((childKey) => {
-            const length = stack.push([
-              childKey,
-              currObservableData[key],
-              newValue
-            ]);
-            stackLength = length;
-          });
-        } else if (newValue !== currValue) {
-          currObservableData[key] = newValue;
-        }
-      } else {
-        delete currObservableData[key];
-      }
-    }
-    Object.keys(newData).forEach((newDataKey) => {
-      if (!this.data[newDataKey]) {
-        this.data[newDataKey] = newData[newDataKey];
-      }
-    });
-  }
-}
-const getMobxAdministration = (context) => context[$mobx];
-const lazyObserve = ({
-  context,
-  property,
-  onStart,
-  onEnd,
-  endDelay = false
-}) => {
-  let timeoutId;
-  let metaData;
-  const observingProps = /* @__PURE__ */ new Set();
-  const properties = Array.isArray(property) ? property : [property];
-  const cleanup = () => {
-    observingProps.clear();
-    if (endDelay === false) {
-      onEnd?.(metaData, cleanup);
-      metaData = void 0;
-      return;
-    }
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-      timeoutId = void 0;
-    }
-    timeoutId = setTimeout(() => {
-      onEnd?.(metaData, cleanup);
-      timeoutId = void 0;
-      metaData = void 0;
-    }, endDelay);
-  };
-  const start = (property2) => {
-    const isAlreadyObserving = observingProps.size > 0;
-    observingProps.add(property2);
-    if (isAlreadyObserving) {
-      return;
-    }
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-      timeoutId = void 0;
-    }
-    metaData = onStart?.();
-  };
-  const stop = (property2) => {
-    const isAlreadyNotObserving = !observingProps.size;
-    observingProps.delete(property2);
-    const isObserving = observingProps.size > 0;
-    if (isAlreadyNotObserving || isObserving) {
-      return;
-    }
-    cleanup();
-  };
-  properties.forEach((property2) => {
-    if (context) {
-      onBecomeObserved(context, property2, () => start(property2));
-      onBecomeUnobserved(context, property2, () => stop(property2));
-    } else {
-      onBecomeObserved(property2, () => start(property2));
-      onBecomeUnobserved(property2, () => stop(property2));
-    }
-  });
-  return cleanup;
+//#endregion
+//#region src/mobx/deep-observable-struct.ts
+/**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **Deep observable object** with structural `set` patches that reuse nested observables when keys
+* overlap. Helps store trees (forms, filters, entities) under MobX without wholesale replacement
+* and without manual `observable.map` wiring for every level.
+*
+* ## Usage
+*
+* ```ts
+* import { DeepObservableStruct } from "yummies/mobx";
+* ```
+*/
+/**
+* Wraps a plain object into a deeply observable structure and allows
+* patch-like updates while preserving nested observable references where possible.
+*
+* @template TData Observable object shape.
+*
+* @example
+* ```ts
+* const state = new DeepObservableStruct({ user: { name: 'Ann' } });
+* state.set({ user: { name: 'Bob' } });
+* ```
+*
+* @example
+* ```ts
+* const state = new DeepObservableStruct({ filters: { active: true } });
+* state.set({ filters: { active: false, archived: true } });
+* ```
+*/
+var DeepObservableStruct = class {
+	data;
+	constructor(data) {
+		this.data = data;
+		makeObservable(this, {
+			data: observable.deep,
+			set: action
+		});
+	}
+	set(newData) {
+		const stack = Object.keys(this.data).map((key) => [
+			key,
+			this.data,
+			newData
+		]);
+		let currentIndex = 0;
+		let stackLength = stack.length;
+		while (currentIndex < stackLength) {
+			const [key, currObservableData, newData] = stack[currentIndex];
+			const newValue = newData[key];
+			const currValue = currObservableData[key];
+			currentIndex++;
+			if (key in newData) {
+				if (typeGuard.isObject(newValue) && typeGuard.isObject(currValue)) {
+					const newValueKeys = Object.keys(newValue);
+					Object.keys(currValue).forEach((childKey) => {
+						if (!(childKey in newValue)) delete currObservableData[key][childKey];
+					});
+					newValueKeys.forEach((childKey) => {
+						stackLength = stack.push([
+							childKey,
+							currObservableData[key],
+							newValue
+						]);
+					});
+				} else if (newValue !== currValue) currObservableData[key] = newValue;
+			} else delete currObservableData[key];
+		}
+		Object.keys(newData).forEach((newDataKey) => {
+			if (!this.data[newDataKey]) this.data[newDataKey] = newData[newDataKey];
+		});
+	}
 };
-export {
-  DeepObservableStruct,
-  applyObservable,
-  createEnhancedAtom,
-  createRef,
-  getMobxAdministration,
-  isRef,
-  lazyObserve,
-  toRef
+//#endregion
+//#region src/mobx/get-mobx-administration.ts
+/**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* Typed access to MobX **internal administration** (`$mobx`) for advanced tooling, migration scripts,
+* or introspection. Prefer public MobX APIs in application code; reach for this when you must align
+* with library internals or patch behavior at the administration layer.
+*
+* ## Usage
+*
+* ```ts
+* import { getMobxAdministration } from "yummies/mobx";
+* ```
+*/
+/**
+* Returns the internal MobX administration object associated with an observable target.
+*
+* @param context Observable object instance.
+* @returns MobX administration internals stored under `$mobx`.
+*
+* @example
+* ```ts
+* const admin = getMobxAdministration(store);
+* admin.name_;
+* ```
+*
+* @example
+* ```ts
+* const values = getMobxAdministration(formState).values_;
+* ```
+*/
+var getMobxAdministration = (context) => context[$mobx];
+//#endregion
+//#region src/mobx/lazy-observe.ts
+/**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **Lazy subscriptions** tied to MobX observation: start work when the first reaction observes
+* tracked keys, stop when nothing listens anymore (optionally after a delay). Ideal for polling,
+* WebSocket feeds, or expensive caches that should idle when the UI is not mounted.
+*
+* ## Usage
+*
+* ```ts
+* import { lazyObserve } from "yummies/mobx";
+* ```
+*/
+/**
+* Starts side effects only while one or more MobX observables are being observed.
+*
+* When the first property becomes observed, `onStart` is called. When all tracked
+* properties become unobserved, `onEnd` is called with the value returned by
+* `onStart`. Cleanup can be delayed via `endDelay`.
+*
+* It uses MobX `onBecomeObserved` and `onBecomeUnobserved` hooks to perform
+* lazy subscription management.
+*
+* @template TMetaData Data returned from `onStart` and forwarded to `onEnd`.
+* @param config Configuration for tracked properties and lifecycle callbacks.
+* @returns Cleanup function that clears the tracked state and runs `onEnd`.
+*
+* @example
+* ```ts
+* const stop = lazyObserve({
+*   context: store,
+*   property: 'items',
+*   onStart: () => api.subscribe(),
+*   onEnd: (subscription) => subscription.unsubscribe(),
+* });
+* ```
+*
+* @example
+* ```ts
+* lazyObserve({
+*   property: [boxA, boxB],
+*   onStart: () => console.log('observed'),
+*   endDelay: 300,
+* });
+* ```
+*/
+var lazyObserve = ({ context, property, onStart, onEnd, endDelay = false }) => {
+	let timeoutId;
+	let metaData;
+	const observingProps = /* @__PURE__ */ new Set();
+	const properties = Array.isArray(property) ? property : [property];
+	const cleanup = () => {
+		observingProps.clear();
+		if (endDelay === false) {
+			onEnd?.(metaData, cleanup);
+			metaData = void 0;
+			return;
+		}
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+			timeoutId = void 0;
+		}
+		timeoutId = setTimeout(() => {
+			onEnd?.(metaData, cleanup);
+			timeoutId = void 0;
+			metaData = void 0;
+		}, endDelay);
+	};
+	const start = (property) => {
+		const isAlreadyObserving = observingProps.size > 0;
+		observingProps.add(property);
+		if (isAlreadyObserving) return;
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+			timeoutId = void 0;
+		}
+		metaData = onStart?.();
+	};
+	const stop = (property) => {
+		const isAlreadyNotObserving = !observingProps.size;
+		observingProps.delete(property);
+		const isObserving = observingProps.size > 0;
+		if (isAlreadyNotObserving || isObserving) return;
+		cleanup();
+	};
+	properties.forEach((property) => {
+		if (context) {
+			onBecomeObserved(context, property, () => start(property));
+			onBecomeUnobserved(context, property, () => stop(property));
+		} else {
+			onBecomeObserved(property, () => start(property));
+			onBecomeUnobserved(property, () => stop(property));
+		}
+	});
+	return cleanup;
 };
-//# sourceMappingURL=mobx.js.map
+//#endregion
+export { DeepObservableStruct, applyObservable, createEnhancedAtom, createRef, getMobxAdministration, isRef, lazyObserve, toRef };
+
+//# sourceMappingURL=mobx.js.map