/** * A list of routes and their parameters and bindings. * * Extended and filled by the route list generated with `php artisan ziggy:generate --types`. */ export interface RouteList {} /** * Marker interface to configure Ziggy's type checking behavior. */ export interface TypeConfig {} /** * A route name registered with Ziggy. */ type KnownRouteName = keyof RouteList; /** * A route name, or any string. */ type RouteName = KnownRouteName | (string & {}); // `(string & {})` prevents TypeScript from reducing this type to just `string`, // which would prevent intellisense from autocompleting known route names. // See https://stackoverflow.com/a/61048124/6484459. /** * A generated route URL string, branded to distinguish it from a plain string. */ declare const RouteUrlBrand: unique symbol; export type RouteUrl = string & { readonly [RouteUrlBrand]: typeof RouteUrlBrand }; /** * A valid route name to pass to `route()` to generate a URL. */ type ValidRouteName = TypeConfig extends { strictRouteNames: true } ? KnownRouteName : RouteName; /** * Information about a single route parameter. */ type ParameterInfo = { name: string; required: boolean; binding?: string }; /** * A primitive route parameter value, as it would appear in a URL. */ type RawParameterValue = string | number; // TODO: Technically booleans work too, does it make sense to add them? Here? What would that look like? /** * An object parameter value containing the 'default' binding key `id`, e.g. representing an Eloquent model. */ type DefaultRoutable = { id: RawParameterValue } & Record; /** * A route parameter value. */ type ParameterValue = RawParameterValue | DefaultRoutable; /** * A parseable route parameter, either plain or nested inside an object under its binding key. */ type Routable = I extends { binding: infer B extends string } ? | { [K in B]: RawParameterValue } | ({ [K in B]: RawParameterValue } & Record) | RawParameterValue : ParameterValue; // Uncomment to test: // type A = Routable<{ name: 'foo'; required: true; binding: 'bar' }>; // = RawParameterValue | { bar: RawParameterValue } // type B = Routable<{ name: 'foo', required: true, }>; // = RawParameterValue | DefaultRoutable // Utility types for KnownRouteParamsObject type RequiredParams = Extract; type OptionalParams = Extract; /** * An object containing a special '_query' key to target the query string of a URL. */ type HasQueryParam = { _query?: Record }; /** * An object of parameters for an unspecified route. */ type GenericRouteParamsObject = Record & HasQueryParam; // `keyof any` essentially makes it function as a plain `Record` /** * An object of parameters for a specific named route. */ type KnownRouteParamsObject = { [T in RequiredParams as T['name']]: Routable; } & { [T in OptionalParams as T['name']]?: Routable; } & GenericRouteParamsObject; // `readonly` allows TypeScript to determine the actual values of all the // parameter names inside the array, instead of just seeing `string`. // See https://github.com/tighten/ziggy/pull/664#discussion_r1329978447. // Uncomment to test: // type A = KnownRouteParamsObject<[{ name: 'foo'; required: true }, { name: 'bar'; required: false }]>; // = { foo: ... } & { bar?: ... } /** * An object of route parameters. */ type RouteParamsObject = N extends KnownRouteName ? KnownRouteParamsObject : GenericRouteParamsObject; /** * An array of parameters for an unspecified route. */ // TODO: this may be able to be more specific, like `Routable[]`, // depending how we want to handle nested objects inside parameter arrays type GenericRouteParamsArray = unknown[]; /** * An array of parameters for a specific named route. * * Required parameters come first as required tuple elements, then optional * parameters become optional tuple elements, followed by arbitrary extras. */ type KnownRouteParamsArray = [ ...RequiredParamsTuple, ...OptionalParamsTuple, ]; type RequiredParamsTuple = I extends readonly [infer F extends ParameterInfo, ...infer R extends ParameterInfo[]] ? F extends { required: true } ? [Routable, ...RequiredParamsTuple] : [] : []; type OptionalParamsTuple = I extends readonly [infer F extends ParameterInfo, ...infer R extends ParameterInfo[]] ? F extends { required: false } ? [Routable?, ...OptionalParamsTuple] : OptionalParamsTuple : [...unknown[]]; // Uncomment to test: // type B = KnownRouteParamsArray<[{ name: 'post'; required: true; binding: 'uuid' }]>; // = [RawParameterValue | { uuid: RawParameterValue }, ...unknown[]] /** * An array of route parameters. */ type RouteParamsArray = N extends KnownRouteName ? KnownRouteParamsArray : GenericRouteParamsArray; /** * All possible parameter argument shapes for a route. */ type RouteParams = RouteParamsObject | RouteParamsArray; /** * A route. */ interface Route { uri: string; methods: ('GET' | 'HEAD' | 'POST' | 'PATCH' | 'PUT' | 'OPTIONS' | 'DELETE')[]; domain?: string; parameters?: string[]; bindings?: Record; wheres?: Record; middleware?: string[]; } /** * Ziggy's config object. */ interface Config { url: string; port: number | null; defaults: Record; routes: Record; location?: { host?: string; pathname?: string; search?: string; } | string; } // qs's parsed query params type, so we don't have to have qs as a dependency interface ParsedQs { [key: string]: undefined | string | string[] | ParsedQs | ParsedQs[]; } /** * Ziggy's Router class. */ interface Router { current(): ValidRouteName | undefined; current(name: T, params?: ParameterValue | RouteParams): boolean; get params(): Record; get routeParams(): Record; get queryParams(): ParsedQs; has(name: T): boolean; } /** * Ziggy's route helper. */ // Call with no arguments - returns a Router instance export function route(): Router; // Call with just a route name - returns a URL string (separate from below to preserve route name autocompletion) export function route(name: ValidRouteName): RouteUrl; // Call with a route name and parameters - returns a URL string export function route( name: T & {}, params: RouteParams | undefined, absolute?: boolean, config?: Config, ): RouteUrl; // Call with a route name and single parameter - returns a URL string (separate from above for better parameter autocompletion and more specific error messages) export function route( name: T & {}, params: ParameterValue | undefined, absolute?: boolean, config?: Config, ): RouteUrl; // Call with configuration arguments only - returns a configured Router instance export function route( name: undefined, params: undefined, absolute?: boolean, config?: Config, ): Router; // All allowed runtime calls (preserves flexible derived type shape) export function route( name?: T, params?: RouteParams | ParameterValue, absolute?: boolean, config?: Config, ): RouteUrl | Router; /** * Ziggy's Vue plugin. */ export const ZiggyVue: { install(app: any, options?: Config | (() => Config)): void; }; /** * Ziggy's React hook. */ export function useRoute(defaultConfig?: Config): typeof route;