@promakeai/dbreact 1.0.1

package/README.md

@@ -0,0 +1,633 @@
+# @promakeai/dbreact
+
+React hooks and providers for schema-driven, multi-language databases. Type-safe, with automatic translation support.
+
+## Features
+
+- **Type-Safe Hooks** - Generated TypeScript types and React hooks
+- **Multi-Language Support** - Automatic translation queries with fallback
+- **Browser SQLite** - sql.js WASM adapter for offline-first apps
+- **React Query Integration** - Built-in caching, loading states, optimistic updates
+- **Zero-Config Language Switching** - Change language, queries refetch automatically
+- **MongoDB-Style Queries** - Intuitive filter syntax (`$gt`, `$in`, `$like`, etc.)
+
+## Installation
+
+```bash
+npm install @promakeai/dbreact @tanstack/react-query
+```
+
+**Peer Dependencies:**
+- `react` >= 18.0.0
+- `@tanstack/react-query` >= 5.0.0
+
+## Quick Start
+
+### 1. Setup Adapter
+
+```tsx
+import { SqliteAdapter } from '@promakeai/dbreact';
+
+const adapter = new SqliteAdapter({
+  storageKey: 'myapp-db',  // localStorage key for persistence
+});
+```
+
+### 2. Wrap App with Provider
+
+```tsx
+import { DbProvider } from '@promakeai/dbreact';
+
+function App() {
+  const [lang, setLang] = useState('en');
+
+  return (
+    <DbProvider
+      adapter={adapter}
+      lang={lang}
+      fallbackLang="en"
+      autoConnect={true}
+    >
+      <MyApp />
+    </DbProvider>
+  );
+}
+```
+
+### 3. Use Hooks
+
+```tsx
+import { useDbList, useDbGet, useDbCreate } from '@promakeai/dbreact';
+
+function ProductList() {
+  // List with filters
+  const { data: products, isLoading } = useDbList('products', {
+    where: { stock: { $gt: 0 } },
+    orderBy: [{ field: 'name', direction: 'ASC' }],
+    limit: 20,
+  });
+
+  // Create mutation
+  const createProduct = useDbCreate('products');
+
+  const handleCreate = () => {
+    createProduct.mutate({
+      sku: 'NEW-001',
+      price: 99.99,
+    });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {products?.map(p => <ProductCard key={p.id} product={p} />)}
+      <button onClick={handleCreate}>Add Product</button>
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### DbProvider
+
+Main provider component that wraps your application.
+
+```tsx
+<DbProvider
+  adapter={adapter}
+  lang="tr"
+  fallbackLang="en"
+  autoConnect={true}
+>
+  <App />
+</DbProvider>
+```
+
+**Props:**
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `adapter` | `IDataAdapter` | Yes | - | Database adapter instance |
+| `lang` | `string` | No | `'en'` | Current language code |
+| `fallbackLang` | `string` | No | `'en'` | Fallback language |
+| `autoConnect` | `boolean` | No | `true` | Auto-connect on mount |
+| `children` | `ReactNode` | Yes | - | Child components |
+
+---
+
+### Query Hooks
+
+#### useDbList
+
+Fetch multiple records with filtering, pagination, and sorting.
+
+```tsx
+const { data, isLoading, error, refetch } = useDbList<Product>('products', {
+  where: { stock: { $gt: 0 } },
+  orderBy: [{ field: 'price', direction: 'DESC' }],
+  limit: 20,
+  offset: 0,
+  enabled: true,
+});
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `where` | `object` | MongoDB-style filter conditions |
+| `orderBy` | `array` | Sort order `[{ field, direction }]` |
+| `limit` | `number` | Max records to return |
+| `offset` | `number` | Skip records |
+| `populate` | `string[]` | Resolve foreign key references |
+| `enabled` | `boolean` | Enable/disable query |
+
+#### useDbGet
+
+Fetch single record by ID.
+
+```tsx
+const { data: product, isLoading } = useDbGet<Product>('products', productId, {
+  populate: ['categoryId'],
+  enabled: !!productId,
+});
+```
+
+---
+
+### Mutation Hooks
+
+#### useDbCreate
+
+Create a new record.
+
+```tsx
+const createProduct = useDbCreate<Product>('products');
+
+createProduct.mutate(
+  { sku: 'NEW-001', price: 99.99 },
+  {
+    onSuccess: (data) => console.log('Created:', data),
+    onError: (error) => console.error(error),
+  }
+);
+```
+
+#### useDbUpdate
+
+Update an existing record.
+
+```tsx
+const updateProduct = useDbUpdate<Product>('products', productId);
+
+updateProduct.mutate(
+  { price: 89.99 },
+  {
+    onSuccess: () => console.log('Updated'),
+  }
+);
+```
+
+#### useDbDelete
+
+Delete a record.
+
+```tsx
+const deleteProduct = useDbDelete('products', productId);
+
+deleteProduct.mutate(undefined, {
+  onSuccess: () => console.log('Deleted'),
+});
+```
+
+---
+
+### Context Hooks
+
+#### useDb
+
+Access database connection status.
+
+```tsx
+const { adapter, isConnected, error } = useDb();
+
+if (!isConnected) return <div>Connecting...</div>;
+```
+
+#### useAdapter
+
+Access adapter directly for raw queries.
+
+```tsx
+const adapter = useAdapter();
+
+const handleRawQuery = async () => {
+  const results = await adapter.raw('SELECT * FROM products WHERE price > ?', [100]);
+  console.log(results);
+};
+```
+
+#### useDbLang
+
+Access and control language settings.
+
+```tsx
+const { lang, fallbackLang, setLang } = useDbLang();
+
+// Language switcher
+<select value={lang} onChange={e => setLang(e.target.value)}>
+  <option value="en">English</option>
+  <option value="tr">Turkce</option>
+  <option value="de">Deutsch</option>
+</select>
+```
+
+---
+
+### SqliteAdapter
+
+Browser-based SQLite storage using sql.js (WebAssembly).
+
+```tsx
+const adapter = new SqliteAdapter({
+  storageKey: 'myapp-db',     // localStorage key for persistence
+  schema: mySchema,           // Optional: schema definition
+  initialData: seedData,      // Optional: initial seed data
+});
+```
+
+**Features:**
+- Automatic persistence to localStorage
+- Full SQL support
+- Works offline
+- WASM-based (no native dependencies)
+
+**Limitations:**
+- Data stored in browser only
+- localStorage limit: ~5-10MB (browser dependent)
+- Best for < 10,000 records
+
+---
+
+## Query Options
+
+### MongoDB-Style Filters
+
+```typescript
+// Comparison
+{ price: { $gt: 100 } }              // > 100
+{ price: { $gte: 100 } }             // >= 100
+{ price: { $lt: 100 } }              // < 100
+{ price: { $lte: 100 } }             // <= 100
+{ price: { $ne: 100 } }              // != 100
+{ price: { $eq: 100 } }              // = 100
+
+// Array
+{ id: { $in: [1, 2, 3] } }           // IN (1, 2, 3)
+{ id: { $nin: [1, 2, 3] } }          // NOT IN (1, 2, 3)
+
+// String
+{ name: { $like: '%shirt%' } }       // LIKE '%shirt%'
+{ name: { $notLike: '%test%' } }     // NOT LIKE '%test%'
+
+// Range
+{ price: { $between: [10, 100] } }   // BETWEEN 10 AND 100
+
+// Null
+{ description: { $isNull: true } }   // IS NULL
+{ description: { $isNull: false } }  // IS NOT NULL
+
+// Logical
+{ $and: [
+  { price: { $gt: 50 } },
+  { stock: { $gt: 0 } }
+]}
+
+{ $or: [
+  { category: 'shirts' },
+  { category: 'pants' }
+]}
+
+{ $not: { price: { $lt: 100 } } }    // NOT (price < 100)
+```
+
+### Query Interface
+
+```typescript
+interface QueryOptions {
+  where?: Record<string, unknown>;
+  orderBy?: Array<{
+    field: string;
+    direction: 'ASC' | 'DESC';
+  }>;
+  limit?: number;
+  offset?: number;
+  populate?: string[];
+  lang?: string;
+  fallbackLang?: string;
+}
+```
+
+---
+
+## Multi-Language Support
+
+### Schema with Translatable Fields
+
+```typescript
+import { defineSchema, f } from '@promakeai/orm';
+
+const schema = defineSchema({
+  languages: ['en', 'tr', 'de'],
+  tables: {
+    products: {
+      id: f.id(),
+      price: f.decimal(),
+      name: f.string().translatable(),      // In translation table
+      description: f.text().translatable(), // In translation table
+    },
+  },
+});
+```
+
+### Automatic Translation
+
+Queries automatically use the current language from DbProvider:
+
+```tsx
+function ProductList() {
+  // Automatically fetches in current language
+  const { data: products } = useDbList('products');
+
+  // products[0].name is in Turkish if lang='tr'
+  // Falls back to English if Turkish translation missing
+}
+```
+
+### Language Switching
+
+When you change language, React Query automatically refetches all queries:
+
+```tsx
+function LanguageSwitcher() {
+  const { lang, setLang } = useDbLang();
+
+  return (
+    <select value={lang} onChange={e => setLang(e.target.value)}>
+      <option value="en">English</option>
+      <option value="tr">Turkce</option>
+    </select>
+  );
+}
+```
+
+---
+
+## Generated Hooks
+
+Generate type-safe hooks from your schema:
+
+```bash
+dbcli generate --schema ./schema.ts --output ./src/db/generated
+```
+
+**Generated files:**
+- `types.ts` - TypeScript interfaces for each table
+- `hooks.ts` - Type-safe hooks for each table
+
+```tsx
+// Generated hooks usage
+import { useProducts, useProduct, useCreateProduct } from './db/generated/hooks';
+
+function ProductManager() {
+  const { data: products } = useProducts({
+    where: { stock: { $gt: 0 } },
+  });
+
+  const { data: product } = useProduct(1);
+
+  const createProduct = useCreateProduct();
+
+  return (
+    // ...
+  );
+}
+```
+
+---
+
+## Advanced Usage
+
+### Custom React Query Options
+
+```tsx
+const { data } = useDbList('products', {
+  where: { active: true },
+}, {
+  // React Query options
+  staleTime: 1000 * 60 * 5,  // 5 minutes
+  gcTime: 1000 * 60 * 30,    // 30 minutes
+  refetchOnWindowFocus: false,
+  retry: 3,
+});
+```
+
+### Direct Adapter Access
+
+For complex queries not covered by hooks:
+
+```tsx
+function AdvancedSearch() {
+  const adapter = useAdapter();
+  const [results, setResults] = useState([]);
+
+  const handleSearch = async (query: string) => {
+    const products = await adapter.list('products', {
+      where: {
+        $or: [
+          { name: { $like: `%${query}%` } },
+          { description: { $like: `%${query}%` } },
+        ],
+      },
+      limit: 50,
+    });
+    setResults(products);
+  };
+
+  return <SearchInput onSearch={handleSearch} />;
+}
+```
+
+### Optimistic Updates
+
+```tsx
+function ProductPrice({ product }) {
+  const queryClient = useQueryClient();
+  const updateProduct = useDbUpdate('products', product.id);
+
+  const handlePriceChange = async (newPrice: number) => {
+    // Optimistic update
+    queryClient.setQueryData(
+      ['products', 'detail', product.id],
+      { ...product, price: newPrice }
+    );
+
+    await updateProduct.mutateAsync({ price: newPrice });
+  };
+
+  return <PriceInput value={product.price} onChange={handlePriceChange} />;
+}
+```
+
+---
+
+## Examples
+
+### E-Commerce Product List
+
+```tsx
+function Shop() {
+  const { lang } = useDbLang();
+  const [category, setCategory] = useState(null);
+
+  const { data: products, isLoading } = useDbList('products', {
+    where: category ? { categoryId: category } : {},
+    orderBy: [{ field: 'name', direction: 'ASC' }],
+  });
+
+  if (isLoading) return <Spinner />;
+
+  return (
+    <div>
+      <CategoryFilter onSelect={setCategory} />
+      <ProductGrid products={products} />
+    </div>
+  );
+}
+```
+
+### Multi-Language Blog
+
+```tsx
+function BlogPost({ slug }: { slug: string }) {
+  const { data: posts } = useDbList('posts', {
+    where: { slug, published: true },
+    limit: 1,
+  });
+
+  const post = posts?.[0];
+  if (!post) return <NotFound />;
+
+  return (
+    <article>
+      <h1>{post.title}</h1>         {/* Auto-translated */}
+      <div>{post.content}</div>     {/* Auto-translated */}
+    </article>
+  );
+}
+```
+
+### Real-Time Search
+
+```tsx
+function ProductSearch() {
+  const adapter = useAdapter();
+  const [query, setQuery] = useState('');
+
+  const { data: results } = useQuery({
+    queryKey: ['search', query],
+    queryFn: () => adapter.list('products', {
+      where: {
+        $or: [
+          { name: { $like: `%${query}%` } },
+          { sku: { $like: `%${query}%` } },
+        ],
+      },
+      limit: 10,
+    }),
+    enabled: query.length > 2,
+  });
+
+  return (
+    <div>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <SearchResults results={results} />
+    </div>
+  );
+}
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with generated types:
+
+```typescript
+import type { Product, ProductInput } from './db/generated/types';
+
+// Type-safe queries
+const products: Product[] = await adapter.list('products');
+
+// Type-safe creates
+const newProduct: ProductInput = {
+  sku: 'SHIRT-001',
+  price: 99.99,
+};
+
+await adapter.create('products', newProduct);
+```
+
+---
+
+## Performance Tips
+
+1. **Use pagination** for large datasets:
+   ```tsx
+   const { data } = useDbList('products', { limit: 20, offset: page * 20 });
+   ```
+
+2. **Enable query conditionally**:
+   ```tsx
+   const { data } = useDbGet('products', id, { enabled: !!id });
+   ```
+
+3. **Prefetch next page**:
+   ```tsx
+   queryClient.prefetchQuery({
+     queryKey: ['products', 'list', { offset: (page + 1) * 20 }],
+     queryFn: () => adapter.list('products', { offset: (page + 1) * 20 }),
+   });
+   ```
+
+---
+
+## Troubleshooting
+
+**"useDbLang must be used within a DbProvider"**
+- Ensure component is wrapped in DbProvider
+
+**Queries return empty results**
+- Check adapter is connected: `const { isConnected } = useDb()`
+- Verify data exists in database
+- Check query filters are correct
+
+**Translations not working**
+- Ensure schema has `.translatable()` fields
+- Run `dbcli generate` to create translation tables
+- Check translation records exist in `{table}_translations`
+
+---
+
+## Related Packages
+
+- [@promakeai/orm](../orm) - Core ORM with schema DSL
+- [@promakeai/dbcli](../dbcli) - CLI tool for database operations
+
+## License
+
+MIT