@xh/hoist 72.0.0-SNAPSHOT.1736881018782 → 72.0.0-SNAPSHOT.1736893155432

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## v72.0.0-SNAPSHOT - unreleased
 
+### ⚙️ Technical
+
+* Added support for providing custom `PersistenceProvider` implementations to `PersistOptions`.
+
+
 ### ⚙️ Typescript API Adjustments
 
 * Improved signature of `HoistBase.markPersist`.

package/build/types/core/persist/PersistOptions.d.ts

@@ -1,17 +1,24 @@
-import { DebounceSpec } from '../';
+import { Class } from 'type-fest';
+import { DebounceSpec, PersistenceProvider, PersistenceProviderConfig } from '../';
 import type { DashViewModel } from '@xh/hoist/desktop/cmp/dash';
 import type { ViewManagerModel } from '@xh/hoist/cmp/viewmanager';
+/**
+ * Built-in Hoist PersistenceProviders.
+ */
+export type PersistenceProviderType = 'pref' | 'localStorage' | 'sessionStorage' | 'dashView' | 'viewManager' | 'custom';
 export interface PersistOptions {
     /** Dot delimited path to store state. */
     path?: string;
     /** Debounce interval in ms, or a lodash debounce config. */
     debounce?: DebounceSpec;
     /**
-     * Type of PersistenceProvider to create. If not provided, defaulted based
-     * on the presence of `prefKey`, `localStorageKey`, `dashViewModel`, 'viewManagerModel',
-     * `getData` and `setData`.
+     * Type of PersistenceProvider to create. Specify as one of the built-in string types,
+     * or a subclass of PersistenceProvider.
+     *
+     * If not provided, defaulted to one of the built-in string types based on the presence of
+     * `prefKey`, `localStorageKey`, `dashViewModel`, 'viewManagerModel', or `getData/setData`.
      */
-    type?: 'pref' | 'localStorage' | 'sessionStorage' | 'dashView' | 'viewManager' | 'custom';
+    type?: PersistenceProviderType | Class<PersistenceProvider, [PersistenceProviderConfig]>;
     /** Predefined Hoist application Preference key used to store state. */
     prefKey?: string;
     /** Browser local storage key used to store state. */

package/build/types/core/persist/PersistenceProvider.d.ts

@@ -1,12 +1,8 @@
 import { DebounceSpec, HoistBase, Persistable, PersistableState } from '../';
 import { PersistOptions } from './';
-export type PersistenceProviderConfig<S> = {
+export type PersistenceProviderConfig<S = any> = {
     persistOptions: PersistOptions;
     target: Persistable<S>;
-    owner: HoistBase;
-} | {
-    persistOptions: PersistOptions;
-    target: Persistable<S> & HoistBase;
     owner?: HoistBase;
 };
 /**
@@ -26,7 +22,7 @@ export type PersistenceProviderConfig<S> = {
  *   - {@link ViewManagerProvider} - persists to saved views managed by {@link ViewManagerModel}.
  *   - {@link CustomProvider} - API for app and components to provide their own storage mechanism.
  */
-export declare abstract class PersistenceProvider<S> {
+export declare abstract class PersistenceProvider<S = any> {
     readonly path: string;
     readonly debounce: DebounceSpec;
     readonly owner: HoistBase;
@@ -59,4 +55,5 @@ export declare abstract class PersistenceProvider<S> {
     protected writeInternal(data: S): void;
     protected writeRaw(obj: Record<typeof this.path, S>): void;
     protected readRaw(): Record<typeof this.path, S>;
+    private static parseProviderClass;
 }

package/core/persist/PersistOptions.ts

@@ -5,10 +5,22 @@
  * Copyright © 2025 Extremely Heavy Industries Inc.
  */
 
-import {DebounceSpec} from '../';
+import {Class} from 'type-fest';
+import {DebounceSpec, PersistenceProvider, PersistenceProviderConfig} from '../';
 import type {DashViewModel} from '@xh/hoist/desktop/cmp/dash'; // Import type only
 import type {ViewManagerModel} from '@xh/hoist/cmp/viewmanager'; // Import type only
 
+/**
+ * Built-in Hoist PersistenceProviders.
+ */
+export type PersistenceProviderType =
+    | 'pref'
+    | 'localStorage'
+    | 'sessionStorage'
+    | 'dashView'
+    | 'viewManager'
+    | 'custom';
+
 export interface PersistOptions {
     /** Dot delimited path to store state. */
     path?: string;
@@ -17,11 +29,13 @@ export interface PersistOptions {
     debounce?: DebounceSpec;
 
     /**
-     * Type of PersistenceProvider to create. If not provided, defaulted based
-     * on the presence of `prefKey`, `localStorageKey`, `dashViewModel`, 'viewManagerModel',
-     * `getData` and `setData`.
+     * Type of PersistenceProvider to create. Specify as one of the built-in string types,
+     * or a subclass of PersistenceProvider.
+     *
+     * If not provided, defaulted to one of the built-in string types based on the presence of
+     * `prefKey`, `localStorageKey`, `dashViewModel`, 'viewManagerModel', or `getData/setData`.
      */
-    type?: 'pref' | 'localStorage' | 'sessionStorage' | 'dashView' | 'viewManager' | 'custom';
+    type?: PersistenceProviderType | Class<PersistenceProvider, [PersistenceProviderConfig]>;
 
     /** Predefined Hoist application Preference key used to store state. */
     prefKey?: string;

package/core/persist/PersistenceProvider.ts

@@ -12,33 +12,29 @@ import {
     get,
     isEmpty,
     isNumber,
+    isString,
     isUndefined,
     set,
     toPath
 } from 'lodash';
 import {IReactionDisposer, reaction} from 'mobx';
-import {DebounceSpec, HoistBase, Persistable, PersistableState, XH} from '../';
+import {Class} from 'type-fest';
+import {DebounceSpec, HoistBase, Persistable, PersistableState} from '../';
 import {
     CustomProvider,
     DashViewProvider,
     LocalStorageProvider,
-    SessionStorageProvider,
     PersistOptions,
     PrefProvider,
+    SessionStorageProvider,
     ViewManagerProvider
 } from './';
 
-export type PersistenceProviderConfig<S> =
-    | {
-          persistOptions: PersistOptions;
-          target: Persistable<S>;
-          owner: HoistBase;
-      }
-    | {
-          persistOptions: PersistOptions;
-          target: Persistable<S> & HoistBase;
-          owner?: HoistBase;
-      };
+export type PersistenceProviderConfig<S = any> = {
+    persistOptions: PersistOptions;
+    target: Persistable<S>;
+    owner?: HoistBase;
+};
 
 /**
  * Abstract superclass for adaptor objects used by models and components to (re)store state to and
@@ -57,7 +53,7 @@ export type PersistenceProviderConfig<S> =
  *   - {@link ViewManagerProvider} - persists to saved views managed by {@link ViewManagerModel}.
  *   - {@link CustomProvider} - API for app and components to provide their own storage mechanism.
  */
-export abstract class PersistenceProvider<S> {
+export abstract class PersistenceProvider<S = any> {
     readonly path: string;
     readonly debounce: DebounceSpec;
     readonly owner: HoistBase;
@@ -79,49 +75,14 @@ export abstract class PersistenceProvider<S> {
      * target without thrashing.
      */
     static create<S>(cfg: PersistenceProviderConfig<S>): PersistenceProvider<S> {
-        cfg = {
-            owner: cfg.target instanceof HoistBase ? cfg.target : cfg.owner,
-            ...cfg
-        };
-        const {target, persistOptions} = cfg;
-
-        let {type, ...rest} = persistOptions,
-            ret: PersistenceProvider<S>;
-
+        let ret: PersistenceProvider<S>;
         try {
-            if (!type) {
-                if (rest.prefKey) type = 'pref';
-                if (rest.localStorageKey) type = 'localStorage';
-                if (rest.sessionStorageKey) type = 'sessionStorage';
-                if (rest.dashViewModel) type = 'dashView';
-                if (rest.viewManagerModel) type = 'viewManager';
-                if (rest.getData || rest.setData) type = 'custom';
-            }
-
-            switch (type) {
-                case 'pref':
-                    ret = new PrefProvider(cfg);
-                    break;
-                case 'localStorage':
-                    ret = new LocalStorageProvider(cfg);
-                    break;
-                case 'sessionStorage':
-                    ret = new SessionStorageProvider(cfg);
-                    break;
-                case `dashView`:
-                    ret = new DashViewProvider(cfg);
-                    break;
-                case `viewManager`:
-                    ret = new ViewManagerProvider(cfg);
-                    break;
-                case 'custom':
-                    ret = new CustomProvider(cfg);
-                    break;
-                default:
-                    throw XH.exception(`Unknown Persistence Provider for type: ${type}`);
-            }
+            // default owner to target
+            cfg = {owner: cfg.target instanceof HoistBase ? cfg.target : cfg.owner, ...cfg};
 
-            ret.bindToTarget(target);
+            const providerClass = this.parseProviderClass<S>(cfg.persistOptions);
+            ret = new providerClass(cfg);
+            ret.bindToTarget(cfg.target);
             return ret;
         } catch (e) {
             logError(e, cfg.owner);
@@ -211,7 +172,39 @@ export abstract class PersistenceProvider<S> {
     }
 
     protected writeRaw(obj: Record<typeof this.path, S>) {}
+
     protected readRaw(): Record<typeof this.path, S> {
         return null;
     }
+
+    private static parseProviderClass<S>(
+        opts: PersistOptions
+    ): Class<PersistenceProvider<S>, [PersistenceProviderConfig<S>]> {
+        // 1) Recognize shortcut form
+        const {type, ...rest} = opts;
+        if (!type) {
+            if (rest.prefKey) return PrefProvider;
+            if (rest.localStorageKey) return LocalStorageProvider;
+            if (rest.sessionStorageKey) return SessionStorageProvider;
+            if (rest.dashViewModel) return DashViewProvider;
+            if (rest.viewManagerModel) return ViewManagerProvider;
+            if (rest.getData || rest.setData) return CustomProvider;
+        }
+
+        // 2) Map any string to known Provider Class, or return raw class
+        const ret = isString(type)
+            ? {
+                  pref: PrefProvider,
+                  localStorage: LocalStorageProvider,
+                  sessionStorage: SessionStorageProvider,
+                  dashView: DashViewProvider,
+                  viewManager: ViewManagerProvider,
+                  custom: CustomProvider
+              }[type]
+            : type;
+
+        throwIf(!ret, `Unknown Persistence Provider: ${type}`);
+
+        return ret;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xh/hoist",
-  "version": "72.0.0-SNAPSHOT.1736881018782",
+  "version": "72.0.0-SNAPSHOT.1736893155432",
   "description": "Hoist add-on for building and deploying React Applications.",
   "repository": "github:xh/hoist-react",
   "homepage": "https://xh.io",