@openframe-org/criteria-set-protocol 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,53 @@
+<img alt="Frame ApS" src="https://openframe-public.s3.eu-west-1.amazonaws.com/assets/logo-text-google-admin.png" width="200" />
+
+# Criteria Set Protocol
+
+## TypeScript library
+This is a TypeScript library with types and implementations of the Criteria Set Protocol. It is published
+publicly on [npmjs](https://www.npmjs.com/package/@openframe-org/criteria-set-protocol) as `@openframe-org/criteria-set-protocol`.
+
+### Installation
+```bash
+npm install --save @openframe-org/criteria-set-protocol
+```
+
+### Contents
+The library contains a service to work with protocol versions, and an interface to interact with this service.
+
+#### Protocol v1
+The library contains the types defined in the protocol v1 specification, and a service that implements this specification.
+
+##### Types
+| Type                          | Remarks                                             |
+|-------------------------------|-----------------------------------------------------|
+| **Metadata types**            |                                                     |
+| `Metadata`                    |                                                     |
+| **Task tree types**           |                                                     |
+| `CriteriaTree`                |                                                     |
+| `Criterion`                   |                                                     |
+| `TaskGroup`                   |                                                     |
+| `Task`                        |                                                     |
+| `TaskItem`                    |                                                     |
+| **TaskItem value types**      |                                                     |
+| `SelectSingleType`            |                                                     |
+| `SelectMultipleType`          |                                                     |
+| `NumberType`                  |                                                     |
+| `BooleanType`                 |                                                     |
+| `PointOption`                 | Used by `SelectSingleType` and `SelectMultipleType` |
+| `TaskItemValue`               | The raw value of a TaskItem                         |
+| **Express types**             |                                                     |
+| `MetadataResponse`            | Metadata endpoint response body                     |
+| `StreamCriteriaSetMatrixBody` | Request body for the matrix streaming endpoints     |
+| `StreamMatrixResponse`        | Matrix streaming endpoints response body            |
+
+##### Schemas
+Validation schemas are provided for validating the endpoints of the protocol v1 specification.
+
+| Schema                     | Remarks                                                          |
+|----------------------------|------------------------------------------------------------------|
+| `criteriaSetIdParamSchema` | Validates the criteriaSetId parameter for endpoints which use it |
+| `versionParamSchema`       | Validates the version parameter for endpoints which use it       |
+| `downloadMatrixBody`       | Validates the request body for the download matrix endpoints     |
+
+##### Services
+The `IProtocolV1Service` interface defines a service which implements the v1 protocol. 

package/dist/services/i-versioned.service.d.ts

@@ -1,5 +1,16 @@
 import { ProtocolVersionServiceMap } from '../types';
+/**
+ * Interface for versioned services
+ *
+ * Services that implement this interface can be managed by the VersionsService
+ */
 export interface IVersionedService {
+    /**
+     * The SemVer version of the service
+     */
     version: string;
+    /**
+     * Whether the service supports the given protocol version
+     */
     supportsProtocol: <ProtocolVersion extends number>(protocolVersion: ProtocolVersion) => this is ProtocolVersionServiceMap<ProtocolVersion>;
 }

package/dist/services/versions.service.d.ts

@@ -1,10 +1,38 @@
 import { IVersionedService } from './i-versioned.service';
 import { ProtocolVersionServiceMap } from '../types';
+/**
+ * Service for managing versions of services
+ *
+ * The VersionsService class is a utility class for services which implement different versions of the protocol, and different versions of their
+ * own service. For example, say you have a v1service, v11service, v2service and v21service with versions 1.0, 1.1, 2.0 and 2.1 respectively.
+ * The VersionsService class can be used to manage these services:
+ *
+ * const versionsService = new VersionsService([v1service, v11service, v2service, v21service]);
+ * versionsService.getLatestVersion(); // v21service
+ * versionsService.getServiceVersions(1); // [v1service, v11service]
+ * versionsService.getServiceVersions(2); // [v2service, v21service]
+ * versionsService.get('1.1'); // v11service
+ */
 export declare class VersionsService {
     protected versions: IVersionedService[];
+    /**
+     * @param versions An array of services implementing IVersionedService
+     */
     constructor(versions: IVersionedService[]);
+    /**
+     * Get all services
+     */
     getAll(): IVersionedService[];
+    /**
+     * Retrieve the services which are compatible with the requested protocol version
+     */
     getServiceVersions<ProtocolVersion extends number, ProtocolImplementingService = ProtocolVersionServiceMap<ProtocolVersion>>(protocolVersion: ProtocolVersion): ProtocolImplementingService[];
+    /**
+     * Retrieve a service by version
+     */
     get(version: string): IVersionedService | undefined;
+    /**
+     * Retrieve the latest service
+     */
     getLatestVersion(): IVersionedService;
 }

package/dist/services/versions.service.js

@@ -1,19 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VersionsService = void 0;
+/**
+ * Service for managing versions of services
+ *
+ * The VersionsService class is a utility class for services which implement different versions of the protocol, and different versions of their
+ * own service. For example, say you have a v1service, v11service, v2service and v21service with versions 1.0, 1.1, 2.0 and 2.1 respectively.
+ * The VersionsService class can be used to manage these services:
+ *
+ * const versionsService = new VersionsService([v1service, v11service, v2service, v21service]);
+ * versionsService.getLatestVersion(); // v21service
+ * versionsService.getServiceVersions(1); // [v1service, v11service]
+ * versionsService.getServiceVersions(2); // [v2service, v21service]
+ * versionsService.get('1.1'); // v11service
+ */
 class VersionsService {
+    /**
+     * @param versions An array of services implementing IVersionedService
+     */
     constructor(versions) {
         this.versions = versions;
     }
+    /**
+     * Get all services
+     */
     getAll() {
         return this.versions;
     }
+    /**
+     * Retrieve the services which are compatible with the requested protocol version
+     */
     getServiceVersions(protocolVersion) {
         return this.versions.filter((service) => service.supportsProtocol(protocolVersion));
     }
+    /**
+     * Retrieve a service by version
+     */
     get(version) {
         return this.versions.find((service) => service.version === version);
     }
+    /**
+     * Retrieve the latest service
+     */
     getLatestVersion() {
         return this.versions[this.versions.length - 1];
     }

package/dist/v1/schemas/criteria-set-id-param-schema.d.ts

@@ -1,4 +1,7 @@
 import * as yup from 'yup';
+/**
+ * Validates the criteriaSetId parameter for endpoints which use it
+ */
 export declare const criteriaSetIdParamSchema: yup.ObjectSchema<{
     params: {
         criteriaSetId: string;

package/dist/v1/schemas/criteria-set-id-param-schema.js

@@ -25,6 +25,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.criteriaSetIdParamSchema = void 0;
 const yup = __importStar(require("yup"));
+/**
+ * Validates the criteriaSetId parameter for endpoints which use it
+ */
 exports.criteriaSetIdParamSchema = yup.object({
     params: yup.object({
         criteriaSetId: yup.string()

package/dist/v1/schemas/download-matrix-body-schema.d.ts

@@ -1,4 +1,7 @@
 import * as yup from 'yup';
+/**
+ * Validates the request body for the download matrix endpoints
+ */
 export declare const downloadMatrixBodySchema: yup.ObjectSchema<{
     body: {
         values: {};

package/dist/v1/schemas/download-matrix-body-schema.js

@@ -25,6 +25,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.downloadMatrixBodySchema = void 0;
 const yup = __importStar(require("yup"));
+/**
+ * Validates the request body for the download matrix endpoints
+ */
 exports.downloadMatrixBodySchema = yup.object({
     body: yup.object({
         parameters: yup.object().required(),

package/dist/v1/schemas/index.d.ts

@@ -1,3 +1,3 @@
 export * from './criteria-set-id-param-schema';
-export * from './download-matrix-body-schema';
+export * from './tree-and-matrix-body-schema';
 export * from './version-param-schema';

package/dist/v1/schemas/index.js

@@ -15,5 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./criteria-set-id-param-schema"), exports);
-__exportStar(require("./download-matrix-body-schema"), exports);
+__exportStar(require("./tree-and-matrix-body-schema"), exports);
 __exportStar(require("./version-param-schema"), exports);

package/dist/v1/schemas/tree-and-matrix-body-schema.d.ts

@@ -0,0 +1,17 @@
+import * as yup from 'yup';
+/**
+ * Validates the request body for the tree and matrix endpoints
+ */
+export declare const treeAndMatrixBodySchema: yup.ObjectSchema<{
+    body: {
+        locale?: string | undefined;
+        values: {};
+        parameters: {};
+    };
+}, yup.AnyObject, {
+    body: {
+        locale: undefined;
+        parameters: {};
+        values: {};
+    };
+}, "">;

package/dist/v1/schemas/tree-and-matrix-body-schema.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.treeAndMatrixBodySchema = void 0;
+const yup = __importStar(require("yup"));
+/**
+ * Validates the request body for the tree and matrix endpoints
+ */
+exports.treeAndMatrixBodySchema = yup.object({
+    body: yup.object({
+        locale: yup.string(),
+        parameters: yup.object().required(),
+        values: yup.object()
+    })
+});

package/dist/v1/schemas/version-param-schema.d.ts

@@ -1,4 +1,7 @@
 import * as yup from 'yup';
+/**
+ * Validates the version parameter for endpoints which use it
+ */
 export declare const versionParamSchema: yup.ObjectSchema<{
     params: {
         version: string;

package/dist/v1/schemas/version-param-schema.js

@@ -25,6 +25,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.versionParamSchema = void 0;
 const yup = __importStar(require("yup"));
+/**
+ * Validates the version parameter for endpoints which use it
+ */
 exports.versionParamSchema = yup.object({
     params: yup.object({
         version: yup.string()

package/dist/v1/services/i-protocol-v1.service.d.ts

@@ -1,9 +1,30 @@
 import { CriteriaTree, Metadata, StreamMatrixResponse, TaskItemValueMap } from '../types';
+/**
+ * Interface for services which implement the v1 protocol
+ */
 export interface IProtocolV1Service {
+    /**
+     * Specific version of this service, SemVer-formatted
+     */
     version: string;
+    /**
+     * Get the criteria tree for the given criteria set ID and combination of parameters
+     */
     getCriteriaTree(criteriaSetId: string, rawParameters: Record<string, unknown>): Promise<CriteriaTree>;
+    /**
+     * Validate the given parameters for the given criteria set ID
+     */
     validateParameters<RequestParameters>(criteriaSetId: string, parameters: RequestParameters): void;
+    /**
+     * Stream the matrix for the given criteria set ID, parameter combination and value map
+     */
     streamMatrix(criteriaSetId: string, rawParameters: Record<string, unknown>, values: TaskItemValueMap): Promise<StreamMatrixResponse>;
-    getMatrixMetadataList(): Metadata[];
+    /**
+     * Get the metadata of all criteria sets supported by this service
+     */
+    getCriteriaSetMetadataList(): Metadata[];
+    /**
+     * Get the JSON schema for the given criteria set ID
+     */
     getParametersJsonSchema(criteriaSetId: string): Record<string, unknown>;
 }

package/dist/v1/types/express.d.ts

@@ -1,14 +1,15 @@
 /// <reference types="node" />
 import { Stream } from 'stream';
 import { Metadata, TaskItemValue } from './criteria';
-export type MetadataSchema<Parameters extends ParameterCombination = ParameterCombination> = {
+export type MetadataResponse<Parameters extends ParameterCombination = ParameterCombination> = {
     protocol: 1;
     metadata: Metadata;
     parameters: Parameters;
 };
 export type StringParam<ParamName extends string> = Record<ParamName, string>;
 export type TaskItemValueMap = Record<string, TaskItemValue>;
-export type StreamCriteriaSetMatrixBody = {
+export type TreeAndMatrixRequestBody = {
+    locale?: string;
     parameters: ParameterCombination;
     values?: TaskItemValueMap;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openframe-org/criteria-set-protocol",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A protocol and tools for defining and working with criteria sets",
   "private": false,
   "author": "Andrés Angulo <aa@openframe.org>",