Documentation

.gitignore

@@ -24,3 +24,6 @@ dist-ssr
 *.sw?
 
 tsconfig.vitest-temp.json
+
+docs/.vitepress/cache
+docs/.vitepress/dist

README.md

@@ -1,2 +1,79 @@
-# query
-A typescript library for state management in Vue components
+# @kitbag/query
+
+A type-safe, composable query system designed specifically for Vue.js applications. Built for Vue 3's Composition API with intelligent caching, tag-based invalidation, and full TypeScript support.
+
+[![NPM Version][npm-badge]][npm-url]
+[![Netlify Status][netlify-badge]][netlify-url]
+[![Discord chat][discord-badge]][discord-url]
+[![Open in StackBlitz][stackblitz-badge]][stackblitz-url]
+
+<img src="https://kitbag.dev/kitbag-logo.svg" width="20%" />
+
+## Getting Started
+
+Get Started with our [documentation](https://kitbag-query.netlify.app/)
+
+## Features
+
+- **Type Safety First** - Fully typed queries, mutations, and data transformations
+- **Vue 3 Native** - Built for Composition API with reactive composables
+- **Intelligent Caching** - Smart caching with tag-based invalidation system
+- **Error Handling** - Built-in loading states, error handling, and retry logic
+- **Optimistic Updates** - Seamless mutations with automatic rollback on failure
+- **Composable Architecture** - Reusable functions that feel natural in Vue
+
+## Quick Start
+
+### Installation
+
+```bash
+# bun
+bun add @kitbag/query
+# yarn
+yarn add @kitbag/query
+# npm
+npm install @kitbag/query
+```
+
+### Creating a query
+
+Simply pass the function (`searchCats`) and a getter for the arguments to that function (`() => ['Maine Coon']`).
+
+```ts
+import { useQuery } from '@kitbag/query'
+
+function searchCats(breed?: string) {
+  ...
+}
+
+const catsQuery = useQuery(searchCats, () => ['Maine Coon'])
+```
+
+That's it! Now you have access to several useful properties on the query for tracking loading state, error state, and of course the response from `searchCats` when it's resolved.
+
+### Using a query
+
+```vue
+<template>
+  <div v-if="catsQuery.loading">
+    Loading...
+  </div>
+
+  <div v-else-if="catsQuery.errored">
+    Error: {{ catsQuery.error }}
+  </div>
+
+  <div v-for="cat in catsQuery.data ?? []" :key="cat.id">
+    <h1>{{ cat.name }}</h1>
+  </div>
+</template>
+```
+
+[npm-badge]: https://img.shields.io/npm/v/@kitbag/query.svg
+[npm-url]: https://www.npmjs.org/package/@kitbag/query
+[netlify-badge]: https://api.netlify.com/api/v1/badges/c12f79b8-49f9-4529-bc23-f8ffca8919a3/deploy-status
+[netlify-url]: https://app.netlify.com/sites/kitbag-query/deploys
+[stackblitz-badge]: https://developer.stackblitz.com/img/open_in_stackblitz_small.svg
+[stackblitz-url]: https://stackblitz.com/~/github.com/kitbagjs/query-preview
+[discord-badge]: https://img.shields.io/discord/1079625926024900739?logo=discord&label=Discord
+[discord-url]: https://discord.gg/zw7dpcc5HV

docs/.vitepress/config.ts

@@ -0,0 +1,99 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Kitbag Query | Type safe query for Vue.js",
+  description: "Type safe query for Vue.js",
+  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],
+  themeConfig: {
+    logo: '/kitbag-logo-circle.svg',
+    siteTitle: 'Kitbag Query',
+
+    editLink: {
+      pattern: 'https://github.com/kitbagjs/query/edit/main/docs/:path',
+      text: 'Suggest changes to this page',
+    },
+
+    nav: [
+      { text: 'Guide', link: '/introduction' },
+      { text: 'API', link: '/api/index' }
+    ],
+
+    search: {
+      provider: 'local'
+    },
+
+    sidebar: {
+      '/api/': [
+        {
+          text: 'API Reference',
+          items: [
+            { text: 'Overview', link: '/api/index' },
+          ]
+        }
+      ],
+      '/': [
+        {
+          text: 'Getting Started',
+          items: [
+            {
+              text: 'Introduction',
+              link: '/introduction',
+            },
+            {
+              text: 'Quick Start',
+              link: '/quick-start',
+            },
+          ],
+        },
+        {
+          text: 'Core Concepts',
+          items: [
+            { text: 'Queries', link: '/core-concepts/queries' },
+            { text: 'Tags & Invalidation', link: '/core-concepts/tags-invalidation' },
+            { text: 'Mutations', link: '/core-concepts/mutations' },
+            { text: 'Query Client', link: '/core-concepts/query-client' },
+            { text: 'Caching', link: '/core-concepts/caching' },
+          ],
+        },
+        {
+          text: 'Advanced Concepts',
+          items: [
+            { text: 'Error Handling', link: '/advanced-concepts/error-handling' },
+            { text: 'Loading States', link: '/advanced-concepts/loading-states' },
+            { text: 'Background Updates', link: '/advanced-concepts/background-updates' },
+            { text: 'Optimistic Updates', link: '/advanced-concepts/optimistic-updates' },
+            { text: 'Using syntax', link: '/advanced-concepts/using-queries' },
+          ],
+        },
+        { text: 'Migrating from Tanstack', link: '/compare-to-tanstack' },
+      ]
+    },
+
+    socialLinks: [
+      {
+        icon: {
+          svg: `<svg fill="#000000" height="800px" width="800px" version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
+        viewBox="0 0 330.242 330.242" xml:space="preserve">
+     <path d="M324.442,129.811l-41.321-33.677V42.275c0-6.065-4.935-11-11-11h-26c-6.065,0-11,4.935-11,11v14.737l-55.213-44.999
+       c-3.994-3.254-9.258-5.047-14.822-5.047c-5.542,0-10.781,1.782-14.753,5.019L5.8,129.81c-6.567,5.351-6.173,10.012-5.354,12.314
+       c0.817,2.297,3.448,6.151,11.884,6.151h19.791v154.947c0,11.058,8.972,20.053,20,20.053h62.5c10.935,0,19.5-8.809,19.5-20.053
+       v-63.541c0-5.446,5.005-10.405,10.5-10.405h42c5.238,0,9.5,4.668,9.5,10.405v63.541c0,10.87,9.388,20.053,20.5,20.053h61.5
+       c11.028,0,20-8.996,20-20.053V148.275h19.791c8.436,0,11.066-3.854,11.884-6.151C330.615,139.822,331.009,135.161,324.442,129.811z"
+       />
+     </svg>`
+        },
+        link: 'https://kitbag.dev',
+        ariaLabel: 'Kitbag Home'
+      },
+      { icon: 'github', link: 'https://github.com/kitbagjs/query' },
+      { icon: 'discord', link: 'https://discord.gg/zw7dpcc5HV' },
+      { icon: 'npm', link: 'https://www.npmjs.com/package/@kitbag/query' },
+    ]
+  },
+  markdown: {
+    image: {
+      lazyLoading: true
+    }
+  }
+})

docs/.vitepress/theme/index.js

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './styles/vars.css'
+
+export default DefaultTheme

docs/.vitepress/theme/styles/vars.css

@@ -0,0 +1,39 @@
+:root {
+  --kitbag-teal-300: rgba(94, 234, 212, 1);
+  --kitbag-teal-500: rgba(20, 184, 166, 1);
+  --kitbag-amber-500: rgba(245, 158, 11, 1);
+  --kitbag-teal-500-75: rgba(20, 184, 166, 0.75);
+
+  --vp-button-brand-bg: var(--kitbag-teal-500-75);
+  --vp-c-brand-1: var(--kitbag-teal-500);
+  --vp-c-brand-2: var(--kitbag-amber-500);
+
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    var(--kitbag-teal-300) 30%,
+    var(--kitbag-amber-500)
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    var(--kitbag-teal-500) 50%,
+    var(--kitbag-amber-500) 50%
+  );
+  --vp-home-hero-image-filter: blur(40px);
+}
+
+a.alt.stackblitz {
+  display: flex;
+  align-items: center;
+  color: rgb(19, 137, 253);
+  gap: 0.2rem;
+}
+
+a.alt.stackblitz::after {
+  display: block;
+  height: 14px;
+  width: 14px;
+  content: '';
+  background-image: url('/stackblitz.svg');
+}