typescript

Files (1)

• SKILL.md

SKILL.md (first lines)

# TypeScript / JavaScript Language Idioms

Work _with_ the language. Embrace its asynchronous nature, its structural type system, and its functional roots. Fight the urge to write Java-in-TypeScript.

---

## Core Philosophy

- **Immutability by default** — `const` everything, spread to copy, never mutate in place
- **Type safety without ceremony** — let inference work, annotate at boundaries
- **Composition over inheritance** — functions, modules, and interfaces beat class hierarchies
- **Explicit over implicit** — no coercion tricks, no hidden state, no magic

---

## References and Variables

### The Rules

| Keyword | Usage                                 | Rationale                                    |
| :------ | :------------------------------------ | :------------------------------------------- |
| `const` | Default for all bindings              | Prevents reassignment, signals intent        |
| `let`   | Only when reassignment is unavoidable | Loops, accumulators, state machines          |
| `var`   | **Prohibited**                        | Function-scoped, hoists, leaks out of blocks |

### Destructuring and Spread

Use destructuring to extract what you need. Use spread to copy without mutation:

```typescript
// ✅ Destructure at the call site
const { name, age } = getUser();

// ✅ Shallow-copy with spread — never mutate the original
const updated = { ...config, timeout: 5000 };
const extended = [...items, newItem];

// ❌ Mutating the original
config.timeout = 5000;
items.push(newItem);
```

Use `Object.hasOwn(obj, key)` instead of `obj.hasOwnProperty(key)` — the latter can be shadowed.

---

## Functions

### Arrow Functions

Use arrow functions for callbacks and short expressions. They preserve lexical `this`:

```typescript
// ✅ Arrow for callbacks
const sorted = items.sort((a, b) => a.name.localeCompare(b.name));

// ✅ Arrow for inline transforms
const names = users.map((u) => u.name);

// ❌ Legacy — don't use `function` for callbacks
const names = users.map(function (u) {
  return u.name;
});
```

Use `function` declarations for top-level named functions (they hoist and have clear stack traces).

### Options Objects

When a function's parameter list becomes unwieldy, use a single options object:

```typescript
// ❌ Positional parameter overload
function createServer(
  port: number,
  host: string,
  ssl: boolean,
  timeout: number,
);

// ✅ Options object — extensible, self-documenting
interface ServerOptions {
  port: number;
  host?: string;
  ssl?: boolean;
  timeout?: number;
}
function createServer(options: ServerOptions);
```

### Rest Parameters

Use rest syntax. The `arguments` object is prohibited:

```typescript
// ✅ Rest gives you a real Array
function log(level: string, ...messages: string[]) {}

// ❌ arguments is not a real Array and has no type safety
function log() {
  console.log(arguments);
}
```

### Pure Functions

Prefer functions that return values based solely on inputs. Reserve side effects for explicit boundaries (I/O, event handlers, logging).

### Functional Iterators

Use `map`, `filter`, `reduce` to build declarative pipelines that produce new data:

```typescript
// ✅ Declarative pipeline — new array, no mutation
const active = users.filter((u) => u.isActive).map((u) => u.email);

// ❌ Imperative mutation
const active: string[] = [];
users.forEach((u) => {

From nrdxp/predicate, MIT.

More from nrdxp/predicate