Synolib2

.gitignore

@@ -1,5 +1,7 @@
 synonym-group.js
 
+docs
+
 npm-package/node_modules
 npm-package/index.js
 npm-package/index.d.ts

DESIGN.md

@@ -0,0 +1,57 @@
+# Design
+
+<!-- deno-fmt-ignore -->
+> [!NOTE]
+> This currently (2024-07-27) describes a potential future design, not
+> the current one.
+
+## Overview
+
+The central taxonomic entity is one object `N` per latin name.\
+Synolib returns as results a list of `N`s.
+
+Each `N` exists because of a taxon-name, taxon-concept or col-taxon in the
+data.\
+Each `N` is uniquely determined by its human-readable latin name (for taxa
+ranking below genus, this is a multi-part name — binomial or trinomial) and
+kingdom.\
+Each `N` contains `N+A` objects which represent latin names with an authority.\
+Each `N` contains, if present, `treatment`s directly associated with the
+respective taxon-name.\
+Other metadata (if present) of a `N` are the list of its parent names (family,
+order, ...); vernacular names; and taxon-name URI.
+
+Each `N+A` exists because of a taxon-concept or col-taxon in the data. It always
+has a parent `N`.\
+Each `N+A` is uniquely determined by its human-readable latin name (as above),
+kingdom and (normalized [^1]) authority.\
+Each `N+A` contains, if present, `treatment`s directly associated with the
+respective taxon-concept.\
+Other metadata (if present) of a `N` are CoL IDs; and taxon-concept URI.
+
+A `treatment` exists because it is in the data, and is identifed by its RDF
+URI.\
+A `treatment` may _define_, _augment_, _deprecate_ or _cite_ a `N+A`, and
+_treat_ or _cite_ a `N`.\
+If a `treatment` does _define_, _augment_, _deprecate_ or _treat_ different `N`
+and/or `N+A`s, they are considered synonyms.\
+Note that _cite_ does not create synonmic links.\
+Other metadata of a `treatment` are its authors, material citations, and images.
+
+Starting point of the algorithm is a latin name or the URI of either a
+taxon-name, tacon-conecpt or col-taxon.\
+It will first try to find the respective `N` and all associated metadata, `N+A`s
+and `treatment`s.\
+This `N` is the first result.\
+Then it will recursively use all synonyms indicated by the found `treatment`s to
+find new `N`s.\
+For each new `N`, it will find all associated metadata, `N+A`s and `treatment`s;
+and return it as the next result.\
+Then it will continue to expand recursively until no more new `N`s are found.
+
+The algorithm keeps track of which treatment links it followed and other reasons
+it added a `N` to the results.\
+This "justification" is also proved as metadata of a `N`.
+
+[^1]: I.e. ignoring differences in punctuation, diacritics, capitalization and
+such.

README.md

@@ -3,11 +3,21 @@
 A js module to get potential synonyms of a taxon name, the justifications for
 such synonymity and treatments about these taxon names or the respective taxa.
 
-See `index.html` for an example of a webpage using the library. Go to
-[http://plazi.github.io/synolib/](http://plazi.github.io/synolib/) to open the example page in the browser
-and execute the script.
+For a command line example using the library see: `example/cli.ts`.
 
-For a simple command line example using the library see: `main.ts`.
+You can try it locally using Deno with
+
+```sh
+deno run --allow-net ./example/cli.ts Ludwigia adscendens
+# or
+deno run --allow-net ./example/cli.ts http://taxon-name.plazi.org/id/Plantae/Ludwigia_adscendens
+# or
+deno run --allow-net ./example/cli.ts http://taxon-concept.plazi.org/id/Plantae/Ludwigia_adscendens_Linnaeus_1767
+# or
+deno run --allow-net ./example/cli.ts https://www.catalogueoflife.org/data/taxon/3WD9M
+```
+
+(replace the argument with whatever name interests you)
 
 ## building
 

SparqlEndpoint.ts

@@ -0,0 +1,81 @@
+async function sleep(ms: number): Promise<void> {
+  const p = new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+  return await p;
+}
+
+/** Describes the format of the JSON return by SPARQL endpoints */
+export type SparqlJson = {
+  head: {
+    vars: string[];
+  };
+  results: {
+    bindings: {
+      [key: string]:
+        | { type: string; value: string; "xml:lang"?: string }
+        | undefined;
+    }[];
+  };
+};
+
+/**
+ * Represents a remote sparql endpoint and provides a uniform way to run queries.
+ */
+export class SparqlEndpoint {
+  /** Create a new SparqlEndpoint with the given URI */
+  constructor(private sparqlEnpointUri: string) {}
+
+  /** @ignore */
+  // reasons: string[] = [];
+
+  /**
+   * Run a query against the sparql endpoint
+   *
+   * It automatically retries up to 10 times on fetch errors, waiting 50ms on the first retry and doupling the wait each time.
+   * Retries are logged to the console (`console.warn`)
+   *
+   * @throws In case of non-ok response status codes or if fetch failed 10 times.
+   * @param query The sparql query to run against the endpoint
+   * @param fetchOptions Additional options for the `fetch` request
+   * @param _reason (Currently ignored, used internally for debugging purposes)
+   * @returns Results of the query
+   */
+  async getSparqlResultSet(
+    query: string,
+    fetchOptions: RequestInit = {},
+    _reason = "",
+  ): Promise<SparqlJson> {
+    // this.reasons.push(_reason);
+
+    fetchOptions.headers = fetchOptions.headers || {};
+    (fetchOptions.headers as Record<string, string>)["Accept"] =
+      "application/sparql-results+json";
+    let retryCount = 0;
+    const sendRequest = async (): Promise<SparqlJson> => {
+      try {
+        // console.info(`SPARQL ${_reason} (${retryCount + 1})`);
+        const response = await fetch(
+          this.sparqlEnpointUri + "?query=" + encodeURIComponent(query),
+          fetchOptions,
+        );
+        if (!response.ok) {
+          throw new Error("Response not ok. Status " + response.status);
+        }
+        return await response.json();
+      } catch (error) {
+        if (fetchOptions.signal?.aborted) {
+          throw error;
+        } else if (retryCount < 10) {
+          const wait = 50 * (1 << retryCount++);
+          console.warn(`!! Fetch Error. Retrying in ${wait}ms (${retryCount})`);
+          await sleep(wait);
+          return await sendRequest();
+        }
+        console.warn("!! Fetch Error:", query, "\n---\n", error);
+        throw error;
+      }
+    };
+    return await sendRequest();
+  }
+}