@dicebear/converter 10.0.0-rc.1 → 10.0.0-rc.3

package/lib/core.js

@@ -12,6 +12,12 @@ export const toWebp = (avatar, options = {}) => {
 export const toAvif = (avatar, options = {}) => {
     return toFormat(avatar, 'avif', options);
 };
+/**
+ * Browser conversion entry point. Returns a {@link Result} with `toDataUri()`
+ * and `toArrayBuffer()` methods that lazily render the avatar to the chosen
+ * raster format. Warns when `includeExif` is set, since Exif metadata is
+ * only supported by the Node build.
+ */
 function toFormat(avatar, format, options = {}) {
     if (options.includeExif) {
         console.warn('The `exif` option is not supported in the browser version of `@dicebear/converter`. \n' +
@@ -23,6 +29,10 @@ function toFormat(avatar, format, options = {}) {
         toArrayBuffer: () => toArrayBuffer(svg, format, options),
     };
 }
+/**
+ * Returns a `data:` URI for the rendered avatar. The `svg` format is
+ * fast-pathed; other formats go through a `<canvas>` rasterization step.
+ */
 async function toDataUri(svg, format, options) {
     if ('svg' === format) {
         return `data:${getMimeType(format)};utf8,${encodeURIComponent(svg)}`;
@@ -30,16 +40,27 @@ async function toDataUri(svg, format, options) {
     const canvas = await toCanvas(svg, format, options);
     return canvas.toDataURL(getMimeType(format));
 }
+/**
+ * Returns the rasterized avatar as a raw `ArrayBuffer` by routing the canvas
+ * through `canvas.toBlob`.
+ */
 async function toArrayBuffer(rawSvg, format, options) {
     const canvas = await toCanvas(rawSvg, format, options);
     return await new Promise((resolve, reject) => {
         canvas.toBlob((blob) => {
-            blob
-                ? resolve(blob.arrayBuffer())
-                : reject(new Error('Could not create blob'));
+            if (blob) {
+                resolve(blob.arrayBuffer());
+            }
+            else {
+                reject(new Error('Could not create blob'));
+            }
         }, getMimeType(format));
     });
 }
+/**
+ * Renders the SVG into a fresh `<canvas>` of the requested size. JPEG output
+ * gets a white background fill so transparent regions don't render black.
+ */
 async function toCanvas(rawSvg, format, options) {
     const { svg, size } = ensureSize(rawSvg, options.size);
     const canvas = document.createElement('canvas');

package/lib/node/core.js

@@ -17,6 +17,12 @@ export const toWebp = (avatar, options = {}) => {
 export const toAvif = (avatar, options = {}) => {
     return toFormat(avatar, 'avif', options);
 };
+/**
+ * Node conversion entry point. Returns a {@link Result} with `toDataUri()`
+ * and `toArrayBuffer()` methods that lazily render the avatar via resvg +
+ * sharp, optionally embedding Exif metadata derived from the SVG's
+ * `<metadata>` block.
+ */
 function toFormat(avatar, format, options) {
     var _a;
     const svg = typeof avatar === 'string' ? avatar : avatar.toString();
@@ -27,6 +33,10 @@ function toFormat(avatar, format, options) {
         toArrayBuffer: () => toArrayBuffer(svg, format, exif, options),
     };
 }
+/**
+ * Returns a `data:` URI for the rendered avatar. The `svg` format is
+ * fast-pathed; raster formats are base64-encoded.
+ */
 async function toDataUri(svg, format, exif, options) {
     if (format === 'svg') {
         return `data:${getMimeType(format)};utf8,${encodeURIComponent(svg)}`;
@@ -34,9 +44,17 @@ async function toDataUri(svg, format, exif, options) {
     const buffer = await toBuffer(svg, format, exif, options);
     return `data:${getMimeType(format)};base64,${buffer.toString('base64')}`;
 }
+/**
+ * Returns the rasterized avatar as a raw `ArrayBuffer` by unwrapping the
+ * underlying Node `Buffer`.
+ */
 async function toArrayBuffer(rawSvg, format, exif, options) {
     return (await toBuffer(rawSvg, format, exif, options)).buffer;
 }
+/**
+ * Renders the SVG via resvg-js, optionally re-encodes through sharp for
+ * non-PNG formats, and writes Exif metadata using exiftool when present.
+ */
 async function toBuffer(rawSvg, format, exif, options) {
     const hasFonts = Array.isArray(options.fonts);
     const { svg, size } = ensureSize(rawSvg, options.size);
@@ -63,8 +81,13 @@ async function toBuffer(rawSvg, format, exif, options) {
     }
     return buffer;
 }
-// https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata
-// https://developers.google.com/search/docs/appearance/structured-data/image-license-metadata
+/**
+ * Maps the SVG's embedded `<metadata>` block to an Exif tag set covering
+ * IPTC-PhotoMetadata and Google's image license metadata schemas.
+ *
+ * @see https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata
+ * @see https://developers.google.com/search/docs/appearance/structured-data/image-license-metadata
+ */
 function getExif(svg) {
     const metadata = getMetadata(svg);
     const exif = {};

package/lib/utils/mime-type.d.ts

@@ -1 +1,4 @@
+/**
+ * Returns the MIME type string for an avatar output format.
+ */
 export declare function getMimeType(format: 'svg' | 'png' | 'jpeg' | 'webp' | 'avif'): string;

package/lib/utils/mime-type.js

@@ -1,3 +1,6 @@
+/**
+ * Returns the MIME type string for an avatar output format.
+ */
 export function getMimeType(format) {
     switch (format) {
         case 'svg':

package/lib/utils/svg.d.ts

@@ -1,6 +1,14 @@
 import { Metadata } from '../types';
+/**
+ * Re-emits the SVG with explicit `width`/`height` attributes set to the
+ * sanitized size, so downstream rasterizers know how large to render.
+ */
 export declare function ensureSize(svg: string, size?: number): {
     svg: string;
     size: number;
 };
+/**
+ * Extracts the embedded RDF/Dublin Core metadata block from an avatar SVG
+ * into a flat {@link Metadata} object. Missing fields become `undefined`.
+ */
 export declare function getMetadata(svg: string): Metadata;

package/lib/utils/svg.js

@@ -12,12 +12,20 @@ const xmlRoundTripOptions = {
 };
 const xmlRoundTripParser = new XMLParser(xmlRoundTripOptions);
 const xmlRoundTripBuilder = new XMLBuilder(xmlRoundTripOptions);
+/**
+ * Clamps a requested size into a sane integer range, falling back to
+ * `DEFAULT_SIZE` for non-finite or non-positive inputs.
+ */
 function sanitizeSize(size) {
     if (!Number.isFinite(size) || size <= 0) {
         return DEFAULT_SIZE;
     }
     return Math.floor(Math.min(size, MAX_SIZE));
 }
+/**
+ * Re-emits the SVG with explicit `width`/`height` attributes set to the
+ * sanitized size, so downstream rasterizers know how large to render.
+ */
 export function ensureSize(svg, size = DEFAULT_SIZE) {
     var _a;
     size = sanitizeSize(size);
@@ -31,12 +39,20 @@ export function ensureSize(svg, size = DEFAULT_SIZE) {
     svg = xmlRoundTripBuilder.build(parsed);
     return { svg, size };
 }
+/**
+ * Returns a non-empty string truncated to {@link MAX_METADATA_LENGTH}, or
+ * `undefined` for non-string or empty input.
+ */
 function sanitizeMetadataValue(value) {
     if (typeof value !== 'string' || value.length === 0) {
         return undefined;
     }
     return value.slice(0, MAX_METADATA_LENGTH);
 }
+/**
+ * Extracts the embedded RDF/Dublin Core metadata block from an avatar SVG
+ * into a flat {@link Metadata} object. Missing fields become `undefined`.
+ */
 export function getMetadata(svg) {
     var _a, _b;
     const parser = new XMLParser();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dicebear/converter",
-  "version": "10.0.0-rc.1",
+  "version": "10.0.0-rc.3",
   "description": "SVG Converter for DiceBear",
   "keywords": [
     "dicebear"
@@ -38,7 +38,7 @@
   "dependencies": {
     "@resvg/resvg-js": "^2.6.2",
     "exiftool-vendored": "^35.5.0",
-    "fast-xml-parser": "^5.5.6",
+    "fast-xml-parser": "^5.7.1",
     "sharp": "^0.34.5",
     "tmp-promise": "^3.0.3"
   },