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

package/dist/esm/environment/Environment.js

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DiagnosticSource } from "../log/DiagnosticSource.js";
+import { Logger } from "../log/Logger.js";
+import "../polyfills/disposable.js";
+import { Time } from "../time/Time.js";
+import { UnsupportedDependencyError } from "../util/Lifecycle.js";
+import { Observable } from "../util/Observable.js";
+import { Environmental } from "./Environmental.js";
+import { RuntimeService } from "./RuntimeService.js";
+import { VariableService } from "./VariableService.js";
+const logger = Logger.get("Environment");
+class Environment {
+  #services;
+  #name;
+  #parent;
+  #added = Observable();
+  #deleted = Observable();
+  #serviceEvents = /* @__PURE__ */ new Map();
+  constructor(name, parent) {
+    this.#name = name;
+    this.#parent = parent;
+  }
+  /**
+   * Determine if an environmental service is available.
+   */
+  has(type) {
+    return this.#services?.get(type) !== void 0 || (this.#parent?.has(type) ?? false);
+  }
+  /**
+   * Access an environmental service.
+   */
+  get(type) {
+    let instance = this.#services?.get(type) ?? this.#parent?.get(type);
+    if (instance) {
+      return instance;
+    }
+    if (type[Environmental.create]) {
+      this.set(type, instance = type[Environmental.create](this));
+      return instance;
+    }
+    throw new UnsupportedDependencyError(`Required dependency ${type.name}`, "is not available");
+  }
+  /**
+   * Remove an environmental service.
+   *
+   * @param type the class of the service to remove
+   * @param instance optional instance expected, if existing instance does not match it is not deleted
+   */
+  delete(type, instance) {
+    if (instance !== void 0 && this.#services?.get(type) !== instance) {
+      return;
+    }
+    this.#services?.delete(type);
+    this.#parent?.delete(type);
+    this.#deleted.emit(type, instance);
+    const serviceEvents = this.#serviceEvents.get(type);
+    if (serviceEvents) {
+      serviceEvents.deleted.emit(instance);
+    }
+  }
+  /**
+   * Access an environmental service, waiting for any async initialization to complete.
+   */
+  async load(type) {
+    const instance = this.get(type);
+    await instance.construction;
+    return instance;
+  }
+  /**
+   * Install a preinitialized version of an environmental service.
+   */
+  set(type, instance) {
+    if (!this.#services) {
+      this.#services = /* @__PURE__ */ new Map();
+    }
+    this.#services.set(type, instance);
+    this.#added.emit(type, instance);
+    const serviceEvents = this.#serviceEvents.get(type);
+    if (serviceEvents) {
+      serviceEvents.added.emit(instance);
+    }
+  }
+  /**
+   * Name of the environment.
+   */
+  get name() {
+    return this.#name;
+  }
+  /**
+   * Emits on service add.
+   *
+   * Currently only emits for services owned directly by this environment.
+   */
+  get added() {
+    return this.#added;
+  }
+  /**
+   * Emits on service delete.
+   *
+   * Currently only emits for services owned directly by this environment.
+   */
+  get deleted() {
+    return this.#deleted;
+  }
+  /**
+   * Obtain an object with events that trigger when a specific service is added or deleted.
+   *
+   * This is a more convenient way to observe a specific service than {@link added} and {@link deleted}.
+   */
+  eventsFor(type) {
+    let events = this.#serviceEvents.get(type);
+    if (events === void 0) {
+      events = {
+        added: new Observable(),
+        deleted: new Observable()
+      };
+      this.#serviceEvents.set(type, events);
+    }
+    return events;
+  }
+  /**
+   * The default environment.
+   *
+   * Currently only emits for services owned directly by this environment.
+   */
+  static get default() {
+    return global;
+  }
+  /**
+   * Set the default environment.
+   */
+  static set default(env) {
+    global = env;
+    env.vars.use(() => {
+      Logger.level = env.vars.get("log.level", Logger.level);
+      Logger.format = env.vars.get("log.format", Logger.format);
+      const stackLimit = global.vars.number("log.stack.limit");
+      if (stackLimit !== void 0) {
+        Error.stackTraceLimit = stackLimit;
+      }
+    });
+  }
+  /**
+   * Shortcut for accessing {@link VariableService.vars}.
+   */
+  get vars() {
+    return this.get(VariableService);
+  }
+  /**
+   * Shortcut for accessing {@link RuntimeService}.
+   */
+  get runtime() {
+    return this.get(RuntimeService);
+  }
+  /**
+   * Display tasks that supply diagnostics.
+   */
+  diagnose() {
+    Time.getTimer("Diagnostics", 0, () => {
+      try {
+        logger.notice("Diagnostics follow", DiagnosticSource);
+      } catch (e) {
+        logger.error(`Unhandled error gathering diagnostics:`, e);
+      }
+    }).start();
+  }
+  loadVariables() {
+    return {};
+  }
+}
+let global = new Environment("default");
+export {
+  Environment
+};
+//# sourceMappingURL=Environment.js.map

package/dist/esm/environment/Environment.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/environment/Environment.ts"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/environment/Environmental.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Diagnostic } from "../log/Diagnostic.js";
+import { Observable } from "../util/Observable.js";
+import type { Environment } from "./Environment.js";
+export declare namespace Environmental {
+    const create: unique symbol;
+    /**
+     * An "environmental service" is an object available via {@link Environment.get}.
+     *
+     * Any object may be an environmental service.  This methods in this interface are optional.
+     */
+    interface Service {
+        /**
+         * Asynchronous construction, respected by {@link Environment.load}.
+         */
+        construction?: Promise<any>;
+        /**
+         * Asynchronous destruction.  Invoked by the environment when it is destroyed.
+         */
+        [Symbol.asyncDispose]?: () => Promise<any>;
+        /**
+         * Standard diagnostic presentation.
+         */
+        [Diagnostic.presentation]?: Diagnostic.Presentation;
+        /**
+         * Standard diagnostic value.
+         */
+        [Diagnostic.value]?: unknown;
+    }
+    /**
+     * A factory for a {@link Service}.  Any constructor may be a service factory.
+     */
+    interface Factory<T extends Service> {
+        new (...args: any[]): T;
+        /**
+         * The environment will create the service automatically if the factory supports {@link create}.
+         */
+        [create]?: (environment: Environment) => T;
+    }
+    /**
+     * Events related to service lifecycle.
+     */
+    interface ServiceEvents<T extends abstract new (...args: any[]) => T> {
+        added: Observable<[instance: InstanceType<T>]>;
+        deleted: Observable<[instance: InstanceType<T>]>;
+    }
+}
+//# sourceMappingURL=Environmental.d.ts.map

package/dist/esm/environment/Environmental.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Environmental.d.ts","sourceRoot":"","sources":["../../../src/environment/Environmental.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,yBAAiB,aAAa,CAAC;IACpB,MAAM,MAAM,eAAmB,CAAC;IAEvC;;;;OAIG;IACH,UAAiB,OAAO;QACpB;;WAEG;QACH,YAAY,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAE5B;;WAEG;QACH,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAE3C;;WAEG;QACH,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC;QAEpD;;WAEG;QACH,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;KAChC;IAED;;OAEG;IACH,UAAiB,OAAO,CAAC,CAAC,SAAS,OAAO;QACtC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAExB;;WAEG;QACH,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,CAAC,CAAC;KAC9C;IAED;;OAEG;IACH,UAAiB,aAAa,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC;QACvE,KAAK,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACpD;CACJ"}

package/dist/esm/environment/Environmental.js

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var Environmental;
+((Environmental2) => {
+  Environmental2.create = Symbol("create");
+})(Environmental || (Environmental = {}));
+export {
+  Environmental
+};
+//# sourceMappingURL=Environmental.js.map

package/dist/esm/environment/Environmental.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/environment/Environmental.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,IAAU;AAAA,CAAV,CAAUA,mBAAV;AACI,EAAMA,eAAA,SAAS,OAAO,QAAQ;AAAA,GADxB;",
+  "names": ["Environmental"]
+}

package/dist/esm/environment/RuntimeService.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Diagnostic } from "../log/Diagnostic.js";
+import { Construction } from "../util/Construction.js";
+import { Cancellable, Destructable } 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";
+/**
+ * Handles lifecycle management of other components.
+ */
+export declare class RuntimeService implements Multiplex {
+    #private;
+    constructor(environment: Environment);
+    /**
+     * 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): void;
+    /**
+     * Remove a worker.
+     */
+    delete(worker: RuntimeService.Worker): void;
+    /**
+     * Emits when a worker is added when previously there were none.
+     */
+    get started(): Observable<[], void>;
+    /**
+     * Emits when the last worker departs.
+     */
+    get stopped(): Observable<[], void>;
+    /**
+     * Emits when a worker experiences an unhandled error.
+     */
+    get crashed(): Observable<[cause: any], void>;
+    static [Environmental.create](environment: Environment): RuntimeService;
+    /**
+     * Cancel execution.
+     *
+     * On cancel the runtime destroys all workers.
+     */
+    cancel(): void;
+    /**
+     * Resolves when no workers are active.
+     */
+    get inactive(): Promise<void>;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    get [Diagnostic.value](): unknown[];
+}
+export declare namespace RuntimeService {
+    const label: unique symbol;
+    /**
+     * 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.
+     */
+    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;
+    }
+}
+//# sourceMappingURL=RuntimeService.d.ts.map

package/dist/esm/environment/RuntimeService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeService.d.ts","sourceRoot":"","sources":["../../../src/environment/RuntimeService.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAsB,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,YAAY,EAAa,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInD;;GAEG;AACH,qBAAa,cAAe,YAAW,SAAS;;gBAShC,WAAW,EAAE,WAAW;IAKpC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,GAAG,IAAI;IA4CxC;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM;IAsBpC;;OAEG;IACH,IAAI,OAAO,yBAEV;IAED;;OAEG;IACH,IAAI,OAAO,yBAEV;IAED;;OAEG;IACH,IAAI,OAAO,mCAEV;IAED,MAAM,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,WAAW;IAItD;;;;OAIG;IACH,MAAM;IAeN;;OAEG;IACH,IAAI,QAAQ,kBAcX;IAEK,KAAK;IAMX,CAAC,MAAM,CAAC,YAAY,CAAC;IAIrB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,cAgBrB;CA4CJ;AAED,yBAAiB,cAAc,CAAC;IACrB,MAAM,KAAK,eAAkB,CAAC;IAErC;;;;;;;OAOG;IACH,UAAiB,MAAO,SAAQ,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;QAClG;;;;;;;WAOG;QACH,YAAY,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;QAEjC;;;;;;;;;WASG;QACH,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAEnD;;WAEG;QACH,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC;QAE9B;;WAEG;QACH,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;QAElB;;WAEG;QACH,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;KAChC;CACJ"}

package/dist/esm/environment/RuntimeService.js

@@ -0,0 +1,202 @@
+/**
+ * @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 { Lifecycle } from "../util/Lifecycle.js";
+import { Observable } from "../util/Observable.js";
+import { Environmental } from "./Environmental.js";
+const logger = Logger.get("Runtime");
+class RuntimeService {
+  #workers = /* @__PURE__ */ new Set();
+  #cancelled = /* @__PURE__ */ new Set();
+  #workerDeleted = Observable();
+  #canceled = false;
+  #started = Observable();
+  #stopped = Observable();
+  #crashed = Observable();
+  constructor(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) {
+    if (!worker) {
+      return;
+    }
+    if (this.#workers.has(worker)) {
+      return;
+    }
+    this.#workers.add(worker);
+    if (this.#workers.size === 1) {
+      this.#started.emit();
+    }
+    if (worker.then) {
+      Promise.resolve(worker).catch((error) => this.#crash(error)).finally(() => this.delete(worker));
+      return;
+    }
+    if (worker.construction?.change) {
+      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) {
+    if (!this.#workers.has(worker)) {
+      return;
+    }
+    this.#workers.delete(worker);
+    this.#cancelled.delete(worker);
+    this.#workerDeleted.emit();
+    if (this.#workers.size) {
+      return;
+    }
+    this.cancel();
+    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) {
+    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((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("\u{1F6E0}", "Workers", {
+      children: [...this.#workers].map((worker) => {
+        let diagnostic = worker[RuntimeService.label];
+        if (diagnostic === void 0) {
+          diagnostic = worker[Diagnostic.value];
+          if (diagnostic === void 0) {
+            diagnostic = worker.toString();
+          }
+        }
+        return diagnostic;
+      })
+    });
+  }
+  #cancelWorker(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;
+      }
+    };
+    if (worker.construction) {
+      worker.construction.onSuccess(cancel);
+      return;
+    }
+    return cancel();
+  }
+  #crash(cause) {
+    if (cause) {
+      logger.error(cause);
+    }
+    this.crashed.emit(cause);
+    this.cancel();
+  }
+}
+((RuntimeService2) => {
+  RuntimeService2.label = Symbol("label");
+})(RuntimeService || (RuntimeService = {}));
+export {
+  RuntimeService
+};
+//# sourceMappingURL=RuntimeService.js.map

package/dist/esm/environment/RuntimeService.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/environment/RuntimeService.ts"],
+  "mappings": "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",
+  "names": ["RuntimeService"]
+}

package/dist/esm/environment/VariableService.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Diagnostic } from "../log/Diagnostic.js";
+import type { Environment } from "./Environment.js";
+import { Environmental } from "./Environmental.js";
+/**
+ * Environmental configuration values.
+ */
+export declare class VariableService {
+    #private;
+    constructor(environment: Environment);
+    static [Environmental.create](environment: Environment): VariableService;
+    get [Diagnostic.value](): string;
+    get vars(): VariableService.Map;
+    /**
+     * 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;
+    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;
+    has(name: string): boolean;
+    set(name: string, value: VariableService.Value): void;
+    string(name: string): string;
+    boolean(name: string): boolean;
+    number(name: string): number | undefined;
+    integer(name: string, fallback?: number): number | undefined;
+    increment(name: string): number;
+    addConfigStyle(vars: VariableService.Map): void;
+    addUnixEnvStyle(vars: Record<string, string | undefined>): void;
+    addArgvStyle(vars: string[]): void;
+}
+export declare namespace VariableService {
+    interface Options {
+        unixEnvStyle?: Record<string, string>;
+        argvStyle?: string[];
+        configStyle?: Map;
+    }
+    interface Map extends Record<string, Value> {
+    }
+    type List = Value[];
+    type Primitive = number | string | boolean;
+    type Value = Primitive | Map | List;
+    interface Usage {
+        variables: Set<string>;
+        configurator(): void;
+        close(): void;
+    }
+}
+//# sourceMappingURL=VariableService.d.ts.map

package/dist/esm/environment/VariableService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VariableService.d.ts","sourceRoot":"","sources":["../../../src/environment/VariableService.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;GAEG;AACH,qBAAa,eAAe;;gBAKZ,WAAW,EAAE,WAAW;IAIpC,MAAM,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,WAAW;IAItD,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,WAErB;IAED,IAAI,IAAI,wBAEP;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK;IAqBpD,GAAG,CAAC,CAAC,SAAS,eAAe,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC;IAEvE,GAAG,CAAC,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAElE,GAAG,CAAC,CAAC,SAAS,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IA4BjE,GAAG,CAAC,IAAI,EAAE,MAAM;IAIhB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,CAAC,KAAK;IA2B9C,MAAM,CAAC,IAAI,EAAE,MAAM;IAcnB,OAAO,CAAC,IAAI,EAAE,MAAM;IAkBpB,MAAM,CAAC,IAAI,EAAE,MAAM;IAcnB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAOvC,SAAS,CAAC,IAAI,EAAE,MAAM;IAMtB,cAAc,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG;IAmBxC,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAIxD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE;CAgB9B;AAED,yBAAiB,eAAe,CAAC;IAC7B,UAAiB,OAAO;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,WAAW,CAAC,EAAE,GAAG,CAAC;KACrB;IAED,UAAiB,GAAI,SAAQ,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;KAAG;IACrD,KAAY,IAAI,GAAG,KAAK,EAAE,CAAC;IAC3B,KAAY,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAClD,KAAY,KAAK,GAAG,SAAS,GAAG,GAAG,GAAG,IAAI,CAAC;IAC3C,UAAiB,KAAK;QAClB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACvB,YAAY,IAAI,IAAI,CAAC;QACrB,KAAK,IAAI,IAAI,CAAC;KACjB;CACJ"}