@loozo/angular-router 0.0.1 → 0.0.3

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

@@ -1,56 +1,193 @@
-import { ActivatedRouteSnapshot, Route, RedirectFunction, UrlTree } from '@angular/router';
-import { AnyRoute, ParamsOf, SearchOf, UrlValues } from '@loozo/angular-router/_core';
-import { Resource } from '@angular/core';
-
+import { ActivatedRouteSnapshot, PartialMatchRouteSnapshot, RedirectFunction, Route, 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[];
+  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>>>>;
+  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>>;
+  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;
-
+interface Job {
+  readonly source: "path" | "search";
+  readonly key: string;
+  readonly raws: readonly string[];
+  readonly array: boolean;
+  readonly codec: {
+    parse(raw: string): unknown;
+  };
+}
+interface Operation {
+  readonly promise: Promise<Parsed>;
+  outcome: {
+    value: Parsed;
+  } | {
+    error: Error;
+  } | undefined;
+}
+declare function hasIdentity(snapshot: Pick<ActivatedRouteSnapshot, "routeConfig">, id: string): boolean;
+export declare function assertIdentity(snapshot: Pick<ActivatedRouteSnapshot, "routeConfig">, id: string): void;
+declare function inputError(source: "path" | "search", key: string, reason: "missing" | "repeated" | "invalid", cause?: unknown): Error;
+declare function validateRaw(source: "path" | "search", key: string, raws: readonly unknown[], array: boolean): asserts raws is readonly string[];
+declare function pathJobs(definition: AnyRoute, url: readonly {
+  path: string;
+}[]): Job[];
+declare function searchJobs(definition: AnyRoute, snapshot: Pick<ActivatedRouteSnapshot, "queryParamMap">): Job[];
+declare function runJobs(jobs: readonly Job[]): Promise<Parsed>;
+declare function fullOperation(set: RouteSet, id: string, snapshot: ActivatedRouteSnapshot): Operation;
+export declare function parseInputs(set: RouteSet, id: string, snapshot: ActivatedRouteSnapshot): Promise<Parsed>;
+declare function matchingInputs(set: RouteSet, id: string, snapshot: PartialMatchRouteSnapshot): Promise<Parsed>;
+export declare function callbacks(set: RouteSet, id: string): Pick<Route, "canActivate" | "canActivateChild" | "canMatch" | "resolve">;
+export declare function redirect(definition: () => AnyRoute): RedirectFunction;
 declare const destinationBrand: unique symbol;
-declare class Destination<Target extends AnyRoute, Set = unknown, Id extends string = string> {
-    #private;
-    readonly [destinationBrand]: {
-        readonly target: Target;
-        readonly set: Set;
-        readonly id: Id;
-    };
+/**
+ * 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.
+ */
+export 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>;
+export 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?: infer Data;
 } ? Readonly<Data> : never;
 type IsUnion<Value, Whole = Value> = Value extends unknown ? [Whole] extends [Value] ? false : true : never;
-interface Handle<Target extends AnyRoute, Selected extends Record<string, AnyRoute> = {}, Set = unknown, References extends Record<string, AnyRoute> = {}> {
-    readonly params: Resource<Readonly<ParamsOf<Target>> | undefined>;
-    readonly search: Resource<Readonly<SearchOf<Target>> | undefined>;
-    readonly data: Resource<DataOf<Target> | undefined>;
-    link<Keys extends keyof SearchOf<Target> = never>(values: UrlValues<Target, Keys>): UrlTree;
-    link<Keys extends keyof SearchOf<Target> = never>(selector: ".", values: UrlValues<Target, Keys>): UrlTree;
-    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;
-    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;
-    navigate<Keys extends keyof SearchOf<Target> = never>(values: UrlValues<Target, Keys>): Promise<boolean>;
-    navigate<Keys extends keyof SearchOf<Target> = never>(selector: ".", values: UrlValues<Target, Keys>): Promise<boolean>;
-    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>;
-    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>;
+/**
+ * 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.
+ * ```
+ */
+export 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 };
+export declare function nativeOptions(definition: AnyRoute): Record<string, unknown>;
+export 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 type { RecordBinding, RouteSet };

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

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

package/.npmignore

@@ -1,3 +0,0 @@
-# Nested package.json's are only needed for development.
-_core/package.json
-_generated/package.json

package/fesm2022/loozo-angular-router.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"loozo-angular-router.mjs","sources":["../../src/loozo-angular-router.ts"],"sourcesContent":["/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAAA;;AAEG"}