@osdk/react-devtools 0.5.0

package/build/esm/styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.js","names":[],"sources":["styles.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// Placeholder. scripts/build-css.mjs replaces the transpiled\n// build/esm/styles.js with a runtime-injection module that adds devtools\n// styles (including Blueprint) to document.head when the package is\n// imported.\n\nexport {};\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;;AAEA","ignoreList":[]}

package/build/esm/types/compute.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compute.js.map

package/build/esm/types/compute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute.js","names":[],"sources":["compute.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\ninterface ComputeRequestBase {\n  id: string;\n  requestUrl: string;\n  requestTimestamp: Date;\n  requestPayload: string;\n  requestPayloadHash: number;\n}\n\nexport interface PendingComputeRequest extends ComputeRequestBase {\n  type: \"pending\";\n}\n\nexport type ComputeRequestError =\n  | { type: \"osdk-network-paused\" }\n  | {\n    type: \"api-gateway-error\";\n    status: number;\n    errorCode: string;\n    errorInstanceId: string;\n    errorName: string;\n  }\n  | { type: \"http-error\"; status: number; message?: string }\n  | { type: \"fetch-error\"; message: string }\n  | { type: \"unknown\" };\n\nexport interface FailedComputeRequest extends ComputeRequestBase {\n  type: \"failed\";\n  failedTimestamp: Date;\n  error: ComputeRequestError;\n}\n\nexport interface FulfilledComputeRequest extends ComputeRequestBase {\n  type: \"fulfilled\";\n  computeUsage: number;\n  responseTimestamp: Date;\n  responsePayload: string;\n  responsePayloadBytes: number;\n  responsePayloadHash: number;\n}\n\nexport interface FulfilledWithoutUsageComputeRequest\n  extends ComputeRequestBase\n{\n  type: \"fulfilled-without-usage\";\n  responseTimestamp: Date;\n  responsePayload: string;\n  responsePayloadBytes: number;\n  responsePayloadHash: number;\n}\n\nexport type ComputeRequest =\n  | FulfilledComputeRequest\n  | FulfilledWithoutUsageComputeRequest\n  | PendingComputeRequest\n  | FailedComputeRequest;\n\nexport interface ComputeMetrics {\n  readonly totalUsage: number;\n  readonly lastMinuteUsage: number;\n  readonly requestCount: number;\n  readonly fulfilledCount: number;\n  readonly fulfilledWithoutUsageCount: number;\n  readonly failedCount: number;\n  readonly pendingCount: number;\n  readonly averageUsagePerRequest: number;\n  readonly averageResponseBytes: number;\n}\n\nexport interface RecordingEvent {\n  type: \"started\" | \"ended\";\n  timestamp: Date;\n  endTimestamp?: Date;\n}\n\nexport interface ComputeSnapshot {\n  readonly metrics: ComputeMetrics;\n  readonly requests: ReadonlyArray<ComputeRequest>;\n  readonly isRecording: boolean;\n  readonly isNetworkPaused: boolean;\n  readonly lastRecordingEvent: RecordingEvent | undefined;\n}\n"],"mappings":"","ignoreList":[]}

package/build/esm/types/emissions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=emissions.js.map

package/build/esm/types/emissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emissions.js","names":[],"sources":["emissions.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport type EmissionStatus = \"init\" | \"loading\" | \"loaded\" | \"error\";\n\nexport interface EmissionRecord {\n  readonly timestamp: number;\n  readonly status: EmissionStatus;\n  readonly hasData: boolean;\n  readonly isOptimistic: boolean;\n  readonly optimisticId?: string | number;\n  readonly sequenceNumber: number;\n}\n\nexport interface SubscriptionMetadata {\n  readonly signature: string;\n  readonly subscribeTime: number;\n  readonly emissions: EmissionRecord[];\n  unsubscribeTime?: number;\n}\n\nexport interface EmissionAnalysis {\n  readonly wasCached: boolean;\n  readonly wasOptimistic: boolean;\n  readonly loadTime?: number;\n  readonly emissionCount: number;\n  readonly firstOptimisticTimestamp?: number;\n  readonly lastOptimisticTimestamp?: number;\n  readonly firstNonOptimisticAfterOptimisticTimestamp?: number;\n}\n"],"mappings":"","ignoreList":[]}

package/build/esm/types/index.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const DEFAULT_MONITOR_CONFIG = {
+  cacheDetectionThresholdMs: 10,
+  cleanupIntervalMs: 60000,
+  maxOperations: 1000,
+  timeSeriesSize: 60
+};
+//# sourceMappingURL=index.js.map

package/build/esm/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["DEFAULT_MONITOR_CONFIG","cacheDetectionThresholdMs","cleanupIntervalMs","maxOperations","timeSeriesSize"],"sources":["index.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { Logger } from \"@osdk/api\";\n\nexport type OperationType =\n  | \"cache-hit\"\n  | \"cache-miss\"\n  | \"revalidation\"\n  | \"deduplication\"\n  | \"optimistic-update\"\n  | \"network-request\"\n  | \"action\"\n  | \"action-validation\";\n\nexport interface Operation {\n  readonly id: string;\n  readonly type: OperationType;\n  readonly signature: string;\n  readonly timestamp: number;\n  readonly responseTime?: number;\n  readonly saved?: number;\n  readonly metadata?: OperationMetadata;\n  readonly objectCount?: number;\n  readonly actionName?: string;\n  readonly optimisticConfigured?: boolean;\n  readonly optimisticObserved?: boolean;\n  readonly optimisticRenderTime?: number;\n  readonly serverRoundTripTime?: number;\n  readonly perceivedSpeedup?: number;\n  readonly rollback?: boolean;\n  readonly optimisticObjectsAffected?: number;\n  readonly renderGapBeforeServer?: number;\n  readonly optimisticLayerCount?: number;\n}\n\nexport interface OperationMetadata {\n  readonly apiName?: string;\n  readonly primaryKey?: string;\n  readonly actionName?: string;\n  readonly objectType?: string;\n  readonly whereClause?: string;\n  readonly pageSize?: number;\n}\n\nexport interface AggregateMetrics {\n  readonly cacheHits: number;\n  readonly cacheMisses: number;\n  readonly deduplications: number;\n  readonly optimisticUpdates: number;\n  readonly totalResponseTime: number;\n  readonly cachedResponseTime: number;\n  readonly networkResponseTime: number;\n  readonly requestsSaved: number;\n  readonly bytesServedFromCache: number;\n  readonly totalObjectsFromCache: number;\n  readonly totalObjectsFromNetwork: number;\n  readonly actionCount: number;\n  readonly configuredOptimisticActionCount: number;\n  readonly optimisticActionCount: number;\n  readonly rollbackActionCount: number;\n  readonly totalOptimisticRenderTime: number;\n  readonly totalServerRoundTripTime: number;\n  readonly totalPerceivedSpeedup: number;\n  readonly totalOptimisticObjectsAffected: number;\n  readonly revalidations: number;\n  readonly validationCount: number;\n  readonly totalValidationTime: number;\n}\n\nexport interface MetricsSnapshot {\n  readonly recent: ReadonlyArray<Operation>;\n  readonly aggregates: AggregateMetrics;\n  readonly rates: MetricRates;\n  readonly timeSeries: TimeSeriesData;\n}\n\nexport interface MetricRates {\n  readonly cacheHitRate: number;\n  readonly deduplicationRate: number;\n  readonly optimisticUpdateRate: number;\n  readonly averageResponseTime: number;\n  readonly averageCachedResponseTime: number;\n  readonly optimisticActionCoverage: number;\n  readonly configuredOptimisticActionRate: number;\n  readonly rollbackRate: number;\n  readonly averageOptimisticRenderTime: number;\n  readonly averageServerRoundTripTime: number;\n  readonly averagePerceivedSpeedup: number;\n  readonly averageValidationTime: number;\n  readonly validationTimeSaved: number;\n}\n\nexport interface TimeSeriesData {\n  readonly timestamps: ReadonlyArray<number>;\n  readonly cacheHits: ReadonlyArray<number>;\n  readonly cacheMisses: ReadonlyArray<number>;\n  readonly revalidations: ReadonlyArray<number>;\n  readonly deduplications: ReadonlyArray<number>;\n}\n\nexport type DockMode = \"floating\" | \"docked-bottom\" | \"docked-right\";\n\nexport interface PanelPosition {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n  readonly collapsed: boolean;\n  readonly dockMode: DockMode;\n}\n\nexport interface ObservableDebugMetadata {\n  readonly optimisticId?: string | number;\n  readonly servedFromCache?: boolean;\n  readonly servedFromMock?: boolean;\n  readonly mockId?: string;\n  readonly fetchSource?:\n    | \"network\"\n    | \"stream\"\n    | \"optimistic\"\n    | \"cross-propagation\";\n}\n\nexport interface MonitoringConfig {\n  readonly logger?: Logger;\n  readonly cacheDetectionThresholdMs: number;\n  readonly cleanupIntervalMs: number;\n  readonly maxOperations: number;\n  readonly timeSeriesSize: number;\n}\n\nexport const DEFAULT_MONITOR_CONFIG: MonitoringConfig = {\n  cacheDetectionThresholdMs: 10,\n  cleanupIntervalMs: 60000,\n  maxOperations: 1000,\n  timeSeriesSize: 60,\n};\n\nexport interface ActionError {\n  readonly id: string;\n  readonly actionType: string;\n  readonly timestamp: number;\n  readonly message: string;\n  readonly stack?: string;\n  readonly parameters: Record<string, unknown>;\n  readonly validationErrors?: ValidationError[];\n}\n\nexport interface ValidationError {\n  readonly field: string;\n  readonly message: string;\n  readonly value: unknown;\n}\n\nexport interface WastedRender {\n  readonly componentId: string;\n  readonly componentName: string;\n  readonly count: number;\n  readonly timestamp: number;\n}\n\nexport interface UnusedProperty {\n  readonly componentId: string;\n  readonly componentName: string;\n  readonly propertyName: string;\n  readonly totalRenders: number;\n  readonly accessCount: number;\n}\n\nexport interface OsdkMonitorGlobal {\n  readonly componentRegistry: object;\n  readonly componentContextCapture: object;\n  readonly prototypeOverrideStore: object;\n}\n\ndeclare global {\n  interface Window {\n    __OSDK_MONITOR__?: OsdkMonitorGlobal;\n  }\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmIA,OAAO,MAAMA,sBAAwC,GAAG;EACtDC,yBAAyB,EAAE,EAAE;EAC7BC,iBAAiB,EAAE,KAAK;EACxBC,aAAa,EAAE,IAAI;EACnBC,cAAc,EAAE;AAClB,CAAC","ignoreList":[]}

package/build/esm/utils/ActionLifecycleTracker.js

@@ -0,0 +1,178 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export class ActionLifecycleTracker {
+  actions = new Map();
+  layerToAction = new Map();
+  subscriptions = new Map();
+  constructor(metricsStore, eventTimeline) {
+    this.metricsStore = metricsStore;
+    this.eventTimeline = eventTimeline;
+  }
+  startAction(options) {
+    const actionId = crypto.randomUUID();
+    const timestamp = Date.now();
+    this.actions.set(actionId, {
+      actionId,
+      signature: options.signature,
+      metadata: options.metadata,
+      actionName: options.actionName,
+      startedAt: timestamp,
+      optimisticConfigured: options.optimisticConfigured,
+      optimisticSeen: false,
+      rollback: false,
+      optimisticObjectsAffected: 0,
+      optimisticLayerIds: new Set(),
+      optimisticLayerCount: 0
+    });
+    if (this.eventTimeline && options.actionName) {
+      this.eventTimeline.record({
+        type: "ACTION_START",
+        actionId,
+        actionName: options.actionName,
+        timestamp,
+        componentId: options.componentId
+      });
+    }
+    return actionId;
+  }
+  registerOptimisticLayer(actionId, layerId) {
+    const action = this.actions.get(actionId);
+    if (!action) return;
+    action.optimisticLayerIds.add(layerId);
+    action.optimisticSeen = true;
+    action.optimisticLayerCount++;
+    this.layerToAction.set(layerId, actionId);
+  }
+  handleLayerCleared(layerId, timestamp) {
+    const actionId = this.layerToAction.get(layerId);
+    if (!actionId) return;
+    const action = this.actions.get(actionId);
+    if (!action) {
+      this.layerToAction.delete(layerId);
+      return;
+    }
+    action.optimisticLayerIds.delete(layerId);
+    action.lastLayerClearedTimestamp = timestamp;
+    if (action.firstConfirmationTimestamp === undefined) {
+      action.firstConfirmationTimestamp = timestamp;
+    }
+    this.layerToAction.delete(layerId);
+  }
+  noteEmission(options) {
+    const {
+      subscriptionId,
+      optimisticId,
+      isOptimistic,
+      timestamp,
+      objectCount
+    } = options;
+    if (isOptimistic && optimisticId != null) {
+      const actionId = this.layerToAction.get(optimisticId);
+      if (!actionId) {
+        return;
+      }
+      const action = this.actions.get(actionId);
+      if (!action) {
+        return;
+      }
+      action.optimisticSeen = true;
+      if (action.optimisticRenderTimestamp === undefined || timestamp < action.optimisticRenderTimestamp) {
+        action.optimisticRenderTimestamp = timestamp;
+      }
+      const state = this.subscriptions.get(subscriptionId) ?? {};
+      if (state.actionId !== actionId) {
+        state.counted = false;
+      }
+      state.actionId = actionId;
+      state.optimisticId = optimisticId;
+      if (objectCount > 0 && state.counted !== true) {
+        action.optimisticObjectsAffected += objectCount;
+        state.counted = true;
+      }
+      this.subscriptions.set(subscriptionId, state);
+      return;
+    }
+    const state = this.subscriptions.get(subscriptionId);
+    if (!state?.actionId) {
+      return;
+    }
+    const action = this.actions.get(state.actionId);
+    if (!action) {
+      this.subscriptions.delete(subscriptionId);
+      return;
+    }
+    if (action.firstConfirmationTimestamp === undefined) {
+      action.firstConfirmationTimestamp = timestamp;
+    }
+    if (!isOptimistic) {
+      this.subscriptions.delete(subscriptionId);
+    }
+  }
+  clearSubscription(subscriptionId) {
+    this.subscriptions.delete(subscriptionId);
+  }
+  markActionSettled(options) {
+    const action = this.actions.get(options.actionId);
+    if (!action) return;
+    action.completedAt = options.completedAt;
+    action.rollback = !options.succeeded;
+    if (action.firstConfirmationTimestamp === undefined) {
+      action.firstConfirmationTimestamp = action.lastLayerClearedTimestamp ?? options.completedAt;
+    }
+    if (this.eventTimeline) {
+      this.eventTimeline.record({
+        type: "ACTION_COMPLETE",
+        actionId: options.actionId,
+        timestamp: options.completedAt,
+        success: options.succeeded
+      });
+    }
+    this.finalizeAction(action);
+  }
+  finalizeAction(action) {
+    const completedAt = action.completedAt ?? Date.now();
+    const serverRoundTripTime = completedAt - action.startedAt;
+    const optimisticRenderTime = action.optimisticRenderTimestamp != null ? action.optimisticRenderTimestamp - action.startedAt : undefined;
+    const perceivedSpeedup = optimisticRenderTime != null ? serverRoundTripTime - optimisticRenderTime : undefined;
+    const renderGapBeforeServer = action.optimisticRenderTimestamp != null && action.firstConfirmationTimestamp != null ? action.firstConfirmationTimestamp - action.optimisticRenderTimestamp : undefined;
+    const optimisticObserved = action.optimisticLayerCount > 0 || action.optimisticSeen;
+    this.metricsStore.recordActionLifecycle({
+      id: action.actionId,
+      type: "action",
+      signature: action.signature,
+      timestamp: completedAt,
+      metadata: action.metadata,
+      actionName: action.actionName,
+      optimisticConfigured: action.optimisticConfigured,
+      optimisticObserved,
+      optimisticRenderTime,
+      serverRoundTripTime,
+      perceivedSpeedup,
+      rollback: action.rollback,
+      optimisticObjectsAffected: action.optimisticObjectsAffected,
+      renderGapBeforeServer,
+      optimisticLayerCount: action.optimisticLayerCount
+    });
+    this.actions.delete(action.actionId);
+  }
+  dispose() {
+    this.actions.clear();
+    this.layerToAction.clear();
+    this.subscriptions.clear();
+  }
+}
+//# sourceMappingURL=ActionLifecycleTracker.js.map

package/build/esm/utils/ActionLifecycleTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionLifecycleTracker.js","names":["ActionLifecycleTracker","actions","Map","layerToAction","subscriptions","constructor","metricsStore","eventTimeline","startAction","options","actionId","crypto","randomUUID","timestamp","Date","now","set","signature","metadata","actionName","startedAt","optimisticConfigured","optimisticSeen","rollback","optimisticObjectsAffected","optimisticLayerIds","Set","optimisticLayerCount","record","type","componentId","registerOptimisticLayer","layerId","action","get","add","handleLayerCleared","delete","lastLayerClearedTimestamp","firstConfirmationTimestamp","undefined","noteEmission","subscriptionId","optimisticId","isOptimistic","objectCount","optimisticRenderTimestamp","state","counted","clearSubscription","markActionSettled","completedAt","succeeded","success","finalizeAction","serverRoundTripTime","optimisticRenderTime","perceivedSpeedup","renderGapBeforeServer","optimisticObserved","recordActionLifecycle","id","dispose","clear"],"sources":["ActionLifecycleTracker.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { MetricsStore } from \"../store/MetricsStore.js\";\nimport type { OperationMetadata } from \"../types/index.js\";\nimport type { EventTimeline } from \"./EventTimeline.js\";\n\ninterface ActionLifecycleData {\n  readonly actionId: string;\n  readonly signature: string;\n  readonly metadata?: OperationMetadata;\n  readonly startedAt: number;\n  readonly optimisticConfigured: boolean;\n  readonly actionName?: string;\n  optimisticSeen: boolean;\n  optimisticRenderTimestamp?: number;\n  firstConfirmationTimestamp?: number;\n  lastLayerClearedTimestamp?: number;\n  completedAt?: number;\n  rollback: boolean;\n  optimisticObjectsAffected: number;\n  optimisticLayerIds: Set<unknown>;\n  optimisticLayerCount: number;\n}\n\ninterface SubscriptionState {\n  actionId?: string;\n  optimisticId?: string | number;\n  counted?: boolean;\n}\n\ninterface StartActionOptions {\n  signature: string;\n  actionName?: string;\n  metadata?: OperationMetadata;\n  optimisticConfigured: boolean;\n  componentId?: string;\n}\n\ninterface SettleActionOptions {\n  actionId: string;\n  succeeded: boolean;\n  completedAt: number;\n}\n\ninterface EmissionOptions {\n  subscriptionId: string;\n  optimisticId?: string | number;\n  isOptimistic: boolean;\n  timestamp: number;\n  objectCount: number;\n}\n\nexport class ActionLifecycleTracker {\n  private readonly actions = new Map<string, ActionLifecycleData>();\n  private readonly layerToAction = new Map<unknown, string>();\n  private readonly subscriptions = new Map<string, SubscriptionState>();\n\n  constructor(\n    private readonly metricsStore: MetricsStore,\n    private readonly eventTimeline?: EventTimeline,\n  ) {}\n\n  startAction(options: StartActionOptions): string {\n    const actionId = crypto.randomUUID();\n    const timestamp = Date.now();\n\n    this.actions.set(actionId, {\n      actionId,\n      signature: options.signature,\n      metadata: options.metadata,\n      actionName: options.actionName,\n      startedAt: timestamp,\n      optimisticConfigured: options.optimisticConfigured,\n      optimisticSeen: false,\n      rollback: false,\n      optimisticObjectsAffected: 0,\n      optimisticLayerIds: new Set(),\n      optimisticLayerCount: 0,\n    });\n\n    if (this.eventTimeline && options.actionName) {\n      this.eventTimeline.record({\n        type: \"ACTION_START\",\n        actionId,\n        actionName: options.actionName,\n        timestamp,\n        componentId: options.componentId,\n      });\n    }\n\n    return actionId;\n  }\n\n  registerOptimisticLayer(actionId: string, layerId: unknown): void {\n    const action = this.actions.get(actionId);\n    if (!action) return;\n\n    action.optimisticLayerIds.add(layerId);\n    action.optimisticSeen = true;\n    action.optimisticLayerCount++;\n    this.layerToAction.set(layerId, actionId);\n  }\n\n  handleLayerCleared(layerId: unknown, timestamp: number): void {\n    const actionId = this.layerToAction.get(layerId);\n    if (!actionId) return;\n\n    const action = this.actions.get(actionId);\n    if (!action) {\n      this.layerToAction.delete(layerId);\n      return;\n    }\n\n    action.optimisticLayerIds.delete(layerId);\n    action.lastLayerClearedTimestamp = timestamp;\n    if (action.firstConfirmationTimestamp === undefined) {\n      action.firstConfirmationTimestamp = timestamp;\n    }\n\n    this.layerToAction.delete(layerId);\n  }\n\n  noteEmission(options: EmissionOptions): void {\n    const {\n      subscriptionId,\n      optimisticId,\n      isOptimistic,\n      timestamp,\n      objectCount,\n    } = options;\n\n    if (isOptimistic && optimisticId != null) {\n      const actionId = this.layerToAction.get(optimisticId);\n      if (!actionId) {\n        return;\n      }\n\n      const action = this.actions.get(actionId);\n      if (!action) {\n        return;\n      }\n\n      action.optimisticSeen = true;\n      if (\n        action.optimisticRenderTimestamp === undefined\n        || timestamp < action.optimisticRenderTimestamp\n      ) {\n        action.optimisticRenderTimestamp = timestamp;\n      }\n\n      const state = this.subscriptions.get(subscriptionId) ?? {};\n      if (state.actionId !== actionId) {\n        state.counted = false;\n      }\n      state.actionId = actionId;\n      state.optimisticId = optimisticId;\n\n      if (objectCount > 0 && state.counted !== true) {\n        action.optimisticObjectsAffected += objectCount;\n        state.counted = true;\n      }\n\n      this.subscriptions.set(subscriptionId, state);\n      return;\n    }\n\n    const state = this.subscriptions.get(subscriptionId);\n    if (!state?.actionId) {\n      return;\n    }\n\n    const action = this.actions.get(state.actionId);\n    if (!action) {\n      this.subscriptions.delete(subscriptionId);\n      return;\n    }\n\n    if (action.firstConfirmationTimestamp === undefined) {\n      action.firstConfirmationTimestamp = timestamp;\n    }\n\n    if (!isOptimistic) {\n      this.subscriptions.delete(subscriptionId);\n    }\n  }\n\n  clearSubscription(subscriptionId: string): void {\n    this.subscriptions.delete(subscriptionId);\n  }\n\n  markActionSettled(options: SettleActionOptions): void {\n    const action = this.actions.get(options.actionId);\n    if (!action) return;\n\n    action.completedAt = options.completedAt;\n    action.rollback = !options.succeeded;\n\n    if (action.firstConfirmationTimestamp === undefined) {\n      action.firstConfirmationTimestamp = action.lastLayerClearedTimestamp\n        ?? options.completedAt;\n    }\n\n    if (this.eventTimeline) {\n      this.eventTimeline.record({\n        type: \"ACTION_COMPLETE\",\n        actionId: options.actionId,\n        timestamp: options.completedAt,\n        success: options.succeeded,\n      });\n    }\n\n    this.finalizeAction(action);\n  }\n\n  private finalizeAction(action: ActionLifecycleData): void {\n    const completedAt = action.completedAt ?? Date.now();\n    const serverRoundTripTime = completedAt - action.startedAt;\n    const optimisticRenderTime = action.optimisticRenderTimestamp != null\n      ? action.optimisticRenderTimestamp - action.startedAt\n      : undefined;\n    const perceivedSpeedup = optimisticRenderTime != null\n      ? serverRoundTripTime - optimisticRenderTime\n      : undefined;\n    const renderGapBeforeServer = action.optimisticRenderTimestamp != null\n        && action.firstConfirmationTimestamp != null\n      ? action.firstConfirmationTimestamp\n        - action.optimisticRenderTimestamp\n      : undefined;\n    const optimisticObserved = action.optimisticLayerCount > 0\n      || action.optimisticSeen;\n\n    this.metricsStore.recordActionLifecycle({\n      id: action.actionId,\n      type: \"action\",\n      signature: action.signature,\n      timestamp: completedAt,\n      metadata: action.metadata,\n      actionName: action.actionName,\n      optimisticConfigured: action.optimisticConfigured,\n      optimisticObserved,\n      optimisticRenderTime,\n      serverRoundTripTime,\n      perceivedSpeedup,\n      rollback: action.rollback,\n      optimisticObjectsAffected: action.optimisticObjectsAffected,\n      renderGapBeforeServer,\n      optimisticLayerCount: action.optimisticLayerCount,\n    });\n\n    this.actions.delete(action.actionId);\n  }\n\n  dispose(): void {\n    this.actions.clear();\n    this.layerToAction.clear();\n    this.subscriptions.clear();\n  }\n}\n"],"mappings":"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","ignoreList":[]}

package/build/esm/utils/CacheEfficiencyAnalyzer.js

@@ -0,0 +1,198 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export class CacheEfficiencyAnalyzer {
+  constructor(metricsStore, coldThresholdMs = 5 * 60 * 1000 // 5 minutes
+  ) {
+    this.metricsStore = metricsStore;
+    this.coldThresholdMs = coldThresholdMs;
+  }
+  analyze(cacheSnapshot) {
+    const snapshot = this.metricsStore.getSnapshot();
+    const metrics = snapshot.aggregates;
+    const totalRequests = metrics.cacheHits + metrics.cacheMisses + metrics.revalidations;
+    const hitRate = totalRequests > 0 ? (metrics.cacheHits + metrics.revalidations) / totalRequests : 0;
+    const cacheMissRate = 1 - hitRate;
+    const avgNetworkTime = this.estimateAverageNetworkTime(metrics);
+    const cacheSavings = (metrics.cacheHits + metrics.revalidations) * avgNetworkTime;
+    const entries = cacheSnapshot.entries || [];
+    const sortedByAccess = [...entries].sort((a, b) => (b.metadata.hitCount || 0) - (a.metadata.hitCount || 0));
+    const hotEntries = sortedByAccess.slice(0, 10);
+    const coldEntries = entries.filter(e => Date.now() - (e.metadata.timestamp || 0) > this.coldThresholdMs);
+    const totalSize = entries.reduce((sum, e) => sum + (e.metadata.size || 0), 0);
+    const avgSize = entries.length > 0 ? totalSize / entries.length : 0;
+    const recommendations = this.generateRecommendations({
+      hitRate,
+      cacheMissRate,
+      totalEntries: entries.length,
+      totalSizeBytes: totalSize,
+      coldEntries: coldEntries.length,
+      cacheHits: metrics.cacheHits,
+      cacheMisses: metrics.cacheMisses,
+      revalidations: metrics.revalidations,
+      deduplications: metrics.deduplications
+    }, cacheSnapshot);
+    const score = this.calculateEfficiencyScore({
+      hitRate,
+      coldEntriesRatio: entries.length > 0 ? coldEntries.length / entries.length : 0,
+      totalSizeBytes: totalSize,
+      recommendationCount: recommendations.filter(r => r.level === "warning" || r.level === "critical").length
+    });
+    return {
+      hitRate,
+      hitRateTrend: this.getHitRateTrend(),
+      cacheMissRate,
+      cacheSavings,
+      bypassedRequests: metrics.cacheHits,
+      avgNetworkTime,
+      totalEntries: entries.length,
+      totalSizeBytes: totalSize,
+      averageEntrySize: avgSize,
+      hotEntries,
+      coldEntries,
+      coldThresholdMs: this.coldThresholdMs,
+      deduplications: metrics.deduplications,
+      recommendations,
+      score,
+      grade: this.scoreToGrade(score)
+    };
+  }
+  getHitRateTrend(windowSeconds = 60) {
+    const snapshot = this.metricsStore.getSnapshot();
+    const {
+      cacheHits,
+      cacheMisses,
+      revalidations
+    } = snapshot.timeSeries;
+    const hitRates = [];
+    const count = Math.min(windowSeconds, cacheHits.length);
+    for (let i = cacheHits.length - count; i < cacheHits.length; i++) {
+      if (i < 0) continue;
+      const total = cacheHits[i] + cacheMisses[i] + revalidations[i];
+      hitRates.push(total > 0 ? (cacheHits[i] + revalidations[i]) / total : 0);
+    }
+    return hitRates;
+  }
+  generateRecommendations(metrics) {
+    const recommendations = [];
+    if (metrics.hitRate < 0.3 && metrics.cacheHits + metrics.cacheMisses + metrics.revalidations > 20) {
+      recommendations.push({
+        level: "critical",
+        title: "Very low cache hit rate",
+        message: `Only ${(metrics.hitRate * 100).toFixed(1)}% of queries are served from cache`,
+        suggestion: "Consider increasing cache TTL, prefetching related data, or memoizing components"
+      });
+    } else if (metrics.hitRate < 0.5 && metrics.cacheHits + metrics.cacheMisses + metrics.revalidations > 20) {
+      recommendations.push({
+        level: "warning",
+        title: "Low cache hit rate",
+        message: `Only ${(metrics.hitRate * 100).toFixed(1)}% of queries are served from cache`,
+        suggestion: "Enable prefetching or increase cache TTL for frequently accessed data"
+      });
+    }
+    if (metrics.coldEntries > 50) {
+      recommendations.push({
+        level: "warning",
+        title: "Many stale cache entries",
+        message: `${metrics.coldEntries} entries haven't been accessed in ${this.coldThresholdMs / 60 / 1000} minutes`,
+        suggestion: "Consider implementing automatic cache eviction policy"
+      });
+    } else if (metrics.coldEntries > 20 && metrics.coldEntries > metrics.totalEntries / 2) {
+      recommendations.push({
+        level: "info",
+        title: "Many cold cache entries",
+        message: `${metrics.coldEntries}/${metrics.totalEntries} entries are not actively used`,
+        suggestion: "You can safely evict cold entries if memory is constrained"
+      });
+    }
+    if (metrics.totalSizeBytes > 50 * 1024 * 1024) {
+      recommendations.push({
+        level: "critical",
+        title: "Very large cache",
+        message: `Cache is using ${(metrics.totalSizeBytes / 1024 / 1024).toFixed(1)}MB - potential memory pressure`,
+        suggestion: "Implement cache size limits, TTL-based eviction, or LRU eviction policy"
+      });
+    } else if (metrics.totalSizeBytes > 10 * 1024 * 1024) {
+      recommendations.push({
+        level: "warning",
+        title: "Large cache",
+        message: `Cache is using ${(metrics.totalSizeBytes / 1024 / 1024).toFixed(1)}MB`,
+        suggestion: "Monitor memory usage and consider implementing cache size limits if not present"
+      });
+    }
+    if (metrics.deduplications > 5) {
+      recommendations.push({
+        level: "success",
+        title: "Good query deduplication",
+        message: `${metrics.deduplications} duplicate queries deduplicated - cache is working well!`,
+        suggestion: "Keep current architecture - components are efficiently sharing cache"
+      });
+    }
+    if (metrics.hitRate > 0.8) {
+      recommendations.push({
+        level: "success",
+        title: "Excellent cache hit rate",
+        message: `${(metrics.hitRate * 100).toFixed(1)}% of queries served from cache`,
+        suggestion: "Cache configuration is optimal for your app"
+      });
+    }
+    if (metrics.cacheHits + metrics.cacheMisses + metrics.revalidations === 0 && metrics.totalEntries > 0) {
+      recommendations.push({
+        level: "info",
+        title: "Cache not being used",
+        message: "Cache entries exist but no hits/misses recorded yet",
+        suggestion: "Monitor cache usage as you interact with the app"
+      });
+    }
+    return recommendations;
+  }
+  calculateEfficiencyScore(params) {
+    let score = 100;
+    if (params.hitRate < 0.3) {
+      score -= 30;
+    } else if (params.hitRate < 0.5) {
+      score -= 15;
+    } else if (params.hitRate < 0.7) {
+      score -= 5;
+    }
+    if (params.coldEntriesRatio > 0.5) {
+      score -= 20;
+    } else if (params.coldEntriesRatio > 0.3) {
+      score -= 10;
+    }
+    if (params.totalSizeBytes > 50 * 1024 * 1024) {
+      score -= 20;
+    } else if (params.totalSizeBytes > 10 * 1024 * 1024) {
+      score -= 10;
+    }
+    score -= Math.min(params.recommendationCount * 5, 20);
+    return Math.max(0, Math.round(score));
+  }
+  scoreToGrade(score) {
+    if (score >= 90) return "A";
+    if (score >= 80) return "B";
+    if (score >= 70) return "C";
+    if (score >= 60) return "D";
+    return "F";
+  }
+  estimateAverageNetworkTime(metrics) {
+    if (metrics.cacheMisses > 0 && metrics.networkResponseTime > 0) {
+      return metrics.networkResponseTime / metrics.cacheMisses;
+    }
+    return 200;
+  }
+}
+//# sourceMappingURL=CacheEfficiencyAnalyzer.js.map

package/build/esm/utils/CacheEfficiencyAnalyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheEfficiencyAnalyzer.js","names":["CacheEfficiencyAnalyzer","constructor","metricsStore","coldThresholdMs","analyze","cacheSnapshot","snapshot","getSnapshot","metrics","aggregates","totalRequests","cacheHits","cacheMisses","revalidations","hitRate","cacheMissRate","avgNetworkTime","estimateAverageNetworkTime","cacheSavings","entries","sortedByAccess","sort","a","b","metadata","hitCount","hotEntries","slice","coldEntries","filter","e","Date","now","timestamp","totalSize","reduce","sum","size","avgSize","length","recommendations","generateRecommendations","totalEntries","totalSizeBytes","deduplications","score","calculateEfficiencyScore","coldEntriesRatio","recommendationCount","r","level","hitRateTrend","getHitRateTrend","bypassedRequests","averageEntrySize","grade","scoreToGrade","windowSeconds","timeSeries","hitRates","count","Math","min","i","total","push","title","message","toFixed","suggestion","params","max","round","networkResponseTime"],"sources":["CacheEfficiencyAnalyzer.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { CacheEntry, CacheSnapshot } from \"@osdk/client/observable\";\nimport type { MetricsStore } from \"../store/MetricsStore.js\";\n\nexport interface NetworkMetrics {\n  cacheMisses: number;\n  networkResponseTime: number;\n}\n\nexport interface CacheRecommendation {\n  level: \"critical\" | \"warning\" | \"info\" | \"success\";\n  title: string;\n  message: string;\n  suggestion: string;\n  action?: {\n    label: string;\n    handler: () => void;\n  };\n}\n\nexport interface CacheEfficiencyMetrics {\n  hitRate: number;\n  hitRateTrend: number[];\n  cacheMissRate: number;\n  cacheSavings: number;\n  bypassedRequests: number;\n  avgNetworkTime: number;\n  totalEntries: number;\n  totalSizeBytes: number;\n  averageEntrySize: number;\n  hotEntries: CacheEntry[];\n  coldEntries: CacheEntry[];\n  coldThresholdMs: number;\n  deduplications: number;\n  recommendations: CacheRecommendation[];\n  score: number;\n  grade: \"A\" | \"B\" | \"C\" | \"D\" | \"F\";\n}\n\nexport class CacheEfficiencyAnalyzer {\n  constructor(\n    private metricsStore: MetricsStore,\n    private coldThresholdMs: number = 5 * 60 * 1000, // 5 minutes\n  ) {}\n\n  analyze(cacheSnapshot: CacheSnapshot): CacheEfficiencyMetrics {\n    const snapshot = this.metricsStore.getSnapshot();\n    const metrics = snapshot.aggregates;\n\n    const totalRequests = metrics.cacheHits + metrics.cacheMisses\n      + metrics.revalidations;\n    const hitRate = totalRequests > 0\n      ? (metrics.cacheHits + metrics.revalidations) / totalRequests\n      : 0;\n    const cacheMissRate = 1 - hitRate;\n\n    const avgNetworkTime = this.estimateAverageNetworkTime(metrics);\n    const cacheSavings = (metrics.cacheHits + metrics.revalidations)\n      * avgNetworkTime;\n\n    const entries = cacheSnapshot.entries || [];\n    const sortedByAccess = [...entries].sort((a, b) =>\n      (b.metadata.hitCount || 0) - (a.metadata.hitCount || 0)\n    );\n    const hotEntries = sortedByAccess.slice(0, 10);\n    const coldEntries = entries.filter(e =>\n      Date.now() - (e.metadata.timestamp || 0) > this.coldThresholdMs\n    );\n\n    const totalSize = entries.reduce(\n      (sum, e) => sum + (e.metadata.size || 0),\n      0,\n    );\n    const avgSize = entries.length > 0 ? totalSize / entries.length : 0;\n\n    const recommendations = this.generateRecommendations(\n      {\n        hitRate,\n        cacheMissRate,\n        totalEntries: entries.length,\n        totalSizeBytes: totalSize,\n        coldEntries: coldEntries.length,\n        cacheHits: metrics.cacheHits,\n        cacheMisses: metrics.cacheMisses,\n        revalidations: metrics.revalidations,\n        deduplications: metrics.deduplications,\n      },\n      cacheSnapshot,\n    );\n\n    const score = this.calculateEfficiencyScore({\n      hitRate,\n      coldEntriesRatio: entries.length > 0\n        ? coldEntries.length / entries.length\n        : 0,\n      totalSizeBytes: totalSize,\n      recommendationCount: recommendations.filter(r =>\n        r.level === \"warning\" || r.level === \"critical\"\n      ).length,\n    });\n\n    return {\n      hitRate,\n      hitRateTrend: this.getHitRateTrend(),\n      cacheMissRate,\n      cacheSavings,\n      bypassedRequests: metrics.cacheHits,\n      avgNetworkTime,\n      totalEntries: entries.length,\n      totalSizeBytes: totalSize,\n      averageEntrySize: avgSize,\n      hotEntries,\n      coldEntries,\n      coldThresholdMs: this.coldThresholdMs,\n      deduplications: metrics.deduplications,\n      recommendations,\n      score,\n      grade: this.scoreToGrade(score),\n    };\n  }\n\n  getHitRateTrend(windowSeconds: number = 60): number[] {\n    const snapshot = this.metricsStore.getSnapshot();\n    const { cacheHits, cacheMisses, revalidations } = snapshot.timeSeries;\n\n    const hitRates: number[] = [];\n    const count = Math.min(windowSeconds, cacheHits.length);\n\n    for (let i = cacheHits.length - count; i < cacheHits.length; i++) {\n      if (i < 0) continue;\n      const total = cacheHits[i] + cacheMisses[i] + revalidations[i];\n      hitRates.push(total > 0 ? (cacheHits[i] + revalidations[i]) / total : 0);\n    }\n\n    return hitRates;\n  }\n\n  private generateRecommendations(\n    metrics: {\n      hitRate: number;\n      cacheMissRate: number;\n      totalEntries: number;\n      totalSizeBytes: number;\n      coldEntries: number;\n      cacheHits: number;\n      cacheMisses: number;\n      revalidations: number;\n      deduplications: number;\n    },\n    cacheSnapshot: CacheSnapshot,\n  ): CacheRecommendation[] {\n    const recommendations: CacheRecommendation[] = [];\n\n    if (\n      metrics.hitRate < 0.3\n      && metrics.cacheHits + metrics.cacheMisses + metrics.revalidations > 20\n    ) {\n      recommendations.push({\n        level: \"critical\",\n        title: \"Very low cache hit rate\",\n        message: `Only ${\n          (metrics.hitRate * 100).toFixed(1)\n        }% of queries are served from cache`,\n        suggestion:\n          \"Consider increasing cache TTL, prefetching related data, or memoizing components\",\n      });\n    } else if (\n      metrics.hitRate < 0.5\n      && metrics.cacheHits + metrics.cacheMisses + metrics.revalidations > 20\n    ) {\n      recommendations.push({\n        level: \"warning\",\n        title: \"Low cache hit rate\",\n        message: `Only ${\n          (metrics.hitRate * 100).toFixed(1)\n        }% of queries are served from cache`,\n        suggestion:\n          \"Enable prefetching or increase cache TTL for frequently accessed data\",\n      });\n    }\n\n    if (metrics.coldEntries > 50) {\n      recommendations.push({\n        level: \"warning\",\n        title: \"Many stale cache entries\",\n        message: `${metrics.coldEntries} entries haven't been accessed in ${\n          this.coldThresholdMs / 60 / 1000\n        } minutes`,\n        suggestion: \"Consider implementing automatic cache eviction policy\",\n      });\n    } else if (\n      metrics.coldEntries > 20 && metrics.coldEntries > metrics.totalEntries / 2\n    ) {\n      recommendations.push({\n        level: \"info\",\n        title: \"Many cold cache entries\",\n        message:\n          `${metrics.coldEntries}/${metrics.totalEntries} entries are not actively used`,\n        suggestion:\n          \"You can safely evict cold entries if memory is constrained\",\n      });\n    }\n\n    if (metrics.totalSizeBytes > 50 * 1024 * 1024) {\n      recommendations.push({\n        level: \"critical\",\n        title: \"Very large cache\",\n        message: `Cache is using ${\n          (metrics.totalSizeBytes / 1024 / 1024).toFixed(1)\n        }MB - potential memory pressure`,\n        suggestion:\n          \"Implement cache size limits, TTL-based eviction, or LRU eviction policy\",\n      });\n    } else if (metrics.totalSizeBytes > 10 * 1024 * 1024) {\n      recommendations.push({\n        level: \"warning\",\n        title: \"Large cache\",\n        message: `Cache is using ${\n          (metrics.totalSizeBytes / 1024 / 1024).toFixed(1)\n        }MB`,\n        suggestion:\n          \"Monitor memory usage and consider implementing cache size limits if not present\",\n      });\n    }\n\n    if (metrics.deduplications > 5) {\n      recommendations.push({\n        level: \"success\",\n        title: \"Good query deduplication\",\n        message:\n          `${metrics.deduplications} duplicate queries deduplicated - cache is working well!`,\n        suggestion:\n          \"Keep current architecture - components are efficiently sharing cache\",\n      });\n    }\n\n    if (metrics.hitRate > 0.8) {\n      recommendations.push({\n        level: \"success\",\n        title: \"Excellent cache hit rate\",\n        message: `${\n          (metrics.hitRate * 100).toFixed(1)\n        }% of queries served from cache`,\n        suggestion: \"Cache configuration is optimal for your app\",\n      });\n    }\n\n    if (\n      metrics.cacheHits + metrics.cacheMisses + metrics.revalidations === 0\n      && metrics.totalEntries > 0\n    ) {\n      recommendations.push({\n        level: \"info\",\n        title: \"Cache not being used\",\n        message: \"Cache entries exist but no hits/misses recorded yet\",\n        suggestion: \"Monitor cache usage as you interact with the app\",\n      });\n    }\n\n    return recommendations;\n  }\n\n  private calculateEfficiencyScore(params: {\n    hitRate: number;\n    coldEntriesRatio: number;\n    totalSizeBytes: number;\n    recommendationCount: number;\n  }): number {\n    let score = 100;\n\n    if (params.hitRate < 0.3) {\n      score -= 30;\n    } else if (params.hitRate < 0.5) {\n      score -= 15;\n    } else if (params.hitRate < 0.7) {\n      score -= 5;\n    }\n\n    if (params.coldEntriesRatio > 0.5) {\n      score -= 20;\n    } else if (params.coldEntriesRatio > 0.3) {\n      score -= 10;\n    }\n\n    if (params.totalSizeBytes > 50 * 1024 * 1024) {\n      score -= 20;\n    } else if (params.totalSizeBytes > 10 * 1024 * 1024) {\n      score -= 10;\n    }\n\n    score -= Math.min(params.recommendationCount * 5, 20);\n\n    return Math.max(0, Math.round(score));\n  }\n\n  private scoreToGrade(score: number): \"A\" | \"B\" | \"C\" | \"D\" | \"F\" {\n    if (score >= 90) return \"A\";\n    if (score >= 80) return \"B\";\n    if (score >= 70) return \"C\";\n    if (score >= 60) return \"D\";\n    return \"F\";\n  }\n\n  private estimateAverageNetworkTime(metrics: NetworkMetrics): number {\n    if (metrics.cacheMisses > 0 && metrics.networkResponseTime > 0) {\n      return metrics.networkResponseTime / metrics.cacheMisses;\n    }\n    return 200;\n  }\n}\n"],"mappings":"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","ignoreList":[]}

package/build/esm/utils/CircularBuffer.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export class CircularBuffer {
+  head = 0;
+  tail = 0;
+  size = 0;
+  constructor(capacity, onEvict) {
+    if (capacity <= 0) {
+      throw new Error("CircularBuffer capacity must be positive");
+    }
+    this.capacity = capacity;
+    this.buffer = new Array(capacity);
+    this.onEvict = onEvict;
+  }
+  push(item) {
+    const index = this.tail;
+    if (this.size === this.capacity) {
+      const evicted = this.buffer[this.tail];
+      if (this.onEvict && evicted !== undefined) {
+        this.onEvict(evicted);
+      }
+    }
+    this.buffer[this.tail] = item;
+    this.tail = (this.tail + 1) % this.capacity;
+    if (this.size < this.capacity) {
+      this.size++;
+    } else {
+      this.head = (this.head + 1) % this.capacity;
+    }
+    return index;
+  }
+  get(index) {
+    if (index < 0 || index >= this.capacity) {
+      return undefined;
+    }
+    return this.buffer[index];
+  }
+  toArray() {
+    const result = [];
+    let current = this.head;
+    for (let i = 0; i < this.size; i++) {
+      const item = this.buffer[current];
+      if (item !== undefined) {
+        result.push(item);
+      }
+      current = (current + 1) % this.capacity;
+    }
+    return result;
+  }
+  getSize() {
+    return this.size;
+  }
+  getCapacity() {
+    return this.capacity;
+  }
+  isFull() {
+    return this.size === this.capacity;
+  }
+  isEmpty() {
+    return this.size === 0;
+  }
+  getLast(n) {
+    const count = Math.min(n, this.size);
+    const result = [];
+    let index = (this.tail - count + this.capacity) % this.capacity;
+    for (let i = 0; i < count; i++) {
+      const item = this.buffer[index];
+      if (item !== undefined) {
+        result.push(item);
+      }
+      index = (index + 1) % this.capacity;
+    }
+    return result;
+  }
+  clear() {
+    this.buffer = new Array(this.capacity);
+    this.head = 0;
+    this.tail = 0;
+    this.size = 0;
+  }
+}
+//# sourceMappingURL=CircularBuffer.js.map

package/build/esm/utils/CircularBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircularBuffer.js","names":["CircularBuffer","head","tail","size","constructor","capacity","onEvict","Error","buffer","Array","push","item","index","evicted","undefined","get","toArray","result","current","i","getSize","getCapacity","isFull","isEmpty","getLast","n","count","Math","min","clear"],"sources":["CircularBuffer.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport class CircularBuffer<T> {\n  private buffer: Array<T | undefined>;\n  private head = 0;\n  private tail = 0;\n  private size = 0;\n  private readonly capacity: number;\n  private readonly onEvict?: (item: T) => void;\n\n  constructor(capacity: number, onEvict?: (item: T) => void) {\n    if (capacity <= 0) {\n      throw new Error(\"CircularBuffer capacity must be positive\");\n    }\n    this.capacity = capacity;\n    this.buffer = new Array(capacity);\n    this.onEvict = onEvict;\n  }\n\n  push(item: T): number {\n    const index = this.tail;\n\n    if (this.size === this.capacity) {\n      const evicted = this.buffer[this.tail];\n      if (this.onEvict && evicted !== undefined) {\n        this.onEvict(evicted);\n      }\n    }\n\n    this.buffer[this.tail] = item;\n    this.tail = (this.tail + 1) % this.capacity;\n\n    if (this.size < this.capacity) {\n      this.size++;\n    } else {\n      this.head = (this.head + 1) % this.capacity;\n    }\n\n    return index;\n  }\n\n  get(index: number): T | undefined {\n    if (index < 0 || index >= this.capacity) {\n      return undefined;\n    }\n    return this.buffer[index];\n  }\n\n  toArray(): T[] {\n    const result: T[] = [];\n    let current = this.head;\n\n    for (let i = 0; i < this.size; i++) {\n      const item = this.buffer[current];\n      if (item !== undefined) {\n        result.push(item);\n      }\n      current = (current + 1) % this.capacity;\n    }\n\n    return result;\n  }\n\n  getSize(): number {\n    return this.size;\n  }\n\n  getCapacity(): number {\n    return this.capacity;\n  }\n\n  isFull(): boolean {\n    return this.size === this.capacity;\n  }\n\n  isEmpty(): boolean {\n    return this.size === 0;\n  }\n\n  getLast(n: number): ReadonlyArray<T> {\n    const count = Math.min(n, this.size);\n    const result: T[] = [];\n\n    let index = (this.tail - count + this.capacity) % this.capacity;\n\n    for (let i = 0; i < count; i++) {\n      const item = this.buffer[index];\n      if (item !== undefined) {\n        result.push(item);\n      }\n      index = (index + 1) % this.capacity;\n    }\n\n    return result;\n  }\n\n  clear(): void {\n    this.buffer = new Array(this.capacity);\n    this.head = 0;\n    this.tail = 0;\n    this.size = 0;\n  }\n}\n"],"mappings":"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","ignoreList":[]}