@loozo/angular-router 0.0.0-stage → 0.0.2

package/types/loozo-angular-router-_core.d.ts

@@ -0,0 +1,484 @@
+import { RedirectCommand, RunGuardsAndResolvers, ActivatedRouteSnapshot, RouterStateSnapshot, MaybeAsync, GuardResult, Route as Route$1, UrlSegment, PartialMatchRouteSnapshot } from '@angular/router';
+import { Observable } from 'rxjs';
+
+/**
+ * Converts one decoded path or search value to and from an application value.
+ *
+ * @remarks
+ * Parsing may be asynchronous; stringification must be synchronous. Neither
+ * method performs URL encoding. Codecs have no Angular injection-context
+ * guarantee, and their returned objects are not recursively frozen.
+ * For a terminal `$name[]` path, this codec applies to each element separately.
+ *
+ * @typeParam Value - The logical value, not a promise of that value.
+ *
+ * @example
+ * ```ts
+ * const dateParam: ParamCodec<Date> = {
+ *   parse: (raw) => new Date(raw),
+ *   stringify: (value) => value.toISOString(),
+ * };
+ * ```
+ */
+interface ParamCodec<Value> {
+    /**
+     * Parses one already percent-decoded value; do not decode it again.
+     *
+     * @param raw - A single logical string from Angular's URL inputs.
+     * @returns The logical value or a promise for it.
+     * @throws An application error for invalid input; generated input parsing
+     * reports throws and rejections as invalid path/search values with a cause.
+     */
+    parse(raw: string): Value | Promise<Value>;
+    /**
+     * Serializes one logical value without percent-encoding it.
+     *
+     * @param value - The application value to serialize.
+     * @returns An unencoded string. Path output must not be empty, `.` or `..`.
+     * @throws An application error when the value cannot be serialized.
+     */
+    stringify(value: Value): string;
+}
+declare const searchPresence: unique symbol;
+/** A search-only codec whose key may be omitted or supplied as `undefined`. */
+type OptionalCodec<Value> = ParamCodec<Value | undefined> & {
+    readonly [searchPresence]: "optional";
+};
+/** A search-only codec that represents explicit `null` as the text `"null"`. */
+type NullableCodec<Value> = ParamCodec<Value | null> & {
+    readonly [searchPresence]: "nullable";
+};
+type PathCodec = ParamCodec<any> & {
+    readonly [searchPresence]?: never;
+};
+type CodecValue<Codec> = Codec extends ParamCodec<infer Value> ? Value : never;
+type IsOptional<Codec> = Codec extends {
+    readonly [searchPresence]: "optional";
+} ? true : false;
+declare function codecPresence(codec: object): "optional" | "nullable" | undefined;
+/**
+ * Preserves strings verbatim, including empty strings and literal percent text.
+ *
+ * @remarks
+ * Empty, dot and dotdot values are valid codec values but cannot be serialized
+ * into path segments by URL creation. Search values may contain them.
+ */
+declare const stringParam: ParamCodec<string>;
+/**
+ * Parses nonblank text with JavaScript `Number` and requires a finite result.
+ *
+ * @remarks
+ * Whitespace around numbers, exponent notation and hexadecimal text are accepted.
+ * Blank text, NaN and infinities throw. Stringification requires a finite number
+ * and uses its JavaScript string representation (including `-0` becoming `"0"`).
+ */
+declare const numberParam: ParamCodec<number>;
+/**
+ * Parses only lowercase `"true"` and `"false"`, and emits those same strings.
+ * Other representations and nonboolean values throw.
+ */
+declare const booleanParam: ParamCodec<boolean>;
+/**
+ * Creates a case-sensitive string codec from a snapshotted list of members.
+ *
+ * @typeParam Values - The literal list from which the value union is inferred.
+ * @param values - Allowed decoded strings; an empty string is valid when listed.
+ * @returns A codec whose parser and stringifier reject nonmembers.
+ * @throws TypeError if the list or its entries are malformed.
+ *
+ * @example
+ * ```ts
+ * const tab = enumParam(["details", "reviews"]);
+ * tab.parse("reviews"); // "reviews"
+ * ```
+ */
+declare function enumParam<const Values extends readonly string[]>(values: Values): ParamCodec<Values[number]>;
+/**
+ * Makes a search key optional without changing the handling of present values.
+ *
+ * @remarks
+ * Generated parsing omits absent keys; URL creation omits absent or `undefined`
+ * values. The wrapper's parser delegates present strings unchanged, preserving
+ * promises and failures. Its stringifier cannot serialize `undefined` directly.
+ * This wrapper is not a path codec. For optional nullable values, wrap
+ * {@link nullableSearchParam} with this function, not the other way around.
+ *
+ * @typeParam Value - The wrapped codec's logical value.
+ * @param codec - The codec used for present search values.
+ * @returns A search-only codec allowing omission.
+ * @throws TypeError if the codec lacks callable parse/stringify methods.
+ */
+declare function optionalSearchParam<Value>(codec: ParamCodec<Value>): OptionalCodec<Value>;
+/**
+ * Adds explicit null to a search codec, represented by the decoded text `"null"`.
+ *
+ * @remarks
+ * The key remains required unless wrapped with {@link optionalSearchParam}.
+ * Non-null values delegate unchanged, including promise/failure identity. The
+ * text `"null"` is reserved by this wrapper even if the inner codec accepts it.
+ * This wrapper is not a path codec and cannot wrap an optional search codec.
+ *
+ * @typeParam Value - The wrapped codec's non-null logical value.
+ * @param codec - The codec used for values other than null.
+ * @returns A search-only codec accepting and serializing null.
+ * @throws TypeError if the codec is malformed or is an optional search wrapper.
+ *
+ * @example
+ * ```ts
+ * const score = optionalSearchParam(nullableSearchParam(numberParam));
+ * // Omission, null, and a present number remain distinct.
+ * ```
+ */
+declare function nullableSearchParam<Value>(codec: ParamCodec<Value> & {
+    readonly [searchPresence]?: "nullable";
+}): NullableCodec<Value>;
+
+type ValidName<Name extends string> = Name extends "" | "__proto__" | `...${string}` | `${string}?${string}` | `${string}*${string}` | `${string}[]${string}` ? false : true;
+type SegmentValid<Segment extends string> = Segment extends `$${infer Name}` ? ValidName<Name> : Segment extends "" | "." | ".." | "*" | "**" | `:${string}` ? false : true;
+type ValidateSegments<Path extends string, Scalars extends string = never> = Path extends `${infer Head}/${infer Tail}` ? Head extends `$${string}[]` ? false : SegmentValid<Head> extends true ? ValidateSegments<Tail, Scalars | ScalarName<Head>> : false : Path extends `$${infer Name}[]` ? ValidName<Name> extends true ? Name extends Scalars ? false : true : false : SegmentValid<Path>;
+type ValidPath<Path extends string> = string extends Path ? never : Path extends "" ? Path : ValidateSegments<Path> extends true ? Path : never;
+type ScalarName<Segment extends string> = Segment extends `$${infer Name}` ? Name : never;
+type SegmentName<Segment extends string> = Segment extends `$${infer Name}[]` ? Name : ScalarName<Segment>;
+type PathNames<Path extends string> = Path extends `${infer Head}/${infer Tail}` ? SegmentName<Head> | PathNames<Tail> : SegmentName<Path>;
+type CatchallName<Path extends string> = Path extends `${string}/${infer Tail}` ? CatchallName<Tail> : Path extends `$${infer Name}[]` ? Name : never;
+type Segment = {
+    readonly kind: "static";
+    readonly text: string;
+} | {
+    readonly kind: "scalar" | "catchall";
+    readonly name: string;
+};
+
+declare const routeBrand: unique symbol;
+/**
+ * A nominal route declaration created by `defineRoute`, not a native Angular Route.
+ *
+ * @remarks
+ * Prefer inference from `defineRoute` over explicit generic arguments. The
+ * optional `__params`, `__search` and `__data` members are type witnesses only;
+ * they are not populated runtime properties. Parent/codec/effective-path metadata
+ * is private. Spreading a declaration does not produce another valid route.
+ *
+ * @typeParam Path - The local authored path literal, not the effective URL path.
+ * @typeParam Params - Effective inherited and local logical path values.
+ * @typeParam Search - Effective inherited and local logical search values.
+ * @typeParam Resolvers - Local resolver callbacks; data unwraps Promise/Observable
+ * results and excludes Angular RedirectCommand values.
+ * @typeParam Fragments - This declaration's own allowed fragment-name union.
+ * @typeParam Catchall - Whether the declaration is a terminal catchall leaf.
+ */
+interface Route<Path extends string, Params, Search, Resolvers = {}, Fragments extends string = string, Catchall extends boolean = CatchallName<Path> extends never ? false : true> {
+    readonly [routeBrand]: {
+        readonly fragments: Fragments;
+        readonly catchall: Catchall;
+    };
+    /** The exact local authored path supplied to `defineRoute`. */
+    readonly path: Path;
+    /** Type-only witness for effective path values; not populated at runtime. */
+    readonly __params?: Params;
+    /** Type-only witness for effective search values; not populated at runtime. */
+    readonly __search?: Search;
+    /** Type-only witness for unwrapped local resolver data, excluding redirects. */
+    readonly __data?: {
+        readonly [Key in keyof Resolvers]: Resolved<Resolvers[Key]>;
+    };
+    /** The snapshotted local resolver map, retaining original callback identities. */
+    readonly resolve?: Readonly<Resolvers>;
+    /** The original native rerun policy; omission preserves Angular's default. */
+    readonly runGuardsAndResolvers?: RunGuardsAndResolvers;
+}
+type Unwrap<Value> = Value extends Promise<infer Inner> | Observable<infer Inner> ? Unwrap<Inner> : Value;
+type Resolved<Callback> = Callback extends (...args: any[]) => infer Value ? Exclude<Unwrap<Value>, RedirectCommand> : never;
+type AnyRoute = Route<string, any, any, any, any, boolean>;
+/** Extracts a declaration's effective inherited and local path-value types. */
+type ParamsOf<Target> = Target extends Route<string, infer Params, any, any, any, boolean> ? Params : {};
+/** Extracts effective search-value types, retaining optional/nullable modifiers. */
+type SearchOf<Target> = Target extends Route<string, any, infer Search, any, any, boolean> ? Search : {};
+/** Extracts only the selected declaration's own allowed fragment-name union. */
+type FragmentsOf<Target> = Target extends Route<string, any, any, any, infer Fragments, boolean> ? Fragments : never;
+type CodecMap = Record<string, ParamCodec<any>>;
+type LocalParams<Path extends string, Codecs> = {
+    readonly [Key in keyof Codecs]: Key extends CatchallName<Path> ? readonly CodecValue<Codecs[Key]>[] : CodecValue<Codecs[Key]>;
+};
+type SearchValues<Codecs> = {
+    readonly [Key in keyof Codecs as IsOptional<Codecs[Key]> extends true ? never : Key]: CodecValue<Codecs[Key]>;
+} & {
+    readonly [Key in keyof Codecs as IsOptional<Codecs[Key]> extends true ? Key : never]?: CodecValue<Codecs[Key]>;
+};
+type EffectiveParams<Path extends string, Codecs, Parent> = ParamsOf<Parent> & LocalParams<Path, Codecs>;
+type EffectiveSearch<Codecs, Parent> = SearchOf<Parent> & SearchValues<Codecs>;
+/**
+ * Shared parsed inputs supplied to typed guards and resolvers.
+ * The container and maps are shallow-frozen; nested codec values remain opaque.
+ */
+type Inputs<Params, Search> = {
+    /** Logical positional path values, not Angular's matrix-merged params. */
+    readonly params: Readonly<Params>;
+    /** Logical declared search values; absent optional keys are omitted. */
+    readonly search: Readonly<Search>;
+};
+/**
+ * A local resolver invoked after successful effective input parsing.
+ * Callback entry has Angular's injection context; later awaits do not inherit it.
+ * Angular owns first-emission, empty, redirect, error and teardown behavior.
+ *
+ * @param inputs - Effective inherited and local parsed values.
+ * @param snapshot - The declaring route's native snapshot.
+ * @param state - The native router state being resolved.
+ * @returns A scalar, Promise, Observable or RedirectCommand result.
+ */
+type Resolver<Params, Search> = (inputs: Inputs<Params, Search>, snapshot: ActivatedRouteSnapshot, state: RouterStateSnapshot) => unknown;
+/**
+ * An activation callback entered in Angular's injection context after parsing.
+ * Parse failures prevent entry and propagate as navigation errors, not false.
+ *
+ * @param inputs - The declaring route's effective parsed params/search.
+ * @param snapshot - The native route snapshot, or the child snapshot for
+ * canActivateChild (whose inputs still belong to the declaring parent).
+ * @param state - The native target router state.
+ * @returns A native guard result, synchronously or via Promise/Observable.
+ */
+type ActivationGuard<Params, Search> = (inputs: Inputs<Params, Search>, snapshot: ActivatedRouteSnapshot, state: RouterStateSnapshot) => MaybeAsync<GuardResult>;
+/**
+ * A candidate matching callback entered in Angular's injection context after parsing.
+ * Unlike activation callbacks, it has no ancestor positional path values.
+ *
+ * @param inputs - Local positional params plus effective inherited/local search.
+ * @param routeConfig - Angular's native candidate configuration.
+ * @param segments - Angular's candidate URL segments.
+ * @param partialSnapshot - Angular's native partial matching snapshot.
+ * @returns A native guard result; false permits Angular's next candidate.
+ */
+type MatchingGuard<Params, Search> = (inputs: Inputs<Params, Search>, routeConfig: Route$1, segments: UrlSegment[], partialSnapshot: PartialMatchRouteSnapshot) => MaybeAsync<GuardResult>;
+type RequiredKeys<Value> = {
+    [Key in keyof Value]-?: Pick<Value, Key> extends Required<Pick<Value, Key>> ? Key : never;
+}[keyof Value];
+type SearchInput<Schema, Keys extends keyof Schema> = keyof Schema extends never ? Record<string, never> : Pick<Schema, RequiredKeys<Schema> | Keys>;
+/**
+ * Explicit values for URL creation and generated link/navigation calls.
+ * Effective path and required search keys must be present; optional search may
+ * be omitted. Paramless/searchless routes forbid those fields. Fragment names
+ * come only from the destination's own declaration.
+ *
+ * @typeParam Target - The selected route declaration.
+ * @typeParam SearchKeys - Supplied search keys inferred by each call to preserve
+ * optional-key typing, including keys that coincide with Object members.
+ */
+type UrlValues<Target extends AnyRoute, SearchKeys extends keyof SearchOf<Target> = keyof SearchOf<Target>> = (keyof ParamsOf<Target> extends never ? {
+    /** Forbidden when the destination has no effective path params. */
+    params?: never;
+} : {
+    /** All effective path values; catchalls are readonly element-value arrays. */
+    params: ParamsOf<Target>;
+}) & (keyof SearchOf<Target> extends never ? {
+    /** Forbidden when the destination has no search declarations. */
+    search?: never;
+} : RequiredKeys<SearchOf<Target>> extends never ? {
+    /** Optional-only search; absent or undefined optional values are omitted. */
+    search?: SearchInput<SearchOf<Target>, SearchKeys>;
+} : {
+    /** All required search values plus any supplied optional values. */
+    search: SearchInput<SearchOf<Target>, SearchKeys>;
+}) & (FragmentsOf<Target> extends never ? {
+    /** Forbidden when this declaration has no fragment names. */
+    fragment?: never;
+} : {
+    /** An optional logical name declared by this exact destination, without `#`. */
+    fragment?: FragmentsOf<Target>;
+});
+type CompatibleKeys<Source, Value> = {
+    [Key in keyof Source]: Source[Key] extends Value ? Key : never;
+}[keyof Source];
+type Mapping<Source, Destination> = {
+    [Key in keyof Destination]: CompatibleKeys<Source, Destination[Key]>;
+};
+type Forwardable<Source, Destination> = {
+    [Key in keyof Destination]: Key extends keyof Source ? Source[Key] extends Destination[Key] ? never : Key : Key;
+}[keyof Destination] extends never ? true : false;
+type Preservable<Source, Destination> = {
+    [Key in RequiredKeys<Destination>]: Key extends RequiredKeys<Source> ? Source[Key & keyof Source] extends Destination[Key] ? never : Key : Key;
+}[RequiredKeys<Destination>] extends never ? true : false;
+/**
+ * A typed redirect to a genuine authored declaration, not a concrete URL.
+ *
+ * @remarks
+ * Params map destination keys to compatible effective source path keys. Omission
+ * forwards by name only when all target keys are compatible. Search and fragment
+ * policies are mandatory. Search preserve validates destination-declared values
+ * but retains original query text and unknown keys; drop requires no required
+ * target search keys; replace uses explicit target-typed values (`{}` is allowed
+ * for searchless targets). Fragment preserve retains the incoming raw name,
+ * whereas replace requires a target-declared name. Angular executes the redirect.
+ */
+type Redirect<SourceParams, SourceSearch, Target extends AnyRoute, SearchKeys extends keyof SearchOf<Target>> = {
+    /** The already constructed target; generation requires a direct default import. */
+    to: Target;
+    /** Explicit query policy: preserve incoming text, drop it, or replace with values. */
+    search: {
+        /** Discard incoming queries and serialize explicit target-typed values. */
+        mode: "replace";
+        /** Required target search keys plus selected optional keys; unknown keys fail. */
+        values: SearchInput<SearchOf<NoInfer<Target>>, SearchKeys>;
+    } | (RequiredKeys<SearchOf<Target>> extends never ? {
+        /** Remove all incoming query values; target required keys are forbidden. */
+        mode: "drop";
+    } : never) | (Preservable<SourceSearch, SearchOf<Target>> extends true ? {
+        /** Keep original query text, validating destination-declared cardinality/values. */
+        mode: "preserve";
+    } : never);
+    /** Explicit hash policy; preserved incoming names need not be declared. */
+    fragment: {
+        /** Keep the raw incoming hash, or remove it entirely. */
+        mode: "preserve" | "drop";
+    } | (FragmentsOf<Target> extends never ? never : {
+        /** Replace the incoming hash with an explicitly declared target name. */
+        mode: "replace";
+        /** A logical target fragment name without the `#` delimiter. */
+        value: FragmentsOf<Target>;
+    });
+} & (Forwardable<SourceParams, ParamsOf<Target>> extends true ? {
+    /** Optional destination-key to source-key mapping; otherwise forward by name. */
+    params?: Mapping<SourceParams, ParamsOf<Target>>;
+} : {
+    /** Required mapping of every destination path key to a compatible source key. */
+    params: Mapping<SourceParams, ParamsOf<Target>>;
+});
+/**
+ * Options inferred by `defineRoute`; Angular's structural route fields are excluded.
+ * Local params/search cannot redeclare keys inherited from the parent.
+ */
+type RouteConfig<Path extends string, Parent extends AnyRoute | undefined, Params extends Record<string, PathCodec>, Search extends CodecMap, Resolvers, Fragments extends readonly string[], Target extends AnyRoute | undefined, ReplacementKeys extends keyof SearchOf<Target>> = {
+    /** Genuine authored parent; pathless nodes retain inherited input ownership. */
+    parent?: Parent & (Parent extends Route<string, any, any, any, any, true> ? never : unknown);
+    /** Local search codecs; keys are required unless wrapped with optionalSearchParam. */
+    search?: Search & Record<Extract<keyof Search, keyof SearchOf<Parent>>, never>;
+    /** Local parsed-input resolvers; not snapshot-first native ResolveFn callbacks. */
+    resolve?: Resolvers & Record<PropertyKey, Resolver<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>>> & {
+        __loozoAngularRouterRouteId?: never;
+    };
+    /** Local logical anchor names, never inherited; this does not enable scrolling. */
+    fragments?: Fragments;
+    /** Native rerun policy. Use paramsOrQueryParamsChange for query-dependent data. */
+    runGuardsAndResolvers?: RunGuardsAndResolvers;
+    /** Guards with declaring-parent inputs and Angular's native child snapshot. */
+    canActivateChild?: readonly ActivationGuard<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>>[];
+    /** Native component-first guard functions/tokens, without automatic input parsing. */
+    canDeactivate?: Route$1["canDeactivate"];
+    /** Native route-scoped providers; provider factories are not run at declaration. */
+    providers?: Route$1["providers"];
+    /** Native static title or title resolver, not a parsed-input callback. */
+    title?: Route$1["title"];
+    /** Native static data; cannot set the reserved __loozoAngularRouterRouteId key. */
+    data?: Route$1["data"] & {
+        __loozoAngularRouterRouteId?: never;
+    };
+} & (PathNames<Path> extends never ? {
+    /** Paths without local placeholders cannot declare a params map. */
+    params?: never;
+} : {
+    /** Exactly the local placeholder names; catchall codecs apply per element. */
+    params: Params & Record<PathNames<Path>, PathCodec> & Record<Exclude<keyof Params, PathNames<Path>> | Extract<keyof Params, keyof ParamsOf<Parent>>, never>;
+}) & (Target extends AnyRoute ? {
+    /** Typed native redirect, incompatible with own canActivate/canMatch fields. */
+    redirect: Redirect<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>, Target, ReplacementKeys>;
+    canActivate?: never;
+    canMatch?: never;
+} : {
+    redirect?: never;
+    /** Activation guards with effective inherited and local parsed inputs. */
+    canActivate?: readonly ActivationGuard<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>>[];
+    /** Matching guards with local path params and effective search only. */
+    canMatch?: readonly MatchingGuard<LocalParams<Path, Params>, EffectiveSearch<Search, Parent>>[];
+});
+
+interface RouteMetadata {
+    readonly parent?: AnyRoute;
+    readonly localSegments: readonly Segment[];
+    readonly segments: readonly Segment[];
+    readonly localParams: Readonly<Record<string, ParamCodec<any>>>;
+    readonly localSearch: Readonly<Record<string, ParamCodec<any>>>;
+    readonly params: Readonly<Record<string, ParamCodec<any>>>;
+    readonly search: Readonly<Record<string, ParamCodec<any>>>;
+    readonly fragments: readonly string[];
+    readonly config: Readonly<Record<string, unknown>>;
+}
+declare function routeMetadata(route: unknown): RouteMetadata;
+/**
+ * Declares a nominal typed route without executing codecs or native callbacks.
+ *
+ * @remarks
+ * Paths are decoded authored text, not URLs: use `""` for root/pathless nodes,
+ * `$name` for a scalar segment and terminal `$name[]` for a zero-or-more
+ * catchall. Repeated local scalar names reuse one value. Leading/trailing or
+ * repeated slashes, dot segments and Angular `:name`/wildcard notation are invalid.
+ *
+ * Parents compose effective params/search transitively, including through
+ * pathless nodes. Children cannot redeclare ancestor-owned keys or have a
+ * catchall parent. Fragment names belong only to this declaration.
+ * The route and copied containers are shallow-frozen; application codecs,
+ * callbacks, providers and opaque values retain identity and are not deep-frozen.
+ *
+ * For generation, author a direct default export of this call with a literal
+ * path and inline config. Parent and redirect targets must be direct default
+ * imports of admitted declarations. Angular owns activation and navigation;
+ * declaration alone does not register a route with Angular.
+ *
+ * @param path - The literal local path, relative to the authored parent.
+ * @param config - Local codecs, parent, fragments and supported native behavior.
+ * Structural Angular options such as children, component and matcher are
+ * generator-owned and cannot be overridden.
+ * @returns A frozen route preserving inferred effective input and local data types.
+ * @throws TypeError for invalid paths/configuration, missing or extra local
+ * codecs, inherited key conflicts, or nongenuine parent/redirect routes.
+ *
+ * @example
+ * ```ts
+ * const product = defineRoute("products/$productId", {
+ *   params: { productId: numberParam },
+ *   search: { tab: optionalSearchParam(enumParam(["details", "reviews"])) },
+ *   fragments: ["summary", "reviews"],
+ * });
+ * ```
+ */
+declare function defineRoute<const Path extends string, Parent extends AnyRoute | undefined = undefined, Params extends Record<string, PathCodec> = {}, Search extends CodecMap = {}, Resolvers extends Record<string, (...args: any[]) => unknown> = {}, const Fragments extends readonly string[] = [], Target extends AnyRoute | undefined = undefined, ReplacementKeys extends keyof SearchOf<NoInfer<Target>> = never>(path: Path & ValidPath<Path>, config: RouteConfig<Path, Parent, Params, Search, Resolvers, Fragments, Target, ReplacementKeys>): Route<Path, EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>, Resolvers, Fragments[number], CatchallName<Path> extends never ? false : true>;
+
+/**
+ * Synchronously serializes a route's explicit values into a root-relative URL.
+ *
+ * @remarks
+ * Includes inherited path/search declarations, but only this route's fragment
+ * names. Every effective path value and required search key must be supplied.
+ * Optional-only search may be omitted; searchless/paramless routes forbid those
+ * records. Catchalls require readonly arrays, including a valid empty array.
+ * Values are never taken from a current navigation.
+ *
+ * Stringifies without calling parsers, guards, resolvers or redirects. Static
+ * segments and logical values are component-encoded (also escaping parentheses),
+ * so a dynamic slash becomes `%2F`. Search keys are globally sorted; optional
+ * `undefined` values are omitted. An empty effective path produces `/`.
+ * Redirect declarations serialize their source URL, not their redirect target.
+ *
+ * @param route - A genuine declaration from this physical package instance,
+ * not a generated destination, spread/copy or structural lookalike.
+ * @param values - Explicit destination-typed params, search and optional fragment.
+ * Pass an empty object when the route needs no values.
+ * @returns A root-relative URL string; this does not navigate or return a UrlTree.
+ * @throws TypeError for invalid routes/records, missing or unknown keys,
+ * undeclared fragments, nonarray catchalls, nonstring codec output, or empty/dot
+ * path output. Application stringifier failures propagate unchanged.
+ * @throws URIError for ill-formed Unicode in a serialized value.
+ *
+ * @example
+ * ```ts
+ * const product = defineRoute("products/$productId", {
+ *   params: { productId: numberParam },
+ *   fragments: ["summary"],
+ * });
+ * createUrl(product, { params: { productId: 42 }, fragment: "summary" });
+ * // /products/42#summary
+ * ```
+ */
+declare function createUrl<Target extends AnyRoute, SearchKeys extends keyof SearchOf<NoInfer<Target>> = never>(route: Target, values: UrlValues<NoInfer<Target>, SearchKeys>): string;
+
+export { booleanParam, codecPresence, createUrl, defineRoute, enumParam, nullableSearchParam, numberParam, optionalSearchParam, routeMetadata, stringParam };
+export type { AnyRoute, FragmentsOf, Inputs, ParamCodec, ParamsOf, Route, RouteMetadata, SearchOf, UrlValues };

package/types/loozo-angular-router-_generated.d.ts

@@ -0,0 +1,171 @@
+import { ActivatedRouteSnapshot, Route, RedirectFunction, UrlTree } from '@angular/router';
+import { AnyRoute, ParamsOf, SearchOf, UrlValues } from '@loozo/angular-router/_core';
+import { Resource } from '@angular/core';
+
+interface RecordBinding {
+    readonly definition: () => AnyRoute;
+    readonly owners: readonly string[];
+}
+interface RouteSet {
+    readonly records: Readonly<Record<string, RecordBinding>>;
+    readonly destinations: Readonly<Record<string, () => AnyRoute>>;
+    readonly absolute: Readonly<Record<string, string>>;
+    readonly relative: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+interface Parsed {
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly search: Readonly<Record<string, unknown>>;
+}
+declare function assertIdentity(snapshot: Pick<ActivatedRouteSnapshot, "routeConfig">, id: string): void;
+declare function parseInputs(set: RouteSet, id: string, snapshot: ActivatedRouteSnapshot): Promise<Parsed>;
+
+declare function callbacks(set: RouteSet, id: string): Pick<Route, "canActivate" | "canActivateChild" | "canMatch" | "resolve">;
+declare function redirect(definition: () => AnyRoute): RedirectFunction;
+
+declare const destinationBrand: unique symbol;
+/**
+ * An inert nominal reference exported as `destination` by a route-local facade.
+ *
+ * @remarks
+ * Use the exported object with a handle's link/navigate methods; no injection
+ * context or target activation is needed. It selects its exact declaration,
+ * not a canonical pathless winner. Only references from the caller's generated
+ * set are accepted. Copies, spreads, fakes and authored routes are not references.
+ * Do not construct this type or pass it to the root createUrl function.
+ *
+ * @typeParam Target - The referenced route's input and fragment schema.
+ * @typeParam Set - The generator's nominal route-set identity.
+ * @typeParam Id - The exact generated declaration identity.
+ */
+declare class Destination<Target extends AnyRoute, Set = unknown, Id extends string = string> {
+    #private;
+    readonly [destinationBrand]: {
+        readonly target: Target;
+        readonly set: Set;
+        readonly id: Id;
+    };
+}
+declare function createDestination<Target extends AnyRoute, Set, Id extends string>(getSet: () => RouteSet, id: Id): Destination<Target, Set, Id>;
+type DataOf<Target> = Target extends {
+    readonly __data?: infer Data;
+} ? Readonly<Data> : never;
+type IsUnion<Value, Whole = Value> = Value extends unknown ? [Whole] extends [Value] ? false : true : never;
+/**
+ * The noncallable typed handle returned by a colocated `injectRoute()` facade.
+ *
+ * @remarks
+ * Obtain it in an Angular injection context for the exact generated activated
+ * record. Params/search parse together; data contains only local resolver results,
+ * not static/ancestor data or title. Resources are native readonly Angular
+ * Resources: use hasValue before value access; error-state value reads throw.
+ *
+ * Navigation hides old values. Cancellation/same-URL skip restores the survivor
+ * without reparsing; obsolete work cannot publish. Relevant parsing participates
+ * in Angular stability until publication, error, replacement or destruction.
+ * Codecs are not abortable and there is no package timeout or resolved-data cache.
+ *
+ * Selectors are single known authored literals, not concrete URLs or string
+ * unions. `.` is exact-current; other absolute/relative selections use generated
+ * canonical targets. Relative climbs count URL-template segments, not parent
+ * edges. Catchall origins permit exact-current, absolute and reference targets,
+ * not depth-dependent relative traversal. Every call supplies all target values;
+ * there is no current-value reuse, extras argument or implicit query merge.
+ *
+ * @typeParam Target - The bound declaration's schema.
+ * @typeParam Selected - Statically admitted literal selectors and target schemas.
+ * @typeParam Set - The generator's nominal route-set identity.
+ * @typeParam References - Exact declarations addressable by same-set references.
+ *
+ * @example
+ * ```ts
+ * import { injectRoute } from "./route.generated.js";
+ * import { destination as report } from "../report/route.generated.js";
+ *
+ * const route = injectRoute(); // Inside an Angular injection context.
+ * const link = route.link(report, { params: { reportId: 42 } });
+ * // Bind link to Angular RouterLink, or call route.navigate with the same values.
+ * ```
+ */
+interface Handle<Target extends AnyRoute, Selected extends Record<string, AnyRoute> = {}, Set = unknown, References extends Record<string, AnyRoute> = {}> {
+    /** Effective positional params; undefined while pending or without a value. */
+    readonly params: Resource<Readonly<ParamsOf<Target>> | undefined>;
+    /** Effective declared search; paired with params from the same parse operation. */
+    readonly search: Resource<Readonly<SearchOf<Target>> | undefined>;
+    /** Own native resolver results only; settles independently of paired inputs. */
+    readonly data: Resource<DataOf<Target> | undefined>;
+    /**
+     * Creates a native UrlTree for this exact declaration without navigating.
+     *
+     * @param values - Explicit effective params/search and optional own fragment.
+     * @returns Router.parseUrl's result, suitable for Angular RouterLink.
+     * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
+     */
+    link<Keys extends keyof SearchOf<Target> = never>(values: UrlValues<Target, Keys>): UrlTree;
+    /**
+     * Creates a UrlTree for the exact bound declaration, not its pathless winner.
+     *
+     * @param selector - The exact-current literal `.`.
+     * @param values - Explicit values for this declaration, with no current-input reuse.
+     * @returns Router.parseUrl's result without navigating.
+     * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
+     */
+    link<Keys extends keyof SearchOf<Target> = never>(selector: ".", values: UrlValues<Target, Keys>): UrlTree;
+    /**
+     * Creates a UrlTree for a statically admitted absolute/relative authored selector.
+     *
+     * @param selector - A single known template literal, never a concrete URL.
+     * @param values - The selected target's complete explicit values.
+     * @returns Router.parseUrl's result without navigating.
+     * @throws Synchronously for unknown selectors or invalid URL values.
+     */
+    link<const Selector extends keyof Selected & string, Keys extends keyof SearchOf<NoInfer<Selected[Selector]>> = never>(selector: Selector & (IsUnion<Selector> extends true ? never : unknown), values: UrlValues<NoInfer<Selected[Selector]>, Keys>): UrlTree;
+    /**
+     * Creates a UrlTree for a generated reference's own exact declaration.
+     *
+     * @param selector - A genuine destination exported by a facade in this route set.
+     * @param values - The referenced declaration's complete explicit values.
+     * @returns Router.parseUrl's result without navigating.
+     * @throws Synchronously for foreign/fake references or invalid URL values.
+     */
+    link<const Id extends keyof References & string, Keys extends keyof SearchOf<NoInfer<References[Id]>> = never>(selector: Destination<NoInfer<References[Id]>, Set, Id> & (IsUnion<Id> extends true ? never : unknown), values: UrlValues<NoInfer<References[Id]>, Keys>): UrlTree;
+    /**
+     * Navigates to this exact declaration via Router.navigateByUrl.
+     *
+     * @param values - Explicit effective params/search and optional own fragment.
+     * @returns Angular's identical Promise; Angular owns skips, redirects and failures.
+     * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
+     */
+    navigate<Keys extends keyof SearchOf<Target> = never>(values: UrlValues<Target, Keys>): Promise<boolean>;
+    /**
+     * Navigates to the exact bound declaration, not its pathless winner.
+     *
+     * @param selector - The exact-current literal `.`.
+     * @param values - Explicit values for this declaration, with no current-input reuse.
+     * @returns Angular's identical Router.navigateByUrl Promise.
+     * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
+     */
+    navigate<Keys extends keyof SearchOf<Target> = never>(selector: ".", values: UrlValues<Target, Keys>): Promise<boolean>;
+    /**
+     * Navigates to a statically admitted absolute/relative authored selector.
+     *
+     * @param selector - A single known template literal, never a concrete URL.
+     * @param values - The selected target's complete explicit values.
+     * @returns Angular's identical Router.navigateByUrl Promise.
+     * @throws Synchronously for unknown selectors or invalid URL values.
+     */
+    navigate<const Selector extends keyof Selected & string, Keys extends keyof SearchOf<NoInfer<Selected[Selector]>> = never>(selector: Selector & (IsUnion<Selector> extends true ? never : unknown), values: UrlValues<NoInfer<Selected[Selector]>, Keys>): Promise<boolean>;
+    /**
+     * Navigates to a generated reference's own exact declaration.
+     *
+     * @param selector - A genuine destination exported by a facade in this route set.
+     * @param values - The referenced declaration's complete explicit values.
+     * @returns Angular's identical Router.navigateByUrl Promise.
+     * @throws Synchronously for foreign/fake references or invalid URL values.
+     */
+    navigate<const Id extends keyof References & string, Keys extends keyof SearchOf<NoInfer<References[Id]>> = never>(selector: Destination<NoInfer<References[Id]>, Set, Id> & (IsUnion<Id> extends true ? never : unknown), values: UrlValues<NoInfer<References[Id]>, Keys>): Promise<boolean>;
+}
+declare function nativeOptions(definition: AnyRoute): Record<string, unknown>;
+declare function injectGeneratedRoute<Target extends AnyRoute, Selected extends Record<string, AnyRoute>, Set, References extends Record<string, AnyRoute>>(set: RouteSet, id: string): Handle<Target, Selected, Set, References>;
+
+export { Destination, assertIdentity, callbacks, createDestination, injectGeneratedRoute, nativeOptions, parseInputs, redirect };
+export type { Handle, RecordBinding, RouteSet };

package/types/loozo-angular-router.d.ts

@@ -0,0 +1 @@
+export { ParamCodec, Route, booleanParam, createUrl, defineRoute, enumParam, nullableSearchParam, numberParam, optionalSearchParam, stringParam } from '@loozo/angular-router/_core';