diff --git a/docs/blog/2024-07-20-new-beginnings.md b/docs/blog/2024-07-20-new-beginnings.md new file mode 100644 index 00000000..09d7f5f7 --- /dev/null +++ b/docs/blog/2024-07-20-new-beginnings.md @@ -0,0 +1,86 @@ +--- +title: A new beginning for fetch-mock +description: What's changing, and why +slug: new-beginning +authors: + - name: Rhys Evans + title: fetch-mock maintainer + url: https://www.wheresrhys.co.uk +hide_table_of_contents: false +--- + +Long time users of fetch-mock may have noticed two things recently + +1. This documentation website has had a makeover +2. I'm actually maintaining it again + +These two things are closely related. Allow me to explain + +## Why I stopped maintaining fetch-mock + +As well as the perennial issue familiar to open source maintainers - working long hours for no pay, and not every user being particularly considerate in their feedback - I was also quite frustrated with the node.js and testing landscape. + +ECMAScript modules were slowly landing, and causing a lot of disruption and conflicts with different toolchains. Increasingly bug reports were about these conflicts in the wider ecosystem, rather than my code specifically. Really not a lot of fun to fix. Additionally, choices I'd made in fetch-mock's API design predated the arrival of the testing leviathan that is Jest. In trying to play nicely with Jest I found myself implementing hack after hack, and still being at the mercy of changes to Jest's internals. And don't even get me started on the demands to support typescript. + +I wasn't being paid and I increasingly felt like I wasn't maintaining a tool, rather piloting a rickety, outdated craft through choppy waters. + +Who needs that in their life? + +## Why I'm back + +I've been unemployed for the last ~4 months, taking stock of my career and where it might head next. Early on in this lull the people from [TEA protocol](https://app.tea.xyz/) got in touch. It's a new way of funding open source and, while I am sceptical that it will catch on (though I hope I'm wrong), it did get me thinking a bit more about open source and fetch-mock. After 3 months of not touching a text editor I figured I also needed to be careful of not getting too rusty; a conversation with a friend uncovered that I'd forgotten the keyboard shortcut to clear the terminal. + +## What I'm working on + +I began by setting out some high level principles to guide the work. + +1. Be modern - support ESM, native global fetch & types by default. Pay as little attention to supporting other patterns as possible. +2. Avoid making API choices that conflict with current, or future, testing toolchains. Remove any APIs that already conflict. +3. Allow users to use fetch-mock in a way that is idiomatic to their choice of toolchain + +Guided by these I came up with a plan of attack: + +### 1. Migrate everything to ESM and to global native fetch + +This was released as fetch-mock@10 about a month ago + +### 2. Turn fetch-mock into a monorepo + +This makes it possible to publish multiple packages aimed at different use cases and environments. I now use conventional commits and release-please, which took a while to get right. + +I did this last week + +### 3. Publish a @fetch-mock/core library + +This contains only the functionality that I'm confident other testing tools won't implement, e.g. it does not contain functionality for actually replacing `fetch` with a mock implementation; testing libraries generally have their own APIs for doing that. + +I did this a few days ago + +### 4. Publish a suite of @fetch-mock libraries + +Each will be targeted at a particular toolchain, such as @fetch-mock/standalone, @fetch-mock/jest, @fetch-mock/vitest... + +I've not started on this yet. + +## Why the new website + +Two reasons + +1. With the new @fetch-mock suite there'll be a lot more to document, and there'll also need to be very clear separation between legacy (fetch-mock) and modern (@fetch-mock) documentation. +2. Static site generators have come a long way since I first put the fetch-mock site together, so worth looking again at the available tools. + +So you are now reading from a new site I put together with docusaurus. I tried astro/starlight too, but it doesn't yet support having multiple different documentation subsites hosted within a single site. Docusaurus does this very well. + +While @fetch-mock/core is not really intended for direct use, you _could_ e.g. do something like this in jest. + +```js +import fetchMock from '@fetch-mock/core' +jest.mock(global, 'fetch', fetchMock.fetchHandler) + +it('works just fine', () => { + fetchMock.route('http://here.com', 200); + await expect (fetch('http://here.com')).resolves +}) +``` + +I'd be very happy if people could start giving the library and its docs an experimental little whirl. diff --git a/docs/docs/@fetch-mock/core/configuration.md b/docs/docs/@fetch-mock/core/configuration.md index 925c8e63..a0aac685 100644 --- a/docs/docs/@fetch-mock/core/configuration.md +++ b/docs/docs/@fetch-mock/core/configuration.md @@ -38,7 +38,6 @@ Match calls that only partially match a specified body json. Uses the [is-subset `fetch`, `Headers`, `Request`, `Response` can all be set on the configuration object, allowing fetch-mock to mock any implementation of `fetch`, e.g. `node-fetch`. e.g. ```js - import { default as fetch, Headers, Request, Response } from 'node-fetch'; import fetchMock from 'fetch-mock'; diff --git a/docs/docs/@fetch-mock/core/route/matcher.md b/docs/docs/@fetch-mock/core/route/matcher.md index 4f5c1b2f..21c2bcfe 100644 --- a/docs/docs/@fetch-mock/core/route/matcher.md +++ b/docs/docs/@fetch-mock/core/route/matcher.md @@ -24,6 +24,7 @@ All of the following can be passed in directly as the `matcher` argument or as t ### Full url `{String|URL}` + Match an exact url. Can be defined using a string or a `URL` instance, e.g. `"http://www.site.com/page.html"` The value `*` can be used to match any url @@ -31,31 +32,37 @@ The value `*` can be used to match any url ### begin:... `{String}` + Match a url beginning with a string, e.g. `"begin:http://www.site.com"` ### end:... `{String}` + Match a url ending with a string, e.g. `"end:.jpg"` ### path:... `{String}` + Match a url which has a given path, e.g. `"path:/posts/2018/7/3"` ### glob:... `{String}` + Match a url using a glob pattern, e.g. `"glob:http://*.*"` ### RegExp `{RegExp}` + Matches a url that satisfies a regular expression, e.g. `/(article|post)\/\d+/` ### express:... `{String}` + Match a url that satisfies an [express style path](https://www.npmjs.com/package/path-to-regexp), e.g. `"express:/user/:user"` #### Matching express param values diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 02d997e6..ca2870a5 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -69,6 +69,7 @@ const config = { label: '@fetch-mock docs', className: 'new', }, + { to: 'blog', label: 'Blog', position: 'right' }, { href: 'https://github.com/wheresrhys/fetch-mock', label: 'GitHub',