@cellaware/utils 8.4.0 → 8.4.1

package/dist/browser.d.ts

@@ -1,3 +1,37 @@
+import type { Browser } from "playwright-core";
+/**
+ * Browserless (hosted) performance & reliability notes
+ *
+ * 1) Prefer connect-per-request (default)
+ *    - We use chromium.connectOverCDP() instead of launching a local browser.
+ *    - In serverless, connecting + closing per request is the safest and most cost-predictable option.
+ *    - Hosted Browserless usage is typically metered by session/connection time, so leaving connections
+ *      open while idle can increase cost.
+ *
+ * 2) Always isolate work in a fresh BrowserContext per PDF
+ *    - Never reuse BrowserContext or Page across requests.
+ *    - Context-per-request avoids cookie/storage leaks, cross-request interference, and memory growth.
+ *
+ * 3) Close deterministically (inner → outer)
+ *    - Always close Page, then Context, then Browser (the CDP connection).
+ *    - This releases remote resources quickly and prevents “dangling sessions” on the provider side.
+ *
+ * 4) Waiting strategy
+ *    - Default waitUntil: "load" to avoid hanging on long-lived network activity (analytics/beacons).
+ *    - If your HTML depends on external assets (remote CSS/fonts/images), consider "networkidle",
+ *      or better: emit an explicit readiness signal and waitForFunction() for deterministic completion.
+ *
+ * 5) Biggest speed wins usually come from reducing network work
+ *    - Inline critical CSS and avoid loading third-party scripts if possible.
+ *    - Host/inline fonts and images where feasible to reduce variability and speed up rendering.
+ *    - The less the page has to fetch, the faster and more consistent PDF generation becomes.
+ *
+ * 6) Optional burst optimization (only if needed)
+ *    - If you generate many PDFs back-to-back on the same warm instance, you can reuse the CDP
+ *      connection briefly (with a short idle timeout).
+ *    - Still keep Context-per-request. Avoid keeping the connection open indefinitely to prevent idle cost.
+ */
+export declare function getBrowser(): Promise<Browser>;
 export interface PdfOptions {
     /**
      * Display header and footer. Defaults to `false`.

package/dist/browser.js

@@ -31,7 +31,7 @@ import { chromium } from "playwright-core";
  *      connection briefly (with a short idle timeout).
  *    - Still keep Context-per-request. Avoid keeping the connection open indefinitely to prevent idle cost.
  */
-async function getBrowser() {
+export async function getBrowser() {
     const token = process.env.BROWSERLESS_TOKEN;
     if (!token) {
         throw new Error('BROWSER: `BROWSER_TOKEN` environment variable is not set');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cellaware/utils",
-    "version": "8.4.0",
+    "version": "8.4.1",
     "description": "Cellaware Utilities for Node.js",
     "author": "Cellaware Technologies",
     "type": "module",
@@ -27,4 +27,4 @@
     "devDependencies": {
         "typescript": "^5.3.2"
     }
-}
+}