@internetarchive/metadata-service 0.0.1-alpha.1

package/src/models/file.ts

@@ -0,0 +1,105 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Memoize } from 'typescript-memoize';
+import {
+  Byte,
+  ByteParser,
+  Duration,
+  DurationParser,
+  NumberParser,
+} from '@internetarchive/field-parsers';
+
+/**
+ * This represents an Internet Archive File
+ *
+ * @export
+ * @class File
+ */
+export class File {
+  rawValue: Record<string, any>;
+
+  get name(): string {
+    return this.rawValue.name;
+  }
+
+  get source(): string {
+    return this.rawValue.source;
+  }
+
+  get btih(): string {
+    return this.rawValue.btih;
+  }
+
+  get md5(): string {
+    return this.rawValue.md5;
+  }
+
+  get format(): string {
+    return this.rawValue.format;
+  }
+
+  get mtime(): string {
+    return this.rawValue.mtime;
+  }
+
+  get crc32(): string {
+    return this.rawValue.crc32;
+  }
+
+  get sha1(): string {
+    return this.rawValue.sha1;
+  }
+
+  get original(): string | undefined {
+    return this.rawValue.original;
+  }
+
+  @Memoize() get size(): Byte | undefined {
+    return this.rawValue.size
+      ? ByteParser.shared.parseValue(this.rawValue.size)
+      : undefined;
+  }
+
+  get title(): string | undefined {
+    return this.rawValue.title;
+  }
+
+  @Memoize() get length(): Duration | undefined {
+    return this.rawValue.length
+      ? DurationParser.shared.parseValue(this.rawValue.length)
+      : undefined;
+  }
+
+  @Memoize() get height(): number | undefined {
+    return this.rawValue.height
+      ? NumberParser.shared.parseValue(this.rawValue.height)
+      : undefined;
+  }
+
+  @Memoize() get width(): number | undefined {
+    return this.rawValue.width
+      ? NumberParser.shared.parseValue(this.rawValue.width)
+      : undefined;
+  }
+
+  @Memoize() get track(): number | undefined {
+    return this.rawValue.track
+      ? NumberParser.shared.parseValue(this.rawValue.track)
+      : undefined;
+  }
+
+  get external_identifier(): string | string[] | undefined {
+    return this.rawValue.external_identifier;
+  }
+
+  get creator(): string | undefined {
+    return this.rawValue.creator;
+  }
+
+  get album(): string | undefined {
+    return this.rawValue.album;
+  }
+
+  constructor(json: Record<string, any>) {
+    this.rawValue = json;
+  }
+}

package/src/models/metadata-fields/field-types/boolean.ts

@@ -0,0 +1,8 @@
+import { BooleanParser } from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+export class BooleanField extends MetadataField<boolean, BooleanParser> {
+  constructor(rawValue: MetadataRawValue) {
+    super(BooleanParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/field-types/byte.ts

@@ -0,0 +1,16 @@
+import { Byte, ByteParser } from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+/**
+ * ByteField is a unit-specific number field that
+ * returns a value in bytes
+ *
+ * @export
+ * @class ByteField
+ * @extends {MetadataField<Byte, ByteParser>}
+ */
+export class ByteField extends MetadataField<Byte, ByteParser> {
+  constructor(rawValue: MetadataRawValue) {
+    super(ByteParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/field-types/date.ts

@@ -0,0 +1,8 @@
+import { DateParser } from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+export class DateField extends MetadataField<Date, DateParser> {
+  constructor(rawValue: MetadataRawValue) {
+    super(DateParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/field-types/duration.ts

@@ -0,0 +1,17 @@
+import { Duration, DurationParser } from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+/**
+ * The DurationField parses different duration formats
+ * and returns a `Duration`, which is a number in seconds
+ * with decimals.
+ *
+ * @export
+ * @class DurationField
+ * @extends {MetadataField<Duration, DurationParser>}
+ */
+export class DurationField extends MetadataField<Duration, DurationParser> {
+  constructor(rawValue: MetadataRawValue) {
+    super(DurationParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/field-types/list.ts

@@ -0,0 +1,44 @@
+import {
+  FieldParserInterface,
+  ListParser,
+  NumberParser,
+  StringParser,
+} from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+/**
+ * The ListField handles parsing of a list of values.
+ *
+ * Certain fields in the metadata, like `subject` typically have a
+ * comma or semicolon-separated list of values. The `ListField`
+ * parses the list values independently and aggregates them into
+ * the main `.values` array.
+ */
+export class ListField<
+  T,
+  FieldParserInterfaceType extends FieldParserInterface<T[]>
+> extends MetadataField<T, FieldParserInterfaceType> {
+  constructor(rawValue: MetadataRawValue, parser: FieldParserInterfaceType) {
+    super(parser, rawValue);
+  }
+}
+
+/**
+ * The StringListField handles parsing of a list of strings.
+ */
+export class StringListField extends ListField<string, ListParser<string>> {
+  constructor(rawValue: MetadataRawValue) {
+    const parser = new ListParser<string>(StringParser.shared);
+    super(rawValue, parser);
+  }
+}
+
+/**
+ * The NumberListField handles parsing of a list of numbers.
+ */
+export class NumberListField extends ListField<number, ListParser<number>> {
+  constructor(rawValue: MetadataRawValue) {
+    const parser = new ListParser<number>(NumberParser.shared);
+    super(rawValue, parser);
+  }
+}

package/src/models/metadata-fields/field-types/mediatype.ts

@@ -0,0 +1,8 @@
+import { MediaType, MediaTypeParser } from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+export class MediaTypeField extends MetadataField<MediaType, MediaTypeParser> {
+  constructor(rawValue: MetadataRawValue) {
+    super(MediaTypeParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/field-types/number.ts

@@ -0,0 +1,8 @@
+import { NumberParser } from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+export class NumberField extends MetadataField<number, NumberParser> {
+  constructor(rawValue: MetadataRawValue) {
+    super(NumberParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/field-types/page-progression.ts

@@ -0,0 +1,14 @@
+import {
+  PageProgression,
+  PageProgressionParser,
+} from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+export class PageProgressionField extends MetadataField<
+  PageProgression,
+  PageProgressionParser
+> {
+  constructor(rawValue: MetadataRawValue) {
+    super(PageProgressionParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/field-types/string.ts

@@ -0,0 +1,8 @@
+import { StringParser } from '@internetarchive/field-parsers';
+import { MetadataField, MetadataRawValue } from '../metadata-field';
+
+export class StringField extends MetadataField<string, StringParser> {
+  constructor(rawValue: MetadataRawValue) {
+    super(StringParser.shared, rawValue);
+  }
+}

package/src/models/metadata-fields/metadata-field.ts

@@ -0,0 +1,108 @@
+import { Memoize } from 'typescript-memoize';
+import { FieldParserInterface } from '@internetarchive/field-parsers';
+
+/**
+ * The MetadataRawValue is all of the possible raw types we can get for a field.
+ *
+ * This allows the parsers to know if they can handle the raw value or not and
+ * how to handle it if they can.
+ */
+export type MetadataRawValue = string | string[] | number | boolean;
+
+export interface MetadataFieldInterface<T> {
+  /**
+   * The raw value received from the API response
+   *
+   * @type {MetadataRawValue}
+   * @memberof MetadataField
+   */
+  rawValue?: MetadataRawValue;
+
+  /**
+   * The first value if there are multiple or the only value if there is one
+   *
+   * @readonly
+   * @type {(T | undefined)}
+   * @memberof MetadataField
+   */
+  value?: T;
+
+  /**
+   * The array of all values for the field.
+   *
+   * Many fields only contain a single value and
+   * can be accessed via the `.value` getter
+   *
+   * @type {T[]}
+   * @memberof MetadataField
+   */
+  values: T[];
+}
+
+/**
+ * The MetadataField is responsible for three things:
+ * 1. Take in some raw data (strings, arrays, numbers, etc)
+ * 2. Normalize the input to an array of the input,
+ *    ie. [string, string], [number, number], [Date, Date], etc
+ * 3. Cast the values to their expected `Type`
+ *
+ * This class gets instiated with a `Type` and a parser of that type. For instance, the
+ * `DateField` is a subclass of `MetadataField` with a `Type` of `Date` and a `DateParser`.
+ *
+ * When using a `DateField`, you can pass it a string date and it will cast it to a javascript Date,
+ * ie:
+ *
+ * ```
+ * const dateField = new DateField('2020-02-13')
+ * dateField.value = Date(2020-02-13) // native javascript Date object
+ * dateField.values = [Date(2020-02-13)] // the normalized array of values
+ * dateField.rawValue = '2020-02-13' // the raw string that was passed in
+ * ```
+ *
+ * @class MetadataField
+ * @template Type The type of metadata this is (string, number, Date, etc)
+ * @template FieldParserInterfaceType The parser for that type (StringParser, NumberParser, etc)
+ */
+export class MetadataField<
+  Type,
+  FieldParserInterfaceType extends FieldParserInterface<Type | Type[]>
+> implements MetadataFieldInterface<Type>
+{
+  /** @inheritdoc */
+  rawValue?: MetadataRawValue;
+
+  /** @inheritdoc */
+  @Memoize() get values(): Type[] {
+    const values = this.parseRawValue();
+    return values;
+  }
+
+  /** @inheritdoc */
+  @Memoize() get value(): Type | undefined {
+    return this.values[0];
+  }
+
+  constructor(parser: FieldParserInterfaceType, rawValue?: MetadataRawValue) {
+    this.parser = parser;
+    this.rawValue = rawValue;
+  }
+
+  private parser: FieldParserInterfaceType;
+
+  private parseRawValue(): Type[] {
+    if (this.rawValue === undefined) return [];
+    const rawValues = Array.isArray(this.rawValue)
+      ? this.rawValue
+      : [this.rawValue];
+    const values: Type[] = [];
+    rawValues.forEach(value => {
+      const parsed = this.parser.parseValue(value);
+      if (Array.isArray(parsed)) {
+        values.push(...parsed);
+      } else {
+        if (parsed !== undefined) values.push(parsed);
+      }
+    });
+    return values;
+  }
+}