@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/src/xmp/Namespaces.ts

@@ -0,0 +1,228 @@
+/**
+ * The namespace IRIs of the XMP core schemas and the conventional prefix of
+ * each, as the XMP specification (ISO 16684-1) and the PDF/A standards
+ * (ISO 19005) name them.
+ *
+ * @since 0.1.0
+ */
+import * as PrefixMap from '../PrefixMap.ts';
+
+/**
+ * The `x:` namespace of the `<x:xmpmeta>` wrapper element.
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const X = 'adobe:ns:meta/';
+
+/**
+ * The RDF namespace.
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
+
+/**
+ * The Dublin Core namespace (`dc:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const DC = 'http://purl.org/dc/elements/1.1/';
+
+/**
+ * The XMP Basic namespace (`xmp:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const XMP = 'http://ns.adobe.com/xap/1.0/';
+
+/**
+ * The XMP Rights Management namespace (`xmpRights:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const XMP_RIGHTS = 'http://ns.adobe.com/xap/1.0/rights/';
+
+/**
+ * The XMP Media Management namespace (`xmpMM:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const XMP_MM = 'http://ns.adobe.com/xap/1.0/mm/';
+
+/**
+ * The XMP note namespace (`xmpNote:`), which carries
+ * `xmpNote:HasExtendedXMP` in JPEG files.
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const XMP_NOTE = 'http://ns.adobe.com/xmp/note/';
+
+/**
+ * The XMP qualifier namespace for identifiers (`xmpidq:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const XMP_IDQ = 'http://ns.adobe.com/xmp/Identifier/qual/1.0/';
+
+/**
+ * The Adobe PDF namespace (`pdf:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDF = 'http://ns.adobe.com/pdf/1.3/';
+
+/**
+ * The PDF/A identification namespace (`pdfaid:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDFA_ID = 'http://www.aiim.org/pdfa/ns/id/';
+
+/**
+ * The PDF/UA identification namespace (`pdfuaid:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDFUA_ID = 'http://www.aiim.org/pdfua/ns/id/';
+
+/**
+ * The PDF/A extension schema container namespace (`pdfaExtension:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDFA_EXTENSION = 'http://www.aiim.org/pdfa/ns/extension/';
+
+/**
+ * The PDF/A schema value type namespace (`pdfaSchema:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDFA_SCHEMA = 'http://www.aiim.org/pdfa/ns/schema#';
+
+/**
+ * The PDF/A property value type namespace (`pdfaProperty:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDFA_PROPERTY = 'http://www.aiim.org/pdfa/ns/property#';
+
+/**
+ * The PDF/A value type namespace (`pdfaType:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDFA_TYPE = 'http://www.aiim.org/pdfa/ns/type#';
+
+/**
+ * The PDF/A field namespace (`pdfaField:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PDFA_FIELD = 'http://www.aiim.org/pdfa/ns/field#';
+
+/**
+ * The Photoshop namespace (`photoshop:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const PHOTOSHOP = 'http://ns.adobe.com/photoshop/1.0/';
+
+/**
+ * The EXIF namespace (`exif:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const EXIF = 'http://ns.adobe.com/exif/1.0/';
+
+/**
+ * The EXIF 2.3+ namespace of the CIPA (`exifEX:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const EXIF_EX = 'http://cipa.jp/exif/1.0/';
+
+/**
+ * The TIFF namespace (`tiff:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const TIFF = 'http://ns.adobe.com/tiff/1.0/';
+
+/**
+ * The ResourceEvent structure namespace (`stEvt:`), the fields of
+ * `xmpMM:History` entries.
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const ST_EVT = 'http://ns.adobe.com/xap/1.0/sType/ResourceEvent#';
+
+/**
+ * The ResourceRef structure namespace (`stRef:`), the fields of
+ * `xmpMM:DerivedFrom`.
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const ST_REF = 'http://ns.adobe.com/xap/1.0/sType/ResourceRef#';
+
+/**
+ * The paged-text namespace (`xmpTPg:`).
+ *
+ * @since 0.1.0
+ * @category namespaces
+ */
+export const XMP_TPG = 'http://ns.adobe.com/xap/1.0/t/pg/';
+
+/**
+ * The conventional prefix of every namespace in this module. The serializer
+ * declares these prefixes unless `SerializeOptions.prefixes` names another.
+ *
+ * @since 0.1.0
+ * @category prefixes
+ */
+export const prefixes: PrefixMap.PrefixMap = PrefixMap.make([
+  ['x', X],
+  ['rdf', RDF],
+  ['dc', DC],
+  ['xmp', XMP],
+  ['xmpRights', XMP_RIGHTS],
+  ['xmpMM', XMP_MM],
+  ['xmpNote', XMP_NOTE],
+  ['xmpidq', XMP_IDQ],
+  ['pdf', PDF],
+  ['pdfaid', PDFA_ID],
+  ['pdfuaid', PDFUA_ID],
+  ['pdfaExtension', PDFA_EXTENSION],
+  ['pdfaSchema', PDFA_SCHEMA],
+  ['pdfaProperty', PDFA_PROPERTY],
+  ['pdfaType', PDFA_TYPE],
+  ['pdfaField', PDFA_FIELD],
+  ['photoshop', PHOTOSHOP],
+  ['exif', EXIF],
+  ['exifEX', EXIF_EX],
+  ['tiff', TIFF],
+  ['stEvt', ST_EVT],
+  ['stRef', ST_REF],
+  ['xmpTPg', XMP_TPG],
+]);

package/src/xmp/Packet.ts

@@ -0,0 +1,297 @@
+/**
+ * XMP packets (ISO 16684-1 §7.3): finding `<?xpacket begin=… ?>` …
+ * `<?xpacket end="w"?>` in arbitrary bytes, and wrapping serialized XMP in
+ * a packet with the whitespace padding that lets a writer update it in
+ * place.
+ *
+ * Packets are found in UTF-8, UTF-16 and UTF-32 (either byte order), the
+ * encodings ISO 16684-1 §7.3.2 lets a packet use and a byte scanner can
+ * recognise without parsing the host file.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from 'effect/Array';
+import * as Option from 'effect/Option';
+import * as Order from 'effect/Order';
+
+/**
+ * The `id` attribute every packet header carries.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const PACKET_ID = 'W5M0MpCehiHzreSzNTczkc9d';
+
+/**
+ * The padding a writable packet gets by default: 2 KiB, as the XMP
+ * specification recommends.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const DEFAULT_PADDING = 2048;
+
+/**
+ * The text encoding of a packet.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type Encoding = 'utf-8' | 'utf-16be' | 'utf-16le' | 'utf-32be' | 'utf-32le';
+
+/**
+ * A packet found in a byte sequence.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Packet {
+  /** The byte offset of `<?xpacket begin`. */
+  readonly offset: number;
+  /** The byte length, through the end of the `<?xpacket end …?>` trailer. */
+  readonly length: number;
+  readonly encoding: Encoding;
+  /** Whether the trailer is `end="w"` (the packet may be updated in place). */
+  readonly writable: boolean;
+  /** The decoded packet, header to trailer. */
+  readonly text: string;
+}
+
+/**
+ * The parts of a packet's text.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Unwrapped {
+  /** The serialized XMP between the header and the padding. */
+  readonly xml: string;
+  /** The number of whitespace characters of padding before the trailer. */
+  readonly padding: number;
+  readonly writable: boolean;
+}
+
+const HEADER = '<?xpacket begin=';
+const TRAILER = '<?xpacket end=';
+const PI_END = '?>';
+
+const ENCODINGS: ReadonlyArray<Encoding> = [
+  'utf-8',
+  'utf-16be',
+  'utf-16le',
+  'utf-32be',
+  'utf-32le',
+];
+
+const WIDTHS: Readonly<Record<Encoding, number>> = {
+  'utf-8': 1,
+  'utf-16be': 2,
+  'utf-16le': 2,
+  'utf-32be': 4,
+  'utf-32le': 4,
+};
+
+const isLittleEndian = (encoding: Encoding): boolean => encoding.endsWith('le');
+
+/** One ASCII code unit in an encoding: the code, zero-padded to the unit's width. */
+const asciiUnit = (code: number, encoding: Encoding): ReadonlyArray<number> => {
+  // `Arr.replicate` never returns an empty array, and UTF-8 needs none.
+  const padding = Array.from({ length: WIDTHS[encoding] - 1 }, () => 0);
+  return isLittleEndian(encoding) ? [code, ...padding] : [...padding, code];
+};
+
+const encodeAscii = (text: string, encoding: Encoding): Uint8Array =>
+  Uint8Array.from(Arr.flatMap(Arr.fromIterable(text), (c) => asciiUnit(c.charCodeAt(0), encoding)));
+
+/**
+ * Decodes UTF-32, which the WHATWG `TextDecoder` does not support. A code
+ * point outside Unicode, or a surrogate, decodes to U+FFFD as `TextDecoder`
+ * would.
+ */
+const decodeUtf32 = (bytes: Uint8Array, littleEndian: boolean): string => {
+  const data = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const units = Math.floor(bytes.length / 4);
+  return Array.from({ length: units }, (_, i) => {
+    const code = data.getUint32(i * 4, littleEndian);
+    return code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)
+      ? '\uFFFD'
+      : String.fromCodePoint(code);
+  }).join('');
+};
+
+const decode = (bytes: Uint8Array, encoding: Encoding): string =>
+  WIDTHS[encoding] === 4
+    ? decodeUtf32(bytes, isLittleEndian(encoding))
+    : new TextDecoder(encoding).decode(bytes);
+
+// windows-1252 decodes every byte to exactly one UTF-16 code unit, so a
+// string search over the decoded bytes finds byte offsets natively.
+const bytesToString = (bytes: Uint8Array): string => new TextDecoder('windows-1252').decode(bytes);
+
+const marker = (text: string, encoding: Encoding): string =>
+  bytesToString(encodeAscii(text, encoding));
+
+const indexIn = (haystack: string, needle: string, from: number): Option.Option<number> => {
+  const i = haystack.indexOf(needle, from);
+  return i < 0 ? Option.none() : Option.some(i);
+};
+
+const isWritable = (text: string, trailer: number): boolean =>
+  text.charAt(trailer + TRAILER.length + 1) === 'w';
+
+const findIn = (bytes: Uint8Array, haystack: string, from: number): Option.Option<Packet> => {
+  const starts = Arr.getSomes(
+    Arr.map(ENCODINGS, (encoding) =>
+      Option.map(indexIn(haystack, marker(HEADER, encoding), from), (offset) => ({
+        offset,
+        encoding,
+      })),
+    ),
+  );
+  const first = Arr.head(
+    Arr.sort(
+      starts,
+      Order.mapInput(Order.Number, (s: { readonly offset: number }) => s.offset),
+    ),
+  );
+  return Option.flatMap(first, ({ offset, encoding }) => {
+    const width = WIDTHS[encoding];
+    const end = Option.flatMap(
+      indexIn(haystack, marker(TRAILER, encoding), offset + HEADER.length * width),
+      (trailer) =>
+        Option.map(
+          indexIn(haystack, marker(PI_END, encoding), trailer + TRAILER.length * width),
+          (close) => close + PI_END.length * width,
+        ),
+    );
+    // A header with no trailer after it is not a packet, and neither is any
+    // later header.
+    return Option.map(end, (close): Packet => {
+      const text = decode(bytes.subarray(offset, close), encoding);
+      return {
+        offset,
+        length: close - offset,
+        encoding,
+        writable: isWritable(text, text.lastIndexOf(TRAILER)),
+        text,
+      };
+    });
+  });
+};
+
+/**
+ * Finds the first packet at or after `fromIndex` in a byte sequence: a file
+ * of any format, scanned without parsing it (ISO 16684-1 §7.3.2's packet
+ * scanning).
+ *
+ * @since 0.1.0
+ * @category scanning
+ */
+export const find = (bytes: Uint8Array, fromIndex: number = 0): Option.Option<Packet> =>
+  findIn(bytes, bytesToString(bytes), fromIndex);
+
+/**
+ * Finds every packet in a byte sequence, in order.
+ *
+ * @since 0.1.0
+ * @category scanning
+ */
+export const findAll = (bytes: Uint8Array): ReadonlyArray<Packet> => {
+  const haystack = bytesToString(bytes);
+  return Arr.unfold(0, (from) =>
+    Option.map(findIn(bytes, haystack, from), (p) => [p, p.offset + p.length] as const),
+  );
+};
+
+/**
+ * Splits a packet's text into the serialized XMP, the padding and the
+ * writability of its trailer. Returns `None` when the text is not a packet.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const unwrap = (text: string): Option.Option<Unwrapped> =>
+  Option.flatMap(indexIn(text, HEADER, 0), (start) =>
+    Option.flatMap(indexIn(text, PI_END, start), (headerEnd) => {
+      const trailer = text.lastIndexOf(TRAILER);
+      if (trailer < headerEnd) return Option.none();
+      const content = text.slice(headerEnd + PI_END.length, trailer).replace(/^\r?\n/, '');
+      const xml = content.trimEnd();
+      return Option.some({
+        xml,
+        padding: content.length - xml.length,
+        writable: isWritable(text, trailer),
+      });
+    }),
+  );
+
+/**
+ * Options for wrapping serialized XMP in a packet.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface WrapOptions {
+  /**
+   * Bytes of whitespace padding before the trailer. Defaults to
+   * `DEFAULT_PADDING` for a writable packet and 0 for a read-only one.
+   */
+  readonly padding?: number | undefined;
+  /** Whether the trailer is `end="w"` rather than `end="r"`. Defaults to `true`. */
+  readonly writable?: boolean | undefined;
+}
+
+const header = `<?xpacket begin="" id="${PACKET_ID}"?>\n`;
+const trailerOf = (writable: boolean) => `<?xpacket end="${writable ? 'w' : 'r'}"?>`;
+
+/**
+ * Whitespace padding of exactly `bytes` bytes: lines of 99 spaces and a
+ * newline, as XMP writers lay it out.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const padding = (bytes: number): string => {
+  const lines = Math.floor(bytes / 100);
+  return `${`${' '.repeat(99)}\n`.repeat(lines)}${' '.repeat(bytes - lines * 100)}`;
+};
+
+const body = (xml: string) => (xml.endsWith('\n') ? xml : `${xml}\n`);
+
+/**
+ * Wraps serialized XMP (an `<x:xmpmeta>` element) in a UTF-8 packet.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const wrap = (xml: string, options?: WrapOptions): string => {
+  const writable = options?.writable ?? true;
+  const pad = options?.padding ?? (writable ? DEFAULT_PADDING : 0);
+  return `${header}${body(xml)}${padding(pad)}${trailerOf(writable)}`;
+};
+
+/**
+ * The UTF-8 byte length of a string.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const byteLength = (text: string): number => new TextEncoder().encode(text).length;
+
+/**
+ * Wraps serialized XMP in a UTF-8 packet of exactly `size` bytes, padding the
+ * difference: how an XMP packet is updated in place in a file. Returns
+ * `None` when the XMP does not fit.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const wrapToSize = (
+  xml: string,
+  size: number,
+  options?: { readonly writable?: boolean | undefined },
+): Option.Option<string> => {
+  const writable = options?.writable ?? true;
+  const fixed = byteLength(`${header}${body(xml)}${trailerOf(writable)}`);
+  return fixed > size ? Option.none() : Option.some(wrap(xml, { writable, padding: size - fixed }));
+};

package/src/xmp/Pdf.ts

@@ -0,0 +1,99 @@
+/**
+ * Typed accessors for the Adobe PDF schema (`pdf:`) and the PDF/UA
+ * identification schema (`pdfuaid:`, ISO 14289).
+ *
+ * @since 0.1.0
+ */
+import type * as Option from 'effect/Option';
+import * as Accessors from './internal/accessors.ts';
+import type * as Metadata from './Metadata.ts';
+import { PDF, PDFUA_ID } from './Namespaces.ts';
+
+/**
+ * The application that wrote the PDF (`pdf:Producer`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const producer: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${PDF}Producer`,
+);
+
+/**
+ * Sets the application that wrote the PDF (`pdf:Producer`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setProducer: Metadata.Setter<string> = Accessors.setText(`${PDF}Producer`);
+
+/**
+ * The keywords (`pdf:Keywords`), one text value.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const keywords: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${PDF}Keywords`,
+);
+
+/**
+ * Sets the keywords (`pdf:Keywords`), one text value.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setKeywords: Metadata.Setter<string> = Accessors.setText(`${PDF}Keywords`);
+
+/**
+ * The PDF version, such as `"1.7"` (`pdf:PDFVersion`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const pdfVersion: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${PDF}PDFVersion`,
+);
+
+/**
+ * Sets the PDF version, such as `"1.7"` (`pdf:PDFVersion`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setPdfVersion: Metadata.Setter<string> = Accessors.setText(`${PDF}PDFVersion`);
+
+/**
+ * Whether the document is trapped (`pdf:Trapped`): `"True"`, `"False"` or `"Unknown"`.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const trapped: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${PDF}Trapped`,
+);
+
+/**
+ * Sets whether the document is trapped (`pdf:Trapped`): `"True"`, `"False"` or `"Unknown"`.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setTrapped: Metadata.Setter<string> = Accessors.setText(`${PDF}Trapped`);
+
+/**
+ * The PDF/UA part the document conforms to (`pdfuaid:part`), such as `1`.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const uaPart = (self: Metadata.Metadata): Option.Option<number> =>
+  Accessors.integer(`${PDFUA_ID}part`)(self);
+
+/**
+ * Sets the PDF/UA part the document conforms to (`pdfuaid:part`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setUaPart: Metadata.Setter<number> = Accessors.setInteger(`${PDFUA_ID}part`);