@signalk/server-api 2.0.0-beta.3 → 2.1.0

package/.eslintrc.js

@@ -0,0 +1,25 @@
+// eslint-disable-next-line no-undef
+module.exports = {
+  root: true,
+  extends: ['eslint:recommended', 'prettier'],
+  parserOptions: {
+    ecmaVersion: 2019,
+    sourceType: 'module'
+  },
+  env: {
+    node: true,
+    es2019: true
+  },
+  overrides: [
+    {
+      files: ['**/*.ts'],
+      extends: [
+        'eslint:recommended',
+        'plugin:@typescript-eslint/recommended',
+        'prettier'
+      ],
+      parser: '@typescript-eslint/parser',
+      plugins: ['@typescript-eslint']
+    }
+  ]
+}

package/dist/{autopilot.d.ts → autopilotapi.d.ts}

@@ -1,13 +1,6 @@
 export interface AutopilotApi {
     register: (pluginId: string, provider: AutopilotProvider) => void;
     unRegister: (pluginId: string) => void;
-    getStates: () => Promise<[string]>;
-    setState: (state: string) => Promise<void>;
-    getModes: () => Promise<[string]>;
-    setMode: (mode: string) => Promise<void>;
-    setTarget: (value: number) => Promise<void>;
-    adjustTarget: (value: number) => Promise<void>;
-    tack: (port: boolean) => Promise<void>;
 }
 export interface AutopilotProvider {
     pilotType: string;
@@ -15,9 +8,13 @@ export interface AutopilotProvider {
 }
 export interface AutopilotProviderMethods {
     pluginId?: string;
-    getStates: () => Promise<[string]>;
+    engage: (enable: boolean) => Promise<void>;
+    getConfig: () => Promise<{
+        [key: string]: any;
+    }>;
+    getState: () => Promise<string>;
     setState: (state: string) => Promise<void>;
-    getModes: () => Promise<[string]>;
+    getMode: () => Promise<string>;
     setMode: (mode: string) => Promise<void>;
     setTarget: (value: number) => Promise<void>;
     adjustTarget: (value: number) => Promise<void>;

package/dist/deltas.d.ts

@@ -0,0 +1,73 @@
+import { Brand } from '.';
+export interface WithContext {
+    context: Context;
+}
+export interface NormalizedDelta extends WithContext {
+    $source: SourceRef;
+    source: Source;
+    path: Path;
+    value: Value;
+    isMeta: boolean;
+}
+export type SourceRef = Brand<string, 'sourceRef'>;
+export type Source = any;
+export type Path = Brand<string, 'path'>;
+export type Timestamp = Brand<string, 'timestamp'>;
+export type Context = Brand<string, 'context'>;
+export type Value = object | number | string | null | Notification;
+export interface DeltaSubscription {
+    context: Context;
+    subscribe: Array<{
+        path: Path;
+        period: number;
+        format: 'delta' | 'full';
+        policy: 'instant' | 'ideal' | 'fixed';
+        minPeriod: number;
+    }>;
+}
+export interface ValuesDelta {
+    context?: Context;
+    updates: Update[];
+}
+export interface MetaDelta {
+    metas: Array<{
+        values: Meta[];
+    }>;
+}
+export type Delta = ValuesDelta | MetaDelta;
+export interface Update {
+    timestamp?: Timestamp;
+    source?: Source;
+    $source?: SourceRef;
+    values: PathValue[];
+}
+export interface PathValue {
+    path: Path;
+    value: Value;
+}
+export interface Notification {
+    state: ALARM_STATE;
+    method: ALARM_METHOD[];
+    message: string;
+}
+export interface Meta {
+    path: string;
+    value: MetaValue;
+}
+export interface MetaValue {
+    description: string;
+    units?: string;
+    example?: string;
+}
+export declare enum ALARM_STATE {
+    nominal = "nominal",
+    normal = "normal",
+    alert = "alert",
+    warn = "warn",
+    alarm = "alarm",
+    emergency = "emergency"
+}
+export declare enum ALARM_METHOD {
+    visual = "visual",
+    sound = "sound"
+}

package/dist/deltas.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALARM_METHOD = exports.ALARM_STATE = void 0;
+// Notification attribute types
+var ALARM_STATE;
+(function (ALARM_STATE) {
+    ALARM_STATE["nominal"] = "nominal";
+    ALARM_STATE["normal"] = "normal";
+    ALARM_STATE["alert"] = "alert";
+    ALARM_STATE["warn"] = "warn";
+    ALARM_STATE["alarm"] = "alarm";
+    ALARM_STATE["emergency"] = "emergency";
+})(ALARM_STATE = exports.ALARM_STATE || (exports.ALARM_STATE = {}));
+var ALARM_METHOD;
+(function (ALARM_METHOD) {
+    ALARM_METHOD["visual"] = "visual";
+    ALARM_METHOD["sound"] = "sound";
+})(ALARM_METHOD = exports.ALARM_METHOD || (exports.ALARM_METHOD = {}));

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { IRouter } from 'express';
 import { PropertyValuesCallback } from './propertyvalues';
 export interface Position {
@@ -5,71 +6,27 @@ export interface Position {
     longitude: number;
     altitude?: number;
 }
-export { PropertyValue, PropertyValues, PropertyValuesCallback } from './propertyvalues';
-export * from './resourcetypes';
-export declare type SignalKResourceType = 'routes' | 'waypoints' | 'notes' | 'regions' | 'charts';
-export declare const SIGNALKRESOURCETYPES: SignalKResourceType[];
-export declare const isSignalKResourceType: (s: string) => boolean;
-export declare type ResourceType = SignalKResourceType | string;
-export interface ResourcesApi {
-    register: (pluginId: string, provider: ResourceProvider) => void;
-    unRegister: (pluginId: string) => void;
-    listResources: (resType: SignalKResourceType, params: {
-        [key: string]: any;
-    }, providerId?: string) => Promise<{
-        [id: string]: any;
-    }>;
-    getResource: (resType: SignalKResourceType, resId: string, providerId?: string) => Promise<object>;
-    setResource: (resType: SignalKResourceType, resId: string, data: {
-        [key: string]: any;
-    }, providerId?: string) => Promise<void>;
-    deleteResource: (resType: SignalKResourceType, resId: string, providerId?: string) => Promise<void>;
-}
-export interface ResourceProvider {
-    type: ResourceType;
-    methods: ResourceProviderMethods;
-}
-export interface ResourceProviderMethods {
-    listResources: (query: {
-        [key: string]: any;
-    }) => Promise<{
-        [id: string]: any;
-    }>;
-    getResource: (id: string, property?: string) => Promise<object>;
-    setResource: (id: string, value: {
-        [key: string]: any;
-    }) => Promise<void>;
-    deleteResource: (id: string) => Promise<void>;
-}
-export interface ResourceProviderRegistry {
-    registerResourceProvider: (provider: ResourceProvider) => void;
-}
-export interface AutopilotApi {
-    register: (pluginId: string, provider: AutopilotProvider) => void;
-    unRegister: (pluginId: string) => void;
-}
-export interface AutopilotProvider {
-    pilotType: string;
-    methods: AutopilotProviderMethods;
+export interface ActionResult {
+    state: 'COMPLETED' | 'PENDING' | 'FAILED';
+    statusCode: number;
+    message?: string;
+    resultStatus?: number;
 }
-export interface AutopilotProviderMethods {
-    pluginId?: string;
-    engage: (enable: boolean) => Promise<void>;
-    getConfig: () => Promise<{
-        [key: string]: any;
-    }>;
-    getState: () => Promise<string>;
-    setState: (state: string) => Promise<void>;
-    getMode: () => Promise<string>;
-    setMode: (mode: string) => Promise<void>;
-    setTarget: (value: number) => Promise<void>;
-    adjustTarget: (value: number) => Promise<void>;
-    tack: (port: boolean) => Promise<void>;
+export declare enum SKVersion {
+    v1 = "v1",
+    v2 = "v2"
 }
-export interface AutopilotProviderRegistry {
-    registerAutopilotProvider: (provider: AutopilotProvider) => void;
-}
-declare type Unsubscribe = () => {};
+export type Brand<K, T> = K & {
+    __brand: T;
+};
+export * from './deltas';
+export * from './resourcetypes';
+export * from './resourcesapi';
+export { ResourceProviderRegistry } from './resourcesapi';
+import { ResourceProviderRegistry } from './resourcesapi';
+export * from './autopilotapi';
+export { PropertyValue, PropertyValues, PropertyValuesCallback } from './propertyvalues';
+type Unsubscribe = () => void;
 export interface PropertyValuesEmitter {
     emitPropertyValue: (name: string, value: any) => void;
     onPropertyValues: (name: string, cb: PropertyValuesCallback) => Unsubscribe;
@@ -105,7 +62,7 @@ export interface Plugin {
      * in the admin UI
      * - when a plugin is Enabled in the admin UI
      */
-    start: (config: object, restart: (newConfiguration: object) => void) => any;
+    start: (config: object, restart: (newConfiguration: object) => void) => void;
     /**
      * Called to stop the plugin. Called when the user disables the plugin in the admin UI.
      */
@@ -115,4 +72,41 @@ export interface Plugin {
     registerWithRouter?: (router: IRouter) => void;
     signalKApiRoutes?: (router: IRouter) => IRouter;
     enabledByDefault?: boolean;
+    getOpenApi?: () => any;
+}
+export type DeltaInputHandler = (delta: object, next: (delta: object) => void) => void;
+export interface Ports {
+    byId: string[];
+    byPath: string[];
+    byOpenPlotter: string[];
+    serialports: any;
+}
+export interface Metadata {
+    units?: string;
+    description?: string;
+}
+export interface ServerAPI extends PluginServerApp {
+    getSelfPath: (path: string) => any;
+    getPath: (path: string) => any;
+    getMetadata: (path: string) => Metadata | undefined;
+    putSelfPath: (aPath: string, value: any, updateCb: () => void) => Promise<any>;
+    putPath: (aPath: string, value: number | string | object | boolean, updateCb: (err?: Error) => void, source: string) => Promise<any>;
+    queryRequest: (requestId: string) => Promise<any>;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+    registerDeltaInputHandler: (handler: DeltaInputHandler) => void;
+    setPluginStatus: (msg: string) => void;
+    setPluginError: (msg: string) => void;
+    handleMessage: (id: string, msg: any, skVersion?: SKVersion) => void;
+    savePluginOptions: (configuration: object, cb: (err: NodeJS.ErrnoException | null) => void) => void;
+    readPluginOptions: () => object;
+    getDataDirPath: () => string;
+    registerPutHandler: (context: string, path: string, callback: () => void, source: string) => void;
+    registerActionHandler: (context: string, path: string, callback: () => void, source: string) => void;
+    registerHistoryProvider: (provider: {
+        hasAnydata: (options: object, cb: (hasResults: boolean) => void) => void;
+        getHistory: (date: Date, path: string, cb: (deltas: object[]) => void) => void;
+        streamHistory: (spark: any, options: object, onDelta: (delta: object) => void) => void;
+    }) => void;
+    getSerialPorts: () => Promise<Ports>;
 }

package/dist/index.js

@@ -1,7 +1,11 @@
 "use strict";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[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];
@@ -10,16 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSignalKResourceType = exports.SIGNALKRESOURCETYPES = exports.PropertyValues = void 0;
+exports.PropertyValues = exports.SKVersion = void 0;
+var SKVersion;
+(function (SKVersion) {
+    SKVersion["v1"] = "v1";
+    SKVersion["v2"] = "v2";
+})(SKVersion = exports.SKVersion || (exports.SKVersion = {}));
+__exportStar(require("./deltas"), exports);
+__exportStar(require("./resourcetypes"), exports);
+__exportStar(require("./resourcesapi"), exports);
+__exportStar(require("./autopilotapi"), exports);
 var propertyvalues_1 = require("./propertyvalues");
 Object.defineProperty(exports, "PropertyValues", { enumerable: true, get: function () { return propertyvalues_1.PropertyValues; } });
-__exportStar(require("./resourcetypes"), exports);
-exports.SIGNALKRESOURCETYPES = [
-    'routes',
-    'waypoints',
-    'notes',
-    'regions',
-    'charts'
-];
-var isSignalKResourceType = function (s) { return exports.SIGNALKRESOURCETYPES.includes(s); };
-exports.isSignalKResourceType = isSignalKResourceType;

package/dist/propertyvalues.d.ts

@@ -4,7 +4,7 @@ export interface PropertyValue {
     name: string;
     value: any;
 }
-export declare type PropertyValuesCallback = (propValuesHistory: PropertyValue[]) => void;
+export type PropertyValuesCallback = (propValuesHistory: PropertyValue[]) => void;
 export declare class PropertyValues {
     private streams;
     private count;

package/dist/propertyvalues.js

@@ -15,7 +15,7 @@ var PropertyValues = /** @class */ (function () {
     };
     PropertyValues.prototype.emitPropertyValue = function (pv) {
         if (this.count >= PropertyValues.MAX_VALUES_COUNT) {
-            throw new Error("Max PropertyValues count " + PropertyValues.MAX_VALUES_COUNT + " exceeded trying to emit " + JSON.stringify(pv));
+            throw new Error("Max PropertyValues count ".concat(PropertyValues.MAX_VALUES_COUNT, " exceeded trying to emit ").concat(JSON.stringify(pv)));
         }
         this.getStreamTuple(pv.name).bus.push(pv);
     };
@@ -23,17 +23,18 @@ var PropertyValues = /** @class */ (function () {
         var _this = this;
         var streamTuple = this.streams[propName];
         if (!streamTuple) {
-            streamTuple = {
-                bus: new baconjs_1.default.Bus(),
-                stream: null
-            };
-            streamTuple.stream = streamTuple.bus
+            var bus = new baconjs_1.default.Bus();
+            var stream = bus
                 .scan([], function (acc, v) {
                 acc.push(v);
                 _this.count++;
                 return acc;
             })
                 .toProperty();
+            streamTuple = {
+                bus: bus,
+                stream: stream
+            };
             streamTuple.stream.subscribe(function () { return ({}); }); // start the stream eagerly
             streamTuple.bus.push(undefined);
             this.streams[propName] = streamTuple;

package/dist/propertyvalues.test.js

@@ -1,8 +1,12 @@
 "use strict";
-var __spreadArray = (this && this.__spreadArray) || function (to, from) {
-    for (var i = 0, il = from.length, j = to.length; i < il; i++, j++)
-        to[j] = from[i];
-    return to;
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var chai_1 = require("chai");
@@ -19,9 +23,9 @@ var setupTest = function (done, startAt) {
     var pv = new propertyvalues_1.PropertyValues();
     var cbCount = 0;
     var cb = function (values) {
-        chai_1.expect(values).to.deep.equal(__spreadArray([
+        (0, chai_1.expect)(values).to.deep.equal(__spreadArray([
             undefined
-        ], testValues.slice(0, startAt + cbCount++)));
+        ], testValues.slice(0, startAt + cbCount++), true));
         if (cbCount === testValues.length) {
             done();
         }
@@ -46,11 +50,12 @@ describe('PropertyValues', function () {
         for (var i = 1; i < propertyvalues_1.PropertyValues.MAX_VALUES_COUNT; i++) {
             pv.emitPropertyValue(newPropertyValue(i));
         }
-        chai_1.expect(function () {
+        (0, chai_1.expect)(function () {
             return pv.emitPropertyValue(newPropertyValue(propertyvalues_1.PropertyValues.MAX_VALUES_COUNT));
         }).to.throw();
     });
 });
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 var newPropertyValue = function (value) { return ({
     timestamp: Date.now(),
     setter: 'foobar',

package/dist/resourcesapi.d.ts

@@ -0,0 +1,37 @@
+export type SignalKResourceType = 'routes' | 'waypoints' | 'notes' | 'regions' | 'charts';
+export declare const SIGNALKRESOURCETYPES: SignalKResourceType[];
+export declare const isSignalKResourceType: (s: string) => boolean;
+export type ResourceType = SignalKResourceType | string;
+export interface ResourcesApi {
+    register: (pluginId: string, provider: ResourceProvider) => void;
+    unRegister: (pluginId: string) => void;
+    listResources: (resType: SignalKResourceType, params: {
+        [key: string]: any;
+    }, providerId?: string) => Promise<{
+        [id: string]: any;
+    }>;
+    getResource: (resType: SignalKResourceType, resId: string, providerId?: string) => Promise<object>;
+    setResource: (resType: SignalKResourceType, resId: string, data: {
+        [key: string]: any;
+    }, providerId?: string) => Promise<void>;
+    deleteResource: (resType: SignalKResourceType, resId: string, providerId?: string) => Promise<void>;
+}
+export interface ResourceProvider {
+    type: ResourceType;
+    methods: ResourceProviderMethods;
+}
+export interface ResourceProviderMethods {
+    listResources: (query: {
+        [key: string]: any;
+    }) => Promise<{
+        [id: string]: any;
+    }>;
+    getResource: (id: string, property?: string) => Promise<object>;
+    setResource: (id: string, value: {
+        [key: string]: any;
+    }) => Promise<void>;
+    deleteResource: (id: string) => Promise<void>;
+}
+export interface ResourceProviderRegistry {
+    registerResourceProvider: (provider: ResourceProvider) => void;
+}

package/dist/resourcesapi.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSignalKResourceType = exports.SIGNALKRESOURCETYPES = void 0;
+exports.SIGNALKRESOURCETYPES = [
+    'routes',
+    'waypoints',
+    'notes',
+    'regions',
+    'charts'
+];
+var isSignalKResourceType = function (s) {
+    return exports.SIGNALKRESOURCETYPES.includes(s);
+};
+exports.isSignalKResourceType = isSignalKResourceType;

package/dist/resourcetypes.d.ts

@@ -55,10 +55,10 @@ export interface Chart {
     bounds?: [[number, number], [number, number]];
     chartFormat: string;
 }
-export declare type GeoJsonPoint = [number, number, number?];
-export declare type GeoJsonLinestring = GeoJsonPoint[];
-export declare type GeoJsonPolygon = GeoJsonLinestring[];
-export declare type GeoJsonMultiPolygon = GeoJsonPolygon[];
+export type GeoJsonPoint = [number, number, number?];
+export type GeoJsonLinestring = GeoJsonPoint[];
+export type GeoJsonPolygon = GeoJsonLinestring[];
+export type GeoJsonMultiPolygon = GeoJsonPolygon[];
 interface Polygon {
     type: 'Feature';
     geometry: {

package/dist/types.js

@@ -1,2 +1,3 @@
 "use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalk/server-api",
-  "version": "2.0.0-beta.3",
+  "version": "2.1.0",
   "description": "signalk-server Typescript API for plugins etc with relevant implementation classes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,11 @@
     "watch": "tsc --declaration --watch",
     "prepublishOnly": "npm run build",
     "typedoc": "typedoc --out docs src",
-    "test": "mocha --require ts-node/register src/**/*.test.ts"
+    "prettier": "prettier -w src/",
+    "lint": "eslint -c .eslintrc.js --ext .ts --ext .js --fix src/",
+    "format": "npm run prettier && npm run lint",
+    "ci-lint": "eslint -c .eslintrc.js --ext .ts --ext .js src/ && prettier --check src/",
+    "test": "mocha --require ts-node/register src/**/*.test.ts && npm run ci-lint"
   },
   "repository": {
     "type": "git",
@@ -18,14 +22,19 @@
   "author": "teppo.kurki@iki.fi",
   "license": "Apache-2.0",
   "devDependencies": {
-    "express": "^4.10.4",
     "@types/chai": "^4.2.15",
     "@types/express": "^4.17.1",
-    "@types/mocha": "^8.2.0",
+    "@types/mocha": "^10.0.1",
+    "@typescript-eslint/eslint-plugin": "^5.52.0",
+    "@typescript-eslint/parser": "^5.52.0",
     "chai": "^4.3.0",
-    "mocha": "^8.3.0",
-    "ts-node": "^9.1.1",
-    "typedoc": "^0.20.28",
+    "eslint": "^8.34.0",
+    "eslint-config-prettier": "^8.6.0",
+    "express": "^4.10.4",
+    "mocha": "^10.2.0",
+    "prettier": "^2.8.4",
+    "ts-node": "^10.9.1",
+    "typedoc": "^0.23.23",
     "typescript": "^4.1.5"
   },
   "peerDependencies": {