@e-mc/core

Interface

View Source

import type { DataSource, LogStatus, WorkerAction } from "./squared";

import type { IHost, IModule, ModuleConstructor } from "./index";
import type { AddEventListenerOptions, CacheOptions, HostInitConfig, JoinQueueOptions, PermissionReadWrite, ResumeThreadOptions, StoreResultOptions, ThreadCountStat, WorkerChannelError, WorkerChannelResponse } from "./core";
import type { QueryResult, TimeoutAction } from "./db";
import type { LogState, StatusType } from "./logger";
import type { Settings } from "./node";
import type { ClientDbSettings, ClientModule, ClientSettings, DbCacheValue, DbCoerceSettings, DbCoerceValue, DbSourceOptions } from "./settings";

import type { TransferListItem, Worker, WorkerOptions } from "node:worker_threads";

import type EventEmitter from "node:events";

interface IHost extends IModule {
    restartable: boolean;
    readonly modules: Set<IModule>;
    readonly subProcesses: Set<IModule>;
    readonly startTime: number;
    using(...items: unknown[] | [boolean, ...unknown[]]): this;
    contains(item: unknown, condition?: (...args: any[]) => boolean): boolean;
    find(name: string): IModule | undefined;
    findAll(name: string): IModule[];
    willLog(name: string): boolean;
    ignoreLog(values: boolean | string | string[]): void;
    collectLog(level?: boolean): LogStatus<StatusType>[];
    pauseLog(type?: string): void;
    resumeLog(type?: string): void;
    hasLog(type: string): boolean;
    delayMessage(...args: unknown[]): void;
    willAbort(value: string | IModule): boolean;
    loadModule(name: string, ...args: any[]): IModule | null;
    retain(process: IModule): void;
    release(process: IModule, log?: boolean): boolean;
    restart(...args: unknown[]): void;
    joinQueue(options?: JoinQueueOptions): boolean;
    updateProgress(name: string, ...args: unknown[]): void;
    resumeThread?(options: ResumeThreadOptions): void;
    set host(value);
    get host(): null;
    get config(): Readonly<HostInitConfig>;
    get username(): string;
    get ipV4(): string;
    get ipV6(): string;
    set done(value);
    get done(): boolean;
    get queued(): boolean;
    get logState(): LogState;
    get errorCount(): number;
}

interface HostConstructor extends ModuleConstructor {
    loadSettings(settings: Settings, password?: string): boolean;
    loadSettings(settings: Settings, permission?: PermissionReadWrite, password?: string): boolean;
    isPermission(value: unknown): value is IPermission;
    createPermission(all?: boolean, freeze?: boolean): IPermission;
    kill(username: string, all: true): number;
    kill(username: string, pid: number | number[]): number;
    kill(username: string, iv: BinaryLike, all: true): number;
    kill(username: string, iv: BinaryLike, pid: number | number[]): number;
    getThreadCount(full: true): ThreadCountStat;
    getThreadCount(username: string, iv?: BinaryLike): ThreadCountStat;
    getThreadCount(username?: string | boolean, iv?: BinaryLike): number;
    parseIp(value: unknown, kind?: "ipv4" | "ipv6"): string;
    getPermissionFromSettings(freeze?: boolean): IPermission;
    readonly prototype: IHost;
    new(config?: HostInitConfig): IHost;
}

interface IClient extends IModule<IHost> {
    module: ClientModule;
    init(...args: unknown[]): this;
    getUserSettings(): unknown;
    extensionsOf(type?: string, cache?: boolean): Function[];
    get settings(): ClientSettings;
    set cacheDir(value: string);
    get cacheDir(): string;
    set extensions(values: unknown[]);
    get extensions(): ((...args: unknown[]) => unknown)[];
}

interface ClientConstructor extends ModuleConstructor {
    signExtensionType(method: FunctionReturn, ...type: string[]): FunctionReturn;
    readonly prototype: IClient;
    new(module?: ClientModule): IClient;
}

interface IClientDb extends IClient<IHost, ClientModule<ClientDbSettings>> {
    database: DataSource[];
    cacheExpires: number;
    add(item: DataSource, state?: number): void;
    hasCache(source: string, sessionKey?: string): boolean;
    hasCoerce(source: string, component: keyof DbCoerceSettings, uuidKey: string | undefined): boolean;
    hasCoerce(source: string, component: keyof DbCoerceSettings, credential?: unknown): boolean;
    getQueryResult(source: string, credential: unknown, queryString: string, options: CacheOptions): QueryResult | undefined;
    getQueryResult(source: string, credential: unknown, queryString: string, renewCache: boolean): QueryResult | undefined;
    getQueryResult(source: string, credential: unknown, queryString: string, sessionKey?: string, renewCache?: boolean): QueryResult | undefined;
    setQueryResult(source: string, credential: unknown, queryString: string, result: unknown, options: CacheOptions): QueryResult;
    setQueryResult(source: string, credential: unknown, queryString: string, result: unknown, sessionKey?: string): QueryResult;
    getCacheResult(source: string, credential: unknown, queryString: string, cacheValue: CacheOptions, ignoreCache?: unknown): QueryResult | undefined;
    applyState(items: DataSource | DataSource[], value: number, as?: boolean): void;
    commit(items?: DataSource[]): Promise<boolean>;
    valueOfKey(credential: unknown, name: keyof DbSourceOptions, component?: string): unknown;
    settingsOf(source: string, name: keyof DbSourceOptions, component?: string): unknown;
    settingsKey(uuidKey: string, name: keyof DbSourceOptions, component?: string): unknown;
    get pending(): DataSource[];
    get committed(): DataSource[];
    get failed(): DataSource[];
}

interface ClientDbConstructor extends ClientConstructor<IHost, ClientModule> {
    STORE_RESULT_PARTITION_SIZE: number;
    STORE_RESULT_PARTITION_MULT: number;
    readonly TRANSACTION_ACTIVE: number;
    readonly TRANSACTION_PARTIAL: number;
    readonly TRANSACTION_COMMIT: number;
    readonly TRANSACTION_TERMINATE: number;
    readonly TRANSACTION_ABORT: number;
    readonly TRANSACTION_FAIL: number;
    readonly HASH_ALGORITHM: string | undefined;
    loadSettings(settings: Pick<Settings, "process" | "memory">, password?: string) : boolean;
    getTimeout(value: number | string | TimeoutAction | undefined): number;
    convertTime(value: number | string): number;
    findResult(source: string, credential: unknown, queryString: string, timeout: number, renewCache: boolean): QueryResult | undefined;
    findResult(source: string, credential: unknown, queryString: string, timeout: number, sessionKey?: string, renewCache?: boolean): QueryResult | undefined;
    storeResult(source: string, credential: unknown, queryString: string, result: QueryResult, options: StoreResultOptions): QueryResult;
    storeResult(source: string, credential: unknown, queryString: string, result: QueryResult, cache: DbCacheValue): QueryResult;
    storeResult(source: string, credential: unknown, queryString: string, result: QueryResult, cache: DbCacheValue | undefined, options?: StoreResultOptions): QueryResult;
    storeResult(source: string, credential: unknown, queryString: string, result: QueryResult, sessionKey?: string, sessionExpires?: number): QueryResult;
    findSession(source: string, user: string, key: string): unknown;
    storeSession(source: string, user: string, key: string, result: unknown, expires?: number): void;
    purgeResult(prefix?: string, lru?: boolean | number): Promise<number>;
    extractUUID(credential: unknown): string;
    setPoolConfig(value: unknown): void;
    getPoolConfig(source: string): unknown;
    keyOfResult(source: string, credential: unknown, uuidOnly?: boolean): string;
    readonly prototype: IClientDb;
    new(module?: ClientModule, database?: DataSource[]): IClientDb;
}

interface IWorkerGroup {
    [Symbol.iterator](): IterableIterator<IWorkerChannel>;
    add(name: string, item: IWorkerChannel, priority?: number): this;
    get(name: string, force?: boolean | number): IWorkerChannel | undefined;
    delete(name: string | IWorkerChannel): boolean;
    free(count?: number): number;
    print(format: "stats" | "errors"): void;
    clear(): void;
    set max(value);
    get max(): number;
    get workers(): IWorkerChannel[];
    get pending(): number;
    get available(): number;
    get errors(): WorkerChannelError[];
    get size(): number;
    get sizeOf(): number;
}

interface WorkerGroupConstructor {
    checkTimeout(value: number, active?: boolean): number;
    readonly prototype: IWorkerGroup;
    new(max?: number, locked?: boolean): IWorkerGroup;
}

interface IWorkerChannel extends EventEmitter {
    [Symbol.iterator](): IterableIterator<Worker>;
    sendObject(data: unknown, transferList?: TransferListItem[], callback?: WorkerChannelResponse<unknown>, ...returnArgs: unknown[]): Worker;
    sendBuffer(data: Buffer, shared?: boolean, callback?: WorkerChannelResponse<unknown>, ...returnArgs: unknown[]): Worker | null;
    send(data: unknown, transferList?: TransferListItem[]): Promise<unknown>;
    drop(count?: number): Promise<number>;
    join(group: IWorkerGroup, label?: string): void;
    quit(): void;
    kill(count?: number): Promise<number>;
    lock(): void;
    isEmpty(): boolean;
    set min(value);
    get min(): number;
    set max(value);
    get max(): number;
    set timeoutMs(value);
    get timeoutMs(): number;
    get filename(): string;
    get workers(): Worker[];
    get detached(): boolean;
    get lastAccessed(): Date;
    get timesAccessed(): number;
    get frequencyAccessed(): number;
    get pending(): number;
    get available(): number;
    get size(): number;

    /* EventEmitter */
    on(event: "error" | "messageerror" | "abort", listener: (err: Error) => void): this;
    on(event: "exit", listener: (exitCode: number) => void): this;
    on(event: "online", listener: () => void): this;
    on(event: "message", listener: (value: any) => void): this;
    on(event: "data", listener: (data: unknown) => void): this;
    on(event: "pass", listener: (data: unknown, transferList: TransferListItem[] | undefined) => void): this;
    once(event: "error" | "messageerror" | "abort", listener: (err: Error) => void): this;
    once(event: "exit", listener: (exitCode: number) => void): this;
    once(event: "online", listener: () => void): this;
    once(event: "message", listener: (value: any) => void): this;
    once(event: "data", listener: (data: unknown) => void): this;
    once(event: "pass", listener: (data: unknown, transferList: TransferListItem[] | undefined) => void): this;
}

interface WorkerChannelConstructor {
    create(filename: string, name: string): IWorkerChannel;
    create(filename: string, options?: WorkerOptions, name?: string): IWorkerChannel;
    hasPermission(options?: WorkerAction): boolean;
    readonly prototype: IWorkerChannel;
    new(filename: string, max?: number, timeoutMs?: number): IWorkerChannel;
}

interface IAbortComponent extends AbortController {
    reset(): void;
    get aborted(): boolean;
}

interface AbortComponentConstructor {
    attach(instance: IAbortComponent, signal: AbortSignal, options?: AddEventListenerOptions): void;
    detach(instance: IAbortComponent, signal: AbortSignal): void;
    readonly prototype: IAbortComponent;
    new(): IAbortComponent;
}

interface IPermission {
    setDiskRead(enabled: boolean): void;
    setDiskRead(pathname?: string | string[], enabled?: boolean): void;
    setDiskWrite(enabled: boolean): void;
    setDiskWrite(pathname?: string | string[], enabled?: boolean): void;
    setUNCRead(enabled: boolean): void;
    setUNCRead(pathname?: string | string[], enabled?: boolean): void;
    setUNCWrite(enabled: boolean): void;
    setUNCWrite(pathname?: string | string[], enabled?: boolean): void;
    getDiskRead(): string | string[];
    getDiskWrite(): string | string[];
    getUNCRead(): string | string[];
    getUNCWrite(): string | string[];
    hasDiskRead(pathname: string): boolean;
    hasDiskWrite(pathname: string): boolean;
    hasUNCRead(pathname: string): boolean;
    hasUNCWrite(pathname: string): boolean;
    get diskRead(): boolean;
    get diskWrite(): boolean;
    get uncRead(): boolean;
    get uncWrite(): boolean;
}

Changelog

Added in version 0.14.0:

• ClientDbConstructor property getter HASH_ALGORITHM for results cache key generation was created.

• IClient function extensionsOf for type-based instance processing was created.

• ClientConstructor function signExtensionType for grouping extensions in a series was created.

Added in version 0.13.7:

• HostConstructor function parseIp for IPV4/IPV6 conversion was created.

Note

Backported: 0.12.15

Changed in version 0.13.7:

• HostConstructor property cacheDir can be permanently locked.

Added in version 0.13.6:

• ClientDbConstructor function storeSession | findSession for single expiration based caching was created.

Changed in version 0.13.6:

• ClientDbConstructor function purgeResult argument lru as boolean | number can initiate garbage collection by source provider.

Changed in version 0.13.6:

• BREAKING IClientDb function setQueryResult did not apply property cacheDir when memory permission was disabled.

Note

Backported: 0.12.15 / 0.11.15 / 0.10.19 / 0.9.28 / 0.8.29

Changed in version 0.13.5:

• BREAKING HostConstructor function getPermissionFromSettings returns a completely frozen Permission global instance. Any attempt to modify the object will silently be denied access.

Note

Backported: 0.12.13 / 0.11.13 / 0.10.17 / 0.9.25 / 0.8.28

Added in version 0.12.0:

• IWorkerChannel and WorkerChannelConstructor were created.

• IWorkerGroup and WorkerGroupConstructor were created.

Changed in version 0.12.0:

• BREAKING Permission glob matchers picomatch | minimatch do not set any initial options other than nocase for Windows.

• HostConstructor function kill can be called without iv when using a pre-encrypted username.

• IPermission function setters can be called with a boolean:

  setDiskRead

  setDiskWrite

  setUNCRead

  setUNCWrite

Added in version 0.11.0:

• IHost property getters ipV4 | ipV6 for remote client address were created.

Added in version 0.10.0:

• IClientDb function getCacheResult was created.

Changed in version 0.10.0:

• IHost function pauseLog | resumeLog argument type as string was implemented.

Added in version 0.9.0:

• IHost function were created:

  pauseLog delayMessage

  resumeLog

  hasLog

  updateProgress

• IHost property getter logState was created.

Removed in version 0.9.0:

• IClientDb function hasCache argument override as DbCacheValue.

• IClientDb function hasCoerce argument override as DbCoerceValue.

Settings

View JSON

import type { ExecOptions } from "./settings";

import type { MinimatchOptions } from "minimatch";
import type { PicomatchOptions } from "picomatch";

interface ProcessModule {
    thread?: {
        admin: {
            users?: string[];
            private?: boolean;
        };
        queue?: {
            limit?: number;
            expires?: number | string;
            priority: {
                bypass?: number;
                min?: number;
                max?: number;
            };
        };
        worker?: {
            users?: boolean | string[];
            max?: number | string;
            locked?: boolean;
            channel?: { min?: number; max?: number; expires?: number | string; verbose?: boolean };
        };
        limit?: number | string;
        sub_limit?: number | string;
        expires?: number | string;
    };
}

interface PermissionModule {
    disk_read?: string | string[];
    disk_write?: string | string[];
    unc_read?: string | string[];
    unc_write?: string | string[];
    settings?: {
        broadcast_id?: string | string[];
        picomatch?: PicomatchOptions | null;
        minimatch?: MinimatchOptions | null;
    };
}

Changelog

Added in version 0.12.0:

• ProcessModule property group workers for channel throttling was implemented.

Example usage

Abstract class

const { Host } = require("@e-mc/core");

Host.loadSettings({ // Global
  process: {
    thread: { limit: 8 }
  },
  permission: {
    disk_read: ["**/*"],
    disk_write: ["/tmp/**"]
  }
});

Attention

@e-mc/core is mostly a collection of abstract base classes which cannot be instantiated. Host is more commonly called through @e-mc/file-manager.

References

• https://www.unpkg.com/@e-mc/types/lib/squared.d.ts

• https://www.unpkg.com/@e-mc/types/lib/core.d.ts

• https://www.unpkg.com/@e-mc/types/lib/db.d.ts

• https://www.unpkg.com/@e-mc/types/lib/dom.d.ts

• https://www.unpkg.com/@e-mc/types/lib/logger.d.ts

• https://www.unpkg.com/@e-mc/types/lib/node.d.ts

• https://www.unpkg.com/@e-mc/types/lib/settings.d.ts

• https://www.npmjs.com/package/@types/node

• https://www.npmjs.com/package/minimatch

• https://www.npmjs.com/package/picomatch