@syncbridge/common 0.4.6 → 0.5.1

package/LICENSE

@@ -1,15 +1,21 @@
-Copyright (c) 2025 Panates (Panates Teknoloji Yatirim A.S.). All rights reserved.
+MIT License
 
-This software and associated documentation files (the "Software") are
-the proprietary property of Panates and are protected by copyright laws
-and international copyright treaties.
+Copyright (c) 2022 Panates
 
-Unauthorized copying, distribution, modification, reverse engineering,
-or use of this software, in whole or in part, is strictly prohibited
-without the express written permission of Panates.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-This Software is provided solely for use in accordance with the terms
-of a valid license agreement. Any unauthorized use may result in
-civil and/or criminal penalties.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-For licensing inquiries, please contact: info@panates.com
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/classes/stack-executor.d.ts

@@ -2,6 +2,7 @@ import { ErrorIssue } from '@opra/common';
 export declare class StackExecutor {
     stack: string[];
     issues: StackExecutor.Issue[];
+    executeAsync(stack: string, fn: () => Promise<any>): Promise<void>;
     execute(stack: string, fn: () => any): void;
     handleError(e: any): void;
 }

package/classes/stack-executor.js

@@ -2,6 +2,18 @@ import { ValidationError } from 'valgen';
 export class StackExecutor {
     stack = [];
     issues = [];
+    async executeAsync(stack, fn) {
+        this.stack.push(stack);
+        try {
+            await fn();
+        }
+        catch (e) {
+            this.handleError(e);
+        }
+        finally {
+            this.stack.pop();
+        }
+    }
     execute(stack, fn) {
         this.stack.push(stack);
         try {

package/constants.d.ts

@@ -1,3 +1,4 @@
+export declare const version = "1";
 export declare const OWN_ELEMENT_METADATA: unique symbol;
 export declare const COMPONENT_OPTIONS: unique symbol;
 export declare const PROCESSOR_OPTIONS: unique symbol;

package/constants.js

@@ -1,3 +1,4 @@
+export const version = '0.5.1';
 export const OWN_ELEMENT_METADATA = Symbol.for('OWN_ELEMENT_METADATA');
 export const COMPONENT_OPTIONS = Symbol.for('COMPONENT_OPTIONS');
 export const PROCESSOR_OPTIONS = Symbol.for('PROCESSOR_OPTIONS');

package/index.d.ts

@@ -14,7 +14,7 @@ export * from './models/index.js';
 export * as models from './models/index.js';
 export * from './models-document.js';
 export * from './processor-factory.js';
-export * from './registry.js';
-export * from './utils/make-extension-package.js';
+export * from './registry/extension-package.js';
+export * from './registry/extension-registry.js';
 export * from './utils/metadata-utils.js';
 export * from './utils/profile-utils.js';

package/index.js

@@ -14,7 +14,7 @@ export * from './models/index.js';
 export * as models from './models/index.js';
 export * from './models-document.js';
 export * from './processor-factory.js';
-export * from './registry.js';
-export * from './utils/make-extension-package.js';
+export * from './registry/extension-package.js';
+export * from './registry/extension-registry.js';
 export * from './utils/metadata-utils.js';
 export * from './utils/profile-utils.js';

package/interfaces/index.d.ts

@@ -1,2 +1 @@
-export * from './extension-package.interface.js';
 export * from './logger.interface.js';

package/interfaces/index.js

@@ -1,2 +1 @@
-export * from './extension-package.interface.js';
 export * from './logger.interface.js';

package/models/profile/profile.d.ts

@@ -16,6 +16,7 @@ export declare class Profile {
     id: string;
     displayName: string;
     processorClass: string;
+    processorVersion?: string;
     group?: string;
     description?: string;
     iconUrl?: string;

package/models/profile/profile.js

@@ -65,6 +65,13 @@ __decorate([
     }),
     __metadata("design:type", String)
 ], Profile.prototype, "processorClass", void 0);
+__decorate([
+    ApiField({
+        label: 'Processor Version',
+        description: 'Determines which installed version will be used. This value accepts semver format. https://semver.npmjs.com/',
+    }),
+    __metadata("design:type", String)
+], Profile.prototype, "processorVersion", void 0);
 __decorate([
     ApiField({
         label: 'Group',

package/models-document.d.ts

@@ -1,3 +1,3 @@
 import { ApiDocument } from '@opra/common';
-export declare function initializeModelsDocument(): Promise<void>;
+export declare function initializeModelsDocument(): Promise<ApiDocument>;
 export declare function getModelsDocument(): ApiDocument;

package/models-document.js

@@ -7,6 +7,7 @@ export async function initializeModelsDocument() {
             (await ApiDocumentFactory.createDocument({
                 types: [...Object.values(models)],
             }));
+    return doc;
 }
 export function getModelsDocument() {
     if (!doc)

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@syncbridge/common",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "SyncBridge Common utilities",
   "author": "Panates Inc",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "dependencies": {
     "@jsopen/objects": "^2.0.2",
     "node-events-async": "^1.5.0",
     "reflect-metadata": "^0.2.2",
+    "semver": "^7.7.3",
     "ts-gems": "^3.11.3",
     "valgen": "^5.19.4"
   },

package/processor-factory.js

@@ -1,6 +1,6 @@
 import { StackExecutor } from './classes/stack-executor.js';
 import { initializeModelsDocument } from './models-document.js';
-import { ExtensionRegistry } from './registry.js';
+import { ExtensionRegistry } from './registry/extension-registry.js';
 import { materializeMetadata } from './utils/metadata-utils.js';
 export var ProcessorFactory;
 (function (ProcessorFactory) {
@@ -8,8 +8,9 @@ export var ProcessorFactory;
     ProcessorFactory.PROFILE_KEY = Symbol('PROFILE');
     async function createProcessor(profile, options) {
         await initializeModelsDocument();
-        const reg = ExtensionRegistry.getProcessor(profile.processorClass);
-        const processor = new reg.ctor({
+        const reg = ExtensionRegistry.getProcessor(profile.processorClass, profile.processorVersion);
+        const processorClass = await reg.getClass();
+        const processor = new processorClass({
             name: profile.displayName,
             logger: options?.logger,
             values: profile.values || {},
@@ -30,14 +31,14 @@ export var ProcessorFactory;
     async function _configureProcessor(processor, profile) {
         const processorMetadata = materializeMetadata(profile);
         const stackExecutor = new StackExecutor();
-        function configureComponents(owner, curPath, newMetadata, newProfile, oldMetadata, oldProfile) {
+        async function configureComponents(owner, curPath, newMetadata, newProfile, oldMetadata, oldProfile) {
             if (!newMetadata.components)
                 return;
             // Stack: components
-            stackExecutor.execute('components', () => {
+            await stackExecutor.executeAsync('components', async () => {
                 for (const [key, childMetadata] of Object.entries(newMetadata.components)) {
                     // Stack: components/componentName
-                    stackExecutor.execute(key, () => {
+                    await stackExecutor.executeAsync(key, async () => {
                         const oldChildMetadata = oldMetadata?.components?.[key];
                         const oldChildProfile = oldProfile?.components?.[key];
                         const childProfile = newProfile.components[key];
@@ -47,7 +48,7 @@ export var ProcessorFactory;
                         if (processor.stopped) {
                             const compReg = ExtensionRegistry.getComponent(childMetadata.className);
                             /** Create the component instance */
-                            const compClass = compReg.ctor;
+                            const compClass = await compReg.getClass();
                             componentInstance = new compClass({
                                 processor: processor,
                                 parent: owner,
@@ -84,23 +85,8 @@ export var ProcessorFactory;
                 }
             });
         }
-        configureComponents(processor, '', processorMetadata, profile, processor[ProcessorFactory.METADATA_KEY], processor[ProcessorFactory.PROFILE_KEY]);
+        await configureComponents(processor, '', processorMetadata, profile, processor[ProcessorFactory.METADATA_KEY], processor[ProcessorFactory.PROFILE_KEY]);
         processor[ProcessorFactory.METADATA_KEY] = processorMetadata;
         processor[ProcessorFactory.PROFILE_KEY] = profile;
-        // processor.on('error', err => this.logger.error(err));
-        // processor.on('status-change', args => {
-        //   this.messageHandler.emit('status-change', args);
-        // });
-        // processor.on(
-        //   'component-status-change',
-        //   (component, status, statusMessage) => {
-        //     this.messageHandler.emit('component-status-change', {
-        //       componentName: component.name,
-        //       path: component.path,
-        //       status,
-        //       statusMessage,
-        //     });
-        //   },
-        // );
     }
 })(ProcessorFactory || (ProcessorFactory = {}));

package/registry/extension-package.d.ts

@@ -0,0 +1,53 @@
+import 'reflect-metadata';
+import { Type } from 'ts-gems';
+import { ComponentBase } from '../classes/component-base.js';
+import { ProcessorBase } from '../classes/processor-base.js';
+import { ComponentMetadata, ProcessorMetadata } from '../models/index.js';
+/**
+ *
+ */
+export declare class ExtensionPackage {
+    name: string;
+    version: string;
+    description: string;
+    entryPoint: string;
+    components: ExtensionPackageComponent[];
+    processors: ExtensionPackageProcessor[];
+    errors: Error[];
+    sortVersions(): void;
+    /**
+     *
+     * @param directory
+     * @static
+     */
+    static fromDirectory(directory: string): Promise<ExtensionPackage>;
+    static fromNodePackage(specifier: string, resolver?: (name: string) => string): Promise<ExtensionPackage>;
+}
+/**
+ *
+ */
+export declare class ExtensionPackageComponent {
+    readonly pkg: ExtensionPackage;
+    readonly exportName: string;
+    readonly metadata: ComponentMetadata;
+    protected _ctor?: Type<ComponentBase>;
+    constructor(pkg: ExtensionPackage, exportName: string, metadata: ComponentMetadata, ctor?: Type<ComponentBase>);
+    get className(): string;
+    get displayName(): string;
+    get version(): string;
+    getClass(): Promise<Type<ComponentBase>>;
+}
+/**
+ *
+ */
+export declare class ExtensionPackageProcessor {
+    readonly pkg: ExtensionPackage;
+    readonly exportName: string;
+    readonly metadata: ProcessorMetadata;
+    protected _ctor?: Type<ProcessorBase>;
+    constructor(pkg: ExtensionPackage, exportName: string, metadata: ProcessorMetadata, ctor?: Type<ProcessorBase>);
+    get className(): string;
+    get displayName(): string;
+    get version(): string;
+    getClass(): Promise<Type<ProcessorBase>>;
+}

package/registry/extension-package.js

@@ -0,0 +1,267 @@
+import 'reflect-metadata';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ComponentBase } from '../classes/component-base.js';
+import { ProcessorBase } from '../classes/processor-base.js';
+import { COMPONENT_OPTIONS, PROCESSOR_OPTIONS } from '../constants.js';
+import { ComponentMetadata, ProcessorMetadata } from '../models/index.js';
+import { initializeModelsDocument } from '../models-document.js';
+import { resolvePromisesDeep } from '../utils/resolve-promises.js';
+let _compMetadataTypeDecoder;
+let _procMetadataTypeDecoder;
+async function getCompMetadataTypeDecoder() {
+    if (!_compMetadataTypeDecoder) {
+        const apiDoc = await initializeModelsDocument();
+        const compMetadataType = apiDoc.node.getComplexType(ComponentMetadata);
+        _compMetadataTypeDecoder = compMetadataType.generateCodec('decode', {
+            coerce: true,
+        });
+    }
+    return _compMetadataTypeDecoder;
+}
+async function getProcMetadataTypeDecoder() {
+    if (!_procMetadataTypeDecoder) {
+        const apiDoc = await initializeModelsDocument();
+        const procMetadataType = apiDoc.node.getComplexType(ProcessorMetadata);
+        _procMetadataTypeDecoder = procMetadataType.generateCodec('decode', {
+            coerce: true,
+        });
+    }
+    return _procMetadataTypeDecoder;
+}
+/**
+ *
+ */
+export class ExtensionPackage {
+    components = [];
+    processors = [];
+    errors = [];
+    sortVersions() {
+        this.components.sort((a, b) => a.version.localeCompare(b.version));
+        this.processors.sort((a, b) => a.version.localeCompare(b.version));
+    }
+    /**
+     *
+     * @param directory
+     * @static
+     */
+    static async fromDirectory(directory) {
+        const compMetadataTypeDecoder = await getCompMetadataTypeDecoder();
+        let filename = path.join(directory, 'package.json');
+        if (!fs.existsSync(filename))
+            throw new TypeError(`Directory "${directory}" does not contain package.json`);
+        const pkgJson = JSON.parse(fs.readFileSync(filename, 'utf8'));
+        if (!pkgJson.syncbridge)
+            throw new TypeError(`"${pkgJson.name}" is not a SyncBridge extension package`);
+        const out = new ExtensionPackage();
+        out.name = pkgJson.name;
+        out.version = pkgJson.version;
+        out.description = pkgJson.description;
+        out.entryPoint = path.join(directory, pkgJson.module || pkgJson.main);
+        let metadata;
+        if (pkgJson.syncbridge.components) {
+            for (const ctorName of pkgJson.syncbridge.components) {
+                filename = path.join(directory, 'metadata', ctorName + '.json');
+                if (!fs.existsSync(filename)) {
+                    out.errors.push(new Error(`Component (${ctorName}) metadata file not found`));
+                    continue;
+                }
+                try {
+                    metadata = JSON.parse(fs.readFileSync(filename, 'utf8'));
+                }
+                catch {
+                    out.errors.push(new Error(`Component (${ctorName}) metadata file read error`));
+                    continue;
+                }
+                try {
+                    metadata = compMetadataTypeDecoder(metadata);
+                }
+                catch (e) {
+                    out.errors.push(new Error(`Component (${ctorName}) metadata validation error. ` + e.message));
+                    continue;
+                }
+                if (metadata.abstract)
+                    continue;
+                out.components = out.components || [];
+                out.components.push(new ExtensionPackageComponent(out, ctorName, metadata));
+            }
+        }
+        if (pkgJson.syncbridge.processors) {
+            for (const ctorName of pkgJson.syncbridge.processors) {
+                filename = path.join(directory, 'metadata', ctorName + '.json');
+                if (!fs.existsSync(filename)) {
+                    out.errors.push(new Error(`Processors (${ctorName}) metadata file not found`));
+                    continue;
+                }
+                try {
+                    metadata = JSON.parse(fs.readFileSync(filename, 'utf8'));
+                }
+                catch {
+                    out.errors.push(new Error(`Processors (${ctorName}) metadata file read error`));
+                    continue;
+                }
+                try {
+                    metadata = compMetadataTypeDecoder(metadata);
+                }
+                catch (e) {
+                    out.errors.push(new Error(`Processor (${ctorName}) metadata validation error. ` + e.message));
+                    continue;
+                }
+                if (metadata.abstract)
+                    continue;
+                out.processors = out.processors || [];
+                out.processors.push(new ExtensionPackageProcessor(out, ctorName, metadata));
+            }
+        }
+        out.sortVersions();
+        return out;
+    }
+    static async fromNodePackage(specifier, resolver = import.meta.resolve) {
+        const compMetadataTypeDecoder = await getCompMetadataTypeDecoder();
+        const procMetadataTypeDecoder = await getProcMetadataTypeDecoder();
+        let entryPoint = fileURLToPath(resolver(specifier));
+        const pkgJson = locatePkgJson(path.dirname(entryPoint));
+        if (!pkgJson) {
+            throw new TypeError(`Can't locate package.json file for "${specifier}"`);
+        }
+        if (path.isAbsolute(entryPoint) && process.platform === 'win32') {
+            entryPoint = pathToFileURL(entryPoint).href;
+        }
+        const out = new ExtensionPackage();
+        out.name = pkgJson.name;
+        out.version = pkgJson.version;
+        out.description = pkgJson.description;
+        out.entryPoint = entryPoint;
+        const module = await import(entryPoint);
+        for (const [ctorName, v] of Object.entries(module)) {
+            if (typeof v !== 'function')
+                continue;
+            let metadata = Reflect.getMetadata(COMPONENT_OPTIONS, v);
+            if (metadata) {
+                metadata = await resolvePromisesDeep(metadata);
+                try {
+                    metadata = compMetadataTypeDecoder(metadata);
+                }
+                catch (e) {
+                    out.errors.push(new Error(`Component (${ctorName}) metadata validation error. ` + e.message));
+                    continue;
+                }
+                if (metadata.abstract)
+                    continue;
+                out.components = out.components || [];
+                out.components.push(new ExtensionPackageComponent(out, ctorName, metadata));
+            }
+            metadata = Reflect.getMetadata(PROCESSOR_OPTIONS, v);
+            if (metadata) {
+                metadata = await resolvePromisesDeep(metadata);
+                try {
+                    metadata = procMetadataTypeDecoder(metadata);
+                }
+                catch (e) {
+                    out.errors.push(new Error(`Processor (${ctorName}) metadata validation error. ` + e.message));
+                    continue;
+                }
+                if (metadata.abstract)
+                    continue;
+                out.processors = out.processors || [];
+                out.processors.push(new ExtensionPackageProcessor(out, ctorName, metadata));
+            }
+        }
+        out.sortVersions();
+        return out;
+    }
+}
+/**
+ *
+ */
+export class ExtensionPackageComponent {
+    pkg;
+    exportName;
+    metadata;
+    _ctor;
+    constructor(pkg, exportName, metadata, ctor) {
+        this.pkg = pkg;
+        this.exportName = exportName;
+        this.metadata = metadata;
+        this._ctor = ctor;
+    }
+    get className() {
+        return this.metadata.className;
+    }
+    get displayName() {
+        return this.metadata.displayName;
+    }
+    get version() {
+        return this.pkg.version;
+    }
+    async getClass() {
+        if (this._ctor)
+            return this._ctor;
+        const module = await import(this.pkg.entryPoint);
+        const ctor = module[this.exportName];
+        if (!ctor)
+            throw new TypeError(`Exported component "${this.exportName}" not found in package "${this.pkg.name}"`);
+        if (typeof ctor !== 'function')
+            throw new TypeError(`Exported component "${this.exportName}" is not a class`);
+        if (!(ctor.prototype instanceof ComponentBase))
+            throw new TypeError(`Exported component "${this.exportName}" does not extends ComponentBase`);
+        this._ctor = ctor;
+        return this._ctor;
+    }
+}
+/**
+ *
+ */
+export class ExtensionPackageProcessor {
+    pkg;
+    exportName;
+    metadata;
+    _ctor;
+    constructor(pkg, exportName, metadata, ctor) {
+        this.pkg = pkg;
+        this.exportName = exportName;
+        this.metadata = metadata;
+        this._ctor = ctor;
+    }
+    get className() {
+        return this.metadata.className;
+    }
+    get displayName() {
+        return this.metadata.displayName;
+    }
+    get version() {
+        return this.pkg.version;
+    }
+    async getClass() {
+        if (this._ctor)
+            return this._ctor;
+        const module = await import(this.pkg.entryPoint);
+        const ctor = module[this.exportName];
+        if (!ctor)
+            throw new TypeError(`Exported processor "${this.exportName}" not found in package "${this.pkg.name}"`);
+        if (typeof ctor !== 'function')
+            throw new TypeError(`Exported processor "${this.exportName}" is not a class`);
+        if (!(ctor.prototype instanceof ProcessorBase))
+            throw new TypeError(`Exported processor "${this.exportName}" does not extends ProcessorBase`);
+        this._ctor = ctor;
+        return this._ctor;
+    }
+}
+/**
+ *
+ */
+function locatePkgJson(directory) {
+    if (directory.startsWith('file:'))
+        directory = fileURLToPath(directory);
+    for (let i = 0; i < 3; i++) {
+        const f = path.resolve(directory, 'package.json');
+        if (fs.existsSync(f)) {
+            const json = JSON.parse(fs.readFileSync(f, 'utf8'));
+            if (json.name && json.version)
+                return json;
+        }
+        directory = path.dirname(directory);
+    }
+}

package/registry/extension-registry.d.ts

@@ -0,0 +1,43 @@
+import { Type } from 'ts-gems';
+import { ExtensionPackage, ExtensionPackageComponent, ExtensionPackageProcessor } from './extension-package.js';
+export declare namespace ExtensionRegistry {
+    let _resolver: {
+        (specifier: string): string;
+        (specifier: string, parent?: string | import("node:url").URL): string;
+    };
+    export const packages: Map<string, ExtensionPackage[]>;
+    export const components: Map<string, ExtensionPackageComponent[]>;
+    export const processors: Map<string, ExtensionPackageProcessor[]>;
+    /**
+     *
+     */
+    export function findComponent(className: string, version?: string): ExtensionPackageComponent | undefined;
+    /**
+     *
+     */
+    export function getComponent(className: string, version?: string): ExtensionPackageComponent;
+    /**
+     *
+     */
+    export function findProcessor(className: string, version?: string): ExtensionPackageProcessor | undefined;
+    /**
+     *
+     */
+    export function getProcessor(className: string, version?: string): ExtensionPackageProcessor;
+    /**
+     *
+     * @param resolver
+     */
+    export function setResolver(resolver: typeof _resolver): void;
+    /**
+     *
+     */
+    export function registerExtensionPackage(directory: string): Promise<ExtensionPackage>;
+    /**
+     *
+     */
+    export function registerNodePackage(specifier: string): Promise<ExtensionPackage>;
+    export function registerComponent(ctor: Type): Promise<ExtensionPackageComponent | undefined>;
+    export function registerProcessor(ctor: Type): Promise<ExtensionPackageProcessor | undefined>;
+    export {};
+}