@json-to-office/core-docx 0.30.0 → 0.31.0

package/dist/core/cached-render.d.ts

@@ -6,6 +6,28 @@ import { Paragraph, Table, TableOfContents, Textbox } from 'docx';
 import { ComponentDefinition, RenderContext } from '../types';
 import { ThemeConfig } from '../styles';
 import { MemoryCache } from '../cache';
+/** Why a component type is never cached (see renderComponentWithCache). */
+export type ComponentBypassReason = 'dynamic-context' | 'bookmark-id' | 'revision-ids';
+export interface ComponentBypassStats {
+    /** Component type name. */
+    type: string;
+    /** Renders that skipped the cache by design. */
+    renders: number;
+    /** The (first observed) reason this type bypasses the cache. */
+    reason: ComponentBypassReason;
+}
+/**
+ * Get per-type "uncached by design" render counters.
+ */
+export declare function getComponentBypassStats(): ComponentBypassStats[];
+/**
+ * True when the serialized props/children reference a registered placeholder
+ * whose output can vary with the generation date. Components without one
+ * render identically across dates, so their cache keys must not embed the
+ * per-render timestamp — that's what made cross-render hits impossible for
+ * date-less documents (#156).
+ */
+export declare function usesDateSensitivePlaceholder(serialized: string): boolean;
 /**
  * Initialize the component cache
  */
@@ -32,9 +54,25 @@ export declare function warmComponentCache(components: Array<{
     context: RenderContext;
 }>): Promise<void>;
 /**
- * Get component cache statistics
+ * Get component cache statistics, extended with per-type "uncached by
+ * design" render counters (#156). The bypass counters exist even before the
+ * cache is initialized — a document full of bypassed types never triggers
+ * initialization, yet its renders are exactly what needs surfacing.
  */
-export declare function getComponentCacheStats(): import("@json-to-office/shared/cache").CacheStatistics | null;
+export declare function getComponentCacheStats(): {
+    bypassedComponents: ComponentBypassStats[];
+} | {
+    bypassedComponents: ComponentBypassStats[];
+    entries: number;
+    totalSize: number;
+    hitRate: number;
+    missRate: number;
+    totalHits: number;
+    totalMisses: number;
+    avgResponseTime: number;
+    evictions: number;
+    componentStats: Map<string, import("@json-to-office/shared/cache").ComponentStatistics>;
+} | null;
 /**
  * Export component cache for persistence
  */

package/dist/core/cached-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cached-render.d.ts","sourceRoot":"","sources":["../../src/core/cached-render.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,WAAW,EAIZ,MAAM,UAAU,CAAC;AAoBlB;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CA4BlE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,GAAG,IAAI,CAEtD;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIzD;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,WAAW,UAAQ,GAClB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,GAAG,eAAe,GAAG,OAAO,CAAC,EAAE,CAAC,CAyG5D;AAKD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,KAAK,CAAC;IAChB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;GAEG;AACH,wBAAgB,sBAAsB,kEAMrC;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,GAAG,CACvD,MAAM,EACN,OAAO,CACR,GAAG,IAAI,CAAC,CAgBR;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAQf"}
+{"version":3,"file":"cached-render.d.ts","sourceRoot":"","sources":["../../src/core/cached-render.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,WAAW,EAIZ,MAAM,UAAU,CAAC;AAWlB,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,aAAa,GACb,cAAc,CAAC;AAEnB,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAwBD;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,EAAE,CAMhE;AAUD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CASxE;AAYD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CA4BlE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,GAAG,IAAI,CAEtD;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,mBAAmB,EAC9B,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,WAAW,UAAQ,GAClB,OAAO,CAAC,CAAC,SAAS,GAAG,KAAK,GAAG,eAAe,GAAG,OAAO,CAAC,EAAE,CAAC,CAuH5D;AAKD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,KAAK,CAAC;IAChB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB;;;;;;;;;;;;;SAOrC;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,GAAG,CACvD,MAAM,EACN,OAAO,CACR,GAAG,IAAI,CAAC,CAgBR;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GACzB,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/core/prerasterizeVisuals.d.ts

@@ -23,6 +23,22 @@ export interface PrerasterizeOptions {
     /** Max concurrent per-visual fallback rasterizations (default 4). */
     concurrency?: number;
 }
+/** Cumulative pre-pass counters for cache observability (#156). */
+export interface VisualPrepassStats {
+    /** Documents that entered the pre-pass with at least one visual. */
+    documents: number;
+    /** Enabled visuals collected across those documents. */
+    collected: number;
+    /** Unique rasterization units after dedupe (identical content+dpi). */
+    unique: number;
+}
+/**
+ * Get cumulative per-document pre-pass counters. `collected - unique` is the
+ * work the dedupe saved — the `visual` cache benefit the component cache
+ * stats can never show, since `visual` bypasses that cache by design.
+ */
+export declare function getVisualPrepassStats(): VisualPrepassStats;
+export declare function resetVisualPrepassStats(): void;
 /**
  * Collect the props of every enabled `visual` component reachable from
  * `root`. The walk is generic — every array element and object value is

package/dist/core/prerasterizeVisuals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prerasterizeVisuals.d.ts","sourceRoot":"","sources":["../../src/core/prerasterizeVisuals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,6BAA6B,EACnC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAkB/D,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,CA4B/D;AAsDD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC,CAmJrD"}
+{"version":3,"file":"prerasterizeVisuals.d.ts","sourceRoot":"","sources":["../../src/core/prerasterizeVisuals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,6BAA6B,EACnC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAkB/D,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB;AAQD;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAE1D;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAI9C;AASD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,CA4B/D;AAsDD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAC5C,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC,CAuJrD"}

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export declare function getCoreVersion(): string;
 export { generateDocument, generateFromConfig, generateDocumentFromJson, generateDocumentFromFile, generateBufferFromJson, generateBufferFromFile, generateAndSaveFromJson, generateAndSaveFromFile, validateJsonSchema, isReportComponentDefinition, saveDocument, generateAndSave, DocumentGenerator as CoreDocumentGenerator, } from './core/generator';
 export { flattenVisuals, type FlattenVisualsOptions, } from './core/flattenVisuals';
 export { MemoryCache, CacheKeyGenerator, DEFAULT_CACHE_CONFIG, getCacheConfigFromEnv, mergeConfigs, ComponentCacheAnalytics, type CacheConfiguration, type CachedComponent, type CacheStatistics, type CacheKeyOptions, type CacheEvents, type CacheAnalyticsReport, type ComponentPerformanceMetrics, type ComponentCacheTrends, type CacheOptimizationRecommendation, type TimeSeriesPoint, } from './cache/index';
-export { initializeComponentCache, getComponentCache, clearComponentCache, getComponentCacheStats, warmComponentCache, } from './core/cached-render';
+export { initializeComponentCache, getComponentCache, clearComponentCache, getComponentCacheStats, getComponentBypassStats, warmComponentCache, type ComponentBypassReason, type ComponentBypassStats, } from './core/cached-render';
+export { getVisualPrepassStats, resetVisualPrepassStats, type VisualPrepassStats, } from './core/prerasterizeVisuals';
 export { isReportComponent, isSectionComponent, isHeadingComponent, isParagraphComponent, isColumnsComponent, isImageComponent, isStatisticComponent, isTableComponent, isListComponent, isHighchartsComponent, isVisualComponent, } from './types/index';
 export type { ImageContent, StatisticContent, TableData, SectionProperties, ColumnSettings, PageSizeOptions, PageMarginOptions, PageNumberOptions, PageBorderOptions, RenderContext, } from './types/index';
 export * from './utils/formatters';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -4271,6 +4271,33 @@ function componentHasRevision(component) {
 import { createHash as createHash3 } from "crypto";
 var componentCache = null;
 var cacheKeyGen = null;
+var bypassStats = /* @__PURE__ */ new Map();
+function recordBypass(type, reason) {
+  const entry = bypassStats.get(type);
+  if (entry) {
+    entry.renders++;
+  } else {
+    bypassStats.set(type, { renders: 1, reason });
+  }
+}
+function getComponentBypassStats() {
+  return Array.from(bypassStats.entries()).map(([type, s]) => ({
+    type,
+    renders: s.renders,
+    reason: s.reason
+  }));
+}
+var DATE_INDEPENDENT_PLACEHOLDERS = /* @__PURE__ */ new Set(["PAGE", "TOTAL_PAGES"]);
+function usesDateSensitivePlaceholder(serialized) {
+  const placeholderRegex = /\{([^}{]+)\}/g;
+  let match;
+  while ((match = placeholderRegex.exec(serialized)) !== null) {
+    const name = match[1].toUpperCase();
+    if (DATE_INDEPENDENT_PLACEHOLDERS.has(name)) continue;
+    if (PlaceholderRegistry.has(name)) return true;
+  }
+  return false;
+}
 function createThemeHash(theme) {
   const themeString = JSON.stringify(theme);
   return createHash3("sha256").update(themeString).digest("hex").substring(0, 8);
@@ -4312,24 +4339,34 @@ async function clearComponentCache() {
   if (componentCache) {
     await componentCache.clear();
   }
+  bypassStats.clear();
 }
 async function renderComponentWithCache(component, theme, themeName, context, bypassCache = false) {
-  const forceBypassForType = component.name === "toc" || component.name === "section" || component.name === "visual" || component.name === "heading" || // Both explicit lists and markdown-list paragraphs register numbering in
-  // the current document scope. Cached paragraphs can otherwise reference
-  // definitions that only existed in a previous render.
-  component.name === "list" || component.name === "paragraph" || "id" in component || componentHasRevision(component);
+  const bypassReason = componentHasRevision(
+    component
+  ) ? "revision-ids" : "id" in component ? "bookmark-id" : component.name === "toc" || component.name === "section" || component.name === "visual" || component.name === "heading" || // Both explicit lists and markdown-list paragraphs register
+  // numbering in the current document scope. Cached paragraphs can
+  // otherwise reference definitions that only existed in a previous
+  // render.
+  component.name === "list" || component.name === "paragraph" ? "dynamic-context" : null;
   if (!componentCache) {
     initializeComponentCache();
   }
-  if (!componentCache || bypassCache || forceBypassForType || !componentCache.getConfig().enabled) {
+  if (bypassReason !== null) {
+    recordBypass(component.name, bypassReason);
+    return renderComponent(component, theme, themeName, context);
+  }
+  if (!componentCache || bypassCache || !componentCache.getConfig().enabled) {
     return renderComponent(component, theme, themeName, context);
   }
   const componentProps = JSON.stringify(component.props || {});
   const themeHash = createThemeHash(theme);
   const contextKey = context?.section ? `${context.section.currentLayout}:${context.section.columnCount}` : "no-section";
-  const generationDateKey = getGenerationDate().toISOString();
   const baseDirKey = getBaseDir() ?? "";
   const childrenKey = "children" in component && component.children ? `:children:${JSON.stringify(component.children)}` : "";
+  const generationDateKey = usesDateSensitivePlaceholder(
+    componentProps + childrenKey
+  ) ? getGenerationDate().toISOString() : "no-date";
   const cacheKey = `component:${component.name}:${themeHash}:${contextKey}:${generationDateKey}:${baseDirKey}:${componentProps}${childrenKey}`;
   const cached = await componentCache.get(cacheKey);
   if (cached) {
@@ -4372,10 +4409,11 @@ async function warmComponentCache(components) {
   await Promise.all(warmingPromises);
 }
 function getComponentCacheStats() {
+  const bypassedComponents = getComponentBypassStats();
   if (!componentCache) {
-    return null;
+    return bypassedComponents.length > 0 ? { bypassedComponents } : null;
   }
-  return componentCache.getStats();
+  return { ...componentCache.getStats(), bypassedComponents };
 }
 
 // src/core/content.ts
@@ -7229,6 +7267,19 @@ function createLimiter(max) {
 var DEFAULT_FALLBACK_CONCURRENCY = 4;
 var BATCH_TIMEOUT_BASE_MS = 3e4;
 var BATCH_TIMEOUT_PER_SLIDE_MS = 1e4;
+var prepassStats = {
+  documents: 0,
+  collected: 0,
+  unique: 0
+};
+function getVisualPrepassStats() {
+  return { ...prepassStats };
+}
+function resetVisualPrepassStats() {
+  prepassStats.documents = 0;
+  prepassStats.collected = 0;
+  prepassStats.unique = 0;
+}
 function collectVisualProps(root) {
   const found = [];
   const seen = /* @__PURE__ */ new WeakSet();
@@ -7305,6 +7356,9 @@ async function prerasterizeVisuals(root, serviceConfig, options = {}) {
     }
   }
   if (targets.size === 0) return map;
+  prepassStats.documents++;
+  prepassStats.collected += visuals.length;
+  prepassStats.unique += targets.size;
   const unique = [...targets.values()];
   const limit = createLimiter(
     Math.max(1, options.concurrency ?? DEFAULT_FALLBACK_CONCURRENCY)
@@ -9297,11 +9351,13 @@ export {
   generatePluginDocumentSchema,
   generateWarningsDocument,
   export_getCacheConfigFromEnv as getCacheConfigFromEnv,
+  getComponentBypassStats,
   getComponentCache,
   getComponentCacheStats,
   getCoreVersion,
   getExample,
   getExampleNames,
+  getVisualPrepassStats,
   hasNodeBuiltins,
   initializeComponentCache,
   isColumnsComponent,
@@ -9325,6 +9381,7 @@ export {
   minimalTheme,
   modernTheme,
   parseTextWithDecorators,
+  resetVisualPrepassStats,
   runExample,
   saveDocument,
   themes,