TypeScript Console Application Framework (tscaf)

tscaf helps you set up a TypeScript console application in under 2 minutes. It provides built-in developer scripts, a command registration system, optional utilities (fetch wrapper, persistent/session storage), and a simple global environment object.

Features

• Quick, minimal boilerplate to start a CLI in TypeScript
• Built-in scripts: tscaf dev, tscaf build
• Command registration API and command index generation
• Optional helpers: FetchWrapper, PersistentStorage, SessionStorage
• GLOBAL object with environment info

1. Setting up the app

Create the entry file src/index.ts and call runApp():

import { runApp } from "tscaf";

runApp({
  afterLoad: async () => {
    console.log("Application loaded!");
  },
  showStartupMessage: true,
  unregisterDefaultCommands: "all" // or an array of default commands
});

runApp params

export interface AppProps {
  afterLoad?: () => void | Promise<void>;
  showStartupMessage?: boolean;
  unregisterDefaultCommands?: "all" | DefaultCommand[];
  customCompleter?: Completer | AsyncCompleter;
}

Use afterLoad for any async initialization, toggle the startup message with showStartupMessage, or remove default commands with unregisterDefaultCommands. Use the customCompleter prop to pass your own command completer.

2. Creating commands

Register commands by pushing them to the registry:

export const registerCommand = (command: Command) => registry.push(command);

Command interface

interface Command {
  name: string;
  execute: (args: string[]) => void | Promise<void>;
  group: string;
  description?: string;
  aliases?: string[];
  usage?: string;
  specialConfig?: CommandSpecialConfig;
  argValidator?: (args: string[]) => boolean | string;
}

Example command (declarative)

src/commands/hello.ts

import { registerCommand } from "tscaf";

registerCommand({
  name: "hello",
  group: "general",
  description: "Say hello",
  execute: () => {
    console.log("Hello World!");
  }
});

Command index generation

You can either register commands manually as above or let the framework create an index for you:

npx tscaf generate-command-index

This scans directories defined in your tscaf.commandsDirs config and builds the index automatically.

Example package.json

{
  "name": "your-project-name",
  "version": "1.0.0",
  "main": "dist/index.js",
  "license": "MIT",
  "scripts": {
    "dev": "tscaf dev",
    "build:generate": "tscaf generate-command-index",
    "build:perform": "tscaf build",
    "build": "npm run build:generate && npm run build:perform"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "ts-node": "^10.9.2",
    "typescript": "^5.0.0"
  },
  "dependencies": {
    "tscaf": "^1.0.17"
  },
  "tscaf": {
    "commandsDirs": [
      "src/commands"
    ]
  }
}

tsconfig.json required for tscaf build

To use the shipped tscaf build command, include a tsconfig.json like this:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "dist",
    "esModuleInterop": true,
    "strict": true
  }
}

If you prefer other packagers (pkg, nexe, etc.) you can build with those instead — tscaf build expects a CommonJS/ES2020 compatible output.

3. Other features

FetchWrapper (optional)

A small convenience wrapper around fetch for common request patterns: This is entirely optional — use native fetch if you prefer.

Persistent & Session Storage

Work with storage objects similar to a browser API:

import { PersistentStorage, SessionStorage } from "tscaf";

PersistentStorage.set("token", "abc123");
const token = PersistentStorage.get("token");

SessionStorage.set("step", "1");

These are lightweight helpers that persist to the filesystem (or memory, depending on configuration).

API (HTTP Server)

tscaf allows you to easily expose all registered commands via a HTTP API. You can use the HTTPServer object.

interface HTTPServer {
  start: (port?: number) => void,
  reload: () => void,
  stop: () => void,
  isRunning: () => boolean,
  getRoutes: () => {
    method: string;
    path: string;
    externalCalls: number;
  }[],
  getPort: () => void | null
}

You can start and stop the HTTP Server and reload the routes. There are also some information methods. The server will not be started automatically.

To use the API, call the command at http://localhost:3000/cmd/<command> with a body of

{
  "args": ["<arg1>", "..."]
}

The API will respond with an object of

  {
    "ok": true,
    "result": "<If your command returns something, it will be returned here aswell>",
    "logs": [
        {
            "type": "log",
            "msg": [
                "<Whatever you log using console.log()>"
            ]
        },
        {
            "type": "log",
            "msg": [
                "<Second usage of console.log()...>"
            ]
        },
        {
            "type": "error",
            "msg": [
                "<Whatever you log using console.error()>"
            ]
        },
    ]
  }

Tips & notes

• Keep commands small and focused; use argValidator to validate CLI args and return either true or a string message for the user.
• Use generate-command-index before building to ensure all commands are bundled.
• tscaf dev runs your project directly (with ts-node or similar) for fast iteration.