react-deepwatch 1.0.0

package/index.d.ts

@@ -0,0 +1,218 @@
+import { ReactNode } from "react";
+import { PreserveOptions } from "./preserve";
+type WatchedComponentOptions = {
+    /**
+     * A fallback react tree to show when some `load(...)` statement in <strong>this</strong> component is loading.
+     * Use this if you have issues with screen flickering with <code><Suspense></code>.
+     */
+    fallback?: ReactNode;
+    /**
+     * Wraps this component in a {@link https://react.dev/reference/react/memo memo} to prevent unnecessary re-renders.
+     * This is enabled by default, since watchedComponents smartly tracks deep changes of used props and knows when to rerender.
+     * Disable this only in a mixed scenario with non-watchedComponents, where they rely on the old way of fully re-rendering the whole tree to pass deep model data (=more than using shallow, primitive props) to the leaves. So this component does not block these re-renders in the middle.
+     * <p>
+     *   Default: true
+     * </p>
+     */
+    memo?: boolean;
+    /**
+     * TODO
+     * Normally, everything that's **taken** from props, {@link useWatchedState} or {@link watched} or load(...)'s result will be returned, wrapped in a proxy that watches for modifications.
+     * So far, so good, this can handle all stuff that's happening inside your component, but the outside world does not have these proxies. For example, when a parent component is not a watchedComponent, and passed in an object (i.e. the model) into this component via props.
+     * Therefore this component can also **patch** these objects to make them watchable.
+     *
+     *
+     * <p>Default: true</p>
+     */
+    watchOutside?: boolean;
+    /**
+     * TODO: implement
+     * Preserves object instances in props by running the {@link preserve} function over the props (where the last value is memoized).
+     * <p>
+     * It's not recommended to enable this. Use only as a workaround when working with non-watched components where you have no control over. Better run {@link preserve} on the fetched source and keep a consistent-instance model in your app in the first place.
+     * </p>
+     *
+     * Note: Even with false, the `props` root object still keeps its instance (so it's save to watch `props.myFirstLevelProperty`).
+     * <p>
+     *     Default: false
+     * </p>
+     */
+    preserveProps?: boolean;
+};
+export declare function watchedComponent<PROPS extends object>(componentFn: (props: PROPS) => any, options?: WatchedComponentOptions): ((props: PROPS) => any) | import("react").MemoExoticComponent<(props: PROPS) => any>;
+type WatchedOptions = {
+    /**
+     * TODO: Implement
+     * Called, when a deep property was changed through the proxy.
+     */
+    onChange?: () => void;
+    /**
+     * TODO: Implement
+     * Called on a change to one of those properties, that were read-recorded in the component function (through the proxy of course).
+     * Reacts also on external changes / not done through the proxy.
+     */
+    onRecordedChange?: () => void;
+};
+export declare function useWatchedState(initial: object, options?: WatchedOptions): object;
+type LoadOptions = {
+    /**
+     * For {@link LoadOptions#preserve preserving} the result's object identity.
+     * Normally, this is obtained from the call stack information plus the {@link LoadOptions#key}.
+     *
+     * @see LoadOptions#key
+     */
+    id?: string | number | object;
+    /**
+     * Helps identifying the load(...) call from inside a loop for {@link LoadOptions#preserve preserving} the result's object identity.
+     * @see LoadOptions#id
+     */
+    key?: string | number;
+    /**
+     * If you specify a fallback, the component can be immediately rendered during loading.
+     * <p>
+     * undefined = undefined as fallback.
+     * </p>
+     */
+    fallback?: unknown;
+    /**
+     * Performance: Will return the old value from a previous load, while this is still loading. This causes less disturbance (i.e. triggering dependent loads) while switching back to the fallback and then to a real value again.
+     * <p>Best used in combination with {@link isLoading} and {@link fallback}</p>
+     * <p>Default: false</p>
+     */
+    silent?: boolean;
+    /**
+     * Performance: Set to false, to mark following `load(...)` statements do not depend on the result. I.e when used only for immediate rendering or passed to child components only. I.e. <div>{load(...)}/div> or `<MySubComponent param={load(...)} />`:
+     * Therefore, the following `load(...)` statements may not need a reload and can run in parallel.
+     * <p>
+     *     Default: true
+     *  </p>
+     */
+    critical?: boolean;
+    /**
+     * Poll after this amount of milliseconds
+     */
+    poll?: number;
+    /**
+     * {@link isLoading} Can filter for only the load(...) statements with this given name.
+     */
+    name?: string;
+    /**
+     *
+     * <p>Default: true</p>
+     */
+    preserve?: boolean | PreserveOptions;
+};
+type PollOptions = {
+    /**
+     * Interval in milliseconds
+     */
+    interval: number;
+    /**
+     * - true = interval means loaderFn-start to loaderFn-start
+     * - false = interval means loaderFn-end to loaderFn-start (the longer loaderFn takes, the more time till next re-poll)
+     * <p>
+     * Default: true
+     * </p>
+     */
+    fixedInterval?: boolean;
+};
+/**
+ * Runs the async loaderFn and re-renders, if its promise was resolved. Also re-renders and re-runs loaderFn, when some of its watched dependencies, used prior or instantly in the loaderFn, change.
+ * Puts the component into suspense while loading. Throws an error when loaderFn throws an error or its promise is rejected. Resumes from react-error-boundary automatically when loaderFn was re-run(because of the above).
+ * <p>
+ * {@link https://github.com/bogeeee/react-deepwatch#and-less-loading-code Usage}.
+ * </p>
+ * @param loaderFn
+ * @param options
+ */
+export declare function load<T, FALLBACK>(loaderFn: (oldResult?: T) => Promise<T>, options?: Omit<LoadOptions, "fallback">): T;
+/**
+ * Runs the async loaderFn and re-renders, if its promise was resolved. Also re-renders and re-runs loaderFn, when some of its watched dependencies, used prior or instantly in the loaderFn, change.
+ * Puts the component into suspense while loading. Throws an error when loaderFn throws an error or its promise is rejected. Resumes from react-error-boundary automatically when loaderFn was re-run(because of the above).
+ * <p>
+ * {@link https://github.com/bogeeee/react-deepwatch#and-less-loading-code Usage}.
+ * </p>
+ * @param loaderFn
+ * @param options
+ */
+export declare function load<T, FALLBACK>(loaderFn: (oldResult?: T) => Promise<T>, options: LoadOptions & {
+    fallback: FALLBACK;
+}): T | FALLBACK;
+/**
+ * Probe if a <code>load(...)</code> statement directly inside this watchedComponent is currently loading.
+ * Note: It's mostly needed to also specify a {@link LoadOptions#fallback} in the load statement's options to produce a valid render result while loading. Otherwise the whole component goes into suspense.
+ * <p>
+ * Example. This uses isLoading() to determine if the Dropdown list should be faded/transparent during while items are loading:
+ * <pre><code>
+ *     return  <select style={{opacity: isLoading("dropdownItems")?0.5:1}}>
+ *                 {load(() => fetchMyDropdownItems(), {name: "dropdownItems", fallback: ["loading items"]}).map(i => <option value="{i}">{i}</option>)}
+ *     </select>
+ * </code></pre>
+ * </p>
+ * <p>
+ * Caveat: You must not use this for a condition that cuts away a load(...) statement in the middle of your render code. This is because an extra render run is issued for isLoading() and the load(...) statements are re-matched by their order.
+ * </p>
+ * @param nameFilter When set, consider only those with the given {@link LoadOptions#name}. I.e. <code>load(..., {name: "myDropdownListEntries"})</code>
+ *
+ */
+export declare function isLoading(nameFilter?: string): boolean;
+/**
+ * Probe if a <code>load(...)</code> statement directly inside this watchedComponent failed.
+ * <p>
+ * Example:
+ * <pre><code>
+ *     if(loadFailed()) {
+ *          return <div>Load failed: {loadFailed().message}</div>;
+ *     }
+ *
+ *     return <div>My component content {load(...)} </div>
+ * </code></pre>
+ * </p>
+ * <p>
+ * Caveat: You must not use this for a condition that cuts away a load(...) statement in the middle of your render code. This is because an extra render run is issued for loadFailed() and the load(...) statements are re-matched by their order.
+ * </p>
+ * @param nameFilter When set, consider only those with the given {@link LoadOptions#name}. I.e. <code>load(..., {name: "myDropdownListEntries"})</code>
+ * @returns unknown The thrown value of the loaderFn or undefined if everything is ok.
+ */
+export declare function loadFailed(nameFilter?: string): unknown;
+/**
+ * Like {@link load}, but re-runs loaderFn regularly at the interval, specified in the options.
+ * <p>
+ * Example: <code>return <div>The current outside temperature is {  poll( async () => await fetchTemperatureFromServer(), {interval: 1000} )  }° </div></code> *
+ * </p>
+ * <p>
+ * Polling is still continued in recoverable error cases, when
+ * </p>
+ *  - loaderFn fails but your watchedComponent catches it and returns fine.
+ *  - Your watchedComponent returns with an error(because of this loaderFn or some other reason) and it is wrapped in a react-error-boundary.
+ *
+ * <p>
+ *     Note, that after the initial load, re-polling is done <strong>very silently</strong>. Meaning, there's no suspense / fallback / isLoading indicator involved.
+ * </p>
+ * @param loaderFn
+ * @param options
+ */
+export declare function poll<T, FALLBACK>(loaderFn: (oldResult?: T) => Promise<T>, options: Omit<LoadOptions, "fallback"> & PollOptions): T;
+/**
+ * Like {@link load}, but re-runs loaderFn regularly at the interval, specified in the options.
+ * <p>
+ * Example: <code>return <div>The current outside temperature is {  async poll( await () => fetchTemperatureFromServer(), {interval: 1000} )  }° </div></code> *
+ * </p>
+ * <p>
+ * Polling is still continued in recoverable error cases, when
+ * </p>
+ *  - loaderFn fails but your watchedComponent catches it and returns fine.
+ *  - Your watchedComponent returns with an error(because of this loaderFn or some other reason) and it is wrapped in a react-error-boundary.
+ *
+ * <p>
+ *     Note, that after the initial load, re-polling is done <strong>very silently</strong>. Meaning, there's no suspense / fallback / isLoading indicator involved.
+ * </p>
+ * @param loaderFn
+ * @param options
+ */
+export declare function poll<T, FALLBACK>(loaderFn: (oldResult?: T) => Promise<T>, options: LoadOptions & {
+    fallback: FALLBACK;
+} & PollOptions): T | FALLBACK;
+export declare function debug_tagComponent(name: string): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}