@strav/pdf 0.4.17

package/src/util/errors.ts

@@ -0,0 +1,61 @@
+/**
+ * Public error taxonomy (spec §16.2).
+ *
+ * Every error thrown by the library is a subclass of {@link PdfGenError} and
+ * carries a stable `code` string for programmatic handling. The taxonomy is
+ * part of the API contract — codes do not change across minor versions.
+ */
+
+export type PdfGenErrorCode =
+  | 'PDF_INVALID_NUMBER'
+  | 'PDF_INVALID_STRING'
+  | 'PDF_INVALID_NAME'
+  | 'PDF_INVALID_OBJECT'
+  | 'PDF_UNBALANCED_GRAPHICS_STATE'
+  | 'PDF_PATH_NOT_CONSUMED'
+  | 'PDF_NO_PATH'
+  | 'PDF_INVALID_COLOR'
+  | 'PDF_INVALID_PAGE'
+  | 'PDF_DOCUMENT_FINALIZED'
+  | 'PDF_CONFORMANCE'
+  | 'PDF_UNSUPPORTED_FONT'
+  | 'PDF_INVALID_IMAGE'
+  | 'PDF_TEXT_STATE'
+  | 'PDF_TEXT_ENCODING'
+  | 'PDF_NO_FONT'
+
+export class PdfGenError extends Error {
+  readonly code: PdfGenErrorCode
+
+  constructor(code: PdfGenErrorCode, message: string) {
+    super(message)
+    this.name = new.target.name
+    this.code = code
+    // Maintain a clean stack across the subclass chain.
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+/** Thrown at `save()` when a conformance mode's requirements are violated. */
+export class ConformanceError extends PdfGenError {
+  readonly violations: string[]
+
+  constructor(message: string, violations: string[] = []) {
+    super('PDF_CONFORMANCE', message)
+    this.violations = violations
+  }
+}
+
+/** Thrown when a font cannot be used (e.g. Standard-14 under conformance). */
+export class UnsupportedFontError extends PdfGenError {
+  constructor(message: string) {
+    super('PDF_UNSUPPORTED_FONT', message)
+  }
+}
+
+/** Thrown when image bytes cannot be parsed or are an unsupported variant. */
+export class InvalidImageError extends PdfGenError {
+  constructor(message: string) {
+    super('PDF_INVALID_IMAGE', message)
+  }
+}

package/src/util/index.ts

@@ -0,0 +1,10 @@
+export {
+  PdfGenError,
+  ConformanceError,
+  UnsupportedFontError,
+  InvalidImageError,
+} from './errors.ts'
+export type { PdfGenErrorCode } from './errors.ts'
+export { pt, inch, mm, cm } from './units.ts'
+export { ascii, utf8, concatBytes } from './ascii.ts'
+export { BinaryReader, fixed1616, f2dot14 } from './binary.ts'

package/src/util/units.ts

@@ -0,0 +1,24 @@
+/**
+ * Unit helpers (spec §6.4). The public API uses points (1 pt = 1/72 inch),
+ * matching PDF user space. These convert from physical units.
+ */
+
+/** Points → points (identity; provided for symmetry and readability). */
+export function pt(value: number): number {
+  return value
+}
+
+/** Inches → points. 1 inch = 72 pt exactly. */
+export function inch(value: number): number {
+  return value * 72
+}
+
+/** Millimetres → points. 1 mm = 72 / 25.4 pt. */
+export function mm(value: number): number {
+  return (value * 72) / 25.4
+}
+
+/** Centimetres → points. */
+export function cm(value: number): number {
+  return mm(value * 10)
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}