feat: add writeJson method

.eslintignore

@@ -11,4 +11,9 @@ coverage
 .jest
 
 src/__tests__/__fixtures__/**
-*.md
+temp/**
+tsdoc-metadata.json
+
+docs/api/*.md
+docs/etc/*.md
+CHANGELOG.md

.gitignore

@@ -4,3 +4,8 @@ node_modules
 dist
 coverage
 .jest
+
+src/__tests__/__fixtures__/.ignored/
+tsdoc-metadata.json
+temp/**
+temp/

api-extractor.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/json.macro.d.ts",
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/docs/etc/"
+  },
+  "docModel": {
+    "enabled": true
+  },
+  "dtsRollup": {
+    "enabled": false
+  },
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

json.macro.d.ts

@@ -7,6 +7,8 @@ import { PackageJson, SemanticVersion, TsConfigJson } from './types';
  *
  * If the file can't be resolved the build will fail.
  *
+ * @remarks
+ *
  * For the following json file: `./my-json.json`
  *
  * ```json
@@ -86,11 +88,69 @@ import { PackageJson, SemanticVersion, TsConfigJson } from './types';
  * const value2 = true;
  * ```
  */
-export function loadJson(filePath: string, path?: string): any;
+export function loadJson<Type>(filePath: string, path?: string): Type;
 
 /**
- * Load all the json files matching the provided glob patterns. If no files
- * match then an empty array is returned.
+ * Write a json object to a relative file path.
+ *
+ * @remarks
+ *
+ * Sometimes it's easier to create an object that needs to follow certain type
+ * rules in typescript and then export it to a json object. How to do this
+ * though?
+ *
+ * This method wraps the json object you create (statically and not dynamically)
+ * and will output to the provided filePath at build time.
+ *
+ * @example
+ *
+ * ```ts
+ * import { writeJson } from 'json.macro';
+ *
+ * type Config = {config: boolean, type: 'string' | 'array' };
+ * const json = writeJson<Config>({config: true, type: 'array'}, './config.json);
+ * ```
+ *
+ * Compiles to
+ * ↓ ↓ ↓ ↓ ↓ ↓
+ *
+ * ```js
+ * const json = { config: true, type: 'array' }
+ * ```
+ *
+ * And `./config.json` is written as.
+ *
+ * ```json
+ * {
+ *   "config": true,
+ *   "type": "array"
+ * }
+ * ```
+ *
+ * One thing to be aware of is that this method only supports inline or
+ * statically inferrable values. You can't use any dynamic values, like return
+ * values from a function call.
+ *
+ * ```ts
+ * import { writeJson } from 'json.macro';
+ *
+ * const json = { custom: 'custom' };
+ * const createJson = () => json;
+ *
+ * writeJson({ a: true }, './file.json'); // Static ✅
+ * writeJson(custom, './file.json'); // Static ✅
+ *
+ * writeJson(createJson(), './file.json'); // Dynamic ❌
+ * ```
+ */
+export function writeJson<Type>(json: Type, filePath: string): Type;
+
+/**
+ * Load all the json files matching the provided glob patterns.
+ *
+ * @remarks
+ *
+ * If no files match then an empty array is returned.
  *
  * @example
  *
@@ -116,11 +176,13 @@ export function loadJson(filePath: string, path?: string): any;
  * const jsonArray: Array<{ custom: string}> = loadJsonFiles('*.json');
  * ```
  */
-export function loadJsonFiles(glob: string, ...globs: string[]): any[];
+export function loadJsonFiles<Type>(glob: string, ...globs: string[]): Type[];
 
 /**
  * Load the nearest parent `package.json` file.
  *
+ * @remarks
+ *
  * You can also provide a key property which will load the property
  * corresponding to the key from the nearest `package.json`.
  *
@@ -151,6 +213,8 @@ export function loadPackageJson<Key extends string>(key: Key): PackageJson[Key];
 /**
  * Load the nearest parent `tsconfig.json` file.
  *
+ * @remarks
+ *
  * You can customise the name of the file searched for.
  *
  * @example
@@ -180,7 +244,9 @@ export function loadTsConfigJson(fileName: string): TsConfigJson;
 /**
  * Get the semver compatible version from the package.json file.
  *
- * This will throw a built error if the semver version in your package.json is
+ * @remarks
+ *
+ * This will throw a build error if the semver version in your package.json is
  * not valid.
  *
  * @example

package.json

@@ -35,14 +35,17 @@
     "src",
     "json.macro.d.ts",
     "types.d.ts",
-    "dist"
+    "dist",
+    "tsdoc-metadata.json"
   ],
   "scripts": {
+    "_fix:api": "node scripts/generate-api-docs.js",
+    "_lint:api": "node scripts/generate-api-docs.js check",
     "build": "run-p build:*",
     "build:declaration": "tsc -p ./tsconfig.build.json",
     "build:js": "preconstruct build",
     "checks": "run-s typecheck lint test",
-    "fix": "run-s fix:prettier fix:es",
+    "fix": "run-s fix:*",
     "fix:es": "yarn lint:es --fix",
     "fix:prettier": "yarn run:prettier --write",
     "lint": "run-s lint:*",
@@ -62,7 +65,7 @@
   },
   "prettier": {
     "plugins": [
-      "prettier-plugin-packagejson"
+      "./node_modules/prettier-plugin-packagejson"
     ],
     "printWidth": 80,
     "semi": true,
@@ -79,6 +82,7 @@
     "@babel/parser": "^7.9.6",
     "@babel/runtime": "^7.9.6",
     "@babel/types": "^7.9.6",
+    "@sindresorhus/is": "^2.1.1",
     "@types/babel-plugin-macros": "^2.8.1",
     "@types/lodash.get": "^4.4.6",
     "@types/semver": "^7.1.0",
@@ -102,11 +106,14 @@
     "@babel/preset-react": "^7.9.4",
     "@babel/preset-typescript": "^7.9.0",
     "@jest/types": "^26.0.1",
+    "@microsoft/api-documenter": "^7.7.19",
+    "@microsoft/api-extractor": "^7.7.13",
     "@preconstruct/cli": "^1.1.14",
     "@semantic-release/changelog": "^5.0.1",
     "@semantic-release/git": "^9.0.0",
     "@sindresorhus/tsconfig": "0.7.0",
     "@types/jest": "^25.2.1",
+    "@types/rimraf": "^3.0.0",
     "@typescript-eslint/eslint-plugin": "^2.30.0",
     "@typescript-eslint/parser": "^2.30.0",
     "babel-jest": "^26.0.0",
@@ -128,8 +135,9 @@
     "npm-run-all": "^4.1.5",
     "prettier": "^2.0.5",
     "prettier-plugin-packagejson": "^2.2.3",
+    "rimraf": "^3.0.2",
     "semantic-release": "^17.0.7",
-    "typescript": "^3.8.3"
+    "typescript": "^3.9.1-rc"
   },
   "peerDependencies": {
     "babel-plugin-macros": "^2.8.0"