🗑️ Add deprecation warnings

Author: ralfstx

CHANGELOG.md

@@ -51,6 +51,7 @@ Minimum build requirements have been raised to Node 20 and npm 10.
 - The `images` property in a document definition.
 - The `makePdf` function in favor of the `makePdf` method on the
   `PdfMaker` class.
+- Using file paths as image sources in favor of `file:` URLs.
 
 ## [0.5.4] - 2024-02-25
 

src/api/PdfMaker.ts

@@ -57,8 +57,18 @@ export class PdfMaker {
   async makePdf(definition: DocumentDefinition): Promise<Uint8Array> {
     const def = readAs(definition, 'definition', readDocumentDefinition);
     const ctx = { ...this.#ctx };
-    if (def.fonts) ctx.fontStore = new FontStore(def.fonts);
-    if (def.images) ctx.imageStore = new ImageStore(def.images);
+    if (def.fonts) {
+      ctx.fontStore = new FontStore(def.fonts);
+      console.warn(
+        'Registering fonts via document definition is deprecated. Use PdfMaker.registerFont() instead.',
+      );
+    }
+    if (def.images) {
+      ctx.imageStore = new ImageStore(def.images);
+      console.warn(
+        'Registering images via document definition is deprecated. Use URLs to include images instead.',
+      );
+    }
     if (def.dev?.guides != null) ctx.guides = def.dev.guides;
     const pages = await layoutPages(def, ctx);
     return await renderDocument(def, pages);

src/api/document.ts

@@ -63,6 +63,8 @@ export type DocumentDefinition = {
    * Pre-defined image data. These images can be used by their name in
    * the document. This is only needed if images cannot be loaded
    * directly from the file system.
+   *
+   * @deprecated Use URLs to include images.
    */
   images?: ImagesDefinition;
 
@@ -191,6 +193,8 @@ export type FontDefinition = {
  * Pre-defined image data. These images can be used by their name in the
  * document. This is only needed if images cannot be loaded directly
  * from the file system.
+ *
+ * @deprecated Use URLs to include images.
  */
 export type ImagesDefinition = { [name: string]: ImageDefinition };
 
@@ -201,6 +205,8 @@ export type ImageDefinition = {
   /**
    * The image data, as a Uint8Array, ArrayBuffer, or a base64-encoded string.
    * Supported image formats are PNG and JPEG.
+   *
+   *  @deprecated Use URLs to include images.
    */
   data: string | Uint8Array | ArrayBuffer;
 };

src/api/make-pdf.ts

@@ -1,10 +1,5 @@
-import { FontStore } from '../font-store.ts';
-import { ImageStore } from '../image-store.ts';
-import { layoutPages } from '../layout/layout.ts';
-import { readDocumentDefinition } from '../read-document.ts';
-import { renderDocument } from '../render/render-document.ts';
-import { readAs } from '../types.ts';
 import type { DocumentDefinition } from './document.ts';
+import { PdfMaker } from './PdfMaker.ts';
 
 /**
  * Generates a PDF from the given document definition.
@@ -16,11 +11,9 @@ import type { DocumentDefinition } from './document.ts';
  * that instance.
  */
 export async function makePdf(definition: DocumentDefinition): Promise<Uint8Array> {
-  const def = readAs(definition, 'definition', readDocumentDefinition);
-  const fontStore = new FontStore(def.fonts ?? []);
-  const imageStore = new ImageStore(def.images ?? []);
-  const guides = !!def.dev?.guides;
-  const ctx = { fontStore, imageStore, guides };
-  const pages = await layoutPages(def, ctx);
-  return await renderDocument(def, pages);
+  console.warn(
+    'makePdf is deprecated. Create an instance of `PdfMaker` and call `makePdf` on that instance.',
+  );
+  const pdfMaker = new PdfMaker();
+  return await pdfMaker.makePdf(definition);
 }

src/image-store.ts

@@ -42,6 +42,9 @@ export class ImageStore {
         const { data } = await this.#dataLoader(url);
         return data;
       }
+      console.warn(
+        `Loading images from file names is deprecated ('${url}'). Use file:/ URLs instead.`,
+      );
       const data = await readRelativeFile('/', url.replace(/^\/+/, ''));
       return new Uint8Array(data);
     } catch (error) {