# typescript-bits

> Production-ready TypeScript utility primitives. Atom, Rich JSON, Queue, Reset, Result, Retry, Safe, Types — zero-dependency, tree-shakeable, fully typed.

## Docs

- [Introduction](/docs/introduction/): Overview of the typescript-bits library and its design principles
- [Installation](/docs/installation/): Install via package manager, CLI source install, or copy source

## Skills

- [Api Design Guidelines](skills/api-design-guidelines/): Guidelines for designing public TypeScript APIs — surface area, types, options objects, exports, tree-shaking, and backwards compatibility
- [Async Patterns](skills/async-patterns/): Production-ready async patterns — concurrency control, cancellation, retry, streams, queues, error handling, and anti-patterns for robust asynchronous TypeScript
- [Caching Patterns](skills/caching-patterns/): In-memory caching patterns for TypeScript — memoization, async deduplication, TTL, LRU, stale-while-revalidate, and invalidation strategies
- [Complexity Principles](skills/complexity-principles/): Big O notation, asymptotic analysis, time and space complexity, and algorithmic efficiency principles for reasoning about performance at scale
- [Composition Patterns](skills/composition-patterns/): Concrete patterns for composing behavior from small units — function composition, middleware, decorators, mixins, monad chaining, builders, plugin systems, strategy composition, and type-level composition for TypeScript
- [Error Handling Patterns](skills/error-handling-patterns/): Type-safe error handling in TypeScript — Result type, error-as-value philosophy, typed hierarchies, Error.cause chaining, exhaustive matching, and Result combinators
- [Esm Best Practices](skills/esm-best-practices/): ESM-specific patterns for TypeScript and Node.js — file extensions, import.meta, dynamic imports, dual packages, and module resolution modes
- [Http Rest Guidelines](skills/http-rest-guidelines/): Guidelines for designing and implementing HTTP REST APIs — resource naming, HTTP semantics, status codes, error responses, pagination, and versioning
- [Memory Management Guidelines](skills/memory-management-guidelines/): Production memory management patterns for Node.js/TypeScript — GC fundamentals, leak detection, weak references, caching strategies, object pooling, stream backpressure, and closure memory for V8
- [Monorepo Guidelines](skills/monorepo-guidelines/): pnpm workspace monorepo patterns — workspace setup, package anatomy, TypeScript project references, build ordering, versioning, and publishing
- [Nextjs Best Practices](skills/nextjs-best-practices/): Production-ready Next.js App Router patterns — server components, data fetching, streaming, server actions, caching, routing architecture, middleware, error handling, and performance for modern Next.js applications
- [Nodejs Best Practices](skills/nodejs-best-practices/): Production-ready Node.js patterns — ESM, native test runner, built-in APIs, async control flow, process management, and security for modern Node.js applications
- [Playwright Best Practices](skills/playwright-best-practices/): Production-ready Playwright patterns — config, locators, assertions, page objects, network mocking, and CI setup for reliable E2E tests.
- [React Best Practices](skills/react-best-practices/): Production-ready React best practices — component architecture, React 19 compiler patterns, useEffect discipline, state management, rendering patterns, performance, testing, and code organization for modern React applications
- [Security Guidelines](skills/security-guidelines/): Security guidelines for TypeScript and Node.js — input validation, injection prevention, authentication hardening, secrets management, HTTP security headers, and common vulnerability patterns
- [Software Principles Guidelines](skills/software-principles-guidelines/): Core software engineering principles and guidelines — SOLID, DRY, KISS, YAGNI, cohesion, coupling, and structural design patterns for maintainable systems
- [Testing Guidelines](skills/testing-guidelines/): Node.js native test runner patterns — assertions, test structure, async tests, isolation, and mocking with node:test and node:assert/strict.
- [Type System Patterns](skills/type-system-patterns/): Advanced TypeScript type system patterns — branded types, discriminated unions, conditional types, mapped types, template literals, type predicates, and variance
- [Typescript Best Practices](skills/typescript-best-practices/): Production-ready TypeScript best practices — tsconfig, type patterns, generics, error handling, and code organization for strict, maintainable codebases
- [Zod Best Practices](skills/zod-best-practices/): Production-ready Zod 4 patterns — schema composition, parsing, error handling, transforms, and performance for type-safe runtime validation

## Modules

- [atom](atom/): A typed reactive container that holds a single value: call `get()` to read it, `set()` to update it and synchronously notify all subscribers, and `subscribe()` to register a listener — receiving an unsubscribe handle in return. `Atom.fn()` extends this model to plain functions, wrapping any callable so that every invocation fans out to subscribers, making it easy to build observable event emitters without a class. Zero dependencies.
- [json](json/): Replacer for use with native `JSON.stringify`. Encodes special types (Map, Set, Date, etc.).
- [queue](queue/): A typed FIFO queue built around a lifecycle event system. Subscribe to `push`, `pop`, `drain`, `empty`, `idle`, and `error` events via `on()`, which returns an unsubscribe handle. Use `drain()` to pull all items at once or `front()` to peek without removing. Designed for ordered processing pipelines where visibility into queue state matters.
- [reset](reset/): A collection of global ambient type augmentations that close long-standing gaps in TypeScript's standard library. It patches `Array.isArray` narrowing for readonly arrays, changes `JSON.parse` and `fetch` `Body.json()` to return `unknown` instead of `any`, and tightens callback inference for `Array.prototype.filter`, `Array.prototype.map`, and `Set`. Import once at your entry point and the stricter types apply project-wide with zero runtime cost.
  - [reset/array](reset/array/): Augment `Array.isArray` to narrow to `unknown[]`.
  - [reset/fetch](reset/fetch/): Augment `Body.json()` to return `Promise<unknown>` instead of `Promise<any>`.
  - [reset/filter](reset/filter/): Augment `Array.filter` return type from `any[]` to the narrowed type.
  - [reset/json](reset/json/): Augment `JSON.parse` to return `unknown` instead of `any`.
  - [reset/map](reset/map/): Augment `Array.map` return type to `U[]` (instead of `any[]`).
  - [reset/set](reset/set/): Augment `Set` constructor and `forEach` with better types.
- [result](result/): Rust-inspired `Result<T, E>` type with `Ok` and `Err` variants that replaces throw/catch with explicit return types, making errors part of the function signature. Ships with `ok()`, `err()`, `isOk()`, `isErr()`, `unwrap()`, and `unwrapOr()` utilities for ergonomic handling.
- [retry](retry/): Retries any sync or async operation up to a configurable number of attempts, with optional fixed or exponentially increasing delays between each try. A `transform` option lets you map raw thrown values into typed errors, and a single overloaded `retry()` function handles both plain functions and Promises transparently.
- [safe](safe/): Wraps any throwable sync or async operation and returns a `Result` instead of throwing. Smart overload detection handles raw Promises, async functions, and sync functions uniformly through a single `attempt` entry point. An optional `transform` parameter lets you shape caught errors into typed `Err` values before they reach the caller.
- [types](types/): Compile-time numeric range utilities: `Enumerate<N>` produces a union of `0` through `N-1`, and `Range<F, T>` produces `F` through `T-1`. Useful for constraining numeric literals in APIs — port numbers, indices, pagination limits — without any runtime overhead. Both are pure type-level constructs; zero runtime code is emitted.

## Resources

- [Terms of Service](/terms-of-service/)
- [Contact](/contact/)
- [GitHub](https://github.com/m10rten/typescript-bits)