Add typed PowerShell object projection

[MariusStorhaug]

Context

PowerShell class instances provide a natural rich-object target for YAML configuration. YAML mappings can be bound into typed objects when callers explicitly request that projection.

Official YAML 1.2.2 references:

• Native data structures and loading: https://yaml.org/spec/1.2.2/#41-processes
• Mapping model: https://yaml.org/spec/1.2.2/#3211-nodes
• Normative module spec: spec/Typed-Projection.md

Current State

The module projects YAML values to PowerShell-native scalar, sequence, object, and dictionary shapes. It does not bind mappings directly to caller-specified classes.

Objective

Add opt-in typed projection that binds YAML mappings into PowerShell classes or supported .NET types while preserving safe default projection.

PowerShell Design Considerations

• Use a clear -As [type] style parameter and avoid conflict with existing -AsHashtable semantics through parameter sets.
• Support rich PowerShell class construction and property binding without invoking arbitrary YAML-driven types.
• Provide predictable conversion rules for scalars, arrays, dictionaries, nullable values, enums, and nested classes.
• Errors should identify missing required data, unknown members, conversion failures, and constructor limitations.

Tasks

• Add opt-in typed projection for a caller-specified type.
• Define binding rules for properties, constructors, and nested values.
• Define handling for missing, extra, null, and default values.
• Compose typed projection with schema selection and tag resolution.
• Document class examples and pipeline behavior.

Benefits

• Lets users consume YAML directly as domain-specific PowerShell objects.
• Keeps default projection simple and safe.
• Reduces boilerplate conversion code in scripts and modules.

Acceptance Criteria

• A mapping can be projected into a caller-specified PowerShell class.
• Nested mappings and sequences bind predictably to typed members.
• Binding failures produce classified errors with member context.
• Typed projection is opt-in and mutually clear with other projection modes.
• Tests cover classes, enums, arrays, nulls, required values, and failures.

Related

• Spec folder: spec/Typed-Projection.md