@o3co/ts.hocon 1.7.1 → 1.8.0

package/dist/{config-DCSLXkNY.d.cts → config-D27s3_aG.d.cts}

@@ -13,6 +13,59 @@ type HoconValue = {
     raw: string;
     valueType: ScalarValueType;
 };
+/**
+ * Deeply-immutable view of a {@link HoconValue}. `Config.getValue` returns this
+ * so callers cannot mutate the parsed configuration tree (the live nodes are
+ * shared, not cloned). `Map`/array containers become `ReadonlyMap`/`readonly[]`
+ * recursively, so `.set` / `.push` / element assignment are compile errors.
+ *
+ * `HoconValue` is structurally assignable to `ReadonlyHoconValue`, so internal
+ * code holding a mutable node can return it here, and the accessor functions
+ * below accept both forms.
+ */
+type ReadonlyHoconValue = {
+    readonly kind: 'object';
+    readonly fields: ReadonlyMap<string, ReadonlyHoconValue>;
+} | {
+    readonly kind: 'array';
+    readonly items: readonly ReadonlyHoconValue[];
+} | {
+    readonly kind: 'scalar';
+    readonly raw: string;
+    readonly valueType: ScalarValueType;
+};
+/** Scalar string only (strict): non-string scalars and containers → undefined. */
+declare function asString(v: ReadonlyHoconValue): string | undefined;
+/**
+ * Scalar coerced to a number via {@link coerceNumber} (lenient, matching the
+ * `getNumber` getter: a numeric-looking string scalar coerces too). TS has a
+ * single `number` type, so this unifies rs's `as_i64` + `as_f64`.
+ */
+declare function asNumber(v: ReadonlyHoconValue): number | undefined;
+/** Scalar coerced to a boolean via {@link coerceBoolean} (true/yes/on, false/no/off). */
+declare function asBoolean(v: ReadonlyHoconValue): boolean | undefined;
+/** The object's fields, or undefined if not an object. */
+declare function asObject(v: ReadonlyHoconValue): ReadonlyMap<string, ReadonlyHoconValue> | undefined;
+/** The array's items, or undefined if not an array. */
+declare function asArray(v: ReadonlyHoconValue): readonly ReadonlyHoconValue[] | undefined;
+/** Type guard: narrows to the object variant. */
+declare function isObject(v: ReadonlyHoconValue): v is {
+    readonly kind: 'object';
+    readonly fields: ReadonlyMap<string, ReadonlyHoconValue>;
+};
+/** Type guard: narrows to the array variant. */
+declare function isArray(v: ReadonlyHoconValue): v is {
+    readonly kind: 'array';
+    readonly items: readonly ReadonlyHoconValue[];
+};
+/** Type guard: narrows to the scalar variant. */
+declare function isScalar(v: ReadonlyHoconValue): v is {
+    readonly kind: 'scalar';
+    readonly raw: string;
+    readonly valueType: ScalarValueType;
+};
+/** True for a null scalar. */
+declare function isNull(v: ReadonlyHoconValue): boolean;
 
 interface Segment {
     readonly text: string;
@@ -212,6 +265,20 @@ declare class Config {
         resolveOpts: ResolveOptions$1;
     }): Config;
     get(path: string): unknown;
+    /**
+     * Returns the raw {@link HoconValue} node at `path` as a deeply-immutable
+     * {@link ReadonlyHoconValue} view, or `undefined` if the path is absent. Unlike
+     * `get` (which decodes to a plain JS value), this exposes the value tree for
+     * structural introspection via the `value.ts` accessors (`asString`, `asObject`,
+     * `isScalar`, …).
+     *
+     * `getValue('')` returns the root object node.
+     *
+     * Throws {@link NotResolvedError} when the node (or its subtree) is unresolved:
+     * the `HoconValue` union has no placeholder variant, so an unresolved value
+     * cannot be represented. This matches `getConfig` / `getList`.
+     */
+    getValue(path: string): ReadonlyHoconValue | undefined;
     getString(path: string): string;
     getNumber(path: string): number;
     getBoolean(path: string): boolean;
@@ -273,4 +340,4 @@ declare class Config {
     private requireScalar;
 }
 
-export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ResolveOptions as R, type ScalarValueType as S, type ParseOptions as a, defaultResolveOptions as b, parseAsync as c, defaultParseOptions as d, parseFile as e, parseFileAsync as f, parseFileWithOptions as g, parseString as h, parseStringWithOptions as i, parse as p };
+export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ReadonlyHoconValue as R, type ScalarValueType as S, type ParseOptions as a, type ResolveOptions as b, asArray as c, asBoolean as d, asNumber as e, asObject as f, asString as g, defaultParseOptions as h, defaultResolveOptions as i, isArray as j, isNull as k, isObject as l, isScalar as m, parseAsync as n, parseFile as o, parse as p, parseFileAsync as q, parseFileWithOptions as r, parseString as s, parseStringWithOptions as t };

package/dist/{config-DCSLXkNY.d.ts → config-D27s3_aG.d.ts}

@@ -13,6 +13,59 @@ type HoconValue = {
     raw: string;
     valueType: ScalarValueType;
 };
+/**
+ * Deeply-immutable view of a {@link HoconValue}. `Config.getValue` returns this
+ * so callers cannot mutate the parsed configuration tree (the live nodes are
+ * shared, not cloned). `Map`/array containers become `ReadonlyMap`/`readonly[]`
+ * recursively, so `.set` / `.push` / element assignment are compile errors.
+ *
+ * `HoconValue` is structurally assignable to `ReadonlyHoconValue`, so internal
+ * code holding a mutable node can return it here, and the accessor functions
+ * below accept both forms.
+ */
+type ReadonlyHoconValue = {
+    readonly kind: 'object';
+    readonly fields: ReadonlyMap<string, ReadonlyHoconValue>;
+} | {
+    readonly kind: 'array';
+    readonly items: readonly ReadonlyHoconValue[];
+} | {
+    readonly kind: 'scalar';
+    readonly raw: string;
+    readonly valueType: ScalarValueType;
+};
+/** Scalar string only (strict): non-string scalars and containers → undefined. */
+declare function asString(v: ReadonlyHoconValue): string | undefined;
+/**
+ * Scalar coerced to a number via {@link coerceNumber} (lenient, matching the
+ * `getNumber` getter: a numeric-looking string scalar coerces too). TS has a
+ * single `number` type, so this unifies rs's `as_i64` + `as_f64`.
+ */
+declare function asNumber(v: ReadonlyHoconValue): number | undefined;
+/** Scalar coerced to a boolean via {@link coerceBoolean} (true/yes/on, false/no/off). */
+declare function asBoolean(v: ReadonlyHoconValue): boolean | undefined;
+/** The object's fields, or undefined if not an object. */
+declare function asObject(v: ReadonlyHoconValue): ReadonlyMap<string, ReadonlyHoconValue> | undefined;
+/** The array's items, or undefined if not an array. */
+declare function asArray(v: ReadonlyHoconValue): readonly ReadonlyHoconValue[] | undefined;
+/** Type guard: narrows to the object variant. */
+declare function isObject(v: ReadonlyHoconValue): v is {
+    readonly kind: 'object';
+    readonly fields: ReadonlyMap<string, ReadonlyHoconValue>;
+};
+/** Type guard: narrows to the array variant. */
+declare function isArray(v: ReadonlyHoconValue): v is {
+    readonly kind: 'array';
+    readonly items: readonly ReadonlyHoconValue[];
+};
+/** Type guard: narrows to the scalar variant. */
+declare function isScalar(v: ReadonlyHoconValue): v is {
+    readonly kind: 'scalar';
+    readonly raw: string;
+    readonly valueType: ScalarValueType;
+};
+/** True for a null scalar. */
+declare function isNull(v: ReadonlyHoconValue): boolean;
 
 interface Segment {
     readonly text: string;
@@ -212,6 +265,20 @@ declare class Config {
         resolveOpts: ResolveOptions$1;
     }): Config;
     get(path: string): unknown;
+    /**
+     * Returns the raw {@link HoconValue} node at `path` as a deeply-immutable
+     * {@link ReadonlyHoconValue} view, or `undefined` if the path is absent. Unlike
+     * `get` (which decodes to a plain JS value), this exposes the value tree for
+     * structural introspection via the `value.ts` accessors (`asString`, `asObject`,
+     * `isScalar`, …).
+     *
+     * `getValue('')` returns the root object node.
+     *
+     * Throws {@link NotResolvedError} when the node (or its subtree) is unresolved:
+     * the `HoconValue` union has no placeholder variant, so an unresolved value
+     * cannot be represented. This matches `getConfig` / `getList`.
+     */
+    getValue(path: string): ReadonlyHoconValue | undefined;
     getString(path: string): string;
     getNumber(path: string): number;
     getBoolean(path: string): boolean;
@@ -273,4 +340,4 @@ declare class Config {
     private requireScalar;
 }
 
-export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ResolveOptions as R, type ScalarValueType as S, type ParseOptions as a, defaultResolveOptions as b, parseAsync as c, defaultParseOptions as d, parseFile as e, parseFileAsync as f, parseFileWithOptions as g, parseString as h, parseStringWithOptions as i, parse as p };
+export { type ByteUnit as B, Config as C, type DurationUnit as D, type HoconValue as H, type PackageResolver as P, type ReadonlyHoconValue as R, type ScalarValueType as S, type ParseOptions as a, type ResolveOptions as b, asArray as c, asBoolean as d, asNumber as e, asObject as f, asString as g, defaultParseOptions as h, defaultResolveOptions as i, isArray as j, isNull as k, isObject as l, isScalar as m, parseAsync as n, parseFile as o, parse as p, parseFileAsync as q, parseFileWithOptions as r, parseString as s, parseStringWithOptions as t };

package/dist/index.cjs

@@ -36,10 +36,19 @@ __export(src_exports, {
   PackageLookupError: () => PackageLookupError,
   ParseError: () => ParseError,
   ResolveError: () => ResolveError,
+  asArray: () => asArray,
+  asBoolean: () => asBoolean,
+  asNumber: () => asNumber,
+  asObject: () => asObject,
+  asString: () => asString,
   defaultParseOptions: () => defaultParseOptions,
   defaultResolveOptions: () => defaultResolveOptions,
   empty: () => empty,
   fromMap: () => fromMap,
+  isArray: () => isArray,
+  isNull: () => isNull,
+  isObject: () => isObject,
+  isScalar: () => isScalar,
   parse: () => parse,
   parseAsync: () => parseAsync,
   parseFile: () => parseFile,
@@ -2601,6 +2610,32 @@ var Config = class _Config {
     if (v === void 0) return void 0;
     return hoconToJs(v);
   }
+  /**
+   * Returns the raw {@link HoconValue} node at `path` as a deeply-immutable
+   * {@link ReadonlyHoconValue} view, or `undefined` if the path is absent. Unlike
+   * `get` (which decodes to a plain JS value), this exposes the value tree for
+   * structural introspection via the `value.ts` accessors (`asString`, `asObject`,
+   * `isScalar`, …).
+   *
+   * `getValue('')` returns the root object node.
+   *
+   * Throws {@link NotResolvedError} when the node (or its subtree) is unresolved:
+   * the `HoconValue` union has no placeholder variant, so an unresolved value
+   * cannot be represented. This matches `getConfig` / `getList`.
+   */
+  getValue(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) {
+      if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+        throw new NotResolvedError(path2);
+      }
+      return void 0;
+    }
+    if (v.kind !== "scalar" && !this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+      throw new NotResolvedError(path2);
+    }
+    return v;
+  }
   getString(path2) {
     const v = this.requireScalar(path2);
     if (v.valueType === "null") {
@@ -3108,6 +3143,35 @@ async function parseFileAsync(filePath, opts = {}) {
   });
 }
 
+// src/value.ts
+function asString(v) {
+  return v.kind === "scalar" && v.valueType === "string" ? v.raw : void 0;
+}
+function asNumber(v) {
+  return v.kind === "scalar" ? coerceNumber(v.raw) : void 0;
+}
+function asBoolean(v) {
+  return v.kind === "scalar" ? coerceBoolean(v.raw) : void 0;
+}
+function asObject(v) {
+  return v.kind === "object" ? v.fields : void 0;
+}
+function asArray(v) {
+  return v.kind === "array" ? v.items : void 0;
+}
+function isObject(v) {
+  return v.kind === "object";
+}
+function isArray(v) {
+  return v.kind === "array";
+}
+function isScalar(v) {
+  return v.kind === "scalar";
+}
+function isNull(v) {
+  return v.kind === "scalar" && v.valueType === "null";
+}
+
 // src/value-factory.ts
 function fromMap(values, originDescription) {
   const fields = coerceObject(values, "");
@@ -3182,10 +3246,19 @@ function coerceValue(v, atPath) {
   PackageLookupError,
   ParseError,
   ResolveError,
+  asArray,
+  asBoolean,
+  asNumber,
+  asObject,
+  asString,
   defaultParseOptions,
   defaultResolveOptions,
   empty,
   fromMap,
+  isArray,
+  isNull,
+  isObject,
+  isScalar,
   parse,
   parseAsync,
   parseFile,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as Config } from './config-DCSLXkNY.cjs';
-export { B as ByteUnit, D as DurationUnit, H as HoconValue, P as PackageResolver, a as ParseOptions, R as ResolveOptions, S as ScalarValueType, d as defaultParseOptions, b as defaultResolveOptions, p as parse, c as parseAsync, e as parseFile, f as parseFileAsync, g as parseFileWithOptions, h as parseString, i as parseStringWithOptions } from './config-DCSLXkNY.cjs';
+import { C as Config } from './config-D27s3_aG.cjs';
+export { B as ByteUnit, D as DurationUnit, H as HoconValue, P as PackageResolver, a as ParseOptions, R as ReadonlyHoconValue, b as ResolveOptions, S as ScalarValueType, c as asArray, d as asBoolean, e as asNumber, f as asObject, g as asString, h as defaultParseOptions, i as defaultResolveOptions, j as isArray, k as isNull, l as isObject, m as isScalar, p as parse, n as parseAsync, o as parseFile, q as parseFileAsync, r as parseFileWithOptions, s as parseString, t as parseStringWithOptions } from './config-D27s3_aG.cjs';
 
 declare class ParseError extends Error {
     readonly line: number;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as Config } from './config-DCSLXkNY.js';
-export { B as ByteUnit, D as DurationUnit, H as HoconValue, P as PackageResolver, a as ParseOptions, R as ResolveOptions, S as ScalarValueType, d as defaultParseOptions, b as defaultResolveOptions, p as parse, c as parseAsync, e as parseFile, f as parseFileAsync, g as parseFileWithOptions, h as parseString, i as parseStringWithOptions } from './config-DCSLXkNY.js';
+import { C as Config } from './config-D27s3_aG.js';
+export { B as ByteUnit, D as DurationUnit, H as HoconValue, P as PackageResolver, a as ParseOptions, R as ReadonlyHoconValue, b as ResolveOptions, S as ScalarValueType, c as asArray, d as asBoolean, e as asNumber, f as asObject, g as asString, h as defaultParseOptions, i as defaultResolveOptions, j as isArray, k as isNull, l as isObject, m as isScalar, p as parse, n as parseAsync, o as parseFile, q as parseFileAsync, r as parseFileWithOptions, s as parseString, t as parseStringWithOptions } from './config-D27s3_aG.js';
 
 declare class ParseError extends Error {
     readonly line: number;

package/dist/index.js

@@ -2548,6 +2548,32 @@ var Config = class _Config {
     if (v === void 0) return void 0;
     return hoconToJs(v);
   }
+  /**
+   * Returns the raw {@link HoconValue} node at `path` as a deeply-immutable
+   * {@link ReadonlyHoconValue} view, or `undefined` if the path is absent. Unlike
+   * `get` (which decodes to a plain JS value), this exposes the value tree for
+   * structural introspection via the `value.ts` accessors (`asString`, `asObject`,
+   * `isScalar`, …).
+   *
+   * `getValue('')` returns the root object node.
+   *
+   * Throws {@link NotResolvedError} when the node (or its subtree) is unresolved:
+   * the `HoconValue` union has no placeholder variant, so an unresolved value
+   * cannot be represented. This matches `getConfig` / `getList`.
+   */
+  getValue(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) {
+      if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+        throw new NotResolvedError(path2);
+      }
+      return void 0;
+    }
+    if (v.kind !== "scalar" && !this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+      throw new NotResolvedError(path2);
+    }
+    return v;
+  }
   getString(path2) {
     const v = this.requireScalar(path2);
     if (v.valueType === "null") {
@@ -3055,6 +3081,35 @@ async function parseFileAsync(filePath, opts = {}) {
   });
 }
 
+// src/value.ts
+function asString(v) {
+  return v.kind === "scalar" && v.valueType === "string" ? v.raw : void 0;
+}
+function asNumber(v) {
+  return v.kind === "scalar" ? coerceNumber(v.raw) : void 0;
+}
+function asBoolean(v) {
+  return v.kind === "scalar" ? coerceBoolean(v.raw) : void 0;
+}
+function asObject(v) {
+  return v.kind === "object" ? v.fields : void 0;
+}
+function asArray(v) {
+  return v.kind === "array" ? v.items : void 0;
+}
+function isObject(v) {
+  return v.kind === "object";
+}
+function isArray(v) {
+  return v.kind === "array";
+}
+function isScalar(v) {
+  return v.kind === "scalar";
+}
+function isNull(v) {
+  return v.kind === "scalar" && v.valueType === "null";
+}
+
 // src/value-factory.ts
 function fromMap(values, originDescription) {
   const fields = coerceObject(values, "");
@@ -3128,10 +3183,19 @@ export {
   PackageLookupError,
   ParseError,
   ResolveError,
+  asArray,
+  asBoolean,
+  asNumber,
+  asObject,
+  asString,
   defaultParseOptions,
   defaultResolveOptions,
   empty,
   fromMap,
+  isArray,
+  isNull,
+  isObject,
+  isScalar,
   parse,
   parseAsync,
   parseFile,

package/dist/zod.cjs

@@ -2588,6 +2588,32 @@ var Config = class _Config {
     if (v === void 0) return void 0;
     return hoconToJs(v);
   }
+  /**
+   * Returns the raw {@link HoconValue} node at `path` as a deeply-immutable
+   * {@link ReadonlyHoconValue} view, or `undefined` if the path is absent. Unlike
+   * `get` (which decodes to a plain JS value), this exposes the value tree for
+   * structural introspection via the `value.ts` accessors (`asString`, `asObject`,
+   * `isScalar`, …).
+   *
+   * `getValue('')` returns the root object node.
+   *
+   * Throws {@link NotResolvedError} when the node (or its subtree) is unresolved:
+   * the `HoconValue` union has no placeholder variant, so an unresolved value
+   * cannot be represented. This matches `getConfig` / `getList`.
+   */
+  getValue(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) {
+      if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+        throw new NotResolvedError(path2);
+      }
+      return void 0;
+    }
+    if (v.kind !== "scalar" && !this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+      throw new NotResolvedError(path2);
+    }
+    return v;
+  }
   getString(path2) {
     const v = this.requireScalar(path2);
     if (v.valueType === "null") {

package/dist/zod.d.cts

@@ -1,5 +1,5 @@
 import { ZodType } from 'zod';
-import { C as Config, a as ParseOptions } from './config-DCSLXkNY.cjs';
+import { C as Config, a as ParseOptions } from './config-D27s3_aG.cjs';
 
 declare function validate<T>(config: Config, schema: ZodType<T>): T;
 declare function getValidated<T>(config: Config, path: string, schema: ZodType<T>): T;

package/dist/zod.d.ts

@@ -1,5 +1,5 @@
 import { ZodType } from 'zod';
-import { C as Config, a as ParseOptions } from './config-DCSLXkNY.js';
+import { C as Config, a as ParseOptions } from './config-D27s3_aG.js';
 
 declare function validate<T>(config: Config, schema: ZodType<T>): T;
 declare function getValidated<T>(config: Config, path: string, schema: ZodType<T>): T;

package/dist/zod.js

@@ -2548,6 +2548,32 @@ var Config = class _Config {
     if (v === void 0) return void 0;
     return hoconToJs(v);
   }
+  /**
+   * Returns the raw {@link HoconValue} node at `path` as a deeply-immutable
+   * {@link ReadonlyHoconValue} view, or `undefined` if the path is absent. Unlike
+   * `get` (which decodes to a plain JS value), this exposes the value tree for
+   * structural introspection via the `value.ts` accessors (`asString`, `asObject`,
+   * `isScalar`, …).
+   *
+   * `getValue('')` returns the root object node.
+   *
+   * Throws {@link NotResolvedError} when the node (or its subtree) is unresolved:
+   * the `HoconValue` union has no placeholder variant, so an unresolved value
+   * cannot be represented. This matches `getConfig` / `getList`.
+   */
+  getValue(path2) {
+    const v = this.lookupNode(path2);
+    if (v === void 0) {
+      if (!this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+        throw new NotResolvedError(path2);
+      }
+      return void 0;
+    }
+    if (v.kind !== "scalar" && !this._resolved && this._resObjRootSubtreeHasPlaceholders(path2)) {
+      throw new NotResolvedError(path2);
+    }
+    return v;
+  }
   getString(path2) {
     const v = this.requireScalar(path2);
     if (v.valueType === "null") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o3co/ts.hocon",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Full Lightbend HOCON spec-compliant parser and config library for TypeScript",
   "keywords": [
     "hocon",