pyfect-dev 0.1.0__py3-none-any.whl

pyfect/config/_schema.py

@@ -0,0 +1,340 @@
+"""``config.schema``: a config decoded with a schema (Effect's ``Config.schema``).
+
+The schema is first turned into its canonical string-tree codec
+(``S.to_codec_string_tree``); the encoded shape of that codec says what to
+load. Each node of the encoded shape gets one more link, from a *cursor*
+(a provider, a path and the node found there): an object loads its declared
+keys and the record keys an index signature accepts, an array loads its
+items, a scalar reads the string at its own path. The schema's own parser
+then drives the loading, so unions, checks and errors work as they do for
+any input.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import Any, Never, cast, final
+
+from pyfect._core import Effect
+from pyfect.cause import Cause, Die, Fail, Interrupt, Reason
+from pyfect.config._config import Config, Resolution
+from pyfect.config._error import ConfigError
+from pyfect.config_provider import Array, ConfigProvider, Node, Path, Record, SourceError
+from pyfect.effect import fail, fail_cause, succeed
+from pyfect.result import Err, Ok
+from pyfect.schema import Codec, SchemaError, ast
+from pyfect.schema import transformation as T
+from pyfect.schema._to_codec_string_tree import to_codec_string_tree_ast
+from pyfect.schema.ast._result import NotAnObject
+from pyfect.schema.issue import Issue, Pointer
+
+_OPAQUE = "Config.schema does not support opaque StringTree encodings"
+
+
+@final
+class _Undefined(NotAnObject):
+    """What a cursor reads where the provider has nothing usable: Effect's
+    ``undefined``, which no schema a config can use accepts."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "undefined"
+
+
+_UNDEFINED = _Undefined()
+
+
+@dataclass(frozen=True, slots=True)
+class _Cursor:
+    provider: ConfigProvider
+    path: Path
+    node: Node | None
+
+    def __str__(self) -> str:
+        return "<configuration>"
+
+
+def schema[A](codec: Codec[A, object, Never, object], path: str | Path | None = None) -> Config[A]:
+    """A config decoded by ``codec`` from what the provider holds at
+    ``path`` (one key, or a path of keys and indexes; ``None``: the
+    config's own path).
+
+    The codec's string-tree form says what to load: a struct or record
+    reads an object, a tuple or array reads indexed items (``A_0``,
+    ``A_1`` in ``from_env``), anything else one string; a union loads each
+    member by its own shape. Missing input that the codec rejects is
+    absent (``with_default`` applies); invalid input fails. A codec with
+    an opaque encoding (``S.Unknown``, ``S.Any``, ``S.Json``, anywhere in
+    it) raises ``ValueError`` here."""
+    root = to_codec_string_tree_ast(codec.__codec__().ast)
+    encoded = ast.to_encoded(root)
+    decoder = _CursorWalk().recur(root)
+    local: Path = () if path is None else (path,) if isinstance(path, str) else path
+
+    def run(provider: ConfigProvider, prefix: Path) -> Effect[Resolution[A], ConfigError]:
+        full = (*prefix, *local)
+
+        def decode(cursor: _Cursor) -> Effect[Resolution[A], Any]:
+            def failed(issue: Issue) -> Effect[Resolution[A], ConfigError]:
+                error = ConfigError(SchemaError(Pointer(full, issue) if full else issue))
+                if _has_input(encoded, cursor.node):
+                    return fail(error)
+                return succeed(Err(error))
+
+            return cast("Effect[A, Issue]", ast.to_effect(decoder.parse(cursor, {}))).match_effect(
+                on_failure=failed, on_success=lambda value: succeed(Ok(value))
+            )
+
+        return _load(provider, full).flat_map(decode).catch_cause(_source_errors)
+
+    return Config(run)
+
+
+def _load(provider: ConfigProvider, path: Path) -> Effect[_Cursor]:
+    """The cursor at ``path``. A source error travels as a defect, so no
+    schema recovers from it; ``schema`` turns it back into a failure."""
+
+    def to_defect(cause: Cause[SourceError]) -> Effect[Never]:
+        return fail_cause(Cause(tuple(map(_as_defect, cause.reasons))))
+
+    return (
+        provider.load(path).catch_cause(to_defect).map(lambda node: _Cursor(provider, path, node))
+    )
+
+
+def _as_defect(reason: Reason[SourceError]) -> Reason[Never]:
+    match reason:
+        case Fail(error):
+            return Die(error, annotations=reason.annotations)
+        case Die() | Interrupt():
+            return reason
+
+
+def _source_errors(cause: Cause[Any]) -> Effect[Never, ConfigError]:
+    return fail_cause(Cause(tuple(map(_as_failure, cause.reasons))))
+
+
+def _as_failure(reason: Reason[Any]) -> Reason[Any]:
+    match reason:
+        case Die(SourceError() as error):
+            return Fail(ConfigError(error), annotations=reason.annotations)
+        case _:
+            return reason
+
+
+def _has_input(node: ast.AST, found: Node | None) -> bool:
+    """``found`` holds something the encoded shape ``node`` could read."""
+    match node:
+        case ast.Objects():
+            return isinstance(found, Record)
+        case ast.Arrays():
+            return isinstance(found, Array)
+        case ast.Union():
+            return any(_has_input(member, found) for member in node.types)
+        case ast.Suspend():
+            return _has_input(node.target, found)
+        case ast.Class():
+            return isinstance(found, Record)
+        case _:
+            return found is not None and found.value is not None
+
+
+def _is_scalar(node: ast.AST) -> bool:
+    match node:
+        case ast.Union():
+            return all(map(_is_scalar, node.types))
+        case ast.Objects() | ast.Arrays() | ast.Suspend() | ast.Class():
+            return False
+        case _:
+            return True
+
+
+type _Materialize = Callable[[_Cursor], Effect[object]]
+
+
+def _from_cursor(node: ast.AST, materialize: _Materialize) -> ast.AST:
+    """``node`` decoding from a cursor: ``materialize`` loads what it reads."""
+
+    def decode(cursor: object, _options: object) -> Effect[object]:
+        return materialize(cast("_Cursor", cursor))
+
+    def encode(value: object, _options: object) -> Effect[object]:
+        return succeed(value)
+
+    return ast.decode_to(ast.unknown, node, T.transform_effect(decode=decode, encode=encode))
+
+
+def _scalar(cursor: _Cursor) -> Effect[object]:
+    value = None if cursor.node is None else cursor.node.value
+    return succeed(_UNDEFINED if value is None else value)
+
+
+def _child(cursor: _Cursor, segment: str | int) -> Effect[_Cursor]:
+    return _load(cursor.provider, (*cursor.path, segment))
+
+
+class _CursorWalk:
+    """Effect's ``toConfigCursorAST``: each node of the encoded shape (the
+    node, or the last node of its encoding chain) decodes from a cursor."""
+
+    def __init__(self) -> None:
+        self._done: dict[int, tuple[ast.AST, ast.AST]] = {}
+        self._seen: set[int] = set()
+
+    def recur(self, node: ast.AST) -> ast.AST:
+        hit = self._done.get(id(node))
+        if hit is not None:
+            return hit[1]
+        self._seen.add(id(node))
+        if node.encoding is None:
+            out = self._step(node)
+        else:
+            *init, last = node.encoding
+            out = replace(
+                node, encoding=(*init, ast.Link(self.recur(last.to), last.transformation))
+            )
+        self._done[id(node)] = (node, out)
+        if isinstance(out, ast.Class) and isinstance(out.shape, _CursorShape):
+            # Walk the fields now, with the class memoized, so an opaque
+            # encoding raises when the config is made.
+            out.shape.start()
+        return out
+
+    def _step(self, node: ast.AST) -> ast.AST:
+        match node:
+            case ast.Objects():
+                properties = tuple(replace(p, type=self.recur(p.type)) for p in node.properties)
+                indexes = tuple(
+                    ast.IndexSignature(i.parameter, self.recur(i.type))
+                    for i in node.index_signatures
+                )
+                rebuilt = replace(node, properties=properties, index_signatures=indexes)
+                return _from_cursor(rebuilt, _objects(node))
+            case ast.Arrays():
+                elements = tuple(ast.Element(self.recur(e.type), e.optional) for e in node.elements)
+                rest = tuple(map(self.recur, node.rest))
+                return _from_cursor(replace(node, elements=elements, rest=rest), _arrays)
+            case ast.Union():
+                types = tuple(map(self.recur, node.types))
+                if not _is_scalar(node):
+                    return replace(node, types=types)
+            case ast.Suspend():
+                target = node.target
+                # Walk new targets now, so an opaque encoding raises when
+                # the config is made.
+                if id(target) not in self._seen:
+                    self.recur(target)
+                return replace(node, thunk=lambda: self.recur(target))
+            case ast.Declaration() | ast.Any():
+                raise ValueError(_OPAQUE)
+            case ast.Class():
+                return self._class(node)
+            case _:
+                pass
+        return _from_cursor(node, _scalar)
+
+    def _class(self, node: ast.Class) -> ast.AST:
+        # A class reads its fields' struct, as Effect's class declaration
+        # links it.
+        match node.side:
+            case "decode":
+                return replace(node, shape=_CursorShape(node.shape, self))
+            case "encoded":
+                return self.recur(node.shape.encoded)
+            case "type" | "encode":
+                raise ValueError(_OPAQUE)
+
+
+def _objects(node: ast.Objects) -> _Materialize:
+    names = [p.name for p in node.properties if isinstance(p.name, str)]
+
+    def materialize(cursor: _Cursor) -> Effect[object]:
+        found = cursor.node
+        if not isinstance(found, Record):
+            return succeed(_UNDEFINED)
+        keys = list(dict.fromkeys(names))
+        if node.index_signatures:
+            for key in found.keys:
+                if key not in keys and any(i.selects(key) for i in node.index_signatures):
+                    keys.append(key)
+        out: dict[str, _Cursor] = {}
+
+        def load(i: int) -> Effect[object]:
+            if i == len(keys):
+                return succeed(out)
+
+            def keep(child: _Cursor) -> Effect[object]:
+                if child.node is not None:
+                    out[keys[i]] = child
+                return load(i + 1)
+
+            return _child(cursor, keys[i]).flat_map(keep)
+
+        return load(0)
+
+    return materialize
+
+
+def _arrays(cursor: _Cursor) -> Effect[object]:
+    found = cursor.node
+    if not isinstance(found, Array):
+        return succeed(_UNDEFINED)
+    out: list[_Cursor] = []
+
+    def load(i: int) -> Effect[object]:
+        if i == found.length:
+            return succeed(out)
+
+        def keep(child: _Cursor) -> Effect[object]:
+            out.append(child)
+            return load(i + 1)
+
+        return _child(cursor, i).flat_map(keep)
+
+    return load(0)
+
+
+class _CursorShape:
+    """A schema class decoding its fields from a cursor. The fields are
+    walked on first use, after the class node is memoized, so a field that
+    refers back to the class meets its walked node."""
+
+    __slots__ = ("_fields", "_started", "base", "walk")
+
+    def __init__(self, base: ast.ClassShape, walk: _CursorWalk) -> None:
+        self.base = base
+        self.walk = walk
+        self._fields: ast.Objects | None = None
+        self._started = False
+
+    @property
+    def fields(self) -> ast.Objects:
+        if self._fields is None:
+            self._started = True
+            self._fields = cast("ast.Objects", self.walk.recur(self.base.fields))
+        return self._fields
+
+    def start(self) -> None:
+        """Walk the fields unless that already began."""
+        if not self._started:
+            self.fields  # noqa: B018
+
+    @property
+    def cls(self) -> type:
+        return self.base.cls
+
+    @property
+    def encoded(self) -> ast.AST:
+        return self.base.encoded
+
+    @property
+    def checks(self) -> ast.Checks | None:
+        return self.base.checks
+
+    def construct(self, values: dict[object, object]) -> object:
+        return self.base.construct(values)
+
+    def values_of(self, instance: object) -> dict[object, object]:
+        return self.base.values_of(instance)

pyfect/config_provider/__init__.py

@@ -0,0 +1,60 @@
+"""Configuration sources (Effect's ``ConfigProvider``).
+
+A ``ConfigProvider`` looks a path up and finds a ``Node``: a ``Value``
+(a string), a ``Record`` (child keys) or an ``Array`` (a length), or
+``None`` when nothing is there::
+
+    provider = config_provider.from_env(env={"APP_PORT": "3000"})
+    provider.load(("APP", "PORT"))  # Effect[Node | None, SourceError]: Value("3000")
+
+Sources: ``from_env`` (``os.environ`` by default), ``from_env_record``,
+``from_unknown`` (nested dicts and lists), ``from_dot_env_contents`` /
+``from_dot_env`` (``.env`` files), ``from_dir`` (a file per key) and
+``make`` (any lookup function). Combinators are methods: ``or_else``,
+``map_input``, ``nested``, ``constant_case``. ``CurrentConfigProvider`` is
+the provider configuration is read from (``from_env()`` unless a ``layer``
+or ``layer_add`` installs another)."""
+
+from pyfect._public import publish
+from pyfect.config_provider._dir import from_dir
+from pyfect.config_provider._dotenv import from_dot_env, from_dot_env_contents
+from pyfect.config_provider._env import from_env, from_env_record
+from pyfect.config_provider._layers import layer, layer_add
+from pyfect.config_provider._node import (
+    Array,
+    Keys,
+    Node,
+    Path,
+    PathInput,
+    Record,
+    Segment,
+    SourceError,
+    Value,
+)
+from pyfect.config_provider._provider import ConfigProvider, CurrentConfigProvider, make
+from pyfect.config_provider._unknown import from_unknown
+
+__all__ = [
+    "Array",
+    "ConfigProvider",
+    "CurrentConfigProvider",
+    "Keys",
+    "Node",
+    "Path",
+    "PathInput",
+    "Record",
+    "Segment",
+    "SourceError",
+    "Value",
+    "from_dir",
+    "from_dot_env",
+    "from_dot_env_contents",
+    "from_env",
+    "from_env_record",
+    "from_unknown",
+    "layer",
+    "layer_add",
+    "make",
+]
+
+publish(globals())

pyfect/config_provider/_dir.py

@@ -0,0 +1,84 @@
+"""``from_dir``: one file per key, as Kubernetes and Docker mount secrets."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Generator
+from typing import Any, Never
+
+from pyfect import _js
+from pyfect._core import Effect
+from pyfect.config_provider._node import Keys, Node, Path, Record, SourceError, Value
+from pyfect.config_provider._provider import ConfigProvider, make
+from pyfect.effect import fail, gen, succeed
+from pyfect.file_system import FileSystem, FileSystemService
+from pyfect.path import Path as PathTag
+from pyfect.path import PathService
+from pyfect.platform_error import NotFound, PlatformError
+
+
+def from_dir(
+    root_path: str | os.PathLike[str] = "/", *, preserve_empty_strings: bool = False
+) -> Effect[ConfigProvider, Never, PathTag | FileSystem]:
+    """A provider over the files under ``root_path``, read through the
+    ``FileSystem`` and ``Path`` services: the path ``("db", "password")``
+    reads the file ``<root_path>/db/password`` (trimmed) as a value, and a
+    directory is a record of its entry names. A path missing both as a file
+    and as a directory is absent; any other failure is a ``SourceError``
+    holding the ``PlatformError``. A path leading above ``root_path`` (``..``)
+    is absent. An empty file is absent unless
+    ``preserve_empty_strings``. Files are read at each lookup."""
+
+    root = os.fspath(root_path)
+
+    def build() -> Generator[Effect[Any, Never, PathTag | FileSystem], Any, ConfigProvider]:
+        paths = yield from PathTag()
+        fs = yield from FileSystem()
+        return make(lambda path: _load(paths, fs, root, path, preserve_empty_strings))
+
+    return gen(build)
+
+
+def _load(
+    paths: PathService,
+    fs: FileSystemService,
+    root: str,
+    path: Path,
+    preserve_empty_strings: bool,
+) -> Effect[Node | None, SourceError]:
+    # Like Node's path.join, a segment is joined below the root even when
+    # it starts with a separator.
+    segments = [str(segment).lstrip("/" + paths.sep) for segment in path]
+    full = paths.normalize(paths.join(root, *segments))
+    # Unlike Effect, a path whose ``..`` segments lead above the root is
+    # absent rather than read.
+    if segments and paths.resolve_within(root, paths.join(*segments)) is None:
+        return succeed(None)
+
+    def as_file(content: str) -> Node | None:
+        value = _js.trim(content)
+        return None if value == "" and not preserve_empty_strings else Value(value)
+
+    def as_directory(entries: list[str]) -> Node | None:
+        return Record(Keys(paths.basename(entry) for entry in entries))
+
+    def after_file(file_error: PlatformError) -> Effect[Node | None, PlatformError]:
+        return (
+            fs.read_directory(full)
+            .map(as_directory)
+            .catch_all(lambda dir_error: _absent_or(file_error, dir_error))
+        )
+
+    return (
+        fs.read_file_string(full)
+        .map(as_file)
+        .catch_all(after_file)
+        .map_error(lambda cause: SourceError(f"Failed to read file at {full}", cause))
+    )
+
+
+def _absent_or(file_error: PlatformError, dir_error: PlatformError) -> Effect[None, PlatformError]:
+    file_missing = isinstance(file_error.reason, NotFound)
+    if file_missing and isinstance(dir_error.reason, NotFound):
+        return succeed(None)
+    return fail(dir_error if file_missing else file_error)

pyfect/config_provider/_dotenv.py

@@ -0,0 +1,127 @@
+"""``.env`` files: Effect's parser (the ``dotenv`` package's rules) and its
+``dotenv-expand``-style ``$NAME`` / ``${NAME:-default}`` expansion."""
+
+from __future__ import annotations
+
+import os
+import re
+
+from pyfect import _js
+from pyfect._core import Effect
+from pyfect.config_provider._env import from_env_record
+from pyfect.config_provider._provider import ConfigProvider
+from pyfect.file_system import FileSystem
+from pyfect.platform_error import PlatformError
+
+# Effect's regexes with JavaScript's \s, ".", and multiline "^" / "$".
+_S = f"[{_js.SPACE}]"
+_START = f"(?:\\A|(?<=[{_js.LINE_END}]))"
+_END = f"(?=[{_js.LINE_END}]|\\Z)"
+_LINE = re.compile(
+    rf"{_START}{_S}*(?:export{_S}+)?([A-Za-z0-9_.-]+)(?:{_S}*={_S}*?|:{_S}+?)"
+    rf"({_S}*'(?:\\'|[^'])*'|{_S}*\"(?:\\\"|[^\"])*\"|{_S}*`(?:\\`|[^`])*`|[^#\r\n]+)?"
+    rf"{_S}*(?:#[^{_js.LINE_END}]*)?{_END}"
+)
+_QUOTED = re.compile(rf"{_START}(['\"`])([\s\S]*)\1{_END}")
+_REFERENCE = re.compile(r"\$\{?([A-Za-z0-9_]+)")
+
+
+def from_dot_env_contents(
+    contents: str, *, expand_variables: bool = False, preserve_empty_strings: bool = False
+) -> ConfigProvider:
+    """A provider over the ``NAME=value`` lines of a ``.env`` file, read as
+    ``from_env_record`` reads them. ``#`` comments, ``export`` prefixes and
+    single, double or backtick quotes are understood; ``\\n`` and ``\\r``
+    are expanded inside double quotes. With ``expand_variables``, ``$NAME``,
+    ``${NAME}`` and ``${NAME:-default}`` are replaced by other entries of the
+    file (``\\$`` stays a literal ``$``)."""
+    env = _parse(contents)
+    if expand_variables:
+        env = _expand(env)
+    return from_env_record(env, preserve_empty_strings=preserve_empty_strings)
+
+
+def from_dot_env(
+    path: str | os.PathLike[str] = ".env",
+    *,
+    expand_variables: bool = False,
+    preserve_empty_strings: bool = False,
+) -> Effect[ConfigProvider, PlatformError, FileSystem]:
+    """Read ``path`` with the ``FileSystem`` service and build
+    ``from_dot_env_contents`` from it; a file that cannot be read fails
+    with the file system's ``PlatformError``."""
+    file = os.fspath(path)
+    return FileSystem().flat_map(
+        lambda fs: fs.read_file_string(file).map(
+            lambda contents: from_dot_env_contents(
+                contents,
+                expand_variables=expand_variables,
+                preserve_empty_strings=preserve_empty_strings,
+            )
+        )
+    )
+
+
+def _parse(contents: str) -> dict[str, str]:
+    env: dict[str, str] = {}
+    text = re.sub(r"\r\n?", "\n", contents)
+    for match in _LINE.finditer(text):
+        value = _js.trim(match.group(2) or "")
+        quote = value[:1]
+        value = _QUOTED.sub(r"\2", value)
+        if quote == '"':
+            value = value.replace("\\n", "\n").replace("\\r", "\r")
+        env[match.group(1)] = value
+    return env
+
+
+def _expand(parsed: dict[str, str]) -> dict[str, str]:
+    return {
+        key: _interpolate(value, parsed, frozenset({key})).replace("\\$", "$")
+        for key, value in parsed.items()
+    }
+
+
+def _interpolate(text: str, parsed: dict[str, str], seen: frozenset[str]) -> str:
+    """Replace the references in ``text``. A reference already being
+    expanded (a cycle, or a name referring to itself) expands to nothing;
+    substituted values are not scanned again."""
+    out: list[str] = []
+    cursor = 0
+    position = 0
+    while (match := _REFERENCE.search(text, position)) is not None:
+        start = match.start()
+        position = match.end()
+        if start > 0 and text[start - 1] == "\\":
+            continue
+        name = match.group(1)
+        end = position
+        default = ""
+        if text.startswith(":-", end):
+            end += 2
+            default_start = end
+            depth = 0
+            # Match the default's braces in the source, not in substituted values.
+            while end < len(text):
+                if text.startswith("${", end):
+                    depth += 1
+                    end += 1
+                elif text[end] == "}":
+                    if depth == 0:
+                        break
+                    depth -= 1
+                end += 1
+            default = text[default_start:end]
+        if text.startswith("}", end):
+            end += 1
+        expanded = (
+            _interpolate(parsed[name], parsed, seen | {name})
+            if name in parsed and name not in seen
+            else ""
+        )
+        out.append(text[cursor:start])
+        out.append(expanded or _interpolate(default, parsed, seen))
+        cursor = end
+        position = end
+    out.append(text[cursor:])
+    return "".join(out)

pyfect/config_provider/_env.py

@@ -0,0 +1,79 @@
+"""``from_env`` and ``from_env_record``: flat ``NAME=value`` pairs read as a
+tree, each ``_`` in a name starting a new path segment."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from pyfect._digits import parse_digits
+from pyfect.config_provider._node import Array, Keys, Node, Path, Record, Value
+from pyfect.config_provider._provider import ConfigProvider, make
+from pyfect.effect import succeed
+
+_MAX_INDEX = 2**32 - 1
+
+
+type _Trie = dict[str, _Trie]
+"""Name segments below a path; empty when no name continues past it."""
+
+
+def from_env_record(
+    env: Mapping[str, str | None], *, preserve_empty_strings: bool = False
+) -> ConfigProvider:
+    """A provider over ``env``; ``None`` values are skipped. A name is split
+    on every ``_`` (``A__B`` has an empty middle segment), and a path also
+    matches the name its segments join to, so ``("NODE_ENV",)`` and
+    ``("NODE", "ENV")`` both find ``NODE_ENV``. A path whose children are
+    all array indices (``A_0``, ``A_1``) is an ``Array``; one with other
+    children a ``Record``, holding the path's own value if it has one. An
+    empty value is absent unless ``preserve_empty_strings``. As in Effect,
+    the names are read when the provider is made and the values at each
+    lookup."""
+    trie = _trie(env)
+    return make(lambda path: succeed(_node_at(trie, env, path, preserve_empty_strings)))
+
+
+def from_env(
+    env: Mapping[str, str] | None = None, *, preserve_empty_strings: bool = False
+) -> ConfigProvider:
+    """``from_env_record`` over ``env``, or over a copy of ``os.environ``
+    made now (as Effect copies ``process.env``), so later writes to the
+    environment are not seen."""
+    return from_env_record(
+        dict(os.environ) if env is None else env, preserve_empty_strings=preserve_empty_strings
+    )
+
+
+def _trie(env: Mapping[str, str | None]) -> _Trie:
+    root: _Trie = {}
+    for name, value in env.items():
+        if value is None:
+            continue
+        node = root
+        for segment in name.split("_"):
+            node = node.setdefault(segment, {})
+    return root
+
+
+def _node_at(
+    trie: _Trie, env: Mapping[str, str | None], path: Path, preserve_empty_strings: bool
+) -> Node | None:
+    leaf = env.get("_".join(str(seg) for seg in path))
+    if leaf == "" and not preserve_empty_strings:
+        leaf = None
+    node: _Trie | None = trie
+    for seg in path:
+        node = node.get(str(seg))
+        if node is None:
+            break
+    if not node:
+        return None if leaf is None else Value(leaf)
+    if all(_is_index(child) for child in node):
+        return Array(max(int(child) for child in node) + 1, leaf)
+    return Record(Keys(node), leaf)
+
+
+def _is_index(key: str) -> bool:
+    index = parse_digits(key, unpadded=True)
+    return index is not None and index < _MAX_INDEX