@superbright/indexeddb-orm 0.1.1

package/docs/property-store.md

@@ -0,0 +1,192 @@
+# 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

@@ -0,0 +1,129 @@
+# 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

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

@@ -0,0 +1,29 @@
+<!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>

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@superbright/indexeddb-orm",
+  "version": "0.1.1",
+  "description": "Vite + TypeScript starter for an IndexedDB ORM (Dexie + Zod) with playground.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.es.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "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"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "concurrently": "^9.0.0",
+    "fake-indexeddb": "^5.0.2",
+    "prettier": "^3.6.2",
+    "prettier-plugin-packagejson": "^2.5.19",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.5",
+    "vite": "^5.4.0",
+    "vitest": "^2.0.5"
+  }
+}

package/playground/main.ts

@@ -0,0 +1,38 @@
+import { getDB, resetDB, debugDump, exportJSON } from "../src/index";
+
+const dumpEl = document.getElementById("dump")!;
+
+function show(obj: unknown) {
+  dumpEl.textContent = JSON.stringify(obj, null, 2);
+}
+
+document.getElementById("btn-init")!.addEventListener("click", async () => {
+  await getDB();
+  const data = await debugDump();
+  show(data);
+  console.log("DB initialized", data);
+});
+
+document.getElementById("btn-write")!.addEventListener("click", async () => {
+  await getDB();
+});
+
+document.getElementById("btn-dump")!.addEventListener("click", async () => {
+  const snapshot = await debugDump();
+  console.log("Snapshot:", snapshot);
+  show(snapshot);
+});
+
+document.getElementById("btn-export")!.addEventListener("click", async () => {
+  await exportJSON();
+});
+
+document.getElementById("btn-reset")!.addEventListener("click", async () => {
+  await resetDB();
+  show({});
+  console.warn("DB reset.");
+});
+
+getDB().then(async () => {
+  show(await debugDump());
+});

package/src/adapters/dexie.ts

@@ -0,0 +1,28 @@
+import Dexie, { type Table } from "dexie";
+import { SCHEMA_VERSION } from "../schema";
+
+export interface KV {
+  key: string;
+  value: unknown;
+}
+
+export interface OrmDexieTables {
+  users: Table<any, string>;
+  kv: Table<KV, string>;
+}
+
+export class OrmDexie extends Dexie {
+  users!: OrmDexieTables["users"];
+  kv!: OrmDexieTables["kv"];
+
+  constructor(name = "inresi-orm") {
+    super(name);
+    this.version(SCHEMA_VERSION).stores({
+      users: "uuid",
+      kv: "key",
+    });
+
+    this.users = this.table("users");
+    this.kv = this.table("kv");
+  }
+}