directory-to-object 0.3.1

directory-to-object-dotnet

.NET implementation of the directory-to-object configuration reader library, tailored to the System.Text.Json JSON parser.

As with its TypeScript ancestor, this library is for complicated configuration cases where having just one structured file is too limiting or is hard for humans to understand. Instead of cramming all the configuration into one structured file, this library will combine configuration data split across multiple files in a directory into a single System.Text.Json.Nodes JsonObject. Consuming code sees the directory contents as the equivalent of a single configuration file.

The library targets .NET 10 (net10.0), .NET 8.0 (net8.0) and netstandard2.0 for maximum compatibility.

Using the library

Install from NuGet

dotnet add package directory-to-object

Build locally

Simply:

dotnet build

To run the TUnit tests from the command line (substitute a different framework identifier, as needed):

dotnet run --project directory-to-object.Tests/directory-to-object.Tests.csproj --framework=net10.0

Reference documentation

Documentation for the latest version of the library is available at: directory-to-object-dotnet.scroogieboy.com.

Examples

Simple loading

The simplest example is to use the default settings for the loader (which treats files with the ".json" extension as JSON and files with the ".txt" extension as plain text files):

using DirectoryToObject;

// Get a directory loader with default options.
var loader = Loader.Default;

// Load a directory from the file system, specified by path, into a JsonObject.
var contents = await loader.LoadFileSystemPathIntoJsonObjectAsync("path/to/my/directory");

Directories as arrays

It's sometimes useful to represent arrays of objects as directories of JSON files. The library now supports loading directories directly as arrays (using the LoadDirectoryIntoJsonArrayAsync extension method) or by specifying explicit loading instructions. For example (from the tests):

var loader = Loader.FromHandlerCollection(
[
    Handler.JsonFile.WhenExtensionIsOneOf(".json"),
    Handler.TextFile.WhenExtensionIsOneOf(".txt"),
    Handler.Directory.WhenPathMatchesAny("spec/containers", "spec/volumes").AsArray("name")
]);

var manifest = await loader.LoadFileSystemPathIntoJsonObjectAsync(manifestDirectoryPath);

This snippet informs the loader to treat the directories at the "spec/containers" and "spec/volumes" relative paths as arrays, mapping the file name into the "name" property of every loaded object.