Deno 2.1.7, Project Idioms

I’ve noticed a collection of file and code idioms I’ve been used in my recent Deno+TypeScript projects at work. I’ve captured them here as a future reference.

Project files

My project generally have the following files, these are derived from the CodeMeta file using CMTools.

codemeta.json
Primary source of project metadata, used to generate various files
CITATION.cff
used by GitHub for citations. version, dateModified, datePublished and releaseNotes
about.md
A project about page. This is generated based on the codemeta.json file.
README.md, README
A general read me describing the project and pointing to INSTALL.md, user_manual.md as appropriate
INSTALL.md
These are boiler plate description of how to install and compile the software
user_manual.md
This is an index document, a table of contents. It points to other document including Markdown versions of the man page(s).

For TypeScript projects I also include a following

version.ts
This hold project version information used in the TypeScript co-debase. It is generated from the codemeta.json via CMTools.
helptext.ts
This is where I place a function, fmtHelp(), for rendering response to the “help” command line option.

I’m currently ambivalent about “main.ts” file which is created by deno init. My ambivalent is that most of my projects wind up producing more than one program from a shared code base. a single “main.ts” doesn’t really fit that situation.

The command line tool will have a TypeScript with it’s name. Inside this file I’ll have a main function and use the Deno idiom if (import.meta.main) main(); to invoke it. I don’t generally put the command line TypeScript in my “mod.ts” file since it’s not going to work in a browser or be useful outside my specific project.

mod.ts
I usually re-export modules here that maybe useful outside my project (or in the web browser).
deps.ts
I use this if there are allot of files consistently being imported across the project, otherwise I skip it.

What I put in Main

I use the main function to define command line options, handle parameters such as data input, output and errors. It usually invokes a primary function modeled in the rest of the project code.

Here is an example Main for a simple “cat” like program.

  1. import { parseArgs } from "jsr:@std/cli";
  2. import { licenseText, releaseDate, releaseHash, version } from "./version.ts";
  3. import { fmtHelp, helpText } from "./helptext.ts";
  5. const appName = "mycat";
  7. async function main() {
  8.   const app = parseArgs(Deno.args, {
  9.     alias: {
  10.       help: "h",
  11.       license: "l",
  12.       version: "v",
  13.     },
  14.     default: {
  15.       help: false,
  16.       version: false,
  17.       license: false,
  18.     },
  19.   });
  20.   const args = app._;
  22.   if (app.help) {
  23.     console.log(fmtHelp(helpText, appName, version, releaseDate, releaseHash));
  24.     Deno.exit(0);
  25.   }
  26.   if (app.license) {
  27.     console.log(licenseText);
  28.     Deno.exit(0);
  29.   }
  30.   if (app.version) {
  31.     console.log(`${appName} ${version} ${releaseHash}`);
  32.     Deno.exit(0);
  33.   }
  35.   let input: Deno.FsFile | any = Deno.stdin;
  37.   // handle case of many file names
  38.   if (args.length > 1) {
  39.     for (const arg of args) {
  40.       input = await Deno.open(`${arg}`);
  41.       for await (const chunk of input.readable) {
  42.         const decoder = new TextDecoder();
  43.         console.log(decoder.decode(chunk));
  44.       }
  45.     }
  46.     Deno.exit(0);
  47.   }
  48.   if (args.length > 0) {
  49.     input = await Deno.open(Deno.args[0]);
  50.   }
  51.   for await (const chunk of input.readable) {
  52.     const decoder = new TextDecoder();
  53.     console.log(decoder.decode(chunk));
  54.   }
  55. }
  57. if (import.meta.main) main();

helptext.ts

The following is an example of the helptext.ts file for the demo mycat.ts.

  1. export function fmtHelp(
  2.   txt: string,
  3.   appName: string,
  4.   version: string,
  5.   releaseDate: string,
  6.   releaseHash: string,
  7. ): string {
  8.   return txt.replaceAll("{app_name}", appName).replaceAll("{version}", version)
  9.     .replaceAll("{release_date}", releaseDate).replaceAll(
  10.       "{release_hash}",
  11.       releaseHash,
  12.     );
  13. }
  15. export const helpText =
  16.   `%{app_name}(1) user manual | version {version} {release_hash}
  17. % R. S. Doiel
  18. % {release_date}
  20. # NAME
  22. {app_name}
  24. # SYNOPSIS
  26. {app_name} FILE [FILE ...] [OPTIONS]
  28. # DESCRIPTION
  30. {app_name} implements a "cat" like program.
  32. # OPTIONS
  34. Options come as the last parameter(s) on the command line.
  36. -h, --help
  37. : display help
  39. -v, --version
  40. : display version
  42. -l, --license
  43. : display license
  46. # EXAMPLES
  47. ~~~shell
  48. {app_name} README.md
  49. {app_name} README.md INSTALL.md
  50. ~~~
  51. `;

Generating version.ts

The version.ts is generated form two files, [codemeta.json] and [LICENSE] using the CMTools, cmt command.

  1. cmt codemeta.json veresion.ts