@blueprint-ts/core 4.1.0-beta.4 → 4.1.0-beta.5

package/dist/vue/forms/BaseForm.d.ts

@@ -1,6 +1,7 @@
 import { type PersistenceDriver } from '../../persistenceDrivers/types/PersistenceDriver';
 import { PropertyAwareArray, type PropertyAwareField } from './PropertyAwareArray';
 import { PropertyAwareObject } from './PropertyAwareObject';
+import { type PersistenceDebugEvent, type PersistenceRestorePolicy } from './persistence/types';
 import { type ValidationGroups, type ValidationRules } from './validation';
 type ErrorMessages = string[];
 interface ErrorObject {
@@ -82,6 +83,9 @@ export declare abstract class BaseForm<RequestBody extends object, FormBody exte
      * Child classes can override this method to return a different driver.
      */
     protected getPersistenceDriver(_suffix: string | undefined): PersistenceDriver;
+    protected getPersistenceRestorePolicy(): PersistenceRestorePolicy<FormBody>;
+    protected shouldLogPersistenceDebug(): boolean;
+    protected logPersistenceDebug(event: PersistenceDebugEvent<FormBody>): void;
     /**
      * Helper: recursively computes the dirty state for a value based on the original.
      * For plain arrays we compare the entire array (a single flag), not each element.

package/dist/vue/forms/BaseForm.js

@@ -12,6 +12,7 @@ import { camelCase, upperFirst, cloneDeep, debounce, isEqual } from 'lodash-es';
 import { NonPersistentDriver } from '../../persistenceDrivers/NonPersistentDriver';
 import { PropertyAwareArray } from './PropertyAwareArray';
 import { PropertyAwareObject, PROPERTY_AWARE_OBJECT_MARKER } from './PropertyAwareObject';
+import { StrictPersistenceRestorePolicy } from './persistence/StrictPersistenceRestorePolicy';
 import { BaseRule } from './validation/rules/BaseRule';
 import { ValidationMode } from './validation';
 function isRecord(value) {
@@ -140,39 +141,6 @@ function restorePropertyAwareStructure(defaults, value) {
     }
     return restoreSerializedPropertyAwareValue(value);
 }
-function normalizePropertyAwareEqualityValue(value) {
-    if (value instanceof PropertyAwareArray) {
-        return Array.from(value, (item) => normalizePropertyAwareEqualityValue(item));
-    }
-    if (isPropertyAwareObject(value) || isSerializedPropertyAwareObject(value)) {
-        const normalized = {};
-        for (const [key, child] of Object.entries(value)) {
-            if (key === PROPERTY_AWARE_OBJECT_MARKER) {
-                continue;
-            }
-            normalized[key] = normalizePropertyAwareEqualityValue(child);
-        }
-        return normalized;
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => normalizePropertyAwareEqualityValue(item));
-    }
-    if (isRecord(value)) {
-        const normalized = {};
-        for (const [key, child] of Object.entries(value)) {
-            normalized[key] = normalizePropertyAwareEqualityValue(child);
-        }
-        return normalized;
-    }
-    return value;
-}
-/**
- * Compare values while ignoring persistence-only markers on property-aware structures.
- * This avoids false negatives when comparing persisted state to defaults.
- */
-function propertyAwareDeepEqual(a, b) {
-    return isEqual(normalizePropertyAwareEqualityValue(a), normalizePropertyAwareEqualityValue(b));
-}
 /**
  * A generic base class for forms.
  *
@@ -191,6 +159,20 @@ export class BaseForm {
     getPersistenceDriver(_suffix) {
         return new NonPersistentDriver();
     }
+    getPersistenceRestorePolicy() {
+        return new StrictPersistenceRestorePolicy();
+    }
+    shouldLogPersistenceDebug() {
+        return false;
+    }
+    logPersistenceDebug(event) {
+        if (!this.shouldLogPersistenceDebug()) {
+            return;
+        }
+        const suffixLabel = event.persistSuffix ? ` (${event.persistSuffix})` : '';
+        const details = event.details ? ` ${JSON.stringify(event.details)}` : '';
+        console.debug(`[BaseForm persistence] ${event.formName}${suffixLabel}: ${event.action} (${event.reason})${details}`);
+    }
     /**
      * Helper: recursively computes the dirty state for a value based on the original.
      * For plain arrays we compare the entire array (a single flag), not each element.
@@ -324,6 +306,7 @@ export class BaseForm {
         }
     }
     constructor(defaults, options) {
+        var _a;
         this.options = options;
         this._errors = reactive({});
         this._asyncErrors = reactive({});
@@ -342,21 +325,35 @@ export class BaseForm {
         let initialData;
         const driver = this.getPersistenceDriver(options === null || options === void 0 ? void 0 : options.persistSuffix);
         if (persist) {
-            const persisted = driver.get(this.constructor.name);
-            if (persisted && propertyAwareDeepEqual(defaults, persisted.original)) {
-                initialData = restorePropertyAwareStructure(defaults, persisted.state);
-                this.original = restorePropertyAwareStructure(defaults, cloneDeep(persisted.original));
-                this.dirty = reactive(persisted.dirty);
-                this.touched = reactive(persisted.touched || {});
+            const persisted = (_a = driver.get(this.constructor.name)) !== null && _a !== void 0 ? _a : null;
+            const restoreDecision = this.getPersistenceRestorePolicy().resolve({
+                formName: this.constructor.name,
+                persistSuffix: options === null || options === void 0 ? void 0 : options.persistSuffix,
+                defaults,
+                persisted
+            });
+            this.logPersistenceDebug({
+                formName: this.constructor.name,
+                persistSuffix: options === null || options === void 0 ? void 0 : options.persistSuffix,
+                action: restoreDecision.action,
+                reason: restoreDecision.reason,
+                details: restoreDecision.details
+            });
+            if (restoreDecision.action === 'restore' && restoreDecision.persisted) {
+                initialData = restorePropertyAwareStructure(defaults, restoreDecision.persisted.state);
+                this.original = restorePropertyAwareStructure(defaults, cloneDeep(restoreDecision.persisted.original));
+                this.dirty = reactive(restoreDecision.persisted.dirty);
+                this.touched = reactive(restoreDecision.persisted.touched || {});
             }
             else {
-                console.log('Discarding persisted data for ' + this.constructor.name + " because it doesn't match the defaults.");
                 initialData = defaults;
                 this.original = restorePropertyAwareStructure(defaults, cloneDeep(defaults));
                 const init = this.initDirtyTouched(defaults);
                 this.dirty = init.dirty;
                 this.touched = init.touched;
-                driver.remove(this.constructor.name);
+                if (restoreDecision.action === 'discard') {
+                    driver.remove(this.constructor.name);
+                }
             }
         }
         else {
@@ -379,7 +376,7 @@ export class BaseForm {
                     set: (newVal) => {
                         const next = Array.isArray(newVal) ? Array.from(newVal) : [];
                         this.replacePropertyAwareArray(key, next);
-                        this.dirty[key] = next.map(() => false);
+                        this.dirty[key] = this.computeDirtyState(this.state[key], this.original[key]);
                         this.markFieldUpdated(key, driver);
                     }
                 });
@@ -1193,7 +1190,7 @@ export class BaseForm {
             if (currentVal instanceof PropertyAwareArray) {
                 const values = newVal instanceof PropertyAwareArray || Array.isArray(newVal) ? Array.from(newVal) : [];
                 this.replacePropertyAwareArray(key, values);
-                this.dirty[key] = values.map(() => false);
+                this.dirty[key] = this.computeDirtyState(this.state[key], this.original[key]);
                 this.touched[key] = true;
                 continue;
             }

package/dist/vue/forms/index.d.ts

@@ -6,5 +6,7 @@ import { SessionStorageDriver } from '../../persistenceDrivers/SessionStorageDri
 import { type PersistenceDriver } from '../../persistenceDrivers/types/PersistenceDriver';
 import { PropertyAwareArray, type PropertyAwareField, type PropertyAware } from './PropertyAwareArray';
 import { PropertyAwareObject } from './PropertyAwareObject';
-export { BaseForm, propertyAwareToRaw, PropertyAwareArray, PropertyAwareObject, NonPersistentDriver, SessionStorageDriver, LocalStorageDriver };
-export type { PersistedForm, PersistenceDriver, PropertyAwareField, PropertyAware };
+import { StrictPersistenceRestorePolicy } from './persistence';
+import type { PersistenceDebugEvent, PersistenceRestoreContext, PersistenceRestorePolicy, PersistenceRestoreResult } from './persistence';
+export { BaseForm, propertyAwareToRaw, PropertyAwareArray, PropertyAwareObject, NonPersistentDriver, SessionStorageDriver, LocalStorageDriver, StrictPersistenceRestorePolicy };
+export type { PersistedForm, PersistenceDriver, PropertyAwareField, PropertyAware, PersistenceDebugEvent, PersistenceRestoreContext, PersistenceRestorePolicy, PersistenceRestoreResult };

package/dist/vue/forms/index.js

@@ -4,4 +4,5 @@ import { NonPersistentDriver } from '../../persistenceDrivers/NonPersistentDrive
 import { SessionStorageDriver } from '../../persistenceDrivers/SessionStorageDriver';
 import { PropertyAwareArray } from './PropertyAwareArray';
 import { PropertyAwareObject } from './PropertyAwareObject';
-export { BaseForm, propertyAwareToRaw, PropertyAwareArray, PropertyAwareObject, NonPersistentDriver, SessionStorageDriver, LocalStorageDriver };
+import { StrictPersistenceRestorePolicy } from './persistence';
+export { BaseForm, propertyAwareToRaw, PropertyAwareArray, PropertyAwareObject, NonPersistentDriver, SessionStorageDriver, LocalStorageDriver, StrictPersistenceRestorePolicy };

package/dist/vue/forms/persistence/StrictPersistenceRestorePolicy.d.ts

@@ -0,0 +1,4 @@
+import { type PersistenceRestoreContext, type PersistenceRestorePolicy, type PersistenceRestoreResult } from './types';
+export declare class StrictPersistenceRestorePolicy<FormBody extends object> implements PersistenceRestorePolicy<FormBody> {
+    resolve(context: PersistenceRestoreContext<FormBody>): PersistenceRestoreResult<FormBody>;
+}

package/dist/vue/forms/persistence/StrictPersistenceRestorePolicy.js

@@ -0,0 +1,42 @@
+import { collectPropertyAwareMismatchPaths, propertyAwareDeepEqual } from './utils';
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isPersistedFormLike(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return 'state' in value && 'original' in value && 'dirty' in value;
+}
+export class StrictPersistenceRestorePolicy {
+    resolve(context) {
+        const { defaults, persisted } = context;
+        if (persisted === null) {
+            return {
+                action: 'ignore',
+                reason: 'no_persisted_state'
+            };
+        }
+        if (!isPersistedFormLike(persisted)) {
+            return {
+                action: 'discard',
+                reason: 'invalid_persisted_state'
+            };
+        }
+        if (propertyAwareDeepEqual(defaults, persisted.original)) {
+            return {
+                action: 'restore',
+                reason: 'defaults_match',
+                persisted
+            };
+        }
+        return {
+            action: 'discard',
+            reason: 'defaults_mismatch',
+            persisted,
+            details: {
+                mismatchPaths: collectPropertyAwareMismatchPaths(defaults, persisted.original)
+            }
+        };
+    }
+}

package/dist/vue/forms/persistence/index.d.ts

@@ -0,0 +1,3 @@
+import { StrictPersistenceRestorePolicy } from './StrictPersistenceRestorePolicy';
+export { StrictPersistenceRestorePolicy };
+export type { PersistenceDebugEvent, PersistenceRestoreContext, PersistenceRestorePolicy, PersistenceRestoreResult } from './types';

package/dist/vue/forms/persistence/index.js

@@ -0,0 +1,2 @@
+import { StrictPersistenceRestorePolicy } from './StrictPersistenceRestorePolicy';
+export { StrictPersistenceRestorePolicy };

package/dist/vue/forms/persistence/types.d.ts

@@ -0,0 +1,23 @@
+import { type PersistedForm } from '../types/PersistedForm';
+export interface PersistenceRestoreContext<FormBody extends object> {
+    formName: string;
+    persistSuffix?: string | undefined;
+    defaults: FormBody;
+    persisted: PersistedForm<FormBody> | null;
+}
+export interface PersistenceRestoreResult<FormBody extends object> {
+    action: 'restore' | 'discard' | 'ignore';
+    reason: string;
+    persisted?: PersistedForm<FormBody> | undefined;
+    details?: Record<string, unknown> | undefined;
+}
+export interface PersistenceDebugEvent<FormBody extends object> {
+    formName: string;
+    persistSuffix?: string | undefined;
+    action: PersistenceRestoreResult<FormBody>['action'];
+    reason: string;
+    details?: Record<string, unknown> | undefined;
+}
+export interface PersistenceRestorePolicy<FormBody extends object> {
+    resolve(context: PersistenceRestoreContext<FormBody>): PersistenceRestoreResult<FormBody>;
+}

package/dist/vue/forms/persistence/types.js

@@ -0,0 +1 @@
+export {};

package/dist/vue/forms/persistence/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function propertyAwareDeepEqual<T>(a: T, b: T): boolean;
+export declare function collectPropertyAwareMismatchPaths(a: unknown, b: unknown, path?: string, maxPaths?: number): string[];

package/dist/vue/forms/persistence/utils.js

@@ -0,0 +1,77 @@
+import { isEqual } from 'lodash-es';
+import { PropertyAwareArray } from '../PropertyAwareArray';
+import { PropertyAwareObject, PROPERTY_AWARE_OBJECT_MARKER } from '../PropertyAwareObject';
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isPropertyAwareObject(value) {
+    return value instanceof PropertyAwareObject;
+}
+function isSerializedPropertyAwareObject(value) {
+    return isRecord(value) && value[PROPERTY_AWARE_OBJECT_MARKER] === true;
+}
+function normalizePropertyAwareEqualityValue(value) {
+    if (value instanceof PropertyAwareArray) {
+        return Array.from(value, (item) => normalizePropertyAwareEqualityValue(item));
+    }
+    if (isPropertyAwareObject(value) || isSerializedPropertyAwareObject(value)) {
+        const normalized = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (key === PROPERTY_AWARE_OBJECT_MARKER) {
+                continue;
+            }
+            normalized[key] = normalizePropertyAwareEqualityValue(child);
+        }
+        return normalized;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizePropertyAwareEqualityValue(item));
+    }
+    if (isRecord(value)) {
+        const normalized = {};
+        for (const [key, child] of Object.entries(value)) {
+            normalized[key] = normalizePropertyAwareEqualityValue(child);
+        }
+        return normalized;
+    }
+    return value;
+}
+export function propertyAwareDeepEqual(a, b) {
+    return isEqual(normalizePropertyAwareEqualityValue(a), normalizePropertyAwareEqualityValue(b));
+}
+export function collectPropertyAwareMismatchPaths(a, b, path = '', maxPaths = 10) {
+    const mismatches = [];
+    const visit = (left, right, currentPath) => {
+        if (mismatches.length >= maxPaths) {
+            return;
+        }
+        const normalizedLeft = normalizePropertyAwareEqualityValue(left);
+        const normalizedRight = normalizePropertyAwareEqualityValue(right);
+        if (isEqual(normalizedLeft, normalizedRight)) {
+            return;
+        }
+        if (Array.isArray(normalizedLeft) && Array.isArray(normalizedRight)) {
+            if (normalizedLeft.length !== normalizedRight.length) {
+                mismatches.push(currentPath || '(root)');
+                return;
+            }
+            normalizedLeft.forEach((item, index) => {
+                visit(item, normalizedRight[index], currentPath ? `${currentPath}.${index}` : String(index));
+            });
+            return;
+        }
+        if (isRecord(normalizedLeft) && isRecord(normalizedRight)) {
+            const keys = new Set([...Object.keys(normalizedLeft), ...Object.keys(normalizedRight)]);
+            for (const key of keys) {
+                visit(normalizedLeft[key], normalizedRight[key], currentPath ? `${currentPath}.${key}` : key);
+                if (mismatches.length >= maxPaths) {
+                    return;
+                }
+            }
+            return;
+        }
+        mismatches.push(currentPath || '(root)');
+    };
+    visit(a, b, path);
+    return mismatches;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "4.1.0-beta.4",
+  "version": "4.1.0-beta.5",
   "license": "MIT",
   "publishConfig": {
     "access": "public"