# @monoid-dev/use-search

> React hook with sanitized and parsed search string.

Latest version **0.1.1** (published 2021-09-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @monoid-dev/use-search
pnpm add @monoid-dev/use-search
yarn add @monoid-dev/use-search
bun add @monoid-dev/use-search
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2021-09-18 |
| First published | 2021-09-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 965.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Chenyu Wang |
| Maintainers | chenyuwang |
| Keywords | typescript, io-ts, url, type, browser, react |

## Links

- npm: https://www.npmjs.com/package/@monoid-dev/use-search
- Repository: https://github.com/MonoidDev/use-search
- npm.io page: https://npm.io/package/@monoid-dev/use-search

## Dependencies (3)

- [fp-ts](https://npm.io/package/fp-ts.md) ^2.11.2
- [io-ts](https://npm.io/package/io-ts.md) ^2.2.16
- [query-string](https://npm.io/package/query-string.md) ^7.0.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2021-09-18
- 0.1.0 — 2021-09-18

## README

# Type-checked query string

> `use-search` is a simple library that helps your deal with all the shit with the query string on the url-bar. Handle `search` like you `React.useState`, with validation against arbitrary input!

## Install

```
yarn add @monoid-dev/use-search
```

## Usage

```tsx
import React from 'react';
import ReactDOM from 'react-dom';

import * as t from 'io-ts'; // For more information about io-ts, please click https://gcanti.github.io/io-ts/

import useSearch, { SearchConfigProvider } from '@monoid-dev/use-search';

export const Page = () => {
  const {
    search, // The parsed { id: string | undefined } object
    updateSearch, // The method to update the object
  } = useSearch(t.type({
    id: t.union([t.undefined,  t.string]),  // Define your query type here
  }));

  return (
    <>
      {JSON.stringify(search)}

      <button
        onClick={() => updateSearch({ id: String(parseInt(search?.id ?? '0') + 1) })}
      >
        Update Search
      </button>
    </>
  );
};

ReactDOM.render((
  <SearchConfigProvider>
    <Page />
  </SearchConfigProvider>
), document.body);
```

## APIs

+ useSearch

  ```tsx
  function useSearch<T>(type: t.Type<T>, config?: UseSearchConfig)
  ```
  Parameters:
    + `type` The `io-ts` type of the parsed search.
    + `config` The local [configuration](#UseSearchConfig) for the search, shallowly merged with the current `UseSearchConfig` in the context.

  Return Type:
    + `search: T | undefined` The parsed and validated search string. Returns `undefined` when there's an error.
    + `setSearch: T` Reset the search string, navigating to the new href.
    + `updateSearch: Partial<T>` Partially update the search string, navigating to the new href.

+ UseSearchConfig

```tsx
interface UseSearchConfig {
  parse?: (q: string) => unknown; // The method to parse the search string, by default using `query-string` with `{ arrayFormat: 'bracket-separator' }`.
  stringify?: (v: Record<string, unknown>) => string; // The method to stringify the search string from your object, by default using `query-string` with `{ arrayFormat: 'bracket-separator' }`.
  errorPolicy?: 'throw' | 'return'; // If 'throw', throws an error when an error happens. Warning: will cause a white screen when ErrorBoundary is not set up.
  useRouter?: () => Router; // The function that returns a Router object. It is called once per rendering thus safe to pass a React hook here. By default uses the native window.location methods. See API Router.
  omitValue?: (value: unknown) => void; // When to omit value in the query string. By default we omit `undefiend`, `null` and empty or all-whitespace strings.
}
```

+ Router

```tsx
interface Router {
  pathname: string; // The current pathname, e.g. the `/search` https://www.google.com.hk/search?q=ErrorBoundary
  search: string; // The current search
  navigate: (link: string) => void; // The method to redirect to new page
}
```

Recipes:

+ For `nextjs`

  ```tsx
  import { useRouter as useNextRouter } from 'next/router';

  // Wrap your tree with global configuration
  const useRouter = () => {
    const router = useNextRouter();

    return {
      get pathname() {
        return router.pathname;
      },
      get search() {
        return router.asPath.split('?')[1] ?? '';
      },
      navigate(link: string) {
        router.push(link);
      },
    };
  };

  // In _app.tsx
  function MyApp({ Component, pageProps }: any) {
    return (
      <SearchConfigProvider
        config={{
          useRouter,
        }}
      >
        <Component {...pageProps} />
      </SearchConfigProvider>
    );
  }

  export default MyApp;
  ```

  Note that, per NextJS document, [router](https://nextjs.org/docs/api-reference/next/router), does not include query information if the page is static. So you'll need the page to be serverside-generated or you'll face an inconsistency in the rehydration step! Or, you can leverage `useEffect` for static pages.

+ For `react-router-dom`

  TBD

---
_Source: https://npm.io/package/@monoid-dev/use-search · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._