oto-storage 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Diomari Madulara
+
+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,212 @@
+# Oto Storage
+
+![npm version](https://img.shields.io/npm/v/oto-storage)
+![npm version](https://img.shields.io/npm/dm/oto-storage)
+
+A lightweight, Proxy-based wrapper for `localStorage` and `sessionStorage` with full TypeScript type safety.
+
+### 📦 Installation
+
+```bash
+npm install oto-storage
+```
+
+Or with yarn:
+
+```bash
+yarn add oto-storage
+```
+
+Or with pnpm:
+
+```bash
+pnpm add oto-storage
+```
+
+### ⚡ The Problem
+
+Working with browser storage usually involves repetitive `JSON.parse` and `JSON.stringify` calls, manual key prefixing to avoid collisions, and a total lack of Type Safety.
+
+```typescript
+// The old, "clunky" way
+const user = JSON.parse(localStorage.getItem("user_data") || "{}");
+localStorage.setItem("user_data", JSON.stringify({ ...user, theme: "dark" }));
+```
+
+### ✨ The Solution
+
+Oto storage uses the JavaScript Proxy API to let you interact with browser storage as if it were a local object. It handles serialization, prefixing, and type-checking automatically.
+
+**Key Features**
+
+- Type-Safe: Full autocomplete and build-time error checking.
+
+- Zero Boilerplate: No more manual JSON parsing.
+
+- Driver Support: Switch between localStorage and sessionStorage with one flag.
+
+- Collision Protection: Automatic key prefixing (namespacing).
+
+### 🚀 Quick Start
+
+**_1. Define your Schema_**
+
+```typescript
+interface AppStorage {
+  theme: "light" | "dark";
+  viewCount: number;
+  user: { id: string; name: string } | null;
+}
+```
+
+**_2. Initialize_**
+
+```typescript
+import { oto } from "oto-storage";
+
+// For localStorage (default)
+const storage = oto<AppStorage>({
+  prefix: "myApp-",
+});
+
+// For sessionStorage
+const session = oto<AppStorage>({
+  prefix: "myApp-",
+  type: "session",
+});
+```
+
+**_3. Use it like a regular object_**
+
+```typescript
+// SETTING: Automatically stringified and saved to 'myApp-theme'
+storage.theme = "dark";
+
+// GETTING: Automatically parsed and typed
+if (storage.theme === "dark") {
+  console.log("Dark mode active!");
+}
+
+// DELETE: Delete the key-value pair from storage
+delete storage.theme;
+
+// CLEAR: Clear entire record
+storage.clearAll();
+```
+
+### 📖 Comprehensive Examples
+
+**Working with Complex Objects**
+
+```typescript
+interface UserData {
+  id: string;
+  name: string;
+  preferences: {
+    theme: "light" | "dark";
+    notifications: boolean;
+  };
+}
+
+const storage = oto<{ user: UserData | null }>({ prefix: "app-" });
+
+// Store complex objects - automatically serialized
+storage.user = {
+  id: "123",
+  name: "Alice",
+  preferences: {
+    theme: "dark",
+    notifications: true,
+  },
+};
+
+// Retrieve - fully typed with autocomplete
+console.log(storage.user?.preferences.theme); // "dark"
+```
+
+**Checking if a Key Exists**
+
+```typescript
+const storage = oto<{ token: string | null }>({ prefix: "auth-" });
+
+// Use 'in' operator to check if key exists in storage
+if ("token" in storage) {
+  console.log("User is authenticated");
+}
+
+// Or check directly (returns undefined for non-existent keys)
+if (storage.token) {
+  console.log("Token exists:", storage.token);
+}
+```
+
+**Session Storage**
+
+```typescript
+const session = oto<{ temporaryData: string }>({
+  prefix: "temp-",
+  type: "session", // Uses sessionStorage instead of localStorage
+});
+
+session.temporaryData = "This will be cleared when tab closes";
+```
+
+**Multiple Namespaced Storages**
+
+```typescript
+const userPrefs = oto<{ theme: string }>({ prefix: "user-prefs-" });
+const appState = oto<{ sidebarOpen: boolean }>({ prefix: "app-" });
+
+userPrefs.theme = "dark";
+appState.sidebarOpen = true;
+
+// Keys are stored separately: 'user-prefs-theme' and 'app-sidebarOpen'
+```
+
+**Deleting and Clearing**
+
+```typescript
+const storage = oto<{ count: number; name: string }>({ prefix: "demo-" });
+
+storage.count = 42;
+storage.name = "Test";
+
+// Delete single key
+delete storage.count;
+
+// Clear all keys with this storage's prefix
+storage.clearAll();
+```
+
+**Type Safety at Work**
+
+```typescript
+interface AppStorage {
+  count: number;
+  items: string[];
+}
+
+const storage = oto<AppStorage>({ prefix: "app-" });
+
+storage.count = 10; // ✓ Works
+storage.count = "ten"; // ✗ TypeScript error: Type 'string' is not assignable to type 'number'
+
+storage.items = ["a", "b"]; // ✓ Works
+storage.items = "abc"; // ✗ TypeScript error: Type 'string' is not assignable to type 'string[]'
+```
+
+**Version Export**
+
+```typescript
+import { oto, version } from "oto-storage";
+
+console.log(`Using oto-storage v${version}`);
+```
+
+### 🛠️ Architecture Decisions
+
+**_Why Proxy?_**
+Choosing Proxy API over standard Class-based approach improves Developer Experience (DX). By intercepting `get` and `set` traps, we eliminate the need for `.getItem()` or `.setItem()` methods, making the storage feel "native" to JavaScript.
+
+**_Type Safety via Generics_**
+The library uses TypeScript Generics to map the user-provided interface to the Proxy. This ensures that if a developer tries to assign a `string` to a `number` field, the IDE will catch the error before the code even runs.

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+interface StorageOptions {
+    prefix?: string;
+    type?: "local" | "session";
+}
+declare function oto<T extends object>(options?: StorageOptions): T;
+declare const version = "1.0.0";
+
+export { type StorageOptions, oto, version };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+interface StorageOptions {
+    prefix?: string;
+    type?: "local" | "session";
+}
+declare function oto<T extends object>(options?: StorageOptions): T;
+declare const version = "1.0.0";
+
+export { type StorageOptions, oto, version };

package/dist/index.js

@@ -0,0 +1,90 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  oto: () => oto,
+  version: () => version
+});
+module.exports = __toCommonJS(index_exports);
+function oto(options = {}) {
+  const { prefix = "", type = "local" } = options;
+  const storage = typeof window !== "undefined" ? type === "session" ? window.sessionStorage : window.localStorage : null;
+  const safeStorage = storage || {
+    getItem: () => null,
+    setItem: () => {
+    },
+    removeItem: () => {
+    },
+    clear: () => {
+    },
+    key: () => null,
+    get length() {
+      return 0;
+    }
+  };
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop === "clearAll") {
+        return () => {
+          const keys = [];
+          for (let i = 0; i < safeStorage.length; i++) {
+            const key = safeStorage.key(i);
+            if (key) keys.push(key);
+          }
+          keys.forEach((key) => {
+            if (key.startsWith(prefix)) safeStorage.removeItem(key);
+          });
+        };
+      }
+      const value = safeStorage.getItem(`${prefix}${prop}`);
+      if (value === null) return void 0;
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    },
+    set(_target, prop, value) {
+      try {
+        const stringValue = JSON.stringify(value);
+        safeStorage.setItem(`${prefix}${prop}`, stringValue);
+        return true;
+      } catch (error) {
+        console.error(`TypedProxy: Failed to save ${prop}`, error);
+        return true;
+      }
+    },
+    has(_target, prop) {
+      return safeStorage.getItem(`${prefix}${prop}`) !== null;
+    },
+    deleteProperty(_target, prop) {
+      const key = `${prefix}${String(prop)}`;
+      safeStorage.removeItem(key);
+      return true;
+    }
+  });
+}
+var version = "1.0.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  oto,
+  version
+});

package/dist/index.mjs

@@ -0,0 +1,64 @@
+// src/index.ts
+function oto(options = {}) {
+  const { prefix = "", type = "local" } = options;
+  const storage = typeof window !== "undefined" ? type === "session" ? window.sessionStorage : window.localStorage : null;
+  const safeStorage = storage || {
+    getItem: () => null,
+    setItem: () => {
+    },
+    removeItem: () => {
+    },
+    clear: () => {
+    },
+    key: () => null,
+    get length() {
+      return 0;
+    }
+  };
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop === "clearAll") {
+        return () => {
+          const keys = [];
+          for (let i = 0; i < safeStorage.length; i++) {
+            const key = safeStorage.key(i);
+            if (key) keys.push(key);
+          }
+          keys.forEach((key) => {
+            if (key.startsWith(prefix)) safeStorage.removeItem(key);
+          });
+        };
+      }
+      const value = safeStorage.getItem(`${prefix}${prop}`);
+      if (value === null) return void 0;
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value;
+      }
+    },
+    set(_target, prop, value) {
+      try {
+        const stringValue = JSON.stringify(value);
+        safeStorage.setItem(`${prefix}${prop}`, stringValue);
+        return true;
+      } catch (error) {
+        console.error(`TypedProxy: Failed to save ${prop}`, error);
+        return true;
+      }
+    },
+    has(_target, prop) {
+      return safeStorage.getItem(`${prefix}${prop}`) !== null;
+    },
+    deleteProperty(_target, prop) {
+      const key = `${prefix}${String(prop)}`;
+      safeStorage.removeItem(key);
+      return true;
+    }
+  });
+}
+var version = "1.0.0";
+export {
+  oto,
+  version
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "oto-storage",
+  "version": "0.1.1",
+  "description": "A lightweight, type-safe wrapper for localStorage and sessionStorage using the Proxy API.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "preview": "vite preview"
+  },
+  "keywords": [
+    "typescript",
+    "localstorage",
+    "sessionstorage",
+    "proxy",
+    "type-safe",
+    "dx",
+    "storage-wrapper"
+  ],
+  "author": "Diomari Madulara",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diomari/oto-storage.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.2",
+    "jsdom": "^24.0.0",
+    "tsup": "^8.0.1",
+    "vite": "^5.1.0"
+  }
+}