oto-storage 0.2.0 → 0.4.0

package/README.md

@@ -49,6 +49,12 @@ Oto storage uses the JavaScript Proxy API to let you interact with browser stora
 
 - **Collision Protection**: Automatic key prefixing (namespacing).
 
+- **Default Values**: Define fallback values for missing keys with deep merge support.
+
+- **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_**
@@ -239,6 +245,139 @@ import { oto, version } from "oto-storage";
 console.log(`Using oto-storage v${version}`);
 ```
 
+**Default Values**
+
+Provide default values that are returned when keys don't exist in storage. Defaults support deep merging with stored values.
+
+```typescript
+interface AppStorage {
+  theme: "light" | "dark";
+  user: { name: string; role: string; active: boolean };
+}
+
+const storage = oto<AppStorage>({
+  prefix: "app-",
+  defaults: {
+    theme: "light",
+    user: { name: "Anonymous", role: "guest", active: false },
+  },
+});
+
+// Returns default when not set
+console.log(storage.theme); // "light"
+
+// Stored values override defaults
+storage.theme = "dark";
+console.log(storage.theme); // "dark"
+
+// Deep merge - partial updates preserve defaults
+storage.user = { name: "Alice" };  // Only set name
+console.log(storage.user);
+// { name: "Alice", role: "guest", active: false }
+
+// Access nested properties - stored value takes precedence over defaults
+console.log(storage.user.name); // "Alice" (stored value)
+```
+
+**TTL / Expiration**
+
+Automatically expire stored values after a specified time (in milliseconds). Expired keys are automatically deleted on access.
+
+```typescript
+interface SessionStorage {
+  token: string;
+  user: { id: string; name: string };
+}
+
+const storage = oto<SessionStorage>({
+  prefix: "session-",
+  ttl: 3600000, // 1 hour in milliseconds
+});
+
+// Store value - automatically wrapped with expiration
+storage.token = "abc123";
+
+// Value is accessible before expiration
+console.log(storage.token); // "abc123"
+
+// ... 1 hour later ...
+
+// Expired key is auto-deleted and returns undefined
+console.log(storage.token); // undefined
+
+// TTL works with nested objects too
+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:
+
+```typescript
+interface AuthStorage {
+  token: string | null;
+  user: { id: string; name: string } | null;
+}
+
+const auth = oto<AuthStorage>({
+  prefix: "auth-",
+  ttl: 3600000, // 1 hour
+  defaults: {
+    token: null,
+    user: null,
+  },
+});
+
+// Before login - returns defaults
+console.log(auth.token); // null
+
+// After login
+auth.token = "secret-token";
+auth.user = { id: "123", name: "Alice" };
+
+// ... after 1 hour (token expires) ...
+console.log(auth.token); // null (back to default)
+```
+
 ### 🛠️ Architecture Decisions
 
 **_Why Proxy?_**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oto-storage",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A lightweight, type-safe wrapper for localStorage and sessionStorage using the Proxy API.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -37,7 +37,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/diomari/oto-storage"
+    "url": "git+https://github.com/diomari/oto-storage.git"
   },
   "devDependencies": {
     "typescript": "^5.3.3",