@zigrivers/scaffold 3.7.0 → 3.9.0

package/content/knowledge/library/library-api-design.md

@@ -0,0 +1,306 @@
+---
+name: library-api-design
+description: Public surface design, method signatures, error contracts, and extension points for published library APIs
+topics: [library, api-design, public-surface, method-signatures, error-contracts, extension-points]
+---
+
+Library API design is the highest-leverage activity in library development. A well-designed API makes correct usage easy and incorrect usage hard, survives multiple major versions without fundamental restructuring, and communicates intent through its shape alone. Poor API design cannot be fixed without breaking changes — every naming mistake, parameter order error, and missing overload becomes permanent once consumers adopt it. Design APIs from the consumer's perspective first, implementation second.
+
+## Summary
+
+Design APIs by writing consumer call sites before writing implementation. Prefer named options objects over positional parameters beyond two arguments. Return values should be typed as specifically as possible — avoid returning `any` or overly wide union types. Error contracts must be explicit: document what each function throws, when, and why. Provide extension points through composition (options injection, middleware, plugins) rather than inheritance. Make the happy path obvious and the error path impossible to ignore.
+
+Core principles:
+- Pit-of-success design: the obvious way to use the API is the correct way
+- Named options objects for 3+ parameters
+- Explicit error contracts (typed throws, documented in JSDoc)
+- Overloads for genuinely different call signatures
+- Consistent return type patterns (never `T | undefined` when you can overload)
+
+## Deep Guidance
+
+### Write Call Sites First
+
+Before implementing any function, write the code that will call it:
+
+```typescript
+// Step 1: Write how consumers will use this
+import { parseConfig } from 'my-library'
+
+// Use case 1: parse a string, get typed config
+const config = parseConfig(rawString)
+
+// Use case 2: parse with strict mode
+const config = parseConfig(rawString, { strict: true })
+
+// Use case 3: parse a file path (different input)
+const config = await parseConfigFile('./config.toml')
+
+// Use case 4: handle parse errors gracefully
+try {
+  const config = parseConfig(rawString)
+} catch (err) {
+  if (err instanceof ParseError) {
+    console.error(`Parse failed at line ${err.line}: ${err.message}`)
+  }
+}
+
+// Step 2: Now design the API to make this work naturally
+export function parseConfig(input: string, options?: ParseOptions): Config
+export async function parseConfigFile(path: string, options?: ParseOptions): Promise<Config>
+```
+
+This technique reveals usability issues before any code is written.
+
+### Options Object Pattern
+
+Positional parameters beyond two create cognitive load and fragile call sites:
+
+```typescript
+// BAD: positional parameters — order is arbitrary, easy to mix up
+function connect(host: string, port: number, timeout: number, ssl: boolean, retries: number): Client
+
+// Called as: connect('localhost', 5432, 30000, true, 3)
+// Which is timeout and which is retries? Must check signature every time.
+
+// GOOD: named options object
+interface ConnectOptions {
+  host: string
+  port: number
+  timeout?: number     // ms, default: 30000
+  ssl?: boolean        // default: false
+  retries?: number     // default: 3
+}
+
+function connect(options: ConnectOptions): Client
+// connect({ host: 'localhost', port: 5432, ssl: true })
+// Self-documenting call site. New options add without breaking callers.
+```
+
+**Options object rules:**
+- All options beyond the first two required parameters go in an options object
+- Options should have sensible defaults (document the defaults in JSDoc)
+- Required options stay required; don't make everything optional
+- Never use boolean flags that change behavior fundamentally — use discriminated unions
+
+```typescript
+// BAD: boolean flag that means completely different behavior
+function parse(input: string, isFile: boolean): Config
+
+// GOOD: separate functions or discriminated union
+function parseString(input: string): Config
+function parseFile(path: string): Promise<Config>
+// Or:
+type ParseInput = { type: 'string'; value: string } | { type: 'file'; path: string }
+function parse(input: ParseInput): Config | Promise<Config>
+```
+
+### Method Signature Design
+
+**Overloads for genuinely different signatures:**
+```typescript
+// Overloads allow TypeScript to narrow the return type based on input
+function parse(input: string): Config
+function parse(input: string, options: { async: true }): Promise<Config>
+function parse(input: string, options: { async: false }): Config
+function parse(input: string, options?: ParseOptions): Config | Promise<Config> {
+  // implementation
+}
+```
+
+Use overloads sparingly. Each overload is a commitment to maintain that signature. If you find yourself needing many overloads, reconsider whether the API should be split into separate functions.
+
+**Generic constraints — add them when they add value:**
+```typescript
+// Good: generic constraint enables type narrowing
+function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>
+
+// Bad: generic without constraint is less type-safe
+function pick<T, K>(obj: T, keys: K[]): any
+
+// Bad: generic where it adds no value (always the same type)
+function identity<T>(value: T): T  // Fine for teaching, rarely needed in practice
+```
+
+**Return type specificity:**
+```typescript
+// BAD: too wide
+function getUser(id: string): object
+
+// BAD: any
+function parseYAML(input: string): any
+
+// GOOD: specific types
+function getUser(id: string): User | null  // null when not found
+function parseYAML<T = unknown>(input: string): T  // generic with default
+
+// BEST when the shape is known:
+interface User {
+  id: string
+  name: string
+  email: string
+  createdAt: Date
+}
+function getUser(id: string): User | null
+```
+
+### Error Contracts
+
+Every public function must have a documented error contract. Document errors in JSDoc and in a separate errors section of the API documentation.
+
+**JSDoc error documentation:**
+```typescript
+/**
+ * Parse a configuration string into a typed Config object.
+ *
+ * @param input - TOML-formatted configuration string
+ * @param options - Parsing options
+ * @returns Parsed and validated Config object
+ *
+ * @throws {ParseError} If the input string is not valid TOML.
+ *   `ParseError.line` and `ParseError.column` indicate the error location.
+ * @throws {ValidationError} If the parsed config fails schema validation.
+ *   `ValidationError.errors` contains the list of validation failures.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const config = parseConfig('[server]\nhost = "localhost"')
+ * } catch (err) {
+ *   if (err instanceof ParseError) {
+ *     console.error(`Syntax error at line ${err.line}`)
+ *   }
+ * }
+ * ```
+ */
+export function parseConfig(input: string, options?: ParseOptions): Config
+```
+
+**Result type pattern (alternative to throws):**
+For APIs where errors are expected and should be handled inline, a Result type is cleaner than throws:
+
+```typescript
+export type Result<T, E extends Error = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E }
+
+export function tryParseConfig(input: string): Result<Config, ParseError | ValidationError> {
+  try {
+    return { ok: true, value: parseConfig(input) }
+  } catch (err) {
+    return { ok: false, error: err as ParseError | ValidationError }
+  }
+}
+
+// Consumer usage:
+const result = tryParseConfig(input)
+if (result.ok) {
+  console.log(result.value.server.host)
+} else {
+  console.error(result.error.message)
+}
+```
+
+Provide both patterns when the use case warrants: throwing for "should not fail" paths, Result type for "expected to sometimes fail" paths.
+
+### Extension Points
+
+Design extension points that don't require forking or subclassing:
+
+**Middleware pattern for transform pipelines:**
+```typescript
+export interface ParseMiddleware {
+  (input: string, next: (input: string) => Config): Config
+}
+
+export function createParser(middlewares: ParseMiddleware[] = []): Parser {
+  return {
+    parse(input: string): Config {
+      const chain = middlewares.reduceRight(
+        (next: (i: string) => Config, mw) => (i: string) => mw(i, next),
+        parseRaw
+      )
+      return chain(input)
+    }
+  }
+}
+
+// Consumer adds preprocessing:
+const parser = createParser([
+  (input, next) => next(input.trim().toLowerCase()),
+  (input, next) => {
+    const result = next(input)
+    return { ...result, source: 'custom' }
+  }
+])
+```
+
+**Hook pattern for lifecycle events:**
+```typescript
+export interface ClientHooks {
+  beforeRequest?: (req: Request) => Request | Promise<Request>
+  afterResponse?: (res: Response) => Response | Promise<Response>
+  onError?: (err: Error) => void
+}
+
+export function createClient(options: ClientOptions & { hooks?: ClientHooks }): Client
+```
+
+**Avoid class inheritance as extension:**
+```typescript
+// BAD: forces consumers to subclass
+class BaseClient {
+  protected abstract buildRequest(options: RequestOptions): Request
+  // Consumers must extend to customize
+}
+
+// GOOD: inject the behavior
+type RequestBuilder = (options: RequestOptions) => Request
+
+function createClient(options: {
+  buildRequest?: RequestBuilder
+}): Client
+```
+
+Subclassing creates tight coupling between the consumer and the library's internal class hierarchy. Every internal restructuring becomes a breaking change.
+
+### Fluent API Design
+
+Fluent APIs (method chaining) improve readability for configuration-heavy builders:
+
+```typescript
+// Query builder example
+export class QueryBuilder<T> {
+  private _where: WhereClause[] = []
+  private _orderBy: OrderClause[] = []
+  private _limit?: number
+
+  where(field: keyof T, op: Operator, value: unknown): this {
+    this._where.push({ field: field as string, op, value })
+    return this
+  }
+
+  orderBy(field: keyof T, direction: 'asc' | 'desc' = 'asc'): this {
+    this._orderBy.push({ field: field as string, direction })
+    return this
+  }
+
+  limit(n: number): this {
+    this._limit = n
+    return this
+  }
+
+  build(): Query<T> {
+    return { where: this._where, orderBy: this._orderBy, limit: this._limit }
+  }
+}
+
+// Consumer:
+const query = new QueryBuilder<User>()
+  .where('active', '=', true)
+  .orderBy('createdAt', 'desc')
+  .limit(10)
+  .build()
+```
+
+Use fluent APIs for builders and configuration DSLs. Avoid them for operational functions — `parseConfig(input).validate().execute()` is harder to debug than three explicit function calls.

package/content/knowledge/library/library-architecture.md

@@ -0,0 +1,247 @@
+---
+name: library-architecture
+description: Module design, dependency minimization, tree-shaking enablement, and plugin patterns for published libraries
+topics: [library, architecture, modules, tree-shaking, plugins, dependencies, design]
+---
+
+Library architecture is constrained by two forces that do not apply to applications: the consumer's bundle size budget and the consumer's dependency graph. Every architectural decision must account for what the library adds to consumers who import it — not just the feature complexity it solves. A well-architected library is modular by default, has minimal or zero runtime dependencies, enables tree-shaking so consumers pay only for what they use, and provides extension points that don't require forking the library.
+
+## Summary
+
+Design libraries as collections of composable, independently tree-shakeable units. The root module is a barrel export; each feature module is independently importable. Minimize runtime dependencies to zero where possible — every dependency you add becomes a transitive dependency for every consumer. Enable tree-shaking by using ES modules, avoiding side effects, and ensuring the `"sideEffects": false` field is accurate. Plugin patterns allow extension without coupling; prefer dependency injection and factory functions over class hierarchies.
+
+Core architectural decisions:
+- Module boundary: each exported function/class is its own module file, barrel at root
+- Dependency strategy: zero runtime deps preferred; peer deps for framework integration
+- Side effects: none at module load time; `"sideEffects": false` in package.json
+- Extension pattern: plugin factory or dependency injection, not subclassing
+- Error strategy: typed error classes, not string codes; never swallow errors
+
+## Deep Guidance
+
+### Module Boundary Design
+
+Each public export should have a clear, single responsibility. The module structure mirrors the API surface:
+
+```
+src/
+├── index.ts           # Barrel: re-exports all public APIs
+├── parser.ts          # parseConfig, ParseOptions, ParseError
+├── validator.ts       # validateSchema, ValidationResult, ValidationError
+├── client.ts          # createClient, ClientOptions, Client interface
+├── types.ts           # Shared types used by multiple modules
+├── errors.ts          # Base error classes
+└── internal/
+    ├── cache.ts       # Internal LRU cache (not exported)
+    ├── http.ts        # Internal HTTP utilities
+    └── utils.ts       # Internal pure utilities
+```
+
+**The key constraint:** modules in `internal/` must never be imported by consumers. Enforce this with an ESLint rule:
+
+```json
+// .eslintrc.json
+{
+  "rules": {
+    "no-restricted-imports": ["error", {
+      "patterns": ["*/internal/*"]
+    }]
+  }
+}
+```
+
+This rule is for consumer code, not for library internals. The library's own modules can freely import from `internal/`.
+
+### Dependency Minimization
+
+Every runtime dependency you add has costs:
+1. Adds to install size for all consumers
+2. Creates a version conflict risk (consumer uses different version of same dep)
+3. Introduces a supply chain attack surface
+4. Creates license compliance requirements for consumers
+
+**Target: zero runtime dependencies for utility libraries.** If the library's value is transforming data, parsing strings, or providing utilities, it should have no runtime dependencies.
+
+**When dependencies are justified:**
+- The dependency solves a genuinely hard problem with no reasonable alternative (cryptography, date parsing)
+- The dependency is a peer dependency the consumer already has (React, Vue, Node.js built-ins)
+- The functionality would require thousands of lines of well-tested code to replicate
+
+**Inlining vs. depending:**
+For small, stable utilities (10-50 lines), consider inlining instead of depending:
+```typescript
+// Instead of: import { clamp } from 'lodash-es'
+// Inline it:
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+```
+
+For large, complex utilities (crypto, parsing), depend on the established library.
+
+### Tree-Shaking Enablement
+
+Tree-shaking requires the bundler to statically analyze which exports are used. Three requirements:
+
+**1. ES module syntax throughout:**
+```typescript
+// Good — static, analyzable
+export function parseConfig(input: string): Config { ... }
+export { validateSchema } from './validator'
+
+// Bad — dynamic, blocks tree-shaking
+module.exports = { parseConfig }  // CommonJS
+exports[functionName] = fn         // Dynamic export key
+```
+
+**2. No side effects at module load time:**
+```typescript
+// BAD: side effect on import — breaks tree-shaking
+const cache = new Map()
+globalThis.__myLibCache = cache  // Pollutes global on import
+console.log('my-library loaded') // Log on import
+
+// GOOD: factory function — no side effect until called
+export function createCache(): Map<string, unknown> {
+  return new Map()
+}
+```
+
+**3. Accurate `sideEffects` field:**
+```json
+// package.json — only if genuinely no side effects
+{ "sideEffects": false }
+
+// If CSS imports or polyfills have side effects:
+{ "sideEffects": ["*.css", "src/polyfills.js"] }
+```
+
+**Verify tree-shaking works:**
+```bash
+# Use bundle-buddy, rollup-plugin-visualizer, or bundlephobia to verify
+npx bundlephobia my-library@1.0.0
+
+# Or build a minimal consumer and check the output bundle size
+# A consumer that only imports parseConfig should not include validateSchema code
+```
+
+### Plugin Architecture Patterns
+
+Plugins allow consumers to extend the library without modifying it. Three patterns in increasing flexibility order:
+
+**Pattern 1: Factory function with options (simplest):**
+```typescript
+export interface ClientOptions {
+  transport?: Transport  // Consumer provides custom transport
+  serializer?: Serializer
+  logger?: Logger
+}
+
+export function createClient(options: ClientOptions = {}): Client {
+  const transport = options.transport ?? defaultHttpTransport()
+  const serializer = options.serializer ?? jsonSerializer()
+  const logger = options.logger ?? noopLogger()
+  return new ClientImpl(transport, serializer, logger)
+}
+
+// Consumer can inject their own transport:
+const client = createClient({
+  transport: myCustomTransport,
+  logger: pinoLogger
+})
+```
+
+This is dependency injection — the simplest, most testable plugin pattern.
+
+**Pattern 2: Plugin registry (for named, composable extensions):**
+```typescript
+export interface Plugin {
+  name: string
+  setup(context: PluginContext): void | Promise<void>
+}
+
+export interface PluginContext {
+  registerTransform(name: string, fn: TransformFn): void
+  registerValidator(name: string, fn: ValidatorFn): void
+  onParse(hook: ParseHook): void
+}
+
+export function createClient(options: { plugins?: Plugin[] } = {}): Client {
+  const context = createPluginContext()
+  for (const plugin of (options.plugins ?? [])) {
+    plugin.setup(context)
+  }
+  return new ClientImpl(context)
+}
+
+// Consumer uses plugins:
+import { myPlugin } from 'my-library-plugin-example'
+const client = createClient({ plugins: [myPlugin()] })
+```
+
+**Pattern 3: Middleware chain (for transform pipelines):**
+```typescript
+export type Middleware<T> = (value: T, next: (value: T) => T) => T
+
+export function createPipeline<T>(middlewares: Middleware<T>[]): (value: T) => T {
+  return (initial: T) => {
+    const chain = middlewares.reduceRight<(value: T) => T>(
+      (next, middleware) => (value) => middleware(value, next),
+      (value) => value
+    )
+    return chain(initial)
+  }
+}
+```
+
+**What to avoid:**
+- Class inheritance as extension mechanism (consumers must subclass to customize — creates tight coupling)
+- Singleton registries (one global registry makes testing and isolation difficult)
+- Monkey-patching as extension (fragile, hidden coupling)
+
+### Error Architecture
+
+Typed errors are part of the public API contract:
+
+```typescript
+// errors.ts — exported as part of public API
+export class LibraryError extends Error {
+  constructor(message: string, public readonly code: ErrorCode) {
+    super(message)
+    this.name = 'LibraryError'
+    // Maintain proper prototype chain in transpiled environments
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+export class ParseError extends LibraryError {
+  constructor(
+    message: string,
+    public readonly line: number,
+    public readonly column: number,
+    public readonly source?: string
+  ) {
+    super(message, 'PARSE_ERROR')
+    this.name = 'ParseError'
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+export type ErrorCode = 'PARSE_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT'
+```
+
+Never throw raw `Error` objects from library code — consumers cannot distinguish library errors from their own errors. Always throw typed errors with enough context to diagnose the problem.
+
+### Avoiding Circular Dependencies
+
+Circular dependencies in libraries cause subtle initialization order bugs. Enforce absence with ESLint:
+
+```json
+{
+  "rules": {
+    "import/no-cycle": ["error", { "maxDepth": 10 }]
+  }
+}
+```
+
+When you detect a circular dependency, the usual fix is extracting shared types to `types.ts` (which has no imports) rather than rearranging imports.