@statlertronik/collection-json-utils
Helper utility to generate data for 'Collection+JSON - Hypermedia Type'
How to use it
to install:
npm install @statlertronik/collection-json-utils
in code (typescript):
/*--------------------------------------------------------------------*/
/* Creating 'Collection+JSON' response object with collection data */
/* and with references to 'queries' & 'template' objects. */
/*--------------------------------------------------------------------*/
import {
CJ_MEDIA_TYPE,
ICollectionJSON,
buildCJResponse,
addCJLink,
IItem,
addCJItem,
addItemData,
addItemLink
} from '@statlertronik/collection-json-utils';
// create 'Collection+JSON' response object and initialize its 'version' and "href" properties
const cj: ICollectionJSON = buildCJResponse("1.0", "http://example.com/api/groups");
// add items to 'links' property array of 'Collection+JSON' response
addCJLink(cj, "http://example.com/api/groups/?queries" /*hr*/, "queries" /*rel*/);
addCJLink(cj, "http://example.com/api/groups/?template" /*hr*/, "template" /*rel*/);
// add items to 'items' property array of 'Collection+JSON' response
{
const itm: IItem = addCJItem(cj, "http://example.com/api/groups/1"):
addItemData(itm, "name" /*name*/, "Writers" /*value*/, "Name" /*prompt*/);
addItemData(itm, "active" /*name*/, "false" /*value*/, "Active" /*prompt*/);
addItemLink(itm, "http://example.com/api/images/13" /*hr*/, "avatar" /*rel*/, "Avatar" /*prompt*/, "image" /*render*/);
}
{
const itm: IItem = addCJItem(cj, "http://example.com/api/groups/2"):
addItemData(itm, "name" /*name*/, "Others" /*value*/, "Name" /*prompt*/);
addItemData(itm, "active" /*name*/, "true" /*value*/, "Active" /*prompt*/);
addItemLink(itm, "http://example.com/api/images/24" /*hr*/, "avatar" /*rel*/, "Avatar" /*prompt*/, "image" /*render*/);
}
// now convert it to JSON string and send it to client with HTTP 'content-type' set to 'CJ_MEDIA_TYPE'
...
/*--------------------------------------------------------------------*/
/* Creating 'Collection+JSON' response object with collection data, */
/* 'queries' and 'template'. */
/*--------------------------------------------------------------------*/
import {
CJ_MEDIA_TYPE,
ICollectionJSON,
buildCJResponse,
addCJLink,
IItem,
addCJItem,
addItemData,
IQuery,
addCJQuery,
addQueryData,
addCJTemplateData
} from '@statlertronik/collection-json-utils';
// create 'Collection+JSON' response object and initialize its 'version' and "href" properties
const cj: ICollectionJSON = buildCJResponse("1.0", "http://example.com/api/groups");
// add items to 'links' property array of 'Collection+JSON' response
addCJLink(cj, "http://example.com/api/groups/page/?offset=10&length=5" /*hr*/, "next" /*rel*/);
addCJLink(cj, "http://example.com/api/groups/page/?offset=0&length=5" /*hr*/, "prev" /*rel*/);
addCJLink(cj, "http://example.com/api/groups/page/?offset=0&length=5" /*hr*/, "first" /*rel*/);
addCJLink(cj, "http://example.com/api/groups/page/?offset=95&length=5" /*hr*/, "last" /*rel*/);
// add items to 'items' property array of 'Collection+JSON' response
{
const itm: IItem = addCJItem(cj, "http://example.com/api/groups/1"):
addItemData(itm, "name" /*name*/, "Writers" /*value*/, "Name" /*prompt*/);
addItemData(itm, "active" /*name*/, "false" /*value*/, "Active" /*prompt*/);
addItemLink(itm, "http://example.com/api/images/13" /*hr*/, "avatar" /*rel*/, "Avatar" /*prompt*/, "image" /*render*/);
}
{
const itm: IItem = addCJItem(cj, "http://example.com/api/groups/2"):
addItemData(itm, "name" /*name*/, "Others" /*value*/, "Name" /*prompt*/);
addItemData(itm, "active" /*name*/, "true" /*value*/, "Active" /*prompt*/);
addItemLink(itm, "http://example.com/api/images/24" /*hr*/, "avatar" /*rel*/, "Avatar" /*prompt*/, "image" /*render*/);
}
// add items to 'queries' property array of 'Collection+JSON' response
{
const qry: IQuery = addCJQuery(cj, "http://example.com/api/groups/search" /*href*/, "search" /*rel*/, "Search" /*prompt*/);
addQueryData(qry, "search" /*name*/, "" /*value*/);
}
// add template data to 'template' propery 'data' array
addCJTemplateData(cj, "name" /*name*/, "Name" /*prompt*/);
addCJTemplateData(cj, "active" /*name*/, "Active" /*prompt*/);
// now convert it to JSON string and send it to client with HTTP 'content-type' set to 'CJ_MEDIA_TYPE'
...
/*--------------------------------------------------------------------*/
/* Creating 'Collection+JSON' response object with error */
/*--------------------------------------------------------------------*/
import {
CJ_MEDIA_TYPE,
ICollectionJSON,
buildCJResponse,
setCJError,
} from '@statlertronik/collection-json-utils';
// create 'Collection+JSON' response object and initialize its 'version' and "href" properties
const cj: ICollectionJSON = buildCJResponse("1.0" /*ver*/, "http://example.com/api/groups" /*hr*/);
// add error object
setCJError(cj, "Server Error" /*title*/, "E7720" /*code*/, "Some unexpected event occured" /*message*/);
// now convert it to JSON string and send it to client with HTTP 'content-type' set to 'CJ_MEDIA_TYPE'
...
/*--------------------------------------------------------------------*/
/* Converting collection-JSON response object to array of */
/* IDataRowObjWithRef objects corresponding to items. */
/* Client does it when it receives response from server. */
/*--------------------------------------------------------------------*/
import {
CJ_MEDIA_TYPE,
ICollectionJSON,
IDataRowObjWithRef,
cjConvertItems2ArrayOfObjects
} from '@statlertronik/collection-json-utils';
// receive and convert JSON string to Collection+JSON response object
const cj: ICollectionJSON = ...;
const a: IDataRowObjWithRef[] = cjConvertItems2ArrayOfObjects(cj)
...
/*--------------------------------------------------------------------*/
/* Creating 'Collection+JSON' write object */
/*--------------------------------------------------------------------*/
import {
CJ_MEDIA_TYPE,
ITemplateResponse,
buildTemplateResponse,
addTemplateRespData
} from '@statlertronik/collection-json-utils';
// create 'Collection+JSON' write object
const templateResp: ITemplateResponse = buildTemplateResponse();
// add write object data
addTemplateRespData(templateResp, "name" /*name*/, "Pilots" /*value*/);
addTemplateRespData(templateResp, "active" /*name*/, "true" /*value*/);
// now convert it to JSON string and send it to server with HTTP 'content-type' set to 'CJ_MEDIA_TYPE'
...
/*--------------------------------------------------------------------*/
/* Creating 'Collection+JSON' write object from JavaScript plain */
/* object. */
/*--------------------------------------------------------------------*/
import {
CJ_MEDIA_TYPE,
ITemplateResponse,
ICJPlainObject,
cjConvertObject2TemplateResponse
} from '@statlertronik/collection-json-utils';
// JavaScript plain object containing data for ITemplateResponse object
const o: ICJPlainObject = {
name: "Citizens",
active: false,
size: 100
}
// create 'Collection+JSON' write object
const templateResp: ITemplateResponse = cjConvertObject2TemplateResponse(o, ["size"] /*ignore*/);
// now convert it to JSON string and send it to server with HTTP 'content-type' set to 'CJ_MEDIA_TYPE'
...
/*--------------------------------------------------------------------*/
/* Converting 'Collection+JSON' ITemplate object to IColumnsInfo */
/* object. It happens when server receives write object or client */
/* receives collection object with template. */
/*--------------------------------------------------------------------*/
import {
CJ_MEDIA_TYPE,
ITemplate,
cjExtractColumnsValuesFromTemplate
} from '@statlertronik/collection-json-utils';
// receives ITemplate object
templ: ITemplate = ...
try {
const columns: IColumnsInfo = cjExtractColumnsValuesFromTemplate(templ, ["active"] /*extra_column_names*/);
...
}
catch(e) {
...
}
API
Basic
// string representing this hypermedia type used as value of HTTP 'content-type' header
const CJ_MEDIA_TYPE;
interface IData {
name: STRING;
value?: VALUE;
prompt?: STRING;
}
interface ILink {
rel: STRING;
href: STRING;
name?: STRING;
render?: RENDER_TYPE;
prompt?: STRING;
}
interface IItem {
href?: URI;
data?: IData[];
links?: ILink[];
}
interface IQuery {
href: URI;
rel: STRING;
prompt?: STRING;
name?: STRING;
data?: IData[];
}
interface ITemplate {
data?: IData[];
}
interface ICJError {
title?: STRING;
code?: STRING;
message?: STRING;
}
interface ICollection {
version?: STRING;
href?: URI;
links?: ILink[];
items?: IItem[];
queries?: IQuery[];
template?: ITemplate;
error?: ICJError;
}
interface ICollectionJSON {
collection: ICollection;
}
interface ITemplateResponse {
template: ITemplate;
}
buildCJResponse(ver: STRING, hr: URI): ICollectionJSON
Function creates Collection-JSON root object containing version and href.
Parameters
Name | Meaning |
---|---|
ver | version |
hr | href to the resource |
addCJLink(cj: ICollectionJSON, hr: URI, rel: STRING, name?: STRING, prompt?: STRING, render?: RENDER_TYPE): void
Function adds single 'ILink' object to Collection-JSON root object
Parameters
Name | Meaning |
---|---|
cj | Collection-JSON root object returned by buildCJResponse(...) |
hr | href of the resource |
rel | type of 'href' |
name | name of the link |
prompt | prompt string |
render | interpretation of reference, either 'image' or 'link' (default = 'link') |
addCJItem(cj: ICollectionJSON, href?: URI): IItem
Function adds 'IItem' object to Collection-JSON root object
Parameters
Name | Meaning |
---|---|
cj | Collection-JSON root object returned by buildCJResponse(...) |
href | reference to the resource |
addItemData(itm: IItem, name: STRING, value?: VALUE, prompt?: STRING): void
Function adds 'IData' object to 'IItem' object
Parameters
Name | Meaning |
---|---|
itm | 'IItem' object returned by addCJItem(...) |
name | name of column |
value | value of column |
prompt | prompt string |
addItemLink(itm: IItem, hr: URI, rel: STRING, name?: STRING, prompt?: STRING, render?: RENDER_TYPE): void
Function adds 'ILink' object to 'IItem' object
Parameters
Name | Meaning |
---|---|
itm | 'IItem' object returned by addCJItem(...) |
hr | href |
rel | type of href |
name | name of the link |
prompt | prompt string |
render | interpretation of reference, either 'image' or 'link' (default = 'link') |
addCJQuery(cj: ICollectionJSON, href: URI, rel: STRING, prompt?: STRING): IQuery
Function adds 'IQuery' object to Collection-JSON root object
Parameters
Name | Meaning |
---|---|
cj | Collection-JSON root object returned by buildCJResponse(...) |
href | reference to the resource |
rel | type of href |
prompt | prompt string |
addQueryData(qry: IQuery, name: STRING, value: VALUE, prompt?: STRING): void
Function adds 'IData' object to 'IQuery' object
Parameters
Name | Meaning |
---|---|
qry | 'IQuery' object returned by addCJQuery(...) |
name | name of column |
value | value of column |
prompt | promppt string |
addCJTemplateData(cj: ICollectionJSON, name: STRING, prompt?: STRING): void
Function adds data to 'ITemplate' object of Collection-JSON root object. It creates 'template' & 'template.data' if any of them is missing.
Parameters
Name | Meaning |
---|---|
cj | Collection-JSON root object returned by buildCJResponse(...) |
name | name of the template |
prompt | prompt string |
setCJError(cj: ICollectionJSON, title?: STRING, code?: STRING, message?: STRING): void
Function sets 'ICJError' object for Collection-JSON root object.
Parameters
Name | Meaning |
---|---|
cj | Collection-JSON root object |
title | description |
code | error code |
message | error text |
buildTemplateResponse(): ITemplateResponse
Function creates Collection-JSON ITemplateResponse object
addTemplateRespData(templateResp: TemplateResponse, name: STRING, value?: VALUE, prompt?: STRING): void
Function adds data to 'ITemplate' object of TemplateResponse object. It creates 'template.data' if missing.
Parameters
Name | Meaning |
---|---|
template - ITemplate object returned by addTemplateRespData() | |
name | name of the template |
value | value |
prompt | prompt string |
Advanced
interface IDataRowObj {
[index: string]: any;
}
interface IDataRowObjWithRef {
href?: string;
data: IDataRowObj;
}
cjConvertItems2ArrayOfObjects(cj: cjlib.ICollectionJSON): IDataRowObjWithRef[]
Function creates array of IDataRowObjWithRef objects containing collection items.
Parameters
Name | Meaning |
---|---|
cj | collection-JSON response object if type ICollectionJSON |
interface IColumnsInfo {
column_names: string[];
column_values: cjlib.VALUE[];
extra_column_names?: string[];
extra_column_values?: cjlib.VALUE[];
}
cjExtractColumnsValuesFromTemplate(templ: cjlib.ITemplate, extra_column_names?: string[]): IColumnsInfo | never
Function creates an object containing arrays of column names/values from 'ITemplate' and returns it. It can also separately extract selected columns and place them in extra column names/value instead of in arrays of column names/values. It throws exception if templ.data is undefined or empty.
Parameters
Name | Meaning |
---|---|
templ | template object |
extra_column_names | array of extra column names |
interface ICJPlainObject {
[prop: string]: cjlib.VALUE;
}
cjConvertObject2TemplateResponse(o: ICJPlainObject, ignore?: string[]): cjlib.ITemplateResponse
Function creates 'ITemplateResponse' object populated from plain object.
Parameters
Name | Meaning |
---|---|
o | plain object |
ignore | array of names of columns to ignore |