Added transform function (instead of update)

[twop]

• This PR allows to conveniently work with redux states modeled with unionize.
• update takes an object and update cases. If the cases are unmet the original object is returned
• If there is a met case the result of it is either merged to the object or replaced. It has Partial signature for update result. So strings, numbers, Dates are being replaced and plain objects merged in.
• this is done via the most brilliant api possible

// Should we merge objects or just replace them?
// was unable to find a better solution to that
const objType = Object.prototype.toString.call({}); // [object Object]
const isObject = (maybeObj: any) => Object.prototype.toString.call(maybeObj) === objType;
const immutableUpd = (old: any, updated: any) =>
  isObject(old) ? Object.assign({}, old, updated) : updated;

Do have any ideas how to achieve it differently?

• For me personally this is probably one of the most needed changes. I use unionize only for redux states.

const Data = unionize({AB: ofType<{ a: number; b: string }>()});
const ab = Data.AB({ a: 1, b: 'hi' });
Data.update(ab, { AB: ({ b }) => ({ b: b + '!' }) }); // {tag:'AB', a: 1, b: 'hi!'}

[twop]

Once/If you accept this PR I will make another one that will cover all api changes in README.

[coveralls]

Coverage remained the same at 100.0% when pulling 115177e on twop:master into b8cb841 on pelotom:master.

[twop]

Improved typings for tag property in config obj

[pelotom]

For consistency, let's say "value" instead of "payload" here.

[twop]

Will do

[pelotom]

s/payload/value/

[twop]

I wanted a helper function that will extract value from an object. What about 'extractVal()'?

[pelotom]

Hmm, I'm not sure how reliable or efficient this sort of check is. Does it even make sense to "update" something that's a primitive type? If not, could we statically forbid using this method in that case?

[twop]

I think it does make sense to have update for primitive types (and things like Date, Array etc).
string -> string, number->number, array->array. So the output has to match exactly the input type.

But for records (plain object) it makes sense to have partial update. The best reference that I found is react setState signature. They use Pick<K,T> type and not partial.

[pelotom]

Using Partial for the return type here is unsafe because it allows overwriting values with undefined. I'm not sure if inference would be able to handle using Pick though... Perhaps we should statically disallow values to be undefined, which we're already doing in the case of SingleValueVariants.

[twop]

I think it is possible to not use Partial + remove this magic check for 'isObject'.
I think the way to do it is this:

function update<T>(val:T):T | Part<T> {}; // Not Partial
type Part<T> = {_opaque:T}//  is opaque for user.

// helper function to create a part
function part<K extends keyof T, T>(p: Pick<K,T>) : Part<T> {
   // tag that this is a part object for implementation
   return  {__part: p} as any as Part<T>
}

// simplified implementation for update
function updateObject(oldV, newV) {
if (typeof newV === 'object'  && newV.__part)  {
   // merge objects
   return merged.
   }
   // if it is not a part it has to be a full object.
   return newV;
} 

So you either have to provide a complete object (not Partial) or use a helper function.

const Data = unionize({AB: ofType<{ a: number; b: string }>()});
const ab = Data.AB({ a: 1, b: 'hi' });
Data.update(ab, { AB: ({ b }) => part({ b: b + '!' }) }); //note usage of 'part'
Data.update(ab, { AB: ({ a, b }) => ({a, b: b + '!' }) }); // or provide a full shape

Not 100% that it is worth complexity. But thinking about updates again, I would either prefer a solution with 'part' function without 'isObject' magic or forbid partial updates. Note that in that case it is still useful:

• don't have to provide default
• don't have to call type constructor

// a bit verbose
Data.match(ab, { AB: ({ a, b }) => Data.AB({a, b: b + '!' }), default: i=>i })

[pelotom]

Thinking about this some more, I think there are a couple of use cases being conflated here:

1. Being able to match on only a subset of the tags, without specifying a default, as long as the return type is still the union type
2. Being able to immutably "modify" a union variant by specifying a minimal patch

Additionally with this current PR, (1) is not fully handled, because one might want to take an old variant and give it not only a new value, but a completely new tag. For example, this would be nice to support:

const State = unionize({
  ok: {},
  error: ofType<{ message: string }>(),
});

// no "ok" case, and no default!
const clearError = State.match({ error: () => State.ok({}) });

I think we can easily support this by just adding another variant to MatchCases:

export type MatchCases<Record, Union, A> =
  | Cases<Record, A> & NoDefaultProp
  | Partial<Cases<Record, Union>> & NoDefaultProp // <--
  | Partial<Cases<Record, A>> & { default: (variant: Union) => A };

If we do that, then perhaps (2) becomes a slightly simpler problem?

[pelotom]

I suppose something is lost if we overload match in that way, which is that you can't get exhaustiveness checking if the result type of match is the union type... 🤔

[pelotom]

It's also worth considering how easy it is already to do immutable updates with an external library like immer:

import produce from 'immer';

const State = unionize({
  foo: {},
  bar: ofType<{ x: string; y: boolean }>(),
});

declare const state: typeof State._Union;

const result = produce(state, copy => {
  switch (state.tag) {
    case 'bar': copy.y = true;
  }
});

[twop]

I think your idea about transforming states makes total sense but I think it is better to have it as a separate function.

export type TransformCases<Record, Union> = Partial<Cases<Record, Union>> 

Then your example

const State = unionize({
  ok: {},
  error: ofType<{ message: string }>(),
});

// clearError:: Union -> Union.
const clearError = State.transform({ error: () => State.ok({}) });

I guess if you think about app state as a state machine (Loading->Loaded or Error) then this signature makes perfect sense. Although it is probably a bit excessive to have both 'transform' and 'update'. Not sure which one I would pick if I have to pick only one.

[twop]

I will try to prototype the solution with 'part' helper function. I'm not 100% sure that you can express that in ts without specifying types (not sure if everything can be inferred). But overall I'm not happy with current "magic" code(isObject) of partial updates.

[twop]

upd:
typings for 'part' functions worked out

  const Data = unionize({
      A: ofType<{ a: 'not used' }>(),
      BC: ofType<{ b: number; c: string }>(),
    });

    const bc = Data.BC({ b: 1, c: 'hi' });
    const expected = Data.BC({ b: 1, c: 'hi!' });
    // part
    expect(Data.update({ BC: ({ c }) => part({ c: c + '!' }) })(bc)).toEqual(expected);
    //whole obj
    expect(Data.update(bc, { BC: ({ b, c }) => ({ b, c: c + '!' }) })).toEqual(expected); 

Here are the types for it

export type UpdateCases<Record> = Partial<
  { [T in keyof Record]: (value: Record[T]) => Record[T] | Part<Record[T]> }
>;
export interface Part<T> { __opaque: T; }

export function part<K extends keyof T, T>(p: Pick<T, K>): Part<T> {
  return (undefined as any) as Part<T>;
}

Not sure if this new function is worth it. But I do like this solution because there is no magic involved + you cannot provide 'undefined' for values. Also it is always clear when you want a partial update vs whole object.

At work I use partial updates extensively. I will update this PR with part function regardless. And then we can discuss having 'transform' on top/instead.

[twop]

upd2:
impl:

export function part<K extends keyof T, T extends { [k: string]: any; }>(p: Pick<T, K>): Part<T> {
  return ({ __part: p } as any) as Part<T>;
}

const immutableUpd = (old: any, updated: any) => {
  if (typeof old === 'object' && typeof updated === 'object' && updated.__part) {
    return Object.assign({}, old, updated.__part);
  }
  return updated;
};

And here are various ways to mess up

it('shoots yourself in the foot', () => {
    const InTheFoot = unionize(
      {
        d: ofType<Date>(),
        s: ofType<string>(),
        n: ofType<number>(),
        a: ofType<number[]>(),
      },
      { value: 'payload' },
    );

    InTheFoot.update({ s: i => part('str?') }); // Error: string not assignable to object
    InTheFoot.update({ d: i => part(new Date(i.getTime())) }); // Date is just fine
    InTheFoot.update({ n: i => part(i) }); // Error: number is not assignable to object
    InTheFoot.update({ a: i => part(i) }); // array is fine as well
  });

Taken that into account I would probably postpone partial updates unless we improve typings or handle arrays at runtime. Without partial update is there a value in adding update? Is there a value in adding a separate 'transform' function?

What are your thoughts?

NOTE: using 2.8 I tried to forbid usage of strings/arrays etc but was unable to do so.

[pelotom]

Taken that into account I would probably postpone partial updates unless we improve typings or handle arrays at runtime.

Yeah, I think I'd rather wait until a cleaner solution presents itself.

Without partial update is there a value in adding update? Is there a value in adding a separate 'transform' function?

I'm not sure. The separate transform function appeals to me because it's very straightforward and (seems) useful.

[twop]

I like transform as well. IMHO it has cleaner semantics. Plus transform will have some utility for me as well.

I can rework this PR to introduce it.
There is a branch with update logic. So It won't be lost.

[pelotom]

Looks good 👍