https://github.com/BowlingX/geschichte

zustand and immer based hook to manage query parameters
https://github.com/BowlingX/geschichte

Last synced: 4 days ago
JSON representation

zustand and immer based hook to manage query parameters

• Host: GitHub
• URL: https://github.com/BowlingX/geschichte
• Owner: BowlingX
• License: mit
• Created: 2019-11-30T14:49:18.000Z (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2024-06-06T13:58:24.000Z (5 months ago)
• Last Synced: 2024-09-24T10:11:01.926Z (about 2 months ago)
• Language: TypeScript
• Homepage:
• Size: 10.7 MB
• Stars: 76
• Watchers: 3
• Forks: 4
• Open Issues: 13
• Metadata Files:
  • Readme: README.md
  • Contributing: .github/CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-ccamel - BowlingX/geschichte - zustand and immer based hook to manage query parameters (TypeScript)

README

        
# 📖 Geschichte (/ɡəˈʃɪçtə/)

🇺🇦 Support Ukraine 🇺🇦 Help Provide Humanitarian Aid to Ukraine.

![CircleCI](https://img.shields.io/circleci/build/gh/BowlingX/geschichte)

![Codecov](https://img.shields.io/codecov/c/github/bowlingx/geschichte)

![npm](https://img.shields.io/npm/v/geschichte)

[![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)

`Geschichte` (german for History / Story / Tale) Let's you manage query-parameters with hooks.

Uses `immer` and `zustand` to manage the internal state.

Documentation & Demo: https://bowlingx.github.io/geschichte/index.html

API: https://bowlingx.github.io/geschichte/api/index.html

    yarn add geschichte

    npm install geschichte

## Basic Example

```typescript jsx

import { pm, factoryParameters, serializers } from 'geschichte'

import { GeschichteWithHistory } from 'geschichte/historyjs'

import { createBrowserHistory } from 'history'

const parameterConfig = {

  item: pm(

    'queryParameter',

    serializers.string /** a basic collection of serializers is availble, like date, int, float, arrays */,

    (value?: V, initialValue?: V) =>

      boolean /** define an optional skip function which will determine if the parameter will be included in the url or not */

  ),

  /* ... more keys, any depth. */

}

// default value is either an object or a factory () => defaultValue

const defaultValue = {

  item: 'defaultValue' /** it automatically skips null or default values*/,

}

// exports a hook (`useQuery`), and

// utility methods `createQueryString` that let's you create a query string based on the described object anywhere outside of components etc.

// `parseQueryString` let's you parse a query string into an object as defined in the `parameterConfig`.

const { useQuery, createQueryString, parseQueryString } = factoryParameters(

  parameterConfig,

  defaultValue /** optional namespace, (creates a prefix separated by a dot)*/

)

const Component = () => {

  const {

    values,

    pushState,

    replaceState,

    resetPush,

    resetReplace,

    createQueryString,

    batchReplaceState,

    batchPushState,

  } = useQuery()

  return (

    <>

       pushState((values) => void (values.item = 'newValue'))}

      >

        push new state

      

      

          replaceState((values) => void (values.item = 'anotherOne'))

        }

      >

        replace state

      

      reset (push) to defaults

      reset (replace) to defaults

      
{JSON.stringify(values)}

      
The current queryString: {createQueryString()}

    >

  )

}


const App = () => (

  

    

  

)

```

## Concept

`Geschichte` let's you describe and serialize an arbitrary object of any depth to your browsers query and history.

It takes care of updating the next state and current query in a efficient way using `immerjs`.

It works on both the browser and server side (with `createMemoryHistory`)

### Naming

I was inspired by `immer` and `zustand`, so I picked a fitting german name :).

## Agenda

- Add more tests

- Propper examples and documentation of the full API

- Describe Use-Cases

## Compability

It works out of the box with react-router (by providing the same `history` instance).

### Using with next.js

Nextjs support is build in, but requires a different Adapter.

#### With page router

```tsx

/** _app.tsx */

import React, { memo } from 'react'

import GeschichteForNextjs from 'geschichte/nextjs'

import type { AppProps } from 'next/app'

function App({ Component, pageProps }: AppProps) {

  return (

    

      

    

  )

}

export default memo(App)

```

#### With App router

You can use `Geschichte` with the app router as well (from `nextjs` 13).

```tsx

/** page.tsx */

import Geschichte from 'geschichte/nextjs-app-router'

import MoreComponentsWithClientSideState from '@/components/ClientComponents'

export default function Home() {

  return (

    

      My header

      

        

      

      My footer

    

  )

}

```