@evolu/common 8.8.0 → 8.10.0

package/dist/src/{Binary.js → Bytes.js}

@@ -1,16 +1,29 @@
 /**
- * Binary data handling and byte array utilities.
+ * Bytes: `Uint8Array` helpers, the {@link Buffer} codec, and byte sizes.
  *
- * Buffer-based decoding functions intentionally throw errors instead of
- * returning {@link Result}. This is a deliberate micro-optimization for Evolu
- * Protocol's hot paths: Result is inexpensive, but returning decoded values
- * directly avoids its success-case allocation, and using `Error` objects
- * preserves stack traces. In the future, we will try returning `Error` objects
- * in `Result` values to measure the real-world performance impact.
+ * Sizes follow the same pattern as durations in Time.ts:
+ *
+ * - {@link ByteLength} is the canonical unit, a validated number of bytes.
+ * - {@link ByteSizeLiteral} is the human-readable form, such as `"10MiB"`,
+ *   validated at compile time and runtime.
+ * - {@link ByteSize} is what APIs accept: `ByteSizeLiteral | ByteLength`.
+ * - {@link byteSizeToByteLength} normalizes a `ByteSize` to a `ByteLength`.
+ * - {@link ByteLengthFromString} parses either form from text.
+ *
+ * Buffer-based decoding functions throw instead of returning {@link Result}.
+ * Result is not slow, but every successful decode would allocate one, and a
+ * protocol message decodes many values. Throwing is the safe bet for that hot
+ * path until benchmarks cover the alternatives. Callers convert a thrown error
+ * into a Result once, at the boundary, as `parseProtocolHeader` in Protocol.ts
+ * does.
  *
  * @module
  */
 import { bytesToUtf8, utf8ToBytes } from "@noble/ciphers/utils.js";
+import { assert } from "./Assert.js";
+import { err, ok } from "./Result.js";
+import { safelyStringifyUnknownValue } from "./String.js";
+import { brand, createTypeWithError, Digit, Digit1To9, NonNegativeInt, String, templateLiteral, transform, union, } from "./Type.js";
 export { bytesToHex, concatBytes, hexToBytes } from "@noble/ciphers/utils.js";
 export { bytesToUtf8, utf8ToBytes };
 /**
@@ -27,7 +40,7 @@ export class BufferError extends Error {
 /** Creates a {@link Buffer} for efficient byte operations. */
 export const createBuffer = (arrayLike) => {
     const initialLength = arrayLike?.length ?? 0;
-    assertNonNegativeInt(initialLength, "arrayLike.length");
+    assertBufferNonNegativeInt(initialLength, "arrayLike.length");
     let value = arrayLike ? new Uint8Array(arrayLike) : new Uint8Array(512);
     let length = initialLength;
     const buffer = {
@@ -35,9 +48,9 @@ export const createBuffer = (arrayLike) => {
         getLength: () => length,
         extend: (arg) => {
             const argLength = arg.length;
-            assertNonNegativeInt(argLength, "arg.length");
+            assertBufferNonNegativeInt(argLength, "arg.length");
             const targetSize = length + argLength;
-            assertNonNegativeInt(targetSize, "Buffer length");
+            assertBufferNonNegativeInt(targetSize, "Buffer length");
             if (value.length < targetSize) {
                 const oldValue = value;
                 const newCapacity = Math.max(value.length * 2, targetSize);
@@ -188,12 +201,12 @@ export const decodeNonNegativeInt = (buffer) => {
         throw new BufferError("Variable-length quantity must terminate within 8 bytes.");
     }
     const value = Number(result);
-    assertNonNegativeInt(value, "Decoded integer");
+    assertBufferNonNegativeInt(value, "Decoded integer");
     return value;
 };
 /** Encodes the length of an array-like value. */
 export const encodeLength = (buffer, value) => {
-    assertNonNegativeInt(value.length, "Array-like length");
+    assertBufferNonNegativeInt(value.length, "Array-like length");
     encodeNonNegativeInt(buffer, value.length);
 };
 /** Decodes an array-like value length. */
@@ -272,7 +285,7 @@ let jsonDecoderSource = emptyJsonDecoderSource;
 let jsonDecoderView = emptyJsonDecoderView;
 let jsonDecoderPosition = 0;
 let jsonDecoderDepth = 0;
-const jsonStringFromCharCode = String.fromCharCode;
+const jsonStringFromCharCode = globalThis.String.fromCharCode;
 // Cache only short keys and use a fixed table to bound retained memory.
 const jsonKeyCache = Array.from({ length: jsonKeyCacheSize }, () => undefined);
 /**
@@ -559,11 +572,11 @@ const writeJsonEncoderByte = (value) => {
 };
 const ensureJsonEncoderCapacity = (additionalLength) => {
     const requiredLength = jsonEncoderPosition + additionalLength;
-    assertNonNegativeInt(requiredLength, "Encoded JSON value length");
+    assertBufferNonNegativeInt(requiredLength, "Encoded JSON value length");
     if (requiredLength <= jsonEncoderTarget.length)
         return;
     const newCapacity = Math.max(jsonEncoderTarget.length * 2, requiredLength);
-    assertNonNegativeInt(newCapacity, "JSON encoder capacity");
+    assertBufferNonNegativeInt(newCapacity, "JSON encoder capacity");
     const oldTarget = jsonEncoderTarget;
     jsonEncoderTarget = new Uint8Array(newCapacity);
     jsonEncoderTarget.set(oldTarget.subarray(0, jsonEncoderPosition));
@@ -946,7 +959,7 @@ const assertJsonDecoderHasRemainingBytes = (requiredBytes) => {
         throw new BufferError("Buffer parse ended prematurely");
     }
 };
-const assertNonNegativeInt = (value, name) => {
+const assertBufferNonNegativeInt = (value, name) => {
     if (!Number.isSafeInteger(value) || value < 0) {
         throw new BufferError(`${name} must be a non-negative safe integer.`);
     }
@@ -956,3 +969,240 @@ const assertBufferHasRemainingBytes = (remainingBytes, requiredBytes) => {
         throw new BufferError("Buffer parse ended prematurely");
     }
 };
+/**
+ * Non-negative safe integer number of bytes.
+ *
+ * The canonical unit for sizes, as milliseconds are for time. APIs accept
+ * {@link ByteSize} and normalize it with {@link byteSizeToByteLength}. Parse text
+ * such as an environment variable with {@link ByteLengthFromString}. Negative
+ * zero is rejected so zero has one canonical representation.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertErr, assertOk, ByteLength } from "@evolu/common";
+ *
+ * assertOk(ByteLength.fromUnknown(0), 0);
+ * assertOk(ByteLength.fromUnknown(1024), 1024);
+ * assertErr(ByteLength.fromUnknown(-0));
+ * assertErr(ByteLength.fromUnknown(-1));
+ * assertErr(ByteLength.fromUnknown(1.5));
+ * ```
+ */
+export const ByteLength = /*#__PURE__*/ brand("ByteLength", NonNegativeInt, (value) => Object.is(value, -0)
+    ? err({ type: "ByteLength", value })
+    : ok(), () => "The value -0 is not a byte length. Use 0 instead.");
+const Digit0To1 = /*#__PURE__*/ union("0", "1");
+const Digit0To3 = /*#__PURE__*/ union("0", "1", "2", "3");
+// Keep these annotations concrete. Generic unit wrappers add thousands of
+// compiler instantiations to pnpm bench:type.
+/** Bytes: `"0B"` to `"1023B"`. See {@link ByteSizeLiteral}. */
+export const ByteSizeLiteralBytes = /*#__PURE__*/ union(
+/*#__PURE__*/ templateLiteral(Digit, "B"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, "B"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "B"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, "B"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, "B"));
+/**
+ * KiB: `"1KiB"` to `"1023KiB"` or `"1.5KiB"` to `"1023.5KiB"`. See
+ * {@link ByteSizeLiteral}.
+ */
+export const ByteSizeLiteralKiB = /*#__PURE__*/ union(
+/*#__PURE__*/ templateLiteral(Digit1To9, "KiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, "KiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "KiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, "KiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, "KiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, ".5KiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, ".5KiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, ".5KiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, ".5KiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, ".5KiB"));
+/**
+ * MiB: `"1MiB"` to `"1023MiB"` or `"1.5MiB"` to `"1023.5MiB"`. See
+ * {@link ByteSizeLiteral}.
+ */
+export const ByteSizeLiteralMiB = /*#__PURE__*/ union(
+/*#__PURE__*/ templateLiteral(Digit1To9, "MiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, "MiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "MiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, "MiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, "MiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, ".5MiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, ".5MiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, ".5MiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, ".5MiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, ".5MiB"));
+/**
+ * GiB: `"1GiB"` to `"1023GiB"` or `"1.5GiB"` to `"1023.5GiB"`. See
+ * {@link ByteSizeLiteral}.
+ */
+export const ByteSizeLiteralGiB = /*#__PURE__*/ union(
+/*#__PURE__*/ templateLiteral(Digit1To9, "GiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, "GiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "GiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, "GiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, "GiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, ".5GiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, ".5GiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, ".5GiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, ".5GiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, ".5GiB"));
+/**
+ * TiB: `"1TiB"` to `"1023TiB"` or `"1.5TiB"` to `"1023.5TiB"`. See
+ * {@link ByteSizeLiteral}.
+ */
+export const ByteSizeLiteralTiB = /*#__PURE__*/ union(
+/*#__PURE__*/ templateLiteral(Digit1To9, "TiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, "TiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "TiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, "TiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, "TiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, ".5TiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, ".5TiB"), 
+/*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, ".5TiB"), 
+/*#__PURE__*/ templateLiteral("10", Digit0To1, Digit, ".5TiB"), 
+/*#__PURE__*/ templateLiteral("102", Digit0To3, ".5TiB"));
+const byteSizeLiteralSyntax = /*#__PURE__*/ union(ByteSizeLiteralBytes, ByteSizeLiteralKiB, ByteSizeLiteralMiB, ByteSizeLiteralGiB, ByteSizeLiteralTiB);
+/**
+ * Byte length literal Type with compile-time and runtime validation.
+ *
+ * Supported formats:
+ *
+ * - Bytes: `0B` to `1023B`
+ * - KiB: `1KiB` to `1023KiB` or `1.5KiB` to `1023.5KiB`
+ * - MiB: `1MiB` to `1023MiB` or `1.5MiB` to `1023.5MiB`
+ * - GiB: `1GiB` to `1023GiB` or `1.5GiB` to `1023.5GiB`
+ * - TiB: `1TiB` to `1023TiB` or `1.5TiB` to `1023.5TiB`
+ *
+ * Units are the binary ones defined by IEC, named kibibyte (`KiB`, 1024 bytes),
+ * mebibyte (`MiB`), gibibyte (`GiB`), and tebibyte (`TiB`), each 1024 times the
+ * previous. Memory, storage quotas, and caches are measured in them. The
+ * familiar `MB` is ambiguous: SI defines it as a million bytes, storage vendors
+ * use that meaning, and most software uses 1048576 instead, which is why a "1
+ * TB" drive shows as 931 "GB". `MiB` has only one meaning, so a literal never
+ * depends on a convention.
+ *
+ * Each unit is bounded below 1024, so equivalent representations are avoided:
+ * `1024KiB` must be written as `"1MiB"`. A half is the only decimal allowed,
+ * because it is the only single decimal digit that is exact in every binary
+ * unit; `1.1KiB` would be 1126.4 bytes. For other exact values, use
+ * {@link ByteLength} directly.
+ *
+ * See {@link ByteSize} for a type that also accepts {@link ByteLength}. Use
+ * {@link byteSizeToByteLength} to convert.
+ *
+ * Invalid values produce a {@link ByteSizeLiteralError}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
+ *   ByteSizeLiteral,
+ * } from "@evolu/common";
+ *
+ * // The TypeScript type accepts valid spellings and rejects the rest.
+ * const literal: ByteSizeLiteral = "1023MiB";
+ * assertType<
+ *   Extract<ByteSizeLiteral, "1024KiB" | "1.1KiB" | "1MB">,
+ *   never
+ * >();
+ *
+ * // The runtime Type validates the same grammar.
+ * assertOk(ByteSizeLiteral.fromUnknown(literal), "1023MiB");
+ * assertFalse(ByteSizeLiteral.is("1024KiB"));
+ *
+ * const invalid = ByteSizeLiteral.fromUnknown("1MB");
+ * assertErr(invalid);
+ * assertEqual(invalid.error.type, "ByteSizeLiteral");
+ * assertEqual(
+ *   ByteSizeLiteral.formatError(invalid.error),
+ *   'The value "1MB" is not a byte-size literal. Use a value such as "512KiB" or "1MiB".',
+ * );
+ * ```
+ */
+export const ByteSizeLiteral = /*#__PURE__*/ createTypeWithError("ByteSizeLiteral", byteSizeLiteralSyntax, (cause, value) => ({
+    type: "ByteSizeLiteral",
+    value,
+    cause,
+}), (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a byte-size literal. Use a value such as "512KiB" or "1MiB".`);
+const bytesByByteLengthUnit = {
+    B: 1,
+    KiB: 1024,
+    MiB: 1024 ** 2,
+    GiB: 1024 ** 3,
+    TiB: 1024 ** 4,
+};
+/**
+ * Converts a {@link ByteSize} to a {@link ByteLength}. A {@link ByteLength} is
+ * returned unchanged.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, byteSizeToByteLength } from "@evolu/common";
+ *
+ * assertEqual(byteSizeToByteLength("0B"), 0);
+ * assertEqual(byteSizeToByteLength("2KiB"), 2048);
+ * assertEqual(byteSizeToByteLength("1GiB"), 1073741824);
+ * ```
+ */
+export const byteSizeToByteLength = (value) => {
+    if (typeof value === "number")
+        return value;
+    const unit = value.endsWith("iB") ? value.slice(-3) : "B";
+    assert(unit in bytesByByteLengthUnit, `Unknown byte length unit: ${unit}`);
+    return ByteLength.orThrow(Number.parseFloat(value) *
+        bytesByByteLengthUnit[unit]);
+};
+/**
+ * Transforms a number of bytes or a {@link ByteSizeLiteral} in text into a
+ * {@link ByteLength}.
+ *
+ * This is useful for inputs that carry sizes as text, such as environment
+ * variables and configuration files, where `"10MiB"` reads better than
+ * `"10485760"`. Encoding produces the number of bytes.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertOk,
+ *   ByteLengthFromString,
+ * } from "@evolu/common";
+ *
+ * assertOk(ByteLengthFromString.fromUnknown("10MiB"), 10485760);
+ * assertOk(ByteLengthFromString.fromUnknown("1048576"), 1048576);
+ * assertEqual(
+ *   ByteLengthFromString.to(ByteLengthFromString.orThrow("1KiB")),
+ *   "1024",
+ * );
+ *
+ * const invalid = ByteLengthFromString.fromUnknown("10MB");
+ * assertErr(invalid, { type: "ByteLengthFromString", value: "10MB" });
+ * assertEqual(
+ *   ByteLengthFromString.formatError(invalid.error),
+ *   'The value "10MB" is not a byte length. Use a number of bytes or a literal such as 10MiB.',
+ * );
+ * ```
+ */
+export const ByteLengthFromString = /*#__PURE__*/ transform("ByteLengthFromString", String, ByteLength, {
+    from: (value) => {
+        if (ByteSizeLiteral.is(value))
+            return ok(byteSizeToByteLength(value));
+        if (/^\d+$/u.test(value)) {
+            const number = Number(value);
+            if (Number.isSafeInteger(number))
+                return ok(number);
+        }
+        return err({ type: "ByteLengthFromString", value });
+    },
+    to: (value) => globalThis.String(value),
+}, (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a byte length. Use a number of bytes or a literal such as 10MiB.`);

package/dist/src/Config.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Strict configuration Types with explicit application policy.
+ *
+ * Decode configuration at startup, then pass validated values to constructors
+ * or Tasks. The application decides how to load configuration, combine sources,
+ * and apply defaults. Declare defaults with {@link withDefault}, or use `??`
+ * where a value is consumed. Invalid supplied values still fail decoding.
+ *
+ * Resolve source precedence before replacing absence with defaults. If a source
+ * Type already provides defaults and later composition needs to distinguish
+ * them from supplied values, use `strategy: "preserve"` and inspect
+ * `defaultUsed` explicitly. Preserving this evidence does not choose a merging
+ * policy: the application still decides which source wins.
+ *
+ * {@link env} creates a pure, reversible codec. It does not read global state,
+ * load files, merge sources, or introduce a Run dependency. Tests can pass
+ * ordinary objects; a Node.js entry point can pass `process.env`.
+ *
+ * @module
+ */
+import { CamelCaseIdentifier, String, Unknown, type AnyType, type InferErrors, type ValidateLiteral, type ObjectKeysType, type ObjectProps, type ObjectType, type TransformType, type TypeNode } from "./Type.ts";
+import type { CompileTimeError, IsUnion, UnionToIntersection } from "./Types.ts";
+/**
+ * An environment variable name in Evolu's configuration convention.
+ *
+ * Names are {@link ConstantCaseIdentifier}s of at most 255 characters, including
+ * the application prefix. This is an Evolu convention, not an operating-system
+ * limit. Double underscores do not introduce nesting.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertErr, assertOk, EnvName } from "@evolu/common";
+ *
+ * assertOk(
+ *   EnvName.fromUnknown("APP_MAX_OWNER_BYTES"),
+ *   "APP_MAX_OWNER_BYTES",
+ * );
+ * assertErr(EnvName.fromUnknown("APP_maxOwnerBytes"));
+ * assertErr(EnvName.fromUnknown("APP_DB__PORT"));
+ * ```
+ */
+export declare const EnvName: import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").Type<"String", string, string, import("./Type.ts").TypeOfError<"String">, null, import("./Type.ts").TypeOfError<"String">, never, string, true>, "ConstantCaseIdentifier", import("./Type.ts").IdentifierError<"CONSTANT_CASE">>, "MaxLength255", import("./Type.ts").MaxLengthError<255>>;
+export type EnvName = typeof EnvName.Output;
+/** Fields and one-level namespace groups used to construct an {@link env} Type. */
+export type EnvProps = Readonly<Record<string, ObjectProps[string] | ObjectProps>>;
+type EnvDeclarationKind<Key> = Key extends string ? Key extends Uppercase<Key> ? "group" : Key extends Uncapitalize<Key> ? "field" : "invalid" : "invalid";
+type EnvFlatProps<Props extends EnvProps> = UnionToIntersection<{
+    [Key in keyof Props]: EnvDeclarationKind<Key> extends "group" ? Props[Key] : EnvDeclarationKind<Key> extends "field" ? {
+        readonly [Field in Key]: Props[Key];
+    } : never;
+}[keyof Props]> extends infer Flat extends ObjectProps ? Flat : {};
+type EnvFieldType<Field> = Field extends TypeNode ? Field : Field extends {
+    readonly type: infer T extends TypeNode;
+} ? T : never;
+type EnvKeysValidation<Props> = (string extends keyof Props ? CompileTimeError<"Env", "Environment properties must use fixed string keys."> : never) | (IsUnion<Props> extends true ? CompileTimeError<"Env", "Environment properties must use one concrete schema."> : never) | {
+    [Key in keyof Props]: Key extends string ? ValidateLiteral<Key> extends Key ? never : CompileTimeError<"Env", "Environment properties must use fixed string keys."> : CompileTimeError<"Env", "Environment properties must use fixed string keys.">;
+}[keyof Props];
+type EnvFieldValidation<Field> = IsUnion<Field> extends true ? CompileTimeError<"Env", "Environment fields must use one concrete Type."> : EnvFieldType<Field> extends infer T extends AnyType ? IsUnion<T> extends true ? CompileTimeError<"Env", "Environment fields must use one concrete Type."> : [T["CanonicalInput"]] extends [string] ? Extract<"ObjectMissingProperty" | "ObjectPropertyAccess" | "ObjectExcessProperty", InferErrors<T>["type"]> extends never ? never : CompileTimeError<"Env", "Environment fields must not use error tags reserved for Object structure."> : CompileTimeError<"Env", "Environment fields must encode to strings."> : CompileTimeError<"Env", "Environment fields must use one concrete Type.">;
+type EnvFieldsValidation<Props extends ObjectProps> = EnvKeysValidation<Props> | {
+    [Key in keyof Props]: EnvDeclarationKind<Key> extends "field" ? EnvFieldValidation<Props[Key]> : CompileTimeError<"Env", "Environment fields must use camelCase names.">;
+}[keyof Props];
+type EnvValidation<Props extends EnvProps> = EnvKeysValidation<Props> | {
+    [Key in keyof Props]: EnvDeclarationKind<Key> extends "group" ? Props[Key] extends ObjectProps ? EnvFieldsValidation<Props[Key]> : CompileTimeError<"Env", "Environment namespaces must contain a group of fields."> : EnvDeclarationKind<Key> extends "field" ? Props[Key] extends ObjectProps[string] ? EnvFieldValidation<Props[Key]> : CompileTimeError<"Env", "Environment fields must be Types, optional properties, or defaulted properties."> : CompileTimeError<"Env", "Environment declarations must use camelCase field names or CONSTANT_CASE namespace names.">;
+}[keyof Props];
+type EnvKeyType = TransformType<typeof String, typeof CamelCaseIdentifier, "EnvKey", never, string>;
+/** The configuration codec returned by {@link env}. */
+export interface EnvType<Props extends EnvProps> extends TransformType<typeof Unknown, ObjectKeysType<EnvKeyType, ObjectType<EnvFlatProps<Props>>>, "Env", never, Readonly<Record<string, ObjectType<EnvFlatProps<Props>>["CanonicalInput"][keyof ObjectType<EnvFlatProps<Props>>["CanonicalInput"]]>>> {
+}
+/**
+ * Creates a reversible environment-variable codec with a flat decoded output.
+ *
+ * Declare camelCase fields directly, or put them in one-level CONSTANT_CASE
+ * namespace groups. A direct `port` field reads `PORT`; a `maxOwnerBytes` field
+ * in an `EVOLU_RELAY` group reads `EVOLU_RELAY_MAX_OWNER_BYTES`. Groups affect
+ * external names only. Duplicate decoded fields or encoded names are rejected
+ * during construction, even when their Types are identical.
+ *
+ * Selects exact declared unprefixed names and all keys within declared
+ * namespaces. Namespace selection ignores casing so incorrectly cased names
+ * fail validation instead of being ignored. Selected names must match their
+ * exact declared spelling. Unrelated variables are ignored; misspelled
+ * unprefixed names or namespace prefixes can therefore still look absent.
+ *
+ * Field Types must encode to strings. Optional fields may be absent, but
+ * explicit `undefined` values are rejected. Empty strings remain present and
+ * must satisfy the field Type. Compose {@link withDefault} to supply defaults.
+ * Encoding emits canonical external names and string values, preserving absence
+ * when the field codec does. Errors retain external names and nested paths.
+ *
+ * Reads own string properties from any non-null object, including
+ * `process.env`. Selected properties must be enumerable data properties;
+ * getters are never read. Prototypes and internal contents such as Map entries
+ * are ignored. Non-object inputs fail with standard object errors. Schema names
+ * must satisfy {@link EnvName}; groups cannot be nested. Loading and source
+ * precedence remain explicit application code.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertOk,
+ *   assertType,
+ *   ByteSizeLiteral,
+ *   env,
+ *   optional,
+ *   Port,
+ *   PortFromString,
+ *   withDefault,
+ * } from "@evolu/common";
+ *
+ * const RelayEnv = env({
+ *   port: withDefault(optional(PortFromString), Port.orThrow(4000)),
+ *   EVOLU_RELAY: {
+ *     maxOwnerBytes: optional(ByteSizeLiteral),
+ *   },
+ * });
+ *
+ * const result = RelayEnv.fromUnknown({
+ *   PORT: "04000",
+ *   EVOLU_RELAY_MAX_OWNER_BYTES: "512KiB",
+ *   HOME: "/home/evolu",
+ * });
+ *
+ * assertOk(result, { port: 4000, maxOwnerBytes: "512KiB" });
+ * assertType<typeof result.value.port, Port>();
+ * assertEqual(RelayEnv.to(result.value), {
+ *   PORT: "4000",
+ *   EVOLU_RELAY_MAX_OWNER_BYTES: "512KiB",
+ * });
+ *
+ * assertOk(RelayEnv.fromUnknown({}), { port: 4000 });
+ * assertErr(RelayEnv.fromUnknown({ PORT: "" }));
+ * assertErr(RelayEnv.fromUnknown({ EVOLU_RELAY_MAX_OWENR_BYTES: "1MiB" }));
+ * assertErr(RelayEnv.fromUnknown({ evolu_relay_max_owner_bytes: "1MiB" }));
+ * ```
+ */
+export declare const env: <const Props extends EnvProps>(props: Props, ..._validation: [EnvValidation<Props>] extends [never] ? [] : [EnvValidation<Props>]) => EnvType<Props>;
+export {};
+//# sourceMappingURL=Config.d.ts.map

package/dist/src/Config.d.ts.map

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