oto-storage 0.3.2 → 0.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Diomari Madulara
+Copyright (c) 2025 Diomari Madulara (https://diom.dev)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -23,6 +23,29 @@ Or with pnpm:
 pnpm add oto-storage
 ```
 
+### 📚 Documentation Site (VitePress)
+
+This repo includes a VitePress documentation site in `/docs`.
+Live documentation: [https://oto.diom.dev](https://oto.diom.dev)
+
+```bash
+# Run docs locally
+npm run docs:dev
+
+# Build static docs
+npm run docs:build
+
+# Preview built docs
+npm run docs:preview
+```
+
+Cloudflare Pages deployment settings:
+
+- Project root: `/` (repo root)
+- Build command: `npm run docs:build`
+- Output directory: `docs/.vitepress/dist`
+- Environment variable (optional analytics): `GA_MEASUREMENT_ID=G-XXXXXXXXXX`
+
 ### ⚡ 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.
@@ -53,6 +76,8 @@ Oto storage uses the JavaScript Proxy API to let you interact with browser stora
 
 - **TTL / Expiration**: Set automatic expiration for stored values.
 
+- **Custom Encryption Hooks**: Encrypt/decrypt stored values with your own sync crypto callbacks.
+
 ### 🚀 Quick Start
 
 **_1. Define your Schema_**
@@ -308,6 +333,44 @@ storage.user = { id: "1", name: "Alice" };
 storage.user.name = "Bob"; // Updates are also TTL-protected
 ```
 
+**Encryption**
+
+Use custom synchronous `encrypt`/`decrypt` hooks to protect stored payloads at rest.
+Security warning: `btoa`/`atob` is encoding, not cryptographic encryption. Use `encryption.encrypt`/`encryption.decrypt` with a real cipher (for example Web Crypto AES-GCM) in production.
+
+```typescript
+interface SecureStorage {
+  token: string;
+  profile: { id: string; name: string };
+}
+
+const keyPrefix = "my-secret-key:";
+const secure = oto<SecureStorage>({
+  prefix: "secure-",
+  encryption: {
+    encrypt: (plainText) => btoa(`${keyPrefix}${plainText}`),
+    decrypt: (cipherText) => {
+      const decoded = atob(cipherText);
+      if (!decoded.startsWith(keyPrefix)) {
+        throw new Error("Invalid encryption key");
+      }
+      return decoded.slice(keyPrefix.length);
+    },
+    migrate: true, // Optional: auto-wrap existing plain JSON entries on read
+  },
+});
+
+secure.token = "abc123";
+console.log(secure.token); // "abc123"
+```
+
+`encryption.migrate` helps adopt encryption without a one-time migration script by upgrading plain JSON entries as they are read.
+Reserved keys note: `__oto_encrypted` and `__oto_payload` are used by the encryption envelope. If your stored object uses both keys with the same shape, it will be treated as encrypted data by `readStoredValue`/`isEncryptedWrapper`.
+
+Encryption + TTL work together automatically. Expired encrypted entries are deleted on access, just like non-encrypted TTL values.
+
+Security note: this feature protects data at rest in storage, but it does not protect against active XSS (malicious runtime code can access your encryption callbacks and decrypted values).
+
 **Combining Defaults and TTL**
 
 Use both features together for powerful patterns like session management:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oto-storage",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "A lightweight, type-safe wrapper for localStorage and sessionStorage using the Proxy API.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -22,7 +22,10 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs && node scripts/inject-ga.mjs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "typescript",
@@ -33,17 +36,19 @@
     "dx",
     "storage-wrapper"
   ],
-  "author": "Diomari Madulara",
+  "author": "Diomari Madulara (https://diom.dev)",
   "license": "MIT",
+  "homepage": "https://oto.diom.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/diomari/oto-storage"
+    "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"
+    "vite": "^5.1.0",
+    "vitepress": "^1.6.4"
   }
 }