feat!: Support transient identities and traits

[khvn26]

Closes #236.

[kyle-ssg]

Awesome, I can see the tests pass so we must be good on regression. I guess we do need additional tests around this:

• Matching tests setting transient traits in the same way we do normal
• Checking we can cache a mix of transient and non-transient traits
• Checking what happens when we call getFlags after identifying with transient traits (does it still send them over, I guess it should)

[khvn26]

@kyle-ssg I've added:

• Fetch mocks, as discussed in Slack.
• Tests to ensure proper getFlags behaviour.
• A test to ensure that the client preserves transient traits correctly.

[novakzaballa]

LGTM

[khvn26]

TODO: change branch reference to main after Flagsmith/flagsmith#4414 is merged.

[khvn26]

Rewrote the implementation keeping existing interfaces intact and adding support for the evaluationContext: EvaluationContext configuration entry.

[khvn26]

As discussed offline, added transiency support to identify, setTrait and setTraits interfaces.

[kyle-ssg]

value is actually a IFlagsmithValue, this is important so that people don't send objects.

[khvn26]

This is sorted out for client input.

[kyle-ssg]

I think here we should let people supply just a value or an object. The reason being is that 99% of the time, traits are not transient and would much rather see the following all over my code

traits:{a:1,b:2,c:{value:3, transient: true}}

than

traits:{a:{value:1,transient:false}, b:{}.....}

Also, a lot of people will just blindly send up an object they received from an api or one they've constructed themselves, with this new api they'd have to go through the hassle of converting a key value pair object to what we expect.

[khvn26]

I see the following ways forward here:

1. Modify the common eval context schema to support a union trait type. IMO, this will not improve UX for strictly typed SDKs at all, and the end result will be harder to support.
2. Add a ClientEvaluationContext type with the union value that will be used in all public interfaces. Envelope the simple trait values internally. Again, more code to support, but slightly more preferable.
3. Don't do anything with the types but export a utility function for the users to wrap their traits with:

toTraitEvaluationContext(input: { [key: string]: IFlagsmithValue }) => { [key: string]: TraitEvaluationContext }

[kyle-ssg]

Essentially I think the following code should work for when (most cases) traits aren't transient

flagsmith.setTraits({ a: 'foo' });
flagsmith.setTrait('a', 'foo');
flagsmith.init({ traits: { a: 'foo' } });

And I guess with evaluationContext

flagsmith.init({ evaluationContext: { identity: { traits: { a:  "foo" } }});

As long as the types reflect that option I'm not that concerned about implementation detail

[kyle-ssg]

The main reason for this other than less code / easier to read is it means that in most cases we wouldn't have to do some form of conversion of existing objects

I'd have to write some code like the following or manually reconstruct an object

const values = { // some object I also want to pass to Flagsmith
    first_name: "Kyle",
    last_name: "Johnson",
};

const updatedValues = Object.entries(values).reduce((acc, [key, value]) => {
    acc[key] = { value };
    return acc;
}, {});

[khvn26]

Just so we're on the same page, the old interfaces, including setTraits and setTrait are meant to continue supporting this.

For init and setContext/updateContext, I propose to expose toTraitEvaluationContext adapter function so users can continue to provide a simple object for traits.

So your example snippet will look like:

import { createFlagsmithInstance, toTraitEvaluationContext } from 'flagsmith';


const values = { // some object I also want to pass to Flagsmith
    first_name: "Kyle",
    last_name: "Johnson",
};

const flagsmith = createFlagsmithInstance();

await flagsmith.init(...)

await flagsmith.setContext({ identity: { traits: toTraitEvaluationContext(values) } });

[kyle-ssg]

Not sure I'm I fan of this, it would add an export that would need to be documented / is not immediately clear what it does.

[kyle-ssg]

If toTraitEvaluationContext is always a safe conversion, we may as well hide this complexity away and let the SDK deal with it?

[khvn26]

So, essentially, we want an option 2 then:

Add a ClientEvaluationContext type with the union value that will be used in all public interfaces. Envelope the simple trait values internally.

[kyle-ssg]

Yeah this sort of pattern feels quite familiar having used lots of SDKs in JS / keeps a basic implementation as terse as possible

[khvn26]

Ok, this is done.

[kyle-ssg]

Shouldn't need npm exec since it's a depedency, regardless, this errors for me - same error mentioned here

[khvn26]

Couldn't get it to work without npm exec. I'm running npm install --include=dev. Is there something I'm missing?