@superbright/indexeddb-orm 0.1.1 → 0.1.2

package/docs/app-store-guide.md

@@ -1,160 +0,0 @@
-/**
- * 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)
-*/

package/docs/property-store.md

@@ -1,192 +0,0 @@
-# Property Store
-
-The Property Store provides a complete solution for managing property-related data in your application using IndexedDB as the storage backend.
-
-## Features
-
-- **Native IndexedDB storage** - Direct integration with the ORM's storage layer
-- **Type-safe operations** - Full TypeScript support with Zod validation
-- **Zustand compatibility** - Easy integration with existing Zustand stores
-- **Async by default** - All operations are properly async for better performance
-- **Centralized state management** - All property data managed in one place
-
-## Core API
-
-### PropertyStore Class
-
-The core `PropertyStore` class provides direct access to property data operations:
-
-```typescript
-import { propertyStore } from "@superbright/indexeddb-orm";
-
-// Initialize a property
-await propertyStore.initializeProperty("prop-123", "property-slug");
-
-// Set current property context
-await propertyStore.setPropertyId("prop-123");
-await propertyStore.setPropertySlug("property-slug");
-
-// Manage favorites
-await propertyStore.toggleFavorite("unit-456");
-
-// Track viewed units
-await propertyStore.markUnitAsViewed("unit-456", "property-slug");
-
-// Store questionnaire results
-await propertyStore.setQuestionnaireResults({ maxRent: 2000, petFriendly: true });
-
-// Get unit state
-const unitState = await propertyStore.getUnitState("unit-456");
-console.log(unitState.isFavorite, unitState.viewedDate);
-```
-
-### Data Structure
-
-Properties are stored with the following structure:
-
-```typescript
-interface PropertyData {
-  id: string;
-  slug: string;
-  favoritedUnits: string[];
-  tourContactedOn: string | null;
-  viewedUnits: {
-    unitId: string;
-    viewedDate: string;
-  }[];
-  questionnaireResults?: unknown | null;
-  tourContactData?: {
-    timezone: string;
-    favouriteUnits?: string[];
-    preferences: Record<string, any>;
-  } | null;
-}
-```
-
-## Zustand Integration
-
-For apps using Zustand, you can create a store that automatically syncs with the ORM:
-
-```typescript
-import { create } from "zustand";
-import { devtools } from "zustand/middleware";
-import {
-  createZustandPropertyStore,
-  createUseUnitState,
-  type ZustandPropertyStoreState
-} from "@superbright/indexeddb-orm";
-
-// Create store
-export const usePropertyStore = create<ZustandPropertyStoreState>()(
-  devtools(
-    createZustandPropertyStore(),
-    { name: "property-store" }
-  )
-);
-
-// Initialize on app startup
-export async function initializeApp() {
-  await usePropertyStore.getState()._hydrate();
-}
-
-// Create unit state hook
-export const useUnitState = createUseUnitState()(usePropertyStore);
-
-// Use in components
-function MyComponent() {
-  const { data, propertyId } = usePropertyStore();
-  const unitState = useUnitState("unit-123");
-
-  const handleToggleFavorite = async () => {
-    await usePropertyStore.getState().toggleFavorite("unit-123");
-  };
-
-  return (
-    <div>
-      <p>Property: {propertyId}</p>
-      <p>Is favorite: {unitState.isFavorite}</p>
-      <button onClick={handleToggleFavorite}>Toggle Favorite</button>
-    </div>
-  );
-}
-```
-
-## Migration from Legacy Store
-
-If you're migrating from a previous implementation using `createORMStringStorage` with Zustand persist middleware:
-
-### Before (Legacy)
-```typescript
-import { create } from "zustand";
-import { persist, createJSONStorage } from "zustand/middleware";
-import { createORMStringStorage } from "@superbright/indexeddb-orm";
-
-const ormStorage = createORMStringStorage({
-  fallbackToMemory: true,
-});
-
-export const usePropertyStore = create(
-  persist(
-    (set, get) => ({
-      // ... store implementation
-    }),
-    {
-      name: "property",
-      storage: createJSONStorage(() => ormStorage),
-    }
-  )
-);
-```
-
-### After (New)
-```typescript
-import { create } from "zustand";
-import { devtools } from "zustand/middleware";
-import { createZustandPropertyStore } from "@superbright/indexeddb-orm";
-
-export const usePropertyStore = create()(
-  devtools(
-    createZustandPropertyStore(),
-    { name: "property-store" }
-  )
-);
-
-// Don't forget to hydrate on app startup!
-await usePropertyStore.getState()._hydrate();
-```
-
-### Key Changes
-1. **No more persist middleware** - Storage is handled natively by the ORM
-2. **All methods are async** - Better performance and error handling
-3. **Type safety** - Built-in validation with Zod schemas
-4. **Explicit hydration** - Must call `_hydrate()` on app startup
-5. **Centralized data** - All property logic lives in the ORM
-
-## API Reference
-
-### PropertyStore Methods
-
-- `initializeProperty(propertyId, slug)` - Initialize a new property
-- `setPropertyId(id)` - Set current property ID
-- `setPropertySlug(slug)` - Set current property slug
-- `setData(data)` - Set all property data
-- `removeData(key)` - Remove a property by ID
-- `clearData()` - Clear all property data
-- `toggleFavorite(unitId)` - Toggle unit favorite status
-- `markUnitAsViewed(unitId, slug)` - Mark unit as viewed
-- `setTourContactedOn()` - Mark tour as contacted
-- `getTourContactedOn()` - Get tour contact date
-- `setQuestionnaireResults(results)` - Store questionnaire results
-- `setTourContactData(data)` - Store tour contact data
-- `getUnitState(unitId)` - Get unit favorite/viewed state
-- `getPropertyData(propertyId?)` - Get property data
-- `getFullState()` - Get complete store state
-
-### Zustand Store Actions
-
-When using the Zustand adapter, all PropertyStore methods are available, plus:
-
-- `_hydrate()` - Load data from IndexedDB into Zustand state
-- `getUnitState(unitId)` - Synchronous unit state getter for React
-
-All data modification methods automatically sync the Zustand state after updating IndexedDB.

package/docs/structured-store-migration.md

@@ -1,129 +0,0 @@
-# Structured Store Migration Guide
-
-## Overview
-
-The `InResiStoreActions` structure has been moved from the consuming app into the ORM library itself. Instead of manually creating action structures in the consuming app, you can now use the new `createStructuredStore` function that provides these actions directly.
-
-## Migration
-
-### Before (Old Pattern)
-
-```typescript
-import {
-  createZustandPropertyStore,
-  type ZustandUnifiedStoreState,
-} from "@superbright/indexeddb-orm";
-
-type InResiStoreActions = {
-  property: {
-    unit: {
-      favorites: {
-        toggle: (unitId: string) => Promise<void>;
-      };
-      viewed: {
-        mark: (unitId: string, slug: string) => Promise<void>;
-      };
-    };
-    questionnaire: {
-      setResults: (results: unknown) => Promise<void>;
-    };
-  };
-};
-
-const baseStore = create<ZustandUnifiedStoreState>()(
-  devtools(createZustandPropertyStore(options))
-);
-
-const inResiStoreActions: InResiStoreActions = {
-  property: {
-    unit: {
-      favorites: {
-        toggle: async (unitId: string) => {
-          await baseStore.getState().toggleFavorite(unitId);
-        },
-      },
-      viewed: {
-        mark: async (unitId: string, slug: string) => {
-          await baseStore.getState().markUnitAsViewed(unitId, slug);
-        },
-      },
-    },
-    questionnaire: {
-      setResults: async (results: unknown) => {
-        await baseStore.getState().setQuestionnaireResults(results);
-      },
-    },
-  },
-};
-
-export const useInResiStore = Object.assign(baseStore, inResiStoreActions);
-```
-
-### After (New Pattern)
-
-```typescript
-import {
-  createStructuredStore,
-  type StructuredStore,
-} from "@superbright/indexeddb-orm";
-
-const baseStore = create<StructuredStore>()(
-  devtools(createStructuredStore(options))
-);
-
-export const useInResiStore = baseStore;
-```
-
-## Usage
-
-The structured actions are now directly available on the store:
-
-```typescript
-// Toggle favorite
-await useInResiStore.getState().property.unit.favorites.toggle(unitId);
-
-// Mark unit as viewed
-await useInResiStore.getState().property.unit.viewed.mark(unitId, slug);
-
-// Set questionnaire results
-await useInResiStore.getState().property.questionnaire.setResults(results);
-
-// All original store methods are still available
-const currentProperty = await useInResiStore.getState().getCurrentProperty();
-const unitState = useInResiStore.getState().getUnitState(unitId);
-```
-
-## Available Structured Actions
-
-The `StructuredStore` type includes all the original `ZustandUnifiedStoreState` methods plus the following structured actions:
-
-### Property Actions
-- `property.unit.favorites.toggle(unitId: string)` - Toggle unit favorite status
-- `property.unit.viewed.mark(unitId: string, slug: string)` - Mark unit as viewed
-- `property.questionnaire.setResults(results: unknown)` - Set questionnaire results
-- `property.tour.setContactedOn()` - Set tour contacted timestamp
-- `property.tour.getContactedOn()` - Get tour contacted timestamp
-- `property.tour.setContactData(data: TourContactData)` - Set tour contact data
-
-### Unit Actions
-- `unit.data.set(unitId: string, data: UnitData)` - Set unit data
-- `unit.data.remove(unitId: string)` - Remove unit data
-- `unit.data.clear()` - Clear all unit data
-- `unit.data.get(unitId: string)` - Get unit data
-- `unit.state.get(unitId: string)` - Get unit state (favorite/viewed status)
-
-### Filter Actions
-- `filters.set(filters: Partial<Filters>)` - Set filters
-- `filters.setTemp(filters: Partial<Filters>)` - Set temporary filters
-- `filters.setToDefault()` - Reset filters to default
-- `filters.commitTemp(key, defaultValue)` - Commit temporary filter changes
-- `filters.commitAvailability()` - Commit availability filter changes
-- `filters.submit()` - Submit all filter updates
-
-## Benefits
-
-1. **Centralized**: Actions are defined once in the ORM library
-2. **Type Safe**: Full TypeScript support with proper types
-3. **Consistent**: Same structure across all consuming applications
-4. **Maintainable**: Changes to action signatures only need to be made in one place
-5. **Extensible**: Easy to add new structured actions to the ORM library

package/examples/property-store-migration.ts

@@ -1,164 +0,0 @@
-/**
- * Example: Unified Store Migration Guide
- *
- * This shows how to migrate from separate property and app stores
- * to the new unified ORM store.
- */
-
-// === NEW APPROACH: Using ORM's unified store ===
-
-/*
-// 1. In your consuming app, create unified Zustand store with ORM backend:
-
-import { create } from "zustand";
-import { devtools } from "zustand/middleware";
-import {
-  createZustandPropertyStore, // More intuitive name
-  createUseUnitState,
-  type ZustandUnifiedStoreState,
-  type QueryParams
-} from "@superbright/indexeddb-orm";
-
-export const useStore = create<ZustandUnifiedStoreState>()(
-  devtools(
-    createZustandPropertyStore({
-      onFilterUpdate: (apiParams: QueryParams) => {
-        // Handle filter updates (replaces updateParams call)
-        console.log("Filters updated:", apiParams);
-      }
-    }),
-    { name: "property-store" }
-  )
-);
-
-// 2. Initialize the store on app startup
-export async function initializeStore() {
-  await useStore.getState()._initialize();
-  await useStore.getState()._hydrate();
-}
-
-// 3. Create the unit state hook
-export const useUnitState = createUseUnitState()(useStore);
-
-// 4. Export store instance (keep familiar naming)
-export const propertyStore = useStore.getState;
-*/
-
-// === USAGE EXAMPLES ===
-
-import {
-  store,
-  type TourContactData,
-  type Filters as UnifiedFilters
-} from "../src/stores/unified";
-import { createZustandUnifiedStore } from "../src/adapters/zustand-unified";
-
-// Direct ORM usage (without Zustand):
-async function directUnifiedStoreUsage() {
-  // Initialize the store
-  await store.initialize();
-
-  // === Property operations ===
-  // Initialize a property
-  await store.initializeProperty("prop-123", "property-slug");
-
-  // Set current property
-  await store.setCurrentProperty("prop-123", "property-slug");
-
-  // Toggle a favorite
-  await store.toggleFavorite("unit-456");
-
-  // Mark unit as viewed
-  await store.markUnitAsViewed("unit-456", "property-slug");
-
-  // Set tour contact data
-  const tourData: TourContactData = {
-    timezone: "America/New_York",
-    favouriteUnits: ["unit-456"],
-    preferences: { bedrooms: 2 }
-  };
-  await store.setTourContactData(tourData);
-
-  // Set questionnaire results
-  await store.setQuestionnaireResults({ maxRent: 2000, petFriendly: true });
-
-  // Mark tour contacted
-  await store.setTourContactedOn();
-
-  // === App operations ===
-  // Set unit data
-  await store.setUnitData("unit-123", { isFavorite: true, viewedDate: "12/25" });
-
-  // Set filters
-  const filters: Partial<UnifiedFilters> = {
-    bedrooms: [1, 2],
-    cost: 2000,
-    highlights: ["pet-friendly", "balcony"]
-  };
-  await store.setFilters(filters);
-
-  // Set results mode
-  await store.setResultsMode("favorites");
-
-  // Set sorting
-  await store.setSortBy("priceLowToHigh");
-
-  // Handle questionnaire values
-  await store.setResolvedQuestionnaireValues("petPreference", ["dogs", "cats"]);
-
-  // === Get data ===
-  // Get unit state (combines property favorite + app unit data)
-  const unitState = await store.getUnitState("unit-456");
-  console.log("Is favorite:", unitState.isFavorite);
-  console.log("Viewed date:", unitState.viewedDate);
-
-  // Get results URL
-  const resultsUrl = await store.getResultsUrl();
-  console.log("Results URL:", resultsUrl);
-
-  // Get current state
-  const state = await store.getFullState();
-  console.log("Full state:", state);
-}
-
-// Zustand store creation example:
-function createExampleZustandUnifiedStore() {
-  return createZustandUnifiedStore({
-    onFilterUpdate: (apiParams) => {
-      console.log("Filters updated:", apiParams);
-      // Call your updateParams function here
-    }
-  });
-}
-
-// === MIGRATION NOTES ===
-
-/**
- * Key differences from the old approach:
- *
- * 1. Single unified store instead of separate property and app stores
- * 2. No more manual persist middleware configuration
- * 3. No more createORMStringStorage or custom IndexedDB setup
- * 4. All storage is handled natively by the ORM
- * 5. Better TypeScript support with proper schemas
- * 6. Validation built-in via Zod schemas
- * 7. Async operations are explicit
- * 8. Must call _initialize() and _hydrate() on app initialization
- *
- * Breaking changes:
- * - Two stores combined into one unified store
- * - All store methods are now async
- * - Must initialize store with _initialize() and _hydrate()
- * - Property data is now in 'properties' object with currentPropertyId tracking
- * - toggleFavorite no longer takes propertyId (uses currentPropertyId)
- * - Unit data and property data are separate but related
- *
- * Benefits:
- * - Single source of truth for all app state
- * - Centralized data management in ORM
- * - Better error handling and validation
- * - More consistent API across all operations
- * - Easier testing and mocking
- * - Better performance with native IndexedDB operations
- * - Simplified state management and debugging
- */

package/index.html

@@ -1,29 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>IndexedDB ORM Playground</title>
-    <style>
-      :root { font-family: system-ui, sans-serif; }
-      body { max-width: 800px; margin: 2rem auto; padding: 1rem; }
-      button { margin: 0.25rem 0.5rem 0.25rem 0; padding: 0.5rem 0.75rem; }
-      pre { background: #111; color: #eee; padding: 1rem; border-radius: 6px; overflow: auto; }
-      .row { margin: 0.75rem 0; }
-    </style>
-  </head>
-  <body>
-    <h1>IndexedDB ORM Playground</h1>
-    <p>Use these buttons to write/read data, then open DevTools → <strong>Application</strong> → <strong>IndexedDB</strong> → <code>inresi-orm</code>.</p>
-    <div class="row">
-      <button id="btn-init">Init DB</button>
-      <button id="btn-write">Write sample data</button>
-      <button id="btn-dump">Dump to console</button>
-      <button id="btn-export">Export JSON</button>
-      <button id="btn-reset">Reset DB</button>
-    </div>
-    <h3>Last dump</h3>
-    <pre id="dump">(nothing yet)</pre>
-    <script type="module" src="/playground/main.ts"></script>
-  </body>
-</html>