tilde-lab / optimade-client Goto Github PK

Isomorphic TypeScript / JavaScript client to aggregate all the official Optimade providers

License: MIT License

JavaScript 25.30% TypeScript 74.70%

materials materials-science materials-informatics materials-design materials-genome materials-platform materials-discoveries materials-discovery chemoinformatics optimade

optimade-client's Introduction

Aggregating Optimade client for the online materials databases

Features

discovers all the official Optimade databases recursively
caches the discovered list (prefetched.json) for future and boosts the retrieval performance
queries them all, in the browser, at the server, everywhere
provides pagination, with the minimized number of pages

Install

npm i optimade --save

yarn add optimade

CDN: UNPKG | jsDelivr (available as window.optimade)

If you are not using ES6 or CDN, add to your HTML just before closing the body tag:

<script src="/path/to/optimade/dist/index.js"></script>
<!-- OR -->
<script type="module" src="/path/to/optimade/dist/index.mjs"></script>

Usage

The code is generally isomorphic, however one should additionally take care of downloading the cache or setting the CORS policy for the browsers. Concerning the CORS, the Optimade class constructor accepts the corsProxyUrl parameter, pointing to a running cors-anywhere proxy instance. This will be valid until all the Optimade providers are supplying the header Access-Control-Allow-Origin $http_origin in their responses. For the server-side environment this is not required.

Discovery and querying

const optimadeClient = new Optimade({
  providersUrl: "https://providers.optimade.org/providers.json",
});

console.log(optimadeClient.providers); // { [id: string]: Provider }[]

const providersMap = await optimadeClient.getProviders(); // { [id: string]: Provider }[]

const providerIds = Object.keys(providersMap); // string[]

const results = await optimadeClient.getStructuresAll({
  providers: Provider[],
  filter: YOUR_OPTIMADE_QUERY,
}); // [StructuresResponse[], Provider][]

Importing depends on your environment. See also the examples folder. The .html examples are suited for the browser environment, the .js examples are suited for the server environment.

Pagination

import prefetched from 'optimade/dist/prefetched.json';

const optimadeClient = new Optimade({
  providersUrl: "https://providers.optimade.org/providers.json",
});

optimadeClient.providers = prefetched.providers;
optimadeClient.apis = prefetched.apis;

const results = await optimadeClient.getStructuresAll({
  providers: Provider[],
  filter: YOUR_OPTIMADE_QUERY,
  page: number,
  limit: number,
  offset: number,
  batch: true
}); // [StructuresResponse[], Provider][]

License

MIT © Pavel Malyshev and Alexander Volkov, Tilde Materials Informatics

optimade-client's People

Stargazers

Watchers

Forkers

lgtm-migrator

optimade-client's Issues

Set HTTP `User-Agent` header for `isomorphic-unfetch`

It is usually very nice when software presents itself in the HTTP User-Agent header. Web browsers almost always present themselves in a verbose but neat way. This way the server-side developers are informed about what software makes requests to their servers, and may occasionally forward common issues to the client developers. Moreover, usage statistics could be drawn at the server-size, which is nice.

optimade-client seems to be using JS isomorphic-unfetch package for HTTP requests. By default its User-Agent is node-fetch/<version> (+https://github.com/bitinn/node-fetch). Changing this should not be difficult. It would be nice to see tilde-lab-optimade-client/<version> (or something similar) at least.

If user privacy is concern, it should be kept in mind that this is F/LOSS, thus anyone concerned with their privacy are free to patch their copy of the client to their liking.

Change the cache syncing strategy

Now done by prefetch.js with each new release at the npm. This is suboptimal.

optimade.prefetch() method

Add optimade.prefetch() method to make custom local cache

const optimade = new Optimade({
  providersUrl: "https://providers.optimade.org/providers.json",
});

optimade.prefetch({
  pathWithFileName: './prefetch.json', 
  excludeProviders: [''],
  batch: false
})

pathWithFileName - path to file output filename.json location
excludeProviders - array for exclude providers from cache
batch - portion statusable prefetching

Unclear error message when the providersUrl is wrong or defunct

const providerArray = Object.values(providersMap);
                             ^
TypeError: Cannot convert undefined or null to object

data_returned
data_available
more_data_available

to the client users, cf. tilde-lab/optimade.science#21

Prefetch does not work (but then works)

$ node prefetch.js
C:\cygwin64\home\Evgeny\basf\bscience-gui\node_modules\optimade\prefetch.js:24
        const source = Object.keys(optimade.providers).sort().reduce(
                              ^

TypeError: Cannot convert undefined or null to object
    at Function.keys (<anonymous>)
    at C:\cygwin64\home\Evgeny\basf\bscience-gui\node_modules\optimade\prefetch.js:24:24
    at processTicksAndRejections (node:internal/process/task_queues:96:5)

re-running helps

#!/usr/bin/env node

const fs = require('fs');