lazypock 0.2.0 → 0.3.0

package/dist/index.global.js

@@ -23,6 +23,7 @@ var Lazypock = (() => {
   __export(index_exports, {
     ApiError: () => ApiError,
     AuthStore: () => AuthStore,
+    CacheStore: () => CacheStore,
     CollectionService: () => CollectionService,
     CollectionsService: () => CollectionsService,
     FilesService: () => FilesService,
@@ -38,6 +39,7 @@ var Lazypock = (() => {
     getFileUrl: () => getFileUrl,
     getScaleUrl: () => getScaleUrl,
     getThumbUrl: () => getThumbUrl,
+    resolveCacheDirective: () => resolveCacheDirective,
     schemaFieldType: () => schemaFieldType,
     wsUrlFromBaseUrl: () => wsUrlFromBaseUrl
   });
@@ -53,6 +55,201 @@ var Lazypock = (() => {
     }
   };
 
+  // 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 Lazypock = (() => {
      * @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 Lazypock = (() => {
       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 Lazypock = (() => {
      * @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 Lazypock = (() => {
           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 Lazypock = (() => {
      * @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 @@ ${opts.body}
      */
     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 @@ ${opts.body}
       }
       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 @@ ${opts.body}
       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() {