@homebound/form-state 2.11.0 → 2.14.0

package/README.md

@@ -1,3 +1,6 @@
+![npm](https://img.shields.io/npm/v/@homebound/form-state)
+[![CircleCI](https://circleci.com/gh/homebound-team/form-state.svg?style=svg)](https://circleci.com/gh/homebound-team/form-state)
+
 # form-state
 
 form-state is a headless form state management library, built on top of mobx.
@@ -7,14 +10,18 @@ It acts as a buffer between the canonical data/entity (i.e. the server-side data
 It also keeps track of low-level form UX details like:
 
 * Which form fields are dirty
-* Which forms fields are valid/invalid
-* Which forms fields are touched (i.e. don't show validation errors for untouched fields)
+* Which form fields are valid/invalid
+* Which form fields are touched (i.e. don't show validation errors for untouched fields)
 * Enabling/disabling buttons/form UX based on the overall form-wide state
 * Submitting the form should touch (validate) all fields
 * Auto-saving the form when appropriate (i.e. not on keystroke, but after blur/leaving the field)
-* Queue and debounce auto-saves if one is already in-flight
+* Queueing auto-saves if one is already in-flight
+  * Auto-saves in a table with per-row forms will serialize to avoid cross-child write conflicts on the backend
+* Not over-writing the user's WIP/actively-focused field when auto-saved data refreshes 
 * Building a wire payload that has only changed fields
-  * Handles children, i.e. a `author: { books: [...} }` will include only changed books if necessary
+  * `form.changedValue` will return the entity `id` + only changed fields to faciliate doing partial update APIs
+  * Supports collections of children, i.e. a `author: { books: [...} }` will include only changed books if necessary
+  * Child collections can be either exhausive (if any child changes, submit them all) or incremental (only include changed children), to match the backend endpoint's semantics
 
 # The Three Type/Shapes Mental Model
 

package/dist/FormStateApp.js

@@ -52,8 +52,8 @@ function FormStateApp() {
                                                     jsx_runtime_1.jsx("td", { children: formState.valid.toString() }, void 0),
                                                     jsx_runtime_1.jsx("td", { children: formState.dirty.toString() }, void 0)] }, void 0) }, void 0)] }), void 0),
                                 jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "touch", onClick: () => (formState.touched = !formState.touched) }, { children: "touch" }), void 0),
-                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "reset", onClick: () => formState.reset() }, { children: "reset" }), void 0),
-                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "save", onClick: () => formState.save() }, { children: "save" }), void 0),
+                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "revertChanges", onClick: () => formState.revertChanges() }, { children: "revert" }), void 0),
+                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "commitChanges", onClick: () => formState.commitChanges() }, { children: "commit" }), void 0),
                                         jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "set", onClick: () => formState.set({ firstName: "a2" }) }, { children: "set" }), void 0)] }, void 0)] }, void 0)] }), void 0) }), void 0));
         } }, void 0));
 }

package/dist/FormStateApp.test.js

@@ -12,7 +12,7 @@ describe("FormStateApp", () => {
         expect(r.firstName_dirty()).toHaveTextContent("true");
         react_1.fireEvent.blur(r.firstName());
         expect(r.firstName_touched()).toHaveTextContent("true");
-        rtl_utils_1.click(r.save);
+        rtl_utils_1.click(r.commitChanges);
         expect(r.firstName_dirty()).toHaveTextContent("false");
         expect(r.firstName_touched()).toHaveTextContent("false");
     });
@@ -20,7 +20,7 @@ describe("FormStateApp", () => {
         const r = await rtl_utils_1.render(jsx_runtime_1.jsx(FormStateApp_1.FormStateApp, {}, void 0));
         expect(r.firstName_original()).toHaveTextContent("a1");
         rtl_utils_1.click(r.set);
-        rtl_utils_1.click(r.save);
+        rtl_utils_1.click(r.commitChanges);
         expect(r.firstName_original()).toHaveTextContent("a2");
     });
 });

package/dist/config.d.ts

@@ -37,6 +37,8 @@ export declare type ValueFieldConfig<T, V> = {
     computed?: boolean;
     /** Marks a field as being initially read-only, i.e. `field.readOnly = true/false` can change this default. */
     readOnly?: boolean;
+    /** Marks an array field to be order agnostic when determining changed/dirty states */
+    strictOrder?: false;
 };
 /** Field configuration for list values, i.e. `U` is `Book` in a form with `books: Book[]`. */
 export declare type ListFieldConfig<T, U> = {

package/dist/fields/listField.js

@@ -184,16 +184,14 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
             _tick.value++;
             maybeAutoSave();
         },
-        reset() {
+        revertChanges() {
             if (originalCopy) {
                 this.set(originalCopy, { resetting: true });
-                this.rows.forEach((r) => r.reset());
+                this.rows.forEach((r) => r.revertChanges());
             }
         },
-        save() {
-            this.rows.forEach((r) => {
-                r.save();
-            });
+        commitChanges() {
+            this.rows.forEach((r) => r.commitChanges());
             originalCopy = [...(parentInstance[key] || [])];
             _tick.value++;
         },

package/dist/fields/objectField.js

@@ -29,11 +29,12 @@ function newObjectState(config, parentState, parentListState, instance, key, may
         return proxy;
     }
     const fieldStates = Object.entries(config).map(([_key, _config]) => {
+        var _a;
         const key = _key;
         const config = _config;
         let field;
         if (config.type === "value") {
-            field = valueField_1.newValueFieldState(instance, getObjectState, key, config.rules || [], config.isIdKey || key === "id", config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, maybeAutoSave);
+            field = valueField_1.newValueFieldState(instance, getObjectState, key, config.rules || [], config.isIdKey || key === "id", config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, (_a = config.strictOrder) !== null && _a !== void 0 ? _a : true, maybeAutoSave);
         }
         else if (config.type === "list") {
             field = listField_1.newListFieldState(instance, getObjectState, key, config.rules || [], config, config.config, maybeAutoSave);
@@ -132,12 +133,12 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             });
         },
         // Resets all fields back to their original values
-        reset() {
-            getFields(this).forEach((f) => f.reset());
+        revertChanges() {
+            getFields(this).forEach((f) => f.revertChanges());
         },
         // Saves all current values into _originalValue
-        save() {
-            getFields(this).forEach((f) => f.save());
+        commitChanges() {
+            getFields(this).forEach((f) => f.commitChanges());
         },
         // Create a result that is only populated with changed keys
         get changedValue() {

package/dist/fields/valueField.d.ts

@@ -33,9 +33,9 @@ export interface FieldState<T, V> {
     maybeAutoSave(): void;
     set(value: V, opts?: SetOpts): void;
     /** Reverts back to the original value and resets dirty/touched. */
-    reset(): void;
+    revertChanges(): void;
     /** Accepts the current changed value (if any) as the original and resets dirty/touched. */
-    save(): void;
+    commitChanges(): void;
 }
 /** Public options for our `set` command. */
 export interface SetOpts {
@@ -56,4 +56,4 @@ export interface FieldStateInternal<T, V> extends FieldState<T, V> {
     _isReadOnlyKey: boolean;
     _focused: boolean;
 }
-export declare function newValueFieldState<T, K extends keyof T>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T, T[K] | null | undefined>[], isIdKey: boolean, isDeleteKey: boolean, isReadOnlyKey: boolean, computed: boolean, readOnly: boolean, maybeAutoSave: () => void): FieldState<T, T[K] | null | undefined>;
+export declare function newValueFieldState<T, K extends keyof T>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T, T[K] | null | undefined>[], isIdKey: boolean, isDeleteKey: boolean, isReadOnlyKey: boolean, computed: boolean, readOnly: boolean, strictOrder: boolean, maybeAutoSave: () => void): FieldState<T, T[K] | null | undefined>;

package/dist/fields/valueField.js

@@ -5,7 +5,7 @@ const is_plain_object_1 = require("is-plain-object");
 const mobx_1 = require("mobx");
 const rules_1 = require("../rules");
 const utils_1 = require("../utils");
-function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, maybeAutoSave) {
+function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, strictOrder, maybeAutoSave) {
     // keep a copy here for reference equality
     const value = parentInstance[key];
     let _originalValue = value === null ? undefined : is_plain_object_1.isPlainObject(value) ? mobx_1.toJS(value) : value;
@@ -35,7 +35,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             this.set(v);
         },
         get dirty() {
-            return !utils_1.areEqual(this.originalValue, this.value);
+            return !utils_1.areEqual(this.originalValue, this.value, strictOrder);
         },
         /** Returns whether this field is readOnly, although if our parent is readOnly then it trumps. */
         get readOnly() {
@@ -106,7 +106,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             const coerceEmptyList = value && value instanceof Array && value.length === 0 && utils_1.isEmpty(this.originalValue);
             const newValue = keepNull ? null : utils_1.isEmpty(value) || coerceEmptyList ? undefined : value;
             // Set the value on our parent object
-            const changed = !utils_1.areEqual(newValue, this.value);
+            const changed = !utils_1.areEqual(newValue, this.value, strictOrder);
             parentInstance[key] = newValue;
             _tick.value++;
             if (opts.refreshing) {
@@ -118,13 +118,13 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
                 this.maybeAutoSave();
             }
         },
-        reset() {
+        revertChanges() {
             if (!computed) {
                 this.set(this.originalValue, { resetting: true });
             }
             this.touched = false;
         },
-        save() {
+        commitChanges() {
             if (is_plain_object_1.isPlainObject(this.originalValue)) {
                 this.originalValue = mobx_1.toJS(this.value);
             }

package/dist/formState.test.js

@@ -452,7 +452,7 @@ describe("formState", () => {
         a1.set({ firstName: "first" });
         expect(maybeAutoSave).toBeCalledTimes(1);
         // When we reset
-        a1.reset();
+        a1.revertChanges();
         // We don't call blur again
         expect(maybeAutoSave).toBeCalledTimes(1);
     });
@@ -487,6 +487,24 @@ describe("formState", () => {
         a1.favoriteColors.set([]);
         expect(a1.dirty).toBeFalsy();
     });
+    it("can evaluate arrays to be equal even if order of options are different from original when strictOrder = false", () => {
+        // Given an array field value where we define `strictOrder` as false
+        const a1 = objectField_1.createObjectState({ favoriteColors: { type: "value", strictOrder: false } }, { favoriteColors: [formStateDomain_1.Color.Red, formStateDomain_1.Color.Blue] });
+        expect(a1.favoriteColors.dirty).toBeFalsy();
+        // When changing the order of the values
+        a1.favoriteColors.set([formStateDomain_1.Color.Blue, formStateDomain_1.Color.Red]);
+        // Then expect the field to not be dirty
+        expect(a1.dirty).toBeFalsy();
+    });
+    it("evaluates arrays to be equal based on order by default", () => {
+        // Given an array field value
+        const a1 = objectField_1.createObjectState({ favoriteColors: { type: "value" } }, { favoriteColors: [formStateDomain_1.Color.Red, formStateDomain_1.Color.Blue] });
+        expect(a1.favoriteColors.dirty).toBeFalsy();
+        // When we change the order of the values
+        a1.favoriteColors.set([formStateDomain_1.Color.Blue, formStateDomain_1.Color.Red]);
+        // Then the field should be dirty
+        expect(a1.dirty).toBeTruthy();
+    });
     it("knows originally unset fields are dirty", () => {
         // Given firstName is purposefully not set when originally initialized
         const a1 = createAuthorInputState({});
@@ -541,7 +559,7 @@ describe("formState", () => {
         a1.books.add({ title: "b3" });
         expect(a1.books.touched).toEqual(true);
         expect(a1.dirty).toBeTruthy();
-        a1.reset();
+        a1.revertChanges();
         expect(a1.firstName.value).toBe("a1");
         expect(a1.firstName.touched).toBeFalsy();
         expect(a1.lastName.value).toBe("aL1");
@@ -577,7 +595,7 @@ describe("formState", () => {
         // And the "readOnly=true" operation has "beat" the reset operation
         a1.readOnly = true;
         // When we reset
-        a1.reset();
+        a1.revertChanges();
         // Then it still works
         expect(a1.firstName.value).toBe("a1");
         expect(a1.firstName.touched).toBeFalsy();
@@ -607,15 +625,15 @@ describe("formState", () => {
         a1.books.rows[1].set({ title: "bb3" });
         // verify ValueFieldState is dirty, then save, then no longer dirty.
         expect(a1.firstName.dirty).toBeTruthy();
-        a1.firstName.save();
+        a1.firstName.commitChanges();
         expect(a1.firstName.dirty).toBeFalsy();
         // verify ListFieldState is dirty, then save, then no longer dirty.
         expect(a1.books.dirty).toBeTruthy();
-        a1.books.save();
+        a1.books.commitChanges();
         expect(a1.books.dirty).toBeFalsy();
         // Verify the remaining form is still dirty
         expect(a1.dirty).toBeTruthy();
-        a1.save();
+        a1.commitChanges();
         // Verify after save the whole form is no longer dirty.
         expect(a1.dirty).toBeFalsy();
     });
@@ -839,7 +857,7 @@ describe("formState", () => {
         expect(a.books.rows[1].readOnly).toBeFalsy();
         expect(a.books.rows[1].title.readOnly).toBeFalsy();
         // And reset does not blow up
-        a.reset();
+        a.revertChanges();
     });
     it("can set nested values when original null", () => {
         const a = createAuthorWithAddressInputState({ address: null });
@@ -894,7 +912,7 @@ describe("formState", () => {
         expect(formState.fullName.value).toEqual("first last");
         formState.firstName.value = "change";
         expect(formState.fullName.value).toEqual("change last");
-        formState.reset();
+        formState.revertChanges();
         expect(formState.firstName.value).toEqual("first");
     });
     it("can set computeds that have setters", () => {
@@ -907,7 +925,7 @@ describe("formState", () => {
         expect(formState.firstName.value).toEqual("Bob");
         formState.fullName.set("Fred Smith");
         expect(formState.firstName.value).toEqual("Fred");
-        formState.reset();
+        formState.revertChanges();
         expect(formState.firstName.value).toEqual("first");
     });
     it("can mark fields as read only", () => {
@@ -920,7 +938,7 @@ describe("formState", () => {
         expect(formState.fullName.readOnly).toEqual(true);
         formState.firstName.value = "change";
         expect(formState.fullName.value).toEqual("change last");
-        formState.reset();
+        formState.revertChanges();
         expect(formState.firstName.value).toEqual("first");
     });
     it("lets rules validate against other fields", () => {
@@ -1300,7 +1318,7 @@ describe("formState", () => {
         // Then the list state is dirty
         expect(a1.books.dirty).toBeTruthy();
         // When saving the form state
-        a1.save();
+        a1.commitChanges();
         // Then the list is no longer dirty
         expect(a1.books.dirty).toBeFalsy();
         // When adding a new book

package/dist/useFormState.d.ts

@@ -1,5 +1,20 @@
 import { ObjectConfig } from "./config";
 import { ObjectState } from "./fields/objectField";
+export declare type Query<I> = {
+    data: I;
+    loading: boolean;
+    error?: any;
+};
+export declare type InputAndMap<T, I> = {
+    input: I;
+    map: (input: Exclude<I, null | undefined>) => T;
+    ifUndefined?: T;
+};
+export declare type QueryAndMap<T, I> = {
+    query: Query<I>;
+    map: (input: Exclude<I, null | undefined>) => T;
+    ifUndefined?: T;
+};
 export declare type UseFormStateOpts<T, I> = {
     /** The form configuration, should be a module-level const or useMemo'd. */
     config: ObjectConfig<T>;
@@ -20,11 +35,7 @@ export declare type UseFormStateOpts<T, I> = {
      * only call `init.map` if it's set, otherwise we'll use `init.ifDefined` or `{}`, saving you
      * from having to null check within your `init.map` function.
      */
-    init?: T | {
-        input: I;
-        map: (input: Exclude<I, null | undefined>) => T;
-        ifUndefined?: T;
-    };
+    init?: T | InputAndMap<T, I> | QueryAndMap<T, I>;
     /**
      * A hook to add custom, cross-field validation rules that can be difficult to setup directly in the config DSL.
      *
@@ -33,6 +44,13 @@ export declare type UseFormStateOpts<T, I> = {
     addRules?: (state: ObjectState<T>) => void;
     /** Whether the form should be read only, when changed it won't re-create the whole form. */
     readOnly?: boolean;
+    /**
+     * Whether the form is loading.
+     *
+     * Note that we also will infer loading from `init.input === undefined` or `init.query.loading`,
+     * so you only need to set this directly if you're not using either of those conventions.
+     */
+    loading?: boolean;
     /**
      * Fired when the form should auto-save, i.e. after a) blur and b) all fields are valid.
      *

package/dist/useFormState.js

@@ -16,7 +16,7 @@ let pendingAutoSave = false;
  * Creates a formState instance for editing in a form.
  */
 function useFormState(opts) {
-    const { config, init, addRules, readOnly = false, autoSave } = opts;
+    const { config, init, addRules, readOnly = false, loading, autoSave } = opts;
     // Use a ref so our memo'ized `onBlur` always see the latest value
     const autoSaveRef = react_1.useRef(autoSave);
     autoSaveRef.current = autoSave;
@@ -25,7 +25,7 @@ function useFormState(opts) {
     const [firstInitValue] = react_1.useState(() => utils_1.initValue(config, init));
     const isWrappingMobxProxy = !is_plain_object_1.isPlainObject(firstInitValue);
     // If they're using init.input, useMemo on it (and it might be an array), otherwise allow the identity of init be unstable
-    const dep = init && "input" in init && "map" in init ? (Array.isArray(init.input) ? init.input : [init.input]) : [];
+    const dep = utils_1.isInput(init) ? makeArray(init.input) : utils_1.isQuery(init) ? [init.query.data, init.query.loading] : [];
     const form = react_1.useMemo(() => {
         function maybeAutoSave() {
             if (isAutoSaving === "in-flight") {
@@ -62,9 +62,7 @@ function useFormState(opts) {
         const value = firstRunRef.current ? firstInitValue : utils_1.initValue(config, init);
         const form = objectField_1.createObjectState(config, value, { maybeAutoSave });
         form.readOnly = readOnly;
-        if (init && "input" in init && !("ifUndefined" in init)) {
-            form.loading = init.input === undefined;
-        }
+        setLoading(form, opts);
         // The identity of `addRules` is not stable, but assume that it is for better UX.
         (addRules || (() => { }))(form);
         firstRunRef.current = true;
@@ -83,15 +81,34 @@ function useFormState(opts) {
             firstRunRef.current = false;
             return;
         }
-        if (init && "input" in init && !("ifUndefined" in init)) {
-            form.loading = init.input === undefined;
-        }
+        setLoading(form, opts);
         form.set(utils_1.initValue(config, init), { refreshing: true });
     }, [form, ...dep]);
     // Use useEffect so that we don't touch the form.init proxy during a render
     react_1.useEffect(() => {
         form.readOnly = readOnly;
-    }, [form, readOnly]);
+        if (loading !== undefined) {
+            form.loading = loading;
+        }
+    }, [form, readOnly, loading]);
     return form;
 }
 exports.useFormState = useFormState;
+function setLoading(form, opts) {
+    const { loading, init } = opts;
+    if (loading !== undefined) {
+        // Prefer the explicit/top-level opts.loading if it's set
+        form.loading = loading;
+    }
+    else if (utils_1.isInput(init) && !init.ifUndefined) {
+        // Otherwise, check for `init.input`
+        form.loading = init.input === undefined;
+    }
+    else if (utils_1.isQuery(init)) {
+        // Or `query.loading`
+        form.loading = init.query.loading;
+    }
+}
+function makeArray(input) {
+    return Array.isArray(input) ? input : [input];
+}

package/dist/useFormState.test.js

@@ -454,6 +454,21 @@ describe("useFormState", () => {
         expect(autoSaveStub).toBeCalledTimes(1);
         expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "first", lastName: "first" });
     });
+    it("sets loading if opts.loading is true", async () => {
+        const config = { firstName: { type: "value" } };
+        function TestComponent({ loading }) {
+            const form = useFormState_1.useFormState({ config, loading });
+            return jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "loading" }, { children: String(form.loading) }), void 0) }, void 0);
+        }
+        // And we initially pass in `init.query.loading: true`
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { loading: true }, void 0));
+        // Then the form is marked as loading
+        expect(r.loading()).toHaveTextContent("true");
+        // And when the query is not loading
+        await r.rerender(jsx_runtime_1.jsx(TestComponent, { loading: false }, void 0));
+        // Then the form is marked as not loading
+        expect(r.loading()).toHaveTextContent("false");
+    });
     it("sets loading if input.data is undefined", async () => {
         const config = { firstName: { type: "value" } };
         function TestComponent({ data }) {
@@ -464,11 +479,26 @@ describe("useFormState", () => {
         const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { data: undefined }, void 0));
         // Then the form is marked as loading
         expect(r.loading()).toHaveTextContent("true");
-        // And when the data is loading
+        // And when the data is no longer undefined
         await r.rerender(jsx_runtime_1.jsx(TestComponent, { data: { firstName: "first" } }, void 0));
         // Then the form is marked as not loading
         expect(r.loading()).toHaveTextContent("false");
     });
+    it("sets loading if query.loading is true", async () => {
+        const config = { firstName: { type: "value" } };
+        function TestComponent({ loading, data }) {
+            const form = useFormState_1.useFormState({ config, init: { query: { data, loading, error: null }, map: (d) => d } });
+            return jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "loading" }, { children: String(form.loading) }), void 0) }, void 0);
+        }
+        // And we initially pass in `init.query.loading: true`
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { loading: true, data: undefined }, void 0));
+        // Then the form is marked as loading
+        expect(r.loading()).toHaveTextContent("true");
+        // And when the query is not loading
+        await r.rerender(jsx_runtime_1.jsx(TestComponent, { loading: false, data: { firstName: "first" } }, void 0));
+        // Then the form is marked as not loading
+        expect(r.loading()).toHaveTextContent("false");
+    });
 });
 const authorConfig = {
     id: { type: "value" },

package/dist/utils.d.ts

@@ -1,4 +1,5 @@
 import { ObjectConfig } from "./config";
+import { InputAndMap, QueryAndMap, UseFormStateOpts } from "./useFormState";
 export declare type Builtin = Date | Function | Uint8Array | string | number | boolean;
 export declare type Primitive = undefined | null | boolean | string | number | Function | Date | {
     toJSON(): any;
@@ -11,6 +12,8 @@ export declare function fail(message?: string): never;
 export declare function assertNever(x: never): never;
 /** Introspects the `init` prop to see if has a `map` function/etc. and returns the form value. */
 export declare function initValue<T>(config: ObjectConfig<T>, init: any): T;
+export declare function isInput<T, I>(init: UseFormStateOpts<T, I>["init"]): init is InputAndMap<T, I>;
+export declare function isQuery<T, I>(init: UseFormStateOpts<T, I>["init"]): init is QueryAndMap<T, I>;
 /**
  * Picks ony fields out of `instance` that are in the `formConfig`.
  *
@@ -34,7 +37,7 @@ export declare function isEmpty(value: any): boolean;
  * - objects that implement `toJSON`
  *
  */
-export declare function areEqual<T>(a?: T, b?: T): boolean;
+export declare function areEqual<T>(a?: T, b?: T, strictOrder?: boolean): boolean;
 export declare function hasToJSON(o?: unknown): o is {
     toJSON(): void;
 };

package/dist/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasToJSON = exports.areEqual = exports.isEmpty = exports.isNotUndefined = exports.pickFields = exports.initValue = exports.assertNever = exports.fail = void 0;
+exports.hasToJSON = exports.areEqual = exports.isEmpty = exports.isNotUndefined = exports.pickFields = exports.isQuery = exports.isInput = exports.initValue = exports.assertNever = exports.fail = void 0;
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
 const is_plain_object_1 = require("is-plain-object");
 const mobx_1 = require("mobx");
@@ -17,14 +17,27 @@ function assertNever(x) {
 exports.assertNever = assertNever;
 /** Introspects the `init` prop to see if has a `map` function/etc. and returns the form value. */
 function initValue(config, init) {
-    const initValue = init && "input" in init && "map" in init
-        ? init.input
-            ? init.map(init.input)
-            : init.ifUndefined || {}
-        : init || {};
-    return pickFields(config, initValue);
+    let value;
+    if (isInput(init)) {
+        value = init.input ? init.map(init.input) : init.ifUndefined;
+    }
+    else if (isQuery(init)) {
+        value = init.query.data ? init.map(init.query.data) : init.ifUndefined;
+    }
+    else {
+        value = init;
+    }
+    return pickFields(config, value !== null && value !== void 0 ? value : {});
 }
 exports.initValue = initValue;
+function isInput(init) {
+    return !!init && "input" in init && "map" in init;
+}
+exports.isInput = isInput;
+function isQuery(init) {
+    return !!init && "query" in init && "map" in init;
+}
+exports.isQuery = isQuery;
 /**
  * Picks ony fields out of `instance` that are in the `formConfig`.
  *
@@ -89,7 +102,7 @@ exports.isEmpty = isEmpty;
  * - objects that implement `toJSON`
  *
  */
-function areEqual(a, b) {
+function areEqual(a, b, strictOrder) {
     if (is_plain_object_1.isPlainObject(a)) {
         return fast_deep_equal_1.default(mobx_1.toJS(a), mobx_1.toJS(b));
     }
@@ -99,7 +112,12 @@ function areEqual(a, b) {
         return fast_deep_equal_1.default(a1, b1);
     }
     if (a && b && a instanceof Array && b instanceof Array) {
-        return fast_deep_equal_1.default(a, b);
+        if (strictOrder !== false) {
+            return fast_deep_equal_1.default(a, b);
+        }
+        if (a.length !== b.length)
+            return false;
+        return a.every((a1) => b.some((b1) => fast_deep_equal_1.default(a1, b1)));
     }
     return a === b;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/form-state",
-  "version": "2.11.0",
+  "version": "2.14.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",