implement untrack API

[dai-shi]

closes #23.

• rename function
• add test
• add example
• update docs

[dai-shi]

I'm thinking of renaming the function. It may sound too general.
I would expect we wouldn't need this API for most (or just some) use cases.
And, if we create a custom hook, it won't shown in a render function.

So, let's make it more descriptive.
Maybe, getUntrackedObject, or getUntracked.

[dai-shi]

untrack sounds like stopping tracking, which is not what it does.

[4nte]

getUntrackedObject is verbose and most descriptive of all, which may help users to understand it easier. +1

IMO tracking is an implementation detail of the library and therefore any name we give to this function will seem odd / out of place to a user as they will feel that they're doing some extra work for the library. I understand it's a limitation, for now, hopefully, there's a better solution for the future.

[dai-shi]

Yeah, this function and the other one trackMemo is exposing implementation details. We would probably build utility functions or middleware based on them in the future. These are primitives. It's a good start.

[4nte]

since the use of getUntrackedObject is limited to objects only the type definition can be improved to:

export const getUntrackedObject: <T extends object>(obj: T) => T;

Unfortunately, array is a typeof object so it will not throw an error but at least it will exclude the primitive types.

See http://www.typescriptlang.org/play/#code/GYVwdgxgLglg9mABAcwKZQKpigJwIYQDWqAJgPIBGAVqtADwAqiqAHlKmCQM6JzW1QAfAAo+VAFwMAlJMQBvAFCJliHOhA4kYgNwKAvgoVpM2fEVKUa0YXMTA4ccYgCMiPVN3GsuAsXL9rAG1nAF0PRAB6COVxYUMvU18LAKhhZw8jdG8zP0sBYQAiezgCjISfc38rVPASVGAYMFIyrMTKvOswEAAbbpaTCtyU4VwQVA8gA

[dai-shi]

since the use of getUntrackedObject is limited to objects

Uh, no, I would like to accept any value. That would make developing custom dispatch easier.
It also accepts arrays.

OK, that's a good sign for adding comments. Will do.

[dai-shi]

Do you suggest to change the function name if it accepts non-object values?

[4nte]

I think it might be for the better to leave it as getUntrackedObject since it's intended
to be used for objects - might reduce misusage of it.

[4nte]

Uh, no, I would like to accept any value. That would make developing custom dispatch easier.

How about 2 functions are exported?
getUntrackedObject should do exactly what it does -- attempt to untrack an object.
getUntracked untrack any value, not limited to objects.

We can refactor getUntrackedObject to omit the if(isPlainObj(obj)) check and to assume that given parameter is an object,

And introduce another API function getUntracked which is safe to call with any value. It's implementation should do the isPlainObj(obj) check and call the getUntrackedObject.

This way, getUntrackedObject will have less overhead for direct users.

Edit:
Or naming them like this?

export const untrack = <T extends object>(obj: T): T = {}
export const getUntrackedObject = <T>(obj: T): T = {}

[dai-shi]

Thanks for you suggestion. But, I wouldn't take that approach because of various reasons.

1. I would prefer to export less functions as possible. getUntrackedObject is much safer and wouldn't be misused.
2. I would like to hide implementation details. isPlainObject is actually an implementation detail. I could imagine that would be changed in the future. So, I don't want users of this library to assume what is an object that would be tracked.
3. As far as I understand, the current implementation of isPlainObject is pretty lightweight, and it wouldn't be a bottleneck. If, in the future, we find use cases that this would impact performance, we can consider exporting another function for optimization.

I hope those make sense.

[dai-shi]

That would make developing custom dispatch easier.

I might be wrong about this. I will try it in an example.

This is what I've got.

react-tracked/examples/10_untracked/src/store.ts

Lines 84 to 96 in e6f7e1d

	const untrackDeep = <T>(obj: T) => {
	if (typeof obj !== 'object' || obj === null) return obj;
	const untrackedObj = getUntrackedObject(obj);
	if (untrackedObj !== obj) return untrackedObj;
	const newObj = {} as T;
	let modified = false;
	Object.entries(obj).forEach(([k, v]) => {
	const vv = untrackDeep(v);
	newObj[k as keyof T] = vv;
	modified = modified || v !== vv;
	});
	return modified ? newObj : obj;
	};

[dai-shi]

Hm, it can be easier for getUntrackedObject to return null if obj is not a proxy.

[dai-shi]

Merging this. Thanks for the feedback.