Added Typescript flake documentation

Author: jared

flake-lang/build.nix

@@ -76,14 +76,11 @@
 
           typescriptFlake = lib.mkOption {
             type = lib.types.functionTo lib.types.attrs;
-            default = import ./flake-typescript.nix pkgs;
+            default = import ./typescript/flake-typescript.nix pkgs;
             readOnly = true;
-            description = lib.mdDoc ''
-              TODO(jaredponn): write down documentation here
-            '';
-            example = lib.mdDoc ''
-              TODO(jaredponn): write down an example here
-            '';
+            description = lib.mdDoc builtins.readFile ./typescript/description.md;
+            # TODO(jaredponn): add an example
+            # example = lib.mdDoc '' '';
           };
 
         };

flake-lang/typescript/description.md

@@ -0,0 +1,60 @@
+<!-- This file is used in `../build.nix`'s `description` for TS -->
+
+<!-- markdownlint-disable MD041 -->
+Creates a flake for a TypeScript project.
+
+Returns an attribute set of the form
+
+```nix
+{
+  devShells."${name}-typescript" = derivation { ... };
+  packages."${name}-typescript" = derivation { ... };
+  packages."${name}-typescript-tgz" = derivation { ... };
+  packages."${name}-typescript-node2nix" = derivation { ... };
+  checks."${name}-typescript-test" = derivation { ... };
+}
+```
+
+where
+
+- `packages."${name}-typescript"` contains the project with a
+  `node_modules/` provided by Nix (in the `configurePhase`), and
+   its `buildPhase` runs `npm run "$npmBuildScript"` (where `npmBuildScript` is
+   `build` by default).
+   Indeed, one can overlay the entire derivation (which contains
+   all its dependencies) to postprocess their project as they
+   see fit. For example, one may want to generate documentation
+   instead of building the project, by running:
+
+   ```nix
+   packages."${name}-typescript".overrideAttrs (_self: _super: {
+     npmBuildScript = "docs";
+     installPhase = 
+        ''
+            mv ./docs "$out"
+        '';
+    });
+    ```
+
+    where we assume that the `package.json` contains
+    `scripts.docs = <some-script>` which produces documentation
+    in the `./docs` folder.
+
+- `devShells."${name}-typescript-test"` provides a developer shell with
+  the environment variable `NODE_PATH` as the path to the
+  `node_modules/` produced by Nix, and the command
+  `${name}-npm-extra-dependencies` which copies the transitive
+  closure of `npmExtraDependencies` to the folder `./extra-dependencies`.
+
+  Moreover, the `shellHook` will:
+      - create a symbolic link named `node_modules` pointing to
+        `$NODE_PATH`; and
+      - executes `${name}-npm-extra-dependencies`.
+
+- `packages."${name}-typescript-tgz"` is `packages."${name}-typescript"` except
+  runs `npm pack` after the `buildPhase` to create a tarball of the project in
+  the directory `$out/tarballs/`.
+
+- `packages."${name}-typescript-test"` is `packages."${name}-typescript"`
+  except it runs `npm test` after the `buildPhase` succeeding only if `npm
+  test` succeeds.

flake-lang/flake-typescript.nix renamed to flake-lang/typescript/flake-typescript.nix

@@ -251,7 +251,7 @@ pkgs.lib.makeExtensible
 
             export NODE_PATH=${pkgs.lib.escapeShellArg "${npmPackage}/lib/node_modules/${srcWithNode2nixIfd.args.packageName}/node_modules"}
 
-            echo 'Removing existing `node_modules`, and creating a symbolic link to `$NODE_PATH` with name `node_modules`...'
+            echo 'Removing existing `node_modules`, and creating a symbolic link named `node_modules` pointing to `$NODE_PATH`'
             rm -rf node_modules
             ln -sf "$NODE_PATH" node_modules