@markwharton/liquidplanner 2.1.1 → 2.2.0

package/README.md

@@ -200,6 +200,7 @@ const client = new LPClient({
   baseUrl: '...',              // Optional: override API base URL
   onRequest: ({ method, url, description }) => { ... },  // Optional: debug callback
   cache: {},                   // Optional: enable TTL caching (defaults below)
+  cacheInstance: cache,        // Optional: custom cache backend (e.g., LayeredCache)
   retry: {                     // Optional: retry on 429/503
     maxRetries: 3,
     initialDelayMs: 1000,
@@ -208,7 +209,7 @@ const client = new LPClient({
 });
 ```
 
-`LPConfig` extends `ClientConfig` from api-core, which provides the `baseUrl`, `onRequest`, and `retry` fields. `apiToken`, `workspaceId`, and `cache` are LP-specific.
+`LPConfig` extends `ClientConfig` from api-core, which provides the `baseUrl`, `onRequest`, `retry`, and `cacheInstance` fields. `apiToken`, `workspaceId`, and `cache` are LP-specific. Pass `cacheInstance` to use a custom cache backend (e.g., `LayeredCache` with persistent stores); otherwise `cache: {}` creates an in-memory `TTLCache`.
 
 ### Cache TTLs
 
@@ -223,6 +224,8 @@ const client = new LPClient({
 
 Write operations (`createTimesheetEntry`, `updateTimesheetEntry`) automatically invalidate timesheet cache entries. Call `client.invalidateTreeCache()` to refresh the workspace tree, or `client.clearCache()` to clear all cached data.
 
+Failed API results (`ok: false`) are never cached — transient errors won't persist for the full TTL. See the [root README Cache System section](../../README.md#cache-system) for the full cache architecture (layered stores, PII handling, request coalescing).
+
 ### Retry
 
 Automatically retries on HTTP 429 (Too Many Requests) and 503 (Service Unavailable) with exponential backoff. Respects the `Retry-After` header when present.

package/dist/client.d.ts

@@ -41,6 +41,8 @@ export declare class LPClient {
     constructor(config: LPConfig);
     /**
      * Route through cache if enabled, otherwise call factory directly.
+     * Failed Results (ok === false) are never cached — transient errors
+     * shouldn't persist for the full TTL.
      */
     private cached;
     /**
@@ -128,6 +130,7 @@ export declare class LPClient {
      *
      * This enables PWA apps to show a task picker populated from LP directly.
      * Note: userId is not a supported filter field in the LP API, so we filter client-side.
+     * The full unfiltered dataset is cached once; all memberId queries share the same cache entry.
      */
     getMyAssignments(memberId: number): Promise<Result<LPItem[]>>;
     /**

package/dist/client.js

@@ -10,7 +10,7 @@ import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIsN
 import { buildTree, getTreeAncestors } from './tree.js';
 import { parseLPErrorResponse } from './errors.js';
 import { LP_API_BASE } from './constants.js';
-import { TTLCache, batchMap, getErrorMessage, fetchWithRetry, ok, err, resolveRetryConfig } from '@markwharton/api-core';
+import { TTLCache, batchMap, getErrorMessage, fetchWithRetry, ok, okVoid, err, resolveRetryConfig } from '@markwharton/api-core';
 /** Transform raw API item to LPItem, preserving scheduling and effort fields */
 function transformItem(raw) {
     const item = {
@@ -114,8 +114,8 @@ export class LPClient {
         this.baseUrl = config.baseUrl ?? LP_API_BASE;
         this.onRequest = config.onRequest;
         // Initialize cache if configured
-        if (config.cache) {
-            this.cache = new TTLCache();
+        if (config.cache || config.cacheInstance) {
+            this.cache = config.cacheInstance ?? new TTLCache();
         }
         this.cacheTtl = {
             membersTtl: config.cache?.membersTtl ?? 300000,
@@ -130,12 +130,16 @@ export class LPClient {
     }
     /**
      * Route through cache if enabled, otherwise call factory directly.
+     * Failed Results (ok === false) are never cached — transient errors
+     * shouldn't persist for the full TTL.
      */
-    async cached(key, ttlMs, factory) {
-        if (this.cache) {
-            return this.cache.get(key, ttlMs, factory);
-        }
-        return factory();
+    async cached(key, ttlMs, factory, options) {
+        if (!this.cache)
+            return factory();
+        return this.cache.get(key, ttlMs, factory, {
+            ...options,
+            shouldCache: (data) => data.ok !== false,
+        });
     }
     /**
      * Clear all cached API responses.
@@ -158,7 +162,7 @@ export class LPClient {
      * (e.g., after logging time which updates loggedHoursRollup).
      */
     invalidateAssignmentsCache() {
-        this.cache?.invalidate('assignments:');
+        this.cache?.invalidate('assignments');
     }
     /**
      * Invalidate cached workspace tree snapshot only.
@@ -248,7 +252,7 @@ export class LPClient {
         try {
             const response = await this.fetch(url);
             if (response.ok) {
-                return { ok: true };
+                return okVoid();
             }
             if (response.status === 401 || response.status === 403) {
                 return err('Invalid or expired API token', response.status);
@@ -372,17 +376,20 @@ export class LPClient {
      *
      * This enables PWA apps to show a task picker populated from LP directly.
      * Note: userId is not a supported filter field in the LP API, so we filter client-side.
+     * The full unfiltered dataset is cached once; all memberId queries share the same cache entry.
      */
     async getMyAssignments(memberId) {
-        return this.cached(`assignments:${memberId}`, this.cacheTtl.assignmentsTtl, async () => {
+        const result = await this.cached('assignments', this.cacheTtl.assignmentsTtl, async () => {
             const baseUrl = this.workspaceUrl(`items/v1?${filterIs('itemType', 'assignments')}`);
             return paginatedFetch({
                 fetchFn: (url) => this.fetch(url),
                 baseUrl,
-                filter: (data) => data.filter(item => item.userId === memberId),
                 transform: (data) => data.map(transformItem),
             });
         });
+        if (!result.ok)
+            return result;
+        return ok(result.data.filter(item => item.userId === memberId));
     }
     /**
      * Get assignments for a member with parent task names resolved

package/dist/index.d.ts

@@ -31,8 +31,8 @@
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
 export type { LPConfig, LPCacheConfig, LPRetryConfig, LPItemType, HierarchyItem, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPUpsertOptions, LPAssignmentWithContext, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
-export { ok, err, getErrorMessage } from '@markwharton/api-core';
-export type { Result, RetryConfig, OnRequestCallback, ClientConfig } from '@markwharton/api-core';
+export { ok, err, getErrorMessage, TTLCache, MemoryCacheStore, LayeredCache } from '@markwharton/api-core';
+export type { Result, RetryConfig, OnRequestCallback, ClientConfig, Cache, CacheStore, CacheGetOptions } from '@markwharton/api-core';
 export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIsNot, filterIn, filterGt, filterLt, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';
 export type { PaginateOptions } from './utils.js';
 export { buildTree, getTreeAncestors, getTreeHierarchyPath, findInTree, } from './tree.js';

package/dist/index.js

@@ -33,7 +33,7 @@ export { LPClient } from './client.js';
 // Workflows
 export { resolveTaskToAssignment } from './workflows.js';
 // Re-exported from @markwharton/api-core
-export { ok, err, getErrorMessage } from '@markwharton/api-core';
+export { ok, err, getErrorMessage, TTLCache, MemoryCacheStore, LayeredCache } from '@markwharton/api-core';
 // Utilities
 export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIsNot, filterIn, filterGt, filterLt, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';
 // Tree utilities

package/dist/utils.d.ts

@@ -49,8 +49,6 @@ export interface PaginateOptions<TRaw, TResult> {
     baseUrl: string;
     /** Transform raw API data to result type */
     transform: (data: TRaw[]) => TResult[];
-    /** Optional filter to apply to each page */
-    filter?: (data: TRaw[]) => TRaw[];
 }
 /**
  * Generic pagination helper for LP API endpoints

package/dist/utils.js

@@ -76,7 +76,7 @@ export function joinFilters(...filters) {
  * Handles the continuation token pattern used by LP API.
  */
 export async function paginatedFetch(options) {
-    const { fetchFn, baseUrl, transform, filter } = options;
+    const { fetchFn, baseUrl, transform } = options;
     const hasQueryParams = baseUrl.includes('?');
     try {
         const allResults = [];
@@ -93,8 +93,7 @@ export async function paginatedFetch(options) {
             }
             const result = await response.json();
             const rawData = result.data || [];
-            const filteredData = filter ? filter(rawData) : rawData;
-            const pageResults = transform(filteredData);
+            const pageResults = transform(rawData);
             allResults.push(...pageResults);
             continuationToken = result.continuationToken;
         } while (continuationToken);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/liquidplanner",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "LiquidPlanner API client for timesheet integration",
   "type": "module",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@markwharton/api-core": "^1.2.0"
+    "@markwharton/api-core": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",