Version 0.6.0

- Dependency updates
- added jsdoc comments to all functions

CHANGELOG.md

@@ -1,11 +1,22 @@
 # Change Log
 
 ## [Unreleased]
+
+## [0.6.0] - 2023-06-06
+
+### Added
+
+- feat: update dependencies to latest versions
+- feat: add ChatGPT-generated JSDoc documentation
+
 ## [0.5.0] - 2023-03-04
+
 ### Added
-- feat: mark internal atoms as private
 
+- feat: mark internal atoms as private
 
 ## [0.4.0] - 2023-01-31
+
 ### Added
+
 - Migrate to Jotai v2 API #3

package.json

@@ -1,7 +1,7 @@
 {
   "name": "jotai-relay",
   "description": "👻🧲",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "author": "Daishi Kato",
   "repository": {
     "type": "git",
@@ -51,46 +51,46 @@
   "license": "MIT",
   "dependencies": {},
   "devDependencies": {
-    "@babel/preset-env": "^7.20.2",
-    "@babel/preset-react": "^7.18.6",
-    "@babel/preset-typescript": "^7.18.6",
-    "@types/jest": "^29.4.0",
-    "@types/react": "^18.0.27",
-    "@types/react-dom": "^18.0.10",
-    "@types/relay-runtime": "^14.1.6",
-    "@typescript-eslint/eslint-plugin": "^5.50.0",
-    "@typescript-eslint/parser": "^5.50.0",
-    "babel-loader": "^9.1.2",
+    "@babel/preset-env": "^7.24.7",
+    "@babel/preset-react": "^7.24.7",
+    "@babel/preset-typescript": "^7.24.7",
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@types/react-relay": "^16.0.6",
+    "@typescript-eslint/eslint-plugin": "^7.12.0",
+    "@typescript-eslint/parser": "^7.12.0",
+    "babel-loader": "^9.1.3",
     "babel-plugin-macros": "^3.1.0",
-    "babel-plugin-relay": "^14.1.0",
-    "eslint": "^8.33.0",
+    "babel-plugin-relay": "^16.2.0",
+    "eslint": "^8.57.0",
     "eslint-config-airbnb": "^19.0.4",
-    "eslint-config-prettier": "^8.6.0",
-    "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-jsx-a11y": "^6.7.1",
-    "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.32.2",
-    "graphql": "^16.6.0",
-    "html-webpack-plugin": "^5.5.0",
-    "jest": "^29.4.1",
-    "jest-environment-jsdom": "^29.4.1",
-    "jotai": "^2.0.3",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsx-a11y": "^6.8.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "eslint-plugin-react": "^7.34.2",
+    "graphql": "^16.8.1",
+    "html-webpack-plugin": "^5.6.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jotai": "^2.8.3",
     "microbundle": "^0.15.1",
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.8.3",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "react-error-boundary": "^3.1.4",
-    "relay-compiler": "^14.1.0",
-    "relay-runtime": "^14.1.0",
-    "ts-jest": "^29.0.5",
-    "typescript": "^4.9.5",
-    "webpack": "^5.75.0",
-    "webpack-cli": "^5.0.1",
-    "webpack-dev-server": "^4.11.1"
+    "prettier": "^3.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-error-boundary": "^4.0.13",
+    "relay-compiler": "^16.2.0",
+    "relay-runtime": "^16.2.0",
+    "ts-jest": "^29.1.4",
+    "typescript": "^5.4.5",
+    "webpack": "^5.91.0",
+    "webpack-cli": "^5.1.4",
+    "webpack-dev-server": "^5.0.4"
   },
   "peerDependencies": {
-    "jotai": ">=1.11.0",
-    "relay-runtime": ">=14.0.0"
+    "jotai": ">=2.8.3",
+    "relay-runtime": ">=16.2.0"
   }
 }

src/atomWithMutation.ts

@@ -1,24 +1,30 @@
-import { commitMutation } from 'relay-runtime';
+import { atom, Getter, WritableAtom } from 'jotai/vanilla';
 import type {
   Disposable,
   Environment,
   MutationConfig,
   MutationParameters,
 } from 'relay-runtime';
-import { atom } from 'jotai/vanilla';
-import type { Getter, WritableAtom } from 'jotai/vanilla';
+import { commitMutation } from 'relay-runtime';
 import { environmentAtom } from './environmentAtom';
 
+/**
+ * Creates a Jotai atom with a Relay mutation.
+ *
+ * @param getEnvironment - Function to retrieve the Relay environment. Defaults to using the environmentAtom.
+ * @returns A Jotai writable atom that commits the mutation.
+ */
 export function atomWithMutation<T extends MutationParameters>(
   getEnvironment: (get: Getter) => Environment = (get) => get(environmentAtom),
 ): WritableAtom<undefined, [MutationConfig<T>], Disposable> {
+  // Define a Jotai atom that performs a Relay mutation when set.
   const mutationAtom = atom(
-    // Don't we have any valid value for this atom??
-    undefined,
+    undefined, // Initial value of the atom is undefined.
     (get, _set, config: MutationConfig<T>) => {
       const environment = getEnvironment(get);
       return commitMutation(environment, config);
     },
   );
+
   return mutationAtom;
 }

src/atomWithQuery.ts

@@ -14,12 +14,22 @@ type Action = {
   type: 'refetch';
 };
 
+/**
+ * Creates a Jotai atom that fetches a GraphQL query with Relay.
+ *
+ * @param taggedNode - The GraphQL tagged node for the query.
+ * @param getVariables - Function to retrieve the query variables.
+ * @param getConfig - Optional function to retrieve the fetch query configuration.
+ * @param getEnvironment - Function to retrieve the Relay environment. Defaults to using the environmentAtom.
+ * @returns A Jotai writable atom that fetches the query response.
+ */
 export function atomWithQuery<T extends OperationType>(
   taggedNode: GraphQLTaggedNode,
   getVariables: (get: Getter) => T['variables'],
   getConfig?: (get: Getter) => Config,
   getEnvironment: (get: Getter) => Environment = (get) => get(environmentAtom),
 ): WritableAtom<T['response'], [Action], void> {
+  // Create a Jotai atom that fetches a GraphQL query with Relay when set.
   return createAtom(
     (get) => [taggedNode, getVariables(get), getConfig?.(get)] as const,
     getEnvironment,

src/atomWithSubscription.ts

@@ -16,13 +16,24 @@ type Action = {
   type: 'refetch';
 };
 
+/**
+ * Creates a Jotai atom with a Relay subscription.
+ *
+ * @param taggedNode - The GraphQL tagged node for the subscription.
+ * @param getVariables - Function to retrieve the subscription variables.
+ * @param getConfigs - Optional function to retrieve the subscription configurations.
+ * @param updater - Optional updater function for the subscription.
+ * @param getEnvironment - Function to retrieve the Relay environment. Defaults to using the environmentAtom.
+ * @returns A Jotai writable atom that subscribes to the Relay subscription.
+ */
 export function atomWithSubscription<T extends OperationType>(
   taggedNode: GraphQLTaggedNode,
   getVariables: (get: Getter) => T['variables'],
   getConfigs?: (get: Getter) => Configs,
   updater?: SelectorStoreUpdater<T['response']>,
   getEnvironment: (get: Getter) => Environment = (get) => get(environmentAtom),
 ): WritableAtom<T['response'], [Action], void> {
+  // Create a Jotai atom that subscribes to a Relay subscription.
   return createAtom(
     (get) => ({
       configs: getConfigs?.(get),
@@ -44,7 +55,7 @@ export function atomWithSubscription<T extends OperationType>(
             unsubscribe: () => {
               disposable.dispose();
             },
-            closed: false, // HACK we don't use this.
+            closed: false, // HACK: we don't use this.
           };
         },
       };

src/common.ts

@@ -3,6 +3,15 @@ import { atom } from 'jotai/vanilla';
 import type { Getter } from 'jotai/vanilla';
 import { atomWithObservable } from 'jotai/vanilla/utils';
 
+/**
+ * Creates a Jotai atom with observable data and action handling.
+ *
+ * @param getArgs - Function to retrieve the arguments for the subscription.
+ * @param getEnvironment - Function to retrieve the Relay environment.
+ * @param execute - Function to execute the subscription.
+ * @param handleAction - Function to handle actions and refresh the subscription.
+ * @returns A Jotai writable atom that manages the subscription and handles actions.
+ */
 export const createAtom = <Args, Result, Action, ActionResult>(
   getArgs: (get: Getter) => Args,
   getEnvironment: (get: Getter) => Environment,
@@ -13,32 +22,35 @@ export const createAtom = <Args, Result, Action, ActionResult>(
     refresh: () => void,
   ) => ActionResult,
 ) => {
+  // Atom to trigger refreshes
   const refreshAtom = atom(0);
   if (process.env.NODE_ENV !== 'production') {
     refreshAtom.debugPrivate = true;
   }
+
+  // Atom to create and manage the observable
   const observableAtom = atom((get) => {
     get(refreshAtom);
     const args = getArgs(get);
     const environment = getEnvironment(get);
     const observable = execute(environment, args);
     return observable;
   });
-
   if (process.env.NODE_ENV !== 'production') {
     observableAtom.debugPrivate = true;
   }
 
+  // Base data atom to handle the observable subscription
   const baseDataAtom = atom((get) => {
     const observable = get(observableAtom);
     const resultAtom = atomWithObservable(() => observable);
     return resultAtom;
   });
-
   if (process.env.NODE_ENV !== 'production') {
     baseDataAtom.debugPrivate = true;
   }
 
+  // Data atom to manage the state and handle actions
   const dataAtom = atom(
     (get) => {
       const resultAtom = get(baseDataAtom);

src/environmentAtom.ts

@@ -1,6 +1,7 @@
 import { Environment, Network, RecordSource, Store } from 'relay-runtime';
 import { atom } from 'jotai/vanilla';
 
+// Retrieve the default GraphQL URL from environment variables or fallback to '/graphql'
 const DEFAULT_URL =
   (() => {
     try {
@@ -10,8 +11,10 @@ const DEFAULT_URL =
     }
   })() || '/graphql';
 
+// Create a default Relay Environment
 const defaultEnvironment = new Environment({
   network: Network.create(async (params, variables) => {
+    // Perform a POST request to the GraphQL endpoint
     const response = await fetch(DEFAULT_URL, {
       method: 'POST',
       headers: {
@@ -27,8 +30,10 @@ const defaultEnvironment = new Environment({
   store: new Store(new RecordSource()),
 });
 
+// Create a Jotai atom to hold the default Relay environment
 export const environmentAtom = atom(defaultEnvironment);
 
+// Enable debug mode for the atom in non-production environments
 if (process.env.NODE_ENV !== 'production') {
   environmentAtom.debugPrivate = true;
 }