@carddb/node 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @carddb/node
+
+CardDB client for Node.js, Bun, and Deno.
+
+## Installation
+
+```bash
+npm install @carddb/node
+# or
+bun add @carddb/node
+# or
+deno add npm:@carddb/node
+```
+
+## Quick Start
+
+```typescript
+import { CardDBClient, MemoryCache, gte, ilike } from '@carddb/node'
+
+const client = new CardDBClient({
+  apiKey: 'carddb_xxx...', // Optional, increases rate limits
+  cache: new MemoryCache(), // Optional in-memory 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)
+}
+```
+
+## MemoryCache
+
+Simple in-memory cache with TTL support:
+
+```typescript
+import { MemoryCache } from '@carddb/node'
+
+const cache = new MemoryCache()
+
+// Use with client
+const client = new CardDBClient({
+  cache,
+  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 entries
+```
+
+For production multi-instance deployments, consider implementing a Redis-based cache using the `Cache` interface.
+
+## Full Documentation
+
+See the [main README](../../README.md) for complete documentation.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+var client = require('@carddb/client');
+
+// src/cache.ts
+var MemoryCache = class {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Get a value from the cache
+   */
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  /**
+   * Set a value in the cache
+   *
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds (optional, undefined = no expiry)
+   */
+  set(key, value, ttl) {
+    const expiresAt = ttl !== void 0 ? Date.now() + ttl * 1e3 : null;
+    this.store.set(key, { value, expiresAt });
+  }
+  /**
+   * Delete a value from the cache
+   */
+  delete(key) {
+    this.store.delete(key);
+  }
+  /**
+   * Clear all cached values
+   */
+  clear() {
+    this.store.clear();
+  }
+  /**
+   * Check if a key exists and is not expired
+   */
+  has(key) {
+    return this.get(key) !== null;
+  }
+  /**
+   * Get the number of entries (including expired ones that haven't been cleaned up)
+   */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * Clean up expired entries
+   * Call this periodically if you want to reclaim memory from expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.expiresAt !== null && now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+};
+
+exports.MemoryCache = MemoryCache;
+Object.keys(client).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return client[k]; }
+  });
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cache.ts"],"names":[],"mappings":";;;;;AAiCO,IAAM,cAAN,MAAmC;AAAA,EAChC,KAAA,uBAAY,GAAA,EAAiC;AAAA;AAAA;AAAA;AAAA,EAKrD,IAAO,GAAA,EAAuB;AAC5B,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,GAAG,CAAA;AAChC,IAAA,IAAI,CAAC,OAAO,OAAO,IAAA;AAGnB,IAAA,IAAI,MAAM,SAAA,KAAc,IAAA,IAAQ,KAAK,GAAA,EAAI,GAAI,MAAM,SAAA,EAAW;AAC5D,MAAA,IAAA,CAAK,KAAA,CAAM,OAAO,GAAG,CAAA;AACrB,MAAA,OAAO,IAAA;AAAA,IACT;AAEA,IAAA,OAAO,KAAA,CAAM,KAAA;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA,CAAO,GAAA,EAAa,KAAA,EAAU,GAAA,EAAoB;AAChD,IAAA,MAAM,YAAY,GAAA,KAAQ,MAAA,GAAY,KAAK,GAAA,EAAI,GAAI,MAAM,GAAA,GAAO,IAAA;AAChE,IAAA,IAAA,CAAK,MAAM,GAAA,CAAI,GAAA,EAAK,EAAE,KAAA,EAAO,WAAW,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,GAAA,EAAmB;AACxB,IAAA,IAAA,CAAK,KAAA,CAAM,OAAO,GAAG,CAAA;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA,EAKA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,MAAM,KAAA,EAAM;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,GAAA,EAAsB;AACxB,IAAA,OAAO,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,KAAM,IAAA;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,IAAA,GAAe;AACjB,IAAA,OAAO,KAAK,KAAA,CAAM,IAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAA,GAAgB;AACd,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,IAAA,CAAK,KAAA,CAAM,SAAQ,EAAG;AAC/C,MAAA,IAAI,KAAA,CAAM,SAAA,KAAc,IAAA,IAAQ,GAAA,GAAM,MAAM,SAAA,EAAW;AACrD,QAAA,IAAA,CAAK,KAAA,CAAM,OAAO,GAAG,CAAA;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AACF","file":"index.cjs","sourcesContent":["/**\n * In-memory cache implementation with TTL support for Node.js\n */\n\nimport type { Cache } from '@carddb/core'\n\ninterface CacheEntry<T> {\n  value: T\n  expiresAt: number | null\n}\n\n/**\n * Simple in-memory cache with TTL support.\n * Suitable for server-side applications where memory caching is appropriate.\n *\n * For production use with multiple instances, consider using Redis or another\n * distributed cache that implements the Cache interface.\n *\n * @example\n * import { CardDBClient, MemoryCache } from '@carddb/node'\n *\n * const client = new CardDBClient({\n *   cache: new MemoryCache(),\n *   cacheTtl: 300 // 5 minutes\n * })\n *\n * @example Manual usage\n * const cache = new MemoryCache()\n * cache.set('key', 'value', 60) // expires in 60 seconds\n * cache.get('key') // => 'value'\n * // After 60 seconds...\n * cache.get('key') // => null\n */\nexport class MemoryCache implements Cache {\n  private store = new Map<string, CacheEntry<unknown>>()\n\n  /**\n   * Get a value from the cache\n   */\n  get<T>(key: string): T | null {\n    const entry = this.store.get(key) as CacheEntry<T> | undefined\n    if (!entry) return null\n\n    // Check if expired\n    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {\n      this.store.delete(key)\n      return null\n    }\n\n    return entry.value\n  }\n\n  /**\n   * Set a value in the cache\n   *\n   * @param key - The cache key\n   * @param value - The value to cache\n   * @param ttl - Time to live in seconds (optional, undefined = no expiry)\n   */\n  set<T>(key: string, value: T, ttl?: number): void {\n    const expiresAt = ttl !== undefined ? Date.now() + ttl * 1000 : null\n    this.store.set(key, { value, expiresAt })\n  }\n\n  /**\n   * Delete a value from the cache\n   */\n  delete(key: string): void {\n    this.store.delete(key)\n  }\n\n  /**\n   * Clear all cached values\n   */\n  clear(): void {\n    this.store.clear()\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 the number of entries (including expired ones that haven't been cleaned up)\n   */\n  get size(): number {\n    return this.store.size\n  }\n\n  /**\n   * Clean up expired entries\n   * Call this periodically if you want to reclaim memory from expired entries\n   */\n  cleanup(): void {\n    const now = Date.now()\n    for (const [key, entry] of this.store.entries()) {\n      if (entry.expiresAt !== null && now > entry.expiresAt) {\n        this.store.delete(key)\n      }\n    }\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,67 @@
+import { Cache } from '@carddb/core';
+export * from '@carddb/client';
+
+/**
+ * In-memory cache implementation with TTL support for Node.js
+ */
+
+/**
+ * Simple in-memory cache with TTL support.
+ * Suitable for server-side applications where memory caching is appropriate.
+ *
+ * For production use with multiple instances, consider using Redis or another
+ * distributed cache that implements the Cache interface.
+ *
+ * @example
+ * import { CardDBClient, MemoryCache } from '@carddb/node'
+ *
+ * const client = new CardDBClient({
+ *   cache: new MemoryCache(),
+ *   cacheTtl: 300 // 5 minutes
+ * })
+ *
+ * @example Manual usage
+ * const cache = new MemoryCache()
+ * cache.set('key', 'value', 60) // expires in 60 seconds
+ * cache.get('key') // => 'value'
+ * // After 60 seconds...
+ * cache.get('key') // => null
+ */
+declare class MemoryCache implements Cache {
+    private store;
+    /**
+     * 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
+     * @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 cached values
+     */
+    clear(): void;
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Get the number of entries (including expired ones that haven't been cleaned up)
+     */
+    get size(): number;
+    /**
+     * Clean up expired entries
+     * Call this periodically if you want to reclaim memory from expired entries
+     */
+    cleanup(): void;
+}
+
+export { MemoryCache };

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { Cache } from '@carddb/core';
+export * from '@carddb/client';
+
+/**
+ * In-memory cache implementation with TTL support for Node.js
+ */
+
+/**
+ * Simple in-memory cache with TTL support.
+ * Suitable for server-side applications where memory caching is appropriate.
+ *
+ * For production use with multiple instances, consider using Redis or another
+ * distributed cache that implements the Cache interface.
+ *
+ * @example
+ * import { CardDBClient, MemoryCache } from '@carddb/node'
+ *
+ * const client = new CardDBClient({
+ *   cache: new MemoryCache(),
+ *   cacheTtl: 300 // 5 minutes
+ * })
+ *
+ * @example Manual usage
+ * const cache = new MemoryCache()
+ * cache.set('key', 'value', 60) // expires in 60 seconds
+ * cache.get('key') // => 'value'
+ * // After 60 seconds...
+ * cache.get('key') // => null
+ */
+declare class MemoryCache implements Cache {
+    private store;
+    /**
+     * 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
+     * @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 cached values
+     */
+    clear(): void;
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Get the number of entries (including expired ones that haven't been cleaned up)
+     */
+    get size(): number;
+    /**
+     * Clean up expired entries
+     * Call this periodically if you want to reclaim memory from expired entries
+     */
+    cleanup(): void;
+}
+
+export { MemoryCache };

package/dist/index.js

@@ -0,0 +1,69 @@
+export * from '@carddb/client';
+
+// src/cache.ts
+var MemoryCache = class {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Get a value from the cache
+   */
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  /**
+   * Set a value in the cache
+   *
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds (optional, undefined = no expiry)
+   */
+  set(key, value, ttl) {
+    const expiresAt = ttl !== void 0 ? Date.now() + ttl * 1e3 : null;
+    this.store.set(key, { value, expiresAt });
+  }
+  /**
+   * Delete a value from the cache
+   */
+  delete(key) {
+    this.store.delete(key);
+  }
+  /**
+   * Clear all cached values
+   */
+  clear() {
+    this.store.clear();
+  }
+  /**
+   * Check if a key exists and is not expired
+   */
+  has(key) {
+    return this.get(key) !== null;
+  }
+  /**
+   * Get the number of entries (including expired ones that haven't been cleaned up)
+   */
+  get size() {
+    return this.store.size;
+  }
+  /**
+   * Clean up expired entries
+   * Call this periodically if you want to reclaim memory from expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.expiresAt !== null && now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+};
+
+export { MemoryCache };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cache.ts"],"names":[],"mappings":";;;AAiCO,IAAM,cAAN,MAAmC;AAAA,EAChC,KAAA,uBAAY,GAAA,EAAiC;AAAA;AAAA;AAAA;AAAA,EAKrD,IAAO,GAAA,EAAuB;AAC5B,IAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,GAAG,CAAA;AAChC,IAAA,IAAI,CAAC,OAAO,OAAO,IAAA;AAGnB,IAAA,IAAI,MAAM,SAAA,KAAc,IAAA,IAAQ,KAAK,GAAA,EAAI,GAAI,MAAM,SAAA,EAAW;AAC5D,MAAA,IAAA,CAAK,KAAA,CAAM,OAAO,GAAG,CAAA;AACrB,MAAA,OAAO,IAAA;AAAA,IACT;AAEA,IAAA,OAAO,KAAA,CAAM,KAAA;AAAA,EACf;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA,CAAO,GAAA,EAAa,KAAA,EAAU,GAAA,EAAoB;AAChD,IAAA,MAAM,YAAY,GAAA,KAAQ,MAAA,GAAY,KAAK,GAAA,EAAI,GAAI,MAAM,GAAA,GAAO,IAAA;AAChE,IAAA,IAAA,CAAK,MAAM,GAAA,CAAI,GAAA,EAAK,EAAE,KAAA,EAAO,WAAW,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,GAAA,EAAmB;AACxB,IAAA,IAAA,CAAK,KAAA,CAAM,OAAO,GAAG,CAAA;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA,EAKA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,MAAM,KAAA,EAAM;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,GAAA,EAAsB;AACxB,IAAA,OAAO,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA,KAAM,IAAA;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,IAAA,GAAe;AACjB,IAAA,OAAO,KAAK,KAAA,CAAM,IAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAA,GAAgB;AACd,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AACrB,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,IAAA,CAAK,KAAA,CAAM,SAAQ,EAAG;AAC/C,MAAA,IAAI,KAAA,CAAM,SAAA,KAAc,IAAA,IAAQ,GAAA,GAAM,MAAM,SAAA,EAAW;AACrD,QAAA,IAAA,CAAK,KAAA,CAAM,OAAO,GAAG,CAAA;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AACF","file":"index.js","sourcesContent":["/**\n * In-memory cache implementation with TTL support for Node.js\n */\n\nimport type { Cache } from '@carddb/core'\n\ninterface CacheEntry<T> {\n  value: T\n  expiresAt: number | null\n}\n\n/**\n * Simple in-memory cache with TTL support.\n * Suitable for server-side applications where memory caching is appropriate.\n *\n * For production use with multiple instances, consider using Redis or another\n * distributed cache that implements the Cache interface.\n *\n * @example\n * import { CardDBClient, MemoryCache } from '@carddb/node'\n *\n * const client = new CardDBClient({\n *   cache: new MemoryCache(),\n *   cacheTtl: 300 // 5 minutes\n * })\n *\n * @example Manual usage\n * const cache = new MemoryCache()\n * cache.set('key', 'value', 60) // expires in 60 seconds\n * cache.get('key') // => 'value'\n * // After 60 seconds...\n * cache.get('key') // => null\n */\nexport class MemoryCache implements Cache {\n  private store = new Map<string, CacheEntry<unknown>>()\n\n  /**\n   * Get a value from the cache\n   */\n  get<T>(key: string): T | null {\n    const entry = this.store.get(key) as CacheEntry<T> | undefined\n    if (!entry) return null\n\n    // Check if expired\n    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {\n      this.store.delete(key)\n      return null\n    }\n\n    return entry.value\n  }\n\n  /**\n   * Set a value in the cache\n   *\n   * @param key - The cache key\n   * @param value - The value to cache\n   * @param ttl - Time to live in seconds (optional, undefined = no expiry)\n   */\n  set<T>(key: string, value: T, ttl?: number): void {\n    const expiresAt = ttl !== undefined ? Date.now() + ttl * 1000 : null\n    this.store.set(key, { value, expiresAt })\n  }\n\n  /**\n   * Delete a value from the cache\n   */\n  delete(key: string): void {\n    this.store.delete(key)\n  }\n\n  /**\n   * Clear all cached values\n   */\n  clear(): void {\n    this.store.clear()\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 the number of entries (including expired ones that haven't been cleaned up)\n   */\n  get size(): number {\n    return this.store.size\n  }\n\n  /**\n   * Clean up expired entries\n   * Call this periodically if you want to reclaim memory from expired entries\n   */\n  cleanup(): void {\n    const now = Date.now()\n    for (const [key, entry] of this.store.entries()) {\n      if (entry.expiresAt !== null && now > entry.expiresAt) {\n        this.store.delete(key)\n      }\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@carddb/node",
+  "version": "0.1.0",
+  "description": "CardDB client for Node.js, Bun, and Deno",
+  "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", "node", "bun", "deno"],
+  "author": "CardDB Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xtda/carddb-js.git",
+    "directory": "packages/node"
+  },
+  "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"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false
+}