vue2-excel-grid 1.7.2 → 2.0.0

package/src/utils/dataHash.js

@@ -0,0 +1,139 @@
+// Content-hashing for localSyncKey's version dedup: two saves of the exact same
+// row data (regardless of object key insertion order) must produce the same hash,
+// so ExcelGrid.vue's flush-on-hide logic can tell "this is identical to an
+// existing local version" from "this is new" without deep-comparing full row
+// arrays pairwise against every stored version.
+//
+// The worker below is intentionally NOT built on this project's existing
+// workerFactory.js/.webpack.js + worker-loader pattern (used for Excel import/
+// export) — that pattern only produces a real Worker inside this repo's own
+// `npm run demo` (vue.config.js aliases workerFactory -> workerFactory.webpack.js
+// and registers worker-loader for *.worker.js). Rollup has no such plugin, so the
+// published npm package's workerFactory.js always returns null — host projects
+// that `npm install` this library never get a real worker for import/export,
+// only the synchronous main-thread fallback. That's an acceptable trade-off for
+// import/export (occasional, user-initiated), but would defeat the point here,
+// where "checked via a Web Worker" is meant to keep the main thread responsive at
+// the exact moment the page may be hiding/unloading.
+//
+// Instead, createDataHashWorker() builds a worker from an inline Blob URL. This
+// requires no bundler-specific loader or alias, so it works unmodified in Rollup
+// UMD/ESM, webpack, Vite, or a plain <script> tag — i.e. it actually reaches
+// consumers of the published package, not just this repo's own demo.
+
+// Deterministic JSON-ish serialization: object keys are sorted, so two row
+// arrays with identical values but differently-ordered keys still hash the same.
+export function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(stableStringify).join(',') + ']'
+  }
+  var keys = Object.keys(value).sort()
+  return '{' + keys.map(function (k) {
+    return JSON.stringify(k) + ':' + stableStringify(value[k])
+  }).join(',') + '}'
+}
+
+// djb2 — small, fast, non-cryptographic string hash. Collision-safety needs here
+// are trivial (dedup within one localSyncKey's <= localSyncMaxVersions entries,
+// not a security boundary), so this is deliberately simple rather than a real
+// cryptographic hash.
+export function djb2(str) {
+  var hash = 5381
+  for (var i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0 // hash*33 + c
+  }
+  return (hash >>> 0).toString(16) // unsigned hex — stable, compact, easy to store/compare
+}
+
+// Synchronous fallback used when no Worker is available (createDataHashWorker()
+// returned null — old browsers, some privacy modes, and jsdom under Jest).
+export function hashRows(data) {
+  return djb2(stableStringify(data))
+}
+
+// The worker's ENTIRE program, deliberately self-contained in one function rather
+// than composed from calls to stableStringify/djb2 above, even though the logic
+// is identical. Function.prototype.toString() only reflects a function's OWN
+// source text — if this called out to the exported helpers by reference, a
+// minifier (terser runs on the UMD build, see rollup.config.js) could rename or
+// inline those bindings independently, with no guarantee the extracted text of
+// THIS function still resolves those names correctly once dropped into a
+// worker's separate global scope. Keeping the whole worker program in one
+// function sidesteps that: whatever a minifier does to it, it does consistently
+// to the one function as a unit, since a minifier can't break its own output.
+//
+// This IS a duplicate of stableStringify/djb2/hashRows above. Keep both copies in
+// sync if the hashing algorithm ever changes — tests/unit/dataHash.spec.js checks
+// them against each other for exactly this reason.
+function workerProgram() {
+  function stableStringify(value) {
+    if (value === null || typeof value !== 'object') return JSON.stringify(value)
+    if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']'
+    var keys = Object.keys(value).sort()
+    return '{' + keys.map(function (k) {
+      return JSON.stringify(k) + ':' + stableStringify(value[k])
+    }).join(',') + '}'
+  }
+  function djb2(str) {
+    var hash = 5381
+    for (var i = 0; i < str.length; i++) {
+      hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0
+    }
+    return (hash >>> 0).toString(16)
+  }
+  self.onmessage = function (e) {
+    self.postMessage({ hash: djb2(stableStringify(e.data.data)) })
+  }
+}
+
+// Returns a ready-to-use Worker, or null if this environment can't support one.
+// Callers must fall back to hashRows() on the main thread when this returns null.
+export function createDataHashWorker() {
+  if (
+    typeof Worker === 'undefined' ||
+    typeof Blob === 'undefined' ||
+    typeof URL === 'undefined' ||
+    !URL.createObjectURL
+  ) {
+    return null
+  }
+  try {
+    var src = '(' + workerProgram.toString() + ')();'
+    var blob = new Blob([src], { type: 'application/javascript' })
+    var url = URL.createObjectURL(blob)
+    var worker = new Worker(url)
+    var revoke = function () { URL.revokeObjectURL(url) }
+    worker.addEventListener('message', revoke, { once: true })
+    worker.addEventListener('error', revoke, { once: true })
+    return worker
+  } catch (e) {
+    return null
+  }
+}
+
+// High-level helper used by ExcelGrid.vue: hashes `data` via a Worker when one
+// can be created, transparently falling back to the synchronous hashRows() on
+// the main thread otherwise. Mirrors the one-shot "create -> use -> terminate"
+// worker pattern already used for Excel import/export (see ExcelGrid.vue's
+// _exportViaWorker) — one Promise, worker torn down exactly once, either way.
+// Deliberately never rejects: a hash is always producible one way or another,
+// so callers don't need error-handling for this specific step.
+export function hashRowsAsync(data) {
+  var worker = createDataHashWorker()
+  if (!worker) return Promise.resolve(hashRows(data))
+  return new Promise(function (resolve) {
+    var done = false
+    var finish = function (hash) {
+      if (done) return
+      done = true
+      worker.terminate()
+      resolve(hash)
+    }
+    worker.onmessage = function (e) { finish(e.data.hash) }
+    worker.onerror = function () { finish(hashRows(data)) } // worker failed — fall back, never reject
+    worker.postMessage({ data: data })
+  })
+}

package/src/utils/i18n.js

@@ -47,16 +47,18 @@ const messages = {
     theme:          'Theme',
     // local sync
     localSync:            'Local sync',
-    localSyncTitle:       'Local saved copy',
-    localSyncEmpty:       'No local copy saved yet',
-    localSyncSavedAt:     'Last saved',
+    localSyncAvailable:   'Local versions are available',
+    localSyncTitle:       'Local versions',
+    localSyncEmpty:       'No local versions saved yet',
     localSyncRows:        'rows',
+    localSyncTouchedAt:   'Reconfirmed',
+    localSyncLoading:     'Loading…',
     localSyncSave:        'Save',
-    localSyncSaveHint:    'Save the current table into the local copy',
+    localSyncSaveHint:    'Save the current table as a new local version',
     localSyncRestore:     'Restore',
-    localSyncRestoreHint: 'Load the local copy back into the table',
+    localSyncRestoreHint: 'Restore the selected local version into the table',
     localSyncClear:       'Delete',
-    localSyncConfirmClear: 'Delete this local copy?',
+    localSyncConfirmClear: 'Delete this local version?',
     localSyncConfirmYes:  'Yes, delete',
     localSyncConfirmNo:   'Cancel',
     localSyncClose:       'Close',
@@ -118,16 +120,18 @@ const messages = {
     theme:          'Тема',
     // local sync
     localSync:            'Локальная синхронизация',
-    localSyncTitle:       'Локально сохранённая копия',
-    localSyncEmpty:       'Локальная копия пока не сохранена',
-    localSyncSavedAt:     'Последнее сохранение',
+    localSyncAvailable:   'Есть локальные версии',
+    localSyncTitle:       'Локальные версии',
+    localSyncEmpty:       'Локальные версии пока не сохранены',
     localSyncRows:        'строк',
+    localSyncTouchedAt:   'Подтверждено',
+    localSyncLoading:     'Загрузка…',
     localSyncSave:        'Сохранить',
-    localSyncSaveHint:    'Сохранить текущую таблицу в локальную копию',
+    localSyncSaveHint:    'Сохранить текущую таблицу как новую локальную версию',
     localSyncRestore:     'Восстановить',
-    localSyncRestoreHint: 'Загрузить локальную копию обратно в таблицу',
+    localSyncRestoreHint: 'Восстановить выбранную локальную версию в таблицу',
     localSyncClear:       'Удалить',
-    localSyncConfirmClear: 'Удалить эту локальную копию?',
+    localSyncConfirmClear: 'Удалить эту локальную версию?',
     localSyncConfirmYes:  'Да, удалить',
     localSyncConfirmNo:   'Отмена',
     localSyncClose:       'Закрыть',
@@ -189,16 +193,18 @@ const messages = {
     theme:          'Mavzu',
     // local sync
     localSync:            'Lokal sinxronlash',
-    localSyncTitle:       'Lokal saqlangan nusxa',
-    localSyncEmpty:       'Hali lokal saqlangan nusxa yo\'q',
-    localSyncSavedAt:     'Oxirgi saqlangan',
+    localSyncAvailable:   'Lokal versiyalar mavjud',
+    localSyncTitle:       'Lokal versiyalar',
+    localSyncEmpty:       'Hali lokal versiya saqlanmagan',
     localSyncRows:        'qator',
+    localSyncTouchedAt:   'Tasdiqlangan',
+    localSyncLoading:     'Yuklanmoqda…',
     localSyncSave:        'Saqlash',
-    localSyncSaveHint:    'Joriy jadvalni lokal nusxaga saqlash',
+    localSyncSaveHint:    'Joriy jadvalni yangi lokal versiya sifatida saqlash',
     localSyncRestore:     'Tiklash',
-    localSyncRestoreHint: 'Lokal nusxani jadvalga qaytarish',
+    localSyncRestoreHint: 'Tanlangan lokal versiyani jadvalga qaytarish',
     localSyncClear:       'O\'chirish',
-    localSyncConfirmClear: 'Bu lokal nusxa o\'chirilsinmi?',
+    localSyncConfirmClear: 'Bu lokal versiya o\'chirilsinmi?',
     localSyncConfirmYes:  'Ha, o\'chirish',
     localSyncConfirmNo:   'Bekor qilish',
     localSyncClose:       'Yopish',
@@ -260,16 +266,18 @@ const messages = {
     theme:          'Мавзу',
     // local sync
     localSync:            'Лакал синхронлаш',
-    localSyncTitle:       'Лакал сақланган нусха',
-    localSyncEmpty:       'Ҳали лакал сақланган нусха йўқ',
-    localSyncSavedAt:     'Охирги сақланган',
+    localSyncAvailable:   'Локал версиялар мавжуд',
+    localSyncTitle:       'Локал версиялар',
+    localSyncEmpty:       'Ҳали локал версия сақланмаган',
     localSyncRows:        'қатор',
+    localSyncTouchedAt:   'Тасдиқланган',
+    localSyncLoading:     'Юкланмоқда…',
     localSyncSave:        'Сақлаш',
-    localSyncSaveHint:    'Жорий жадвални лакал нусхага сақлаш',
+    localSyncSaveHint:    'Жорий жадвални янги локал версия сифатида сақлаш',
     localSyncRestore:     'Тиклаш',
-    localSyncRestoreHint: 'Лакал нусхани жадвалга қайтариш',
+    localSyncRestoreHint: 'Танланган локал версияни жадвалга қайтариш',
     localSyncClear:       'Ўчириш',
-    localSyncConfirmClear: 'Бу лакал нусха ўчирилсинми?',
+    localSyncConfirmClear: 'Бу локал версия ўчирилсинми?',
     localSyncConfirmYes:  'Ҳа, ўчириш',
     localSyncConfirmNo:   'Бекор қилиш',
     localSyncClose:       'Ёпиш',

package/src/utils/idbStore.js

@@ -1,13 +1,40 @@
 // Minimal Promise-based wrapper over the native indexedDB API — used by
-// ExcelGrid.vue's localSyncKey feature to autosave/restore the v-model
-// `data` array locally in the browser. One database, one object store,
-// records keyed by the host-supplied localSyncKey string. No third-party
-// dependency (e.g. idb/localforage) — the API surface needed here (put/get/
-// delete by key) is small enough that a raw wrapper is simpler than a new
-// dependency, matching this project's otherwise minimal dependency list.
+// ExcelGrid.vue's localSyncKey feature to keep MULTIPLE local versions of the
+// v-model `data` array, saved on page-hide (not per-edit — see
+// ExcelGrid.vue's _flushLocalVersionOnHide()). No third-party dependency (e.g.
+// idb/localforage) — the API surface needed here is small enough that a raw
+// wrapper is simpler than a new dependency, matching this project's otherwise
+// minimal dependency list.
+//
+// Schema (v2 — breaking change from v1's single-snapshot-per-key 'snapshots'
+// store, which is dropped on upgrade with no migration):
+//   DB 'vue2-excel-grid-sync', store 'versions', keyPath 'id', plus an index
+//   'by_localSyncKey' so all versions for one key can be listed without a full
+//   table scan. Record shape:
+//     { id, localSyncKey, data, hash, createdAt, updatedAt }
+//   `id` is `${localSyncKey}-YYYY-MM-DD-HHmmss`, minted once when a version is
+//   first created. `hash` is a content hash (src/utils/dataHash.js) used to
+//   detect "this is the same content as an existing version" — in that case
+//   the existing record's `updatedAt` is bumped instead of creating a new id
+//   ("ustiga yoziladi, alohida versiya qilinmaydi").
 const DB_NAME = 'vue2-excel-grid-sync'
-const STORE_NAME = 'snapshots'
-const DB_VERSION = 1
+const STORE_NAME = 'versions'
+const OLD_STORE_NAME = 'snapshots' // v1 — dropped on upgrade, not migrated
+const INDEX_BY_KEY = 'by_localSyncKey'
+const DB_VERSION = 2
+
+function pad2(n) { return n < 10 ? '0' + n : '' + n }
+
+// `${localSyncKey}-YYYY-MM-DD-HHmmss`, minute/second precision so two flushes
+// within the same second (rare, but possible from multiple rapid tab-hides)
+// collide on id rather than silently sorting oddly — callers treat that as
+// "overwrite this version", which is correct: it's still the same visit.
+export function formatVersionId(localSyncKey, date) {
+  var d = date || new Date()
+  return localSyncKey + '-' +
+    d.getFullYear() + '-' + pad2(d.getMonth() + 1) + '-' + pad2(d.getDate()) + '-' +
+    pad2(d.getHours()) + pad2(d.getMinutes()) + pad2(d.getSeconds())
+}
 
 function openDb() {
   return new Promise((resolve, reject) => {
@@ -18,8 +45,12 @@ function openDb() {
     const req = indexedDB.open(DB_NAME, DB_VERSION)
     req.onupgradeneeded = () => {
       const db = req.result
+      if (db.objectStoreNames.contains(OLD_STORE_NAME)) {
+        db.deleteObjectStore(OLD_STORE_NAME) // v1 -> v2: breaking, no migration
+      }
       if (!db.objectStoreNames.contains(STORE_NAME)) {
-        db.createObjectStore(STORE_NAME, { keyPath: 'key' })
+        const store = db.createObjectStore(STORE_NAME, { keyPath: 'id' })
+        store.createIndex(INDEX_BY_KEY, 'localSyncKey', { unique: false })
       }
     }
     req.onsuccess = () => resolve(req.result)
@@ -27,33 +58,104 @@ function openDb() {
   })
 }
 
-export async function saveSnapshot(key, data) {
+export async function listVersions(localSyncKey) {
   const db = await openDb()
   return new Promise((resolve, reject) => {
-    const tx = db.transaction(STORE_NAME, 'readwrite')
-    const updatedAt = Date.now()
-    tx.objectStore(STORE_NAME).put({ key, data, updatedAt })
-    tx.oncomplete = () => { db.close(); resolve({ key, updatedAt }) }
-    tx.onerror = () => { db.close(); reject(tx.error) }
+    const tx = db.transaction(STORE_NAME, 'readonly')
+    const idx = tx.objectStore(STORE_NAME).index(INDEX_BY_KEY)
+    // getAll() accepts a bare key directly (no IDBKeyRange needed) — keeps this
+    // module (and its test mock) free of a dependency on the IDBKeyRange global.
+    const req = idx.getAll(localSyncKey)
+    req.onsuccess = () => {
+      db.close()
+      const rows = req.result || []
+      rows.sort((a, b) => b.createdAt - a.createdAt) // newest first
+      resolve(rows)
+    }
+    req.onerror = () => { db.close(); reject(req.error) }
   })
 }
 
-export async function loadSnapshot(key) {
+export async function getVersion(id) {
   const db = await openDb()
   return new Promise((resolve, reject) => {
     const tx = db.transaction(STORE_NAME, 'readonly')
-    const req = tx.objectStore(STORE_NAME).get(key)
+    const req = tx.objectStore(STORE_NAME).get(id)
     req.onsuccess = () => { db.close(); resolve(req.result || null) }
     req.onerror = () => { db.close(); reject(req.error) }
   })
 }
 
-export async function deleteSnapshot(key) {
-  const db = await openDb()
+export async function findVersionByHash(localSyncKey, hash) {
+  const versions = await listVersions(localSyncKey)
+  return versions.find(v => v.hash === hash) || null
+}
+
+function putVersion(db, record) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, 'readwrite')
+    tx.objectStore(STORE_NAME).put(record)
+    tx.oncomplete = () => { db.close(); resolve(record) }
+    tx.onerror = () => { db.close(); reject(tx.error) }
+  })
+}
+
+function deleteVersionOnDb(db, id) {
   return new Promise((resolve, reject) => {
     const tx = db.transaction(STORE_NAME, 'readwrite')
-    tx.objectStore(STORE_NAME).delete(key)
+    tx.objectStore(STORE_NAME).delete(id)
     tx.oncomplete = () => { db.close(); resolve() }
     tx.onerror = () => { db.close(); reject(tx.error) }
   })
 }
+
+export async function deleteVersion(id) {
+  const db = await openDb()
+  return deleteVersionOnDb(db, id)
+}
+
+// The core write path: given a content hash already computed for `data`
+// (src/utils/dataHash.js — main thread or Worker, ExcelGrid.vue's concern, not
+// this module's), either touches an existing version with the same hash
+// (updatedAt bump only — "ustiga yoziladi") or creates a brand-new one and
+// evicts the oldest version(s) past `maxVersions` (FIFO). Centralized here
+// rather than in ExcelGrid.vue so the dedup+eviction policy lives with the
+// storage layer it operates on.
+export async function saveOrTouchVersion(localSyncKey, data, hash, maxVersions) {
+  const existing = await findVersionByHash(localSyncKey, hash)
+  const now = Date.now()
+
+  if (existing) {
+    const db = await openDb()
+    const touched = { ...existing, updatedAt: now }
+    await putVersion(db, touched)
+    return { version: touched, overwritten: true }
+  }
+
+  // Disambiguate the rare case of two DIFFERENT contents saved within the
+  // same wall-clock second (the id's precision) — not reachable from real
+  // page-hide events in practice, but possible via rapid saveLocalVersionNow()
+  // calls. Without this, the second save's id would collide with the first
+  // and silently overwrite it via put() — the same-hash "touch" case is
+  // already handled above; this is specifically the different-hash case.
+  const existingIds = new Set((await listVersions(localSyncKey)).map(v => v.id))
+  let id = formatVersionId(localSyncKey, new Date(now))
+  for (let suffix = 2; existingIds.has(id); suffix++) {
+    id = formatVersionId(localSyncKey, new Date(now)) + '-' + suffix
+  }
+
+  const record = { id, localSyncKey, data, hash, createdAt: now, updatedAt: now }
+  const db = await openDb()
+  await putVersion(db, record)
+
+  if (maxVersions > 0) {
+    const versions = await listVersions(localSyncKey) // newest first
+    const excess = versions.slice(maxVersions)
+    for (const stale of excess) {
+      const staleDb = await openDb()
+      await deleteVersionOnDb(staleDb, stale.id)
+    }
+  }
+
+  return { version: record, overwritten: false }
+}