@docyrus/tanstack-db-generator/README.md

Code generator utilities for TanStack Query / Database integration with Docyrus API

# @docyrus/tanstack-db-generator

Generate TanStack Query collections and TypeScript types from OpenAPI 3.1.0 specifications.

## Installation

```bash
npm install @docyrus/tanstack-db-generator
# or
pnpm add @docyrus/tanstack-db-generator
```

## Usage

### CLI

```bash
# Generate collections and types from OpenAPI spec
tanstack-db-generator path/to/openapi-spec.json

# Specify output directory
tanstack-db-generator path/to/openapi-spec.json -o ./src/generated
```

### Programmatic API

```typescript
import { generateFromOpenAPI } from '@docyrus/tanstack-db-generator';

const spec = JSON.parse(fs.readFileSync('openapi-spec.json', 'utf-8'));
await generateFromOpenAPI(spec, './src');
```

## Features

- Automatically generates TanStack Query collections for CRUD operations
- Creates TypeScript type definitions from OpenAPI schemas
- Supports dataSource endpoints with the following pattern:
  - `GET /v1/apps/:appName/data-sources/:dataSourceName/items` - List items
  - `GET /v1/apps/:appName/data-sources/:dataSourceName/items/:itemId` - Get single item
  - `POST /v1/apps/:appName/data-sources/:dataSourceName/items` - Create item
  - `PATCH /v1/apps/:appName/data-sources/:dataSourceName/items/:itemId` - Update item
  - `DELETE /v1/apps/:appName/data-sources/:dataSourceName/items/:itemId` - Delete item
  - `DELETE /v1/apps/:appName/data-sources/:dataSourceName/items` - Delete many items

## Generated Files Structure

```
src/db/
├── types/
│   └── index.ts          # TypeScript interfaces and Zod schemas
├── collections/
│   ├── app-datasource.collection.ts   # Individual collection files
│   └── index.ts          # Exports all collections
└── index.ts              # Main entry point
```

## Example Usage

After generation, you can use the collections in your React components:

```tsx
import { useDrizzleQuery } from '@tanstack/react-db';
import { baseContactCollection } from './db/collections';

function ContactList() {
  const { data, isLoading, error } = useDrizzleQuery(
    baseContactCollection.list()
  );

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

  return (
    <ul>
      {data?.data.map(contact => (
        <li key={contact.id}>{contact.name}</li>
      ))}
    </ul>
  );
}
```

## License

MIT