@syncbridge/common 2.0.0 → 2.0.1

package/README.md

@@ -1 +1,192 @@
-# SyncBridge Common Library
+# @syncbridge/common
+
+What a SyncBridge module is written against. A module is an npm package
+of **components** - clients, servers, connections - and **apps**, which
+SyncBridge runs as workers, each a Node.js process of its own, made of
+components. This package gives you the decorators that describe them, the
+base classes they extend, and their lifecycle.
+
+```sh
+npm i -D @syncbridge/common
+```
+
+SyncBridge provides `@syncbridge/common` to every module it runs, so a
+module declares it in `peerDependencies`, never in `dependencies`:
+
+```json
+"peerDependencies": { "@syncbridge/common": "^2.0.0" }
+```
+
+Start a module with `npx @syncbridge/syncbuild init @vendor/name`
+([`@syncbridge/syncbuild`](https://www.npmjs.com/package/@syncbridge/syncbuild)),
+and test it with
+[`@syncbridge/testing`](https://www.npmjs.com/package/@syncbridge/testing).
+
+## A component
+
+A component is a class that extends `ComponentBase`, decorated with
+`@Component`. Its settings - shown in SyncBridge's UI and kept in the
+worker's profile - are a variables class, given with `UseVariables`:
+
+```ts
+import {
+  Component,
+  ComponentBase,
+  DefineVariable,
+  VariableType,
+} from '@syncbridge/common';
+
+export class WeatherClientVariables {
+  @DefineVariable({ label: 'API address', required: true })
+  declare url: string;
+
+  @DefineVariable({ label: 'API key', type: VariableType.Secret })
+  declare apiKey?: string;
+
+  @DefineVariable({ label: 'Interval (s)', default: 60, minValue: 5 })
+  declare interval: number;
+}
+
+@Component({
+  displayName: 'Weather client',
+  description: 'Reads the weather from a web service',
+  tags: ['weather', 'http'],
+})
+export class WeatherClientComponent extends ComponentBase {
+  @Component.UseVariables()
+  declare values: WeatherClientVariables;
+
+  protected async _start(abortSignal?: AbortSignal): Promise<void> {
+    await super._start(abortSignal);
+    this.logger?.info(`Reading ${this.values.url}`);
+  }
+
+  protected async _stop(): Promise<void> {
+    /* Close what _start opened */
+    await super._stop();
+  }
+}
+```
+
+An element's URI is `<package>:<className>`. A component's class name is
+its class's without `Component` (`@acme/weather:WeatherClient`); an app's
+is its class's (`@acme/weather:WeatherStationApp`). Give `className` to
+choose another.
+
+## An app
+
+An app extends `AppBase`, decorated with `@App`. It names the components it
+uses with `UseComponent`, by URI. SyncBridge creates them with the values the
+worker's profile gives, and starts them before the app:
+
+```ts
+import { App, AppBase, DefineVariable } from '@syncbridge/common';
+import type { WeatherClientComponent } from './weather-client.component.js';
+
+export class WeatherStationVariables {
+  @DefineVariable({ label: 'Station name', default: 'Station 1' })
+  declare name: string;
+}
+
+@App({ displayName: 'Weather station' })
+export class WeatherStationApp extends AppBase {
+  @App.UseVariables()
+  declare values: WeatherStationVariables;
+
+  @App.UseComponent({
+    uri: '@acme/weather:WeatherClient',
+    required: true,
+  })
+  declare readonly weather: WeatherClientComponent;
+
+  protected async _start(abortSignal?: AbortSignal): Promise<void> {
+    await super._start(abortSignal);
+    this.logger?.info(`${this.values.name} started`);
+  }
+}
+```
+
+A component may use components too, with `Component.UseComponent`. A URI
+can name another module's component, for example
+`@syncbridge/net:TcpClient`. Declare that module as a peer as well.
+
+## Variables
+
+`@DefineVariable` describes a setting. Its type is read from the
+property's TypeScript type when not given. Some options:
+
+| Option | Meaning |
+| --- | --- |
+| `label`, `description` | How it is shown |
+| `type` | `VariableType`: `String`, `Secret` (a password or key, kept encrypted in the profile), `Number`, `BigInt`, `Boolean`, `Enum`, `Nested` |
+| `default`, `required` | Its default value, and whether it must be given |
+| `enumValues` | The values of an enum |
+| `enumSource` | Values SyncBridge fills in from the server it runs on: `EnumSource.SerialPorts`, `EnumSource.NetworkAddresses` |
+| `format`, `pattern` | A string's format (`url`, `email`, `date-time`...) or pattern |
+| `minValue`, `maxValue` | A number's range |
+| `isArray` | A list of values |
+| `hotPlug` | A change applies while running, without a restart |
+| `index` | Its order in the UI |
+
+## Lifecycle
+
+Apps and components are `Runnable`s. Override the protected methods, and
+always call `super`:
+
+- `_init()`: once, before the first start.
+- `_start(abortSignal)`: start working. The signal aborts when a stop comes
+  while starting.
+- `_stop()`: stop, and release what `_start` took. Close every timer,
+  socket and pool: what is left open is logged as a warning when the
+  worker ends.
+- `_restart()`: stop and start in place, for example when values change.
+
+`status` is a `ServiceStatus`: `stopped`, `starting`, `started`,
+`unhealthy`, `stopping`. Report trouble with
+`this.setStatus(ServiceStatus.unhealthy, message)`. An app's status
+follows its components'.
+
+## Logging
+
+`this.logger` writes the element's log. A log channel is a log of its own
+that the user can turn on, filter and keep apart, such as what a
+connection sends and receives:
+
+```ts
+import { LogChannel } from '@syncbridge/common';
+
+@LogChannel({ name: 'communication', title: 'Communication', kind: 'transmit' })
+declare readonly ioLog: LogChannel;
+
+// later
+this.ioLog.info('Sent', { bytes: 42 });
+```
+
+## Permissions
+
+SyncBridge runs each worker as a Linux user of its own, under Node's
+permission model. A component or app that needs more than its own data
+directory declares it:
+
+```ts
+@Component({
+  displayName: 'Serial client',
+  permissions: [WorkerPermission.SerialPorts, WorkerPermission.NativeCode],
+})
+```
+
+- `SerialPorts`: the serial devices.
+- `NativeCode`: native addons (`.node`), such as `serialport` or `oracledb`.
+- `ChildProcesses`: starting other programs.
+
+A subclass has its base's permissions. `spm verify` runs a module under
+the permission model and tells you what it failed to declare.
+
+## Examples
+
+The modules SyncBridge ships are open source:
+[syncbridge-io/public-modules](https://github.com/syncbridge-io/public-modules).
+
+## License
+
+[MIT](LICENSE)

package/app-factory.js

@@ -307,4 +307,3 @@ export var AppFactory;
         }
     }
 })(AppFactory || (AppFactory = {}));
-//# sourceMappingURL=app-factory.js.map

package/classes/app-base.js

@@ -8,4 +8,3 @@ export class AppBase extends BaseElement {
 }
 const APP_BASE_TOKEN = Symbol.for(AppBase.name);
 AppBase.prototype[APP_BASE_TOKEN] = true;
-//# sourceMappingURL=app-base.js.map

package/classes/base-element.js

@@ -90,4 +90,3 @@ export class BaseElement extends Runnable {
         super.onStatusChange();
     }
 }
-//# sourceMappingURL=base-element.js.map

package/classes/component-base.js

@@ -12,4 +12,3 @@ export class ComponentBase extends BaseElement {
 }
 const COMPONENT_BASE_TOKEN = Symbol.for(ComponentBase.name);
 ComponentBase.prototype[COMPONENT_BASE_TOKEN] = true;
-//# sourceMappingURL=component-base.js.map

package/classes/console-logger.js

@@ -35,4 +35,3 @@ export class ConsoleLogger {
         return undefined;
     }
 }
-//# sourceMappingURL=console-logger.js.map

package/classes/frame-stream.js

@@ -138,4 +138,3 @@ export class FrameStream extends Transform {
         this.push(combined);
     }
 }
-//# sourceMappingURL=frame-stream.js.map

package/classes/log-channel-writer.js

@@ -94,4 +94,3 @@ function eventOf(record) {
     if (record.direction === 'out')
         return 'write';
 }
-//# sourceMappingURL=log-channel-writer.js.map

package/classes/runnable.js

@@ -256,4 +256,3 @@ export class Runnable extends AsyncEventEmitter {
 }
 const RUNNABLE_TOKEN = Symbol.for(Runnable.name);
 Runnable.prototype[RUNNABLE_TOKEN] = true;
-//# sourceMappingURL=runnable.js.map

package/classes/sb-error.js

@@ -57,4 +57,3 @@ export class SbError extends Error {
  */
 export class SbValidationError extends SbError {
 }
-//# sourceMappingURL=sb-error.js.map

package/classes/stack-executor.js

@@ -53,4 +53,3 @@ export class StackExecutor {
         }
     }
 }
-//# sourceMappingURL=stack-executor.js.map

package/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const version = "2.0.0";
+export declare const version = "2.0.1";
 export declare const CLASS_METADATA: unique symbol;
 export declare const CLASS_TYPE: unique symbol;
 export declare const VARIABLE_CONTAINER: unique symbol;

package/constants.js

@@ -1,4 +1,4 @@
-export const version = '2.0.0';
+export const version = '2.0.1';
 export const CLASS_METADATA = Symbol.for('CLASS_METADATA');
 export const CLASS_TYPE = Symbol.for('CLASS_TYPE');
 export const VARIABLE_CONTAINER = Symbol.for('VARIABLE_CONTAINER');
@@ -8,4 +8,3 @@ export const NODE_ENV = process.env.NODE_ENV === 'test'
     : (process.env.NODE_ENV || '').startsWith('dev')
         ? 'dev'
         : 'prod';
-//# sourceMappingURL=constants.js.map

package/decorators/app-events.decorator.js

@@ -19,4 +19,3 @@ export function OnUpdateProfile() {
         });
     };
 }
-//# sourceMappingURL=app-events.decorator.js.map

package/decorators/app.decorator.js

@@ -92,4 +92,3 @@ export function App(options) {
     }
     App.OnUpdateProfile = OnUpdateProfile;
 })(App || (App = {}));
-//# sourceMappingURL=app.decorator.js.map

package/decorators/component.decorator.js

@@ -84,4 +84,3 @@ export function Component(options) {
     }
     Component.UseComponent = UseComponent;
 })(Component || (Component = {}));
-//# sourceMappingURL=component.decorator.js.map

package/decorators/decorator-helpers.js

@@ -22,4 +22,3 @@ export function defineOwnMetadata(target, metadataKey, overwrite) {
     Reflect.defineMetadata(metadataKey, metadata, target);
     return metadata;
 }
-//# sourceMappingURL=decorator-helpers.js.map

package/decorators/define-variable.decorator.js

@@ -65,4 +65,3 @@ export function DefineVariable(options = {}) {
         Reflect.defineMetadata(VARIABLE_CONTAINER, metadataRecord, target);
     };
 }
-//# sourceMappingURL=define-variable.decorator.js.map

package/decorators/log-channel.decorator.js

@@ -31,4 +31,3 @@ export function LogChannel(options = {}) {
         });
     };
 }
-//# sourceMappingURL=log-channel.decorator.js.map

package/decorators/use-component.decorator.js

@@ -26,4 +26,3 @@ export function UseComponent(options = {}) {
         };
     };
 }
-//# sourceMappingURL=use-component.decorator.js.map

package/decorators/use-variables.decorator.js

@@ -16,4 +16,3 @@ export function UseVariables(variablesClass) {
             Reflect.getMetadata(VARIABLE_CONTAINER, variablesClass.prototype) || {};
     };
 }
-//# sourceMappingURL=use-variables.decorator.js.map

package/host-link/host-identity.js

@@ -137,4 +137,3 @@ export function normalizePairingCode(input) {
             return;
     return `${code.slice(0, 4)}-${code.slice(4)}`;
 }
-//# sourceMappingURL=host-identity.js.map

package/host-link/host-link.js

@@ -51,4 +51,3 @@ export function summarizeWorkers(workers) {
 export const CONSOLE_USER_HEADER = 'x-sb-console-user';
 export const CONSOLE_USER_NAME_HEADER = 'x-sb-console-user-name';
 export const CONSOLE_ROLE_HEADER = 'x-sb-console-role';
-//# sourceMappingURL=host-link.js.map

package/host-link/host-packages.js

@@ -7,4 +7,3 @@
  */
 /** Where, under Console's API, a host's packages are planned */
 export const HOST_PACKAGES_PATH = 'host/packages';
-//# sourceMappingURL=host-packages.js.map

package/host-link/host-workers.js

@@ -26,4 +26,3 @@ export function mapProfileStrings(value, fn) {
 }
 /** Where, under Console's API, a host reinstalled takes its workers back */
 export const HOST_WORKERS_RESTORE_PATH = 'host/workers/restore';
-//# sourceMappingURL=host-workers.js.map

package/host-link/multiplexer.js

@@ -286,4 +286,3 @@ function parseJson(payload) {
         return undefined;
     }
 }
-//# sourceMappingURL=multiplexer.js.map

package/host-link/sealed-box.js

@@ -101,4 +101,3 @@ export function openSealed(privateKey, sealed) {
         decipher.final(),
     ]).toString('utf8');
 }
-//# sourceMappingURL=sealed-box.js.map

package/index.js

@@ -37,4 +37,3 @@ export * from './utils/registry-names.js';
 export * from './utils/type-guards.js';
 export * from './utils/uri-to-id.js';
 export * from './utils/worker-permissions.js';
-//# sourceMappingURL=index.js.map

package/interfaces/index.js

@@ -1,2 +1 @@
 export * from './logger.interface.js';
-//# sourceMappingURL=index.js.map

package/interfaces/logger.interface.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=logger.interface.js.map

package/models/enums/enum-source.enum.js

@@ -19,4 +19,3 @@ EnumType(EnumSource, {
         NetworkAddresses: "The server's IPv4 addresses, its loopback's apart",
     },
 });
-//# sourceMappingURL=enum-source.enum.js.map

package/models/enums/log-channel-kind.js

@@ -11,4 +11,3 @@ EnumType(LogChannelKind, {
     name: 'LogChannelKind',
     description: "How a log channel's records are shown",
 });
-//# sourceMappingURL=log-channel-kind.js.map

package/models/enums/log-level.js

@@ -15,4 +15,3 @@ EnumType(LogLevel, {
     name: 'LogLevel',
     description: 'Logging levels',
 });
-//# sourceMappingURL=log-level.js.map

package/models/enums/service-status.js

@@ -16,4 +16,3 @@ EnumType(ServiceStatus, {
     name: 'ServiceStatus',
     description: 'Status of any service',
 });
-//# sourceMappingURL=service-status.js.map

package/models/enums/variable-format.enum.js

@@ -13,4 +13,3 @@ EnumType(VariableFormat, {
     name: 'VariableFormat',
     description: 'Format of string variable',
 });
-//# sourceMappingURL=variable-format.enum.js.map

package/models/enums/variable-type.enum.js

@@ -13,4 +13,3 @@ EnumType(VariableType, {
     name: 'VariableType',
     description: 'Data type of the variable',
 });
-//# sourceMappingURL=variable-type.enum.js.map

package/models/enums/worker-permission.enum.js

@@ -25,4 +25,3 @@ EnumType(WorkerPermission, {
         ChildProcesses: "Starting other programs, outside Node's permission model too",
     },
 });
-//# sourceMappingURL=worker-permission.enum.js.map

package/models/index.js

@@ -15,4 +15,3 @@ export * from './metadata/variable-metadata.js';
 export * from './profile/log-options.js';
 export * from './profile/profile.js';
 export * from './profile/profile-component.js';
-//# sourceMappingURL=index.js.map

package/models/metadata/app-metadata.js

@@ -20,4 +20,3 @@ AppMetadata = __decorate([
     __metadata("design:paramtypes", [Object])
 ], AppMetadata);
 export { AppMetadata };
-//# sourceMappingURL=app-metadata.js.map

package/models/metadata/component-metadata.js

@@ -30,4 +30,3 @@ ComponentMetadata = __decorate([
     __metadata("design:paramtypes", [Object])
 ], ComponentMetadata);
 export { ComponentMetadata };
-//# sourceMappingURL=component-metadata.js.map

package/models/metadata/element-component-metadata.js

@@ -86,4 +86,3 @@ ElementComponentMetadata = __decorate([
     })
 ], ElementComponentMetadata);
 export { ElementComponentMetadata };
-//# sourceMappingURL=element-component-metadata.js.map

package/models/metadata/element-metadata.js

@@ -126,4 +126,3 @@ ElementMetadata = __decorate([
     __metadata("design:paramtypes", [Object])
 ], ElementMetadata);
 export { ElementMetadata };
-//# sourceMappingURL=element-metadata.js.map

package/models/metadata/log-channel-metadata.js

@@ -70,4 +70,3 @@ LogChannelMetadata = __decorate([
     __metadata("design:paramtypes", [Object])
 ], LogChannelMetadata);
 export { LogChannelMetadata };
-//# sourceMappingURL=log-channel-metadata.js.map

package/models/metadata/package-metadata.js

@@ -25,4 +25,3 @@ PackageMetadata = __decorate([
     __metadata("design:paramtypes", [Object])
 ], PackageMetadata);
 export { PackageMetadata };
-//# sourceMappingURL=package-metadata.js.map

package/models/metadata/plugin-metadata.js

@@ -63,4 +63,3 @@ PluginMetadata = __decorate([
     __metadata("design:paramtypes", [Object])
 ], PluginMetadata);
 export { PluginMetadata };
-//# sourceMappingURL=plugin-metadata.js.map

package/models/metadata/variable-metadata.js

@@ -174,4 +174,3 @@ VariableMetadata = __decorate([
     })
 ], VariableMetadata);
 export { VariableMetadata };
-//# sourceMappingURL=variable-metadata.js.map

package/models/profile/log-options.js

@@ -109,4 +109,3 @@ ProfileLogOptions = __decorate([
     __metadata("design:paramtypes", [Object])
 ], ProfileLogOptions);
 export { ProfileLogOptions };
-//# sourceMappingURL=log-options.js.map

package/models/profile/profile-component.js

@@ -82,4 +82,3 @@ ProfileComponent = __decorate([
     })
 ], ProfileComponent);
 export { ProfileComponent };
-//# sourceMappingURL=profile-component.js.map

package/models/profile/profile.js

@@ -120,4 +120,3 @@ Profile = __decorate([
     __metadata("design:paramtypes", [Object])
 ], Profile);
 export { Profile };
-//# sourceMappingURL=profile.js.map

package/models-document.js

@@ -17,4 +17,3 @@ export function getModelsDocument() {
         });
     return doc;
 }
-//# sourceMappingURL=models-document.js.map

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@syncbridge/common",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "SyncBridge Common utilities",
   "author": "Panates Inc",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/syncbridge-io/syncbridge.git",
+    "url": "git+https://github.com/syncbridge-io/node-sdk.git",
     "directory": "packages/common"
   },
   "dependencies": {
@@ -37,5 +37,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "homepage": "https://github.com/syncbridge-io/node-sdk/tree/main/packages/common#readme",
+  "bugs": {
+    "url": "https://github.com/syncbridge-io/node-sdk/issues"
   }
 }

package/registry/docs-sidebar.js

@@ -167,4 +167,3 @@ export function sidebarDocs(sidebar) {
     walk(sidebar.items);
     return out;
 }
-//# sourceMappingURL=docs-sidebar.js.map

package/registry/extension-package.js

@@ -144,4 +144,3 @@ export class PluginExtension {
         return ctor;
     }
 }
-//# sourceMappingURL=extension-package.js.map

package/registry/extension-registry.js

@@ -353,4 +353,3 @@ export class ExtensionRegistry extends AsyncEventEmitter {
         this.emitSafe('register-package', pkg);
     }
 }
-//# sourceMappingURL=extension-registry.js.map

package/registry/module-catalog.js

@@ -86,4 +86,3 @@ function extensionOf(file) {
     const dot = base.lastIndexOf('.');
     return dot > 0 ? base.slice(dot).toLowerCase() : '';
 }
-//# sourceMappingURL=module-catalog.js.map

package/registry/package-docs.js

@@ -157,4 +157,3 @@ export async function packageDigest(files) {
         .map(b => b.toString(16).padStart(2, '0'))
         .join('');
 }
-//# sourceMappingURL=package-docs.js.map

package/registry/package-manifest.js

@@ -57,4 +57,3 @@ export function readExtensionManifest(packageDir, pkgJson) {
 export function manifestOf(packageDir, pkgJson) {
     return readExtensionManifest(packageDir, pkgJson)?.manifest;
 }
-//# sourceMappingURL=package-manifest.js.map

package/utils/decode-profile.js

@@ -347,4 +347,3 @@ function _codecValues(stackExecutor, codec, variables, oldValues, options) {
     process(variables, values, oldValues);
     return values;
 }
-//# sourceMappingURL=decode-profile.js.map

package/utils/encrypt-helpers.js

@@ -48,4 +48,3 @@ function decryptText(input, secretKey) {
     ]);
     return decrypted.toString('utf8');
 }
-//# sourceMappingURL=encrypt-helpers.js.map

package/utils/locate-package-json.js

@@ -22,4 +22,3 @@ export function resolvePackageJson(directory) {
     const content = fs.readFileSync(path.resolve(pkg, 'package.json'), 'utf-8');
     return JSON.parse(content);
 }
-//# sourceMappingURL=locate-package-json.js.map

package/utils/materialize-metadata.js

@@ -146,4 +146,3 @@ function sortVariables(variables) {
         return a;
     }, {});
 }
-//# sourceMappingURL=materialize-metadata.js.map

package/utils/normalize-metadata.js

@@ -200,4 +200,3 @@ async function getProcMetadataTypeDecoder() {
     }
     return _procMetadataTypeDecoder;
 }
-//# sourceMappingURL=normalize-metadata.js.map

package/utils/registry-names.js

@@ -106,4 +106,3 @@ export function parseSbSpecifier(specifier) {
     assertRegistryName(m[1]);
     return { name: m[1], subpath: m[2] ? '.' + m[2] : '.' };
 }
-//# sourceMappingURL=registry-names.js.map

package/utils/resolve-promises.js

@@ -8,4 +8,3 @@ export async function resolvePromisesDeep(obj) {
     }
     return obj;
 }
-//# sourceMappingURL=resolve-promises.js.map

package/utils/type-guards.js

@@ -13,4 +13,3 @@ export function isAppBase(proto) {
 export function isComponentBase(proto) {
     return !!proto[COMPONENT_BASE_TOKEN];
 }
-//# sourceMappingURL=type-guards.js.map

package/utils/uri-to-id.js

@@ -5,4 +5,3 @@ export function uriToId(uri) {
         .replace(/\W/g, '_')
         .toLowerCase();
 }
-//# sourceMappingURL=uri-to-id.js.map

package/utils/worker-permissions.js

@@ -57,4 +57,3 @@ function realpathOf(p) {
         return p;
     }
 }
-//# sourceMappingURL=worker-permissions.js.map