@superbright/indexeddb-orm 0.1.2 → 0.1.3

package/README.md

@@ -1,30 +1,365 @@
-# indexeddb-orm-starter
+# IndexedDB ORM with Structured Store Actions
 
-Minimal **Vite + TypeScript** starter for an IndexedDB ORM using **Dexie** + **Zod**, with a built-in browser playground.
+A TypeScript-first IndexedDB ORM built with Dexie and Zod, featuring structured Zustand store integration for React applications.
 
-## Features
-- Library build via Vite (ES + CJS) with type declarations (tsc)
-- Dexie-powered tables: `users`, `properties`, `units`, and a `kv` store
-- Helpers for **favourites** and **preferences**
-- Schema version manifest + reset on incompatible version
-- Vitest + fake-indexeddb tests
-- Browser playground to inspect data
+## 🚀 Features
+
+- **TypeScript-First**: Full type safety with Zod schema validation
+- **Structured Store Actions**: Organized, nested API for better developer experience
+- **IndexedDB Powered**: Built on Dexie for robust browser storage
+- **Zustand Integration**: Seamless state management with React
+- **Schema Validation**: Runtime validation with Zod schemas
+- **Developer Experience**: Hot reloading, type inference, and great autocomplete
+- **Production Ready**: Optimized builds with proper package exports
+
+## 📦 Installation
+
+```bash
+pnpm install @superbright/indexeddb-orm zustand
+```
+
+## 🏃 Quick Start
+
+### 1. Basic Setup
+
+```typescript
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+import {
+  createStructuredStore,
+  createUseUnitState,
+  type StructuredStore,
+  type Filters,
+  type QueryParams,
+} from "@superbright/indexeddb-orm";
+
+// Create your store with structured actions
+export const useStore = create<StructuredStore>()(
+  devtools(
+    createStructuredStore({
+      onFilterUpdate: (apiParams: QueryParams) => {
+        console.log("Filters updated:", apiParams);
+      },
+    }),
+    { name: "inresi-store" }
+  )
+);
+
+export const useUnitState = createUseUnitState()(useStore);
+```
+
+### 2. Initialize in Your App
+
+```typescript
+// main.tsx or App.tsx
+import { useStore } from './stores/myStore';
+
+async function initializeApp() {
+  await useStore.getState()._initialize();
+  await useStore.getState()._hydrate();
+}
+
+initializeApp().then(() => {
+  // Render your app
+});
+```
+
+### 3. Use Structured Actions
+
+```typescript
+function MyComponent() {
+  const store = useStore();
+
+  // Property actions
+  const toggleFavorite = async (unitId: string) => {
+    await store.property.unit.favorites.toggle(unitId);
+  };
+
+  const markViewed = async (unitId: string, slug: string) => {
+    await store.property.unit.viewed.mark(unitId, slug);
+  };
+
+  // Filter actions
+  const updateFilters = async () => {
+    await store.filters.set({ bedrooms: [1, 2] });
+    await store.filters.submit();
+  };
+
+  return (
+    <div>
+      <button onClick={() => toggleFavorite("unit-123")}>
+        Toggle Favorite
+      </button>
+      <button onClick={() => markViewed("unit-123", "property-slug")}>
+        Mark as Viewed
+      </button>
+      <button onClick={updateFilters}>
+        Update Filters
+      </button>
+    </div>
+  );
+}
+```
+
+## 🏗️ Architecture
+
+### Core Components
+
+- **Dexie Database**: IndexedDB abstraction layer
+- **Zod Schemas**: Runtime type validation and TypeScript inference
+- **Unified Store**: Single source of truth combining property and app state
+- **Structured Actions**: Organized API with nested action groups
+- **Zustand Integration**: React state management with devtools support
+
+### Data Flow
+
+```
+React Components
+       ↓
+Structured Store Actions
+       ↓
+Unified Store (Zustand)
+       ↓
+ORM Layer (Validation)
+       ↓
+IndexedDB (Dexie)
+```
+
+## 📚 API Reference
+
+### Structured Store Actions
+
+#### Property Actions
+```typescript
+// Unit favorites
+store.property.unit.favorites.toggle(unitId: string)
+
+// Unit viewing
+store.property.unit.viewed.mark(unitId: string, slug: string)
+
+// Questionnaire
+store.property.questionnaire.setResults(results: unknown)
+
+// Tour scheduling
+store.property.tour.setContactedOn()
+store.property.tour.getContactedOn()
+store.property.tour.setContactData(data: TourContactData)
+```
+
+#### Filter Actions
+```typescript
+// Filter management
+store.filters.set(filters: Partial<Filters>)
+store.filters.setTemp(filters: Partial<Filters>)
+store.filters.setToDefault()
+store.filters.commitTemp(key, defaultValue)
+store.filters.commitAvailability()
+store.filters.submit()
+```
+
+### Store State
+
+```typescript
+// Property data
+const currentPropertyId = useStore(state => state.currentPropertyId);
+const properties = useStore(state => state.properties);
+
+// App data
+const filters = useStore(state => state.filters);
+const units = useStore(state => state.units);
+const resultsMode = useStore(state => state.resultsMode);
+
+// Unit state helper
+const unitState = useUnitState("unit-123");
+// Returns: { isFavorite: boolean, viewedDate: string }
+```
+
+### Direct Store Methods
+
+For advanced use cases, all original store methods are available:
+
+```typescript
+// Property operations
+await store.getCurrentProperty()
+await store.setCurrentProperty(propertyId, slug)
+await store.getPropertyData(propertyId)
+
+// Unit operations
+await store.getUnitData(unitId)
+await store.setUnitData(unitId, data)
+await store.removeUnitData(unitId)
+
+// Filter operations
+await store.loadPersistedFilters()
+await store.handleFilterCommitIndexDB(newFilters)
+```
+
+## 🛠️ Development
+
+### Local Development Setup
+
+1. **Environment Configuration**
+
+Create `.env` in your consuming app:
+
+```bash
+VITE_USE_LOCAL_ORM_LIBRARY=true
+VITE_LOCAL_ORM_LIBRARY_PATH=/path/to/indexeddb-orm-starter-with-playground
+```
+
+2. **Vite Configuration**
+
+```typescript
+// vite.config.ts
+const alias: Record<string, string> = {};
+if (useLocalORM && ormPath) {
+  alias["@superbright/indexeddb-orm"] = resolve(ormPath, "./dist");
+}
+```
+
+### 🎮 Interactive Playground
+
+The ORM includes a comprehensive interactive playground for testing and exploring functionality:
 
-## Dev / Playground
 ```bash
 pnpm i
 pnpm dev
 # Visit http://localhost:5173 (or printed URL)
-# Use the buttons to write/dump/export, then open DevTools → Application → IndexedDB → inresi-orm
 ```
 
-## Build & Test
+#### Playground Features
+
+- **🗄️ Database Operations**: Initialize, dump state, export JSON, and reset database
+- **🏠 Property Management**: Create properties, set current property, retrieve property data
+- **⭐ Unit Actions**: Toggle favorites, mark units as viewed, get unit state
+- **🔍 Filter Operations**: Set filters, reset to defaults, submit filter updates
+- **📝 Questionnaire & Tours**: Set questionnaire results, manage tour contact data
+- **📊 Real-time State View**: Live view of database state and action logs
+- **🛠️ Developer Tools Integration**: Inspect IndexedDB directly in DevTools → Application → IndexedDB → `inresi-orm`
+
+#### How to Use
+
+1. **Start with Database Operations**: Click "Initialize Database" to set up the ORM
+2. **Create a Property**: Enter a property ID and slug, then click "Initialize Property"
+3. **Test Unit Actions**: Enter a unit ID and try toggling favorites or marking as viewed
+4. **Experiment with Filters**: Set bedroom counts and cost filters, then submit them
+5. **View State Changes**: Watch the real-time state updates and action logs
+6. **Inspect Database**: Open browser DevTools to see the actual IndexedDB storage
+
+The playground demonstrates all structured store actions and provides immediate feedback, making it perfect for learning the API and testing integrations.
+
+### Build Scripts
+
 ```bash
-pnpm build
-pnpm test
+# Development
+pnpm run dev          # Start playground with hot reload
+pnpm run watch        # Watch mode for types and bundle
+
+# Building
+pnpm run build        # Production build
+pnpm run clean        # Clean dist folder
+
+# Testing
+pnpm run test         # Run tests
+pnpm run test:watch   # Watch mode testing
+```
+
+### Package Structure
+
+```
+dist/
+├── index.d.ts       # Main type definitions
+├── index.es.js      # ES module build
+├── index.cjs.js     # CommonJS build
+├── adapters/        # Store adapters
+├── api/            # API modules
+└── stores/         # Store implementations
 ```
 
-## Programmatic usage
+## 🎯 TypeScript Support
+
+Full TypeScript support with proper type inference:
+
+```typescript
+import type {
+  StructuredStore,
+  StructuredStoreActions,
+  Filters,
+  QueryParams,
+  UnitData,
+  TourContactData,
+  PropertyData,
+  ZustandUnifiedStoreState,
+} from "@superbright/indexeddb-orm";
+```
+
+## 📋 Schema Validation
+
+Built-in Zod schemas ensure data integrity:
+
+```typescript
+// Example schema usage
+import { FiltersSchema, UnitDataSchema } from "@superbright/indexeddb-orm";
+
+// Validate data at runtime
+const validatedFilters = FiltersSchema.parse(userInput);
+const validatedUnit = UnitDataSchema.parse(apiResponse);
+```
+
+## 🔧 Configuration
+
+### Store Configuration
+
+```typescript
+createStructuredStore({
+  onFilterUpdate?: (apiParams: QueryParams) => void;
+  // Add more configuration options as needed
+})
+```
+
+### Validation Configuration
+
+```typescript
+import { configureValidation } from "@superbright/indexeddb-orm";
+
+// Configure validation mode
+configureValidation("strict"); // "strict" | "warn" | "off"
+```
+
+## 🚀 Production
+
+### Package Exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+### Bundle Optimization
+
+- Tree-shakable ES modules
+- Separate type definitions
+- Optimized for Vite and Webpack
+- Source maps included
+
+## 📖 Documentation
+
+- [Consuming App Guide](./CONSUMING_APP_GUIDE.md) - Complete integration guide
+- [Migration Summary](./MIGRATION_SUMMARY.md) - Migration from legacy stores
+- [Property Store Guide](./docs/property-store.md) - Property-specific usage
+- [App Store Guide](./docs/app-store-guide.md) - App state management
+
+## 🔧 Legacy API
+
+For backward compatibility, the original API is still available:
+
 ```ts
 import {
   getDB,
@@ -32,7 +367,7 @@ import {
   getPreferences, setPreferences,
   upsertUser, getUser,
   debugDump, exportJSON
-} from "indexeddb-orm-starter";
+} from "@superbright/indexeddb-orm";
 
 await getDB();
 await setFavouritedUnits(["u1","u2"]);
@@ -40,6 +375,22 @@ console.log(await getFavouritedUnits());
 await exportJSON();
 ```
 
-## Notes
-- Increment `SCHEMA_VERSION` in `src/schema.ts` to force a reset (basic strategy).
-- Add entities/repositories in `src/api/*` following the same pattern.
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Ensure type checking passes: `pnpm run build`
+6. Submit a pull request
+
+## 📝 License
+
+UNLICENSED - Proprietary software for internal use
+
+## 🔗 Related Projects
+
+- [Dexie](https://dexie.org/) - IndexedDB wrapper
+- [Zod](https://zod.dev/) - TypeScript schema validation
+- [Zustand](https://zustand-demo.pmnd.rs/) - React state management
+- [Vite](https://vitejs.dev/) - Build tool and dev server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superbright/indexeddb-orm",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Vite + TypeScript starter for an IndexedDB ORM (Dexie + Zod) with playground.",
   "license": "UNLICENSED",
   "type": "module",
@@ -15,9 +15,23 @@
     }
   },
   "sideEffects": false,
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
+
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm clean && vite build && tsc -p tsconfig.build.json",
+    "prepare": "pnpm build",
+    "start": "vite --clearScreen false",
+    "dev": "concurrently -k -n PLAY,BUILD \"pnpm:start\" \"pnpm:watch\"",
+    "watch": "concurrently -k -n TYPES,BUNDLE \"pnpm:watch:types\" \"pnpm:watch:bundle\"",
+    "watch:types": "tsc -w -p tsconfig.build.json",
+    "watch:bundle": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "pnpm format:write",
+    "format:write": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
   "dependencies": {
     "dexie": "^4.0.8",
     "zod": "^3.23.8"
@@ -32,19 +46,5 @@
     "typescript": "^5.4.5",
     "vite": "^5.4.0",
     "vitest": "^2.0.5"
-  },
-  "scripts": {
-    "clean": "rimraf dist",
-    "build": "pnpm clean && vite build && tsc -p tsconfig.build.json",
-    "start": "vite --clearScreen false",
-    "dev": "concurrently -k -n PLAY,BUILD \"pnpm:start\" \"pnpm:watch\"",
-    "watch": "concurrently -k -n TYPES,BUNDLE \"pnpm:watch:types\" \"pnpm:watch:bundle\"",
-    "watch:types": "tsc -w -p tsconfig.build.json",
-    "watch:bundle": "vite build --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "format": "pnpm format:write",
-    "format:write": "prettier --write .",
-    "format:check": "prettier --check ."
   }
-}
+}