schema-storage 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,258 @@
+# schema-storage
+
+TypeScript-first wrapper around localStorage that provides typed keys, schema validation, and automatic data migrations — so persisted client-side data never breaks your app.
+
+## Installation
+
+```bash
+npm install schema-storage zod
+```
+
+## Quick Start
+
+```typescript
+import { createStorage } from "schema-storage";
+import { z } from "zod";
+
+const storage = createStorage({
+  user: z.object({
+    id: z.string(),
+    email: z.string().email(),
+  }),
+  theme: z.enum(["light", "dark"]),
+});
+
+// Fully typed!
+storage.set("theme", "dark"); // ✅
+storage.set("theme", "blue"); // ❌ Type error
+
+const user = storage.get("user"); // { id: string; email: string } | null
+const theme = storage.getOrDefault("theme", "light"); // "light" | "dark"
+```
+
+## Features
+
+### 1. Typed Keys
+
+No more magic strings. All keys are typed and autocompleted.
+
+```typescript
+const storage = createStorage({
+  settings: z.object({
+    language: z.string(),
+    notifications: z.boolean(),
+  }),
+});
+
+storage.get("settings"); // Typed return
+storage.get("unknown"); // ❌ Type error
+```
+
+### 2. Schema Validation
+
+Every read operation validates data against your schema. Invalid or corrupted data is safely rejected.
+
+```typescript
+const storage = createStorage({
+  count: z.number(),
+}, {
+  onInvalid: "reset", // or "throw" | "ignore"
+});
+
+// If localStorage contains invalid JSON or wrong shape:
+const count = storage.get("count"); // null (or throws if onInvalid: "throw")
+```
+
+### 3. Versioned Migrations
+
+Safely evolve your data models without breaking existing users.
+
+```typescript
+const storage = createStorage({
+  user: {
+    version: 2,
+    schema: z.object({
+      id: z.string(),
+      email: z.string().email(),
+      name: z.string(),
+    }),
+    migrate: {
+      1: (oldData) => ({
+        id: oldData.id,
+        email: "unknown@example.com",
+        name: "User",
+      }),
+    },
+  },
+});
+```
+
+When `get("user")` is called:
+1. Detects stored version (1)
+2. Applies migration from 1 → 2
+3. Validates final result
+4. Persists upgraded version automatically
+
+### 4. Storage-Agnostic
+
+Use any storage backend with the same API.
+
+```typescript
+import { createStorage, MemoryStorage } from "schema-storage";
+
+// Default: localStorage
+const storage1 = createStorage({ ... });
+
+// sessionStorage
+const storage2 = createStorage({ ... }, { driver: sessionStorage });
+
+// Memory (SSR-safe, testing)
+const storage3 = createStorage({ ... }, { driver: new MemoryStorage() });
+```
+
+## API
+
+### `createStorage<T>(schema, options?)`
+
+Creates a typed storage instance.
+
+**Parameters:**
+- `schema`: Object mapping keys to Zod schemas or versioned schemas
+- `options`:
+  - `driver?: StorageDriver` - Storage backend (default: localStorage)
+  - `onInvalid?: "throw" | "reset" | "ignore"` - Behavior for invalid data (default: "ignore")
+  - `prefix?: string` - Key prefix for namespacing
+
+**Returns:** `SafeStorage<T>`
+
+### Storage Methods
+
+#### `get<K>(key: K): T[K] | null`
+
+Reads and validates a value. Returns `null` if missing or invalid.
+
+#### `set<K>(key: K, value: T[K]): void`
+
+Writes a value with validation. Throws if validation fails and `onInvalid: "throw"`.
+
+#### `remove(key: keyof T): void`
+
+Removes a key and its metadata.
+
+#### `clear(): void`
+
+Clears all storage (or all prefixed keys if using a prefix).
+
+#### `has(key: keyof T): boolean`
+
+Checks if a key exists.
+
+#### `getOrDefault<K>(key: K, defaultValue: T[K]): T[K]`
+
+Gets a value or returns the default if missing/invalid.
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { createStorage } from "schema-storage";
+import { z } from "zod";
+
+const storage = createStorage({
+  todos: z.array(z.object({
+    id: z.string(),
+    text: z.string(),
+    completed: z.boolean(),
+  })),
+  filter: z.enum(["all", "active", "completed"]),
+});
+
+storage.set("todos", [
+  { id: "1", text: "Learn schema-storage", completed: false },
+]);
+
+const todos = storage.get("todos"); // Fully typed!
+```
+
+### With Migrations
+
+```typescript
+const storage = createStorage({
+  preferences: {
+    version: 3,
+    schema: z.object({
+      theme: z.enum(["light", "dark", "auto"]),
+      fontSize: z.number().min(12).max(24),
+      language: z.string(),
+    }),
+    migrate: {
+      1: (old) => ({
+        theme: old.theme ?? "light",
+        fontSize: 16,
+        language: "en",
+      }),
+      2: (old) => ({
+        ...old,
+        theme: old.theme === "system" ? "auto" : old.theme,
+      }),
+    },
+  },
+});
+```
+
+### Custom Storage Driver
+
+```typescript
+import { createStorage, type StorageDriver } from "schema-storage";
+
+class CustomStorage implements StorageDriver {
+  private data = new Map<string, string>();
+
+  getItem(key: string): string | null {
+    return this.data.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string): void {
+    this.data.set(key, value);
+  }
+
+  removeItem(key: string): void {
+    this.data.delete(key);
+  }
+
+  clear(): void {
+    this.data.clear();
+  }
+
+  key(index: number): string | null {
+    return Array.from(this.data.keys())[index] ?? null;
+  }
+
+  get length(): number {
+    return this.data.size;
+  }
+}
+
+const storage = createStorage({ ... }, { driver: new CustomStorage() });
+```
+
+## Why schema-storage?
+
+**localStorage problems:**
+- Everything is a string (manual JSON parsing)
+- No type safety
+- No validation
+- No migration strategy
+
+**schema-storage solves:**
+- ✅ Typed keys with autocomplete
+- ✅ Automatic JSON handling
+- ✅ Runtime validation with Zod
+- ✅ Versioned migrations
+- ✅ Storage-agnostic design
+
+## License
+
+MIT
+

package/dist/drivers.d.ts

@@ -0,0 +1,12 @@
+import { StorageDriver } from "./types";
+export declare class MemoryStorage implements StorageDriver {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    key(index: number): string | null;
+    get length(): number;
+}
+export declare function getDefaultDriver(): StorageDriver;
+//# sourceMappingURL=drivers.d.ts.map

package/dist/drivers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drivers.d.ts","sourceRoot":"","sources":["../src/drivers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,qBAAa,aAAc,YAAW,aAAa;IACjD,OAAO,CAAC,KAAK,CAAkC;IAE/C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI7B,KAAK,IAAI,IAAI;IAIb,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKjC,IAAI,MAAM,IAAI,MAAM,CAEnB;CACF;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD"}

package/dist/drivers.js

@@ -0,0 +1,30 @@
+export class MemoryStorage {
+    constructor() {
+        this.store = new Map();
+    }
+    getItem(key) {
+        return this.store.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.store.set(key, value);
+    }
+    removeItem(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+    key(index) {
+        const keys = Array.from(this.store.keys());
+        return keys[index] ?? null;
+    }
+    get length() {
+        return this.store.size;
+    }
+}
+export function getDefaultDriver() {
+    if (typeof window !== "undefined" && window.localStorage) {
+        return window.localStorage;
+    }
+    return new MemoryStorage();
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createStorage, type SafeStorage } from "./storage";
+export { type StorageDriver, type SchemaDefinition, type StorageOptions } from "./types";
+export { MemoryStorage, getDefaultDriver } from "./drivers";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createStorage } from "./storage";
+export { MemoryStorage, getDefaultDriver } from "./drivers";

package/dist/storage.d.ts

@@ -0,0 +1,11 @@
+import { SchemaDefinition, StorageOptions } from "./types";
+export interface SafeStorage<T extends Record<string, unknown>> {
+    get<K extends keyof T>(key: K): T[K] | null;
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    remove(key: keyof T): void;
+    clear(): void;
+    has(key: keyof T): boolean;
+    getOrDefault<K extends keyof T>(key: K, defaultValue: T[K]): T[K];
+}
+export declare function createStorage<T extends Record<string, unknown>>(schema: SchemaDefinition<T>, options?: StorageOptions): SafeStorage<T>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,gBAAgB,EAChB,cAAc,EAEf,MAAM,SAAS,CAAC;AASjB,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC5C,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAClD,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC3B,KAAK,IAAI,IAAI,CAAC;IACd,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;IAC3B,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;CACnE;AAQD,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,cAAmB,GAC3B,WAAW,CAAC,CAAC,CAAC,CAmIhB"}

package/dist/storage.js

@@ -0,0 +1,113 @@
+import { getDefaultDriver } from "./drivers";
+import { parseStoredValue, serializeValue, serializeMetadata, getMetadataKey, } from "./validation";
+function isVersioned(schema) {
+    return typeof schema === "object" && "version" in schema && "schema" in schema;
+}
+export function createStorage(schema, options = {}) {
+    const driver = options.driver ?? getDefaultDriver();
+    const onInvalid = options.onInvalid ?? "ignore";
+    const prefix = options.prefix ?? "";
+    function getStorageKey(key) {
+        return prefix ? `${prefix}:${key}` : key;
+    }
+    function get(key) {
+        const storageKey = getStorageKey(String(key));
+        const raw = driver.getItem(storageKey);
+        const schemaDef = schema[key];
+        if (!schemaDef) {
+            return null;
+        }
+        const metadataKey = getMetadataKey(storageKey);
+        const result = parseStoredValue(raw, schemaDef, metadataKey, driver);
+        if (result.value === null && onInvalid === "throw") {
+            throw new Error(`Invalid or missing data for key: ${String(key)}`);
+        }
+        if (result.needsWrite && result.value !== null) {
+            const serialized = serializeValue(result.value);
+            driver.setItem(storageKey, serialized);
+            if (isVersioned(schemaDef)) {
+                const metadataSerialized = serializeMetadata(schemaDef.version);
+                driver.setItem(metadataKey, metadataSerialized);
+            }
+        }
+        return result.value;
+    }
+    function set(key, value) {
+        const storageKey = getStorageKey(String(key));
+        const schemaDef = schema[key];
+        if (!schemaDef) {
+            throw new Error(`Unknown key: ${String(key)}`);
+        }
+        let actualSchema;
+        if (isVersioned(schemaDef)) {
+            actualSchema = schemaDef.schema;
+        }
+        else {
+            actualSchema = schemaDef;
+        }
+        const validated = actualSchema.safeParse(value);
+        if (!validated.success) {
+            if (onInvalid === "throw") {
+                throw new Error(`Validation failed for key ${String(key)}: ${validated.error.message}`);
+            }
+            return;
+        }
+        const serialized = serializeValue(validated.data);
+        driver.setItem(storageKey, serialized);
+        if (isVersioned(schemaDef)) {
+            const metadataSerialized = serializeMetadata(schemaDef.version);
+            const metadataKey = getMetadataKey(storageKey);
+            driver.setItem(metadataKey, metadataSerialized);
+        }
+    }
+    function remove(key) {
+        const storageKey = getStorageKey(String(key));
+        driver.removeItem(storageKey);
+        const metadataKey = getMetadataKey(storageKey);
+        driver.removeItem(metadataKey);
+    }
+    function clear() {
+        if (prefix) {
+            const keysToRemove = [];
+            const prefixWithColon = `${prefix}:`;
+            const metadataPrefix = getMetadataKey(prefixWithColon);
+            for (let i = 0; i < driver.length; i++) {
+                const key = driver.key(i);
+                if (key) {
+                    if (key.startsWith(prefixWithColon) || key.startsWith(metadataPrefix)) {
+                        keysToRemove.push(key);
+                    }
+                }
+            }
+            keysToRemove.forEach((key) => driver.removeItem(key));
+        }
+        else {
+            const keysToRemove = [];
+            const metadataPrefix = getMetadataKey("");
+            for (let i = 0; i < driver.length; i++) {
+                const key = driver.key(i);
+                if (key && key.startsWith(metadataPrefix)) {
+                    keysToRemove.push(key);
+                }
+            }
+            keysToRemove.forEach((key) => driver.removeItem(key));
+            driver.clear();
+        }
+    }
+    function has(key) {
+        const storageKey = getStorageKey(String(key));
+        return driver.getItem(storageKey) !== null;
+    }
+    function getOrDefault(key, defaultValue) {
+        const value = get(key);
+        return value !== null ? value : defaultValue;
+    }
+    return {
+        get,
+        set,
+        remove,
+        clear,
+        has,
+        getOrDefault,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export interface StorageDriver {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    key(index: number): string | null;
+    readonly length: number;
+}
+export interface VersionedSchema<T> {
+    version: number;
+    schema: z.ZodType<T>;
+    migrate?: Record<number, (data: unknown) => T>;
+}
+export type SchemaDefinition<T extends Record<string, unknown>> = {
+    [K in keyof T]: z.ZodType<T[K]> | VersionedSchema<T[K]>;
+};
+export interface StorageOptions {
+    driver?: StorageDriver;
+    onInvalid?: "throw" | "reset" | "ignore";
+    prefix?: string;
+}
+export interface StorageMetadata {
+    version: number;
+    data: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,IAAI,IAAI,CAAC;IACd,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC;CAChD;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;KAC/D,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACxD,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf"}

package/dist/types.js

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

package/dist/validation.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { VersionedSchema } from "./types";
+export declare function getMetadataKey(key: string): string;
+export declare function parseStoredValue<T>(raw: string | null, schema: z.ZodType<T> | VersionedSchema<T>, metadataKey: string, driver: {
+    getItem(key: string): string | null;
+}): {
+    value: T | null;
+    needsWrite: boolean;
+};
+export declare function serializeValue<T>(value: T): string;
+export declare function serializeMetadata(version: number): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAmB,MAAM,SAAS,CAAC;AAI3D,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,EACzC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE;IAAE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9C;IAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAqD1C;AAsBD,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAElD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzD"}

package/dist/validation.js

@@ -0,0 +1,70 @@
+const METADATA_PREFIX = "__safe_storage_meta__";
+export function getMetadataKey(key) {
+    return `${METADATA_PREFIX}${key}`;
+}
+export function parseStoredValue(raw, schema, metadataKey, driver) {
+    if (raw === null) {
+        return { value: null, needsWrite: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { value: null, needsWrite: false };
+    }
+    const isVersioned = (s) => {
+        return typeof s === "object" && "version" in s && "schema" in s;
+    };
+    if (isVersioned(schema)) {
+        const metadataRaw = driver.getItem(metadataKey);
+        let storedVersion = 1;
+        if (metadataRaw) {
+            try {
+                const metadata = JSON.parse(metadataRaw);
+                storedVersion = metadata.version;
+            }
+            catch {
+                storedVersion = 1;
+            }
+        }
+        if (storedVersion < schema.version) {
+            const migrated = migrateData(parsed, storedVersion, schema);
+            const validated = schema.schema.safeParse(migrated);
+            if (validated.success) {
+                return { value: validated.data, needsWrite: true };
+            }
+            return { value: null, needsWrite: false };
+        }
+        const validated = schema.schema.safeParse(parsed);
+        if (validated.success) {
+            return { value: validated.data, needsWrite: false };
+        }
+        return { value: null, needsWrite: false };
+    }
+    const validated = schema.safeParse(parsed);
+    if (validated.success) {
+        return { value: validated.data, needsWrite: false };
+    }
+    return { value: null, needsWrite: false };
+}
+function migrateData(data, fromVersion, schema) {
+    let current = data;
+    let currentVersion = fromVersion;
+    while (currentVersion < schema.version && schema.migrate) {
+        const migration = schema.migrate[currentVersion];
+        if (!migration) {
+            break;
+        }
+        current = migration(current);
+        currentVersion++;
+    }
+    return current;
+}
+export function serializeValue(value) {
+    return JSON.stringify(value);
+}
+export function serializeMetadata(version) {
+    const metadata = { version, data: null };
+    return JSON.stringify(metadata);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "schema-storage",
+  "version": "0.1.0",
+  "description": "TypeScript-first localStorage wrapper with typed keys, schema validation, and automatic migrations",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "localStorage",
+    "storage",
+    "typescript",
+    "validation",
+    "migration",
+    "schema",
+    "zod"
+  ],
+  "author": "Justinkarso",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Justinkarso/schema-storage"
+  },
+  "peerDependencies": {
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "zod": "^4.2.1"
+  }
+}