@qwanyx/stack

The Modern HyperCard - All-in-one data management system for React applications.

Stack combines everything you need to work with data:
- 🌐 REST API Client - Generic HTTP client for any API
- 🕸️ Graph Client - Hierarchical data from qwanyx-brain
- 🔐 Auth Management - Token storage and handling
- ⚛️ React Hooks - useQuery and useMutation
- 🎨 UI Components (coming soon) - Default views and editors

Philosophy

Like HyperCard's stacks were self-contained data + UI + logic, @qwanyx/stack provides everything you need to manage data in one package. No more juggling multiple libraries for API calls, auth, and state management.

React is our HyperTalk - we use React for UI instead of a custom scripting language, because React is practical and everyone knows it.

Installation

``bash
npm install @qwanyx/stack
`

Quick Start

$3

`typescript
import { initializeApiClient } from '@qwanyx/stack'

// In your app entry point
initializeApiClient({
baseUrl: 'https://api.qwanyx.com'
})
`

$3

`typescript
import { useQuery } from '@qwanyx/stack'

function AuthorsList() {
const { data, loading, error } = useQuery('belgicomics/authors', {
country: 'BE'
})

if (loading) return

Loading...

if (error) return

Error: {error.message}

return (

{data.map(author => (

{author.name}

))}

)
}
`

$3

`typescript
import { useMutation } from '@qwanyx/stack'

function CreateAuthor() {
const { mutate, loading } = useMutation('belgicomics/authors', 'POST')

const handleSubmit = async (formData) => {
await mutate(formData)
}

return

...

}
`

API Clients

$3

For standard REST APIs:

`typescript
import { getApiClient } from '@qwanyx/stack'

const client = getApiClient()

// CRUD operations
const authors = await client.get('belgicomics/authors', { country: 'BE' })
const author = await client.post('belgicomics/authors', { name: 'Hergé' })
await client.put('belgicomics/authors/123', { name: 'Updated' })
await client.delete('belgicomics/authors/123')
`

$3

For hierarchical data from qwanyx-brain:

`typescript
import { GraphClient } from '@qwanyx/stack'

const graph = new GraphClient({
baseUrl: 'https://api.qwanyx.com',
system_id: 'user-id'
})

// Work with nodes and edges
const children = await graph.getChildren(parentId)
const node = await graph.addNode({ type: 'note', title: 'Hello' })
await graph.moveNode(nodeId, newParentId)
`

Authentication

`typescript
import { AuthManager } from '@qwanyx/stack'

// Login
AuthManager.setToken('your-jwt-token')

// Check auth
if (AuthManager.isAuthenticated()) {
// User is logged in
}

// Logout
AuthManager.clearToken()

// Token is automatically added to all API requests
`

React Hooks

$3

Fetch data with automatic loading and error states:

`typescript
const { data, loading, error, refetch } = useQuery(
'endpoint',
{ filter: 'value' }, // optional params
{
enabled: true, // optional: disable auto-fetch
onSuccess: (data) => console.log(data),
onError: (error) => console.error(error)
}
)
`

$3

Create, update, or delete data:

`typescript
const { mutate, loading, error, reset } = useMutation(
'endpoint',
'POST', // or 'PUT', 'PATCH', 'DELETE'
{
onSuccess: (data) => console.log('Success!', data),
onError: (error) => console.error('Failed!', error)
}
)

await mutate({ name: 'New Item' })
`

TypeScript Support

Full TypeScript support with generics:

`typescript
interface Author {
id: string
name: string
country: string
}

const { data } = useQuery('belgicomics/authors')
// data is typed as Author[] | null

const { mutate } = useMutation>('belgicomics/authors', 'POST')
// mutate accepts Partial and returns Author
`

Architecture

Stack follows a stable API principle:

`
┌─────────────────────────────────────┐
│ Your App (Belgicomics) │
│ - React components │
│ - App-specific logic │
└─────────────┬───────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ @qwanyx/stack (this package) │
│ - API clients │
│ - Auth management │
│ - React hooks │
│ - UI components │
└─────────────┬───────────────────────┘
│
↓
┌─────────────────────────────────────┐
│ API (Rust backend) │
│ - STABLE, rarely changes │
│ - Just returns data │
└─────────────────────────────────────┘
`

The API stays simple and stable. Stack adds intelligence and evolves rapidly. Your app uses Stack's simple interface.

For Desktop Apps

Stack works great with Tauri for desktop applications:

`
Rust (backend) + Tauri (framework) + React (UI) + Stack (data) = Perfect combo
``

License

MIT

---

@qwanyx/stack - Because managing data shouldn't require 10 different packages.