@qwanyx/stack

@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

npm install @qwanyx/stack

Quick Start

1. Initialize the API client

import { initializeApiClient } from '@qwanyx/stack'

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

2. Use hooks in components

import { useQuery } from '@qwanyx/stack'

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

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <div>
      {data.map(author => (
        <div key={author.id}>{author.name}</div>
      ))}
    </div>
  )
}

3. Mutations (create/update/delete)

import { useMutation } from '@qwanyx/stack'

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

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

  return <form onSubmit={handleSubmit}>...</form>
}

API Clients

REST API Client

For standard REST APIs:

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')

Graph Client

For hierarchical data from qwanyx-brain:

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

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

useQuery

Fetch data with automatic loading and error states:

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)
  }
)

useMutation

Create, update, or delete data:

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:

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

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

const { mutate } = useMutation<Author, Partial<Author>>('belgicomics/authors', 'POST')
// mutate accepts Partial<Author> 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.