@promakeai/dbreact 1.0.1 → 1.0.4

package/SKILL.md

@@ -1,311 +0,0 @@
----
-name: dbreact
-description: |
-  React hooks and providers for schema-driven multi-language databases (@promakeai/dbreact).
-  Use when: integrating React apps with SQLite database, using DbProvider setup,
-  data hooks (useDbList, useDbGet, useDbCreate, useDbUpdate, useDbDelete),
-  language switching (useDbLang), SqliteAdapter for browser, React Query patterns,
-  or any @promakeai/dbreact task.
----
-
-# dbreact - React Database Integration
-
-## Installation
-
-```bash
-npm install @promakeai/dbreact @promakeai/orm @tanstack/react-query sql.js
-```
-
-Peer dependencies: `react >= 18`, `react-dom >= 18`, `@tanstack/react-query >= 5`
-
----
-
-## Quick Setup
-
-```tsx
-import { DbProvider, SqliteAdapter, parseJSONSchema } from '@promakeai/dbreact';
-import schema from './db/schema.json';
-
-const adapter = new SqliteAdapter({
-  storageKey: 'myapp',
-  schema: parseJSONSchema(schema),
-  defaultLang: 'en',
-});
-
-function App() {
-  return (
-    <DbProvider adapter={adapter} lang="en" fallbackLang="en">
-      <YourApp />
-    </DbProvider>
-  );
-}
-```
-
----
-
-## DbProvider Props
-
-```tsx
-interface DbProviderProps {
-  adapter: IDataAdapter;       // Required: SqliteAdapter instance
-  lang?: string;               // Current language (default: 'en')
-  fallbackLang?: string;       // Fallback if translation missing (default: 'en')
-  autoConnect?: boolean;       // Auto-connect on mount (default: true)
-  queryClient?: QueryClient;   // Custom React Query client (optional)
-}
-```
-
-Language changes automatically invalidate all queries and refetch with new language.
-
----
-
-## SqliteAdapter Config
-
-```tsx
-const adapter = new SqliteAdapter({
-  storageKey: 'myapp',           // localStorage key
-  schema: parsedSchema,          // For translation support
-  defaultLang: 'en',             // Default language
-  initialData?: Uint8Array,      // Seed with existing DB
-  wasmPath?: string,             // Custom sql.js WASM path
-});
-```
-
-### Loading Existing Database
-
-```tsx
-// Load from base64 file
-const response = await fetch('/app.db.b64');
-const base64 = await response.text();
-const bytes = Uint8Array.from(atob(base64), c => c.charCodeAt(0));
-
-const adapter = new SqliteAdapter({
-  storageKey: 'myapp',
-  initialData: bytes,
-  schema: parseJSONSchema(schema),
-});
-```
-
----
-
-## Data Hooks
-
-### useDbList<T>(table, options?)
-
-Query multiple records.
-
-```tsx
-interface ListOptions {
-  where?: Record<string, unknown>;  // MongoDB-style filter
-  orderBy?: Array<{ field: string; direction: 'ASC' | 'DESC' }>;
-  limit?: number;
-  offset?: number;
-  enabled?: boolean;  // Conditional query
-}
-
-function ProductList() {
-  const { data, isLoading, error } = useDbList<Product>('products', {
-    where: { stock: { $gt: 0 } },
-    orderBy: [{ field: 'name', direction: 'ASC' }],
-    limit: 10,
-  });
-
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-
-  return <ul>{data?.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
-}
-```
-
-### useDbGet<T>(table, id, options?)
-
-Fetch single record by ID.
-
-```tsx
-function ProductDetail({ id }: { id: number }) {
-  const { data: product, isLoading } = useDbGet<Product>('products', id);
-
-  if (isLoading) return <div>Loading...</div>;
-  if (!product) return <div>Not found</div>;
-
-  return <div>{product.name} - ${product.price}</div>;
-}
-```
-
-### useDbCreate<T>(table)
-
-Create new record.
-
-```tsx
-function CreateProduct() {
-  const mutation = useDbCreate<Product>('products');
-
-  const handleCreate = () => {
-    mutation.mutate({ name: 'New Product', price: 99 });
-  };
-
-  return (
-    <button onClick={handleCreate} disabled={mutation.isPending}>
-      {mutation.isPending ? 'Creating...' : 'Create'}
-    </button>
-  );
-}
-```
-
-### useDbUpdate<T>(table)
-
-Update existing record.
-
-```tsx
-function EditProduct({ id }: { id: number }) {
-  const mutation = useDbUpdate<Product>('products');
-
-  const handleUpdate = () => {
-    mutation.mutate({ id, data: { price: 149 } });
-  };
-
-  return <button onClick={handleUpdate}>Update Price</button>;
-}
-```
-
-### useDbDelete(table)
-
-Delete record by ID.
-
-```tsx
-function DeleteProduct({ id }: { id: number }) {
-  const mutation = useDbDelete('products');
-
-  return (
-    <button onClick={() => mutation.mutate(id)}>
-      {mutation.isPending ? 'Deleting...' : 'Delete'}
-    </button>
-  );
-}
-```
-
----
-
-## Language Hook
-
-### useDbLang()
-
-Access and change current language.
-
-```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">Turkish</option>
-      <option value="de">German</option>
-    </select>
-  );
-}
-```
-
-When `setLang()` is called:
-1. Provider state updates
-2. All queries invalidated
-3. Queries refetch with new language
-4. UI updates automatically
-
----
-
-## Context Hooks
-
-### useDb()
-
-Access connection state.
-
-```tsx
-const { adapter, isConnected, error } = useDb();
-```
-
-### useAdapter()
-
-Direct adapter access for advanced operations.
-
-```tsx
-const adapter = useAdapter();
-await adapter.createWithTranslations('products', data, translations);
-```
-
----
-
-## Query Operators
-
-Same MongoDB-style operators as dbcli:
-
-```tsx
-useDbList('products', {
-  where: {
-    $and: [
-      { price: { $between: [50, 500] } },
-      { stock: { $gt: 0 } },
-      { categoryId: { $in: [1, 5, 10] } },
-      { $or: [{ active: true }, { featured: true }] }
-    ]
-  }
-});
-```
-
-Operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$like`, `$notLike`, `$between`, `$isNull`, `$and`, `$or`, `$nor`, `$not`
-
----
-
-## Type Definitions
-
-Use generated types from `dbcli generate`:
-
-```tsx
-// src/db/types.ts (generated)
-export interface DbProduct {
-  id: number;
-  name: string;
-  price: number;
-  stock: number;
-}
-
-// Usage
-const { data } = useDbList<DbProduct>('products');
-const mutation = useDbCreate<DbProduct>('products');
-```
-
----
-
-## Best Practices
-
-1. **Single DbProvider at root** - Don't nest providers
-2. **Use generated types** - Type safety with `DbXxx` interfaces
-3. **Conditional queries** - Use `enabled: false` to prevent unwanted fetches
-4. **Handle all states** - Check `isLoading`, `error`, and empty data
-5. **Language via hook** - Use `setLang()` not prop changes for proper invalidation
-6. **Batch with adapter** - Use `adapter.createMany()` for bulk operations
-7. **Check connection** - Use `useDb().isConnected` before critical operations
-
----
-
-## Exports
-
-```tsx
-// Provider & Context
-export { DbProvider, useDb, useAdapter, useDbLang };
-
-// Data Hooks
-export { useDbList, useDbGet, useDbCreate, useDbUpdate, useDbDelete };
-
-// Adapter
-export { SqliteAdapter };
-
-// Schema
-export { parseJSONSchema, defineSchema, f };
-
-// Query Utilities
-export { buildWhereClause };
-
-// Types
-export type { DbProviderConfig, DbContextValue, DbLangContextValue, ListOptions };
-```

package/providers/DbProvider.tsx

@@ -1,191 +0,0 @@
-/**
- * Database Provider
- *
- * React context provider for database operations with language support.
- */
-
-import {
-  createContext,
-  useContext,
-  useState,
-  useEffect,
-  useMemo,
-  useCallback,
-  useRef,
-  type ReactNode,
-} from "react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type {
-  IDataAdapter,
-  DbProviderConfig,
-  DbLangContextValue,
-  DbContextValue,
-} from "../types";
-
-// Database context
-const DbContext = createContext<DbContextValue | null>(null);
-
-// Language context
-const DbLangContext = createContext<DbLangContextValue | null>(null);
-
-/**
- * Default QueryClient for React Query
- */
-const defaultQueryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60 * 5, // 5 minutes
-      gcTime: 1000 * 60 * 30, // 30 minutes (formerly cacheTime)
-      refetchOnWindowFocus: false,
-    },
-  },
-});
-
-interface DbProviderProps extends DbProviderConfig {
-  children: ReactNode;
-  queryClient?: QueryClient;
-}
-
-/**
- * Database Provider Component
- *
- * Wraps application with database context, language context, and React Query.
- *
- * @example
- * ```tsx
- * import { DbProvider, SqliteAdapter } from '@promakeai/dbreact';
- *
- * const adapter = new SqliteAdapter({ storageKey: 'myapp' });
- *
- * function App() {
- *   return (
- *     <DbProvider adapter={adapter} lang="tr" fallbackLang="en">
- *       <MyApp />
- *     </DbProvider>
- *   );
- * }
- * ```
- */
-export function DbProvider({
-  adapter,
-  lang: langProp = "en",
-  fallbackLang = "en",
-  autoConnect = true,
-  queryClient = defaultQueryClient,
-  children,
-}: DbProviderProps) {
-  const [isConnected, setIsConnected] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [lang, setLangState] = useState(langProp);
-  const isFirstRender = useRef(true);
-
-  // Sync internal state when prop changes
-  useEffect(() => {
-    if (langProp !== lang) {
-      setLangState(langProp);
-    }
-  }, [langProp]);
-
-  // Invalidate all queries when language changes (skip first render)
-  useEffect(() => {
-    if (isFirstRender.current) {
-      isFirstRender.current = false;
-      return;
-    }
-    // Invalidate all queries to refetch with new language
-    queryClient.invalidateQueries();
-  }, [lang]);
-
-  // Connect to adapter on mount
-  useEffect(() => {
-    if (!autoConnect) return;
-
-    let mounted = true;
-
-    async function connect() {
-      try {
-        await adapter.connect?.();
-        if (mounted) {
-          setIsConnected(true);
-          setError(null);
-        }
-      } catch (err) {
-        if (mounted) {
-          setError(err instanceof Error ? err : new Error(String(err)));
-          setIsConnected(false);
-        }
-      }
-    }
-
-    connect();
-
-    return () => {
-      mounted = false;
-    };
-  }, [adapter, autoConnect]);
-
-  // setLang updates internal state (and triggers invalidation via effect)
-  const setLang = useCallback((newLang: string) => {
-    setLangState(newLang);
-  }, []);
-
-  // Database context value
-  const dbContextValue = useMemo<DbContextValue>(
-    () => ({
-      adapter,
-      isConnected,
-      error,
-    }),
-    [adapter, isConnected, error]
-  );
-
-  // Language context value
-  const langContextValue = useMemo<DbLangContextValue>(
-    () => ({
-      lang,
-      fallbackLang,
-      setLang,
-    }),
-    [lang, fallbackLang, setLang]
-  );
-
-  return (
-    <QueryClientProvider client={queryClient}>
-      <DbContext.Provider value={dbContextValue}>
-        <DbLangContext.Provider value={langContextValue}>
-          {children}
-        </DbLangContext.Provider>
-      </DbContext.Provider>
-    </QueryClientProvider>
-  );
-}
-
-/**
- * Hook to access database context
- */
-export function useDb(): DbContextValue {
-  const context = useContext(DbContext);
-  if (!context) {
-    throw new Error("useDb must be used within a DbProvider");
-  }
-  return context;
-}
-
-/**
- * Hook to access the raw adapter
- */
-export function useAdapter(): IDataAdapter {
-  const { adapter } = useDb();
-  return adapter;
-}
-
-/**
- * Hook to access language context
- */
-export function useDbLang(): DbLangContextValue {
-  const context = useContext(DbLangContext);
-  if (!context) {
-    throw new Error("useDbLang must be used within a DbProvider");
-  }
-  return context;
-}