js-style-kit 0.6.1 → 0.7.0

package/src/eslint/perfectionist/rules.ts

@@ -0,0 +1,39 @@
+import type { EslintRuleConfig } from "../types.js";
+
+interface PerfectionistRuleOptions {
+  order: "asc" | "desc";
+  type: "alphabetical" | "custom" | "line-length" | "natural";
+}
+
+const defaultOptions: PerfectionistRuleOptions = {
+  order: "asc",
+  type: "natural",
+};
+
+type PerfectionRules = Record<
+  `perfectionist/${string}`,
+  EslintRuleConfig<PerfectionistRuleOptions>
+>;
+
+export const perfectionistRules: PerfectionRules = {
+  "perfectionist/sort-array-includes": ["warn", defaultOptions],
+  "perfectionist/sort-classes": ["warn", defaultOptions],
+  "perfectionist/sort-decorators": ["warn", defaultOptions],
+  "perfectionist/sort-enums": ["warn", defaultOptions],
+  "perfectionist/sort-exports": ["warn", defaultOptions],
+  "perfectionist/sort-heritage-clauses": ["warn", defaultOptions],
+  "perfectionist/sort-imports": ["warn", defaultOptions],
+  "perfectionist/sort-interfaces": ["warn", defaultOptions],
+  "perfectionist/sort-intersection-types": ["warn", defaultOptions],
+  "perfectionist/sort-jsx-props": ["warn", defaultOptions],
+  "perfectionist/sort-maps": ["warn", defaultOptions],
+  "perfectionist/sort-modules": ["off", defaultOptions],
+  "perfectionist/sort-named-exports": ["warn", defaultOptions],
+  "perfectionist/sort-named-imports": ["warn", defaultOptions],
+  "perfectionist/sort-object-types": ["warn", defaultOptions],
+  "perfectionist/sort-objects": ["warn", defaultOptions],
+  "perfectionist/sort-sets": ["warn", defaultOptions],
+  "perfectionist/sort-switch-case": ["warn", defaultOptions],
+  "perfectionist/sort-union-types": ["warn", defaultOptions],
+  "perfectionist/sort-variable-declarations": ["warn", defaultOptions],
+};

package/src/eslint/prefer-arrow-function/config.ts

@@ -0,0 +1,33 @@
+import type { ESLint } from "eslint";
+
+import preferArrowFunctions from "eslint-plugin-prefer-arrow-functions";
+
+import type { EslintConfigObject, EslintRuleConfig } from "../types.js";
+import type { PreferArrowFunctionsRules } from "./types.js";
+
+import { configNames } from "../constants.js";
+
+/**
+ * Creates an ESLint configuration for Prefer Arrow Functions.
+ *
+ * @param customRules - Optional object containing custom rules to override or add to the configuration.
+ * @returns ESLint configuration object for Prefer Arrow Functions
+ */
+export const preferArrowFunctionConfig = (
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject => ({
+  name: configNames.preferArrowFunction,
+  plugins: {
+    "prefer-arrow-functions": preferArrowFunctions as ESLint.Plugin,
+  },
+  rules: {
+    "prefer-arrow-functions/prefer-arrow-functions": [
+      "warn",
+      {
+        returnStyle: "unchanged",
+        singleReturnOnly: false,
+      },
+    ],
+    ...(customRules ?? {}),
+  } satisfies PreferArrowFunctionsRules,
+});

package/src/eslint/prefer-arrow-function/types.ts

@@ -0,0 +1,13 @@
+import type { EslintRuleConfig } from "../types.js";
+
+export interface PreferArrowFunctionsRules {
+  "prefer-arrow-functions/prefer-arrow-functions": EslintRuleConfig<{
+    allowedNames?: string[];
+    allowNamedFunctions?: boolean;
+    allowObjectProperties?: boolean;
+    classPropertiesAllowed?: boolean;
+    disallowPrototype?: boolean;
+    returnStyle?: "explicit" | "implicit" | "unchanged";
+    singleReturnOnly?: boolean;
+  }>;
+}

package/src/eslint/process-custom-rules.ts

@@ -0,0 +1,72 @@
+import type { ConfigName } from "./constants.js";
+import type { EslintRuleConfig } from "./types.js";
+
+import { configNames, pluginPrefixMap } from "./constants.js";
+
+/**
+ * Categorizes custom rules provided by the user based on plugin prefixes.
+ *
+ * @param customRules - The custom rules provided by the user.
+ * @returns An object where keys are config names (e.g., 'base', 'typescript')
+ *          and values are the corresponding rule subsets for that config.
+ */
+export const processCustomRules = (
+  customRules: Record<string, EslintRuleConfig>,
+): Partial<Record<ConfigName, Record<string, EslintRuleConfig>>> => {
+  // Initialize result object with all possible config categories
+  const categorizedRules = Object.values(configNames).reduce<
+    Record<ConfigName, Record<string, EslintRuleConfig>>
+  >(
+    (acc, configName) => {
+      acc[configName] = {};
+      return acc;
+    },
+    {} as Record<ConfigName, Record<string, EslintRuleConfig>>,
+  );
+
+  // Process each custom rule
+  for (const [ruleKey, ruleValue] of Object.entries(customRules)) {
+    // Quick check if rule has no prefix (no '/' or '@')
+    // Rules without prefixes go directly to base config
+    if (!ruleKey.includes("/") && !ruleKey.startsWith("@")) {
+      categorizedRules[configNames.base][ruleKey] = ruleValue;
+      continue;
+    }
+
+    // Extract the plugin prefix from the rule key
+    let prefix: null | string = null;
+
+    if (ruleKey.startsWith("@")) {
+      // Handle scoped packages like @typescript-eslint/rule-name
+      const firstSlashIndex = ruleKey.indexOf("/");
+      if (firstSlashIndex !== -1) {
+        prefix = ruleKey.substring(0, firstSlashIndex);
+      }
+    } else {
+      // Handle regular plugins like eslint-plugin-react/rule-name
+      const firstSlashIndex = ruleKey.indexOf("/");
+      if (firstSlashIndex !== -1) {
+        prefix = ruleKey.substring(0, firstSlashIndex);
+      }
+    }
+
+    // Find the corresponding config name for this prefix
+    const configName =
+      prefix ?
+        (pluginPrefixMap.get(prefix) ?? configNames.base)
+      : configNames.base;
+
+    // Add the rule to the appropriate config
+    categorizedRules[configName][ruleKey] = ruleValue;
+  }
+
+  // Filter out empty config objects to save memory
+  return Object.entries(categorizedRules).reduce<
+    Partial<Record<ConfigName, Record<string, EslintRuleConfig>>>
+  >((acc, [configName, rules]) => {
+    if (Object.keys(rules).length > 0) {
+      acc[configName as ConfigName] = rules;
+    }
+    return acc;
+  }, {});
+};

package/src/eslint/query/README.md

@@ -0,0 +1,254 @@
+# TanStack Query Configuration
+
+ESLint rules for [TanStack Query](https://tanstack.com/query) (formerly React Query) to ensure proper usage patterns and prevent common mistakes.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+TanStack Query support is **disabled by default** and provides:
+
+- Query dependency validation
+- Property ordering consistency
+- Stable query client patterns
+- Hook usage best practices
+
+## Quick Start
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  query: true, // Enable TanStack Query rules
+});
+```
+
+## When to Use
+
+Enable this configuration when using TanStack Query in your project:
+
+```bash
+npm install @tanstack/react-query
+# or
+yarn add @tanstack/react-query
+# or
+pnpm add @tanstack/react-query
+# or
+bun add @tanstack/react-query
+```
+
+## Rules
+
+### Dependency Validation
+
+**`exhaustive-deps`**
+Ensures all dependencies are declared in query keys and function scopes.
+
+```ts
+// ✅ Good
+const { data } = useQuery({
+  queryKey: ["users", userId], // userId in queryKey
+  queryFn: () => fetchUser(userId),
+});
+
+// ❌ Bad
+const { data } = useQuery({
+  queryKey: ["users"], // Missing userId
+  queryFn: () => fetchUser(userId),
+});
+```
+
+**`no-unstable-deps`**
+Prevents unstable references in query keys that could cause unnecessary refetches.
+
+```ts
+// ✅ Good
+const queryKey = useMemo(() => ["users", userId], [userId]);
+const { data } = useQuery({
+  queryKey,
+  queryFn: fetchUsers,
+});
+
+// ❌ Bad
+const { data } = useQuery({
+  queryKey: ["users", { id: userId }], // New object each render
+  queryFn: fetchUsers,
+});
+```
+
+### Property Ordering
+
+**`infinite-query-property-order`**
+Enforces consistent property order in `useInfiniteQuery`:
+
+```ts
+// ✅ Good - correct order
+useInfiniteQuery({
+  queryKey: ["projects"],
+  queryFn: fetchProjects,
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+  initialPageParam: 0,
+});
+```
+
+**`mutation-property-order`**
+Enforces consistent property order in `useMutation`:
+
+```ts
+// ✅ Good - correct order
+useMutation({
+  mutationFn: createUser,
+  onSuccess: () => {
+    /* ... */
+  },
+  onError: () => {
+    /* ... */
+  },
+});
+```
+
+### Query Function Patterns
+
+**`no-void-query-fn`**
+Prevents `void` returning query functions:
+
+```ts
+// ✅ Good
+useQuery({
+  queryKey: ["users"],
+  queryFn: () => fetchUsers(), // Returns Promise<User[]>
+});
+
+// ❌ Bad
+useQuery({
+  queryKey: ["users"],
+  queryFn: () => {
+    fetchUsers();
+  }, // Returns void
+});
+```
+
+**`no-rest-destructuring`**
+Prevents rest destructuring which can lead to serialization issues:
+
+```ts
+// ✅ Good
+const { data, isLoading, error } = useQuery({
+  queryKey: ["users"],
+  queryFn: fetchUsers,
+});
+
+// ❌ Bad
+const { data, ...rest } = useQuery({
+  queryKey: ["users"],
+  queryFn: fetchUsers,
+});
+```
+
+### Client Stability
+
+**`stable-query-client`**
+Ensures QueryClient is stable across renders:
+
+```ts
+// ✅ Good - client created outside component or with useMemo
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>{/* ... */}</QueryClientProvider>
+  );
+}
+
+// ❌ Bad - new client every render
+function App() {
+  const queryClient = new QueryClient();
+  return (
+    <QueryClientProvider client={queryClient}>{/* ... */}</QueryClientProvider>
+  );
+}
+```
+
+## Common Patterns
+
+### With React and TypeScript
+
+```js
+export default eslintConfig({
+  typescript: true,
+  react: { framework: "vite" },
+  query: true,
+});
+```
+
+### With Next.js
+
+```js
+export default eslintConfig({
+  typescript: true,
+  react: { framework: "next" },
+  query: true,
+});
+```
+
+## Customization
+
+Override specific Query rules:
+
+```js
+export default eslintConfig({
+  query: true,
+  rules: {
+    // Disable property ordering if you prefer different order
+    "@tanstack/query/mutation-property-order": "off",
+
+    // Make exhaustive-deps an error instead of warning
+    "@tanstack/query/exhaustive-deps": "error",
+  },
+});
+```
+
+## Best Practices
+
+1. **Always declare dependencies** in query keys
+2. **Use stable references** for query keys (memoize objects)
+3. **Keep query functions pure** - return data, don't mutate
+4. **Hoist QueryClient** creation outside components
+5. **Follow property order conventions** for consistency
+
+## Troubleshooting
+
+### False positives on exhaustive-deps
+
+Ensure all variables used in `queryFn` are in `queryKey`:
+
+```ts
+const { data } = useQuery({
+  queryKey: ["users", filter, sort], // Include all dependencies
+  queryFn: () => fetchUsers({ filter, sort }),
+});
+```
+
+### Object key instability warnings
+
+Memoize object keys:
+
+```ts
+const params = useMemo(() => ({ filter, sort }), [filter, sort]);
+const { data } = useQuery({
+  queryKey: ["users", params],
+  queryFn: () => fetchUsers(params),
+});
+```
+
+## Related Configurations
+
+- [React](../react/README.md) - React configuration
+- [TypeScript](../typescript/README.md) - TypeScript support
+- [Testing](../testing/README.md) - Test Query hooks
+
+## Learn More
+
+- [TanStack Query ESLint Plugin](https://tanstack.com/query/latest/docs/eslint/eslint-plugin-query)
+- [TanStack Query Documentation](https://tanstack.com/query/latest)
+- [Main README](../../../README.md)

package/src/eslint/query/config.ts

@@ -0,0 +1,27 @@
+import type { ESLint } from "eslint";
+
+import queryPlugin from "@tanstack/eslint-plugin-query";
+
+import type { EslintConfigObject, EslintRuleConfig } from "../types.js";
+
+import { configNames } from "../constants.js";
+import { queryRules } from "./rules.js";
+
+/**
+ * Creates an ESLint configuration for TanStack Query.
+ *
+ * @param customRules - Optional object containing custom rules to override or add to the Query configuration.
+ * @returns ESLint configuration object for TanStack Query
+ */
+export const queryConfig = (
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject => ({
+  name: configNames.query,
+  plugins: {
+    "@tanstack/query": queryPlugin as unknown as ESLint.Plugin,
+  },
+  rules: {
+    ...queryRules,
+    ...(customRules ?? {}),
+  },
+});

package/src/eslint/query/rules.ts

@@ -0,0 +1,11 @@
+import type { QueryRules } from "./types.js";
+
+export const queryRules: QueryRules = {
+  "@tanstack/query/exhaustive-deps": "warn",
+  "@tanstack/query/infinite-query-property-order": "warn",
+  "@tanstack/query/mutation-property-order": "warn",
+  "@tanstack/query/no-rest-destructuring": "warn",
+  "@tanstack/query/no-unstable-deps": "warn",
+  "@tanstack/query/no-void-query-fn": "warn",
+  "@tanstack/query/stable-query-client": "warn",
+};

package/src/eslint/query/types.ts

@@ -0,0 +1,11 @@
+import type { EslintRuleConfig } from "../types.js";
+
+export interface QueryRules {
+  "@tanstack/query/exhaustive-deps": EslintRuleConfig;
+  "@tanstack/query/infinite-query-property-order": EslintRuleConfig;
+  "@tanstack/query/mutation-property-order": EslintRuleConfig;
+  "@tanstack/query/no-rest-destructuring": EslintRuleConfig;
+  "@tanstack/query/no-unstable-deps": EslintRuleConfig;
+  "@tanstack/query/no-void-query-fn": EslintRuleConfig;
+  "@tanstack/query/stable-query-client": EslintRuleConfig;
+}