hvp-shared 3.3.3 → 3.5.0

package/dist/utils/sync-field.helpers.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValue = getValue;
+exports.getQvetValue = getQvetValue;
+exports.hasPending = hasPending;
+exports.isDirty = isDirty;
+exports.setPending = setPending;
+exports.clearPending = clearPending;
+exports.confirmSync = confirmSync;
+exports.applySyncPreservePending = applySyncPreservePending;
+/**
+ * Get the effective value (pending if exists, otherwise current)
+ *
+ * @example
+ * getValue({ value: "old", pending: "new" }) // "new"
+ * getValue({ value: "old", pending: undefined }) // "old"
+ */
+function getValue(field) {
+    return field.pending ?? field.value;
+}
+/**
+ * Get the external system value (always the synced one, ignores pending)
+ *
+ * @example
+ * getQvetValue({ value: "old", pending: "new" }) // "old"
+ */
+function getQvetValue(field) {
+    return field.value;
+}
+/**
+ * Check if field has a pending change
+ *
+ * @example
+ * hasPending({ value: "old", pending: "new" }) // true
+ * hasPending({ value: "old", pending: undefined }) // false
+ */
+function hasPending(field) {
+    return field.pending !== undefined && field.pending !== null;
+}
+/**
+ * Check if pending value differs from current value
+ *
+ * @example
+ * isDirty({ value: "old", pending: "new" }) // true
+ * isDirty({ value: "old", pending: "old" }) // false (same value)
+ * isDirty({ value: "old", pending: undefined }) // false
+ */
+function isDirty(field) {
+    return hasPending(field) && field.pending !== field.value;
+}
+/**
+ * Set a pending value. If newValue equals current value, clears pending instead.
+ *
+ * @example
+ * setPending({ value: "old", pending: undefined }, "new")
+ * // { value: "old", pending: "new" }
+ *
+ * setPending({ value: "old", pending: undefined }, "old")
+ * // { value: "old", pending: undefined } - no change needed
+ */
+function setPending(field, newValue) {
+    if (newValue === field.value) {
+        return { value: field.value, pending: undefined };
+    }
+    return { value: field.value, pending: newValue };
+}
+/**
+ * Clear pending (revert to external system value)
+ *
+ * @example
+ * clearPending({ value: "old", pending: "new" })
+ * // { value: "old", pending: undefined }
+ */
+function clearPending(field) {
+    return { value: field.value, pending: undefined };
+}
+/**
+ * Confirm sync from external system.
+ * Updates the value to the new external value and clears pending.
+ *
+ * @example
+ * // External system confirmed our change
+ * confirmSync({ value: "old", pending: "new" }, "new")
+ * // { value: "new", pending: undefined }
+ *
+ * // External system has different value
+ * confirmSync({ value: "old", pending: undefined }, "updated")
+ * // { value: "updated", pending: undefined }
+ */
+function confirmSync(field, externalValue) {
+    return { value: externalValue, pending: undefined };
+}
+/**
+ * Apply sync from external system, preserving pending if it differs from new value.
+ * Use this when you want to keep local changes during a sync.
+ *
+ * @example
+ * // We have pending, external hasn't changed yet
+ * applySyncPreservePending({ value: "old", pending: "new" }, "old")
+ * // { value: "old", pending: "new" } - pending preserved
+ *
+ * // External confirmed our change
+ * applySyncPreservePending({ value: "old", pending: "new" }, "new")
+ * // { value: "new", pending: undefined } - pending cleared
+ *
+ * // External changed to something else (conflict scenario)
+ * applySyncPreservePending({ value: "old", pending: "new" }, "other")
+ * // { value: "other", pending: "new" } - pending preserved, value updated
+ */
+function applySyncPreservePending(field, externalValue) {
+    // If pending equals new external value, the change was confirmed
+    if (field.pending === externalValue) {
+        return { value: externalValue, pending: undefined };
+    }
+    // Otherwise, update value but preserve pending
+    return { value: externalValue, pending: field.pending };
+}

package/dist/utils/sync-field.helpers.test.d.ts

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

package/dist/utils/sync-field.helpers.test.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const sync_field_types_1 = require("../types/sync-field.types");
+const sync_field_helpers_1 = require("./sync-field.helpers");
+describe('SyncField Helpers', () => {
+    describe('createSyncField', () => {
+        it('should create a clean sync field', () => {
+            const field = (0, sync_field_types_1.createSyncField)('hello');
+            expect(field).toEqual({ value: 'hello', pending: undefined });
+        });
+        it('should work with numbers', () => {
+            const field = (0, sync_field_types_1.createSyncField)(42);
+            expect(field).toEqual({ value: 42, pending: undefined });
+        });
+    });
+    describe('getValue', () => {
+        it('should return value when no pending', () => {
+            const field = { value: 'original', pending: undefined };
+            expect((0, sync_field_helpers_1.getValue)(field)).toBe('original');
+        });
+        it('should return pending when present', () => {
+            const field = { value: 'original', pending: 'modified' };
+            expect((0, sync_field_helpers_1.getValue)(field)).toBe('modified');
+        });
+        it('should work with numbers', () => {
+            const field = { value: 10, pending: 20 };
+            expect((0, sync_field_helpers_1.getValue)(field)).toBe(20);
+        });
+    });
+    describe('getQvetValue', () => {
+        it('should return value regardless of pending', () => {
+            const field = { value: 'original', pending: 'modified' };
+            expect((0, sync_field_helpers_1.getQvetValue)(field)).toBe('original');
+        });
+        it('should return value when no pending', () => {
+            const field = { value: 'original', pending: undefined };
+            expect((0, sync_field_helpers_1.getQvetValue)(field)).toBe('original');
+        });
+    });
+    describe('hasPending', () => {
+        it('should return false when pending is undefined', () => {
+            const field = { value: 'original', pending: undefined };
+            expect((0, sync_field_helpers_1.hasPending)(field)).toBe(false);
+        });
+        it('should return true when pending has value', () => {
+            const field = { value: 'original', pending: 'modified' };
+            expect((0, sync_field_helpers_1.hasPending)(field)).toBe(true);
+        });
+        it('should return false when pending is null', () => {
+            const field = { value: 'original', pending: null };
+            expect((0, sync_field_helpers_1.hasPending)(field)).toBe(false);
+        });
+        it('should return true for falsy pending values like 0', () => {
+            const field = { value: 10, pending: 0 };
+            expect((0, sync_field_helpers_1.hasPending)(field)).toBe(true);
+        });
+        it('should return true for empty string pending', () => {
+            const field = { value: 'original', pending: '' };
+            expect((0, sync_field_helpers_1.hasPending)(field)).toBe(true);
+        });
+    });
+    describe('isDirty', () => {
+        it('should return false when no pending', () => {
+            const field = { value: 'original', pending: undefined };
+            expect((0, sync_field_helpers_1.isDirty)(field)).toBe(false);
+        });
+        it('should return true when pending differs from value', () => {
+            const field = { value: 'original', pending: 'modified' };
+            expect((0, sync_field_helpers_1.isDirty)(field)).toBe(true);
+        });
+        it('should return false when pending equals value', () => {
+            const field = { value: 'same', pending: 'same' };
+            expect((0, sync_field_helpers_1.isDirty)(field)).toBe(false);
+        });
+    });
+    describe('setPending', () => {
+        it('should set pending when value differs', () => {
+            const field = { value: 'original', pending: undefined };
+            const result = (0, sync_field_helpers_1.setPending)(field, 'modified');
+            expect(result).toEqual({ value: 'original', pending: 'modified' });
+        });
+        it('should clear pending when new value equals current value', () => {
+            const field = { value: 'original', pending: 'modified' };
+            const result = (0, sync_field_helpers_1.setPending)(field, 'original');
+            expect(result).toEqual({ value: 'original', pending: undefined });
+        });
+        it('should replace existing pending', () => {
+            const field = { value: 'original', pending: 'first' };
+            const result = (0, sync_field_helpers_1.setPending)(field, 'second');
+            expect(result).toEqual({ value: 'original', pending: 'second' });
+        });
+        it('should work with numbers', () => {
+            const field = { value: 10, pending: undefined };
+            const result = (0, sync_field_helpers_1.setPending)(field, 20);
+            expect(result).toEqual({ value: 10, pending: 20 });
+        });
+    });
+    describe('clearPending', () => {
+        it('should remove pending', () => {
+            const field = { value: 'original', pending: 'modified' };
+            const result = (0, sync_field_helpers_1.clearPending)(field);
+            expect(result).toEqual({ value: 'original', pending: undefined });
+        });
+        it('should work when already clean', () => {
+            const field = { value: 'original', pending: undefined };
+            const result = (0, sync_field_helpers_1.clearPending)(field);
+            expect(result).toEqual({ value: 'original', pending: undefined });
+        });
+    });
+    describe('confirmSync', () => {
+        it('should update value and clear pending', () => {
+            const field = { value: 'old', pending: 'new' };
+            const result = (0, sync_field_helpers_1.confirmSync)(field, 'new');
+            expect(result).toEqual({ value: 'new', pending: undefined });
+        });
+        it('should update to external value even if different from pending', () => {
+            const field = { value: 'old', pending: 'expected' };
+            const result = (0, sync_field_helpers_1.confirmSync)(field, 'external');
+            expect(result).toEqual({ value: 'external', pending: undefined });
+        });
+        it('should work when no pending', () => {
+            const field = { value: 'old', pending: undefined };
+            const result = (0, sync_field_helpers_1.confirmSync)(field, 'updated');
+            expect(result).toEqual({ value: 'updated', pending: undefined });
+        });
+    });
+    describe('applySyncPreservePending', () => {
+        it('should preserve pending when external unchanged', () => {
+            const field = { value: 'old', pending: 'new' };
+            const result = (0, sync_field_helpers_1.applySyncPreservePending)(field, 'old');
+            expect(result).toEqual({ value: 'old', pending: 'new' });
+        });
+        it('should clear pending when external confirms our change', () => {
+            const field = { value: 'old', pending: 'new' };
+            const result = (0, sync_field_helpers_1.applySyncPreservePending)(field, 'new');
+            expect(result).toEqual({ value: 'new', pending: undefined });
+        });
+        it('should preserve pending and update value on conflict', () => {
+            const field = { value: 'old', pending: 'our-change' };
+            const result = (0, sync_field_helpers_1.applySyncPreservePending)(field, 'external-change');
+            expect(result).toEqual({ value: 'external-change', pending: 'our-change' });
+        });
+        it('should update value when no pending', () => {
+            const field = { value: 'old', pending: undefined };
+            const result = (0, sync_field_helpers_1.applySyncPreservePending)(field, 'updated');
+            expect(result).toEqual({ value: 'updated', pending: undefined });
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hvp-shared",
-  "version": "3.3.3",
+  "version": "3.5.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",