@rhombus-std/config.core 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Butler
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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/README.md

@@ -0,0 +1,38 @@
+# @rhombus-std/config.core
+
+Types-only configuration abstractions: the `IConfiguration*` interfaces
+(`IConfiguration`, `IConfigurationBuilder`, `IConfigurationRoot`,
+`IConfigurationSection`, `IConfigurationSource`, `IConfigurationProvider`,
+`IConfigurationManager`) plus the `ITryGetResult` tuple type.
+
+This package ships **zero runtime** — no JavaScript, only a `.d.ts` bundle.
+`@rhombus-std/config` and the provider packages (`@rhombus-std/config.json`, `@rhombus-std/config.env`,
+`@rhombus-std/config.commandline`) depend on it for shared interface types via `import
+type`, so those types erase at compile time and never appear in any built
+bundle.
+
+## Install
+
+You generally don't install this package directly — `@rhombus-std/config`
+re-exports every type it defines, and installing `@rhombus-std/config` pulls it
+in as a dependency automatically. Install it explicitly only if you're
+writing a package that implements one of these interfaces (for example a
+custom `IConfigurationSource`) without depending on `@rhombus-std/config`
+itself.
+
+```sh
+npm install @rhombus-std/config.core
+```
+
+## Usage
+
+```ts
+import type {
+  IConfiguration,
+  IConfigurationSource,
+} from "@rhombus-std/config.core";
+
+function readPort(config: IConfiguration): string | undefined {
+  return config.get("Server:Port");
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Propagates notifications that a change has occurred.
+ */
+interface IChangeToken {
+    /**
+     * A value that indicates if a change has occurred.
+     */
+    readonly hasChanged: boolean;
+    /**
+     * A value that indicates whether this token will proactively raise
+     * callbacks. If `false`, the token consumer must poll {@link hasChanged}
+     * to detect changes.
+     *
+     * A `true` value does not guarantee that callbacks will be raised for all
+     * changes. Consumers should also check {@link hasChanged} when complete
+     * accuracy is required.
+     */
+    readonly activeChangeCallbacks: boolean;
+    /**
+     * Registers a callback that will be invoked when the token has changed.
+     * {@link hasChanged} MUST be set before the callback is invoked.
+     *
+     * @param callback The callback to invoke.
+     * @param state State to be passed into the callback.
+     * @returns A {@link Disposable} that is used to unregister the callback.
+     */
+    registerChangeCallback(callback: (state: unknown) => void, state?: unknown): Disposable;
+}
+
+/** Represents a section of application configuration values. */
+interface IConfigurationSection extends IConfiguration {
+    /** The key this section occupies in its parent. */
+    get key(): string;
+    /** The full path to this section within the {@link IConfiguration}. */
+    get path(): string;
+    /** The section value. */
+    get value(): string | undefined;
+    set value(value: string);
+}
+
+/**
+ * A node's subtree as a nested plain string object. A node that has children
+ * is a nested record (its own scalar value, if any, is dropped -- see
+ * {@link IConfiguration.toObject}); a pure leaf is its string value.
+ */
+type ConfigObject = {
+    readonly [key: string]: string | ConfigObject;
+};
+/**
+ * The index-navigable Section type: an {@link IConfigurationSection} whose
+ * unknown string keys resolve to further sections, so `config.Server.Port`
+ * dot/bracket navigation type-checks.
+ *
+ * INLINE self-referential intersection by design -- routing the recursive
+ * self-reference through a generic alias trips TS2456 ("Type alias circularly
+ * references itself"). Real members (`value`, `get`, `getSection`, ...) win
+ * over the index signature; only genuinely-unknown keys resolve to
+ * `IndexedSection`. Under `noUncheckedIndexedAccess` the index-access site
+ * (`config.Server`) types as `IndexedSection | undefined` -- a conservative
+ * false-positive for navigation (runtime always returns a Section for a string
+ * key), by design. The typed path without that tax is a runtime schema
+ * (`ConfigurationBuilder.withSchema`), whose result has named keys and no
+ * index signature.
+ */
+type IndexedSection = IConfigurationSection & {
+    readonly [key: string]: IndexedSection;
+};
+/**
+ * The result of a try-get lookup: `[false]` on a miss, `[true, value]` on a
+ * hit. Replaces ME's `bool TryGet(out string?)` out-param pattern, which has
+ * no direct TS equivalent.
+ */
+type ITryGetResult<T> = [success: false] | [success: true, value: T];
+
+/**
+ * A set of key/value application configuration properties. Every value is a
+ * raw string unless explicitly coerced; navigation always yields a Section and
+ * leaf reads always yield the requested scalar type (no accessor returns a
+ * string for one input and a section for another).
+ */
+interface IConfiguration {
+    /** This node's own value (undefined on the root, or when absent). */
+    readonly value: string | undefined;
+    /** The raw string at a flat colon-delimited path (undefined if absent). */
+    get(path: string): string | undefined;
+    /** A typed leaf via a caller-supplied factory (undefined if the path is absent). */
+    get<T>(path: string, factory: (value: string) => T): T | undefined;
+    /**
+     * Coerces a leaf to a finite number. Returns `dflt` (or undefined) when the
+     * path is absent; THROWS when the path is present but not a finite number.
+     */
+    getNum(path: string): number | undefined;
+    getNum(path: string, dflt: number): number;
+    /**
+     * Coerces a leaf to a boolean, LIBERAL and case-insensitive (true/1/yes/on
+     * -> true, false/0/no/off -> false). Returns `dflt` (or undefined) when
+     * absent; THROWS when present but unrecognized.
+     */
+    getBool(path: string): boolean | undefined;
+    getBool(path: string, dflt: boolean): boolean;
+    /** Writes a descendant key (index-based writes are not supported). */
+    set(key: string, value: string): this;
+    /**
+     * A sub-section with the specified key. Never returns `null`: a missing key
+     * yields an empty {@link IConfigurationSection}.
+     */
+    getSection(key: string): IConfigurationSection;
+    /** The immediate descendant configuration sub-sections. */
+    getChildren(): Iterable<IConfigurationSection>;
+    /** This node's subtree as a nested plain string object. */
+    toObject(): ConfigObject;
+    /**
+     * A token that fires when this configuration is reloaded -- the root
+     * composes its providers' tokens into its own; a section delegates to its
+     * root.
+     */
+    getReloadToken(): IChangeToken;
+}
+
+/** Provides configuration key/values for an application. */
+interface IConfigurationProvider {
+    /** Tries to get a configuration value for the specified key. */
+    tryGet(key: string): ITryGetResult<string>;
+    /** Sets a configuration value for the specified key. */
+    set(key: string, value?: string): void;
+    /**
+     * Attempts to get an {@link IChangeToken} for change tracking. Returns a
+     * token if this provider supports change tracking.
+     */
+    getReloadToken(): IChangeToken;
+    /** Loads configuration values from the source represented by this provider. */
+    load(): void;
+    /**
+     * Returns the immediate descendant configuration keys for a given parent
+     * path based on the data of this provider and the set of keys returned by
+     * all the preceding providers.
+     *
+     * @param earlierKeys The child keys returned by the preceding providers for the same parent path.
+     * @param parentPath The parent path.
+     */
+    getChildKeys(earlierKeys: Iterable<string>, parentPath?: string): Iterable<string>;
+}
+
+/** Represents the root of an {@link IConfiguration} hierarchy. */
+interface IConfigurationRoot extends IConfiguration {
+    /**
+     * Forces the configuration values to be reloaded from the underlying
+     * {@link IConfigurationProvider} providers.
+     */
+    reload(): void;
+    /** The {@link IConfigurationProvider} providers for this configuration. */
+    get providers(): Iterable<IConfigurationProvider>;
+}
+
+/** Represents a source of configuration key/values for an application. */
+interface IConfigurationSource {
+    /** Builds the {@link IConfigurationProvider} for this source. */
+    build(builder: IConfigurationBuilder): IConfigurationProvider;
+}
+
+/** Represents a type used to build application configuration. */
+interface IConfigurationBuilder {
+    /** The sources used to obtain configuration values. */
+    get sources(): readonly IConfigurationSource[];
+    /** Adds a new configuration source. Returns the same {@link IConfigurationBuilder}. */
+    add(source: IConfigurationSource): IConfigurationBuilder;
+    /**
+     * Builds an {@link IConfiguration} with keys and values from the set of
+     * sources registered in {@link IConfigurationBuilder.sources}.
+     */
+    build(): IConfigurationRoot;
+}
+
+/**
+ * Represents a mutable configuration object. It is both an
+ * {@link IConfigurationBuilder} and an {@link IConfiguration} -- as sources
+ * are added, it updates its current view of configuration.
+ */
+interface IConfigurationManager extends IConfiguration, IConfigurationBuilder {
+}
+
+export type { ConfigObject, IConfiguration, IConfigurationBuilder, IConfigurationManager, IConfigurationProvider, IConfigurationRoot, IConfigurationSection, IConfigurationSource, ITryGetResult, IndexedSection };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@rhombus-std/config.core",
+  "version": "0.0.0-alpha.0",
+  "description": "Types-only configuration abstractions: the IConfiguration* interfaces and ITryGetResult. Zero runtime; depends on @rhombus-std/primitives for the IChangeToken type only.",
+  "keywords": [
+    "configuration",
+    "config",
+    "abstractions",
+    "types",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fnioc/std.git",
+    "directory": "libraries/config.core"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@rhombus-std/primitives": "0.0.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun build.ts",
+    "lint": "bun x tsc --noEmit -p tsconfig.json"
+  }
+}