Add type definitions for recoil

[csantos42]

Please fill in this template.

• Use a meaningful title for the pull request. Include the name of the package modified.
• Test the change in your own code. (Compile and run.)
• Add or edit tests to reflect the change. (Run with npm test.)
• Follow the advice from the readme.
• Avoid common mistakes.
• Run npm run lint package-name (or tsc if no tslint.json is present).

Select one of these and delete the others:

If adding a new definition:

• The package does not already provide its own types, or cannot have its .d.ts files generated via --declaration
• If this is for an NPM package, match the name. If not, do not conflict with the name of an NPM package.
• Create it with dts-gen --dt, not by basing it on an existing project.
• Represents shape of module/library correctly
• tslint.json should be present and it shouldn't have any additional or disabling of rules. Just content as { "extends": "dtslint/dt.json" }. If for reason the some rule need to be disabled, disable it for that line using // tslint:disable-next-line [ruleName] and not for whole package so that the need for disabling can be reviewed.
• tsconfig.json should have noImplicitAny, noImplicitThis, strictNullChecks, and strictFunctionTypes set to true.

[typescript-bot]

@csantos42 Thank you for submitting this PR! I see this is your first time submitting to DefinitelyTyped 👋 - keep an eye on this comment as I'll be updating it with information as things progress.

Code Reviews

This PR adds a new definition, so it needs to be reviewed by a DT maintainer before it can be merged.

• recoil on npm
• recoil on unpkg

Status

• ✅ No merge conflicts
• ✅ Continuous integration tests have passed
• ✅ Only a DT maintainer can merge changes when there are new packages added

Once every item on this list is checked, I'll ask you for permission to merge and publish the changes.

---

Diagnostic Information: What the bot saw about this PR

{
  "type": "info",
  "now": "-",
  "pr_number": 44756,
  "author": "csantos42",
  "owners": [],
  "dangerLevel": "ScopedAndConfiguration",
  "headCommitAbbrOid": "f6ddc8d",
  "headCommitOid": "f6ddc8da25b2f47bf62aa132a87fd2ce24d82eb4",
  "mergeIsRequested": false,
  "stalenessInDays": 0,
  "lastCommitDate": "2020-05-29T18:05:09.000Z",
  "lastCommentDate": "2020-05-29T17:40:30.000Z",
  "reviewLink": "https://github.com/DefinitelyTyped/DefinitelyTyped/pull/44756/files",
  "hasMergeConflict": false,
  "authorIsOwner": false,
  "isFirstContribution": true,
  "popularityLevel": "Well-liked by everyone",
  "anyPackageIsNew": true,
  "packages": [
    "recoil"
  ],
  "files": [
    {
      "filePath": "types/recoil/index.d.ts",
      "kind": "definition",
      "package": "recoil"
    },
    {
      "filePath": "types/recoil/recoil-tests.ts",
      "kind": "test",
      "package": "recoil"
    },
    {
      "filePath": "types/recoil/tsconfig.json",
      "kind": "package-meta",
      "package": "recoil"
    },
    {
      "filePath": "types/recoil/tslint.json",
      "kind": "package-meta",
      "package": "recoil"
    }
  ],
  "hasDismissedReview": false,
  "ciResult": "pass",
  "lastReviewDate": "2020-05-29T18:19:28.000Z",
  "reviewersWithStaleReviews": [
    {
      "reviewedAbbrOid": "22328be",
      "reviewer": "smmoosavi",
      "date": "2020-05-21T00:52:24Z"
    },
    {
      "reviewedAbbrOid": "53fcac4",
      "reviewer": "acutmore",
      "date": "2020-05-16T16:48:28Z"
    }
  ],
  "approvalFlags": 4,
  "isChangesRequested": false
}

[danger-public]

Inspecting the JavaScript source for this package found some properties that are not in the .d.ts files.
The check for missing properties isn't always right, so take this list as advice, not a requirement.

recoil (unpkg)

was missing the following properties:

1. useSetUnvalidatedAtomValues_UNSTABLE
2. useTransactionObservation_UNSTABLE
3. useTransactionSubscription_UNSTABLE

Generated by 🚫 dangerJS against f6ddc8d

[typescript-bot]

👋 Hi there! I’ve run some quick measurements against master and your PR. These metrics should help the humans reviewing this PR gauge whether it might negatively affect compile times or editor responsiveness for users who install these typings.

Let’s review the numbers, shall we?

These typings are for a package that doesn’t yet exist on master, so I don’t have anything to compare against yet! In the future, I’ll be able to compare PRs to recoil with its source on master.

Comparison details 📊

Batch compilation
Type count	16266
Assignability cache size	34408
Language service measurements
Samples taken	135
Identifiers in tests	135
getCompletionsAtPosition
Mean duration (ms)	300.8
Mean CV	9.5%
Worst duration (ms)	401.6
Worst identifier	loadable
getQuickInfoAtPosition
Mean duration (ms)	306.6
Mean CV	9.2%
Worst duration (ms)	378.2
Worst identifier	getValue
System information
Node version	v12.16.3
CPU count	2
CPU speed	2.095 GHz
CPU model	Intel(R) Xeon(R) Platinum 8171M CPU @ 2.60GHz
CPU Architecture	x64
Memory	6.8 GiB
Platform	linux
Release	4.15.0-1082-azure

[davidmccabe]

I'm not too familiar with TypeScript but I don't see any indicator of covariance for the read-only values. Is that part of this?

[Albert-Gao]

@davidmccabe Do you mean to mark the argument of the setValue as readonly?

Sadly, the keyword readonly in TS can only be applied to a property of an object, does not apply to an argument of a function. and the issue is closed :(

microsoft/TypeScript#18497

[Dreamacro]

can export the type like RecoilState? Sometimes need to wrap useRecoilState

[aappddeevv]

I'm not sure the RecoilValue type is right. If RecoilValue can be used in useRecoilState then it should be readwrite. But the definition is RecoilValue = RecoilValueReadOnly|RecoilState and useRecoilState(RecoilValue). Did I read that correctly? I'm not sure I'm looking in the right place.

I think I read the wrong code..it does look like it is set correctly.

[smmoosavi]

RecoilState should be both covariance and contravariance. because it is both readable and writable.

but right now any RecoilState can be assigned to any RecoilState without any error.

[typescript-bot]

@smmoosavi, @acutmore Thank you for reviewing this PR! The author has pushed new commits since your last review. Could you take another look and submit a fresh review?

[kolodny]

I've done some work independently, not realizing this PR existed. I have a couple of the tricky cases worked out. The types are pretty well tested and are quite robust. Feel free to incorporate anything from that branch to this PR.

kolodny@7bae698#diff-536a520cf5eea35920533711cf917823

[typescript-bot]

@amcasey, @smmoosavi, @acutmore Thank you for reviewing this PR! The author has pushed new commits since your last review. Could you take another look and submit a fresh review?

[amcasey]

@csantos42 Thanks! I think that addresses @sheetalkamat's concern. She knows more about modules resolution than I do and may be able to suggest a way to get back your tidy multi-file structure, but it seems like there's enough excitement around these types to handle that in a separate PR.

Did you have a chance to look at @kolodny and pull out possible improvements?

@smmoosavi @Gregoor @acutmore @renanmav Remaining concerns?

[csantos42]

@amcasey yes, we should be good to go on our end :)

[smmoosavi]

Remaining concerns?

@amcasey the issue with RecoilValueReadOnly fixed. but RecoilState has a problem yet. contravariance is not checked in writable states

problem

const stringAtom: RecoilState<string> = {} as any;
const stringOrNumberAtom: RecoilState<string|number> = stringAtom // no error. it should detect error, it should check contravariance. because RecoilState is writable

const [value, setValue] = useRecoilState<string|number>(stringOrNumberAtom)
setValue(5) // no error, ok, SetterOrUpdater<string|number> should accept number

const value2 = useRecoilValue(stringAtom) // expect value2 should be string, but it is 5

solution

we can add another key to writable states to check contravariance.
see solution in playground playground
there is other solution with one extra key: solution2

type NodeKey = string
declare type CB<T> = (t: T) => void;

export class AbstractRecoilValue<T> {
    ' covariance-value': [T];
    ' contravariance-value': [CB<T>];
    key: NodeKey;
    constructor(newKey: NodeKey);
}

export class AbstractRecoilValueReadonly<T> {
    ' covariance-value': [T];
    key: NodeKey;
    constructor(newKey: NodeKey);
}

also tag and valTag doesn't exist in js, it's better to have unintuitive names started with space, and with this new suggested types we can remove tag key.

[csantos42]

thanks @smmoosavi ! Clever-- I didn't think of using a function type to ensure contravariance, I'll make that change now :)

[amcasey]

I think @smmoosavi's concerns have been addressed and there's tremendous interest in this PR, so I'm going to preemptively merge it. @csantos42, please be responsive to subsequent feedback if it turns out I've merged too soon.

[csantos42]

Thanks a lot @amcasey! And thanks to everyone that reviewed/contributed/commented on this PR! I'll be sure to monitor any subsequent feedback promptly

[itsMapleLeaf]

Recoil 0.0.8 is published on npm, but the types are still missing a few things, like atomFamily and selectorFamily. I wouldn't mind adding those myself, I guess checking to see if someone's already working on it

[csantos42]

hi @kingdaro, I'm working on this now, should be done some time tonight. Thanks!