feat: add TypeScript definition (#69)

Co-authored-by: Erick Zhao <[email protected]>

.gitignore

@@ -13,3 +13,4 @@ results
 
 npm-debug.log
 node_modules
+typedoc

README.md

@@ -4,15 +4,17 @@
 
 Node module to edit resources of Windows executables.
 
-## Docs
+## Requirements
+
+On platforms other than Windows, you will need to have [Wine](https://winehq.org)
+1.6 or later installed and in the system path.
+
+## Usage
 
 ```javascript
 const rcedit = require('rcedit')
 ```
 
-On platforms other than Windows, you will need to have [Wine](http://winehq.org)
-1.6 or later installed and in the system path.
-
 ### `async rcedit(exePath, options)`
 
 `exePath` is the path to the Windows executable to be modified.

lib/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Runs the `rcedit` Windows binary (via Wine on macOS/Linux) to modify the metadata of a
+ * Windows executable.
+ *
+ * @param exePath - the path to the Windows executable to be modified
+ * @param options - metadata used to update the Windows executable
+ */
+declare function rcedit (exePath: string, options: rcedit.Options): Promise<void>
+
+/* eslint-disable-next-line no-redeclare */
+declare namespace rcedit {
+  /** See [MSDN](https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/deployment/trustinfo-element-clickonce-application?view=vs-2015#requestedexecutionlevel) for details. */
+  type RequestedExecutionLevel = 'asInvoker' | 'highestAvailable' | 'requireAdministrator'
+  /**
+   * Basic user-supplied metadata embedded in the application. Docstrings are copied from MSDN.
+   *
+   * See [MSDN](https://docs.microsoft.com/en-us/windows/win32/menurc/stringfileinfo-block) for details.
+   */
+  interface VersionStringOptions {
+    /** Additional information that should be displayed for diagnostic purposes. */
+    Comments?: string
+    /** Company that produced the executable. */
+    CompanyName?: string
+    /** File description to be presented to users. */
+    FileDescription?: string
+    /** Internal name of the file. Usually, this string should be the original filename, without the extension. */
+    InternalFilename?: string
+    /** Copyright notices that apply, including the full text of all notices, legal symbols, copyright dates, etc. */
+    LegalCopyright?: string
+    /** Trademarks and registered trademarks, including the full text of all notices, legal symbols, trademark numbers, etc. */
+    LegalTrademarks1?: string
+    /** Trademarks and registered trademarks, including the full text of all notices, legal symbols, trademark numbers, etc. */
+    LegalTrademarks2?: string
+    /** Original name of the file, not including a path. */
+    OriginalFilename?: string
+    /** Name of the product with which the file is distributed. */
+    ProductName?: string
+  }
+  /**
+   * EXE metadata that can be changed.
+   */
+  interface Options {
+    /** The metadata within a version-information resource. */
+    'version-string'?: VersionStringOptions
+    /**
+     * See [MSDN](https://docs.microsoft.com/en-us/windows/win32/msi/version) for the version format.
+     */
+    'file-version'?: string
+    /**
+     * See [MSDN](https://docs.microsoft.com/en-us/windows/win32/msi/version) for the version format.
+     */
+    'product-version'?: string
+    /**
+     * Absolute path to the [ICO-formatted icon](https://en.wikipedia.org/wiki/ICO_(file_format))
+     * to set as the application's icon.
+     */
+    icon?: string
+    /** See [MSDN](https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/deployment/trustinfo-element-clickonce-application?view=vs-2015#requestedexecutionlevel) for details. */
+    'requested-execution-level'?: RequestedExecutionLevel
+    /**
+     * The path to the [application manifest](https://docs.microsoft.com/en-us/windows/win32/sbscs/application-manifests)
+     * XML that is to be embedded in the EXE.
+     */
+    'application-manifest'?: string
+  }
+}
+
+export = rcedit

package.json

@@ -3,10 +3,15 @@
   "version": "0.0.0-development",
   "description": "Node module to edit resources of exe",
   "main": "lib/rcedit.js",
+  "types": "lib/index.d.ts",
   "scripts": {
+    "docs:build": "node script/build-docs.js",
     "mocha": "mocha test/*.js",
-    "test": "npm run lint && npm run mocha",
-    "lint": "standard"
+    "test": "npm run lint && npm run tsd && npm run mocha",
+    "lint": "npm run lint:js && npm run lint:ts",
+    "lint:js": "standard",
+    "lint:ts": "ts-standard",
+    "tsd": "tsd"
   },
   "repository": {
     "type": "git",
@@ -26,6 +31,16 @@
     "rcinfo": "^0.1.3",
     "semantic-release": "^15.13.3",
     "standard": "^14.3.3",
-    "temp": "^0.9.0"
+    "temp": "^0.9.0",
+    "ts-standard": "^8.0.1",
+    "tsd": "^0.11.0",
+    "typedoc": "^0.17.0",
+    "typescript": "^4.1.2"
+  },
+  "resolutions": {
+    "**/semver": "< 7"
+  },
+  "tsd": {
+    "directory": "test"
   }
 }

script/build-docs.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict'
+
+const { Application } = require('typedoc')
+
+const config = {
+  excludeExternals: true,
+  excludePrivate: true,
+  excludeProtected: true,
+  includeDeclarations: true,
+  mode: 'file'
+}
+
+const replaceRef = /^refs\/(head|tag)s\//
+
+function gitRevisionFromGitHubRef () {
+  const githubRef = process.env.GITHUB_REF
+  if (githubRef) {
+    return githubRef.replace(replaceRef, '')
+  }
+}
+
+const gitRevision = process.argv[2] || gitRevisionFromGitHubRef()
+if (gitRevision) {
+  if (/^[0-9a-f]+$/i.test(gitRevision)) {
+    config.gitRevision = gitRevision
+  } else if (gitRevision.startsWith('v')) {
+    config.includeVersion = true
+  }
+}
+
+const app = new Application()
+app.bootstrap(config)
+
+const project = app.convert(['lib/index.d.ts'])
+if (project) {
+  app.generateDocs(project, 'typedoc')
+} else {
+  console.error('Could not generate API documentation from TypeScript definition!')
+  process.exit(1)
+}

test/index.test-d.ts

@@ -0,0 +1,9 @@
+import { expectError } from 'tsd'
+import * as rcedit from '..'
+
+await rcedit('foo.exe', {})
+await rcedit('foo.exe', { 'version-string': { CompanyName: 'FooCorp' }, 'requested-execution-level': 'requireAdministrator' })
+
+expectError(await rcedit('foo.exe', { 'version-string': { UnknownProperty: 'asdf' } }))
+
+expectError(await rcedit('foo.exe', { 'requested-execution-level': 'unknown' }))

tsconfig.eslint.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2018",
+    "outDir": "dist",
+    "lib": ["es2018"],
+    "sourceMap": true,
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true
+  },
+  "include": ["lib/index.d.ts", "test/index.test-d.ts"]
+}