@meonode/canvas 1.7.2 → 2.0.0

package/dist/esm/canvas/root.canvas.util.js

@@ -1,6 +1,7 @@
 import { FontLibrary, Canvas } from 'skia-canvas';
 import { ColumnNode, RowNode, BoxNode } from './layout.canvas.util.js';
-import { ImageNode, disposeImageCache, getImageCache } from './image.canvas.util.js';
+import { ImageNode } from './image.canvas.util.js';
+import { deleteDiskCache } from '../util/disk.cache.js';
 import { TextNode } from './text.canvas.util.js';
 import { ChartNode } from './chart.canvas.util.js';
 import { GridItemNode, GridNode } from './grid.canvas.util.js';
@@ -14,26 +15,48 @@ import { fileURLToPath } from 'node:url';
 
 /** Registry to track fonts that have already been loaded */
 const registeredFonts = new Map();
-/** Engine configuration */
-let _workerMode = true;
-let _workerPoolSize = Math.max(1, cpus().length - 1);
+/**
+ * FinalizationRegistry to clean up WorkerCanvas instances that were not explicitly released.
+ * This is a safety net — users should still call .release() explicitly.
+ */
+const canvasRegistry = new FinalizationRegistry(heldValue => {
+    // Best-effort cleanup — worker may already be terminated
+    try {
+        // Access workers via a public method or make it accessible
+        // For now, just try to send the message and let errors be caught
+        if (_workerPool) {
+            ;
+            _workerPool.workers?.[heldValue.workerIdx]?.postMessage({ type: 'release', canvasId: heldValue.canvasId });
+        }
+    }
+    catch {
+        // Worker already gone — nothing to clean up
+    }
+});
+/** Engine configuration — legacy support for configure() */
+let _defaultWorkerMode = true;
+let _defaultWorkerPoolSize = Math.max(1, cpus().length - 1);
 let _workerPool = null;
 /**
  * Configure the canvas rendering engine.
  * Call this once at application startup before rendering.
+ * @deprecated Pass workerMode and workers directly to Root() props instead.
  */
 function configure(options) {
     if (options.workerMode !== undefined)
-        _workerMode = options.workerMode;
+        _defaultWorkerMode = options.workerMode;
     if (options.workers !== undefined)
-        _workerPoolSize = options.workers;
-    if (options.imageCacheSize !== undefined) {
-        // Dispose existing cache and create a new one with the specified size
-        disposeImageCache();
-        getImageCache(options.imageCacheSize);
-    }
-    if (_workerMode) {
-        _workerPool = new WorkerPool(_workerPoolSize);
+        _defaultWorkerPoolSize = options.workers;
+}
+/**
+ * Terminate all worker pools and free worker thread resources.
+ * Call this when shutting down a long-running server to clean up immediately.
+ * After calling, you must call configure() again before rendering.
+ */
+function terminate() {
+    if (_workerPool) {
+        _workerPool.terminate();
+        _workerPool = null;
     }
 }
 /**
@@ -55,6 +78,8 @@ class WorkerCanvas {
         this._pool = opts.pool;
         this._workerIdx = opts.workerIdx;
         this._canvasId = opts.canvasId;
+        // Register for finalizer-based cleanup if user forgets to call .release()
+        canvasRegistry.register(this, { workerIdx: opts.workerIdx, canvasId: opts.canvasId }, this);
     }
     _call(method, ...args) {
         return this._pool.callOnCanvas(this._workerIdx, this._canvasId, method, args);
@@ -105,6 +130,8 @@ class WorkerCanvas {
     /** Release the Canvas from worker memory. Call when done with this object. */
     release() {
         this._pool.releaseCanvas(this._workerIdx, this._canvasId);
+        // Unregister from finalizer since we're explicitly cleaning up
+        canvasRegistry.unregister(this);
     }
 }
 /** Worker thread pool — routes render and canvas-call messages */
@@ -295,6 +322,7 @@ class RootNode extends ColumnNode {
      * @returns Promise resolving to the rendered Canvas instance
      */
     async render() {
+        const diskCacheKeys = this.props.useDiskCache ? new Set() : undefined;
         try {
             // Step 1: Load all images with a concurrency limit to avoid overwhelming remote sources.
             // A per-render cache deduplicates identical src+color combinations within this render pass.
@@ -306,7 +334,7 @@ class RootNode extends ColumnNode {
                 const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
                     while (queue.length > 0) {
                         const node = queue.shift();
-                        await node.load(imageCache);
+                        await node.load(imageCache, diskCacheKeys);
                     }
                 });
                 await Promise.allSettled(workers);
@@ -334,35 +362,26 @@ class RootNode extends ColumnNode {
             return this.canvas;
         }
         finally {
-            // Always clear the persistent image cache after render (success or error)
-            // so resolved CanvasImage references don't outlive the render pass.
-            disposeImageCache();
+            if (diskCacheKeys?.size) {
+                await Promise.allSettled([...diskCacheKeys].map(key => deleteDiskCache(key)));
+            }
         }
     }
 }
-/**
- * Creates and renders a new root node with the given properties.
- * When worker mode is enabled via configure(), rendering runs in a worker thread
- * and the returned object implements the same toBuffer/toBufferSync interface.
- * @param props Configuration properties for the root node
- * @returns Promise resolving to the rendered Canvas (or WorkerCanvas in worker mode)
- */
-const Root = async (props) => {
-    try {
-        if (_workerMode) {
-            if (!_workerPool) {
-                _workerPool = new WorkerPool(_workerPoolSize);
-            }
-            const result = await _workerPool.render(props);
-            return new WorkerCanvas({ ...result, pool: _workerPool });
+async function Root(props) {
+    // Determine worker mode: props override legacy configure()
+    const workerMode = props.workerMode ?? _defaultWorkerMode;
+    const workerPoolSize = props.workers ?? _defaultWorkerPoolSize;
+    if (workerMode) {
+        // Lazy initialize worker pool
+        if (!_workerPool) {
+            _workerPool = new WorkerPool(workerPoolSize);
         }
-        return await new RootNode(props).render();
+        const result = await _workerPool.render(props);
+        return new WorkerCanvas({ ...result, pool: _workerPool });
     }
-    catch (err) {
-        // Ensure cache is cleared even if Root-level orchestration fails
-        disposeImageCache();
-        throw err;
-    }
-};
+    // Non-worker mode — render directly and return Canvas
+    return new RootNode(props).render();
+}
 
-export { Root, RootNode, buildTree, configure };
+export { Root, RootNode, buildTree, configure, terminate };

package/dist/esm/index.d.ts

@@ -1,10 +1,11 @@
 export * from './constant/common.const.js';
 export * from './canvas/canvas.type.js';
 export { Box, Column, Row, type BoxNode } from './canvas/layout.canvas.util.js';
-export { Image, disposeImageCache } from './canvas/image.canvas.util.js';
+export { Image } from './canvas/image.canvas.util.js';
 export { Text } from './canvas/text.canvas.util.js';
-export { Root, configure } from './canvas/root.canvas.util.js';
+export { Root, configure, terminate } from './canvas/root.canvas.util.js';
 export { GridItem } from './canvas/grid.canvas.util.js';
 export { Grid } from './canvas/grid.canvas.util.js';
 export { Chart } from './canvas/chart.canvas.util.js';
+export { clearDiskCache } from './util/disk.cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,gCAAgC,CAAA;AAC/E,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACxE,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,MAAM,gCAAgC,CAAA;AAC/E,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAA;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/esm/index.js

@@ -1,8 +1,9 @@
 export { Border, Style } from './constant/common.const.js';
 export { Box, Column, Row } from './canvas/layout.canvas.util.js';
-export { Image, disposeImageCache } from './canvas/image.canvas.util.js';
+export { Image } from './canvas/image.canvas.util.js';
 export { Text } from './canvas/text.canvas.util.js';
-export { Root, configure } from './canvas/root.canvas.util.js';
+export { Root, configure, terminate } from './canvas/root.canvas.util.js';
 export { Grid, GridItem } from './canvas/grid.canvas.util.js';
 export { Chart } from './canvas/chart.canvas.util.js';
+export { clearDiskCache } from './util/disk.cache.js';
 export * from 'yoga-layout';

package/dist/esm/util/disk.cache.d.ts

@@ -1,4 +1,10 @@
 export declare function hashBuffer(buf: Buffer): string;
 export declare function readDiskCache(key: string): Promise<Buffer | null>;
 export declare function writeDiskCache(key: string, data: Buffer): Promise<void>;
+export declare function deleteDiskCache(key: string): Promise<void>;
+/**
+ * Delete the entire disk cache directory.
+ * Called on process exit to clean up any orphaned cache files.
+ */
+export declare function clearDiskCache(): Promise<void>;
 //# sourceMappingURL=disk.cache.d.ts.map

package/dist/esm/util/disk.cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disk.cache.d.ts","sourceRoot":"","sources":["../../../src/util/disk.cache.ts"],"names":[],"mappings":"AAaA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOvE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E"}
+{"version":3,"file":"disk.cache.d.ts","sourceRoot":"","sources":["../../../src/util/disk.cache.ts"],"names":[],"mappings":"AAaA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOvE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAMpD"}

package/dist/esm/util/disk.cache.js

@@ -31,5 +31,36 @@ async function writeDiskCache(key, data) {
         // best-effort — cache write failures are non-fatal
     }
 }
+async function deleteDiskCache(key) {
+    try {
+        await promises.unlink(join(CACHE_DIR, key));
+    }
+    catch {
+        // non-fatal — file may not exist if write failed earlier
+    }
+}
+/**
+ * Delete the entire disk cache directory.
+ * Called on process exit to clean up any orphaned cache files.
+ */
+async function clearDiskCache() {
+    try {
+        await promises.rm(CACHE_DIR, { recursive: true, force: true });
+    }
+    catch {
+        // non-fatal — directory may not exist
+    }
+}
+// Clean up disk cache on process exit to handle crashes mid-render
+process.on('beforeExit', () => {
+    // Fire and forget — best effort cleanup
+    clearDiskCache();
+});
+// Also clean up on SIGINT/SIGTERM for graceful shutdowns
+const cleanupOnExit = () => {
+    clearDiskCache().finally(() => process.exit(0));
+};
+process.on('SIGINT', cleanupOnExit);
+process.on('SIGTERM', cleanupOnExit);
 
-export { hashBuffer, readDiskCache, writeDiskCache };
+export { clearDiskCache, deleteDiskCache, hashBuffer, readDiskCache, writeDiskCache };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meonode/canvas",
-  "version": "1.7.2",
+  "version": "2.0.0",
   "description": "A declarative, component-based library for server-side canvas image generation. Write complex visuals with simple functions, similar to the composition style of @meonode/ui.",
   "keywords": [
     "canvas",
@@ -42,6 +42,7 @@
     "lint": "eslint . --ext .ts,.tsx,.js,.jsx,.mjs --fix",
     "format": "prettier --write .",
     "generate:samples": "npx tsx scripts/generate_sample_charts.ts && npx tsx scripts/generate_sample_grids.ts && npx tsx scripts/generate_sample_nested_grids.ts",
+    "check:memory": "npx tsx --expose-gc scripts/check_memory.ts",
     "prepare": "husky"
   },
   "devDependencies": {