README

Author: uhyo

README.md

@@ -0,0 +1,41 @@
+# better-typescript-lib
+
+An alternative TypeScript standard library with better type definitions.
+
+## The Problem
+
+While it is well known that TypeScript is not _very_ type safe due to the existence of `any` and other pitfalls, TypeScript's built-in type definitions are also to blame for that unsafety. For example, it is handy but very unsafe that the return type of `JSON.parse` is `any`.
+
+Ideally TypeScript's built-in type definitions should have been better in view of type safety, but it is nearly impossible if we take backward compatibility into account.
+
+## The Solution
+
+This package provides an alternative type definitions which are safer than TypeScript's built-in ones. With this package, TypeScript users obtain less chance of unexpectedly getting `any` values. This package also includes other improved, stricter type definitions.
+
+## Usage
+
+### Install
+
+```sh
+npm i -D better-typescript-lib
+```
+
+### Remove built-in library from tsconfig.json
+
+```diff
+- "lib": ["es5", "dom"]
++ "noLib": true
+```
+
+### Include better-typescript-lib
+
+Include better-typescript-lib with triple-slash directives from the entry point of your code. Note that these directives must be placed at the very top of a `.ts` file.
+
+```ts
+/// <reference path="./node_modules/better-typescript-lib/lib.es5.d.ts" />
+/// <reference path="./node_modules/better-typescript-lib/lib.dom.d.ts" />
+```
+
+## Contributing
+
+Welcome

build/build.ts

@@ -1,4 +1,4 @@
-import { mkdir, readdir, writeFile } from "fs/promises";
+import { mkdir, readdir, rm, symlink, writeFile } from "fs/promises";
 import path from "path";
 import ts from "typescript";
 import { replacement } from "./replacement";
@@ -8,9 +8,14 @@ const distDir = path.join(projectDir, "dist", "lib");
 const tsDir = path.join(projectDir, "TypeScript");
 
 async function main() {
+  await rm(distDir, {
+    force: true,
+    recursive: true,
+  });
   await mkdir(distDir, {
     recursive: true,
   });
+  await symlink(path.join(projectDir, "lib"), path.join(distDir, "better"));
 
   // copy TypeScript lib files
   const libs = await readdir(path.join(tsDir, "lib"));
@@ -27,7 +32,7 @@ async function main() {
       continue;
     }
     const repl = replacement.get(libFile);
-    let result = repl ? `/// <reference path="../../lib/${libFile}" />\n` : "";
+    let result = repl ? `/// <reference path="./better/${libFile}" />\n` : "";
     if (!repl) {
       for (const statement of file.statements) {
         result += statement.getFullText(file);

build/package.ts

@@ -3,6 +3,7 @@ import path from "path";
 
 const projectDir = process.env.PROJECT || process.cwd();
 const libDir = path.join(projectDir, "dist", "lib");
+const betterDir = path.join(projectDir, "lib");
 const templateDir = path.join(projectDir, "package-template");
 const packageDir = path.join(projectDir, "dist-package");
 
@@ -11,24 +12,34 @@ async function main() {
     force: true,
     recursive: true,
   });
-  await mkdir(packageDir, {
+  await mkdir(path.join(packageDir, "better"), {
     recursive: true,
   });
 
   // copy package template
   // copy lib files
   const files = (await readdir(libDir))
+    .filter((libFile) => /\.d\.ts$/.test(libFile))
     .map((libFile) => path.join(libDir, libFile))
     .concat(
       (await readdir(templateDir)).map((file) => path.join(templateDir, file))
     );
   await Promise.all(
-    files.map(async (libFile) => {
-      await writeFile(
-        path.join(packageDir, path.basename(libFile)),
-        await readFile(libFile)
-      );
-    })
+    files
+      .map(async (libFile) => {
+        await writeFile(
+          path.join(packageDir, path.basename(libFile)),
+          await readFile(libFile)
+        );
+      })
+      .concat(
+        (await readdir(betterDir)).map(async (libFile) => {
+          await writeFile(
+            path.join(packageDir, "better", libFile),
+            await readFile(path.join(betterDir, libFile))
+          );
+        })
+      )
   );
 }