Skip to content

Commit 89c9388

Browse files
ConsoleTVsConsoleTVs
committed
docs: add comprehensive JSDoc documentation to all exported APIs
- Document all React hooks with examples and parameter descriptions - Document all React components with proper @example usage - Document React context types (ContextValue, QueryTransitionContextValue) - Add JSDoc for all core query function types (OnceFunction, SequenceFunction, NextFunction, StreamFunction, etc.) - Document internal query functions (emit, next, stream, once, sequence) - Add documentation to Solid.js module (QueryProvider, context types) - Change ErrNoQueryInstanceFound from string to Error instance for proper error handling - Ensure all interface properties have multi-line JSDoc with blank lines between entries - Add AGENTS.md with project overview, build commands, code style guidelines, and naming conventions
1 parent 82a4651 commit 89c9388

21 files changed

Lines changed: 827 additions & 68 deletions

‎AGENTS.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# AGENTS.md
2+
3+
Guidelines for AI coding agents working in this repository.
4+
5+
## Project Overview
6+
7+
`@studiolambda/query` is a lightweight, isomorphic, framework-agnostic async data management library (SWR-style). It has bindings for React 19+ and Solid.js.
8+
9+
## Build/Lint/Test Commands
10+
11+
```bash
12+
# Install dependencies
13+
npm install
14+
15+
# Run all tests
16+
npm test
17+
18+
# Run tests in watch mode
19+
npm run dev
20+
21+
# Run a single test file
22+
npx vitest run src/query/query.test.ts
23+
24+
# Run tests matching a pattern
25+
npx vitest run -t "can query resources"
26+
27+
# Run with coverage
28+
npm run test:cover
29+
30+
# Lint
31+
npm run lint
32+
33+
# Format code
34+
npm run format
35+
36+
# Check formatting
37+
npm run format:check
38+
39+
# Build (runs format:check and lint first)
40+
npm run build
41+
42+
# Build without checks
43+
npm run build:only
44+
```
45+
46+
## Directory Structure
47+
48+
```
49+
src/
50+
query/ # Core library (framework-agnostic)
51+
react/ # React bindings
52+
hooks/ # useQuery, useQueryBasic, etc.
53+
components/# QueryProvider, QueryPrefetch, etc.
54+
solid/ # Solid.js bindings (partial)
55+
```
56+
57+
## Code Style
58+
59+
### Formatting (Prettier)
60+
61+
- Single quotes, no semicolons
62+
- 2-space indentation (no tabs)
63+
- 100 character line width
64+
- Trailing commas: `es5`
65+
- Always use parentheses in arrow functions: `(x) => x`
66+
67+
### Imports
68+
69+
1. External/framework imports first, then internal imports
70+
2. Use path aliases: `query:index`, `query/react:context`, `query/react:hooks/useQuery`
71+
3. Use inline `type` keyword for type imports:
72+
```typescript
73+
import { type Options } from 'query:index'
74+
```
75+
4. Multi-line imports with trailing comma:
76+
```typescript
77+
import { type Caches, type CacheType, type ItemsCacheItem } from 'query:cache'
78+
```
79+
80+
### TypeScript
81+
82+
- Strict mode enabled with `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`
83+
- Use `interface` for object shapes, `type` for unions and function signatures
84+
- Use `readonly` on interface properties
85+
- Generic type parameters with defaults: `<T = unknown>`
86+
- Explicit type assertions when needed: `as T`
87+
88+
### Naming Conventions
89+
90+
| Element | Convention | Example |
91+
| ------------------ | ----------------------------- | ------------------------------------- |
92+
| Files (modules) | camelCase | `useQuery.ts`, `cache.ts` |
93+
| Files (components) | PascalCase | `QueryProvider.tsx` |
94+
| Test files | `.test.ts`/`.test.tsx` suffix | `query.test.ts` |
95+
| Functions | camelCase | `createQuery`, `defaultFetcher` |
96+
| React hooks | `use` prefix | `useQuery`, `useQueryActions` |
97+
| Types/Interfaces | PascalCase | `Cache`, `Configuration` |
98+
| Function types | `*Function` suffix | `FetcherFunction`, `MutationFunction` |
99+
| Props interfaces | `*Props` suffix | `QueryProviderProps` |
100+
101+
### Functions
102+
103+
- Use `function` declarations for named/exported functions (not arrow functions)
104+
- Use arrow functions only for callbacks and inline functions
105+
- Use `async/await` for async code
106+
107+
```typescript
108+
// Correct - regular function for exports
109+
export function createQuery(options?: Configuration): Query {
110+
// ...
111+
}
112+
113+
// Correct - arrow for callbacks
114+
events.addEventListener(`${event}:${key}`, listener)
115+
```
116+
117+
### Exports
118+
119+
- **Named exports only** - never use default exports
120+
- Use barrel files (`index.ts`) for re-exports
121+
- Factory pattern for main API: `createQuery()` returns object with methods
122+
123+
### Error Handling
124+
125+
- Simple `throw new Error('message')` for errors
126+
- Try-catch with event emission pattern for async operations
127+
- Explicit empty catch `catch(() => {})` when intentionally silencing errors
128+
129+
### Comments
130+
131+
- JSDoc-style block comments for function documentation
132+
- Inline comments for explaining specific logic
133+
- Document interface properties with JSDoc
134+
135+
```typescript
136+
/**
137+
* Subscribes to a given keyed event.
138+
*/
139+
function subscribe<T = unknown>(...) {
140+
// For the refetching event, we want to immediately return...
141+
}
142+
```
143+
144+
## Testing
145+
146+
- Test framework: Vitest with happy-dom environment
147+
- Use `describe.concurrent()` for parallel test execution
148+
- Destructure `expect` from test context: `it('...', async ({ expect }) => { ... })`
149+
- React tests use `act()` and `createRoot`
150+
151+
```typescript
152+
import { describe, it, vi } from 'vitest'
153+
154+
describe.concurrent('feature', function () {
155+
it('does something', async ({ expect }) => {
156+
// test code
157+
expect(result).toBe(expected)
158+
})
159+
})
160+
```
161+
162+
## ESLint
163+
164+
- TypeScript strict type checking enabled for `src/**`
165+
- React hooks rules for `src/react/**`
166+
- Solid.js rules for `src/solid/**`
167+
- Rule `@typescript-eslint/no-unnecessary-type-parameters` is disabled
168+
169+
## Environment
170+
171+
- Node.js 25+ (see `.nvmrc`)
172+
- npm 11+ (package manager)
173+
- TypeScript ~5.9.3
174+
- React 19.2+ (peer dependency)

‎package.json‎

Lines changed: 54 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,39 @@
11
{
22
"name": "@studiolambda/query",
33
"version": "1.4.0",
4-
"license": "MIT",
4+
"description": "Lightweight, isomorphic and framework agnostic asynchronous data management for modern UIs",
55
"keywords": [
6-
"stale-while-revalidate",
7-
"swr",
8-
"react-query",
9-
"isomorphic",
6+
"data-management",
107
"fetch",
8+
"isomorphic",
119
"query",
12-
"data-management",
10+
"react",
11+
"react-query",
12+
"stale-while-revalidate",
13+
"swr",
1314
"ui",
14-
"vanilla",
15-
"react"
15+
"vanilla"
1616
],
17-
"description": "Lightweight, isomorphic and framework agnostic asynchronous data management for modern UIs",
17+
"homepage": "https://erik.cat/blog/query-docs",
18+
"license": "MIT",
1819
"author": {
1920
"name": "Erik C. Forés",
2021
"email": "soc@erik.cat",
2122
"url": "https://erik.cat"
2223
},
23-
"homepage": "https://erik.cat/blog/query-docs",
2424
"repository": {
2525
"type": "git",
2626
"url": "https://github.com/StudioLambda/Query.git"
2727
},
28-
"engines": {
29-
"node": ">=18.0.0"
30-
},
28+
"files": [
29+
"dist",
30+
"package.json"
31+
],
3132
"type": "module",
32-
"types": "./dist/src/query/index.d.ts",
33+
"sideEffects": false,
3334
"main": "./dist/query.cjs",
3435
"module": "./dist/query.js",
36+
"types": "./dist/src/query/index.d.ts",
3537
"exports": {
3638
"./package.json": "./package.json",
3739
".": {
@@ -45,10 +47,6 @@
4547
"require": "./dist/query_react.cjs"
4648
}
4749
},
48-
"files": [
49-
"dist",
50-
"package.json"
51-
],
5250
"scripts": {
5351
"build:only": "vite build",
5452
"build": "npm run build:only",
@@ -62,15 +60,32 @@
6260
"test:cover": "vitest run --coverage",
6361
"prepack": "npm run build"
6462
},
65-
"devEngines": {
66-
"packageManager": {
67-
"name": "npm",
68-
"version": ">=11.0.0"
69-
},
70-
"runtime": {
71-
"name": "node",
72-
"version": ">=24.0.0"
73-
}
63+
"devDependencies": {
64+
"@types/node": "^25.1.0",
65+
"@types/react": "19.2.10",
66+
"@types/react-dom": "19.2.3",
67+
"@typescript-eslint/eslint-plugin": "^8.54.0",
68+
"@typescript-eslint/parser": "^8.54.0",
69+
"@vitejs/plugin-react": "^5.1.2",
70+
"@vitest/coverage-v8": "^4.0.18",
71+
"babel-plugin-react-compiler": "^1.0.0",
72+
"eslint": "^9.39.2",
73+
"eslint-plugin-react-hooks": "^7.0.1",
74+
"eslint-plugin-react-refresh": "^0.4.26",
75+
"eslint-plugin-solid": "^0.14.5",
76+
"globals": "^17.2.0",
77+
"happy-dom": "^20.4.0",
78+
"prettier": "^3.8.1",
79+
"react": "^19.2.4",
80+
"react-dom": "^19.2.4",
81+
"react-error-boundary": "^6.1.0",
82+
"solid-js": "^1.9.11",
83+
"typescript": "~5.9.3",
84+
"typescript-eslint": "^8.54.0",
85+
"vite": "^7.1.12",
86+
"vite-plugin-dts": "^4.5.4",
87+
"vite-plugin-solid": "^2.11.10",
88+
"vitest": "^4.0.18"
7489
},
7590
"peerDependencies": {
7691
"react": "^19.1.0",
@@ -88,32 +103,17 @@
88103
"optional": true
89104
}
90105
},
91-
"sideEffects": false,
92-
"devDependencies": {
93-
"@types/node": "^24.9.1",
94-
"@types/react": "19.1.12",
95-
"@types/react-dom": "19.1.9",
96-
"@typescript-eslint/eslint-plugin": "^8.46.2",
97-
"@typescript-eslint/parser": "^8.46.2",
98-
"@vitejs/plugin-react": "^5.1.0",
99-
"@vitest/coverage-v8": "^4.0.3",
100-
"babel-plugin-react-compiler": "^1.0.0",
101-
"eslint": "^9.38.0",
102-
"eslint-plugin-react-hooks": "^7.0.1",
103-
"eslint-plugin-react-refresh": "^0.4.24",
104-
"eslint-plugin-solid": "^0.14.5",
105-
"globals": "^16.4.0",
106-
"happy-dom": "^20.0.8",
107-
"prettier": "^3.6.2",
108-
"react": "^19.1.1",
109-
"react-dom": "^19.1.1",
110-
"react-error-boundary": "^6.0.0",
111-
"solid-js": "^1.9.9",
112-
"typescript": "~5.9.3",
113-
"typescript-eslint": "^8.46.2",
114-
"vite": "^7.1.12",
115-
"vite-plugin-dts": "^4.5.4",
116-
"vite-plugin-solid": "^2.11.10",
117-
"vitest": "^4.0.3"
106+
"devEngines": {
107+
"packageManager": {
108+
"name": "npm",
109+
"version": ">=11.0.0"
110+
},
111+
"runtime": {
112+
"name": "node",
113+
"version": ">=24.0.0"
114+
}
115+
},
116+
"engines": {
117+
"node": ">=18.0.0"
118118
}
119119
}

0 commit comments

Comments
 (0)