@trackunit/shared-utils 1.16.4 → 1.16.5

package/index.cjs.js

@@ -1,6 +1,8 @@
 'use strict';
 
+var esToolkit = require('es-toolkit');
 var zod = require('zod');
+var superjson = require('superjson');
 var uuid = require('uuid');
 
 /**
@@ -549,7 +551,7 @@ const insertToUUID = (arr, position, value) => [
  * @param input A string.
  * @param maxLength The maximum length of the string that it should pad for.
  */
-const zeroPadToUUIDLength = (input, maxLength) => input.length < maxLength ? zeroPadToUUIDLength("0" + input, maxLength) : input;
+const zeroPadToUUIDLength = (input, maxLength) => input.length < maxLength ? zeroPadToUUIDLength(`0${input}`, maxLength) : input;
 /**
  * A helper function that converts any value into a UUID.
  *
@@ -705,6 +707,424 @@ const fetchImageAsBase64 = async (url) => {
     });
 };
 
+/**
+ * Runs a sequential migration pipeline on the provided data, applying
+ * each migration whose version is in the range (fromVersion, toVersion].
+ *
+ * Throws if the filtered migrations have non-contiguous versions (gaps).
+ */
+const runMigrations = ({ data, fromVersion, toVersion, migrations, }) => {
+    if (toVersion <= fromVersion) {
+        return data;
+    }
+    const applicable = migrations
+        .toSorted((a, b) => a.version - b.version)
+        .filter(m => m.version > fromVersion && m.version <= toVersion);
+    if (applicable.length === 0) {
+        return data;
+    }
+    for (let i = 1; i < applicable.length; i++) {
+        const prev = applicable[i - 1];
+        const curr = applicable[i];
+        if (prev && curr && curr.version !== prev.version + 1) {
+            throw new Error(`Migration gap detected: found version ${prev.version} and ${curr.version} but no migration for version ${prev.version + 1}.`);
+        }
+    }
+    return applicable.reduce((acc, migration) => migration.migrate(acc), data);
+};
+
+/**
+ * Recursively builds a salvaging schema from a ZodObject by injecting `.catch(defaultValue[key])`
+ * for each field. This means invalid field values fall back to defaultState values rather than
+ * failing the entire parse.
+ *
+ * Unwraps ZodOptional, ZodNullable, and ZodDefault to reach the inner schema.
+ * ZodCatch is intentionally NOT unwrapped — consumer-defined catches take precedence.
+ * Non-ZodObject schemas (unions, discriminated unions, refinements, etc.) are returned unchanged
+ * so they behave as atomic units.
+ */
+function buildSalvagingSchema(schema, defaultValue) {
+    if (schema instanceof zod.z.ZodOptional) {
+        return buildSalvagingSchema(schema.unwrap(), defaultValue).optional();
+    }
+    if (schema instanceof zod.z.ZodNullable) {
+        return buildSalvagingSchema(schema.unwrap(), defaultValue).nullable();
+    }
+    if (schema instanceof zod.z.ZodDefault) {
+        return buildSalvagingSchema(schema._def.innerType, defaultValue);
+    }
+    if (!(schema instanceof zod.z.ZodObject)) {
+        return schema;
+    }
+    const defaultRecordResult = zod.z.record(zod.z.string(), zod.z.unknown()).safeParse(defaultValue);
+    if (!defaultRecordResult.success) {
+        return schema;
+    }
+    const defaultRecord = defaultRecordResult.data;
+    const salvagingShape = {};
+    for (const key of Object.keys(schema.shape)) {
+        const fieldSchema = schema.shape[key];
+        if (fieldSchema === undefined)
+            continue;
+        const fieldDefault = defaultRecord[key];
+        salvagingShape[key] = buildSalvagingSchema(fieldSchema, fieldDefault).catch(fieldDefault);
+    }
+    return zod.z.object(salvagingShape);
+}
+/**
+ * Attempts to salvage partial state from raw data when full schema validation has failed.
+ *
+ * For ZodObject schemas, rebuilds the schema with per-field `.catch(defaultState[key])` fallbacks
+ * and reparses. Valid field values from the stored data are kept; invalid fields fall back to their
+ * corresponding values in `defaultState`. Works recursively for nested ZodObject fields.
+ *
+ * Non-object schemas (discriminated unions, unions with `.refine()`, etc.) cannot be partially
+ * salvaged and return `null`.
+ *
+ * Consumer-defined `.catch()` wrappers take precedence over the injected salvage catches, since
+ * Zod processes catches inside-out.
+ *
+ * Note: when every field is invalid, the salvaged result will be deeply equal to `defaultState`.
+ * Callers should compare the result against `defaultState` to distinguish a genuine partial
+ * salvage from a total loss where no stored data survived.
+ *
+ * @template TState - The type of the stored state.
+ * @param schema - Zod schema for validation.
+ * @param rawData - The raw deserialized value that failed validation.
+ * @param defaultState - The authoritative fallback value; used as per-field catch defaults.
+ * @returns {TState | null} The salvaged state, or `null` if salvaging is not possible or also fails.
+ */
+const salvageState = (schema, rawData, defaultState) => {
+    try {
+        const salvagingSchema = buildSalvagingSchema(schema, defaultState);
+        const intermediate = salvagingSchema.safeParse(rawData);
+        if (!intermediate.success) {
+            return null;
+        }
+        // Re-validate through the original schema to ensure correctness and get the proper TState type.
+        // By construction this should always succeed: each field value is either the valid stored value
+        // or defaultState[key], both of which satisfy the original schema.
+        const result = schema.safeParse(intermediate.data);
+        return result.success ? result.data : null;
+    }
+    catch {
+        return null;
+    }
+};
+
+/**
+ * Internal envelope used to tag superjson-serialized data in web storage.
+ *
+ * `__serializer` is a **reserved internal key** — consumer state objects must
+ * not include it as a top-level key. The double-underscore prefix is a
+ * deliberate signal that this is a private implementation detail.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+const taggedSuperjsonEnvelopeSchema = zod.z.object({
+    __serializer: zod.z.literal("superjson"),
+    json: zod.z.custom(),
+    meta: zod.z.custom().optional(),
+});
+const storageSerializer = {
+    serialize: (value) => {
+        const serialized = superjson.serialize(value);
+        return JSON.stringify({ __serializer: "superjson", ...serialized });
+    },
+    deserialize: (value) => {
+        const parsed = JSON.parse(value);
+        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
+        if (result.success) {
+            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
+        }
+        return parsed;
+    },
+};
+
+/**
+ * Internal envelope that pairs stored data with a schema version number.
+ *
+ * `__version` and `__data` are **reserved internal keys** — consumer state
+ * objects must not include them as top-level keys. The double-underscore
+ * prefix is a deliberate signal that these are private implementation details.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+const storageVersionEnvelopeSchema = zod.z
+    .object({
+    __version: zod.z.number(),
+    __data: zod.z.unknown(),
+})
+    .refine((x) => "__data" in x, {
+    message: "__data is required",
+});
+/** Wraps data and version into a versioned storage envelope. */
+const createStorageVersionEnvelope = (data, version) => ({
+    __version: version,
+    __data: data,
+});
+
+/**
+ * Validates raw data against the schema, attempting partial salvage on failure.
+ *
+ * On success: returns the parsed data.
+ * On failure with a salvageable ZodObject schema where at least one stored field
+ *   survived: returns the salvaged state and calls `onValidationSalvaged`.
+ * On failure where salvage produces a result identical to `defaultState` (i.e. every
+ *   field was invalid and caught to its default): treats this as a total failure and
+ *   calls `onValidationFailed` instead of `onValidationSalvaged`.
+ * On failure with no salvage possible: returns `defaultState` and calls `onValidationFailed`.
+ */
+const validateOrSalvage = ({ rawValue, schema, defaultState, key, onValidationFailed, onValidationSalvaged, }) => {
+    const parseResult = schema.safeParse(rawValue);
+    if (parseResult.success) {
+        return parseResult.data;
+    }
+    const salvaged = salvageState(schema, rawValue, defaultState);
+    if (salvaged !== null && !esToolkit.isEqual(salvaged, defaultState)) {
+        // eslint-disable-next-line no-console
+        console.warn(`Partially invalid data in storage key "${key}" — salvaged valid fields, reset invalid fields to defaults.`, parseResult.error);
+        onValidationSalvaged?.(parseResult.error, salvaged);
+        return salvaged;
+    }
+    // eslint-disable-next-line no-console
+    console.error(`Failed to parse and validate the state from storage key "${key}". Returning default state.`, parseResult.error);
+    onValidationFailed?.(parseResult.error);
+    return defaultState;
+};
+/**
+ * Reads and deserializes a value from web storage, validating it against the provided schema.
+ * Falls back to defaultState if the key is missing or data is corrupt.
+ *
+ * On partial validation failure for ZodObject schemas, salvages valid fields rather than
+ * resetting the entire state to `defaultState`. See `salvageState` for salvage mechanics.
+ * If the salvaged result is deeply equal to `defaultState` (i.e. every field was invalid),
+ * the salvage is considered a total loss and `onValidationFailed` is called instead of
+ * `onValidationSalvaged`.
+ *
+ * Deserialization failures (unparseable/corrupt raw data) are routed through
+ * `onValidationFailed` so consumers are always notified when stored data is unusable.
+ *
+ * `legacyRawString` is a narrow, opt-in escape hatch for keys that are known to hold a
+ * plain-text value that was never JSON-encoded in the first place (e.g. a legacy username
+ * written via `localStorage.setItem` directly, with no `JSON.stringify`). When set, a raw
+ * value that fails JSON parsing is treated as the candidate string itself rather than a
+ * hard failure, and handed to schema validation (a permissive schema like `z.string()`
+ * recovers it; a schema expecting structured data still correctly rejects it). Leave this
+ * unset for every other key — enabling it globally would let a genuinely corrupted,
+ * truncated envelope be silently accepted as a valid string and re-persisted as such on the
+ * next write, permanently hiding the corruption. Scope it only to keys that are provably
+ * never written by anything other than a plain string.
+ *
+ * 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.
+ *
+ * @template TState - The type of the stored state.
+ * @param params - Storage, key, default state, Zod schema, optional migration config, and optional callbacks.
+ * @param params.storage - The web Storage instance.
+ * @param params.key - The storage key.
+ * @param params.defaultState - Fallback value when no stored data exists or data is corrupt.
+ * @param params.schema - Zod schema to validate the deserialized data.
+ * @param params.migration - Optional migration configuration (version, steps, fromKey).
+ * @param params.legacyRawString - Opt-in recovery for keys known to hold a plain-text value
+ *   that was never JSON-encoded. See the note above the function for when (not) to use this.
+ * @param params.onValidationFailed - Called when validation fails and no salvage is possible, or when
+ *   deserialization of the raw storage value fails entirely.
+ * @param params.onValidationSalvaged - Called when validation fails but at least one stored field
+ *   was recovered (salvaged result differs from defaultState).
+ * @returns {TState} The validated or salvaged state, or defaultState.
+ */
+const readFromStorage = ({ storage, key, defaultState, schema, migration, legacyRawString, onValidationFailed, onValidationSalvaged, }) => {
+    const version = migration?.version;
+    const steps = migration?.steps;
+    const fromKey = migration?.fromKey;
+    let raw = storage.getItem(key);
+    if (raw === null && fromKey !== undefined) {
+        raw = storage.getItem(fromKey);
+    }
+    if (raw === null) {
+        return defaultState;
+    }
+    let deserialized;
+    try {
+        deserialized = storageSerializer.deserialize(raw);
+    }
+    catch (deserializationError) {
+        if (legacyRawString) {
+            return validateOrSalvage({
+                rawValue: raw,
+                schema,
+                defaultState,
+                key,
+                onValidationFailed,
+                onValidationSalvaged,
+            });
+        }
+        // eslint-disable-next-line no-console
+        console.error(`Failed to deserialize storage key "${key}". Returning default state.`, deserializationError);
+        onValidationFailed?.(deserializationError);
+        return defaultState;
+    }
+    if (version === undefined) {
+        return validateOrSalvage({
+            rawValue: deserialized,
+            schema,
+            defaultState,
+            key,
+            onValidationFailed,
+            onValidationSalvaged,
+        });
+    }
+    let storedVersion;
+    let data;
+    const envelopeResult = storageVersionEnvelopeSchema.safeParse(deserialized);
+    if (envelopeResult.success) {
+        storedVersion = envelopeResult.data.__version;
+        data = envelopeResult.data.__data;
+    }
+    else {
+        storedVersion = 0;
+        data = deserialized;
+    }
+    if (steps !== undefined && storedVersion < version) {
+        try {
+            data = runMigrations({ data, fromVersion: storedVersion, toVersion: version, migrations: steps });
+        }
+        catch (migrationError) {
+            // eslint-disable-next-line no-console
+            console.error(`Migration failed for storage key "${key}" (v${storedVersion} → v${version}). Returning default state.`, migrationError);
+            return defaultState;
+        }
+    }
+    return validateOrSalvage({ rawValue: data, schema, defaultState, key, onValidationFailed, onValidationSalvaged });
+};
+
+/**
+ * Validates the state using a Zod schema. Returns the parsed state on success,
+ * or defaultState on failure (with error logging and optional callbacks).
+ *
+ * @template TState - The type of the state.
+ * @param params - The state, schema, defaultState, and optional callbacks.
+ * @param params.state - The raw state to validate.
+ * @param params.schema - The Zod schema for validation.
+ * @param params.defaultState - The fallback value on failure.
+ * @param params.onValidationFailed - Optional error callback.
+ * @param params.onValidationSuccessful - Optional success callback.
+ * @returns {TState} The validated state or defaultState.
+ */
+const validateState = ({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }) => {
+    const result = schema.safeParse(state);
+    if (result.success) {
+        onValidationSuccessful?.(result.data);
+        return result.data;
+    }
+    // eslint-disable-next-line no-console
+    console.error("Failed to parse and validate the state from storage.", result.error);
+    onValidationFailed?.(result.error);
+    return defaultState;
+};
+
+/**
+ * Keys reserved for internal storage envelope metadata.
+ * Consumer state objects must not use these as top-level keys.
+ */
+const RESERVED_STORAGE_KEYS = ["__data", "__version", "__serializer"];
+const warnIfReservedKeys = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return;
+    for (const key of RESERVED_STORAGE_KEYS) {
+        if (key in value) {
+            // eslint-disable-next-line no-console
+            console.warn(`[useWebStorage] "${key}" is a reserved internal storage key and must not be used in state objects. ` +
+                `It will conflict with the storage serialization envelope.`);
+        }
+    }
+};
+/**
+ * Serializes and writes a value to web storage.
+ * When a version is provided, wraps the data in a versioned envelope
+ * before serializing so the migration pipeline can detect it on read.
+ *
+ * @param storage - The Storage instance (localStorage / sessionStorage).
+ * @param key - The storage key.
+ * @param value - The value to serialize and store.
+ * @param version - Optional schema version to stamp onto the stored payload.
+ */
+const writeToStorage = (storage, key, value, version) => {
+    warnIfReservedKeys(value);
+    const payload = version === undefined ? value : createStorageVersionEnvelope(value, version);
+    storage.setItem(key, storageSerializer.serialize(payload));
+};
+
+/**
+ * Reads and validates a value from `localStorage`, pre-bound to `globalThis.localStorage`
+ * so callers never reference the `localStorage` global directly (and therefore never need
+ * a `no-direct-storage-access` lint exemption).
+ *
+ * This is the non-hook counterpart to `useLocalStorage` (in `@trackunit/react-components`),
+ * for the rare call site that has no React component/hook to attach a hook to (e.g.
+ * module-scope bootstrap code, or a callback invoked by framework internals outside of
+ * render — see `useLocalStorage`'s docs for when to prefer the hook instead). Uses the same
+ * schema validation, salvage, superjson serialization, and migration pipeline as
+ * `useLocalStorage`.
+ *
+ * @example
+ * ```ts
+ * import { readLocalStorageValue } from "@trackunit/shared-utils";
+ *
+ * const reloadData = readLocalStorageValue({
+ *   key: "irisAppLoader:reload",
+ *   defaultState: { count: 0, firstReloadTime: null },
+ *   schema: z.object({ count: z.number(), firstReloadTime: z.number().nullable() }),
+ * });
+ * ```
+ */
+const readLocalStorageValue = (options) => readFromStorage({ storage: globalThis.localStorage, ...options });
+/**
+ * Validates and writes a value to `localStorage`, pre-bound to `globalThis.localStorage`.
+ * See {@link readLocalStorageValue} for why this exists alongside `useLocalStorage`.
+ *
+ * Symmetrical with the read side: `value` is validated against `schema` before writing,
+ * exactly like the hook's write path (`useStorageSyncEffect` runs `validateState` before
+ * `writeToStorage`). On validation failure, nothing is written and any existing value at
+ * `key` is removed — this keeps `writeLocalStorageValue` from being the one place in the
+ * library that could persist schema-violating data for a `useLocalStorage`/
+ * `readLocalStorageValue` reader to later find and silently discard.
+ *
+ * @param params - Key, value, schema, and optional version/callbacks.
+ * @param params.key - The storage key.
+ * @param params.value - The value to validate, serialize, and store.
+ * @param params.schema - Zod schema the value must satisfy before it's written.
+ * @param params.version - Optional schema version to stamp onto the stored payload (see `MigrationConfig`).
+ * @param params.onValidationFailed - Called instead of writing, when `value` fails schema validation.
+ * @param params.onValidationSuccessful - Called after a successful write.
+ */
+const writeLocalStorageValue = ({ key, value, schema, version, onValidationFailed, onValidationSuccessful, }) => {
+    validateState({
+        state: value,
+        schema,
+        defaultState: value,
+        onValidationFailed: error => {
+            globalThis.localStorage.removeItem(key);
+            onValidationFailed?.(error);
+        },
+        onValidationSuccessful: data => {
+            writeToStorage(globalThis.localStorage, key, data, version);
+            onValidationSuccessful?.(data);
+        },
+    });
+};
+/**
+ * Removes a key from `localStorage`, pre-bound to `globalThis.localStorage`. A no-op if the
+ * key is already absent.
+ */
+const removeLocalStorageValue = (key) => {
+    globalThis.localStorage.removeItem(key);
+};
+
 /**
  * Deletes all undefined keys from an object.
  *
@@ -1200,7 +1620,7 @@ function getLoremIpsum({ paragraphs = 1, asArray = false } = {}) {
         }
         const sentences = firstParagraph.split(/\. /).filter(s => s.length > 0);
         const halfLength = Math.ceil(sentences.length / 2);
-        const halfText = sentences.slice(0, halfLength).join(". ") + ".";
+        const halfText = `${sentences.slice(0, halfLength).join(". ")}.`;
         return halfText;
     }
     // Handle numeric paragraphs
@@ -1677,7 +2097,10 @@ exports.objectValues = objectValues;
 exports.parseTailwindArbitraryValue = parseTailwindArbitraryValue;
 exports.pick = pick;
 exports.preload = preload;
+exports.readFromStorage = readFromStorage;
+exports.readLocalStorageValue = readLocalStorageValue;
 exports.removeLeftPadding = removeLeftPadding;
+exports.removeLocalStorageValue = removeLocalStorageValue;
 exports.removeProperties = removeProperties;
 exports.removeProperty = removeProperty;
 exports.replaceNullableNumbersWithZero = replaceNullableNumbersWithZero;
@@ -1686,6 +2109,7 @@ exports.resizeBlob = resizeBlob;
 exports.resizeImage = resizeImage;
 exports.rgb2hex = rgb2hex;
 exports.size = size;
+exports.storageSerializer = storageSerializer;
 exports.stringCompare = stringCompare;
 exports.stringCompareFromKey = stringCompareFromKey;
 exports.stringNaturalCompare = stringNaturalCompare;
@@ -1703,3 +2127,6 @@ exports.unionArraysByKey = unionArraysByKey;
 exports.uuidv3 = uuidv3;
 exports.uuidv4 = uuidv4;
 exports.uuidv5 = uuidv5;
+exports.validateState = validateState;
+exports.writeLocalStorageValue = writeLocalStorageValue;
+exports.writeToStorage = writeToStorage;

package/index.esm.js

@@ -1,4 +1,6 @@
+import { isEqual } from 'es-toolkit';
 import { z } from 'zod';
+import superjson from 'superjson';
 import { v3, v4, v5 } from 'uuid';
 
 /**
@@ -547,7 +549,7 @@ const insertToUUID = (arr, position, value) => [
  * @param input A string.
  * @param maxLength The maximum length of the string that it should pad for.
  */
-const zeroPadToUUIDLength = (input, maxLength) => input.length < maxLength ? zeroPadToUUIDLength("0" + input, maxLength) : input;
+const zeroPadToUUIDLength = (input, maxLength) => input.length < maxLength ? zeroPadToUUIDLength(`0${input}`, maxLength) : input;
 /**
  * A helper function that converts any value into a UUID.
  *
@@ -703,6 +705,424 @@ const fetchImageAsBase64 = async (url) => {
     });
 };
 
+/**
+ * Runs a sequential migration pipeline on the provided data, applying
+ * each migration whose version is in the range (fromVersion, toVersion].
+ *
+ * Throws if the filtered migrations have non-contiguous versions (gaps).
+ */
+const runMigrations = ({ data, fromVersion, toVersion, migrations, }) => {
+    if (toVersion <= fromVersion) {
+        return data;
+    }
+    const applicable = migrations
+        .toSorted((a, b) => a.version - b.version)
+        .filter(m => m.version > fromVersion && m.version <= toVersion);
+    if (applicable.length === 0) {
+        return data;
+    }
+    for (let i = 1; i < applicable.length; i++) {
+        const prev = applicable[i - 1];
+        const curr = applicable[i];
+        if (prev && curr && curr.version !== prev.version + 1) {
+            throw new Error(`Migration gap detected: found version ${prev.version} and ${curr.version} but no migration for version ${prev.version + 1}.`);
+        }
+    }
+    return applicable.reduce((acc, migration) => migration.migrate(acc), data);
+};
+
+/**
+ * Recursively builds a salvaging schema from a ZodObject by injecting `.catch(defaultValue[key])`
+ * for each field. This means invalid field values fall back to defaultState values rather than
+ * failing the entire parse.
+ *
+ * Unwraps ZodOptional, ZodNullable, and ZodDefault to reach the inner schema.
+ * ZodCatch is intentionally NOT unwrapped — consumer-defined catches take precedence.
+ * Non-ZodObject schemas (unions, discriminated unions, refinements, etc.) are returned unchanged
+ * so they behave as atomic units.
+ */
+function buildSalvagingSchema(schema, defaultValue) {
+    if (schema instanceof z.ZodOptional) {
+        return buildSalvagingSchema(schema.unwrap(), defaultValue).optional();
+    }
+    if (schema instanceof z.ZodNullable) {
+        return buildSalvagingSchema(schema.unwrap(), defaultValue).nullable();
+    }
+    if (schema instanceof z.ZodDefault) {
+        return buildSalvagingSchema(schema._def.innerType, defaultValue);
+    }
+    if (!(schema instanceof z.ZodObject)) {
+        return schema;
+    }
+    const defaultRecordResult = z.record(z.string(), z.unknown()).safeParse(defaultValue);
+    if (!defaultRecordResult.success) {
+        return schema;
+    }
+    const defaultRecord = defaultRecordResult.data;
+    const salvagingShape = {};
+    for (const key of Object.keys(schema.shape)) {
+        const fieldSchema = schema.shape[key];
+        if (fieldSchema === undefined)
+            continue;
+        const fieldDefault = defaultRecord[key];
+        salvagingShape[key] = buildSalvagingSchema(fieldSchema, fieldDefault).catch(fieldDefault);
+    }
+    return z.object(salvagingShape);
+}
+/**
+ * Attempts to salvage partial state from raw data when full schema validation has failed.
+ *
+ * For ZodObject schemas, rebuilds the schema with per-field `.catch(defaultState[key])` fallbacks
+ * and reparses. Valid field values from the stored data are kept; invalid fields fall back to their
+ * corresponding values in `defaultState`. Works recursively for nested ZodObject fields.
+ *
+ * Non-object schemas (discriminated unions, unions with `.refine()`, etc.) cannot be partially
+ * salvaged and return `null`.
+ *
+ * Consumer-defined `.catch()` wrappers take precedence over the injected salvage catches, since
+ * Zod processes catches inside-out.
+ *
+ * Note: when every field is invalid, the salvaged result will be deeply equal to `defaultState`.
+ * Callers should compare the result against `defaultState` to distinguish a genuine partial
+ * salvage from a total loss where no stored data survived.
+ *
+ * @template TState - The type of the stored state.
+ * @param schema - Zod schema for validation.
+ * @param rawData - The raw deserialized value that failed validation.
+ * @param defaultState - The authoritative fallback value; used as per-field catch defaults.
+ * @returns {TState | null} The salvaged state, or `null` if salvaging is not possible or also fails.
+ */
+const salvageState = (schema, rawData, defaultState) => {
+    try {
+        const salvagingSchema = buildSalvagingSchema(schema, defaultState);
+        const intermediate = salvagingSchema.safeParse(rawData);
+        if (!intermediate.success) {
+            return null;
+        }
+        // Re-validate through the original schema to ensure correctness and get the proper TState type.
+        // By construction this should always succeed: each field value is either the valid stored value
+        // or defaultState[key], both of which satisfy the original schema.
+        const result = schema.safeParse(intermediate.data);
+        return result.success ? result.data : null;
+    }
+    catch {
+        return null;
+    }
+};
+
+/**
+ * Internal envelope used to tag superjson-serialized data in web storage.
+ *
+ * `__serializer` is a **reserved internal key** — consumer state objects must
+ * not include it as a top-level key. The double-underscore prefix is a
+ * deliberate signal that this is a private implementation detail.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+const taggedSuperjsonEnvelopeSchema = z.object({
+    __serializer: z.literal("superjson"),
+    json: z.custom(),
+    meta: z.custom().optional(),
+});
+const storageSerializer = {
+    serialize: (value) => {
+        const serialized = superjson.serialize(value);
+        return JSON.stringify({ __serializer: "superjson", ...serialized });
+    },
+    deserialize: (value) => {
+        const parsed = JSON.parse(value);
+        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
+        if (result.success) {
+            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
+        }
+        return parsed;
+    },
+};
+
+/**
+ * Internal envelope that pairs stored data with a schema version number.
+ *
+ * `__version` and `__data` are **reserved internal keys** — consumer state
+ * objects must not include them as top-level keys. The double-underscore
+ * prefix is a deliberate signal that these are private implementation details.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+const storageVersionEnvelopeSchema = z
+    .object({
+    __version: z.number(),
+    __data: z.unknown(),
+})
+    .refine((x) => "__data" in x, {
+    message: "__data is required",
+});
+/** Wraps data and version into a versioned storage envelope. */
+const createStorageVersionEnvelope = (data, version) => ({
+    __version: version,
+    __data: data,
+});
+
+/**
+ * Validates raw data against the schema, attempting partial salvage on failure.
+ *
+ * On success: returns the parsed data.
+ * On failure with a salvageable ZodObject schema where at least one stored field
+ *   survived: returns the salvaged state and calls `onValidationSalvaged`.
+ * On failure where salvage produces a result identical to `defaultState` (i.e. every
+ *   field was invalid and caught to its default): treats this as a total failure and
+ *   calls `onValidationFailed` instead of `onValidationSalvaged`.
+ * On failure with no salvage possible: returns `defaultState` and calls `onValidationFailed`.
+ */
+const validateOrSalvage = ({ rawValue, schema, defaultState, key, onValidationFailed, onValidationSalvaged, }) => {
+    const parseResult = schema.safeParse(rawValue);
+    if (parseResult.success) {
+        return parseResult.data;
+    }
+    const salvaged = salvageState(schema, rawValue, defaultState);
+    if (salvaged !== null && !isEqual(salvaged, defaultState)) {
+        // eslint-disable-next-line no-console
+        console.warn(`Partially invalid data in storage key "${key}" — salvaged valid fields, reset invalid fields to defaults.`, parseResult.error);
+        onValidationSalvaged?.(parseResult.error, salvaged);
+        return salvaged;
+    }
+    // eslint-disable-next-line no-console
+    console.error(`Failed to parse and validate the state from storage key "${key}". Returning default state.`, parseResult.error);
+    onValidationFailed?.(parseResult.error);
+    return defaultState;
+};
+/**
+ * Reads and deserializes a value from web storage, validating it against the provided schema.
+ * Falls back to defaultState if the key is missing or data is corrupt.
+ *
+ * On partial validation failure for ZodObject schemas, salvages valid fields rather than
+ * resetting the entire state to `defaultState`. See `salvageState` for salvage mechanics.
+ * If the salvaged result is deeply equal to `defaultState` (i.e. every field was invalid),
+ * the salvage is considered a total loss and `onValidationFailed` is called instead of
+ * `onValidationSalvaged`.
+ *
+ * Deserialization failures (unparseable/corrupt raw data) are routed through
+ * `onValidationFailed` so consumers are always notified when stored data is unusable.
+ *
+ * `legacyRawString` is a narrow, opt-in escape hatch for keys that are known to hold a
+ * plain-text value that was never JSON-encoded in the first place (e.g. a legacy username
+ * written via `localStorage.setItem` directly, with no `JSON.stringify`). When set, a raw
+ * value that fails JSON parsing is treated as the candidate string itself rather than a
+ * hard failure, and handed to schema validation (a permissive schema like `z.string()`
+ * recovers it; a schema expecting structured data still correctly rejects it). Leave this
+ * unset for every other key — enabling it globally would let a genuinely corrupted,
+ * truncated envelope be silently accepted as a valid string and re-persisted as such on the
+ * next write, permanently hiding the corruption. Scope it only to keys that are provably
+ * never written by anything other than a plain string.
+ *
+ * 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.
+ *
+ * @template TState - The type of the stored state.
+ * @param params - Storage, key, default state, Zod schema, optional migration config, and optional callbacks.
+ * @param params.storage - The web Storage instance.
+ * @param params.key - The storage key.
+ * @param params.defaultState - Fallback value when no stored data exists or data is corrupt.
+ * @param params.schema - Zod schema to validate the deserialized data.
+ * @param params.migration - Optional migration configuration (version, steps, fromKey).
+ * @param params.legacyRawString - Opt-in recovery for keys known to hold a plain-text value
+ *   that was never JSON-encoded. See the note above the function for when (not) to use this.
+ * @param params.onValidationFailed - Called when validation fails and no salvage is possible, or when
+ *   deserialization of the raw storage value fails entirely.
+ * @param params.onValidationSalvaged - Called when validation fails but at least one stored field
+ *   was recovered (salvaged result differs from defaultState).
+ * @returns {TState} The validated or salvaged state, or defaultState.
+ */
+const readFromStorage = ({ storage, key, defaultState, schema, migration, legacyRawString, onValidationFailed, onValidationSalvaged, }) => {
+    const version = migration?.version;
+    const steps = migration?.steps;
+    const fromKey = migration?.fromKey;
+    let raw = storage.getItem(key);
+    if (raw === null && fromKey !== undefined) {
+        raw = storage.getItem(fromKey);
+    }
+    if (raw === null) {
+        return defaultState;
+    }
+    let deserialized;
+    try {
+        deserialized = storageSerializer.deserialize(raw);
+    }
+    catch (deserializationError) {
+        if (legacyRawString) {
+            return validateOrSalvage({
+                rawValue: raw,
+                schema,
+                defaultState,
+                key,
+                onValidationFailed,
+                onValidationSalvaged,
+            });
+        }
+        // eslint-disable-next-line no-console
+        console.error(`Failed to deserialize storage key "${key}". Returning default state.`, deserializationError);
+        onValidationFailed?.(deserializationError);
+        return defaultState;
+    }
+    if (version === undefined) {
+        return validateOrSalvage({
+            rawValue: deserialized,
+            schema,
+            defaultState,
+            key,
+            onValidationFailed,
+            onValidationSalvaged,
+        });
+    }
+    let storedVersion;
+    let data;
+    const envelopeResult = storageVersionEnvelopeSchema.safeParse(deserialized);
+    if (envelopeResult.success) {
+        storedVersion = envelopeResult.data.__version;
+        data = envelopeResult.data.__data;
+    }
+    else {
+        storedVersion = 0;
+        data = deserialized;
+    }
+    if (steps !== undefined && storedVersion < version) {
+        try {
+            data = runMigrations({ data, fromVersion: storedVersion, toVersion: version, migrations: steps });
+        }
+        catch (migrationError) {
+            // eslint-disable-next-line no-console
+            console.error(`Migration failed for storage key "${key}" (v${storedVersion} → v${version}). Returning default state.`, migrationError);
+            return defaultState;
+        }
+    }
+    return validateOrSalvage({ rawValue: data, schema, defaultState, key, onValidationFailed, onValidationSalvaged });
+};
+
+/**
+ * Validates the state using a Zod schema. Returns the parsed state on success,
+ * or defaultState on failure (with error logging and optional callbacks).
+ *
+ * @template TState - The type of the state.
+ * @param params - The state, schema, defaultState, and optional callbacks.
+ * @param params.state - The raw state to validate.
+ * @param params.schema - The Zod schema for validation.
+ * @param params.defaultState - The fallback value on failure.
+ * @param params.onValidationFailed - Optional error callback.
+ * @param params.onValidationSuccessful - Optional success callback.
+ * @returns {TState} The validated state or defaultState.
+ */
+const validateState = ({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }) => {
+    const result = schema.safeParse(state);
+    if (result.success) {
+        onValidationSuccessful?.(result.data);
+        return result.data;
+    }
+    // eslint-disable-next-line no-console
+    console.error("Failed to parse and validate the state from storage.", result.error);
+    onValidationFailed?.(result.error);
+    return defaultState;
+};
+
+/**
+ * Keys reserved for internal storage envelope metadata.
+ * Consumer state objects must not use these as top-level keys.
+ */
+const RESERVED_STORAGE_KEYS = ["__data", "__version", "__serializer"];
+const warnIfReservedKeys = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return;
+    for (const key of RESERVED_STORAGE_KEYS) {
+        if (key in value) {
+            // eslint-disable-next-line no-console
+            console.warn(`[useWebStorage] "${key}" is a reserved internal storage key and must not be used in state objects. ` +
+                `It will conflict with the storage serialization envelope.`);
+        }
+    }
+};
+/**
+ * Serializes and writes a value to web storage.
+ * When a version is provided, wraps the data in a versioned envelope
+ * before serializing so the migration pipeline can detect it on read.
+ *
+ * @param storage - The Storage instance (localStorage / sessionStorage).
+ * @param key - The storage key.
+ * @param value - The value to serialize and store.
+ * @param version - Optional schema version to stamp onto the stored payload.
+ */
+const writeToStorage = (storage, key, value, version) => {
+    warnIfReservedKeys(value);
+    const payload = version === undefined ? value : createStorageVersionEnvelope(value, version);
+    storage.setItem(key, storageSerializer.serialize(payload));
+};
+
+/**
+ * Reads and validates a value from `localStorage`, pre-bound to `globalThis.localStorage`
+ * so callers never reference the `localStorage` global directly (and therefore never need
+ * a `no-direct-storage-access` lint exemption).
+ *
+ * This is the non-hook counterpart to `useLocalStorage` (in `@trackunit/react-components`),
+ * for the rare call site that has no React component/hook to attach a hook to (e.g.
+ * module-scope bootstrap code, or a callback invoked by framework internals outside of
+ * render — see `useLocalStorage`'s docs for when to prefer the hook instead). Uses the same
+ * schema validation, salvage, superjson serialization, and migration pipeline as
+ * `useLocalStorage`.
+ *
+ * @example
+ * ```ts
+ * import { readLocalStorageValue } from "@trackunit/shared-utils";
+ *
+ * const reloadData = readLocalStorageValue({
+ *   key: "irisAppLoader:reload",
+ *   defaultState: { count: 0, firstReloadTime: null },
+ *   schema: z.object({ count: z.number(), firstReloadTime: z.number().nullable() }),
+ * });
+ * ```
+ */
+const readLocalStorageValue = (options) => readFromStorage({ storage: globalThis.localStorage, ...options });
+/**
+ * Validates and writes a value to `localStorage`, pre-bound to `globalThis.localStorage`.
+ * See {@link readLocalStorageValue} for why this exists alongside `useLocalStorage`.
+ *
+ * Symmetrical with the read side: `value` is validated against `schema` before writing,
+ * exactly like the hook's write path (`useStorageSyncEffect` runs `validateState` before
+ * `writeToStorage`). On validation failure, nothing is written and any existing value at
+ * `key` is removed — this keeps `writeLocalStorageValue` from being the one place in the
+ * library that could persist schema-violating data for a `useLocalStorage`/
+ * `readLocalStorageValue` reader to later find and silently discard.
+ *
+ * @param params - Key, value, schema, and optional version/callbacks.
+ * @param params.key - The storage key.
+ * @param params.value - The value to validate, serialize, and store.
+ * @param params.schema - Zod schema the value must satisfy before it's written.
+ * @param params.version - Optional schema version to stamp onto the stored payload (see `MigrationConfig`).
+ * @param params.onValidationFailed - Called instead of writing, when `value` fails schema validation.
+ * @param params.onValidationSuccessful - Called after a successful write.
+ */
+const writeLocalStorageValue = ({ key, value, schema, version, onValidationFailed, onValidationSuccessful, }) => {
+    validateState({
+        state: value,
+        schema,
+        defaultState: value,
+        onValidationFailed: error => {
+            globalThis.localStorage.removeItem(key);
+            onValidationFailed?.(error);
+        },
+        onValidationSuccessful: data => {
+            writeToStorage(globalThis.localStorage, key, data, version);
+            onValidationSuccessful?.(data);
+        },
+    });
+};
+/**
+ * Removes a key from `localStorage`, pre-bound to `globalThis.localStorage`. A no-op if the
+ * key is already absent.
+ */
+const removeLocalStorageValue = (key) => {
+    globalThis.localStorage.removeItem(key);
+};
+
 /**
  * Deletes all undefined keys from an object.
  *
@@ -1198,7 +1618,7 @@ function getLoremIpsum({ paragraphs = 1, asArray = false } = {}) {
         }
         const sentences = firstParagraph.split(/\. /).filter(s => s.length > 0);
         const halfLength = Math.ceil(sentences.length / 2);
-        const halfText = sentences.slice(0, halfLength).join(". ") + ".";
+        const halfText = `${sentences.slice(0, halfLength).join(". ")}.`;
         return halfText;
     }
     // Handle numeric paragraphs
@@ -1609,4 +2029,4 @@ const formatUsCustomaryDistance = (value) => {
     }
 };
 
-export { DateTimeFormat, HoursAndMinutesFormat, UnitsOfMeasurementSI, UnitsOfMeasurementUSCustomary, VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, align, alphabeticallySort, arrayLengthCompare, arrayNotEmpty, booleanCompare, calculateImageScaleRatio, capitalize, colorsFromStyleDeclaration, convertBlobToBase64, convertMetersToKilometers, convertMetersToYards, convertYardsToMeters, convertYardsToMiles, dateCompare, deleteUndefinedKeys, difference, doNothing, enumFromValue, enumFromValueTypesafe, enumOrUndefinedFromValue, exhaustiveCheck, fetchImageAsBase64, filterByMultiple, formatAddress, formatCoordinates, formatSiDistance, formatUsCustomaryDistance, fuzzySearch, getAllColors, getCountryName, getDifferenceBetweenDates, getEndOfDay, getFirstLevelObjectPropertyDifferences, getISOStringFromDate, getLoremIpsum, getMimeTypeFromDataURL, getResizedDimensions, getStartOfDay, groupBy, groupTinyDataToOthers, hourIntervals, intersection, isArrayEqual, isNavigatingAway, isSortByProperty, isSorted, isUUID, isValidImage, loadSVGDimensions, markNavigatingAway, nonNullable, numberCompare, numberCompareUnknownAfterHighest, objNotEmpty, objectEntries, objectFromEntries, objectKeys, objectValues, parseTailwindArbitraryValue, pick, preload, removeLeftPadding, removeProperties, removeProperty, replaceNullableNumbersWithZero, resetNavigatingAwayForTests, resizeBlob, resizeImage, rgb2hex, size, stringCompare, stringCompareFromKey, stringNaturalCompare, stripHiddenCharacters, svgToPNG, titleCase, toID, toIDs, toPNG, toUUID, trimIds, trimPath, truthy, unionArraysByKey, uuidv3, uuidv4, uuidv5 };
+export { DateTimeFormat, HoursAndMinutesFormat, UnitsOfMeasurementSI, UnitsOfMeasurementUSCustomary, VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, align, alphabeticallySort, arrayLengthCompare, arrayNotEmpty, booleanCompare, calculateImageScaleRatio, capitalize, colorsFromStyleDeclaration, convertBlobToBase64, convertMetersToKilometers, convertMetersToYards, convertYardsToMeters, convertYardsToMiles, dateCompare, deleteUndefinedKeys, difference, doNothing, enumFromValue, enumFromValueTypesafe, enumOrUndefinedFromValue, exhaustiveCheck, fetchImageAsBase64, filterByMultiple, formatAddress, formatCoordinates, formatSiDistance, formatUsCustomaryDistance, fuzzySearch, getAllColors, getCountryName, getDifferenceBetweenDates, getEndOfDay, getFirstLevelObjectPropertyDifferences, getISOStringFromDate, getLoremIpsum, getMimeTypeFromDataURL, getResizedDimensions, getStartOfDay, groupBy, groupTinyDataToOthers, hourIntervals, intersection, isArrayEqual, isNavigatingAway, isSortByProperty, isSorted, isUUID, isValidImage, loadSVGDimensions, markNavigatingAway, nonNullable, numberCompare, numberCompareUnknownAfterHighest, objNotEmpty, objectEntries, objectFromEntries, objectKeys, objectValues, parseTailwindArbitraryValue, pick, preload, readFromStorage, readLocalStorageValue, removeLeftPadding, removeLocalStorageValue, removeProperties, removeProperty, replaceNullableNumbersWithZero, resetNavigatingAwayForTests, resizeBlob, resizeImage, rgb2hex, size, storageSerializer, stringCompare, stringCompareFromKey, stringNaturalCompare, stripHiddenCharacters, svgToPNG, titleCase, toID, toIDs, toPNG, toUUID, trimIds, trimPath, truthy, unionArraysByKey, uuidv3, uuidv4, uuidv5, validateState, writeLocalStorageValue, writeToStorage };

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@trackunit/shared-utils",
-  "version": "1.16.4",
+  "version": "1.16.5",
   "repository": "https://github.com/Trackunit/manager",
   "engines": {
     "node": ">=24.x"
   },
   "license": "SEE LICENSE IN LICENSE.txt",
   "dependencies": {
+    "es-toolkit": "^1.39.10",
+    "superjson": "^2.2.6",
     "uuid": "^11.1.0",
     "zod": "^3.25.76"
   },

package/src/index.d.ts

@@ -18,6 +18,12 @@ export * from "./groupBy/groupBy";
 export * from "./GroupingUtility";
 export * from "./idUtils";
 export * from "./imageTools";
+export * from "./localStorage/localStorageAccessors";
+export * from "./localStorage/readFromStorage";
+export * from "./localStorage/storageSerializer";
+export * from "./localStorage/types";
+export * from "./localStorage/validateState";
+export * from "./localStorage/writeToStorage";
 export * from "./Maybe";
 export * from "./objectUtils";
 export * from "./pathUtils";

package/src/localStorage/localStorageAccessors.d.ts

@@ -0,0 +1,60 @@
+import type { z } from "zod";
+import { readFromStorage } from "./readFromStorage";
+import type { WebStorageCallbacks } from "./types";
+type ReadLocalStorageOptions<TState> = Omit<Parameters<typeof readFromStorage<TState>>[0], "storage">;
+/**
+ * Reads and validates a value from `localStorage`, pre-bound to `globalThis.localStorage`
+ * so callers never reference the `localStorage` global directly (and therefore never need
+ * a `no-direct-storage-access` lint exemption).
+ *
+ * This is the non-hook counterpart to `useLocalStorage` (in `@trackunit/react-components`),
+ * for the rare call site that has no React component/hook to attach a hook to (e.g.
+ * module-scope bootstrap code, or a callback invoked by framework internals outside of
+ * render — see `useLocalStorage`'s docs for when to prefer the hook instead). Uses the same
+ * schema validation, salvage, superjson serialization, and migration pipeline as
+ * `useLocalStorage`.
+ *
+ * @example
+ * ```ts
+ * import { readLocalStorageValue } from "@trackunit/shared-utils";
+ *
+ * const reloadData = readLocalStorageValue({
+ *   key: "irisAppLoader:reload",
+ *   defaultState: { count: 0, firstReloadTime: null },
+ *   schema: z.object({ count: z.number(), firstReloadTime: z.number().nullable() }),
+ * });
+ * ```
+ */
+export declare const readLocalStorageValue: <TState>(options: ReadLocalStorageOptions<TState>) => TState;
+type WriteLocalStorageOptions<TState> = {
+    readonly key: string;
+    readonly value: TState;
+    readonly schema: z.ZodType<TState>;
+    readonly version?: number;
+} & Pick<WebStorageCallbacks<TState>, "onValidationFailed" | "onValidationSuccessful">;
+/**
+ * Validates and writes a value to `localStorage`, pre-bound to `globalThis.localStorage`.
+ * See {@link readLocalStorageValue} for why this exists alongside `useLocalStorage`.
+ *
+ * Symmetrical with the read side: `value` is validated against `schema` before writing,
+ * exactly like the hook's write path (`useStorageSyncEffect` runs `validateState` before
+ * `writeToStorage`). On validation failure, nothing is written and any existing value at
+ * `key` is removed — this keeps `writeLocalStorageValue` from being the one place in the
+ * library that could persist schema-violating data for a `useLocalStorage`/
+ * `readLocalStorageValue` reader to later find and silently discard.
+ *
+ * @param params - Key, value, schema, and optional version/callbacks.
+ * @param params.key - The storage key.
+ * @param params.value - The value to validate, serialize, and store.
+ * @param params.schema - Zod schema the value must satisfy before it's written.
+ * @param params.version - Optional schema version to stamp onto the stored payload (see `MigrationConfig`).
+ * @param params.onValidationFailed - Called instead of writing, when `value` fails schema validation.
+ * @param params.onValidationSuccessful - Called after a successful write.
+ */
+export declare const writeLocalStorageValue: <TState>({ key, value, schema, version, onValidationFailed, onValidationSuccessful, }: WriteLocalStorageOptions<TState>) => void;
+/**
+ * Removes a key from `localStorage`, pre-bound to `globalThis.localStorage`. A no-op if the
+ * key is already absent.
+ */
+export declare const removeLocalStorageValue: (key: string) => void;
+export {};

package/src/localStorage/readFromStorage.d.ts

@@ -0,0 +1,53 @@
+import type { z } from "zod";
+import type { MigrationConfig, WebStorageCallbacks } from "./types";
+/**
+ * Reads and deserializes a value from web storage, validating it against the provided schema.
+ * Falls back to defaultState if the key is missing or data is corrupt.
+ *
+ * On partial validation failure for ZodObject schemas, salvages valid fields rather than
+ * resetting the entire state to `defaultState`. See `salvageState` for salvage mechanics.
+ * If the salvaged result is deeply equal to `defaultState` (i.e. every field was invalid),
+ * the salvage is considered a total loss and `onValidationFailed` is called instead of
+ * `onValidationSalvaged`.
+ *
+ * Deserialization failures (unparseable/corrupt raw data) are routed through
+ * `onValidationFailed` so consumers are always notified when stored data is unusable.
+ *
+ * `legacyRawString` is a narrow, opt-in escape hatch for keys that are known to hold a
+ * plain-text value that was never JSON-encoded in the first place (e.g. a legacy username
+ * written via `localStorage.setItem` directly, with no `JSON.stringify`). When set, a raw
+ * value that fails JSON parsing is treated as the candidate string itself rather than a
+ * hard failure, and handed to schema validation (a permissive schema like `z.string()`
+ * recovers it; a schema expecting structured data still correctly rejects it). Leave this
+ * unset for every other key — enabling it globally would let a genuinely corrupted,
+ * truncated envelope be silently accepted as a valid string and re-persisted as such on the
+ * next write, permanently hiding the corruption. Scope it only to keys that are provably
+ * never written by anything other than a plain string.
+ *
+ * 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.
+ *
+ * @template TState - The type of the stored state.
+ * @param params - Storage, key, default state, Zod schema, optional migration config, and optional callbacks.
+ * @param params.storage - The web Storage instance.
+ * @param params.key - The storage key.
+ * @param params.defaultState - Fallback value when no stored data exists or data is corrupt.
+ * @param params.schema - Zod schema to validate the deserialized data.
+ * @param params.migration - Optional migration configuration (version, steps, fromKey).
+ * @param params.legacyRawString - Opt-in recovery for keys known to hold a plain-text value
+ *   that was never JSON-encoded. See the note above the function for when (not) to use this.
+ * @param params.onValidationFailed - Called when validation fails and no salvage is possible, or when
+ *   deserialization of the raw storage value fails entirely.
+ * @param params.onValidationSalvaged - Called when validation fails but at least one stored field
+ *   was recovered (salvaged result differs from defaultState).
+ * @returns {TState} The validated or salvaged state, or defaultState.
+ */
+export declare const readFromStorage: <TState>({ storage, key, defaultState, schema, migration, legacyRawString, onValidationFailed, onValidationSalvaged, }: {
+    readonly storage: Storage;
+    readonly key: string;
+    readonly defaultState: TState;
+    readonly schema: z.ZodType<TState>;
+    readonly migration?: MigrationConfig;
+    readonly legacyRawString?: boolean;
+} & Pick<WebStorageCallbacks<TState>, "onValidationFailed" | "onValidationSalvaged">) => TState;

package/src/localStorage/runMigrations.d.ts

@@ -0,0 +1,13 @@
+import type { StorageMigration } from "./types";
+/**
+ * Runs a sequential migration pipeline on the provided data, applying
+ * each migration whose version is in the range (fromVersion, toVersion].
+ *
+ * Throws if the filtered migrations have non-contiguous versions (gaps).
+ */
+export declare const runMigrations: ({ data, fromVersion, toVersion, migrations, }: {
+    readonly data: unknown;
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly migrations: ReadonlyArray<StorageMigration>;
+}) => unknown;

package/src/localStorage/salvageState.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/**
+ * Attempts to salvage partial state from raw data when full schema validation has failed.
+ *
+ * For ZodObject schemas, rebuilds the schema with per-field `.catch(defaultState[key])` fallbacks
+ * and reparses. Valid field values from the stored data are kept; invalid fields fall back to their
+ * corresponding values in `defaultState`. Works recursively for nested ZodObject fields.
+ *
+ * Non-object schemas (discriminated unions, unions with `.refine()`, etc.) cannot be partially
+ * salvaged and return `null`.
+ *
+ * Consumer-defined `.catch()` wrappers take precedence over the injected salvage catches, since
+ * Zod processes catches inside-out.
+ *
+ * Note: when every field is invalid, the salvaged result will be deeply equal to `defaultState`.
+ * Callers should compare the result against `defaultState` to distinguish a genuine partial
+ * salvage from a total loss where no stored data survived.
+ *
+ * @template TState - The type of the stored state.
+ * @param schema - Zod schema for validation.
+ * @param rawData - The raw deserialized value that failed validation.
+ * @param defaultState - The authoritative fallback value; used as per-field catch defaults.
+ * @returns {TState | null} The salvaged state, or `null` if salvaging is not possible or also fails.
+ */
+export declare const salvageState: <TState>(schema: z.ZodType<TState>, rawData: unknown, defaultState: TState) => TState | null;

package/src/localStorage/storageSerializer.d.ts

@@ -0,0 +1,4 @@
+export declare const storageSerializer: {
+    readonly serialize: (value: unknown) => string;
+    readonly deserialize: (value: string) => unknown;
+};

package/src/localStorage/storageVersionEnvelope.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/**
+ * Internal envelope that pairs stored data with a schema version number.
+ *
+ * `__version` and `__data` are **reserved internal keys** — consumer state
+ * objects must not include them as top-level keys. The double-underscore
+ * prefix is a deliberate signal that these are private implementation details.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+export declare const storageVersionEnvelopeSchema: z.ZodEffects<z.ZodObject<{
+    __version: z.ZodNumber;
+    __data: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    __version: number;
+    __data?: unknown;
+}, {
+    __version: number;
+    __data?: unknown;
+}>, {
+    __version: number;
+    __data: unknown;
+}, {
+    __version: number;
+    __data?: unknown;
+}>;
+export type StorageVersionEnvelope = z.infer<typeof storageVersionEnvelopeSchema>;
+/** Wraps data and version into a versioned storage envelope. */
+export declare const createStorageVersionEnvelope: (data: unknown, version: number) => StorageVersionEnvelope;

package/src/localStorage/types.d.ts

@@ -0,0 +1,41 @@
+import type { z } from "zod";
+export type StorageMigration = {
+    readonly version: number;
+    readonly migrate: (data: unknown) => unknown;
+};
+export type MigrationConfig = {
+    readonly version: number;
+    readonly steps?: ReadonlyArray<StorageMigration>;
+    readonly fromKey?: string;
+};
+export type WebStorageOptions<TState> = {
+    /** Must be a stable, non-empty string. Passing an empty string throws during render. Changing from non-empty to empty across renders is unsupported and will throw. */
+    readonly key: string;
+    readonly defaultState: NoInfer<TState>;
+    readonly schema: z.ZodType<TState>;
+    readonly migration?: MigrationConfig;
+    /**
+     * Narrow, opt-in recovery for keys known to hold a plain-text value that was never
+     * JSON-encoded (e.g. a legacy value written via `localStorage.setItem` directly, with
+     * no `JSON.stringify`). Only enable this for a key that is provably never written by
+     * anything other than a plain string — enabling it broadly would let a genuinely
+     * corrupted, truncated envelope be silently accepted as a valid string and re-persisted
+     * as such on the next write, permanently hiding the corruption. See `readFromStorage`'s
+     * docs for the full rationale.
+     */
+    readonly legacyRawString?: boolean;
+};
+export type WebStorageCallbacks<TState> = {
+    readonly onValidationFailed?: (error: unknown) => void;
+    readonly onValidationSuccessful?: (data: TState) => void;
+    /**
+     * Called when schema validation fails but partial state was recovered.
+     * Valid fields from the stored value are kept; invalid fields fall back to their
+     * corresponding values in `defaultState`. Only fires during reads (initialization
+     * and key changes) — never during the write-sync path.
+     *
+     * @param error - The ZodError describing which fields failed validation.
+     * @param salvaged - The recovered state combining valid stored fields and defaultState fallbacks.
+     */
+    readonly onValidationSalvaged?: (error: z.ZodError, salvaged: TState) => void;
+};

package/src/localStorage/validateState.d.ts

@@ -0,0 +1,22 @@
+import type { z } from "zod";
+import type { WebStorageCallbacks } from "./types";
+type ValidateStateOptions<TState> = {
+    readonly state: unknown;
+    readonly defaultState: TState;
+    readonly schema: z.ZodType<TState>;
+} & WebStorageCallbacks<TState>;
+/**
+ * Validates the state using a Zod schema. Returns the parsed state on success,
+ * or defaultState on failure (with error logging and optional callbacks).
+ *
+ * @template TState - The type of the state.
+ * @param params - The state, schema, defaultState, and optional callbacks.
+ * @param params.state - The raw state to validate.
+ * @param params.schema - The Zod schema for validation.
+ * @param params.defaultState - The fallback value on failure.
+ * @param params.onValidationFailed - Optional error callback.
+ * @param params.onValidationSuccessful - Optional success callback.
+ * @returns {TState} The validated state or defaultState.
+ */
+export declare const validateState: <TState>({ state, schema, onValidationFailed, onValidationSuccessful, defaultState, }: ValidateStateOptions<TState>) => TState;
+export {};

package/src/localStorage/writeToStorage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serializes and writes a value to web storage.
+ * When a version is provided, wraps the data in a versioned envelope
+ * before serializing so the migration pipeline can detect it on read.
+ *
+ * @param storage - The Storage instance (localStorage / sessionStorage).
+ * @param key - The storage key.
+ * @param value - The value to serialize and store.
+ * @param version - Optional schema version to stamp onto the stored payload.
+ */
+export declare const writeToStorage: (storage: Storage, key: string, value: unknown, version?: number) => void;