standard-typed-config 0.0.1

package/HOWTO.md

@@ -0,0 +1,214 @@
+# How-to Guides
+
+Practical tasks for working with `typed-builder`. Each guide assumes you understand the core concepts in [DESIGN.md](./DESIGN.md).
+
+## How to Create a Builder for a New Domain
+
+1. **Define your item configuration type.**
+   This is the shape each item in your domain has:
+
+   ```typescript
+   type MyItemConfig = {
+     enabled: boolean;
+     priority: number;
+   };
+   ```
+
+2. **Define your hooks map.**
+   Each hook declares its `input` (what it receives) and `output` (what it returns). Use `output: void` for terminal hooks that don't accumulate data:
+
+   ```typescript
+   type MyHooks = {
+     beforeProcess: { input: { items: Record<string, MyItemConfig> }; output: { cost: number } };
+     report: { input: { items: Record<string, MyItemConfig> } & { cost: number }; output: void };
+     execute: { input: { items: Record<string, MyItemConfig> } & { cost: number }; output: string };
+   };
+   ```
+
+3. **Create the builder factory.**
+   Pass your hooks map and an array of hook names to `createBuilder`:
+
+   ```typescript
+   const { define } = createBuilder<MyItemConfig, MyHooks>()([
+     'beforeProcess',
+     'report',
+     'execute',
+   ]);
+   ```
+
+4. **Define items.**
+
+   ```typescript
+   const builder = define({
+     itemA: { enabled: true, priority: 1 },
+     itemB: { enabled: false, priority: 2 },
+   });
+   ```
+
+5. **Chain hooks to build your workflow.**
+
+   ```typescript
+   builder
+     .beforeProcess((ctx) => ({ cost: 42 }))
+     .report((ctx) => {
+       // ctx.cost is visible here because beforeProcess accumulated it
+     });
+   ```
+
+---
+
+## How to Add a New Hook to an Existing Builder
+
+1. **Add a new entry to your `THooksMap`.**
+
+   ```typescript
+   type MyHooks = {
+     beforeProcess: { input: { items: Record<string, MyItemConfig> }; output: { cost: number } };
+     report: { input: { items: Record<string, MyItemConfig> } & { cost: number }; output: void };
+     onRetry: { input: { items: Record<string, MyItemConfig> } & { cost: number }; output: { attempt: number } }; // ← new
+   };
+   ```
+
+2. **Add the hook name to the array passed to `createBuilder`.**
+
+   ```typescript
+   const { define } = createBuilder<MyItemConfig, MyHooks>()([
+     'beforeProcess',
+     'report',
+     'onRetry',  // ← added
+   ]);
+   ```
+
+3. **Chain the new hook on the builder.**
+
+   ```typescript
+   builder
+     .beforeProcess((ctx) => ({ cost: 10 }))
+     .onRetry((ctx) => ({ attempt: 1 }))
+     .report((ctx) => {
+       ctx.cost;    // number
+       ctx.attempt; // number
+     });
+   ```
+
+The mapped types automatically generate the new method — no changes to the library code needed.
+
+---
+
+## How to Compose Two Builders
+
+Use `.use()` to merge two builders when building a larger system from smaller ones.
+
+**Prerequisites:** Both builders must share the same `TConfig`.
+
+```typescript
+// Builder A: CI/CD runners
+type RunnerConfig = { capabilities: string[]; region: string };
+type RunnerHooks = {
+  beforeJob: { input: { items: Record<string, RunnerConfig> }; output: { estimatedCost: number } };
+  afterJob: { input: { items: Record<string, RunnerConfig> } & { estimatedCost: number }; output: void };
+};
+const { define: defineRunners } = createBuilder<RunnerConfig, RunnerHooks>()(['beforeJob', 'afterJob']);
+
+// Builder B: notifications (same TConfig)
+type NotifyHooks = {
+  notify: { input: { items: Record<string, RunnerConfig> } & { estimatedCost: number }; output: void };
+};
+const { define: defineNotify } = createBuilder<RunnerConfig, NotifyHooks>()(['notify']);
+
+// Compose — types merge via intersection
+defineRunners({
+  gpu: { capabilities: ['cuda'], region: 'us-east' },
+})
+  .beforeJob((ctx) => ({ estimatedCost: 2.5 }))
+  .use(defineNotify({
+    gpu: { capabilities: ['cuda'], region: 'us-east' }, // same item keys
+  }))
+  .notify((ctx) => {
+    ctx.estimatedCost; // number — from beforeJob, intersected from both builders
+  });
+```
+
+**Rule:** Both builders must have the same `TConfig` to compose. Different hook sets are fine — the `THooksMap` types are independent per builder.
+
+---
+
+## How to Use Accumulated Data Across Multiple Hooks
+
+Hooks with non-void `output` merge their return values into `TContext`, making data available to all downstream hooks.
+
+```typescript
+type ItemConfig = { base: number };
+type MyHooks = {
+  step1: { input: { items: Record<string, ItemConfig> }; output: { value: number } };
+  step2: { input: { items: Record<string, ItemConfig> } & { value: number }; output: { total: number } };
+  finalize: { input: { items: Record<string, ItemConfig> } & { value: number } & { total: number }; output: void };
+};
+
+const { define } = createBuilder<ItemConfig, MyHooks>()(['step1', 'step2', 'finalize']);
+
+define({
+  item: { base: 10 },
+})
+  .step1((ctx) => ({ value: ctx.items.item.base * 2 }))
+  .step2((ctx) => ({
+    // ctx.value (from step1) is visible here
+    total: ctx.value + ctx.items.item.base,
+  }))
+  .finalize((ctx) => {
+    ctx.value; // number — from step1
+    ctx.total; // number — from step2
+  });
+```
+
+**Rule:** Each hook sees types from hooks declared *before* it in the chain, not after. Order matters.
+
+---
+
+## How to Debug Type Errors in a Builder
+
+When TypeScript reports an error on a builder chain, read the type from right to left — each step narrows the types for the next.
+
+**Common error: property not in context**
+
+```typescript
+.beforeHook((ctx) => ({ cost: 10 }))
+.finalize((ctx) => {
+  ctx.total; // Error: Property 'total' does not exist
+});
+```
+
+**Fix:** `finalize` only sees types accumulated *before* it. Either add a hook that returns `total` before `finalize`, or access it in a different hook.
+
+**Common error: key not in items**
+
+```typescript
+builder.items['nonexistent']; // Error: Property 'nonexistent' does not exist
+```
+
+This is correct — the builder only knows about keys declared in `items`. Add the key to `items` or use a key from the routes.
+
+**Common error: TConfig mismatch on `.use()`**
+
+```typescript
+type ConfigA = { a: string };
+type ConfigB = { b: number };
+// Both builders must have identical TConfig to compose
+```
+
+The `TConfig` types must match exactly for `.use()` to work. This is intentional — it prevents cross-domain contamination.
+
+---
+
+## How to Mark a Hook as Terminal (Non-accumulating)
+
+Use `output: void` to indicate a hook that doesn't pass data downstream:
+
+```typescript
+type MyHooks = {
+  accumulating: { input: { items: Record<string, Config> }; output: { cost: number } };
+  terminal: { input: { items: Record<string, Config> } & { cost: number }; output: void }; // ← void means no accumulation
+};
+```
+
+Any `output` that is not `Record<string, unknown>` won't merge into `TContext`. The type guard `THooksMap[K]['output'] extends Record<string, unknown> ? THooksMap[K]['output'] : {}` handles this.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# typed-builder
+
+A TypeScript library implementing a **builder pattern with accumulating type parameters**. Each method call narrows the types available to subsequent calls, giving you end-to-end type safety without runtime overhead.
+
+```
+npm install typed-builder
+```
+
+## What Problem It Solves
+
+When you chain builder methods, you often lose type information from earlier steps. `typed-builder` solves this by carrying **generic type parameters that narrow with each method call** — the types from early calls are preserved and available downstream.
+
+For example, if a `beforeEach` hook returns `{ cost: number }`, that type is visible in every subsequent hook without you re-declaring it.
+
+## Core Concepts
+
+| Concept | Role |
+|---------|------|
+| **Accumulating hooks** | Return data that flows downstream to all later hooks |
+| **Terminal hooks** | Consume accumulated data; produce final output |
+| **Composition (`.use()`)** | Merge two builders — their type parameters intersect |
+
+See [DESIGN.md](./DESIGN.md) for the full design rationale and type mechanics.
+
+## Quick Start
+
+```typescript
+import { createBuilder } from 'typed-builder';
+
+// 1. Define your domain's item shape
+type MenuItemConfig = {
+  inStock: boolean;
+  price: number;
+};
+
+// 2. Create a builder factory for your domain
+const { define } = createBuilder<MenuItemConfig>()({
+  accumulating: ['beforePrep'],
+  terminal: ['receipt'],
+});
+
+// 3. Define items and routes
+define({
+  items: {
+    burger: { inStock: true, price: 12.99 },
+    salad: { inStock: false, price: 8.99 },
+  },
+  routes: {
+    // Routes receive { key, items }
+    list: (ctx) => Object.entries(ctx.items).map(([k, v]) => k),
+  },
+})
+  // 4. Accumulating hook — return data is available downstream
+  .beforePrep((key, ctx) => ({ totalPrice: ctx.items[key].price }))
+  // 5. Terminal hook — reads accumulated data, produces final output
+  .receipt((ctx) => {
+    ctx.totalPrice; // number ✓
+    return `Total: $${ctx.totalPrice}`;
+  });
+```
+
+## Documentation
+
+| Doc | Type | What it covers |
+|-----|------|----------------|
+| [TUTORIAL.md](./TUTORIAL.md) | Tutorial | Build a CI/CD pipeline builder from scratch |
+| [HOWTO.md](./HOWTO.md) | How-to guides | Build a new builder, compose builders, add hooks |
+| [API.md](./API.md) | Reference | `createBuilder`, hook signatures, type parameters |
+| [DESIGN.md](./DESIGN.md) | Explanation | How the type machinery works, why it exists |
+
+## Installation
+
+```bash
+npm install typed-builder
+# or
+yarn add typed-builder
+# or
+pnpm add typed-builder
+```
+
+Requires TypeScript 5.0+.
+
+## License
+
+MIT

package/TUTORIAL.md

@@ -0,0 +1,152 @@
+# Build a CI/CD Pipeline Builder from Scratch
+
+In this tutorial, you will build a typed builder for a CI/CD pipeline domain. By the end, you will have a working builder that tracks estimated cost through job steps and produces a final execution report.
+
+No prior experience with `typed-builder` is needed. Familiarity with TypeScript generics is helpful.
+
+## What you're building
+
+A pipeline builder for a CI/CD system where:
+- Each **job step** (like `beforeJob`, `afterJob`) can accumulate cost data
+- The `execute` terminal hook produces a final report using all accumulated data
+
+## Step 1 — Define the item configuration type
+
+CI/CD runners have a configuration that all jobs share:
+
+```typescript
+type RunnerConfig = {
+  capabilities: string[];
+  maxParallel: number;
+  region: string;
+};
+```
+
+Every runner in your pipeline has this shape.
+
+## Step 2 — Define the hooks map
+
+Each hook declares what it **receives** (`input`) and what it **returns** (`output`). Hooks that return `void` are terminal — they don't accumulate data downstream.
+
+```typescript
+type PipelineHooks = {
+  // Accumulating: returns cost data that flows to later hooks
+  beforeJob: {
+    input: { items: Record<string, RunnerConfig> };
+    output: { estimatedCost: number };
+  };
+  // Terminal: receives cost data, produces a final report
+  report: {
+    input: { items: Record<string, RunnerConfig> } & { estimatedCost: number };
+    output: void;
+  };
+  // Terminal: receives cost data, returns the final result string
+  execute: {
+    input: { items: Record<string, RunnerConfig> } & { estimatedCost: number };
+    output: string;
+  };
+};
+```
+
+## Step 3 — Create the builder factory
+
+Pass your config type, hooks map, and an array of hook names:
+
+```typescript
+const { define } = createBuilder<RunnerConfig, PipelineHooks>()([
+  'beforeJob',
+  'report',
+  'execute',
+]);
+```
+
+## Step 4 — Define your pipeline runners
+
+```typescript
+const pipeline = define({
+  'gpu-runner': {
+    capabilities: ['cuda', 'tensor cores'],
+    maxParallel: 4,
+    region: 'us-east-1',
+  },
+  'cpu-runner': {
+    capabilities: ['x86_64'],
+    maxParallel: 8,
+    region: 'us-west-2',
+  },
+});
+```
+
+## Step 5 — Chain hooks to build the pipeline
+
+```typescript
+const result = pipeline
+  // beforeJob accumulates { estimatedCost }
+  .beforeJob((ctx) => ({
+    estimatedCost: ctx.items['gpu-runner'].maxParallel * 0.25,
+  }))
+  // execute receives ctx.estimatedCost from beforeJob
+  .execute((ctx) => {
+    return `Pipeline complete. Estimated cost: $${ctx.estimatedCost}`;
+  });
+// result: "Pipeline complete. Estimated cost: $1.00"
+```
+
+## What just happened
+
+| Phase | What changed |
+|-------|-------------|
+| `define({...})` | `TKeys` = `"gpu-runner" \| "cpu-runner"`, `TItems` = the item map, `TContext` = `{}` |
+| `.beforeJob(fn)` | `TContext` narrowed to `{ estimatedCost: number }` |
+| `.execute(fn)` | Receives `{ key: TKeys } & { items: TItems } & { estimatedCost: number }` |
+
+TypeScript validates each step. If you try to access `.estimatedCost` inside `beforeJob`, it won't exist yet — that's the point.
+
+## Step 6 — Add a second accumulating hook
+
+Suppose you want to track memory usage separately. Add it to the hooks map and re-create the factory:
+
+```typescript
+type PipelineHooks = {
+  beforeJob: { input: { items: Record<string, RunnerConfig> }; output: { estimatedCost: number } };
+  beforeJobMemory: { input: { items: Record<string, RunnerConfig> } & { estimatedCost: number }; output: { memoryMB: number } };
+  report: { input: { items: Record<string, RunnerConfig> } & { estimatedCost: number } & { memoryMB: number }; output: void };
+  execute: { input: { items: Record<string, RunnerConfig> } & { estimatedCost: number } & { memoryMB: number }; output: string };
+};
+
+const { define } = createBuilder<RunnerConfig, PipelineHooks>()([
+  'beforeJob',
+  'beforeJobMemory',
+  'report',
+  'execute',
+]);
+```
+
+Now chain both accumulating hooks:
+
+```typescript
+pipeline
+  .beforeJob((ctx) => ({ estimatedCost: 1.0 }))
+  .beforeJobMemory((ctx) => ({ memoryMB: 512 }))
+  .execute((ctx) => {
+    ctx.estimatedCost; // number
+    ctx.memoryMB;      // number — accumulated from beforeJobMemory
+    return `Cost: $${ctx.estimatedCost}, Memory: ${ctx.memoryMB}MB`;
+  });
+```
+
+Each accumulating hook adds its output to `TContext`. Later hooks see the union of all accumulated data.
+
+## What you learned
+
+- How to define a domain with `TConfig` and `THooksMap`
+- How `createBuilder` generates typed methods from hook names
+- How accumulating hooks narrow `TContext` for downstream hooks
+- How terminal hooks with `output: void` consume but don't further accumulate
+- How TypeScript enforces type narrowing at each step in the chain
+
+## Next steps
+
+- Read [API.md](./API.md) for the full hook signature reference
+- Read [HOWTO.md](./HOWTO.md) to learn how to compose two builders together
+- Read [DESIGN.md](./DESIGN.md) to understand the type machinery under the hood

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+type THookDef = {
+    input: unknown;
+    output: unknown;
+};
+type TerminalResult<TConfig, TItems extends Record<string, TConfig>, TContext extends Record<string, unknown>> = {
+    config: TConfig;
+    items: TItems;
+    context: TContext;
+};
+type Builder<TConfig, TKeys extends string, TItems extends Record<string, TConfig>, TContext extends Record<string, unknown>, THooksMap extends Record<string, THookDef>> = {
+    use<UKeys extends string, UItems extends Record<string, TConfig>, UContext extends Record<string, unknown>, UHooksMap extends Record<string, THookDef>>(source: Builder<TConfig, UKeys, UItems, UContext, UHooksMap>): Builder<TConfig, TKeys | UKeys, TItems & UItems, TContext & UContext, THooksMap>;
+} & {
+    [K in keyof THooksMap]: (fn: (ctx: THooksMap[K]['input'] & {
+        key: TKeys;
+    } & TItems & TContext) => void | THooksMap[K]['output']) => [THooksMap[K]['output']] extends [never] ? TerminalResult<TConfig, TItems, TContext> : THooksMap[K]['output'] extends Record<string, unknown> ? Builder<TConfig, TKeys, TItems, TContext & THooksMap[K]['output'], THooksMap> : TerminalResult<TConfig, TItems, TContext>;
+};
+declare function createBuilder<TConfig, THooksMap extends Record<string, THookDef>>(hookNames: Array<keyof THooksMap>): {
+    define: {
+        <TItems extends Record<string, TConfig>>(items: TItems): Builder<TConfig, keyof TItems & string, TItems, {}, THooksMap>;
+        (): Builder<TConfig, never, {}, {}, THooksMap>;
+    };
+};
+export { createBuilder, type Builder };

package/dist/index.js

@@ -0,0 +1,14 @@
+// ══════════════════════════════════════════════════════════════════════════════════
+// Typed Builder — domain-agnostic builder with accumulating type parameters
+// ══════════════════════════════════════════════════════════════════════════════════
+function createBuilder(hookNames) {
+    function define(items) {
+        const instance = {};
+        instance.use = (source) => instance;
+        for (const hookName of hookNames)
+            instance[hookName] = (fn) => instance;
+        return instance;
+    }
+    return { define };
+}
+export { createBuilder };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "standard-typed-config",
+  "version": "0.0.1",
+  "description": "TypeScript pattern: builder with accumulating type parameters, domain-defined hooks, Elysia-style .use() composition",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit --strict --skipLibCheck test/types.test-d.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "typescript",
+    "builder-pattern",
+    "type-level",
+    "generic",
+    "fluent-api",
+    "accumulating-types",
+    "mapped-types"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsd": "^0.33.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+// ══════════════════════════════════════════════════════════════════════════════════
+// Typed Builder — domain-agnostic builder with accumulating type parameters
+// ══════════════════════════════════════════════════════════════════════════════════
+
+type THookDef = { input: unknown; output: unknown };
+
+type TerminalResult<TConfig, TItems extends Record<string, TConfig>, TContext extends Record<string, unknown>> = {
+  config: TConfig;
+  items: TItems;
+  context: TContext;
+};
+
+type Builder<
+  TConfig,
+  TKeys extends string,
+  TItems extends Record<string, TConfig>,
+  TContext extends Record<string, unknown>,
+  THooksMap extends Record<string, THookDef>
+> = {
+  use<UKeys extends string, UItems extends Record<string, TConfig>, UContext extends Record<string, unknown>, UHooksMap extends Record<string, THookDef>>(
+    source: Builder<TConfig, UKeys, UItems, UContext, UHooksMap>
+  ): Builder<TConfig, TKeys | UKeys, TItems & UItems, TContext & UContext, THooksMap>;
+} & {
+  [K in keyof THooksMap]: (
+    fn: (ctx: THooksMap[K]['input'] & { key: TKeys } & TItems & TContext) => void | THooksMap[K]['output']
+  ) => [THooksMap[K]['output']] extends [never]
+    ? TerminalResult<TConfig, TItems, TContext>
+    : THooksMap[K]['output'] extends Record<string, unknown>
+      ? Builder<TConfig, TKeys, TItems, TContext & THooksMap[K]['output'], THooksMap>
+      : TerminalResult<TConfig, TItems, TContext>;
+};
+
+function createBuilder<TConfig, THooksMap extends Record<string, THookDef>>(hookNames: Array<keyof THooksMap>) {
+
+  function define<TItems extends Record<string, TConfig>>(
+    items: TItems
+  ): Builder<TConfig, keyof TItems & string, TItems, {}, THooksMap>;
+  function define(): Builder<TConfig, never, {}, {}, THooksMap>;
+  function define(items?: any): any {
+    const instance: any = {};
+    instance.use = (source: any) => instance;
+    for (const hookName of hookNames) instance[hookName] = (fn: any) => instance;
+    return instance;
+  }
+
+  return { define };
+}
+
+export { createBuilder, type Builder };