@promakeai/dbreact 1.0.1

package/SKILL.md

@@ -0,0 +1,311 @@
+---
+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/dist/adapters/RestAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RestAdapter.d.ts","sourceRoot":"","sources":["../../adapters/RestAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/SqliteAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteAdapter.d.ts","sourceRoot":"","sources":["../../adapters/SqliteAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAepG,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,gDAAgD;IAChD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,MAAM,CAGZ;IAEF,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;gBAET,MAAM,GAAE,mBAAwB;IAc5C,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAKnC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB9B,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,QAAQ;IAkBhB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,gBAAgB;IAuCxB;;OAEG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,CAAC,EAAE,CAAC;YAWD,YAAY;IA2B1B;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAUd,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAClF,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;YAKN,WAAW;IA8BzB;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAMnE;;OAEG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAqB9B;;OAEG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EACtB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC;IA4Cb;;OAEG;IACG,sBAAsB,CAAC,CAAC,GAAG,OAAO,EACtC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrD,OAAO,CAAC,CAAC,CAAC;IAwCb;;OAEG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EACtB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC;IAyCb;;OAEG;IACG,iBAAiB,CACrB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC;IAYhB;;OAEG;IACG,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/B,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,GAAG,MAAM,GAClB,OAAO,CAAC,CAAC,EAAE,CAAC;IAaf;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBlE;;OAEG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAWhH;;OAEG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,CAAC,EAAE,CAAC;IAIf;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB1E;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAOpC;;OAEG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAgBzE;;OAEG;IACH,KAAK,IAAI,IAAI;IASP,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAKvB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAKzB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAClC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;KAAE,CAAC;IAwCnD,UAAU,CACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,GAChE,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAWzB,UAAU,CACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GACvB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAW/B;;OAEG;IACH,MAAM,IAAI,UAAU;IAIpB;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7C;;OAEG;IACH,KAAK,IAAI,IAAI;CAQd"}