@carddb/browser 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { Cache } from '@carddb/core';
+export * from '@carddb/client';
+
+/**
+ * Browser-based cache implementations using localStorage/sessionStorage
+ */
+
+type StorageType = 'localStorage' | 'sessionStorage';
+/**
+ * Browser cache using localStorage or sessionStorage.
+ *
+ * Uses localStorage by default for persistent caching across sessions.
+ * Use sessionStorage for per-session caching that clears when the tab is closed.
+ *
+ * @example localStorage (default, persistent)
+ * import { CardDBClient, BrowserCache } from '@carddb/browser'
+ *
+ * const client = new CardDBClient({
+ *   cache: new BrowserCache(),
+ *   cacheTtl: 300 // 5 minutes
+ * })
+ *
+ * @example sessionStorage (per-session)
+ * import { CardDBClient, BrowserCache } from '@carddb/browser'
+ *
+ * const client = new CardDBClient({
+ *   cache: new BrowserCache({ storage: 'sessionStorage' }),
+ *   cacheTtl: 300
+ * })
+ *
+ * @example Custom prefix
+ * const cache = new BrowserCache({ prefix: 'myapp:carddb:' })
+ */
+declare class BrowserCache implements Cache {
+    private storage;
+    private prefix;
+    constructor(options?: {
+        storage?: StorageType;
+        prefix?: string;
+    });
+    /**
+     * Get a value from the cache
+     */
+    get<T>(key: string): T | null;
+    /**
+     * Set a value in the cache
+     *
+     * @param key - The cache key
+     * @param value - The value to cache (must be JSON-serializable)
+     * @param ttl - Time to live in seconds (optional, undefined = no expiry)
+     */
+    set<T>(key: string, value: T, ttl?: number): void;
+    /**
+     * Delete a value from the cache
+     */
+    delete(key: string): void;
+    /**
+     * Clear all CardDB cached values (only keys with our prefix)
+     */
+    clear(): void;
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Get approximate number of cached entries (only counts our prefixed keys)
+     */
+    get size(): number;
+    /**
+     * Clean up expired entries
+     * Call this periodically if you want to reclaim storage space from expired entries
+     */
+    cleanup(): void;
+}
+
+export { BrowserCache };

package/dist/index.js

@@ -0,0 +1,119 @@
+export * from '@carddb/client';
+
+// src/cache.ts
+var BrowserCache = class {
+  storage;
+  prefix;
+  constructor(options = {}) {
+    const storageType = options.storage ?? "localStorage";
+    this.storage = storageType === "sessionStorage" ? globalThis.sessionStorage : globalThis.localStorage;
+    this.prefix = options.prefix ?? "carddb:";
+  }
+  /**
+   * Get a value from the cache
+   */
+  get(key) {
+    try {
+      const raw = this.storage.getItem(this.prefix + key);
+      if (!raw) return null;
+      const entry = JSON.parse(raw);
+      if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+        this.storage.removeItem(this.prefix + key);
+        return null;
+      }
+      return entry.value;
+    } catch {
+      this.storage.removeItem(this.prefix + key);
+      return null;
+    }
+  }
+  /**
+   * Set a value in the cache
+   *
+   * @param key - The cache key
+   * @param value - The value to cache (must be JSON-serializable)
+   * @param ttl - Time to live in seconds (optional, undefined = no expiry)
+   */
+  set(key, value, ttl) {
+    try {
+      const entry = {
+        value,
+        expiresAt: ttl !== void 0 ? Date.now() + ttl * 1e3 : null
+      };
+      this.storage.setItem(this.prefix + key, JSON.stringify(entry));
+    } catch (e) {
+      console.warn("[CardDB] Failed to write to cache:", e);
+    }
+  }
+  /**
+   * Delete a value from the cache
+   */
+  delete(key) {
+    this.storage.removeItem(this.prefix + key);
+  }
+  /**
+   * Clear all CardDB cached values (only keys with our prefix)
+   */
+  clear() {
+    const keysToRemove = [];
+    for (let i = 0; i < this.storage.length; i++) {
+      const key = this.storage.key(i);
+      if (key && key.startsWith(this.prefix)) {
+        keysToRemove.push(key);
+      }
+    }
+    for (const key of keysToRemove) {
+      this.storage.removeItem(key);
+    }
+  }
+  /**
+   * Check if a key exists and is not expired
+   */
+  has(key) {
+    return this.get(key) !== null;
+  }
+  /**
+   * Get approximate number of cached entries (only counts our prefixed keys)
+   */
+  get size() {
+    let count = 0;
+    for (let i = 0; i < this.storage.length; i++) {
+      const key = this.storage.key(i);
+      if (key && key.startsWith(this.prefix)) {
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Clean up expired entries
+   * Call this periodically if you want to reclaim storage space from expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    const keysToRemove = [];
+    for (let i = 0; i < this.storage.length; i++) {
+      const fullKey = this.storage.key(i);
+      if (fullKey && fullKey.startsWith(this.prefix)) {
+        try {
+          const raw = this.storage.getItem(fullKey);
+          if (raw) {
+            const entry = JSON.parse(raw);
+            if (entry.expiresAt !== null && now > entry.expiresAt) {
+              keysToRemove.push(fullKey);
+            }
+          }
+        } catch {
+          keysToRemove.push(fullKey);
+        }
+      }
+    }
+    for (const key of keysToRemove) {
+      this.storage.removeItem(key);
+    }
+  }
+};
+
+export { BrowserCache };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cache.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Browser-based cache implementations using localStorage/sessionStorage\n */\n\nimport type { Cache } from '@carddb/core'\n\ninterface CacheEntry<T> {\n  value: T\n  expiresAt: number | null\n}\n\ntype StorageType = 'localStorage' | 'sessionStorage'\n\n/**\n * Browser cache using localStorage or sessionStorage.\n *\n * Uses localStorage by default for persistent caching across sessions.\n * Use sessionStorage for per-session caching that clears when the tab is closed.\n *\n * @example localStorage (default, persistent)\n * import { CardDBClient, BrowserCache } from '@carddb/browser'\n *\n * const client = new CardDBClient({\n *   cache: new BrowserCache(),\n *   cacheTtl: 300 // 5 minutes\n * })\n *\n * @example sessionStorage (per-session)\n * import { CardDBClient, BrowserCache } from '@carddb/browser'\n *\n * const client = new CardDBClient({\n *   cache: new BrowserCache({ storage: 'sessionStorage' }),\n *   cacheTtl: 300\n * })\n *\n * @example Custom prefix\n * const cache = new BrowserCache({ prefix: 'myapp:carddb:' })\n */\nexport class BrowserCache implements Cache {\n  private storage: Storage\n  private prefix: string\n\n  constructor(options: { storage?: StorageType; prefix?: string } = {}) {\n    const storageType = options.storage ?? 'localStorage'\n    this.storage =\n      storageType === 'sessionStorage' ? globalThis.sessionStorage : globalThis.localStorage\n    this.prefix = options.prefix ?? 'carddb:'\n  }\n\n  /**\n   * Get a value from the cache\n   */\n  get<T>(key: string): T | null {\n    try {\n      const raw = this.storage.getItem(this.prefix + key)\n      if (!raw) return null\n\n      const entry = JSON.parse(raw) as CacheEntry<T>\n\n      // Check if expired\n      if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {\n        this.storage.removeItem(this.prefix + key)\n        return null\n      }\n\n      return entry.value\n    } catch {\n      // If parsing fails, remove the invalid entry\n      this.storage.removeItem(this.prefix + key)\n      return null\n    }\n  }\n\n  /**\n   * Set a value in the cache\n   *\n   * @param key - The cache key\n   * @param value - The value to cache (must be JSON-serializable)\n   * @param ttl - Time to live in seconds (optional, undefined = no expiry)\n   */\n  set<T>(key: string, value: T, ttl?: number): void {\n    try {\n      const entry: CacheEntry<T> = {\n        value,\n        expiresAt: ttl !== undefined ? Date.now() + ttl * 1000 : null,\n      }\n      this.storage.setItem(this.prefix + key, JSON.stringify(entry))\n    } catch (e) {\n      // Storage might be full or disabled - silently fail\n      // In the future, we could implement LRU eviction here\n      console.warn('[CardDB] Failed to write to cache:', e)\n    }\n  }\n\n  /**\n   * Delete a value from the cache\n   */\n  delete(key: string): void {\n    this.storage.removeItem(this.prefix + key)\n  }\n\n  /**\n   * Clear all CardDB cached values (only keys with our prefix)\n   */\n  clear(): void {\n    const keysToRemove: string[] = []\n    for (let i = 0; i < this.storage.length; i++) {\n      const key = this.storage.key(i)\n      if (key && key.startsWith(this.prefix)) {\n        keysToRemove.push(key)\n      }\n    }\n    for (const key of keysToRemove) {\n      this.storage.removeItem(key)\n    }\n  }\n\n  /**\n   * Check if a key exists and is not expired\n   */\n  has(key: string): boolean {\n    return this.get(key) !== null\n  }\n\n  /**\n   * Get approximate number of cached entries (only counts our prefixed keys)\n   */\n  get size(): number {\n    let count = 0\n    for (let i = 0; i < this.storage.length; i++) {\n      const key = this.storage.key(i)\n      if (key && key.startsWith(this.prefix)) {\n        count++\n      }\n    }\n    return count\n  }\n\n  /**\n   * Clean up expired entries\n   * Call this periodically if you want to reclaim storage space from expired entries\n   */\n  cleanup(): void {\n    const now = Date.now()\n    const keysToRemove: string[] = []\n\n    for (let i = 0; i < this.storage.length; i++) {\n      const fullKey = this.storage.key(i)\n      if (fullKey && fullKey.startsWith(this.prefix)) {\n        try {\n          const raw = this.storage.getItem(fullKey)\n          if (raw) {\n            const entry = JSON.parse(raw) as CacheEntry<unknown>\n            if (entry.expiresAt !== null && now > entry.expiresAt) {\n              keysToRemove.push(fullKey)\n            }\n          }\n        } catch {\n          // Invalid entry, remove it\n          keysToRemove.push(fullKey)\n        }\n      }\n    }\n\n    for (const key of keysToRemove) {\n      this.storage.removeItem(key)\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@carddb/browser",
+  "version": "0.1.0",
+  "description": "CardDB client for browsers",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": ["carddb", "api", "client", "graphql", "card-games", "browser", "web"],
+  "author": "CardDB Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xtda/carddb-js.git",
+    "directory": "packages/browser"
+  },
+  "homepage": "https://github.com/xtda/carddb-js#readme",
+  "bugs": {
+    "url": "https://github.com/xtda/carddb-js/issues"
+  },
+  "dependencies": {
+    "@carddb/client": "0.1.0",
+    "@carddb/core": "0.1.0"
+  },
+  "sideEffects": false
+}