Drop-in TypeScript support for the 'staticify' module

staticify TypeScript Drop-In Support.md

staticify

These type definitions will help you work with react-intl-tel-input in TypeScript while this library doesn't have official support for it.

UPDATE: Follow the development of baked-in types here: errorception/staticify#48

---

Table of Contents

• Versions Supported
• How You Can Use This
• Known Limitations

---

Versions Supported

>= 4

How You Can Use This

Those of you who are familiar with TypeScript .d.ts files would already know how to get this done your own way, but for those who don't, well, here's one way to do it using express-generator-typescript:

1. Make an app.

   express-generator-typescript express-typescript-example

2. Use the tsconfig.json file I've sampled to configure TypeScript in your project.

3. Add the type definition file to a @/types folder in /src, so that type definitions are located exactly in /src/@types/staticify/index.d.ts, like this:

   ├── env
   ├── node_modules
   ├── spec
   ├── src
   │   ├── @types
   │   │   └── react-intl-tel-input
   │   │       └── index.d.ts
   │   ├── daos
   │   ├── public
   │   ├── routes
   │   ├── shared
   │   ├── views
   │   ├── index.ts
   │   ├── LoadEnv.ts
   │   └── Server.ts
   ├── build.js
   ├── package.json
   ├── package-lock.json
   ├── tsconfig.json
   ├── tsconfig.prod.json
   └── tslint.json
   

4. Use the library for effect.

   import staticify from 'staticify';

Known Limitations

None.

staticify.d.ts

declare module 'staticify' {
  import { SendOptions } from 'send';
  import { RequestHandler } from 'express';
  import { Request } from 'express-serve-static-core';

  export type StaticifyOptions = {
    /**
     * Include all files when scanning the public directory.
     * By default, the directories from [ignore-by-default](https://github.com/novemberborn/ignore-by-default/blob/master/index.js) are ignored.
     *
     * @type {boolean}
     * @default false
     */
    includeAll?: boolean;
    /**
     * Generate a short (7-digit) MD5 hash instead of the full (32-digit) one.
     *
     * @type {boolean}
     * @default true
     */
    shortHash?: boolean;
    /**
     * If you are using the staticify convenience middleware through a specific route, it is necessary to indicate the route in this option.
     *
     * @type {string}
     * @default '/'
     */
    pathPrefix?: string;
    /**
     * `maxAge` for assets without a hash such as /image.png passed to [send](https://github.com/pillarjs/send).
     *
     * Can be defined as a number of milliseconds or string accepted by [ms](https://www.npmjs.org/package/ms#readme) module (eg. `'5d'`, `'1y'`, etc.)
     *
     * @type {(string|number)}
     * @default 0
     */
    maxAgeNonHashed?: string|number;
    /**
     * You can pass any [send](https://github.com/pillarjs/send) options; used in `middleware` and `serve` functions.
     *
     * @type {SendOptions}
     * @default { maxAge: '1y' } // hashed assets
     * @default { maxAge: 0 } // non-hashed assets
     */
    sendOptions?: SendOptions;
  };

  export interface Statificy {
    _versions: object;
    /**
      Does the following transformation to the `path`, and returns immediately:

      ```js
      staticify.getVersionedPath('/path/to/file.ext'); // --> /path/to/file.<MD5 of the contents of file.ext>.ext
      ```

      This method is meant to be used inside your templates.

      This method is really fast (simply an in-memory lookup) and returns immediately.
      When you initialize this module, it crawls your public folder synchronously at startup, and pre-determines all the MD5 hashes for your static files.
      This slows down application startup slightly, but it keeps the runtime performance at its peak.
     *
     * @param {string} path
     * @returns {string}
     * @memberof Statificy
     */
    getVersionedPath(path: string): string;
    /**
      Takes the input string, and replaces any paths it can understand. For example:

      ```js
      staticify.replacePaths('body { background: url("/index.js") }');
      ```

      returns

      ```js
      "body { background: url('/index.d766c4a983224a3696bc4913b9e47305.js') }"
      ```

      Perfect for use in your build script, to modify references to external paths within your CSS files.

     *
     * @param {string} input
     * @returns {string}
     * @memberof Statificy
     */
    replacePaths(input: string): string;
    /**
      Removes the MD5 identifier in a path.

      ```js
      staticify.stripVersion('/path/to/file.ae2b1fca515949e5d54fb22b8ed95575.ext'); // --> /path/to/file.ext
      ```

      Note, this function doesn't verify that the hash is valid. It simply finds what looks like a hash and strips it from the path.
     *
     * @param {string} path
     * @returns {string}
     * @memberof Statificy
     */
    stripVersion(path: string): string;
    /**
      Handles an incoming request for the file.
      Internally calls `.stripVersion` to strip the version identifier, and serves the file with a `maxAge` of one year, using [send](https://github.com/pillarjs/send).
      Returns a stream that can be `.pipe`d to a http response stream.
      See [here](https://github.com/pillarjs/send#options) for the options you can pass.

      ```js
      staticify.serve(req, {
          sendOptions: {
              maxAge: 3600 * 1000 // milliseconds
          }
      }).pipe(res);
      ```
     *
     * @param {Request} req
     * @memberof Statificy
     */
    serve(req: Request): void;
    /**
      Rebuilds the MD5 version cache described above.
      Use this method sparingly.
      This crawls your public folder synchronously (in a blocking fashion) to rebuild the cache.
      This is typically only useful when you are doing some kind of live-reloading during development.
     *
     * @memberof Statificy
     */
    refresh(): void;
    /**
      Convenience wrapper over `.serve` to handle static files in express.js.

      ```js
      app.use(staticify.middleware);  // `app` is your express instance
      ```
     *
     * @type {RequestHandler}
     * @memberof Statificy
     */
    middleware: RequestHandler;
  }

  /**
   * Provides helpers to add a version identifier to your static asset's public URLs, and to remove the hash before serving the file from the file system.
   *
   * @export
   * @param {string} root The root path to the static content.
   * @param {StaticifyOptions} [options] Additional options.
   * @returns {Statificy} 
   */
  export default function staticify(root: string, options?: StaticifyOptions): Statificy;
}

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": "./",
    "emitDecoratorMetadata": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "importHelpers": true,
    "module": "commonjs",
    "outDir": "dist",
    "removeComments": true,
    "sourceMap": true,
    "strict": true,
    "target": "es6",
    "moduleResolution": "node",
    "paths": {
      "@daos/*": [
        "src/daos/*"
      ],
      "@entities/*": [
        "src/entities/*"
      ],
      "@shared/*": [
        "src/shared/*"
      ],
      "@server": [
        "src/Server"
      ]
    },
    "types": [
      "node"
    ],
    "typeRoots": [
      "node_modules/@types",
      "src/@types"
    ]
  },
  "include": [
    "src/**/*.ts",
    "spec/**/*.ts"
  ],
  "exclude": [
    "src/public/"
  ]
}