feat(jotai): add @suspensive/jotai package (#1042)

# Overview

## Roadmap

- [x] Atom (setAtom)
- [x] SetAtom (useSetAtom)
- [x] AtomValue (useAtomValue)

## Tests

- [x] local package test (pack .tgz)
- [x] jotai-tanstack-query (query, mutation)

![Jul-07-2024
21-34-16](https://github.com/toss/suspensive/assets/39869096/c69a449c-a3a5-4ee0-9d91-dbb1c8793519)

## PR Checklist

- [x] I did below actions if need

1. I read the [Contributing
Guide](https://github.com/toss/suspensive/blob/main/CONTRIBUTING.md)
2. I added documents and tests.

---------

Co-authored-by: Jonghyeon Ko <jonghyeon@toss.im>

.changeset/five-tips-grow.md

@@ -0,0 +1,5 @@
+---
+"@suspensive/jotai": patch
+---
+
+feat(jotai): add @suspensive/jotai package

.github/ISSUE_TEMPLATE/bug.yml

@@ -14,6 +14,7 @@ body:
         - "@suspensive/react-query"
         - "@suspensive/react-query-4"
         - "@suspensive/react-query-5"
+        - "@suspensive/jotai"
         - "@suspensive/react-await"
         - "@suspensive/react-image"
         - etc

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -14,6 +14,7 @@ body:
         - "@suspensive/react-query"
         - "@suspensive/react-query-4"
         - "@suspensive/react-query-5"
+        - "@suspensive/jotai"
         - "@suspensive/react-await"
         - "@suspensive/react-image"
         - etc

.github/labeler.yml

@@ -2,6 +2,12 @@
   - "packages/react/**/*"
 "@suspensive/react-query":
   - "packages/react-query/**/*"
+"@suspensive/react-query-4":
+  - "packages/react-query-4/**/*"
+"@suspensive/react-query-5":
+  - "packages/react-query-5/**/*"
+"@suspensive/jotai":
+  - "packages/jotai/**/*"
 "@suspensive/react-await":
   - "packages/react-await/**/*"
 "@suspensive/react-image":

codecov.yml

@@ -36,6 +36,10 @@ component_management:
       name: '@suspensive/react-query-5'
       paths:
         - packages/react-query-5/**
+    - component_id: jotai
+      name: '@suspensive/jotai'
+      paths:
+        - packages/jotai/**
     - component_id: react-await
       name: '@suspensive/react-await'
       paths:

docs/suspensive.org/package.json

@@ -10,10 +10,7 @@
   ],
   "homepage": "https://suspensive.org",
   "bugs": "https://github.com/toss/suspensive/issues",
-  "author": {
-    "name": "Jonghyeon Ko",
-    "email": "jonghyeon@toss.im"
-  },
+  "author": "Jonghyeon Ko <jonghyeon@toss.im>",
   "type": "commonjs",
   "scripts": {
     "build": "next build",

packages/jotai/.eslintrc.cjs

@@ -0,0 +1,10 @@
+/** @type {import('eslint').Linter.Config} */
+module.exports = {
+  root: true,
+  extends: ['@suspensive/eslint-config/react-ts'],
+  ignorePatterns: ['dist', 'coverage'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: 'tsconfig.json',
+  },
+}

packages/jotai/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Viva Republica, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/jotai/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@suspensive/jotai",
+  "version": "0.0.0",
+  "description": "Useful helpers for jotai with suspense",
+  "keywords": [
+    "suspensive",
+    "jotai"
+  ],
+  "homepage": "https://suspensive.org",
+  "bugs": "https://github.com/toss/suspensive/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toss/suspensive.git",
+    "directory": "packages/jotai"
+  },
+  "license": "MIT",
+  "author": "GwanSik Kim <Seorit98@gmail.com> & Jonghyeon Ko <jonghyeon@toss.im>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "ci:attw": "attw --pack",
+    "ci:eslint": "eslint \"**/*.{js,jsx,cjs,mjs,ts,tsx,cts,mts}\"",
+    "ci:publint": "publint --strict",
+    "ci:test": "vitest run --coverage --typecheck",
+    "ci:test:watch": "vitest --ui --coverage --typecheck",
+    "ci:type": "tsc --noEmit",
+    "clean": "rimraf ./dist && rimraf ./coverage",
+    "dev": "tsup --watch",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "@suspensive/eslint-config": "workspace:*",
+    "@suspensive/tsconfig": "workspace:*",
+    "@suspensive/tsup": "workspace:*",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "jotai": "^2.8.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "peerDependencies": {
+    "jotai": "^2",
+    "react": "^18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/jotai/src/Atom.test-d.tsx

@@ -0,0 +1,49 @@
+import { atom, useAtom } from 'jotai'
+import type { ReactNode } from 'react'
+import { Atom } from './Atom'
+
+const countAtom = atom(0)
+const asyncAtom = atom(async () => Promise.resolve('string'))
+// eslint-disable-next-line @typescript-eslint/require-await
+const asyncIncrementAtom = atom(null, async (get, set) => {
+  set(countAtom, get(countAtom) + 1)
+})
+
+describe('<Atom/>', () => {
+  it('type check', () => {
+    ;() => (
+      <Atom atom={countAtom}>
+        {(result) => {
+          const returnOfJotai = useAtom(countAtom)
+          expectTypeOf(result).toEqualTypeOf<typeof returnOfJotai>()
+          return <></>
+        }}
+      </Atom>
+    )
+    ;() => (
+      <Atom atom={asyncAtom}>
+        {(result) => {
+          const returnOfJotai = useAtom(asyncAtom)
+          expectTypeOf(result).toEqualTypeOf<typeof returnOfJotai>()
+          return <></>
+        }}
+      </Atom>
+    )
+    ;() => (
+      <Atom atom={asyncIncrementAtom}>
+        {(result) => {
+          const returnOfJotai = useAtom(asyncIncrementAtom)
+          expectTypeOf(result).toEqualTypeOf<typeof returnOfJotai>()
+          return <></>
+        }}
+      </Atom>
+    )
+
+    expectTypeOf(<Atom atom={countAtom}>{() => <></>}</Atom>).toEqualTypeOf<JSX.Element>()
+    expectTypeOf(<Atom atom={countAtom}>{() => <></>}</Atom>).not.toEqualTypeOf<ReactNode>()
+    expectTypeOf(<Atom atom={asyncAtom}>{() => <></>}</Atom>).toEqualTypeOf<JSX.Element>()
+    expectTypeOf(<Atom atom={asyncAtom}>{() => <></>}</Atom>).not.toEqualTypeOf<ReactNode>()
+    expectTypeOf(<Atom atom={asyncIncrementAtom}>{() => <></>}</Atom>).toEqualTypeOf<JSX.Element>()
+    expectTypeOf(<Atom atom={asyncIncrementAtom}>{() => <></>}</Atom>).not.toEqualTypeOf<ReactNode>()
+  })
+})

packages/jotai/src/Atom.tsx

@@ -0,0 +1,82 @@
+/* eslint-disable @typescript-eslint/unified-signatures */
+import {
+  type ExtractAtomArgs,
+  type ExtractAtomResult,
+  type ExtractAtomValue,
+  type Atom as JotaiAtom,
+  type PrimitiveAtom,
+  type SetStateAction,
+  type WritableAtom,
+  type useAtom,
+  useAtomValue,
+  useSetAtom,
+} from 'jotai'
+import type { ReactNode } from 'react'
+import type { ChildrenRenderProps } from './utility-types'
+type UseAtomProps<TAtom extends JotaiAtom<unknown>> = {
+  atom: TAtom
+  options?: Parameters<typeof useAtom>[1]
+}
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function Atom<TValue, TArgs extends unknown[], TResult>({
+  children,
+  atom,
+  options,
+}: UseAtomProps<WritableAtom<TValue, TArgs, TResult>> &
+  ChildrenRenderProps<[Awaited<TValue>, (...args: TArgs) => TResult]>): ReactNode
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function Atom<TValue>({
+  children,
+  atom,
+  options,
+}: UseAtomProps<PrimitiveAtom<TValue>> &
+  ChildrenRenderProps<[Awaited<TValue>, (...args: [SetStateAction<TValue>]) => void]>): ReactNode
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function Atom<TValue>({
+  children,
+  atom,
+  options,
+}: UseAtomProps<JotaiAtom<TValue>> & ChildrenRenderProps<[Awaited<TValue>, never]>): ReactNode
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function Atom<TAtom extends WritableAtom<unknown, never[], unknown>>({
+  children,
+  atom,
+  options,
+}: UseAtomProps<TAtom> &
+  ChildrenRenderProps<
+    [Awaited<ExtractAtomValue<TAtom>>, (...args: ExtractAtomArgs<TAtom>) => ExtractAtomResult<TAtom>]
+  >): ReactNode
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function Atom<TAtom extends JotaiAtom<unknown>>({
+  children,
+  atom,
+  options,
+}: UseAtomProps<TAtom> & ChildrenRenderProps<[Awaited<ExtractAtomValue<TAtom>>, never]>): ReactNode
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function Atom<TValue, TArgs extends unknown[], TResult>({
+  children,
+  atom,
+  options,
+}: UseAtomProps<JotaiAtom<unknown>> & ChildrenRenderProps<any>): ReactNode {
+  return (
+    <>{children([useAtomValue(atom, options), useSetAtom(atom as WritableAtom<TValue, TArgs, TResult>, options)])}</>
+  )
+}

packages/jotai/src/AtomValue.test-d.tsx

@@ -0,0 +1,22 @@
+import { atom, useAtomValue } from 'jotai'
+import type { ReactNode } from 'react'
+import { AtomValue } from './AtomValue'
+
+const asyncAtom = atom(() => Promise.resolve('string'))
+
+describe('<AtomValue/>', () => {
+  it('type check', () => {
+    ;() => (
+      <AtomValue atom={asyncAtom}>
+        {(value) => {
+          const valueOfJotai = useAtomValue(asyncAtom)
+          expectTypeOf(value).toEqualTypeOf<typeof valueOfJotai>()
+          return <></>
+        }}
+      </AtomValue>
+    )
+
+    expectTypeOf(<AtomValue atom={asyncAtom}>{() => <></>}</AtomValue>).toEqualTypeOf<JSX.Element>()
+    expectTypeOf(<AtomValue atom={asyncAtom}>{() => <></>}</AtomValue>).not.toEqualTypeOf<ReactNode>()
+  })
+})

packages/jotai/src/AtomValue.tsx

@@ -0,0 +1,18 @@
+import { type Atom as JotaiAtom, useAtomValue } from 'jotai'
+import type { ChildrenRenderProps } from './utility-types'
+
+type UseAtomValueProps<TValue> = {
+  atom: JotaiAtom<TValue>
+  options?: Parameters<typeof useAtomValue>[1] & { delay?: number }
+}
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function AtomValue<TValue>({
+  children,
+  atom,
+  options,
+}: UseAtomValueProps<TValue> & ChildrenRenderProps<Awaited<TValue>>) {
+  return <>{children(useAtomValue(atom, options))}</>
+}

packages/jotai/src/SetAtom.test-d.tsx

@@ -0,0 +1,22 @@
+import { atom, useSetAtom } from 'jotai'
+import type { ReactNode } from 'react'
+import { SetAtom } from './SetAtom'
+
+const countAtom = atom(0)
+
+describe('<SetAtom/>', () => {
+  it('type check', () => {
+    ;() => (
+      <SetAtom atom={countAtom}>
+        {(setCount) => {
+          const setCountOfJotai = useSetAtom(countAtom)
+          expectTypeOf(setCount).toEqualTypeOf<typeof setCountOfJotai>()
+          return <></>
+        }}
+      </SetAtom>
+    )
+
+    expectTypeOf(<SetAtom atom={countAtom}>{() => <></>}</SetAtom>).toEqualTypeOf<JSX.Element>()
+    expectTypeOf(<SetAtom atom={countAtom}>{() => <></>}</SetAtom>).not.toEqualTypeOf<ReactNode>()
+  })
+})

packages/jotai/src/SetAtom.tsx

@@ -0,0 +1,18 @@
+import { type WritableAtom, useSetAtom } from 'jotai'
+import type { ChildrenRenderProps } from './utility-types'
+
+type UseSetAtomProps<TValue, TArgs extends unknown[], TResult> = {
+  atom: WritableAtom<TValue, TArgs, TResult>
+  options?: Parameters<typeof useSetAtom>[1]
+}
+
+/**
+ * @experimental This is experimental feature.
+ */
+export function SetAtom<TValue, TArgs extends unknown[], TResult>({
+  children,
+  atom,
+  options,
+}: UseSetAtomProps<TValue, TArgs, TResult> & ChildrenRenderProps<(...args: TArgs) => TResult>) {
+  return <>{children(useSetAtom(atom, options))}</>
+}

packages/jotai/src/index.ts

@@ -0,0 +1,3 @@
+export { Atom } from './Atom'
+export { SetAtom } from './SetAtom'
+export { AtomValue } from './AtomValue'

packages/jotai/src/utility-types/ChildrenRenderProps.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react'
+
+export interface ChildrenRenderProps<TValue> {
+  children: (value: TValue) => ReactNode
+}

packages/jotai/src/utility-types/index.ts

@@ -0,0 +1 @@
+export type { ChildrenRenderProps } from './ChildrenRenderProps'

packages/jotai/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@suspensive/tsconfig/react-library.json",
+  "include": [".", "./.eslintrc.cjs"],
+  "compilerOptions": {
+    "types": ["@testing-library/jest-dom/vitest", "vitest/globals"]
+  }
+}