@trackunit/shared-utils 1.16.10 → 1.16.11

package/index.cjs.js

@@ -918,6 +918,13 @@ const validateOrSalvage = ({ rawValue, schema, defaultState, key, onValidationFa
  * next write, permanently hiding the corruption. Scope it only to keys that are provably
  * never written by anything other than a plain string.
  *
+ * A legacy raw string that also happens to be valid JSON (e.g. an all-digit username, or the
+ * literal text "true"/"false"/"null") parses successfully but as the wrong type (a number,
+ * boolean, or null instead of a string) — `JSON.parse` alone can't tell "legacy plain string"
+ * apart from "genuinely structured data" here. When `legacyRawString` is set and that first
+ * validation attempt fails, this retries validation against the original raw string before
+ * falling back to `defaultState`, so a permissive schema still recovers the literal text.
+ *
  * When `migration` is provided, detects versioned envelopes, runs the
  * migration pipeline, and validates the migrated result. Non-versioned consumers are
  * unaffected — the migration path is fully opt-in.
@@ -969,6 +976,19 @@ const readFromStorage = ({ storage, key, defaultState, schema, migration, legacy
         return defaultState;
     }
     if (version === undefined) {
+        if (legacyRawString) {
+            const deserializedResult = schema.safeParse(deserialized);
+            if (deserializedResult.success) {
+                return deserializedResult.data;
+            }
+            // The deserialized value parsed as JSON but didn't match the schema (e.g. an all-digit
+            // legacy string became a number) — retry against the original raw string before
+            // falling back further.
+            const rawResult = schema.safeParse(raw);
+            if (rawResult.success) {
+                return rawResult.data;
+            }
+        }
         return validateOrSalvage({
             rawValue: deserialized,
             schema,

package/index.esm.js

@@ -916,6 +916,13 @@ const validateOrSalvage = ({ rawValue, schema, defaultState, key, onValidationFa
  * next write, permanently hiding the corruption. Scope it only to keys that are provably
  * never written by anything other than a plain string.
  *
+ * A legacy raw string that also happens to be valid JSON (e.g. an all-digit username, or the
+ * literal text "true"/"false"/"null") parses successfully but as the wrong type (a number,
+ * boolean, or null instead of a string) — `JSON.parse` alone can't tell "legacy plain string"
+ * apart from "genuinely structured data" here. When `legacyRawString` is set and that first
+ * validation attempt fails, this retries validation against the original raw string before
+ * falling back to `defaultState`, so a permissive schema still recovers the literal text.
+ *
  * When `migration` is provided, detects versioned envelopes, runs the
  * migration pipeline, and validates the migrated result. Non-versioned consumers are
  * unaffected — the migration path is fully opt-in.
@@ -967,6 +974,19 @@ const readFromStorage = ({ storage, key, defaultState, schema, migration, legacy
         return defaultState;
     }
     if (version === undefined) {
+        if (legacyRawString) {
+            const deserializedResult = schema.safeParse(deserialized);
+            if (deserializedResult.success) {
+                return deserializedResult.data;
+            }
+            // The deserialized value parsed as JSON but didn't match the schema (e.g. an all-digit
+            // legacy string became a number) — retry against the original raw string before
+            // falling back further.
+            const rawResult = schema.safeParse(raw);
+            if (rawResult.success) {
+                return rawResult.data;
+            }
+        }
         return validateOrSalvage({
             rawValue: deserialized,
             schema,

package/migrations/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../../libs/shared/utils/migrations/entry.ts"],"names":[],"mappings":"","sourcesContent":["export {};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/shared-utils",
-  "version": "1.16.10",
+  "version": "1.16.11",
   "repository": "https://github.com/Trackunit/manager",
   "engines": {
     "node": ">=24.x"

package/src/localStorage/readFromStorage.d.ts

@@ -24,6 +24,13 @@ import type { MigrationConfig, WebStorageCallbacks } from "./types";
  * next write, permanently hiding the corruption. Scope it only to keys that are provably
  * never written by anything other than a plain string.
  *
+ * A legacy raw string that also happens to be valid JSON (e.g. an all-digit username, or the
+ * literal text "true"/"false"/"null") parses successfully but as the wrong type (a number,
+ * boolean, or null instead of a string) — `JSON.parse` alone can't tell "legacy plain string"
+ * apart from "genuinely structured data" here. When `legacyRawString` is set and that first
+ * validation attempt fails, this retries validation against the original raw string before
+ * falling back to `defaultState`, so a permissive schema still recovers the literal text.
+ *
  * When `migration` is provided, detects versioned envelopes, runs the
  * migration pipeline, and validates the migrated result. Non-versioned consumers are
  * unaffected — the migration path is fully opt-in.