feat(COMPT-44): README guide + changeset for v0.1.0

[a-elkhiraooui-ciscode]

• Rewrote README as an end-to-end usage guide for @ciscode/query-kit
• createQuery: key builder, fetcher, useQuery shorthand, direct key/fn access
• usePaginatedQuery: offset mode (nextPage/prevPage) and cursor mode (fetchNextPage/hasNextPage)
• createMutation + invalidateQueries full lifecycle example
• setQueryData typed updater example
• API reference table covering all exports
• Peer dep @tanstack/react-query >=5 clearly stated
• Changeset: minor bump to v0.1.0 (initial public release)

Summary

• What does this PR change?

Why

• Why is this change needed?

Checklist

• Added/updated tests (if behavior changed)
• npm run lint passes
• npm run typecheck passes
• npm test passes
• npm run build passes
• Added a changeset (npx changeset) if this affects consumers

Notes

• Anything reviewers should pay attention to?

[Copilot]

Pull request overview

This PR prepares @ciscode/query-kit for its initial public release by replacing the template README with an end-to-end usage guide and adding a Changesets entry for a 0.1.0 release.

Changes:

• Rewrites README.md into a usage guide covering createQuery, usePaginatedQuery, createMutation, and cache helpers.
• Adds an API reference table and release flow notes to the README.
• Adds a changeset to bump @ciscode/query-kit to v0.1.0.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
README.md	New usage guide and API reference for query-kit consumers.
.changeset/v0-1-0-initial-release.md	Changesets entry for initial public release version bump.

[Copilot]

In this snippet, userQuery.useQuery returns UseQueryResult<User, Error> where data is User | undefined and error is Error | null. As written, error.message and data.name/data.email won’t typecheck without additional guards (e.g., check error/data or use optional chaining).

[Copilot]

The example implies postsQuery’s key/fetcher take { page, pageSize }, but usePaginatedQuery already appends page and pageSize onto the generated queryKey (and also passes them into queryDef.queryKey). If the query definition’s key builder includes page/pageSize, keys will contain duplicates (e.g., ['posts', page, pageSize, page, pageSize]). Consider clarifying the expected key builder shape for paginated queries to avoid confusing/unstable keys.

Suggested change

	// postsQuery is a createQuery definition whose fetcher accepts { page, pageSize }
	export function PostsList() {
	const { data, isLoading, page, pageSize, nextPage, prevPage } = usePaginatedQuery(
	postsQuery,
	{ page: 1, pageSize: 10 },
	// For usePaginatedQuery, postsQuery should define only non-pagination params.
	// The hook manages page and pageSize internally for the generated query key/fetching.
	export function PostsList() {
	const { data, isLoading, page, pageSize, nextPage, prevPage } = usePaginatedQuery(
	postsQuery,
	{},

[Copilot]

The docs say calling invalidateQueries(queryClient, userQuery) invalidates all queries matching the query’s key prefix, but the current implementation calls queryDef.queryKey({} as TParams) when params are omitted. For definitions like ['users', params.id], this becomes ['users', undefined] and will not match/invalidate existing user queries. Either update the docs to require params (or explain the keyFn must handle empty params), or change the helper to invalidate by a real prefix key.

[Copilot]

This snippet uses error.message inside {isError && ...}, but TanStack mutation results type error as Error | null, and isError doesn’t narrow error to non-null for TypeScript. Use optional chaining or an explicit if (error) check so the example typechecks.

Suggested change

	{isError && <p role="alert">Error: {error.message}</p>}
	{isError && <p role="alert">Error: {error?.message ?? 'Unknown error'}</p>}

[Copilot]

The API reference table doesn’t reflect everything that’s currently exported from the package (e.g., NoopButton, useNoop, noop, and the __*_placeholder exports are re-exported from src/index.ts). Either add these to the table or remove/stop exporting the placeholders so the README matches the actual public API.

Suggested change

	| Export | Kind | Description |
	| ------------------------- | ---------- | -------------------------------------------------- |
	| `createQuery` | `function` | Creates a `QueryDefinition` (key + fetcher + hook) |
	| `usePaginatedQuery` | `function` | Offset or cursor pagination hook |
	| `createMutation` | `function` | Creates a `MutationDefinition` (fn + hook) |
	| `invalidateQueries` | `function` | Type-safe query invalidation via `QueryDefinition` |
	| `setQueryData` | `function` | Type-safe cache write via `QueryDefinition` |
	| `QueryDefinition` | `type` | Shape returned by `createQuery` |
	| `MutationDefinition` | `type` | Shape returned by `createMutation` |
	| `OffsetPaginationOptions` | `type` | Options for `usePaginatedQuery` offset mode |
	| `CursorPaginationOptions` | `type` | Options for `usePaginatedQuery` cursor mode |
	| Export | Kind | Description |
	| ------------------------- | ------------------- | -------------------------------------------------- |
	| `createQuery` | `function` | Creates a `QueryDefinition` (key + fetcher + hook) |
	| `usePaginatedQuery` | `function` | Offset or cursor pagination hook |
	| `createMutation` | `function` | Creates a `MutationDefinition` (fn + hook) |
	| `invalidateQueries` | `function` | Type-safe query invalidation via `QueryDefinition` |
	| `setQueryData` | `function` | Type-safe cache write via `QueryDefinition` |
	| `noop` | `function` | No-op utility export |
	| `useNoop` | `function` | No-op hook export |
	| `NoopButton` | `component` | No-op button component export |
	| `__*_placeholder` | `internal export(s)`| Placeholder re-exports currently exposed publicly |
	| `QueryDefinition` | `type` | Shape returned by `createQuery` |
	| `MutationDefinition` | `type` | Shape returned by `createMutation` |
	| `OffsetPaginationOptions` | `type` | Options for `usePaginatedQuery` offset mode |
	| `CursorPaginationOptions` | `type` | Options for `usePaginatedQuery` cursor mode |

[Copilot]

Release flow branch naming here (feat/*) conflicts with other repo docs/workflows that mention feature/* as well (e.g., CONTRIBUTING uses feature/amazing-feature, and publish workflow mentions feat/** or feature/**). Aligning these instructions will reduce confusion for contributors.

Suggested change

	- Work on a `feat/*` branch from `develop`
	- Work on a `feature/*` branch from `develop`