@syncbridge/common 1.1.4 → 2.0.1

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": "1.1.4",
+  "version": "2.0.1",
   "description": "SyncBridge Common utilities",
   "author": "Panates Inc",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/panates/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.d.ts

@@ -0,0 +1,59 @@
+/**
+ * How a package's documents are listed, where its author tells it: a
+ * sidebar.json in docs/ (the package's own) or in docs/<ClassName>/ (an
+ * app's, component's or plugin's). Without one they are listed by their
+ * front matter's order and titles.
+ *
+ *   {
+ *     "items": [
+ *       "README.md",
+ *       { "doc": "user-guide.pdf",
+ *         "title": { "tr": "Kullanım kılavuzu", "en": "User guide" } },
+ *       { "label": { "tr": "Ağ", "en": "Network" },
+ *         "items": ["network.md", "firewall.md"] }
+ *     ]
+ *   }
+ *
+ * A document is named as it is in the package's own language, from where
+ * the sidebar is - its languages are found by its name (network.md for
+ * network.tr.md). A title is text, or text by language. A document not
+ * listed is read by a link to it alone.
+ */
+export declare const SIDEBAR_FILE = "sidebar.json";
+/** Text, or text by language: { "tr": "Ağ", "en": "Network" } */
+export type SidebarText = string | Record<string, string>;
+/** An item of a sidebar, as its author writes it */
+export type SidebarItemSource = string | {
+    doc: string;
+    title?: SidebarText;
+} | {
+    label: SidebarText;
+    items: SidebarItemSource[];
+};
+/** An item of a sidebar as kept: each document by its path in the package */
+export type SidebarItem = {
+    doc: string;
+    title?: SidebarText;
+} | {
+    label: SidebarText;
+    items: SidebarItem[];
+};
+/** A sidebar as kept: its items, each document by its path in the package */
+export interface DocsSidebar {
+    items: SidebarItem[];
+}
+/**
+ * Whose a sidebar is, by its path in the package: '' for docs/sidebar.json
+ * (the package's own), the class for docs/<ClassName>/sidebar.json; none
+ * if it is not where a sidebar may be
+ */
+export declare function sidebarOwner(file: string): string | undefined;
+/**
+ * Reads a sidebar: what its author wrote, each document found among `docs`
+ * - the paths, in the package's own language, the package's documents are
+ * read by (docs/Gw/network.md, for network.md and network.tr.md alike).
+ * Throws, telling every problem, when it is not one.
+ */
+export declare function parseSidebar(file: string, source: unknown, docs: ReadonlySet<string>): DocsSidebar;
+/** The documents a sidebar lists, by their paths */
+export declare function sidebarDocs(sidebar: DocsSidebar): string[];

package/registry/docs-sidebar.js

@@ -0,0 +1,169 @@
+import { SbError } from '../classes/sb-error.js';
+import { CLASS_DIR_PATTERN, DOCS_DIR, isDocsLanguage } from './package-docs.js';
+/**
+ * How a package's documents are listed, where its author tells it: a
+ * sidebar.json in docs/ (the package's own) or in docs/<ClassName>/ (an
+ * app's, component's or plugin's). Without one they are listed by their
+ * front matter's order and titles.
+ *
+ *   {
+ *     "items": [
+ *       "README.md",
+ *       { "doc": "user-guide.pdf",
+ *         "title": { "tr": "Kullanım kılavuzu", "en": "User guide" } },
+ *       { "label": { "tr": "Ağ", "en": "Network" },
+ *         "items": ["network.md", "firewall.md"] }
+ *     ]
+ *   }
+ *
+ * A document is named as it is in the package's own language, from where
+ * the sidebar is - its languages are found by its name (network.md for
+ * network.tr.md). A title is text, or text by language. A document not
+ * listed is read by a link to it alone.
+ */
+export const SIDEBAR_FILE = 'sidebar.json';
+/** Categories within categories, at most */
+const MAX_DEPTH = 3;
+/**
+ * Whose a sidebar is, by its path in the package: '' for docs/sidebar.json
+ * (the package's own), the class for docs/<ClassName>/sidebar.json; none
+ * if it is not where a sidebar may be
+ */
+export function sidebarOwner(file) {
+    const parts = file.split('/');
+    if (parts[0] !== DOCS_DIR || parts[parts.length - 1] !== SIDEBAR_FILE)
+        return;
+    if (parts.length === 2)
+        return '';
+    if (parts.length === 3 && CLASS_DIR_PATTERN.test(parts[1]))
+        return parts[1];
+}
+/**
+ * Reads a sidebar: what its author wrote, each document found among `docs`
+ * - the paths, in the package's own language, the package's documents are
+ * read by (docs/Gw/network.md, for network.md and network.tr.md alike).
+ * Throws, telling every problem, when it is not one.
+ */
+export function parseSidebar(file, source, docs) {
+    const owner = sidebarOwner(file);
+    if (owner === undefined)
+        throw new SbError(`${file}: a sidebar is ${DOCS_DIR}/${SIDEBAR_FILE} or ${DOCS_DIR}/<ClassName>/${SIDEBAR_FILE}`);
+    const dir = owner ? `${DOCS_DIR}/${owner}` : DOCS_DIR;
+    const errors = [];
+    const listed = new Set();
+    const text = (value, at) => {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const entries = Object.entries(value);
+            const bad = entries.filter(([lang, t]) => !isDocsLanguage(lang) || typeof t !== 'string' || !t.trim());
+            if (entries.length && !bad.length)
+                return Object.fromEntries(entries.map(([l, t]) => [l, t.trim()]));
+        }
+        errors.push(`${at}: text, or text by language ({ "tr": "...", "en": "..." })`);
+    };
+    const doc = (name, at) => {
+        if (typeof name !== 'string' || !name) {
+            errors.push(`${at}: a document's name, from where the sidebar is`);
+            return;
+        }
+        const parts = dir.split('/');
+        for (const part of name.split('/')) {
+            if (part === '..')
+                parts.pop();
+            else if (part && part !== '.')
+                parts.push(part);
+        }
+        const path = parts.join('/');
+        if (!path.startsWith(dir + '/') || (!owner && isModuleDoc(path))) {
+            errors.push(`${at}: "${name}" is not ${owner ? `${owner}'s` : "the package's own"} - a sidebar lists the documents beside it`);
+            return;
+        }
+        if (!docs.has(path)) {
+            errors.push(`${at}: "${name}" is not a document of the package - named as in its own language, without one (network.md, not network.tr.md)`);
+            return;
+        }
+        if (listed.has(path)) {
+            errors.push(`${at}: "${name}" is listed twice`);
+            return;
+        }
+        listed.add(path);
+        return path;
+    };
+    const items = (value, at, depth) => {
+        if (!Array.isArray(value)) {
+            errors.push(`${at}: a list of items`);
+            return [];
+        }
+        const out = [];
+        value.forEach((item, i) => {
+            const here = `${at}[${i}]`;
+            if (typeof item === 'string') {
+                const path = doc(item, here);
+                if (path)
+                    out.push({ doc: path });
+                return;
+            }
+            if (!item || typeof item !== 'object' || Array.isArray(item)) {
+                errors.push(`${here}: a document's name, or an object`);
+                return;
+            }
+            const keys = Object.keys(item);
+            if ('doc' in item) {
+                const unknown = keys.filter(k => k !== 'doc' && k !== 'title');
+                if (unknown.length)
+                    errors.push(`${here}: "${unknown.join('", "')}" is not read`);
+                const path = doc(item.doc, `${here}.doc`);
+                const title = item.title === undefined
+                    ? undefined
+                    : text(item.title, `${here}.title`);
+                if (path)
+                    out.push(title ? { doc: path, title } : { doc: path });
+            }
+            else if ('label' in item) {
+                const unknown = keys.filter(k => k !== 'label' && k !== 'items');
+                if (unknown.length)
+                    errors.push(`${here}: "${unknown.join('", "')}" is not read`);
+                if (depth >= MAX_DEPTH)
+                    errors.push(`${here}: categories go ${MAX_DEPTH} deep at most`);
+                const label = text(item.label, `${here}.label`);
+                const inner = items(item.items, `${here}.items`, depth + 1);
+                if (label)
+                    out.push({ label, items: inner });
+            }
+            else
+                errors.push(`${here}: a document ("doc") or a category ("label" and "items")`);
+        });
+        return out;
+    };
+    let result = [];
+    if (!source || typeof source !== 'object' || Array.isArray(source))
+        errors.push(`${file}: an object, its "items" listed`);
+    else {
+        const unknown = Object.keys(source).filter(k => k !== 'items');
+        if (unknown.length)
+            errors.push(`${file}: "${unknown.join('", "')}" is not read`);
+        result = items(source.items, `${file}: items`, 0);
+    }
+    if (errors.length)
+        throw new SbError(errors.join('\n'));
+    return { items: result };
+}
+/** A path in docs/ that is a module's: in docs/<ClassName>/ */
+function isModuleDoc(path) {
+    const parts = path.split('/');
+    return parts.length > 2 && CLASS_DIR_PATTERN.test(parts[1]);
+}
+/** The documents a sidebar lists, by their paths */
+export function sidebarDocs(sidebar) {
+    const out = [];
+    const walk = (items) => {
+        for (const item of items)
+            if ('doc' in item)
+                out.push(item.doc);
+            else
+                walk(item.items);
+    };
+    walk(sidebar.items);
+    return out;
+}

package/registry/extension-package.d.ts

@@ -1,10 +1,10 @@
 import 'reflect-metadata';
 import type { Type } from 'ts-gems';
+import { AppBase } from '../classes/app-base.js';
 import { BaseElement } from '../classes/base-element.js';
 import { ComponentBase } from '../classes/component-base.js';
-import { ProcessorBase } from '../classes/processor-base.js';
-import { ComponentMetadata, ElementMetadata, ProcessorMetadata } from '../models/index.js';
-import type { ExtensionPackageJson } from './package-manifest.js';
+import { AppMetadata, ComponentMetadata, ElementMetadata, PluginMetadata } from '../models/index.js';
+import type { ExtensionPackageJson, SyncBridgeManifest } from './package-manifest.js';
 /**
  *
  */
@@ -19,23 +19,32 @@ export declare class ExtensionPackage {
     /** What the package expects the host to provide */
     peerDependencies: Record<string, string>;
     components: ComponentExtension[];
-    processors: ProcessorExtension[];
+    apps: AppExtension[];
+    plugins: PluginExtension[];
     errors: Error[];
+    /** What was passed over reading the package: fields of its manifest SyncBridge does not know */
+    warnings: string[];
     /**
-     * Takes the package's identity and dependencies from its `package.json`.
+     * Takes the package's identity and dependencies from its `package.json`
+     * and its manifest (see readExtensionManifest)
      */
-    assignManifest(pkgJson: ExtensionPackageJson): void;
+    assignManifest(pkgJson: ExtensionPackageJson, manifest?: SyncBridgeManifest): void;
 }
 /**
  *
  */
 export declare abstract class ExtensionBase {
-    abstract readonly kind: 'component' | 'processor';
+    abstract readonly kind: 'component' | 'app';
     protected _ctor?: Type;
     readonly pkg: ExtensionPackage;
     readonly exportName: string;
     readonly metadata: ElementMetadata;
     readonly className: string;
+    /**
+     * The module the class is exported from: its own, given in the manifest,
+     * or else the package's entry point
+     */
+    entryPoint?: string;
     protected constructor(pkg: ExtensionPackage, exportName: string, metadata: ElementMetadata, ctor?: Type<BaseElement>);
     get uri(): string;
     get displayName(): string;
@@ -54,10 +63,28 @@ export declare class ComponentExtension extends ExtensionBase {
 /**
  *
  */
-export declare class ProcessorExtension extends ExtensionBase {
-    readonly kind = "processor";
-    protected _ctor?: Type<ProcessorBase>;
-    readonly metadata: ProcessorMetadata;
-    constructor(pkg: ExtensionPackage, exportName: string, metadata: ProcessorMetadata, ctor?: Type<ProcessorBase>);
-    getClass(): Promise<Type<ProcessorBase>>;
+export declare class AppExtension extends ExtensionBase {
+    readonly kind = "app";
+    protected _ctor?: Type<AppBase>;
+    readonly metadata: AppMetadata;
+    constructor(pkg: ExtensionPackage, exportName: string, metadata: AppMetadata, ctor?: Type<AppBase>);
+    getClass(): Promise<Type<AppBase>>;
+}
+/**
+ * A plugin a package brings: it extends SyncBridge itself, loaded in the
+ * engine's main process, never in a worker
+ */
+export declare class PluginExtension {
+    readonly pkg: ExtensionPackage;
+    readonly exportName: string;
+    readonly metadata: PluginMetadata;
+    readonly kind = "plugin";
+    protected _ctor?: Type;
+    /** The module the class is exported from */
+    entryPoint?: string;
+    constructor(pkg: ExtensionPackage, exportName: string, metadata: PluginMetadata, ctor?: Type);
+    /** The name it is set by: `plugins.<name>` */
+    get name(): string;
+    get version(): string;
+    getClass(): Promise<Type>;
 }

package/registry/extension-package.js

@@ -1,10 +1,11 @@
 import 'reflect-metadata';
+import { AppBase } from '../classes/app-base.js';
 import { BaseElement } from '../classes/base-element.js';
 import { ComponentBase } from '../classes/component-base.js';
-import { ProcessorBase } from '../classes/processor-base.js';
 import { SbError } from '../classes/sb-error.js';
-import { ComponentMetadata, ElementMetadata, ProcessorMetadata, } from '../models/index.js';
-import { isComponentBase, isProcessorBase } from '../utils/type-guards.js';
+import { CLASS_TYPE } from '../constants.js';
+import { AppMetadata, ComponentMetadata, ElementMetadata, PluginMetadata, } from '../models/index.js';
+import { isAppBase, isComponentBase } from '../utils/type-guards.js';
 /**
  *
  */
@@ -14,16 +15,20 @@ export class ExtensionPackage {
     /** What the package expects the host to provide */
     peerDependencies = {};
     components = [];
-    processors = [];
+    apps = [];
+    plugins = [];
     errors = [];
+    /** What was passed over reading the package: fields of its manifest SyncBridge does not know */
+    warnings = [];
     /**
-     * Takes the package's identity and dependencies from its `package.json`.
+     * Takes the package's identity and dependencies from its `package.json`
+     * and its manifest (see readExtensionManifest)
      */
-    assignManifest(pkgJson) {
-        this.name = pkgJson.syncbridge?.name || pkgJson.name;
+    assignManifest(pkgJson, manifest) {
+        this.name = manifest?.name || pkgJson.name;
         this.version = pkgJson.version;
         this.description = pkgJson.description;
-        this.registryDependencies = { ...pkgJson.syncbridge?.dependencies };
+        this.registryDependencies = { ...manifest?.dependencies };
         this.peerDependencies = { ...pkgJson.peerDependencies };
     }
 }
@@ -66,7 +71,7 @@ export class ComponentExtension extends ExtensionBase {
     async getClass() {
         if (this._ctor)
             return this._ctor;
-        const module = await import(this.pkg.entryPoint);
+        const module = await import(this.entryPoint || this.pkg.entryPoint);
         const ctor = module[this.exportName];
         if (!ctor)
             throw new SbError(`Exported component "${this.exportName}" not found in package "${this.pkg.name}"`);
@@ -81,26 +86,61 @@ export class ComponentExtension extends ExtensionBase {
 /**
  *
  */
-export class ProcessorExtension extends ExtensionBase {
-    kind = 'processor';
+export class AppExtension extends ExtensionBase {
+    kind = 'app';
     constructor(pkg, exportName, metadata, ctor) {
         super(pkg, exportName, metadata, ctor);
-        if (ctor && !isProcessorBase(ctor.prototype))
-            throw new SbError(`${ctor.name} does not extends ProcessorBase`);
+        if (ctor && !isAppBase(ctor.prototype))
+            throw new SbError(`${ctor.name} does not extends AppBase`);
     }
     async getClass() {
         if (this._ctor)
             return this._ctor;
-        const module = await import(this.pkg.entryPoint);
+        const module = await import(this.entryPoint || this.pkg.entryPoint);
         const ctor = module[this.exportName];
         if (!ctor)
-            throw new SbError(`Exported processor "${this.exportName}" not found in package "${this.pkg.name}"`);
+            throw new SbError(`Exported app "${this.exportName}" not found in package "${this.pkg.name}"`);
         if (typeof ctor !== 'function')
-            throw new SbError(`Exported processor "${this.exportName}" is not a class`);
-        if (!isProcessorBase(ctor.prototype))
-            throw new SbError(`Exported processor "${this.exportName}" does not extends ProcessorBase`);
+            throw new SbError(`Exported app "${this.exportName}" is not a class`);
+        if (!isAppBase(ctor.prototype))
+            throw new SbError(`Exported app "${this.exportName}" does not extends AppBase`);
         this._ctor = ctor;
         return this._ctor;
     }
 }
-//# sourceMappingURL=extension-package.js.map
+/**
+ * A plugin a package brings: it extends SyncBridge itself, loaded in the
+ * engine's main process, never in a worker
+ */
+export class PluginExtension {
+    pkg;
+    exportName;
+    metadata;
+    kind = 'plugin';
+    _ctor;
+    constructor(pkg, exportName, metadata, ctor) {
+        this.pkg = pkg;
+        this.exportName = exportName;
+        this.metadata = metadata;
+        this._ctor = ctor;
+    }
+    /** The name it is set by: `plugins.<name>` */
+    get name() {
+        return this.metadata.name;
+    }
+    get version() {
+        return this.pkg.version;
+    }
+    async getClass() {
+        if (this._ctor)
+            return this._ctor;
+        const module = await import(this.entryPoint || this.pkg.entryPoint);
+        const ctor = module[this.exportName];
+        if (typeof ctor !== 'function')
+            throw new SbError(`Exported plugin "${this.exportName}" not found in package "${this.pkg.name}"`);
+        if (Reflect.getMetadata(CLASS_TYPE, ctor) !== 'plugin')
+            throw new SbError(`Exported plugin "${this.exportName}" is not decorated with @Plugin`);
+        this._ctor = ctor;
+        return ctor;
+    }
+}

package/registry/extension-registry.d.ts

@@ -1,15 +1,15 @@
 import { ResponsiveMap } from '@opra/common';
 import { AsyncEventEmitter } from 'node-events-async';
 import type { Type } from 'ts-gems';
+import { AppBase } from '../classes/app-base.js';
 import { ComponentBase } from '../classes/component-base.js';
-import { ProcessorBase } from '../classes/processor-base.js';
-import { ComponentExtension, ExtensionPackage, ProcessorExtension } from './extension-package.js';
+import { AppExtension, ComponentExtension, ExtensionPackage } from './extension-package.js';
 declare const instanceSymbol: unique symbol;
 /**
- * The `ExtensionRegistry` class is responsible for managing component and processor extensions,
+ * The `ExtensionRegistry` class is responsible for managing component and app extensions,
  * as well as handling the registration of extension packages. It provides methods to locate and
  * retrieve extensions by their class name and version, and offers the ability to dynamically register
- * packages, components, and processors at runtime.
+ * packages, components, and apps at runtime.
  *
  * @class ExtensionRegistry
  */
@@ -22,7 +22,7 @@ export declare class ExtensionRegistry extends AsyncEventEmitter {
         registry: ExtensionRegistry;
     }[];
     /**
-     * The registry the static methods act on, and so ProcessorFactory and
+     * The registry the static methods act on, and so AppFactory and
      * the metadata helpers: the process's own, unless another is in use.
      */
     static get current(): ExtensionRegistry;
@@ -37,27 +37,27 @@ export declare class ExtensionRegistry extends AsyncEventEmitter {
     static get packages(): ResponsiveMap<ExtensionPackage[]>;
     static get components(): ResponsiveMap<ComponentExtension[]>;
     static get componentsByClassName(): ResponsiveMap<ComponentExtension[]>;
-    static get processors(): ResponsiveMap<ProcessorExtension[]>;
-    static get processorsByClassName(): ResponsiveMap<ProcessorExtension[]>;
+    static get apps(): ResponsiveMap<AppExtension[]>;
+    static get appsByClassName(): ResponsiveMap<AppExtension[]>;
     static setResolver(fn: ExtensionRegistry.PackageResolver | undefined): void;
     static findComponent(uri: string, version?: string): ComponentExtension | undefined;
     static getComponent(uri: string, version?: string): ComponentExtension;
-    static findProcessor(uri: string, version?: string): ProcessorExtension | undefined;
-    static getProcessor(uri: string, version?: string): ProcessorExtension;
+    static findApp(uri: string, version?: string): AppExtension | undefined;
+    static getApp(uri: string, version?: string): AppExtension;
     static registerPackage(specifier: string): Promise<ExtensionPackage>;
     static registerClass<T extends ComponentBase>(ctor: Type<T>): Promise<ComponentExtension>;
-    static registerClass<T extends ProcessorBase>(ctor: Type<T>): Promise<ProcessorExtension>;
+    static registerClass<T extends AppBase>(ctor: Type<T>): Promise<AppExtension>;
     static storePackage(pkg: ExtensionPackage): void;
     static onRegisterPackage(fn: (pkg: ExtensionPackage) => void): void;
     static onRegisterComponent(fn: (pkg: ComponentExtension) => void): void;
-    static onRegisterProcessor(fn: (pkg: ProcessorExtension) => void): void;
+    static onRegisterApp(fn: (pkg: AppExtension) => void): void;
     constructor();
     protected _resolver: ExtensionRegistry.PackageResolver;
     readonly packages: ResponsiveMap<ExtensionPackage[]>;
     readonly components: ResponsiveMap<ComponentExtension[]>;
     readonly componentsByClassName: ResponsiveMap<ComponentExtension[]>;
-    readonly processors: ResponsiveMap<ProcessorExtension[]>;
-    readonly processorsByClassName: ResponsiveMap<ProcessorExtension[]>;
+    readonly apps: ResponsiveMap<AppExtension[]>;
+    readonly appsByClassName: ResponsiveMap<AppExtension[]>;
     /**
      *
      */
@@ -73,17 +73,17 @@ export declare class ExtensionRegistry extends AsyncEventEmitter {
     /**
      *
      */
-    findProcessor(uri: string, version?: string): ProcessorExtension | undefined;
+    findApp(uri: string, version?: string): AppExtension | undefined;
     /**
      *
      */
-    getProcessor(uri: string, version?: string): ProcessorExtension;
+    getApp(uri: string, version?: string): AppExtension;
     /**
      *
      */
     registerPackage(specifier: string): Promise<ExtensionPackage>;
     registerClass<T extends ComponentBase>(ctor: Type<T>): Promise<ComponentExtension>;
-    registerClass<T extends ProcessorBase>(ctor: Type<T>): Promise<ProcessorExtension>;
+    registerClass<T extends AppBase>(ctor: Type<T>): Promise<AppExtension>;
     /**
      *
      */