@rondinif/phytojs 1.3.0 | Documentation

Intro

Introduction to the PhytoJS package

Welcome to PhytoJS, a modern javascript toolkit to search about plants on open data.

The prefix phyto- , comes from ancient greek φυτόν (phutón, “plant”), is used when something is pertaining to or derived from plants.
js is the abbreviation of javascript.

About PhytoJS documentation

This documentation is still a work in progress,nevertheless it could help to understand what PhytoJS consists of, how to use the library and what are the APIs it provides.

Why should this project interest me?

The development of PhytoJS has a single goal: gain experience by experimenting with emerging and gain experience by experimenting with interesting software engineering practices and enjoy the benefits that can be obtained through them. This can be done by having fun with an area of interest as pleasant and important as the world of flowers, vegetables and plants.

Collaborating together in the development of PhytoJS it's an opportunity to learn a lot of new things and share them with fellow friends and the community

How to use the PhytoJS's algorithms as a dependency or service component for my programs

PhytoJS is released as a package and can easily be exploited by other projects thaks to popular package manager such as npm or yarm.

PhytoJS was designed to (theoretically) work whatever the use case,as long as the application in in the Javascript or Typescript ecosystem, as long as the application in in the Javascript or Typescript ecosystem, it could be used in:

Front-end and browser scripts
Command line interface (CLI) applications
Desktop (GUI) applications
Mobile applications
Back-end development
In the build or continous integration phases
Any combination of the above

Some examples of how this library could apply in your projects

PhytoJS Samples for NodeJS

There are examples that use both require and import to reference the PhytoJS servive module.

UMD (Universal Module Definition)
- AMD and CJS (CommonJS) are both compatible with UMD
ESM / ES6 (ECMAScript.next and TC39 Module Definition)

PhytoJS Samples for the browser

Live Demo of PhytoJS running in the browser

video demo available

Play & Learn by these codepens: PhytoJS & pReact tutorial

.. more pens linked in the samples for the browser section

ServerSide PhytoJS Samples for NodeJS

What's in `PhythoJS` the library

Let's start with the main Phyto class or jump directly to its most useful methods:

resolvedPlantsByName
wdSearchByAnyName
wdPlantsByAnyName
sparqlScientificNameById

rondinif/phytojs

src/main.js

this module contains the Phyto class that has methods to simplify access to open data relating to the world of flowers, vegetables and plants by providing powerful search functions to obtain entities belonging to this data domain

rondinif/phytojs

Config

PhytoJS Configuration

this chapter explains phytojs configuration

Logging

PhytoJS logging

this chapter will explains logging in phytojs

Licence

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Phyto

src/main.js

main class to use as PhytoJS application programming interface. see Instance Members to learn about the features available and what each one of them does.

new Phyto(fetch: Function, config: object, log: object, logconfig: object)

Parameters

fetch (Function) a fetch function possibly an isomorphic one; when code runs in browsers it could be window.fetch , or any compliant standard fetch ; PhytoJS's tests are passed by using isomorphic-fetch

config

(object
            = {isUnderTest:()=>false})

an optional configuration object that has confifuration properties as defined in config/config @rondinif/phytojs/esm/config config

log

(object
            = newLog())

a logger object isomorph with @rondinif/phytojs/esm/log

logconfig

(object
            = {isLogVerbose:()=>false,isLogSilent:()=>true})

a configuration object for the logger, isomorph with config/logconfig @rondinif/phytojs/esm/logconfig logconfig

Example

import 'isomorphic-fetch';
import { Phyto } from '@rondinif/phytojs';
const api = new Phyto(fetch);
api.resolvedPlantsByName('origano').then(async res => {
  console.log(JSON.stringify(res.plants));
});

wdSearchByAnyName

src/main.js

wdSearchByAnyName(name: string): Promise

Parameters

name (string) the name or any term for which the wikidata search will be carried out; read Phyto#getWikiDataApiEndpointUri carefully and make sure you understand the recommendations regarding the use of data sources and endpoints for an aware use of this functionality.

Returns

Promise: a Promise of the search results; @see tests and expectations

wdPlantsByAnyName

src/main.js

wdPlantsByAnyName(name: string): Promise

Parameters

name (string) the name of the plant for which the odla search will be carried out

Returns

Promise: a Promise of the search results; @see tests and expectations

resolvedPlantsByName

src/main.js

resolvedPlantsByName(name: string): Promise

Parameters

name (string) the name of the plant for which the odla re-solver will go to find valid entities uniquely identifiable by means of an id and a scientific-name

Returns

Promise: a Promise of results with the list resolved plants; @see tests and expectations

sparqlScientificNameById

src/main.js

Bla Bla TODO ... completare con un Example

sparqlScientificNameById(id: string): Promise

Parameters

id (string) the id of the entitity for which the odla re-solver will go to find valid scientific-name

Returns

Promise: a Promise of results with the list of scientific-name of the resolved plant; see tests and expectations

getSparqlEndpointUri

src/main.js

The URI of the Web API enpoint used by PhytoJS to interface the Wikidata Query Service. The SPARQL endpoint URI is set by configuration; default behavior uses live endpoint only in production, while a virtualized service is used for tests.

Recommendation #1: Before using live endpoints make sure you have checked , accepted and agreed to the Web API endpoint service's term of use, disclaimers, privacy policies and other conditions; in this case see wikimedia.org-wiki term of use and wikidata disclaimer

Recommendation #2: When the system is under test (or is at the development stage) the live endpoint should not be used; use a service virtualization tool instead with proxies support and record/replay behavior to easily capture data from origin server that the request should proxy to. @see service-virtualization as a possible choice.

getSparqlEndpointUri(): string

Returns

string: the SPARQL endpoint which will be used by the OpenDataLogicAgent

Example

import 'isomorphic-fetch';
import { Phyto } from '@rondinif/phytojs';
const api = new Phyto(fetch);
console.log(api.getSparqlEndpointUri()); // > 'https://query.wikidata.org'
api.config().isUnderTest = () => true;
console.log(api.getSparqlEndpointUri()); // > 'http://127.0.0.1:6569'

getWikiDataApiEndpointUri

src/main.js

The URI of the Web API enpoint used by PhytoJS to interface MediaWiki API. The Web API enpoint URI is set by configuration; default behavior uses live endpoint only in production, while a virtualized service is used for tests.

getWikiDataApiEndpointUri(): string

Returns

string: the Wikidata API endpoint which will be used by OpenDataLogicAgent

Example

import 'isomorphic-fetch';
import { Phyto } from '@rondinif/phytojs';
const api = new Phyto(fetch);
console.log(api.getWikiDataApiEndpointUri()); // > 'https://www.wikidata.org/w/api.php'
api.config().isUnderTest = () => true;
console.log(api.getWikiDataApiEndpointUri()); // > 'http://127.0.0.1:6568/w/api.php'

config

src/main.js

Allow access to the configuration object; Use this function to inspect the current logger configuration or to change on the fly the the PhytoJS's api instance configuration settings (hot change).

config(): object

Returns

object: the effective configuration which will be used by the OpenDataLogicAgent PhytoJs internals.

Example

import 'isomorphic-fetch';
import { Phyto } from '@rondinif/phytojs';
const api = new Phyto(fetch);
console.log(api.config().isUnderTest()); // > false
api.config().isUnderTest = () => true;
console.log(api.config().isUnderTest()); // > true

logger

src/main.js

Allow access to the actual internal used logger Use this function to get the logger object actually used internally by PhytoJS; the logger object could be used to inspect the current logger configuration or for logging by the same logger used by the PhytoJS's api instance.

logger(): object

Returns

object: the effective logger which will be used by the OpenDataLogicAgent PhytoJs internals.

Example

import 'isomorphic-fetch';
import { Phyto } from '@rondinif/phytojs';
const api = new Phyto(fetch);
api.logger()._config.isLogSilent();
//	true
api.logger()._config.isLogVerbose();
//	false

// live change logger configuration settings
api.logger()._config.isLogSilent = () => false;
api.logger()._config.isLogSilent();
// false
api.logger().info(('this log information is written by the actual logger used by the API instance of PhytoJS');
// this log information is written by the actual logger used by the API instance of PhytoJS

Intro

Introduction to the PhytoJS package

About PhytoJS documentation

Why should this project interest me?

How to use the PhytoJS's algorithms as a dependency or service component for my programs

Some examples of how this library could apply in your projects

PhytoJS Samples for NodeJS

PhytoJS Samples for the browser

Live Demo of PhytoJS running in the browser

Play & Learn by these codepens: PhytoJS & pReact tutorial

ServerSide PhytoJS Samples for NodeJS

What's in PhythoJS the library

rondinif/phytojs

Config

PhytoJS Configuration

see also:

Logging

PhytoJS logging

Licence

Phyto

wdSearchByAnyName

wdPlantsByAnyName

resolvedPlantsByName

sparqlScientificNameById

getSparqlEndpointUri

getWikiDataApiEndpointUri

config

logger

What's in `PhythoJS` the library