@valkyrjaio/valkyrja 26.8.17 → 26.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyrjaio/valkyrja",
-    "version": "26.8.17",
+    "version": "26.9.0",
     "description": "The Valkyrja Framework.",
     "keywords": [
         "framework",

package/src/Valkyrja/Application/Constant/ApplicationInfo.ts

@@ -7,8 +7,8 @@
  */
 
 export class ApplicationInfo {
-    static readonly VERSION = '26.8.17' as const;
-    static readonly VERSION_BUILD_DATE_TIME = 'September 26 2026 09:12:25 MST' as const;
+    static readonly VERSION = '26.9.0' as const;
+    static readonly VERSION_BUILD_DATE_TIME = 'October 19 2026 11:37:33 MST' as const;
     static readonly ASCII = `
                  _ _               _
      /\\   /\\__ _| | | ___   _ _ __(_) __ _

package/src/Valkyrja/Cli/README.md

@@ -251,8 +251,9 @@ An empty string given at the call site counts as a default, so it suppresses
 the declared one. Omit the default, or pass `null`, to reach step 3.
 
 `getArgumentValue()` reads step 1 and step 2, because an argument declares no
-default. Read the parameter's own `getCastValues()` for every value of a
-parameter in `ARRAY` value mode.
+default. Read `ParameterContract.getValues()` for every raw value of a parameter
+in `ARRAY` value mode, and `Caster.getCastValues()` for every value with the
+cast applied.
 
 ```ts
 const isShort = route.hasProvidedOption('short');
@@ -319,11 +320,45 @@ group and keeps the default for the rest.
 
 ### Value casting
 
-A parameter carries an optional `Cast`. See [Type](../Type/README.md).
+Warning: the router applies no cast. `getArgumentValue()` and `getOptionValue()`
+on the route return the raw string, whatever cast the parameter declares. The
+application asks the caster for the cast values.
 
-Note that the CLI stores the cast and does not apply it.
-`getCastValuesForParameters()` returns each raw value, whether the parameter
-carries a cast or not.
+`Caster` applies the cast, and the parameter applies nothing. `Caster` holds the
+container, so the data object needs none. The parameter holds the cast and the
+raw values, and `getValues()` returns those raw values.
+
+`Caster.getCastValues()` reads `cast.type` as a container binding key. It passes
+the raw value as the first entry of the factory's `args`. It returns the
+converted value when `cast.convert` is `true`, and the type itself when
+`cast.convert` is `false`. It returns each raw value for a parameter that holds
+no cast.
+
+Warning: register a cast type with `bind`. The caster calls `getService()`, and
+`getService()` skips the singleton cache, so the container builds a type that
+`bindSingleton` registers for each value, and not once for the application. An
+alias, and an instance that `setSingleton` holds, raise
+`ContainerInvalidReferenceException`. See [Type](../Type/README.md).
+
+Warning: the factory must return a `TypeContract`. The caster calls `asValue()`
+on the object that the container builds, and an object without that method
+raises a `TypeError`.
+
+```ts
+import { Argument } from '@valkyrjaio/valkyrja/Cli/Interaction/Argument/Argument.ts';
+import { ArgumentParameter } from '@valkyrjaio/valkyrja/Cli/Routing/Data/ArgumentParameter.ts';
+import { CliRoutingServiceId } from '@valkyrjaio/valkyrja/Cli/Routing/Constant/CliRoutingServiceId.ts';
+import { Cast } from '@valkyrjaio/valkyrja/Type/Data/Cast.ts';
+
+import type { CasterContract } from '@valkyrjaio/valkyrja/Cli/Routing/Caster/Contract/CasterContract.ts';
+
+container.bind('App.Type.Slug', Slug.make);
+
+const parameter = new ArgumentParameter('target', 'The target', new Cast('App.Type.Slug')).withArguments(
+    new Argument('a-slug'),
+);
+const values = container.getSingleton<CasterContract>(CliRoutingServiceId.CasterContract).getCastValues(parameter);
+```
 
 ## Input and output
 
@@ -602,6 +637,7 @@ list, because the input handler runs that stage before it matches a route.
 | `CliRoutingServiceId.RouterContract`                   | A `Router`                             |
 | `CliRoutingServiceId.RouteCollectionContract`          | A `RouteCollection`                    |
 | `CliRoutingServiceId.RouteCollectorContract`           | An `AttributeRouteCollector`           |
+| `CliRoutingServiceId.CasterContract`                   | A `Caster`, which applies a cast       |
 | `CliRoutingServiceId.CliRoutingData`                   | The collection's `CliRoutingData`      |
 | `CliRoutingServiceId.RouteContract`                    | The matched route, set at dispatch     |
 | `CliInteractionServiceId.CliInteractionConfigContract` | The interaction config                 |

package/src/Valkyrja/Cli/Routing/Caster/Caster.ts

@@ -0,0 +1,32 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import type { ContainerContract } from '../../../Container/Manager/Contract/ContainerContract.ts';
+import type { TypeContract } from '../../../Type/Contract/TypeContract.ts';
+import type { ParameterContract } from '../Data/Contract/ParameterContract.ts';
+import type { CasterContract } from './Contract/CasterContract.ts';
+
+export class Caster implements CasterContract {
+    constructor(protected container: ContainerContract) {}
+
+    getCastValues(parameter: ParameterContract): unknown[] {
+        const values = parameter.getValues();
+
+        if (!parameter.hasCast()) {
+            return values;
+        }
+
+        const cast = parameter.getCast();
+
+        return values.map((value) => {
+            const type = this.container.getService<TypeContract>(cast.type, [value]);
+
+            return cast.convert ? type.asValue() : type;
+        });
+    }
+}

package/src/Valkyrja/Cli/Routing/Caster/Contract/CasterContract.ts

@@ -0,0 +1,13 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import type { ParameterContract } from '../../Data/Contract/ParameterContract.ts';
+
+export interface CasterContract {
+    getCastValues(parameter: ParameterContract): unknown[];
+}

package/src/Valkyrja/Cli/Routing/Constant/CliRoutingServiceId.ts

@@ -10,6 +10,7 @@ export class CliRoutingServiceId {
     static readonly RouterContract = 'Valkyrja.Cli.Routing.Dispatcher.RouterContract' as const;
     static readonly RouteCollectionContract = 'Valkyrja.Cli.Routing.Collection.RouteCollectionContract' as const;
     static readonly RouteCollectorContract = 'Valkyrja.Cli.Routing.Collector.RouteCollectorContract' as const;
+    static readonly CasterContract = 'Valkyrja.Cli.Routing.Caster.CasterContract' as const;
     static readonly RouteContract = 'Valkyrja.Cli.Routing.Data.RouteContract' as const;
     static readonly CliRoutingData = 'Valkyrja.Cli.Routing.Data.CliRoutingData' as const;
     static readonly CliRoutingConfigContract = 'Valkyrja.Cli.Routing.Data.CliRoutingConfigContract' as const;

package/src/Valkyrja/Cli/Routing/Data/Abstract/Parameter.ts

@@ -6,8 +6,6 @@
  * Released under the MIT License. See LICENSE.md for details.
  */
 
-import type { ArgumentContract } from '../../../Interaction/Argument/Contract/ArgumentContract.ts';
-import type { OptionContract } from '../../../Interaction/Option/Contract/OptionContract.ts';
 import type { ParameterContract } from '../Contract/ParameterContract.ts';
 import type { Cast } from '../../../../Type/Data/Cast.ts';
 import { CliRoutingNoCastException } from '../../Throwable/Exception/CliRoutingNoCastException.ts';
@@ -63,25 +61,7 @@ export abstract class Parameter implements ParameterContract {
         return clone;
     }
 
-    abstract getCastValues(): unknown[];
-
-    protected getCastValuesForParameters(parameters: Array<ArgumentContract | OptionContract>): unknown[] {
-        const values: unknown[] = [];
-        const cast = this.cast;
-
-        for (const param of parameters) {
-            const paramValue = param.getValue();
-
-            if (cast === null) {
-                values.push(paramValue);
-                continue;
-            }
-
-            values.push(paramValue);
-        }
-
-        return values;
-    }
+    abstract getValues(): string[];
 
     abstract isProvided(): boolean;
     abstract hasFirstValue(): boolean;

package/src/Valkyrja/Cli/Routing/Data/ArgumentParameter.ts

@@ -63,8 +63,8 @@ export class ArgumentParameter extends Parameter implements ArgumentParameterCon
         return clone;
     }
 
-    getCastValues(): unknown[] {
-        return this.getCastValuesForParameters(this.arguments_);
+    getValues(): string[] {
+        return this.arguments_.map((argument) => argument.getValue());
     }
 
     isProvided(): boolean {

package/src/Valkyrja/Cli/Routing/Data/Contract/ParameterContract.ts

@@ -17,7 +17,7 @@ export interface ParameterContract {
     withoutCast(): this;
     getDescription(): string;
     withDescription(description: string): this;
-    getCastValues(): unknown[];
+    getValues(): string[];
     isProvided(): boolean;
     hasFirstValue(): boolean;
     getFirstValue(): string;

package/src/Valkyrja/Cli/Routing/Data/OptionParameter.ts

@@ -152,8 +152,8 @@ export class OptionParameter extends Parameter implements OptionParameterContrac
         return clone;
     }
 
-    getCastValues(): unknown[] {
-        return this.getCastValuesForParameters(this.options);
+    getValues(): string[] {
+        return this.options.map((option) => option.getValue());
     }
 
     isProvided(): boolean {

package/src/Valkyrja/Cli/Routing/Provider/CliRoutingServiceProvider.ts

@@ -25,6 +25,8 @@ import type { RouteCollectorContract } from '../Collector/Contract/RouteCollecto
 import type { RouteContract } from '../Data/Contract/RouteContract.ts';
 import { CliRoutingServiceId } from '../Constant/CliRoutingServiceId.ts';
 import { CliRoutingData } from '../Data/CliRoutingData.ts';
+import { Caster } from '../Caster/Caster.ts';
+import type { CasterContract } from '../Caster/Contract/CasterContract.ts';
 import type { RouterContract } from '../Dispatcher/Contract/RouterContract.ts';
 import { Router } from '../Dispatcher/Router.ts';
 
@@ -34,6 +36,7 @@ export class CliRoutingServiceProvider implements ServiceProviderContract {
             [CliRoutingServiceId.RouterContract]: CliRoutingServiceProvider.publishRouter,
             [CliRoutingServiceId.RouteCollectionContract]: CliRoutingServiceProvider.publishRouteCollection,
             [CliRoutingServiceId.RouteCollectorContract]: CliRoutingServiceProvider.publishAttributeRouteCollector,
+            [CliRoutingServiceId.CasterContract]: CliRoutingServiceProvider.publishCaster,
             [CliRoutingServiceId.CliRoutingData]: CliRoutingServiceProvider.publishData,
         };
     }
@@ -87,6 +90,10 @@ export class CliRoutingServiceProvider implements ServiceProviderContract {
         );
     }
 
+    static publishCaster(this: void, container: ContainerContract): void {
+        container.setSingleton<CasterContract>(CliRoutingServiceId.CasterContract, new Caster(container));
+    }
+
     static publishData(this: void, container: ContainerContract): void {
         const collection = container.getSingleton<RouteCollectionContract>(CliRoutingServiceId.RouteCollectionContract);
         const app = container.getSingleton<ApplicationContract>(ApplicationServiceId.ApplicationContract);

package/src/Valkyrja/Container/Manager/ChildContainer.ts

@@ -6,12 +6,16 @@
  * Released under the MIT License. See LICENSE.md for details.
  */
 
+import { ContainerCyclicAliasException } from '../Throwable/Exception/ContainerCyclicAliasException.ts';
 import { Container } from './Container.ts';
 
 import type { ContainerData } from '../Data/ContainerData.ts';
 import type { ContainerContract } from './Contract/ContainerContract.ts';
 
 export class ChildContainer extends Container {
+    /** The alias targets this container is resolving. */
+    protected targetsInFlight = new Set<string>();
+
     constructor(
         protected parent: ContainerContract,
         data: ContainerData,
@@ -34,10 +38,6 @@ export class ChildContainer extends Container {
         return super.isSingletonInstance(id) || this.parent.isSingletonInstance(id);
     }
 
-    override isDeferred(id: string): boolean {
-        return super.isDeferred(id) || this.parent.isDeferred(id);
-    }
-
     override isPublished(id: string): boolean {
         return super.isPublished(id) || this.parent.isPublished(id);
     }
@@ -58,11 +58,106 @@ export class ChildContainer extends Container {
         return super.getServiceWithoutChecks<T>(id, args);
     }
 
+    override getAliasedId(alias: string): string | undefined {
+        return super.getAliasedId(alias) ?? this.parent.getAliasedId(alias);
+    }
+
     protected override getAliasedWithoutChecks<T extends object>(id: string, args: unknown[] = []): T | undefined {
-        if (!super.isAlias(id) && this.parent.isAlias(id)) {
-            return this.parent.getAliased<T>(id, args);
+        if (super.isAlias(id)) {
+            return super.getAliasedWithoutChecks<T>(id, args);
+        }
+
+        const target = this.getParentAliasTarget(id);
+
+        if (target === undefined) {
+            return undefined;
+        }
+
+        // The child holds the same registration. One request must not hold one copy
+        // for the alias and another for the target.
+        if (this.resolvesInChild(target)) {
+            return this.getTargetOnce<T>(id, target, args);
+        }
+
+        return this.parent.getAliased<T>(id, args);
+    }
+
+    /**
+     * Resolve an alias target, and check a chain that returns to one already in flight.
+     */
+    protected getTargetOnce<T extends object>(id: string, target: string, args: unknown[]): T {
+        // A chain that closes across two walks returns here rather than to one walk. An
+        // instance cached for the target has broken the chain, so read that first.
+        if (this.targetsInFlight.has(target)) {
+            const registered = this.getSingletonInstance<T>(target);
+
+            if (registered !== undefined) {
+                return registered;
+            }
+
+            throw new ContainerCyclicAliasException(id, target);
+        }
+
+        this.targetsInFlight.add(target);
+
+        try {
+            return this.get<T>(target, args);
+        } finally {
+            this.targetsInFlight.delete(target);
+        }
+    }
+
+    /**
+     * Walk the parent's chain of aliases, and return the last hop it reaches.
+     */
+    protected getParentAliasTarget(id: string): string | undefined {
+        let current = id;
+        let target: string | undefined;
+        let aliasedId = this.parent.getAliasedId(current);
+        const seen = new Set<string>([id]);
+
+        while (aliasedId !== undefined) {
+            // A parent that is itself a child reads its own map and its parent's, and a
+            // binding made on either after it was built can close a chain between them.
+            if (seen.has(aliasedId)) {
+                throw new ContainerCyclicAliasException(current, aliasedId);
+            }
+
+            seen.add(aliasedId);
+            target = aliasedId;
+            current = aliasedId;
+
+            // The parent reads these before it follows an alias, so it can answer at this
+            // hop rather than continue the chain.
+            if (
+                (this.parent.isDeferred(current) && !this.parent.isPublished(current)) ||
+                this.parent.isSingleton(current) ||
+                this.parent.isService(current)
+            ) {
+                break;
+            }
+
+            aliasedId = this.parent.getAliasedId(current);
+        }
+
+        return target;
+    }
+
+    /**
+     * Check whether the child resolves the target of a parent-declared alias itself.
+     */
+    protected resolvesInChild(target: string): boolean {
+        // The parent publishes before it reads any map, so this test comes first. The
+        // parent's state and the child's callback each decide one half.
+        if (this.parent.isDeferred(target) && !this.parent.isPublished(target) && this.isDeferred(target)) {
+            return true;
+        }
+
+        if (this.parent.isSingletonInstance(target)) {
+            return false;
         }
 
-        return super.getAliasedWithoutChecks<T>(id, args);
+        // Both containers answer here, and each marker decides one half.
+        return this.parent.isSingletonBinding(target) && this.isSingletonBinding(target);
     }
 }

package/src/Valkyrja/Container/Manager/Container.ts

@@ -7,6 +7,7 @@
  */
 
 import { ContainerData } from '../Data/ContainerData.ts';
+import { ContainerCyclicAliasException } from '../Throwable/Exception/ContainerCyclicAliasException.ts';
 import { ContainerInvalidReferenceException } from '../Throwable/Exception/ContainerInvalidReferenceException.ts';
 import { ContainerInvalidPublishCallbackException } from '../Throwable/Exception/ContainerInvalidPublishCallbackException.ts';
 
@@ -22,6 +23,9 @@ export class Container implements ContainerContract {
     protected published: Record<string, boolean> = {};
 
     constructor(data: ContainerData = new ContainerData()) {
+        // Nothing is installed yet, so past the map there is nothing to read
+        this.validateAliasMapIsNotCyclic(data.aliases, () => undefined);
+
         this.aliases = { ...data.aliases };
         this.deferredCallback = { ...data.deferredCallback };
         this.services = { ...data.services };
@@ -38,7 +42,13 @@ export class Container implements ContainerContract {
     }
 
     setFromData(data: ContainerData): void {
-        this.aliases = { ...this.aliases, ...data.aliases };
+        const aliases = { ...this.aliases, ...data.aliases };
+
+        // Only the incoming aliases start a walk, and each walk reads the container past
+        // the map it is given. Nothing is installed before the walks end.
+        this.validateAliasMapIsNotCyclic(data.aliases, (id) => this.getAliasedId(id));
+
+        this.aliases = aliases;
         this.deferredCallback = { ...this.deferredCallback, ...data.deferredCallback };
         this.services = { ...this.services, ...data.services };
         this.singletons = { ...this.singletons, ...data.singletons };
@@ -56,11 +66,81 @@ export class Container implements ContainerContract {
     }
 
     bindAlias(alias: string, id: string): this {
+        this.validateAliasIsNotCyclic(alias, id);
+
         this.aliases[alias] = id;
 
         return this;
     }
 
+    /**
+     * Validate that an alias does not point at a chain that returns to it.
+     */
+    protected validateAliasIsNotCyclic(alias: string, id: string): void {
+        if (alias === id) {
+            throw new ContainerCyclicAliasException(alias, id);
+        }
+
+        const seen = new Set<string>();
+        let current = id;
+        let aliasedId = this.getAliasedId(current);
+
+        while (aliasedId !== undefined) {
+            if (aliasedId === alias) {
+                throw new ContainerCyclicAliasException(alias, id);
+            }
+
+            // A parent that binds an alias after a child is built checks only its own map,
+            // so the two can hold a cycle this alias is no part of. End the walk there.
+            if (seen.has(aliasedId)) {
+                return;
+            }
+
+            seen.add(aliasedId);
+            current = aliasedId;
+            aliasedId = this.getAliasedId(current);
+        }
+    }
+
+    /**
+     * Validate that no alias in a map points at a chain that returns to it.
+     */
+    protected validateAliasMapIsNotCyclic(
+        aliases: Record<string, string>,
+        installed: (id: string) => string | undefined,
+    ): void {
+        // `installed` is a parameter rather than a call, because an override reaches a
+        // subclass the constructor has not set up yet.
+
+        // Past the supplied aliases, the walk reads what the container answers already,
+        // so it follows a chain the supplied map only reaches into.
+        const next = (id: string): string | undefined => (Object.hasOwn(aliases, id) ? aliases[id] : installed(id));
+
+        for (const alias of Object.keys(aliases)) {
+            const seen = new Set<string>([alias]);
+            let current = alias;
+            let aliasedId = next(current);
+
+            while (aliasedId !== undefined) {
+                // The chain returns to the alias this walk started from, so the map the
+                // caller supplied is what closes it. Name the edge that took it there.
+                if (aliasedId === alias) {
+                    throw new ContainerCyclicAliasException(current, aliasedId);
+                }
+
+                // A chain the container already held returns here. `bindAlias()` ends its
+                // walk for that state, so this entry point answers it the same way.
+                if (seen.has(aliasedId)) {
+                    break;
+                }
+
+                seen.add(aliasedId);
+                current = aliasedId;
+                aliasedId = next(current);
+            }
+        }
+    }
+
     bindSingleton<T extends object>(id: string, factory: (container: ContainerContract, args?: unknown[]) => T): this {
         this.singletons[id] = id;
         this.bind(id, factory);
@@ -76,11 +156,12 @@ export class Container implements ContainerContract {
     }
 
     isAlias(id: string): boolean {
-        return id in this.aliases;
+        // The map is a plain object, so only its own keys are aliases the container holds
+        return Object.hasOwn(this.aliases, id);
     }
 
     isService(id: string): boolean {
-        return id in this.services;
+        return Object.hasOwn(this.services, id);
     }
 
     isSingleton(id: string): boolean {
@@ -88,11 +169,11 @@ export class Container implements ContainerContract {
     }
 
     isSingletonBinding(id: string): boolean {
-        return id in this.singletons;
+        return Object.hasOwn(this.singletons, id);
     }
 
     isSingletonInstance(id: string): boolean {
-        return id in this.instances;
+        return Object.hasOwn(this.instances, id);
     }
 
     get<T extends object>(id: string, args: unknown[] = []): T {
@@ -150,11 +231,11 @@ export class Container implements ContainerContract {
     }
 
     isDeferred(id: string): boolean {
-        return id in this.deferredCallback;
+        return Object.hasOwn(this.deferredCallback, id);
     }
 
     isPublished(id: string): boolean {
-        return id in this.published;
+        return Object.hasOwn(this.published, id);
     }
 
     publish(id: string): void {
@@ -169,7 +250,7 @@ export class Container implements ContainerContract {
     }
 
     protected getAliasedWithoutChecks<T extends object>(id: string, args: unknown[] = []): T | undefined {
-        const aliased = this.getAlias(id);
+        const aliased = this.getAliasedId(id);
 
         if (aliased === undefined) {
             return undefined;
@@ -191,10 +272,20 @@ export class Container implements ContainerContract {
 
         const singleton = this.getServiceWithoutChecks<T>(id);
 
-        if (singleton !== undefined) {
-            this.instances[id] = singleton;
+        if (singleton === undefined) {
+            return undefined;
+        }
+
+        // The map decides which instance every reader gets, because a factory can cache
+        // an instance for this id while it runs, before this write.
+        const registered = this.getSingletonInstance<T>(id);
+
+        if (registered !== undefined) {
+            return registered;
         }
 
+        this.instances[id] = singleton;
+
         return singleton;
     }
 
@@ -208,20 +299,22 @@ export class Container implements ContainerContract {
         return factory(this, args) as T;
     }
 
-    protected getAlias(id: string): string | undefined {
-        return this.aliases[id];
+    getAliasedId(alias: string): string | undefined {
+        // The map is a plain object, so only its own keys are aliases the container holds
+        return Object.hasOwn(this.aliases, alias) ? this.aliases[alias] : undefined;
     }
 
     protected getSingletonInstance<T extends object>(id: string): T | undefined {
-        return this.instances[id] as T | undefined;
+        // The map is a plain object, so only its own keys are instances the container holds
+        return Object.hasOwn(this.instances, id) ? (this.instances[id] as T) : undefined;
     }
 
     protected getServiceCallable(id: string): ((container: ContainerContract, args?: unknown[]) => object) | undefined {
-        return this.services[id];
+        return Object.hasOwn(this.services, id) ? this.services[id] : undefined;
     }
 
     protected getDeferredCallback(id: string): ((container: ContainerContract) => void) | undefined {
-        return this.deferredCallback[id];
+        return Object.hasOwn(this.deferredCallback, id) ? this.deferredCallback[id] : undefined;
     }
 
     protected publishUnpublishedProvided(id: string): void {

package/src/Valkyrja/Container/Manager/Contract/ContainerContract.ts

@@ -23,6 +23,7 @@ export interface ContainerContract extends ProvidersAwareContract {
     isSingletonBinding(id: string): boolean;
     isSingletonInstance(id: string): boolean;
     get<T extends object>(id: string, args?: unknown[]): T;
+    getAliasedId(alias: string): string | undefined;
     getAliased<T extends object>(id: string, args?: unknown[]): T;
     getService<T extends object>(id: string, args?: unknown[]): T;
     getSingleton<T extends object>(id: string): T;

package/src/Valkyrja/Container/README.md

@@ -56,14 +56,15 @@ export interface ContainerContract extends ProvidersAwareContract {
     isSingletonBinding(id: string): boolean;
     isSingletonInstance(id: string): boolean;
     get<T extends object>(id: string, args?: unknown[]): T;
+    getAliasedId(alias: string): string | undefined;
     getAliased<T extends object>(id: string, args?: unknown[]): T;
     getService<T extends object>(id: string, args?: unknown[]): T;
     getSingleton<T extends object>(id: string): T;
 }
 ```
 
-Note that this port declares no `getAliasedId()`. The PHP reference declares
-one.
+`getAliasedId()` returns the id an alias points to, one hop at a time, and
+`undefined` when the id is not an alias.
 
 ## Service types
 
@@ -139,6 +140,15 @@ container.bindSingleton(CliServerServiceId.InputHandlerContract, (container) =>
 The second call returns the stored object. The container writes that object
 into `instances` on the first resolution.
 
+Warning: a build keeps the first instance the map holds for an id. A factory
+that caches an instance for the id it is building decides what every reader
+gets. The object that factory returns is discarded then.
+
+Warning: that rule holds inside one container. A `ChildContainer` hands a
+parent-held factory to the parent, so the registration lands in the parent and
+the child caches the object the factory returned. The two containers then hold
+different objects for that id.
+
 ### bindAlias()
 
 `bindAlias()` maps one id onto another. The first argument is the alias, and the
@@ -148,6 +158,33 @@ second argument is the id the container resolves instead:
 container.bindAlias('App.Logger', LoggerContractId);
 ```
 
+An alias that points at a chain that returns to it has no end. Four checks
+reject one with `ContainerCyclicAliasException`:
+
+- `bindAlias()` checks the pair it is asked to store.
+- The constructor and `setFromData()` check the aliases they receive, and the
+  chain those aliases reach.
+- A child walking the parent's aliases checks the hops of one walk.
+- A child resolving a parent-declared alias checks the target it returns to. The
+  check sits on the container that resolves, so a parent which is itself a child
+  throws from its own. An instance cached for the target while the lookup ran
+  has broken the chain, so the lookup answers with that instance.
+
+The first two checks run at registration. A container installs no map before its
+walk ends, so a caller that catches the exception keeps the container it had. A
+container that writes an alias after a child reads through it is outside
+registration. The last two checks see one walk and one return, so a chain that
+reaches neither is unchecked. It has one of four outcomes:
+
+- It resolves through the first hop the parent would answer.
+- It ends with a missing reference, when no hop answers.
+- It does not end, when a factory or a publish callback runs in a container that
+  carries no such check. A plain `Container` carries none. The child hands the
+  lookup to the parent for a target the child does not resolve itself. The
+  parent also runs its own factory for a target the child declares none for.
+- It does not end, when an alias the child declares closes a chain through a
+  factory or a publish callback the child runs. No check sits on that path.
+
 ### Every service needs a binding
 
 The container does not read a constructor and does not build an unregistered
@@ -330,7 +367,10 @@ transfer.
 object into the container, so an existing key keeps the incoming value:
 
 ```ts
-this.aliases = { ...this.aliases, ...data.aliases };
+container.bindAlias('App.Logger', FileLoggerId);
+container.setFromData(new ContainerData({ aliases: { 'App.Logger': SlackLoggerId } }));
+
+container.getAliasedId('App.Logger'); // SlackLoggerId
 ```
 
 The `Container` constructor also takes a `ContainerData`, and it replaces the
@@ -339,7 +379,9 @@ four maps instead of merging.
 ## Child containers
 
 A child container is a per-request container. `WorkerHttp` builds one for each
-request, so request state never reaches the long-lived parent:
+request, so request state never reaches the long-lived parent. The parent still
+publishes a deferred id, and caches a singleton, when it answers a lookup a
+child handed to it:
 
 ```ts
 static getChildContainer(app: ApplicationContract, data: ContainerData): ContainerContract {
@@ -382,18 +424,24 @@ protected override getServiceWithoutChecks<T extends object>(id: string, args: u
 }
 ```
 
-`isAlias()`, `isService()`, `isSingletonInstance()`, `isDeferred()`, and
-`isPublished()` each report the child state or the parent state.
+`isAlias()`, `isService()`, `isSingletonInstance()`, and `isPublished()` each
+report the child state or the parent state. `isSingletonBinding()` is not
+overridden: the child answers for its own markers, which start from the
+snapshot.
 
-Warning: `isSingletonBinding()` is not overridden. The child reports its own
-copied bindings, and it does not report a binding that the parent added after
-`getData()` ran.
+Warning: `isDeferred()` is not overridden. The child reports the callbacks its
+own map holds, and it does not report a provider the parent registered after
+`getData()` ran. `has()` reads `isDeferred()`, `isSingleton()`, `isService()`,
+and `isAlias()`. It follows the narrowing for a deferred id, and it reports the
+parent for a service, an alias, or a cached instance.
 
 ### Where a singleton instance lives
 
 A singleton binding that the child copied resolves once for each child. The
-child asks the parent to run the factory, and the child stores the result in its
-own `instances` map. The parent's map does not change.
+child's own factory runs when the child declares one for that id. Otherwise the
+child asks the parent to run the parent's factory, and the child stores the
+result in its own `instances` map. The parent's map keeps what that factory
+resolved for itself, because that factory receives the parent.
 
 An instance the parent built before the request loop is shared. The child
 returns the parent's object:
@@ -417,11 +465,87 @@ static bootstrapParentServices(app: ApplicationContract): void {
 }
 ```
 
-Note that this port declares no guard against a parent that writes while it
-answers a child. The PHP reference throws
-`ContainerUnpublishedParentTargetException` and
-`ContainerUnresolvedParentAliasException`. This port has neither exception, and
-the child delegates to the parent in every case above.
+### Where an alias resolves
+
+An alias resolves in the container that declares it, so where you declare an
+alias selects the resolution scope. A child lookup of an alias that only the
+parent declares goes to the parent, and the parent answers it as it would for
+any caller:
+
+```ts
+// Once, at boot. The child never declares this alias.
+parent.bind(SlackNotifierId, (c) => SlackNotifier.make(c));
+parent.bindAlias(NotifierContractId, SlackNotifierId);
+
+// For each request, the child binds its own.
+child.bind(SlackNotifierId, (c) => SlackNotifier.make(c));
+
+child.get(SlackNotifierId); // built by the child's binding
+child.get(NotifierContractId); // built by the parent's binding
+```
+
+There is one exception. The child resolves a target the parent would answer for
+the first time, when the child holds that registration too. The request must not
+hold one copy for the alias and another for the target. Three cases:
+
+- **A singleton binding the parent never built** — the child resolves it when
+  its own `singletons` map carries the marker.
+- **A publisher the parent has not run** — the child resolves it when the child
+  reports that callback.
+- **Every other target** — the parent answers the whole lookup, whatever the
+  child carries.
+
+A worker takes one snapshot after boot, so a request carries every registration.
+The child reuses anything that the parent already built or published.
+
+The child reports its own maps, which start from the snapshot, and the parent's
+through the predicates it overrides.
+
+Warning: that exception also decides which binding the alias reaches. Give the
+parent a singleton binding it never built. Give the child the marker for that id
+and a factory of its own. The alias then reaches the factory of the child. A
+child that holds the marker and no factory reaches the parent's factory
+instead.
+
+Warning: outside that exception, the parent answers the alias, so a factory that
+the parent holds receives the parent. A `bind()` service is outside it, whether
+the parent built one or not.
+
+Warning: on that path the parent reads none of the child's maps. An instance the
+child holds for the target does not answer the alias. The parent answers from
+its own maps in one of four ways:
+
+- It returns the copy it holds.
+- It runs its own binding.
+- It publishes a provider it holds, and answers with what that publisher
+  registered.
+- It throws `ContainerInvalidReferenceException`, when it holds no registration
+  for the target.
+
+To reach the child's copy through an alias, declare the alias on the child:
+
+```ts
+// Once, at boot.
+parent.setSingleton(ClockContractId, bootClock);
+parent.bindAlias(TimeSourceContractId, ClockContractId);
+
+// For each request.
+child.setSingleton(ClockContractId, requestClock);
+
+child.get(ClockContractId); // requestClock
+child.get(TimeSourceContractId); // bootClock, answered by the parent
+
+child.bindAlias(TimeSourceContractId, ClockContractId);
+
+child.get(TimeSourceContractId); // requestClock
+```
+
+On the exception path, the child's own factory runs when the child declares one
+for that id. Otherwise the child asks the parent to run the parent's factory,
+as [Where a singleton instance lives](#where-a-singleton-instance-lives)
+states. A singleton caches in the child. A deferred target publishes in the
+child, so its callback receives the child, and what caches is whatever that
+publisher registers.
 
 ## Exceptions
 
@@ -429,6 +553,7 @@ the child delegates to the parent in every case above.
 | :----------------------------------------- | :---------------------------------- | :--------------------------------------- |
 | `ContainerInvalidReferenceException`       | `ContainerInvalidArgumentException` | No map holds the id                      |
 | `ContainerInvalidPublishCallbackException` | `ContainerRuntimeException`         | A `publishers()` value is not a function |
+| `ContainerCyclicAliasException`            | `ContainerInvalidArgumentException` | An alias reaches a chain with no end     |
 
 `ContainerRuntimeException` and `ContainerInvalidArgumentException` are the
 abstract bases. Both implement `ContainerThrowable`. See

package/src/Valkyrja/Container/Throwable/Exception/ContainerCyclicAliasException.ts

@@ -0,0 +1,21 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+import { ContainerInvalidArgumentException } from './Abstract/ContainerInvalidArgumentException.ts';
+
+export class ContainerCyclicAliasException extends ContainerInvalidArgumentException {
+    constructor(alias: string, id: string, options?: ErrorOptions) {
+        super(
+            alias === id
+                ? `Alias \`${alias}\` cannot point at itself.`
+                : `Alias \`${alias}\` cannot reach \`${id}\`, because the chain from \`${id}\` returns to \`${alias}\`.`,
+            options,
+        );
+        this.name = 'ContainerCyclicAliasException';
+    }
+}

package/src/Valkyrja/Http/Message/Uri/Factory/UriFactory.ts

@@ -51,7 +51,7 @@ export abstract class UriFactory {
 
     static filterScheme(scheme: string): Scheme {
         scheme = scheme.toLowerCase().replace(/:(\/\/)?$/, '');
-        return (Object.values(Scheme) as string[]).includes(scheme) ? (scheme as Scheme) : Scheme.EMPTY;
+        return Object.values(Scheme).find((value: string) => value === scheme) ?? Scheme.EMPTY;
     }
 
     static validatePort(port: number): void {

package/src/Valkyrja/Http/README.md

@@ -222,6 +222,11 @@ const match = namedGroups[name] ?? parameter.getDefault();
 Warning: `processArguments()` throws `HttpRoutingInvalidRoutePathException` when
 a dynamic route declares no parameter.
 
+Warning: an unbound cast type raises `ContainerInvalidReferenceException` out of
+`match()`, and out of `matchDynamic()`. The matcher resolves `cast.type` through
+the container for a parameter that carries a cast. Bind that key with `bind`.
+See [Type](../Type/README.md) for casting.
+
 ### The router
 
 `Router.dispatch()` matches, then dispatches:

package/src/Valkyrja/Http/Routing/Dispatcher/Router.ts

@@ -16,6 +16,7 @@ import { RouteNotMatchedHandler } from '../../Middleware/Handler/RouteNotMatched
 import { SendingResponseHandler } from '../../Middleware/Handler/SendingResponseHandler.ts';
 import { ResponseSentHandler } from '../../Middleware/Handler/ResponseSentHandler.ts';
 import { ThrowableCaughtHandler } from '../../Middleware/Handler/ThrowableCaughtHandler.ts';
+import { RouteCollection } from '../Collection/RouteCollection.ts';
 import { Matcher } from '../Matcher/Matcher.ts';
 
 import type { ContainerContract } from '../../../Container/Manager/Contract/ContainerContract.ts';
@@ -35,7 +36,7 @@ import type { RouterContract } from './Contract/RouterContract.ts';
 export class Router implements RouterContract {
     constructor(
         protected container: ContainerContract = new Container(),
-        protected matcher: MatcherContract = new Matcher(),
+        protected matcher: MatcherContract = new Matcher(new RouteCollection(), container),
         protected responseFactory: ResponseFactoryContract = new ResponseFactory(),
         protected throwableCaughtHandler: ThrowableCaughtHandlerContract = new ThrowableCaughtHandler(),
         protected routeMatchedHandler: RouteMatchedHandlerContract = new RouteMatchedHandler(),

package/src/Valkyrja/Http/Routing/Matcher/Matcher.ts

@@ -6,9 +6,10 @@
  * Released under the MIT License. See LICENSE.md for details.
  */
 
-import { RouteCollection } from '../Collection/RouteCollection.ts';
 import { HttpRoutingInvalidRoutePathException } from '../Throwable/Exception/HttpRoutingInvalidRoutePathException.ts';
 
+import type { ContainerContract } from '../../../Container/Manager/Contract/ContainerContract.ts';
+import type { TypeContract } from '../../../Type/Contract/TypeContract.ts';
 import type { RequestMethod } from '../../Message/Enum/RequestMethod.ts';
 import type { DynamicRouteContract } from '../Data/Contract/DynamicRouteContract.ts';
 import type { ParameterContract } from '../Data/Contract/ParameterContract.ts';
@@ -17,7 +18,10 @@ import type { RouteCollectionContract } from '../Collection/Contract/RouteCollec
 import type { MatcherContract } from './Contract/MatcherContract.ts';
 
 export class Matcher implements MatcherContract {
-    constructor(protected collection: RouteCollectionContract = new RouteCollection()) {}
+    constructor(
+        protected collection: RouteCollectionContract,
+        protected container: ContainerContract,
+    ) {}
 
     match(path: string, requestMethod: RequestMethod): RouteContract | null {
         const normalizedPath = '/' + path.replace(/^\/+|\/+$/g, '');
@@ -95,14 +99,8 @@ export class Matcher implements MatcherContract {
 
     protected castMatchValue(parameter: ParameterContract, match: string): unknown {
         const cast = parameter.getCast();
-        const type = (cast.type as unknown as { fromValue: (v: unknown) => { asValue: () => unknown } }).fromValue(
-            match,
-        );
+        const type = this.container.getService<TypeContract>(cast.type, [match]);
 
-        if (cast.convert) {
-            return type.asValue();
-        }
-
-        return type;
+        return cast.convert ? type.asValue() : type;
     }
 }

package/src/Valkyrja/Http/Routing/Provider/HttpRoutingServiceProvider.ts

@@ -102,7 +102,10 @@ export class HttpRoutingServiceProvider implements ServiceProviderContract {
     static publishMatcher(this: void, container: ContainerContract): void {
         container.setSingleton<MatcherContract>(
             HttpRoutingServiceId.MatcherContract,
-            new Matcher(container.getSingleton<RouteCollectionContract>(HttpRoutingServiceId.RouteCollectionContract)),
+            new Matcher(
+                container.getSingleton<RouteCollectionContract>(HttpRoutingServiceId.RouteCollectionContract),
+                container,
+            ),
         );
     }
 

package/src/Valkyrja/Type/Contract/TypeContract.ts

@@ -0,0 +1,13 @@
+/*
+ * This file is part of the Valkyrja Framework package.
+ *
+ * Copyright (c) 2016-present Melech Mizrachi
+ *
+ * Released under the MIT License. See LICENSE.md for details.
+ */
+
+export interface TypeContract {
+    asValue(): unknown;
+    asFlatValue(): string | number | boolean | null;
+    modify(closure: (value: unknown) => unknown): this;
+}

package/src/Valkyrja/Type/README.md

@@ -2,22 +2,51 @@
 
 ## Introduction
 
-The Type component holds two support classes. `Cast` records how to convert a
-route parameter value. `ObjectFactory` copies an object.
+The Type component holds one contract and two support classes. `TypeContract`
+declares a value the framework converts. `Cast` records how to convert a route
+parameter value. `ObjectFactory` copies an object.
 
-**This port ships no typed value objects.** The component has no `TypeContract`,
-no primitive wrapper, no identifier type, no collection, no JSON wrapper, and no
-UUID, ULID, or VLID support. The component holds two files:
+**This component ships no typed value object.** It declares `TypeContract`, and
+it holds no implementation of that contract. There is no primitive wrapper, no
+identifier type, no collection, no JSON wrapper, and no UUID, ULID, or VLID
+support. An application supplies its own type. The component holds three files:
 
-| File                              | Class           |
-| :-------------------------------- | :-------------- |
-| `Data/Cast.ts`                    | `Cast`          |
-| `Object/Factory/ObjectFactory.ts` | `ObjectFactory` |
+| File                              | Class or contract |
+| :-------------------------------- | :---------------- |
+| `Contract/TypeContract.ts`        | `TypeContract`    |
+| `Data/Cast.ts`                    | `Cast`            |
+| `Object/Factory/ObjectFactory.ts` | `ObjectFactory`   |
+
+## TypeContract
+
+`TypeContract` is the contract for a value that the framework converts. A type
+holds one value. Two methods return that value, and `modify()` returns a new
+type that holds the result of a closure:
+
+```ts
+export interface TypeContract {
+    asValue(): unknown;
+    asFlatValue(): string | number | boolean | null;
+    modify(closure: (value: unknown) => unknown): this;
+}
+```
+
+PHP declares a static `fromValue()` on this contract. A TypeScript interface
+declares instance members only, so a contract cannot carry a static method and
+this port leaves it out. The CLI asks the container for the type instead. See
+[STATIC_METHODS.md](https://github.com/valkyrjaio/architecture/blob/26.x/STATIC_METHODS.md).
+
+The contract mirrors PHP's `TypeContract`, which every PHP value object
+implements. PHP's contract also extends `JsonSerializable`, and this port leaves
+that out, because TypeScript serializes an object through `JSON.stringify()`.
+The framework calls `asValue()` only. `asFlatValue()` and `modify()`
+are there for the application, and for the ports that hold value objects
+already.
 
 ## Cast
 
-`Cast` is a data object. It records the type to convert a value to, and how to
-return the result:
+`Cast` is a data object. It records the container binding key of the type to
+convert a value to, and how to return the result:
 
 ```ts
 export class Cast {
@@ -31,7 +60,7 @@ export class Cast {
 
 | Property  | Default | Meaning                                         |
 | :-------- | :------ | :---------------------------------------------- |
-| `type`    | —       | The type to convert the value to                |
+| `type`    | —       | The container binding key of the type           |
 | `convert` | `true`  | Return the converted value, and not the wrapper |
 | `isArray` | `false` | The value holds more than one item              |
 
@@ -41,42 +70,69 @@ A route parameter carries the cast. Both routing components declare
 `withCast()`, `getCast()`, and `hasCast()` on a parameter:
 
 ```ts
+import { ArgumentParameter } from '@valkyrjaio/valkyrja/Cli/Routing/Data/ArgumentParameter.ts';
 import { Cast } from '@valkyrjaio/valkyrja/Type/Data/Cast.ts';
 
-const parameter = new ArgumentParameter('name', 'description').withCast(new Cast('string'));
+const parameter = new ArgumentParameter('name', 'description').withCast(new Cast('App.Type.Slug'));
 ```
 
 `getCast()` throws when the parameter carries no cast. The CLI parameter throws
 `CliRoutingNoCastException`.
 
-### Where the framework applies a cast
+### Where a cast applies
+
+Two components convert a value, and each one reads `cast.type` as a container
+binding key. The framework calls the HTTP matcher. The application calls the CLI
+caster.
+
+`Matcher.castMatchValue()` asks the container for the type that `cast.type`
+names, and it passes the matched text as the first entry of the factory's
+`args`. It returns `asValue()` when `cast.convert` is `true`, and the type itself
+when `cast.convert` is `false`. See [Http](../Http/README.md) for dynamic routes
+and their parameters.
+
+`Caster.getCastValues()` asks the container for that type once for each value.
+It passes the raw value as the first entry of the factory's `args`. It returns
+`asValue()` when `cast.convert` is `true`, and the type itself when
+`cast.convert` is `false`. It returns each raw value for a parameter that holds
+no cast.
 
-The HTTP `Matcher` is the one place that converts a matched value. It reads
-`cast.type` as a class, and it calls the static `fromValue()` on that class:
+A route parameter holds the cast, and it converts nothing. The matcher and the
+caster each hold the container, which is why no parameter needs one.
+
+Warning: register a cast type with `bind`. Each reader calls `getService()`,
+which reads only a service binding. An alias, and an instance that
+`setSingleton` holds, raise `ContainerInvalidReferenceException`.
+
+`bindSingleton` also registers a callable, so a cast type that `bindSingleton`
+registers still resolves. `getService()` skips the singleton cache, so the
+container builds one instance for each value. That is not the lifetime that
+`bindSingleton` states, which is why a cast type takes `bind`.
+
+Warning: the factory must return a `TypeContract`. Each reader calls `asValue()`
+on the object that the container builds, and an object without that method
+raises a `TypeError`.
+
+The application binds the type to the key that the cast names, and it asks the
+caster for the values:
 
 ```ts
-protected castMatchValue(parameter: ParameterContract, match: string): unknown {
-    const cast = parameter.getCast();
-    const type = (cast.type as unknown as { fromValue: (v: unknown) => { asValue: () => unknown } }).fromValue(
-        match,
-    );
-
-    if (cast.convert) {
-        return type.asValue();
-    }
+import { Argument } from '@valkyrjaio/valkyrja/Cli/Interaction/Argument/Argument.ts';
+import { ArgumentParameter } from '@valkyrjaio/valkyrja/Cli/Routing/Data/ArgumentParameter.ts';
+import { CliRoutingServiceId } from '@valkyrjaio/valkyrja/Cli/Routing/Constant/CliRoutingServiceId.ts';
+import { Cast } from '@valkyrjaio/valkyrja/Type/Data/Cast.ts';
 
-    return type;
-}
-```
+import type { CasterContract } from '@valkyrjaio/valkyrja/Cli/Routing/Caster/Contract/CasterContract.ts';
 
-Warning: the port ships no class with a `fromValue()` method. An application
-that sets a cast on an HTTP route parameter supplies that class itself. The
-class declares a static `fromValue()` that returns an object with `asValue()`.
-See [Http](../Http/README.md) for dynamic routes and their parameters.
+container.bind('App.Type.Slug', Slug.make);
+
+const parameter = new ArgumentParameter('target', 'The target', new Cast('App.Type.Slug')).withArguments(
+    new Argument('a-slug'),
+);
+const values = container.getSingleton<CasterContract>(CliRoutingServiceId.CasterContract).getCastValues(parameter);
+```
 
-Note that the CLI does not apply a cast. `getCastValues()` returns each raw
-parameter value, and the stored `Cast` does not change the result. See
-[Cli](../Cli/README.md) for CLI arguments and options.
+See [Cli](../Cli/README.md) for CLI arguments and options.
 
 Note that no code reads `isArray`.