@kronos-integration/service 10.4.55 → 10.4.57

package/README.md

@@ -1,5 +1,6 @@
 [![npm](https://img.shields.io/npm/v/@kronos-integration/service.svg)](https://www.npmjs.com/package/@kronos-integration/service)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Typed with TypeScript](https://flat.badgen.net/badge/icon/Typed?icon=typescript\&label\&labelColor=blue\&color=555555)](https://typescriptlang.org)
 [![bundlejs](https://deno.bundlejs.com/?q=@kronos-integration/service\&badge=detailed)](https://bundlejs.com/?q=@kronos-integration/service)
 [![downloads](http://img.shields.io/npm/dm/@kronos-integration/service.svg?style=flat-square)](https://npmjs.org/package/@kronos-integration/service)
 [![GitHub Issues](https://img.shields.io/github/issues/Kronos-Integration/service.svg?style=flat-square)](https://github.com/Kronos-Integration/service/issues)
@@ -46,6 +47,7 @@ Base service implementation
     *   [Parameters](#parameters-7)
 *   [Service](#service)
     *   [Parameters](#parameters-8)
+    *   [Properties](#properties-1)
     *   [extendetName](#extendetname)
     *   [stateChanged](#statechanged)
         *   [Parameters](#parameters-9)
@@ -82,9 +84,7 @@ Manages endpoints in a container.
 
 ### Parameters
 
-*   `superclass` **Class** class to be extended
-
-Returns **Class** extended class
+*   `superclass`  
 
 ## endpoints
 
@@ -97,8 +97,8 @@ Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/G
 **Extends Service**
 
 Config providing service.
-Dispatches config requests to services;
-or preserves them until a maching service becomes avaliable.
+Dispatches config requests to services.
+Also preserves them until a maching service becomes avaliable.
 
 ### Properties
 
@@ -111,7 +111,7 @@ Deliver configuration for a given service.
 #### Parameters
 
 *   `name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** service name
-*   `config` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+*   `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
 
 ### clearPreserved
 
@@ -200,8 +200,8 @@ By default a service provider has two build in services
 ### Parameters
 
 *   `superclass`  
-*   `serviceLoggerClass` **Class** where the logging houtd go (optional, default `ServiceLogger`)
-*   `serviceConfigClass` **Class** where the config comes from (optional, default `ServiceConfig`)
+*   `serviceLoggerClass`   (optional, default `ServiceLogger`)
+*   `serviceConfigClass`   (optional, default `ServiceConfig`)
 
 ## Service
 
@@ -243,6 +243,10 @@ All services have at least three endpoints:
     *   `config.endpoints` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** will be merged with the build in ones
 *   `ic` **InitializationContext** 
 
+### Properties
+
+*   `endpoints` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+
 ### extendetName
 
 Used in human readable state messages.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@kronos-integration/service",
-  "version": "10.4.55",
+  "version": "10.4.57",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "exports": {
-    ".": "./src/module.mjs"
+    ".": {
+      "default": "./src/module.mjs"
+    }
   },
   "description": "Base service implementation",
   "contributors": [
@@ -20,33 +23,37 @@
   ],
   "license": "BSD-2-Clause",
   "scripts": {
+    "prepare": "npm run prepare:typescript",
+    "prepare:typescript": "tsc --allowJs --declaration --emitDeclarationOnly --declarationDir types --resolveJsonModule -t esnext -m esnext --module nodenext --moduleResolution nodenext --rootDir src ./src**/*.mjs",
     "test": "npm run test:ava",
     "test:ava": "ava --timeout 4m tests/*-ava.mjs tests/*-ava-node.mjs",
     "cover": "c8 -x 'tests/**/*' --temp-directory build/tmp ava --timeout 4m tests/*-ava.mjs tests/*-ava-node.mjs && c8 report -r lcov -o build/coverage --temp-directory build/tmp",
     "docs": "documentation readme --section=API ./src/**/*.mjs",
-    "lint": "npm run lint:docs",
-    "lint:docs": "documentation lint ./src/**/*.mjs"
+    "lint": "npm run lint:docs && npm run lint:typescript",
+    "lint:docs": "documentation lint ./src/**/*.mjs",
+    "lint:typescript": "tsc --allowJs --checkJs --noEmit --resolveJsonModule -t esnext -m esnext --module nodenext --moduleResolution nodenext ./src**/*.mjs"
   },
   "dependencies": {
-    "@kronos-integration/endpoint": "^9.4.45",
-    "@kronos-integration/interceptor": "^10.2.37",
-    "loglevel-mixin": "^7.1.0",
+    "@kronos-integration/endpoint": "^9.5.4",
+    "@kronos-integration/interceptor": "^10.3.0",
+    "loglevel-mixin": "^7.2.2",
     "model-attributes": "^4.2.2",
-    "remove-sensible-values": "^1.2.3",
-    "statetransition-mixin": "^8.0.5"
+    "remove-sensible-values": "^1.3.1",
+    "statetransition-mixin": "^8.1.0"
   },
   "devDependencies": {
-    "ava": "^6.0.1",
-    "c8": "^9.0.0",
-    "documentation": "^14.0.2",
-    "semantic-release": "^22.0.12"
+    "ava": "^6.1.2",
+    "c8": "^9.1.0",
+    "documentation": "^14.0.3",
+    "semantic-release": "^23.0.8",
+    "typescript": "^5.4.5"
   },
   "engines": {
-    "node": ">=20.10.0"
+    "node": ">=20.12.2"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Kronos-Integration/service"
+    "url": "git+https://github.com/Kronos-Integration/service.git"
   },
   "bugs": {
     "url": "https://github.com/Kronos-Integration/service/issues"
@@ -55,7 +62,8 @@
   "template": {
     "inheritFrom": [
       "arlac77/template-arlac77-github",
-      "arlac77/template-kronos-component"
+      "arlac77/template-kronos-component",
+      "arlac77/template-typescript"
     ]
   }
 }

package/src/endpoints-mixin.mjs

@@ -1,4 +1,5 @@
 import {
+  Endpoint,
   SendEndpoint,
   SendEndpointDefault,
   SendReceiveEndpoint,
@@ -7,12 +8,13 @@ import {
   ReceiveEndpointDefault,
   ReceiveEndpointSelfConnectedDefault
 } from "@kronos-integration/endpoint";
+import { InitializationContext } from "./initialization-context.mjs";
 
 /**
  * Endpoint accessor mixin.
  * Manages endpoints in a container.
- * @param {Class} superclass class to be extended
- * @return {Class} extended class
+ * @param {new() => superclass} superclass class to be extended
+ * @return {new() => superclass} extended class
  */
 export function EndpointsMixin(superclass) {
   return class EndpointsMixin extends superclass {
@@ -41,6 +43,7 @@ export function EndpointsMixin(superclass) {
      * @param {string} name of the endpoint
      * @param {Object} definition endpoints definition
      * @param {string|Function} definition.receive name of method or property
+     * @param {Endpoint} definition.connected
      * @param {InitializationContext} ic
      * @return {Object} suitable to pass as options to the endpoint factory
      */
@@ -75,6 +78,8 @@ export function EndpointsMixin(superclass) {
      * @param {any} definition.receive defined will result in a ReceiveEndpoint
      * @param {boolean} definition.out true will result in a SendEndpoint
      * @param {boolean} definition.default true will result in a (Send|Receive)DefaultEndpoint
+     * @param {boolean} definition.multi true will result in a MultiSendEndpoint
+     * @param {Endpoint[]|string} definition.connected true will result in a MultiSendEndpoint
      * @param {InitializationContext} ic
      * @return {Object} endpoint factory
      */

package/src/initialization-context.mjs

@@ -21,9 +21,9 @@ export const InitializationContext = LogLevelMixin(
    */
   class InitializationContext {
 
-    outstandingServices = new Map();
-    outstandingFactories = new Map();
-    outstandingEndpointConnections = new Map();
+    /** @type {Map<string,Promise<Service>>} */ outstandingServices = new Map();
+    /** @type {Map<string,Promise<Function>>} */ outstandingFactories = new Map();
+    /** @type {Map<string,Promise<Endpoint>>} */ outstandingEndpointConnections = new Map();
 
     constructor(serviceProvider, options) {
       this.serviceProvider = serviceProvider;
@@ -32,7 +32,7 @@ export const InitializationContext = LogLevelMixin(
     /**
      * Forward to the serviceProvider.
      * @param {string} level the log level
-     * @param {Object} arg log content
+     * @param {Object} args log content
      */
     log(level, ...args) {
       if (this.serviceProvider) {
@@ -162,7 +162,7 @@ export const InitializationContext = LogLevelMixin(
 
     /**
      *
-     * @param {string|class} type name if type
+     * @param {string|(new() => type)} type name if type
      */
     async getServiceFactory(type) {
       const sp = this.serviceProvider;
@@ -230,7 +230,7 @@ export const InitializationContext = LogLevelMixin(
      * - otherwise declare this action as a new outstanding service declaration
      * @param {Object} config
      * @param {string} name service name
-     * @return {Service}
+     * @return {Promise<Service|undefined>}
      */
     async declareService(config, name) {      
       const sp = this.serviceProvider;

package/src/service-config.mjs

@@ -25,7 +25,7 @@ export class ServiceConfig extends Service {
   /**
    * Deliver configuration for a given service.
    * @param {string} name service name
-   * @param {object} config
+   * @param {Object} config
    */
   async configFor(name, config) {
     this.trace(`configFor ${name}`);

package/src/service-provider-mixin.mjs

@@ -9,8 +9,8 @@ import { InitializationContext } from "./initialization-context.mjs";
  * By default a service provider has two build in services
  * 'logger' and 'config'.
  *
- * @param {Class} serviceLoggerClass where the logging houtd go
- * @param {Class} serviceConfigClass where the config comes from
+ * @param {new(Object,InitializationContext) => serviceLoggerClass} serviceLoggerClass where the logging houtd go
+ * @param {new(Object,InitializationContext) => serviceConfigClass} serviceConfigClass where the config comes from
  */
 export function ServiceProviderMixin(
   superclass,
@@ -106,8 +106,8 @@ export function ServiceProviderMixin(
      * Registers a interceptor factory for later use by
      * @see {instantiateInterceptor}.
      *
-     * @param {Class} factory
-     * @returns {Class} factory
+     * @param {new() => factory} factory
+     * @returns {new() => factory} factory
      */
     registerInterceptorFactory(factory) {
       this.interceptorFactories[factory.name] = factory;
@@ -181,7 +181,7 @@ export function ServiceProviderMixin(
      * If a service for the name is already present and it has a matching type
      * then its configure() is called and returned.
      * Otherwise a new service will be created eventually replacing an already existing service with the same name.
-     * @param {object} config with
+     * @param {object} configs with
      *     name - the service name
      *     type - the service factory name - defaults to config.name
      * @return {Promise<Object>} resolving to the declared services

package/src/service.mjs

@@ -6,6 +6,7 @@ import {
   setAttributes
 } from "model-attributes";
 import { EndpointsMixin } from "./endpoints-mixin.mjs";
+import { InitializationContext } from "./initialization-context.mjs";
 
 const _ca = createAttributes({
   description: {
@@ -78,6 +79,8 @@ const ssfDefault = {
  * @param {string} config.description human readable description
  * @param {Object} config.endpoints will be merged with the build in ones
  * @param {InitializationContext} ic
+ * 
+ * @property {Object} endpoints
  */
 export class Service extends EndpointsMixin(
   StateTransitionMixin(

package/types/endpoints-mixin.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Endpoint accessor mixin.
+ * Manages endpoints in a container.
+ * @param {new() => superclass} superclass class to be extended
+ * @return {new() => superclass} extended class
+ */
+export function EndpointsMixin(superclass: new () => new () => any): new () => new () => any;

package/types/initialization-context.d.mts

@@ -0,0 +1,4 @@
+/**
+ * Keeps track of all in flight object creations and loose ends during config initialization.
+ */
+export const InitializationContext: any;

package/types/module.d.mts

@@ -0,0 +1,8 @@
+export * from "./service.mjs";
+export * from "./service-logger.mjs";
+export * from "./service-config.mjs";
+export * from "./service-provider-mixin.mjs";
+export * from "./endpoints-mixin.mjs";
+export * from "./standalone-service-provider.mjs";
+export * from "./service-consumer-mixin.mjs";
+export * from "./initialization-context.mjs";

package/types/service-config.d.mts

@@ -0,0 +1,40 @@
+/**
+ * Merge from b into a.
+ * When *a* and *b* are arrays of values only the none duplicates are appendend to *a*.
+ * @param {any} a
+ * @param {any} b
+ * @return {any} merged b into a
+ */
+export function merge(a: any, b: any): any;
+/**
+ * Config providing service.
+ * Dispatches config requests to services.
+ * Also preserves them until a maching service becomes avaliable.
+ * @property {Map<string,Object>} preservedConfigs values for services not already established
+ */
+export class ServiceConfig extends Service {
+    preservedConfigs: Map<any, any>;
+    /**
+     * Deliver configuration for a given service.
+     * @param {string} name service name
+     * @param {Object} config
+     */
+    configFor(name: string, config: any): Promise<any>;
+    /**
+     * Forget about preserved config of a service.
+     * @param {string} name service name
+     */
+    clearPreserved(name: string): void;
+    /**
+     * Set config entry.
+     * @param {string} key path to the value
+     * @param {any} value
+     */
+    configureValue(key: string, value: any): Promise<void>;
+    /**
+     *
+     * @param {Array|Object} config
+     */
+    configure(config: any[] | any): Promise<void>;
+}
+import { Service } from "./service.mjs";

package/types/service-consumer-mixin.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Assign services based on a configuration.
+ * @param {Object} target object
+ * @param {Object} config service defintion
+ * @param {Object} provider service provider
+ * @param {boolean} waitUntilFactoryPresent
+ */
+export function defineServiceConsumerProperties(target: any, config: any, provider: any, waitUntilFactoryPresent: boolean): Promise<any[]>;

package/types/service-logger.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Log receiving service.
+ */
+export class ServiceLogger extends Service {
+    logEntry(entry: any): Promise<void>;
+}
+import { Service } from './service.mjs';

package/types/service-provider-mixin.d.mts

@@ -0,0 +1,83 @@
+/**
+ * Provide services and hold service configuration.
+ * By default a service provider has two build in services
+ * 'logger' and 'config'.
+ *
+ * @param {new(Object,InitializationContext) => serviceLoggerClass} serviceLoggerClass where the logging houtd go
+ * @param {new(Object,InitializationContext) => serviceConfigClass} serviceConfigClass where the config comes from
+ */
+export function ServiceProviderMixin(superclass: any, serviceLoggerClass?: new (Object, InitializationContext) => new (Object: any, InitializationContext: any) => any, serviceConfigClass?: new (Object, InitializationContext) => new (Object: any, InitializationContext: any) => any): {
+    new (config: any, ic?: any): {
+        [x: string]: any;
+        listeners: {};
+        interceptorFactories: {};
+        serviceFactories: {};
+        services: {};
+        ic: any;
+        emit(name: any, ...args: any[]): void;
+        addListener(name: any, listener: any): void;
+        removeListener(name: any, listener: any): void;
+        /**
+         * By default be our own owner.
+         * @return this
+         */
+        readonly owner: any;
+        /**
+         * We are the service provider.
+         * @return {boolean} true
+         */
+        readonly isServiceProvider: boolean;
+        /**
+         * Register service or interceptor factories.
+         *
+         * @param {Function[]} factories
+         */
+        registerFactories(factories: Function[]): void;
+        /**
+         * Registers a interceptor factory for later use by
+         * @see {instantiateInterceptor}.
+         *
+         * @param {new() => factory} factory
+         * @returns {new() => factory} factory
+         */
+        registerInterceptorFactory(factory: new () => new () => any): new () => new () => any;
+        unregisterInterceptorFactory(factory: any): void;
+        /**
+         * Instanciates an interceptor from its definition data.
+         * @see {interceptorFactories}
+         * @param {Object} definition data
+         * @returns {Interceptor}
+         */
+        instantiateInterceptor(definition: any): Interceptor;
+        serviceStateChanged(service: any, oldState: any, newState: any): void;
+        registerServiceFactory(factory: any): Promise<any>;
+        unregisterServiceFactory(factory: any): Promise<void>;
+        registerService(service: any): Promise<any>;
+        unregisterService(serviceName: any): Promise<void>;
+        readonly serviceNames: string[];
+        getService(name: any): any;
+        declareService(config: any): Promise<any>;
+        /**
+         * Add a new service based on its configuration.
+         * If a service for the name is already present and it has a matching type
+         * then its configure() is called and returned.
+         * Otherwise a new service will be created eventually replacing an already existing service with the same name.
+         * @param {object} configs with
+         *     name - the service name
+         *     type - the service factory name - defaults to config.name
+         * @return {Promise<Object>} resolving to the declared services
+         */
+        declareServices(configs: object): Promise<any>;
+        /**
+         * Start all registered services which hanving autostart set.
+         */
+        _start(): Promise<any[]>;
+        /**
+         * Stop all services.
+         * @return {Promise} that resolves when all services are stopped
+         */
+        _stop(): Promise<any>;
+    };
+    [x: string]: any;
+};
+import { Interceptor } from "@kronos-integration/interceptor";

package/types/service.d.mts

@@ -0,0 +1,152 @@
+declare const Service_base: new () => new () => any;
+/**
+ * Service
+ * The initial state is 'stopped'.
+ * All services have at least three endpoints:
+ * - log _out_: log events
+ * - config _in_: configuration request
+ * - command _in_: administrative actions to be executed by the step
+ * @param {Object} config
+ * @param {string} config.name
+ * @param {string} config.logLevel
+ * @param {boolean} config.autostart defaults to false
+ * @param {string} config.description human readable description
+ * @param {Object} config.endpoints will be merged with the build in ones
+ * @param {InitializationContext} ic
+ *
+ * @property {Object} endpoints
+ */
+export class Service extends Service_base {
+    static get description(): string;
+    /**
+     * Meta information for the config attributes.
+     * - default optional default value of the attribute
+     * - needsRestart optional modification requires a service restart
+     * - setter(newValue,attribute) optional function to be used if simple value assignment is not enough
+     * The Service class only defines the logLevel, and start/stop/restart timeout attribute
+     * @return {Object}
+     */
+    static get configurationAttributes(): any;
+    /**
+     * Definition of the predefined endpoints.
+     * - log _out_
+     * - config _in_
+     * @return {Object} predefined endpoints
+     */
+    static get endpoints(): any;
+    constructor(config: any, ic: any);
+    owner: any;
+    logLevel: any;
+    instantiateInterceptor(options: any): any;
+    get configurationAttributes(): any;
+    get type(): string;
+    set description(desc: any);
+    get description(): any;
+    /**
+     * Used in human readable state messages.
+     * Besides the actual service name it may contain additional short hints.
+     * @return {string}
+     */
+    get extendetName(): string;
+    /**
+     * Called when the service state changes.
+     * Emits a serviceStateChanged event to the owner.
+     * @param {string} oldState
+     * @param {string} newState
+     */
+    stateChanged(origin: any, oldState: string, newState: string): void;
+    stateTransitionRejection(rejected: any, newState: any): any;
+    /**
+     * Called when state transition is not allowed.
+     * @param {string} action originating action name
+     * @throws always
+     */
+    rejectWrongState(action: string): Promise<void>;
+    /**
+     * Deliver transition timeout.
+     * @param {Object} transition
+     * @return {number} milliseconds before throwing for a long running transition
+     */
+    timeoutForTransition(transition: any): number;
+    /**
+     * Opens all endpoint connections.
+     */
+    _start(): Promise<void>;
+    /**
+     * Closes all endpoint connections.
+     */
+    _stop(): Promise<void>;
+    /**
+     * Restart action.
+     * default implementation does a _stop() and a _start()
+     * @return {Promise} fulfills after start
+     */
+    _restart(): Promise<any>;
+    /**
+     * Restarts if in running mode.
+     * Otherwise does nothing.
+     * @returns {Promise} resolves when restart is done (or immediate if no restart triggered)
+     */
+    restartIfRunning(): Promise<any>;
+    /**
+     * Mapping of properties used in toString.
+     * @return {Object}
+     */
+    get toStringAttributes(): any;
+    /**
+     * Base service is not a provider.
+     * @return {boolean} false
+     */
+    get isServiceProvider(): boolean;
+    toJSON(): any;
+    /**
+     * Deliver json representation.
+     * @param {Object} options
+     * @param {boolean} options.includeRuntimeInfo include runtime informtion like state
+     * @param {boolean} options.includeDefaults include default endpoints
+     * @param {boolean} options.includeName include name of the service
+     * @param {boolean} options.includeConfig include config attributes
+     * @param {boolean} options.includePrivate include private config attributes
+     * @return {Object} json representation
+     */
+    toJSONWithOptions(options: {
+        includeRuntimeInfo: boolean;
+        includeDefaults: boolean;
+        includeName: boolean;
+        includeConfig: boolean;
+        includePrivate: boolean;
+    }): any;
+    /**
+     * Should we start when beeing registered.
+     * @return {boolean} false
+     */
+    get autostart(): boolean;
+    /**
+     * Takes attribute values from config parameters
+     * and copies them over to the object.
+     * Copying is done according to configurationAttributes.
+     * Which means we loop over all configuration attributes.
+     * and then for each attribute decide if we use the default, call a setter function
+     * or simply assign the attribute value.
+     * @param {Object} config
+     * @return {Set} of modified attributes
+     */
+    _configure(config: any): Set<any>;
+    /**
+     * Use new configuration.
+     * Internally calls _configure(config) as the constructor does.
+     * If attribute with needsRestart are touched the restartIfRunning method
+     * will be called.
+     * @param {Object} config
+     * @return {Promise} fillfills when config is applied
+     */
+    configure(config: any): Promise<any>;
+    /**
+     * Adds service name to the log event.
+     * @param {string} level the log level
+     * @param {Object} arg log content
+     */
+    log(level: string, arg: any): void;
+    #private;
+}
+export {};

package/types/standalone-service-provider.d.mts

@@ -0,0 +1,38 @@
+declare const StandaloneServiceProvider_base: {
+    new (config: any, ic?: any): {
+        [x: string]: any;
+        listeners: {};
+        interceptorFactories: {};
+        serviceFactories: {};
+        services: {};
+        ic: any;
+        emit(name: any, ...args: any[]): void;
+        addListener(name: any, listener: any): void;
+        removeListener(name: any, listener: any): void;
+        readonly owner: any;
+        readonly isServiceProvider: boolean;
+        registerFactories(factories: Function[]): void;
+        registerInterceptorFactory(factory: new () => any): new () => new () => any;
+        unregisterInterceptorFactory(factory: any): void;
+        instantiateInterceptor(definition: any): import("@kronos-integration/interceptor").Interceptor;
+        serviceStateChanged(service: any, oldState: any, newState: any): void;
+        registerServiceFactory(factory: any): Promise<any>;
+        unregisterServiceFactory(factory: any): Promise<void>;
+        registerService(service: any): Promise<any>;
+        unregisterService(serviceName: any): Promise<void>;
+        readonly serviceNames: string[];
+        getService(name: any): any;
+        declareService(config: any): Promise<any>;
+        declareServices(configs: any): Promise<any>;
+        _start(): Promise<any[]>;
+        _stop(): Promise<any>;
+    };
+    [x: string]: any;
+};
+/**
+ * Simple service manager (for examples and testing only).
+ */
+export class StandaloneServiceProvider extends StandaloneServiceProvider_base {
+    static get description(): string;
+}
+export {};

package/types/util.d.mts

@@ -0,0 +1 @@
+export function keyValue2Object(key: any, value: any): {};