@superbright/indexeddb-orm 0.1.1

package/.prettierignore

@@ -0,0 +1,9 @@
+dist
+node_modules
+coverage
+*.log
+.vite
+.vscode
+.DS_Store
+*.zip
+inresi-orm-export.json

package/.prettierrc.cjs

@@ -0,0 +1,13 @@
+/** @type {import("prettier").Config} */
+export default {
+  printWidth: 100,
+  tabWidth: 2,
+  useTabs: false,
+  semi: true,
+  singleQuote: true,
+  trailingComma: "all",
+  bracketSpacing: true,
+  arrowParens: "always",
+  endOfLine: "lf",
+  plugins: ["prettier-plugin-packagejson"],
+};

package/CONSUMING_APP_GUIDE.md

@@ -0,0 +1,164 @@
+/**
+ * Consuming App Integration Guide
+ *
+ * Replace your existing stores with a single unified ORM-backed store
+ */
+
+// 1. Remove these old imports:
+// import { persist, createJSONStorage } from "zustand/middleware";
+// import { get, set, del } from "idb-keyval";
+// import { createORMStringStorage } from "@superbright/indexeddb-orm";
+
+// 2. Add these new imports for the UNIFIED STORE:
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+import {
+  createZustandPropertyStore, // More intuitive name (alias for createZustandUnifiedStore)
+  createUseUnitState,
+  type ZustandUnifiedStoreState,
+  type Filters,
+  type QueryParams,
+  type UnitData,
+  type TourContactData
+} from "@superbright/indexeddb-orm";
+
+// 3. Replace BOTH your property store AND app store with one unified store:
+
+// This replaces both usePropertyStore AND useStore
+export const useStore = create<ZustandUnifiedStoreState>()(
+  devtools(
+    createZustandPropertyStore({
+      // Optional: callback for when filters are updated
+      onFilterUpdate: (apiParams: QueryParams) => {
+        // Replace your updateParams call here
+        // updateParams(apiParams);
+        console.log("Filters updated:", apiParams);
+      }
+    }),
+    { name: "property-store" }
+  )
+);
+
+// 4. Create the unit state hook (same as before):
+export const useUnitState = createUseUnitState()(useStore);
+
+// 5. Export store instance (replaces both propertyStore.getState and old useStore.getState):
+export const propertyStore = useStore.getState;
+
+// 6. Initialize the unified store in your app startup (e.g., main.tsx or App.tsx):
+/*
+import { useStore } from './stores/propertyStore'; // Keep the same file name
+
+async function initializeApp() {
+  // Initialize and hydrate the unified store with data from IndexedDB
+  await useStore.getState()._initialize();
+  await useStore.getState()._hydrate();
+
+  // ... rest of your app initialization
+}
+
+// Call this on app startup
+initializeApp();
+*/
+
+// 7. Usage in components remains largely the same:
+/*
+function MyComponent() {
+  const { data, propertyId } = usePropertyStore();
+  const unitState = useUnitState("unit-123");
+
+  // NOTE: These are now async operations
+  const handleToggleFavorite = async () => {
+    await usePropertyStore.getState().toggleFavorite("unit-123");
+  };
+
+  const handleMarkViewed = async () => {
+    await usePropertyStore.getState().markUnitAsViewed("unit-123", "property-slug");
+  };
+
+  return (
+    <div>
+      <p>Property: {propertyId}</p>
+      <p>Is favorite: {unitState.isFavorite}</p>
+      <p>Viewed: {unitState.viewedDate}</p>
+      <button onClick={handleToggleFavorite}>Toggle Favorite</button>
+      <button onClick={handleMarkViewed}>Mark as Viewed</button>
+    </div>
+  );
+}
+*/
+
+// 7. Usage examples - the API combines both stores:
+/*
+function PropertyComponent() {
+  const {
+    // Property data (was usePropertyStore)
+    properties,
+    currentPropertyId,
+    currentPropertySlug,
+
+    // App data (was useStore)
+    units,
+    filters,
+    resultsMode,
+    sortBy
+  } = useStore();
+
+  const unitState = useUnitState("unit-123");
+
+  // Property operations
+  const handleToggleFavorite = async () => {
+    await useStore.getState().toggleFavorite("unit-123");
+  };
+
+  const handleMarkViewed = async () => {
+    await useStore.getState().markUnitAsViewed("unit-123", "property-slug");
+  };
+
+  // App operations
+  const handleFilterChange = async () => {
+    await useStore.getState().setFilters({ bedrooms: [1, 2] });
+  };
+
+  const handleSetUnitData = async () => {
+    await useStore.getState().setUnitData("unit-123", { isFavorite: true });
+  };
+
+  return (
+    <div>
+      <p>Property: {currentPropertyId}</p>
+      <p>Unit is favorite: {unitState.isFavorite}</p>
+      <p>Results mode: {resultsMode}</p>
+      <button onClick={handleToggleFavorite}>Toggle Favorite</button>
+      <button onClick={handleFilterChange}>Set Filters</button>
+    </div>
+  );
+}
+*/
+
+// 8. Key breaking changes to be aware of:
+/*
+BREAKING CHANGES:
+- Two stores combined into one unified store
+- All store methods are now async (return Promise<void>)
+- Must call _initialize() and _hydrate() on app startup
+- No more persist middleware configuration needed
+- No more custom IndexedDB storage setup
+- Property data is now in 'properties' object, current property tracked separately
+- toggleFavorite() no longer takes propertyId parameter (uses currentPropertyId)
+- loadPersistedFilters() is now redundant (always loads from IndexedDB)
+- availabilityOptions array should be handled in UI components
+- updateParams callback is now handled in store configuration
+
+BENEFITS:
+- Single source of truth for all app state
+- Better type safety with Zod validation
+- Centralized storage logic in ORM
+- Better error handling and validation
+- No more manual storage configuration
+- More consistent API across all operations
+- Better performance with native IndexedDB operations
+- Automatic state synchronization
+- Built-in callbacks for external integrations
+- Easier state management and debugging
+*/

package/MIGRATION_SUMMARY.md

@@ -0,0 +1,157 @@
+# Complete Store Migration Summary
+
+This document provides a complete overview of migrating both the Property Store and App Store from the consuming application into a single unified IndexedDB ORM store.
+
+## What Was Extracted
+
+### Unified Store (Combines Both Previous Stores)
+- **Original**: Two separate Zustand stores (property + app) with different storage mechanisms
+- **New**: Single unified ORM-backed store with Zustand adapter
+- **Key Features**:
+  - **Property data**: Multiple properties, current property tracking, favorites, viewed units, tour contacts, questionnaire results
+  - **App data**: Unit data, filters, temp filters, API filters, results mode, sorting, questionnaire values
+
+## Architecture Changes
+
+### Before (Consuming App)
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│ Property Store  │    │ Persist          │    │ ORM String      │
+│ (Zustand)       │───▶│ Middleware       │───▶│ Storage         │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│ App Store       │    │ Persist          │    │ idb-keyval      │
+│ (Zustand)       │───▶│ Middleware       │───▶│ Custom Storage  │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+```
+
+### After (Unified ORM-Centric)
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Zustand       │    │ Unified ORM      │    │ IndexedDB       │
+│   Store         │───▶│ Store Adapter    │───▶│ (Native)        │
+│   (UI Layer)    │    │                  │    │                 │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+                                │
+                                ▼
+                       ┌──────────────────┐
+                       │ Direct ORM API   │
+                       │ (Server/Logic)   │
+                       └──────────────────┘
+```
+
+## New Unified ORM API
+
+### UnifiedStore (Direct ORM Usage)
+```typescript
+import { store } from "@superbright/indexeddb-orm";
+
+// Property operations
+await store.initializeProperty("prop-123", "property-slug");
+await store.setCurrentProperty("prop-123", "property-slug");
+await store.toggleFavorite("unit-456");
+await store.markUnitAsViewed("unit-456", "property-slug");
+
+// App operations
+await store.setUnitData("unit-123", { isFavorite: true });
+await store.setFilters({ bedrooms: [1, 2], cost: 2000 });
+await store.setResultsMode("favorites");
+
+// Get data
+const unitState = await store.getUnitState("unit-456");
+const fullState = await store.getFullState();
+```
+
+## Zustand Integration
+
+### Unified Store (Replaces Both Previous Stores)
+```typescript
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+import { createZustandUnifiedStore } from "@superbright/indexeddb-orm";
+
+// This replaces BOTH usePropertyStore AND useStore
+export const useStore = create()(
+  devtools(
+    createZustandUnifiedStore({
+      onFilterUpdate: (apiParams) => {
+        // Handle filter updates (e.g., call updateParams)
+        updateParams(apiParams);
+      }
+    }),
+    { name: "property-store" } // Keep familiar naming
+  )
+);
+
+// Usage combines both property and app data
+const {
+  // Property data
+  properties, currentPropertyId, currentPropertySlug,
+  // App data
+  units, filters, resultsMode, sortBy
+} = useStore();
+```
+
+## Migration Checklist
+
+### ✅ Completed in ORM
+- [x] UnifiedStore class combining both property and app functionality
+- [x] Zustand adapter for unified store
+- [x] Type definitions with Zod validation
+- [x] Schema exports and integration
+- [x] Legacy compatibility methods for smooth migration
+- [x] Documentation and migration guides
+- [x] Example usage code
+- [x] Single storage mechanism for all data
+
+### 🔄 Required in Consuming App
+- [ ] Remove old persist middleware imports
+- [ ] Remove custom storage setup (idb-keyval, createORMStringStorage)
+- [ ] Replace BOTH stores with single unified store
+- [ ] Update imports to use unified store types
+- [ ] Add store initialization calls in app startup
+- [ ] Update component handlers to be async
+- [ ] Handle updateParams callback in store configuration
+- [ ] Remove availabilityOptions from store state (handle in UI)
+- [ ] Update component state selectors (properties vs data)
+- [ ] Test all existing functionality
+
+## Benefits
+
+1. **Single Source of Truth**: All app state in one unified store
+2. **Centralized Logic**: All storage logic lives in the ORM
+3. **Type Safety**: Full TypeScript + Zod validation
+4. **Better Performance**: Direct IndexedDB operations
+5. **Simplified Architecture**: One store instead of two
+6. **Testability**: Easier to mock and test centralized logic
+7. **Flexibility**: Can use direct ORM API or Zustand adapters
+8. **Error Handling**: Built-in validation and error handling
+9. **Consistent API**: Same patterns for all operations
+10. **Easier Debugging**: Single store to inspect and debug
+
+## Breaking Changes Summary
+
+### All Stores
+- All methods are now async
+- Must call initialization methods on app startup
+- No more persist middleware configuration
+
+### Property Store Specific
+- `toggleFavorite()` no longer takes propertyId parameter
+- Questionnaire results can be any type (not just IFilters)
+
+### App Store Specific
+- `loadPersistedFilters()` is redundant (always loads from IndexedDB)
+- `availabilityOptions` should be handled in UI components
+- `updateParams` callback moved to store configuration
+
+## Next Steps
+
+1. **Update Consuming App**: Follow the migration guides to update both stores
+2. **Test Thoroughly**: Ensure all existing functionality works
+3. **Remove Dead Code**: Clean up old storage-related code
+4. **Add Error Handling**: Leverage the improved error handling in the ORM
+5. **Consider Direct ORM Usage**: For server-side or complex logic, consider using the ORM APIs directly
+
+The migration provides a solid foundation for scalable, type-safe data management while maintaining compatibility with existing Zustand-based UI patterns.

package/README.md

@@ -0,0 +1,45 @@
+# indexeddb-orm-starter
+
+Minimal **Vite + TypeScript** starter for an IndexedDB ORM using **Dexie** + **Zod**, with a built-in browser playground.
+
+## 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
+
+## 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
+```bash
+pnpm build
+pnpm test
+```
+
+## Programmatic usage
+```ts
+import {
+  getDB,
+  getFavouritedUnits, setFavouritedUnits,
+  getPreferences, setPreferences,
+  upsertUser, getUser,
+  debugDump, exportJSON
+} from "indexeddb-orm-starter";
+
+await getDB();
+await setFavouritedUnits(["u1","u2"]);
+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.

package/docs/app-store-guide.md

@@ -0,0 +1,160 @@
+/**
+ * App Store Integration Guide
+ *
+ * Replace your existing app store (useStore) with this new ORM-backed implementation
+ */
+
+// 1. Remove these old imports:
+// import { persist, createJSONStorage } from "zustand/middleware";
+// import { get, set, del } from "idb-keyval";
+// import { createORMStringStorage } from "@superbright/indexeddb-orm";
+
+// 2. Add these new imports:
+import { create } from "zustand";
+import { devtools } from "zustand/middleware";
+import {
+  createZustandAppStore,
+  type ZustandAppStoreState,
+  type Filters,
+  type QueryParams,
+  type UnitData
+} from "@superbright/indexeddb-orm";
+
+// 3. Replace your store creation:
+export const useStore = create<ZustandAppStoreState>()(
+  devtools(
+    createZustandAppStore({
+      // Optional: callback for when filters are updated
+      onFilterUpdate: (apiParams: QueryParams) => {
+        // This replaces your updateParams call
+        // Import and call your updateParams function here
+        // updateParams(apiParams);
+        console.log("Filters updated:", apiParams);
+      }
+    }),
+    { name: "app-store" }
+  )
+);
+
+// 4. Initialize the store in your app startup (e.g., main.tsx or App.tsx):
+/*
+import { useStore } from './stores/appStore';
+
+async function initializeApp() {
+  // Initialize and hydrate the store with data from IndexedDB
+  await useStore.getState()._initialize();
+  await useStore.getState()._hydrate();
+
+  // ... rest of your app initialization
+}
+
+// Call this on app startup
+initializeApp();
+*/
+
+// 5. Usage in components remains largely the same, but methods are now async:
+/*
+function FiltersComponent() {
+  const {
+    filters,
+    tempFilters,
+    resultsMode,
+    sortBy,
+    filtersLoaded
+  } = useStore();
+
+  // NOTE: These are now async operations
+  const handleFilterChange = async (key: keyof Filters, value: any) => {
+    await useStore.getState().handleTempFilterChange(key, value);
+  };
+
+  const handleCommitFilter = async () => {
+    await useStore.getState().submitFilterUpdate();
+  };
+
+  const handleResultsModeChange = async (mode: "all" | "bestFit" | "closestMatch" | "favorites") => {
+    await useStore.getState().setResultsMode(mode);
+  };
+
+  const handleSortChange = async (sortBy: "relevance" | "newest" | "priceLowToHigh" | "priceHighToLow") => {
+    await useStore.getState().setSortBy(sortBy);
+  };
+
+  return (
+    <div>
+      <p>Filters loaded: {filtersLoaded}</p>
+      <p>Current bedrooms: {filters.bedrooms?.join(", ")}</p>
+      <p>Results mode: {resultsMode}</p>
+      <p>Sort by: {sortBy}</p>
+      <button onClick={() => handleFilterChange("bedrooms", [1, 2])}>
+        Set 1-2 bedrooms
+      </button>
+      <button onClick={handleCommitFilter}>Apply Filters</button>
+    </div>
+  );
+}
+
+function UnitComponent({ unitId }: { unitId: string }) {
+  const { data } = useStore();
+  const unitData = data[unitId];
+
+  const handleToggleFavorite = async () => {
+    const currentData = data[unitId] || {};
+    await useStore.getState().setData(unitId, {
+      ...currentData,
+      isFavorite: !currentData.isFavorite
+    });
+  };
+
+  const handleMarkViewed = async () => {
+    const today = new Date();
+    const formattedDate = `${String(today.getMonth() + 1).padStart(2, "0")}/${String(today.getDate()).padStart(2, "0")}`;
+
+    const currentData = data[unitId] || {};
+    await useStore.getState().setData(unitId, {
+      ...currentData,
+      viewedDate: formattedDate
+    });
+  };
+
+  return (
+    <div>
+      <p>Unit: {unitId}</p>
+      <p>Is favorite: {unitData?.isFavorite ? "Yes" : "No"}</p>
+      <p>Viewed: {unitData?.viewedDate || "Never"}</p>
+      <button onClick={handleToggleFavorite}>Toggle Favorite</button>
+      <button onClick={handleMarkViewed}>Mark as Viewed</button>
+    </div>
+  );
+}
+*/
+
+// 6. Key breaking changes to be aware of:
+/*
+BREAKING CHANGES:
+- All store methods are now async (return Promise<void>)
+- Must call _initialize() and _hydrate() on app startup
+- No more persist middleware configuration needed
+- No more custom IndexedDB storage setup
+- loadPersistedFilters() is now redundant (always loads from IndexedDB)
+- availabilityOptions array is not stored (should be handled in UI)
+
+BENEFITS:
+- Better type safety with Zod validation
+- Centralized storage logic in ORM
+- Better error handling and validation
+- No more manual storage configuration
+- More consistent API across different data types
+- Better performance with native IndexedDB operations
+- Automatic state synchronization
+- Built-in filter update callbacks
+
+MIGRATION NOTES:
+1. The store structure remains the same, but all operations are async
+2. Remove custom IndexedDB setup (idb-keyval, custom storage)
+3. Replace persist middleware with ORM storage
+4. Add initialization calls in app startup
+5. Update component handlers to be async
+6. Handle updateParams callback in store configuration
+7. Remove availabilityOptions from store (handle in UI components)
+*/