Add TypeScript declarations (#681)

ktsn · yyx990803 · commit 7eef024b5d9e · 2016-09-24T12:48:37.000-04:00
* add TypeScript declarations

* add config of package.json for typings

* fix vue dep
diff --git a/package.json b/package.json
@@ -5,10 +5,14 @@
   "author": "Evan You",
   "license": "MIT",
   "main": "dist/vue-router.js",
+  "typings": "types/index.d.ts",
   "files": [
     "dist/vue-router.js",
     "dist/vue-router.min.js",
-    "src"
+    "src",
+    "types/index.d.ts",
+    "types/router.d.ts",
+    "types/vue.d.ts"
   ],
   "keywords": [
     "vue",
@@ -20,9 +24,10 @@
     "dev:dist": "rollup -wm -c build/rollup.config.js",
     "build": "rollup --environment NODE_ENV:production -c build/rollup.config.js && uglifyjs dist/vue-router.js -cm --comments -o dist/vue-router.min.js",
     "lint": "eslint src examples",
-    "test": "npm run lint && flow check && npm run test:unit && npm run test:e2e",
+    "test": "npm run lint && flow check && npm run test:unit && npm run test:e2e && npm run test:types",
     "test:unit": "jasmine JASMINE_CONFIG_PATH=test/unit/jasmine.json",
     "test:e2e": "node test/e2e/runner.js",
+    "test:types": "tsc -p types/test",
     "docs": "cd docs && gitbook serve",
     "deploy-docs": "bash ./build/update-docs.sh",
     "release": "bash build/release.sh"
@@ -60,8 +65,9 @@
     "rollup-plugin-replace": "^1.1.1",
     "rollup-watch": "^2.4.0",
     "selenium-server": "^2.53.1",
+    "typescript": "^2.0.3",
     "uglify-js": "^2.7.0",
-    "vue": "^2.0.0-rc.6",
+    "vue": "^2.0.0-rc.7",
     "vue-loader": "^9.4.0",
     "webpack": "^1.13.1",
     "webpack-dev-middleware": "^1.6.1"
diff --git a/types/index.d.ts b/types/index.d.ts
@@ -0,0 +1,20 @@
+import "./vue";
+import * as R from "./router";
+
+// `VueRouter` in `export = VueRouter` must be a namespace
+// All available types are exported via this namespace
+declare namespace VueRouter {
+  export type RouterMode = R.RouterMode;
+  export type RawLocation = R.RawLocation;
+  export type RedirectOption = R.RedirectOption;
+  export type RouterOptions = R.RouterOptions;
+  export type RouteConfig = R.RouteConfig;
+  export type RouteRecord = R.RouteRecord;
+  export type Location = R.Location;
+  export type Route = R.Route;
+}
+
+// TS cannot merge imported class with namespace, declare a subclass to bypass
+declare class VueRouter extends R.VueRouter {}
+
+export = VueRouter;
diff --git a/types/router.d.ts b/types/router.d.ts
@@ -0,0 +1,98 @@
+import Vue = require("vue");
+import { ComponentOptions, PluginFunction } from "vue";
+
+type Component = ComponentOptions<Vue> | typeof Vue;
+type Dictionary<T> = { [key: string]: T };
+
+export type RouterMode = "hash" | "history" | "abstract";
+export type RawLocation = string | Location;
+export type RedirectOption = RawLocation | ((to: Route) => RawLocation);
+
+declare class VueRouter {
+  constructor (options?: RouterOptions);
+
+  app: Vue;
+  mode: RouterMode;
+  currentRoute: Route;
+
+  beforeEach (
+    guard: (
+      route: Route,
+      redirect: (location: RawLocation) => void,
+      next: () => void
+    ) => any
+  ): void;
+  afterEach (hook: (route: Route) => any): void;
+  push (location: RawLocation): void;
+  replace (location: RawLocation): void;
+  go (n: number): void;
+  back (): void;
+  forward (): void;
+  getMatchedComponentes (): Component;
+
+  static install: PluginFunction<never>;
+}
+
+export interface RouterOptions {
+  routes?: RouteConfig[];
+  mode?: RouterMode;
+  base?: string;
+  linkActiveClass?: string;
+  scrollBehavior?: (
+    to: Route,
+    from: Route,
+    savedPosition: { x: number, y: number } | undefined
+  ) => { x: number, y: number } | { selector: string } | void;
+}
+
+export interface RouteConfig {
+  path: string;
+  name?: string;
+  component?: Component;
+  components?: Dictionary<Component>;
+  redirect?: RedirectOption;
+  alias?: string | string[];
+  children?: RouteConfig[];
+  meta?: any;
+  beforeEnter?: (
+    route: Route,
+    redirect: (location: RawLocation) => void,
+    next: () => void
+  ) => any;
+}
+
+export interface RouteRecord {
+  path: string;
+  components: Dictionary<Component>;
+  instances: Dictionary<Vue>;
+  name?: string;
+  parent?: RouteRecord;
+  redirect?: RedirectOption;
+  matchAs?: string;
+  meta: any;
+  beforeEnter?: (
+    route: Route,
+    redirect: (location: RawLocation) => void,
+    next: () => void
+  ) => any;
+}
+
+export interface Location {
+  name?: string;
+  path?: string;
+  hash?: string;
+  query?: Dictionary<string>;
+  params?: Dictionary<string>;
+}
+
+export interface Route {
+  path: string;
+  name?: string;
+  hash: string;
+  query: Dictionary<string>;
+  params: Dictionary<string>;
+  fullPath: string;
+  matched: RouteRecord[];
+  redirectedFrom?: string;
+  meta?: any;
+}
diff --git a/types/test/index.ts b/types/test/index.ts
@@ -0,0 +1,145 @@
+import Vue = require("vue");
+import { ComponentOptions } from "vue";
+
+import VueRouter = require("../index");
+import { Route, RouteRecord, RedirectOption } from "../index";
+
+Vue.use(VueRouter);
+
+const Home = { template: "<div>home</div>" };
+const Foo = { template: "<div>foo</div>" };
+const Bar = { template: "<div>bar</div>" };
+
+const Hook: ComponentOptions<{ a: string } & Vue> = {
+  template: "<div>hook</div>",
+
+  beforeRouteEnter (route, redirect, next) {
+    route.params;
+    redirect("/");
+    next(vm => {
+      vm.a = "done";
+    });
+  },
+
+  beforeRouteLeave (route, redirect, next) {
+    route.params;
+    redirect("/");
+    next();
+  }
+};
+
+const router = new VueRouter({
+  mode: "history",
+  base: "/",
+  linkActiveClass: "active",
+  scrollBehavior: (to, from, savedPosition) => {
+    if (from.path === "/") {
+      return { selector: "#app" };
+    }
+
+    if (to.path === "/child") {
+      return;
+    }
+
+    if (savedPosition) {
+      return savedPosition;
+    }
+  },
+  routes: [
+    { path: "/", name: "home", component: Home, children: [
+      {
+        path: "child",
+        components: {
+          default: Foo,
+          bar: Bar
+        },
+        meta: { auth: true },
+        beforeEnter (route, redirect, next) {
+          route.params;
+          redirect({ name: "home" });
+          next();
+        }
+      },
+      {
+        path: "children",
+        redirect: to => {
+          to.params;
+          return "/child";
+        }
+      }
+    ]},
+    { path: "/home", alias: "/" },
+    { path: "*", redirect: "/" }
+  ]
+});
+
+const App: Vue = router.app;
+const mode: string = router.mode;
+
+const route: Route = router.currentRoute;
+const path: string = route.path;
+const name: string | undefined = route.name;
+const hash: string = route.hash;
+const query: string = route.query["foo"];
+const params: string = route.params["bar"];
+const fullPath: string = route.fullPath;
+const redirectedFrom: string | undefined = route.redirectedFrom;
+const meta: any = route.meta;
+const matched: RouteRecord[] = route.matched;
+
+matched.forEach(m => {
+  const path: string = m.path;
+  const components: {
+    [key: string]: ComponentOptions<Vue> | typeof Vue
+  } = m.components;
+  const instances: { [key: string]: Vue } = m.instances;
+  const name: string | undefined = m.name;
+  const parant: RouteRecord | undefined = m.parent;
+  const redirect: RedirectOption | undefined = m.redirect;
+});
+
+router.beforeEach((route, redirect, next) => {
+  route.params;
+  redirect("/");
+  next();
+});
+
+router.afterEach(route => {
+  route.params;
+});
+
+router.push({
+  path: "/",
+  params: {
+    foo: "foo"
+  },
+  query: {
+    bar: "bar"
+  },
+  hash: "hash"
+});
+router.replace({ name: "home" });
+
+router.go(-1);
+router.back();
+router.forward();
+
+const Components: ComponentOptions<Vue> | typeof Vue = router.getMatchedComponentes();
+
+const vm = new Vue({
+  router,
+  template: `
+    <div id="app">
+      <h1>Basic</h1>
+      <ul>
+        <li><router-link to="/">/</router-link></li>
+        <li><router-link to="/foo">/foo</router-link></li>
+        <li><router-link to="/bar">/bar</router-link></li>
+      </ul>
+      <router-view class="view"></router-view>
+    </div>
+  `
+}).$mount("#app");
+
+vm.$router.push("/");
+vm.$route.params;
diff --git a/types/test/tsconfig.json b/types/test/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "commonjs",
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noEmit": true
+  },
+  "include": [
+    "*.ts",
+    "../*.d.ts"
+  ]
+}
diff --git a/types/typings.json b/types/typings.json
@@ -0,0 +1,4 @@
+{
+  "name": "vue-router",
+  "main": "index.d.ts"
+}
diff --git a/types/vue.d.ts b/types/vue.d.ts
@@ -0,0 +1,34 @@
+/**
+ * Augment the typings of Vue.js
+ */
+
+import Vue = require("vue");
+import VueRouter = require("./index");
+import { Route, RawLocation } from "./index";
+
+declare module "vue/types/vue" {
+  interface Vue {
+    $router: VueRouter;
+    $route: Route;
+  }
+}
+
+declare module "vue/types/options" {
+  interface ComponentOptions<V extends Vue> {
+    router?: VueRouter;
+
+    beforeRouteEnter?: (
+      this: never,
+      route: Route,
+      redirect: (location: RawLocation) => void,
+      next: (callback: (vm: V) => any) => void
+    ) => any;
+
+    beforeRouteLeave?: (
+      this: V,
+      route: Route,
+      redirect: (location: RawLocation) => void,
+      next: () => void
+    ) => any;
+  }
+}

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "name": "vue-router",
 +  "main": "index.d.ts"
 +}