https://github.com/nknapp/query-bin
A bin for arbitrary objects that can be queried like the DOM in https://testing-library.com/docs/queries/about#types-of-queries
https://github.com/nknapp/query-bin
Last synced: 3 months ago
JSON representation
A bin for arbitrary objects that can be queried like the DOM in https://testing-library.com/docs/queries/about#types-of-queries
- Host: GitHub
- URL: https://github.com/nknapp/query-bin
- Owner: nknapp
- License: other
- Created: 2024-04-21T15:25:55.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-30T13:40:25.000Z (about 1 year ago)
- Last Synced: 2025-03-16T15:23:43.146Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 250 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# query-bin
This README is generated via [./scripts/build-readme.js](./scripts/build-readme.js)
## Introduction
I like the [testing-library](https://testing-library.com/), and one reason for that is its [queries](https://testing-library.com/docs/queries/about#types-of-queries),
you have different queries like `byText` and `byRole`, each of which comes in variations like
- `query` and `queryAll` when finding a result is optional
- `get`, `getAll` when finding a result is mandatory
- `find` and `findAll` when you want to wait for the result to be there
You can add custom queries but just providing a `queryAll` function and some error messages, but sadly everything is set around the DOM and querying HTML elements.
I always wanted to have those queries for other use-cases, such as querying requests captured by [mock-service-worker](https://mswjs.io/).
This project builds an abstraction, so that you get those queries on lists of arbitrary objects. You provide the implementation for `queryAll` and
the rest will be built for you.
This project is not a finished test-utility for a given use case, but a basis so that you can build queries, for example around `mock-service-worker`.
## Installation
```bash
npm install query-bin
```
## Example
The [tests](./src/QueryBin.test.ts) give a broad overview over the functionality, but here is also more real-life
example.
```typescript
import { Queries, QueryBin } from "query-bin";
import { describe, expect, it } from "vitest";
type Method = "GET" | "PUT" | "POST" | "PATCH" | "DELETE";
interface Request {
method: Method;
url: string;
body?: Record;
}
const queries = {
byMethodAndUrl: function (method: Method, url: string) {
return {
test: (item) => item.method === method && item.url.includes(url),
noneFoundMessage: `Could not find requests with method ${method} and URL containing ${url}.`,
multipleFoundMessage: `Multiple requests found method ${method} and URL containing ${url}.`,
// optional
serializeForErrorMessage: (item) => JSON.stringify(item, null, 2),
};
},
// This typing should be improved. Consider this interface unstable...
} as const satisfies Queries;
const requests = new QueryBin(queries);
// Let's assume we have a component under test here.
describe("The Login component", () => {
it("logs in with the correct credentials", async () => {
// Simulate some requests. Those would normally originate from your component
requests.add({ method: "GET", url: "http://localhost:8080" });
setTimeout(() => {
requests.add({
method: "POST",
body: { user: "tom", password: "tom" },
url: "http://localhost:8080/login",
});
}, 500);
// "find" waits for a single request to appear, but fails if there have been multiple requests
const loginRequest = await requests.find.byMethodAndUrl("POST", "/login");
expect(loginRequest.body).toEqual({ user: "tom", password: "tom" });
});
});
```
## License
This project is licensed under the [MIT License](./LICENSE)
## Maintainance-free
I want to be honest. I am not good at maintaining OS projects these days. I have my turn with Handlebars.js, but now there is just to much going on in my life.
That is why I tried to make this project as "maintenance-free" as possible.
That said: If you find this package in 2026 or so and you tell yourself: "This is a dead project". Think about how much maintenance is really required for it:
- There are no dependendies except for development, and I tried to keep them at a minimum.
- The library is small and has a clear scope. There might be some features missing, but I think of it as almost complete.
- I don't see any way this library may impact security.
If you like to help me maintain and update dependencies, please contact me. At the moment, I tend not to be very active
though.
## Funding :coffee:
You can support me at
- [Liberapay](https://de.liberapay.com/nils.knappmeier/)
- [Paypal](https://www.paypal.com/donate/?hosted_button_id=GB656ZSAEQEXN)