@agile-team/mach-report 2.16.0 → 2.17.0

package/dist/runtime-dL5ygIfa.cjs

@@ -0,0 +1 @@
+"use strict";var J=Object.create;var D=Object.defineProperty;var V=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var U=Object.getPrototypeOf,X=Object.prototype.hasOwnProperty;var W=(e,t,a,c)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of N(t))!X.call(e,s)&&s!==a&&D(e,s,{get:()=>t[s],enumerable:!(c=V(t,s))||c.enumerable});return e};var E=(e,t,a)=>(a=e!=null?J(U(e)):{},W(t||!e||!e.__esModule?D(a,"default",{value:e,enumerable:!0}):a,e));const n=require("./json-snapshot-D7PE1NsU.cjs"),F=require("./report-params-WDGrA4oP.cjs"),k=require("./param-validation-C3HlcLLO.cjs"),o=require("./sha256-BshdOkCC.cjs"),z=require("./template-registry-CpysHAxy.cjs"),G=require("./tree-CLpxYbKa.cjs"),M=require("./assets-Dfs2ElxI.cjs"),b=require("./prepared-Ch1x_Gog.cjs");function I(e=[]){return e.map(({code:t,message:a,severity:c,pageIndex:s,componentIndex:r})=>({code:t,message:a,severity:c,path:r<0?`$.pages.${s}`:`$.pages.${s}.components.${r}`}))}async function q(e,t,a=Date.now()){const c=e.prepared;if(e.fidelity==="strict"&&c.diagnostics.some(f=>f.code==="asset-render-failed"||f.code==="asset-budget-exceeded"))throw new n.ReportSourceError("validate","严格输出拒绝已有资产渲染降级，请修复组件后重新准备报表。");const s=e.format==="pdf"?await import("@agile-team/mach-report/pdf"):void 0;o.throwIfAborted(e.signal);const r=e.pdf?.customFontFaces??(e.pdf?.customFontBytes?{regular:e.pdf.customFontBytes}:void 0),u=s&&r?s.createFontBytesMeasurer(r):void 0,m=n.createReportTaskReporter(e),p=await m.run("encode",async()=>{let f;if(e.format==="pdf"){o.throwIfAborted(e.signal);const i=await s.renderPlanToPdf(c.plan,{...e.pdf,...u?{measurer:u}:{},fidelity:e.fidelity,signal:e.signal,onProgress:(w,l)=>m.progress("encode",w,l)});f=i.bytes,c.diagnostics.push(...I(i.diagnostics)),c.diagnostics.push(...i.fidelityWarnings.map(w=>({code:"pdf-fidelity",message:w,severity:"warning"})),...i.pageErrors.map(w=>({code:"pdf-page",message:w,severity:"error"}))),i.unsupportedTextCount&&c.diagnostics.push({code:"pdf-font",message:`${i.unsupportedTextCount} 段文本包含当前字体不支持的字符`,severity:"warning"})}else{const{renderPlanToXlsx:i}=await import("@agile-team/mach-report/xlsx");o.throwIfAborted(e.signal);const w=await i(c.plan,{...e.xlsx,fidelity:e.fidelity,signal:e.signal,onProgress:(l,h)=>m.progress("encode",l,h)});f=new Uint8Array(w.buffer),c.diagnostics.push(...I(w.diagnostics)),c.diagnostics.push(...w.warnings.map(l=>({code:"xlsx-fidelity",message:l,severity:"warning"})))}return o.throwIfAborted(e.signal),f});o.assertBudget(t,"maxOutputBytes",p.byteLength);const{plan:d,...y}=c;return{...y,bytes:p,format:e.format,contentType:e.format==="pdf"?"application/pdf":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",stats:{...y.stats,durationMs:Date.now()-a,outputBytes:p.byteLength}}}function A(e){return{...e,reportIds:[...e.reportIds],...e.params?{params:{...e.params}}:{}}}function $(e,t){if(t.length===0)throw new n.ReportSourceError("config","缺少报表 ID");return t.map(a=>{if(!Object.prototype.hasOwnProperty.call(e,a))throw new n.ReportSourceError("config",`未注册报表 ${a}`);return e[a]})}function T(e){return e.grid?.cells.reduce((t,a)=>t+a.reduce((c,s)=>c+(s?1+(s.children?.reduce((r,u)=>r+T(u),0)??0):0),0),0)??0}function Q(e,t,a){return e.pages.reduce((c,s)=>c+s.components.reduce((r,u)=>u.kind!=="list"?r+T(u):r+n.estimateListLayoutCells(u,t,a),0),0)}function H(e,t=Object.keys(e)){return $(e,t).map((a,c)=>{const s=t[c],r=F.getReportParamDefs(e,[s]);return{id:s,params:JSON.parse(JSON.stringify(r)),paramsSchema:k.reportParamsJsonSchema(r),datasetsSchema:Object.fromEntries(Object.entries(a.dataSchema??{}).map(([u,m])=>[u,n.templateDatasetJsonSchema(typeof a.template=="function"?void 0:a.template,u,m)])),capabilities:{save:!!a.provider?.save,export:!!a.provider?.export,templates:!!a.provider?.templates}}})}function j(e,t){$(e,t.reportIds);const a=k.validateReportParams(F.getReportParamDefs(e,t.reportIds),t.params),c=t.reportIds.flatMap(r=>k.validateReportParams(F.getReportParamDefs(e,[r]),t.params).issues),s=new Map(c.map(r=>[JSON.stringify(r),r]));return{...a,ok:s.size===0,issues:[...s.values()]}}function O(e,t){const a=z.validateRenderPlan(e.plan);if(!a.ok)throw new n.ReportSourceError("validate",`执行器返回无效计划：${a.errors[0]?.path}`);const c=e.plan.pages.length,s=e.plan.pages.reduce((r,u)=>r+u.components.reduce((m,p)=>m+T(p),0),0);return o.assertBudget(t,"maxRows",e.stats.rows),o.assertBudget(t,"maxPages",c),o.assertBudget(t,"maxCells",s),{...e,stats:{...e.stats,pages:c,cells:s}}}function L(e,t){const a=j(e.reports,t);if(!a.ok)throw new k.ReportParamValidationError(a.issues)}function K(e){const t={...o.DEFAULT_REPORT_RUNTIME_BUDGET,...e.budget};o.validateBudget(t);const a=async(s,r)=>{const u=Date.now();let m=0,p=0;const d=[],y={},f=[],i=Object.fromEntries(Object.entries(e.reports).map(([g,x])=>[g,{...x,pagination:{...e.pagination,...x.pagination,...r?{measurer:r}:{}},dataValidation:{...x.dataValidation,maxRows:Math.min(t.maxRows??1e5,x.dataValidation?.maxRows??1/0),maxCells:Math.min(t.maxCells??2e6,x.dataValidation?.maxCells??1/0)}}])),l=await n.createReportSource(i,{maxPages:t.maxPages,maxCells:t.maxCells,onDatasets:(g,x,v)=>{try{m+=n.templateDatasetRowCount(v,x,{maxRows:t.maxRows,signal:s.signal})}catch(R){throw R instanceof G.TreeRowLimitError?new o.ReportRuntimeError("budget",R.message,"$.budget.maxRows"):R}o.assertBudget(t,"maxRows",m),p+=Q(v,x,i[g]?.pagination),o.assertBudget(t,"maxCells",p)}})({...s,params:s.params??{},onWarning:g=>d.push({code:"layout",message:g,severity:"warning"}),onQueryResult:(g,x,v=0)=>{const R=n.reportOccurrenceScope(v,g);Object.defineProperty(y,g,{value:{revision:x.revision,sourceToken:x.sourceToken},enumerable:!0,writable:!0}),f.push({reportId:g,reportIndex:v,reportScope:R,...x.revision===void 0?{}:{revision:x.revision},...x.sourceToken===void 0?{}:{sourceToken:x.sourceToken}}),d.push(...(x.diagnostics??[]).map(P=>({...P,...P.target?{target:{...P.target,reportScope:R,...P.target.tableId?{tableId:JSON.stringify([v,g,P.target.tableId])}:{}}}:{}})))}}).catch(g=>{throw g instanceof n.ReportSourceError&&g.cause instanceof n.PaginatePageLimitError?new o.ReportRuntimeError("budget",g.cause.message,"$.budget.maxPages"):g instanceof n.ReportSourceError&&g.cause instanceof n.PaginateCellLimitError?new o.ReportRuntimeError("budget",g.cause.message,"$.budget.maxCells"):g});o.throwIfAborted(s.signal);const h=e.assets?await n.createReportTaskReporter(s).run("assets",()=>M.resolvePlanAssets(l,{...e.assets,signal:s.signal})):{plan:l,diagnostics:[]},B=h.plan;d.push(...I(h.diagnostics));const C=B.pages.reduce((g,x)=>g+x.components.reduce((v,R)=>v+T(R),0),0);o.assertBudget(t,"maxPages",B.pages.length),o.assertBudget(t,"maxCells",C);const S=b.reportFontFingerprint(s.pdf),_=e.pagination?.measurer||Object.values(e.reports).some(g=>g.pagination?.measurer);return{plan:B,diagnostics:d,revisions:y,sources:f,layout:{textMetrics:S?"font-bytes":_?"provided":"heuristic",...S?{fontFingerprint:S}:{}},stats:{rows:m,pages:B.pages.length,cells:C,durationMs:Date.now()-u}}},c=async s=>{const r=Date.now();if(s.format!=="pdf"&&s.format!=="xlsx")throw new n.ReportSourceError("config","不支持的报表导出格式");const u=s.format==="pdf"?await import("@agile-team/mach-report/pdf"):void 0;o.throwIfAborted(s.signal);const m=s.pdf?.customFontFaces??(s.pdf?.customFontBytes?{regular:s.pdf.customFontBytes}:void 0),p=u&&m?u.createFontBytesMeasurer(m):void 0,d=await a(s,p);return o.throwIfAborted(s.signal),q({...s,prepared:d},t,r)};return{describe:s=>H(e.reports,s),validate:s=>j(e.reports,s),prepare:s=>o.controlled(s.signal,t.maxDurationMs,async r=>{const{signal:u,onEvent:m,...p}=A(s),d={...p,...p.pdf?{pdf:b.snapshotPdfFonts(p.pdf)}:{},taskId:p.taskId??n.reportTaskId()},y=m?h=>n.notifyReportTaskEvent(m,h,r):void 0,f={...d,signal:r,onEvent:y};n.createReportTaskReporter(f).runSync("validate",()=>L(e,d));let i;const w=d.pdf?.customFontFaces??(d.pdf?.customFontBytes?{regular:d.pdf.customFontBytes}:void 0);if(!e.executor&&w){const h=await import("@agile-team/mach-report/pdf");o.throwIfAborted(r),i=h.createFontBytesMeasurer(w)}const l=e.executor?await e.executor.prepare(d,r,y):await a(f,i);return O(l,t)}),exportPrepared:s=>o.controlled(s.signal,t.maxDurationMs,async r=>{const u=Date.now(),{signal:m,onEvent:p,...d}=s,y=O(b.snapshotPreparedReport(s.prepared,t.maxPreparedBytes??64e6,r),t),f={...d,xlsx:b.snapshotXlsxOptions(d.xlsx),prepared:y,...d.pdf?{pdf:b.snapshotPdfFonts(d.pdf)}:{},taskId:d.taskId??n.reportTaskId()};if(f.format!=="pdf"&&f.format!=="xlsx")throw new n.ReportSourceError("config","不支持的报表导出格式");const i=p?l=>n.notifyReportTaskEvent(p,l,r):void 0;if(e.executor){if(!e.executor.exportPrepared)throw new n.ReportSourceError("config","执行器未实现 exportPrepared；请升级执行器或显式使用本地运行时");const l=await e.executor.exportPrepared(f,r,i);return o.assertBudget(t,"maxRows",l.stats.rows),o.assertBudget(t,"maxPages",l.stats.pages),o.assertBudget(t,"maxCells",l.stats.cells),o.assertBudget(t,"maxOutputBytes",l.bytes.byteLength),{...l,stats:{...l.stats,outputBytes:l.bytes.byteLength}}}const w={...f,signal:r,onEvent:i};if(n.createReportTaskReporter(w).runSync("validate",()=>b.checkPreparedFont(w)),e.assets){const l=await n.createReportTaskReporter(w).run("assets",()=>M.resolvePlanAssets(y.plan,{...e.assets,signal:r}));y.plan=l.plan,y.diagnostics.push(...I(l.diagnostics))}return q(w,t,u)}),export:s=>o.controlled(s.signal,t.maxDurationMs,async r=>{const{signal:u,onEvent:m,...p}=A(s),d={...p,xlsx:b.snapshotXlsxOptions(p.xlsx),...p.pdf?{pdf:b.snapshotPdfFonts(p.pdf)}:{},taskId:p.taskId??n.reportTaskId()},y=m?w=>n.notifyReportTaskEvent(m,w,r):void 0,f={...d,signal:r,onEvent:y};if(n.createReportTaskReporter(f).runSync("validate",()=>L(e,d)),d.format!=="pdf"&&d.format!=="xlsx")throw new n.ReportSourceError("config","不支持的报表导出格式");const i=e.executor?await e.executor.export(d,r,y):await c(f);return o.assertBudget(t,"maxRows",i.stats.rows),o.assertBudget(t,"maxPages",i.stats.pages),o.assertBudget(t,"maxCells",i.stats.cells),o.assertBudget(t,"maxOutputBytes",i.bytes.byteLength),{...i,stats:{...i.stats,outputBytes:i.bytes.byteLength}}})}}exports.createReportRuntime=K;exports.enforcePrepared=O;

package/dist/sbom.cdx.json

@@ -6,7 +6,7 @@
     "component": {
       "type": "library",
       "name": "@agile-team/mach-report",
-      "version": "2.16.0"
+      "version": "2.17.0"
     },
     "properties": [
       {

package/dist/server/node.d.cts

@@ -87,6 +87,14 @@ export declare function createNodeAutoReportExporter(options?: Omit<ReportExport
 /** 独立 worker_threads 适配器；worker 入口注册自己的模板/Provider，不把函数跨线程序列化。 */
 export declare function createNodeReportExecutor(options: NodeReportExecutorOptions): ReportRuntimeExecutor;
 
+export declare interface FileReportDocumentStore extends ReportDocumentStore {
+    close(): Promise<void>;
+}
+
+export declare interface FileReportDocumentStoreOptions extends ReportDocumentBudget {
+    directory: string;
+}
+
 export declare interface FileReportJobStore extends ReportJobStore {
     close(): Promise<void>;
 }
@@ -141,6 +149,9 @@ export declare interface NodeReportExecutorOptions extends ReportWorkerOptions {
     workerOptions?: WorkerOptions_2;
 }
 
+/** Exclusive-process disk reference. Pages stay on disk; manifest/page reads and appends are bounded. */
+export declare function openFileReportDocumentStore(options: FileReportDocumentStoreOptions): Promise<FileReportDocumentStore>;
+
 /** Durable local store with one process owner; database adapters provide multi-instance atomic CAS. */
 export declare function openFileReportJobStore(options: FileReportJobStoreOptions): Promise<FileReportJobStore>;
 
@@ -294,6 +305,41 @@ declare interface ReportDiagnostic {
     target?: ReportDataTarget;
 }
 
+declare interface ReportDocumentBudget {
+    maxDocuments?: number;
+    maxBytes?: number;
+    maxPages?: number;
+    maxPageBytes?: number;
+    maxManifestBytes?: number;
+}
+
+declare interface ReportDocumentManifest {
+    scope: string;
+    id: string;
+    version: string;
+    /** CAS token increases after each append and completion. */
+    revision: number;
+    state: "building" | "complete" | "failed";
+    failure?: {
+        code: "cancelled" | "generation";
+        message: string;
+    };
+    pageCount: number;
+    bytes: number;
+    plan: Omit<RenderPlan, "pages">;
+    metadata?: Omit<PreparedReport, "plan">;
+}
+
+declare interface ReportDocumentStore {
+    create(input: Pick<ReportDocumentManifest, "scope" | "id" | "version" | "plan">, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    append(scope: string, id: string, version: string, expectedRevision: number, page: PlanPage, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    complete(scope: string, id: string, version: string, expectedRevision: number, metadata?: Omit<PreparedReport, "plan">, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    fail(scope: string, id: string, version: string, expectedRevision: number, failure: NonNullable<ReportDocumentManifest["failure"]>): Promise<ReportDocumentManifest>;
+    read(scope: string, id: string, signal?: AbortSignal): Promise<ReportDocumentManifest | undefined>;
+    readPage(scope: string, id: string, version: string, index: number, signal?: AbortSignal): Promise<PlanPage | undefined>;
+    remove(scope: string, id: string, version: string, signal?: AbortSignal): Promise<boolean>;
+}
+
 export declare interface ReportExportDecision {
     mode: "local" | "worker";
     reason: ReportExportDecisionReason;

package/dist/server/node.d.ts

@@ -87,6 +87,14 @@ export declare function createNodeAutoReportExporter(options?: Omit<ReportExport
 /** 独立 worker_threads 适配器；worker 入口注册自己的模板/Provider，不把函数跨线程序列化。 */
 export declare function createNodeReportExecutor(options: NodeReportExecutorOptions): ReportRuntimeExecutor;
 
+export declare interface FileReportDocumentStore extends ReportDocumentStore {
+    close(): Promise<void>;
+}
+
+export declare interface FileReportDocumentStoreOptions extends ReportDocumentBudget {
+    directory: string;
+}
+
 export declare interface FileReportJobStore extends ReportJobStore {
     close(): Promise<void>;
 }
@@ -141,6 +149,9 @@ export declare interface NodeReportExecutorOptions extends ReportWorkerOptions {
     workerOptions?: WorkerOptions_2;
 }
 
+/** Exclusive-process disk reference. Pages stay on disk; manifest/page reads and appends are bounded. */
+export declare function openFileReportDocumentStore(options: FileReportDocumentStoreOptions): Promise<FileReportDocumentStore>;
+
 /** Durable local store with one process owner; database adapters provide multi-instance atomic CAS. */
 export declare function openFileReportJobStore(options: FileReportJobStoreOptions): Promise<FileReportJobStore>;
 
@@ -294,6 +305,41 @@ declare interface ReportDiagnostic {
     target?: ReportDataTarget;
 }
 
+declare interface ReportDocumentBudget {
+    maxDocuments?: number;
+    maxBytes?: number;
+    maxPages?: number;
+    maxPageBytes?: number;
+    maxManifestBytes?: number;
+}
+
+declare interface ReportDocumentManifest {
+    scope: string;
+    id: string;
+    version: string;
+    /** CAS token increases after each append and completion. */
+    revision: number;
+    state: "building" | "complete" | "failed";
+    failure?: {
+        code: "cancelled" | "generation";
+        message: string;
+    };
+    pageCount: number;
+    bytes: number;
+    plan: Omit<RenderPlan, "pages">;
+    metadata?: Omit<PreparedReport, "plan">;
+}
+
+declare interface ReportDocumentStore {
+    create(input: Pick<ReportDocumentManifest, "scope" | "id" | "version" | "plan">, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    append(scope: string, id: string, version: string, expectedRevision: number, page: PlanPage, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    complete(scope: string, id: string, version: string, expectedRevision: number, metadata?: Omit<PreparedReport, "plan">, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    fail(scope: string, id: string, version: string, expectedRevision: number, failure: NonNullable<ReportDocumentManifest["failure"]>): Promise<ReportDocumentManifest>;
+    read(scope: string, id: string, signal?: AbortSignal): Promise<ReportDocumentManifest | undefined>;
+    readPage(scope: string, id: string, version: string, index: number, signal?: AbortSignal): Promise<PlanPage | undefined>;
+    remove(scope: string, id: string, version: string, signal?: AbortSignal): Promise<boolean>;
+}
+
 export declare interface ReportExportDecision {
     mode: "local" | "worker";
     reason: ReportExportDecisionReason;