lazypock 0.2.0 → 0.4.0

package/dist/index.js

@@ -17,6 +17,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");
@@ -27,18 +222,39 @@ 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
      * previous one — PocketBase-style auto-cancellation of duplicated requests.
      */
     this.cancelControllers = {};
+    /**
+     * In-flight request promises, keyed by cancellation key. When auto-cancellation
+     * would abort a pending duplicate, the newer request instead awaits the same
+     * promise — single-flight coalescing (no duplicate network request, no
+     * spurious abort rejection for the caller).
+     */
+    this.inflight = {};
     /** Global toggle for the auto-cancellation behaviour (default: on). */
     this.enableAutoCancellation = true;
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     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;
@@ -115,12 +331,33 @@ 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;
+    if (options?.singleFlight && requestKey !== null) {
+      const pending = this.inflight[requestKey];
+      if (pending !== void 0) {
+        return pending;
+      }
+    }
     let controller = null;
     const externalSignal = options?.signal;
     if (requestKey !== null) {
@@ -138,6 +375,38 @@ var HttpClient = class {
       }
     }
     const signal = controller?.signal ?? externalSignal;
+    const perform = async () => {
+      try {
+        return await this.doRequest(
+          method,
+          path,
+          body,
+          options,
+          signal,
+          requestKey,
+          controller,
+          cacheKey,
+          cacheDirective
+        );
+      } finally {
+        if (requestKey !== null) {
+          if (this.inflight[requestKey] === promise) {
+            delete this.inflight[requestKey];
+          }
+        }
+      }
+    };
+    const promise = perform();
+    if (requestKey !== null) {
+      this.inflight[requestKey] = promise;
+    }
+    return promise;
+  }
+  /**
+   * Execute the actual HTTP request (fetch + parse + cache). Called by {@link request}
+   * as the inner in-flight unit so single-flight callers can reuse the promise.
+   */
+  async doRequest(method, path, body, options, signal, requestKey, controller, cacheKey, cacheDirective) {
     let url = this.baseUrl + path;
     if (options?.params) {
       const qs = new URLSearchParams(options.params).toString();
@@ -202,8 +471,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.
@@ -379,6 +703,30 @@ var memoryStorage = {
 };
 
 // src/collection.ts
+function stableStringify(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const sort = (v) => {
+    if (Array.isArray(v)) return v.map(sort);
+    if (v && typeof v === "object") {
+      if (seen.has(v)) return "[Circular]";
+      seen.add(v);
+      const out = {};
+      for (const k of Object.keys(v).sort()) {
+        if (k === "requestKey" || k === "singleFlight" || k === "fetch" || k === "signal") {
+          continue;
+        }
+        out[k] = sort(v[k]);
+      }
+      return out;
+    }
+    return v;
+  };
+  try {
+    return JSON.stringify(sort(value));
+  } catch {
+    return String(value);
+  }
+}
 function normalizeAction(event, rawAction) {
   if (typeof rawAction === "string") {
     const a = rawAction.toLowerCase();
@@ -410,19 +758,44 @@ 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,
+      singleFlight,
+      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,
+        singleFlight,
+        params
+      }
     );
   }
   /**
@@ -433,6 +806,7 @@ var CollectionService = class {
    */
   async getFullList(options) {
     const { batch = 1e3, ...rest } = options ?? {};
+    const effectiveKey = typeof rest.requestKey === "string" ? rest.requestKey : `getFullList:${this.collectionName}:${stableStringify(rest)}`;
     const items = [];
     let page = 1;
     for (; ; ) {
@@ -440,9 +814,9 @@ var CollectionService = class {
         page,
         batch,
         {
-          // disable auto-cancellation across pages — each page request is unique
           ...rest,
-          requestKey: null
+          requestKey: effectiveKey,
+          singleFlight: true
         }
       );
       if (!res || !res.items || res.items.length === 0) break;
@@ -965,14 +1339,40 @@ var CollectionsService = class {
   async getFullList(options) {
     if (!this.http) return [];
     const { batch = 1e3, ...rest } = options ?? {};
+    const {
+      requestKey: reqKey,
+      singleFlight: _singleFlight,
+      fetch: fetchFn,
+      headers: hdrs,
+      signal: sig,
+      cache: cacheOpt,
+      ttl: ttlOpt,
+      invalidate: inval,
+      params: passthroughParams,
+      ...queryParams
+    } = rest;
+    const effectiveKey = typeof reqKey === "string" ? reqKey : `getFullList:collections:${stableStringify(rest)}`;
     const items = [];
     let page = 1;
     for (; ; ) {
-      const res = await this.getList({
-        ...rest,
-        page,
-        perPage: batch
-      });
+      const res = await this.getList(
+        {
+          ...queryParams,
+          ...passthroughParams ?? {},
+          page,
+          perPage: batch
+        },
+        {
+          requestKey: effectiveKey,
+          singleFlight: true,
+          ...fetchFn ? { fetch: fetchFn } : {},
+          ...hdrs ? { headers: hdrs } : {},
+          ...sig ? { signal: sig } : {},
+          ...cacheOpt !== void 0 ? { cache: cacheOpt } : {},
+          ...ttlOpt !== void 0 ? { ttl: ttlOpt } : {},
+          ...inval ? { invalidate: inval } : {}
+        }
+      );
       if (!res || !res.items || res.items.length === 0) break;
       items.push(...res.items);
       if (page >= (res.totalPages ?? page)) break;
@@ -1071,6 +1471,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);
@@ -1080,6 +1524,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])
@@ -1160,6 +1612,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() {
@@ -1296,6 +1791,7 @@ function createClient(options) {
 export {
   ApiError,
   AuthStore,
+  CacheStore,
   CollectionService,
   CollectionsService,
   FilesService,
@@ -1311,6 +1807,7 @@ export {
   getFileUrl,
   getScaleUrl,
   getThumbUrl,
+  resolveCacheDirective,
   schemaFieldType,
   wsUrlFromBaseUrl
 };