# TypeScript Build Configuration

# TypeScript Build Configuration

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [.gitignore](.gitignore)
- [package.json](package.json)
- [tsconfig.json](tsconfig.json)

</details>



The `@primebrick/sdk` utilizes a modern TypeScript configuration designed for Node.js environments, ensuring high performance, strict type safety, and compatibility with ECMAScript Modules (ESM). The build process transforms the source files located in `src/` into a distributable format in `dist/`, suitable for consumption by other microservices.

### Compiler Settings and Target

The SDK targets `ES2022` to leverage modern JavaScript features while maintaining a balance of performance and compatibility within recent Node.js LTS versions [tsconfig.json:3-3](). 

The project is configured as a pure ESM package, indicated by `"type": "module"` in the manifest [package.json:5-5](). To support this, the compiler uses `NodeNext` for both `module` and `moduleResolution` [tsconfig.json:4-5](). This ensures that the generated code respects modern Node.js resolution algorithms, including the requirement for file extensions in imports and the correct handling of the `exports` map defined in the package manifest [package.json:19-21]().

| Setting | Value | Purpose |
| :--- | :--- | :--- |
| `target` | `ES2022` | Modern JS feature support (Classes, Private fields, etc.) |
| `module` | `NodeNext` | ESM compatibility for Node.js |
| `moduleResolution` | `NodeNext` | Modern module lookup strategy |
| `outDir` | `dist` | Destination for compiled assets [tsconfig.json:7-7]() |
| `rootDir` | `src` | Source code entry point [tsconfig.json:8-8]() |

**Sources:**
- [tsconfig.json:1-8]()
- [package.json:5-5]()
- [package.json:19-21]()

---

### Strictness and Dependency Inversion

While the project enforces `strict` mode [tsconfig.json:9-9](), it specifically disables `strictPropertyInitialization` [tsconfig.json:10-10](). 

This decision is architectural. The SDK heavily utilizes a **Ports and Adapters** (Hexagonal) pattern where classes often have properties that are initialized via Dependency Injection (DI) or late-binding patterns rather than directly in the constructor. Disabling this check prevents the compiler from erroring when properties are intended to be populated by external adapters or setup routines after instantiation.

**Sources:**
- [tsconfig.json:9-10]()

---

### Build Output and Declarations

The build process is configured to generate comprehensive metadata for consuming packages:

1.  **Declaration Files (`.d.ts`)**: Enabled via `declaration: true`, these files provide the type definitions required by TypeScript consumers [tsconfig.json:14-14]().
2.  **Declaration Maps (`.d.ts.map`)**: Enabled via `declarationMap: true`, these allow consumers to use "Go to Definition" in their IDEs and land directly in the SDK's original TypeScript source code instead of the compiled type definitions [tsconfig.json:15-15]().
3.  **Source Maps (`.js.map`)**: Enabled via `sourceMap: true`, these facilitate debugging of the compiled JavaScript back to the original source [tsconfig.json:16-16]().

### Build Pipeline Visualization

The following diagram illustrates how the `tsconfig.json` configuration directs the flow from source code to the final published package.

**Source to Distribution Flow**
```mermaid
graph TD
    subgraph "Code Entity Space"
        SRC["src/index.ts"]
        TEST["src/**/*.test.ts"]
        DIST_JS["dist/index.js"]
        DIST_DTS["dist/index.d.ts"]
        DIST_MAP["dist/index.d.ts.map"]
    end

    subgraph "Process Space"
        TSC["'tsc' (TypeScript Compiler)"]
        PNPM["'pnpm build'"]
    end

    PNPM --> TSC
    SRC -- "included by [tsconfig.json:18]" --> TSC
    TEST -- "excluded by [tsconfig.json:19]" --> TSC
    
    TSC -- "target: ES2022" --> DIST_JS
    TSC -- "declaration: true" --> DIST_DTS
    TSC -- "declarationMap: true" --> DIST_MAP
```

**Sources:**
- [tsconfig.json:14-19]()
- [package.json:24-24]()

---

### Scripts and Package Integration

The SDK uses `pnpm` as its package manager [package.json:46-46](). The build lifecycle is managed through standard NPM scripts:

*   **`build`**: Executes `tsc` to perform a full compilation of the project [package.json:24-24]().
*   **`prepare`**: Also executes `tsc`, ensuring that the code is compiled whenever the package is installed from a git dependency or before publishing [package.json:25-25]().

The `package.json` explicitly defines which files are included in the published NPM artifact. Only the `dist/` directory is bundled, ensuring that source files and test suites are not shipped to production environments [package.json:22-22]().

**Build Script Mapping**
```mermaid
graph LR
    subgraph "Commands"
        PB["pnpm build"]
        PP["pnpm prepare"]
    end

    subgraph "Execution"
        TSC_EXEC["tsc"]
    end

    subgraph "Output Artifacts"
        OUT["./dist/"]
    end

    PB --> TSC_EXEC
    PP --> TSC_EXEC
    TSC_EXEC --> OUT
    OUT -->|referenced by| MAIN["package.json: 'main' [17]"]
    OUT -->|referenced by| TYPES["package.json: 'types' [18]"]
```

**Sources:**
- [package.json:17-25]()
- [package.json:46-46]()
- [.gitignore:2-2]()

---