@o3co/ts.hocon 1.13.0 → 1.14.0

package/dist/zod.d.cts

@@ -1,9 +1,89 @@
-import { ZodType } from 'zod';
-import { C as Config, a as ParseOptions } from './config-6sApTEMM.cjs';
+import { ZodType, ZodTransform } from 'zod';
+import { C as Config, D as DurationUnit, B as ByteUnit, b as Period, a as ParseOptions } from './config-OccaKqXu.cjs';
 
+/**
+ * The whole config, validated against `schema`. HOCON strings are coerced
+ * where the schema expects a number or a boolean (`"8080"` → 8080), through
+ * objects, arrays and optional / nullable / default / catch / readonly
+ * wrappers (not unions, records, tuples or pipes); unit values go through the
+ * {@link hocon} markers.
+ *
+ * An object key named `__proto__`, `constructor` or `prototype` anywhere in
+ * the value is refused with a `ZodError` issue at the object that holds it
+ * (#202); read such a key with the plain getters instead.
+ *
+ * @throws {@link NotResolvedError} when the config still holds an unresolved
+ *   substitution (#210); call `resolve()` first.
+ * @throws `ZodError` when the value does not match the schema.
+ */
 declare function validate<T>(config: Config, schema: ZodType<T>): T;
+/**
+ * The value at `path`, validated against `schema` as {@link validate} does;
+ * issue paths are relative to that value.
+ *
+ * An object key named `__proto__`, `constructor` or `prototype` anywhere in
+ * the value is refused with a `ZodError` issue at the object that holds it
+ * (#202); read such a key with the plain getters instead.
+ *
+ * @throws {@link NotResolvedError} when the value at `path` still holds an
+ *   unresolved substitution (#210); a resolved subtree of an otherwise
+ *   unresolved config validates.
+ * @throws `ZodError` when the value does not match the schema.
+ */
 declare function getValidated<T>(config: Config, path: string, schema: ZodType<T>): T;
+/**
+ * Zod schema markers for HOCON unit values. Each reads the forms the matching
+ * Config getter reads and gives what the getter gives (a number in the
+ * requested unit, or a {@link Period}); pipe it into a schema for the
+ * constraints:
+ *
+ * ```ts
+ * const Session = z.object({
+ *   lifetime: hocon.duration('s').pipe(z.number().int().min(60)),
+ *   maxBody: hocon.bytes().pipe(z.number().int().positive()),
+ * })
+ * ```
+ */
+declare const hocon: {
+    /**
+     * A duration, read as {@link Config.getDuration} reads it (default unit `ms`),
+     * exponent forms included, except that a number literal with more
+     * significant digits than a double holds can read differently: the getter
+     * reads its text, the marker its JS value (`1.0000000000000001` in `us`:
+     * 1000.0000000000001 through the getter, 1000 here).
+     */
+    duration(unit?: DurationUnit): ZodTransform<number, unknown>;
+    /**
+     * A byte size, read as {@link Config.getBytes} reads it (default unit `B`),
+     * exponent forms included, except that a number literal with more
+     * significant digits than a double holds can read differently: the getter
+     * reads its text, the marker its JS value (`1.99999999999999999`: 1 through
+     * the getter, 2 here).
+     */
+    bytes(unit?: ByteUnit): ZodTransform<number, unknown>;
+    /**
+     * A calendar period, read as {@link Config.getPeriod} reads it (a bare
+     * integer is days), except that a number literal with a decimal point or in
+     * exponent form (`7.0`, `1e2`) can read differently: the getter refuses it,
+     * the marker reads the JS number.
+     */
+    period(): ZodTransform<Period, unknown>;
+};
+/**
+ * Parse a HOCON string and {@link validate} it.
+ *
+ * @throws as `parse`; {@link NotResolvedError} when parsed with
+ *   `resolveSubstitutions: false` and a substitution is left (#210); `ZodError`
+ *   when the value does not match the schema.
+ */
 declare function parseWithSchema<T>(input: string, schema: ZodType<T>, opts?: ParseOptions): T;
+/**
+ * Read and parse a HOCON file and {@link validate} it.
+ *
+ * @throws as `parseFile`; {@link NotResolvedError} when parsed with
+ *   `resolveSubstitutions: false` and a substitution is left (#210); `ZodError`
+ *   when the value does not match the schema.
+ */
 declare function parseFileWithSchema<T>(filePath: string, schema: ZodType<T>, opts?: ParseOptions): T;
 
-export { getValidated, parseFileWithSchema, parseWithSchema, validate };
+export { getValidated, hocon, parseFileWithSchema, parseWithSchema, validate };

package/dist/zod.d.ts

@@ -1,9 +1,89 @@
-import { ZodType } from 'zod';
-import { C as Config, a as ParseOptions } from './config-6sApTEMM.js';
+import { ZodType, ZodTransform } from 'zod';
+import { C as Config, D as DurationUnit, B as ByteUnit, b as Period, a as ParseOptions } from './config-OccaKqXu.js';
 
+/**
+ * The whole config, validated against `schema`. HOCON strings are coerced
+ * where the schema expects a number or a boolean (`"8080"` → 8080), through
+ * objects, arrays and optional / nullable / default / catch / readonly
+ * wrappers (not unions, records, tuples or pipes); unit values go through the
+ * {@link hocon} markers.
+ *
+ * An object key named `__proto__`, `constructor` or `prototype` anywhere in
+ * the value is refused with a `ZodError` issue at the object that holds it
+ * (#202); read such a key with the plain getters instead.
+ *
+ * @throws {@link NotResolvedError} when the config still holds an unresolved
+ *   substitution (#210); call `resolve()` first.
+ * @throws `ZodError` when the value does not match the schema.
+ */
 declare function validate<T>(config: Config, schema: ZodType<T>): T;
+/**
+ * The value at `path`, validated against `schema` as {@link validate} does;
+ * issue paths are relative to that value.
+ *
+ * An object key named `__proto__`, `constructor` or `prototype` anywhere in
+ * the value is refused with a `ZodError` issue at the object that holds it
+ * (#202); read such a key with the plain getters instead.
+ *
+ * @throws {@link NotResolvedError} when the value at `path` still holds an
+ *   unresolved substitution (#210); a resolved subtree of an otherwise
+ *   unresolved config validates.
+ * @throws `ZodError` when the value does not match the schema.
+ */
 declare function getValidated<T>(config: Config, path: string, schema: ZodType<T>): T;
+/**
+ * Zod schema markers for HOCON unit values. Each reads the forms the matching
+ * Config getter reads and gives what the getter gives (a number in the
+ * requested unit, or a {@link Period}); pipe it into a schema for the
+ * constraints:
+ *
+ * ```ts
+ * const Session = z.object({
+ *   lifetime: hocon.duration('s').pipe(z.number().int().min(60)),
+ *   maxBody: hocon.bytes().pipe(z.number().int().positive()),
+ * })
+ * ```
+ */
+declare const hocon: {
+    /**
+     * A duration, read as {@link Config.getDuration} reads it (default unit `ms`),
+     * exponent forms included, except that a number literal with more
+     * significant digits than a double holds can read differently: the getter
+     * reads its text, the marker its JS value (`1.0000000000000001` in `us`:
+     * 1000.0000000000001 through the getter, 1000 here).
+     */
+    duration(unit?: DurationUnit): ZodTransform<number, unknown>;
+    /**
+     * A byte size, read as {@link Config.getBytes} reads it (default unit `B`),
+     * exponent forms included, except that a number literal with more
+     * significant digits than a double holds can read differently: the getter
+     * reads its text, the marker its JS value (`1.99999999999999999`: 1 through
+     * the getter, 2 here).
+     */
+    bytes(unit?: ByteUnit): ZodTransform<number, unknown>;
+    /**
+     * A calendar period, read as {@link Config.getPeriod} reads it (a bare
+     * integer is days), except that a number literal with a decimal point or in
+     * exponent form (`7.0`, `1e2`) can read differently: the getter refuses it,
+     * the marker reads the JS number.
+     */
+    period(): ZodTransform<Period, unknown>;
+};
+/**
+ * Parse a HOCON string and {@link validate} it.
+ *
+ * @throws as `parse`; {@link NotResolvedError} when parsed with
+ *   `resolveSubstitutions: false` and a substitution is left (#210); `ZodError`
+ *   when the value does not match the schema.
+ */
 declare function parseWithSchema<T>(input: string, schema: ZodType<T>, opts?: ParseOptions): T;
+/**
+ * Read and parse a HOCON file and {@link validate} it.
+ *
+ * @throws as `parseFile`; {@link NotResolvedError} when parsed with
+ *   `resolveSubstitutions: false` and a substitution is left (#210); `ZodError`
+ *   when the value does not match the schema.
+ */
 declare function parseFileWithSchema<T>(filePath: string, schema: ZodType<T>, opts?: ParseOptions): T;
 
-export { getValidated, parseFileWithSchema, parseWithSchema, validate };
+export { getValidated, hocon, parseFileWithSchema, parseWithSchema, validate };