Add TypeScript declaration files

docs/getting-started.md

@@ -18,17 +18,15 @@ environment:
   non-browser environments, like [React
   Native](https://facebook.github.io/react-native/) or tests
 
-Since you'll only ever need to use one in a given app, we provide
-environment-specific bundles. You'll need to `import` one of these bundles:
+The main bundle exports one method for each environment: `createBrowserHistory`
+for browsers, `createHashHistory` for using hash history in browsers,  and
+`createMemoryHistory` for creating an in-memory history.
 
-- `history/browser`
-- `history/hash`
-- `history/memory`
-
-Each bundle exports a `createHistory` method you can use to create your own
-history object. In addition, `history/browser` and `history/hash` export a
-singleton instance you can use which reflects the state of [the current
-`document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document).
+In addition to the main bundle, the library also includes `history/browser` and
+`history/hash` bundles that export singletons you can use to quickly get a
+history instance for [the current
+`document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document)
+(web page).
 
 ## Basic Usage
 
@@ -37,6 +35,7 @@ Basic usage looks like this:
 ```js
 // Import the browser history singleton instance.
 import history from 'history/browser';
+
 // Alternatively, if you're using hash history import
 // the hash history singleton instance.
 // import history from 'history/hash';
@@ -62,21 +61,21 @@ history.back();
 unlisten();
 ```
 
-If you're using `history/memory` you'll need to create your own `history` object
+If you're using memory history you'll need to create your own `history` object
 before you can use it.
 
 ```js
-import { createHistory } from 'history/memory';
-let history = createHistory();
+import { createMemoryHistory } from 'history';
+let history = createMemoryHistory();
 ```
 
 If you're using browser or hash history with a `window` other than that of the
 current `document` (like an iframe), you'll need to create your own browser/hash
 history:
 
 ```js
-import { createHistory } from 'history/browser';
-let history = createHistory({
+import { createBrowserHistory } from 'history';
+let history = createBrowserHistory({
   window: iframe.contentWindow
 });
 ```
@@ -136,3 +135,20 @@ let unlisten = history.listen(myListener);
 // Later, when you're done...
 unlisten();
 ```
+
+## Utilities
+
+The main history bundle also contains both `createPath` and `parsePath` methods
+that may be useful when working with URL paths.
+
+```js
+let pathPieces = parsePath('/the/path?the=query#the-hash');
+// pathPieces = {
+//   pathname: '/the/path',
+//   search: '?the=query',
+//   hash: '#the-hash'
+// }
+
+let path = createPath(pathPieces);
+// path = '/the/path?the=query#the-hash'
+```

docs/installation.md

@@ -8,34 +8,16 @@ registry. You can install it using:
 ## Using a Bundler
 
 The best way to use the `history` library is with a bundler that supports
-JavaScript modules (we recommend [Rollup](https://rollupjs.org)). Then, you can
-write your code naturally, like:
+JavaScript modules (we recommend [Rollup](https://rollupjs.org)). Recent
+versions of Webpack and Parcel are also good choices.
+
+Then you can write your code using JavaScript `import` statements, like this:
 
 ```js
 import { createBrowserHistory } from 'history';
 // ...
 ```
 
-If you're using a bundler that does not support dead code removal, or you're not
-sure if your bundler supports dead code removal, we also publish
-environment-specific builds you can use to get just the code you need. You can
-use one of the following bundles:
-
-- `history/browser`
-- `history/hash`
-- `history/memory`
-
-Each of these bundles contains a subset of the code specific to that
-environment.
-
-```js
-// Import only the code needed to create a browser history
-import { createBrowserHistory } from 'history/browser';
-
-// Import only the code needed to create a memory history
-import { createMemoryHistory } from 'history/memory';
-```
-
 If you're using a bundler that doesn't understand JavaScript modules and only
 understands CommonJS, you can use `require` as you would with anything else:
 
@@ -53,6 +35,7 @@ just use the `history.production.min.js` build:
 
 ```html
 <script type="module">
+// Can also use history.development.js in development
 import { createBrowserHistory } from 'https://unpkg.com/history/history.production.min.js';
 // ...
 </script>
@@ -64,6 +47,7 @@ In legacy browsers that do not yet support JavaScript modules, you can use one
 of our UMD (global) builds:
 
 ```html
+<!-- Can also use history.development.js in development -->
 <script src="https://unpkg.com/history/umd/history.production.min.js"></script>
 ```
 

fixtures/hash-click.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <base href="/the/base" />
+    <script>
+      window.addEventListener('hashchange', () => {
+        console.log('hashchange', window.location.hash);
+      });
+
+      function handleClick(link) {
+        const href = link.getAttribute('href');
+        history.pushState(null, null, href);
+        return false; // preventDefault
+      }
+    </script>
+  </head>
+  <body>
+    <a href="/hash-click">home</a>
+    <a href="/hash-click#one">#one</a>
+    <a href="/hash-click#one" onclick="return handleClick(this)"
+      >#one w pushState</a
+    >
+    <a href="/hash-click#two">#two</a>
+    <a href="/hash-click#two" onclick="return handleClick(this)"
+      >#two w pushState</a
+    >
+  </body>
+</html>

fixtures/hash-history-length.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script>
+      console.log(window.history.length);
+    </script>
+  </head>
+  <body>
+    <a href="/hash-history-length">home</a>
+    <a href="/hash-history-length#one">#one</a>
+    <a href="/hash-history-length#two">#two</a>
+  </body>
+</html>

fixtures/unpkg-test.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html>
+  <body>
+    <script type="module">
+      import { createBrowserHistory } from 'https://unpkg.com/history@next/history.production.min.js';
+      let history = createBrowserHistory();
+      console.log(history);
+    </script>
+  </body>
+</html>

package.json

@@ -1,5 +1,4 @@
 {
-  "name": "history-packages",
   "private": true,
   "scripts": {
     "build": "node ./scripts/build.js",

packages/history/browser.d.ts

@@ -0,0 +1,5 @@
+import { History } from 'history';
+
+declare const _default: History;
+
+export default _default;

packages/history/browser.js

@@ -1,5 +1,4 @@
-import { createBrowserHistory } from './index.js';
-export { createBrowserHistory };
+import { createBrowserHistory } from './history.js';
 
 /**
  * Create a default instance for the current document.

packages/history/hash.d.ts

@@ -0,0 +1,5 @@
+import { History } from 'history';
+
+declare const _default: History;
+
+export default _default;

packages/history/hash.js

@@ -1,5 +1,4 @@
-import { createHashHistory } from './index.js';
-export { createHashHistory };
+import { createHashHistory } from './history.js';
 
 /**
  * Create a default instance for the current document.

packages/history/history.d.ts

@@ -0,0 +1,62 @@
+export type Action = "POP" | "PUSH" | "REPLACE";
+
+export type Path = string;
+export type PathPieces = {
+  pathname?: string;
+  search?: string;
+  hash?: string;
+};
+
+export type State = object;
+export interface Location<S extends State = State> extends PathPieces {
+  pathname: string;
+  search: string;
+  hash: string;
+  state?: S;
+  key?: string;
+}
+
+export interface Update<S extends State = State> {
+  action: Action;
+  location: Location<S>;
+}
+export interface Listener<S extends State = State> {
+  (update: Update<S>): void;
+}
+export type Unlistener = () => void;
+
+export interface Transaction<S extends State = State> extends Update {
+  retry(): void;
+}
+export interface Blocker<S extends State = State> {
+  (tx: Transaction<S>): void;
+}
+export type Unblocker = () => void;
+
+export interface History<S extends State = State> {
+  action: Action;
+  location: Location<S>;
+  createHref(to: Path | PathPieces): string;
+  push(to: Path | PathPieces, state?: State): void;
+  replace(to: Path | PathPieces, state?: State): void;
+  go(n: number): void;
+  back(): void;
+  forward(): void;
+  listen(listener: Listener<S>): Unlistener;
+  block(blocker: Blocker<S>): Unblocker;
+}
+export interface MemoryHistory<S extends State = State> extends History<S> {
+  index: number;
+}
+
+export function createBrowserHistory(options?: { window?: Window }): History;
+export function createHashHistory(options?: { window?: Window }): History;
+
+type InitialEntry = Path | PathPieces;
+export function createMemoryHistory(options?: {
+  initialEntries?: InitialEntry[];
+  initialIndex?: number;
+}): MemoryHistory;
+
+export function createPath(pieces: PathPieces): Path;
+export function parsePath(path: Path): PathPieces;

packages/history/package.json

@@ -8,6 +8,7 @@
   "main": "main.js",
   "module": "history.js",
   "unpkg": "umd/history.production.min.js",
+  "types": "history.d.ts",
   "sideEffects": false,
   "dependencies": {
     "@babel/runtime": "^7.7.6"

scripts/builds/history.js

@@ -11,7 +11,7 @@ const OUTPUT_DIR = 'build/history';
 
 const modules = [
   {
-    input: `${SOURCE_DIR}/index.js`,
+    input: `${SOURCE_DIR}/history.js`,
     output: {
       file: `${OUTPUT_DIR}/history.js`,
       format: 'esm',
@@ -31,15 +31,18 @@ const modules = [
       compiler(),
       copy({
         targets: [
-          { src: `${SOURCE_DIR}/package.json`, dest: OUTPUT_DIR },
           { src: 'README.md', dest: OUTPUT_DIR },
-          { src: 'LICENSE', dest: OUTPUT_DIR }
+          { src: 'LICENSE', dest: OUTPUT_DIR },
+          { src: `${SOURCE_DIR}/package.json`, dest: OUTPUT_DIR },
+          { src: `${SOURCE_DIR}/history.d.ts`, dest: OUTPUT_DIR },
+          { src: `${SOURCE_DIR}/browser.d.ts`, dest: OUTPUT_DIR },
+          { src: `${SOURCE_DIR}/hash.d.ts`, dest: OUTPUT_DIR }
         ],
         verbose: true
       })
     ].concat(PRETTY ? prettier({ parser: 'babel' }) : [])
   },
-  ...['browser', 'hash', 'memory'].map(env => {
+  ...['browser', 'hash'].map(env => {
     return {
       input: `${SOURCE_DIR}/${env}.js`,
       output: {
@@ -50,7 +53,8 @@ const modules = [
       plugins: [
         babel({
           exclude: /node_modules/,
-          presets: [['@babel/preset-env', { loose: true }]]
+          presets: [['@babel/preset-env', { loose: true }]],
+          plugins: ['babel-plugin-dev-expression']
         }),
         compiler()
       ].concat(PRETTY ? prettier({ parser: 'babel' }) : [])
@@ -60,7 +64,7 @@ const modules = [
 
 const webModules = [
   {
-    input: `${SOURCE_DIR}/index.js`,
+    input: `${SOURCE_DIR}/history.js`,
     output: {
       file: `${OUTPUT_DIR}/history.development.js`,
       format: 'esm',
@@ -77,7 +81,7 @@ const webModules = [
     ].concat(PRETTY ? prettier({ parser: 'babel' }) : [])
   },
   {
-    input: `${SOURCE_DIR}/index.js`,
+    input: `${SOURCE_DIR}/history.js`,
     output: {
       file: `${OUTPUT_DIR}/history.production.min.js`,
       format: 'esm',
@@ -98,7 +102,7 @@ const webModules = [
 
 const globals = [
   {
-    input: `${SOURCE_DIR}/index.js`,
+    input: `${SOURCE_DIR}/history.js`,
     output: {
       file: `${OUTPUT_DIR}/umd/history.development.js`,
       format: 'umd',
@@ -116,7 +120,7 @@ const globals = [
     ].concat(PRETTY ? prettier({ parser: 'babel' }) : [])
   },
   {
-    input: `${SOURCE_DIR}/index.js`,
+    input: `${SOURCE_DIR}/history.js`,
     output: {
       file: `${OUTPUT_DIR}/umd/history.production.min.js`,
       format: 'umd',