Enrich the docs when it comes to types

[ahmed-hritani]

Follow up PR after #269

[iambumblehead]

please move the example from the javascript code block to a separated (new) typescript code block

[iambumblehead]

Please see suggested changes.

[iambumblehead]

Remove the JavaScript and TypeScript labels. Subjectively, I don't they are necesssary.

[ahmed-hritani]

I disagree, otherwise we would have merged the two section together, it's your call tho.

[iambumblehead]

Include all of imports needed for the example, and separate the imports from the first test with an empty newline. Remove the dangling comma after 'HARD',

import test from 'node:test'
import assert from 'node:assert'
import esmock from 'esmock'
import type MinecraftWorld from '../src/minecraftWorld.js'

test('allows you to specify the type of returned exports', async () => {

[ahmed-hritani]

Remove the dangling comma after 'HARD',

This is actually a best practice, see here.

[iambumblehead]

There is a lint plugin that should int the README but does not seem to be working fixed: #275

[iambumblehead]

I don't believe this functionality needs to be documented in the README.

The ability to use typescript types is expected from esmock, and therefore it is not really a "feature" that needs to be document or explained. Rather, it is a bug if esmock types are specified incorrectly so as to not allow using import types.

The other examples in the README are needed, because they demonstrate features of esmock used for mocking modules in unit tests which is the purpose of esmock.

What do you think @koshic @ahmed-hritani?

[koshic]

@iambumblehead, documentation should describe all 'non-default' behavior aspects.

For TS, we expect that any function has some return type (void, undefined, any, doesn't matter). And based on excellent examples, it's easy to understand that return type is 'any', as the same as for the import() statement.

What is not default and not expected - esmock function has generic signature and can accept optional type parameter. It's a 'feature' in TS terms, some piece of code in .d.ts file. So, I think it should be documented.

Do we need separate example or just 'TS usage' section? Don't know, it's a matter of taste.

[iambumblehead]

Adding an import README example sounds like a good idea, based on the reasoning above.

[ahmed-hritani]

There is a lint plugin that should int the README but does not seem to be working fixed: #275

Looks like it's too strict now, see here.

[iambumblehead]

Looks like it's too strict now, see here.

Thanks. Let's close this PR and use the typescript example added from a different PR #278

[ahmed-hritani]

Great job, you just saw somebody's idea, made it tooo hard for them to do it, then copied it and did it yourself, this is the definition of toxic behaviour.

Your PR here also shows how "open" this open source repo is.

[koshic]

@ahmed-hritani if you really want to discuss it (because I strongly disagree) - let's create some thread outside of that PR (or even GitHub).

[iambumblehead]

Some observations,

• Enrich the docs when it comes to types #269 When your first PR was reverted, you replied with a new PR "Update contributing docs to save people's time" and basically this implies your time was wasted; something is wrong with esmock,
• Update contributing docs to save people's time #273 (comment) You told us what should be in CONTRIBUTING.md and how PRs should be handled; something is wrong with esmock,
• update README to work with markdown lint plugin #275 When the README linting was fixed, you told us the linting was too-strict Enrich the docs when it comes to types #272 (comment); something is wrong with esmock,
• update CONTRIBUTING.md #277 When I updated the CHANGELOG to express my feeling, you commented the repo was open source unfriendly; something is wrong with esmock,
• update CONTRIBUTING.md #277 You disagreed with review comments on this PR and told us they went against best practices; something is wrong with esmock

Do you always enter new projects telling people what to do? What authority qualifies you as an expert?

My own un-solicited advice,

• consider you may be wrong,
• ask questions first, state opinions later or never,
• be flexible, allow other people to guide and discuss,
• appreciate what is good, focus less on what is bad

[ahmed-hritani]

Some observations,
#269 When your first PR was reverted, you replied with a new PR "Update contributing docs to save people's time" and basically this implies your time was wasted; something is wrong with esmock,
#273 (comment) You told us what should be in CONTRIBUTING.md and how PRs should be handled; something is wrong with esmock,
#275 When the README linting was fixed, you told us the linting was too-strict #272 (comment); something is wrong with esmock,
#277 When I updated the CHANGELOG to express my feeling, you commented the repo was open source unfriendly; something is wrong with esmock,
#277 You disagreed with review comments on this PR and told us they went against best practices; something is wrong with esmock
Do you always enter new projects telling people what to do? What authority qualifies you as an expert?
My own un-solicited advice,
consider you may be wrong,
ask questions first, state opinions later or never,
be flexible, allow other people to guide and discuss,
appreciate what is good, focus less on what is bad

Hmm, your "obersvations" are not so accurate, let me show you how:
1- If you would think about my PR message negatively you would surely reach such conclusion, however if you think about other people's time (me and others how could contribute) you would see directly how necessary the PR was and accurate the message is.
2- The content of my PR is actually COPIED from your message here, please feel free to take a look to refresh your memory, I will also copy it here so you could see it quicker
"@ahmed-hritani would you remake the README example to follow these points?

The example should work. It should be possible to write a real unit-test that passes with the example,
Each line less than 70 characters wide. This is a special optimization for the README so the examples fit inside most laptop screens without scrollbars,
The example should be slightly interesting, if possible, and should use a unicode emoji"
3- When I said that the linting is "too strict", I was seeking help, I faced a "weird" error and I thought that by reaching out to you (as I did) you would provide an explanation or add a suggestion review, evidently I was wrong.
4- First time hearing about somebody expressing their feelings through the CONTRIBUTING.md file, the file should follow the guidelines suggested by GitHub, when you change it to be "Collaborators may reject or revert any issue or PR for any reason." you are actually making it open source unfriendly.
5- Not sure if it's wrong now to disagree with CONTRIBUTES, very fruitful outcomes could come out of disagreements, as a matter of fact, your review comment was a disagreement in the first place that I ACCEPTED and modified the PR to match, however I added my opinion PLUS a link to google's javascript guideline.

I think that you could actually use the "advices" that you've added for your own sake, on top of that, you did actually waste my time, when you merge and revert multiple times as you do, when you review the same PR multiple times when you could have done so in one time you waste my time, when you CLOSE my PR that I've invested my time with and COPY my idea and add it with YOUR PR you have both wasted my time and stole it.

The sole reason that I've contributed to the repo was because I liked the project and I wanted it to be better, that's how operation systems were built btw, however, it looks like you don't like it when people try to do that, therefore I will leave you to it and wish you the best of luck.

[iambumblehead]

Hmm, your "obersvations" are not so accurate [...]

something is wrong with esmock

[...] therefore I will leave you to it and wish you the best of luck.

please