@syncbridge/common 0.4.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2025 Panates (Panates Teknoloji Yatirim A.S.). All rights reserved.
+
+This software and associated documentation files (the "Software") are
+the proprietary property of Panates and are protected by copyright laws
+and international copyright treaties.
+
+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.
+
+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.
+
+For licensing inquiries, please contact: info@panates.com

package/README.md

@@ -0,0 +1 @@
+# SyncBridge Common Library

package/classes/base-element.d.ts

@@ -0,0 +1,46 @@
+import { ILogger } from '../interfaces/index.js';
+import { ServiceStatus } from '../models/index.js';
+import type { ComponentBase } from './component-base.js';
+import { Runnable } from './runnable.js';
+export declare abstract class BaseElement<TEvents extends BaseElement.Events = BaseElement.Events> extends Runnable<TEvents> {
+    static className: string;
+    static interfaces: string[];
+    protected _context: BaseElement.Context;
+    readonly name: string;
+    logger?: ILogger;
+    components: Record<string, ComponentBase>;
+    values: Record<string, any>;
+    constructor(init: BaseElement.InitArgs);
+    get status(): ServiceStatus;
+    get statusMessage(): string;
+    protected _init(): Promise<void>;
+    protected _start(abortSignal: AbortSignal): Promise<void>;
+    protected _stop(): Promise<void>;
+    protected onStatusChange(): void;
+}
+/**
+ * @namespace
+ */
+export declare namespace BaseElement {
+    interface Events extends Runnable.Events {
+        'component-status-change': [
+            component: ComponentBase,
+            status: ServiceStatus,
+            statusMessage: string
+        ];
+    }
+    interface InitArgs extends Runnable.InitArgs {
+        logger?: ILogger;
+        name: string;
+        values: Record<string, any>;
+    }
+    interface Context extends Runnable.Context {
+        calculatedStatus?: ServiceStatus;
+        calculatedStatusMessage?: string;
+        statusIndicators: Record<string, {
+            count: number;
+            components: ComponentBase[];
+            componentNames: string[];
+        }>;
+    }
+}

package/classes/base-element.js

@@ -0,0 +1,80 @@
+import { ServiceStatus } from '../models/index.js';
+import { Runnable } from './runnable.js';
+export class BaseElement extends Runnable {
+    static className;
+    static interfaces;
+    name;
+    logger;
+    components = {};
+    values;
+    constructor(init) {
+        super(init);
+        this.logger = init.logger;
+        this.name = init.name;
+        this.values = init.values;
+        if (this.logger)
+            this.on('error', err => this.logger?.error(err));
+    }
+    get status() {
+        return this._context.calculatedStatus || this._context.status;
+    }
+    get statusMessage() {
+        return this._context.calculatedStatusMessage ?? this._context.statusMessage;
+    }
+    async _init() {
+        for (const component of Object.values(this.components)) {
+            component.on('status-change', (status, statusMessage) => {
+                /** Reset counters */
+                this._context.statusIndicators = this._context.statusIndicators || {};
+                Object.keys(ServiceStatus).forEach(key => {
+                    this._context.statusIndicators[key] = {
+                        count: 0,
+                        components: [],
+                        componentNames: [],
+                    };
+                });
+                Object.values(this.components).forEach(comp => {
+                    const counter = this._context.statusIndicators[comp.status];
+                    counter.count++;
+                    counter.components.push(comp);
+                    counter.componentNames.push(comp.name);
+                });
+                this.emitSafe('component-status-change', component, status, statusMessage);
+                if (this._context.status !== this._context.calculatedStatus)
+                    this.onStatusChange();
+            });
+        }
+        /** Initialize components first */
+        await Promise.all(Object.values(this.components).map(component => component.init()));
+    }
+    async _start(abortSignal) {
+        await Promise.all(Object.values(this.components).map(component => component.start(abortSignal)));
+    }
+    async _stop() {
+        await Promise.all(Object.values(this.components)
+            .reverse()
+            .map(component => component.stop()));
+    }
+    onStatusChange() {
+        const oldStatus = this.status;
+        const oldStatusMessage = this.statusMessage;
+        this._context.calculatedStatus = this._context.status;
+        this._context.calculatedStatusMessage = this._context.statusMessage;
+        if (!(this.status === ServiceStatus.stopped ||
+            this.status === ServiceStatus.stopping)) {
+            /** If there are one or more unhealthy components, set calculatedStatus to unhealthy */
+            for (const _status of [ServiceStatus.unhealthy, ServiceStatus.starting]) {
+                const indicator = this._context.statusIndicators?.[_status];
+                if (indicator?.count) {
+                    this._context.calculatedStatus = _status;
+                    this._context.calculatedStatusMessage = `${_status} components: ${indicator.componentNames}`;
+                    return;
+                }
+            }
+        }
+        if (this.status !== oldStatus || this.statusMessage !== oldStatusMessage) {
+            this.logger?.debug(this.status);
+            super.onStatusChange();
+        }
+    }
+}

package/classes/component-base.d.ts

@@ -0,0 +1,26 @@
+import { BaseElement } from './base-element.js';
+import type { ProcessorBase } from './processor-base.js';
+export declare class ComponentBase<TEvents extends ComponentBase.Events = ComponentBase.Events> extends BaseElement<TEvents> {
+    protected _context: ComponentBase.Context;
+    readonly processor: ProcessorBase;
+    readonly parent: ProcessorBase | ComponentBase;
+    readonly path: string;
+    constructor(init: ComponentBase.InitArgs);
+}
+/**
+ * @namespace
+ */
+export declare namespace ComponentBase {
+    interface Events extends BaseElement.Events {
+    }
+    interface InitArgs extends BaseElement.InitArgs {
+        processor: ProcessorBase;
+        parent: ProcessorBase | ComponentBase;
+        path: string;
+    }
+    interface Context extends BaseElement.Context {
+        parent: ProcessorBase | ComponentBase;
+        name: string;
+        path: string;
+    }
+}

package/classes/component-base.js

@@ -0,0 +1,12 @@
+import { BaseElement } from './base-element.js';
+export class ComponentBase extends BaseElement {
+    processor;
+    parent;
+    path;
+    constructor(init) {
+        super(init);
+        this.processor = init.processor;
+        this.parent = init.parent;
+        this.path = init.path;
+    }
+}

package/classes/frame-stream.d.ts

@@ -0,0 +1,34 @@
+import { Buffer } from 'node:buffer';
+import { Transform } from 'node:stream';
+import { TransformCallback, TransformOptions } from 'stream';
+import { StrictOmit } from 'ts-gems';
+export declare class FrameStream extends Transform {
+    private _chunks;
+    private _chunkBuffer?;
+    private _flushTimeout?;
+    private readonly _frameDelayMs;
+    private readonly _frameStart?;
+    private readonly _frameEnd?;
+    private readonly _maxBufferSize?;
+    private _bufferSize;
+    private readonly _customTransform?;
+    constructor(opts?: StrictOmit<TransformOptions, 'objectMode'> & {
+        encoding?: string;
+        /**
+         * Time in milliseconds to be waited before accepting a buffer as a frame
+         */
+        frameDelayMs?: number;
+        /**
+         * The start character(s) or byte(s) of the actual frame
+         */
+        frameStart?: Buffer | string;
+        frameEnd?: Buffer | string;
+        maxBufferSize?: number;
+    });
+    _transform(chunk: Buffer | string, _encoding: BufferEncoding, callback: TransformCallback): void;
+    protected _pushChunk(chunk: Buffer): void;
+    protected _assertMaxBuffer(newChunkLen?: number): void;
+    _flush(callback: TransformCallback): void;
+    reset(): void;
+    private flushBuffer;
+}

package/classes/frame-stream.js

@@ -0,0 +1,140 @@
+import { Buffer } from 'node:buffer';
+import { Transform } from 'node:stream';
+export class FrameStream extends Transform {
+    _chunks = [];
+    _chunkBuffer;
+    _flushTimeout;
+    _frameDelayMs;
+    _frameStart;
+    _frameEnd;
+    _maxBufferSize;
+    _bufferSize = 0;
+    _customTransform;
+    constructor(opts) {
+        super({
+            ...opts,
+            objectMode: true,
+            transform: undefined,
+        });
+        this._customTransform = opts?.transform;
+        this._frameDelayMs = opts?.frameDelayMs || (opts?.frameEnd ? 0 : 500);
+        this._maxBufferSize = opts?.maxBufferSize;
+        if (opts?.frameStart) {
+            this._frameStart = Buffer.isBuffer(opts.frameStart)
+                ? opts.frameStart
+                : Buffer.from(opts.frameStart);
+        }
+        if (opts?.frameEnd) {
+            this._frameEnd = Buffer.isBuffer(opts.frameEnd)
+                ? opts.frameEnd
+                : Buffer.from(opts.frameEnd);
+        }
+    }
+    _transform(chunk, _encoding, callback) {
+        // Reset flush timer
+        if (this._flushTimeout) {
+            clearTimeout(this._flushTimeout);
+        }
+        try {
+            // console.log(chunk);
+            if (!Buffer.isBuffer(chunk))
+                chunk = Buffer.from(chunk);
+            if (this._chunkBuffer) {
+                this._assertMaxBuffer(chunk.length);
+                chunk = Buffer.concat([this._chunkBuffer, chunk]);
+                this._chunkBuffer = undefined;
+            }
+            const frameStart = this._frameStart;
+            const frameEnd = this._frameEnd;
+            if (frameStart || frameEnd) {
+                const stxLen = frameStart?.length || 0;
+                const etxLen = frameEnd?.length || 0;
+                let stxPos = 0;
+                let etxPos = 0;
+                while (etxPos < chunk.length) {
+                    /** Find the next stx position */
+                    stxPos = etxPos;
+                    if (frameStart) {
+                        stxPos = chunk.indexOf(frameStart, etxPos);
+                        if (stxPos < 0) {
+                            this._chunkBuffer = chunk.subarray(etxPos);
+                            return;
+                        }
+                    }
+                    if (stxPos < 0)
+                        stxPos = 0;
+                    etxPos = frameEnd
+                        ? /** Find the next etx position if frameEnd defined */
+                            chunk.indexOf(frameEnd, stxPos + stxLen)
+                        : frameStart
+                            ? /** Find the next stx if frameStart not defined */
+                                chunk.indexOf(frameStart, stxPos + stxLen)
+                            : -1;
+                    if (etxPos < 0) {
+                        this._chunkBuffer = chunk.subarray(stxPos);
+                        return;
+                    }
+                    etxPos += etxLen;
+                    this._pushChunk(chunk.subarray(stxPos, etxPos));
+                    this.flushBuffer();
+                }
+                return;
+            }
+            this._pushChunk(chunk);
+        }
+        finally {
+            if (this._chunks.length && this._frameDelayMs)
+                this._flushTimeout = setTimeout(() => this.flushBuffer(), this._frameDelayMs).unref();
+            callback();
+        }
+    }
+    _pushChunk(chunk) {
+        this._assertMaxBuffer(chunk.length);
+        this._chunks.push(chunk);
+        this._bufferSize += chunk.length;
+    }
+    _assertMaxBuffer(newChunkLen = 0) {
+        if (this._maxBufferSize &&
+            this._bufferSize + newChunkLen + (this._chunkBuffer?.length || 0) >
+                this._maxBufferSize) {
+            this.emit('error', new Error('Max buffer size exceeded'));
+        }
+    }
+    _flush(callback) {
+        if (this._flushTimeout) {
+            clearTimeout(this._flushTimeout);
+        }
+        this.flushBuffer();
+        callback();
+    }
+    reset() {
+        this._chunks = [];
+        this._chunkBuffer = undefined;
+        if (this._flushTimeout) {
+            clearTimeout(this._flushTimeout);
+            this._flushTimeout = undefined;
+        }
+    }
+    flushBuffer() {
+        if (this._chunkBuffer) {
+            this._chunks.push(this._chunkBuffer);
+            this._chunkBuffer = undefined;
+        }
+        /* c8 ignore next */
+        if (this._chunks.length === 0)
+            return;
+        const combined = this._chunks.length === 1 ? this._chunks[0] : Buffer.concat(this._chunks);
+        this._chunks = [];
+        this._bufferSize = 0;
+        if (this._customTransform) {
+            this._customTransform(combined, 'buffer', (err, data) => {
+                if (err)
+                    this.emit('error', err);
+                else
+                    this.push(data);
+            });
+            return;
+        }
+        this.push(combined);
+    }
+}

package/classes/processor-base.d.ts

@@ -0,0 +1,15 @@
+import { BaseElement } from './base-element.js';
+export declare abstract class ProcessorBase<TEvents extends ProcessorBase.Events = ProcessorBase.Events> extends BaseElement<TEvents> {
+    dataDirectory?: string;
+    constructor(init: ProcessorBase.InitArgs);
+}
+/**
+ * @namespace
+ */
+export declare namespace ProcessorBase {
+    interface Events extends BaseElement.Events {
+    }
+    interface InitArgs extends BaseElement.InitArgs {
+        dataDirectory?: string;
+    }
+}

package/classes/processor-base.js

@@ -0,0 +1,8 @@
+import { BaseElement } from './base-element.js';
+export class ProcessorBase extends BaseElement {
+    dataDirectory;
+    constructor(init) {
+        super(init);
+        this.dataDirectory = init.dataDirectory;
+    }
+}

package/classes/runnable.d.ts

@@ -0,0 +1,86 @@
+import { AsyncEventEmitter, EventMap } from 'node-events-async';
+import { ServiceStatus } from '../models/index.js';
+/**
+ *
+ */
+export declare abstract class Runnable<T extends Runnable.Events = Runnable.Events> extends AsyncEventEmitter<EventMap<T>> {
+    protected _context: Runnable.Context;
+    constructor(init?: Runnable.InitArgs);
+    get status(): ServiceStatus;
+    get statusMessage(): string;
+    get startTime(): Date | undefined;
+    /**
+     *
+     */
+    get stopped(): boolean;
+    startNoWait(): void;
+    stopNoWait(): void;
+    /**
+     *
+     */
+    init(): Promise<void>;
+    /**
+     *
+     */
+    start(abortSignal?: AbortSignal): Promise<void>;
+    /**
+     *
+     */
+    stop(): Promise<void>;
+    /**
+     *
+     */
+    protected _init(): Promise<void>;
+    /**
+     *
+     */
+    protected abstract _start(abortSignal: AbortSignal): Promise<void>;
+    /**
+     *
+     */
+    protected abstract _stop(): Promise<void>;
+    /**
+     *
+     */
+    protected _terminate(): Promise<void>;
+    /**
+     *
+     */
+    protected onError(err: Error): void;
+    /**
+     *
+     */
+    protected onInitialize(): void;
+    /**
+     *
+     */
+    protected onStatusChange(): void;
+    /**
+     *
+     */
+    protected setStatus(status: ServiceStatus, statusMessage?: string): void;
+}
+/**
+ * @namespace
+ */
+export declare namespace Runnable {
+    interface Events {
+        error: [error: unknown, ...args: any[]];
+        initialize: [];
+        'status-change': [status: ServiceStatus, message: string];
+    }
+    interface InitArgs {
+        startMaxWaitMs?: number;
+        stopMaxWaitMs?: number;
+    }
+    interface Context {
+        initialized: boolean;
+        status: ServiceStatus;
+        statusMessage: string;
+        waitTimer?: Promise<void>;
+        startTime?: Date;
+        startMaxWaitMs: number;
+        stopMaxWaitMs: number;
+        stopTimer?: NodeJS.Timeout;
+    }
+}