{"id":13406795,"url":"https://github.com/timdeschryver/rx-query","last_synced_at":"2025-04-06T06:08:16.602Z","repository":{"id":46097036,"uuid":"277357823","full_name":"timdeschryver/rx-query","owner":"timdeschryver","description":null,"archived":false,"fork":false,"pushed_at":"2022-09-05T09:14:19.000Z","size":1416,"stargazers_count":201,"open_issues_count":0,"forks_count":15,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T05:06:23.102Z","etag":null,"topics":["angular","query","rxjs"],"latest_commit_sha":null,"homepage":"https://timdeschryver.github.io/rx-query/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timdeschryver.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-05T18:11:10.000Z","updated_at":"2025-03-28T21:23:56.000Z","dependencies_parsed_at":"2023-01-17T21:47:47.799Z","dependency_job_id":null,"html_url":"https://github.com/timdeschryver/rx-query","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timdeschryver%2Frx-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timdeschryver%2Frx-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timdeschryver%2Frx-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timdeschryver%2Frx-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timdeschryver","download_url":"https://codeload.github.com/timdeschryver/rx-query/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441051,"owners_count":20939239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","query","rxjs"],"created_at":"2024-07-30T19:02:39.501Z","updated_at":"2025-04-06T06:08:16.537Z","avatar_url":"https://github.com/timdeschryver.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"❗ This package is no longer being actively maintained. ❗\n\n# rx-query\n\n\u003e Batteries included fetching library\n\u003e Fetch your data with ease and give your users a better experience\n\n## Why\n\n- a better user experience\n- ease of use\n- configurable\n- promotes [Push-based Architecture](https://medium.com/@thomasburlesonIA/push-based-architectures-with-rxjs-81b327d7c32d)\n\n## Features\n\n- Retries\n- Cache\n- Refresh on interval, focus, online\n- Mutate data\n\n## Basics\n\n### Query without parameters\n\nThe most simple query is a parameter without parameters, it's just a wrapper around and Observable.\nThe `query` method expects a callback method to invoke the query.\n\n```ts\nimport { query } from \"rx-query\";\n\ncharacters$ = query(\"characters\", () =\u003e\n\tthis.rickAndMortyService.getCharacters(),\n);\n```\n\n### Query with static parameter\n\nA query that has a static parameter (a value that doesn't change over time), can be written in the same way as a query without parameters.\n\n```ts\nimport { query } from \"rx-query\";\n\ncharacters$ = query(\"character\", () =\u003e\n\tthis.rickAndMortyService.getCharacter(1),\n);\n```\n\nAn alternative way if to pass the static parameter as the first argument.\nThe query callback will then be invoked with the passed parameter.\n\n```ts\nimport { query } from \"rx-query\";\n\ncharacters$ = query(\"character\", 1, (characterId) =\u003e\n\tthis.rickAndMortyService.getCharacter(characterId),\n);\n```\n\n### Query with dynamic parameter\n\nIf a parameter can change over time (aka an Observable), it can also be passed as a parameter to `query`.\nWhen the input Observable emits a new value, the callback query will be invoked with the new input value.\n\n```ts\ncharacter$ = query(\n\t\"character\",\n\tthis.activatedRoute.params.pipe(map((p) =\u003e p.characterId)),\n\t(characterId: number) =\u003e this.rickAndMortyService.getCharacter(characterId),\n);\n```\n\n### Query status\n\nA query can have the following:\n\n- `loading`: when the query is being invoked and hasn't responded yet\n- `refreshing`: when the query is being invoked, and there's a cached value (the cached value gets refreshed when the query is successful)\n- `success`: when the query returns a successful response\n- `error`: when the query threw an error\n- `mutating`: when a [mutation](#mutate) is in progress\n- `mutate-error`: when a [mutation](#mutate) threw an error\n\nIn the view layer you will often see a structure like this, with a segment to represent each status:\n\n```html\n\u003cng-container *ngIf=\"characters$ | async as characters\"\u003e\n\t\u003cng-container [ngSwitch]=\"characters.status\"\u003e\n\t\t\u003cdiv *ngSwitchCase=\"'loading'\"\u003eLoading ... ({{ characters.retries }})\u003c/div\u003e\n\n\t\t\u003cdiv *ngSwitchCase=\"'error'\"\u003e\n\t\t\tSomething went wrong ... ({{ characters.retries }})\n\t\t\u003c/div\u003e\n\n\t\t\u003cdiv *ngSwitchDefault\u003e\n\t\t\t\u003cul\u003e\n\t\t\t\t\u003cli *ngFor=\"let character of characters.data\"\u003e\n\t\t\t\t\t\u003ca [routerLink]=\"character.id\"\u003e{{ character.name }}\u003c/a\u003e\n\t\t\t\t\u003c/li\u003e\n\t\t\t\u003c/ul\u003e\n\t\t\u003c/div\u003e\n\t\u003c/ng-container\u003e\n\u003c/ng-container\u003e\n```\n\n### Refresh a query\n\nUse `refreshQuery` to trigger a new fetch from a previously contructed query.  \nNote that the key _and_ parameters provided to `refreshQuery` should be exactly the same!\nThe following will refetch the data and update the cache.\n\n```ts\nimport { query, refreshQuery } from \"rx-query\";\n\ncharacter$ = query(\"character\", 1, (id) =\u003e\n\tthis.rickAndMortyService.getCharacter(id),\n);\n\n// On some event\nrefreshQuery(\"character\", 1);\n```\n\n## Output\n\n```ts\nexport type QueryOutput\u003cQueryResult = unknown\u003e = {\n\tstatus: Readonly\u003c\n\t\t| \"idle\"\n\t\t| \"success\"\n\t\t| \"error\"\n\t\t| \"loading\"\n\t\t| \"refreshing\"\n\t\t| \"mutating\"\n\t\t| \"mutate-error\"\n\t\u003e;\n\tdata?: Readonly\u003cQueryResult\u003e;\n\terror?: Readonly\u003cunknown\u003e;\n\tretries?: Readonly\u003cnumber\u003e;\n\tmutate: (data: QueryResult) =\u003e void;\n};\n```\n\n### `status`\n\nThe current status of the query.\n\n### `data`\n\nThe result of the query, or the cached result.\n\n### `error`\n\nThe error object returned by the query.\nOnly available in the error status.\n\n### `retries`\n\nNumber of query retries.\nIs reset every time data is fetched.\nAvailable on all statuses.\n\n### `mutate`\n\nThe mutate method to mutate the current query.\nThis is optimistic, the data of the query will be modified while the request is pending.\nWhen the request resolves, the query data will be refreshed with the server data.\nIf the request fails, the original data of the query will be restored.\n\n## Config\n\n```ts\nexport type QueryConfig = {\n\tretries?: number | ((retryAttempt: number, error: unknown) =\u003e boolean);\n\tretryDelay?: number | ((retryAttempt: number) =\u003e number);\n\trefetchInterval?: number | Observable\u003cunknown\u003e;\n\trefetchOnWindowFocus?: boolean;\n\trefetchOnReconnect?: boolean;\n\tstaleTime?: number;\n\tcacheTime?: number;\n\tmutator?: (data: QueryResult, params: QueryParam) =\u003e QueryResult;\n};\n```\n\n### `retries`\n\nThe number of retries to retry a query before ending up in the error status.\nAlso accepts a callback method `((retryAttempt: number, error: unknown) =\u003e boolean)` to give more control to the consumer.\nWhen a query is being retried, the status remains in the original (loading or refreshing) status.\n[Example](https://timdeschryver.github.io/rx-query/?path=/story/rx-query--error).\n\nDefault: `3`\n\nUsage:\n\n```ts\n{\n\tretries: 3,\n}\n\n{\n  // Never retry when 3 attempts has been made already, or when the query is totally broken\n\tretries: (retryAttempt: number, error: string) =\u003e\n\t\tretryAttempt \u003c 3 \u0026\u0026 !error !== \"Totally broken\",\n}\n```\n\n### `retryDelay`\n\nThe delay in milliseconds before retrying the query.\nAlso accepts a callback method `((retryAttempt: number) =\u003e number)` to give more control to the consumer.\n[Example](https://timdeschryver.github.io/rx-query/?path=/story/rx-query--error).\n\nDefault: `(n) =\u003e (n + 1) * 1000`\n\nUsage:\n\n```ts\n{\n\tretryDelay: 100,\n}\n\n{\n  // Increase the delay with 1 second after every attempt\n\tretryDelay: (retryAttempt) =\u003e retryAttempt * 1000,\n}\n```\n\n### `refetchInterval`\n\nInvoke the query in the background every x milliseconds, and emit the new value when the query is resolved.\n[Example](https://timdeschryver.github.io/rx-query/?path=/story/rx-query--refresh-on-interval).\n\nDefault: `Infinity`\n\nUsage:\n\n```ts\n{\n  // every 5 minutes\n\trefetchInterval: 6000 * 5,\n}\n```\n\n### `refetchOnWindowFocus`\n\nInvoke the query in the background when the window is focused, and emit the new value when the query is resolved.\n[Example](https://timdeschryver.github.io/rx-query/?path=/story/rx-query--refresh-on-focus).\n\nDefault: `true`\n\nUsage:\n\n```ts\n{\n\trefetchOnWindowFocus: false,\n}\n```\n\n### `refetchOnReconnect`\n\nInvoke the query when the client goes back online.\n\nDefault: `true`\n\nUsage:\n\n```ts\n{\n\trefetchOnReconnect: false,\n}\n```\n\n### `cacheTime`\n\nSet the cache time (in milliseconds) for a query key.\n[Example](https://timdeschryver.github.io/rx-query/?path=/story/rx-query--type-ahead).\n\nDefault: `30_000` (5 minutes)\n\nUsage:\n\n```ts\n{\n\tcacheTime: 60_000,\n}\n```\n\n### `staleTime`\n\nDecides when a query should be refetched when it receives a trigger.\n\nDefault: `0`\n\nUsage:\n\n```ts\n{\n\tstaleTime: 60_000,\n}\n```\n\n### `mutator`\n\nThe `mutator`, is the method that will be invoked when the `mutate` method is called.\nIt receives the data passed to the `mutate` method and the current params of the query.\n[Example](https://timdeschryver.github.io/rx-query/?path=/story/rx-query--mutate).\n\nDefault: `mutator: (data) =\u003e data`\n\nUsage:\n\n```ts\n{\n  mutator: (data, queryOptions) =\u003e\n    this.http\n      .post(`/persons/${queryOptions.queryParameters.id}`, data)\n      // 👇 important to let the request throw in order to rollback\n      .pipe(catchError((err) =\u003e throwError(err.statusText))),\n}\n```\n\n### Config override\n\nTo override the defaults for all queries, you can use the `setQueryConfig` method.\n\n```ts\nsetQueryConfig({\n\trefetchOnWindowFocus: false,\n\tretries: 0,\n\tcacheTime: 60_000,\n});\n```\n\n## Inspiration\n\nThis library is inspired by:\n\n- [react-query](https://github.com/tannerlinsley/react-query), written by [Tanner Linsley](https://twitter.com/tannerlinsley)\n- [vercel/swr](https://github.com/vercel/swr)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimdeschryver%2Frx-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimdeschryver%2Frx-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimdeschryver%2Frx-query/lists"}