Fix intellisense/completions for partial route parameter objects

README.md

@@ -2,7 +2,7 @@
 
 # Ziggy – Use your Laravel routes in JavaScript
 
-[![GitHub Actions Status](https://img.shields.io/github/actions/workflow/status/tighten/ziggy/test.yml?branch=main&style=flat)](https://github.com/tighten/ziggy/actions?query=workflow:Test+branch:2.x)
+[![GitHub Actions Status](https://img.shields.io/github/actions/workflow/status/tighten/ziggy/test.yml?style=flat)](https://github.com/tighten/ziggy/actions/workflows/test.yml)
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/tightenco/ziggy.svg?style=flat)](https://packagist.org/packages/tightenco/ziggy)
 [![Downloads on Packagist](https://img.shields.io/packagist/dt/tightenco/ziggy.svg?style=flat)](https://packagist.org/packages/tightenco/ziggy)
 [![Latest Version on NPM](https://img.shields.io/npm/v/ziggy-js.svg?style=flat)](https://npmjs.com/package/ziggy-js)

package.json

@@ -56,6 +56,7 @@
         "qs-esm": "^7.0.3"
     },
     "devDependencies": {
+        "@types/node": "^25.3.5",
         "jsdom": "^28.1.0",
         "microbundle": "^0.15.1",
         "prettier": "^3.8.1",

src/js/index.d.ts

@@ -205,29 +205,35 @@ interface Router {
 // Called with no arguments - returns a Router instance
 export function route(): Router;
 
-// Called with configuration arguments only - returns a configured Router instance
-export function route(
-    name: undefined,
-    params: undefined,
-    absolute?: boolean,
-    config?: Config,
-): Router;
+// Called with just a route name - returns a URL string
+// Separate from the overloads below to preserve route name autocompletion
+export function route(name: ValidRouteName): RouteUrl;
 
-// Called with a route name and optional additional arguments - returns a URL string
+// Called with a route name and parameters - returns a URL string
 export function route<T extends ValidRouteName>(
-    name: T,
-    params?: RouteParams<T> | undefined,
+    name: T & {},
+    params: RouteParams<T> | undefined,
     absolute?: boolean,
     config?: Config,
 ): RouteUrl;
 
+// Called with a route name and single parameter - returns a URL string
+// Separate from the overload above for better parameter autocompletion and more specific error messages
 export function route<T extends ValidRouteName>(
-    name: T,
-    params?: ParameterValue | undefined,
+    name: T & {},
+    params: ParameterValue | undefined,
     absolute?: boolean,
     config?: Config,
 ): RouteUrl;
 
+// Called with configuration arguments only - returns a configured Router instance
+export function route(
+    name: undefined,
+    params: undefined,
+    absolute?: boolean,
+    config?: Config,
+): Router;
+
 /**
  * Ziggy's Vue plugin.
  */

tests/js/completions.test.ts

@@ -0,0 +1,130 @@
+import { resolve } from 'node:path';
+import ts from 'typescript';
+import { describe, expect, test } from 'vitest';
+
+const fixtureFile = resolve(__dirname, '__completions__.ts');
+
+function getCompletions(source: string, marker = '/*cursor*/') {
+    if (!source.includes(marker)) {
+        throw new Error(`Missing completion marker ${marker}`);
+    }
+
+    source = `
+        import { route } from '../../src/js';
+        declare module '../../src/js' {
+            interface RouteList {
+                'posts.comments.show': [
+                    { name: 'post'; required: true },
+                    { name: 'comment'; required: false; binding: 'uuid' },
+                ];
+                optional: [{ name: 'maybe'; required: false }];
+            }
+        }
+        ${source}
+    `;
+
+    const cursor = source.indexOf(marker);
+    source = source.replace(marker, '');
+
+    const compilerOptions: ts.CompilerOptions = {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true,
+        lib: ['lib.esnext.d.ts'],
+        noEmit: true,
+    };
+
+    function fileExists(fileName: string) {
+        return fileName === fixtureFile || ts.sys.fileExists(fileName);
+    }
+    function readFile(fileName: string) {
+        return fileName === fixtureFile ? source : ts.sys.readFile(fileName);
+    }
+
+    const host: ts.LanguageServiceHost = {
+        getCompilationSettings: () => compilerOptions,
+        getCurrentDirectory: () => process.cwd(),
+        getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+        getScriptFileNames: () => [fixtureFile],
+        getScriptVersion: () => '0',
+        getScriptSnapshot: (fileName) => {
+            const contents = readFile(fileName);
+            return contents === undefined ? undefined : ts.ScriptSnapshot.fromString(contents);
+        },
+        fileExists,
+        readFile,
+        readDirectory: ts.sys.readDirectory,
+        directoryExists: ts.sys.directoryExists,
+        getDirectories: ts.sys.getDirectories,
+        resolveModuleNames: (moduleNames, containingFile) =>
+            moduleNames.map(
+                (moduleName) =>
+                    ts.resolveModuleName(moduleName, containingFile, compilerOptions, {
+                        fileExists,
+                        readFile,
+                        directoryExists: ts.sys.directoryExists,
+                        getCurrentDirectory: () => process.cwd(),
+                        getDirectories: ts.sys.getDirectories,
+                        realpath: ts.sys.realpath,
+                    }).resolvedModule,
+            ),
+    };
+
+    const service = ts.createLanguageService(host);
+    const completions =
+        service
+            .getCompletionsAtPosition(fixtureFile, cursor, {})
+            ?.entries.map((entry) => entry.name) ?? [];
+
+    service.dispose();
+
+    return new Set(completions);
+}
+
+describe('TypeScript completions', () => {
+    test('suggest known route names', () => {
+        let completions = getCompletions(`
+            route('/*cursor*/');
+        `);
+
+        expect(completions).toContain('posts.comments.show');
+        expect(completions).toContain('optional');
+    });
+
+    test('suggest route params when a required param is still missing', () => {
+        let completions = getCompletions(`
+            route('posts.comments.show', {
+                /*cursor*/
+            });
+        `);
+
+        expect(completions).toContain('post');
+        expect(completions).toContain('comment');
+        expect(completions).toContain('_query');
+    });
+
+    test('suggest remaining params after required params are provided', () => {
+        let completions = getCompletions(`
+            route('posts.comments.show', {
+                post: 1,
+                /*cursor*/
+            });
+        `);
+
+        expect(completions).toContain('comment');
+        expect(completions).toContain('_query');
+        expect(completions).not.toContain('post');
+    });
+
+    test('suggest optional params on all-optional routes', () => {
+        let completions = getCompletions(`
+            route('optional', {
+                /*cursor*/
+            });
+        `);
+
+        expect(completions).toContain('maybe');
+        expect(completions).toContain('_query');
+    });
+});

tests/js/route.test-d.ts

@@ -112,12 +112,17 @@ assertType(route().current('posts.comments.show', 'foo'));
 assertType(route('optional', []));
 assertType(route('optional', ['foo']));
 
+// All-optional route with config
+assertType(route('optional', undefined, false));
+assertType(route('optional', undefined, undefined, {} as Config));
+
 // Test route function return types
 assertType<string>(route('optional', { maybe: 'foo' }));
 assertType<string>(route('optional', 'foo'));
 assertType<RouteUrl>(route('posts.comments.show', 'foo'));
 // @ts-expect-error a plain string is not assignable to RouteUrl
 assertType<RouteUrl>('/posts/foo' as string);
+assertType<Router>(route(undefined, undefined, false));
 assertType<Router>(route(undefined, undefined, undefined, {} as Config));
 
 // Uncomment to test strict route name checking - invalid route names in this file should error
@@ -126,3 +131,17 @@ assertType<Router>(route(undefined, undefined, undefined, {} as Config));
 //         strictRouteNames: true;
 //     }
 // }
+
+// Test Intellisense/autocomplete
+assertType(
+    // @ts-expect-error missing required 'post' parameter
+    route('posts.comments.show', {
+        // Trigger completions here (add a new line and type 'p' or 'c') - should suggest 'post' and 'comment'
+    }),
+);
+assertType(
+    route('posts.comments.show', {
+        post: 1,
+        // Trigger completions here - now that 'post' (required) is provided, suggestions show 'comment' as expected
+    }),
+);

tsconfig.json

@@ -2,7 +2,8 @@
     "compilerOptions": {
         "module": "ESNext",
         "moduleResolution": "Bundler",
-        "target": "ESNext"
+        "target": "ESNext",
+        "types": ["node"]
     },
     "exclude": ["vendor", "tests/fixtures"]
 }