@readium/shared 1.2.0

package/src/publication/Metadata.ts

@@ -0,0 +1,329 @@
+/* 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,
+  datefromJSON,
+  positiveNumberfromJSON,
+} from '../util/JSONParse';
+import { BelongsTo } from './BelongsTo';
+import { Contributors } from './Contributor';
+import { LocalizedString } from './LocalizedString';
+import { ReadingProgression } from './ReadingProgression';
+import { Subjects } from './Subject';
+
+/**
+ * https://readium.org/webpub-manifest/schema/metadata.schema.json
+ *
+ * readingProgression : This contains the reading progression as declared in the
+ *     publication, so it might be [auto]. To lay out the content, use [effectiveReadingProgression]
+ *     to get the calculated reading progression from the declared direction and the language.
+ * otherMetadata Additional metadata for extensions, as a JSON dictionary.
+ */
+export class Metadata {
+  public title: LocalizedString;
+  public typeUri?: string;
+  public identifier?: string;
+  public subtitle?: LocalizedString;
+  public sortAs?: LocalizedString;
+  public artists?: Contributors;
+  public authors?: Contributors;
+  public colorists?: Contributors;
+  public contributors?: Contributors;
+  public editors?: Contributors;
+  public illustrators?: Contributors;
+  public inkers?: Contributors;
+  public letterers?: Contributors;
+  public narrators?: Contributors;
+  public pencilers?: Contributors;
+  public translators?: Contributors;
+  public languages?: Array<string>;
+  public description?: string;
+  public publishers?: Contributors;
+  public imprints?: Contributors;
+  public published?: Date;
+  public modified?: Date;
+  public subjects?: Subjects;
+  public belongsTo?: BelongsTo;
+  public belongsToCollections?: Contributors;
+  public belongsToSeries?: Contributors;
+  public readingProgression?: ReadingProgression;
+  public duration?: number;
+  public numberOfPages?: number;
+  public otherMetadata?: { [key: string]: any };
+
+  /**All metadata not in otherMetadata */
+  private static readonly mappedProperties = [
+    'title',
+    '@type',
+    'identifier',
+    'subtitle',
+    'sortAs',
+    'artist',
+    'author',
+    'colorist',
+    'contributor',
+    'editor',
+    'illustrator',
+    'inker',
+    'letterer',
+    'narrator',
+    'penciler',
+    'translator',
+    'language',
+    'description',
+    'publisher',
+    'imprint',
+    'published',
+    'modified',
+    'subject',
+    'belongsTo',
+    'readingProgression',
+    'duration',
+    'numberOfPages',
+  ];
+
+  /** Creates [Metadata] object */
+  constructor(values: {
+    title: LocalizedString;
+    typeUri?: string;
+    identifier?: string;
+    subtitle?: LocalizedString;
+    sortAs?: LocalizedString;
+    artists?: Contributors;
+    authors?: Contributors;
+    colorists?: Contributors;
+    contributors?: Contributors;
+    editors?: Contributors;
+    illustrators?: Contributors;
+    inkers?: Contributors;
+    letterers?: Contributors;
+    narrators?: Contributors;
+    pencilers?: Contributors;
+    translators?: Contributors;
+    languages?: Array<string>;
+    description?: string;
+    publishers?: Contributors;
+    imprints?: Contributors;
+    published?: Date;
+    modified?: Date;
+    subjects?: Subjects;
+    belongsTo?: BelongsTo;
+    belongsToCollections?: Contributors;
+    belongsToSeries?: Contributors;
+    readingProgression?: ReadingProgression;
+    duration?: number;
+    numberOfPages?: number;
+    otherMetadata?: { [key: string]: any };
+  }) {
+    //title always required
+    this.title = values.title as LocalizedString;
+    this.typeUri = values.typeUri;
+    this.identifier = values.identifier;
+    this.subtitle = values.subtitle;
+    this.sortAs = values.sortAs;
+    this.artists = values.artists;
+    this.authors = values.authors;
+    this.colorists = values.colorists;
+    this.contributors = values.contributors;
+    this.editors = values.editors;
+    this.illustrators = values.illustrators;
+    this.inkers = values.inkers;
+    this.letterers = values.letterers;
+    this.narrators = values.narrators;
+    this.pencilers = values.pencilers;
+    this.translators = values.translators;
+    this.languages = values.languages;
+    this.description = values.description;
+    this.publishers = values.publishers;
+    this.imprints = values.imprints;
+    this.published = values.published;
+    this.modified = values.modified;
+    this.subjects = values.subjects;
+    this.belongsTo = values.belongsTo;
+    this.belongsToCollections = values.belongsToCollections;
+    this.belongsToSeries = values.belongsToSeries;
+
+    if (
+      this.belongsToCollections &&
+      this.belongsToCollections.items.length > 0
+    ) {
+      if (!this.belongsTo) {
+        this.belongsTo = new BelongsTo();
+      }
+      this.belongsTo.items.set('collection', this.belongsToCollections);
+    }
+
+    if (this.belongsToSeries && this.belongsToSeries.items.length > 0) {
+      if (!this.belongsTo) {
+        this.belongsTo = new BelongsTo();
+      }
+      this.belongsTo.items.set('series', this.belongsToSeries);
+    }
+
+    this.readingProgression = values.readingProgression;
+    this.duration = values.duration;
+    this.numberOfPages = values.numberOfPages;
+    this.otherMetadata = values.otherMetadata;
+  }
+
+  /**
+   * Parses a [Metadata] from its RWPM JSON representation.
+   *
+   * If the metadata can't be parsed, a warning will be logged with [warnings].
+   */
+  public static deserialize(json: any): Metadata | undefined {
+    if (!(json && json.title)) return;
+
+    const title = LocalizedString.deserialize(json.title) as LocalizedString;
+    const typeUri = json['@type'];
+    const identifier = json.identifier;
+    const subtitle = LocalizedString.deserialize(json.subtitle);
+    const sortAs = LocalizedString.deserialize(json.sortAs);
+    const artists = Contributors.deserialize(json.artist);
+    const authors = Contributors.deserialize(json.author);
+    const colorists = Contributors.deserialize(json.colorist);
+    const contributors = Contributors.deserialize(json.contributor);
+    const editors = Contributors.deserialize(json.editor);
+    const illustrators = Contributors.deserialize(json.illustrator);
+    const inkers = Contributors.deserialize(json.inker);
+    const letterers = Contributors.deserialize(json.letterer);
+    const narrators = Contributors.deserialize(json.narrator);
+    const pencilers = Contributors.deserialize(json.penciler);
+    const translators = Contributors.deserialize(json.translator);
+    const languages = arrayfromJSONorString(json.language);
+    const description = json.description;
+    const publishers = Contributors.deserialize(json.publisher);
+    const imprints = Contributors.deserialize(json.imprint);
+    const published = datefromJSON(json.published);
+    const modified = datefromJSON(json.modified);
+    const subjects = Subjects.deserialize(json.subject);
+    const belongsTo = BelongsTo.deserialize(json.belongsTo);
+    const readingProgression = json.readingProgression;
+    const duration = positiveNumberfromJSON(json.duration);
+    const numberOfPages = positiveNumberfromJSON(json.numberOfPages);
+
+    let otherMetadata = Object.assign({}, json);
+    Metadata.mappedProperties.forEach(x => delete otherMetadata[x]);
+    if (Object.keys(otherMetadata).length === 0) {
+      otherMetadata = undefined;
+    }
+
+    return new Metadata({
+      title,
+      typeUri,
+      identifier,
+      subtitle,
+      sortAs,
+      artists,
+      authors,
+      colorists,
+      contributors,
+      editors,
+      illustrators,
+      inkers,
+      letterers,
+      narrators,
+      pencilers,
+      translators,
+      languages,
+      description,
+      publishers,
+      imprints,
+      published,
+      modified,
+      subjects,
+      belongsTo,
+      readingProgression,
+      duration,
+      numberOfPages,
+      otherMetadata,
+    });
+  }
+
+  /**
+   * Serializes a [Metadata] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = { title: this.title.serialize() };
+    if (this.typeUri !== undefined) json['@type'] = this.typeUri;
+    if (this.identifier !== undefined) json.identifier = this.identifier;
+    if (this.subtitle) json.subtitle = this.subtitle.serialize();
+    if (this.sortAs) json.sortAs = this.sortAs.serialize();
+    if (this.editors) json.editor = this.editors.serialize();
+    if (this.artists) json.artist = this.artists.serialize();
+    if (this.authors) json.author = this.authors.serialize();
+    if (this.colorists) json.colorist = this.colorists.serialize();
+    if (this.contributors) json.contributor = this.contributors.serialize();
+    if (this.illustrators) json.illustrator = this.illustrators.serialize();
+    if (this.letterers) json.letterer = this.letterers.serialize();
+    if (this.narrators) json.narrator = this.narrators.serialize();
+    if (this.pencilers) json.penciler = this.pencilers.serialize();
+    if (this.translators) json.translator = this.translators.serialize();
+    if (this.inkers) json.inker = this.inkers.serialize();
+    if (this.languages) json.language = this.languages;
+    if (this.description !== undefined) json.description = this.description;
+    if (this.publishers) json.publisher = this.publishers.serialize();
+    if (this.imprints) json.imprint = this.imprints.serialize();
+    if (this.published !== undefined)
+      json.published = this.published.toISOString();
+    if (this.modified !== undefined)
+      json.modified = this.modified.toISOString();
+    if (this.subjects) json.subject = this.subjects.serialize();
+    if (this.belongsTo) json.belongsTo = this.belongsTo.serialize();
+    if (this.readingProgression)
+      json.readingProgression = this.readingProgression;
+    if (this.duration !== undefined) json.duration = this.duration;
+    if (this.numberOfPages !== undefined)
+      json.numberOfPages = this.numberOfPages;
+
+    if (this.otherMetadata) {
+      const metadata = this.otherMetadata;
+      Object.keys(metadata).forEach(x => (json[x] = metadata[x]));
+    }
+
+    return json;
+  }
+
+  /**
+   * Computes a [ReadingProgression] when the value of [readingProgression] is set to
+   * auto, using the publication language.
+   *
+   * See this issue for more details: https://github.com/readium/architecture/issues/113
+   */
+  public get effectiveReadingProgression(): ReadingProgression {
+    if (
+      this.readingProgression &&
+      this.readingProgression !== ReadingProgression.auto
+    ) {
+      return this.readingProgression;
+    }
+
+    // https://github.com/readium/readium-css/blob/develop/docs/CSS16-internationalization.md#missing-page-progression-direction
+    if (this.languages?.length !== 1) {
+      return ReadingProgression.ltr;
+    }
+
+    const primaryLang = this.languages[0].toLowerCase();
+
+    if (primaryLang === 'zh-hant' || primaryLang === 'zh-tw') {
+      return ReadingProgression.rtl;
+    }
+
+    // The region is ignored for ar, fa and he.
+    const lang = primaryLang.split('-')[0];
+
+    switch (lang) {
+      case 'ar':
+        return ReadingProgression.rtl;
+      case 'fa':
+        return ReadingProgression.rtl;
+      case 'he':
+        return ReadingProgression.rtl;
+      default:
+        return ReadingProgression.ltr;
+    }
+  }
+}

package/src/publication/Properties.ts

@@ -0,0 +1,44 @@
+/* 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.
+ */
+
+/**
+ * Properties associated to the linked resource.
+ *
+ * This is opened for extensions.
+ * https://readium.org/webpub-manifest/schema/link.schema.json
+ */
+export class Properties {
+  public otherProperties: { [key: string]: any };
+
+  constructor(values: { [key: string]: any }) {
+    this.otherProperties = values;
+  }
+
+  /**
+   * Creates a [Properties] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): Properties | undefined {
+    if (!json) return;
+    return new Properties(json);
+  }
+
+  /**
+   * Serializes a [Properties] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    return this.otherProperties;
+  }
+
+  /**
+   * Makes a copy of this [Properties] after merging in the given additional other [properties].
+   */
+  public add(properties: { [key: string]: any }): Properties {
+    const _properties = Object.assign({}, this.otherProperties);
+    for (const property in properties) {
+      _properties[property] = properties[property];
+    }
+    return new Properties(_properties);
+  }
+}

package/src/publication/Publication.ts

@@ -0,0 +1,148 @@
+/* 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 { Link, Links } from './Link';
+import { Locator } from './Locator';
+import { Manifest } from './Manifest';
+import { Metadata } from './Metadata';
+import { EmptyFetcher, Fetcher } from '../fetcher/Fetcher';
+import { PublicationCollection } from './PublicationCollection';
+import { Resource } from '../fetcher/Resource';
+import { GuidedNavigationDocument } from "./GuidedNavigation";
+import { URITemplate } from "../util";
+
+export type ServiceFactory = () => null;
+
+/** Shared model for a Readium Publication. */
+export class Publication {
+  /** The manifest holding the publication metadata extracted from the publication file */
+  public manifest: Manifest;
+  private readonly fetcher: Fetcher = new EmptyFetcher();
+
+  // Shortcuts to manifest properties
+  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;
+  /** Identifies the collection that contains sub collections. */
+  public readonly subcollections?: Map<string, Array<PublicationCollection>>;
+
+  constructor(values: { manifest: Manifest; fetcher?: Fetcher }) {
+    if (values.fetcher) this.fetcher = values.fetcher;
+    this.manifest = values.manifest;
+    this.context = values.manifest.context;
+    this.metadata = values.manifest.metadata;
+    this.links = values.manifest.links;
+    this.readingOrder = values.manifest.readingOrder;
+    this.resources = values.manifest.resources;
+    this.tableOfContents = values.manifest.tableOfContents;
+    this.subcollections = values.manifest.subcollections;
+  }
+
+  /** 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 {
+    return this.manifest.baseURL;
+  }
+
+  /** Finds the first Link having the given `href` in the publication's links. */
+  public linkWithHref(href: string): Link | undefined {
+    return this.manifest.linkWithHref(href);
+  }
+
+  /**
+   * Returns the [links] of the first child [PublicationCollection] with the given role, or an
+   * empty list.
+   */
+  public linksWithRole(role: string): Links | undefined {
+    const list = this.subcollections?.get(role);
+    return list && list.length > 0 ? list[0].links : undefined;
+  }
+
+  /** Finds all the links with the given relation in the publication's links. */
+  public linksWithRel(rel: string): Array<Link> {
+    return this.manifest.linksWithRel(rel);
+  }
+
+  /**
+   * Finds the first [Link] having the given [rel] in the publications's links.
+   */
+  public linkWithRel(rel: string): Link | undefined {
+    return this.manifest.linkWithRel(rel);
+  }
+
+  public async positionsFromManifest(): Promise<Locator[]> {
+    const positionListLink = this.manifest.links.findWithMediaType(
+      'application/vnd.readium.position-list+json'
+    );
+    if (positionListLink === undefined) return [];
+    const positionListJSON = (await this.get(
+      positionListLink
+    ).readAsJSON()) as { positions: unknown[] | null, total: number };
+    if(!positionListJSON['total']) return [];
+    return (positionListJSON['positions'] as unknown[]) // Get the array for the positions key
+      .map(pos => Locator.deserialize(pos)) // Parse locators
+      .filter(l => l !== undefined) as Locator[]; // Filter out failures
+  }
+
+  public async guideForLink(link: Link): Promise<GuidedNavigationDocument | undefined> {
+    const findGNLink = (l: Link): Link | undefined => l.alternates?.findWithMediaType(
+      'application/guided-navigation+json'
+    );
+
+    let guidedNavigationLink = findGNLink(link);
+    if(!guidedNavigationLink) {
+      // If provided link doesn't have a guided navigation link,
+      // search through the manfiest for a matching Link based on the `href`
+      const foundLink = this.linkWithHref(link.href);
+      if (foundLink !== undefined) {
+        // A Link was found, attempt to find a guided navigation link
+        guidedNavigationLink = findGNLink(foundLink);
+      }
+    }
+
+    if(!guidedNavigationLink) {
+      // Still unable to find a guided navigation link, try to use the manifest's global document
+      guidedNavigationLink = this.manifest.links.findWithMediaType(
+        'application/guided-navigation+json'
+      );
+    }
+
+    // Unable to find any guided navigation Link, give up
+    if(!guidedNavigationLink) return;
+
+    let href = guidedNavigationLink.href;
+    if(guidedNavigationLink.templated) {
+      // The manifest's guided navigation link is templated, expand it
+      const template = new URITemplate(href);
+      const params: { [param: string]: string } = {};
+      if(template.parameters.has('ref')) {
+        // The template has a `ref` parameter that could be used to reduce the returned doc's size
+        params['ref'] = link.href;
+      }
+      href = new URITemplate(href).expand(params);
+    }
+
+    // Fetch the guided navigation document
+    const guidedNavigationJSON = (await this.get(new Link({
+      href,
+    })).readAsJSON());
+    return GuidedNavigationDocument.deserialize(guidedNavigationJSON);
+  }
+
+  /**
+   * Returns the resource targeted by the given non-templated [link].
+   */
+  public get(link: Link): Resource {
+    // TODO warn about expanding templated links
+    return this.fetcher.get(link);
+  }
+}

package/src/publication/PublicationCollection.ts

@@ -0,0 +1,144 @@
+/* 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 { Links } from './Link';
+
+/**
+ * Core Collection Model
+ *
+ * https://readium.org/webpub-manifest/schema/subcollection.schema.json
+ * Can be used as extension point in the Readium Web Publication Manifest.
+ */
+export class PublicationCollection {
+  public metadata?: Map<string, any>;
+  public links: Links;
+  public subcollections?: Map<string, Array<PublicationCollection>>;
+
+  /**
+   * Creates a [PublicationCollection].
+   */
+  constructor(values: {
+    metadata?: Map<string, any>;
+    links: Links;
+    subcollections?: Map<string, Array<PublicationCollection>>;
+  }) {
+    this.metadata = values.metadata;
+    this.links = values.links;
+    this.subcollections = values.subcollections;
+  }
+
+  /**
+   * Parses a [PublicationCollection] from its RWPM JSON representation.
+   */
+  public static deserialize(json: any): PublicationCollection | undefined {
+    if (!json) return;
+
+    let links: Links | undefined;
+    let metadata: Map<string, any> | undefined;
+    let subcollections: Map<string, Array<PublicationCollection>> | undefined;
+
+    if (json instanceof Array) {
+      // Parses an array of links.
+      links = Links.deserialize(json);
+    } else if (json instanceof Object) {
+      // Parses a sub-collection object.
+      links = Links.deserialize(json.links);
+
+      metadata = new Map<string, any>();
+
+      if (json.metadata) {
+        Object.entries(json.metadata).forEach(([key, value]) => {
+          metadata?.set(key, value);
+        });
+      }
+
+      subcollections = PublicationCollection.deserializeCollections(json);
+    } else {
+      return;
+    }
+
+    if (!links || links.items.length === 0) return;
+
+    return new PublicationCollection({
+      metadata: metadata?.size ? metadata : undefined,
+      links,
+      subcollections: subcollections?.size ? subcollections : undefined,
+    });
+  }
+
+  /**
+   * Parses a map of [PublicationCollection] indexed by their roles from its RWPM JSON representation.
+   *
+   */
+  public static deserializeCollections(
+    json: any
+  ): Map<string, Array<PublicationCollection>> | undefined {
+    if (!json) return;
+    const collections = new Map<string, Array<PublicationCollection>>();
+    Object.entries(json).forEach(([role, subJSON]) => {
+      if (role !== 'links' && role !== 'metadata') {
+        // Parses a list of links or a single collection object.
+        const collection = PublicationCollection.deserialize(subJSON);
+
+        if (collection) {
+          const list = new Array<PublicationCollection>();
+          list.push(collection);
+          collections.set(role, list);
+        } else if (subJSON instanceof Array) {
+          // Parses a list of collection objects.
+          const list = subJSON
+            .map<PublicationCollection>(
+              item =>
+                PublicationCollection.deserialize(item) as PublicationCollection
+            )
+            .filter(x => x !== undefined);
+
+          collections.set(role, list);
+        }
+      }
+    });
+
+    return collections.size ? collections : undefined;
+  }
+
+  /**
+   * Serializes a [PublicationCollection] to its RWPM JSON representation.
+   */
+  public serialize(): any {
+    const json: any = {};
+
+    if (this.metadata) {
+      json.metadata = {};
+      this.metadata.forEach(
+        (value: any, key: string) => (json.metadata[key] = value)
+      );
+    }
+
+    if (this.links.items.length) {
+      json.links = this.links.serialize();
+    }
+
+    PublicationCollection.serializeCollection(json, this.subcollections);
+
+    return json;
+  }
+
+  public static serializeCollection(
+    json: any,
+    subcollections?: Map<string, Array<PublicationCollection>>
+  ) {
+    if (subcollections && subcollections.size > 0) {
+      subcollections.forEach(
+        (value: Array<PublicationCollection>, key: string) => {
+          if (value.length === 1) {
+            json[key] = value[0].serialize();
+          } else {
+            json[key] = value.map(x => x.serialize());
+          }
+        }
+      );
+    }
+  }
+}

package/src/publication/ReadingProgression.ts

@@ -0,0 +1,28 @@
+/* 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 { Page } from './presentation/Presentation';
+
+export enum ReadingProgression {
+  auto = 'auto',
+  btt = 'btt',
+  ltr = 'ltr',
+  rtl = 'rtl',
+  ttb = 'ttb',
+}
+
+export function leadingPage(readingProgression: ReadingProgression): Page {
+  switch (readingProgression) {
+    case ReadingProgression.auto:
+    case ReadingProgression.ttb:
+    case ReadingProgression.ltr:
+      return Page.left;
+    case ReadingProgression.rtl:
+    case ReadingProgression.btt:
+      return Page.right;
+    default:
+      return Page.left;
+  }
+}