{"id":13566707,"url":"https://github.com/BowlingX/geschichte","last_synced_at":"2025-04-04T00:32:07.927Z","repository":{"id":36466064,"uuid":"225026872","full_name":"BowlingX/geschichte","owner":"BowlingX","description":"zustand and immer based hook to manage query parameters","archived":false,"fork":false,"pushed_at":"2025-03-21T13:03:56.000Z","size":11290,"stargazers_count":77,"open_issues_count":13,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T14:22:24.335Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BowlingX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-30T14:49:18.000Z","updated_at":"2025-03-21T13:01:01.000Z","dependencies_parsed_at":"2024-06-06T15:26:29.746Z","dependency_job_id":"c193708e-9ff7-494f-a6ff-22a348225ab2","html_url":"https://github.com/BowlingX/geschichte","commit_stats":{"total_commits":240,"total_committers":5,"mean_commits":48.0,"dds":"0.24583333333333335","last_synced_commit":"f6037227dc60511d66a88fed7efc558ca3318b4c"},"previous_names":[],"tags_count":158,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BowlingX%2Fgeschichte","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BowlingX%2Fgeschichte/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BowlingX%2Fgeschichte/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BowlingX%2Fgeschichte/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BowlingX","download_url":"https://codeload.github.com/BowlingX/geschichte/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247103290,"owners_count":20884023,"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":[],"created_at":"2024-08-01T13:02:15.067Z","updated_at":"2025-04-04T00:32:07.574Z","avatar_url":"https://github.com/BowlingX.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# 📖 Geschichte (/ɡəˈʃɪçtə/)\n\n🇺🇦 Support Ukraine 🇺🇦 Help Provide Humanitarian Aid to Ukraine.\n\n![CircleCI](https://img.shields.io/circleci/build/gh/BowlingX/geschichte)\n![Codecov](https://img.shields.io/codecov/c/github/bowlingx/geschichte)\n![npm](https://img.shields.io/npm/v/geschichte)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\n`Geschichte` (german for History / Story / Tale) Let's you manage query-parameters with hooks.\nUses `immer` and `zustand` to manage the internal state.\n\nDocumentation \u0026 Demo: https://bowlingx.github.io/geschichte/index.html\n\nAPI: https://bowlingx.github.io/geschichte/api/index.html\n\n    yarn add geschichte\n\n    npm install geschichte\n\n## Basic Example\n\n```typescript jsx\nimport { pm, factoryParameters, serializers } from 'geschichte'\nimport { GeschichteWithHistory } from 'geschichte/historyjs'\nimport { createBrowserHistory } from 'history'\n\nconst parameterConfig = {\n  item: pm(\n    'queryParameter',\n    serializers.string /** a basic collection of serializers is availble, like date, int, float, arrays */,\n    (value?: V, initialValue?: V) =\u003e\n      boolean /** define an optional skip function which will determine if the parameter will be included in the url or not */\n  ),\n  /* ... more keys, any depth. */\n}\n\n// default value is either an object or a factory () =\u003e defaultValue\nconst defaultValue = {\n  item: 'defaultValue' /** it automatically skips null or default values*/,\n}\n\n// exports a hook (`useQuery`), and\n// utility methods `createQueryString` that let's you create a query string based on the described object anywhere outside of components etc.\n// `parseQueryString` let's you parse a query string into an object as defined in the `parameterConfig`.\nconst { useQuery, createQueryString, parseQueryString } = factoryParameters(\n  parameterConfig,\n  defaultValue /** optional namespace, (creates a prefix separated by a dot)*/\n)\n\nconst Component = () =\u003e {\n  const {\n    values,\n    pushState,\n    replaceState,\n    resetPush,\n    resetReplace,\n    createQueryString,\n    batchReplaceState,\n    batchPushState,\n  } = useQuery()\n  return (\n    \u003c\u003e\n      \u003cbutton\n        onClick={() =\u003e pushState((values) =\u003e void (values.item = 'newValue'))}\n      \u003e\n        push new state\n      \u003c/button\u003e\n      \u003cbutton\n        onClick={() =\u003e\n          replaceState((values) =\u003e void (values.item = 'anotherOne'))\n        }\n      \u003e\n        replace state\n      \u003c/button\u003e\n      \u003cbutton onClick={resetPush}\u003ereset (push) to defaults\u003c/button\u003e\n      \u003cbutton onClick={resetReplace}\u003ereset (replace) to defaults\u003c/button\u003e\n      \u003cdiv\u003e{JSON.stringify(values)}\u003c/div\u003e\n      \u003cdiv\u003eThe current queryString: {createQueryString()}\u003c/div\u003e\n    \u003c/\u003e\n  )\n}\n\nconst App = () =\u003e (\n  \u003cGeschichteWithHistory history={createBrowserHistory()}\u003e\n    \u003cComponent /\u003e\n  \u003c/GeschichteWithHistory\u003e\n)\n```\n\n## Concept\n\n`Geschichte` let's you describe and serialize an arbitrary object of any depth to your browsers query and history.\nIt takes care of updating the next state and current query in a efficient way using `immerjs`.\nIt works on both the browser and server side (with `createMemoryHistory`)\n\n### Naming\n\nI was inspired by `immer` and `zustand`, so I picked a fitting german name :).\n\n## Agenda\n\n- Add more tests\n- Propper examples and documentation of the full API\n- Describe Use-Cases\n\n## Compability\n\nIt works out of the box with react-router (by providing the same `history` instance).\n\n### Using with next.js\n\nNextjs support is build in, but requires a different Adapter.\n\n#### With page router\n\n```tsx\n/** _app.tsx */\n\nimport React, { memo } from 'react'\nimport GeschichteForNextjs from 'geschichte/nextjs'\nimport type { AppProps } from 'next/app'\n\nfunction App({ Component, pageProps }: AppProps) {\n  return (\n    \u003cGeschichteForNextjs\u003e\n      \u003cComponent {...pageProps} /\u003e\n    \u003c/GeschichteForNextjs\u003e\n  )\n}\n\nexport default memo(App)\n```\n\n#### With App router\n\nYou can use `Geschichte` with the app router as well (from `nextjs` 13).\n\n```tsx\n/** page.tsx */\n\nimport Geschichte from 'geschichte/nextjs-app-router'\nimport MoreComponentsWithClientSideState from '@/components/ClientComponents'\n\nexport default function Home() {\n  return (\n    \u003cmain\u003e\n      \u003cheader\u003eMy header\u003c/header\u003e\n      \u003cGeschichte\u003e\n        \u003cMoreComponentsWithClientSideState /\u003e\n      \u003c/Geschichte\u003e\n      \u003cfooter\u003eMy footer\u003c/footer\u003e\n    \u003c/main\u003e\n  )\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBowlingX%2Fgeschichte","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBowlingX%2Fgeschichte","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBowlingX%2Fgeschichte/lists"}