Skip to content
Skills Library
Programming · Building & coding

lean-ts-patterns

/lean-ts-patterns

Build lightweight TypeScript tools and libraries with few or no dependencies. Use when building a CLI, library, or utility; when deciding whether to add a dependency; or when replacing a package with a Node, Bun, or browser built-in. Covers the built-ins that replace common packages and unjs-style library design (one core primitive, factories, smart defaults). Triggers on: "build a CLI", "zero-dep", "remove dependencies", "do I need a library for", "fetch wrapper", "write a logger", "lightweight", "inline utility".

Repository
skills ↗
Licence
MIT
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Build lightweight TypeScript tools and libraries with few or no dependencies. Use when building a CLI, library, or utility; when deciding whether to add a dependency; or when replacing a package with a Node, Bun, or browser built-in. Covers the built-ins that replace common packages and unjs-style library design (one core primitive, factories, smart defaults). Triggers on: "build a CLI", "zero-dep", "remove dependencies", "do I need a library for", "fetch wrapper", "write a logger", "lightweight", "inline utility".

Triggers from the description

build a CLIzero-depremove dependenciesdo I need a library forfetch wrapperwrite a loggerlightweightinline utility
Original author description

Build lightweight TypeScript tools and libraries with few or no dependencies. Use when building a CLI, library, or utility; when deciding whether to add a dependency; or when replacing a package with a Node, Bun, or browser built-in. Covers the built-ins that replace common packages and unjs-style library design (one core primitive, factories, smart defaults). Triggers on: "build a CLI", "zero-dep", "remove dependencies", "do I need a library for", "fetch wrapper", "write a logger", "lightweight", "inline utility".

How it works

  1. Decision Order
  2. Built-ins That Replace Packages
  3. Library Design Patterns
  4. Snippets
  5. References
  6. Anti-Patterns
Original SKILL.md headings · 132 lines, 952 words
SKILL.md preview
---
name: lean-ts-patterns
description: >-
  Build lightweight TypeScript tools and libraries with few or no dependencies. Use when
  building a CLI, library, or utility; when deciding whether to add a dependency; or when
  replacing a package with a Node, Bun, or browser built-in. Covers the built-ins that replace
  common packages and unjs-style library design (one core primitive, factories, smart defaults).
  Triggers on: "build a CLI", "zero-dep", "remove dependencies", "do I need a library for",
  "fetch wrapper", "write a logger", "lightweight", "inline utility".
---

# Lean TypeScript

Ship less code you did not write, and less code you have to maintain. Library-design patterns come from studying unjs (citty, consola, ofetch, defu, scule, pathe) and antfu/taze.

## Decision Order

1. **Platform built-in.** Check the table below first.
2. **A dependency the project already has.** Use it the way the codebase already does.
3. **Inline it.** Only when it is under ~50 lines, you understand every line, and you add a test.
4. **A small, zero-dependency package.**

Do not inline crypto, auth, sanitizers, parsers for untrusted or quirky formats (YAML, CSV
quoting, HTML), date and timezone math, or semver ranges. A maintained library beats your
edge-case bugs there.

## Built-ins That Replace Packages

Assumes Node 22+ (current LTS lines: 22, 24). Bun and Deno implement most `node:` APIs; check
before relying on the newest ones.

| Need | Built-in | Instead of |
|---|---|---|
| CLI args | `util.parseArgs` (`allowNegative` for `--no-x`, Node 22.4+) | commander, yargs, minimist |
| Terminal colors | `util.styleText` (honors TTY, `NO_COLOR`, `FORCE_COLOR`) | chalk, picocolors |
| Strip ANSI | `util.stripVTControlCharacters` | strip-ansi |
| HTTP | `fetch` + `AbortSignal.timeout()` / `AbortSignal.any()` | axios, node-fetch |
| `.env` files | `node --env-file=.env`, `process.loadEnvFile()`, `util.parseEnv()` | dotenv |
| Globbing | `fs.promises.glob` (stable in Node 24, 22.17) | glob, fast-glob |
| Run `.ts` directly | `node script.ts` (type stripping; erasable syntax only) | ts-node, tsx for simple scripts |
| Test runner | `node:test` + `node:assert/strict` | jest, mocha for libraries and CLIs |
| Watch mode | `node --watch` | nodemon |
| Deep clone | `structuredClone()` | lodash.clonedeep |
| Deep equality | `util.isDeepStrictEqual()` | fast-deep-equal |
| Group by | `Object.groupBy()`, `Map.groupBy()` | lodash.groupby |
| Copying array ops | `toSorted`, `toReversed`, `toSpliced`, `with` | spread-then-mutate |
| Set algebra | `union`, `intersection`, `difference` (ES2025) | lodash set helpers |
| Lazy iteration | Iterator helpers: `.map`, `.filter`, `.take`, `.toArray` (ES2025) | itertools packages |
| Deferred promise | `Promise.withResolvers()` | p-defer |
| UUID v4 | `crypto.randomUUID()` | uuid |
| Escape for RegExp | `RegExp.escape()` (ES2025) | escape-string-regexp |

## Library Design Patterns

- **One core primitive, thin wrappers.** scule's `splitByCase()` powers every case converter; pathe's `normalizeWindowsPath()` sits under every path function; consola's levels all call one log function. Fix a bug once, every wrapper gets it.
- **Factory with `.create(defaults)`.** `createFetch()`, `createConsola()`: a closure captures config and returns a callable instance that can spawn preconfigured children. See the `typescript-best-practices` skill for factories versus classes.
- **`define*` identity helpers.** `defineCommand`, `defineConfig` return their argument; a `const` type parameter keeps literal types. See the `typescript-best-practices` skill.
- **Smart defaults, explicit escape hatches.** ofetch retries GET once and mutations zero times; consola picks a fancy reporter in a TTY and plain output in CI; defu treats `null`/`undefined` as "not set".
- **Hooks as options.** `{ onRequest, onResponse, onError }` beat a `.use()` middleware chain for small libraries.
- **Lazy values.** `Resolvable<T> = T | Promise<T> | (() => T | Promise<T>)` lets subcommands and config load via dynamic `import()` only when used.
- **Types mirror runtime.** If runtime code switches on `arg.type`, the types branch on the same discriminant.
- **Small public surface.** One entry point; `_`-prefixed internal files are never exported.

## Snippets

Tested on Node 26.

### CLI args and colors

```ts
import { parseArgs, styleText } from "node:util";

const { values, positionals } = parseArgs({
  allowPositionals: true,
  allowNegative: true, // --no-color sets color: false
  options: {
    out: { type: "string", short: "o", default: "dist" },
    color: { type: "boolean", default: true },
    verbose: { type: "boolean", short: "v", multiple: true }, // -vv → [true, true]
  },
});

// Plain text when stderr is not a TTY or NO_COLOR is set
console.error(styleText(["bold", "red"], "error:", { stream: process.stderr }), "build failed");
```

### fetch with timeout and retries

```ts
const RETRYABLE = new Set([408, 425, 429, 500, 502, 503, 504]);

class HttpError extends Error {
  readonly response: Response;
  constructor(response: Response) {
    super(`${response.status} ${response.statusText}: ${response.url}`);
    this.response = response;
  }
}

async function fetchJson<T>(
  url: string | URL,
  { timeout = 10_000, retries, ...init }: RequestInit & { timeout?: number; retries?: number } = {},
): Promise<T> {
  // Only retry idempotent requests unless the caller opts in.
  const maxRetries = retries ?? (!init.method || init.method === "GET" ? 2 : 0);
  for (let attempt = 0; ; attempt++) {
    const timeoutSignal = AbortSignal.timeout(timeout);
    const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
    try {
      const res = await fetch(url, { ...init, signal });
      if (res.ok) return (await res.json()) as T;
      throw new HttpError(res);
    } catch (err) {
      const retryable = err instanceof HttpError
        ? RETRYABLE.has(err.response.status)
        : !init.signal?.aborted; // network error or our timeout, not a caller abort
      if (!retryable || attempt >= maxRetries) throw err;
    }
    await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
  }
}
```

## References

| Need | Reference |
|---|---|
| Typed CLI args, lazy subcommands, help text, `runMain` | [cli-patterns.md](references/cli-patterns.md) |
| Fetch factory, interceptor hooks, body and response handling | [fetch-patterns.md](references/fetch-patterns.md) |
| Logger with levels, reporters, throttling, scoped tags | [logging-patterns.md](references/logging-patterns.md) |
| Deep defaults (defu), case conversion (scule), paths (pathe), shared queues, file cache | [data-utils.md](references/data-utils.md) |
| Type tricks from these libraries (`const` generics, key remapping, module augmentation) | [typescript-tricks.md](references/typescript-tricks.md) |

## Anti-Patterns

- Adding a package for something in the table above.
- Inlining security, parsing, or date code to avoid a dependency.
- Copy-pasting a utility without a test.
- Adding "flexibility" or options nobody asked for.
- A class hierarchy for configuration when a factory closure does the job.
- Exporting internals from a barrel file; keep the public surface to one entry.
Files in this package (6)
  • SKILL.md 7 KB
  • references/cli-patterns.md 7 KB
  • references/data-utils.md 9 KB
  • references/fetch-patterns.md 8 KB
  • references/logging-patterns.md 6 KB
  • references/typescript-tricks.md 9 KB

Versions

RepositoryScoreLicence
This page · caidanw/skills100MIT
caidanw/skills100MIT

Database snapshot: 13.11.2026 · package version c91c9435df34 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100bun
    Assists with using Bun as an all-in-one JavaScript/TypeScript runtime, package manager, bundler, and test runner. Use when building HTTP servers, managing packages, running tests, or migrating from Node.js. Trigger words: bun, bun serve, bun install, bun test, bun build,…
  • 100bun-build
    Bun build: bundle or compile JS/TS to production bundle or standalone binary. Use when the user wants to bundle, compile, or build for browser/bun/node target.
  • 85bun
    Bun runtime patterns. Use when running bun commands, working with package.json/bun.lock, writing TypeScript scripts under Bun, or developing Claude Code plugins.
  • 100ts-runtime-bun
    Use when running TypeScript on Bun — bunfig.toml, bun test, Bun.build/--compile, or Bun workspaces. Not for Node.js runtime setup (ts-runtime-node).
  • 100update
    Smart bulk update of npm/pnpm/yarn/bun dependencies. Skips frameworks and packages with their own upgrade CLI, and aligns @types/node with the latest Node major installed locally. Use whenever the user wants to bump dependencies, refresh outdated packages, run a dependency…
  • 90bun-script
    Use when writing a TypeScript script with Bun. Covers the template, conventions, and required patterns.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.