@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/skills/lit-code/references/typescript/bootstrap.md

@@ -0,0 +1,199 @@
+# Bootstrap — Runtime, Package Manager, Tooling
+
+When starting a new TypeScript project (or scripting against the world), the choice of runtime, package manager, framework, and toolchain compounds. The wrong default at minute zero costs hours every week. The right defaults for 2026:
+
+## Runtime decision tree
+
+```
+Is this a CLI / script / single-binary tool?
+└─ Yes → Bun (single executable, hot reload, native TS)
+        Use `bun run script.ts` directly. No build step.
+
+Is this a backend service?
+├─ Edge (Cloudflare Workers / Vercel / Deno Deploy) → match the platform
+├─ Bun-supported runtime          → Bun + Hono
+├─ Need Node-only deps (sharp, native modules without Bun support) → Node + Hono
+└─ Otherwise                       → Bun + Hono
+
+Is this a frontend?
+└─ Vite (regardless of framework). Bun for the package manager.
+
+Is this a library to publish to npm?
+└─ tsdown (or unbuild). Targets Node 20+. Use pnpm for monorepo workspaces.
+```
+
+## Bun is the default runtime
+
+Use Bun for:
+- Scripts and CLIs (`bun run` is faster than `tsx` and `ts-node`)
+- New backends (Hono runs natively, hot reload via `bun --hot`)
+- Test runner (`bun test` is built-in, faster than vitest for small suites)
+- Package manager (`bun install` is faster than `pnpm` and far faster than `npm`)
+
+Use Node when:
+- A dependency uses native modules Bun can't load (rare in 2026; check the dep's release notes)
+- Production target is a Node-specific platform (some serverless platforms don't run Bun yet)
+- You're contributing to a Node-only project
+
+`bunx` replaces `npx`. `bun create` scaffolds projects.
+
+## Package manager — pnpm > npm
+
+If you must use Node, use pnpm. NEVER npm except in legacy projects you don't control.
+
+Why pnpm:
+- Content-addressable store: 10x less disk usage on a machine with many projects
+- Strict node_modules layout: phantom dependencies fail at install time, not at runtime
+- Workspaces are first-class
+- Significantly faster than npm
+
+Why not yarn:
+- Yarn classic is unmaintained
+- Yarn berry's "PnP" mode breaks with editor tooling more often than it should
+- pnpm has caught up on every yarn berry feature people actually use
+
+Why not npm:
+- Slowest of the three
+- No proper workspace story until very recently
+- Phantom dependencies allowed by default
+
+```bash
+# Convert npm/yarn → pnpm
+pnpm import   # reads package-lock.json or yarn.lock and produces pnpm-lock.yaml
+rm -rf node_modules package-lock.json yarn.lock
+pnpm install
+```
+
+## Backend framework — Hono
+
+Use Hono for any new HTTP service. It is:
+- Type-safe end-to-end (request/response types flow through middleware)
+- Edge-compatible (runs on Bun, Node, Cloudflare Workers, Deno, AWS Lambda)
+- Faster than Express, Fastify, and most of its peers in synthetic benchmarks
+- Maintained, opinionated, and documented well
+
+When Hono → ALWAYS pair with `hono-openapi` + `@scalar/hono-api-reference` + `@hono/swagger-ui`. Full setup with copy-pasteable `app.ts`: [backend-hono.md](backend-hono.md).
+
+NEVER:
+- Express for new services. Express is the COBOL of Node — works, but writes itself out of every benchmark.
+- Fastify for new services. Hono ships with better TypeScript ergonomics.
+- NestJS for new services. The Angular-flavoured DI/decorator stack is overkill for ~95% of services.
+- Bare `Bun.serve` or `node:http` unless you have a specific reason. Lose middleware, routing, validation. Reinvent everything.
+
+## Frontend tooling — Vite
+
+Vite for any frontend. Replaces webpack, parcel, rollup-as-app-bundler. Works with React, Vue, Svelte, Solid, Preact, vanilla.
+
+```bash
+bun create vite my-app -- --template react-ts
+cd my-app
+bun install
+bun run dev
+```
+
+## Lint + format — Biome
+
+Biome replaces ESLint + Prettier with one tool, written in Rust, ~30x faster.
+
+```bash
+bun add --dev @biomejs/biome
+bun biome init
+```
+
+`biome.json`:
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
+  "organizeImports": { "enabled": true },
+  "linter": { "enabled": true, "rules": { "recommended": true } },
+  "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 }
+}
+```
+
+Use ESLint only when:
+- You have an ESLint plugin Biome doesn't replicate (rare in 2026)
+- You're contributing to an existing ESLint project
+
+Never run both — pick one.
+
+## Test runner — bun test or vitest
+
+| Runner | Use when |
+|---|---|
+| `bun test` | Bun project, simple unit tests, no TypeScript path aliases that need vite-style resolution |
+| `vitest` | Vite-based frontend, complex test infrastructure (DOM testing, snapshot, in-browser tests), or you need vitest-specific features |
+
+NEVER Jest for a new project. Jest's CommonJS-first design fights every modern Node/TS project.
+
+## TypeScript
+
+`tsconfig.json` for a Bun + Hono backend:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "types": ["bun-types"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}
+```
+
+`verbatimModuleSyntax: true` enforces explicit `import type { ... }` for type-only imports — pairs with the no-excuse rule on type-only imports.
+
+`noEmit: true` because `bun run` and `bun build` handle compilation. The `tsc` command becomes a typechecker only.
+
+## Quick-start: Bun + Hono backend
+
+```bash
+mkdir my-api && cd my-api
+bun init -y
+bun add hono hono-openapi @scalar/hono-api-reference @hono/swagger-ui zod
+bun add --dev @biomejs/biome typescript
+bun biome init
+```
+
+`package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "bun run --hot src/index.ts",
+    "start": "bun run src/index.ts",
+    "build": "bun build src/index.ts --target bun --outdir dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --write src tests",
+    "test": "bun test"
+  }
+}
+```
+
+Wire the `app.ts` from [backend-hono.md](backend-hono.md). You have a documented, validated, OpenAPI-spec-emitting service in ~15 minutes.
+
+## When NOT to bootstrap from scratch
+
+| Situation | Use |
+|---|---|
+| Internal tool with auth/admin/dashboards | Next.js (full-stack) - lots of free wiring |
+| Documentation site | Astro or VitePress |
+| Real-time features (WebRTC, complex sockets) | Bun + Hono + a real-time library |
+| Data-heavy SPA | Vite + React + TanStack Query + TanStack Router |
+
+For greenfield backend services, Bun + Hono. Always.

package/node_modules/@litcodex/lit-loop/skills/lit-code/references/typescript/data-modeling.md

@@ -0,0 +1,202 @@
+# Data Modeling
+
+Which construct to use, how to structure data, and why readonly is the default.
+
+---
+
+## Decision flowchart
+
+```
+Is it a fixed set of named constants?
+  YES → as const object + literal union type
+  NO ↓
+Is it just branding a primitive (string, number)?
+  YES → Branded type
+  NO ↓
+Is it an interface / contract?
+  YES → interface (structural typing is the default in TS)
+  NO ↓
+Does the data cross a trust boundary (user input, API, file)?
+  YES → Zod schema + z.infer<typeof schema>
+  NO ↓
+Is it a union of possible outcomes?
+  YES → Discriminated union (kind/type field)
+  NO ↓
+Is it structured data with named fields?
+  YES → type alias with readonly properties
+  NO → you probably don't need a new type
+```
+
+---
+
+## Container reference
+
+### type alias — internal data
+
+The default for structured data inside your codebase. Zero runtime cost.
+
+```typescript
+type User = {
+  readonly id: UserId
+  readonly name: string
+  readonly email: string
+}
+
+type Point = {
+  readonly x: number
+  readonly y: number
+}
+```
+
+All properties `readonly`. Mutable only when mutation is the documented purpose.
+
+### interface — contracts and extension
+
+Use when you need declaration merging or `extends`.
+
+```typescript
+interface Repository<T> {
+  get(id: string): Promise<T | null>
+  save(entity: T): Promise<void>
+}
+
+interface UserRepository extends Repository<User> {
+  findByEmail(email: string): Promise<User | null>
+}
+```
+
+### interface vs type — when to use which
+
+| Use | When |
+|---|---|
+| `type` | Union types, intersections, mapped types, utility types, internal data shapes |
+| `interface` | Contracts that will be `implements`ed or `extends`ed, declaration merging needed |
+| **Default** | **`type` — unless you have a specific reason for `interface`** |
+
+### Zod schema — trust boundary guardian
+
+Use when data enters your system. Validates at runtime, infers types at compile time.
+
+```typescript
+import { z } from "zod"
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().int().min(0),
+})
+type CreateUser = z.infer<typeof CreateUserSchema>
+
+const UserResponseSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  email: z.string(),
+})
+type UserResponse = z.infer<typeof UserResponseSchema>
+```
+
+**The one rule**: data crosses a trust boundary → Zod. Everything else → plain type/interface.
+Never use Zod for internal-only data. The runtime validation cost and Zod coupling are unnecessary.
+
+### as const — fixed constants
+
+Replaces `enum` entirely. Type-safe, tree-shakeable, no runtime overhead.
+
+```typescript
+const ROLES = ["admin", "user", "guest"] as const
+type Role = (typeof ROLES)[number]
+
+const STATUS = {
+  ACTIVE: "active",
+  INACTIVE: "inactive",
+  DELETED: "deleted",
+} as const
+type Status = (typeof STATUS)[keyof typeof STATUS]
+```
+
+### Discriminated union — multiple outcomes
+
+```typescript
+type GetUserResult =
+  | { readonly kind: "found"; readonly user: User }
+  | { readonly kind: "not_found"; readonly id: UserId }
+  | { readonly kind: "forbidden"; readonly reason: string }
+```
+
+Each variant has a `kind` discriminant. TypeScript narrows on `switch (result.kind)`.
+
+---
+
+## Quick lookup
+
+| Situation | Use |
+|---|---|
+| User input, API request/response | Zod schema + `z.infer` |
+| Internal value object | `type` with `readonly` properties |
+| Function with multiple outcomes | Discriminated union |
+| Contract for implementations | `interface` |
+| Fixed constants | `as const` + literal union |
+| Distinct primitive (UserId vs OrderId) | Branded type |
+| Dict shape / key-value map | `Record<K, V>` or index signature |
+
+---
+
+## Readonly by default
+
+Every property is `readonly` unless mutation is the documented purpose.
+
+```typescript
+// DEFAULT — readonly
+type Config = {
+  readonly apiUrl: string
+  readonly timeout: number
+}
+
+// Arrays too
+function getUsers(): readonly User[] { ... }
+
+// Utility for existing types
+type ReadonlyUser = Readonly<User>
+type DeepReadonlyConfig = Readonly<Config>
+```
+
+For mutable state (rare), document why:
+
+```typescript
+/** Counter state — mutation is the entire purpose. */
+type CounterState = {
+  count: number  // intentionally mutable
+}
+```
+
+---
+
+## Parse, don't validate
+
+Validate at the boundary. Inside the boundary, types are proof of validity.
+
+```typescript
+// BAD — validate then pass raw data
+function processEmail(email: string): void {
+  if (!email.includes("@")) throw new Error("invalid")
+  // still a raw string downstream
+}
+
+// GOOD — parse into typed value at boundary
+const EmailSchema = z.string().email().brand("Email")
+type Email = z.infer<typeof EmailSchema>
+
+function sendWelcome(email: Email): void { ... }
+
+// Boundary code
+const parsed = EmailSchema.parse(rawInput)  // Email or throws
+sendWelcome(parsed)  // no re-validation needed
+```
+
+---
+
+## Sources
+
+- TypeScript Handbook: [Object Types](https://www.typescriptlang.org/docs/handbook/2/objects.html)
+- Zod: [docs](https://zod.dev)
+- Total TypeScript: [Type vs Interface](https://www.totaltypescript.com/type-vs-interface-which-should-you-use)

package/node_modules/@litcodex/lit-loop/skills/lit-code/references/typescript/error-handling.md

@@ -0,0 +1,169 @@
+# Error Handling
+
+Typed errors, exhaustive matching, Result pattern, and resource safety.
+
+---
+
+## Typed errors — no bare strings
+
+Error classes carry structured data. Callers know exactly what can go wrong.
+
+```typescript
+class UserNotFoundError extends Error {
+  readonly name = "UserNotFoundError"
+  constructor(readonly userId: UserId) {
+    super(`user ${userId} not found`)
+  }
+}
+
+class PermissionDeniedError extends Error {
+  readonly name = "PermissionDeniedError"
+  constructor(
+    readonly userId: UserId,
+    readonly requiredRole: string,
+  ) {
+    super(`user ${userId} needs role ${requiredRole}`)
+  }
+}
+```
+
+```typescript
+// BAD
+throw new Error("user not found")
+throw new Error("permission denied")
+
+// GOOD
+throw new UserNotFoundError(userId)
+throw new PermissionDeniedError(userId, "admin")
+```
+
+Always set `readonly name` explicitly — `instanceof` checks survive minification, but `error.name` is more reliable for logging and serialization.
+
+---
+
+## Result pattern — expected failures without exceptions
+
+For failures that are **expected** (not found, validation), return a discriminated union instead of throwing.
+
+```typescript
+type Result<T, E = Error> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E }
+
+function ok<T>(value: T): Result<T, never> {
+  return { ok: true, value }
+}
+
+function err<E>(error: E): Result<never, E> {
+  return { ok: false, error }
+}
+```
+
+### Usage
+
+```typescript
+type UserError =
+  | { readonly kind: "not_found"; readonly id: UserId }
+  | { readonly kind: "forbidden"; readonly reason: string }
+
+function getUser(id: UserId): Result<User, UserError> {
+  const user = db.find(id)
+  if (!user) return err({ kind: "not_found", id })
+  if (!user.active) return err({ kind: "forbidden", reason: "deactivated" })
+  return ok(user)
+}
+
+// Caller must handle both cases
+const result = getUser(userId)
+if (!result.ok) {
+  switch (result.error.kind) {
+    case "not_found":
+      log.warn(`missing: ${result.error.id}`)
+      break
+    case "forbidden":
+      log.error(`denied: ${result.error.reason}`)
+      break
+    default:
+      assertNever(result.error)
+  }
+  return
+}
+const user = result.value  // narrowed to User
+```
+
+### When to use which
+
+**The heuristic**: caller is 1-2 levels away and MUST handle it → Result. Error should propagate up many layers → throw.
+
+| Scenario | Pattern | Why |
+|---|---|---|
+| Repository → service (caller handles it) | Result | Caller is right there, must handle both |
+| Validation at boundary (parsing input) | throw (Zod throws) | Propagates up to HTTP handler |
+| Infrastructure failure (network, OOM) | throw | Can't handle locally |
+| Service → service (deep internal) | throw (typed Error subclass) | Result boilerplate across many layers is worse |
+| HTTP handler → response | Catch errors, convert to response | Boundary code catches and translates |
+
+**Practical tradeoff**: Result is safest (compiler forces handling) but creates boilerplate when every caller in a chain must check `.ok`. If the error would just propagate through 3+ layers unchanged, use a typed Error subclass instead.
+
+### Library or roll your own?
+
+Roll your own with the `Result`, `ok`, `err` above. It's 10 lines. Libraries like `neverthrow` add chaining (`.map`, `.andThen`) — use them only if you actually chain results frequently.
+
+---
+
+## Error cause — chain context
+
+Use the `cause` option to chain errors without losing the original stack.
+
+```typescript
+try {
+  await db.query(sql)
+} catch (error) {
+  throw new DatabaseError("query failed", { cause: error })
+}
+```
+
+The `cause` is available on `error.cause` and shows up in stack traces.
+
+---
+
+## Exhaustive error handling at boundaries
+
+HTTP handlers catch and translate:
+
+```typescript
+app.onError((error, c) => {
+  if (error instanceof UserNotFoundError) {
+    return c.json({ error: error.message }, 404)
+  }
+  if (error instanceof PermissionDeniedError) {
+    return c.json({ error: error.message }, 403)
+  }
+  console.error("unhandled:", error)
+  return c.json({ error: "internal server error" }, 500)
+})
+```
+
+---
+
+## Async error patterns
+
+```typescript
+// Promise.allSettled — when partial failure is OK
+const results = await Promise.allSettled(urls.map(fetch))
+const successes = results
+  .filter((r): r is PromiseFulfilledResult<Response> => r.status === "fulfilled")
+  .map((r) => r.value)
+
+// AbortSignal — cancellation
+async function fetchWithTimeout(url: string, ms: number): Promise<Response> {
+  return fetch(url, { signal: AbortSignal.timeout(ms) })
+}
+```
+
+---
+
+## Sources
+
+- MDN: [Error cause](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)
+- MDN: [Promise.allSettled](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled)