@thomasfosterau/effect-rdf 0.0.0 → 0.1.0

package/src/xmp/DublinCore.ts

@@ -0,0 +1,147 @@
+/**
+ * Typed accessors for the Dublin Core schema (`dc:`, ISO 16684-1 §8.3).
+ *
+ * @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 { DC } from './Namespaces.ts';
+
+/**
+ * The title (`dc:title`), a language alternative. Reads the item in `language` (default `x-default`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const title: (self: Metadata.Metadata, language?: string) => Option.Option<string> =
+  Accessors.localized(`${DC}title`);
+
+/**
+ * Sets one language of the title (`dc:title`), a language alternative.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setTitle: Metadata.LocalizedSetter = Accessors.setLocalized(`${DC}title`);
+
+/**
+ * The creators (`dc:creator`), an ordered array: the document's authors.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const creator: (self: Metadata.Metadata) => Option.Option<ReadonlyArray<string>> =
+  Accessors.items(`${DC}creator`);
+
+/**
+ * Sets the creators (`dc:creator`), an ordered array: the document's authors.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setCreator: Metadata.Setter<Iterable<string>> = Accessors.setSeq(`${DC}creator`);
+
+/**
+ * The description (`dc:description`), a language alternative. Reads the item in `language` (default `x-default`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const description: (self: Metadata.Metadata, language?: string) => Option.Option<string> =
+  Accessors.localized(`${DC}description`);
+
+/**
+ * Sets one language of the description (`dc:description`), a language alternative.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setDescription: Metadata.LocalizedSetter = Accessors.setLocalized(`${DC}description`);
+
+/**
+ * The subjects (`dc:subject`), an unordered array of keywords.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const subject: (self: Metadata.Metadata) => Option.Option<ReadonlyArray<string>> =
+  Accessors.items(`${DC}subject`);
+
+/**
+ * Sets the subjects (`dc:subject`), an unordered array of keywords.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setSubject: Metadata.Setter<Iterable<string>> = Accessors.setBag(`${DC}subject`);
+
+/**
+ * The rights statement (`dc:rights`), a language alternative. Reads the item in `language` (default `x-default`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const rights: (self: Metadata.Metadata, language?: string) => Option.Option<string> =
+  Accessors.localized(`${DC}rights`);
+
+/**
+ * Sets one language of the rights statement (`dc:rights`), a language alternative.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setRights: Metadata.LocalizedSetter = Accessors.setLocalized(`${DC}rights`);
+
+/**
+ * The publishers (`dc:publisher`), an unordered array.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const publisher: (self: Metadata.Metadata) => Option.Option<ReadonlyArray<string>> =
+  Accessors.items(`${DC}publisher`);
+
+/**
+ * Sets the publishers (`dc:publisher`), an unordered array.
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setPublisher: Metadata.Setter<Iterable<string>> = Accessors.setBag(`${DC}publisher`);
+
+/**
+ * The media type of the resource (`dc:format`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const format: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${DC}format`,
+);
+
+/**
+ * Sets the media type of the resource (`dc:format`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setFormat: Metadata.Setter<string> = Accessors.setText(`${DC}format`);
+
+/**
+ * An unambiguous identifier of the resource (`dc:identifier`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const identifier: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${DC}identifier`,
+);
+
+/**
+ * Sets an unambiguous identifier of the resource (`dc:identifier`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setIdentifier: Metadata.Setter<string> = Accessors.setText(`${DC}identifier`);

package/src/xmp/Exif.ts

@@ -0,0 +1,109 @@
+/**
+ * Typed accessors for the most used properties of the EXIF schema (`exif:`,
+ * XMP Specification Part 2 §3.3.6). Any other EXIF property is read with
+ * `Metadata.get`.
+ *
+ * @since 0.1.0
+ */
+import type * as DateTime from 'effect/DateTime';
+import type * as Option from 'effect/Option';
+import * as Accessors from './internal/accessors.ts';
+import type * as Metadata from './Metadata.ts';
+import { EXIF } from './Namespaces.ts';
+
+/**
+ * When the original image was taken (`exif:DateTimeOriginal`). An ISO 8601 date, as XMP stores it; the setter takes a `DateTime` or a string.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const dateTimeOriginal: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${EXIF}DateTimeOriginal`,
+);
+
+/**
+ * Sets when the original image was taken (`exif:DateTimeOriginal`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setDateTimeOriginal: Metadata.Setter<DateTime.DateTime | string> = Accessors.setDate(
+  `${EXIF}DateTimeOriginal`,
+);
+
+/**
+ * When the image was stored as digital data (`exif:DateTimeDigitized`). An ISO 8601 date, as XMP stores it; the setter takes a `DateTime` or a string.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const dateTimeDigitized: (self: Metadata.Metadata) => Option.Option<string> = Accessors.text(
+  `${EXIF}DateTimeDigitized`,
+);
+
+/**
+ * Sets when the image was stored as digital data (`exif:DateTimeDigitized`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setDateTimeDigitized: Metadata.Setter<DateTime.DateTime | string> = Accessors.setDate(
+  `${EXIF}DateTimeDigitized`,
+);
+
+/**
+ * A user comment (`exif:UserComment`). A language alternative; reads the item in `language` (default `x-default`).
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const userComment: (self: Metadata.Metadata, language?: string) => Option.Option<string> =
+  Accessors.localized(`${EXIF}UserComment`);
+
+/**
+ * Sets a user comment (`exif:UserComment`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setUserComment: Metadata.LocalizedSetter = Accessors.setLocalized(
+  `${EXIF}UserComment`,
+);
+
+/**
+ * The valid image width, in pixels (`exif:PixelXDimension`). An integer.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const pixelXDimension: (self: Metadata.Metadata) => Option.Option<number> =
+  Accessors.integer(`${EXIF}PixelXDimension`);
+
+/**
+ * Sets the valid image width, in pixels (`exif:PixelXDimension`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setPixelXDimension: Metadata.Setter<number> = Accessors.setInteger(
+  `${EXIF}PixelXDimension`,
+);
+
+/**
+ * The valid image height, in pixels (`exif:PixelYDimension`). An integer.
+ *
+ * @since 0.1.0
+ * @category getters
+ */
+export const pixelYDimension: (self: Metadata.Metadata) => Option.Option<number> =
+  Accessors.integer(`${EXIF}PixelYDimension`);
+
+/**
+ * Sets the valid image height, in pixels (`exif:PixelYDimension`).
+ *
+ * @since 0.1.0
+ * @category setters
+ */
+export const setPixelYDimension: Metadata.Setter<number> = Accessors.setInteger(
+  `${EXIF}PixelYDimension`,
+);

package/src/xmp/Extract.ts

@@ -0,0 +1,351 @@
+/**
+ * Reading the XMP packet embedded in an image file, as XMP Specification
+ * Part 3 places it: a JPEG's APP1 segment (with Extended XMP split across
+ * further APP1 segments) or a PNG's `iTXt` chunk with the keyword
+ * `XML:com.adobe.xmp` (stored or, read with `png`, zlib-compressed). Any
+ * other format (TIFF, WebP, GIF, MP4, PDF, …) can
+ * be scanned for its packet with `Packet.find`.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from 'effect/Array';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Result from 'effect/Result';
+import * as Schema from 'effect/Schema';
+
+/**
+ * A malformed image file.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class XmpExtractError extends Schema.TaggedError<XmpExtractError>()('XmpExtractError', {
+  message: Schema.String,
+}) {}
+
+/**
+ * The XMP of a JPEG file: the standard packet and, when the packet does not
+ * fit one segment, the Extended XMP document its `xmpNote:HasExtendedXMP`
+ * names.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface JpegXmp {
+  readonly standard: string;
+  readonly extended: Option.Option<string>;
+}
+
+const fail = (message: string): never => {
+  throw new XmpExtractError({ message });
+};
+
+const ascii = (text: string): Uint8Array =>
+  Uint8Array.from(Arr.map(Arr.fromIterable(text), (c) => c.charCodeAt(0)));
+
+const startsWith = (bytes: Uint8Array, prefix: Uint8Array): boolean =>
+  bytes.length >= prefix.length && Arr.every(Arr.fromIterable(prefix), (b, i) => bytes[i] === b);
+
+const utf8 = (bytes: Uint8Array): string => new TextDecoder().decode(bytes);
+const latin1 = (bytes: Uint8Array): string => new TextDecoder('windows-1252').decode(bytes);
+
+const view = (bytes: Uint8Array) => new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+const catchExtract = <A>(f: () => A): Result.Result<A, XmpExtractError> =>
+  Result.try({
+    try: f,
+    catch: (e) => {
+      if (e instanceof XmpExtractError) return e;
+      throw e;
+    },
+  });
+
+// -----------------------------------------------------------------------------
+// JPEG
+// -----------------------------------------------------------------------------
+
+const STANDARD = ascii('http://ns.adobe.com/xap/1.0/\0');
+const EXTENSION = ascii('http://ns.adobe.com/xmp/extension/\0');
+const APP1 = 0xe1;
+
+interface Segment {
+  readonly marker: number;
+  readonly data: Uint8Array;
+}
+
+const isStandalone = (marker: number) =>
+  marker === 0x01 || marker === 0xff || (marker >= 0xd0 && marker <= 0xd7);
+
+/** The segments before the image data (SOS) or the end of the image (EOI). */
+const jpegSegments = (bytes: Uint8Array): ReadonlyArray<Segment> => {
+  const data = view(bytes);
+  return Arr.getSomes(
+    Arr.unfold(2, (pos): Option.Option<readonly [Option.Option<Segment>, number]> => {
+      if (pos + 2 > bytes.length) return Option.none();
+      if (data.getUint8(pos) !== 0xff) return fail(`Expected a JPEG marker at offset ${pos}`);
+      const marker = data.getUint8(pos + 1);
+      if (marker === 0xd9 || marker === 0xda) return Option.none();
+      // A fill byte (0xFF) or a marker without a length.
+      if (isStandalone(marker))
+        return Option.some([Option.none(), marker === 0xff ? pos + 1 : pos + 2]);
+      if (pos + 4 > bytes.length) return fail(`Truncated JPEG segment at offset ${pos}`);
+      const length = data.getUint16(pos + 2);
+      const end = pos + 2 + length;
+      if (length < 2 || end > bytes.length) return fail(`Truncated JPEG segment at offset ${pos}`);
+      return Option.some([Option.some({ marker, data: bytes.subarray(pos + 4, end) }), end]);
+    }),
+  );
+};
+
+interface Chunk {
+  readonly guid: string;
+  readonly length: number;
+  readonly offset: number;
+  readonly data: Uint8Array;
+}
+
+const extensionChunk = (payload: Uint8Array): Chunk => {
+  const header = EXTENSION.length + 40;
+  if (payload.length < header) return fail('Truncated Extended XMP segment');
+  const data = view(payload);
+  return {
+    guid: latin1(payload.subarray(EXTENSION.length, EXTENSION.length + 32)),
+    length: data.getUint32(EXTENSION.length + 32),
+    offset: data.getUint32(EXTENSION.length + 36),
+    data: payload.subarray(header),
+  };
+};
+
+/** Reassembles the Extended XMP whose GUID the standard packet names. */
+const extended = (standard: string, chunks: ReadonlyArray<Chunk>): Option.Option<string> =>
+  Option.map(
+    Arr.findFirst(chunks, (c) => standard.includes(c.guid)),
+    ({ guid, length }) => {
+      const whole = new Uint8Array(length);
+      Arr.filter(chunks, (c) => c.guid === guid).forEach((c) => {
+        if (c.offset + c.data.length > length) fail('Extended XMP chunk out of bounds');
+        whole.set(c.data, c.offset);
+      });
+      return utf8(whole);
+    },
+  );
+
+/**
+ * Reads the XMP of a JPEG file, returning a `Result`: `None` when the file
+ * has no XMP.
+ *
+ * @since 0.1.0
+ * @category extraction
+ */
+export const jpegResult = (
+  bytes: Uint8Array,
+): Result.Result<Option.Option<JpegXmp>, XmpExtractError> =>
+  catchExtract(() => {
+    if (bytes[0] !== 0xff || bytes[1] !== 0xd8) return fail('Not a JPEG file');
+    const app1 = Arr.map(
+      Arr.filter(jpegSegments(bytes), (s) => s.marker === APP1),
+      (s) => s.data,
+    );
+    const chunks = Arr.map(
+      Arr.filter(app1, (d) => startsWith(d, EXTENSION)),
+      extensionChunk,
+    );
+    return Option.map(
+      Arr.findFirst(app1, (d) => startsWith(d, STANDARD)),
+      (d) => {
+        const standard = utf8(d.subarray(STANDARD.length));
+        return { standard, extended: extended(standard, chunks) };
+      },
+    );
+  });
+
+/**
+ * Reads the XMP of a JPEG file: `None` when the file has no XMP.
+ *
+ * @since 0.1.0
+ * @category extraction
+ */
+export const jpeg = (bytes: Uint8Array): Effect.Effect<Option.Option<JpegXmp>, XmpExtractError> =>
+  Effect.suspend(() => Effect.fromResult(jpegResult(bytes)));
+
+// -----------------------------------------------------------------------------
+// PNG
+// -----------------------------------------------------------------------------
+
+const PNG_SIGNATURE = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+const XMP_KEYWORD = 'XML:com.adobe.xmp';
+
+interface PngChunk {
+  readonly type: string;
+  readonly data: Uint8Array;
+}
+
+const pngChunks = (bytes: Uint8Array): ReadonlyArray<PngChunk> => {
+  const data = view(bytes);
+  return Arr.unfold(PNG_SIGNATURE.length, (pos): Option.Option<readonly [PngChunk, number]> => {
+    if (pos >= bytes.length) return Option.none();
+    if (pos + 12 > bytes.length) return fail(`Truncated PNG chunk at offset ${pos}`);
+    const length = data.getUint32(pos);
+    const type = latin1(bytes.subarray(pos + 4, pos + 8));
+    const end = pos + 12 + length;
+    if (end > bytes.length) return fail(`Truncated PNG chunk at offset ${pos}`);
+    if (type === 'IEND') return Option.none();
+    return Option.some([{ type, data: bytes.subarray(pos + 8, pos + 8 + length) }, end]);
+  });
+};
+
+/** The text of an XMP `iTXt` chunk: stored, or zlib-compressed. */
+interface XmpChunk {
+  readonly compressed: boolean;
+  readonly text: Uint8Array;
+}
+
+/** The XMP of an `iTXt` chunk, when its keyword is XMP's. */
+const xmpChunk = (chunk: Uint8Array): Option.Option<XmpChunk> => {
+  const keywordEnd = chunk.indexOf(0);
+  if (keywordEnd < 0 || latin1(chunk.subarray(0, keywordEnd)) !== XMP_KEYWORD) {
+    return Option.none();
+  }
+  const compressed = chunk[keywordEnd + 1] !== 0;
+  // Compression method 0 (zlib) is the only one PNG defines.
+  if (compressed && chunk[keywordEnd + 2] !== 0) return fail('Unknown iTXt compression method');
+  const languageEnd = chunk.indexOf(0, keywordEnd + 3);
+  const translatedEnd = languageEnd < 0 ? -1 : chunk.indexOf(0, languageEnd + 1);
+  if (translatedEnd < 0) return fail('Malformed iTXt chunk');
+  return Option.some({ compressed, text: chunk.subarray(translatedEnd + 1) });
+};
+
+const pngXmpChunk = (bytes: Uint8Array): Option.Option<XmpChunk> => {
+  if (!startsWith(bytes, PNG_SIGNATURE)) return fail('Not a PNG file');
+  return Option.firstSomeOf(
+    Arr.map(
+      Arr.filter(pngChunks(bytes), (c) => c.type === 'iTXt'),
+      (c) => xmpChunk(c.data),
+    ),
+  );
+};
+
+/**
+ * The most bytes `Extract.png` inflates a compressed XMP chunk to by
+ * default: 4 MiB, far above any real packet, so a small deflate bomb fails
+ * instead of exhausting memory.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const DEFAULT_MAX_XMP_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Options for `Extract.png`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface PngOptions {
+  /**
+   * The most bytes a compressed `iTXt` chunk may inflate to; past it the
+   * read fails. Defaults to `DEFAULT_MAX_XMP_BYTES`.
+   */
+  readonly maxXmpBytes?: number | undefined;
+}
+
+const concatChunks = (chunks: ReadonlyArray<Uint8Array>, total: number): Uint8Array => {
+  const out = new Uint8Array(total);
+  Arr.reduce(chunks, 0, (offset, chunk) => {
+    out.set(chunk, offset);
+    return offset + chunk.length;
+  });
+  return out;
+};
+
+/**
+ * Reads a stream to its end, failing (and cancelling it) as soon as the
+ * running total passes `max`, so nothing past the cap is buffered.
+ */
+const readCapped = (
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  max: number,
+  chunks: Array<Uint8Array>,
+  total: number,
+): Promise<Uint8Array> =>
+  reader.read().then((result) => {
+    if (result.done) return concatChunks(chunks, total);
+    const next = total + result.value.length;
+    if (next > max) {
+      void reader.cancel();
+      return fail(`Compressed XMP iTXt chunk inflates to more than ${max} bytes`);
+    }
+    chunks.push(result.value);
+    return readCapped(reader, max, chunks, next);
+  });
+
+/** Inflates zlib data with the platform's `DecompressionStream`, up to `max` bytes. */
+const inflate = (data: Uint8Array, max: number): Effect.Effect<Uint8Array, XmpExtractError> =>
+  Effect.tryPromise({
+    try: () => {
+      const source = new ReadableStream<BufferSource>({
+        start: (controller) => {
+          // A copy: `BufferSource` excludes a view over a `SharedArrayBuffer`.
+          controller.enqueue(data.slice());
+          controller.close();
+        },
+      });
+      return readCapped(
+        source.pipeThrough(new DecompressionStream('deflate')).getReader(),
+        max,
+        [],
+        0,
+      );
+    },
+    catch: (e) =>
+      e instanceof XmpExtractError
+        ? e
+        : new XmpExtractError({ message: 'Malformed compressed iTXt chunk' }),
+  });
+
+/**
+ * Reads the XMP packet of a PNG file, returning a `Result`: `None` when the
+ * file has no XMP. Decompression is asynchronous, so a compressed `iTXt`
+ * chunk fails here; `png` inflates it. (The XMP specification writes the
+ * chunk uncompressed, so a scanner can find the packet.)
+ *
+ * @since 0.1.0
+ * @category extraction
+ */
+export const pngResult = (
+  bytes: Uint8Array,
+): Result.Result<Option.Option<string>, XmpExtractError> =>
+  catchExtract(() =>
+    Option.map(pngXmpChunk(bytes), (chunk) =>
+      chunk.compressed
+        ? fail('A compressed XMP iTXt chunk needs Extract.png, which inflates it')
+        : utf8(chunk.text),
+    ),
+  );
+
+/**
+ * Reads the XMP packet of a PNG file: `None` when the file has no XMP. A
+ * zlib-compressed `iTXt` chunk is inflated with the platform's
+ * `DecompressionStream` (Node, browsers and Workers all provide it), and
+ * fails once it inflates past `maxXmpBytes` (default `DEFAULT_MAX_XMP_BYTES`).
+ *
+ * @since 0.1.0
+ * @category extraction
+ */
+export const png = (
+  bytes: Uint8Array,
+  options?: PngOptions,
+): Effect.Effect<Option.Option<string>, XmpExtractError> =>
+  Effect.flatMap(
+    Effect.suspend(() => Effect.fromResult(catchExtract(() => pngXmpChunk(bytes)))),
+    Option.match({
+      onNone: () => Effect.succeed(Option.none()),
+      onSome: (chunk) =>
+        chunk.compressed
+          ? Effect.map(inflate(chunk.text, options?.maxXmpBytes ?? DEFAULT_MAX_XMP_BYTES), (text) =>
+              Option.some(utf8(text)),
+            )
+          : Effect.succeed(Option.some(utf8(chunk.text))),
+    }),
+  );