@overture-stack/lectern-client
v2.0.0-beta.3
Published
TypeScript client to interact with Lectern servers and perform data validation versus Lectern dictionaries.
Downloads
110
Keywords
Readme
Lectern Client
The Lectern Client provides developers TypeScript code tools to interact with Lectern servers and Lectern Dictionaries. This package provides data processing functions that will parse and validate submitted data, ensuring that it adheres to the structure defined by the Dictionary. It also provides a REST client to fetch Lectern Dictionary data from a Lectern Server.
Features
- REST client to interact with Lectern servers:
- Fetch dictionary by name and version
- Fetch difference summaries between dictionary versions
- Process data using a Lectern Dictionary:
- Convert raw string inputs into properly typed values.
- Check the structure of input data is valid.
- Apply all restrictions, both across schemas and on individual fields, to validate input data.
- Report all validation errors found in the input data.
- Expose Lectern Validation library functionality:
- Parsing functions to check and convert data types from string values
- Validation functions to confirm the structure and content of records match Lectern schemas
- This functionality is combined in the Processing functions
Developer Examples
Data Fetching
import * as lectern from '@overture-stack/lectern-client';
const lecternUrl = 'http://lectern.example.com';
const dictionaryName = 'dictionary-name';
const currentVersion = "2.3";
const previousVersion = "2.1";
const dictionary = lectern.rest.fetchSchema(lecternUrl, dictionaryName, currentVersion);
const versionUpdates = lectern.rest.fetchDiff(lecternUrl, dictionaryName, currentVersion, previousVersion);
Data Processing
The following example shows how to process data using the Lectern Client. The input donorData
is presented as hardcoded, but in a typical scenario this would be submitted to the application through an uploaded TSV, form entry, or similar user submission system.
To process data records which all belong to the same schema we use the processSchema
function:
import * as lectern from '@overture-stack/lectern-client';
const dictionary = await getLecternDictionary();
const donorData = [{submitter_donor_id: "abc123", gender: "Male", age: "28"}, {submitter_donor_id: "def456", gender: "Female", age: "37"}]
const schemaProcessingResult = lectern.process.processSchema(dictionary, "donors", donorData);
switch (schemaProcessingResult.status) {
case 'SUCCESS': {
const { records } = schemaProcessingResult;
// use converted and validated records
}
case 'ERROR_PARSING': {
const { errors, records } = schemaProcessingResult;
// errors occured parsing records. read the errors that occurred
// records have been return with their values parsed where possible. If an error occurred, the original input string value is returned
}
case 'ERROR_VALIDATION': {
const { records, errors } = schemaProcessingResult;
// errors occured validating records. these errors have been returned
// records were parsed successfully, so this returns all parsed records
}
Lectern Dependencies
The Lectern Client is a wrapper around Lectern submodules that allow functionality to be shared between client and server implementations. If you do not need the REST client, or the combined processing functions, you can consider including submodules directly to access the specific pieces of functionality you require.
| Package | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lectern-dictionary | Definition of the Lectern Dictionary structure. Includes TS types and schemas for validating the content of Lectern dictionary. Also includes functionality to comparing multiple Lectern Dictionary versions, and to analyze the differences between them. | | lectern-validation | Provides functionality for validating data against a Lectern dictionary. |