@superbright/indexeddb-orm 0.1.1

package/src/api/properties.ts

@@ -0,0 +1,293 @@
+import { z } from "zod";
+import { kvGet, kvSet } from "../storage";
+
+// Property-related schemas
+export const ViewedUnitSchema = z.object({
+  unitId: z.string(),
+  viewedDate: z.string(),
+});
+
+export const TourContactDataSchema = z.object({
+  timezone: z.string(),
+  favouriteUnits: z.array(z.string()).optional(),
+  preferences: z.record(z.unknown()),
+});
+
+export const PropertyDataSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  favoritedUnits: z.array(z.string()),
+  tourContactedOn: z.string().nullable(),
+  viewedUnits: z.array(ViewedUnitSchema),
+  questionnaireResults: z.unknown().nullable().optional(), // Generic for IFilters
+  tourContactData: TourContactDataSchema.nullable().optional(),
+});
+
+export const PropertyStoreDataSchema = z.object({
+  data: z.record(PropertyDataSchema),
+  propertySlug: z.string().nullable(),
+  propertyId: z.string().nullable(),
+  hasPreviouslySearched: z.array(z.string()),
+});
+
+export type ViewedUnit = z.infer<typeof ViewedUnitSchema>;
+export type TourContactData = z.infer<typeof TourContactDataSchema>;
+export type PropertyData = z.infer<typeof PropertyDataSchema>;
+export type PropertyStoreData = z.infer<typeof PropertyStoreDataSchema>;
+
+// Default state
+const defaultPropertyStoreData: PropertyStoreData = {
+  data: {},
+  propertySlug: null,
+  propertyId: null,
+  hasPreviouslySearched: [],
+};
+
+// Core property store API
+export class PropertyStore {
+  private async getState(): Promise<PropertyStoreData> {
+    const state = await kvGet<PropertyStoreData>("property");
+    return state ?? defaultPropertyStoreData;
+  }
+
+  private async setState(updater: (state: PropertyStoreData) => PropertyStoreData): Promise<void> {
+    const currentState = await this.getState();
+    const newState = updater(currentState);
+    await kvSet("property", newState);
+  }
+
+  // Basic state operations
+  async setData(value: Record<string, PropertyData>): Promise<void> {
+    await this.setState(state => ({ ...state, data: value }));
+  }
+
+  async setPropertySlug(slug: string): Promise<void> {
+    await this.setState(state => ({ ...state, propertySlug: slug }));
+  }
+
+  async setPropertyId(id: string): Promise<void> {
+    await this.setState(state => ({ ...state, propertyId: id }));
+  }
+
+  async removeData(key: string): Promise<void> {
+    await this.setState(state => ({
+      ...state,
+      data: Object.entries(state.data)
+        .filter(([k]) => k !== key)
+        .reduce((acc, [k, v]) => ({ ...acc, [k]: v }), {}),
+    }));
+  }
+
+  async clearData(): Promise<void> {
+    await this.setState(state => ({ ...state, data: {} }));
+  }
+
+  async setHasPreviouslySearched(slug: string): Promise<void> {
+    await this.setState(state => ({
+      ...state,
+      hasPreviouslySearched: Array.from(
+        new Set([...state.hasPreviouslySearched, slug])
+      ),
+    }));
+  }
+
+  // Property-specific operations
+  async setTourContactedOn(): Promise<void> {
+    await this.setState(state => {
+      const propertyId = state.propertyId;
+      if (!propertyId) return state;
+
+      const property = state.data[propertyId];
+      if (!property) return state;
+
+      return {
+        ...state,
+        data: {
+          ...state.data,
+          [propertyId]: {
+            ...property,
+            tourContactedOn: new Date().toISOString(),
+          },
+        },
+      };
+    });
+  }
+
+  async getTourContactedOn(): Promise<string | null> {
+    const state = await this.getState();
+    const propertyId = state.propertyId;
+    if (!propertyId) return null;
+
+    return state.data[propertyId]?.tourContactedOn ?? null;
+  }
+
+  async setQuestionnaireResults(results: unknown): Promise<void> {
+    await this.setState(state => {
+      const propertyId = state.propertyId;
+      if (!propertyId) return state;
+
+      const property = state.data[propertyId];
+      if (!property) return state;
+
+      return {
+        ...state,
+        data: {
+          ...state.data,
+          [propertyId]: {
+            ...property,
+            questionnaireResults: results,
+          },
+        },
+      };
+    });
+  }
+
+  async setTourContactData(data: TourContactData): Promise<void> {
+    await this.setState(state => {
+      const propertyId = state.propertyId;
+      if (!propertyId) return state;
+
+      const property = state.data[propertyId];
+      if (!property) return state;
+
+      return {
+        ...state,
+        data: {
+          ...state.data,
+          [propertyId]: {
+            ...property,
+            tourContactData: data,
+          },
+        },
+      };
+    });
+  }
+
+  async toggleFavorite(unitId: string): Promise<void> {
+    await this.setState(state => {
+      const propertyId = state.propertyId;
+      if (!propertyId) return state;
+
+      const property = state.data[propertyId];
+      if (!property) return state;
+
+      const isFavorited = property.favoritedUnits.includes(unitId);
+      const updatedFavoritedUnits = isFavorited
+        ? property.favoritedUnits.filter((id) => id !== unitId)
+        : [...property.favoritedUnits, unitId];
+
+      return {
+        ...state,
+        data: {
+          ...state.data,
+          [propertyId]: {
+            ...property,
+            favoritedUnits: updatedFavoritedUnits,
+          },
+        },
+      };
+    });
+  }
+
+  async markUnitAsViewed(unitId: string, slug: string): Promise<void> {
+    const today = new Date();
+    const formattedDate = `${String(today.getMonth() + 1).padStart(
+      2,
+      "0"
+    )}/${String(today.getDate()).padStart(2, "0")}`;
+
+    await this.setState(state => {
+      const propertyId = state.propertyId;
+      if (!propertyId) return state;
+
+      const property = state.data[propertyId];
+      if (!property) return state;
+
+      const updatedViewedUnits = [
+        // Remove existing entry if it exists
+        ...property.viewedUnits.filter((u) => u.unitId !== unitId),
+        // Add updated one
+        {
+          unitId,
+          viewedDate: formattedDate,
+        },
+      ];
+
+      return {
+        ...state,
+        data: {
+          ...state.data,
+          [propertyId]: {
+            ...property,
+            viewedUnits: updatedViewedUnits,
+          },
+        },
+      };
+    });
+
+    // Note: This opens a new window - you might want to handle this in the consuming app
+    if (typeof window !== 'undefined') {
+      window.open(`//${slug}`, "_blank");
+    }
+  }
+
+  // Utility methods for getting specific data
+  async getUnitState(unitId: string): Promise<{
+    isFavorite: boolean;
+    viewedDate: string;
+  }> {
+    const state = await this.getState();
+    const property = state.propertyId ? state.data[state.propertyId] : null;
+
+    return {
+      isFavorite: property?.favoritedUnits.includes(unitId) ?? false,
+      viewedDate:
+        property?.viewedUnits.find((u) => u.unitId === unitId)?.viewedDate ?? "",
+    };
+  }
+
+  async getPropertyData(propertyId?: string): Promise<PropertyData | null> {
+    const state = await this.getState();
+    const id = propertyId ?? state.propertyId;
+    return id ? state.data[id] ?? null : null;
+  }
+
+  async getCurrentProperty(): Promise<PropertyData | null> {
+    const state = await this.getState();
+    return state.propertyId ? state.data[state.propertyId] ?? null : null;
+  }
+
+  async getFullState(): Promise<PropertyStoreData> {
+    return this.getState();
+  }
+
+  // Initialize property if it doesn't exist
+  async initializeProperty(propertyId: string, slug: string): Promise<void> {
+    await this.setState(state => {
+      if (state.data[propertyId]) {
+        return { ...state, propertyId, propertySlug: slug };
+      }
+
+      return {
+        ...state,
+        propertyId,
+        propertySlug: slug,
+        data: {
+          ...state.data,
+          [propertyId]: {
+            id: propertyId,
+            slug,
+            favoritedUnits: [],
+            tourContactedOn: null,
+            viewedUnits: [],
+            questionnaireResults: null,
+            tourContactData: null,
+          },
+        },
+      };
+    });
+  }
+}
+
+// Export singleton instance
+export const propertyStore = new PropertyStore();

package/src/api/users.ts

@@ -0,0 +1,66 @@
+import { getDB } from "../db";
+import { UserSchema, type User } from "../schema";
+
+const USER_POINTER_KEY = "user";
+
+export type IdGenerator = () => string;
+export const defaultIdGenerator: IdGenerator = () =>
+  typeof globalThis.crypto?.randomUUID === "function"
+    ? globalThis.crypto.randomUUID()
+    : (() => {
+        const b =
+          globalThis.crypto?.getRandomValues?.(new Uint8Array(16)) ??
+          Uint8Array.from({ length: 16 }, () => (Math.random() * 256) | 0);
+        b[6] = (b[6] & 0x0f) | 0x40; // v4
+        b[8] = (b[8] & 0x3f) | 0x80; // variant
+        const h = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+        return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+      })();
+
+const getPointerUuid = (row: any) => row?.value?.useruuid ?? row?.value?.uuid;
+
+export async function ensureUser(
+  gen: IdGenerator = defaultIdGenerator,
+): Promise<User> {
+  const db = await getDB();
+
+  // Fast path
+  const ptrUuid = getPointerUuid(await db.kv.get(USER_POINTER_KEY));
+  if (ptrUuid) {
+    const existing = await db.users.get(ptrUuid);
+    if (existing) return UserSchema.parse(existing);
+  }
+
+  // Race-safe creation
+  try {
+    return await db.transaction("rw", db.kv, db.users, async () => {
+      const insideUuid = getPointerUuid(await db.kv.get(USER_POINTER_KEY));
+      if (insideUuid) {
+        const existing = await db.users.get(insideUuid);
+        if (existing) return UserSchema.parse(existing);
+      }
+
+      const uuid = gen();
+      await db.kv.add({ key: USER_POINTER_KEY, value: { useruuid: uuid } }); // claim pointer
+      const newUser: User = UserSchema.parse({
+        uuid,
+        createdAt: new Date().toISOString(),
+      });
+      await db.users.add(newUser);
+      return newUser;
+    });
+  } catch (e: any) {
+    if (e?.name === "ConstraintError") {
+      // Lost the race → read winner
+      const uuid = getPointerUuid(await db.kv.get(USER_POINTER_KEY));
+      if (uuid) {
+        const winner = await db.users.get(uuid);
+        if (winner) return UserSchema.parse(winner);
+      }
+    }
+    throw e;
+  }
+}
+
+export const getUserUUID = async (gen?: IdGenerator) =>
+  (await ensureUser(gen)).uuid;

package/src/db.ts

@@ -0,0 +1,185 @@
+// src/db.ts
+import { OrmDexie } from "./adapters/dexie";
+import { OpenDBError } from "./errors";
+import { SCHEMA_VERSION, UserSchema } from "./schema";
+import {
+  validate,
+  configureValidation,
+  type ValidationMode,
+} from "./validation";
+import type { Table } from "dexie";
+import { z } from "zod";
+
+const MANIFEST_KEY = "manifest";
+const ManifestSchema = z.object({ schemaVersion: z.number().int() });
+type Manifest = z.infer<typeof ManifestSchema>;
+
+export type OrmOptions = {
+  dbName?: string;
+  onReset?: (reason: "incompatible" | "versionchange" | "blocked") => void;
+  onError?: (err: unknown) => void;
+  validation?: {
+    mode?: ValidationMode; // 'strict' | 'warn' | 'silent'
+    onIssue?: (ctx: string, details: unknown) => void;
+    validateReads?: boolean; // default: true
+    dropInvalidOnRead?: boolean; // default: true (when validateReads)
+  };
+};
+
+let db: OrmDexie | null = null;
+let openPromise: Promise<OrmDexie> | null = null;
+
+// Prevent double-installing hooks on the same instance
+const VALIDATION_INSTALLED = Symbol("validationInstalled");
+
+function installValidationHooks(
+  instance: OrmDexie,
+  vopts: OrmOptions["validation"] | undefined,
+) {
+  const anyDb = instance as any;
+  if (anyDb[VALIDATION_INSTALLED]) return;
+  anyDb[VALIDATION_INSTALLED] = true;
+
+  const writeHook = <T>(table: Table<T, any>, schema: any, name: string) => {
+    table.hook("creating", (_pk, obj) => {
+      const v = validate(schema, obj, `${name}.creating`);
+      if (!v) throw new Error(`Rejected invalid ${name} on create`);
+      return v as T; // allow coercion/stripping
+    });
+    table.hook("updating", (mods, _pk, obj) => {
+      const next = { ...(obj as any), ...(mods as any) };
+      const v = validate(schema, next, `${name}.updating`);
+      if (!v) return {}; // cancel update in warn/silent
+      return mods;
+    });
+  };
+
+  writeHook(instance.users, UserSchema, "users");
+
+  const shouldValidateReads = vopts?.validateReads ?? true;
+  if (shouldValidateReads) {
+    const dropInvalid = vopts?.dropInvalidOnRead ?? true;
+    const readHook = <T>(table: Table<T, any>, schema: any, name: string) => {
+      table.hook("reading", (obj) => {
+        const v = validate(schema, obj, `${name}.reading`);
+        if (v) return v;
+        return dropInvalid ? undefined : obj; // pass-through if you prefer
+      });
+    };
+    readHook(instance.users, UserSchema, "users");
+  }
+}
+
+function isProbablyDev(): boolean {
+  try {
+    // @ts-ignore
+    if (typeof import.meta !== "undefined" && import.meta.env)
+      // @ts-ignore
+      return !!import.meta.env.DEV;
+  } catch {}
+  try {
+    if (typeof process !== "undefined" && process.env)
+      return process.env.NODE_ENV !== "production";
+  } catch {}
+  return false;
+}
+
+export async function getDB(opts: OrmOptions = {}): Promise<OrmDexie> {
+  if (db) return db;
+  if (openPromise) return openPromise;
+
+  const name = opts.dbName ?? "inresi-orm";
+
+  openPromise = (async () => {
+    try {
+      // Configure validation once per open
+      const defaultMode: ValidationMode = isProbablyDev() ? "warn" : "strict";
+      configureValidation({
+        mode: opts.validation?.mode ?? defaultMode,
+        onIssue: opts.validation?.onIssue,
+      });
+
+      const instance = new OrmDexie(name);
+
+      // Multi-tab friendliness
+      instance.on("versionchange", () => {
+        try {
+          instance.close();
+        } finally {
+          opts.onReset?.("versionchange");
+        }
+      });
+      instance.on("blocked", () => {
+        opts.onReset?.("blocked");
+      });
+
+      await instance.open();
+
+      // Validate/initialize manifest
+      const row = await instance.kv.get(MANIFEST_KEY);
+      const saved = (row?.value ?? null) as unknown;
+
+      if (!saved) {
+        await instance.transaction("rw", instance.kv, async () => {
+          await instance.kv.put({
+            key: MANIFEST_KEY,
+            value: { schemaVersion: SCHEMA_VERSION },
+          });
+        });
+        installValidationHooks(instance, opts.validation);
+        db = instance;
+        return instance;
+      }
+
+      const parsed = ManifestSchema.safeParse(saved as Manifest);
+      if (!parsed.success || parsed.data.schemaVersion !== SCHEMA_VERSION) {
+        await instance.delete();
+        const fresh = new OrmDexie(name);
+        fresh.on("versionchange", () => {
+          try {
+            fresh.close();
+          } finally {
+            opts.onReset?.("versionchange");
+          }
+        });
+        fresh.on("blocked", () => {
+          opts.onReset?.("blocked");
+        });
+        await fresh.open();
+        await fresh.kv.put({
+          key: MANIFEST_KEY,
+          value: { schemaVersion: SCHEMA_VERSION },
+        });
+        installValidationHooks(fresh, opts.validation);
+        opts.onReset?.("incompatible");
+        db = fresh;
+        return fresh;
+      }
+
+      installValidationHooks(instance, opts.validation);
+      db = instance;
+      return instance;
+    } catch (e) {
+      opts.onError?.(e);
+      throw new OpenDBError("Failed to open IndexedDB", e);
+    } finally {
+      openPromise = null; // allow future reuse/retry
+    }
+  })();
+
+  return openPromise;
+}
+
+export async function resetDB(dbName?: string) {
+  const name = dbName ?? "inresi-orm";
+  if (db) {
+    try {
+      await db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+  const instance = new OrmDexie(name);
+  await instance.delete();
+  db = null;
+}

package/src/debug.ts

@@ -0,0 +1,25 @@
+import { getDB } from "./db";
+
+export async function debugDump(): Promise<Record<string, unknown[]>> {
+  const db = await getDB();
+  const out: Record<string, unknown[]> = {};
+  for (const t of db.tables) {
+    out[t.name] = await t.toArray();
+  }
+  return out;
+}
+
+export async function exportJSON(filename = "inresi-orm-export.json"): Promise<void> {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    throw new Error("exportJSON can only run in a browser.");
+  }
+  const snapshot = await debugDump();
+  const blob = new Blob([JSON.stringify(snapshot, null, 2)], { type: "application/json" });
+  const a = document.createElement("a");
+  a.href = URL.createObjectURL(blob);
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(a.href);
+}

package/src/errors.ts

@@ -0,0 +1,13 @@
+export class SchemaMismatchError extends Error {
+  constructor(message: string, public detail?: unknown) {
+    super(message);
+    this.name = "SchemaMismatchError";
+  }
+}
+
+export class OpenDBError extends Error {
+  constructor(message: string, public detail?: unknown) {
+    super(message);
+    this.name = "OpenDBError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+export * from "./errors";
+export * from "./schema";
+export * from "./db";
+export * from "./api/users";
+export * from "./debug";
+export * from "./storage";
+export * from "./api/favorites";
+export {
+  PropertyStore,
+  propertyStore,
+  type PropertyData,
+  type PropertyStoreData,
+} from "./api/properties";
+
+// Export unified store classes and main functionality
+export { UnifiedStore, store } from "./stores/unified";
+export {
+  createZustandUnifiedStore,
+  createZustandUnifiedStore as createZustandPropertyStore, // Alias for easier migration
+  createUseUnitState,
+  type ZustandUnifiedStoreState
+} from "./adapters/zustand-unified";
+
+// Export structured store with nested actions
+export {
+  createStructuredStore,
+  createStructuredStoreActions,
+  type StructuredStore,
+  type StructuredStoreActions
+} from "./adapters/structured-store";
+
+export { favorites } from "./units/favorites";
+
+export { configureValidation, type ValidationMode } from "./validation";

package/src/schema.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+export const SCHEMA_VERSION = 1 as const;
+
+// Entities
+export const UserSchema = z.object({
+  uuid: z.string().uuid(),
+});
+export type User = z.infer<typeof UserSchema>;
+
+// favorites
+export const FavoritesSchema = z.object({
+  propertyId: z.string() || z.number(),
+  unitIds: z.array(z.string()),
+});
+export type Favorites = z.infer<typeof FavoritesSchema>;
+
+// Re-export property schemas from the API module
+export {
+  ViewedUnitSchema,
+  TourContactDataSchema,
+  PropertyDataSchema,
+  PropertyStoreDataSchema,
+  type ViewedUnit,
+  type TourContactData,
+  type PropertyData,
+  type PropertyStoreData,
+} from "./api/properties";
+
+// Re-export app schemas from the API module
+export {
+  UnitDataSchema,
+  FiltersSchema,
+  QueryParamsSchema,
+  AppStoreDataSchema,
+  type UnitData,
+  type Filters,
+  type QueryParams,
+  type AppStoreData,
+  type ResultsMode,
+  type SortBy,
+} from "./api/app";
+
+// Re-export unified store schemas
+export {
+  UnifiedStoreDataSchema,
+  type UnifiedStoreData,
+} from "./stores/unified";