@matter/general 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/environment/RuntimeService.ts

@@ -0,0 +1,301 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic } from "../log/Diagnostic.js";
+import { DiagnosticSource } from "../log/DiagnosticSource.js";
+import { Logger } from "../log/Logger.js";
+import { Construction, type Constructable } from "../util/Construction.js";
+import { Cancellable, Destructable, Lifecycle } from "../util/Lifecycle.js";
+import { Multiplex } from "../util/Multiplex.js";
+import { Observable } from "../util/Observable.js";
+import type { Environment } from "./Environment.js";
+import { Environmental } from "./Environmental.js";
+
+const logger = Logger.get("Runtime");
+
+/**
+ * Handles lifecycle management of other components.
+ */
+export class RuntimeService implements Multiplex {
+    #workers = new Set<RuntimeService.Worker>();
+    #cancelled = new Set<RuntimeService.Worker>();
+    #workerDeleted = Observable<[]>();
+    #canceled = false;
+    #started = Observable<[]>();
+    #stopped = Observable<[]>();
+    #crashed = Observable<[cause: any]>();
+
+    constructor(environment: Environment) {
+        environment.set(RuntimeService, this);
+        DiagnosticSource.add(this);
+    }
+
+    /**
+     * Add a {@link Worker}.
+     *
+     * The runtime considers itself "active" if there are one or more workers installed.
+     *
+     * A worker must either be {@link PromiseLike} or {@link Constructable} for the runtime to detect completion. On
+     * completion the worker is removed and destroyed if the worker is {@link Destructable}.
+     *
+     * Once added, the {@link worker} is owned by the RuntimeService until closed, resolved or removed via
+     * {@link delete}.
+     */
+    add(worker: RuntimeService.Worker | void) {
+        if (!worker) {
+            return;
+        }
+
+        if (this.#workers.has(worker)) {
+            return;
+        }
+
+        this.#workers.add(worker);
+        if (this.#workers.size === 1) {
+            this.#started.emit();
+        }
+
+        // For PromiseLike just track until resolution
+        if (worker.then) {
+            Promise.resolve(worker)
+                .catch(error => this.#crash(error))
+                .finally(() => this.delete(worker));
+            return;
+        }
+
+        if (worker.construction?.change) {
+            // Constructable
+            worker.construction.change.on(status => {
+                switch (status) {
+                    case Lifecycle.Status.Crashed:
+                        this.#crash();
+                        break;
+
+                    case Lifecycle.Status.Destroyed:
+                        this.delete(worker);
+                        break;
+                }
+            });
+        } else if (worker.then) {
+            if (worker.then) {
+                Promise.resolve(worker)
+                    .catch(error => this.#crash(error))
+                    .finally(() => this.delete(worker));
+            }
+        }
+    }
+
+    /**
+     * Remove a worker.
+     */
+    delete(worker: RuntimeService.Worker) {
+        if (!this.#workers.has(worker)) {
+            return;
+        }
+
+        // Remove the worker
+        this.#workers.delete(worker);
+        this.#cancelled.delete(worker);
+        this.#workerDeleted.emit();
+
+        // If there are still non-helper workers, remain in active state
+        if (this.#workers.size) {
+            return;
+        }
+
+        // No workers except helpers; cancel helpers and exit
+        this.cancel();
+
+        // Emit stopped event when all activity stops.  Safe to ignore rejection because this promise can't reject
+        void this.inactive.finally(() => this.#stopped.emit());
+    }
+
+    /**
+     * Emits when a worker is added when previously there were none.
+     */
+    get started() {
+        return this.#started;
+    }
+
+    /**
+     * Emits when the last worker departs.
+     */
+    get stopped() {
+        return this.#stopped;
+    }
+
+    /**
+     * Emits when a worker experiences an unhandled error.
+     */
+    get crashed() {
+        return this.#crashed;
+    }
+
+    static [Environmental.create](environment: Environment) {
+        return new this(environment);
+    }
+
+    /**
+     * Cancel execution.
+     *
+     * On cancel the runtime destroys all workers.
+     */
+    cancel() {
+        if (this.#canceled) {
+            return;
+        }
+        this.#canceled = true;
+        logger.notice("Shutting down");
+
+        for (const worker of this.#workers) {
+            const disposal = this.#cancelWorker(worker);
+            if (disposal) {
+                this.add(disposal);
+            }
+        }
+    }
+
+    /**
+     * Resolves when no workers are active.
+     */
+    get inactive() {
+        if (!this.#workers.size) {
+            return Promise.resolve();
+        }
+
+        return new Promise<void>(resolve => {
+            const listener = () => {
+                if (!this.#workers.size) {
+                    this.#workerDeleted.off(listener);
+                    resolve();
+                }
+            };
+            this.#workerDeleted.on(listener);
+        });
+    }
+
+    async close() {
+        this.cancel();
+        await this.inactive;
+        DiagnosticSource.delete(this);
+    }
+
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+
+    get [Diagnostic.value]() {
+        return Diagnostic.node("🛠", "Workers", {
+            children: [...this.#workers].map(worker => {
+                let diagnostic: unknown = worker[RuntimeService.label];
+
+                if (diagnostic === undefined) {
+                    diagnostic = worker[Diagnostic.value];
+
+                    if (diagnostic === undefined) {
+                        diagnostic = worker.toString();
+                    }
+                }
+
+                return diagnostic;
+            }),
+        });
+    }
+
+    #cancelWorker(worker: RuntimeService.Worker) {
+        if (this.#cancelled.has(worker)) {
+            return;
+        }
+
+        const cancel = () => {
+            this.#cancelled.add(worker);
+
+            if (worker.close) {
+                this.#cancelled.add(worker);
+                return Promise.resolve(worker.close()).finally(() => this.delete(worker));
+            }
+
+            if (worker[Symbol.asyncDispose]) {
+                this.#cancelled.add(worker);
+                return Promise.resolve(worker[Symbol.asyncDispose]?.()).finally(() => this.delete(worker));
+            }
+
+            if (worker[Symbol.dispose]) {
+                worker[Symbol.dispose]?.();
+                this.delete(worker);
+                return;
+            }
+
+            // No means of cancellation so we just need to wait for the worker to exit
+        };
+
+        if (worker.construction) {
+            worker.construction.onSuccess(cancel);
+            return;
+        }
+
+        return cancel();
+    }
+
+    #crash(cause?: Error) {
+        if (cause) {
+            logger.error(cause);
+        }
+        this.crashed.emit(cause);
+        this.cancel();
+    }
+}
+
+export namespace RuntimeService {
+    export const label = Symbol("label");
+
+    /**
+     * The runtime tracks individual discrete tasks as "workers".
+     *
+     * The state of the runtime is dependent on installed workers.  Any JS object may be a worker but the runtime's
+     * interaction with workers varies as documented here.
+     *
+     * If a worker is a {@link PromiseLike} the runtime will delete and/or destroy it on completion.
+     */
+    export interface Worker extends Partial<PromiseLike<any>>, Partial<Cancellable>, Partial<Destructable> {
+        /**
+         * If the worker supports {@link Construction}, the runtime will monitor the worker's lifecycle:
+         *
+         *   - If the worker crashed (e.g. experiences an error during initialization) the runtime will cancel all
+         *     workers and exit
+         *
+         *   - If the worker is destroyed the runtime deletes it from the set of known workers
+         */
+        construction?: Construction<any>;
+
+        /**
+         * If the worker supports {@link Symbol.asyncDispose} the runtime will invoke when the worker is no longer
+         * needed.  This happens if:
+         *
+         *   - The worker is a {@link PromiseLike} that resolves
+         *
+         *   - The worker's {@link construction} status changed as noted above
+         *
+         *   - The runtime is canceled via {@link RuntimeService.cancel}
+         */
+        [Symbol.asyncDispose]?: () => void | Promise<void>;
+
+        /**
+         * Workers may implement {@link Symbol.dispose} to handle disposal.  Works the same as the async equivalent.
+         */
+        [Symbol.dispose]?: () => void;
+
+        /**
+         * If label is present, it will be presented in diagnostics.  This takes precedence over [Diagnostic.value].
+         */
+        [label]?: unknown;
+
+        /**
+         * In diagnostics workers render using toString() unless they provide explicit diagnostics.
+         */
+        [Diagnostic.value]?: unknown;
+    }
+}

package/src/environment/VariableService.ts

@@ -0,0 +1,308 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "../MatterError.js";
+import { Diagnostic } from "../log/Diagnostic.js";
+import { isObject } from "../util/Type.js";
+import type { Environment } from "./Environment.js";
+import { Environmental } from "./Environmental.js";
+
+/**
+ * Environmental configuration values.
+ */
+export class VariableService {
+    #vars = {} as VariableService.Map;
+    #usageCollectors = Array<Set<string>>();
+    #usages = new Set<VariableService.Usage>();
+
+    constructor(environment: Environment) {
+        environment.set(VariableService, this);
+    }
+
+    static [Environmental.create](environment: Environment) {
+        return new this(environment);
+    }
+
+    get [Diagnostic.value]() {
+        return "Configuration";
+    }
+
+    get vars() {
+        return this.#vars;
+    }
+
+    /**
+     * Configure a component.
+     *
+     * Runs the supplied {@link configurator} immediately and whenever variables reference by the {@link configurator}
+     * change.
+     *
+     * To terminate reconfiguration invoke {@link VariableService.Usage.close} on the return value.
+     */
+    use(configurator: () => void): VariableService.Usage {
+        const variables = new Set<string>();
+        try {
+            this.#usageCollectors.push(variables);
+            configurator();
+        } finally {
+            this.#usageCollectors.pop();
+        }
+
+        const usage = {
+            variables,
+            configurator,
+            close: () => {
+                this.#usages.delete(usage);
+            },
+        };
+        this.#usages.add(usage);
+
+        return usage;
+    }
+
+    get<T extends VariableService.Primitive>(name: string, fallback?: T): T;
+
+    get<T extends VariableService.Value>(name: string, fallback: T): T;
+
+    get<T extends VariableService.Value>(name: string): T | undefined;
+
+    get(name: string, fallback?: VariableService.Value) {
+        for (const collector of this.#usageCollectors) {
+            collector.add(name);
+        }
+
+        switch (typeof fallback) {
+            case "string":
+                return this.string(name) ?? fallback;
+
+            case "number":
+                return this.number(name) ?? fallback;
+
+            case "boolean":
+                return this.boolean(name) ?? fallback;
+        }
+
+        let value: VariableService.Value = this.#vars;
+        for (const segment of this.#parseName(name)) {
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                return fallback;
+            }
+            value = value[segment];
+        }
+        return value ?? fallback;
+    }
+
+    has(name: string) {
+        return this.get(name) !== undefined;
+    }
+
+    set(name: string, value: VariableService.Value) {
+        const segments = name.toLowerCase().split(".");
+        const key = segments.pop() as string;
+        let parent: VariableService.Map = this.#vars;
+        for (const segment of segments) {
+            let nextParent = parent[segment];
+            if (nextParent === undefined || nextParent === null) {
+                nextParent = parent[segment] = {};
+            } else if (typeof nextParent !== "object" || Array.isArray(nextParent)) {
+                throw new ImplementationError(`Can't set ${name} because segment ${segment} is not a map`);
+            }
+            parent = nextParent;
+        }
+
+        if (parent[key] === value) {
+            return;
+        }
+
+        parent[key] = value;
+
+        for (const usage of this.#usages) {
+            if (usage.variables.has(name)) {
+                usage.configurator();
+            }
+        }
+    }
+
+    string(name: string) {
+        const value = this.get(name);
+        if (value === undefined) {
+            return value;
+        }
+        if (typeof value === "string") {
+            return value;
+        }
+        if (value === null) {
+            return "null";
+        }
+        return value.toString();
+    }
+
+    boolean(name: string) {
+        const value = this.get(name);
+        switch (value) {
+            case undefined:
+                return value;
+
+            case null:
+            case 0:
+            case false:
+            case "false":
+            case "off":
+                return false;
+
+            default:
+                return true;
+        }
+    }
+
+    number(name: string) {
+        let value = this.get(name);
+        if (typeof value === "number") {
+            return value;
+        }
+        if (typeof value === "string") {
+            value = Number.parseFloat(value);
+            if (Number.isNaN(value)) {
+                return;
+            }
+            return value;
+        }
+    }
+
+    integer(name: string, fallback?: number) {
+        const number = this.number(name) ?? fallback;
+        if (typeof number === "number") {
+            return Math.floor(number);
+        }
+    }
+
+    increment(name: string) {
+        const value = this.integer(name) ?? 0;
+        this.set(name, value + 1);
+        return value;
+    }
+
+    addConfigStyle(vars: VariableService.Map) {
+        const path = Array<string>();
+
+        const add = (vars: VariableService.Map) => {
+            for (const name in vars) {
+                const val = vars[name];
+                if (isObject(val)) {
+                    path.push(name);
+                    add(val);
+                    path.pop();
+                } else {
+                    this.set([...path, name].join("."), val);
+                }
+            }
+        };
+
+        add(vars);
+    }
+
+    addUnixEnvStyle(vars: Record<string, string | undefined>) {
+        this.addConfigStyle(parseUnixStyle(vars));
+    }
+
+    addArgvStyle(vars: string[]) {
+        this.addConfigStyle(parseArgvStyle(vars));
+    }
+
+    #parseName(name: string) {
+        return name
+            .toLowerCase()
+            .split(".")
+            .map(segment => {
+                segment = segment.trim();
+                if (segment === "") {
+                    throw new ImplementationError(`Variable name ${name} contains empty segments`);
+                }
+                return segment;
+            });
+    }
+}
+
+export namespace VariableService {
+    export interface Options {
+        unixEnvStyle?: Record<string, string>;
+        argvStyle?: string[];
+        configStyle?: Map;
+    }
+
+    export interface Map extends Record<string, Value> {}
+    export type List = Value[];
+    export type Primitive = number | string | boolean;
+    export type Value = Primitive | Map | List;
+    export interface Usage {
+        variables: Set<string>;
+        configurator(): void;
+        close(): void;
+    }
+}
+
+function addVariable(into: Record<string, any>, path: string[], value: any) {
+    if (!path.length) {
+        return;
+    }
+
+    let current = into[path[0]];
+    if (path.length === 1) {
+        if (current === undefined) {
+            into[path[0]] = value;
+        }
+        return;
+    }
+
+    if (typeof current !== "object") {
+        current = into[path[0]] = {};
+    }
+    addVariable(current, path.slice(1), value);
+}
+
+function parseUnixStyle(values: Record<string, string | undefined>) {
+    const variables = {} as VariableService.Map;
+
+    for (const key in values) {
+        if (key.startsWith("MATTER_")) {
+            if (values[key] === undefined || values[key] === "") {
+                continue;
+            }
+            addVariable(variables, key.slice(7).toLowerCase().split("_"), values[key]);
+        }
+    }
+
+    return variables;
+}
+
+function parseArgvStyle(values: string[]) {
+    const variables = {} as VariableService.Map;
+
+    for (let arg of values) {
+        if (!arg.startsWith("--")) {
+            continue;
+        }
+        arg = arg.slice(2);
+
+        const separatorPos = arg.indexOf("=");
+        let key, value;
+
+        if (separatorPos === -1) {
+            key = arg;
+            value = true;
+        } else {
+            key = arg.slice(0, separatorPos);
+            value = arg.slice(separatorPos + 1);
+            if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+                value = value.slice(1, -1).replaceAll("\\'", "'").replaceAll('\\"', '"');
+            }
+        }
+
+        addVariable(variables, key.toLowerCase().split("-"), value);
+    }
+
+    return variables;
+}

package/src/environment/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Environment.js";
+export * from "./Environmental.js";
+export * from "./RuntimeService.js";
+export * from "./VariableService.js";

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./codec/index.js";
+export * from "./crypto/index.js";
+export * from "./environment/index.js";
+export * from "./log/index.js";
+export * from "./math/index.js";
+export * from "./MatterError.js";
+export * from "./net/index.js";
+export * from "./storage/index.js";
+export * from "./time/index.js";
+export * from "./util/index.js";
+import "./polyfills/index.js";