Generic object edition with dirty state management

[llemire]

Hello! I am currently working on a project that contains a generic react component whose goal is to take any json object and allow a user to:

• see the value of any of its properties
• make changes to its properties
• allow the user to see which properties are dirty (meaning what properties have changed in comparison to when the object has been provided)

Since the structure of the json object can vary, the component is used as a wrapper and only provide utility function through a React Context. as of right now the context contains:

• the current value of the json object
• a method to update the current value of the json object
• a method that checks if a certain property of the json object is dirty

Because every time the user updates a field in the object, it changes the context and re-render the whole wrapper, we want to replace the current Context implementation with Jotai. I have already created a prototype that works, but I have never worked with Jotai before so the point of this thread is to see if anyone can find any issue or suggestion with our implementation.

Entity Atoms and utility functions

// Atom Definition

// Read-Write atom, contains the editable entity.
export const entityAtom = atom<any>(null);

// Read-Write atom, contains the initial entity.
export const initialEntityAtom = atom<any>(null);

// Read-only atom, contains true if the entity, initialEntity and the config atom are not null
export const hasLoadedAtom = atom((get) => !!get(entityAtom) && !!get(initialEntityAtom) && !!get(configAtom));

// Write-only atom, used for editing the entity atom.
const writeEntityAtom = atom(null, (get, set, update: object | null) => {
    set(entityAtom, {
        ...get(entityAtom),
        ...update,
    });
});

//Write-only atom used for editing the initial entity atom.
const writeInitialEntityAtom = atom(null, (get, set, update: object | null) => {
    set(initialEntityAtom, {
        ...get(initialEntityAtom),
        ...update,
    });
});

// Helper hooks

/**
 * Hook used for editing the entity while inside a react component or hook
 * @returns a method that takes a Partial<TEntity>.
 */
export const useEdit = <TEntity>() => {
    const setAtom = useSetAtom(writeEntityAtom);
    const set = useCallback(
        (update: Partial<TEntity> | null) => {
            setAtom(update);
        },
        [setAtom],
    );

    return set;
};

/**
 * Hook used for editing the initial entity while inside a react component or hook
 * @returns a method that takes a Partial<TEntity>.
 */
export const useInitialEdit = <TEntity>() => {
    const setAtom = useSetAtom(writeInitialEntityAtom);
    const set = useCallback(
        (update: Partial<TEntity> | null) => {
            setAtom(update);
        },
        [setAtom],
    );

    return set;
};

/**
 * Hook that acts like a useState but for a specific property of the entity Atom.
 * @param prop the name of the property, must be a key of TEntity.
 * @returns the value of the property and a method to change the value of the property.
 */
export const useProperty = <TEntity, TSlice>(prop: keyof TEntity): [TSlice, (newValue: TSlice) => void] => {
    const set = useEdit();

    const [value] = useAtom(useMemo(() => selectAtom(entityAtom, (v: TEntity) => v[prop] as TSlice), [prop]));

    const setValue = useCallback(
        (newValue: TSlice) => {
            set({
                [prop]: newValue,
            });
        },
        [prop, set],
    );
    return [value, setValue];
};

/**
 * Hook that acts like a useState but for a specific property of the initial entity Atom.
 * @param prop the name of the property, must be a key of TEntity.
 * @returns the value of the property as a TSlice and a method to change the value of the property.
 */
export const useInitialProperty = <TEntity, TSlice>(prop: keyof TEntity): [TSlice, (newValue: TSlice) => void] => {
    const set = useInitialEdit();

    const [value] = useAtom(useMemo(() => selectAtom(initialEntityAtom, (v: TEntity) => v[prop] as TSlice), [prop]));

    const setValue = useCallback(
        (newValue: TSlice) => {
            set({
                [prop]: newValue,
            });
        },
        [prop, set],
    );

    return [value, setValue];
};

Dirty Atoms and utility hooks

// Atom Definition

// Atom family, for each property, it will create an Atom<boolean> that represents if this property is dirty.
const dirtyPropertyFamily = atomFamily((property: string) => {
    return atom((get) => {
        const a = get(entityAtom)[property];
        const b = get(initialEntityAtom)[property];

        return a !== b;
    });
});

// Read-only atom representing if the entity is Dirty as a whole.
export const isEntityDirtyAtom = atom((get) => {
    const entity = get<object>(entityAtom);

    for (const p of Object.keys(entity)) {
        const isPropertyDirty = get(dirtyPropertyFamily(p));
        if (isPropertyDirty) {
            return true;
        }
    }

    return false;
});

// Helper Hooks

/**
 * Hook used to check if a specific property of the TEntity is Dirty
 * @param property the name of the property
 * @returns true if the property is dirty, false otherwise.
 */
export const useIsDirty = <TEntity>(property: keyof TEntity): boolean => {
    const isDirty = useAtomValue(dirtyPropertyFamily(property.toString()));
    return isDirty;
};

This is a first draft, so some stuff like typings and naming are not perfect yet, but I just wanted to know if I was going in the right direction.

Explanation

My editable object and initial entity are both inside a singular atom, I create an utility hook called useProperty that acts like a useState for a singular property of the editable object which can be used inside react components.

My dirty state is managed by an atom family which creates a boolean atom for each property of my object, I created a special atom which checks every atom in the family to check if the entity as a whole is dirty or not and also a custom hook for checking if a specific property is dirty or not.

Example:

interface Test {
  description: string
}

export const MyComponent = () => {
    const [description, setDescription] = useProperty<Test , string>("description");
    const isDescriptionDirty = useIsDirty<Test >("description");

    return (
        <div>
            description
            <div>isDirty: {isDescriptionDirty.toString()}</div>
            <Input
                value={description}
                onChange={(e) => {
                    setDescription(e.target.value);
                }}
            />
        </div>
    );
};

This is my first time creating a thread like this so if I forgot something like putting a tag or something like that don't hesitate to tell me!

[MiroslavPetrik]

Hey, I see 2 issues here.
First that you have a 'god object' in that you are patching the entity.
Next, that you support only 1 level of property, which currently maybe is ok, but later you could need the support for nested objects.

Instead of the 'god object' you could benefit from the bottom-up approach, so you wrap each of the properties to a separate "molecule" which would have separate atom for dirty, value, etc.
Finally, you would aggregate the molecules of properties to construct the "entity".

You could benefit from the form-atoms library, where on top of dirty check or value modification, you get validation metadata like error and validateStatus, or touched state. Those could also aid the editing process of your properties.

Currently I don't remember if there are examples how to dynamically initialize a form from a JSON, but the library does support dynamic fields, so you won't get stuck.

[llemire]

Thanks for the quick response!

For your first point, I agree that using a "god object" is not ideal, but for a first draft it seemed like the easiest way to be able to use atoms in a generic way. I looked at the form-atoms library you mentioned and I saw how you can create your entity using formAtom by declaring each atom and then pass it to your generic Form Component. This indeed looks like a better way to handle what I am trying to do, so thank you for sharing!

For your second point, It was indeed something that I was aware of. A solution that I had not implemented yet is to pass the select function directly instead of just the name of the property for example:

interface Test {
  user: {
    name: string
  }
}

const selector = useCallback((t: Test) => t.user.name), []);
const [name, setName] = usePropertyWithSelector<Test, string>(selector);

export const usePropertyWithSelector = <TEntity, TSlice>(selector: any /*Not sure of the typing*/): [TSlice, (newValue: TSlice) => void] => {
    const set = useEdit();

    const [value] = useAtom(useMemo(() => selectAtom(entityAtom, selector), [selector]));

    const setValue = // Not sure how to create the setValue method
   
    return [value, setValue];
};

But I had some issues with the typing and I am not sure how to actually edit the entityAtom using the selector function which is why I didn't post it, I am not 100% certain if its actually do-able.

I really love the form-atoms library since we do actually want to handle errors, validation and other things that the library seems to already be managing very well, but I do have 1 concern: One of the entity we want to use it on has a field with properties that can change over time, for example:

interface Root {
  [rowKey: string]: Row;
}

interface Row {
  [dataKey: string]: Data;
}

interface Data {
  name: string;
  age: number;
  // etc...
}

which means that we cannot declare all atoms since the object can actually evolve over time. Can the form-atoms library handle such a case? (I saw in the documentation that it says that the library can handle dynamic fields, but I cannot find any example or documentation on how to actually do it)

[MiroslavPetrik]

For your setValue, you would need something like deep object merge, to apply patches to your root entity.

import { set as setObject } from "object-path-immutable";

const patchEntity = (path) => atom(null, (get, set, update: object | null) => {
    set(entityAtom, setObject(get(entityAtom), path, update));
});

const patchUserNameAtom = patchEntity("user.name");

const setUserName = useSetAtom(patchUserNameAtom);

For the dynamic part of form atom, your Root interface with rows maybe can use listAtom from @form-atoms/field when your Row are homogenous (like regular array e.g. Array<{name: string, age: number}>). It would work for your example, if you can have the rowKey and dataKey as number.

Also you might have use case for "decoration" of objects, e.g. let's say I have a

type Card = {
  size: "sm" | "md" | "lg",
};

and you need to decorate it with background:

type WithBackground<T> = T & { background: string };

type BgCard = WithBackground<Card>;
        // ^? { size: "sm" | "md" | "lg", background: string };

For that you would introduce new fieldAtom() into the form via the updateFields() action of useFormActions().
You can see the updateFields in practice as it updates an array. Its a manual handling of array of atoms, before the listAtom was implemented. The listAtom is more powerful as it uses the splitAtoms from jotai/utils so you don't have to set the array items manually, and have actions for add/remove/move.