lazypock 0.2.0 → 0.3.0

package/README.md

@@ -179,6 +179,7 @@ The main client class.
 | `storage` | `StorageAdapter` | `memoryStorage` | Custom storage adapter for token persistence |
 | `authStore` | `AuthStore` | auto-created | Explicit auth store instance |
 | `realtime` | `RealtimeService` | auto-created | Real-time service for WebSocket subscriptions |
+| `cache` | [`CacheConfig`](#query-cache) | disabled | Query-cache configuration (opt-in) |
 
 #### Auto-Cancellation Methods
 
@@ -186,6 +187,14 @@ The main client class.
 - `cancelRequest(requestKey)` — Abort a single pending request by key (default `HTTP_METHOD + path`)
 - `cancelAllRequests()` — Abort all pending requests
 
+#### Query-Cache Methods
+
+- `cache(config?)` — Enable/configure the query cache at runtime (see [Query Cache](#query-cache))
+- `clearCache()` — Drop every cached entry
+- `invalidateCache(namespace)` — Invalidate entries for a collection / custom namespace
+- `cacheStats()` — `{ hits, misses, entries }` cache statistics
+- `invalidateCacheOnRealtime(collection)` — Subscribe the cache to realtime events for a collection; returns an unsubscribe fn
+
 #### Authentication Methods
 
 - `login(email, password, collection?)` — Login as superuser or auth collection user
@@ -349,6 +358,104 @@ client.cancelRequest('GET /api/posts?page=1');
 client.cancelAllRequests();
 ```
 
+## Query Cache
+
+Lazypock has a built-in query cache for **GET** requests — disabled by default.
+It's useful for read-heavy UIs (lists, dashboards) to avoid hammering the server.
+
+### Enabling
+
+```typescript
+import { createClient } from "lazypock";
+
+const client = createClient({
+  baseUrl: "https://api.example.com",
+  cache: {
+    enabled: true,
+    defaultTTL: 30_000, // 30s
+    // store: myStorage, // optional: reuse any StorageAdapter (localStorage/AsyncStorage)
+  },
+});
+```
+
+When enabled, **all** GET requests are cached with the default TTL, and
+mutations (`create`/`update`/`delete`) automatically invalidate the affected
+collection's cached entries.
+
+### Per-request control
+
+```typescript
+// Cache this request (works even when the global cache is off)
+await client.collection('posts').getList(1, 20, { cache: true });
+
+// Bypass the cache — always fetch fresh (and don't store the result)
+const fresh = await client.collection('posts').getList(1, 20, { cache: false });
+
+// Custom TTL for this request
+await client.collection('posts').getOne('abc', { ttl: 120_000 });
+
+// Cache with a custom key (dedupe/override the default `METHOD path|token` key)
+await client.collection('posts').getList(1, 20, { cache: { ttl: 60_000, key: 'my-list' } });
+```
+
+### Prefix deletion (per-operation invalidation)
+
+Every cached entry is tagged with its operation and collection, so you can
+invalidate a whole class of caches without touching the rest:
+
+```typescript
+client.cache.deleteByPrefix('getList:posts'); // delete all getList cache for posts
+client.cache.deleteByPrefix('getOne:posts');  // delete all getOne cache for posts
+client.cache.deleteByPrefix('collections:getList'); // admin collection list caches
+```
+
+The `client.cache` namespace also exposes `invalidate(ns)`, `clear()`, `stats()`,
+and is callable to (re)configure (`client.cache({ enabled: true })`).
+
+### Invalidation
+
+```typescript
+// Mutations invalidate the collection automatically:
+await client.collection('posts').create({ title: 'New' });
+await client.collection('posts').getList(1, 20); // re-fetched (cache cleared)
+
+// Invalidate extra namespaces explicitly:
+await client.collection('posts').create(
+  { title: 'New' },
+  { invalidate: ['users'] },
+);
+
+// Manual / out-of-band invalidation:
+client.invalidateCache('posts');
+client.clearCache();
+```
+
+### Cache key scoping
+
+Cache keys are **scoped by auth token** — a logged-in user's cached data can
+never leak to another user (or to anonymous visitors). Logging out/in changes
+the token, so cached entries are naturally isolated per identity.
+
+### Realtime-driven invalidation
+
+```typescript
+// Keep the posts cache fresh: any create/update/delete event clears it.
+const stop = client.invalidateCacheOnRealtime('posts');
+// later:
+stop();
+```
+
+When a realtime event arrives for the collection, its cached entries are
+cleared so the next read fetches fresh data. This is **invalidate-only** —
+cached list payloads are never mutated in place (a filter/sort change could
+make an in-place patch serve wrong data).
+
+### Stats
+
+```typescript
+client.cacheStats(); // { hits, misses, entries }
+```
+
 ## Error Handling
 
 The SDK throws `ApiError` on non-2xx responses:

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   ApiError: () => ApiError,
   AuthStore: () => AuthStore,
+  CacheStore: () => CacheStore,
   CollectionService: () => CollectionService,
   CollectionsService: () => CollectionsService,
   FilesService: () => FilesService,
@@ -37,6 +38,7 @@ __export(index_exports, {
   getFileUrl: () => getFileUrl,
   getScaleUrl: () => getScaleUrl,
   getThumbUrl: () => getThumbUrl,
+  resolveCacheDirective: () => resolveCacheDirective,
   schemaFieldType: () => schemaFieldType,
   wsUrlFromBaseUrl: () => wsUrlFromBaseUrl
 });
@@ -53,6 +55,201 @@ var ApiError = class extends Error {
   }
 };
 
+// src/cache.ts
+var CacheStore = class {
+  constructor(config = {}) {
+    this.memory = /* @__PURE__ */ new Map();
+    this.hits = 0;
+    this.misses = 0;
+    this.namespaceEntries = /* @__PURE__ */ new Map();
+    /** Key → set of prefix tags registered for that key (e.g. `getList:posts`). */
+    this.prefixEntries = /* @__PURE__ */ new Map();
+    this.ttl = config.defaultTTL ?? 6e4;
+    this.persistence = config.store;
+    this.maxEntries = config.maxEntries ?? 500;
+  }
+  /** Resolve the effective TTL: request override → global default. */
+  resolveTTL(ttl) {
+    return ttl && ttl > 0 ? ttl : this.ttl;
+  }
+  /**
+   * Read a cached value. Fast sync path (memory) with async persistence
+   * fallback for adapters whose `get` returns a Promise.
+   * @param key Cache key (e.g. `"GET /posts?page=1"`).
+   * @returns The cached value, or undefined when absent/expired (the hit is
+   * cleared on expiry so a stale value is never served).
+   */
+  async get(key) {
+    const mem = this.memory.get(key);
+    if (mem !== void 0) {
+      if (Date.now() > mem.expiresAt) {
+        this.delete(key);
+        this.misses++;
+        return void 0;
+      }
+      this.memory.delete(key);
+      this.memory.set(key, mem);
+      this.hits++;
+      return mem.value;
+    }
+    if (this.persistence) {
+      const entry = await this.readPersisted(key);
+      if (entry) {
+        if (Date.now() > entry.expiresAt) {
+          this.delete(key);
+          this.misses++;
+          return void 0;
+        }
+        this.hits++;
+        return entry.value;
+      }
+    }
+    this.misses++;
+    return void 0;
+  }
+  /**
+   * Store a value.
+   * @param key Cache key.
+   * @param value The response payload.
+   * @param ttlOverride Optional TTL override (ms).
+   * @param namespace Optional namespace for group invalidation.
+   */
+  set(key, value, ttlOverride, namespace, tags) {
+    const expiresAt = Date.now() + this.resolveTTL(ttlOverride);
+    const entry = { value, expiresAt, namespace, tags };
+    this.memory.set(key, entry);
+    if (this.memory.size > this.maxEntries) {
+      const oldest = this.memory.keys().next().value;
+      if (oldest !== void 0) this.delete(oldest);
+    }
+    if (namespace) {
+      let keys = this.namespaceEntries.get(namespace);
+      if (!keys) {
+        keys = /* @__PURE__ */ new Set();
+        this.namespaceEntries.set(namespace, keys);
+      }
+      keys.add(key);
+    }
+    for (const tag of tags ?? []) {
+      let keys = this.prefixEntries.get(tag);
+      if (!keys) {
+        keys = /* @__PURE__ */ new Set();
+        this.prefixEntries.set(tag, keys);
+      }
+      keys.add(key);
+    }
+    if (this.persistence) {
+      void this.persistence.set(this.persistKey(key), JSON.stringify(entry));
+    }
+  }
+  /**
+   * Invalidate entries belonging to a namespace (e.g. a collection name).
+   * Also clears the namespace index entry.
+   */
+  invalidate(namespace) {
+    const keys = Array.from(this.namespaceEntries.get(namespace) ?? []);
+    for (const key of keys) this.delete(key);
+    this.namespaceEntries.delete(namespace);
+  }
+  /** Remove a single key. */
+  delete(key) {
+    const entry = this.memory.get(key);
+    if (entry?.namespace) {
+      const set = this.namespaceEntries.get(entry.namespace);
+      if (set) {
+        set.delete(key);
+        if (set.size === 0) this.namespaceEntries.delete(entry.namespace);
+      }
+    }
+    for (const tag of entry?.tags ?? []) {
+      const set = this.prefixEntries.get(tag);
+      if (set) {
+        set.delete(key);
+        if (set.size === 0) this.prefixEntries.delete(tag);
+      }
+    }
+    this.memory.delete(key);
+    if (this.persistence) {
+      void this.persistence.remove(this.persistKey(key));
+    }
+  }
+  /**
+   * Delete every entry whose key starts with `prefix`.
+   *
+   * Useful for fine-grained invalidation, e.g.:
+   * ```ts
+   * client.cache.deleteByPrefix('getList:posts'); // delete all getList cache
+   * client.cache.deleteByPrefix('getOne:posts');  // delete all getOne cache
+   * ```
+   */
+  deleteByPrefix(prefix) {
+    if (!prefix) return;
+    const tagged = this.prefixEntries.get(prefix);
+    if (tagged) {
+      for (const key of Array.from(tagged)) this.delete(key);
+      this.prefixEntries.delete(prefix);
+      return;
+    }
+    for (const key of Array.from(this.memory.keys())) {
+      if (key.startsWith(prefix)) this.delete(key);
+    }
+  }
+  /** Drop every cached entry (memory + persistence). */
+  clear() {
+    this.memory.clear();
+    this.namespaceEntries.clear();
+    this.prefixEntries.clear();
+  }
+  /** Cache hit/miss/entry statistics. */
+  stats() {
+    return { hits: this.hits, misses: this.misses, entries: this.memory.size };
+  }
+  persistKey(key) {
+    return "lazypock:cache:" + key;
+  }
+  async readPersisted(key) {
+    if (!this.persistence) return void 0;
+    const raw = await this.persistence.get(this.persistKey(key));
+    if (raw == null) return void 0;
+    try {
+      const entry = JSON.parse(raw);
+      this.memory.set(key, entry);
+      if (entry.namespace) {
+        let keys = this.namespaceEntries.get(entry.namespace);
+        if (!keys) {
+          keys = /* @__PURE__ */ new Set();
+          this.namespaceEntries.set(entry.namespace, keys);
+        }
+        keys.add(key);
+      }
+      for (const tag of entry.tags ?? []) {
+        let keys = this.prefixEntries.get(tag);
+        if (!keys) {
+          keys = /* @__PURE__ */ new Set();
+          this.prefixEntries.set(tag, keys);
+        }
+        keys.add(key);
+      }
+      return entry;
+    } catch {
+      void this.persistence.remove(this.persistKey(key));
+      return void 0;
+    }
+  }
+};
+function resolveCacheDirective(opts) {
+  if (!opts) return null;
+  if (typeof opts.ttl === "number" && opts.ttl > 0) {
+    return { enabled: true, ttl: opts.ttl };
+  }
+  const c = opts.cache;
+  if (c === void 0) return null;
+  if (c === true) return { enabled: true };
+  if (c === false) return { enabled: false };
+  if (typeof c === "number") return { enabled: true, ttl: c > 0 ? c : void 0 };
+  return { enabled: true, ttl: c.ttl, key: c.key };
+}
+
 // src/http.ts
 function isAbortError(err) {
   return err instanceof Error && (err.name === "AbortError" || err.message === "Aborted");
@@ -63,6 +260,8 @@ var HttpClient = class {
    * @param authStore The auth store providing the token for Authorization headers.
    */
   constructor(baseUrl, authStore) {
+    /** Master switch resolved from CacheConfig.enabled. */
+    this.cacheEnabled = false;
     /**
      * Abort controllers for in-flight requests, keyed by their cancellation key
      * (default `METHOD path`). A new request with the same key aborts the
@@ -75,6 +274,18 @@ var HttpClient = class {
     this.authStore = authStore;
     this.defaultFetch = globalThis.fetch.bind(globalThis);
   }
+  /**
+   * Attach a cache store + master switch.
+   * Called by the client constructor when cache config is present.
+   */
+  setCache(cache, enabled) {
+    this.cache = cache;
+    this.cacheEnabled = enabled;
+  }
+  /** Whether the global cache flag is on (requests opt in/out individually too). */
+  get cacheIsEnabled() {
+    return this.cacheEnabled;
+  }
   async refreshAuth() {
     const collection = this.authStore.collectionName;
     if (!collection) return null;
@@ -151,10 +362,25 @@ var HttpClient = class {
    * @throws {ApiError} On non-2xx responses or when the request is aborted
    * (aborted requests throw an `ApiError` with `isAbort === true`).
    */
+  /** Invalidate a namespace (collection name). No-op when cache is off. */
+  invalidateCache(namespace) {
+    this.cache?.invalidate(namespace);
+  }
+  /** Current cache statistics (hits/misses/entries), or null when disabled. */
+  cacheStats() {
+    return this.cache ? this.cache.stats() : null;
+  }
   async request(method, path, body, options) {
     if (this.authStore.isExpired && this.authStore.collectionName) {
       await this.refreshAuth();
     }
+    const cacheDirective = resolveCacheDirective(options);
+    const wantCache = cacheDirective !== null ? cacheDirective.enabled : this.cacheEnabled;
+    const cacheKey = method === "GET" && this.cache && wantCache ? this.cacheKeyFor(method, path, options?.params) : null;
+    if (cacheKey !== null) {
+      const hit = await this.cache?.get(cacheKey);
+      if (hit !== void 0) return hit;
+    }
     let requestKey = options?.requestKey === void 0 ? options?.cancelKey ?? `${method} ${path}` : options.requestKey;
     if (options?.autoCancel === false) requestKey = null;
     let controller = null;
@@ -238,8 +464,63 @@ var HttpClient = class {
         res.status
       );
     }
+    if (cacheKey !== null && this.cache) {
+      const namespace = this.namespaceFromPath(path);
+      const ttl = cacheDirective?.ttl;
+      const tags = this.cacheTagsFor(path, namespace);
+      this.cache.set(
+        cacheKey,
+        data,
+        ttl,
+        namespace ?? void 0,
+        tags
+      );
+    }
+    if (method !== "GET" && this.cache) {
+      const namespaces = /* @__PURE__ */ new Set();
+      const ns = this.namespaceFromPath(path);
+      if (ns) namespaces.add(ns);
+      for (const extra of options?.invalidate ?? []) {
+        if (extra) namespaces.add(extra);
+      }
+      for (const nsName of namespaces) this.cache.invalidate(nsName);
+    }
     return data;
   }
+  // ── Cache key/namespace helpers ──
+  /** Build a token-scoped cache key: `METHOD path|token-hash|params`. */
+  cacheKeyFor(method, path, params) {
+    const token = this.authStore.token || "anon";
+    const qs = params ? "?" + new URLSearchParams(params).toString() : "";
+    return `${method} ${path}${qs}|${token}`;
+  }
+  /** Best-effort namespace (collection name) from a REST path. */
+  namespaceFromPath(path) {
+    const clean = path.split("?")[0];
+    const parts = clean.split("/").filter(Boolean);
+    if (parts.length === 0) return void 0;
+    if (parts[0] === "collections" || parts[0] === "_superusers") {
+      return parts[0];
+    }
+    return parts[0];
+  }
+  /**
+   * Semantic prefix tags for `deleteByPrefix`, derived from the REST shape:
+   * - `/{collection}?...` → `getList:{collection}`
+   * - `/{collection}/{id}` → `getOne:{collection}`
+   * - `/collections?...` / `/collections/{id}` → `collections:getList` / `collections:getOne`
+   */
+  cacheTagsFor(path, namespace) {
+    if (!namespace) return [];
+    const clean = path.split("?")[0];
+    const parts = clean.split("/").filter(Boolean);
+    if (parts[0] === "collections" || parts[0] === "_superusers") {
+      const op2 = parts.length >= 2 ? "getOne" : "getList";
+      return [`${namespace}:${op2}`];
+    }
+    const op = parts.length >= 2 ? "getOne" : "getList";
+    return [`${op}:${namespace}`];
+  }
   /**
    * HTTP GET.
    * @param path URL path.
@@ -446,19 +727,42 @@ var CollectionService = class {
    * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
    */
   getList(page = 1, perPage = 30, options) {
-    const { requestKey, autoCancel, cancelKey, ...rest } = options ?? {};
+    const {
+      requestKey,
+      autoCancel,
+      cancelKey,
+      fetch,
+      headers,
+      signal,
+      cache,
+      ttl,
+      invalidate,
+      params,
+      ...queryParams
+    } = options ?? {};
     const qs = new URLSearchParams(
       Object.fromEntries(
         Object.entries({
           page: String(page),
           perPage: String(perPage),
-          ...rest
+          ...queryParams
         }).map(([k, v]) => [k, String(v)])
       )
     ).toString();
     return this.http.get(
       "/" + this.encodeId(this.collectionName) + "?" + qs,
-      { requestKey, autoCancel, cancelKey }
+      {
+        requestKey,
+        autoCancel,
+        cancelKey,
+        fetch,
+        headers,
+        signal,
+        cache,
+        ttl,
+        invalidate,
+        params
+      }
     );
   }
   /**
@@ -1291,6 +1595,50 @@ var LazypockClient = class {
    */
   constructor(options) {
     this.collectionCache = /* @__PURE__ */ new Map();
+    /** Namespace → realtime unsubscribe; used for realtime-driven invalidation. */
+    this.realtimeInvalidators = /* @__PURE__ */ new Map();
+    // ── Query cache (opt-in by default; opt-out per request) ──
+    /**
+     * Configure the query cache at runtime (also a namespace for cache
+     * management methods).
+     *
+     * ```ts
+     * client.cache({ enabled: true, defaultTTL: 30_000 });
+     * client.cache.deleteByPrefix('getList:posts');  // all list caches for posts
+     * client.cache.deleteByPrefix('getOne:posts');   // all one-record caches
+     * ```
+     *
+     * When enabled, GET requests cache their payload; mutations invalidate the
+     * affected collection automatically. Individual requests can opt out with
+     * `{ cache: false }` or override the TTL with `{ ttl: ms }`.
+     */
+    this.cache = Object.assign(
+      ((config) => {
+        if (!this.cacheStore) {
+          this.cacheStore = new CacheStore({
+            defaultTTL: config?.defaultTTL,
+            store: config?.store,
+            maxEntries: config?.maxEntries
+          });
+          this.http.setCache(this.cacheStore, config?.enabled ?? true);
+        } else {
+          if (config?.enabled !== void 0) {
+            this.http.setCache(this.cacheStore, config.enabled);
+          }
+        }
+        return this;
+      }),
+      {
+        deleteByPrefix: (prefix) => this.cacheStore?.deleteByPrefix(prefix),
+        invalidate: (namespace) => this.cacheStore?.invalidate(namespace),
+        clear: () => {
+          this.cacheStore?.clear();
+          for (const unsub of this.realtimeInvalidators.values()) unsub();
+          this.realtimeInvalidators.clear();
+        },
+        stats: () => this.cacheStore ? this.cacheStore.stats() : null
+      }
+    );
     const baseUrl = options.baseUrl.replace(/\/+$/, "");
     this.authStore = options.authStore ?? new AuthStore(options.storage ?? memoryStorage);
     this.http = new HttpClient(baseUrl, this.authStore);
@@ -1300,6 +1648,14 @@ var LazypockClient = class {
     }
     this.files = new FilesService(this.http);
     this.collections = new CollectionsService(this.http, this.realtime);
+    if (options.cache) {
+      this.cacheStore = new CacheStore({
+        defaultTTL: options.cache.defaultTTL,
+        store: options.cache.store,
+        maxEntries: options.cache.maxEntries
+      });
+      this.http.setCache(this.cacheStore, options.cache.enabled ?? false);
+    }
     if (options.types?.schemas) {
       this.schemaByName = new Map(
         options.types.schemas.map((s) => [s.name, s])
@@ -1380,6 +1736,49 @@ var LazypockClient = class {
     this.http.cancelAllRequests();
     return this;
   }
+  /**
+   * Drop every cached entry (all collections / namespaces).
+   * Also disables realtime-driven invalidation subscriptions.
+   */
+  clearCache() {
+    this.cacheStore?.clear();
+    for (const unsub of this.realtimeInvalidators.values()) unsub();
+    this.realtimeInvalidators.clear();
+    return this;
+  }
+  /**
+   * Invalidate cached entries for a collection (or custom namespace).
+   * Runs automatically on mutations — call explicitly when data changed
+   * out-of-band (e.g. another client wrote to the same collection).
+   */
+  invalidateCache(namespace) {
+    this.cacheStore?.invalidate(namespace);
+    return this;
+  }
+  /**
+   * Cache hit/miss/entry statistics.
+   * Returns null when caching was never configured.
+   */
+  cacheStats() {
+    return this.cacheStore ? this.cacheStore.stats() : null;
+  }
+  /**
+   * Subscribe a collection's cache to realtime invalidation: any inbound
+   * create/update/delete event for the collection clears its cached entries.
+   * Returns an unsubscribe function.
+   */
+  invalidateCacheOnRealtime(collectionName) {
+    if (!this.cacheStore) {
+      this.cache({ enabled: false });
+    }
+    const existing = this.realtimeInvalidators.get(collectionName);
+    if (existing) return existing;
+    const unsub = this.collection(collectionName).subscribe(() => {
+      this.cacheStore?.invalidate(collectionName);
+    });
+    this.realtimeInvalidators.set(collectionName, unsub);
+    return unsub;
+  }
   // ── Auth ──
   /** Check whether any superuser exists (for login vs setup screen routing). */
   async checkSuperuser() {
@@ -1517,6 +1916,7 @@ function createClient(options) {
 0 && (module.exports = {
   ApiError,
   AuthStore,
+  CacheStore,
   CollectionService,
   CollectionsService,
   FilesService,
@@ -1532,6 +1932,7 @@ function createClient(options) {
   getFileUrl,
   getScaleUrl,
   getThumbUrl,
+  resolveCacheDirective,
   schemaFieldType,
   wsUrlFromBaseUrl
 });