@homebound/form-state 2.4.0 → 2.5.2

package/dist/FormStateApp.js

@@ -20,7 +20,7 @@ function FormStateApp() {
                 return state.firstName.value === state.lastName.value ? "Last name cannot equal first name" : undefined;
             });
         },
-        autoSave() {
+        async autoSave() {
             console.log("saving", formState.changedValue);
         },
     });

package/dist/formState.js

@@ -261,13 +261,11 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             this._focused = true;
         },
         blur() {
-            // Now that the user is done editing the field, we sneak in some trim logic
-            if (this._focused) {
-                this.maybeAutoSave();
-            }
+            this.maybeAutoSave();
             this._focused = false;
         },
         maybeAutoSave() {
+            // Now that the user is done editing the field (note maybe w/o blurring, i.e. if they hit enter), we sneak in some trim logic
             this.maybeTrim();
             // touched is readonly, but we're allowed to change it
             this.touched = true;
@@ -514,7 +512,7 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
             this.rows.forEach((r) => {
                 r.save();
             });
-            originalCopy = parentInstance[key];
+            originalCopy = [...(parentInstance[key] || [])];
             _tick.value++;
         },
         ensureSet() {

package/dist/formState.test.js

@@ -1145,6 +1145,23 @@ describe("formState", () => {
         expect(formState.books.rows[1].isNewEntity).toBeTruthy();
         expect(formState.books.isNewEntity).toBeFalsy();
     });
+    it("can properly evaluate dirty lists after calling 'save'", () => {
+        // Given an empty list state
+        const a1 = createAuthorInputState({ books: [] });
+        expect(a1.books.dirty).toBeFalsy();
+        // When adding a book
+        a1.books.add({ title: "t2" });
+        // Then the list state is dirty
+        expect(a1.books.dirty).toBeTruthy();
+        // When saving the form state
+        a1.save();
+        // Then the list is no longer dirty
+        expect(a1.books.dirty).toBeFalsy();
+        // When adding a new book
+        a1.books.add({ title: "t3" });
+        // The list is again dirty
+        expect(a1.books.dirty).toBeTruthy();
+    });
 });
 class ObservableObject {
     constructor() {

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { createObjectState, FieldState, ListFieldState, ObjectConfig, ObjectState, required, Rule, } from "./formState";
 export { useFormState } from "./useFormState";
+export { useFormStates } from "./useFormStates";

package/dist/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFormState = exports.required = exports.createObjectState = void 0;
+exports.useFormStates = exports.useFormState = exports.required = exports.createObjectState = void 0;
 var formState_1 = require("./formState");
 Object.defineProperty(exports, "createObjectState", { enumerable: true, get: function () { return formState_1.createObjectState; } });
 Object.defineProperty(exports, "required", { enumerable: true, get: function () { return formState_1.required; } });
 var useFormState_1 = require("./useFormState");
 Object.defineProperty(exports, "useFormState", { enumerable: true, get: function () { return useFormState_1.useFormState; } });
+var useFormStates_1 = require("./useFormStates");
+Object.defineProperty(exports, "useFormStates", { enumerable: true, get: function () { return useFormStates_1.useFormStates; } });

package/dist/setupTests.js

@@ -4,5 +4,10 @@ require("@testing-library/jest-dom");
 const mobx_1 = require("mobx");
 // formState doesn't use actions
 mobx_1.configure({ enforceActions: "never" });
-beforeAll(() => jest.useFakeTimers("modern"));
-afterAll(() => jest.useRealTimers());
+beforeEach(() => {
+    jest.useFakeTimers("modern");
+});
+afterEach(() => {
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+});

package/dist/useFormState.d.ts

@@ -37,21 +37,9 @@ export declare type UseFormStateOpts<T, I> = {
      *
      * Does not need to be stable/useMemo'd.
      */
-    autoSave?: (state: ObjectState<T>) => void;
+    autoSave?: (state: ObjectState<T>) => Promise<unknown>;
 };
 /**
  * Creates a formState instance for editing in a form.
  */
 export declare function useFormState<T, I>(opts: UseFormStateOpts<T, I>): ObjectState<T>;
-/**
- * Picks ony fields out of `instance` that are in the `formConfig`.
- *
- * This is useful for creating a form input from a GraphQL query result,
- * but ignoring extra data in the query that we don't want/need in the form.
- *
- * (Especially because the form.value will become our mutation's input type
- * that goes on the wire, we don't want superfluous data in it.)
- */
-export declare function pickFields<T, I>(formConfig: ObjectConfig<T>, instance: I): {
-    [K in keyof T]: K extends keyof I ? I[K] : never;
-};

package/dist/useFormState.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pickFields = exports.useFormState = void 0;
+exports.useFormState = void 0;
 const is_plain_object_1 = require("is-plain-object");
-const mobx_1 = require("mobx");
 const react_1 = require("react");
 const formState_1 = require("./formState");
 const utils_1 = require("./utils");
@@ -10,6 +9,10 @@ const utils_1 = require("./utils");
 // in some business logic right before their GraphQL mutation call, ignore it
 // so that we don't infinite loop.
 let isAutoSaving = false;
+// `pendingAutoSave` is a flag for determining if we need to immediately call `maybeAutoSave` again after the initial Promise finishes
+// This could happen if a field triggers auto-save while another field's auto-save is already in progress.
+let pendingAutoSave = false;
+let timerId;
 /**
  * Creates a formState instance for editing in a form.
  */
@@ -20,28 +23,47 @@ function useFormState(opts) {
     autoSaveRef.current = autoSave;
     const firstRunRef = react_1.useRef(true);
     // This is a little weird, but we need to know ahead of time, before the form useMemo, if we're working with classes/mobx proxies
-    const [firstInitValue] = react_1.useState(() => initValue(config, init));
+    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 form = react_1.useMemo(() => {
         function maybeAutoSave() {
+            if (isAutoSaving === "in-flight") {
+                pendingAutoSave = true;
+            }
+            else if (isAutoSaving === "queued") {
+                return;
+            }
             // Don't use canSave() because we don't want to set touched for all the fields
             if (autoSaveRef.current && form.dirty && form.valid && !isAutoSaving) {
-                try {
-                    isAutoSaving = true;
-                    autoSaveRef.current(form);
-                }
-                finally {
-                    isAutoSaving = false;
-                }
+                isAutoSaving = "queued";
+                // We use setTimeout as a cheap way to wait until the end of the current event listener
+                timerId = setTimeout(async () => {
+                    try {
+                        // We technically don't flip to in-flight until after the call in case the
+                        // user's autoSave function itself wants to call a .set.
+                        const promise = autoSaveRef.current(form);
+                        isAutoSaving = "in-flight";
+                        await promise;
+                    }
+                    finally {
+                        isAutoSaving = false;
+                        if (pendingAutoSave) {
+                            pendingAutoSave = false;
+                            // Push out the follow-up by 1 tick to allow refreshes to happen to potentially
+                            // un-dirty the just-saved data (e.g. if we run right away, the caller's maybeAutoSave
+                            // will see a form.changedValue that thinks the just-saved data is still dirty).
+                            setTimeout(maybeAutoSave, 0);
+                        }
+                    }
+                }, 0);
             }
         }
-        const value = firstRunRef.current ? firstInitValue : initValue(config, init);
+        const value = firstRunRef.current ? firstInitValue : utils_1.initValue(config, init);
         const form = formState_1.createObjectState(config, value, { maybeAutoSave });
         form.readOnly = readOnly;
         // The identity of `addRules` is not stable, but assume that it is for better UX.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
         (addRules || (() => { }))(form);
         firstRunRef.current = true;
         return form;
@@ -59,7 +81,7 @@ function useFormState(opts) {
             firstRunRef.current = false;
             return;
         }
-        form.set(initValue(config, init), { refreshing: true });
+        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(() => {
@@ -68,59 +90,3 @@ function useFormState(opts) {
     return form;
 }
 exports.useFormState = useFormState;
-/** 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);
-}
-/**
- * Picks ony fields out of `instance` that are in the `formConfig`.
- *
- * This is useful for creating a form input from a GraphQL query result,
- * but ignoring extra data in the query that we don't want/need in the form.
- *
- * (Especially because the form.value will become our mutation's input type
- * that goes on the wire, we don't want superfluous data in it.)
- */
-function pickFields(formConfig, instance) {
-    // If the caller is using classes, i.e. with their own custom observable behavior, then just use as-is
-    if (!is_plain_object_1.isPlainObject(instance)) {
-        return instance;
-    }
-    return Object.fromEntries(Object.entries(formConfig).map(([key, _keyConfig]) => {
-        const keyConfig = _keyConfig;
-        const value = instance[key];
-        if (keyConfig.type === "object") {
-            if (value) {
-                return [key, pickFields(keyConfig.config, value)];
-            }
-            else {
-                return [key, value];
-            }
-        }
-        else if (keyConfig.type === "list") {
-            if (mobx_1.isObservable(value)) {
-                // If we hit an observable array, leave it as the existing proxy so the our
-                // ListFieldState will react to changes in the original array.
-                return [key, value];
-            }
-            else if (value) {
-                return [key, value.map((u) => pickFields(keyConfig.config, u))];
-            }
-            else {
-                return [key, value];
-            }
-        }
-        else if (keyConfig.type === "value") {
-            return [key, value];
-        }
-        else {
-            return utils_1.assertNever(keyConfig);
-        }
-    }));
-}
-exports.pickFields = pickFields;

package/dist/useFormState.test.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const rtl_utils_1 = require("@homebound/rtl-utils");
-const mobx_1 = require("mobx");
+const react_1 = require("@testing-library/react");
 const mobx_react_1 = require("mobx-react");
-const react_1 = require("react");
+const react_2 = require("react");
 const formState_1 = require("./formState");
 const useFormState_1 = require("./useFormState");
 describe("useFormState", () => {
@@ -27,7 +27,7 @@ describe("useFormState", () => {
     it("memoizes on init.input being an array", async () => {
         const config = { firstName: { type: "value" } };
         function TestComponent() {
-            const [, setTick] = react_1.useState(0);
+            const [, setTick] = react_2.useState(0);
             const form = useFormState_1.useFormState({
                 config,
                 init: { input: ["a", "b"], map: ([a, b]) => ({ firstName: a + b }) },
@@ -86,7 +86,7 @@ describe("useFormState", () => {
     it("uses init if set as a value", async () => {
         const config = { firstName: { type: "value" } };
         function TestComponent() {
-            const [, setTick] = react_1.useState(0);
+            const [, setTick] = react_2.useState(0);
             const form = useFormState_1.useFormState({
                 config,
                 // That's using a raw init value
@@ -154,7 +154,7 @@ describe("useFormState", () => {
                 ],
             };
             // And we start out with data1
-            const [data, setData] = react_1.useState(data1);
+            const [data, setData] = react_2.useState(data1);
             const form = useFormState_1.useFormState({ config, init: { input: data, map: (d) => d } });
             function makeLocalChanges() {
                 form.firstName.value = "local";
@@ -230,7 +230,7 @@ describe("useFormState", () => {
                 books: [{ title: "a2" }],
             };
             // And we start out with data1
-            const [data, setData] = react_1.useState(data1);
+            const [data, setData] = react_2.useState(data1);
             const form = useFormState_1.useFormState({
                 config,
                 init: { input: data, map: (d) => d },
@@ -271,9 +271,9 @@ describe("useFormState", () => {
             const data1 = { firstName: "f1", lastName: "l1" };
             const data2 = { firstName: "f2", lastName: "l2" };
             // And we start out with data1
-            const [data, setData] = react_1.useState(data1);
-            const author = react_1.useMemo(() => new AuthorRow(data.firstName, data.lastName), [data]);
-            const config = react_1.useMemo(() => ({
+            const [data, setData] = react_2.useState(data1);
+            const author = react_2.useMemo(() => new AuthorRow(data.firstName, data.lastName), [data]);
+            const config = react_2.useMemo(() => ({
                 firstName: { type: "value" },
                 lastName: { type: "value" },
                 fullName: { type: "value", computed: true },
@@ -297,7 +297,7 @@ describe("useFormState", () => {
         // Given a component
         function TestComponent() {
             // When the data is initially undefined
-            const [data, setData] = react_1.useState();
+            const [data, setData] = react_2.useState();
             const data2 = { books: [{ title: "Title 1" }] };
             const form = useFormState_1.useFormState({
                 config: authorWithBooksConfig,
@@ -314,16 +314,16 @@ describe("useFormState", () => {
         // When the data/child is now available
         rtl_utils_1.click(r.refreshData);
         // And the field is blurred
-        rtl_utils_1.click(r.blurBookOne);
+        await rtl_utils_1.clickAndWait(r.blurBookOne);
         // Then we don't auto-save because nothing has changed
         expect(autoSave).toBeCalledTimes(0);
         // And when adding a new book
-        rtl_utils_1.click(r.add);
+        await rtl_utils_1.clickAndWait(r.add);
         // We autoSave the new row right away (because we don't have any validation rules
         // that say the new row can't be empty)
         expect(autoSave).toBeCalledTimes(1);
         // And the new book is blurred
-        rtl_utils_1.click(r.blurBookTwo);
+        await rtl_utils_1.clickAndWait(r.blurBookTwo);
         // Then we auto save again
         expect(autoSave).toBeCalledTimes(2);
     });
@@ -337,7 +337,7 @@ describe("useFormState", () => {
                 config,
                 init: data,
                 // And there is reactive business logic in the `autoSave` method
-                autoSave(state) {
+                async autoSave(state) {
                     state.lastName.set("l2");
                     autoSaves++;
                 },
@@ -346,79 +346,84 @@ describe("useFormState", () => {
         }
         const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
         // When we change firstName
-        rtl_utils_1.click(r.setFirst);
+        await rtl_utils_1.clickAndWait(r.setFirst);
         // When autoSave didn't infinite loop
         expect(autoSaves).toEqual(1);
     });
-    describe("pickFields", () => {
-        it("can pick a value field", () => {
-            const a = useFormState_1.pickFields(
-            //
-            { firstName: { type: "value" } }, { firstName: "a", b: "ignored" });
-            expect(a).toMatchInlineSnapshot(`
-      Object {
-        "firstName": "a",
-      }
-    `);
-        });
-        it("can pick an unset object fields", () => {
-            const a = useFormState_1.pickFields(authorWithAddressConfig, { firstName: "a", b: "ignored" });
-            expect(a).toMatchInlineSnapshot(`
-      Object {
-        "address": undefined,
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-        });
-        it("can pick a set object field", () => {
-            const a = useFormState_1.pickFields(authorWithAddressConfig, { firstName: "a", b: "ignored", address: {} });
-            expect(a).toMatchInlineSnapshot(`
-      Object {
-        "address": Object {
-          "city": undefined,
-          "street": undefined,
-        },
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-        });
-        it("can pick an unset list field", () => {
-            const a = useFormState_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored" });
-            expect(a).toMatchInlineSnapshot(`
-      Object {
-        "books": undefined,
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-        });
-        it("can pick a set list field", () => {
-            const a = useFormState_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored", books: [{}] });
-            expect(a).toMatchInlineSnapshot(`
-      Object {
-        "books": Array [
-          Object {
-            "classification": undefined,
-            "id": undefined,
-            "title": undefined,
-          },
-        ],
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-        });
-        it("can pick a set observable list field", () => {
-            const books = mobx_1.observable([]);
-            const a = useFormState_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored", books });
-            expect(mobx_1.isObservable(a.books)).toEqual(true);
+    it("batches calls to auto-save", async () => {
+        // Given a component
+        const autoSave = jest.fn();
+        function TestComponent() {
+            const config = authorConfig;
+            const data = { firstName: "f1", lastName: "f1" };
+            const form = useFormState_1.useFormState({
+                config,
+                init: data,
+                autoSave: (form) => autoSave(form.changedValue),
+            });
+            return (jsx_runtime_1.jsx("div", { children: jsx_runtime_1.jsx("button", { "data-testid": "set", onClick: () => {
+                        // And it sets two fields in a single callback
+                        form.firstName.set("f2");
+                        form.lastName.set("l2");
+                    } }, void 0) }, void 0));
+        }
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // When we change both
+        await rtl_utils_1.clickAndWait(r.set);
+        // Then we only call autoSave once
+        expect(autoSave).toBeCalledTimes(1);
+        expect(autoSave).toBeCalledWith({ firstName: "f2", lastName: "l2" });
+    });
+    it("queues changes for auto save if a save is already in progress", async () => {
+        const autoSaveStub = jest.fn();
+        const config = {
+            id: { type: "value" },
+            firstName: { type: "value" },
+            lastName: { type: "value" },
+        };
+        // Given a component using `getObjectState` for lazily creating ObjectStates
+        function TestComponent() {
+            const [apiData, setApiData] = react_2.useState({ id: "a:1", firstName: "Brandon", lastName: "Dow" });
+            const state = useFormState_1.useFormState({ config, autoSave, init: { input: apiData, map: (v) => v } });
+            async function autoSave(form) {
+                autoSaveStub(form.changedValue);
+                const changed = form.changedValue;
+                // Pretend to make an API call and update the local state
+                await Promise.resolve(1);
+                setApiData((prevState) => ({ ...prevState, ...changed }));
+            }
+            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsxs("div", Object.assign({ "data-testid": "name" }, { children: [apiData.firstName, " ", apiData.lastName] }), void 0),
+                    jsx_runtime_1.jsx("button", { "data-testid": "focusSetAndSaveField", onClick: () => {
+                            state.firstName.focus();
+                            state.firstName.set("Foo");
+                            state.firstName.maybeAutoSave();
+                            state.firstName.blur();
+                        } }, void 0),
+                    jsx_runtime_1.jsx("button", { "data-testid": "focusSetAndSaveFieldLastName", onClick: () => {
+                            state.lastName.focus();
+                            state.lastName.set("Bar");
+                            state.lastName.maybeAutoSave();
+                        } }, void 0)] }, void 0));
+        }
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // And triggering the auto save behavior before awaiting the initial promise to
+        // resolve so we have pending changes.
+        rtl_utils_1.click(r.focusSetAndSaveField(), { allowAsync: true });
+        // Let the initial autoSave be called
+        react_1.act(() => {
+            jest.runOnlyPendingTimers();
         });
+        expect(r.name()).toHaveTextContent("Brandon Dow");
+        expect(autoSaveStub).toBeCalledTimes(1);
+        expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "Foo" });
+        // And while that is in flight, trigger another user action
+        rtl_utils_1.click(r.focusSetAndSaveFieldLastName(), { allowAsync: true });
+        // (Use `wait` so that our timer flushes before the Promise.resolve(1) is ran)
+        await rtl_utils_1.wait();
+        // Then expect the auto save to only have been called twice. Once with each changedValues.
+        expect(autoSaveStub).toBeCalledTimes(2);
+        expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "Foo" });
+        expect(autoSaveStub).toBeCalledWith({ id: "a:1", lastName: "Bar" });
     });
 });
 const authorConfig = {
@@ -426,18 +431,6 @@ const authorConfig = {
     firstName: { type: "value" },
     lastName: { type: "value" },
 };
-const authorWithAddressConfig = {
-    id: { type: "value" },
-    firstName: { type: "value" },
-    lastName: { type: "value" },
-    address: {
-        type: "object",
-        config: {
-            street: { type: "value", rules: [formState_1.required] },
-            city: { type: "value" },
-        },
-    },
-};
 const authorWithBooksConfig = {
     id: { type: "value" },
     firstName: { type: "value" },

package/dist/useFormStates.d.ts

@@ -0,0 +1,12 @@
+import { ObjectConfig, ObjectState } from "./formState";
+export declare type ObjectStateCache<T, I> = Record<string, [ObjectState<T>, I]>;
+declare type UseFormStatesOpts<T, I> = {
+    config: ObjectConfig<T>;
+    autoSave?: (state: ObjectState<T>) => Promise<void>;
+    getId: (v: I) => string;
+    map?: (input: Exclude<I, null | undefined>) => T;
+};
+export declare function useFormStates<T, I>(opts: UseFormStatesOpts<T, I>): {
+    getObjectState: (input: I) => ObjectState<T>;
+};
+export {};

package/dist/useFormStates.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFormStates = void 0;
+const react_1 = require("react");
+const formState_1 = require("./formState");
+const utils_1 = require("./utils");
+function useFormStates(opts) {
+    const { config, autoSave, getId, map } = opts;
+    const objectStateCache = react_1.useMemo(() => ({}), [config]);
+    // Keep track of ObjectStates that triggered auto-save when a save was already in progress.
+    const pendingAutoSaves = react_1.useRef([]);
+    // Use a ref so our memo'ized `autoSave` always see the latest value
+    const autoSaveRef = react_1.useRef(autoSave);
+    autoSaveRef.current = autoSave;
+    async function maybeAutoSave(form) {
+        if (isAutoSaving && !pendingAutoSaves.current.includes(form)) {
+            pendingAutoSaves.current.push(form);
+        }
+        // Don't use canSave() because we don't want to set touched for all the fields
+        if (autoSaveRef.current && form.dirty && form.valid && !isAutoSaving) {
+            try {
+                isAutoSaving = true;
+                await autoSaveRef.current(form);
+            }
+            finally {
+                isAutoSaving = false;
+                if (pendingAutoSaves.current.length > 0) {
+                    await maybeAutoSave(pendingAutoSaves.current.shift());
+                }
+            }
+        }
+    }
+    return {
+        getObjectState: (input) => {
+            const existing = objectStateCache[getId(input)];
+            const form = existing
+                ? existing[0]
+                : formState_1.createObjectState(config, utils_1.initValue(config, map ? { map, input } : input), {
+                    maybeAutoSave: () => maybeAutoSave(form),
+                });
+            // If it didn't exist, then add to the cache.
+            if (!existing) {
+                objectStateCache[getId(input)] = [form, input];
+            }
+            // If the source of truth changed, then update the existing state and return it.
+            if (existing && existing[1] !== input) {
+                existing[0].set(utils_1.initValue(config, map ? { map, input } : input), { refreshing: true });
+                existing[1] = input;
+            }
+            return form;
+        },
+    };
+}
+exports.useFormStates = useFormStates;
+// If the user's autoSave hook makes some last-minute `.set` calls to sneak
+// in some business logic right before their GraphQL mutation call, ignore it
+// so that we don't infinite loop.
+let isAutoSaving = false;

package/dist/useFormStates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/useFormStates.test.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const rtl_utils_1 = require("@homebound/rtl-utils");
+const react_1 = require("react");
+const formState_1 = require("./formState");
+const useFormStates_1 = require("./useFormStates");
+describe("useFormStates", () => {
+    it("can lazily create form states", async () => {
+        const autoSave = jest.fn();
+        // Given a parent and child component, where the formState is created only for the child component.
+        function ChildComponent({ os }) {
+            return jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: os.firstName.value }), void 0);
+        }
+        function TestComponent() {
+            const config = { id: { type: "value" }, firstName: { type: "value" } };
+            const { getObjectState } = useFormStates_1.useFormStates({
+                config,
+                autoSave,
+                getId: (o) => o.id,
+            });
+            return (jsx_runtime_1.jsx("div", { children: jsx_runtime_1.jsx(ChildComponent, { os: getObjectState({ id: "a:1", firstName: "Brandon" }) }, void 0) }, void 0));
+        }
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // And the child component has defined state
+        expect(r.firstName()).toHaveTextContent("Brandon");
+    });
+    it("can update existing object state from cache with new values", async () => {
+        const autoSave = jest.fn();
+        const config = { id: { type: "value" }, firstName: { type: "value" } };
+        // Given a component using `getObjectState` for lazily creating ObjectStates
+        function TestComponent() {
+            const [apiData, setApiData] = react_1.useState({ id: "a:1", firstName: "Brandon" });
+            const { getObjectState } = useFormStates_1.useFormStates({ config, autoSave, getId: (o) => o.id });
+            // Memoize an original for comparing the update against.
+            const originalState = react_1.useMemo(() => getObjectState(apiData), []);
+            const state = getObjectState(apiData);
+            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: state.firstName.value }), void 0),
+                    jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "statesEqual" }, { children: JSON.stringify(state === originalState) }), void 0),
+                    jsx_runtime_1.jsx("button", { "data-testid": "updateApiData", onClick: () => setApiData((prevState) => ({ ...prevState, firstName: "Bob" })) }, void 0)] }, void 0));
+        }
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // And the initial values for the form state display
+        expect(r.firstName()).toHaveTextContent("Brandon");
+        expect(r.statesEqual()).toHaveTextContent("true");
+        // When updating the API data
+        await rtl_utils_1.clickAndWait(r.updateApiData());
+        // Then the new value is shown in the component
+        expect(r.firstName()).toHaveTextContent("Bob");
+        // And the two states are using the same reference
+        expect(r.statesEqual()).toHaveTextContent("true");
+    });
+    it("can queue up changes for auto save if a save is already in progress - works across multiple states", async () => {
+        const autoSaveStub = jest.fn();
+        const config = {
+            id: { type: "value" },
+            firstName: { type: "value" },
+            lastName: { type: "value" },
+        };
+        // Given a component using `getObjectState` for lazily creating ObjectStates
+        function TestComponent() {
+            const [apiData, setApiData] = react_1.useState({ id: "a:1", firstName: "Tony", lastName: "Stark" });
+            const [apiData2, setApiData2] = react_1.useState({ id: "a:2", firstName: "Steve", lastName: "Rogers" });
+            const { getObjectState } = useFormStates_1.useFormStates({ config, autoSave, getId: (o) => o.id });
+            const state = getObjectState(apiData);
+            const state2 = getObjectState(apiData2);
+            async function autoSave(form) {
+                autoSaveStub(form.changedValue);
+                // Pretend to make an API call and update the local state
+                if (form.id.value === "a:1") {
+                    setApiData((prevState) => ({ ...prevState, ...form.changedValue }));
+                }
+                else {
+                    setApiData2((prevState) => ({ ...prevState, ...form.changedValue }));
+                }
+                await Promise.resolve(1);
+            }
+            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: state.firstName.value }), void 0),
+                    jsx_runtime_1.jsx("button", { "data-testid": "focusSetAndSaveField", onClick: () => {
+                            state.firstName.focus();
+                            state.firstName.set("Foo");
+                            state.firstName.maybeAutoSave();
+                        } }, void 0),
+                    jsx_runtime_1.jsx("button", { "data-testid": "focusSetAndSaveFieldLastName", onClick: () => {
+                            state.lastName.focus();
+                            state.lastName.set("Bar");
+                            state.lastName.maybeAutoSave();
+                        } }, void 0),
+                    jsx_runtime_1.jsx("button", { "data-testid": "focusSetAndSaveField2", onClick: () => {
+                            state2.lastName.focus();
+                            state2.lastName.set("Bar");
+                            state2.lastName.maybeAutoSave();
+                        } }, void 0)] }, void 0));
+        }
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // And triggering the auto save behavior before awaiting the initial promise to resolve so we have pending changes.
+        rtl_utils_1.click(r.focusSetAndSaveField());
+        rtl_utils_1.click(r.focusSetAndSaveFieldLastName());
+        rtl_utils_1.click(r.focusSetAndSaveField2());
+        // Awaits the promises for all methods triggered above
+        await rtl_utils_1.wait();
+        // Then expect the auto save to only have been called three times. Once with each set of changedValues.
+        expect(autoSaveStub).toBeCalledTimes(3);
+        expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "Foo" });
+        expect(autoSaveStub).toBeCalledWith({ id: "a:1", lastName: "Bar" });
+        expect(autoSaveStub).toBeCalledWith({ id: "a:2", lastName: "Bar" });
+    });
+    it("clears out cache if configuration changes", async () => {
+        const autoSave = jest.fn();
+        // Given a component with stable API data.
+        const apiData = { id: "a:1", firstName: "Brandon", lastName: "Dow" };
+        // And two sets of configurations
+        const originalConfig = { id: { type: "value" }, firstName: { type: "value" } };
+        const updatedConfig = {
+            id: { type: "value" },
+            firstName: { type: "value", rules: [formState_1.required] },
+        };
+        function TestComponent() {
+            const [config, setConfig] = react_1.useState(originalConfig);
+            const { getObjectState } = useFormStates_1.useFormStates({ config, autoSave, getId: (o) => o.id });
+            // Memoize an original for comparing the update against.
+            const originalState = react_1.useMemo(() => getObjectState(apiData), []);
+            const state = getObjectState(apiData);
+            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "statesEqual" }, { children: JSON.stringify(state === originalState) }), void 0),
+                    jsx_runtime_1.jsx("button", { "data-testid": "updateConfig", onClick: () => setConfig(updatedConfig) }, void 0)] }, void 0));
+        }
+        // When rendered with the original configuration
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // Then the two form-states generated are equal
+        expect(r.statesEqual()).toHaveTextContent("true");
+        // When updating the configuration object
+        rtl_utils_1.click(r.updateConfig);
+        // Then the two form-states are no longer equal.
+        expect(r.statesEqual()).toHaveTextContent("false");
+    });
+});

package/dist/utils.d.ts

@@ -1,2 +1,17 @@
+import { ObjectConfig } from "./formState";
 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;
+/**
+ * Picks ony fields out of `instance` that are in the `formConfig`.
+ *
+ * This is useful for creating a form input from a GraphQL query result,
+ * but ignoring extra data in the query that we don't want/need in the form.
+ *
+ * (Especially because the form.value will become our mutation's input type
+ * that goes on the wire, we don't want superfluous data in it.)
+ */
+export declare function pickFields<T, I>(formConfig: ObjectConfig<T>, instance: I): {
+    [K in keyof T]: K extends keyof I ? I[K] : never;
+};

package/dist/utils.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertNever = exports.fail = void 0;
+exports.pickFields = exports.initValue = exports.assertNever = exports.fail = void 0;
+const is_plain_object_1 = require("is-plain-object");
+const mobx_1 = require("mobx");
 function fail(message) {
     throw new Error(message || "Failed");
 }
@@ -9,3 +11,60 @@ function assertNever(x) {
     throw new Error("Unexpected object: " + 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);
+}
+exports.initValue = initValue;
+/**
+ * Picks ony fields out of `instance` that are in the `formConfig`.
+ *
+ * This is useful for creating a form input from a GraphQL query result,
+ * but ignoring extra data in the query that we don't want/need in the form.
+ *
+ * (Especially because the form.value will become our mutation's input type
+ * that goes on the wire, we don't want superfluous data in it.)
+ */
+function pickFields(formConfig, instance) {
+    // If the caller is using classes, i.e. with their own custom observable behavior, then just use as-is
+    if (!is_plain_object_1.isPlainObject(instance)) {
+        return instance;
+    }
+    return Object.fromEntries(Object.entries(formConfig).map(([key, _keyConfig]) => {
+        const keyConfig = _keyConfig;
+        const value = instance[key];
+        if (keyConfig.type === "object") {
+            if (value) {
+                return [key, pickFields(keyConfig.config, value)];
+            }
+            else {
+                return [key, value];
+            }
+        }
+        else if (keyConfig.type === "list") {
+            if (mobx_1.isObservable(value)) {
+                // If we hit an observable array, leave it as the existing proxy so the our
+                // ListFieldState will react to changes in the original array.
+                return [key, value];
+            }
+            else if (value) {
+                return [key, value.map((u) => pickFields(keyConfig.config, u))];
+            }
+            else {
+                return [key, value];
+            }
+        }
+        else if (keyConfig.type === "value") {
+            return [key, value];
+        }
+        else {
+            return assertNever(keyConfig);
+        }
+    }));
+}
+exports.pickFields = pickFields;

package/dist/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils.test.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mobx_1 = require("mobx");
+const formState_1 = require("./formState");
+const utils_1 = require("./utils");
+describe("utils", () => {
+    describe("pickFields", () => {
+        it("can pick a value field", () => {
+            const a = utils_1.pickFields(
+            //
+            { firstName: { type: "value" } }, { firstName: "a", b: "ignored" });
+            expect(a).toMatchInlineSnapshot(`
+      Object {
+        "firstName": "a",
+      }
+    `);
+        });
+        it("can pick an unset object fields", () => {
+            const a = utils_1.pickFields(authorWithAddressConfig, { firstName: "a", b: "ignored" });
+            expect(a).toMatchInlineSnapshot(`
+      Object {
+        "address": undefined,
+        "firstName": "a",
+        "id": undefined,
+        "lastName": undefined,
+      }
+    `);
+        });
+        it("can pick a set object field", () => {
+            const a = utils_1.pickFields(authorWithAddressConfig, { firstName: "a", b: "ignored", address: {} });
+            expect(a).toMatchInlineSnapshot(`
+      Object {
+        "address": Object {
+          "city": undefined,
+          "street": undefined,
+        },
+        "firstName": "a",
+        "id": undefined,
+        "lastName": undefined,
+      }
+    `);
+        });
+        it("can pick an unset list field", () => {
+            const a = utils_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored" });
+            expect(a).toMatchInlineSnapshot(`
+      Object {
+        "books": undefined,
+        "firstName": "a",
+        "id": undefined,
+        "lastName": undefined,
+      }
+    `);
+        });
+        it("can pick a set list field", () => {
+            const a = utils_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored", books: [{}] });
+            expect(a).toMatchInlineSnapshot(`
+      Object {
+        "books": Array [
+          Object {
+            "classification": undefined,
+            "id": undefined,
+            "title": undefined,
+          },
+        ],
+        "firstName": "a",
+        "id": undefined,
+        "lastName": undefined,
+      }
+    `);
+        });
+        it("can pick a set observable list field", () => {
+            const books = mobx_1.observable([]);
+            const a = utils_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored", books });
+            expect(mobx_1.isObservable(a.books)).toEqual(true);
+        });
+    });
+});
+const authorWithAddressConfig = {
+    id: { type: "value" },
+    firstName: { type: "value" },
+    lastName: { type: "value" },
+    address: {
+        type: "object",
+        config: {
+            street: { type: "value", rules: [formState_1.required] },
+            city: { type: "value" },
+        },
+    },
+};
+const authorWithBooksConfig = {
+    id: { type: "value" },
+    firstName: { type: "value" },
+    lastName: { type: "value" },
+    books: {
+        type: "list",
+        config: {
+            id: { type: "value" },
+            title: { type: "value", rules: [formState_1.required] },
+            classification: { type: "value" },
+        },
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/form-state",
-  "version": "2.4.0",
+  "version": "2.5.2",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",
@@ -21,6 +21,14 @@
     "format": "prettier --loglevel warn --write \"**/*.{ts,tsx,css,md}\"",
     "semantic-release": "semantic-release"
   },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged --allow-empty"
+    }
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx,css,md}": "prettier --write"
+  },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",
     "is-plain-object": "^5.0.0",
@@ -32,16 +40,16 @@
   },
   "devDependencies": {
     "@babel/core": "^7.13.1",
-    "@homebound/rtl-utils": "^2.40.0",
+    "@homebound/rtl-utils": "^2.59.2",
     "@semantic-release/git": "^9.0.0",
     "@storybook/addon-essentials": "^6.2.9",
     "@storybook/addon-info": "^5.3.21",
     "@storybook/addon-links": "^6.2.9",
     "@storybook/addons": "^6.2.9",
     "@storybook/react": "^6.2.9",
-    "@testing-library/dom": "^7.31.0",
-    "@testing-library/jest-dom": "^5.12.0",
-    "@testing-library/react": "^11.2.7",
+    "@testing-library/dom": "^8.11.3",
+    "@testing-library/jest-dom": "^5.16.2",
+    "@testing-library/react": "^12.1.2",
     "@tsconfig/recommended": "^1.0.1",
     "@types/jest": "^26.0.20",
     "@types/react": "^16.14.5",
@@ -59,8 +67,9 @@
     "eslint-plugin-jsx-a11y": "^6.4.1",
     "eslint-plugin-react": "^7.22.0",
     "eslint-plugin-react-hooks": "^4.2.0",
-    "husky": "^5.1.1",
+    "husky": "^3.0.9",
     "jest": "^27.0.2",
+    "lint-staged": "^10.1.2",
     "mobx": "^6.3.2",
     "mobx-react": "^7.2.0",
     "prettier": "^2.2.1",