@readium/shared 1.2.0

package/src/publication/LocalizedString.ts

@@ -0,0 +1,74 @@
+/* Copyright 2021 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by a BSD-style license,
+ * available in the LICENSE file present in the Github repository of the project.
+ */
+
+/**
+ * Represents a string with multiple translations indexed by a BCP 47 language tag.
+ */
+export class LocalizedString {
+  public readonly translations: { [key: string]: string };
+
+  public static readonly UNDEFINED_LANGUAGE = 'undefined';
+  public static readonly LANGUAGE_EN = 'en';
+
+  /**
+   * translations can be a string or a collection of language/translation pairs,
+   * for a single string the language is assumed to be undefined
+   */
+  constructor(translations: string | { [key: string]: string }) {
+    this.translations =
+      typeof translations === 'string'
+        ? { [LocalizedString.UNDEFINED_LANGUAGE]: translations }
+        : translations;
+  }
+
+  /**
+   * Parses a [LocalizedString] from its RWPM JSON representation.
+   *
+   * "anyOf": [
+   *   {
+   *     "type": "string"
+   *   },
+   *   {
+   *     "description": "The language in a language map must be a valid BCP 47 tag.",
+   *     "type": "object",
+   *     "patternProperties": {
+   *       "^((?<grandfathered>(en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang))|((?<language>([A-Za-z]{2,3}(-(?<extlang>[A-Za-z]{3}(-[A-Za-z]{3}){0,2}))?)|[A-Za-z]{4}|[A-Za-z]{5,8})(-(?<script>[A-Za-z]{4}))?(-(?<region>[A-Za-z]{2}|[0-9]{3}))?(-(?<variant>[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-(?<extension>[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+))*(-(?<privateUse>x(-[A-Za-z0-9]{1,8})+))?)|(?<privateUse2>x(-[A-Za-z0-9]{1,8})+))$": {
+   *         "type": "string"
+   *       }
+   *     },
+   *     "additionalProperties": false,
+   *     "minProperties": 1
+   *   }
+   * ]
+   */
+  public static deserialize(json: any): undefined | LocalizedString {
+    if (!(json && (typeof json === 'string' || json.constructor === Object)))
+      return;
+    return new LocalizedString(json);
+  }
+
+  public serialize(): any {
+    return this.translations;
+  }
+
+  /**
+   * Returns the first translation for the given [language] BCP–47 tag.
+   * If not found, then fallback:
+   *    1. on the undefined language
+   *    2. on the English language
+   *    3. the first translation found
+   *    4. returns empty string
+   */
+  public getTranslation(language?: string): string {
+    return (
+      this.translations[language || LocalizedString.UNDEFINED_LANGUAGE] ||
+      this.translations[LocalizedString.UNDEFINED_LANGUAGE] ||
+      this.translations[LocalizedString.LANGUAGE_EN] ||
+      (Object.values(this.translations).length === 0
+        ? ''
+        : Object.values(this.translations)[0])
+    );
+  }
+}

package/src/publication/Locator.ts

@@ -0,0 +1,225 @@
+/* Copyright 2021 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by a BSD-style license,
+ * available in the LICENSE file present in the Github repository of the project.
+ */
+
+import { arrayfromJSONorString, numberfromJSON } from '../util/JSONParse';
+
+/**
+ * One or more alternative expressions of the location.
+ * https://github.com/readium/architecture/tree/master/models/locators#the-location-object
+ */
+export class LocatorLocations {
+  /** Contains one or more fragment in the resource referenced by the `Locator`. */
+  public readonly fragments: Array<string>;
+
+  /** Progression in the resource expressed as a percentage (between 0 and 1). */
+  public readonly progression?: number;
+
+  /** Progression in the publication expressed as a percentage (between 0 and 1). */
+  public readonly totalProgression?: number;
+
+  /** An index in the publication (>= 1).*/
+  public readonly position?: number;
+
+  /** Additional locations for extensions. */
+  public readonly otherLocations?: Map<string, any>;
+
+  /**
+   * Creates a [Locations].
+   */
+  constructor(values: {
+    fragments?: Array<string>;
+    progression?: number;
+    totalProgression?: number;
+    position?: number;
+    otherLocations?: Map<string, any>;
+  }) {
+    this.fragments = values.fragments ? values.fragments : new Array<string>();
+    this.progression = values.progression;
+    this.totalProgression = values.totalProgression;
+    this.position = values.position;
+    this.otherLocations = values.otherLocations;
+  }
+
+  /**
+   * Parses a [Locations] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): LocatorLocations | undefined {
+    if (!json) return;
+    const progression = numberfromJSON(json.progression);
+    const totalProgression = numberfromJSON(json.totalProgression);
+    const position = numberfromJSON(json.position);
+
+    const otherLocations = new Map<string, any>();
+
+    const reservedKeys = new Set([
+      'fragment',
+      'fragments',
+      'progression',
+      'totalProgression',
+      'position',
+    ]);
+    Object.entries(json).forEach(([key, value]) => {
+      if (!reservedKeys.has(key)) {
+        otherLocations.set(key, value);
+      }
+    });
+
+    return new LocatorLocations({
+      fragments: arrayfromJSONorString(json.fragments || json.fragment),
+      progression:
+        progression !== undefined && progression >= 0 && progression <= 1
+          ? progression
+          : undefined,
+      totalProgression:
+        totalProgression !== undefined &&
+        totalProgression >= 0 &&
+        totalProgression <= 1
+          ? totalProgression
+          : undefined,
+      position: position !== undefined && position > 0 ? position : undefined,
+      otherLocations: otherLocations.size === 0 ? undefined : otherLocations,
+    });
+  }
+
+  /**
+   * Serializes a [Locations] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.fragments) json.fragments = this.fragments;
+    if (this.progression !== undefined) json.progression = this.progression;
+    if (this.totalProgression !== undefined)
+      json.totalProgression = this.totalProgression;
+    if (this.position !== undefined) json.position = this.position;
+    if (this.otherLocations) {
+      this.otherLocations.forEach((value, key) => (json[key] = value));
+    }
+    return json;
+  }
+}
+
+export class LocatorText {
+  public readonly after?: string;
+  public readonly before?: string;
+  public readonly highlight?: string;
+
+  /**
+   * Creates a [Text].
+   */
+  constructor(values: { after?: string; before?: string; highlight?: string }) {
+    this.after = values.after;
+    this.before = values.before;
+    this.highlight = values.highlight;
+  }
+
+  /**
+   * Parses a [Locations] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): LocatorText | undefined {
+    if (!json) return;
+    return new LocatorText({
+      after: json.after,
+      before: json.before,
+      highlight: json.highlight,
+    });
+  }
+
+  /**
+   * Serializes a [Locations] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.after !== undefined) json.after = this.after;
+    if (this.before !== undefined) json.before = this.before;
+    if (this.highlight !== undefined) json.highlight = this.highlight;
+    return json;
+  }
+}
+
+/**
+ * Provides a precise location in a publication in a format that can be stored and shared.
+ *
+ * There are many different use cases for locators:
+ *  - getting back to the last position in a publication
+ *  - bookmarks
+ *  - highlights & annotations
+ *  - search results
+ *  - human-readable (and shareable) reference in a publication
+ *
+ * https://github.com/readium/architecture/tree/master/locators
+ */
+export class Locator {
+  /** The URI of the resource that the Locator Object points to. */
+  public readonly href: string;
+
+  /** The media type of the resource that the Locator Object points to. */
+  public readonly type: string;
+
+  /** The title of the chapter or section which is more relevant in the context of this locator. */
+  public readonly title?: string;
+
+  /** One or more alternative expressions of the location. */
+  public readonly locations: LocatorLocations;
+
+  /** Textual context of the locator. */
+  public readonly text?: LocatorText;
+
+  /**
+   * Creates a [Locator].
+   */
+  constructor(values: {
+    href: string;
+    type: string;
+    title?: string;
+    locations?: LocatorLocations;
+    text?: LocatorText;
+  }) {
+    this.href = values.href;
+    this.type = values.type;
+    this.title = values.title;
+    this.locations = values.locations
+      ? values.locations
+      : new LocatorLocations({});
+    this.text = values.text;
+  }
+
+  /**
+   * Parses a [Link] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): Locator | undefined {
+    if (!(json && json.href && json.type)) return;
+    return new Locator({
+      href: json.href,
+      type: json.type,
+      title: json.title,
+      locations: LocatorLocations.deserialize(json.locations),
+      text: LocatorText.deserialize(json.text),
+    });
+  }
+
+  /**
+   * Serializes a [Link] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = { href: this.href, type: this.type };
+    if (this.title !== undefined) json.title = this.title;
+    if (this.locations) json.locations = this.locations.serialize();
+    if (this.text) json.text = this.text.serialize();
+    return json;
+  }
+
+  /**
+   * Shortcut to get a copy of the [Locator] with different [Locations] sub-properties.
+   */
+  public copyWithLocations(values: any): Locator {
+    return new Locator({
+      href: this.href,
+      type: this.type,
+      title: this.title,
+      text: this.text,
+      locations: new LocatorLocations({ ...this.locations, ...values }),
+    });
+  }
+}

package/src/publication/LocatorCollection.ts

@@ -0,0 +1,133 @@
+/* Copyright 2021 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by a BSD-style license,
+ * available in the LICENSE file present in the Github repository of the project.
+ */
+
+import { numberfromJSON } from '../util/JSONParse';
+import { Links } from './Link';
+import { LocalizedString } from './LocalizedString';
+import { Locator } from './Locator';
+
+/**
+ * Holds the metadata of a `LocatorCollection`.
+ */
+export class LocatorCollectionMetadata {
+  public title?: LocalizedString;
+
+  /** numberOfItems Indicates the total number of locators in the collection. */
+  public numberOfItems?: number;
+
+  public otherMetadata?: Map<string, any>;
+
+  /**
+   * Creates a [LocatorMetadata].
+   */
+  constructor(values: {
+    title?: LocalizedString;
+    numberOfItems?: number;
+    otherMetadata?: Map<string, any>;
+  }) {
+    this.title = values.title;
+    this.numberOfItems = values.numberOfItems;
+    this.otherMetadata = values.otherMetadata;
+  }
+
+  /**
+   * Parses a [LocatorMetadata] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): LocatorCollectionMetadata | undefined {
+    if (!json) return;
+
+    const otherMetadata = new Map<string, any>();
+
+    const reservedKeys = new Set(['title', 'numberOfItems']);
+    Object.entries(json).forEach(([key, value]) => {
+      if (!reservedKeys.has(key)) {
+        otherMetadata.set(key, value);
+      }
+    });
+
+    return new LocatorCollectionMetadata({
+      title: LocalizedString.deserialize(json.title),
+      numberOfItems: numberfromJSON(json.numberOfItems),
+      otherMetadata: otherMetadata.size === 0 ? undefined : otherMetadata,
+    });
+  }
+
+  /**
+   * Serializes a [LocatorMetadata] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.title) json.title = this.title.serialize();
+    if (this.numberOfItems !== undefined)
+      json.numberOfItems = this.numberOfItems;
+    if (this.otherMetadata) {
+      this.otherMetadata.forEach((value, key) => (json[key] = value));
+    }
+    return json;
+  }
+}
+
+/**
+ * Represents a sequential list of `Locator` objects.
+ *
+ * For example, a search result or a list of positions.
+ */
+export class LocatorCollection {
+  public metadata: LocatorCollectionMetadata;
+  public links: Links;
+  public locators: Array<Locator>;
+
+  /**
+   * Creates a [LocatorCollection].
+   */
+  constructor(values: {
+    metadata?: LocatorCollectionMetadata;
+    links?: Links;
+    locators?: Array<Locator>;
+  }) {
+    this.metadata = values.metadata ?? new LocatorCollectionMetadata({});
+    this.links = values.links ?? new Links([]);
+    this.locators = values.locators ?? [];
+  }
+
+  /**
+   * Parses a [LocatorCollection] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): LocatorCollection | undefined {
+    if (!json) return;
+
+    let locators: Array<Locator> | undefined;
+
+    let jsonList = json.locators;
+
+    if (jsonList && jsonList instanceof Array) {
+      locators = jsonList
+        .map<Locator>(x => Locator.deserialize(x) as Locator)
+        .filter(x => x !== undefined);
+    }
+
+    return new LocatorCollection({
+      metadata: LocatorCollectionMetadata.deserialize(json.metadata),
+      links: Links.deserialize(json.links),
+      locators,
+    });
+  }
+
+  /**
+   * Serializes a [LocatorCollection] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.metadata) {
+      let serializedMetadata = this.metadata.serialize();
+      if (serializedMetadata && Object.keys(serializedMetadata).length > 0)
+        json.metadata = serializedMetadata;
+    }
+    if (this.links && this.links.items.length > 0)
+      json.links = this.links.serialize();
+    if (this.locators) json.locators = this.locators.map(x => x.serialize());
+    return json;
+  }
+}

package/src/publication/Manifest.ts

@@ -0,0 +1,256 @@
+/* Copyright 2021 Readium Foundation. All rights reserved.
+ * Use of this source code is governed by a BSD-style license,
+ * available in the LICENSE file present in the Github repository of the project.
+ */
+
+import { Metadata } from './Metadata';
+import { Link, Links } from './Link';
+import { arrayfromJSONorString } from '../util/JSONParse';
+import { PublicationCollection } from './PublicationCollection';
+import { MediaType } from '../util/mediatype/MediaType';
+import { Locator, LocatorLocations } from "./Locator";
+
+/** Holds the metadata of a Readium publication, as described in
+ *  the Readium Web Publication Manifest.
+ *  See. https://readium.org/webpub-manifest/
+ */
+export class Manifest {
+  public readonly context?: Array<string>;
+
+  public readonly metadata: Metadata;
+
+  public readonly links: Links;
+
+  /** Identifies a list of resources in reading order for the publication. */
+  public readonly readingOrder: Links;
+
+  /** Identifies resources that are necessary for rendering the publication. */
+  public readonly resources?: Links;
+
+  /** Identifies the collection that contains a table of contents. */
+  public readonly tableOfContents?: Links;
+
+  public readonly subcollections?: Map<string, Array<PublicationCollection>>;
+
+  constructor(values: {
+    context?: Array<string>;
+    metadata: Metadata;
+    links: Links;
+    readingOrder: Links;
+    resources?: Links;
+    tableOfContents?: Links;
+    subcollections?: Map<string, Array<PublicationCollection>>;
+  }) {
+    this.context = values.context;
+    this.metadata = values.metadata;
+    this.links = values.links;
+    this.readingOrder = values.readingOrder;
+    this.resources = values.resources;
+    this.tableOfContents = values.tableOfContents;
+    this.subcollections = values.subcollections;
+  }
+
+  /**
+   * Parses a [Publication] from its RWPM JSON representation.
+   *
+   * https://readium.org/webpub-manifest/
+   * https://readium.org/webpub-manifest/schema/publication.schema.json
+   */
+  public static deserialize(json: any): Manifest | undefined {
+    if (!json) return;
+
+    const metadata = Metadata.deserialize(json.metadata);
+
+    if (!metadata) return;
+
+    const links = Links.deserialize(json.links);
+
+    if (!links) return;
+
+    const readingOrder = Links.deserialize(
+      json.readingOrder ? json.readingOrder : json.spine
+    );
+
+    if (!readingOrder) return;
+
+    return new Manifest({
+      context: arrayfromJSONorString(json['@context']),
+      metadata,
+      links,
+      readingOrder,
+      resources: Links.deserialize(json.resources),
+      tableOfContents: Links.deserialize(json.toc),
+      subcollections: PublicationCollection.deserializeCollections({
+        sub: json.sub,
+      }),
+    });
+  }
+
+  /**
+   * Serializes a [Publication] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+    if (this.context !== undefined) json['@context'] = this.context;
+    json.metadata = this.metadata.serialize();
+    json.links = this.links.serialize();
+    json.readingOrder = this.readingOrder.serialize();
+    if (this.resources) json.resources = this.resources.serialize();
+    if (this.tableOfContents) json.toc = this.tableOfContents.serialize();
+    PublicationCollection.serializeCollection(json, this.subcollections);
+    return json;
+  }
+
+  /** Finds the first link with the given relation in the manifest's links. */
+  public linkWithRel(rel: string): Link | undefined {
+    const links = new Array<Links>();
+    links.push(this.readingOrder);
+    if (this.resources) {
+      links.push(this.resources);
+    }
+    links.push(this.links);
+
+    let result: Link | undefined;
+
+    for (const collection of links) {
+      result = collection.findWithRel(rel);
+      if (result !== undefined) {
+        return result;
+      }
+    }
+
+    return result;
+  }
+
+  /** Finds all the links with the given relation in the manifest's links. */
+  public linksWithRel(rel: string): Array<Link> {
+    const result = [];
+    result.push(this.readingOrder.filterByRel(rel));
+    if (this.resources) {
+      result.push(this.resources.filterByRel(rel));
+    }
+    result.push(this.links.filterByRel(rel));
+
+    return result.reduce((acc, val) => acc.concat(val), []);
+  }
+
+  /**
+   * Creates a new [Locator] object from a [Link] to a resource of this manifest.
+   * Returns null if the resource is not found in this manifest.
+   */
+  public locatorFromLink(link: Link): Locator | undefined {
+    const components = link.href.split("#");
+    const href = components.length == 2 ? components[0] : link.href;
+    const resourceLink = this.linkWithHref(href);
+    if(!resourceLink) return undefined;
+    const type = resourceLink.type;
+    if(!type) return undefined;
+    const fragment = components.length == 2 ? components[1] : undefined;
+
+    return new Locator({
+      href,
+      type,
+      title: resourceLink.title ?? link.title,
+      locations: new LocatorLocations({
+        fragments: fragment ? [fragment] : undefined,
+        progression: fragment ? undefined : 0.0,
+      })
+    });
+  }
+
+  /** Finds the first Link having the given `href` in the publication's links. */
+  public linkWithHref(href: string): Link | undefined {
+    const find = (links: Array<Links>): Link | undefined => {
+      let result = undefined;
+
+      for (const collection of links) {
+        result = collection.findWithHref(href);
+        if (result !== undefined) {
+          return result;
+        }
+      }
+
+      const children = new Array<Links>();
+
+      links.forEach(item => {
+        const arr = [];
+        for (const link of item.items) {
+          if (link.alternates) {
+            arr.push(link.alternates);
+          }
+          if (link.children) {
+            arr.push(link.children);
+          }
+        }
+        children.push(...arr);
+      });
+
+      if (children.length > 0) {
+        result = find(children);
+      }
+
+      return result;
+    };
+
+    const links: Array<Links> = [];
+    links.push(this.readingOrder);
+    if (this.resources) {
+      links.push(this.resources);
+    }
+    links.push(this.links);
+
+    const link = find(links);
+
+    if (link !== undefined) {
+      return link;
+    }
+
+    const parts = href.split(/[#]/);
+
+    if (parts.length < 2) return;
+
+    const shortHref = parts[0];
+
+    return this.linkWithHref(shortHref);
+  }
+
+  /** The URL where this publication is served, computed from the `Link` with `self` relation.
+   *  e.g. https://provider.com/pub1293/manifest.json gives https://provider.com/pub1293/
+   */
+  public get baseURL(): string | undefined {
+    const selfLink = this.links.items.find(
+      el => el.rels && el.rels.has('self')
+    );
+    if (selfLink) {
+      let href = selfLink.href;
+      if (href) {
+        const li = href.lastIndexOf('/');
+        const lastpart = li === -1 ? undefined : href.substring(li + 1);
+
+        href = href.replace(new RegExp('/?$query$'), '');
+        href = href.replace(new RegExp('//$'), '');
+        if (lastpart) {
+          href = href.replace(new RegExp(lastpart + '$'), '');
+        }
+      }
+      return href;
+    }
+    return undefined;
+  }
+
+  /**
+   * Sets the URL where this [Publication]'s RWPM manifest is served.
+   */
+  public setSelfLink(href: string): void {
+    this.links.items = this.links.items.filter(
+      x => x.rels === undefined || !x.rels?.has('self')
+    );
+    this.links.items.push(
+      new Link({
+        href,
+        type: MediaType.READIUM_WEBPUB_MANIFEST.string,
+        rels: new Set<string>(['self']),
+      })
+    );
+  }
+}