@carddb/browser

CardDB client for browsers.

Installation

npm install @carddb/browser
# or
bun add @carddb/browser

Quick Start

import { CardDBClient, BrowserCache, gte, ilike } from '@carddb/browser'

const client = new CardDBClient({
  apiKey: 'carddb_xxx...', // Optional, increases rate limits
  cache: new BrowserCache(), // Optional localStorage-based caching
  defaultPublisher: 'pokemon',
  defaultGame: 'tcg',
})

// Search for cards with filtering
const cards = await client.records.search({
  datasetKey: 'cards',
  filter: (f) => f.where('hp', gte(100)).where('name', ilike('%pikachu%')),
})

// Iterate through all results (auto-paginates)
for await (const card of cards) {
  console.log(card.data.name)
}

BrowserCache

Browser-based cache using localStorage or sessionStorage:

import { BrowserCache } from '@carddb/browser'

// localStorage (default, persistent across sessions)
const persistentCache = new BrowserCache()

// sessionStorage (cleared when tab closes)
const sessionCache = new BrowserCache({ storage: 'sessionStorage' })

// Custom key prefix (default: 'carddb:')
const customCache = new BrowserCache({ prefix: 'myapp:carddb:' })

// Use with client
const client = new CardDBClient({
  cache: persistentCache,
  cacheTtl: 300, // 5 minutes default
  cacheTtls: {
    publishers: 3600, // 1 hour for publishers
    records: 60, // 1 minute for records
  },
})

// Manual cache management
cache.cleanup() // Remove expired entries
cache.clear() // Clear all CardDB entries
cache.size // Number of cached entries

Bundle Size

The browser package is optimized for minimal bundle size. Tree-shaking is fully supported.

Full Documentation

See the main README for complete documentation.

License

MIT