resvg-napi 0.1.2 → 0.3.0

package/index.d.ts

@@ -44,6 +44,11 @@ export declare class Font {
   get stretch(): FontStretch
   get weight(): number
   get variations(): Array<FontVariation>
+  /**
+   * Families this span asked for, in order. Never empty: usvg appends
+   * `RenderOptions.fontFamily` as the last resort.
+   */
+  get families(): Array<string>
 }
 
 /** Opaque wrapper over `fontdb::Database` (memory-mapped faces, no JSON form). */
@@ -158,7 +163,7 @@ export declare class FontDatabase {
 /** Read-only view of a `FaceInfo`. */
 export declare class FontFace {
   get index(): number
-  get postScriptName(): string
+  get postScriptName(): String
   get style(): FontFaceStyle
   get weight(): number
   get monospaced(): boolean
@@ -166,6 +171,49 @@ export declare class FontFace {
   get families(): Array<string>
 }
 
+/** Read-only view of an `Image`. */
+export declare class Image {
+  get id(): String
+  get isVisible(): boolean
+  get renderingMode(): ImageRendering
+  get kind(): ImageKindJpeg | ImageKindPng | ImageKindGif | ImageKindWebp | ImageKindSvg
+  get absTransform(): Matrix
+  get boundingBox(): BBox
+  get absBoundingBox(): BBox
+}
+
+/** `ImageKind::GIF`. The bytes are the document's own. */
+export declare class ImageKindGif {
+  /** Discriminant. Narrow on this. */
+  get type(): 'gif'
+  /** The encoded bytes, exactly as the document supplied them: usvg does not decode them, and neither does this. */
+  get bytes(): Buffer
+}
+
+/** `ImageKind::JPEG`. The bytes are the document's own. */
+export declare class ImageKindJpeg {
+  /** Discriminant. Narrow on this. */
+  get type(): 'jpeg'
+  /** The encoded bytes, exactly as the document supplied them: usvg does not decode them, and neither does this. */
+  get bytes(): Buffer
+}
+
+/** `ImageKind::PNG`. The bytes are the document's own. */
+export declare class ImageKindPng {
+  /** Discriminant. Narrow on this. */
+  get type(): 'png'
+  /** The encoded bytes, exactly as the document supplied them: usvg does not decode them, and neither does this. */
+  get bytes(): Buffer
+}
+
+/** `ImageKind::WEBP`. The bytes are the document's own. */
+export declare class ImageKindWebp {
+  /** Discriminant. Narrow on this. */
+  get type(): 'webp'
+  /** The encoded bytes, exactly as the document supplied them: usvg does not decode them, and neither does this. */
+  get bytes(): Buffer
+}
+
 /** Read-only handle on a `usvg::LinearGradient`. */
 export declare class LinearGradient {
   /** `x1` coordinate. */
@@ -249,6 +297,17 @@ export declare class Pattern {
   children(): Array<SvgNode>
 }
 
+/** Read-only view of a `PositionedGlyph`. */
+export declare class PositionedGlyph {
+  get fontSize(): number
+  get transform(): Matrix
+  get outlineTransform(): Matrix
+  get svgTransform(): Matrix
+  get colrTransform(): Matrix
+  get id(): number
+  get text(): String
+}
+
 /** Read-only handle on a `usvg::RadialGradient`. */
 export declare class RadialGradient {
   /** `cx` coordinate. */
@@ -306,6 +365,23 @@ export declare class Resvg {
    * `FontDatabase` and re-parse to fix the output.
    */
   pendingFonts(): Array<string>
+  /**
+   * The face that actually drew a glyph, from the database this
+   * document was parsed with.
+   *
+   * `pendingFonts()` names the families that were missing; this names
+   * what was used instead, glyph by glyph, which is the half a
+   * document-wide list cannot answer. A fallback that renders is the
+   * failure nobody sees.
+   *
+   * The lookup lives here rather than on `FontDatabase` because
+   * `PositionedGlyph.font` is a `fontdb::ID` -- a slotmap key with no
+   * public numeric form, and meaningless against any other database.
+   * The glyph carries it the way `FontFace` carries one for
+   * `FontDatabase.face`, and `null` means exactly that: a glyph from
+   * another document.
+   */
+  faceOf(glyph: PositionedGlyph): FontFace | null
   /**
    * Supplies one image and re-parses the document.
    *
@@ -478,6 +554,21 @@ export declare class Resvg {
   renderRawAsync(params?: RenderParams | undefined | null, signal?: AbortSignal | undefined | null): Promise<RawImage>
 }
 
+/** Read-only view of a `Span`. */
+export declare class Span {
+  get fill(): Fill | null
+  get stroke(): Stroke | null
+  get paintOrder(): PaintOrder
+  get fontSize(): number
+  get variations(): Array<FontVariation>
+  get fontOpticalSizing(): FontOpticalSizing
+  get visible(): boolean
+  get positionedGlyphs(): Array<PositionedGlyph>
+  get underline(): Path | null
+  get overline(): Path | null
+  get lineThrough(): Path | null
+}
+
 /**
  * A read-only handle on one element of the parsed tree.
  *
@@ -504,6 +595,17 @@ export declare class SvgNode {
    * mapper prunes any generated type no exposed method hands out.
    */
   path(): Path | null
+  /**
+   * The content of an image node: where it sits, how it is to
+   * be scaled, and the bytes themselves. Null for anything else.
+   *
+   * `kind` is a discriminated union. The four raster variants
+   * carry the encoded bytes exactly as the document supplied
+   * them -- usvg says they should be decoded by the caller, and
+   * this is the caller -- while `svg` carries none, an embedded
+   * SVG being a tree rather than a payload.
+   */
+  image(): Image | null
   /** Direct children. Empty for anything that is not a group. */
   children(): Array<SvgNode>
   /**
@@ -561,7 +663,7 @@ export declare class SvgNode {
 
 /** Read-only view of a `Text`. */
 export declare class Text {
-  get id(): string
+  get id(): String
   get renderingMode(): TextRendering
   get dx(): Array<number>
   get dy(): Array<number>
@@ -583,7 +685,7 @@ export declare class TextChunk {
   get anchor(): TextAnchor
   get spans(): Array<TextSpan>
   get textFlow(): TextFlowPlain | TextFlowPath
-  get text(): string
+  get text(): String
 }
 
 /** Read-only view of a `TextSpan`. */
@@ -610,20 +712,18 @@ export declare class TextSpan {
 }
 
 /** An alignment baseline property. */
-export declare const enum AlignmentBaseline {
-  Auto = 'auto',
-  Baseline = 'baseline',
-  BeforeEdge = 'beforeEdge',
-  TextBeforeEdge = 'textBeforeEdge',
-  Middle = 'middle',
-  Central = 'central',
-  AfterEdge = 'afterEdge',
-  TextAfterEdge = 'textAfterEdge',
-  Ideographic = 'ideographic',
-  Alphabetic = 'alphabetic',
-  Hanging = 'hanging',
-  Mathematical = 'mathematical'
-}
+export type AlignmentBaseline =  'auto'|
+'baseline'|
+'beforeEdge'|
+'textBeforeEdge'|
+'middle'|
+'central'|
+'afterEdge'|
+'textAfterEdge'|
+'ideographic'|
+'alphabetic'|
+'hanging'|
+'mathematical';
 
 /** `BaselineShift::Number`. */
 export interface BaselineShiftNumber {
@@ -658,24 +758,22 @@ export interface Blend {
  *
  * `mix-blend-mode` attribute in the SVG.
  */
-export declare const enum BlendMode {
-  Normal = 'normal',
-  Multiply = 'multiply',
-  Screen = 'screen',
-  Overlay = 'overlay',
-  Darken = 'darken',
-  Lighten = 'lighten',
-  ColorDodge = 'colorDodge',
-  ColorBurn = 'colorBurn',
-  HardLight = 'hardLight',
-  SoftLight = 'softLight',
-  Difference = 'difference',
-  Exclusion = 'exclusion',
-  Hue = 'hue',
-  Saturation = 'saturation',
-  Color = 'color',
-  Luminosity = 'luminosity'
-}
+export type BlendMode =  'normal'|
+'multiply'|
+'screen'|
+'overlay'|
+'darken'|
+'lighten'|
+'colorDodge'|
+'colorBurn'|
+'hardLight'|
+'softLight'|
+'difference'|
+'exclusion'|
+'hue'|
+'saturation'|
+'color'|
+'luminosity';
 
 /** Plain view of a `Color`. */
 export interface Color {
@@ -685,22 +783,18 @@ export interface Color {
 }
 
 /** A color channel. */
-export declare const enum ColorChannel {
-  R = 'r',
-  G = 'g',
-  B = 'b',
-  A = 'a'
-}
+export type ColorChannel =  'r'|
+'g'|
+'b'|
+'a';
 
 /**
  * A color interpolation mode.
  *
  * The default is `ColorInterpolation::LinearRGB`.
  */
-export declare const enum ColorInterpolation {
-  SRGB = 'srgb',
-  LinearRGB = 'linearRgb'
-}
+export type ColorInterpolation =  'srgb'|
+'linearRgb';
 
 /** Plain view of a `ColorMatrix`. */
 export interface ColorMatrix {
@@ -817,20 +911,18 @@ export interface DistantLight {
 }
 
 /** A dominant baseline property. */
-export declare const enum DominantBaseline {
-  Auto = 'auto',
-  UseScript = 'useScript',
-  NoChange = 'noChange',
-  ResetSize = 'resetSize',
-  Ideographic = 'ideographic',
-  Alphabetic = 'alphabetic',
-  Hanging = 'hanging',
-  Mathematical = 'mathematical',
-  Central = 'central',
-  Middle = 'middle',
-  TextAfterEdge = 'textAfterEdge',
-  TextBeforeEdge = 'textBeforeEdge'
-}
+export type DominantBaseline =  'auto'|
+'useScript'|
+'noChange'|
+'resetSize'|
+'ideographic'|
+'alphabetic'|
+'hanging'|
+'mathematical'|
+'central'|
+'middle'|
+'textAfterEdge'|
+'textBeforeEdge';
 
 /** Plain view of a `DropShadow`. */
 export interface DropShadow {
@@ -844,11 +936,9 @@ export interface DropShadow {
 }
 
 /** An edges processing mode. */
-export declare const enum EdgeMode {
-  None = 'none',
-  Duplicate = 'duplicate',
-  Wrap = 'wrap'
-}
+export type EdgeMode =  'none'|
+'duplicate'|
+'wrap';
 
 /** Plain view of a `Fill`. */
 export interface Fill {
@@ -862,10 +952,8 @@ export interface Fill {
  *
  * `fill-rule` attribute in the SVG.
  */
-export declare const enum FillRule {
-  NonZero = 'nonZero',
-  EvenOdd = 'evenOdd'
-}
+export type FillRule =  'nonZero'|
+'evenOdd';
 
 /** Plain view of a `Flood`. */
 export interface Flood {
@@ -874,11 +962,9 @@ export interface Flood {
 }
 
 /** Allows italic or oblique faces to be selected. */
-export declare const enum FontFaceStyle {
-  Normal = 'normal',
-  Italic = 'italic',
-  Oblique = 'oblique'
-}
+export type FontFaceStyle =  'normal'|
+'italic'|
+'oblique';
 
 /**
  * A font optical sizing property.
@@ -886,34 +972,28 @@ export declare const enum FontFaceStyle {
  * Controls automatic adjustment of the `opsz` axis in variable fonts
  * based on font size. Matches CSS `font-optical-sizing`.
  */
-export declare const enum FontOpticalSizing {
-  Auto = 'auto',
-  None = 'none'
-}
+export type FontOpticalSizing =  'auto'|
+'none';
 
 /** A font stretch property. */
-export declare const enum FontStretch {
-  UltraCondensed = 'ultraCondensed',
-  ExtraCondensed = 'extraCondensed',
-  Condensed = 'condensed',
-  SemiCondensed = 'semiCondensed',
-  Normal = 'normal',
-  SemiExpanded = 'semiExpanded',
-  Expanded = 'expanded',
-  ExtraExpanded = 'extraExpanded',
-  UltraExpanded = 'ultraExpanded'
-}
+export type FontStretch =  'ultraCondensed'|
+'extraCondensed'|
+'condensed'|
+'semiCondensed'|
+'normal'|
+'semiExpanded'|
+'expanded'|
+'extraExpanded'|
+'ultraExpanded';
 
 /** A font style property. */
-export declare const enum FontStyle {
-  Normal = 'normal',
-  Italic = 'italic',
-  Oblique = 'oblique'
-}
+export type FontStyle =  'normal'|
+'italic'|
+'oblique';
 
 /** Plain view of a `FontVariation`. */
 export interface FontVariation {
-  tag: string
+  tag: String
   value: number
 }
 
@@ -924,19 +1004,23 @@ export interface GaussianBlur {
   stdDevY: number
 }
 
+/** `ImageKind::SVG`. */
+export interface ImageKindSvg {
+  /** Discriminant. Narrow on this. */
+  type: 'svg'
+}
+
 /**
  * An image rendering method.
  *
  * `image-rendering` attribute in the SVG.
  */
-export declare const enum ImageRendering {
-  OptimizeQuality = 'optimizeQuality',
-  OptimizeSpeed = 'optimizeSpeed',
-  Smooth = 'smooth',
-  HighQuality = 'highQuality',
-  CrispEdges = 'crispEdges',
-  Pixelated = 'pixelated'
-}
+export type ImageRendering =  'optimizeQuality'|
+'optimizeSpeed'|
+'smooth'|
+'highQuality'|
+'crispEdges'|
+'pixelated';
 
 /** The payload-free variants of `Input`. */
 export interface InputPlain {
@@ -1070,10 +1154,8 @@ export interface KindTurbulence {
 }
 
 /** A length adjust property. */
-export declare const enum LengthAdjust {
-  Spacing = 'spacing',
-  SpacingAndGlyphs = 'spacingAndGlyphs'
-}
+export type LengthAdjust =  'spacing'|
+'spacingAndGlyphs';
 
 /** `LightSource::DistantLight`. */
 export interface LightSourceDistantLight {
@@ -1101,31 +1183,34 @@ export interface LightSourceSpotLight {
  *
  * `stroke-linecap` attribute in the SVG.
  */
-export declare const enum LineCap {
-  Butt = 'butt',
-  Round = 'round',
-  Square = 'square'
-}
+export type LineCap =  'butt'|
+'round'|
+'square';
 
 /**
  * A line join.
  *
  * `stroke-linejoin` attribute in the SVG.
  */
-export declare const enum LineJoin {
-  Miter = 'miter',
-  MiterClip = 'miterClip',
-  Round = 'round',
-  Bevel = 'bevel'
-}
+export type LineJoin =  'miter'|
+'miterClip'|
+'round'|
+'bevel';
 
 /** A mask type. */
-export declare const enum MaskType {
-  Luminance = 'luminance',
-  Alpha = 'alpha'
-}
+export type MaskType =  'luminance'|
+'alpha';
 
-/** An affine transform, same field order as SVG's `matrix(...)`. */
+/**
+ * An affine transform. Field names and order are tiny-skia's.
+ *
+ * They are *not* the order of SVG's `matrix(a b c d e f)`, which
+ * takes `sx ky kx sy tx ty` -- upstream says so itself: "we are
+ * using column-major-column-vector matrix notation, therefore it's
+ * ky-kx, not kx-ky". Reading these positionally into a `matrix()`
+ * string mirrors the transform, silently. Name the fields:
+ * `matrix(${m.sx} ${m.ky} ${m.kx} ${m.sy} ${m.tx} ${m.ty})`.
+ */
 export interface Matrix {
   sx: number
   kx: number
@@ -1149,18 +1234,14 @@ export interface Morphology {
 }
 
 /** A morphology operation. */
-export declare const enum MorphologyOperator {
-  Erode = 'erode',
-  Dilate = 'dilate'
-}
+export type MorphologyOperator =  'erode'|
+'dilate';
 
 /** Which flavour of node this is. */
-export declare const enum NodeKind {
-  Group = 'group',
-  Path = 'path',
-  Image = 'image',
-  Text = 'text'
-}
+export type NodeKind =  'group'|
+'path'|
+'image'|
+'text';
 
 /** Plain view of a `Offset`. */
 export interface Offset {
@@ -1191,10 +1272,8 @@ export interface PaintLinearGradient {
  *
  * [`paint-order`]: https://www.w3.org/TR/SVG2/painting.html#PaintOrder
  */
-export declare const enum PaintOrder {
-  FillAndStroke = 'fillAndStroke',
-  StrokeAndFill = 'strokeAndFill'
-}
+export type PaintOrder =  'fillAndStroke'|
+'strokeAndFill';
 
 /** `Paint::Pattern`. */
 export interface PaintPattern {
@@ -1212,7 +1291,7 @@ export interface PaintRadialGradient {
 
 /** Plain view of a `Path`. */
 export interface Path {
-  id: string
+  id: String
   isVisible: boolean
   fill?: Fill
   stroke?: Stroke
@@ -1249,20 +1328,11 @@ export interface PointLight {
   z: number
 }
 
-/** Plain view of a `PositionedGlyph`. */
-export interface PositionedGlyph {
-  fontSize: number
-  transform: Matrix
-  outlineTransform: Matrix
-  svgTransform: Matrix
-  colrTransform: Matrix
-}
-
 /** Plain view of a `Primitive`. */
 export interface Primitive {
   rect: BBox
   colorInterpolation: ColorInterpolation
-  result: string
+  result: String
   kind: KindBlend | KindColorMatrix | KindComponentTransfer | KindComposite | KindConvolveMatrix | KindDiffuseLighting | KindDisplacementMap | KindDropShadow | KindFlood | KindGaussianBlur | KindImage | KindMerge | KindMorphology | KindOffset | KindSpecularLighting | KindTile | KindTurbulence
 }
 
@@ -1402,33 +1472,16 @@ export interface RenderParams {
  * `level` is `off`, `error`, `warn`, `info`, `debug` or `trace`. Safe to
  * call repeatedly: the logger is installed once, the level always applies.
  */
-export declare function setLogLevel(level: string): void
+export declare function setLogLevel(level: 'off' | 'error' | 'warn' | 'info' | 'debug' | 'trace'): void
 
 /**
  * A shape rendering method.
  *
  * `shape-rendering` attribute in the SVG.
  */
-export declare const enum ShapeRendering {
-  OptimizeSpeed = 'optimizeSpeed',
-  CrispEdges = 'crispEdges',
-  GeometricPrecision = 'geometricPrecision'
-}
-
-/** Plain view of a `Span`. */
-export interface Span {
-  fill?: Fill
-  stroke?: Stroke
-  paintOrder: PaintOrder
-  fontSize: number
-  variations: Array<FontVariation>
-  fontOpticalSizing: FontOpticalSizing
-  visible: boolean
-  positionedGlyphs: Array<PositionedGlyph>
-  underline?: string
-  overline?: string
-  lineThrough?: string
-}
+export type ShapeRendering =  'optimizeSpeed'|
+'crispEdges'|
+'geometricPrecision';
 
 /** Plain view of a `SpecularLighting`. */
 export interface SpecularLighting {
@@ -1457,11 +1510,9 @@ export interface SpotLight {
  *
  * `spreadMethod` attribute in the SVG.
  */
-export declare const enum SpreadMethod {
-  Pad = 'pad',
-  Reflect = 'reflect',
-  Repeat = 'repeat'
-}
+export type SpreadMethod =  'pad'|
+'reflect'|
+'repeat';
 
 /** Plain view of a `Stop`. */
 export interface Stop {
@@ -1486,11 +1537,9 @@ export interface Stroke {
 export declare function takeLogs(): Array<string>
 
 /** A text chunk anchor property. */
-export declare const enum TextAnchor {
-  Start = 'start',
-  Middle = 'middle',
-  End = 'end'
-}
+export type TextAnchor =  'start'|
+'middle'|
+'end';
 
 /** Plain view of a `TextDecoration`. */
 export interface TextDecoration {
@@ -1523,11 +1572,9 @@ export interface TextFlowPlain {
  *
  * `text-rendering` attribute in the SVG.
  */
-export declare const enum TextRendering {
-  OptimizeSpeed = 'optimizeSpeed',
-  OptimizeLegibility = 'optimizeLegibility',
-  GeometricPrecision = 'geometricPrecision'
-}
+export type TextRendering =  'optimizeSpeed'|
+'optimizeLegibility'|
+'geometricPrecision';
 
 /** Plain view of a `Tile`. */
 export interface Tile {
@@ -1582,10 +1629,8 @@ export interface Turbulence {
 }
 
 /** A turbulence kind for the `feTurbulence` filter. */
-export declare const enum TurbulenceKind {
-  FractalNoise = 'fractalNoise',
-  Turbulence = 'turbulence'
-}
+export type TurbulenceKind =  'fractalNoise'|
+'turbulence';
 
 /**
  * Mirror of `usvg::WriteOptions`, for `Resvg.toString()`. Every field is
@@ -1639,7 +1684,5 @@ export interface WriteOptions {
 }
 
 /** A writing mode. */
-export declare const enum WritingMode {
-  LeftToRight = 'leftToRight',
-  TopToBottom = 'topToBottom'
-}
+export type WritingMode =  'leftToRight'|
+'topToBottom';