@superbright/indexeddb-orm 0.1.4 → 0.1.6

package/dist/storage.d.ts

@@ -0,0 +1,14 @@
+export interface AsyncStringStorage {
+    getItem(name: string): Promise<string | null>;
+    setItem(name: string, value: string): Promise<void>;
+    removeItem(name: string): Promise<void>;
+}
+type storeKeys = "property" | "user" | "app";
+export declare function kvGet<T>(key: storeKeys): Promise<T | null>;
+export declare function kvSet<T>(key: storeKeys, value: T): Promise<void>;
+export declare function kvRemove(key: storeKeys): Promise<void>;
+export declare function createORMStringStorage(opts?: {
+    prefix?: string;
+    fallbackToMemory?: boolean;
+}): AsyncStringStorage;
+export {};

package/dist/stores/store.d.ts

@@ -0,0 +1,211 @@
+import type { ZodObject, ZodTypeAny } from "zod";
+import { type UnifiedStoreData, type UserPropertyState, type Filters, type QueryParams, type ResultsMode, type SortBy, type TourContactData } from "../schema";
+export declare class UnifiedStore {
+    /**
+     * Resolves the persisted unified store snapshot, coercing legacy shapes into the latest schema
+     * and sanitizing invalid entries where possible.
+     */
+    private getState;
+    /**
+     * Applies an updater function to the current store state, validates the result, and persists it.
+     *
+     * @param updater - Pure function that maps the current state to the next state.
+     */
+    private setState;
+    /**
+     * Polls the persisted state until a current property pointer is available or the timeout elapses.
+     *
+     * @param timeoutMs - Maximum time in milliseconds to wait before failing.
+     * @returns The active property ID once it becomes available.
+     * @throws Error if the property pointer is not set before the timeout expires.
+     */
+    private waitForCurrentProperty;
+    /**
+     * Ensures a property entry exists and registers it as the current property.
+     *
+     * @param propertyId - Identifier used to track the property.
+     * @param slug - Canonical slug associated with the property.
+     */
+    initializeProperty(propertyId: string | number, slug: string): Promise<void>;
+    /**
+     * Persists a collection of units after validating each entry against the provided schema.
+     *
+     * @param units - Raw units collection returned by an API call.
+     * @param schema - Optional override schema when the default `UnitSchema` is not sufficient.
+     */
+    setUnitResults(units: unknown, schema?: ZodTypeAny): Promise<void>;
+    /**
+     * Clears the cached unit results array.
+     */
+    clearUnitResults(): Promise<void>;
+    /**
+     * Replaces the persisted property payload with validated data.
+     *
+     * @param propertyId - ID of the property to mutate.
+     * @param data - New property payload.
+     * @param schema - Optional schema override used for validation.
+     */
+    setPropertyData(propertyId: string | number, data: unknown, schema?: ZodObject<any, any, any, any, any>): Promise<void>;
+    /**
+     * Merges partial property data into the persisted payload with validation safeguards.
+     *
+     * @param propertyId - ID of the property to update.
+     * @param partial - Partial payload to merge.
+     * @param schema - Optional schema override for validation.
+     */
+    mergePropertyData(propertyId: string | number, partial: unknown, schema?: ZodObject<any, any, any, any, any>): Promise<void>;
+    /**
+     * Inserts or updates a property entry from an API payload, enforcing schema validation.
+     *
+     * @param apiProperty - Raw property object returned by an API.
+     * @param schema - Optional schema override.
+     */
+    upsertPropertyFromApi(apiProperty: unknown, schema?: ZodTypeAny): Promise<void>;
+    /**
+     * Marks the provided property as current and optionally updates the slug.
+     *
+     * @param propertyId - Property identifier to focus.
+     * @param slug - Optional slug override.
+     */
+    setCurrentProperty(propertyId: string | number, slug?: string): Promise<void>;
+    /**
+     * Updates the slug for the current property selection.
+     *
+     * @param slug - New slug to persist.
+     */
+    setCurrentPropertySlug(slug: string): Promise<void>;
+    /**
+     * Adds a slug to the `hasPreviouslySearched` list without duplicating existing entries.
+     *
+     * @param slug - Slug to record.
+     */
+    setHasPreviouslySearched(slug: string): Promise<void>;
+    /**
+     * Toggles a unit's favorite state for the currently active property.
+     *
+     * @param unitId - Unit identifier to toggle.
+     */
+    toggleFavorite(unitId: string): Promise<void>;
+    /**
+     * Records the most recent view date for a unit and opens the unit URL in the browser when available.
+     *
+     * @param unitId - Identifier of the viewed unit.
+     * @param slug - Property slug used to construct the URL.
+     */
+    markUnitAsViewed(unitId: string, slug: string): Promise<void>;
+    /**
+     * Stamps the current property with the moment the tour outreach occurred.
+     */
+    setTourContactedOn(): Promise<void>;
+    /**
+     * Reads the stored tour contact timestamp for the current property.
+     *
+     * @returns ISO string or null when no timestamp exists.
+     */
+    getTourContactedOn(): Promise<string | null>;
+    /**
+     * Persists questionnaire results captured for the current property.
+     *
+     * @param results - Arbitrary questionnaire data.
+     */
+    setQuestionnaireResults(results: unknown): Promise<void>;
+    /**
+     * Persists structured tour contact preferences for the active property. The method waits until
+     * a current property is available, allowing callers to invoke it before initialization completes.
+     *
+     * @param data - Contact preferences captured from the UI.
+     */
+    setTourContactData(data: TourContactData): Promise<void>;
+    /**
+     * Merges the provided filter values into the committed filter state.
+     *
+     * @param filters - Partial filter payload to apply.
+     */
+    setFilters(filters: Partial<Filters>): Promise<void>;
+    /**
+     * Updates the transient filters used for in-progress UI interactions.
+     *
+     * @param filters - Partial staging filter payload.
+     */
+    setTempFilters(filters: Partial<Filters>): Promise<void>;
+    /**
+     * Resets the committed filters to their default values.
+     */
+    setFiltersToDefault(): Promise<void>;
+    /**
+     * Merges partial values into the API filters payload used for network requests.
+     *
+     * @param filters - Partial query parameters to persist.
+     */
+    setApiFilters(filters: Partial<QueryParams>): Promise<void>;
+    /**
+     * Updates a single temporary filter field without touching the rest of the staged filters.
+     *
+     * @param key - Filter key to mutate.
+     * @param value - New value to assign.
+     */
+    handleTempFilterChange<K extends keyof Filters>(key: K, value: Filters[K]): Promise<void>;
+    /**
+     * Normalizes the committed filters into API-ready structures and persists the result.
+     */
+    submitFilterUpdate(): Promise<void>;
+    /**
+     * Persists the selected results mode (e.g. "all" or "favorites").
+     *
+     * @param mode - Mode identifier to store.
+     */
+    setResultsMode(mode: ResultsMode): Promise<void>;
+    /**
+     * Persists the currently selected sort option.
+     *
+     * @param sortBy - Sort identifier.
+     */
+    setSortBy(sortBy: SortBy): Promise<void>;
+    /**
+     * Stores resolved questionnaire answers keyed by questionnaire name.
+     *
+     * @param name - Questionnaire identifier.
+     * @param values - Selected option values.
+     */
+    setResolvedQuestionnaireValues(name: string, values: string[]): Promise<void>;
+    /**
+     * Returns convenience state for a unit within the current property.
+     *
+     * @param unitId - Identifier of the unit to inspect.
+     * @returns Favorite flag and last viewed date.
+     */
+    getUnitState(unitId: string): Promise<{
+        isFavorite: boolean;
+        viewedDate: string;
+    }>;
+    /**
+     * Builds a canonical results URL based on the current property slug.
+     *
+     * @returns Relative results URL or null when no property is selected.
+     */
+    getResultsUrl(): Promise<string | null>;
+    /**
+     * Retrieves the currently selected property entry.
+     *
+     * @returns Property state or null when unset.
+     */
+    getCurrentProperty(): Promise<UserPropertyState | null>;
+    /**
+     * Retrieves property data for a specific property or defaults to the current property.
+     *
+     * @param propertyId - Optional property identifier to fetch.
+     * @returns Property state or null when unavailable.
+     */
+    getPropertyData(propertyId?: string | number): Promise<UserPropertyState | null>;
+    /**
+     * Reads and returns the full validated unified store state.
+     */
+    getFullState(): Promise<UnifiedStoreData>;
+    /**
+     * Hydrates the store with the default scaffold when no data has been persisted yet.
+     */
+    initialize(): Promise<void>;
+}
+export declare const store: UnifiedStore;
+export { UnifiedStore as Store };
+export type { UserPropertyState, Filters } from "../schema";

package/dist/units/favorites.d.ts

@@ -0,0 +1,7 @@
+declare const favorites: {
+    isFavorite(propertyId: string | number, unitId: string): Promise<boolean>;
+    toggle(propertyId: string | number, unitId: string): Promise<string[]>;
+    set(propertyId: string | number, unitId: string, on: boolean): Promise<string[]>;
+    getAll(propertyId: string | number): Promise<string[]>;
+};
+export { favorites };

package/dist/validation.d.ts

@@ -0,0 +1,7 @@
+import type { z } from "zod";
+export type ValidationMode = "strict" | "warn" | "silent";
+export declare function configureValidation(opts: {
+    mode?: ValidationMode;
+    onIssue?: (ctx: string, details: unknown) => void;
+}): void;
+export declare function validate<T>(schema: z.ZodType<T>, value: unknown, ctx: string): T | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superbright/indexeddb-orm",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Vite + TypeScript starter for an IndexedDB ORM (Dexie + Zod) with playground.",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,20 +20,29 @@
   ],
   "dependencies": {
     "dexie": "^4.0.8",
+    "mixpanel-browser": "^2.67.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",
+    "@types/react": "^18.3.3",
     "concurrently": "^9.0.0",
+    "docusaurus-plugin-typedoc": "^1.4.2",
     "fake-indexeddb": "^5.0.2",
     "prettier": "^3.6.2",
     "prettier-plugin-packagejson": "^2.5.19",
+    "react": "^18.3.1",
     "rimraf": "^5.0.5",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.4.5",
     "vite": "^5.4.0",
     "vitest": "^2.0.5",
     "zustand": "^5.0.8"
   },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
   "scripts": {
     "clean": "rimraf dist",
     "build": "pnpm clean && vite build && tsc -p tsconfig.build.json",